diff options
Diffstat (limited to 'docs/man')
| -rw-r--r-- | docs/man/nng_sockaddr.5.adoc | 6 | ||||
| -rw-r--r-- | docs/man/nng_sockaddr_zt.5.adoc | 82 | ||||
| -rw-r--r-- | docs/man/nng_zerotier.7.adoc | 207 |
3 files changed, 1 insertions, 294 deletions
diff --git a/docs/man/nng_sockaddr.5.adoc b/docs/man/nng_sockaddr.5.adoc index cd10cab4..efcdf93a 100644 --- a/docs/man/nng_sockaddr.5.adoc +++ b/docs/man/nng_sockaddr.5.adoc @@ -25,7 +25,6 @@ typedef union nng_sockaddr { nng_sockaddr_inproc s_inproc; nng_sockaddr_in s_in; nng_sockaddr_in6 s_in6; - nng_sockaddr_zt s_zt; nng_sockaddr_abstract s_abstract; } nng_sockaddr; @@ -35,8 +34,7 @@ enum sockaddr_family { NNG_AF_IPC = 2, NNG_AF_INET = 3, NNG_AF_INET6 = 4, - NNG_AF_ZT = 5, - NNG_AF_ABSTRACT = 6 + NNG_AF_ABSTRACT = 5 }; ---- @@ -71,7 +69,6 @@ The values of `s_family` are as follows: `NNG_AF_IPC`:: Address for interprocess communication (xref:nng_ipc.7.adoc[nng_ipc(7)]). The `s_path` member is valid. `NNG_AF_INET`:: Address for TCP/IP (v4) communication. The `s_in` member is valid. `NNG_AF_INET6`:: Address for TCP/IP (v6) communication. The `s_in6` member is valid. -`NNG_AF_ZT`:: Address for ZeroTier transport (xref:nng_zerotier.7.adoc[nng_zerotier(7)]). The `s_zt` member is valid. `NNG_AF_ABSTRACT`:: Address for an abstract UNIX domain socket. The `s_abstract` member is valid. Please see the manual pages for each individual type for more information. @@ -84,5 +81,4 @@ xref:nng_sockaddr_in.5.adoc[nng_sockaddr_in(5)], xref:nng_sockaddr_in6.5.adoc[nng_sockaddr_in6(5)], xref:nng_sockaddr_inproc.5.adoc[nng_sockaddr_inproc(5)], xref:nng_sockaddr_ipc.5.adoc[nng_sockaddr_ipc(5)], -xref:nng_sockaddr_zt.5.adoc[nng_sockaddr_zt(5)], xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_sockaddr_zt.5.adoc b/docs/man/nng_sockaddr_zt.5.adoc deleted file mode 100644 index 70bb78af..00000000 --- a/docs/man/nng_sockaddr_zt.5.adoc +++ /dev/null @@ -1,82 +0,0 @@ -= nng_sockaddr_zt(5) -// -// 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_sockaddr_zt - ZeroTier socket address - -== SYNOPSIS - -[source, c] ----- -#include <nng/nng.h> - -enum sockaddr_family { - NNG_AF_ZT = 5, -}; - -typedef struct { - uint16_t sa_family; - uint64_t sa_nwid; - uint64_t sa_nodeid; - uint32_t sa_port; -} nng_sockaddr_zt; ----- - -== DESCRIPTION - -(((socket, address, ZeroTier))) -An `nng_sockaddr_zt` is the flavor of xref:nng_sockaddr.5.adoc[`nng_sockaddr`] -used to represent ZeroTier addresses, including the -(((port number, ZeroTier)))port number used by the -xref:nng_zerotier.7.adoc[_zt_] transport. - -IMPORTANT: The ZeroTier transport, and the details of this structure, -are still considered experimental, and subject to change. - -The following structure members are present: - -`sa_family`:: - This field will always have the value ((`NNG_AF_ZT`)). - -`sa_nwid`:: - (((network number, ZeroTier))) - This field holds the ZeroTier network number (or ID). - This value is in native byte order. - -`sa_nodeid`:: - This field holds the ZeroTier node ID.(((node ID, ZeroTier))) - This value is in native byte order, and only the lower 40 bits - are significant. - (ZeroTier node numbers are 40 bits long.) - A zero value here is used for a wild-card to indicate that the - caller's own node number be used. - -`sa_port`:: - This field holds the port number used by the - xref:nng_zerotier.7.adoc[_zt_] transport to distinguish different - sockets. - This value in native byte order.(((port number, ZeroTier))) - A zero value here indicates that a port number should be chosen - randomly from the ephemeral ports. - Only the lower 24 bits of the port number are used. - -NOTE: ZeroTier port numbers are in *native* byte order, and are larger -than TCP/IP port numbers. -They are also not part of the ZeroTier protocol itself, but defined by -the Scalability Protocols binding for them. - -== SEE ALSO - -[.text-left] -xref:nng_sockaddr.5.adoc[nng_sockaddr(5)], -xref:nng_zerotier.7.adoc[nng_zerotier(7)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/man/nng_zerotier.7.adoc b/docs/man/nng_zerotier.7.adoc deleted file mode 100644 index 0f98b33d..00000000 --- a/docs/man/nng_zerotier.7.adoc +++ /dev/null @@ -1,207 +0,0 @@ -= nng_zerotier(7) -// -// Copyright 2020 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 - -== DESCRIPTION - -(((ZeroTier)))(((transport, _zt_))) -The ((_zt_ transport)) provides communication support for -_NNG_ applications over a http://www.zerotier.com[ZeroTier] 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. - -=== URI Format - -(((URI, `zt://`))) -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(((port number, ZeroTier))) (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 -xref:nng_listener_get.3.adoc[`nng_listener_get_int()`] function. - -=== Socket Address - -When using an xref:nng_sockaddr.5.adoc[`nng_sockaddr`] structure, -the actual structure is of type -xref:nng_sockaddr_zt.5.adoc[`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 -(((status, zerotier network))) -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]] -((`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]] -((`NNG_OPT_ZT_NODE`)):: - (`uint64_t`) The ZeroTier 40-bit node address (native byte order). - -[[NNG_OPT_ZT_NETWORK_STATUS]] -((`NNG_OPT_ZT_NETWORK_STATUS`)):: - (((status, zerotier network))) - (`int`) The ZeroTier network status. - See <<Network Status>> for an explanation of this option. - -[[NNG_OPT_ZT_NETWORK_NAME]] -((`NNG_OPT_ZT_NETWORK_NAME`)):: - (((name, zerotier network))) - (string) The name of the network - as established by the ZeroTier network administrator. - -[[NNG_OPT_ZT_CONN_TIME]] -((`NNG_OPT_ZT_CONN_TIME`)):: - (xref:nng_duration.5.adoc[`nng_duration`]) - The time to wait between sending connection attempts, - only used with dialers. - The default is 500 msec. - -[[NNG_OPT_ZT_CONN_TRIES]] -((`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_OPT_ZT_PING_TIME`)):: - (xref:nng_duration.5.adoc[`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]] -((`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]] -((`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]] -((`NNG_OPT_ZT_ORBIT`))(((orbit, ZeroTier)))(((federation,ZeroTier))):: - (`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]] -((`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. - -== SEE ALSO - -[.text-left] -xref:nng_sockaddr_zt.5.adoc[nng_sockaddr_zt(5)], -xref:nng.7.adoc[nng(7)] |