Netconf docs, add clock field to status, simplify netconf a bit by eliminating caching for now. We will re-add if it is needed.

controller/SqliteNetworkController.cpp

@@ -64,9 +64,6 @@
 // API version reported via JSON control plane
 #define ZT_NETCONF_CONTROLLER_API_VERSION 1
 
-// Maximum age in ms for a cached netconf before we regenerate anyway (one hour)
-#define ZT_CACHED_NETCONF_MAX_AGE (60 * 60 * 1000)
-
 namespace ZeroTier {
 
 namespace {
@@ -96,11 +93,6 @@ static std::string _jsonEscape(const std::string &s) { return _jsonEscape(s.c_st
 struct MemberRecord {
 	int64_t rowid;
 	char nodeId[16];
-	int cachedNetconfBytes;
-	const void *cachedNetconf;
-	uint64_t cachedNetconfRevision;
-	uint64_t cachedNetconfTimestamp;
-	uint64_t clientReportedRevision;
 	bool authorized;
 	bool activeBridge;
 };
@@ -156,13 +148,12 @@ SqliteNetworkController::SqliteNetworkController(const char *dbPath) :
 
 	if (
 			  (sqlite3_prepare_v2(_db,"SELECT name,private,enableBroadcast,allowPassiveBridging,v4AssignMode,v6AssignMode,multicastLimit,creationTime,revision FROM Network WHERE id = ?",-1,&_sGetNetworkById,(const char **)0) != SQLITE_OK)
-			||(sqlite3_prepare_v2(_db,"SELECT rowid,cachedNetconf,cachedNetconfRevision,cachedNetconfTimestamp,clientReportedRevision,authorized,activeBridge FROM Member WHERE networkId = ? AND nodeId = ?",-1,&_sGetMember,(const char **)0) != SQLITE_OK)
+			||(sqlite3_prepare_v2(_db,"SELECT rowid,authorized,activeBridge FROM Member WHERE networkId = ? AND nodeId = ?",-1,&_sGetMember,(const char **)0) != SQLITE_OK)
-			||(sqlite3_prepare_v2(_db,"INSERT INTO Member (networkId,nodeId,cachedNetconfRevision,clientReportedRevision,authorized,activeBridge) VALUES (?,?,0,0,?,0)",-1,&_sCreateMember,(const char **)0) != SQLITE_OK)
+			||(sqlite3_prepare_v2(_db,"INSERT INTO Member (networkId,nodeId,authorized,activeBridge) VALUES (?,?,?,0)",-1,&_sCreateMember,(const char **)0) != SQLITE_OK)
 			||(sqlite3_prepare_v2(_db,"SELECT identity FROM Node WHERE id = ?",-1,&_sGetNodeIdentity,(const char **)0) != SQLITE_OK)
 			||(sqlite3_prepare_v2(_db,"INSERT INTO Node (id,identity,lastAt,lastSeen,firstSeen) VALUES (?,?,?,?,?)",-1,&_sCreateNode,(const char **)0) != SQLITE_OK)
 			||(sqlite3_prepare_v2(_db,"UPDATE Node SET lastAt = ?,lastSeen = ? WHERE id = ?",-1,&_sUpdateNode,(const char **)0) != SQLITE_OK)
 			||(sqlite3_prepare_v2(_db,"UPDATE Node SET lastSeen = ? WHERE id = ?",-1,&_sUpdateNode2,(const char **)0) != SQLITE_OK)
-			||(sqlite3_prepare_v2(_db,"UPDATE Member SET clientReportedRevision = ? WHERE rowid = ?",-1,&_sUpdateMemberClientReportedRevision,(const char **)0) != SQLITE_OK)
 			||(sqlite3_prepare_v2(_db,"SELECT etherType FROM Rule WHERE networkId = ? AND \"action\" = 'accept'",-1,&_sGetEtherTypesFromRuleTable,(const char **)0) != SQLITE_OK)
 			||(sqlite3_prepare_v2(_db,"SELECT mgMac,mgAdi,preload,maxBalance,accrual FROM MulticastRate WHERE networkId = ?",-1,&_sGetMulticastRates,(const char **)0) != SQLITE_OK)
 			||(sqlite3_prepare_v2(_db,"SELECT nodeId FROM Member WHERE networkId = ? AND activeBridge > 0 AND authorized > 0",-1,&_sGetActiveBridges,(const char **)0) != SQLITE_OK)
@@ -170,10 +161,9 @@ SqliteNetworkController::SqliteNetworkController(const char *dbPath) :
 			||(sqlite3_prepare_v2(_db,"SELECT ipNetwork,ipNetmaskBits FROM IpAssignmentPool WHERE networkId = ? AND ipVersion = ?",-1,&_sGetIpAssignmentPools,(const char **)0) != SQLITE_OK)
 			||(sqlite3_prepare_v2(_db,"SELECT 1 FROM IpAssignment WHERE networkId = ? AND ip = ? AND ipVersion = ?",-1,&_sCheckIfIpIsAllocated,(const char **)0) != SQLITE_OK)
 			||(sqlite3_prepare_v2(_db,"INSERT INTO IpAssignment (networkId,nodeId,ip,ipNetmaskBits,ipVersion) VALUES (?,?,?,?,?)",-1,&_sAllocateIp,(const char **)0) != SQLITE_OK)
-			||(sqlite3_prepare_v2(_db,"UPDATE Member SET cachedNetconf = ?,cachedNetconfRevision = ? WHERE rowid = ?",-1,&_sCacheNetconf,(const char **)0) != SQLITE_OK)
 			||(sqlite3_prepare_v2(_db,"SELECT nodeId,phyAddress FROM Relay WHERE networkId = ? ORDER BY nodeId ASC",-1,&_sGetRelays,(const char **)0) != SQLITE_OK)
 			||(sqlite3_prepare_v2(_db,"SELECT id FROM Network ORDER BY id ASC",-1,&_sListNetworks,(const char **)0) != SQLITE_OK)
-			||(sqlite3_prepare_v2(_db,"SELECT m.authorized,m.activeBridge,n.id,n.lastAt,n.lastSeen,n.firstSeen FROM Member AS m,Node AS n WHERE m.networkId = ? AND n.id = m.nodeId ORDER BY n.id ASC",-1,&_sListNetworkMembers,(const char **)0) != SQLITE_OK)
+			||(sqlite3_prepare_v2(_db,"SELECT n.id FROM Member AS m,Node AS n WHERE m.networkId = ? AND n.id = m.nodeId ORDER BY n.id ASC",-1,&_sListNetworkMembers,(const char **)0) != SQLITE_OK)
 			||(sqlite3_prepare_v2(_db,"SELECT m.authorized,m.activeBridge,n.identity,n.lastAt,n.lastSeen,n.firstSeen FROM Member AS m,Node AS n WHERE m.networkId = ? AND m.nodeId = ?",-1,&_sGetMember2,(const char **)0) != SQLITE_OK)
 			||(sqlite3_prepare_v2(_db,"SELECT ipNetwork,ipNetmaskBits,ipVersion FROM IpAssignmentPool WHERE networkId = ? ORDER BY ipNetwork ASC",-1,&_sGetIpAssignmentPools2,(const char **)0) != SQLITE_OK)
 			||(sqlite3_prepare_v2(_db,"SELECT ruleId,nodeId,vlanId,vlanPcp,etherType,macSource,macDest,ipSource,ipDest,ipTos,ipProtocol,ipSourcePort,ipDestPort,\"action\" FROM Rule WHERE networkId = ? ORDER BY ruleId ASC",-1,&_sListRules,(const char **)0) != SQLITE_OK)
@@ -205,7 +195,6 @@ SqliteNetworkController::~SqliteNetworkController()
 		sqlite3_finalize(_sCreateNode);
 		sqlite3_finalize(_sUpdateNode);
 		sqlite3_finalize(_sUpdateNode2);
-		sqlite3_finalize(_sUpdateMemberClientReportedRevision);
 		sqlite3_finalize(_sGetEtherTypesFromRuleTable);
 		sqlite3_finalize(_sGetMulticastRates);
 		sqlite3_finalize(_sGetActiveBridges);
@@ -213,7 +202,6 @@ SqliteNetworkController::~SqliteNetworkController()
 		sqlite3_finalize(_sGetIpAssignmentPools);
 		sqlite3_finalize(_sCheckIfIpIsAllocated);
 		sqlite3_finalize(_sAllocateIp);
-		sqlite3_finalize(_sCacheNetconf);
 		sqlite3_finalize(_sGetRelays);
 		sqlite3_finalize(_sListNetworks);
 		sqlite3_finalize(_sListNetworkMembers);
@@ -332,21 +320,13 @@ NetworkController::ResultCode SqliteNetworkController::doNetworkConfigRequest(co
 	if (sqlite3_step(_sGetMember) == SQLITE_ROW) {
 		foundMember = true;
 		member.rowid = (int64_t)sqlite3_column_int64(_sGetMember,0);
-		member.cachedNetconfBytes = sqlite3_column_bytes(_sGetMember,1);
+		member.authorized = (sqlite3_column_int(_sGetMember,1) > 0);
-		member.cachedNetconf = sqlite3_column_blob(_sGetMember,1);
+		member.activeBridge = (sqlite3_column_int(_sGetMember,2) > 0);
-		member.cachedNetconfRevision = (uint64_t)sqlite3_column_int64(_sGetMember,2);
-		member.cachedNetconfTimestamp = (uint64_t)sqlite3_column_int64(_sGetMember,3);
-		member.clientReportedRevision = (uint64_t)sqlite3_column_int64(_sGetMember,4);
-		member.authorized = (sqlite3_column_int(_sGetMember,5) > 0);
-		member.activeBridge = (sqlite3_column_int(_sGetMember,6) > 0);
 	}
 
 	// Create Member record for unknown nodes, auto-authorizing if network is public
 
 	if (!foundMember) {
-		member.cachedNetconfBytes = 0;
-		member.cachedNetconfRevision = 0;
-		member.clientReportedRevision = 0;
 		member.authorized = (network.isPrivate ? false : true);
 		member.activeBridge = false;
 		sqlite3_reset(_sCreateMember);
@@ -364,32 +344,15 @@ NetworkController::ResultCode SqliteNetworkController::doNetworkConfigRequest(co
 	if (!member.authorized)
 		return NetworkController::NETCONF_QUERY_ACCESS_DENIED;
 
-	// Update client's currently reported haveRevision in Member record
-
-	if (member.rowid > 0) {
-		sqlite3_reset(_sUpdateMemberClientReportedRevision);
-		sqlite3_bind_int64(_sUpdateMemberClientReportedRevision,1,(sqlite3_int64)haveRevision);
-		sqlite3_bind_int64(_sUpdateMemberClientReportedRevision,2,member.rowid);
-		sqlite3_step(_sUpdateMemberClientReportedRevision);
-	}
-
 	// If netconf is unchanged from client reported revision, just tell client they're up to date
 
 	if ((haveRevision > 0)&&(haveRevision == network.revision))
 		return NetworkController::NETCONF_QUERY_OK_BUT_NOT_NEWER;
 
-	// Generate or retrieve cached netconf
+	// Create and sign netconf
 
 	netconf.clear();
-	if ( (member.cachedNetconfBytes > 0)&&
+	{
-		   (member.cachedNetconfRevision == network.revision)&&
-		   ((OSUtils::now() - member.cachedNetconfTimestamp) < ZT_CACHED_NETCONF_MAX_AGE) ) {
-		// Use cached copy
-		std::string tmp((const char *)member.cachedNetconf,member.cachedNetconfBytes);
-		netconf.fromString(tmp);
-	} else {
-		// Create and sign a new netconf, and save in database to re-use in the future
-
 		char tss[24],rs[24];
 		Utils::snprintf(tss,sizeof(tss),"%.16llx",(unsigned long long)OSUtils::now());
 		Utils::snprintf(rs,sizeof(rs),"%.16llx",(unsigned long long)network.revision);
@@ -574,16 +537,6 @@ NetworkController::ResultCode SqliteNetworkController::doNetworkConfigRequest(co
 			netconf["error"] = "unable to sign netconf dictionary";
 			return NETCONF_QUERY_INTERNAL_SERVER_ERROR;
 		}
-
-		// Save serialized netconf for future re-use
-		std::string netconfSerialized(netconf.toString());
-		if (netconfSerialized.length() < 4096) { // sanity check
-			sqlite3_reset(_sCacheNetconf);
-			sqlite3_bind_blob(_sCacheNetconf,1,(const void *)netconfSerialized.data(),netconfSerialized.length(),SQLITE_STATIC);
-			sqlite3_bind_int64(_sCacheNetconf,2,(sqlite3_int64)network.revision);
-			sqlite3_bind_int64(_sCacheNetconf,3,member.rowid);
-			sqlite3_step(_sCacheNetconf);
-		}
 	}
 
 	return NetworkController::NETCONF_QUERY_OK;
@@ -622,7 +575,8 @@ unsigned int SqliteNetworkController::handleControlPlaneHttpGET(
 					if (sqlite3_step(_sGetMember2) == SQLITE_ROW) {
 						Utils::snprintf(json,sizeof(json),
 							"{\n"
-							"\taddress: \"%s\"\n"
+							"\tnwid: \"%s\",\n"
+							"\taddress: \"%s\",\n"
 							"\tauthorized: %s,\n"
 							"\tactiveBridge: %s,\n"
 							"\tlastAt: \"%s\",\n"
@@ -630,6 +584,7 @@ unsigned int SqliteNetworkController::handleControlPlaneHttpGET(
 							"\tfirstSeen: %llu,\n"
 							"\tidentity: \"%s\",\n"
 							"\tipAssignments: [",
+							nwids,
 							addrs,
 							(sqlite3_column_int(_sGetMember2,0) > 0) ? "true" : "false",
 							(sqlite3_column_int(_sGetMember2,1) > 0) ? "true" : "false",
@@ -674,7 +629,7 @@ unsigned int SqliteNetworkController::handleControlPlaneHttpGET(
 						"\tmulticastLimit: %d,\n"
 						"\tcreationTime: %llu,\n",
 						"\trevision: %llu,\n"
-						"\tmembers: [",
+						"\amembers: [",
 						nwids,
 						_jsonEscape((const char *)sqlite3_column_text(_sGetNetworkById,0)).c_str(),
 						(sqlite3_column_int(_sGetNetworkById,1) > 0) ? "true" : "false",
@@ -691,23 +646,11 @@ unsigned int SqliteNetworkController::handleControlPlaneHttpGET(
 					sqlite3_bind_text(_sListNetworkMembers,1,nwids,16,SQLITE_STATIC);
 					bool firstMember = true;
 					while (sqlite3_step(_sListNetworkMembers) == SQLITE_ROW) {
-						Utils::snprintf(json,sizeof(json),
+						if (!firstMember)
-							"%s{\n"
+							responseBody.push_back(',');
-							"\t\taddress: \"%s\",\n"
+						responseBody.push_back('"');
-							"\t\tauthorized: %s,\n"
+						responseBody.append((const char *)sqlite3_column_text(_sListNetworkMembers,0));
-							"\t\tactiveBridge: %s,\n"
+						responseBody.push_back('"');
-							"\t\tlastAt: \"%s\",\n"
-							"\t\tlastSeen: %llu,\n"
-							"\t\tfirstSeen: %llu\n"
-							"\t}",
-							firstMember ? "\n\t" : ",",
-							(const char *)sqlite3_column_text(_sListNetworkMembers,2),
-							(sqlite3_column_int(_sListNetworkMembers,0) > 0) ? "true" : "false",
-							(sqlite3_column_int(_sListNetworkMembers,1) > 0) ? "true" : "false",
-							_jsonEscape((const char *)sqlite3_column_text(_sListNetworkMembers,3)).c_str(),
-							(unsigned long long)sqlite3_column_int64(_sListNetworkMembers,4),
-							(unsigned long long)sqlite3_column_int64(_sListNetworkMembers,5));
-						responseBody.append(json);
 						firstMember = false;
 					}
 					responseBody.append("],\n\trelays: [");

controller/SqliteNetworkController.hpp

@@ -94,7 +94,6 @@ private:
 	sqlite3_stmt *_sCreateNode;
 	sqlite3_stmt *_sUpdateNode;
 	sqlite3_stmt *_sUpdateNode2;
-	sqlite3_stmt *_sUpdateMemberClientReportedRevision;
 	sqlite3_stmt *_sGetEtherTypesFromRuleTable;
 	sqlite3_stmt *_sGetMulticastRates;
 	sqlite3_stmt *_sGetActiveBridges;
@@ -102,7 +101,6 @@ private:
 	sqlite3_stmt *_sGetIpAssignmentPools;
 	sqlite3_stmt *_sCheckIfIpIsAllocated;
 	sqlite3_stmt *_sAllocateIp;
-	sqlite3_stmt *_sCacheNetconf;
 	sqlite3_stmt *_sGetRelays;
 	sqlite3_stmt *_sListNetworks;
 	sqlite3_stmt *_sListNetworkMembers;

controller/schema.sql

@@ -29,10 +29,6 @@ CREATE INDEX IpAssignmentPool_networkId ON IpAssignmentPool (networkId);
 CREATE TABLE Member (
   networkId char(16) NOT NULL,
   nodeId char(10) NOT NULL,
-  cachedNetconf blob(4096),
-  cachedNetconfRevision integer NOT NULL DEFAULT(0),
-  cachedNetconfTimestamp integer NOT NULL DEFAULT(0),
-  clientReportedRevision integer NOT NULL DEFAULT(0),
   authorized integer NOT NULL DEFAULT(0),
   activeBridge integer NOT NULL DEFAULT(0)
 );

service/ControlPlane.cpp

@@ -360,7 +360,8 @@ unsigned int ControlPlane::handleRequest(
 					"\t\"versionMajor\":%d,\n"
 					"\t\"versionMinor\":%d,\n"
 					"\t\"versionRev\":%d,\n"
-					"\t\"version\":\"%d.%d.%d\"\n"
+					"\t\"version\":\"%d.%d.%d\",\n"
+					"\t\"clock\": %llu\n"
 					"}\n",
 					status.address,
 					status.publicIdentity,
@@ -368,7 +369,8 @@ unsigned int ControlPlane::handleRequest(
 					ZEROTIER_ONE_VERSION_MAJOR,
 					ZEROTIER_ONE_VERSION_MINOR,
 					ZEROTIER_ONE_VERSION_REVISION,
-					ZEROTIER_ONE_VERSION_MAJOR,ZEROTIER_ONE_VERSION_MINOR,ZEROTIER_ONE_VERSION_REVISION);
+					ZEROTIER_ONE_VERSION_MAJOR,ZEROTIER_ONE_VERSION_MINOR,ZEROTIER_ONE_VERSION_REVISION,
+					(unsigned long long)OSUtils::now());
 				responseBody = json;
 				scode = 200;
 			} else if (ps[0] == "config") {

service/README.md

@@ -0,0 +1,239 @@
+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*.
+
+### JSON API
+
+The JSON API supports GET, POST/PUT, and DELETE. PUT is treated as a synonym for POST.
+
+Any JSON objects POSTed to the service are *extremely* type-sensitive due to the simple embedded C JSON parser that we use. If, for example, an integer field is quoted as a string, its contents may be ignored or an error 400 may be returned. Integer fields must be ASCII integers (no decimal point), and boolean fields must be *true* or *false*.
+
+Each request to the API 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 *authToken* URL parameter (e.g. '?authToken=...') or via the *X-ZT1-Auth* HTTP request header. Static UI pages will be served without authentication but all other requests require it. In addition, a *jsonp* URL argument may be supplied to invoke JSONP response behavior. In this mode, JSON responses are passed into the function specified by the *jsonp* URL argument's value (e.g. '?jsonp=myJsonPHandler').
+
+#### /status
+
+ * Purpose: Get running node status and addressing info
+ * 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>online</td><td>boolean</td><td>Does this node appear to have upstream network access?</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>
+
+#### /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. 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.
+
+<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>multicastSubscriptions</td><td>[string]</td><td>Multicast memberships as array of MAC/ADI tuples</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>portDeviceName</td><td>string</td><td>OS-specific network device name (if available)</td><td>no</td></tr>
+</table>
+
+#### /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 }
+
+<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>lastUnicastFrame</td><td>integer</td><td>Time of last unicast frame in ms since epoch</td><td>no</td></tr>
+<tr><td>lastMulticastFrame</td><td>integer</td><td>Time of last multicast frame in ms since epoch</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 SUPERNODE</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>
+
+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:
+
+<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>
+
+### 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 }
+
+<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>controller</td><td>boolean</td><td>Always 'true' if controller is running</td><td>no</td></tr>
+<tr><td>apiVersion</td><td>integer</td><td>JSON API version, currently 1</td><td>no</td></tr>
+<tr><td>clock</td><td>integer</td><td>Controller system clock in ms since epoch</td><td>no</td></tr>
+</table>
+
+#### /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 }
+
+DELETE for networks is final. Don't do this unless you really mean it!
+
+<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>name</td><td>string</td><td>Short network name (max: 127 chars)</td><td>yes</td></tr>
+<tr><td>private</td><td>boolean</td><td>False if public network, true for access control</td><td>yes</td></tr>
+<tr><td>enableBroadcast</td><td>boolean</td><td>True to allow Ethernet broadcast (ff:ff:ff:ff:ff:ff)</td><td>yes</td></tr>
+<tr><td>allowPassiveBridging</td><td>boolean</td><td>True to allow any member to bridge (experimental!)</td><td>yes</td></tr>
+<tr><td>v4AssignMode</td><td>string</td><td>'none', 'zt', or 'dhcp' (see below)</td><td>yes</td></tr>
+<tr><td>v6AssignMode</td><td>string</td><td>'none', 'zt', or 'dhcp' (see below)</td><td>yes</td></tr>
+<tr><td>multicastLimit</td><td>integer</td><td>Maximum number of multicast recipients per multicast/broadcast address</td><td>yes</td></tr>
+<tr><td>creationTime</td><td>integer</td><td>Time network was created in ms since epoch</td><td>no</td></tr>
+<tr><td>revision</td><td>integer</td><td>Network config revision number</td><td>no</td></tr>
+<tr><td>members</td><td>[string]</td><td>Array of ZeroTier addresses of network members</td><td>no</td></tr>
+<tr><td>relays</td><td>[object]</td><td>Array of network-specific relay nodes (see below)</td><td>yes</td></tr>
+<tr><td>ipAssignmentPools</td><td>[object]</td><td>Array of IP auto-assignment pools for 'zt' assignment mode</td><td>yes</td></tr>
+<tr><td>rules</td><td>[object]</td><td>Array of network flow rules (see below)</td><td>yes</td></tr>
+</table>
+
+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 supernode infrastructure.
+
+<table>
+<tr><td><b>Field</b></td><td><b>Type</b></td><td><b>Description</b></td></tr>
+<tr><td>address</td><td>string</td><td>10-digit ZeroTier address of relay node</td></tr>
+<tr><td>phyAddress</td><td>string</td><td>Fixed path address in IP/port format e.g. 192.168.1.1/9993</td></tr>
+</table>
+
+**IP assignment pool object format:**
+
+<table>
+<tr><td><b>Field</b></td><td><b>Type</b></td><td><b>Description</b></td></tr>
+<tr><td>network</td><td>string</td><td>IP network e.g. 192.168.0.0</td></tr>
+<tr><td>netmaskBits</td><td>integer</td><td>IP network netmask bits e.g. 16 for 255.255.0.0</td></tr>
+</table>
+
+**Rule object format:**
+
+ * **Note**: at the moment, <u>only rules specifying allowed Ethernet types are used</u>. The database supports a richer rule set, but this is not implemented yet in the client. <u>Other types of rules will have no effect</u> (yet).
+
+Rules are matched in order of ruleId. 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.
+
+<table>
+<tr><td><b>Field</b></td><td><b>Type</b></td><td><b>Description</b></td></tr>
+<tr><td>ruleId</td><td>integer</td><td>User-defined rule ID and sort order</td></tr>
+<tr><td>nodeId</td><td>string</td><td>10-digit hex ZeroTier address of node (a.k.a. "port on switch")</td></tr>
+<tr><td>vlanId</td><td>integer</td><td>Ethernet VLAN ID</td></tr>
+<tr><td>vlanPcp</td><td>integer</td><td>Ethernet VLAN priority code point (PCP) ID</td></tr>
+<tr><td>etherType</td><td>integer</td><td>Ethernet frame type</td></tr>
+<tr><td>macSource</td><td>string</td><td>Ethernet source MAC address</td></tr>
+<tr><td>macDest</td><td>string</td><td>Ethernet destination MAC address</td></tr>
+<tr><td>ipSource</td><td>string</td><td>Source IP address</td></tr>
+<tr><td>ipDest</td><td>string</td><td>Destination IP address</td></tr>
+<tr><td>ipTos</td><td>integer</td><td>IP TOS field</td></tr>
+<tr><td>ipProtocol</td><td>integer</td><td>IP protocol</td></tr>
+<tr><td>ipSourcePort</td><td>integer</td><td>IP source port</td></tr>
+<tr><td>ipDestPort</td><td>integer</td><td>IP destination port</td></tr>
+<tr><td>action</td><td>string</td><td>Rule action: accept, drop, etc.</td></tr>
+</table>
+
+#### /controller/network/\<network ID\>/member/\<address\>
+
+ * Purpose: Create, authorize, or remove a network member
+ * Methods: GET, POST, DELETE
+ * 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>nwid</td><td>string</td><td>16-digit hex network ID</td><td>no</td></tr>
+<tr><td>address</td><td>string</td><td>10-digit hex ZeroTier address</td><td>no</td></tr>
+<tr><td>authorized</td><td>boolean</td><td>Is member authorized?</td><td>yes</td></tr>
+<tr><td>activeBridge</td><td>boolean</td><td>This member is an active network bridge</td><td>yes</td></tr>
+<tr><td>lastAt</td><td>string</td><td>Socket address (e.g. IP/port) where member was last seen</td><td>no</td></tr>
+<tr><td>lastSeen</td><td>integer</td><td>Timestamp of member's last request in ms since epoch</td><td>no</td></tr>
+<tr><td>firstSeen</td><td>integer</td><td>Timestamp member was first seen in ms since epoch</td><td>no</td></tr>
+<tr><td>identity</td><td>string</td><td>Full ZeroTier identity of member</td><td>no</td></tr>
+<tr><td>ipAssignments</td><td>[string]</td><td>Array of IP/bits IP assignments</td><td>yes</td></tr>
+</table>