libnftables-json(5)

===================

Phil Sutter <phil@nwl.cc>

:doctype: manpage

:compat-mode!:

== NAME

libnftables-json - Supported JSON schema by libnftables

== SYNOPSIS

*{ "nftables": [* 'OBJECTS' *] }*

'OBJECTS' := 'LIST_OBJECTS' | 'CMD_OBJECTS'

'LIST_OBJECTS' := 'LIST_OBJECT' [ *,* 'LIST_OBJECTS' ]

'CMD_OBJECTS' := 'CMD_OBJECT' [ *,* 'CMD_OBJECTS' ]

'CMD_OBJECT' := *{* 'CMD'*:* 'LIST_OBJECT' *}* | 'METAINFO_OBJECT'

'CMD' := *"add"* | *"replace"* | *"create"* | *"insert"* | *"delete"* |

         *"list"* | *"reset"* | *"flush"* | *"rename"*

'LIST_OBJECT' := 'TABLE' | 'CHAIN' | 'RULE' | 'SET' | 'MAP' | 'ELEMENT' |

		 'FLOWTABLE' | 'COUNTER' | 'QUOTA' | 'CT_HELPER' | 'LIMIT' |

		 'METAINFO_OBJECT' | 'CT_TIMEOUT' | 'CT_EXPECTATION'

== DESCRIPTION

libnftables supports JSON formatted input and output. This is implemented as an

alternative frontend to the standard CLI syntax parser, therefore basic

behaviour is identical and, for (almost) any operation available in standard

syntax, there should be an equivalent one in JSON.

JSON input may be provided in a single string as parameter to

*nft_run_cmd_from_buffer()* or in a file identified by the 'filename' parameter

of the *nft_run_cmd_from_filename()* function.

JSON output has to be enabled via the *nft_ctx_output_set_json()* function, turning

library standard output into JSON format. Error output remains unaffected.

== GLOBAL STRUCTURE

In general, any JSON input or output is enclosed in an object with a single

property named 'nftables'. Its value is an array containing commands (for

input) or ruleset elements (for output).

A command is an object with a single property whose name identifies the command.

Its value is a ruleset element - basically identical to output elements, apart

from certain properties which may be interpreted differently or are required

when output generally omits them.

== METAINFO OBJECT

In output, the first object in an *nftables* array is a special one containing

library information. Its content is as follows:

[verse]

*{ "metainfo": {

	"version":* 'STRING'*,

	"release_name":* 'STRING'*,

	"json_schema_version":* 'NUMBER'

*}}*

The values of *version* and *release_name* properties are equal to the package

version and release name as printed by *nft -v*. The value of the

*json_schema_version* property is an integer indicating the schema version.

If supplied in library input, the parser will verify the *json_schema_version* value

to not exceed the internally hardcoded one (to make sure the given schema is

fully understood). In future, a lower number than the internal one may activate

compatibility mode to parse outdated and incompatible JSON input.

== COMMAND OBJECTS

The structure accepts an arbitrary amount of commands which are interpreted in

order of appearance. For instance, the following standard syntax input:

----

flush ruleset

add table inet mytable

add chain inet mytable mychain

add rule inet mytable mychain tcp dport 22 accept

----

translates into JSON as such:

----

{ "nftables": [

	{ "flush": { "ruleset": null }},

	{ "add": { "table": {

			"family": "inet",

			"name": "mytable"

	}}},

	{ "add": { "chain": {

			"family": "inet",

			"table": "mytable",

			"chain": "mychain"

	}}}

	{ "add": { "rule": {

			"family": "inet",

			"table": "mytable",

			"chain": "mychain",

			"expr": [

				{ "match": {

					"left": { "payload": {

							"protocol": "tcp",

							"field": "dport"

					}},

					"right": 22

				}},

				{ "accept": null }

			]

	}}}

]}

----

=== ADD

[verse]

____

*{ "add":* 'ADD_OBJECT' *}*

'ADD_OBJECT' := 'TABLE' | 'CHAIN' | 'RULE' | 'SET' | 'MAP' | 'ELEMENT' |

                'FLOWTABLE' | 'COUNTER' | 'QUOTA' | 'CT_HELPER' | 'LIMIT' |

		'CT_TIMEOUT' | 'CT_EXPECTATION'

____

Add a new ruleset element to the kernel.

