ExternalVendorCode/ZeroTierOne
1
0
Fork 0
mirror of https://github.com/zerotier/ZeroTierOne.git synced 2025-02-06 11:10:13 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs and API stuff

Browse Source
This commit is contained in:
Adam Ierymenko 2016-11-23 15:53:53 -08:00
parent 84732fcb12
commit 27f1155f1b
3 changed files with 94 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
service/ControlPlane.cpp
View File

@ -123,6 +123,7 @@ static void _jsonAppend(unsigned int depth,std::string &buf,const ZT_VirtualNetw
Utils::snprintf(json,sizeof(json), Utils::snprintf(json,sizeof(json),
"%s{\n" "%s{\n"
"%s\t\"id\": \"%.16llx\",\n"
"%s\t\"nwid\": \"%.16llx\",\n" "%s\t\"nwid\": \"%.16llx\",\n"
"%s\t\"mac\": \"%.2x:%.2x:%.2x:%.2x:%.2x:%.2x\",\n" "%s\t\"mac\": \"%.2x:%.2x:%.2x:%.2x:%.2x:%.2x\",\n"
"%s\t\"name\": \"%s\",\n" "%s\t\"name\": \"%s\",\n"
@ -143,6 +144,7 @@ static void _jsonAppend(unsigned int depth,std::string &buf,const ZT_VirtualNetw
"%s}", "%s}",
prefix, prefix,
prefix,nc->nwid, 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,(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,_jsonEscape(nc->name).c_str(),
prefix,nstatus, prefix,nstatus,

7
service/OneService.cpp
View File

@ -1179,7 +1179,8 @@ public:
if ((nstr.length() == ZT_ADDRESS_LENGTH_HEX)&&(v.value().is_object())) { if ((nstr.length() == ZT_ADDRESS_LENGTH_HEX)&&(v.value().is_object())) {
const Address ztaddr(nstr.c_str()); const Address ztaddr(nstr.c_str());
if (ztaddr) { 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(); const uint64_t ztaddr2 = ztaddr.toInt();
std::vector<InetAddress> &v4h = _v4Hints[ztaddr2]; std::vector<InetAddress> &v4h = _v4Hints[ztaddr2];
@ -1239,9 +1240,9 @@ public:
json &settings = _localConfig["settings"]; json &settings = _localConfig["settings"];
if (settings.is_object()) { if (settings.is_object()) {
const std::string rp(_jS(settings["relayPolicy"],"")); const std::string rp(_jS(settings["relayPolicy"],""));
if (rp == "always") if ((rp == "always")||(rp == "ALWAYS"))
_node->setRelayPolicy(ZT_RELAY_POLICY_ALWAYS); _node->setRelayPolicy(ZT_RELAY_POLICY_ALWAYS);
else if (rp == "never") else if ((rp == "never")||(rp == "NEVER"))
_node->setRelayPolicy(ZT_RELAY_POLICY_NEVER); _node->setRelayPolicy(ZT_RELAY_POLICY_NEVER);
else _node->setRelayPolicy(ZT_RELAY_POLICY_TRUSTED); else _node->setRelayPolicy(ZT_RELAY_POLICY_TRUSTED);
} }

163
service/README.md
View File

@ -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. 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 ### Network Virtualization Service API
@ -21,32 +44,19 @@ A *jsonp* URL argument may be supplied to request JSONP encapsulation. A JSONP r
* Methods: GET * Methods: GET
* Returns: { object } * Returns: { object }
<table> | Field | Type | Description | Writable |
<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> | address | string | 10-digit hex ZeroTier address of this node | no |
<tr><td>publicIdentity</td><td>string</td><td>Full public ZeroTier identity of this node</td><td>no</td></tr> | publicIdentity | string | This node's ZeroTier identity.public | no |
<tr><td>worldId</td><td>integer</td><td>Fixed value representing the virtual data center of Earth.</td><td>no</td></tr> | worldId | integer | ZeroTier world ID (never changes except for test) | no |
<tr><td>worldTimestamp</td><td>integer</td><td>Timestamp of the last root server topology change.</td><td>no</td></tr> | worldTimestamp | integer | Timestamp of most recent world definition | no |
<tr><td>online</td><td>boolean</td><td>Does this node appear to have upstream network access?</td><td>no</td></tr> | online | boolean | If true at least one upstream peer is reachable | no |
<tr><td>tcpFallbackActive</td><td>boolean</td><td>Is TCP fallback mode active?</td><td>no</td></tr> | tcpFallbackActive | boolean | If true we are using slow TCP fallback | no |
<tr><td>versionMajor</td><td>integer</td><td>ZeroTier major version</td><td>no</td></tr> | versionMajor | integer | Software major version | no |
<tr><td>versionMinor</td><td>integer</td><td>ZeroTier minor version</td><td>no</td></tr> | versionMinor | integer | Software minor version | no |
<tr><td>versionRev</td><td>integer</td><td>ZeroTier revision</td><td>no</td></tr> | versionRev | integer | Software revision | no |
<tr><td>version</td><td>string</td><td>Version in major.minor.rev format</td><td>no</td></tr> | version | string | major.minor.revision | no |
<tr><td>clock</td><td>integer</td><td>Node system clock in ms since epoch</td><td>no</td></tr> | clock | integer | Current system clock at node (ms since epoch) | no |
</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>
#### /network #### /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. Most network settings are not writable, as they are defined by the network controller.
<table> | Field | Type | Description | Writable |
<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> | id | string | 16-digit hex network ID | no |
<tr><td>mac</td><td>string</td><td>Ethernet MAC address of virtual network port</td><td>no</td></tr> | nwid | string | 16-digit hex network ID (legacy field) | no |
<tr><td>name</td><td>string</td><td>Network short name as configured on network controller</td><td>no</td></tr> | mac | string | MAC address of network device for this network | no |
<tr><td>status</td><td>string</td><td>Network status: OK, ACCESS_DENIED, PORT_ERROR, etc.</td><td>no</td></tr> | name | string | Short name of this network (from controller) | no |
<tr><td>type</td><td>string</td><td>Network type, currently PUBLIC or PRIVATE</td><td>no</td></tr> | status | string | Network status (OK, ACCESS_DENIED, etc.) | no |
<tr><td>mtu</td><td>integer</td><td>Ethernet MTU</td><td>no</td></tr> | type | string | Network type (PUBLIC or PRIVATE) | no |
<tr><td>dhcp</td><td>boolean</td><td>If true, DHCP may be used to obtain an IP address</td><td>no</td></tr> | mtu | integer | Ethernet MTU | no |
<tr><td>bridge</td><td>boolean</td><td>If true, this node may bridge in other Ethernet devices</td><td>no</td></tr> | dhcp | boolean | If true, DHCP should be used to get IP info | no |
<tr><td>broadcastEnabled</td><td>boolean</td><td>Is Ethernet broadcast (ff:ff:ff:ff:ff:ff) allowed?</td><td>no</td></tr> | bridge | boolean | If true, this device can bridge others | no |
<tr><td>portError</td><td>integer</td><td>Error code (if any) returned by underlying OS "tap" driver</td><td>no</td></tr> | broadcastEnabled | boolean | If true ff:ff:ff:ff:ff:ff broadcasts work | no |
<tr><td>netconfRevision</td><td>integer</td><td>Network configuration revision ID</td><td>no</td></tr> | portError | integer | Error code returned by underlying tap driver | no |
<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> | netconfRevision | integer | Network configuration revision ID | no |
<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> | assignedAddresses | [string] | Array of ZeroTier-assigned IP addresses (/bits) | no |
<tr><td>portDeviceName</td><td>string</td><td>OS-specific network device name (if available)</td><td>no</td></tr> | routes | [object] | Array of ZeroTier-assigned routes (see below) | no |
<tr><td>allowManaged</td><td>boolean</td><td>Whether ZeroTier-managed IP addresses are allowed.</td><td>yes</td></tr> | portDeviceName | string | Name of virtual network device (if any) | no |
<tr><td>allowGlobal</td><td>boolean</td><td>Whether globally-reachable IP addresses are allowed to be assigned.</td><td>yes</td></tr> | allowManaged | boolean | Allow IP and route management | yes |
<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> | allowGlobal | boolean | Allow IPs and routes that overlap with global IPs | yes |
</table> | allowDefault | boolean | Allow overriding of system default route | yes |
`route` objects Route objects:
<table> | Field | Type | Description | Writable |
<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> | target | string | Target network / netmask bits | no |
<tr><td>via</td><td>string</td><td>Gateway IP address</td><td>no</td></tr> | via | string | Gateway IP address (next hop) or null for LAN | no |
<tr><td>flags</td><td>integer</td><td>Route flags</td><td>no</td></tr> | flags | integer | Flags, currently always 0 | no |
<tr><td>metric</td><td>integer</td><td>Route metric (not currently used)</td><td>no</td></tr> | metric | integer | Route metric (not currently used) | no |
</table>
#### /peer #### /peer
@ -107,29 +116,29 @@ Getting /peer returns an array of peer objects for all current peers. See below
#### /peer/\<address\> #### /peer/\<address\>
* Purpose: Get information about a peer * Purpose: Get or set information about a peer
* Methods: GET * Methods: GET, POST
* Returns: { object } * Returns: { object }
<table> | Field | Type | Description | Writable |
<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> | address | string | 10-digit hex ZeroTier address of peer | no |
<tr><td>versionMajor</td><td>integer</td><td>Major version of remote if known</td><td>no</td></tr> | versionMajor | integer | Major version of remote (if known) | no |
<tr><td>versionMinor</td><td>integer</td><td>Minor version of remote if known</td><td>no</td></tr> | versionMinor | integer | Minor version of remote (if known) | no |
<tr><td>versionRev</td><td>integer</td><td>Revision of remote if known</td><td>no</td></tr> | versionRev | integer | Software revision of remote (if known) | no |
<tr><td>version</td><td>string</td><td>Version in major.minor.rev format</td><td>no</td></tr> | version | string | major.minor.revision | no |
<tr><td>latency</td><td>integer</td><td>Latency in milliseconds if known</td><td>no</td></tr> | latency | integer | Latency in milliseconds if known | no |
<tr><td>role</td><td>string</td><td>LEAF, HUB, or ROOTSERVER</td><td>no</td></tr> | role | string | LEAF, UPSTREAM, or ROOT | no |
<tr><td>paths</td><td>[object]</td><td>Array of path objects (see below)</td><td>no</td></tr> | paths | [object] | Currently active physical paths (see below) | no |
</table>
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> | Field | Type | Description | Writable |
<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> | address | string | Physical socket address e.g. IP/port | no |
<tr><td>lastSend</td><td>integer</td><td>Last send via this path in ms since epoch</td><td>no</td></tr> | lastSend | integer | Time of last send through this path | no |
<tr><td>lastReceive</td><td>integer</td><td>Last receive via this path in ms since epoch</td><td>no</td></tr> | lastReceive | integer | Time of last receive through this path | no |
<tr><td>fixed</td><td>boolean</td><td>If true, this is a statically-defined "fixed" path</td><td>no</td></tr> | active | boolean | Is this path in use? | no |
<tr><td>preferred</td><td>boolean</td><td>If true, this is the current preferred path</td><td>no</td></tr> | expired | boolean | Is this path expired? | no |
</table> | preferred | boolean | Is this a current preferred path? | no |
| trustedPathId | integer | If nonzero this is a trusted path (unencrypted) | no |