+knet_handle_add_datafd \- Install a file descriptor for communication.
+.SH SYNOPSIS
+.nf
+.B #include <libknet.h>
+.sp
+\fBint knet_handle_add_datafd\fP(
+ \fBknet_handle_t \fP\fIknet_h\fP,
+ \fBint *\fP\fIdatafd\fP,
+ \fBint8_t *\fP\fIchannel\fP
+);
+.fi
+.SH DESCRIPTION
+.PP
+knet_handle_add_datafd
+.PP
+IMPORTANT: In order to add datafd to knet, knet_handle_enable_sock_notify MUST be set and be able to handle both errors (-1) and 0 bytes read / write from the provided datafd. On read error (< 0) from datafd, the socket is automatically removed from polling to avoid spinning on dead sockets. It is safe to call knet_handle_remove_datafd even on sockets that have been removed.
+.PP
+knet_h - pointer to knet_handle_t
+.PP
+*datafd - read/write file descriptor. knet will read data here to send to the other hosts and will write data received from the network. Each data packet can be of max size KNET_MAX_PACKET_SIZE! Applications using knet_send/knet_recv will receive a proper error if the packet size is not within boundaries. Applications using their own functions to write to the datafd should NOT write more than KNET_MAX_PACKET_SIZE.
+.PP
+Please refer to handle.c on how to set up a socketpair.
+.PP
+datafd can be 0, and knet_handle_add_datafd will create a properly populated socket pair the same way as ping_test, or a value higher than 0. A negative number will return an error. On exit knet_handle_free will take care to cleanup the socketpair only if they have been created by knet_handle_add_datafd.
+.PP
+It is possible to pass either sockets or normal fds. User provided datafd will be marked as non-blocking and close-on-exit.
+.PP
+*channel - This value has the same effect of VLAN tagging. A negative value will auto-allocate a channel. Setting a value between 0 and 31 will try to allocate that specific channel (unless already in use).
+.PP
+It is possible to add up to 32 datafds but be aware that each one of them must have a receiving end on the other host.
+.PP
+Example: hostA channel 0 will be delivered to datafd on hostB channel 0 hostA channel 1 to hostB channel 1.
+.PP
+Each channel must have a unique file descriptor.
+.PP
+If your application could have 2 channels on one host and one channel on another host, then you can use dst_host_filter to manipulate channel values on TX and RX.
+.SH RETURN VALUE
+.PP
+knet_handle_add_datafd returns
+.TP
+.B 0
+on success, *datafd will be populated with a socket if the original value was 0 or if a specific fd was set, the value is untouched. *channel will be populated with a channel number if the original value was negative or the value is untouched if a specific channel was requested.
+
+.TP
+.B -1
+on error and errno is set. *datafd and *channel are untouched or empty.
+knet_handle_compress_cfg - pointer to a knet_handle_compress_cfg structure
+.PP
+compress_model should contain the mode name. Currently only "zlib" and "lz4" are supported. Setting to "none" will disable compression.
+.PP
+compress_threshold tells the transmission thread to NOT compress any packets that are smaller than the value indicated. Default 100 bytes. Set to 0 to reset to the default. Set to 1 to compress everything. Max accepted value is KNET_MAX_PACKET_SIZE.
+.PP
+compress_level some compression libraries allow tuning of compression parameters. For example zlib value ranges from 0 to 9 where 0 is no compression and 9 is max compression. This value is passed pristine to the compression library. zlib: 0 (no compression), 1 (minimal) .. 9 (max compression). lz4: 1 (max compression)... 9 (fastest compression). lz4hc: 1 (min compression) ... LZ4HC_MAX_CLEVEL (16) or LZ4HC_CLEVEL_MAX (12) depends on the installed version of lz4hc. libknet can detects the max value and will print an appropriate warning. lzo2: accepts only some specific values depending on the requested algorithm: 1 : lzo1x_1_compress (default) 11 : lzo1x_1_11_compress 12 : lzo1x_1_12_compress 15 : lzo1x_1_15_compress 999: lzo1x_999_compress every other values will use default lzma: 0 (minimal) .. 9 (max compression) bzip2: 1 (minimal) .. 9 (max compression) Please refer to the library man pages on how to be set this value, as it is passed unmodified to the compression algorithm where supported.
+.PP
+knet does NOT implement the compression algorithm directly. it relies on external libraries for this functionality. Please read the libraries man pages to figure out which algorithm/compression level is best for the data you are planning to transmit.
+.SH STRUCTURES
+.SS ""
+.PP
+.sp
+.sp
+.RS
+.nf
+\fB
+struct knet_handle_compress_cfg {
+ char \fIcompress_model\fP;
+ uint32_t \fIcompress_threshold\fP;
+ int \fIcompress_level\fP;
+};
+\fP
+.fi
+.RE
+.SH RETURN VALUE
+.PP
+knet_handle_compress returns 0 on success -1 on error and errno is set. EINVAL means that either the model or the level are not supported.
+knet_handle_crypto_cfg - pointer to a knet_handle_crypto_cfg structure
+.PP
+crypto_model should contain the model name. Currently only "openssl" and "nss" are supported. Setting to "none" will disable crypto.
+.PP
+crypto_cipher_type should contain the cipher algo name. It can be set to "none" to disable encryption. Currently supported by "nss" model: "3des", "aes128", "aes192" and "aes256". "openssl" model supports more modes and it strictly depends on the openssl build. See: EVP_get_cipherbyname openssl API call for details.
+.PP
+crypto_hash_type should contain the hashing algo name. It can be set to "none" to disable hashing. Currently supported by "nss" model: "md5", "sha1", "sha256", "sha384" and "sha512". "openssl" model supports more modes and it strictly depends on the openssl build. See: EVP_get_digestbyname openssl API call for details.
+.PP
+private_key will contain the private shared key. It has to be at least KNET_MIN_KEY_LEN long.
+.PP
+private_key_len length of the provided private_key.
+.PP
+it is safe to call knet_handle_crypto multiple times at runtime. The last config will be used. IMPORTANT: a call to knet_handle_crypto can fail due to: 1) failure to obtain locking 2) errors to initializing the crypto level. This can happen even in subsequent calls to knet_handle_crypto. A failure in crypto init, might leave your traffic unencrypted! It's best to stop data forwarding (see knet_handle_setfwd(3)), change crypto config, start forward again.
+.SH STRUCTURES
+.SS ""
+.PP
+.sp
+.sp
+.RS
+.nf
+\fB
+struct knet_handle_crypto_cfg {
+ char \fIcrypto_model\fP;
+ char \fIcrypto_cipher_type\fP;
+ char \fIcrypto_hash_type\fP;
+ unsigned char \fIprivate_key\fP;
+ unsigned int \fIprivate_key_len\fP;
+};
+\fP
+.fi
+.RE
+.SH RETURN VALUE
+.PP
+knet_handle_crypto returns:
+.TP
+.B 0
+on success
+
+.TP
+.B -1
+on error and errno is set.
+
+.TP
+.B -2
+on crypto subsystem initialization error. No errno is provided at the moment (yet).
+dst_host_filter_fn_private_data void pointer to data that can be used to identify the callback.
+.PP
+dst_host_filter_fn - is a callback function that is invoked every time a packet hits datafd (see knet_handle_new(3)). the function allows users to tell libknet where the packet has to be delivered.
+.PP
+const unsigned char *outdata - is a pointer to the current packet ssize_t outdata_len - lenght of the above data uint8_t tx_rx - filter is called on tx or rx (see defines below) knet_node_id_t this_host_id - host_id processing the packet knet_node_id_t src_host_id - host_id that generated the packet knet_node_id_t *dst_host_ids - array of KNET_MAX_HOST knet_node_id_t where to store the destinations size_t *dst_host_ids_entries - number of hosts to send the message
+.PP
+dst_host_filter_fn should return -1 on error, packet is discarded. 0 packet is unicast and should be sent to dst_host_ids and there are dst_host_ids_entries in the buffer. 1 packet is broadcast/multicast and is sent all hosts. contents of dst_host_ids and dst_host_ids_entries are ignored. (see also kronosnetd/etherfilter.* for an example that filters based on ether protocol)
+.SH RETURN VALUE
+.PP
+knet_handle_enable_filter returns 0 on success -1 on error and errno is set.
+knet_handle_enable_pmtud_notify \- install a callback to receive PMTUd changes
+.SH SYNOPSIS
+.nf
+.B #include <libknet.h>
+.sp
+\fBint knet_handle_enable_pmtud_notify\fP(
+ \fBknet_handle_t \fP\fIknet_h\fP,
+ \fBvoid *\fP\fIpmtud_notify_fn_private_data\fP,
+ \fBvoid(*)(void *private_data, unsigned int data_mtu) \fP\fIpmtud_notify_fn\fP
+);
+.fi
+.SH DESCRIPTION
+.PP
+knet_handle_enable_pmtud_notify
+.PP
+knet_h - pointer to knet_handle_t
+.PP
+pmtud_notify_fn_private_data void pointer to data that can be used to identify the callback.
+.PP
+pmtud_notify_fn is a callback function that is invoked every time a path MTU size change is detected. The function allows libknet to notify the user of data MTU, that's the max value that can be send onwire without fragmentation. The data MTU will always be lower than real link MTU because it accounts for protocol overhead, knet packet header and (if configured) crypto overhead, This function MUST NEVER block or add substantial delays.
+.SH RETURN VALUE
+.PP
+knet_handle_enable_pmtud_notify returns 0 on success -1 on error and errno is set.
+knet_handle_enable_sock_notify \- Register a callback to receive socket events.
+.SH SYNOPSIS
+.nf
+.B #include <libknet.h>
+.sp
+\fBint knet_handle_enable_sock_notify\fP(
+ \fBknet_handle_t \fP\fIknet_h\fP,
+ \fBvoid *\fP\fIsock_notify_fn_private_data\fP,
+ \fBvoid(*)(void *private_data, int datafd, int8_t channel, uint8_t tx_rx, int error, int errorno) \fP\fIsock_notify_fn\fP
+);
+.fi
+.SH DESCRIPTION
+.PP
+knet_handle_enable_sock_notify knet_h - pointer to knet_handle_t
+.PP
+sock_notify_fn_private_data void pointer to data that can be used to identify the callback.
+.PP
+sock_notify_fn A callback function that is invoked every time a socket in the datafd pool will report an error (-1) or an end of read (0) (see socket.7). This function MUST NEVER block or add substantial delays. The callback is invoked in an internal unlocked area to allow calls to knet_handle_add_datafd/knet_handle_remove_datafd to swap/replace the bad fd. if both err and errno are 0, it means that the socket has received a 0 byte packet (EOF?). The callback function must either remove the fd from knet (by calling knet_handle_remove_fd()) or dup a new fd in its place. Failure to do this can cause problems.
+.SH RETURN VALUE
+.PP
+knet_handle_enable_sock_notify returns 0 on success -1 on error and errno is set.
+knet_handle_get_stats \- Get statistics for compression & crypto.
+.SH SYNOPSIS
+.nf
+.B #include <libknet.h>
+.sp
+\fBint knet_handle_get_stats\fP(
+ \fBknet_handle_t \fP\fIknet_h\fP,
+ \fBstruct knet_handle_stats *\fP\fIstats\fP,
+ \fBsize_t \fP\fIstruct_size\fP
+);
+.fi
+.SH DESCRIPTION
+.PP
+knet_handle_get_stats
+.PP
+knet_h - pointer to knet_handle_t
+.PP
+knet_handle_stats pointer to a knet_handle_stats structure
+.PP
+struct_size size of knet_handle_stats structure to allow for backwards compatibility. libknet will only copy this much data into the stats structure so that older callers will not get overflowed if new fields are added.
+knet_handle_new \- create a new instance of a knet handle
+.SH SYNOPSIS
+.nf
+.B #include <libknet.h>
+.sp
+\fBknet_handle_t knet_handle_new\fP(
+ \fBknet_node_id_t \fP\fIhost_id\fP,
+ \fBint \fP\fIlog_fd\fP,
+ \fBuint8_t \fP\fIdefault_log_level\fP
+);
+.fi
+.SH DESCRIPTION
+.PP
+knet_handle_new
+.PP
+host_id - Each host in a knet is identified with a unique ID. when creating a new handle local host_id must be specified (0 to UINT16T_MAX are all valid). It is the user's responsibility to check that the value is unique, or bad things might happen.
+.PP
+log_fd - Write file descriptor. If set to a value > 0, it will be used to write log packets (see below) from libknet to the application. Setting to 0 will disable logging from libknet. It is possible to enable logging at any given time (see logging API below). Make sure to either read from this filedescriptor properly and/or mark it O_NONBLOCK, otherwise if the fd becomes full, libknet could block.
+.PP
+default_log_level - If logfd is specified, it will initialize all subsystems to log at default_log_level value. (see logging API below)
+.SH RETURN VALUE
+.PP
+on success, a new knet_handle_t is returned. on failure, NULL is returned and errno is set.
+host_status_change_notify_fn_private_data void pointer to data that can be used to identify the callback.
+.PP
+external, 0 if the host_id is configured locally or 1 if it has been added from remote nodes config. NOTE: dynamic topology is NOT currently implemented, but this is ready for future and can avoid an API/ABI breakage later on. This function MUST NEVER block or add substantial delays.
+.SH RETURN VALUE
+.PP
+knet_host_status_change_notify returns 0 on success -1 on error and errno is set.
+knet_host_get_name_by_host_id \- Get the name of a host given its ID.
+.SH SYNOPSIS
+.nf
+.B #include <libknet.h>
+.sp
+\fBint knet_host_get_name_by_host_id\fP(
+ \fBknet_handle_t \fP\fIknet_h\fP,
+ \fBknet_node_id_t \fP\fIhost_id\fP,
+ \fBchar *\fP\fIname\fP
+);
+.fi
+.SH DESCRIPTION
+.PP
+knet_host_get_name_by_host_id
+.PP
+knet_h - pointer to knet_handle_t
+.PP
+host_id - see knet_host_add(3)
+.PP
+name - pointer to a preallocated buffer of at least size KNET_MAX_HOST_LEN where the current host name will be stored (as set by knet_host_set_name or default by knet_host_add)
+.SH RETURN VALUE
+.PP
+knet_host_get_name_by_host_id returns: 0 on success -1 on error and errno is set (name is left untouched)
+knet_host_set_name \- Set the name of a knet host.
+.SH SYNOPSIS
+.nf
+.B #include <libknet.h>
+.sp
+\fBint knet_host_set_name\fP(
+ \fBknet_handle_t \fP\fIknet_h\fP,
+ \fBknet_node_id_t \fP\fIhost_id\fP,
+ \fBconst char *\fP\fIname\fP
+);
+.fi
+.SH DESCRIPTION
+.PP
+knet_host_set_name
+.PP
+knet_h - pointer to knet_handle_t
+.PP
+host_id - see above
+.PP
+name - this name will be used for pretty logging and eventually search for hosts (see also knet_handle_host_get_name(2) and knet_handle_host_get_id(3)). Only up to KNET_MAX_HOST_LEN - 1 bytes will be accepted and name has to be unique for each host.
+.SH RETURN VALUE
+.PP
+knet_host_set_name returns: 0 on success -1 on error and errno is set.
+knet_host_set_policy \- Set the switching policy for a host's links.
+.SH SYNOPSIS
+.nf
+.B #include <libknet.h>
+.sp
+\fBint knet_host_set_policy\fP(
+ \fBknet_handle_t \fP\fIknet_h\fP,
+ \fBknet_node_id_t \fP\fIhost_id\fP,
+ \fBuint8_t \fP\fIpolicy\fP
+);
+.fi
+.SH DESCRIPTION
+.PP
+knet_host_set_policy
+.PP
+knet_h - pointer to knet_handle_t
+.PP
+host_id - see knet_host_add(3)
+.PP
+policy - there are currently 3 kind of simple switching policies as defined above, based on link configuration. KNET_LINK_POLICY_PASSIVE - the active link with the lowest priority will be used. if one or more active links share the same priority, the one with lowest link_id will be used.
+.PP
+KNET_LINK_POLICY_ACTIVE - all active links will be used simultaneously to send traffic. link priority is ignored.
+.PP
+KNET_LINK_POLICY_RR - round-robin policy, every packet will be send on a different active link.
+.SH RETURN VALUE
+.PP
+knet_host_set_policy returns 0 on success -1 on error and errno is set.
+knet_link_get_status \- Get the status (and statistics) for a link.
+.SH SYNOPSIS
+.nf
+.B #include <libknet.h>
+.sp
+\fBint knet_link_get_status\fP(
+ \fBknet_handle_t \fP\fIknet_h\fP,
+ \fBknet_node_id_t \fP\fIhost_id\fP,
+ \fBuint8_t \fP\fIlink_id\fP,
+ \fBstruct knet_link_status *\fP\fIstatus\fP,
+ \fBsize_t \fP\fIstruct_size\fP
+);
+.fi
+.SH DESCRIPTION
+.PP
+knet_link_get_status
+.PP
+knet_h - pointer to knet_handle_t
+.PP
+host_id - see above
+.PP
+link_id - see above
+.PP
+status - pointer to knet_link_status struct (see above)
+.PP
+struct_size - max size of knet_link_status - allows library to add fields without ABI change. Returned structure will be truncated to this length and .size member indicates the full size.
+.SH STRUCTURES
+.SS ""
+.PP
+.sp
+.sp
+.RS
+.nf
+\fB
+struct knet_link_status {
+ size_t \fIsize\fP;
+ char \fIsrc_ipaddr\fP;
+ char \fIsrc_port\fP;
+ char \fIdst_ipaddr\fP;
+ char \fIdst_port\fP;
+ uint8_t \fIenabled\fP;
+ uint8_t \fIconnected\fP;
+ uint8_t \fIdynconnected\fP;
+ unsigned long long \fIlatency\fP;
+ struct timespec \fIpong_last\fP;
+ unsigned int \fImtu\fP;
+ unsigned int \fIproto_overhead\fP;
+ struct knet_link_stats \fIstats\fP;
+};
+\fP
+.fi
+.RE
+.SH RETURN VALUE
+.PP
+knet_link_get_status returns 0 on success -1 on error and errno is set.
+knet_link_set_config \- Configure the link to a host.
+.SH SYNOPSIS
+.nf
+.B #include <libknet.h>
+.sp
+\fBint knet_link_set_config\fP(
+ \fBknet_handle_t \fP\fIknet_h\fP,
+ \fBknet_node_id_t \fP\fIhost_id\fP,
+ \fBuint8_t \fP\fIlink_id\fP,
+ \fBuint8_t \fP\fItransport\fP,
+ \fBstruct sockaddr_storage *\fP\fIsrc_addr\fP,
+ \fBstruct sockaddr_storage *\fP\fIdst_addr\fP,
+ \fBuint64_t \fP\fIflags\fP
+);
+.fi
+.SH DESCRIPTION
+.PP
+knet_link_set_config
+.PP
+knet_h - pointer to knet_handle_t
+.PP
+host_id - see knet_host_add(3)
+.PP
+link_id - see knet_link_set_config(3)
+.PP
+transport - one of the above KNET_TRANSPORT_xxx constants
+.PP
+src_addr - sockaddr_storage that can be either IPv4 or IPv6
+.PP
+dst_addr - sockaddr_storage that can be either IPv4 or IPv6 this can be null if we don't know the incoming IP address/port and the link will remain quiet till the node on the other end will initiate a connection
+.PP
+flags - KNET_LINK_FLAG_*
+.SH RETURN VALUE
+.PP
+knet_link_set_config returns 0 on success -1 on error and errno is set.
+knet_send_sync \- Synchronously send data to knet nodes.
+.SH SYNOPSIS
+.nf
+.B #include <libknet.h>
+.sp
+\fBint knet_send_sync\fP(
+ \fBknet_handle_t \fP\fIknet_h\fP,
+ \fBconst char *\fP\fIbuff\fP,
+ \fBconst size_t \fP\fIbuff_len\fP,
+ \fBconst int8_t \fP\fIchannel\fP
+);
+.fi
+.SH DESCRIPTION
+.PP
+knet_send_sync
+.PP
+knet_h - pointer to knet_handle_t
+.PP
+buff - pointer to the buffer of data to send
+.PP
+buff_len - length of data to send
+.PP
+channel - data channel to use (see knet_handle_add_datafd(3))
+.PP
+All knet RX/TX operations are async for performance reasons. There are applications that might need a sync version of data transmission and receive errors in case of failure to deliver to another host. knet_send_sync bypasses the whole TX async layer and delivers data directly to the link layer, and returns errors accordingly. knet_send_sync allows to send only one packet to one host at a time. It does NOT support multiple destinations or multicast packets. Decision is still based on dst_host_filter_fn.
+.SH RETURN VALUE
+.PP
+knet_send_sync returns 0 on success and -1 on error. In addition to normal sendmmsg errors, knet_send_sync can fail due to:
+.TP
+.B ECANCELED
+- data forward is disabled
+
+.TP
+.B EFAULT
+- dst_host_filter fatal error
+
+.TP
+.B EINVAL
+- dst_host_filter did not provide dst_host_ids_entries on unicast pckts
+
+.TP
+.B E2BIG
+- dst_host_filter did return more than one dst_host_ids_entries on unicast pckts
+
+.TP
+.B ENOMSG
+- received unknown message type
+
+.TP
+.B EHOSTDOWN
+- unicast pckt cannot be delivered because dest host is not connected yet
+
+.TP
+.B ECHILD
+- crypto failed
+
+.TP
+.B EAGAIN
+- sendmmsg was unable to send all messages and there was no progress during retry