ZeroTierOne/service/README.md

ZeroTier One Network Virtualization Service

This is the common background service implementation for ZeroTier One, the VPN-like OS-level network virtualization service.

It provides a ready-made core I/O loop and a local HTTP-based JSON control bus for controlling the service. This control bus HTTP server can also serve the files in ui/ if this folder's contents are installed in the ZeroTier home folder. The ui/ implements a React-based HTML5 user interface which is then wrappered for various platforms via MacGap, Windows .NET WebControl, etc. It can also be used locally from scripts or via curl.

Network Virtualization Service API

The JSON API supports GET, POST/PUT, and DELETE. PUT is treated as a synonym for POST. Other methods including HEAD are not supported.

Values POSTed to the JSON API are extremely type sensitive. Things must be of the indicated type, otherwise they will be ignored or will generate an error. Anything quoted is a string so booleans and integers must lack quotes. Booleans must be true or false and nothing else. Integers cannot contain decimal points or they are floats (and vice versa). If something seems to be getting ignored or set to a strange value, or if you receive errors, check the type of all JSON fields you are submitting against the types listed below. Unrecognized fields in JSON objects are also ignored.

API requests must be authenticated via an authentication token. ZeroTier One saves this token in the authtoken.secret file in its working directory. This token may be supplied via the auth URL parameter (e.g. '?auth=...') or via the X-ZT1-Auth HTTP request header. Static UI pages are the only thing the server will allow without authentication.

A jsonp URL argument may be supplied to request JSONP encapsulation. A JSONP response is sent as a script with its JSON response payload wrapped in a call to the function name supplied as the argument to jsonp.

/status

• Purpose: Get running node status and addressing info
• Methods: GET
• Returns: { object }

Field	Type	Description	Writable
address	string	10-digit hexadecimal ZeroTier address of this node	no
publicIdentity	string	Full public ZeroTier identity of this node	no
online	boolean	Does this node appear to have upstream network access?	no
tcpFallbackActive	boolean	Is TCP fallback mode active?	no
versionMajor	integer	ZeroTier major version	no
versionMinor	integer	ZeroTier minor version	no
versionRev	integer	ZeroTier revision	no
version	string	Version in major.minor.rev format	no
clock	integer	Node system clock in ms since epoch	no

/config

• Purpose: Get or set local configuration
• Methods: GET, POST
• Returns: { object }

No local configuration options are exposed yet.

Field

Type

Description

Writable

/network

• Purpose: Get all network memberships
• Methods: GET
• Returns: [ {object}, ... ]

Getting /network returns an array of all networks that this node has joined. See below for network object format.

/network/<network ID>

• Purpose: Get, join, or leave a network
• Methods: GET, POST, DELETE
• Returns: { object }

To join a network, POST to it. Since networks have no mandatory writable parameters, POST data is optional and may be omitted. Example: POST to /network/8056c2e21c000001 to join the public "Earth" network. To leave a network, DELETE it e.g. DELETE /network/8056c2e21c000001.

Most network settings are not writable, as they are defined by the network controller.

Field	Type	Description	Writable
nwid	string	16-digit hex network ID	no
mac	string	Ethernet MAC address of virtual network port	no
name	string	Network short name as configured on network controller	no
status	string	Network status: OK, ACCESS_DENIED, PORT_ERROR, etc.	no
type	string	Network type, currently PUBLIC or PRIVATE	no
mtu	integer	Ethernet MTU	no
dhcp	boolean	If true, DHCP may be used to obtain an IP address	no
bridge	boolean	If true, this node may bridge in other Ethernet devices	no
broadcastEnabled	boolean	Is Ethernet broadcast (ff:ff:ff:ff:ff:ff) allowed?	no
portError	integer	Error code (if any) returned by underlying OS "tap" driver	no
netconfRevision	integer	Network configuration revision ID	no
multicastSubscriptions	[string]	Multicast memberships as array of MAC/ADI tuples	no
assignedAddresses	[string]	ZeroTier-managed IP address assignments as array of IP/netmask bits tuples	no
portDeviceName	string	OS-specific network device name (if available)	no

/peer

• Purpose: Get all peers
• Methods: GET
• Returns: [ {object}, ... ]

Getting /peer returns an array of peer objects for all current peers. See below for peer object format.

/peer/<address>

• Purpose: Get information about a peer
• Methods: GET
• Returns: { object }

Field	Type	Description	Writable
address	string	10-digit hex ZeroTier address	no
lastUnicastFrame	integer	Time of last unicast frame in ms since epoch	no
lastMulticastFrame	integer	Time of last multicast frame in ms since epoch	no
versionMajor	integer	Major version of remote if known	no
versionMinor	integer	Minor version of remote if known	no
versionRev	integer	Revision of remote if known	no
version	string	Version in major.minor.rev format	no
latency	integer	Latency in milliseconds if known	no
role	string	LEAF, HUB, or ROOTSERVER	no
paths	[object]	Array of path objects (see below)	no

Path objects describe direct physical paths to peer. If no path objects are listed, peer is only reachable via indirect relay fallback. Path object format is:

Field	Type	Description	Writable
address	string	Physical socket address e.g. IP/port for UDP	no
lastSend	integer	Last send via this path in ms since epoch	no
lastReceive	integer	Last receive via this path in ms since epoch	no
fixed	boolean	If true, this is a statically-defined "fixed" path	no
preferred	boolean	If true, this is the current preferred path	no

Network Controller API

If ZeroTier One was built with ZT_ENABLE_NETWORK_CONTROLLER defined, the following API paths are available. Otherwise these paths will return 404.

