From 27f1155f1b2e7bbd61336837498d098b9e4f4a8d Mon Sep 17 00:00:00 2001 From: Adam Ierymenko Date: Wed, 23 Nov 2016 15:53:53 -0800 Subject: [PATCH] docs and API stuff --- service/ControlPlane.cpp | 6 +- service/OneService.cpp | 7 +- service/README.md | 163 +++++++++++++++++++++------------------ 3 files changed, 94 insertions(+), 82 deletions(-) diff --git a/service/ControlPlane.cpp b/service/ControlPlane.cpp index 2f9e746e1..21afee52f 100644 --- a/service/ControlPlane.cpp +++ b/service/ControlPlane.cpp @@ -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), diff --git a/service/OneService.cpp b/service/OneService.cpp index a2024e520..6cfaeb0ea 100644 --- a/service/OneService.cpp +++ b/service/OneService.cpp @@ -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 &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); } diff --git a/service/README.md b/service/README.md index f487f2bc0..45f06fcf7 100644 --- a/service/README.md +++ b/service/README.md @@ -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 } - - - - - - - - - - - - - -
FieldTypeDescriptionWritable
addressstring10-digit hexadecimal ZeroTier address of this nodeno
publicIdentitystringFull public ZeroTier identity of this nodeno
worldIdintegerFixed value representing the virtual data center of Earth.no
worldTimestampintegerTimestamp of the last root server topology change.no
onlinebooleanDoes this node appear to have upstream network access?no
tcpFallbackActivebooleanIs TCP fallback mode active?no
versionMajorintegerZeroTier major versionno
versionMinorintegerZeroTier minor versionno
versionRevintegerZeroTier revisionno
versionstringVersion in major.minor.rev formatno
clockintegerNode system clock in ms since epochno
- -#### /config - - * Purpose: Get or set local configuration - * Methods: GET, POST - * Returns: { object } - -No local configuration options are exposed yet. - - - -
FieldTypeDescriptionWritable
+| 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. - - - - - - - - - - - - - - - - - - - -
FieldTypeDescriptionWritable
nwidstring16-digit hex network IDno
macstringEthernet MAC address of virtual network portno
namestringNetwork short name as configured on network controllerno
statusstringNetwork status: OK, ACCESS_DENIED, PORT_ERROR, etc.no
typestringNetwork type, currently PUBLIC or PRIVATEno
mtuintegerEthernet MTUno
dhcpbooleanIf true, DHCP may be used to obtain an IP addressno
bridgebooleanIf true, this node may bridge in other Ethernet devicesno
broadcastEnabledbooleanIs Ethernet broadcast (ff:ff:ff:ff:ff:ff) allowed?no
portErrorintegerError code (if any) returned by underlying OS "tap" driverno
netconfRevisionintegerNetwork configuration revision IDno
assignedAddresses[string]ZeroTier-managed IP address assignments as array of IP/netmask bits tuplesno
routes[route]ZeroTier-managed route assignments for a network. See below for a description of the route object.no
portDeviceNamestringOS-specific network device name (if available)no
allowManagedbooleanWhether ZeroTier-managed IP addresses are allowed.yes
allowGlobalbooleanWhether globally-reachable IP addresses are allowed to be assigned.yes
allowDefaultbooleanWhether a default route is allowed to be assigned for the network (route all traffic via ZeroTier)yes
+| 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: - - - - - - -
FieldTypeDescriptionWritable
targetstringTarget network / netmask bits, NULL, or 0.0.0.0/0 for default routeno
viastringGateway IP addressno
flagsintegerRoute flagsno
metricintegerRoute metric (not currently used)no
+| 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/\ - * Purpose: Get information about a peer - * Methods: GET + * Purpose: Get or set information about a peer + * Methods: GET, POST * Returns: { object } - - - - - - - - - - -
FieldTypeDescriptionWritable
addressstring10-digit hex ZeroTier addressno
versionMajorintegerMajor version of remote if knownno
versionMinorintegerMinor version of remote if knownno
versionRevintegerRevision of remote if knownno
versionstringVersion in major.minor.rev formatno
latencyintegerLatency in milliseconds if knownno
rolestringLEAF, HUB, or ROOTSERVERno
paths[object]Array of path objects (see below)no
+| 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: - - - - - - - -
FieldTypeDescriptionWritable
addressstringPhysical socket address e.g. IP/port for UDPno
lastSendintegerLast send via this path in ms since epochno
lastReceiveintegerLast receive via this path in ms since epochno
fixedbooleanIf true, this is a statically-defined "fixed" pathno
preferredbooleanIf true, this is the current preferred pathno
+| 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 |