<commit_before>= nng_zerotier(7)
//
// Copyright 2018 Staysail Systems, Inc. <<EMAIL>>
// Copyright 2018 Capitar IT Group BV <<EMAIL>>
//
// 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 for nng

== SYNOPSIS

[source,c]
----------
#include <nng/transport/zerotier/zerotier.h>

int nng_zt_register(void);
----------

== DESCRIPTION

The _nng_zerotier_ transport provides communication support for
_nng_ applications over a http://www.zerotier.com[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 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
`struct nng_sockaddr_zt`.  This type has the following definition:

[source,c]
--------
#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:
+
[cols="1,2"]
|===

| `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.
<commit_msg>Minor formatting fix for network status table.<commit_after>= nng_zerotier(7)
//
// Copyright 2018 Staysail Systems, Inc. <<EMAIL>>
// Copyright 2018 Capitar IT Group BV <<EMAIL>>
//
// 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 for nng

== SYNOPSIS

[source,c]
----------
#include <nng/transport/zerotier/zerotier.h>

int nng_zt_register(void);
----------

== DESCRIPTION

The _nng_zerotier_ transport provides communication support for
_nng_ applications over a http://www.zerotier.com[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 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
`struct nng_sockaddr_zt`.  This type has the following definition:

[source,c]
--------
#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:
+
[cols="3,5"]
|===

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

{'fraction_non_alphanumeric': 0.06364339087863953, 'fraction_numerical': 0.01374216267285064, 'mean_word_length': 4.235611510791367, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 13, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4196487', 'n_tokens_mistral': 3521, 'n_tokens_neox': 3297, 'n_words': 1596}