oxmox
7063e2102e
git-subtree-dir: external/nng git-subtree-split: 29b73962b939a6fbbf6ea8d5d7680bb06d0eeb99
225 lines
8.2 KiB
Text
225 lines
8.2 KiB
Text
= 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
|
|
|
|
== SYNOPSIS
|
|
|
|
[source,c]
|
|
----
|
|
#include <nng/transport/zerotier/zerotier.h>
|
|
|
|
int nng_zt_register(void);
|
|
----
|
|
|
|
== 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.
|
|
|
|
=== Registration
|
|
|
|
Depending upon how the library was built, it may be necessary to
|
|
register the transport by calling
|
|
xref:nng_zt_register.3.adoc[`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
|
|
|
|
(((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_getopt.3.adoc[`nng_listener_getopt()`] 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)]
|