8.7 KiB
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 |
| worldId | integer | Fixed value representing the virtual data center of Earth. | no |
| worldTimestamp | integer | Timestamp of the last root server topology change. | 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 |
| assignedAddresses | [string] | ZeroTier-managed IP address assignments as array of IP/netmask bits tuples | no |
| routes | [route] | ZeroTier-managed route assignments for a network. See below for a description of the route object. | no |
| portDeviceName | string | OS-specific network device name (if available) | no |
| allowManaged | boolean | Whether ZeroTier-managed IP addresses are allowed. | yes |
| allowGlobal | boolean | Whether globally-reachable IP addresses are allowed to be assigned. | yes |
| allowDefault | boolean | Whether a default route is allowed to be assigned for the network (route all traffic via ZeroTier) | yes |
route objects
| Field | Type | Description | Writable |
| target | string | Target network / netmask bits, NULL, or 0.0.0.0/0 for default route | no |
| via | string | Gateway IP address | no |
| flags | integer | Route flags | no |
| metric | integer | Route metric (not currently used) | 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 |
| 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 |