From 98f23e10cc1d65da6a7f6c7e4f5665d7afc27a86 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Thu, 15 Mar 2018 08:40:17 -0700
Subject: fixes #286 nng_pair0_open (and all others) need man page fixes #279
 consider restructuring man sections

This represents a rather significant rework, and major editing
effort, for the entire set of manual pages.

All of the pages now have a section number in their filename;
this assists in some other tooling, particularly ebook generation
as every link needs to be programmatically modified when combined
into an ebook.

Section 5 is introduced, and populated with pages for the main
types, and all options are now documented.

Numerous errors have been corrected, including rewriting certain
portions such as the header section of the surveyor protocol.

Much work has been done to facilitate index generation, although
certainly more work remains here.

Every internal link within these pages now resolves; there are no
more dead links.  (This is required to generate Kindle format books.)
---
 docs/man/nng_zerotier.adoc | 234 ---------------------------------------------
 1 file changed, 234 deletions(-)
 delete mode 100644 docs/man/nng_zerotier.adoc

(limited to 'docs/man/nng_zerotier.adoc')

diff --git a/docs/man/nng_zerotier.adoc b/docs/man/nng_zerotier.adoc
deleted file mode 100644
index b77b8b8c..00000000
--- a/docs/man/nng_zerotier.adoc
+++ /dev/null
@@ -1,234 +0,0 @@
-= nng_zerotier(7)
-//
-// 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_zerotier - ZeroTier transport for nng
-
-== SYNOPSIS
-
-[source,c]
-----------
-#include <nng/transport/zerotier/zerotier.h>
-
-int nng_zt_register(void);
-----------
-
-== DESCRIPTION
-
-(((ZeroTier)))
-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.
-
-IMPORTANT: 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.
-
-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 `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 (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
-
-(((address, socket, zerotier)))
-(((`NNG_AF_ZT`)))
-(((`nng_sockaddr_zt`)))
-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.
-
-NOTE: The fields of this structure are in *native* byte order,
-unlike the other socket address structures associated with `NNG_AF_INET` or
-`NNG_AF_INET6`.
-
-=== 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.
-
-=== 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`))::
-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`))::
-  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`))::
-  (((status, zerotier network)))
-  This is a read-only integer, representing the ZeroTier network status.
-  See <<Network Status>> for an explanation of this option.
-
-((`NNG_OPT_ZT_NETWORK_NAME`))::
-  (((name, zerotier network)))
-  This is a read-only ASCIIZ string containing the name of the network
-  as established by the ZeroTier network administrator.
-
-((`NNG_OPT_ZT_CONN_TIME`))::
-  The time to wait between sending connection attempts.  This is an
-  `nng_duration` (msec), and is only used with dialers. The default is 500 msec.
-
-((`NNG_OPT_ZT_CONN_TRIES`))::
-  The maximum number (`int`) 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
-  it's default of 500.  If the value is set to 0, then the connection
-  attempts will keep retrying forever.
-
-((`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_TRIES`))::
-  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
-
-[.text-left]
-<<nng#,nng(7)>>
-- 
cgit v1.2.3-70-g09d2

