From 390c147518d882384038c16431e60fdf810c862e Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Tue, 24 Oct 2017 12:21:48 -0700 Subject: Initial github pages commit. --- _adoc/build.sh | 69 +++++++++++ _adoc/index.adoc | 15 +++ _adoc/logo.png | Bin 0 -> 3103 bytes _adoc/man/index.adoc | 8 ++ _adoc/man/v0.0.0/README.adoc | 8 ++ _adoc/man/v0.0.0/nng.adoc | 88 ++++++++++++++ _adoc/man/v0.0.0/nng_zerotier.adoc | 231 +++++++++++++++++++++++++++++++++++++ _config.yml | 1 + _includes/footer.html | 1 + _includes/header.html | 19 +++ _layouts/default.html | 6 + 11 files changed, 446 insertions(+) create mode 100755 _adoc/build.sh create mode 100644 _adoc/index.adoc create mode 100644 _adoc/logo.png create mode 100644 _adoc/man/index.adoc create mode 100644 _adoc/man/v0.0.0/README.adoc create mode 100644 _adoc/man/v0.0.0/nng.adoc create mode 100644 _adoc/man/v0.0.0/nng_zerotier.adoc create mode 100644 _config.yml create mode 100644 _includes/footer.html create mode 100644 _includes/header.html create mode 100644 _layouts/default.html diff --git a/_adoc/build.sh b/_adoc/build.sh new file mode 100755 index 00000000..d029d3ea --- /dev/null +++ b/_adoc/build.sh @@ -0,0 +1,69 @@ +#!/bin/sh + +# This shell script takes our content from _adoc and runs it through +# asciidoctor and applies front matter that Jekyll will see. Its kind +# of annoying, since Jekyll on github-pages doesn't support asciidoctor +# properly. + +cd $(dirname $0) +for f in $(find . -name '*.adoc'); do + + input=${f#./} + indir=$(dirname $f) + indir=${indir#./} + output=../${input%.adoc}.html + outdir=../${indir} + + when=$(git log -n1 --format='%ad' '--date=format-local:%s' $f) + echo "Processing $input -> $output" + infrontmatter=0 + manpage=0 + frontmatter= + case $input in + v[0-9]*) + vers=${input#v} + vers=${vers%%/*} + aargs="${aargs} -aversion-label=nanomsg -arevnumber=${vers} -dmanpage" + manpage=1 + ;; + esac + while read line; do + if [[ "$line" == "---" ]] + then + if (( $infrontmatter != 0 )) + then + break + else + infrontmatter=1 + fi + elif [[ "$infrontmatter" != 0 ]] + then + if [[ -z "$frontmater" ]] + then + frontmatter="$line" + else + frontmatter="$frontmatter\n$line" + fi + elif (( $manpage != 0 )) + then + frontmatter="version: ${vers}\nlayout: default" + break + else + break + fi + + done < $input + + if [[ -n "$indir" ]] && [[ ! -d "$outdir" ]] + then + mkdir -p $outdir + fi + + if [[ -n "$frontmatter" ]] + then + echo "---" + echo "$frontmatter" + echo "---" + env SOURCE_DATE_EPOCH=${when} asciidoctor ${aargs} -b html5 -o - -a skip-front-matter $input + fi > $output +done diff --git a/_adoc/index.adoc b/_adoc/index.adoc new file mode 100644 index 00000000..f9746f72 --- /dev/null +++ b/_adoc/index.adoc @@ -0,0 +1,15 @@ +nng - nanomsg-NG +================ + +image:https://img.shields.io/badge/license-MIT-blue.svg[MIT License] +image:https://img.shields.io/travis/nanomsg/nng/master.svg?label=linux[Linux Status,link="https://travis-ci.org/nanomsg/nng"] +image:https://img.shields.io/appveyor/ci/nanomsg/nng/master.svg?label=windows[Windows Status,link="https://ci.appveyor.com/project/nanomsg/nng"] +image:https://codecov.io/gh/nanomsg/nng/branch/master/graph/badge.svg?label=coverage[Coverage,link="https://codecov.io/gh/nanomsg/nng"] + +This is the documentation for _nng_. This is all very preliminary at this +point. + +A reference manual is available <. + +Please see the https://github.com/nanomsg/nng[GitHub Repsitory] for further +information. diff --git a/_adoc/logo.png b/_adoc/logo.png new file mode 100644 index 00000000..5d0761c4 Binary files /dev/null and b/_adoc/logo.png differ diff --git a/_adoc/man/index.adoc b/_adoc/man/index.adoc new file mode 100644 index 00000000..489dbec5 --- /dev/null +++ b/_adoc/man/index.adoc @@ -0,0 +1,8 @@ +--- +title: Documentation +layout: default +--- + +== Documentation + +* Browse the nng reference manual <>. diff --git a/_adoc/man/v0.0.0/README.adoc b/_adoc/man/v0.0.0/README.adoc new file mode 100644 index 00000000..5030ec42 --- /dev/null +++ b/_adoc/man/v0.0.0/README.adoc @@ -0,0 +1,8 @@ +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/_adoc/man/v0.0.0/nng.adoc b/_adoc/man/v0.0.0/nng.adoc new file mode 100644 index 00000000..8a9d2596 --- /dev/null +++ b/_adoc/man/v0.0.0/nng.adoc @@ -0,0 +1,88 @@ +nng(7) +====== +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 7 +:icons:font +:copyright: Copyright 2017 Garrett D'Amore \ + Copyright 2017 Capitar IT Group BV \ + 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 +~~~~~~~~~ + +* <> - Bus protocol +* <> - Pair protocol +* <> - Publish/Subscribe protocol +* <> - Request/Reply protocol +* <> - Survey/Respond protocol + +Transports +~~~~~~~~~~ + +* <> - Intra-process transport +* <> - Inter-process transport +* <> - TCP (and TCPv6) transport +* <> - ZeroTier transport + +AUTHORS +------- +link:mailto:garrett@damore.org[Garrett D'Amore] + +SEE ALSO +-------- +<> + +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/_adoc/man/v0.0.0/nng_zerotier.adoc b/_adoc/man/v0.0.0/nng_zerotier.adoc new file mode 100644 index 00000000..c8a658ef --- /dev/null +++ b/_adoc/man/v0.0.0/nng_zerotier.adoc @@ -0,0 +1,231 @@ +nng_zerotier(7) +=============== +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 7 +:icons: font +:source-highlighter: pygments +:copyright: Copyright 2017 Garrett D'Amore \ + Copyright 2017 Capitar IT Group BV \ + 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 * + +*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 +-------- +<> + +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/_config.yml b/_config.yml new file mode 100644 index 00000000..251f7719 --- /dev/null +++ b/_config.yml @@ -0,0 +1 @@ +latest: 0.0.0 diff --git a/_includes/footer.html b/_includes/footer.html new file mode 100644 index 00000000..e0860ee3 --- /dev/null +++ b/_includes/footer.html @@ -0,0 +1 @@ +"nanomsg" and "nng" are trademarks of Garrett D'Amore. diff --git a/_includes/header.html b/_includes/header.html new file mode 100644 index 00000000..87a1ebd9 --- /dev/null +++ b/_includes/header.html @@ -0,0 +1,19 @@ +
+ + + + + + + + + + + +
nanomsg NextGen2
+Home GitHub Documentation +
+ +
+
+
diff --git a/_layouts/default.html b/_layouts/default.html new file mode 100644 index 00000000..3e5ec98e --- /dev/null +++ b/_layouts/default.html @@ -0,0 +1,6 @@ +{% include header.html %} +{% if page.version and page.version != site.latest %} + {% include old_version.html %} +{% endif %} +{{ content }} +{% include footer.html %} -- cgit v1.2.3-70-g09d2