/controller

• Purpose: Check for controller function and return controller status
• Methods: GET
• Returns: { object }

Field	Type	Description	Writable
controller	boolean	Always 'true' if controller is running	no
apiVersion	integer	JSON API version, currently 1	no
clock	integer	Controller system clock in ms since epoch	no

/controller/network

• Purpose: List all networks hosted by this controller
• Methods: GET
• Returns: [ string, ... ]

This returns an array of 16-digit hexadecimal network IDs. Unlike /network under the top-level API, it does not dump full network information for all networks as this may be quite large for a large controller.

/controller/network/<network ID>

• Purpose: Create, configure, and delete hosted networks
• Methods: GET, POST, DELETE
• Returns: { object }

By making queries to this path you can create, configure, and delete networks. DELETE is final, so don't do it unless you really mean it.

It's important to understand how network IDs work. The first ten digits (most significant 40 bits) of a network ID are the ZeroTier address of the controller. This is how clients find it. The last six digits (least significant 24 bits) are arbitrary and serve to identify the network uniquely on the controller.

Thus a network's first ten digits must be the controller's address. If your controller is deadbeef01, then the networks it controls must have IDs like deadbeef01feed02 or deadbeef01beef03. This API however does not enforce this requirement. It will allow you to add arbitrary network IDs, but they won't work since clients will never be able to find them.

To create a new network with a random last six digits safely and atomically, you can POST to /controller/network/##########______ where ########## is the controller's address and the underscores are as shown. This will pick a random unallocated network ID, which will be returned in the 'nwid' field of the returned JSON object.

Field	Type	Description	Writable
nwid	string	16-digit hex network ID	no
name	string	Short network name (max: 127 chars)	yes
private	boolean	False if public network, true for access control	yes
enableBroadcast	boolean	True to allow Ethernet broadcast (ff:ff:ff:ff:ff:ff)	yes
allowPassiveBridging	boolean	True to allow any member to bridge (experimental!)	yes
v4AssignMode	string	'none', 'zt', or 'dhcp' (see below)	yes
v6AssignMode	string	'none', 'zt', or 'dhcp' (see below)	yes
multicastLimit	integer	Maximum number of multicast recipients per multicast/broadcast address	yes
creationTime	integer	Time network was created in ms since epoch	no
revision	integer	Network config revision number	no
memberRevisionCounter	integer	Current value of network revision counter (incremented after every member add or revision)	no
relays	[object]	Array of network-specific relay nodes (see below)	yes
ipLocalRoutes	[string]	Array of IP network/netmask entries corresponding to networks routed directly via this interface (e.g. 10.0.0.0/8 to route 10.0.0.0 via this interface)
ipAssignmentPools	[object]	Array of IP auto-assignment pools for 'zt' assignment mode	yes
rules	[object]	Array of network flow rules (see below)	yes

The network member list includes both authorized and unauthorized members. DELETE unauthorized members to remove them from the list.

Relays, IP assignment pools, and rules are edited via direct POSTs to the network object. New values replace all previous values.

Relay object format:

Relay objects define network-specific preferred relay nodes. Traffic to peers on this network will preferentially use these relays if they are available, and otherwise will fall back to the global rootserver infrastructure.

Field	Type	Description
address	string	10-digit ZeroTier address of relay node
phyAddress	string	Fixed path address in IP/port format e.g. 192.168.1.1/9993

IP assignment pool object format:

IP assignment pools are only used if they are within a network specified in ipLocalRoutes.

Field	Type	Description
ipRangeStart	string	Start of IP assignment range
ipRangeEnd	string	End of IP assignment range

Rule object format:

• Note: at the moment, only rules specifying allowed Ethernet types are used. The database supports a richer rule set, but this is not implemented yet in the client. Other types of rules will have no effect (yet).

Rules are matched in order of ruleNo. If no rules match, the default action is 'drop'. To allow all traffic, create a single rule with all null fields and an action of 'accept'.

Rule object fields can be null, in which case they are omitted from the object. A null field indicates "no match on this criteria."

IP related fields apply only to Ethernet frames of type IPv4 or IPV6. Otherwise they are ignored.

Field	Type	Description
ruleNo	integer	User-defined rule ID and sort order
nodeId	string	10-digit hex ZeroTier address of node if this rule is local to only one member
sourcePort	string	10-digit hex ZeroTier address of source port on virtual switch (source device address)
destPort	string	10-digit hex ZeroTier address of destination port on virtual switch (destination device address)
vlanId	integer	Ethernet VLAN ID
vlanPcp	integer	Ethernet VLAN priority code point (PCP) ID
etherType	integer	Ethernet frame type
macSource	string	Ethernet source MAC address
macDest	string	Ethernet destination MAC address
ipSource	string	Source IP address
ipDest	string	Destination IP address
ipTos	integer	IP TOS field
ipProtocol	integer	IP protocol
ipSourcePort	integer	IP source port
ipDestPort	integer	IP destination port
action	string	Rule action: accept, drop, etc.

/controller/network/<network ID>/member/<address>

• Purpose: Create, authorize, or remove a network member
• Methods: GET, POST, DELETE
• Returns: { object }

Field	Type	Description	Writable
nwid	string	16-digit hex network ID	no
address	string	10-digit hex ZeroTier address	no
authorized	boolean	Is member authorized?	yes
activeBridge	boolean	This member is an active network bridge	yes
identity	string	Full ZeroTier identity of member	no
ipAssignments	[string]	Array of IP/bits IP assignments	yes
memberRevision	integer	Member revision counter value from network at time of last revision or member creation	no