{ "content": [ { "type": "text", "text": "# libnftables-json (man)\n\n## NAME\n\nlibnftables-json - Supported JSON schema by libnftables\n\n## SYNOPSIS\n\n{ \"nftables\": [ OBJECTS ] }\nOBJECTS := LISTOBJECTS | CMDOBJECTS\nLISTOBJECTS := LISTOBJECT [ , LISTOBJECTS ]\nCMDOBJECTS := CMDOBJECT [ , CMDOBJECTS ]\nCMDOBJECT := { CMD: LISTOBJECT } | METAINFOOBJECT\nCMD := \"add\" | \"replace\" | \"create\" | \"insert\" | \"delete\" | \"list\" | \"reset\" | \"flush\" |\n\n## DESCRIPTION\n\nlibnftables supports JSON formatted input and output. This is implemented as an alternative\nfrontend to the standard CLI syntax parser, therefore basic behaviour is identical and, for\n(almost) any operation available in standard syntax, there should be an equivalent one in\nJSON.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS** (1 subsections)\n- **DESCRIPTION**\n- **GLOBAL STRUCTURE**\n- **METAINFO OBJECT**\n- **COMMAND OBJECTS**\n- **RULESET ELEMENTS** (89 subsections)\n- **STATEMENTS** (44 subsections)\n- **EXPRESSIONS** (8 subsections)\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "libnftables-json", "section": "", "mode": "man", "summary": "libnftables-json - Supported JSON schema by libnftables", "synopsis": "{ \"nftables\": [ OBJECTS ] }\nOBJECTS := LISTOBJECTS | CMDOBJECTS\nLISTOBJECTS := LISTOBJECT [ , LISTOBJECTS ]\nCMDOBJECTS := CMDOBJECT [ , CMDOBJECTS ]\nCMDOBJECT := { CMD: LISTOBJECT } | METAINFOOBJECT\nCMD := \"add\" | \"replace\" | \"create\" | \"insert\" | \"delete\" | \"list\" | \"reset\" | \"flush\" |", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 11, "subsections": [ { "name": "\"rename\"", "lines": 3 } ] }, { "name": "DESCRIPTION", "lines": 11, "subsections": [] }, { "name": "GLOBAL STRUCTURE", "lines": 8, "subsections": [] }, { "name": "METAINFO OBJECT", "lines": 18, "subsections": [] }, { "name": "COMMAND OBJECTS", "lines": 105, "subsections": [] }, { "name": "RULESET ELEMENTS", "lines": 9, "subsections": [ { "name": "family", "lines": 2 }, { "name": "name", "lines": 2 }, { "name": "handle", "lines": 18 }, { "name": "family", "lines": 2 }, { "name": "table", "lines": 2 }, { "name": "name", "lines": 2 }, { "name": "handle", "lines": 2 }, { "name": "newname", "lines": 4 }, { "name": "type", "lines": 2 }, { "name": "hook", "lines": 2 }, { "name": "prio", "lines": 2 }, { "name": "dev", "lines": 2 }, { "name": "policy", "lines": 18 }, { "name": "family", "lines": 2 }, { "name": "table", "lines": 2 }, { "name": "chain", "lines": 2 }, { "name": "expr", "lines": 3 }, { "name": "handle", "lines": 4 }, { "name": "index", "lines": 2 }, { "name": "comment", "lines": 43 }, { "name": "family", "lines": 2 }, { "name": "table", "lines": 2 }, { "name": "name", "lines": 2 }, { "name": "handle", "lines": 2 }, { "name": "type", "lines": 2 }, { "name": "map", "lines": 2 }, { "name": "policy", "lines": 2 }, { "name": "flags", "lines": 2 }, { "name": "elem", "lines": 2 }, { "name": "timeout", "lines": 2 }, { "name": "gc-interval", "lines": 2 }, { "name": "size", "lines": 25 }, { "name": "family", "lines": 2 }, { "name": "table", "lines": 2 }, { "name": "name", "lines": 2 }, { "name": "elem", "lines": 18 }, { "name": "family", "lines": 2 }, { "name": "table", "lines": 2 }, { "name": "name", "lines": 2 }, { "name": "handle", "lines": 2 }, { "name": "hook", "lines": 2 }, { "name": "prio", "lines": 2 }, { "name": "dev", "lines": 14 }, { "name": "family", "lines": 2 }, { "name": "table", "lines": 2 }, { "name": "name", "lines": 2 }, { "name": "handle", "lines": 2 }, { "name": "packets", "lines": 2 }, { "name": "bytes", "lines": 15 }, { "name": "family", "lines": 2 }, { "name": "table", "lines": 2 }, { "name": "name", "lines": 2 }, { "name": "handle", "lines": 2 }, { "name": "bytes", "lines": 2 }, { "name": "used", "lines": 2 }, { "name": "inv", "lines": 17 }, { "name": "family", "lines": 2 }, { "name": "table", "lines": 2 }, { "name": "name", "lines": 2 }, { "name": "handle", "lines": 2 }, { "name": "type", "lines": 2 }, { "name": "protocol", "lines": 2 }, { "name": "l3proto", "lines": 19 }, { "name": "family", "lines": 2 }, { "name": "table", "lines": 2 }, { "name": "name", "lines": 2 }, { "name": "handle", "lines": 2 }, { "name": "rate", "lines": 2 }, { "name": "per", "lines": 3 }, { "name": "burst", "lines": 2 }, { "name": "unit", "lines": 2 }, { "name": "inv", "lines": 18 }, { "name": "family", "lines": 2 }, { "name": "table", "lines": 2 }, { "name": "name", "lines": 2 }, { "name": "handle", "lines": 2 }, { "name": "protocol", "lines": 2 }, { "name": "state", "lines": 3 }, { "name": "value", "lines": 2 }, { "name": "l3proto", "lines": 19 }, { "name": "family", "lines": 2 }, { "name": "table", "lines": 2 }, { "name": "name", "lines": 2 }, { "name": "handle", "lines": 2 }, { "name": "l3proto", "lines": 2 }, { "name": "protocol", "lines": 2 }, { "name": "dport", "lines": 2 }, { "name": "timeout", "lines": 2 }, { "name": "size", "lines": 2 } ] }, { "name": "STATEMENTS", "lines": 27, "subsections": [ { "name": "left", "lines": 2 }, { "name": "right", "lines": 58 }, { "name": "packets", "lines": 2 }, { "name": "bytes", "lines": 10 }, { "name": "key", "lines": 3 }, { "name": "value", "lines": 16 }, { "name": "val", "lines": 5 }, { "name": "used", "lines": 5 }, { "name": "inv", "lines": 17 }, { "name": "rate", "lines": 5 }, { "name": "per", "lines": 2 }, { "name": "burst", "lines": 5 }, { "name": "inv", "lines": 13 }, { "name": "dev", "lines": 2 }, { "name": "family", "lines": 2 }, { "name": "addr", "lines": 17 }, { "name": "addr", "lines": 2 }, { "name": "dev", "lines": 33 }, { "name": "addr", "lines": 2 }, { "name": "family", "lines": 2 }, { "name": "port", "lines": 2 }, { "name": "flags", "lines": 12 }, { "name": "type", "lines": 2 }, { "name": "expr", "lines": 16 }, { "name": "elem", "lines": 2 }, { "name": "set", "lines": 22 }, { "name": "prefix", "lines": 2 }, { "name": "group", "lines": 2 }, { "name": "snaplen", "lines": 2 }, { "name": "queue-threshold", "lines": 2 }, { "name": "level", "lines": 2 }, { "name": "flags", "lines": 9 }, { "name": "ct helper", "lines": 11 }, { "name": "name", "lines": 2 }, { "name": "key", "lines": 2 }, { "name": "stmt", "lines": 14 }, { "name": "num", "lines": 2 }, { "name": "flags", "lines": 10 }, { "name": "key", "lines": 2 }, { "name": "data", "lines": 10 }, { "name": "val", "lines": 2 }, { "name": "inv", "lines": 7 }, { "name": "ct timeout", "lines": 7 }, { "name": "ct expectation", "lines": 8 } ] }, { "name": "EXPRESSIONS", "lines": 11, "subsections": [ { "name": "@STRING", "lines": 35 }, { "name": "key", "lines": 2 }, { "name": "data", "lines": 34 }, { "name": "\"ll\"", "lines": 2 }, { "name": "\"nh\"", "lines": 2 }, { "name": "\"th\"", "lines": 179 }, { "name": "key", "lines": 3 }, { "name": "ttl", "lines": 4 } ] }, { "name": "AUTHOR", "lines": 6, "subsections": [] } ], "sections": { "NAME": { "content": "libnftables-json - Supported JSON schema by libnftables\n", "subsections": [] }, "SYNOPSIS": { "content": "{ \"nftables\": [ OBJECTS ] }\n\nOBJECTS := LISTOBJECTS | CMDOBJECTS\n\nLISTOBJECTS := LISTOBJECT [ , LISTOBJECTS ]\n\nCMDOBJECTS := CMDOBJECT [ , CMDOBJECTS ]\n\nCMDOBJECT := { CMD: LISTOBJECT } | METAINFOOBJECT\n\nCMD := \"add\" | \"replace\" | \"create\" | \"insert\" | \"delete\" | \"list\" | \"reset\" | \"flush\" |", "subsections": [ { "name": "\"rename\"", "content": "LISTOBJECT := TABLE | CHAIN | RULE | SET | MAP | ELEMENT | FLOWTABLE | COUNTER | QUOTA |\nCTHELPER | LIMIT | METAINFOOBJECT | CTTIMEOUT | CTEXPECTATION\n" } ] }, "DESCRIPTION": { "content": "libnftables supports JSON formatted input and output. This is implemented as an alternative\nfrontend to the standard CLI syntax parser, therefore basic behaviour is identical and, for\n(almost) any operation available in standard syntax, there should be an equivalent one in\nJSON.\n\nJSON input may be provided in a single string as parameter to nftruncmdfrombuffer() or in\na file identified by the filename parameter of the nftruncmdfromfilename() function.\n\nJSON output has to be enabled via the nftctxoutputsetjson() function, turning library\nstandard output into JSON format. Error output remains unaffected.\n", "subsections": [] }, "GLOBAL STRUCTURE": { "content": "In general, any JSON input or output is enclosed in an object with a single property named\nnftables. Its value is an array containing commands (for input) or ruleset elements (for\noutput).\n\nA command is an object with a single property whose name identifies the command. Its value is\na ruleset element - basically identical to output elements, apart from certain properties\nwhich may be interpreted differently or are required when output generally omits them.\n", "subsections": [] }, "METAINFO OBJECT": { "content": "In output, the first object in an nftables array is a special one containing library\ninformation. Its content is as follows:\n\n{ \"metainfo\": {\n\"version\": STRING,\n\"releasename\": STRING,\n\"jsonschemaversion\": NUMBER\n}}\n\nThe values of version and releasename properties are equal to the package version and\nrelease name as printed by nft -v. The value of the jsonschemaversion property is an\ninteger indicating the schema version.\n\nIf supplied in library input, the parser will verify the jsonschemaversion value to not\nexceed the internally hardcoded one (to make sure the given schema is fully understood). In\nfuture, a lower number than the internal one may activate compatibility mode to parse\noutdated and incompatible JSON input.\n", "subsections": [] }, "COMMAND OBJECTS": { "content": "The structure accepts an arbitrary amount of commands which are interpreted in order of\nappearance. For instance, the following standard syntax input:\n\nflush ruleset\nadd table inet mytable\nadd chain inet mytable mychain\nadd rule inet mytable mychain tcp dport 22 accept\n\ntranslates into JSON as such:\n\n{ \"nftables\": [\n{ \"flush\": { \"ruleset\": null }},\n{ \"add\": { \"table\": {\n\"family\": \"inet\",\n\"name\": \"mytable\"\n}}},\n{ \"add\": { \"chain\": {\n\"family\": \"inet\",\n\"table\": \"mytable\",\n\"name\": \"mychain\"\n}}},\n{ \"add\": { \"rule\": {\n\"family\": \"inet\",\n\"table\": \"mytable\",\n\"chain\": \"mychain\",\n\"expr\": [\n{ \"match\": {\n\"op\": \"==\",\n\"left\": { \"payload\": {\n\"protocol\": \"tcp\",\n\"field\": \"dport\"\n}},\n\"right\": 22\n}},\n{ \"accept\": null }\n]\n}}}\n]}\n\nADD\n{ \"add\": ADDOBJECT }\n\nADDOBJECT := TABLE | CHAIN | RULE | SET | MAP | ELEMENT |\nFLOWTABLE | COUNTER | QUOTA | CTHELPER | LIMIT |\nCTTIMEOUT | CTEXPECTATION\n\nAdd a new ruleset element to the kernel.\n\nREPLACE\n{ \"replace\": RULE }\n\nReplace a rule. In RULE, the handle property is mandatory and identifies the rule to be\nreplaced.\n\nCREATE\n{ \"create\": ADDOBJECT }\n\nIdentical to add command, but returns an error if the object already exists.\n\nINSERT\n{ \"insert\": RULE }\n\nThis command is identical to add for rules, but instead of appending the rule to the chain by\ndefault, it inserts at first position. If a handle or index property is given, the rule is\ninserted before the rule identified by those properties.\n\nDELETE\n{ \"delete\": ADDOBJECT }\n\nDelete an object from the ruleset. Only the minimal number of properties required to uniquely\nidentify an object is generally needed in ADDOBJECT. For most ruleset elements, this is\nfamily and table plus either handle or name (except rules since they don’t have a name).\n\nLIST\n{ \"list\": LISTOBJECT }\n\nLISTOBJECT := TABLE | TABLES | CHAIN | CHAINS | SET | SETS |\nMAP | MAPS | COUNTER | COUNTERS | QUOTA | QUOTAS |\nCTHELPER | CTHELPERS | LIMIT | LIMITS | RULESET |\nMETER | METERS | FLOWTABLE | FLOWTABLES |\nCTTIMEOUT | CTEXPECTATION\n\nList ruleset elements. The plural forms are used to list all objects of that kind, optionally\nfiltered by family and for some, also table.\n\nRESET\n{ \"reset\": RESETOBJECT }\n\nRESETOBJECT := COUNTER | COUNTERS | QUOTA | QUOTAS\n\nReset state in suitable objects, i.e. zero their internal counter.\n\nFLUSH\n{ \"flush\": FLUSHOBJECT }\n\nFLUSHOBJECT := TABLE | CHAIN | SET | MAP | METER | RULESET\n\nEmpty contents in given object, e.g. remove all chains from given table or remove all\nelements from given set.\n\nRENAME\n{ \"rename\": CHAIN }\n\nRename a chain. The new name is expected in a dedicated property named newname.\n", "subsections": [] }, "RULESET ELEMENTS": { "content": "TABLE\n{ \"table\": {\n\"family\": STRING,\n\"name\": STRING,\n\"handle\": NUMBER\n}}\n\nThis object describes a table.\n", "subsections": [ { "name": "family", "content": "The table’s family, e.g. \"ip\" or \"ip6\".\n" }, { "name": "name", "content": "The table’s name.\n" }, { "name": "handle", "content": "The table’s handle. In input, it is used only in delete command as alternative to name.\n\nCHAIN\n{ \"chain\": {\n\"family\": STRING,\n\"table\": STRING,\n\"name\": STRING,\n\"newname\": STRING,\n\"handle\": NUMBER,\n\"type\": STRING,\n\"hook\": STRING,\n\"prio\": NUMBER,\n\"dev\": STRING,\n\"policy\": STRING\n}}\n\nThis object describes a chain.\n" }, { "name": "family", "content": "The table’s family.\n" }, { "name": "table", "content": "The table’s name.\n" }, { "name": "name", "content": "The chain’s name.\n" }, { "name": "handle", "content": "The chain’s handle. In input, it is used only in delete command as alternative to name.\n" }, { "name": "newname", "content": "A new name for the chain, only relevant in the rename command.\n\nThe following properties are required for base chains:\n" }, { "name": "type", "content": "The chain’s type.\n" }, { "name": "hook", "content": "The chain’s hook.\n" }, { "name": "prio", "content": "The chain’s priority.\n" }, { "name": "dev", "content": "The chain’s bound interface (if in the netdev family).\n" }, { "name": "policy", "content": "The chain’s policy.\n\nRULE\n{ \"rule\": {\n\"family\": STRING,\n\"table\": STRING,\n\"chain\": STRING,\n\"expr\": [ STATEMENTS ],\n\"handle\": NUMBER,\n\"index\": NUMBER,\n\"comment\": STRING\n}}\n\nSTATEMENTS := STATEMENT [, STATEMENTS ]\n\nThis object describes a rule. Basic building blocks of rules are statements. Each rule\nconsists of at least one.\n" }, { "name": "family", "content": "The table’s family.\n" }, { "name": "table", "content": "The table’s name.\n" }, { "name": "chain", "content": "The chain’s name.\n" }, { "name": "expr", "content": "An array of statements this rule consists of. In input, it is used in add/insert/replace\ncommands only.\n" }, { "name": "handle", "content": "The rule’s handle. In delete/replace commands, it serves as an identifier of the rule to\ndelete/replace. In add/insert commands, it serves as an identifier of an existing rule to\nappend/prepend the rule to.\n" }, { "name": "index", "content": "The rule’s position for add/insert commands. It is used as an alternative to handle then.\n" }, { "name": "comment", "content": "Optional rule comment.\n\nSET / MAP\n{ \"set\": {\n\"family\": STRING,\n\"table\": STRING,\n\"name\": STRING,\n\"handle\": NUMBER,\n\"type\": SETTYPE,\n\"policy\": SETPOLICY,\n\"flags\": [ SETFLAGLIST ],\n\"elem\": SETELEMENTS,\n\"timeout\": NUMBER,\n\"gc-interval\": NUMBER,\n\"size\": NUMBER\n}}\n\n{ \"map\": {\n\"family\": STRING,\n\"table\": STRING,\n\"name\": STRING,\n\"handle\": NUMBER,\n\"type\": SETTYPE,\n\"map\": STRING,\n\"policy\": SETPOLICY,\n\"flags\": [ SETFLAGLIST ],\n\"elem\": SETELEMENTS,\n\"timeout\": NUMBER,\n\"gc-interval\": NUMBER,\n\"size\": NUMBER\n}}\n\nSETTYPE := STRING | [ SETTYPELIST ]\nSETTYPELIST := STRING [, SETTYPELIST ]\nSETPOLICY := \"performance\" | \"memory\"\nSETFLAGLIST := SETFLAG [, SETFLAGLIST ]\nSETFLAG := \"constant\" | \"interval\" | \"timeout\"\nSETELEMENTS := EXPRESSION | [ EXPRESSIONLIST ]\nEXPRESSIONLIST := EXPRESSION [, EXPRESSIONLIST ]\n\nThese objects describe a named set or map. Maps are a special form of sets in that they\ntranslate a unique key to a value.\n" }, { "name": "family", "content": "The table’s family.\n" }, { "name": "table", "content": "The table’s name.\n" }, { "name": "name", "content": "The set’s name.\n" }, { "name": "handle", "content": "The set’s handle. For input, it is used in the delete command only.\n" }, { "name": "type", "content": "The set’s datatype, see below.\n" }, { "name": "map", "content": "Type of values this set maps to (i.e. this set is a map).\n" }, { "name": "policy", "content": "The set’s policy.\n" }, { "name": "flags", "content": "The set’s flags.\n" }, { "name": "elem", "content": "Initial set element(s), see below.\n" }, { "name": "timeout", "content": "Element timeout in seconds.\n" }, { "name": "gc-interval", "content": "Garbage collector interval in seconds.\n" }, { "name": "size", "content": "Maximum number of elements supported.\n\nTYPE\nThe set type might be a string, such as \"ipv4addr\" or an array consisting of strings\n(for concatenated types).\n\nELEM\nA single set element might be given as string, integer or boolean value for simple cases.\nIf additional properties are required, a formal elem object may be used.\n\nMultiple elements may be given in an array.\n\nELEMENT\n{ \"element\": {\n\"family\": STRING,\n\"table\": STRING,\n\"name\": STRING,\n\"elem\": SETELEM\n}}\n\nSETELEM := EXPRESSION | [ EXPRESSIONLIST ]\nEXPRESSIONLIST := EXPRESSION [, EXPRESSION ]\n\nManipulate element(s) in a named set.\n" }, { "name": "family", "content": "The table’s family.\n" }, { "name": "table", "content": "The table’s name.\n" }, { "name": "name", "content": "The set’s name.\n" }, { "name": "elem", "content": "See elem property of set object.\n\nFLOWTABLE\n{ \"flowtable\": {\n\"family\": STRING,\n\"table\": STRING,\n\"name\": STRING,\n\"handle\": NUMBER,\n\"hook\": STRING,\n\"prio\": NUMBER,\n\"dev\": FTINTERFACE\n}}\n\nFTINTERFACE := STRING | [ FTINTERFACELIST ]\nFTINTERFACELIST := STRING [, STRING ]\n\nThis object represents a named flowtable.\n" }, { "name": "family", "content": "The table’s family.\n" }, { "name": "table", "content": "The table’s name.\n" }, { "name": "name", "content": "The flow table’s name.\n" }, { "name": "handle", "content": "The flow table’s handle. In input, it is used by the delete command only.\n" }, { "name": "hook", "content": "The flow table’s hook.\n" }, { "name": "prio", "content": "The flow table’s priority.\n" }, { "name": "dev", "content": "The flow table’s interface(s).\n\nCOUNTER\n{ \"counter\": {\n\"family\": STRING,\n\"table\": STRING,\n\"name\": STRING,\n\"handle\": NUMBER,\n\"packets\": NUMBER,\n\"bytes\": NUMBER\n}}\n\nThis object represents a named counter.\n" }, { "name": "family", "content": "The table’s family.\n" }, { "name": "table", "content": "The table’s name.\n" }, { "name": "name", "content": "The counter’s name.\n" }, { "name": "handle", "content": "The counter’s handle. In input, it is used by the delete command only.\n" }, { "name": "packets", "content": "Packet counter value.\n" }, { "name": "bytes", "content": "Byte counter value.\n\nQUOTA\n{ \"quota\": {\n\"family\": STRING,\n\"table\": STRING,\n\"name\": STRING,\n\"handle\": NUMBER,\n\"bytes\": NUMBER,\n\"used\": NUMBER,\n\"inv\": BOOLEAN\n}}\n\nThis object represents a named quota.\n" }, { "name": "family", "content": "The table’s family.\n" }, { "name": "table", "content": "The table’s name.\n" }, { "name": "name", "content": "The quota’s name.\n" }, { "name": "handle", "content": "The quota’s handle. In input, it is used by the delete command only.\n" }, { "name": "bytes", "content": "Quota threshold.\n" }, { "name": "used", "content": "Quota used so far.\n" }, { "name": "inv", "content": "If true, match if the quota has been exceeded.\n\nCT HELPER\n{ \"ct helper\": {\n\"family\": STRING,\n\"table\": STRING,\n\"name\": STRING,\n\"handle\": ... ',\n\"type\": 'STRING,\n\"protocol\": CTHPROTO,\n\"l3proto\": STRING\n}}\n\nCTHPROTO := \"tcp\" | \"udp\"\n\nThis object represents a named conntrack helper.\n" }, { "name": "family", "content": "The table’s family.\n" }, { "name": "table", "content": "The table’s name.\n" }, { "name": "name", "content": "The ct helper’s name.\n" }, { "name": "handle", "content": "The ct helper’s handle. In input, it is used by the delete command only.\n" }, { "name": "type", "content": "The ct helper type name, e.g. \"ftp\" or \"tftp\".\n" }, { "name": "protocol", "content": "The ct helper’s layer 4 protocol.\n" }, { "name": "l3proto", "content": "The ct helper’s layer 3 protocol, e.g. \"ip\" or \"ip6\".\n\nLIMIT\n{ \"limit\": {\n\"family\": STRING,\n\"table\": STRING,\n\"name\": STRING,\n\"handle\": NUMBER,\n\"rate\": NUMBER,\n\"per\": STRING,\n\"burst\": NUMBER,\n\"unit\": LIMITUNIT,\n\"inv\": BOOLEAN\n}}\n\nLIMITUNIT := \"packets\" | \"bytes\"\n\nThis object represents a named limit.\n" }, { "name": "family", "content": "The table’s family.\n" }, { "name": "table", "content": "The table’s name.\n" }, { "name": "name", "content": "The limit’s name.\n" }, { "name": "handle", "content": "The limit’s handle. In input, it is used by the delete command only.\n" }, { "name": "rate", "content": "The limit’s rate value.\n" }, { "name": "per", "content": "Time unit to apply the limit to, e.g. \"week\", \"day\", \"hour\", etc. If omitted, defaults\nto \"second\".\n" }, { "name": "burst", "content": "The limit’s burst value. If omitted, defaults to 0.\n" }, { "name": "unit", "content": "Unit of rate and burst values. If omitted, defaults to \"packets\".\n" }, { "name": "inv", "content": "If true, match if limit was exceeded. If omitted, defaults to false.\n\nCT TIMEOUT\n{ \"ct timeout\": {\n\"family\": STRING,\n\"table\": STRING,\n\"name\": STRING,\n\"handle\": NUMBER,\n\"protocol\": CTHPROTO,\n\"state\": STRING,\n\"value: NUMBER,\n\"l3proto\": STRING\n}}\n\nCTHPROTO := \"tcp\" | \"udp\" | \"dccp\" | \"sctp\" | \"gre\" | \"icmpv6\" | \"icmp\" | \"generic\"\n\nThis object represents a named conntrack timeout policy.\n" }, { "name": "family", "content": "The table’s family.\n" }, { "name": "table", "content": "The table’s name.\n" }, { "name": "name", "content": "The ct timeout object’s name.\n" }, { "name": "handle", "content": "The ct timeout object’s handle. In input, it is used by delete command only.\n" }, { "name": "protocol", "content": "The ct timeout object’s layer 4 protocol.\n" }, { "name": "state", "content": "The connection state name, e.g. \"established\", \"synsent\", \"close\" or \"closewait\", for\nwhich the timeout value has to be updated.\n" }, { "name": "value", "content": "The updated timeout value for the specified connection state.\n" }, { "name": "l3proto", "content": "The ct timeout object’s layer 3 protocol, e.g. \"ip\" or \"ip6\".\n\nCT EXPECTATION\n{ \"ct expectation\": {\n\"family\": STRING,\n\"table\": STRING,\n\"name\": STRING,\n\"handle\": NUMBER,\n\"l3proto\": STRING\n\"protocol\":* CTHPROTO,\n\"dport\": NUMBER,\n\"timeout: NUMBER,\n\"size: NUMBER,\n*}}\n\nCTHPROTO := \"tcp\" | \"udp\" | \"dccp\" | \"sctp\" | \"gre\" | \"icmpv6\" | \"icmp\" | \"generic\"\n\nThis object represents a named conntrack expectation.\n" }, { "name": "family", "content": "The table’s family.\n" }, { "name": "table", "content": "The table’s name.\n" }, { "name": "name", "content": "The ct expectation object’s name.\n" }, { "name": "handle", "content": "The ct expectation object’s handle. In input, it is used by delete command only.\n" }, { "name": "l3proto", "content": "The ct expectation object’s layer 3 protocol, e.g. \"ip\" or \"ip6\".\n" }, { "name": "protocol", "content": "The ct expectation object’s layer 4 protocol.\n" }, { "name": "dport", "content": "The destination port of the expected connection.\n" }, { "name": "timeout", "content": "The time in millisecond that this expectation will live.\n" }, { "name": "size", "content": "The maximum count of expectations to be living in the same time.\n" } ] }, "STATEMENTS": { "content": "Statements are the building blocks for rules. Each rule consists of at least one.\n\nVERDICT\n{ \"accept\": null }\n{ \"drop\": null }\n{ \"continue\": null }\n{ \"return\": null }\n{ \"jump\": { \"target\": * STRING *}}\n{ \"goto\": { \"target\": * STRING *}}\n\nA verdict either terminates packet traversal through the current chain or delegates to a\ndifferent one.\n\njump and goto statements expect a target chain name.\n\nMATCH\n{ \"match\": {\n\"left\": EXPRESSION,\n\"right\": EXPRESSION,\n\"op\": STRING\n}}\n\nThis matches the expression on left hand side (typically a packet header or packet meta info)\nwith the expression on right hand side (typically a constant value). If the statement\nevaluates to true, the next statement in this rule is considered. If not, processing\ncontinues with the next rule in the same chain.\n", "subsections": [ { "name": "left", "content": "Left hand side of this match.\n" }, { "name": "right", "content": "Right hand side of this match.\n\nop\nOperator indicating the type of comparison.\n\nOPERATORS\n& Binary AND\n\n| Binary OR\n\n^ Binary XOR\n\n<< Left shift\n\n>> Right shift\n\n== Equal\n\n!= Not equal\n\n< Less than\n\n> Greater than\n\n⇐⇐ Less than or equal to\n\n>= Greater than or equal to\n\nin Perform a lookup, i.e. test if\nbits on RHS are contained in LHS\nvalue\n\n\nUnlike with the standard API, the operator is mandatory here. In the standard API, a\nmissing operator may be resolved in two ways, depending on the type of expression on the\nRHS:\n\n• If the RHS is a bitmask or a list of bitmasks, the expression resolves into a binary\noperation with the inequality operator, like this: LHS & RHS != 0.\n\n• In any other case, the equality operator is simply inserted.\n\nFor the non-trivial first case, the JSON API supports the in operator.\n\nCOUNTER\n{ \"counter\": {\n\"packets\": NUMBER,\n\"bytes\": NUMBER\n}}\n\n{ \"counter\": STRING }\n\nThis object represents a byte/packet counter. In input, no properties are required. If given,\nthey act as initial values for the counter.\n\nThe first form creates an anonymous counter which lives in the rule it appears in. The second\nform specifies a reference to a named counter object.\n" }, { "name": "packets", "content": "Packets counted.\n" }, { "name": "bytes", "content": "Bytes counted.\n\nMANGLE\n{ \"mangle\": {\n\"key\": EXPRESSION,\n\"value\": EXPRESSION\n}}\n\nThis changes the packet data or meta info.\n" }, { "name": "key", "content": "The packet data to be changed, given as an exthdr, payload, meta, ct or ct helper\nexpression.\n" }, { "name": "value", "content": "Value to change data to.\n\nQUOTA\n{ \"quota\": {\n\"val\": NUMBER,\n\"valunit\": STRING,\n\"used\": NUMBER,\n\"usedunit\": STRING,\n\"inv\": BOOLEAN\n}}\n\n{ \"quota\": STRING }\n\nThe first form creates an anonymous quota which lives in the rule it appears in. The second\nform specifies a reference to a named quota object.\n" }, { "name": "val", "content": "Quota value.\n\nvalunit\nUnit of val, e.g. \"kbytes\" or \"mbytes\". If omitted, defaults to \"bytes\".\n" }, { "name": "used", "content": "Quota used so far. Optional on input. If given, serves as initial value.\n\nusedunit\nUnit of used. Defaults to \"bytes\".\n" }, { "name": "inv", "content": "If true, will match if quota was exceeded. Defaults to false.\n\nLIMIT\n{ \"limit\": {\n\"rate\": NUMBER,\n\"rateunit\": STRING,\n\"per\": STRING,\n\"burst\": NUMBER,\n\"burstunit\": STRING,\n\"inv\": BOOLEAN\n}}\n\n{ \"limit\": STRING }\n\nThe first form creates an anonymous limit which lives in the rule it appears in. The second\nform specifies a reference to a named limit object.\n" }, { "name": "rate", "content": "Rate value to limit to.\n\nrateunit\nUnit of rate, e.g. \"packets\" or \"mbytes\". Defaults to \"packets\".\n" }, { "name": "per", "content": "Denominator of rate, e.g. \"week\" or \"minutes\".\n" }, { "name": "burst", "content": "Burst value. Defaults to 0.\n\nburstunit\nUnit of burst, ignored if rateunit is \"packets\". Defaults to \"bytes\".\n" }, { "name": "inv", "content": "If true, matches if the limit was exceeded. Defaults to false.\n\nFWD\n{ \"fwd\": {\n\"dev\": EXPRESSION,\n\"family\": FWDFAMILY,\n\"addr\": EXPRESSION\n}}\n\nFWDFAMILY := \"ip\" | \"ip6\"\n\nForward a packet to a different destination.\n" }, { "name": "dev", "content": "Interface to forward the packet on.\n" }, { "name": "family", "content": "Family of addr.\n" }, { "name": "addr", "content": "IP(v6) address to forward the packet to.\n\nBoth family and addr are optional, but if at least one is given, both must be present.\n\nNOTRACK\n{ \"notrack\": null }\n\nDisable connection tracking for the packet.\n\nDUP\n{ \"dup\": {\n\"addr\": EXPRESSION,\n\"dev\": EXPRESSION\n}}\n\nDuplicate a packet to a different destination.\n" }, { "name": "addr", "content": "Address to duplicate packet to.\n" }, { "name": "dev", "content": "Interface to duplicate packet on. May be omitted to not specify an interface explicitly.\n\nNETWORK ADDRESS TRANSLATION\n{ \"snat\": {\n\"addr\": EXPRESSION,\n\"family\": STRING,\n\"port\": EXPRESSION,\n\"flags\": FLAGS\n}}\n\n{ \"dnat\": {\n\"addr\": EXPRESSION,\n\"family\": STRING,\n\"port\": EXPRESSION,\n\"flags\": FLAGS\n}}\n\n{ \"masquerade\": {\n\"port\": EXPRESSION,\n\"flags\": FLAGS\n}}\n\n{ \"redirect\": {\n\"port\": EXPRESSION,\n\"flags\": FLAGS\n}}\n\nFLAGS := FLAG | [ FLAGLIST ]\nFLAGLIST := FLAG [, FLAGLIST ]\nFLAG := \"random\" | \"fully-random\" | \"persistent\"\n\nPerform Network Address Translation.\n" }, { "name": "addr", "content": "Address to translate to.\n" }, { "name": "family", "content": "Family of addr, either ip or ip6. Required in inet table family.\n" }, { "name": "port", "content": "Port to translate to.\n" }, { "name": "flags", "content": "Flag(s).\n\nAll properties are optional and default to none.\n\nREJECT\n{ \"reject\": {\n\"type\": STRING,\n\"expr\": EXPRESSION\n}}\n\nReject the packet and send the given error reply.\n" }, { "name": "type", "content": "Type of reject, either \"tcp reset\", \"icmpx\", \"icmp\" or \"icmpv6\".\n" }, { "name": "expr", "content": "ICMP code to reject with.\n\nAll properties are optional.\n\nSET\n{ \"set\": {\n\"op\": STRING,\n\"elem\": EXPRESSION,\n\"set\": STRING\n}}\n\nDynamically add/update elements to a set.\n\nop\nOperator on set, either \"add\" or \"update\".\n" }, { "name": "elem", "content": "Set element to add or update.\n" }, { "name": "set", "content": "Set reference.\n\nLOG\n{ \"log\": {\n\"prefix\": STRING,\n\"group\": NUMBER,\n\"snaplen\": NUMBER,\n\"queue-threshold\": NUMBER,\n\"level\": LEVEL,\n\"flags\": FLAGS\n}}\n\nLEVEL := \"emerg\" | \"alert\" | \"crit\" | \"err\" | \"warn\" | \"notice\" |\n\"info\" | \"debug\" | \"audit\"\n\nFLAGS := FLAG | [ FLAGLIST ]\nFLAGLIST := FLAG [, FLAGLIST ]\nFLAG := \"tcp sequence\" | \"tcp options\" | \"ip options\" | \"skuid\" |\n\"ether\" | \"all\"\n\nLog the packet.\n" }, { "name": "prefix", "content": "Prefix for log entries.\n" }, { "name": "group", "content": "Log group.\n" }, { "name": "snaplen", "content": "Snaplen for logging.\n" }, { "name": "queue-threshold", "content": "Queue threshold.\n" }, { "name": "level", "content": "Log level. Defaults to \"warn\".\n" }, { "name": "flags", "content": "Log flags.\n\nAll properties are optional.\n\nCT HELPER\n{ \"ct helper\": EXPRESSION }\n\nEnable the specified conntrack helper for this packet.\n" }, { "name": "ct helper", "content": "CT helper reference.\n\nMETER\n{ \"meter\": {\n\"name\": STRING,\n\"key\": EXPRESSION,\n\"stmt\": STATEMENT\n}}\n\nApply a given statement using a meter.\n" }, { "name": "name", "content": "Meter name.\n" }, { "name": "key", "content": "Meter key.\n" }, { "name": "stmt", "content": "Meter statement.\n\nQUEUE\n{ \"queue\": {\n\"num\": EXPRESSION,\n\"flags\": FLAGS\n}}\n\nFLAGS := FLAG | [ FLAGLIST ]\nFLAGLIST := FLAG [, FLAGLIST ]\nFLAG := \"bypass\" | \"fanout\"\n\nQueue the packet to userspace.\n" }, { "name": "num", "content": "Queue number.\n" }, { "name": "flags", "content": "Queue flags.\n\nVERDICT MAP\n{ \"vmap\": {\n\"key\": EXPRESSION,\n\"data\": EXPRESSION\n}}\n\nApply a verdict conditionally.\n" }, { "name": "key", "content": "Map key.\n" }, { "name": "data", "content": "Mapping expression consisting of value/verdict pairs.\n\nCT COUNT\n{ \"ct count\": {\n\"val\": NUMBER,\n\"inv\": BOOLEAN\n}}\n\nLimit the number of connections using conntrack.\n" }, { "name": "val", "content": "Connection count threshold.\n" }, { "name": "inv", "content": "If true, match if val was exceeded. If omitted, defaults to false.\n\nCT TIMEOUT\n{ \"ct timeout\": EXPRESSION }\n\nAssign connection tracking timeout policy.\n" }, { "name": "ct timeout", "content": "CT timeout reference.\n\nCT EXPECTATION\n{ \"ct expectation\": EXPRESSION }\n\nAssign connection tracking expectation.\n" }, { "name": "ct expectation", "content": "CT expectation reference.\n\nXT\n{ \"xt\": null }\n\nThis represents an xt statement from xtables compat interface. Sadly, at this point, it is\nnot possible to provide any further information about its content.\n" } ] }, "EXPRESSIONS": { "content": "Expressions are the building blocks of (most) statements. In their most basic form, they are\njust immediate values represented as a JSON string, integer or boolean type.\n\nIMMEDIATES\nSTRING\nNUMBER\nBOOLEAN\n\nImmediate expressions are typically used for constant values. For strings, there are two\nspecial cases:\n", "subsections": [ { "name": "@STRING", "content": "The remaining part is taken as set name to create a set reference.\n\n\\*\nConstruct a wildcard expression.\n\nLISTS\nARRAY\n\nList expressions are constructed by plain arrays containing of an arbitrary number of\nexpressions.\n\nCONCAT\n{ \"concat\": CONCAT }\n\nCONCAT := [ EXPRESSIONLIST ]\nEXPRESSIONLIST := EXPRESSION [, EXPRESSIONLIST ]\n\nConcatenate several expressions.\n\nSET\n{ \"set\": SET }\n\nSET := EXPRESSION | [ EXPRESSIONLIST ]\n\nThis object constructs an anonymous set. For mappings, an array of arrays with exactly two\nelements is expected.\n\nMAP\n{ \"map\": {\n\"key\": EXPRESSION,\n\"data\": EXPRESSION\n}}\n\nMap a key to a value.\n" }, { "name": "key", "content": "Map key.\n" }, { "name": "data", "content": "Mapping expression consisting of value/target pairs.\n\nPREFIX\n{ \"prefix\": {\n\"addr\": EXPRESSION,\n\"len\": NUMBER\n}}\n\nConstruct an IPv4 or IPv6 prefix consisting of address part in addr and prefix length in len.\n\nRANGE\n{ \"range\": [ EXPRESSION , EXPRESSION ] }\n\nConstruct a range of values. The first array item denotes the lower boundary, the second one\nthe upper boundary.\n\nPAYLOAD\n{ \"payload\": {\n\"base\": BASE,\n\"offset\": NUMBER,\n\"len\": NUMBER\n}}\n\n{ \"payload\": {\n\"protocol\": STRING,\n\"field\": STRING\n}}\n\nBASE := \"ll\" | \"nh\" | \"th\"\n\nConstruct a payload expression, i.e. a reference to a certain part of packet data. The first\nform creates a raw payload expression to point at a random number (len) of bytes at a certain\noffset (offset) from a given reference point (base). The following base values are accepted:\n" }, { "name": "\"ll\"", "content": "The offset is relative to Link Layer header start offset.\n" }, { "name": "\"nh\"", "content": "The offset is relative to Network Layer header start offset.\n" }, { "name": "\"th\"", "content": "The offset is relative to Transport Layer header start offset.\n\nThe second form allows to reference a field by name (field) in a named packet header\n(protocol).\n\nEXTHDR\n{ \"exthdr\": {\n\"name\": STRING,\n\"field\": STRING,\n\"offset\": NUMBER\n}}\n\nCreate a reference to a field (field) in an IPv6 extension header (name). offset is used only\nfor rt0 protocol.\n\nIf the field property is not given, the expression is to be used as a header existence check\nin a match statement with a boolean on the right hand side.\n\nTCP OPTION\n{ \"tcp option\": {\n\"name\": STRING,\n\"field\": STRING\n}}\n\nCreate a reference to a field (field) of a TCP option header (name).\n\nIf the field property is not given, the expression is to be used as a TCP option existence\ncheck in a match statement with a boolean on the right hand side.\n\nSCTP CHUNK\n{ \"sctp chunk\": {\n\"name\": STRING,\n\"field\": STRING\n}}\n\nCreate a reference to a field (field) of an SCTP chunk (name).\n\nIf the field property is not given, the expression is to be used as an SCTP chunk existence\ncheck in a match statement with a boolean on the right hand side.\n\nMETA\n{ \"meta\": {\n\"key\": METAKEY\n}}\n\nMETAKEY := \"length\" | \"protocol\" | \"priority\" | \"random\" | \"mark\" |\n\"iif\" | \"iifname\" | \"iiftype\" | \"oif\" | \"oifname\" |\n\"oiftype\" | \"skuid\" | \"skgid\" | \"nftrace\" |\n\"rtclassid\" | \"ibriport\" | \"obriport\" | \"ibridgename\" |\n\"obridgename\" | \"pkttype\" | \"cpu\" | \"iifgroup\" |\n\"oifgroup\" | \"cgroup\" | \"nfproto\" | \"l4proto\" |\n\"secpath\"\n\nCreate a reference to packet meta data.\n\nRT\n{ \"rt\": {\n\"key\": RTKEY,\n\"family\": RTFAMILY\n}}\n\nRTKEY := \"classid\" | \"nexthop\" | \"mtu\"\nRTFAMILY := \"ip\" | \"ip6\"\n\nCreate a reference to packet routing data.\n\nThe family property is optional and defaults to unspecified.\n\nCT\n{ \"ct\": {\n\"key\": STRING,\n\"family\": CTFAMILY,\n\"dir\": CTDIRECTION\n}}\n\nCTFAMILY := \"ip\" | \"ip6\"\nCTDIRECTION := \"original\" | \"reply\"\n\nCreate a reference to packet conntrack data.\n\nSome CT keys do not support a direction. In this case, dir must not be given.\n\nNUMGEN\n{ \"numgen\": {\n\"mode\": NGMODE,\n\"mod\": NUMBER,\n\"offset\": NUMBER\n}}\n\nNGMODE := \"inc\" | \"random\"\n\nCreate a number generator.\n\nThe offset property is optional and defaults to 0.\n\nHASH\n{ \"jhash\": {\n\"mod\": NUMBER,\n\"offset\": NUMBER,\n\"expr\": EXPRESSION,\n\"seed\": NUMBER\n}}\n\n{ \"symhash\": {\n\"mod\": NUMBER,\n\"offset\": NUMBER\n}}\n\nHash packet data.\n\nThe offset and seed properties are optional and default to 0.\n\nFIB\n{ \"fib\": {\n\"result\": FIBRESULT,\n\"flags\": FIBFLAGS\n}}\n\nFIBRESULT := \"oif\" | \"oifname\" | \"type\"\n\nFIBFLAGS := FIBFLAG | [ FIBFLAGLIST ]\nFIBFLAGLIST := FIBFLAG [, FIBFLAGLIST ]\nFIBFLAG := \"saddr\" | \"daddr\" | \"mark\" | \"iif\" | \"oif\"\n\nPerform kernel Forwarding Information Base lookups.\n\nBINARY OPERATION\n{ \"|\": [ EXPRESSION, EXPRESSION ] }\n{ \"^\": [ EXPRESSION, EXPRESSION ] }\n{ \"&\": [ EXPRESSION, EXPRESSION ] }\n{ \"<<\": [ EXPRESSION, EXPRESSION ] }\n{ \">>\": [ EXPRESSION, EXPRESSION ] }\n\nAll binary operations expect an array of exactly two expressions, of which the first element\ndenotes the left hand side and the second one the right hand side.\n\nVERDICT\n{ \"accept\": null }\n{ \"drop\": null }\n{ \"continue\": null }\n{ \"return\": null }\n{ \"jump\": { \"target\": STRING }}\n{ \"goto\": { \"target\": STRING }}\n\nSame as the verdict statement, but for use in verdict maps.\n\njump and goto verdicts expect a target chain name.\n\nELEM\n{ \"elem\": {\n\"val\": EXPRESSION,\n\"timeout\": NUMBER,\n\"expires\": NUMBER,\n\"comment\": STRING\n}}\n\nExplicitly set element object, in case timeout, expires or comment are desired. Otherwise, it\nmay be replaced by the value of val.\n\nSOCKET\n{ \"socket\": {\n\"key\": SOCKETKEY\n}}\n\nSOCKETKEY := \"transparent\"\n\nConstruct a reference to packet’s socket.\n\nOSF\n{ \"osf\": {\n\"key\": OSFKEY,\n\"ttl\": OSFTTL\n}}\n\nOSFKEY := \"name\"\nOSFTTL := \"loose\" | \"skip\"\n\nPerform OS fingerprinting. This expression is typically used in the LHS of a match statement.\n" }, { "name": "key", "content": "Which part of the fingerprint info to match against. At this point, only the OS name is\nsupported.\n" }, { "name": "ttl", "content": "Define how the packet’s TTL value is to be matched. This property is optional. If\nomitted, the TTL value has to match exactly. A value of loose accepts TTL values less\nthan the fingerprint one. A value of skip omits TTL value comparison entirely.\n" } ] }, "AUTHOR": { "content": "Phil Sutter \nAuthor.\n\n\n\n02/24/2026 LIBNFTABLES-JSON(5)", "subsections": [] } } } }