NNG_ZEROTIER(7)

📦
version 1.12.0 · 4 versions
, in ubuntu stonking

💖 NNG_ZEROTIER(7) 💖

ok so bestie, welcome to the NNG Reference Manual entry for the ZeroTier transport. grab a boba, this one's a whole journey ✨

🌸 NAME 🌸

nng_zerotier — the ZeroTier transport, fr fr 🦋

✨ SYNOPSIS ✨

#include <nng/transport/zerotier/zerotier.h>

int nng_zt_register(void);

💅 DESCRIPTION 💅

okay so the zt transport is what lets your NNG apps chat over a ZeroTier network (that's <http://www.zerotier.com> if you wanna go look), using a Virtual Layer 2 packet facility. it's giving virtual ethernet but make it networked 🌈

⚠️ Important — this transport is experimental, like literally. to use it rn, the library has to be built with support for it, and linked against a suitable libzerotiercore library. more deets about building with this support live in the build documentation that ships with the distribution. iykyk 📚
⚠️ Important — libzerotiercore at present is covered under different license terms than the rest of NNG. please be careful to review and adhere to the licensing terms. no cap, read the license 🙈
⚠️ Important — the ZeroTier transport can take a long time to establish an initial connection — like, up to even a minute in extreme cases, while the network topology is configuring itself 😭. so yeah, this transport is not recommended for use cases involving short-lived programs. it's way better for long-running programs, like background daemons or agents. main character energy = patience 💜

so here's the tea: even though ZeroTier does make 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. which means all those considerations about IP address management? mitigated. gone. not a thing 🎀

this service uses Ethernet type 901 to transport packets. so network rules must permit this Ethernet type to pass, otherwise your network is not functional. periodt 🔥

📝 Note — this document assumes the reader is already familiar with ZeroTier concepts and administration. do your homework bestie, this isn't ZeroTier 101 🧚

🛠️ Registration

depending on how the library was built, it may be necessary to register the transport by calling nng_zt_register(). that function returns zero on success, or an nng error value if the transport can't be initialized for any reason. slay ✅

🔗 URI Format

this transport uses URIs with the scheme zt://, then a node number (ten hexadecimal digits), then a . delimiter, then a network address (sixteen hexadecimal digits), then a colon (:) and a service or port number (a decimal value, up to 24-bits).

so for example, the URI zt://fedcba9876.0123456789abdef:999 says: node fedcba9876 on network 0123456789abcdef is listening on port 999. iconic ✨

and the special value * can be used instead of a node number to represent the node's own node number. cute right? 🌟

listeners may use port 0 to say "idk just pick a suitable port number automatically." applications that do this must figure out the selected port number using the nng_listener_getopt() function. mystery port, but make it solvable 🕵️

🧬 Socket Address

when you're using an nng_sockaddr structure, the actual structure is of type nng_sockaddr_zt. that's it, that's the whole vibe 🌸

👻 Node Presence

by default, this transport creates an "ephemeral" node, and uses that same ephemeral node for any additional endpoints created. and because this node is ephemeral, the keys associated with it and all associated data live in memory and get discarded upon application termination. poof, gone 💨

if a persistent node is what you want instead, go check out the NNG_OPT_ZT_HOME option. 👑

also worth knowing: a single application can join multiple networks using the same node, or using separate nodes. multitasking queen 💅

📡 Network Status

a ZeroTier node can be in one of these states, which you can grab with the NNG_OPT_ZT_NETWORK_STATUS option:

  • NNG_ZT_STATUS_UP — the ZeroTier network is up 🟢. this is the only state where it's 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 yet. hold on bestie ⏳
  • NNG_ZT_STATUS_DENIED — the node does not have permission to join the ZeroTier network. ouch 🚫
  • NNG_ZT_STATUS_NOTFOUND — the ZeroTier network is not found. where is she 🔍
  • 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. update her 🙈
  • NNG_ZT_STATUS_UNKNOWN — the network is in an unknown state. this should not happen, because it means the ZeroTier software is reporting an unexpected status. the network is most likely not available. spooky 😭

🎀 Transport Options 🎀

the following transport options are available:

  • NNG_OPT_ZT_HOME — (string) this option represents the home directory, where the transport can store (and reuse) persistent state, like 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. multiple personalities, all valid 💜
  • NNG_OPT_ZT_NWID — (uint64_t) the 64-bit ZeroTier network number (native byte order). 🔢
  • NNG_OPT_ZT_NODE — (uint64_t) the ZeroTier 40-bit node address (native byte order). 🌟
  • NNG_OPT_ZT_NETWORK_STATUS — (int) the ZeroTier network status. see Network Status above for the full explanation of this option. 📡
  • NNG_OPT_ZT_NETWORK_NAME — (string) the name of the network as established by the ZeroTier network administrator. named by admin, respected by us 👑
  • NNG_OPT_ZT_CONN_TIME — (nng_duration) the time to wait between sending connection attempts. only used with dialers. default is 500 msec. ⏱️
  • NNG_OPT_ZT_CONN_TRIES — (int) the maximum number of attempts to try to establish a connection before reporting a timeout, and it's only used with dialers. default is 240, which gives you a 2 minute timeout if NNG_OPT_ZT_CONN_TIME is at its default of 500. and if you set this value to 0, then connection attempts will keep retrying forever. forever ever 🔁
  • NNG_OPT_ZT_PING_TIME — (nng_duration) 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. you good? you alive? 👋
  • NNG_OPT_ZT_PING_TRIES — (int) if this number 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. rip 💀
  • NNG_OPT_ZT_MTU — (size_t) the ZeroTier virtual network MTU (read-only) as configured on the network; 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 it, and each protocol may consume additional space, typically not more than 16-bytes.) 📏
  • NNG_OPT_ZT_ORBIT — (uint64_t[2]) write-only 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 its root server ID, which is conventional.) 🌙🚀
  • NNG_OPT_ZT_DEORBIT — (uint64_t) write-only option indicating the moon ID to deorbit. if the node is not already orbiting the moon, then this has no effect. bye moon 👋🌙

👀 SEE ALSO 👀

nng_sockaddr_zt(5), nng(7)

that's the whole page bestie, go forth and ZeroTier responsibly 💖✨🦋

this was the NNG Reference Manual, entry for June 30, 2026 — mwah, stay slay 💅🎀

📦 where this page comes from