diff options
| author | Garrett D'Amore <garrett@damore.org> | 2017-10-24 11:46:24 -0700 |
|---|---|---|
| committer | Garrett D'Amore <garrett@damore.org> | 2017-10-24 11:46:24 -0700 |
| commit | a7b20c3babd965b12dec8cb5ff0883a4d8d1116d (patch) | |
| tree | 35d3c001ebe57d5320fcd75963fad5f5a2c6faec /doc | |
| parent | 5c45bc28facc08601431df95a751e9f6a9d80c3a (diff) | |
| download | nng-a7b20c3babd965b12dec8cb5ff0883a4d8d1116d.tar.gz nng-a7b20c3babd965b12dec8cb5ff0883a4d8d1116d.tar.bz2 nng-a7b20c3babd965b12dec8cb5ff0883a4d8d1116d.zip | |
Doc directory moved to make github pages happy.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.adoc | 8 | ||||
| -rw-r--r-- | doc/nng.adoc | 88 | ||||
| -rw-r--r-- | doc/nng_zerotier.adoc | 231 |
3 files changed, 0 insertions, 327 deletions
diff --git a/doc/README.adoc b/doc/README.adoc deleted file mode 100644 index 5030ec42..00000000 --- a/doc/README.adoc +++ /dev/null @@ -1,8 +0,0 @@ -This contains the nng documentation for API users. - -The documentation is written in asciidoc in the form of man pages. It is -automatically formatted for display on the website. - -It is possible to emit TROFF sources for use by the UNIX man page, and HTML -for online viewing. asciidoctor supports PDF and EPUB formats via plugins, -so there are still more options available. diff --git a/doc/nng.adoc b/doc/nng.adoc deleted file mode 100644 index 8a9d2596..00000000 --- a/doc/nng.adoc +++ /dev/null @@ -1,88 +0,0 @@ -nng(7) -====== -:doctype: manpage -:manmanual: nng -:mansource: nng -:manvolnum: 7 -:icons:font -:copyright: Copyright 2017 Garrett D'Amore <garrett@damore.org> \ - Copyright 2017 Capitar IT Group BV <info@capitar.com> \ - This software 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 - nanomsg next generation - -SYNOPSIS --------- -*cc* ['flags'] 'files' *-lnng* ['libraries'] - - -DESCRIPTION ------------ - -The _nng_ library provides a common messaging framework intended to -solve common communication problems in distributed applications. -It offers a number of _protocols_, and also a number of _transports_. - -The _protocols_ implement the semantics associated with particular -communications scenarios, such as RPC style services, service discovery, -publish/subscribe, and so forth. - -The _transports_ provide support for underlying transport methods, such -as TCP, IPC, websockets, and so forth. - -The _nng_ library is designed to permit easy creation of new _transports_ and, -to a lesser extent, new _protocols_. - -The _nng_ library is wire compatible with the SP protocols described in -the nanomsg project; projects using _libnanomsg_ can interoperate with -nng as well as other conforming implementations. (One such implementation -is the https://github.com/go-mangos/mangos[mangos]. Applications using _nng_ -which wish to communicate with older libraries must ensure that they only -use protocols or transports offered by the earlier library. - -The _nng_ library also offers a compatible API, permitting legacy code to -be recompiled or relinked against _nng_. When doing this, support for -certain enhancements or features will likely be absent, requiring the -application developer to use the new-style API. - -The _nng_ library is implemented in pure C; if you need bindings for -other languages please check the http://nanomsg.org/[website]. - -Protocols -~~~~~~~~~ - -* <<nng_bus.adoc,nng_bus(7)>> - Bus protocol -* <<nng_pair.adoc,nng_pair(7)>> - Pair protocol -* <<nng_pubsub.adoc,nng_pubsub(7)>> - Publish/Subscribe protocol -* <<nng_reqrep.adoc,nng_reqrep(7)>> - Request/Reply protocol -* <<nng_survey.adoc,nng_survey(7)>> - Survey/Respond protocol - -Transports -~~~~~~~~~~ - -* <<nng_inproc.adoc#,nng_inproc(7)>> - Intra-process transport -* <<nng_ipc.adoc#,nng_ipc(7)>> - Inter-process transport -* <<nng_tcp.adoc#,nng_tcp(7)>> - TCP (and TCPv6) transport -* <<nng_zerotier.adoc#,nng_zerotier(7)>> - ZeroTier transport - -AUTHORS -------- -link:mailto:garrett@damore.org[Garrett D'Amore] - -SEE ALSO --------- -<<nng_compat.adoc#,nng_compat(3)>> - -COPYRIGHT ---------- - -Copyright 2017 mailto:garrett@damore.org[Garrett D'Amore] + -Copyright 2017 mailto:info@capitar.com[Capitar IT Group BV] - -This document is supplied under the terms of the -https://opensource.org/licenses/LICENSE.txt[MIT License]. diff --git a/doc/nng_zerotier.adoc b/doc/nng_zerotier.adoc deleted file mode 100644 index c8a658ef..00000000 --- a/doc/nng_zerotier.adoc +++ /dev/null @@ -1,231 +0,0 @@ -nng_zerotier(7) -=============== -:doctype: manpage -:manmanual: nng -:mansource: nng -:manvolnum: 7 -:icons: font -:source-highlighter: pygments -:copyright: Copyright 2017 Garrett D'Amore <garrett@damore.org> \ - Copyright 2017 Capitar IT Group BV <info@capitar.com> \ - This software 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 --------- - -*#include <nn/transports/zt.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 network -address (sixteen hexadecimal digits), followed by a `/` delimiter, -followed by the node number (ten hexadecimal digits) of the listening -node, followed by a service or port number (decimal value, up to 24-bits). -For example, the URI `zt://0123456789abdef/fedcba9876:999` indicates -that node fedcba9876 on network 0123456789abcdef listening on port 999. - -Listening nodes may use port 0, or `*`, to indicate that a suitable port -number be selected automatically. Applications using this must get the -selected port address using the `nng_listener_getopt` function. - -Listening nodes may also elide their own node number, as well as the -delimiter seperating the node number. - -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 ephermal - 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-ony 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. - -*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_COUNT*:: - - 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. - -AUTHORS -------- -link:mailto:garrett@damore.org[Garrett D'Amore] - -SEE ALSO --------- -<<nng.adoc#,nng(7)>> - -COPYRIGHT ---------- - -Copyright 2017 mailto:garrett@damore.org[Garrett D'Amore] + -Copyright 2017 mailto:info@capitar.com[Capitar IT Group BV] - -This document is supplied under the terms of the -https://opensource.org/licenses/LICENSE.txt[MIT License]. |
