Skip to content

Latest commit

 

History

History
229 lines (169 loc) · 7.59 KB

nng_zerotier.adoc

File metadata and controls

229 lines (169 loc) · 7.59 KB
Raw

nng_zerotier(7) Manual Page

NAME

nng_zerotier - ZeroTier transport for nng

SYNOPSIS

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

int nng_zt_register(void);

DESCRIPTION

The nng_zerotier transport provides communication support for nng applications over a 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 network address (sixteen hexadecimal digits), followed by a / delimiter, followed by the node number (ten hexadecimal digits) of the listening node, followed by a service or port number (decimal value, up to 24-bits). For example, the URI zt://0123456789abdef/fedcba9876:999 indicates that node fedcba9876 on network 0123456789abcdef listening on port 999.

Listening nodes may use port 0, or *, to indicate that a suitable port number be selected automatically. Applications using this must get the selected port address using the nng_listener_getopt function.

Listening nodes may also elide their own node number, as well as the delimiter separating the node number.

Socket Address

When using an nng_sockaddr structure, the actual structure is of type struct nng_sockaddr_zt. This type has the following definition:

#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:

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

COPYRIGHT

Copyright 2017 Garrett D’Amore
Copyright 2017 Capitar IT Group BV

This document is supplied under the terms of the MIT License.