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

NetJSON: data interchange format for networks

draft-capoano-kaplan-netjson-00

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

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:

the Community Networking Markup Language [CNML] [CNML]

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]

([RFC3626] and [RFC7181] ), [Babel] ([RFC6126] ), [Batman-adv] and [BMX] linux distributions like [OpenWRT] [OpenWRT]

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.

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.

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.

2.1. NetJSON types

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

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

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

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

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

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]

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

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

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:

which optional members to publish (sensitive data can be omitted)

how to publish it (public, basic auth, token auth, ecc.)

how to collect it

which parts should be collected

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

11.1. Normative References

11.2. Informative References

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

{{ ../examples/network-routes.json }}

{{ ../examples/network-graph.json }}

{{ ../examples/device-configuration.json }}

{{ ../examples/device-monitoring.json }}

{{ ../examples/network-collection.json }}

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

{{ ../schema/network-routes.json }}

{{ ../schema/network-graph.json }}

{{ ../schema/device-configuration.json }}

{{ ../schema/device-monitoring.json }}

{{ ../schema/network-collection.json }}

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