path: root/man/tip/nng_zerotier.7.html

---
version: tip
layout: manpage_v2
title: nng_zerotier(7)
---
<h1>nng_zerotier(7)</h1>
<div class="sect1">
<h2 id="_name">NAME</h2>
<div class="sectionbody">
<div class="paragraph">
<p>nng_zerotier - ZeroTier transport</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_synopsis">SYNOPSIS</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content">
<pre class="pygments highlight"><code data-lang="c"><span></span><span class="tok-cp">#include</span><span class="tok-w"> </span><span class="tok-cpf">&lt;nng/transport/zerotier/zerotier.h&gt;</span>

<span class="tok-kt">int</span><span class="tok-w"> </span><span class="tok-nf">nng_zt_register</span><span class="tok-p">(</span><span class="tok-kt">void</span><span class="tok-p">);</span></code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_description">DESCRIPTION</h2>
<div class="sectionbody">
<div class="paragraph">
<p>
The <em>zt</em> transport provides communication support for
<em>NNG</em> applications over a <a href="http://www.zerotier.com">ZeroTier</a> network,
using a Virtual Layer 2 packet facility.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
This transport is experimental.
To utilize it at present, the library must be built with support, and linked
against a suitable <code>libzerotiercore</code> library.
Further information about building with this support are in the build
documentation included with the distribution.
</td>
</tr>
</table>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
The <code>libzerotiercore</code> library at present is covered under different
license terms than the rest of <em>NNG</em>.  Please be careful to review
and adhere to the licensing terms.
</td>
</tr>
</table>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
The ZeroTier transport can take a long time to establish an
initial connection&#8201;&#8212;&#8201;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.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>While ZeroTier makes use of the host&#8217;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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
This document assumes that the reader is familiar with ZeroTier
concepts and administration.
</td>
</tr>
</table>
</div>
<div class="sect2">
<h3 id="_registration">Registration</h3>
<div class="paragraph">
<p>Depending upon how the library was built, it may be necessary to
register the transport by calling
<a href="nng_zt_register.3.html"><code>nng_zt_register()</code></a>.
This function
returns zero on success, or an nng error value if the transport
cannot be initialized for any reason.</p>
</div>
</div>
<div class="sect2">
<h3 id="_uri_format">URI Format</h3>
<div class="paragraph">
<p>
This transport uses URIs using the scheme <code>zt://</code>, followed by a node
number (ten hexadecimal digits) followed by a <code>.</code> delimited, and then
a network address (sixteen hexadecimal digits), followed by a colon (<code>:</code>)
and service or port number (decimal value,
up to 24-bits).
For example, the URI <code>zt://fedcba9876.0123456789abdef:999</code> indicates
that node fedcba9876 on network 0123456789abcdef is listening on port 999.</p>
</div>
<div class="paragraph">
<p>The special value <code>*</code> can be used in lieu of a node number to represent
the node&#8217;s own node number.</p>
</div>
<div class="paragraph">
<p>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
<a href="nng_listener_getopt.3.html"><code>nng_listener_getopt()</code></a> function.</p>
</div>
</div>
<div class="sect2">
<h3 id="_socket_address">Socket Address</h3>
<div class="paragraph">
<p>When using an <a href="nng_sockaddr.5.html"><code>nng_sockaddr</code></a> structure,
the actual structure is of type
<a href="nng_sockaddr_zt.5.html"><code>nng_sockaddr_zt</code></a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_node_presence">Node Presence</h3>
<div class="paragraph">
<p>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 <code>NNG_OPT_ZT_HOME</code> option.</p>
</div>
<div class="paragraph">
<p>It is possible for a single application to join multiple networks
using the same node, or using separate nodes.</p>
</div>
</div>
<div class="sect2">
<h3 id="_network_status">Network Status</h3>
<div class="paragraph">
<p>
A ZeroTier node can be in one of the following states, which can be obtained
with the <code>NNG_OPT_ZT_NETWORK_STATUS</code> option:</p>
</div>
<div id="NNG_ZT_STATUS_UP" class="dlist">
<dl>
<dt class="hdlist1"><code>NNG_ZT_STATUS_UP</code></dt>
<dd>
<p>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 (<code>NNG_OPT_ZT_NETWORK_NAME</code>)
is available.</p>
</dd>
<dt class="hdlist1"><code>NNG_ZT_STATUS_CONFIG</code></dt>
<dd>
<p>The ZeroTier node is still configuring, network services are not available.</p>
</dd>
<dt class="hdlist1"><code>NNG_ZT_STATUS_DENIED</code></dt>
<dd>
<p>The node does not have permission to join the ZeroTier network.</p>
</dd>
<dt class="hdlist1"><code>NNG_ZT_STATUS_NOTFOUND</code></dt>
<dd>
<p>The ZeroTier network is not found.</p>
</dd>
<dt class="hdlist1"><code>NNG_ZT_STATUS_ERROR</code></dt>
<dd>
<p>Some other ZeroTier error has occurred; the network is not available.</p>
</dd>
<dt class="hdlist1"><code>NNG_ZT_STATUS_OBSOLETE</code></dt>
<dd>
<p>The node is running obsolete software; the network is not available.</p>
</dd>
<dt class="hdlist1"><code>NNG_ZT_STATUS_UNKNOWN</code></dt>
<dd>
<p>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.</p>
</dd>
</dl>
</div>
</div>
<div class="sect2">
<h3 id="_transport_options">Transport Options</h3>
<div class="paragraph">
<p>The following transport options are available:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>NNG_OPT_ZT_HOME</code></dt>
<dd>
<p>(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.</p>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
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.
</td>
</tr>
</table>
</div>
</dd>
<dt class="hdlist1"><code>NNG_OPT_ZT_NWID</code></dt>
<dd>
<p>(<code>uint64_t</code>) The 64-bit ZeroTier network number (native byte order).</p>
</dd>
</dl>
</div>
<div id="NNG_OPT_ZT_NODE" class="dlist">
<dl>
<dt class="hdlist1"><code>NNG_OPT_ZT_NODE</code></dt>
<dd>
<p>(<code>uint64_t</code>) The ZeroTier  40-bit node address (native byte order).</p>
</dd>
</dl>
</div>
<div id="NNG_OPT_ZT_NETWORK_STATUS" class="dlist">
<dl>
<dt class="hdlist1"><code>NNG_OPT_ZT_NETWORK_STATUS</code></dt>
<dd>
<p>
(<code>int</code>) The ZeroTier network status.
See <a href="#_network_status">Network Status</a> for an explanation of this option.</p>
</dd>
</dl>
</div>
<div id="NNG_OPT_ZT_NETWORK_NAME" class="dlist">
<dl>
<dt class="hdlist1"><code>NNG_OPT_ZT_NETWORK_NAME</code></dt>
<dd>
<p>
(string) The name of the network
as established by the ZeroTier network administrator.</p>
</dd>
</dl>
</div>
<div id="NNG_OPT_ZT_CONN_TIME" class="dlist">
<dl>
<dt class="hdlist1"><code>NNG_OPT_ZT_CONN_TIME</code></dt>
<dd>
<p>(<a href="nng_duration.5.html"><code>nng_duration</code></a>)
The time to wait between sending connection attempts,
only used with dialers.
The default is 500 msec.</p>
</dd>
</dl>
</div>
<div id="NNG_OPT_ZT_CONN_TRIES" class="dlist">
<dl>
<dt class="hdlist1"><code>NNG_OPT_ZT_CONN_TRIES</code></dt>
<dd>
<p>(<code>int</code>) 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
<code>NNG_OPT_ZT_CONN_TIME</code> is at its default of 500.
If the value is set to 0, then connection attempts will keep retrying forever.</p>
</dd>
</dl>
</div>
<div id="NNG_OPT_ZT_PING_TIME" class="dlist">
<dl>
<dt class="hdlist1"><code>NNG_OPT_ZT_PING_TIME</code></dt>
<dd>
<p>(<a href="nng_duration.5.html"><code>nng_duration</code></a>) 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.</p>
</dd>
</dl>
</div>
<div id="NNG_OPT_ZT_PING_TRIES" class="dlist">
<dl>
<dt class="hdlist1"><code>NNG_OPT_ZT_PING_TRIES</code></dt>
<dd>
<p>(<code>int</code>) 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.</p>
</dd>
</dl>
</div>
<div id="NNG_OPT_ZT_MTU" class="dlist">
<dl>
<dt class="hdlist1"><code>NNG_OPT_ZT_MTU</code></dt>
<dd>
<p>(<code>size_t</code>) 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.)</p>
</dd>
</dl>
</div>
<div id="NNG_OPT_ZT_ORBIT" class="dlist">
<dl>
<dt class="hdlist1"><code>NNG_OPT_ZT_ORBIT</code></dt>
<dd>
<p>(<code>uint64_t[2]</code>) Write-only array of two <code>uint64_t</code> values,
indicating the ID of a ZeroTier &lt;em&gt;moon&lt;/em&gt;, 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.)</p>
</dd>
</dl>
</div>
<div id="NNG_OPT_ZT_DEORBIT" class="dlist">
<dl>
<dt class="hdlist1"><code>NNG_OPT_ZT_DEORBIT</code></dt>
<dd>
<p>(<code>uint64_t</code>) Write-only option indicating the moon ID to deorbit.
If the node is not already orbiting the moon, then this has no effect.</p>
</dd>
</dl>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_see_also">SEE ALSO</h2>
<div class="sectionbody">
<div class="paragraph text-left">
<p><a href="nng_sockaddr_zt.5.html">nng_sockaddr_zt(5)</a>,
<a href="nng.7.html">nng(7)</a></p>
</div>
</div>
</div>