plotnetcfg-json.5

.TH plotnetcfg-json 5 "10 June 2015"
.SH NAME
plotnetcfg \- json output format
.SH DESCRIPTION

.SS Root object fields

.TP
format
.I (number)
Currently 2. Will be increased if incompatible changes are introduced.
A tool parsing the json output should refuse any format it's not aware of.
Note that adding of new fields is not considered to be an incompatible
change.

.TP
version
.I (string)
Plotnetcfg version.

.TP
date
.I (string)
Time and date when the data were gathered, in
.BR ctime (3)
format.

.TP
namespaces
.I (object)
Associative array of name space objects. Key is the namespace id.

.TP
root
.I (object)
The id and key of root namespace.

.SS Name space object fields

.TP
id
.I (string)
An arbitrary identifier, unique among other namespaces.

.TP
name
.I (string)
Name of the name space suitable for user consumption. This in general cannot
be used for machine consumption, e.g. switching to the name space. The root
name space has an empty name.

.TP
interfaces
.I (object)
Associative array of interface objects. Key is the interface id.

.TP
warnings
.I (array)
If present, an array of strings. Contains error messages encountered when
gathering data in the given name space.

.TP
routes
.I (array)
An array of existing routing tables.

.SS Interface object fields

.TP
id
.I (string)
Unique identifier of the interface. This is an arbitrary opaque string and
the consumer should not make any assumption of its contents (apart of not
containing null characters). It should not be displayed to the user, the
sole purpose of this field is linking to other interfaces. The identifier is
globally unique, it is safe to assume that interfaces with the same name in
different name spaces have a different id.

.TP
name
.I (string)
User visible name of the interface. Usually (but not always) the name of the
corresponding Linux interface. This is not unique between name spaces.

.TP
driver
.I (string)
The kernel module (driver) behind the interface. May be empty in some
specific cases.

.TP
info
.I (object)
Contains additional information about the interface. Values are formatted
strings, e.g. tunnel endpoints. The exact content is dependent on the
type of the interface.

.TP
addresses
.I (array)
Array of address objects.

.TP
mac
.I (string)
Link-layer address of the interface.

.TP
mtu
.I (number)
Interface MTU.

.TP
type
.I (string)
.RS
"device": normal interface. Most interfaces are of this type.
.P
"internal": this interface is not backed up by a Linux interface. Can be
often found with Open vSwitch.
.P
Further types are possible with future plotnetcfg versions. Adding them will
not be considered a format change.
.RE

.TP
state
.I (string)
.RS
"down": the interface is administratively disabled.
.P
"up": the interface is up and operating.
.P
"up_no_link": the interface is up but has no link.
.P
"none": state cannot be determined or is not applicable to this kind of
interface.
.P
More states are possible to be added in future plotnetcfg versions. Adding
them will not be considered a format change.
.RE

.TP
warning
.I (bool)
There was a problem gathering data about this interface. Details are in the
name space warnings field. The purpose of this flag is for visual
representation of this interface as not having complete data available.
Not present if there was no error.

.TP
parents
.I (array)
Array of parent interfaces, as connection objects. Not present if there
are no parents.

.TP
children
.I (array)
Array of children interfaces, as connection objects. Not present if there
are no children.

.TP
peer
.I (object)
The peer interface, as a connection object. Not present if there's no peer.

.SS Connection object fields

.TP
info
.I (array)
Array of strings. Contains additional information about the connection
between the two interfaces, formatted. May be an empty array.

.TP
target
.I (string)
Id of the interface that is being linked to.

.SS Address object fields

.TP
family
.I (string)
Currently only "INET" or "INET6". More types will be added in the future
(without considering it a format change).

.TP
address
.I (string)
Address formatted for user consumption. May include net mask. This field
should be generally machine parseable.

.TP
peer
.I (object)
If present, the peer address corresponding to this address. It's of the
address object type but cannot contain futher peer field.

.SS Routing table object fields

.TP
name
.I (string)
The well-known name of the table, if there is such.

.TP
routes
.I (array)
An array of route objects.

.SS Route object fields

.TP
destination
.I (string)
Formatted prefix of the route destination.

.TP
family
.I (string)
A family of all addresses in this route. Currently only "INET" or "INET6".

.TP
gateway
.I (string)
Formatted address of the gateway, if this is a next-hop route.

.TP
iif
.I (string)
Interface id of the input interface, if any.

.TP
metrics
.I (object)
Associative array of integers, containing all integer metrics that kernel
reports, if any. Keys are one of the following: mtu, window, rtt, rttvar,
sshthresh, cwnd, advmss, reordering, hoplimit, initcwnd, features, rto_min,
initrwnd, quickack.

.TP
oif
.I (string)
Interface id of the output interface, if any.

.TP
priority
.I (integer)
Kernel reported priority of this route.

.TP
protocol
.I (string)
An origin of the route. Currently one of redirect, kernel, boot, static, gated,
ra, mrt, zebra, bird, dnrouted, xorp, ntk, dhcp, mrouted or babel, but others
may be added in the future.

.TP
scope
.I (string)
A scope of the route.

.TP
source
.I (string)
A formatted source prefix.

.TP
preferred-source
.I (string)
A formatted preferred source address.

.TP
tos
.I (integer)
The type of service.

.TP
type
.I (string)
Route type, one of the following: unspec, unicast, local, broadcast, anycast,
multicast, blackhole, unreachable, prohibit, throw, nat. Others may be added in
the future, without breaking the format.

.SH SEE ALSO
.BR plotnetcfg (8)

.SH AUTHOR
.B plotnetcfg
was written and is maintained by Jiri Benc <jbenc@redhat.com>.