From 8a20acfa34e1eedf34254354b8a219bd8fbca2ed Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Wed, 7 Mar 2018 17:06:16 -0800 Subject: fixes #269 nngcat unreliable with ZeroTier transport This does a few things. First it closes a case where a dropped message could prevent subsequent connection attempts from getting through. Second, it changes the rate at which we retry, and the timeout, to be a lot more aggressive when attempting to establish a connection. We retry every 500 ms, for up to 2 minutes, before giving up. This gives a lot more resilience in the face of message loss that is typical of ZeroTier in some environments when first establishing communication. Third, makes the values for the connection attempts *tunable*, so that applications can adjust for different deployment scenarios. Fourth, it includes the ability to get the UDP socket name. This was needed during some debug, and may be useful for a real UDP transport later, so we're keeping it. Finally, we added documentation for the above items. --- docs/man/nng_zerotier.adoc | 71 ++++++++++++++++++++++++++++++---------------- 1 file changed, 47 insertions(+), 24 deletions(-) (limited to 'docs/man') diff --git a/docs/man/nng_zerotier.adoc b/docs/man/nng_zerotier.adoc index 1b26ea6e..a36f20de 100644 --- a/docs/man/nng_zerotier.adoc +++ b/docs/man/nng_zerotier.adoc @@ -28,15 +28,21 @@ 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 +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. +linking against a suitable `libzerotiercore` static library. -NOTE: The `libzerotiercore` library at present is covered under different +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. @@ -93,6 +99,10 @@ 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 @@ -169,40 +179,53 @@ in this fashion. 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). + 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`:: +`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. + 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.) + 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.) + 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. + 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 -- cgit v1.2.3-70-g09d2