mirror of
https://github.com/zerotier/ZeroTierOne.git
synced 2025-01-29 15:43:52 +00:00
docs and API stuff
This commit is contained in:
Adam Ierymenko
parent
84732fcb12
commit
27f1155f1b
@ -123,6 +123,7 @@ static void _jsonAppend(unsigned int depth,std::string &buf,const ZT_VirtualNetw
|
||||
|
||||
Utils::snprintf(json,sizeof(json),
|
||||
"%s{\n"
|
||||
"%s\t\"id\": \"%.16llx\",\n"
|
||||
"%s\t\"nwid\": \"%.16llx\",\n"
|
||||
"%s\t\"mac\": \"%.2x:%.2x:%.2x:%.2x:%.2x:%.2x\",\n"
|
||||
"%s\t\"name\": \"%s\",\n"
|
||||
@ -143,6 +144,7 @@ static void _jsonAppend(unsigned int depth,std::string &buf,const ZT_VirtualNetw
|
||||
"%s}",
|
||||
prefix,
|
||||
prefix,nc->nwid,
|
||||
prefix,nc->nwid,
|
||||
prefix,(unsigned int)((nc->mac >> 40) & 0xff),(unsigned int)((nc->mac >> 32) & 0xff),(unsigned int)((nc->mac >> 24) & 0xff),(unsigned int)((nc->mac >> 16) & 0xff),(unsigned int)((nc->mac >> 8) & 0xff),(unsigned int)(nc->mac & 0xff),
|
||||
prefix,_jsonEscape(nc->name).c_str(),
|
||||
prefix,nstatus,
|
||||
@ -214,9 +216,9 @@ static void _jsonAppend(unsigned int depth,std::string &buf,const ZT_Peer *peer)
|
||||
|
||||
const char *prole = "";
|
||||
switch(peer->role) {
|
||||
case ZT_PEER_ROLE_LEAF: prole = "LEAF"; break;
|
||||
case ZT_PEER_ROLE_LEAF: prole = "LEAF"; break;
|
||||
case ZT_PEER_ROLE_UPSTREAM: prole = "UPSTREAM"; break;
|
||||
case ZT_PEER_ROLE_ROOT: prole = "ROOT"; break;
|
||||
case ZT_PEER_ROLE_ROOT: prole = "ROOT"; break;
|
||||
}
|
||||
|
||||
Utils::snprintf(json,sizeof(json),
|
||||
|
||||
@ -1179,7 +1179,8 @@ public:
|
||||
if ((nstr.length() == ZT_ADDRESS_LENGTH_HEX)&&(v.value().is_object())) {
|
||||
const Address ztaddr(nstr.c_str());
|
||||
if (ztaddr) {
|
||||
_node->setRole(ztaddr.toInt(),(_jS(v.value()["role"],"") == "upstream") ? ZT_PEER_ROLE_UPSTREAM : ZT_PEER_ROLE_LEAF);
|
||||
const std::string rstr(_jS(v.value()["role"],""));
|
||||
_node->setRole(ztaddr.toInt(),((rstr == "upstream")||(rstr == "UPSTREAM")) ? ZT_PEER_ROLE_UPSTREAM : ZT_PEER_ROLE_LEAF);
|
||||
|
||||
const uint64_t ztaddr2 = ztaddr.toInt();
|
||||
std::vector<InetAddress> &v4h = _v4Hints[ztaddr2];
|
||||
@ -1239,9 +1240,9 @@ public:
|
||||
json &settings = _localConfig["settings"];
|
||||
if (settings.is_object()) {
|
||||
const std::string rp(_jS(settings["relayPolicy"],""));
|
||||
if (rp == "always")
|
||||
if ((rp == "always")||(rp == "ALWAYS"))
|
||||
_node->setRelayPolicy(ZT_RELAY_POLICY_ALWAYS);
|
||||
else if (rp == "never")
|
||||
else if ((rp == "never")||(rp == "NEVER"))
|
||||
_node->setRelayPolicy(ZT_RELAY_POLICY_NEVER);
|
||||
else _node->setRelayPolicy(ZT_RELAY_POLICY_TRUSTED);
|
||||
}
|
||||
|
||||
@ -3,7 +3,30 @@ 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*.
|
||||
### Local Configuration File
|
||||
|
||||
Example `local.conf`:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"physical": {
|
||||
"network/bits": {
|
||||
"trustedPathId": 0,
|
||||
"blacklist": false
|
||||
}
|
||||
},
|
||||
"virtual": {
|
||||
"##########": {
|
||||
"role": "UPSTREAM",
|
||||
"try": [ "IP/port" ],
|
||||
"blacklist": [ "network/bits" ]
|
||||
}
|
||||
},
|
||||
"settings": {
|
||||
"relayPolicy": "TRUSTED"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Network Virtualization Service API
|
||||
|
||||
@ -21,32 +44,19 @@ A *jsonp* URL argument may be supplied to request JSONP encapsulation. A JSONP r
|
||||
* Methods: GET
|
||||
* Returns: { object }
|
||||
|
||||
<table>
|
||||
<tr><td><b>Field</b></td><td><b>Type</b></td><td><b>Description</b></td><td><b>Writable</b></td></tr>
|
||||
<tr><td>address</td><td>string</td><td>10-digit hexadecimal ZeroTier address of this node</td><td>no</td></tr>
|
||||
<tr><td>publicIdentity</td><td>string</td><td>Full public ZeroTier identity of this node</td><td>no</td></tr>
|
||||
<tr><td>worldId</td><td>integer</td><td>Fixed value representing the virtual data center of Earth.</td><td>no</td></tr>
|
||||
<tr><td>worldTimestamp</td><td>integer</td><td>Timestamp of the last root server topology change.</td><td>no</td></tr>
|
||||
<tr><td>online</td><td>boolean</td><td>Does this node appear to have upstream network access?</td><td>no</td></tr>
|
||||
<tr><td>tcpFallbackActive</td><td>boolean</td><td>Is TCP fallback mode active?</td><td>no</td></tr>
|
||||
<tr><td>versionMajor</td><td>integer</td><td>ZeroTier major version</td><td>no</td></tr>
|
||||
<tr><td>versionMinor</td><td>integer</td><td>ZeroTier minor version</td><td>no</td></tr>
|
||||
<tr><td>versionRev</td><td>integer</td><td>ZeroTier revision</td><td>no</td></tr>
|
||||
<tr><td>version</td><td>string</td><td>Version in major.minor.rev format</td><td>no</td></tr>
|
||||
<tr><td>clock</td><td>integer</td><td>Node system clock in ms since epoch</td><td>no</td></tr>
|
||||
</table>
|
||||
|
||||
#### /config
|
||||
|
||||
* Purpose: Get or set local configuration
|
||||
* Methods: GET, POST
|
||||
* Returns: { object }
|
||||
|
||||
No local configuration options are exposed yet.
|
||||
|
||||
<table>
|
||||
<tr><td><b>Field</b></td><td><b>Type</b></td><td><b>Description</b></td><td><b>Writable</b></td></tr>
|
||||
</table>
|
||||
| Field | Type | Description | Writable |
|
||||
| --------------------- | ------------- | ------------------------------------------------- | -------- |
|
||||
| address | string | 10-digit hex ZeroTier address of this node | no |
|
||||
| publicIdentity | string | This node's ZeroTier identity.public | no |
|
||||
| worldId | integer | ZeroTier world ID (never changes except for test) | no |
|
||||
| worldTimestamp | integer | Timestamp of most recent world definition | no |
|
||||
| online | boolean | If true at least one upstream peer is reachable | no |
|
||||
| tcpFallbackActive | boolean | If true we are using slow TCP fallback | no |
|
||||
| versionMajor | integer | Software major version | no |
|
||||
| versionMinor | integer | Software minor version | no |
|
||||
| versionRev | integer | Software revision | no |
|
||||
| version | string | major.minor.revision | no |
|
||||
| clock | integer | Current system clock at node (ms since epoch) | no |
|
||||
|
||||
#### /network
|
||||
|
||||
@ -66,36 +76,35 @@ To join a network, POST to it. Since networks have no mandatory writable paramet
|
||||
|
||||
Most network settings are not writable, as they are defined by the network controller.
|
||||
|
||||
<table>
|
||||
<tr><td><b>Field</b></td><td><b>Type</b></td><td><b>Description</b></td><td><b>Writable</b></td></tr>
|
||||
<tr><td>nwid</td><td>string</td><td>16-digit hex network ID</td><td>no</td></tr>
|
||||
<tr><td>mac</td><td>string</td><td>Ethernet MAC address of virtual network port</td><td>no</td></tr>
|
||||
<tr><td>name</td><td>string</td><td>Network short name as configured on network controller</td><td>no</td></tr>
|
||||
<tr><td>status</td><td>string</td><td>Network status: OK, ACCESS_DENIED, PORT_ERROR, etc.</td><td>no</td></tr>
|
||||
<tr><td>type</td><td>string</td><td>Network type, currently PUBLIC or PRIVATE</td><td>no</td></tr>
|
||||
<tr><td>mtu</td><td>integer</td><td>Ethernet MTU</td><td>no</td></tr>
|
||||
<tr><td>dhcp</td><td>boolean</td><td>If true, DHCP may be used to obtain an IP address</td><td>no</td></tr>
|
||||
<tr><td>bridge</td><td>boolean</td><td>If true, this node may bridge in other Ethernet devices</td><td>no</td></tr>
|
||||
<tr><td>broadcastEnabled</td><td>boolean</td><td>Is Ethernet broadcast (ff:ff:ff:ff:ff:ff) allowed?</td><td>no</td></tr>
|
||||
<tr><td>portError</td><td>integer</td><td>Error code (if any) returned by underlying OS "tap" driver</td><td>no</td></tr>
|
||||
<tr><td>netconfRevision</td><td>integer</td><td>Network configuration revision ID</td><td>no</td></tr>
|
||||
<tr><td>assignedAddresses</td><td>[string]</td><td>ZeroTier-managed IP address assignments as array of IP/netmask bits tuples</td><td>no</td></tr>
|
||||
<tr><td>routes</td><td>[route]</td><td>ZeroTier-managed route assignments for a network. See below for a description of the route object.</td><td>no</td></tr>
|
||||
<tr><td>portDeviceName</td><td>string</td><td>OS-specific network device name (if available)</td><td>no</td></tr>
|
||||
<tr><td>allowManaged</td><td>boolean</td><td>Whether ZeroTier-managed IP addresses are allowed.</td><td>yes</td></tr>
|
||||
<tr><td>allowGlobal</td><td>boolean</td><td>Whether globally-reachable IP addresses are allowed to be assigned.</td><td>yes</td></tr>
|
||||
<tr><td>allowDefault</td><td>boolean</td><td>Whether a default route is allowed to be assigned for the network (route all traffic via ZeroTier)</td><td>yes</td></tr>
|
||||
</table>
|
||||
| Field | Type | Description | Writable |
|
||||
| --------------------- | ------------- | ------------------------------------------------- | -------- |
|
||||
| id | string | 16-digit hex network ID | no |
|
||||
| nwid | string | 16-digit hex network ID (legacy field) | no |
|
||||
| mac | string | MAC address of network device for this network | no |
|
||||
| name | string | Short name of this network (from controller) | no |
|
||||
| status | string | Network status (OK, ACCESS_DENIED, etc.) | no |
|
||||
| type | string | Network type (PUBLIC or PRIVATE) | no |
|
||||
| mtu | integer | Ethernet MTU | no |
|
||||
| dhcp | boolean | If true, DHCP should be used to get IP info | no |
|
||||
| bridge | boolean | If true, this device can bridge others | no |
|
||||
| broadcastEnabled | boolean | If true ff:ff:ff:ff:ff:ff broadcasts work | no |
|
||||
| portError | integer | Error code returned by underlying tap driver | no |
|
||||
| netconfRevision | integer | Network configuration revision ID | no |
|
||||
| assignedAddresses | [string] | Array of ZeroTier-assigned IP addresses (/bits) | no |
|
||||
| routes | [object] | Array of ZeroTier-assigned routes (see below) | no |
|
||||
| portDeviceName | string | Name of virtual network device (if any) | no |
|
||||
| allowManaged | boolean | Allow IP and route management | yes |
|
||||
| allowGlobal | boolean | Allow IPs and routes that overlap with global IPs | yes |
|
||||
| allowDefault | boolean | Allow overriding of system default route | yes |
|
||||
|
||||
`route` objects
|
||||
Route objects:
|
||||
|
||||
<table>
|
||||
<tr><td><b>Field</b></td><td><b>Type</b></td><td><b>Description</b></td><td><b>Writable</b></td></tr>
|
||||
<tr><td>target</td><td>string</td><td>Target network / netmask bits, NULL, or 0.0.0.0/0 for default route</td><td>no</td></tr>
|
||||
<tr><td>via</td><td>string</td><td>Gateway IP address</td><td>no</td></tr>
|
||||
<tr><td>flags</td><td>integer</td><td>Route flags</td><td>no</td></tr>
|
||||
<tr><td>metric</td><td>integer</td><td>Route metric (not currently used)</td><td>no</td></tr>
|
||||
</table>
|
||||
| Field | Type | Description | Writable |
|
||||
| --------------------- | ------------- | ------------------------------------------------- | -------- |
|
||||
| target | string | Target network / netmask bits | no |
|
||||
| via | string | Gateway IP address (next hop) or null for LAN | no |
|
||||
| flags | integer | Flags, currently always 0 | no |
|
||||
| metric | integer | Route metric (not currently used) | no |
|
||||
|
||||
#### /peer
|
||||
|
||||
@ -107,29 +116,29 @@ Getting /peer returns an array of peer objects for all current peers. See below
|
||||
|
||||
#### /peer/\<address\>
|
||||
|
||||
* Purpose: Get information about a peer
|
||||
* Methods: GET
|
||||
* Purpose: Get or set information about a peer
|
||||
* Methods: GET, POST
|
||||
* Returns: { object }
|
||||
|
||||
<table>
|
||||
<tr><td><b>Field</b></td><td><b>Type</b></td><td><b>Description</b></td><td><b>Writable</b></td></tr>
|
||||
<tr><td>address</td><td>string</td><td>10-digit hex ZeroTier address</td><td>no</td></tr>
|
||||
<tr><td>versionMajor</td><td>integer</td><td>Major version of remote if known</td><td>no</td></tr>
|
||||
<tr><td>versionMinor</td><td>integer</td><td>Minor version of remote if known</td><td>no</td></tr>
|
||||
<tr><td>versionRev</td><td>integer</td><td>Revision of remote if known</td><td>no</td></tr>
|
||||
<tr><td>version</td><td>string</td><td>Version in major.minor.rev format</td><td>no</td></tr>
|
||||
<tr><td>latency</td><td>integer</td><td>Latency in milliseconds if known</td><td>no</td></tr>
|
||||
<tr><td>role</td><td>string</td><td>LEAF, HUB, or ROOTSERVER</td><td>no</td></tr>
|
||||
<tr><td>paths</td><td>[object]</td><td>Array of path objects (see below)</td><td>no</td></tr>
|
||||
</table>
|
||||
| Field | Type | Description | Writable |
|
||||
| --------------------- | ------------- | ------------------------------------------------- | -------- |
|
||||
| address | string | 10-digit hex ZeroTier address of peer | no |
|
||||
| versionMajor | integer | Major version of remote (if known) | no |
|
||||
| versionMinor | integer | Minor version of remote (if known) | no |
|
||||
| versionRev | integer | Software revision of remote (if known) | no |
|
||||
| version | string | major.minor.revision | no |
|
||||
| latency | integer | Latency in milliseconds if known | no |
|
||||
| role | string | LEAF, UPSTREAM, or ROOT | no |
|
||||
| paths | [object] | Currently active physical paths (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:
|
||||
Path objects:
|
||||
|
||||
<table>
|
||||
<tr><td><b>Field</b></td><td><b>Type</b></td><td><b>Description</b></td><td><b>Writable</b></td></tr>
|
||||
<tr><td>address</td><td>string</td><td>Physical socket address e.g. IP/port for UDP</td><td>no</td></tr>
|
||||
<tr><td>lastSend</td><td>integer</td><td>Last send via this path in ms since epoch</td><td>no</td></tr>
|
||||
<tr><td>lastReceive</td><td>integer</td><td>Last receive via this path in ms since epoch</td><td>no</td></tr>
|
||||
<tr><td>fixed</td><td>boolean</td><td>If true, this is a statically-defined "fixed" path</td><td>no</td></tr>
|
||||
<tr><td>preferred</td><td>boolean</td><td>If true, this is the current preferred path</td><td>no</td></tr>
|
||||
</table>
|
||||
| Field | Type | Description | Writable |
|
||||
| --------------------- | ------------- | ------------------------------------------------- | -------- |
|
||||
| address | string | Physical socket address e.g. IP/port | no |
|
||||
| lastSend | integer | Time of last send through this path | no |
|
||||
| lastReceive | integer | Time of last receive through this path | no |
|
||||
| active | boolean | Is this path in use? | no |
|
||||
| expired | boolean | Is this path expired? | no |
|
||||
| preferred | boolean | Is this a current preferred path? | no |
|
||||
| trustedPathId | integer | If nonzero this is a trusted path (unencrypted) | no |
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user