Network Working Group F. Capoano
Internet-Draft Ninux.org
Intended status: Informational L. Kaplan
Expires: January 2, 2016 CERT.at
July 2015

NetJSON: data interchange format for networks
draft-capoano-kaplan-netjson-00

Abstract

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.

Status of This Memo

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 January 2, 2016.

Copyright Notice

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 Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.


Table of Contents

1. Introduction

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:

These concepts have been streamlined to encourage interoperability between network centric web applications using JSON.

1.1. Motivatons

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.

1.2. Requirements Language

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].

1.3. Conventions Used in This Document

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.

1.4. Definitions

2. NetJSON Object

NetJSON always consists of a single object, referred to as the "NetJSON object" below.

2.1. NetJSON types

NetJSON defines the following types:

3. NetworkRoutes

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 [NetworkRoutes-example].

JSON Schema: B.1. NetworkRoutes Schema [NetworkRoutes-schema].

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 [route-objects]

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)

3.1. Route Objects

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)

4. NetworkGraph

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 [NetworkGraph-example].

JSON Schema: B.2. NetworkGraph Schema [NetworkGraph-schema].

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 [node-objects]
links array array of Link Objects [link-objects]

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

4.1. Node Objects

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 aribtrary members SHOULD be visualized by user interface software

4.2. Link Objects

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 aribtrary members SHOULD be visualized by user interface software

5. DeviceConfiguration

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 [DeviceConfiguration-example].

JSON Schema: B.3. DeviceConfiguration Schema [DeviceConfiguration-schema].

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 [general1] for details
hardware object hardware information related to the network device, see Hardware Object [general1] for details
operating_system object operating system information, see Operating System Object [operating_system1] for details
interfaces array array of objects that represent how network interfaces are configured on the device, see Interface Objects [interfaces1] for details
radios array array of objects that represent the configuration of radios available on the system, see Radio Objects [radios1] for details
routes array array of objects that represent static routes configured on the device, see Static Route Objects [routes1] 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

5.1. General Object

The "general" object of DeviceConfiguration MAY define the following OPTIONAL members:

key name JSON type description
hostname string hostname of the network device
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

5.2. Hardware Object

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

5.3. Operating Sytem Object

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

5.4. Interface Objects

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 [addresses1]
wireless object wireless settings, valid only if "type" is "wireless"; see Wireless Object [wireless1].

5.4.1. Address Objects

Each object contained in the "addresses" member of an Interface Object [interfaces1] 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 [interfaces1] 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

5.4.2. Wireless Object

The object contained in the "wireless" member of an Interface Object [interfaces1] 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 [radios1]
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 [interfaces1] 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 [encryption1]

5.4.2.1. Encryption Object

The object contained in the "encryption" member of a Wireless Object [wireless1] 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 [wireless1] MAY define the following OPTIONAL members:

key name JSON type description
ciphers array array of strings representing security ciphers, eg: CCMP, TKIP
disabled boolean whether to disable encryption, defaults to false

5.5. Radio Objects

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
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

5.6. Static Route Objects

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

6. DeviceMonitoring

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 [DeviceMonitoring-example].

JSON Schema: B.4. DeviceMonitoring Schema [DeviceMonitoring-schema].

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 [general2] for details
resources object describes how hardware resources are being used by the system, see Resources Object [resources2] for details
interfaces array array of objects that represent monitoring data related to specific network interfaces, see Interface Objects [interfaces2] for details

6.1. General Object

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

6.2. Resources Object

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)

6.3. Interface Objects

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"

7. NetworkCollection

Definition: collection of NetJSON objects.

Goals: allow to list various netjson objects into a coherent group, eg:

Example: A.5. NetworkCollection Example [NetworkCollection-example].

JSON Schema: B.5. NetworkCollection Schema [NetworkCollection-schema].

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 [netjson-object]

8. Security Considerations

NetJSON types and their schemas are JSON values. As such, all security considerations defined in RFC 7159 [RFC7159] apply.

9. Privacy Considerations

NetJSON does not impose to publish, send or collect sensitive information.

NetJSON only describes how to represent data, each implementer MAY decide:

10. Acknowledgements

This work was partially supported financially via the CONFINE EU FP7 [CONFINE] grant.

11. References

11.1. Normative References

[JSON-Schema] Galiegue, F., "JSON Schema: core definitions and terminology", 2013.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", 2014.

11.2. Informative References

[Babel] Chroboczek, J., "Babel - a loop-avoiding distance-vector routing protocol", 2009.
[Batman-adv] The B.A.T.M.A.N. team, "Batman-adv routing protocol", 2009.
[BMX] Neumann, A., "BMX6 Mesh networking protocol", 2007.
[CNML] Klosch, A. and M. Behling, "The Community Networking Markup Language (CNML)", 2007.
[CONFINE] The CONFINE project team, "The CONFINE EU project", 2011.
[GeoJSON] Butler, H., "The GeoJSON Format", 2015.
[Nagios] Galstad, E., "Nagios network monitoring", 1999.
[OLSRd] Rogge, H., Tonnesen, A., Kaplan, L., Petrovitsch, B., Lopatic, T. and F. Huberts, "The Optimised Link State Routing Protocol (OLSR), olsrd open source implementation", 2004.
[OpenWRT] The OpenWRT team, "OpenWRT", 2004.
[RFC3626] Clausen, T. and P. Jacquet, "Optimized Link State Routing Protocol (OLSR)", 2003.
[RFC6126] Chroboczek, J., "The Babel Routing Protocol", 2009.
[RFC7181] Clausen, T., Dearlove, C., Jacquet, P. and U. Herberg, "The Optimized Link State Routing Protocol Version 2", 2003.

Appendix A. Examples

Each of the examples below represents a valid and complete NetJSON object.

A.1. NetworkRoutes Example


{
    "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",
        }
    ]
}

                    

A.2. NetworkGraph Example


{
    "type": "NetworkGraph",
    "protocol": "olsr",
    "version": "0.6.6",
    "revision": "5031a799fcbe17f61d57e387bc3806de",
    "metric": "etx",
    "label": "Test Network",
    "router_id": "172.16.40.24",
    "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
            }
        }
    ]
}

                    

A.3. DeviceConfiguration Example


{
    "type": "DeviceConfiguration",
    "general": {
        "hostname": "DeviceNameExample",
        "maintainer": "email@example.org",
        "description": "general info here",
        "ula_prefix": "fd8e:f40a:6701::/48"
    },
    "hardware": {
        "manufacturer": "Example inc.",
        "model": "Example model",
        "revision": 1,
        "cpu": "Atheros AR2317"
    },
    "operating_system": {
        "name": "OpenWRT",
        "kernel": "3.10.49",
        "version": "Barrier Breaker",
        "revision": "r43321",
        "description": "OpenWrt Barrier Breaker 14.07"
    },
    "resources": {
        "memory": {
            "total": 67108864
        },
        "swap": {
            "total": 0
        },
        "cpu": {
            "frequency": 400000000
        },
        "flash": {
            "total": 8388608
        },
        "storage": {
            "total": null
        }
    },
    "radios": [
        {
            "name": "radio0",
            "phy": "phy0",
            "channel": 149,
            "channel_width": 20,
            "tx_power": 18,
            "country": "en",
            "disabled": false
        }
    ],
    "interfaces": [
        {
            "type": "wireless",
            "name": "wlan0",
            "mac": "de:9f:db:30:c9:c5",
            "mtu": 1500,
            "txqueuelen": 1000,
            "autostart": true,
            "wireless": {
                "radio": "radio0",
                "mode": "access_point",
                "ssid": "ap-ssid-example"
            },
            "addresses": [
                {
                    "address": "192.168.1.1",
                    "mask": 24,
                    "family": "ipv4",
                    "proto": "static"
                },
                {
                    "address": "fe80::216:44ff:fe60:32d2",
                    "mask": 64,
                    "family": "ipv6",
                    "proto": "static"
                }
            ]
        },
        {
            "type": "ethernet",
            "name": "eth0",
            "mac": "52:54:00:56:46:d0",
            "mtu": 1500,
            "txqueuelen": 1000,
            "autostart": true,
            "addresses": [
                {
                    "address": "176.9.211.214",
                    "mask": 28,
                    "family": "ipv4",
                    "proto": "static"
                },
                {
                    "address": "2a01:4f8:150:8ffc::214",
                    "mask": 64,
                    "family": "ipv6",
                    "proto": "static"
                },
                {
                    "address": "fe80::5054:ff:fe56:46d0",
                    "mask": 64,
                    "family": "ipv6",
                    "proto": "static"
                }
            ]
        }
    ],
    "routes": [
        {
            "destination": "10.0.3.1",
            "next": "10.0.2.1"
        }
    ],
    "dns_servers": [
        "10.254.0.1",
        "10.254.0.2"
    ],
    "dns_search": [
        "domain.com"
    ]
}

                    

A.4. DeviceMonitoring Example


{
    "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
            }
        }
    ]
}

                    

A.5. NetworkCollection Example


{
    "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" }
            ],
            "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"
                    }
                }
            ]
        }
    ]
}

                    

Appendix B. Schemas

Below are listed the JSON Schemas of the each NetJSON Type.

B.1. NetworkRoutes Schema


{
    "$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"
                    }
                }
            }
        }
    }
}

                    

B.2. NetworkGraph Schema


{
    "$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
                    }
                }
            }
        }
    }
}

                    

B.3. DeviceConfiguration Schema


{
    "$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"
                                        },
                                        "ciphers": {
                                            "type": "array",
                                            "items": {
                                                "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",
                            "items": {
                                "uniqueItems": true,
                                "$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"
                },
                "maintainer": {
                    "type": "string"
                },
                "description": {
                    "type": "string"
                },
                "ula_prefix": {
                    "type": "string"
                }
            }
        },
        "hardware": {
            "type": "object",
            "title": "Hardware",
            "additionalProperties": true,
            "properties": {
                "manufacturer": {
                    "type": "string"
                },
                "model": {
                    "type": "string"
                },
                "revision": {
                    "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",
                    "channel",
                    "channel_width"
                ],
                "properties": {
                    "name": {
                        "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"
            }
        }
    }
}

                    

B.4. DeviceMonitoring Schema


{
    "$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": "integer",
                        "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,
            "required": [
                "name"
            ],
            "items": {
                "type": "object",
                "title": "Interface",
                "additionalProperties": true,
                "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"
                            }
                        }
                    }
                }
            }
        }
    }
}

                    

B.5. NetworkCollection Schema


{
    "$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"
                        ]
                    }
                }
            }
        }
    }
}

                    

Appendix C. Contributions

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/interop-dev/netjson/issues.

Some contributors deserve special credit for the intense technical discussions, early reviews and constructive contribution: Henning Rogge (Fraunhofer FKIE).

Authors' Addresses

Federico Capoano Ninux.org Via Silvio Pellico 29 Pomezia, Rome 00071 Italy Phone: +39 366 4253802 EMail: nemesis@ninux.org URI: http://www.ninux.org/
L. Aaron Kaplan CERT.at Karlsplatz 1/2/9 Vienna, A-1010 Austria Phone: +43 1 5056416 78 EMail: kaplan@cert.at URI: http://www.cert.at/