=== REPLACE

[verse]

*{ "replace":* 'RULE' *}*

Replace a rule. In 'RULE', the *handle* property is mandatory and identifies the

rule to be replaced.

=== CREATE

[verse]

*{ "create":* 'ADD_OBJECT' *}*

Identical to *add* command, but returns an error if the object already exists.

=== INSERT

[verse]

*{ "insert":* 'RULE' *}*

This command is identical to *add* for rules, but instead of appending the rule

to the chain by default, it inserts at first position. If a *handle* or *index*

property is given, the rule is inserted before the rule identified by those

properties.

=== DELETE

[verse]

*{ "delete":* 'ADD_OBJECT' *}*

Delete an object from the ruleset. Only the minimal number of properties

required to uniquely identify an object is generally needed in 'ADD_OBJECT'. For

most ruleset elements, this is *family* and *table* plus either *handle* or

*name* (except rules since they don't have a name).

=== LIST

[verse]

____

*{ "list":* 'LIST_OBJECT' *}*

'LIST_OBJECT' := 'TABLE' | 'TABLES' | 'CHAIN' | 'CHAINS' | 'SET' | 'SETS' |

                 'MAP' | 'MAPS | COUNTER' | 'COUNTERS' | 'QUOTA' | 'QUOTAS' |

                 'CT_HELPER' | 'CT_HELPERS' | 'LIMIT' | 'LIMITS' | 'RULESET' |

                 'METER' | 'METERS' | 'FLOWTABLE' | 'FLOWTABLES' |

                 'CT_TIMEOUT' | 'CT_EXPECTATION'

____

List ruleset elements. The plural forms are used to list all objects of that

kind, optionally filtered by *family* and for some, also *table*.

=== RESET

[verse]

____

*{ "reset":* 'RESET_OBJECT' *}*

'RESET_OBJECT' := 'COUNTER' | 'COUNTERS' | 'QUOTA' | 'QUOTAS'

____

Reset state in suitable objects, i.e. zero their internal counter.

=== FLUSH

[verse]

____

*{ "flush":* 'FLUSH_OBJECT' *}*

'FLUSH_OBJECT' := 'TABLE' | 'CHAIN' | 'SET' | 'MAP' | 'METER' | 'RULESET'

____

Empty contents in given object, e.g. remove all chains from given *table* or

remove all elements from given *set*.

=== RENAME

[verse]

*{ "rename":* 'CHAIN' *}*

Rename a chain. The new name is expected in a dedicated property named

*newname*.

== RULESET ELEMENTS

=== TABLE

[verse]

*{ "table": {

	"family":* 'STRING'*,

	"name":* 'STRING'*,

	"handle":* 'NUMBER'

*}}*

This object describes a table.

*family*::

	The table's family, e.g. *"ip"* or *"ip6"*.

*name*::

	The table's name.

*handle*::

	The table's handle. In input, it is used only in *delete* command as

	alternative to *name*.

=== CHAIN

[verse]

*{ "chain": {

	"family":* 'STRING'*,

	"table":* 'STRING'*,

	"name":* 'STRING'*,

	"newname":* 'STRING'*,

	"handle":* 'NUMBER'*,

	"type":* 'STRING'*,

	"hook":* 'STRING'*,

	"prio":* 'NUMBER'*,

	"dev":* 'STRING'*,

	"policy":* 'STRING'

*}}*

This object describes a chain.

*family*::

	The table's family.

*table*::

	The table's name.

*name*::

	The chain's name.

*handle*::

	The chain's handle. In input, it is used only in *delete* command as

	alternative to *name*.

*newname*::

	A new name for the chain, only relevant in the *rename* command.

The following properties are required for base chains:

*type*::

	The chain's type.

*hook*::

	The chain's hook.

*prio*::

	The chain's priority.

*dev*::

	The chain's bound interface (if in the netdev family).

*policy*::

	The chain's policy.

=== RULE

[verse]

____

*{ "rule": {

	"family":* 'STRING'*,

	"table":* 'STRING'*,

	"chain":* 'STRING'*,

	"expr": [* 'STATEMENTS' *],

	"handle":* 'NUMBER'*,

	"index":* 'NUMBER'*,

	"comment":* 'STRING'

*}}*

'STATEMENTS' := 'STATEMENT' [*,* 'STATEMENTS' ]

____

This object describes a rule. Basic building blocks of rules are statements.

Each rule consists of at least one.

*family*::

	The table's family.

*table*::

	The table's name.

*chain*::

	The chain's name.

*expr*::

	An array of statements this rule consists of. In input, it is used in

	*add*/*insert*/*replace* commands only.

*handle*::

	The rule's handle. In *delete*/*replace* commands, it serves as an identifier

	of the rule to delete/replace. In *add*/*insert* commands, it serves as

	an identifier of an existing rule to append/prepend the rule to.

*index*::

	The rule's position for *add*/*insert* commands. It is used as an alternative to

	*handle* then.

*comment*::

	Optional rule comment.

=== SET / MAP

[verse]

____

*{ "set": {

	"family":* 'STRING'*,

	"table":* 'STRING'*,

	"name":* 'STRING'*,

	"handle":* 'NUMBER'*,

	"type":* 'SET_TYPE'*,

	"policy":* 'SET_POLICY'*,

	"flags": [* 'SET_FLAG_LIST' *],

	"elem":* 'SET_ELEMENTS'*,

	"timeout":* 'NUMBER'*,

	"gc-interval":* 'NUMBER'*,

	"size":* 'NUMBER'

*}}*

*{ "map": {

	"family":* 'STRING'*,

	"table":* 'STRING'*,

	"name":* 'STRING'*,

	"handle":* 'NUMBER'*,

	"type":* 'SET_TYPE'*,

	"map":* 'STRING'*,

	"policy":* 'SET_POLICY'*,

	"flags": [* 'SET_FLAG_LIST' *],

	"elem":* 'SET_ELEMENTS'*,

	"timeout":* 'NUMBER'*,

	"gc-interval":* 'NUMBER'*,

	"size":* 'NUMBER'

*}}*

'SET_TYPE' := 'STRING' | *[* 'SET_TYPE_LIST' *]*

'SET_TYPE_LIST' := 'STRING' [*,* 'SET_TYPE_LIST' ]

'SET_POLICY' := *"performance"* | *"memory"*

'SET_FLAG_LIST' := 'SET_FLAG' [*,* 'SET_FLAG_LIST' ]

'SET_FLAG' := *"constant"* | *"interval"* | *"timeout"*

'SET_ELEMENTS' := 'EXPRESSION' | *[* 'EXPRESSION_LIST' *]*

'EXPRESSION_LIST' := 'EXPRESSION' [*,* 'EXPRESSION_LIST' ]

____

These objects describe a named set or map. Maps are a special form of sets in

that they translate a unique key to a value.

*family*::

	The table's family.

*table*::

	The table's name.

*name*::

	The set's name.

*handle*::

	The set's handle. For input, it is used in the *delete* command only.

*type*::

	The set's datatype, see below.

*map*::

	Type of values this set maps to (i.e. this set is a map).

*policy*::

	The set's policy.

*flags*::

	The set's flags.

*elem*::

	Initial set element(s), see below.

*timeout*::

	Element timeout in seconds.

*gc-interval*::

	Garbage collector interval in seconds.

*size*::

	Maximum number of elements supported.

==== TYPE

The set type might be a string, such as *"ipv4_addr"* or an array

consisting of strings (for concatenated types).

==== ELEM

A single set element might be given as string, integer or boolean value for

simple cases. If additional properties are required, a formal *elem* object may

be used.

Multiple elements may be given in an array.

=== ELEMENT

[verse]

____

*{ "element": {

	"family":* 'STRING'*,

	"table":* 'STRING'*,

	"name":* 'STRING'*,

	"elem":* 'SET_ELEM'

*}}*

'SET_ELEM' := 'EXPRESSION' | *[* 'EXPRESSION_LIST' *]*

'EXPRESSION_LIST' := 'EXPRESSION' [*,* 'EXPRESSION' ]

____

Manipulate element(s) in a named set.

*family*::

	The table's family.

*table*::

	The table's name.

*name*::

	The set's name.

*elem*::

	See elem property of set object.

=== FLOWTABLE

[verse]

____

*{ "flowtable": {

	"family":* 'STRING'*,

	"table":* 'STRING'*,

	"name":* 'STRING'*,

	"handle":* 'NUMBER'*,

	"hook":* 'STRING'*,

	"prio":* 'NUMBER'*,

	"dev":* 'FT_INTERFACE'

*}}*

'FT_INTERFACE' := 'STRING' | *[* 'FT_INTERFACE_LIST' *]*

'FT_INTERFACE_LIST' := 'STRING' [*,* 'STRING' ]

____

This object represents a named flowtable.

*family*::

	The table's family.

*table*::

	The table's name.

*name*::

	The flow table's name.

*handle*::

	The flow table's handle. In input, it is used by the *delete* command only.

*hook*::

	The flow table's hook.

*prio*::

	The flow table's priority.

*dev*::

	The flow table's interface(s).

=== COUNTER

[verse]

*{ "counter": {

	"family":* 'STRING'*,

	"table":* 'STRING'*,

	"name":* 'STRING'*,

	"handle":* 'NUMBER'*,

	"packets":* 'NUMBER'*,

	"bytes":* 'NUMBER'

*}}*

This object represents a named counter.

*family*::

	The table's family.

*table*::

	The table's name.

*name*::

	The counter's name.

*handle*::

	The counter's handle. In input, it is used by the *delete* command only.

*packets*::

	Packet counter value.

*bytes*::

	Byte counter value.

=== QUOTA

[verse]

*{ "quota": {

	"family":* 'STRING'*,

	"table":* 'STRING'*,

	"name":* 'STRING'*,

	"handle":* 'NUMBER'*,

	"bytes":* 'NUMBER'*,

	"used":* 'NUMBER'*,

	"inv":* 'BOOLEAN'

*}}*

This object represents a named quota.

*family*::

	The table's family.

*table*::

	The table's name.

*name*::

	The quota's name.

*handle*::

	The quota's handle. In input, it is used by the *delete* command only.

*bytes*::

	Quota threshold.

*used*::

	Quota used so far.

*inv*::

	If true, match if the quota has been exceeded.

=== CT HELPER

[verse]

____

*{ "ct helper": {

	"family":* 'STRING'*,

	"table":* 'STRING'*,

	"name":* 'STRING'*,

	"handle":* '... '*,

	"type":* 'STRING'*,

	"protocol":* 'CTH_PROTO'*,

	"l3proto":* 'STRING'

*}}*

'CTH_PROTO' := *"tcp"* | *"udp"*

____

This object represents a named conntrack helper.

*family*::

	The table's family.

*table*::

	The table's name.

*name*::

	The ct helper's name.

*handle*::

	The ct helper's handle. In input, it is used by the *delete* command only.

*type*::

	The ct helper type name, e.g. *"ftp"* or *"tftp"*.

*protocol*::

	The ct helper's layer 4 protocol.

*l3proto*::

	The ct helper's layer 3 protocol, e.g. *"ip"* or *"ip6"*.

=== LIMIT

[verse]

____

*{ "limit": {

	"family":* 'STRING'*,

	"table":* 'STRING'*,

	"name":* 'STRING'*,

	"handle":* 'NUMBER'*,

	"rate":* 'NUMBER'*,

	"per":* 'STRING'*,

	"burst":* 'NUMBER'*,

	"unit":* 'LIMIT_UNIT'*,

	"inv":* 'BOOLEAN'

*}}*

'LIMIT_UNIT' := *"packets"* | *"bytes"*

____

This object represents a named limit.

*family*::

	The table's family.

*table*::

	The table's name.

*name*::

	The limit's name.

*handle*::

	The limit's handle. In input, it is used by the *delete* command only.

*rate*::

	The limit's rate value.

*per*::

	Time unit to apply the limit to, e.g. *"week"*, *"day"*, *"hour"*, etc.

	If omitted, defaults to *"second"*.

*burst*::

	The limit's burst value. If omitted, defaults to *0*.

*unit*::

	Unit of rate and burst values. If omitted, defaults to *"packets"*.

*inv*::

	If true, match if limit was exceeded. If omitted, defaults to *false*.

=== CT TIMEOUT

[verse]

____

*{ "ct timeout": {

	"family":* 'STRING'*,

	"table":* 'STRING'*,

	"name":* 'STRING'*,

	"handle":* 'NUMBER'*,

	"protocol":* 'CTH_PROTO'*,

	"state":* 'STRING'*,

	"value:* 'NUMBER'*,

	"l3proto":* 'STRING'

*}}*

'CTH_PROTO' := *"tcp"* | *"udp"* | *"dccp"* | *"sctp"* | *"gre"* | *"icmpv6"* | *"icmp"* | *"generic"*

____

This object represents a named conntrack timeout policy.

*family*::

	The table's family.

*table*::

	The table's name.

*name*::

	The ct timeout object's name.

*handle*::

	The ct timeout object's handle. In input, it is used by *delete* command only.

*protocol*::

	The ct timeout object's layer 4 protocol.

*state*::

	The connection state name, e.g. *"established"*, *"syn_sent"*, *"close"* or

	*"close_wait"*, for which the timeout value has to be updated.

*value*::

	The updated timeout value for the specified connection state.

*l3proto*::

	The ct timeout object's layer 3 protocol, e.g. *"ip"* or *"ip6"*.

=== CT EXPECTATION

[verse]

____

*{ "ct expectation": {

	"family":* 'STRING'*,

	"table":* 'STRING'*,

	"name":* 'STRING'*,

	"handle":* 'NUMBER'*,

	"l3proto":* 'STRING'

	"protocol":* 'CTH_PROTO'*,

	"dport":* 'NUMBER'*,

	"timeout:* 'NUMBER'*,

	"size:* 'NUMBER'*,

*}}*

'CTH_PROTO' := *"tcp"* | *"udp"* | *"dccp"* | *"sctp"* | *"gre"* | *"icmpv6"* | *"icmp"* | *"generic"*

____

This object represents a named conntrack expectation.

*family*::

	The table's family.

*table*::

	The table's name.

*name*::

	The ct expectation object's name.

*handle*::

	The ct expectation object's handle. In input, it is used by *delete* command only.

*l3proto*::

	The ct expectation object's layer 3 protocol, e.g. *"ip"* or *"ip6"*.

*protocol*::

	The ct expectation object's layer 4 protocol.

*dport*::

	The destination port of the expected connection.

*timeout*::

	The time in millisecond that this expectation will live.

*size*::

	The maximum count of expectations to be living in the same time.

== STATEMENTS

Statements are the building blocks for rules. Each rule consists of at least

one.

=== VERDICT

[verse]

*{ "accept": null }*

*{ "drop": null }*

*{ "continue": null }*

*{ "return": null }*

*{ "jump": { "target": * 'STRING' *}}*

*{ "goto": { "target": * 'STRING' *}}*

A verdict either terminates packet traversal through the current chain or

delegates to a different one.

*jump* and *goto* statements expect a target chain name.

=== MATCH

[verse]

*{ "match": {

	"left":* 'EXPRESSION'*,

	"right":* 'EXPRESSION'*,

	"op":* 'STRING'

*}}*

This matches the expression on left hand side (typically a packet header or packet meta

info) with the expression on right hand side (typically a constant value). If the

statement evaluates to true, the next statement in this rule is considered. If not,

processing continues with the next rule in the same chain.

*left*::

	Left hand side of this match.

*right*::

	Right hand side of this match.

*op*::

	Operator indicating the type of comparison.

==== OPERATORS

[horizontal]

*&*:: Binary AND

*|*:: Binary OR

*^*:: Binary XOR

*<<*:: Left shift

*>>*:: Right shift

*==*:: Equal

*!=*:: Not equal

*<*:: Less than

*>*:: Greater than

*<=*:: Less than or equal to

*>=*:: Greater than or equal to

*in*:: Perform a lookup, i.e. test if bits on RHS are contained in LHS value

Unlike with the standard API, the operator is mandatory here. In the standard API,

a missing operator may be resolved in two ways, depending on the type of expression

on the RHS:

- If the RHS is a bitmask or a list of bitmasks, the expression resolves into a

  binary operation with the inequality operator, like this: '+LHS & RHS != 0+'.

- In any other case, the equality operator is simply inserted.

For the non-trivial first case, the JSON API supports the *in* operator.

=== COUNTER

[verse]

____

*{ "counter": {

	"packets":* 'NUMBER'*,

	"bytes":* 'NUMBER'

*}}*

*{ "counter":* 'STRING' *}*

____

This object represents a byte/packet counter. In input, no properties are

required. If given, they act as initial values for the counter.

The first form creates an anonymous counter which lives in the rule it appears

in. The second form specifies a reference to a named counter object.

*packets*::

	Packets counted.

*bytes*::

	Bytes counted.

=== MANGLE

[verse]

*{ "mangle": {

	"key":* 'EXPRESSION'*,

	"value":* 'EXPRESSION'

*}}*

This changes the packet data or meta info.

*key*::

	The packet data to be changed, given as an *exthdr*, *payload*, *meta*, *ct* or

	*ct helper* expression.

*value*::

	Value to change data to.

=== QUOTA

[verse]

____

*{ "quota": {

	"val":* 'NUMBER'*,

	"val_unit":* 'STRING'*,

	"used":* 'NUMBER'*,

	"used_unit":* 'STRING'*,

	"inv":* 'BOOLEAN'

*}}*

*{ "quota":* 'STRING' *}*

____

The first form creates an anonymous quota which lives in the rule it appears in.

The second form specifies a reference to a named quota object.

*val*::

	Quota value.

*val_unit*::

	Unit of *val*, e.g. *"kbytes"* or *"mbytes"*. If omitted, defaults to

	*"bytes"*.

*used*::

	Quota used so far. Optional on input. If given, serves as initial value.

*used_unit*::

	Unit of *used*. Defaults to *"bytes"*.

*inv*::

	If *true*, will match if quota was exceeded. Defaults to *false*.

=== LIMIT

[verse]

____

*{ "limit": {

	"rate":* 'NUMBER'*,

	"rate_unit":* 'STRING'*,

	"per":* 'STRING'*,

	"burst":* 'NUMBER'*,

	"burst_unit":* 'STRING'*,

	"inv":* 'BOOLEAN'

*}}*

*{ "limit":* 'STRING' *}*

____

The first form creates an anonymous limit which lives in the rule it appears in.

The second form specifies a reference to a named limit object.

*rate*::

	Rate value to limit to.

*rate_unit*::

	Unit of *rate*, e.g. *"packets"* or *"mbytes"*. Defaults to *"packets"*.

*per*::

	Denominator of *rate*, e.g. *"week"* or *"minutes"*.

*burst*::

	Burst value. Defaults to *0*.

*burst_unit*::

	Unit of *burst*, ignored if *rate_unit* is *"packets"*. Defaults to

	*"bytes"*.

*inv*::

	If *true*, matches if the limit was exceeded. Defaults to *false*.

=== FWD

[verse]

____

*{ "fwd": {

	"dev":* 'EXPRESSION'*,

	"family":* 'FWD_FAMILY'*,

	"addr":* 'EXPRESSION'

*}}*

'FWD_FAMILY' := *"ip"* | *"ip6"*

____

Forward a packet to a different destination.

*dev*::

	Interface to forward the packet on.

*family*::

	Family of *addr*.

*addr*::

	IP(v6) address to forward the packet to.

Both *family* and *addr* are optional, but if at least one is given, both must be present.

=== NOTRACK

[verse]

*{ "notrack": null }*

Disable connection tracking for the packet.

=== DUP

[verse]

*{ "dup": {

	"addr":* 'EXPRESSION'*,

	"dev":* 'EXPRESSION'

*}}*

Duplicate a packet to a different destination.

*addr*::

	Address to duplicate packet to.

*dev*::

	Interface to duplicate packet on. May be omitted to not specify an

	interface explicitly.

=== NETWORK ADDRESS TRANSLATION

[verse]

____

*{ "snat": {

	"addr":* 'EXPRESSION'*,

	"family":* 'STRING'*,

	"port":* 'EXPRESSION'*,

	"flags":* 'FLAGS'

*}}*

*{ "dnat": {

	"addr":* 'EXPRESSION'*,

	"family":* 'STRING'*,

	"port":* 'EXPRESSION'*,

	"flags":* 'FLAGS'

*}}*

*{ "masquerade": {

	"port":* 'EXPRESSION'*,

	"flags":* 'FLAGS'

*}}*

*{ "redirect": {

	"port":* 'EXPRESSION'*,

	"flags":* 'FLAGS'

*}}*

'FLAGS' := 'FLAG' | *[* 'FLAG_LIST' *]*

'FLAG_LIST' := 'FLAG' [*,* 'FLAG_LIST' ]

'FLAG' := *"random"* | *"fully-random"* | *"persistent"*

____