Ubuntu Manpage: nng_zerotier - ZeroTier transport

NAME

       nng_zerotier - ZeroTier transport

SYNOPSIS

           #include <nng/transport/zerotier/zerotier.h>

           int nng_zt_register(void);

DESCRIPTION

The zt transport provides communication support for NNG applications over a ZeroTier
<http://www.zerotier.com> network, using a Virtual Layer 2 packet facility.

Important
This transport is experimental. To utilize it at present, the library must be built
with support, and linked against a suitable libzerotiercore library. Further
information about building with this support are in the build documentation included
with the distribution.

Important
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.

Important
The ZeroTier transport can take a long time to establish an initial connection — up to
even a minute in extreme cases, while the network topology is configured.
Consequently, this transport is not recommended for use cases involving short-lived
programs, but is better for long-running programs such as background daemons or
agents.

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 nng_sockaddr_zt.

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.

It is possible for a single application to join multiple networks using the same node, or
using separate nodes.

Network Status
A ZeroTier node can be in one of the following states, which can be obtained with the
NNG_OPT_ZT_NETWORK_STATUS option:

NNG_ZT_STATUS_UP
The ZeroTier network is up. This is the only state where it is possible to communicate
with peers, and the only state where the network name (NNG_OPT_ZT_NETWORK_NAME) is
available.

NNG_ZT_STATUS_CONFIG
The ZeroTier node is still configuring, network services are not available.

NNG_ZT_STATUS_DENIED
The node does not have permission to join the ZeroTier network.

NNG_ZT_STATUS_NOTFOUND
The ZeroTier network is not found.

NNG_ZT_STATUS_ERROR
Some other ZeroTier error has occurred; the network is not available.

NNG_ZT_STATUS_OBSOLETE
The node is running obsolete software; the network is not available.

NNG_ZT_STATUS_UNKNOWN
The network is in an unknown state. This should not happen, as it indicates that the
ZeroTier software is reporting an unexpected status. The network is most likely not
available.

Transport Options
The following transport options are available:

NNG_OPT_ZT_HOME
(string) This option represents 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
(uint64_t) The 64-bit ZeroTier network number (native byte order).

NNG_OPT_ZT_NODE
(uint64_t) The ZeroTier 40-bit node address (native byte order).

NNG_OPT_ZT_NETWORK_STATUS

(int) The ZeroTier network status. See Network Status for an explanation of this
option.

NNG_OPT_ZT_NETWORK_NAME

(string) The name of the network as established by the ZeroTier network administrator.

NNG_OPT_ZT_CONN_TIME
(nng_duration) The time to wait between sending connection attempts, only used with
dialers. The default is 500 msec.

NNG_OPT_ZT_CONN_TRIES
(int) The maximum number of attempts to try to establish a connection before reporting
a timeout, and is only used with dialers. The default is 240, which results in a 2
minute timeout if NNG_OPT_ZT_CONN_TIME is at its default of 500. If the value is set
to 0, then connection attempts will keep retrying forever.

NNG_OPT_ZT_PING_TIME
(nng_duration) 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.

NNG_OPT_ZT_PING_TRIES
(int) If this number 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.

NNG_OPT_ZT_MTU
(size_t) The ZeroTier virtual network MTU (read-only) as configured on the network;
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
(uint64_t[2]) Write-only array of two uint64_t values, indicating the ID of a ZeroTier
<em>moon</em>, and the node ID of the root server for that moon. (The ID may be zero
if the moon ID is the same as its root server ID, which is conventional.)

NNG_OPT_ZT_DEORBIT
(uint64_t) Write-only option indicating the moon ID to deorbit. If the node is not
already orbiting the moon, then this has no effect.

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO