diff options
Diffstat (limited to 'docs/man/nng_zerotier.adoc')
| -rw-r--r-- | docs/man/nng_zerotier.adoc | 209 |
1 files changed, 209 insertions, 0 deletions
diff --git a/docs/man/nng_zerotier.adoc b/docs/man/nng_zerotier.adoc new file mode 100644 index 00000000..d28b1884 --- /dev/null +++ b/docs/man/nng_zerotier.adoc @@ -0,0 +1,209 @@ += nng_zerotier(7) +// +// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech> +// Copyright 2018 Capitar IT Group BV <info@capitar.com> +// +// This document is supplied under the terms of the MIT License, a +// copy of which should be located in the distribution where this +// file was obtained (LICENSE.txt). A copy of the license may also be +// found online at https://opensource.org/licenses/MIT. +// + +== NAME + +nng_zerotier - ZeroTier transport for nng + +== SYNOPSIS + +[source,c] +---------- +#include <nng/transport/zerotier/zerotier.h> + +int nng_zt_register(void); +---------- + +== DESCRIPTION + +The _nng_zerotier_ transport provides communication support for +_nng_ applications over a http://www.zerotier.com[ZeroTier] network, +using a Virtual Layer 2 packet facility. + +CAUTION: This transport is very experimental. To utilize it at +present, the library must be built with support, and the +ZeroTierOne `dev` branch must be included; this will require +linking against a suitable `libzerotiercore` static library. + +NOTE: The `libzerotiercore` library at present is covered under different +license terms than the rest of _nng_. Please be careful to review +and adhere to the licensing terms. + +While ZeroTier makes use of the host's IP stack (and UDP in particular), +this transport does not use or require an IP stack on the virtual +network; thereby mitigating any considerations about IP address management. + +This service uses Ethernet type 901 to transport packets. Network rules +must permit this Ethernet type to pass in order to have a functional +network. + +NOTE: This document assumes that the reader is familiar with ZeroTier +concepts and administration. + +=== Registration + +Depending upon how the library was built, it may be necessary to +register the transport by calling `nng_zt_register`. This function +returns zero on success, or an nng error value if the transport +cannot be initialized for any reason. + +=== URI Format + +This transport uses URIs using the scheme `zt://`, followed by a node +number (ten hexadecimal digits) followed by a `.` delimited, and then +a network address (sixteen hexadecimal digits), followed by a colon (`.`) +and service or port number (decimal value, up to 24-bits). +For example, the URI `zt://fedcba9876.0123456789abdef:999` indicates +that node fedcba9876 on network 0123456789abcdef is listening on port 999. + +The special value `*` can be used in lieu of a node number to represent +the node's own node number. + +Listeners may use port 0 to indicate that a suitable port +number be selected automatically. Applications using this must determine the +selected port number using the `nng_listener_getopt` function. + +=== Socket Address + +When using an `nng_sockaddr` structure, the actual structure is of type +`struct nng_sockaddr_zt`. This type has the following definition: + +[source,c] +-------- +#define NNG_AF_ZT 5 + +struct nng_sockaddr_zt { + uint16_t sa_family; // must be NNG_AF_ZT + uint64_t sa_nwid; // 64-bit network ID + uint64_t sa_nodeid; // 40-bit node ID + uint32_t sa_port; // 24-bit application port +} +-------- + +The `sa_family` member will have the value `NNG_AF_ZT` (5). The remaining +members are, unlike TCP socket address, in native byte order. Only the +lower 24-bits of the `sa_port` may be used. Likewise only the lower 40-bits +of the `sa_nodeid` may be used. + +=== Node Presence + +By default this transport creates an "ephemeral" node, and used the +same ephemeral node for any additional endpoints created. As this node +is ephemeral, the keys associated with it and all associated data are +located in memory and are discarded upon application termination. If +a persistent node is desired, please see the `NNG_OPT_ZT_HOME` option +below. + +It is possible for a single application to join multiple networks +using the same node, or using separate nodes. + +=== Transport Options + +The following transport options are available: + +`NNG_OPT_ZT_HOME`:: + + This is a string representing the "home directory", where the transport + can store (and reuse) persistent state, such as key materials, node + identity, and federation membership. This option must be set before the + ZeroTier transport is first used. If this value is empty, then an ephemeral + ZeroTier node is created, and no persistent state is used. The default + is to use an ephemeral node. ++ +NOTE: If this option is set to different values on different sockets, +dialers, or listeners, then separate nodes will be created. It +is perfectly valid for an application to have multiple node identities +in this fashion. + +`NNG_OPT_ZT_NWID`:: + + This is a read-only option for listeners, dialers, and pipes, and + provides a `uint64_t` in native byte order representing the 64-bit ZeroTier + network number. + +`NNG_OPT_ZT_NODE`:: + + This is a read-only option for listeners, dialers, and pipes, and + provides a `uint64_t` in native byte order representing the ZeroTier + 40-bit node address. + +`NNG_OPT_ZT_NETWORK_STATUS`:: + + This is a read-only integer, representing the ZeroTier network status. + Valid values for this are: ++ +[cols="1,2"] +|=== + +| `nng_zt_network_status_configuring` +| The ZeroTier node is still configuring, network services are not available. + +| `nng_zt_network_status_ok` +| The ZeroTier network is up. + +| `nng_zt_network_status_denied` +| The node does not have permission to join the ZeroTier network. + +| `nng_zt_network_status_notfound` +| The ZeroTier network is not found. + +| `nng_zt_network_status_error` +| Some other ZeroTier error has occurred; the network is not available. + +| `nng_zt_network_status_obsolete` +| The node is running obsolete software; the network is not available. + +|=== + + +`NNG_OPT_ZT_NETWORK_NAME`:: + + This is a read-only ASCIIZ string containing the name of the network + as established by the ZeroTier network administrator. + +`NNG_OPT_ZT_PING_TIME`:: + + If no traffic has been received from the ZeroTier peer after this + period of time, then a "ping" message is sent to check if the peer + is still alive. This is an `nng_duration` (msec). + +`NNG_OPT_ZT_PING_COUNT`:: + + If this number (`int`) of consecutive "ping" requests are sent to the + peer with no response (and no other intervening traffic), then the + peer is assumed to be dead and the connection is closed. Note that + if any traffic is received from the peer, then the underlying counter + is reset to zero. + +`NNG_OPT_ZT_MTU`:: + + This is a read-only size (`size_t`) representing the ZeroTier virtual + network MTU; this is the Virtual Layer 2 MTU. The headers used by + this transport and the protocols consume some of this for each message + sent over the network. (The transport uses 20-bytes of this, and each + protocol may consume additional space, typically not more than 16-bytes.) + +`NNG_OPT_ZT_ORBIT`:: + + This is a write-only option that takes an array of two `uint64_t` values, + indicating the ID of a ZeroTier "moon", and the node ID of the root server + for that moon. (The ID may be zero if the moon ID is the same as it's + root server ID, which is conventional.) + +`NNG_OPT_ZT_DEORBIT`:: + + This write-only option takes a single `uint64_t` indicating the moon + ID to "deorbit". If the node is not already orbiting the moon, then + this has no effect. + +== SEE ALSO + +<<nng#,nng(7)>> |