Preface
Because there’s very little information on this topic online, and I sometimes found myself scratching my head while using it, I’m writing this down for future reference. ZeroTier protocol, hereinafter referred to as the protocol. As of this article’s writing date of 2024/04/11, it is at v1. The v2 version is said to be a major overhaul, but it has been vaporware for four years now, and this kind of network infrastructure should stay backward compatible, so the information here should largely remain valid long-term, with the current version prevailing on the fine details.
What is Planet
To achieve this VL1 is organized like DNS. At the base of the network is a collection of always-present root servers whose role is similar to that of DNS root name servers. Roots run the same software as regular endpoints but reside at fast stable locations on the network and are designated as such by a world definition. World definitions come in two forms: the planet and one or more moons. The protocol includes a secure mechanism allowing world definitions to be updated in-band if root servers’ IP addresses or ZeroTier addresses change. There is only one planet. Earth’s root servers are operated by ZeroTier, Inc. as a free service. There are currently four root servers distributed across the globe and multiple network providers. Almost everyone in the world has one within less than 100ms network latency from their location.
Actually, I think the Planet in ZeroTier is very, very similar to the global root servers in the movie The Wandering Earth
In the ZeroTier world, everything revolves around the Planet. You can think of it as the root servers in DNS (they do indeed call them RootServers in the protocol). When nodes come online, they all try to connect to the Planet to obtain information about other nodes. The officially provided Planet servers are free. The Planet’s functions include recording the network information of all online nodes (remember this), recording the keys used for inter-node connections and providing exchange services, and providing relay when nodes cannot connect to each other directly.
The only paid service ZeroTier Inc. provides is the web-based Controller. Its 25-device limit can be bypassed simply by setting up our own Controller, but a self-hosted Controller lacks features like SSO and Ruler.
On first startup, zerotier obtains all the connection information it needs from the Planet. It first tries to locate Moon (if configured) information by ID and caches it; if it cannot connect to the Planet, it connects to the cached Moon.
What is Moon
The relationship between Planet and Moon can be understood as: Moon is a Root Server you establish yourself. Its functions are basically exactly the same as the Planet’s. If you choose to self-host a Moon server, to ensure stability the official recommendation is that the Moon server not take on other network functions (such as being a LEAF). This also means that as long as you know someone else’s Moon server ID, you can join it directly without their consent.
How to join a Moon
zerotier-cli orbit <world ID> <seed> - Join a moon via any member root#一般情况下world ID和seed可以一样Link-layer structure
The ZeroTier link layer is divided into VL1 and VL2. VL1 is the peer-to-peer network, used only to connect to the infrastructure Planet and Moon to obtain network configuration. In most cases it’s zero-configuration and needs no attention. VL2 is the Ethernet virtualization layer — the network you create yourself through my.zerotier.com or a Controller you build yourself. Planet/Moon are ZeroTier VL1-layer facilities, mainly used to assist in establishing connections between peers. Controller is a VL2-layer facility, mainly used to store the virtual network configuration. A device in a virtual network must first access VL1 to communicate with the Controller, and only then can it join a virtual network in VL2.
Node types
After running zerotier-cli peers, the <role> field shows each node’s type. These types are roles within the VL1 layer. They include LEAF, PLANET, MOON.
LEAF is an ordinary node; generally your device becomes a LEAF right after connecting.
Controller
The Controller resides in VL2 of the link layer and is a special LEAF within VL1. To join a network, or to connect to other nodes on that network, you first need to connect to that network’s corresponding Controller. If you cannot connect to the Controller, it will keep showing Request Configure.
If you’ve read the above carefully, you should understand that the Controller doesn’t need a public IP, but it does require a stable connection. For this reason, I run my Controller on a Moon myself, though the official docs actually don’t recommend doing so ZeroTier officially provides a way to set up a Controller, but the official method is command-line based. Someone has already wrapped a GUI around it, named ztncui.
Setting up ztncui
https://key-networks.com/ztncui/ Note that it’s best not to access the Controller you’ve set up over a ZeroTier network — if something goes wrong, you can easily lose access. I recommend accessing it via a CloudFlare Tunnel, where you can also set up two-step verification for better security. ztncui uses HTTPS by default and has no HTTP protocol; its certificate is self-signed. To map it to a domain via Cloudflare Tunnel, you need to enable “Allow any certificate” in Cloudflare (because by default the Tunnel doesn’t trust self-signed certificates) for it to be accessible properly.
Below are some useful quick commands.
Quick commands for setting up a Moon
cd /var/lib/zerotier-onesudo su#zerotier-idtool initmoon identity.public > moon.jsonexit
#下面几行可以保存为一个脚本，之后只用改moon.json里面的stablePointzerotier-idtool genmoon moon.jsonsudo mv 000000??????????.moon moons.d/sudo systemctl restart zerotier-one