1LIBNFTABLES-JSON(5) LIBNFTABLES-JSON(5)
2
6 libnftables-json - Supported JSON schema by libnftables
7
9 { "nftables": [ OBJECTS ] }
10 OBJECTS := LIST_OBJECTS | CMD_OBJECTS
12 LIST_OBJECTS := LIST_OBJECT [ , LIST_OBJECTS ]
14 CMD_OBJECTS := CMD_OBJECT [ , CMD_OBJECTS ]
16 CMD_OBJECT := { CMD: LIST_OBJECT } | METAINFO_OBJECT
18 CMD := "add" | "replace" | "create" | "insert" | "delete" | "list" |
20 "reset" | "flush" | "rename"
21 LIST_OBJECT := TABLE | CHAIN | RULE | SET | MAP | ELEMENT | FLOWTABLE |
23 COUNTER | QUOTA | CT_HELPER | LIMIT | METAINFO_OBJECT | CT_TIMEOUT |
24 CT_EXPECTATION
25
27 libnftables supports JSON formatted input and output. This is
28 implemented as an alternative frontend to the standard CLI syntax
29 parser, therefore basic behaviour is identical and, for (almost) any
30 operation available in standard syntax, there should be an equivalent
31 one in JSON.
32 JSON input may be provided in a single string as parameter to
34 nft_run_cmd_from_buffer() or in a file identified by the filename
35 parameter of the nft_run_cmd_from_filename() function.
36 JSON output has to be enabled via the nft_ctx_output_set_json()
38 function, turning library standard output into JSON format. Error
39 output remains unaffected.
40
42 In general, any JSON input or output is enclosed in an object with a
43 single property named nftables. Its value is an array containing
44 commands (for input) or ruleset elements (for output).
45 A command is an object with a single property whose name identifies the
47 command. Its value is a ruleset element - basically identical to output
48 elements, apart from certain properties which may be interpreted
49 differently or are required when output generally omits them.
50
52 In output, the first object in an nftables array is a special one
53 containing library information. Its content is as follows:
54 { "metainfo": {
56 "version": STRING,
57 "release_name": STRING,
58 "json_schema_version": NUMBER
59 }}
60 The values of version and release_name properties are equal to the
62 package version and release name as printed by nft -v. The value of the
63 json_schema_version property is an integer indicating the schema
64 version.
65 If supplied in library input, the parser will verify the
67 json_schema_version value to not exceed the internally hardcoded one
68 (to make sure the given schema is fully understood). In future, a lower
69 number than the internal one may activate compatibility mode to parse
70 outdated and incompatible JSON input.
71
73 The structure accepts an arbitrary amount of commands which are
74 interpreted in order of appearance. For instance, the following
75 standard syntax input:
76 flush ruleset
78 add table inet mytable
79 add chain inet mytable mychain
80 add rule inet mytable mychain tcp dport 22 accept
81 translates into JSON as such:
83 { "nftables": [
85 { "flush": { "ruleset": null }},
86 { "add": { "table": {
87 "family": "inet",
88 "name": "mytable"
89 }}},
90 { "add": { "chain": {
91 "family": "inet",
92 "table": "mytable",
93 "chain": "mychain"
94 }}}
95 { "add": { "rule": {
96 "family": "inet",
97 "table": "mytable",
98 "chain": "mychain",
99 "expr": [
100 { "match": {
101 "left": { "payload": {
102 "protocol": "tcp",
103 "field": "dport"
104 }},
105 "right": 22
106 }},
107 { "accept": null }
108 ]
109 }}}
110 ]}
111 ADD
113 { "add": ADD_OBJECT }
114 ADD_OBJECT := TABLE | CHAIN | RULE | SET | MAP | ELEMENT |
116 FLOWTABLE | COUNTER | QUOTA | CT_HELPER | LIMIT |
117 CT_TIMEOUT | CT_EXPECTATION
118 Add a new ruleset element to the kernel.
120 REPLACE
122 { "replace": RULE }
123 Replace a rule. In RULE, the handle property is mandatory and
125 identifies the rule to be replaced.
126 CREATE
128 { "create": ADD_OBJECT }
129 Identical to add command, but returns an error if the object already
131 exists.
132 INSERT
134 { "insert": RULE }
135 This command is identical to add for rules, but instead of appending
137 the rule to the chain by default, it inserts at first position. If a
138 handle or index property is given, the rule is inserted before the rule
139 identified by those properties.
140 DELETE
142 { "delete": ADD_OBJECT }
143 Delete an object from the ruleset. Only the minimal number of
145 properties required to uniquely identify an object is generally needed
146 in ADD_OBJECT. For most ruleset elements, this is family and table plus
147 either handle or name (except rules since they don’t have a name).
148 LIST
150 { "list": LIST_OBJECT }
151 LIST_OBJECT := TABLE | TABLES | CHAIN | CHAINS | SET | SETS |
153 MAP | MAPS | COUNTER | COUNTERS | QUOTA | QUOTAS |
154 CT_HELPER | CT_HELPERS | LIMIT | LIMITS | RULESET |
155 METER | METERS | FLOWTABLE | FLOWTABLES |
156 CT_TIMEOUT | CT_EXPECTATION
157 List ruleset elements. The plural forms are used to list all objects of
159 that kind, optionally filtered by family and for some, also table.
160 RESET
162 { "reset": RESET_OBJECT }
163 RESET_OBJECT := COUNTER | COUNTERS | QUOTA | QUOTAS
165 Reset state in suitable objects, i.e. zero their internal counter.
167 FLUSH
169 { "flush": FLUSH_OBJECT }
170 FLUSH_OBJECT := TABLE | CHAIN | SET | MAP | METER | RULESET
172 Empty contents in given object, e.g. remove all chains from given table
174 or remove all elements from given set.
175 RENAME
177 { "rename": CHAIN }
178 Rename a chain. The new name is expected in a dedicated property named
180 newname.
181
183 TABLE
184 { "table": {
185 "family": STRING,
186 "name": STRING,
187 "handle": NUMBER
188 }}
189 This object describes a table.
191 family
193 The table’s family, e.g. "ip" or "ip6".
194 name
196 The table’s name.
197 handle
199 The table’s handle. In input, it is used only in delete command as
200 alternative to name.
201 CHAIN
203 { "chain": {
204 "family": STRING,
205 "table": STRING,
206 "name": STRING,
207 "newname": STRING,
208 "handle": NUMBER,
209 "type": STRING,
210 "hook": STRING,
211 "prio": NUMBER,
212 "dev": STRING,
213 "policy": STRING
214 }}
215 This object describes a chain.
217 family
219 The table’s family.
220 table
222 The table’s name.
223 name
225 The chain’s name.
226 handle
228 The chain’s handle. In input, it is used only in delete command as
229 alternative to name.
230 newname
232 A new name for the chain, only relevant in the rename command.
233 The following properties are required for base chains:
235 type
237 The chain’s type.
238 hook
240 The chain’s hook.
241 prio
243 The chain’s priority.
244 dev
246 The chain’s bound interface (if in the netdev family).
247 policy
249 The chain’s policy.
250 RULE
252 { "rule": {
253 "family": STRING,
254 "table": STRING,
255 "chain": STRING,
256 "expr": [ STATEMENTS ],
257 "handle": NUMBER,
258 "index": NUMBER,
259 "comment": STRING
260 }}
261 STATEMENTS := STATEMENT [, STATEMENTS ]
263 This object describes a rule. Basic building blocks of rules are
265 statements. Each rule consists of at least one.
266 family
268 The table’s family.
269 table
271 The table’s name.
272 chain
274 The chain’s name.
275 expr
277 An array of statements this rule consists of. In input, it is used
278 in add/insert/replace commands only.
279 handle
281 The rule’s handle. In delete/replace commands, it serves as an
282 identifier of the rule to delete/replace. In add/insert commands,
283 it serves as an identifier of an existing rule to append/prepend
284 the rule to.
285 index
287 The rule’s position for add/insert commands. It is used as an
288 alternative to handle then.
289 comment
291 Optional rule comment.
292 SET / MAP
294 { "set": {
295 "family": STRING,
296 "table": STRING,
297 "name": STRING,
298 "handle": NUMBER,
299 "type": SET_TYPE,
300 "policy": SET_POLICY,
301 "flags": [ SET_FLAG_LIST ],
302 "elem": SET_ELEMENTS,
303 "timeout": NUMBER,
304 "gc-interval": NUMBER,
305 "size": NUMBER
306 }}
307 { "map": {
309 "family": STRING,
310 "table": STRING,
311 "name": STRING,
312 "handle": NUMBER,
313 "type": SET_TYPE,
314 "map": STRING,
315 "policy": SET_POLICY,
316 "flags": [ SET_FLAG_LIST ],
317 "elem": SET_ELEMENTS,
318 "timeout": NUMBER,
319 "gc-interval": NUMBER,
320 "size": NUMBER
321 }}
322 SET_TYPE := STRING | [ SET_TYPE_LIST ]
324 SET_TYPE_LIST := STRING [, SET_TYPE_LIST ]
325 SET_POLICY := "performance" | "memory"
326 SET_FLAG_LIST := SET_FLAG [, SET_FLAG_LIST ]
327 SET_FLAG := "constant" | "interval" | "timeout"
328 SET_ELEMENTS := EXPRESSION | [ EXPRESSION_LIST ]
329 EXPRESSION_LIST := EXPRESSION [, EXPRESSION_LIST ]
330 These objects describe a named set or map. Maps are a special form of
332 sets in that they translate a unique key to a value.
333 family
335 The table’s family.
336 table
338 The table’s name.
339 name
341 The set’s name.
342 handle
344 The set’s handle. For input, it is used in the delete command only.
345 type
347 The set’s datatype, see below.
348 map
350 Type of values this set maps to (i.e. this set is a map).
351 policy
353 The set’s policy.
354 flags
356 The set’s flags.
357 elem
359 Initial set element(s), see below.
360 timeout
362 Element timeout in seconds.
363 gc-interval
365 Garbage collector interval in seconds.
366 size
368 Maximum number of elements supported.
369 TYPE
371 The set type might be a string, such as "ipv4_addr" or an array
372 consisting of strings (for concatenated types).
373 ELEM
375 A single set element might be given as string, integer or boolean
376 value for simple cases. If additional properties are required, a
377 formal elem object may be used.
378 Multiple elements may be given in an array.
380 ELEMENT
382 { "element": {
383 "family": STRING,
384 "table": STRING,
385 "name": STRING,
386 "elem": SET_ELEM
387 }}
388 SET_ELEM := EXPRESSION | [ EXPRESSION_LIST ]
390 EXPRESSION_LIST := EXPRESSION [, EXPRESSION ]
391 Manipulate element(s) in a named set.
393 family
395 The table’s family.
396 table
398 The table’s name.
399 name
401 The set’s name.
402 elem
404 See elem property of set object.
405 FLOWTABLE
407 { "flowtable": {
408 "family": STRING,
409 "table": STRING,
410 "name": STRING,
411 "handle": NUMBER,
412 "hook": STRING,
413 "prio": NUMBER,
414 "dev": FT_INTERFACE
415 }}
416 FT_INTERFACE := STRING | [ FT_INTERFACE_LIST ]
418 FT_INTERFACE_LIST := STRING [, STRING ]
419 This object represents a named flowtable.
421 family
423 The table’s family.
424 table
426 The table’s name.
427 name
429 The flow table’s name.
430 handle
432 The flow table’s handle. In input, it is used by the delete command
433 only.
434 hook
436 The flow table’s hook.
437 prio
439 The flow table’s priority.
440 dev
442 The flow table’s interface(s).
443 COUNTER
445 { "counter": {
446 "family": STRING,
447 "table": STRING,
448 "name": STRING,
449 "handle": NUMBER,
450 "packets": NUMBER,
451 "bytes": NUMBER
452 }}
453 This object represents a named counter.
455 family
457 The table’s family.
458 table
460 The table’s name.
461 name
463 The counter’s name.
464 handle
466 The counter’s handle. In input, it is used by the delete command
467 only.
468 packets
470 Packet counter value.
471 bytes
473 Byte counter value.
474 QUOTA
476 { "quota": {
477 "family": STRING,
478 "table": STRING,
479 "name": STRING,
480 "handle": NUMBER,
481 "bytes": NUMBER,
482 "used": NUMBER,
483 "inv": BOOLEAN
484 }}
485 This object represents a named quota.
487 family
489 The table’s family.
490 table
492 The table’s name.
493 name
495 The quota’s name.
496 handle
498 The quota’s handle. In input, it is used by the delete command
499 only.
500 bytes
502 Quota threshold.
503 used
505 Quota used so far.
506 inv
508 If true, match if the quota has been exceeded.
509 CT HELPER
511 { "ct helper": {
512 "family": STRING,
513 "table": STRING,
514 "name": STRING,
515 "handle": ... ',
516 "type": 'STRING,
517 "protocol": CTH_PROTO,
518 "l3proto": STRING
519 }}
520 CTH_PROTO := "tcp" | "udp"
522 This object represents a named conntrack helper.
524 family
526 The table’s family.
527 table
529 The table’s name.
530 name
532 The ct helper’s name.
533 handle
535 The ct helper’s handle. In input, it is used by the delete command
536 only.
537 type
539 The ct helper type name, e.g. "ftp" or "tftp".
540 protocol
542 The ct helper’s layer 4 protocol.
543 l3proto
545 The ct helper’s layer 3 protocol, e.g. "ip" or "ip6".
546 LIMIT
548 { "limit": {
549 "family": STRING,
550 "table": STRING,
551 "name": STRING,
552 "handle": NUMBER,
553 "rate": NUMBER,
554 "per": STRING,
555 "burst": NUMBER,
556 "unit": LIMIT_UNIT,
557 "inv": BOOLEAN
558 }}
559 LIMIT_UNIT := "packets" | "bytes"
561 This object represents a named limit.
563 family
565 The table’s family.
566 table
568 The table’s name.
569 name
571 The limit’s name.
572 handle
574 The limit’s handle. In input, it is used by the delete command
575 only.
576 rate
578 The limit’s rate value.
579 per
581 Time unit to apply the limit to, e.g. "week", "day", "hour", etc.
582 If omitted, defaults to "second".
583 burst
585 The limit’s burst value. If omitted, defaults to 0.
586 unit
588 Unit of rate and burst values. If omitted, defaults to "packets".
589 inv
591 If true, match if limit was exceeded. If omitted, defaults to
592 false.
593 CT TIMEOUT
595 { "ct timeout": {
596 "family": STRING,
597 "table": STRING,
598 "name": STRING,
599 "handle": NUMBER,
600 "protocol": CTH_PROTO,
601 "state": STRING,
602 "value: NUMBER,
603 "l3proto": STRING
604 }}
605 CTH_PROTO := "tcp" | "udp" | "dccp" | "sctp" | "gre" | "icmpv6" | "icmp" | "generic"
607 This object represents a named conntrack timeout policy.
609 family
611 The table’s family.
612 table
614 The table’s name.
615 name
617 The ct timeout object’s name.
618 handle
620 The ct timeout object’s handle. In input, it is used by delete
621 command only.
622 protocol
624 The ct timeout object’s layer 4 protocol.
625 state
627 The connection state name, e.g. "established", "syn_sent", "close"
628 or "close_wait", for which the timeout value has to be updated.
629 value
631 The updated timeout value for the specified connection state.
632 l3proto
634 The ct timeout object’s layer 3 protocol, e.g. "ip" or "ip6".
635 CT EXPECTATION
637 { "ct expectation": {
638 "family": STRING,
639 "table": STRING,
640 "name": STRING,
641 "handle": NUMBER,
642 "l3proto": STRING
643 "protocol":* CTH_PROTO,
644 "dport": NUMBER,
645 "timeout: NUMBER,
646 "size: NUMBER,
647 *}}
648 CTH_PROTO := "tcp" | "udp" | "dccp" | "sctp" | "gre" | "icmpv6" | "icmp" | "generic"
650 This object represents a named conntrack expectation.
652 family
654 The table’s family.
655 table
657 The table’s name.
658 name
660 The ct expectation object’s name.
661 handle
663 The ct expectation object’s handle. In input, it is used by delete
664 command only.
665 l3proto
667 The ct expectation object’s layer 3 protocol, e.g. "ip" or "ip6".
668 protocol
670 The ct expectation object’s layer 4 protocol.
671 dport
673 The destination port of the expected connection.
674 timeout
676 The time in millisecond that this expectation will live.
677 size
679 The maximum count of expectations to be living in the same time.
680
682 Statements are the building blocks for rules. Each rule consists of at
683 least one.
684 VERDICT
686 { "accept": null }
687 { "drop": null }
688 { "continue": null }
689 { "return": null }
690 { "jump": { "target": * STRING *}}
691 { "goto": { "target": * STRING *}}
692 A verdict either terminates packet traversal through the current chain
694 or delegates to a different one.
695 jump and goto statements expect a target chain name.
697 MATCH
699 { "match": {
700 "left": EXPRESSION,
701 "right": EXPRESSION,
702 "op": STRING
703 }}
704 This matches the expression on left hand side (typically a packet
706 header or packet meta info) with the expression on right hand side
707 (typically a constant value). If the statement evaluates to true, the
708 next statement in this rule is considered. If not, processing continues
709 with the next rule in the same chain.
710 left
712 Left hand side of this match.
713 right
715 Right hand side of this match.
716 op
718 Operator indicating the type of comparison.
719 OPERATORS
721 & Binary AND
722 | Binary OR
724 ^ Binary XOR
726 << Left shift
728 >> Right shift
730 == Equal
732 != Not equal
735 < Less than
737 > Greater than
739 ⇐ Less than or equal to
741 >= Greater than or equal to
743 in Perform a lookup, i.e.
745 test if bits on RHS are
746 contained in LHS value
747 Unlike with the standard API, the operator is mandatory here. In
750 the standard API, a missing operator may be resolved in two ways,
751 depending on the type of expression on the RHS:
752 • If the RHS is a bitmask or a list of bitmasks, the expression
754 resolves into a binary operation with the inequality operator,
755 like this: LHS & RHS != 0.
756 • In any other case, the equality operator is simply inserted.
758 For the non-trivial first case, the JSON API supports the in
760 operator.
761 COUNTER
763 { "counter": {
764 "packets": NUMBER,
765 "bytes": NUMBER
766 }}
767 { "counter": STRING }
769 This object represents a byte/packet counter. In input, no properties
771 are required. If given, they act as initial values for the counter.
772 The first form creates an anonymous counter which lives in the rule it
774 appears in. The second form specifies a reference to a named counter
775 object.
776 packets
778 Packets counted.
779 bytes
781 Bytes counted.
782 MANGLE
784 { "mangle": {
785 "key": EXPRESSION,
786 "value": EXPRESSION
787 }}
788 This changes the packet data or meta info.
790 key
792 The packet data to be changed, given as an exthdr, payload, meta,
793 ct or ct helper expression.
794 value
796 Value to change data to.
797 QUOTA
799 { "quota": {
800 "val": NUMBER,
801 "val_unit": STRING,
802 "used": NUMBER,
803 "used_unit": STRING,
804 "inv": BOOLEAN
805 }}
806 { "quota": STRING }
808 The first form creates an anonymous quota which lives in the rule it
810 appears in. The second form specifies a reference to a named quota
811 object.
812 val
814 Quota value.
815 val_unit
817 Unit of val, e.g. "kbytes" or "mbytes". If omitted, defaults to
818 "bytes".
819 used
821 Quota used so far. Optional on input. If given, serves as initial
822 value.
823 used_unit
825 Unit of used. Defaults to "bytes".
826 inv
828 If true, will match if quota was exceeded. Defaults to false.
829 LIMIT
831 { "limit": {
832 "rate": NUMBER,
833 "rate_unit": STRING,
834 "per": STRING,
835 "burst": NUMBER,
836 "burst_unit": STRING,
837 "inv": BOOLEAN
838 }}
839 { "limit": STRING }
841 The first form creates an anonymous limit which lives in the rule it
843 appears in. The second form specifies a reference to a named limit
844 object.
845 rate
847 Rate value to limit to.
848 rate_unit
850 Unit of rate, e.g. "packets" or "mbytes". Defaults to "packets".
851 per
853 Denominator of rate, e.g. "week" or "minutes".
854 burst
856 Burst value. Defaults to 0.
857 burst_unit
859 Unit of burst, ignored if rate_unit is "packets". Defaults to
860 "bytes".
861 inv
863 If true, matches if the limit was exceeded. Defaults to false.
864 FWD
866 { "fwd": {
867 "dev": EXPRESSION,
868 "family": FWD_FAMILY,
869 "addr": EXPRESSION
870 }}
871 FWD_FAMILY := "ip" | "ip6"
873 Forward a packet to a different destination.
875 dev
877 Interface to forward the packet on.
878 family
880 Family of addr.
881 addr
883 IP(v6) address to forward the packet to.
884 Both family and addr are optional, but if at least one is given, both
886 must be present.
887 NOTRACK
889 { "notrack": null }
890 Disable connection tracking for the packet.
892 DUP
894 { "dup": {
895 "addr": EXPRESSION,
896 "dev": EXPRESSION
897 }}
898 Duplicate a packet to a different destination.
900 addr
902 Address to duplicate packet to.
903 dev
905 Interface to duplicate packet on. May be omitted to not specify an
906 interface explicitly.
907 NETWORK ADDRESS TRANSLATION
909 { "snat": {
910 "addr": EXPRESSION,
911 "family": STRING,
912 "port": EXPRESSION,
913 "flags": FLAGS
914 }}
915 { "dnat": {
917 "addr": EXPRESSION,
918 "family": STRING,
919 "port": EXPRESSION,
920 "flags": FLAGS
921 }}
922 { "masquerade": {
924 "port": EXPRESSION,
925 "flags": FLAGS
926 }}
927 { "redirect": {
929 "port": EXPRESSION,
930 "flags": FLAGS
931 }}
932 FLAGS := FLAG | [ FLAG_LIST ]
934 FLAG_LIST := FLAG [, FLAG_LIST ]
935 FLAG := "random" | "fully-random" | "persistent"
936 Perform Network Address Translation.
938 addr
940 Address to translate to.
941 family
943 Family of addr, either ip or ip6. Required in inet table family.
944 port
946 Port to translate to.
947 flags
949 Flag(s).
950 All properties are optional and default to none.
952 REJECT
954 { "reject": {
955 "type": STRING,
956 "expr": EXPRESSION
957 }}
958 Reject the packet and send the given error reply.
960 type
962 Type of reject, either "tcp reset", "icmpx", "icmp" or "icmpv6".
963 expr
965 ICMP code to reject with.
966 All properties are optional.
968 SET
970 { "set": {
971 "op": STRING,
972 "elem": EXPRESSION,
973 "set": STRING
974 }}
975 Dynamically add/update elements to a set.
977 op
979 Operator on set, either "add" or "update".
980 elem
982 Set element to add or update.
983 set
985 Set reference.
986 LOG
988 { "log": {
989 "prefix": STRING,
990 "group": NUMBER,
991 "snaplen": NUMBER,
992 "queue-threshold": NUMBER,
993 "level": LEVEL,
994 "flags": FLAGS
995 }}
996 LEVEL := "emerg" | "alert" | "crit" | "err" | "warn" | "notice" |
998 "info" | "debug" | "audit"
999 FLAGS := FLAG | [ FLAG_LIST ]
1001 FLAG_LIST := FLAG [, FLAG_LIST ]
1002 FLAG := "tcp sequence" | "tcp options" | "ip options" | "skuid" |
1003 "ether" | "all"
1004 Log the packet.
1006 prefix
1008 Prefix for log entries.
1009 group
1011 Log group.
1012 snaplen
1014 Snaplen for logging.
1015 queue-threshold
1017 Queue threshold.
1018 level
1020 Log level. Defaults to "warn".
1021 flags
1023 Log flags.
1024 All properties are optional.
1026 CT HELPER
1028 { "ct helper": EXPRESSION }
1029 Enable the specified conntrack helper for this packet.
1031 ct helper
1033 CT helper reference.
1034 METER
1036 { "meter": {
1037 "name": STRING,
1038 "key": EXPRESSION,
1039 "stmt": STATEMENT
1040 }}
1041 Apply a given statement using a meter.
1043 name
1045 Meter name.
1046 key
1048 Meter key.
1049 stmt
1051 Meter statement.
1052 QUEUE
1054 { "queue": {
1055 "num": EXPRESSION,
1056 "flags": FLAGS
1057 }}
1058 FLAGS := FLAG | [ FLAG_LIST ]
1060 FLAG_LIST := FLAG [, FLAG_LIST ]
1061 FLAG := "bypass" | "fanout"
1062 Queue the packet to userspace.
1064 num
1066 Queue number.
1067 flags
1069 Queue flags.
1070 VERDICT MAP
1072 { "vmap": {
1073 "key": EXPRESSION,
1074 "data": EXPRESSION
1075 }}
1076 Apply a verdict conditionally.
1078 key
1080 Map key.
1081 data
1083 Mapping expression consisting of value/verdict pairs.
1084 CT COUNT
1086 { "ct count": {
1087 "val": NUMBER,
1088 "inv": BOOLEAN
1089 }}
1090 Limit the number of connections using conntrack.
1092 val
1094 Connection count threshold.
1095 inv
1097 If true, match if val was exceeded. If omitted, defaults to false.
1098 CT TIMEOUT
1100 { "ct timeout": EXPRESSION }
1101 Assign connection tracking timeout policy.
1103 ct timeout
1105 CT timeout reference.
1106 CT EXPECTATION
1108 { "ct expectation": EXPRESSION }
1109 Assign connection tracking expectation.
1111 ct expectation
1113 CT expectation reference.
1114 XT
1116 { "xt": null }
1117 This represents an xt statement from xtables compat interface. Sadly,
1119 at this point, it is not possible to provide any further information
1120 about its content.
1121
1123 Expressions are the building blocks of (most) statements. In their most
1124 basic form, they are just immediate values represented as a JSON
1125 string, integer or boolean type.
1126 IMMEDIATES
1128 STRING
1129 NUMBER
1130 BOOLEAN
1131 Immediate expressions are typically used for constant values. For
1133 strings, there are two special cases:
1134 @STRING
1136 The remaining part is taken as set name to create a set reference.
1137 \*
1139 Construct a wildcard expression.
1140 LISTS
1142 ARRAY
1143 List expressions are constructed by plain arrays containing of an
1145 arbitrary number of expressions.
1146 CONCAT
1148 { "concat": CONCAT }
1149 CONCAT := [ EXPRESSION_LIST ]
1151 EXPRESSION_LIST := EXPRESSION [, EXPRESSION_LIST ]
1152 Concatenate several expressions.
1154 SET
1156 { "set": SET }
1157 SET := EXPRESSION | [ EXPRESSION_LIST ]
1159 This object constructs an anonymous set. For mappings, an array of
1161 arrays with exactly two elements is expected.
1162 MAP
1164 { "map": {
1165 "key": EXPRESSION,
1166 "data": EXPRESSION
1167 }}
1168 Map a key to a value.
1170 key
1172 Map key.
1173 data
1175 Mapping expression consisting of value/target pairs.
1176 PREFIX
1178 { "prefix": {
1179 "addr": EXPRESSION,
1180 "len": NUMBER
1181 }}
1182 Construct an IPv4 or IPv6 prefix consisting of address part in addr and
1184 prefix length in len.
1185 RANGE
1187 { "range": [ EXPRESSION , EXPRESSION ] }
1188 Construct a range of values. The first array item denotes the lower
1190 boundary, the second one the upper boundary.
1191 PAYLOAD
1193 { "payload": {
1194 "base": BASE,
1195 "offset": NUMBER,
1196 "len": NUMBER
1197 }}
1198 { "payload": {
1200 "protocol": STRING,
1201 "field": STRING
1202 }}
1203 BASE := "ll" | "nh" | "th"
1205 Construct a payload expression, i.e. a reference to a certain part of
1207 packet data. The first form creates a raw payload expression to point
1208 at a random number (len) of bytes at a certain offset (offset) from a
1209 given reference point (base). The following base values are accepted:
1210 "ll"
1212 The offset is relative to Link Layer header start offset.
1213 "nh"
1215 The offset is relative to Network Layer header start offset.
1216 "th"
1218 The offset is relative to Transport Layer header start offset.
1219 The second form allows to reference a field by name (field) in a named
1221 packet header (protocol).
1222 EXTHDR
1224 { "exthdr": {
1225 "name": STRING,
1226 "field": STRING,
1227 "offset": NUMBER
1228 }}
1229 Create a reference to a field (field) in an IPv6 extension header
1231 (name). offset is used only for rt0 protocol.
1232 If the field property is not given, the expression is to be used as a
1234 header existence check in a match statement with a boolean on the right
1235 hand side.
1236 TCP OPTION
1238 { "tcp option": {
1239 "name": STRING,
1240 "field": STRING
1241 }}
1242 Create a reference to a field (field) of a TCP option header (name).
1244 If the field property is not given, the expression is to be used as a
1246 TCP option existence check in a match statement with a boolean on the
1247 right hand side.
1248 SCTP CHUNK
1250 { "sctp chunk": {
1251 "name": STRING,
1252 "field": STRING
1253 }}
1254 Create a reference to a field (field) of an SCTP chunk (name).
1256 If the field property is not given, the expression is to be used as an
1258 SCTP chunk existence check in a match statement with a boolean on the
1259 right hand side.
1260 META
1262 { "meta": {
1263 "key": META_KEY
1264 }}
1265 META_KEY := "length" | "protocol" | "priority" | "random" | "mark" |
1267 "iif" | "iifname" | "iiftype" | "oif" | "oifname" |
1268 "oiftype" | "skuid" | "skgid" | "nftrace" |
1269 "rtclassid" | "ibriport" | "obriport" | "ibridgename" |
1270 "obridgename" | "pkttype" | "cpu" | "iifgroup" |
1271 "oifgroup" | "cgroup" | "nfproto" | "l4proto" |
1272 "secpath"
1273 Create a reference to packet meta data.
1275 RT
1277 { "rt": {
1278 "key": RT_KEY,
1279 "family": RT_FAMILY
1280 }}
1281 RT_KEY := "classid" | "nexthop" | "mtu"
1283 RT_FAMILY := "ip" | "ip6"
1284 Create a reference to packet routing data.
1286 The family property is optional and defaults to unspecified.
1288 CT
1290 { "ct": {
1291 "key": STRING,
1292 "family": CT_FAMILY,
1293 "dir": CT_DIRECTION
1294 }}
1295 CT_FAMILY := "ip" | "ip6"
1297 CT_DIRECTION := "original" | "reply"
1298 Create a reference to packet conntrack data.
1300 Some CT keys do not support a direction. In this case, dir must not be
1302 given.
1303 NUMGEN
1305 { "numgen": {
1306 "mode": NG_MODE,
1307 "mod": NUMBER,
1308 "offset": NUMBER
1309 }}
1310 NG_MODE := "inc" | "random"
1312 Create a number generator.
1314 The offset property is optional and defaults to 0.
1316 HASH
1318 { "jhash": {
1319 "mod": NUMBER,
1320 "offset": NUMBER,
1321 "expr": EXPRESSION,
1322 "seed": NUMBER
1323 }}
1324 { "symhash": {
1326 "mod": NUMBER,
1327 "offset": NUMBER
1328 }}
1329 Hash packet data.
1331 The offset and seed properties are optional and default to 0.
1333 FIB
1335 { "fib": {
1336 "result": FIB_RESULT,
1337 "flags": FIB_FLAGS
1338 }}
1339 FIB_RESULT := "oif" | "oifname" | "type"
1341 FIB_FLAGS := FIB_FLAG | [ FIB_FLAG_LIST ]
1343 FIB_FLAG_LIST := FIB_FLAG [, FIB_FLAG_LIST ]
1344 FIB_FLAG := "saddr" | "daddr" | "mark" | "iif" | "oif"
1345 Perform kernel Forwarding Information Base lookups.
1347 BINARY OPERATION
1349 { "|": [ EXPRESSION, EXPRESSION ] }
1350 { "^": [ EXPRESSION, EXPRESSION ] }
1351 { "&": [ EXPRESSION, EXPRESSION ] }
1352 { "<<": [ EXPRESSION, EXPRESSION ] }
1353 { ">>": [ EXPRESSION, EXPRESSION ] }
1354 All binary operations expect an array of exactly two expressions, of
1356 which the first element denotes the left hand side and the second one
1357 the right hand side.
1358 VERDICT
1360 { "accept": null }
1361 { "drop": null }
1362 { "continue": null }
1363 { "return": null }
1364 { "jump": { "target": STRING }}
1365 { "goto": { "target": STRING }}
1366 Same as the verdict statement, but for use in verdict maps.
1368 jump and goto verdicts expect a target chain name.
1370 ELEM
1372 { "elem": {
1373 "val": EXPRESSION,
1374 "timeout": NUMBER,
1375 "expires": NUMBER,
1376 "comment": STRING
1377 }}
1378 Explicitly set element object, in case timeout, expires or comment are
1380 desired. Otherwise, it may be replaced by the value of val.
1381 SOCKET
1383 { "socket": {
1384 "key": SOCKET_KEY
1385 }}
1386 SOCKET_KEY := "transparent"
1388 Construct a reference to packet’s socket.
1390 OSF
1392 { "osf": {
1393 "key": OSF_KEY,
1394 "ttl": OSF_TTL
1395 }}
1396 OSF_KEY := "name"
1398 OSF_TTL := "loose" | "skip"
1399 Perform OS fingerprinting. This expression is typically used in the LHS
1401 of a match statement.
1402 key
1404 Which part of the fingerprint info to match against. At this point,
1405 only the OS name is supported.
1406 ttl
1408 Define how the packet’s TTL value is to be matched. This property
1409 is optional. If omitted, the TTL value has to match exactly. A
1410 value of loose accepts TTL values less than the fingerprint one. A
1411 value of skip omits TTL value comparison entirely.
1412
1414 Phil Sutter <phil@nwl.cc>
1415 Author.
1416 08/19/2021 LIBNFTABLES-JSON(5)