NAME
libnftables-json - Supported JSON schema by libnftablesSYNOPSIS
{ "nftables": [ OBJECTS ] }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.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).METAINFO OBJECT
In output, the first object in an nftables array is a special one containing library information. Its content is as follows:{ "metainfo": { "version": STRING, "release_name": STRING, "json_schema_version": NUMBER }}
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
{ "nftables": [ { "flush": { "ruleset": null }}, { "add": { "table": { "family": "inet", "name": "mytable" }}}, { "add": { "chain": { "family": "inet", "table": "mytable", "name": "mychain" }}}, { "add": { "rule": { "family": "inet", "table": "mytable", "chain": "mychain", "expr": [ { "match": { "op": "==", "left": { "payload": { "protocol": "tcp", "field": "dport" }}, "right": 22 }}, { "accept": null } ] }}} ]}
ADD
{ "add": ADD_OBJECT } ADD_OBJECT := TABLE | CHAIN | RULE | SET | MAP | ELEMENT | FLOWTABLE | COUNTER | QUOTA | CT_HELPER | LIMIT | CT_TIMEOUT | CT_EXPECTATION
REPLACE
{ "replace": RULE }
CREATE
{ "create": ADD_OBJECT }
INSERT
{ "insert": RULE }
DELETE
{ "delete": ADD_OBJECT }
LIST
{ "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
RESET
{ "reset": RESET_OBJECT } RESET_OBJECT := COUNTER | COUNTERS | QUOTA | QUOTAS
FLUSH
{ "flush": FLUSH_OBJECT } FLUSH_OBJECT := TABLE | CHAIN | SET | MAP | METER | RULESET
RENAME
{ "rename": CHAIN }
RULESET ELEMENTS
TABLE
{ "table": { "family": STRING, "name": STRING, "handle": NUMBER }}
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
{ "chain": { "family": STRING, "table": STRING, "name": STRING, "newname": STRING, "handle": NUMBER, "type": STRING, "hook": STRING, "prio": NUMBER, "dev": STRING, "policy": STRING }}
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 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
{ "rule": { "family": STRING, "table": STRING, "chain": STRING, "expr": [ STATEMENTS ], "handle": NUMBER, "index": NUMBER, "comment": STRING }} STATEMENTS := STATEMENT [, STATEMENTS ]
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
{ "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 ]
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.
ELEMENT
{ "element": { "family": STRING, "table": STRING, "name": STRING, "elem": SET_ELEM }} SET_ELEM := EXPRESSION | [ EXPRESSION_LIST ] EXPRESSION_LIST := EXPRESSION [, EXPRESSION ]
The table’s family.
table
The table’s name.
name
The set’s name.
elem
See elem property of set object.
FLOWTABLE
{ "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 ]
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
{ "counter": { "family": STRING, "table": STRING, "name": STRING, "handle": NUMBER, "packets": NUMBER, "bytes": NUMBER }}
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
{ "quota": { "family": STRING, "table": STRING, "name": STRING, "handle": NUMBER, "bytes": NUMBER, "used": NUMBER, "inv": BOOLEAN }}
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
{ "ct helper": { "family": STRING, "table": STRING, "name": STRING, "handle": ... ', "type": 'STRING, "protocol": CTH_PROTO, "l3proto": STRING }} CTH_PROTO := "tcp" | "udp"
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
{ "limit": { "family": STRING, "table": STRING, "name": STRING, "handle": NUMBER, "rate": NUMBER, "per": STRING, "burst": NUMBER, "unit": LIMIT_UNIT, "inv": BOOLEAN }} LIMIT_UNIT := "packets" | "bytes"
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
{ "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"
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
{ "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"
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
{ "accept": null } { "drop": null } { "continue": null } { "return": null } { "jump": { "target": * STRING *}} { "goto": { "target": * STRING *}}
MATCH
{ "match": { "left": EXPRESSION, "right": EXPRESSION, "op": STRING }}
Left hand side of this match.
right
Right hand side of this match.
op
Operator indicating the type of
comparison.
& | 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 |
•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.
COUNTER
{ "counter": { "packets": NUMBER, "bytes": NUMBER }} { "counter": STRING }
Packets counted.
bytes
Bytes counted.
MANGLE
{ "mangle": { "key": EXPRESSION, "value": EXPRESSION }}
The packet data to be changed, given as an
exthdr, payload, meta, ct or ct helper
expression.
value
Value to change data to.
QUOTA
{ "quota": { "val": NUMBER, "val_unit": STRING, "used": NUMBER, "used_unit": STRING, "inv": BOOLEAN }} { "quota": STRING }
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
{ "limit": { "rate": NUMBER, "rate_unit": STRING, "per": STRING, "burst": NUMBER, "burst_unit": STRING, "inv": BOOLEAN }} { "limit": STRING }
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
{ "fwd": { "dev": EXPRESSION, "family": FWD_FAMILY, "addr": EXPRESSION }} FWD_FAMILY := "ip" | "ip6"
Interface to forward the packet on.
family
Family of addr.
addr
IP(v6) address to forward the packet to.
NOTRACK
{ "notrack": null }
DUP
{ "dup": { "addr": EXPRESSION, "dev": EXPRESSION }}
Address to duplicate packet to.
dev
Interface to duplicate packet on. May be
omitted to not specify an interface explicitly.
NETWORK ADDRESS TRANSLATION
{ "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"
Address to translate to.
family
Family of addr, either ip or
ip6. Required in inet table family.
port
Port to translate to.
flags
Flag(s).
REJECT
{ "reject": { "type": STRING, "expr": EXPRESSION }}
Type of reject, either "tcp
reset", "icmpx", "icmp" or
"icmpv6".
expr
ICMP code to reject with.
SET
{ "set": { "op": STRING, "elem": EXPRESSION, "set": STRING }}
Operator on set, either "add"
or "update".
elem
Set element to add or update.
set
Set reference.
LOG
{ "log": { "prefix": STRING, "group": NUMBER, "snaplen": NUMBER, "queue-threshold": NUMBER, "level": LEVEL, "flags": FLAGS }} LEVEL := "emerg" | "alert" | "crit" | "err" | "warn" | "notice" | "info" | "debug" | "audit" FLAGS := FLAG | [ FLAG_LIST ] FLAG_LIST := FLAG [, FLAG_LIST ] FLAG := "tcp sequence" | "tcp options" | "ip options" | "skuid" | "ether" | "all"
Prefix for log entries.
group
Log group.
snaplen
Snaplen for logging.
queue-threshold
Queue threshold.
level
Log level. Defaults to
"warn".
flags
Log flags.
CT HELPER
{ "ct helper": EXPRESSION }
CT helper reference.
METER
{ "meter": { "name": STRING, "key": EXPRESSION, "stmt": STATEMENT }}
Meter name.
key
Meter key.
stmt
Meter statement.
QUEUE
{ "queue": { "num": EXPRESSION, "flags": FLAGS }} FLAGS := FLAG | [ FLAG_LIST ] FLAG_LIST := FLAG [, FLAG_LIST ] FLAG := "bypass" | "fanout"
Queue number.
flags
Queue flags.
VERDICT MAP
{ "vmap": { "key": EXPRESSION, "data": EXPRESSION }}
Map key.
data
Mapping expression consisting of value/verdict
pairs.
CT COUNT
{ "ct count": { "val": NUMBER, "inv": BOOLEAN }}
Connection count threshold.
inv
If true, match if val was
exceeded. If omitted, defaults to false.
CT TIMEOUT
{ "ct timeout": EXPRESSION }
CT timeout reference.
CT EXPECTATION
{ "ct expectation": EXPRESSION }
CT expectation reference.
XT
{ "xt": { "type": TYPENAME, "name": STRING }} TYPENAME := match | target | watcher
EXPRESSIONS
Expressions are the building blocks of (most) statements. In their most basic form, they are just immediate values represented as a JSON string, integer or boolean type.IMMEDIATES
STRING NUMBER BOOLEAN
The remaining part is taken as set name to
create a set reference.
\*
Construct a wildcard expression.
LISTS
ARRAY
CONCAT
{ "concat": CONCAT } CONCAT := [ EXPRESSION_LIST ] EXPRESSION_LIST := EXPRESSION [, EXPRESSION_LIST ]
SET
{ "set": SET } SET := EXPRESSION | [ EXPRESSION_LIST ]
MAP
{ "map": { "key": EXPRESSION, "data": EXPRESSION }}
Map key.
data
Mapping expression consisting of value/target
pairs.
PREFIX
{ "prefix": { "addr": EXPRESSION, "len": NUMBER }}
RANGE
{ "range": [ EXPRESSION , EXPRESSION ] }
PAYLOAD
{ "payload": { "base": BASE, "offset": NUMBER, "len": NUMBER }} { "payload": { "protocol": STRING, "field": STRING }} BASE := "ll" | "nh" | "th"
The offset is relative to Link Layer header
start offset.
"nh"
The offset is relative to Network Layer header
start offset.
"th"
The offset is relative to Transport Layer
header start offset.
EXTHDR
{ "exthdr": { "name": STRING, "field": STRING, "offset": NUMBER }}
TCP OPTION
{ "tcp option": { "name": STRING, "field": STRING }}
SCTP CHUNK
{ "sctp chunk": { "name": STRING, "field": STRING }}
META
{ "meta": { "key": META_KEY }} META_KEY := "length" | "protocol" | "priority" | "random" | "mark" | "iif" | "iifname" | "iiftype" | "oif" | "oifname" | "oiftype" | "skuid" | "skgid" | "nftrace" | "rtclassid" | "ibriport" | "obriport" | "ibridgename" | "obridgename" | "pkttype" | "cpu" | "iifgroup" | "oifgroup" | "cgroup" | "nfproto" | "l4proto" | "secpath"
RT
{ "rt": { "key": RT_KEY, "family": RT_FAMILY }} RT_KEY := "classid" | "nexthop" | "mtu" RT_FAMILY := "ip" | "ip6"
CT
{ "ct": { "key": STRING, "family": CT_FAMILY, "dir": CT_DIRECTION }} CT_FAMILY := "ip" | "ip6" CT_DIRECTION := "original" | "reply"
NUMGEN
{ "numgen": { "mode": NG_MODE, "mod": NUMBER, "offset": NUMBER }} NG_MODE := "inc" | "random"
HASH
{ "jhash": { "mod": NUMBER, "offset": NUMBER, "expr": EXPRESSION, "seed": NUMBER }} { "symhash": { "mod": NUMBER, "offset": NUMBER }}
FIB
{ "fib": { "result": FIB_RESULT, "flags": FIB_FLAGS }} FIB_RESULT := "oif" | "oifname" | "type" FIB_FLAGS := FIB_FLAG | [ FIB_FLAG_LIST ] FIB_FLAG_LIST := FIB_FLAG [, FIB_FLAG_LIST ] FIB_FLAG := "saddr" | "daddr" | "mark" | "iif" | "oif"
BINARY OPERATION
{ "|": [ EXPRESSION, EXPRESSION ] } { "^": [ EXPRESSION, EXPRESSION ] } { "&": [ EXPRESSION, EXPRESSION ] } { "<<": [ EXPRESSION, EXPRESSION ] } { ">>": [ EXPRESSION, EXPRESSION ] }
VERDICT
{ "accept": null } { "drop": null } { "continue": null } { "return": null } { "jump": { "target": STRING }} { "goto": { "target": STRING }}
ELEM
{ "elem": { "val": EXPRESSION, "timeout": NUMBER, "expires": NUMBER, "comment": STRING }}
SOCKET
{ "socket": { "key": SOCKET_KEY }} SOCKET_KEY := "transparent"
OSF
{ "osf": { "key": OSF_KEY, "ttl": OSF_TTL }} OSF_KEY := "name" OSF_TTL := "loose" | "skip"
Which part of the fingerprint info to match
against. At this point, only the OS name is supported.
ttl
Define how the packet’s TTL value is to
be matched. This property is optional. If omitted, the TTL value has to match
exactly. A value of loose accepts TTL values less than the fingerprint
one. A value of skip omits TTL value comparison entirely.
AUTHOR
Phil Sutter <[email protected]>Author.
09/16/2023 |