Internet-Draft | NetJSON | July 2015 |
Capoano & Kaplan | Expires 1 February 2016 | [Page] |
NetJSON is a data interchange format based on JavaScript Object Notation (JSON) designed to describe the basic building blocks of layer2 and layer3 networking.¶
It defines several types of JSON objects and the manner in which they are combined to represent a network: configuration of devices, monitoring data, network topology and routing information.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 2 January 2016.¶
Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
NetJSON is a format for describing data about layer 2 and layer 3 networks using JavaScript Object Notation (JSON) [RFC7159] [RFC7159].¶
The format is concerned with the basic building blocks that compose a computer network (devices, monitoring data, routing, topology).¶
The concepts in NetJSON are not new; they are derived from existing conventions consolidated in open source projects related to the networking field, such as:¶
open source implementations of network monitoring tools like [Nagios] [Nagios]¶
dynamic routing protocols like [OLSRd] [OLSRd] ([RFC3626] [RFC3626] and [RFC7181] [RFC7181]), [Babel] [Babel] ([RFC6126] [RFC6126]), [Batman-adv] [Batman-adv] and [BMX] [BMX]¶
These concepts have been streamlined to encourage interoperability between network centric web applications using JSON.¶
Developing software that deals with networks is harder than it should be.¶
Developers have to take into account all the differences between vendors, operating systems, routing protocols, hardware and (when working with community networks) with the different approaches of each community.¶
Very often, each vendor develops an entire stack that works exclusively with its own hardware and software.¶
There exist many libraries and web apps for networking, but it is very hard to make them interoperable, that is, making them talk and understand one another with minimum effort.¶
This is an attempt to invert this trend, following the successful example of the GeoJSON format [GeoJSON].¶
By defining common data structures we can allow developers to focus on their goals instead of having to struggle with the differences of each vendor, firmware, routing protocol or community.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119].¶
The ordering of the members of any JSON object defined in this document MUST be considered irrelevant, as specified by RFC RFC7159 [RFC7159].¶
Some examples use the combination of a JavaScript single line comment (//) followed by an ellipsis (...) as placeholder notation for content deemed irrelevant by the authors. These placeholders must of course be deleted or otherwise replaced, before attempting to validate the corresponding JSON code example.¶
Whitespace is used in the examples inside this document to help illustrate the data structures, but is not required. Unquoted whitespace is not significant in JSON.¶
JavaScript Object Notation (JSON), and the terms "object", "member", "name", "value", "array", "number", "true", "false", and "null" are to be interpreted as defined in RFC RFC7159 [RFC7159].¶
The term "NetJSON type(s)" (sometimes abbreviated to "type(s)") refers to (one of) the five case-sensitive strings: "DeviceConfiguration", "DeviceMonitoring", "NetworkRoutes", "NetworkGraph" and "NetworkCollection".¶
The term "JSON Schema" (sometimes abbreviated as "schema"), refers to JSON-Schema [JSON-Schema] version 4.¶
NetJSON always consists of a single object, referred to as the "NetJSON object" below.¶
The top level of NetJSON text MUST be a JSON object.¶
The NetJSON object MUST have a member with the name "type". The value of the member MUST be one of the NetJSON types defined below.¶
The NetJSON object MAY have any number of other members not explicitly defined in this specification, referred as "custom members" below. Implementations MUST ignore unrecognized custom members.¶
Before adding any custom member, implementers SHOULD read the NetJSON extension registry in order to find existing custom members to reuse or to learn how to officially submit new custom members.¶
NetJSON defines the following types:¶
Definition: a list of routes of a dynamic routing protocol or statically configured on the device.¶
Goals: show internal information of a routing protocol for monitoring and debugging purposes.¶
Example: A.1. NetworkRoutes Example (Appendix A.1).¶
JSON Schema: B.1. NetworkRoutes Schema (Appendix B.1).¶
A NetworkRoutes object MUST define the following REQUIRED members:¶
key name | JSON type | description |
---|---|---|
type | string | MUST be "NetworkRoutes" |
protocol | string | name of the routing protocol implementation, may be "static" when representing static routes |
version | string | version of the routing protocol implementation, may be null when representing static routes |
metric | string | name of main routing metric used by the routing protocol to determine the best routes when sending packets, may be null when representing static routes |
routes | array | array of Route Objects (Section 3.1) |
A NetworkRoutes object MAY also define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
revision | string | string indicating the revision from which the routing protocol deamon binary was built (eg: git hash, svn revision) |
topology_id | string | arbitrary identifier of the topology |
router_id | string | arbitrary identifier of the router on which the protocol is running (eg: ip, mac, hash) |
Each route object MUST define the following REQUIRED members:¶
key name | JSON type | description |
---|---|---|
destination | string | the ip address, prefix or mac address that will be matched to the destination of the traffic |
next | string | the ip address or mac address of the next hop |
device | string | the interface the traffic will be going to, it may be omitted when representing static routes |
cost | number | value of the routing metric indicating the outgoing cost to reach the destination; lower cost is better, it MAY be omitted when representing static routes Infinity and NaN are not allowed in accordance with the JSON RFC [RFC7159] |
Each route object MAY also define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
cost_text | string | human readable representation of the cost member |
source | string | the source address of the route (used in source-specific routing) |
Definition: a list of nodes and links known by a node.¶
Goals: visualization of network topology, collect network topology from distance vector protocols, monitoring.¶
Example: A.2. NetworkGraph Example (Appendix A.2).¶
JSON Schema: B.2. NetworkGraph Schema (Appendix B.2).¶
A NetworkGraph object MUST define the following REQUIRED members:¶
key name | JSON type | description |
---|---|---|
type | string | MUST be "NetworkGraph" |
protocol | string | name of the routing protocol implementation, may be "static" when representing static routes |
version | string | version of the routing protocol implementation, may be null when representing static routes |
metric | string | name of main routing metric used by the routing protocol to determine the best routes when sending packets, may be null when representing static routes |
nodes | array | array of Node Objects (Section 4.1) |
links | array | array of Link Objects (Section 4.2) |
A NetworkGraph object MAY also define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
revision | string | string indicating the revision from which the routing protocol deamon binary was built (eg: git hash, svn revision) |
topology_id | string | arbitrary identifier of the topology |
router_id | string | arbitrary identifier of the router on which the protocol is running (eg: ip, mac, hash) |
label | string | a human readable label for the topology |
Each node object MUST define the following REQUIRED members:¶
key name | JSON type | description |
---|---|---|
id | string | arbitrary identifier of the node, eg: ipv4, ipv6, mac address, hash, ecc. |
Each node object MAY also define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
label | string | human readable label of the node |
local_addresses | array | array of strings representing additional addresses (mac/ip) which can be used to communicate with the node |
properties | object | object which MAY contain any arbitrary member; these arbitrary members SHOULD be visualized by user interface software |
Each link object MUST define the following REQUIRED members:¶
key name | JSON type | description |
---|---|---|
source | string | id of the source node |
target | string | id of the target node |
cost | number | value of the routing metric indicating the outgoing cost to reach the destination; lower cost is better, it MAY be omitted when representing static routes; Infinity and NaN are not allowed in accordance with the JSON RFC [RFC7159] |
Each link object MAY also define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
cost_text | string | human readable representation of the cost member; |
properties | object | object which MAY contain any arbitrary member; these arbitrary members SHOULD be visualized by user interface software |
Definition: configuration and properties of a network device.¶
Goals: configuration storage and management, import and export configurations between different monitoring tools or network controllers.¶
Example: A.3. DeviceConfiguration Example (Appendix A.3).¶
JSON Schema: B.3. DeviceConfiguration Schema (Appendix B.3).¶
A DeviceConfiguration object MUST define the following REQUIRED members:¶
key name | JSON type | description |
---|---|---|
type | string | MUST be "DeviceConfiguration" |
A DeviceConfiguration object MAY also define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
general | object | object that contains general information related to the network device, see General Object (Section 5.1) for details |
hardware | object | hardware information related to the network device, see Hardware Object (Section 5.1) for details |
operating_system | object | operating system information, see Operating System Object (Section 5.3) for details |
interfaces | array | array of objects that represent how network interfaces are configured on the device, see Interface Objects (Section 5.4) for details |
radios | array | array of objects that represent the configuration of radios available on the system, see Radio Objects (Section 5.5) for details |
routes | array | array of objects that represent static routes configured on the device, see Static Route Objects (Section 5.6) for details |
dns_servers | array | an array of strings denoting DNS servers configured on the device |
dns_search | array | an array of strings denoting DNS search paths configured on the device |
The "general" object of DeviceConfiguration MAY define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
hostname | string | hostname of the network device |
timezone | string | system timezone; the value of this member MUST be one of the values present in the Time Zone Database maintained by IANA |
maintainer | string | email address of the maintainer of the network device |
description | string | free-form textual description of the network device |
ula_prefix | string | IPv6 Unique Local Address prefix applicable to every network interface |
The "hardware" object of DeviceConfiguration MAY define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
manufacturer | string | name of the manufacturer |
model | string | name of the model |
version | string | version of the device (as in the OpenWRT Table of Hardware) |
cpu | string | CPU specification |
The "operating_system" object of DeviceConfiguration MAY define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
name | string | name of the operating system or firmware |
kernel | string | kernel version |
version | string | version name or version number of the operating system |
revision | string | revision from which the firmware binary was built (eg: git hash, svn revision) |
description | string | free-form textual description |
Each object contained in the "interfaces" array of DeviceConfiguration MUST define the following REQUIRED members:¶
key name | JSON type | description |
---|---|---|
name | string | name of the interface, MUST NOT be longer than 15 characters, MUST accept all characters except whitespace |
type | string | RECOMMENDED possible values for this field are: "ethernet", "wireless", "bridge", "virtual", "loopback" or "other". Additional values MAY be allowed if needed. |
Each object contained in the "interfaces" array of DeviceConfiguration MAY define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
mac | string | mac address |
mtu | integer | value of the Maximum Transmission Unit setting, defaults to 1500 |
txqueuelen | integer | value of the TX queue length setting |
autostart | boolean | indicates whether the interface should be automatically started after reboot, defaults to true |
disabled | boolean | indicates whether the interface is disabled, defaults to false |
bridge_members | array | valid only if "type" is "bridge"; array of interface names (strings) representing the bridged interfaces |
addresses | array | a array of Address Objects (Section 5.4.1) |
wireless | object | wireless settings, valid only if "type" is "wireless"; see Wireless Object (Section 5.4.2). |
Each object contained in the "addresses" member of an Interface Object (Section 5.4) MUST define the following REQUIRED members:¶
key name | JSON type | description |
---|---|---|
proto | string | either "dhcp" or "static" |
family | integer | either "ipv4" or "ipv6" |
Each object contained in the "addresses" member of an Interface Object (Section 5.4) MAY define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
address | string | ipv4 or ipv6 address, MUST be present if type is "static" |
mask | integer | integer representing the network mask, number commonly used in CIDR notation after the slash (/); MUST be present if type is "static" |
gateway | string | address of the gateway |
The object contained in the "wireless" member of an Interface Object (Section 5.4) which has type "wireless" MUST define the following REQUIRED members:¶
key name | JSON type | description |
---|---|---|
radio | string | MUST refer to the name of one of the radios defined in Radio Objects (Section 5.5) |
mode | string | wireless mode, allowed values are: access_point, station, adhoc, wds, monitor, 802.11s |
ssid | string | ESSID of the network, MUST NOT be longer than 32 characters |
The object contained in the "wireless" member of an Interface Object (Section 5.4) which has type "wireless" MAY define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
bssid | string | BSSID, usually used in "adhoc" or "wds" mode |
hidden | boolean | whether the SSID is hidden from the user, if omitted MUST default to false |
ack_distance | integer | distance between the access point and the furthest client in meters, MUST NOT be less than 1 |
rts_threshold | integer | specifies the frame size at which the transmitter must use the RTS/CTS protocol, MUST be between 0 and 2346 |
frag_threshold | integer | indicates the maximum frame size, MUST be between 0 and 2346 |
encryption | object | encryption settings, if omitted MUST default to disabled encryption, see Encryption Object (Section 5.4.2.1) |
The object contained in the "encryption" member of a Wireless Object (Section 5.4.2) MUST define the following REQUIRED members:¶
key name | JSON type | description |
---|---|---|
protocol | string | encryption protocol; the RECOMMENDED allowed values are: wep_open, wep_shared, wpa_personal, wpa2_personal, wpa_personal_mixed, wpa_enterprise, wpa2_enterprise, wpa_enterprise_mixed, wps |
key | string | encryption key |
The object contained in the "encryption" member of a Wireless Object (Section 5.4.2) MAY define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
cipher | string | string representing security ciphers; the RECOMMENDED allowed values are: auto, ccmp, tkip and tkip+ccmp |
disabled | boolean | whether to disable encryption, SHOULD default to false |
Each object contained in the "radios" array of DeviceConfiguration MUST define the following REQUIRED members:¶
key name | JSON type | description |
---|---|---|
name | string | arbitrary name of the radio device |
protocol | string | wireless protocol used, the RECOMMENDED allowed values are: 802.11ac, 802.11n, 802.11b, 802.11g, 802.11a |
channel | integer | channel number |
channel_width | integer | channel width in Hertz |
Each object contained in the "radios" array of DeviceConfiguration MAY define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
phy | string | name of the physical device to which the radio object is related to, optional because usually autodetected |
country | string | two digit country code in ISO 3166-1 alpha-2 format, case insensitive |
tx_power | integer | transmission power in dBm |
disabled | boolean | whether the radio should be disabled or not, defaults to false |
Each object contained in the "routes" array of DeviceConfiguration MUST define the following REQUIRED members:¶
key name | JSON type | description |
---|---|---|
destination | string | destination address of the static route |
next | string | next hop address for the static route |
Definition: information that indicates the behaviour of a device that changes over time.¶
Goals: ouput, collect, parse and visualize monitoring data of a network device.¶
Example: A.4. DeviceMonitoring Example (Appendix A.4).¶
JSON Schema: B.4. DeviceMonitoring Schema (Appendix B.4).¶
A DeviceMonitoring object MUST define the following REQUIRED members:¶
key name | JSON type | description |
---|---|---|
type | string | MUST be "DeviceMonitoring" |
A DeviceMonitoring object MAY also define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
general | object | object that contains monitoring data that is related to the whole device, see General Object (Section 6.1) for details |
resources | object | describes how hardware resources are being used by the system, see Resources Object (Section 6.2) for details |
interfaces | array | array of objects that represent monitoring data related to specific network interfaces, see Interface Objects (Section 6.3) for details |
The "general" object of DeviceMonitoring MAY define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
local_time | integer | device local time |
uptime | integer | time since boot, in seconds |
The "resources" object of DeviceMonitoring MAY define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
load | array | array with 3 numeric values representing load average values respectively in the last minute, in the last 5 minutes and in the last 15 minutes |
memory | object | object describing RAM usage, SHOULD contain the following RECOMMENDED members: "total", "free", "buffered", "cache" (unit: bytes) |
swap | object | object describing swap memory usage, SHOULD contain the following RECOMMENDED members: "total", "free" (unit: bytes) |
connections | object | object describing connection state, SHOULD contain two RECOMMENDED objects: "ipv4", "ipv6", each object MUST have two members: "tcp" and "udp", indicating the number of open connections |
processes | object | object describing running processes, SHOULD contain the RECOMMENDED member "running" and MAY contain the following RECOMMENDED members: "sleeping", "blocked", "zombie", "stopped", "paging". |
cpu | object | object describing CPU usage, MAY contain the following OPTIONAL members: "frequency" (MHz), "user", "system, "nice", "idle", "iowait", "irq", "softirq" |
flash | object | object describing flash usage, SHOULD contain the following RECOMMENDED members: "total", "free" (unit: bytes) |
storage | object | object describing storage usage, SHOULD contain the following RECOMMENDED members: "total", "free" (unit: bytes) |
Each object contained in the "interfaces" array of DeviceMonitoring MAY define the following OPTIONAL members:¶
key name | JSON type | description |
---|---|---|
name | string | name of the logical interface |
uptime | integer | interface specific uptime in seconds |
statistics | object | object providing detailed monitoring data related to the interface, it MAY contain the following OPTIONAL members: "collisions", "rx_frame_errors", "tx_compressed", "multicast", rx_length_errors", "tx_dropped", "rx_bytes", "rx_missed_errors", "tx_errors", "rx_compressed", "rx_over_errors", "tx_fifo_errors", "rx_crc_errors", "rx_packets", "tx_heartbeat_errors", "rx_dropped", "tx_aborted_errors", "tx_packets", "rx_errors", "tx_bytes", "tx_window_errors", "rx_fifo_errors", "tx_carrier_errors" |
Definition: collection of NetJSON objects.¶
Goals: allow to list various netjson objects into a coherent group, eg:¶
list graphs of different routing protocols running on the same device;¶
list all the routes of a multi-topology capable routing protocol;¶
list devices of a network.¶
Example: A.5. NetworkCollection Example (Appendix A.5).¶
JSON Schema: B.5. NetworkCollection Schema (Appendix B.5).¶
A NetworkCollection object MUST define the following REQUIRED members:¶
key name | JSON type | description |
---|---|---|
type | string | MUST be "NetworkCollection" |
collection | array | array of NetJSON objects (Section 2) |
NetJSON types and their schemas are JSON values. As such, all security considerations defined in RFC 7159 [RFC7159] apply.¶
NetJSON does not impose to publish, send or collect sensitive information.¶
NetJSON only describes how to represent data, each implementer MAY decide:¶
This work was partially supported financially via the CONFINE EU FP7 [CONFINE] grant.¶
Each of the examples below represents a valid and complete NetJSON object.¶
{ "type": "NetworkRoutes", "protocol": "olsrv2", "version": "0.8.2", "revision": "v0.8.2-6-ge2e3acc", "metric": "ff_dat_metric", "router_id": "192.168.0.101", "routes": [ { "destination": "192.168.0.102", "next": "169.254.1.102", "cost": 4292352, "device": "eth1" } ] }¶
{ "type": "NetworkGraph", "protocol": "olsr", "version": "0.6.6", "revision": "5031a799fcbe17f61d57e387bc3806de", "metric": "etx", "router_id": "172.16.40.24", "topology_id": "topology0", "label": "Optional human readable label", "nodes": [ { "id": "172.16.40.24", "label": "node-A", "local_addresses": [ "10.0.0.1", "10.0.0.2" ], "properties": { "hostname": "node1.my.net" } }, { "id": "172.16.40.60", "label": "node-B", "properties": { "hostname": "node2.my.net" } } ], "links": [ { "source": "172.16.40.24", "target": "172.16.40.60", "cost": 1.000, "cost_text": "1020 bit/s", "properties": { "lq": 1.000, "nlq": 0.497 } } ] }¶
{ "type": "DeviceConfiguration", "general": { "hostname": "DeviceNameExample", "timezone": "Europe/Amsterdam", "maintainer": "email@example.org", "description": "general info here", "ula_prefix": "fd8e:f40a:6701::/48" }, "hardware": { "model": "Example model", "manufacturer": "Example inc.", "version": 1, "cpu": "Atheros AR2317" }, "operating_system": { "name": "OpenWRT", "description": "OpenWrt Barrier Breaker 14.07", "version": "Barrier Breaker", "revision": "r43321", "kernel": "3.10.49" }, "radios": [ { "channel_width": 80, "name": "radio0", "protocol": "802.11ac", "country": "US", "disabled": false, "phy": "phy0", "tx_power": 10, "channel": 1 } ], "interfaces": [ { "mtu": 1500, "name": "wlan0", "addresses": [ { "mask": 24, "family": "ipv4", "proto": "static", "address": "192.168.1.1" }, { "mask": 64, "family": "ipv6", "proto": "static", "address": "fe80::216:44ff:fe60:32d2" } ], "txqueuelen": 1000, "autostart": true, "type": "wireless", "wireless": { "mode": "access_point", "ssid": "ap-ssid-example", "radio": "radio0" }, "mac": "de:9f:db:30:c9:c5" }, { "mtu": 1500, "name": "adhoc0", "addresses": [ { "mask": 24, "family": "ipv4", "proto": "static", "address": "10.0.1.1" } ], "txqueuelen": 1000, "autostart": true, "type": "wireless", "wireless": { "bssid": "02:CA:FF:EE:BA:BE", "mode": "adhoc", "ssid": "adhoc-ssid-example", "radio": "radio0" }, "mac": "02:CA:FF:EE:BA:BE" }, { "mtu": 1500, "name": "eth0", "addresses": [ { "gateway": "176.9.211.209", "mask": 28, "family": "ipv4", "proto": "static", "address": "176.9.211.214" }, { "mask": 64, "family": "ipv6", "proto": "static", "address": "2a01:4f8:150:8ffc::214" }, { "mask": 64, "family": "ipv6", "proto": "static", "address": "fe80::5054:ff:fe56:46d0" } ], "txqueuelen": 1000, "autostart": true, "type": "ethernet", "mac": "52:54:00:56:46:d0" }, { "mtu": 1500, "name": "eth1", "addresses": [ { "family": "ipv4", "proto": "dhcp" }, { "family": "ipv6", "proto": "dhcp" } ], "txqueuelen": 1000, "autostart": true, "type": "ethernet", "mac": "52:54:00:56:46:c0" }, { "mtu": 1500, "name": "wlan1", "addresses": [ { "family": "ipv4", "proto": "dhcp" }, { "family": "ipv6", "proto": "dhcp" } ], "txqueuelen": 1000, "autostart": true, "type": "wireless", "wireless": { "encryption": { "cipher": "tkip+ccmp", "key": "passphrase012345", "protocol": "wpa_personal_mixed" }, "mode": "access_point", "ssid": "private-network-example", "radio": "radio0" }, "mac": "de:9f:db:30:c9:c4" }, { "mtu": 1500, "name": "vpn", "addresses": [ { "mask": 64, "family": "ipv6", "proto": "static", "address": "fe80::8029:23ff:fe7d:c214" } ], "txqueuelen": 100, "autostart": true, "type": "virtual", "mac": "82:29:23:7d:c2:14" }, { "mtu": 1500, "name": "vpn.40", "txqueuelen": 100, "autostart": true, "type": "virtual", "mac": "82:29:23:7d:c2:14" }, { "mtu": 1500, "name": "brwifi", "bridge_members": [ "wlan0", "vpn.40" ], "addresses": [ { "mask": 64, "family": "ipv6", "proto": "static", "address": "fe80::8029:23ff:fe7d:c214" } ], "txqueuelen": 0, "autostart": true, "type": "bridge", "mac": "82:29:23:7d:c2:14" } ], "dns_search": [ "domain.com" ], "dns_servers": [ "10.254.0.1", "10.254.0.2" ], "routes": [ { "device": "eth0", "next": "10.0.2.1", "destination": "10.0.3.1", "cost": 1 } ] }¶
{ "type": "DeviceMonitoring", "general": { "local_time": 1414305354, "uptime": 3501937 }, "resources": { "load": [ 0.08, 0.04, 0.05 ], "memory": { "total": 67108864, "free": 3156, "buffered": 2072, "cache": 6884 }, "swap": { "total": 0, "free": 0 }, "connections": { "ipv4": { "tcp": 4, "udp": 18 }, "ipv6": { "tcp": 2, "udp": 1 } }, "processes": { "running": 2, "sleeping": 36, "blocked": 0, "zombie": 0, "stopped": 0, "paging": 0 }, "cpu": { "frequency": 400000000, "user": 13, "system": 0, "nice": 4, "idle": 83, "iowait": 0, "irq": 0, "softirq": 0 }, "flash": { "total": 8388608, "free": 1388608 }, "storage": { "total": null, "free": null } }, "interfaces": [ { "name": "lo", "uptime": 1404305354, "statistics": { "collisions": 0, "rx_frame_errors": 0, "tx_compressed": 0, "multicast": 0, "rx_length_errors": 0, "tx_dropped": 0, "rx_bytes": 9287737, "rx_missed_errors": 0, "tx_errors": 0, "rx_compressed": 0, "rx_over_errors": 0, "tx_fifo_errors": 0, "rx_crc_errors": 0, "rx_packets": 57624, "tx_heartbeat_errors": 0, "rx_dropped": 0, "tx_aborted_errors": 0, "tx_packets": 57624, "rx_errors": 0, "tx_bytes": 9287737, "tx_window_errors": 0, "rx_fifo_errors": 0, "tx_carrier_errors": 0 } }, { "name": "wlan0", "uptime": 1304305354, "statistics": { "collisions": 0, "rx_frame_errors": 0, "tx_compressed": 0, "multicast": 0, "rx_length_errors": 0, "tx_dropped": 0, "rx_bytes": 2434, "rx_missed_errors": 0, "tx_errors": 0, "rx_compressed": 0, "rx_over_errors": 0, "tx_fifo_errors": 0, "rx_crc_errors": 0, "rx_packets": 5, "tx_heartbeat_errors": 0, "rx_dropped": 0, "tx_aborted_errors": 0, "tx_packets": 2169666, "rx_errors": 0, "tx_bytes": 583692816, "tx_window_errors": 0, "rx_fifo_errors": 0, "tx_carrier_errors": 0 } }, { "name": "eth0", "uptime": 1294305354, "statistics": { "collisions": 0, "rx_frame_errors": 0, "tx_compressed": 0, "multicast": 0, "rx_length_errors": 0, "tx_dropped": 0, "rx_bytes": 3542783708, "rx_missed_errors": 0, "tx_errors": 0, "rx_compressed": 0, "rx_over_errors": 0, "tx_fifo_errors": 0, "rx_crc_errors": 0, "rx_packets": 35118502, "tx_heartbeat_errors": 0, "rx_dropped": 14, "tx_aborted_errors": 0, "tx_packets": 11761973, "rx_errors": 0, "tx_bytes": 2952333765, "tx_window_errors": 0, "rx_fifo_errors": 0, "tx_carrier_errors": 0 } } ] }¶
{ "type": "NetworkCollection", "collection": [ { "type": "NetworkGraph", "protocol": "olsr", "version": "0.6.6", "revision": "5031a799fcbe17f61d57e387bc3806de", "metric": "etx", "router_id": "172.16.40.24", "nodes": [ { "id": "172.16.40.24" }, { "id": "172.16.40.60" } ], "links": [ { "source": "172.16.40.24", "target": "172.16.40.60", "cost": 1.000, "properties": { "lq": 1.000, "nlq": 0.497 } } ] }, { "type": "NetworkGraph", "protocol": "olsrv2", "version": "0.8.0", "revision": "v0.8.0-0-g31b63ec-dirty", "router_id": "192.168.0.101", "metric": "ff_dat_metric", "nodes": [ { "id": "192.168.0.101" }, { "id": "192.168.0.102" }, { "id": "192.168.0.103" }, { "id": "192.168.0.104" } ], "links": [ { "source": "192.168.0.101", "target": "192.168.0.102", "cost": 2105088, "cost_text": "1020 bit/s", "properties": { "in": 2105088, "in_txt": "1020 bit/s" } }, { "source": "192.168.0.102", "target": "192.168.0.101", "cost": 2105088, "cost_text": "1020 bit/s", "properties": { "in": 2105088, "in_txt": "1020 bit/s" } }, { "source": "192.168.0.102", "target": "192.168.0.103", "cost": 2105088, "cost_text": "1020 bit/s", "properties": { "in": 2105088, "in_txt": "1020 bit/s" } }, { "source": "192.168.0.103", "target": "192.168.0.102", "cost": 2105088, "cost_text": "1020 bit/s", "properties": { "in": 2105088, "in_txt": "1020 bit/s" } }, { "source": "192.168.0.103", "target": "192.168.0.104", "cost": 2105088, "cost_text": "1020 bit/s", "properties": { "in": 2105088, "in_txt": "1020 bit/s" } }, { "source": "192.168.0.104", "target": "192.168.0.103", "cost": 2105088, "cost_text": "1020 bit/s", "properties": { "in": 2105088, "in_txt": "1020 bit/s" } } ] } ] }¶
Below are listed the JSON Schemas of the each NetJSON Type.¶
{ "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "additionalProperties": true, "required": [ "type", "protocol", "version", "metric", "routes" ], "properties": { "type": { "type": "string", "enum": ["NetworkRoutes"] }, "protocol": { "type": "string" }, "version": { "type": "string" }, "metric": { "type": "string" }, "revision": { "type": "string" }, "router_id": { "type": "string" }, "topology_id": { "type": "string" }, "routes": { "type": "array", "title": "Routes", "uniqueItems": true, "additionalItems": true, "items": { "type": "object", "title": "Route", "additionalProperties": true, "required": [ "destination", "next", "device", "cost" ], "properties": { "destination": { "type": "string" }, "next": { "type": "string" }, "device": { "type": "string" }, "cost": { "type": "number" }, "source": { "type": "string" }, "cost_txt": { "type": "string" } } } } } }¶
{ "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "additionalProperties": true, "required": [ "type", "protocol", "version", "metric", "nodes", "links" ], "properties": { "type": { "type": "string", "enum": ["NetworkGraph"] }, "protocol": { "type": "string" }, "version": { "type": "string" }, "revision": { "type": "string" }, "metric": { "type": "string" }, "router_id": { "type": "string" }, "topology_id": { "type": "string" }, "label": { "type": "string" }, "nodes": { "type": "array", "title": "Nodes", "uniqueItems": true, "additionalItems": true, "items": [ { "title": "Node", "type": "object", "additionalProperties": true, "required": [ "id" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "local_addresses": { "type": "array", "additionalItems": true, "uniqueItems": true, "items": { "type": "string" } }, "properties": { "type": "object", "additionalProperties": true } } } ] }, "links": { "type": "array", "title": "Links", "uniqueItems": true, "additionalItems": true, "items": { "type": "object", "title": "Link", "additionalProperties": true, "required": [ "source", "target", "cost" ], "properties": { "source": { "type": "string" }, "target": { "type": "string" }, "cost": { "type": "number", "default": 1 }, "cost_text": { "type": "string" }, "properties": { "type": "object", "additionalProperties": true } } } } } }¶
{ "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "additionalProperties": true, "definitions": { "interface_settings": { "type": "object", "additionalProperties": true, "required": [ "name", "type" ], "properties": { "name": { "type": "string", "maxLength": 15, "pattern": "^[^\\s]*$" }, "mac": { "type": "string" }, "mtu": { "type": "integer", "default": 1500 }, "txqueuelen": { "type": "integer" }, "autostart": { "type": "boolean", "default": true }, "disabled": { "type": "boolean", "default": false }, "addresses": { "type": "array", "title": "Addresses", "uniqueItems": true, "additionalItems": true, "items": { "type": "object", "title": "Address", "additionalProperties": true, "required": [ "proto", "family" ], "properties": { "proto": { "type": "string", "enum": [ "static", "dhcp" ] }, "family": { "type": "string", "enum": [ "ipv4", "ipv6" ] }, "address": { "type": "string" }, "mask": { "type": "integer" }, "gateway": { "type": "string" } } } } } }, "network_interface": { "title": "Network interface", "allOf": [ { "properties": { "type": { "type": "string", "enum": [ "ethernet", "virtual", "loopback", "other" ] } } }, {"$ref": "#/definitions/interface_settings"} ] }, "wireless_interface": { "title": "Wireless interface", "allOf": [ { "properties": { "type": { "type": "string", "enum": ["wireless"], "default": "wireless" } } }, {"$ref": "#/definitions/interface_settings"}, { "properties": { "wireless": { "type": "object", "title": "Wireless Interface", "additionalProperties": true, "required": [ "radio", "mode", "ssid" ], "properties": { "radio": { "type": "string" }, "mode": { "type": "string", "enum": [ "access_point", "station", "adhoc", "wds", "monitor", "802.11s" ] }, "ssid": { "type": "string", "maxLength": 32 }, "bssid": { "type": "string" }, "hidden": { "type": "boolean", "default": false }, "ack_distance": { "type": "integer", "minimum": 1 }, "rts_threshold": { "type": "integer", "minimum": 0, "maximum": 2346 }, "frag_threshold": { "type": "integer", "minimum": 0, "maximum": 2346 }, "encryption": { "type": "object", "title": "Encryption", "required": [ "protocol", "key" ], "properties": { "protocol": { "type": "string", "enum": [ "wep_open", "wep_shared", "wpa_personal", "wpa2_personal", "wpa_personal_mixed", "wpa_enterprise", "wpa2_enterprise", "wpa_enterprise_mixed", "wps" ] }, "key": { "type": "string" }, "cipher": { "type": "string" }, "disabled": { "type": "boolean", "default": false } } } } } } } ] }, "bridge_interface": { "title": "Bridge interface", "required": [ "bridge_members" ], "allOf": [ { "properties": { "type": { "type": "string", "enum": ["bridge"] } } }, {"$ref": "#/definitions/interface_settings"}, { "properties": { "bridge_members": { "type": "array", "title": "Bridge Members", "uniqueItems": true, "items": { "$ref": "#/definitions/interface_settings/properties/name" } } } } ] } }, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": ["DeviceConfiguration"] }, "general": { "type": "object", "title": "General", "additionalProperties": true, "properties": { "hostname": { "type": "string" }, "timezone": { "type": "string" }, "maintainer": { "type": "string" }, "description": { "type": "string" }, "ula_prefix": { "type": "string" } } }, "hardware": { "type": "object", "title": "Hardware", "additionalProperties": true, "properties": { "manufacturer": { "type": "string" }, "model": { "type": "string" }, "version": { "type": "integer" }, "cpu": { "type": "string" } } }, "operating_system": { "type": "object", "title": "Operating System", "additionalProperties": true, "properties": { "name": { "type": "string" }, "kernel": { "type": "string" }, "version": { "type": "string" }, "revision": { "type": "string" }, "description": { "type": "string" } } }, "radios": { "type": "array", "title": "Radios", "uniqueItems": true, "additionalItems": true, "items": { "type": "object", "title": "Radio", "additionalProperties": true, "required": [ "name", "protocol", "channel", "channel_width" ], "properties": { "name": { "type": "string" }, "protocol": { "type": "string" }, "phy": { "type": "string" }, "channel": { "type": "integer" }, "channel_width": { "type": "integer" }, "tx_power": { "type": "integer" }, "country": { "type": "string", "minLength": 2, "maxLength": 2 }, "disabled": { "type": "boolean", "default": false } } } }, "interfaces": { "type": "array", "title": "Interfaces", "uniqueItems": true, "additionalItems": true, "items": { "oneOf": [ {"$ref": "#/definitions/network_interface"}, {"$ref": "#/definitions/wireless_interface"}, {"$ref": "#/definitions/bridge_interface"} ] } }, "routes": { "type": "array", "title": "Routes", "uniqueItems": true, "additionalItems": true, "items": { "type": "object", "title": "Route", "additionalProperties": true, "required": [ "device", "destination", "next" ], "properties": { "device": { "type": "string" }, "next": { "type": "string" }, "destination": { "type": "string" } } } }, "dns_servers": { "title": "DNS Servers", "type": "array", "uniqueItems": true, "additionalItems": true, "items": { "type": "string" } }, "dns_search": { "title": "DNS Search", "type": "array", "uniqueItems": true, "additionalItems": true, "items": { "type": "string" } } } }¶
{ "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "additionalProperties": true, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": ["DeviceMonitoring"] }, "general": { "type": "object", "title": "General", "additionalProperties": true, "properties": { "local_time": { "type": "integer" }, "uptime": { "type": "integer" } } }, "resources": { "type": "object", "title": "Resources", "additionalProperties": true, "properties": { "load": { "type": "array", "items": { "type": "number", "minItems": 3, "maxItems": 3 } }, "memory": { "id": "memory", "type": "object", "properties": { "total": { "type": "integer" }, "free": { "type": "integer" }, "buffered": { "type": "integer" }, "cache": { "type": "integer" } } }, "swap": { "type": "object", "properties": { "total": { "type": "integer" }, "free": { "type": "integer" } } }, "connections": { "type": "object", "properties": { "ipv4": { "type": "object", "properties": { "tcp": { "type": "integer" }, "udp": { "type": "integer" } } }, "ipv6": { "type": "object", "properties": { "tcp": { "type": "integer" }, "udp": { "type": "integer" } } } } }, "processes": { "type": "object", "properties": { "running": { "type": "integer" }, "sleeping": { "type": "integer" }, "blocked": { "type": "integer" }, "zombie": { "type": "integer" }, "stopped": { "type": "integer" }, "paging": { "type": "integer" } } }, "cpu": { "type": "object", "properties": { "frequency": { "type": "integer" }, "user": { "type": "integer" }, "system": { "type": "integer" }, "nice": { "type": "integer" }, "idle": { "type": "integer" }, "iowait": { "type": "integer" }, "irq": { "type": "integer" }, "softirq": { "type": "integer" } } }, "flash": { "type": "object", "properties": { "total": { "type": "integer" }, "free": { "type": "integer" } } }, "storage": { "type": "object", "properties": { "total": { "type": "integer" }, "free": { "type": "integer" } } } } }, "interfaces": { "type": "array", "title": "Interfaces", "uniqueItems": true, "additionalItems": true, "items": { "type": "object", "title": "Interface", "additionalProperties": true, "required": [ "name" ], "properties": { "name": { "type": "string" }, "uptime": { "type": "integer" }, "statistics": { "type": "object", "properties": { "collisions": { "type": "integer" }, "rx_frame_errors": { "type": "integer" }, "tx_compressed": { "type": "integer" }, "multicast": { "type": "integer" }, "rx_length_errors": { "type": "integer" }, "tx_dropped": { "type": "integer" }, "rx_bytes": { "type": "integer" }, "rx_missed_errors": { "type": "integer" }, "tx_errors": { "type": "integer" }, "rx_compressed": { "type": "integer" }, "rx_over_errors": { "type": "integer" }, "tx_fifo_errors": { "type": "integer" }, "rx_crc_errors": { "type": "integer" }, "rx_packets": { "type": "integer" }, "tx_heartbeat_errors": { "type": "integer" }, "rx_dropped": { "type": "integer" }, "tx_aborted_errors": { "type": "integer" }, "tx_packets": { "type": "integer" }, "rx_errors": { "type": "integer" }, "tx_bytes": { "type": "integer" }, "tx_window_errors": { "type": "integer" }, "rx_fifo_errors": { "type": "integer" }, "tx_carrier_errors": { "type": "integer" } } } } } } } }¶
{ "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "additionalProperties": true, "required": [ "type", "collection" ], "properties": { "type": { "type": "string", "enum": ["NetworkCollection"] }, "collection": { "type": "array", "title": "NetJSON Objects", "uniqueItems": true, "additionalItems": true, "items": { "type": "object", "title": "NetJSON Object", "additionalProperties": true, "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "NetworkRoutes", "NetworkGraph", "DeviceConfiguration", "DeviceMonitoring", "NetworkCollection" ] } } } } } }¶
The NetJSON format is the product of discussion on the interop-dev mailing list: https://lists.funkfeuer.at/mailman/listinfo/interop-dev.¶
Comments are solicited and should be addressed to the interop-dev mailing list at interop-dev@lists.funkfeuer.at or to the NetJSON issue tracker at https://github.com/netjson/netjson/issues.¶
Some contributors deserve special credit for the intense technical discussions, early reviews and constructive contribution: Henning Rogge (Fraunhofer FKIE).¶