Getting out changes I've accumulated while making nftables spec to work with Rust netlink-bindings. Hopefully, this will be useful upstream. This patch: - Adds missing byte order annotations. - Fills out attributes in some operations. - Replaces non-existent "name" attribute with todo comment. - Adds some missing sub-messages (and associated attributes). - Adds (copies over) documentation for some attributes / enum entries. - Adds "getcompat" operation defined in nft_compat.c . - Allows ynl_gen_rst.py script to handle empty request/reply attribute. Signed-off-by: Remy D. Farley --- Documentation/netlink/specs/nftables.yaml | 446 ++++++++++++++++++++-- tools/net/ynl/pyynl/ynl_gen_rst.py | 2 + 2 files changed, 407 insertions(+), 41 deletions(-) diff --git a/Documentation/netlink/specs/nftables.yaml b/Documentation/netlink/specs/nftables.yaml index 2ee10d92d..2717084a9 100644 --- a/Documentation/netlink/specs/nftables.yaml +++ b/Documentation/netlink/specs/nftables.yaml @@ -66,9 +66,22 @@ definitions: name: bitwise-ops type: enum entries: - - bool + - + name: mask-xor # aka bool (old name) + doc: | + mask-and-xor operation used to implement NOT, AND, OR and XOR boolean operations + dreg = (sreg & mask) ^ xor + with these mask and xor values: + mask xor + NOT: 1 1 + OR: ~x x + XOR: 1 x + AND: x 0 - lshift - rshift + - and + - or + - xor - name: cmp-ops type: enum @@ -225,14 +238,216 @@ definitions: - icmp-unreach - tcp-rst - icmpx-unreach + - + # Defined in include/linux/netfilter/nf_tables.h + name: payload-base + type: enum + entries: + - link-layer-header + - network-header + - transport-header + - inner-header + - tun-header + - + # Defined in include/linux/netfilter/nf_tables.h + name: range-ops + doc: Range operator + type: enum + entries: + - eq + - neq + - + # Defined in include/linux/netfilter/nf_tables.h + name: registers + doc: | + nf_tables registers. + nf_tables used to have five registers: a verdict register and four data + registers of size 16. The data registers have been changed to 16 registers + of size 4. For compatibility reasons, the NFT_REG_[1-4] registers still + map to areas of size 16, the 4 byte registers are addressed using + NFT_REG32_00 - NFT_REG32_15. + type: enum + entries: + - reg_verdict + - reg_1 + - reg_2 + - reg_3 + - reg_4 + - + name: reg32_00 + value: 8 + - reg32_01 + - reg32_02 + - reg32_03 + - reg32_04 + - reg32_05 + - reg32_06 + - reg32_07 + - reg32_08 + - reg32_09 + - reg32_10 + - reg32_11 + - reg32_12 + - reg32_13 + - reg32_14 + - reg32_15 + - + # Defined in include/linux/netfilter/nf_tables.h + name: numgen-types + type: enum + entries: + - incremental + - random + - + name: log-level + doc: nf_tables log levels + type: enum + entries: + - + name: emerg + doc: system is unusable + - + name: alert + doc: action must be taken immediately + - + name: crit + doc: critical conditions + - + name: err + doc: error conditions + - + name: warning + doc: warning conditions + - + name: notice + doc: normal but significant condition + - + name: info + doc: informational + - + name: debug + doc: debug-level messages + - + name: audit + doc: enabling audit logging + - + # Defined in include/uapi/linux/netfilter/nf_log.h + name: log-flags + doc: nf_tables log flags + type: flags + entries: + - + name: tcpseq + doc: Log TCP sequence numbers + - + name: tcpopt + doc: Log TCP options + - + name: ipopt + doc: Log IP options + - + name: uid + doc: Log UID owning local socket + - + name: nflog + doc: Unsupported, don't reuse + - + name: macdecode + doc: Decode MAC header attribute-sets: - - name: empty-attrs + # Defined in include/linux/netfilter/nf_tables.h + name: log-attrs + doc: log expression netlink attributes attributes: + # Mentioned in nft_log_init() - - name: name + name: group + doc: netlink group to send messages to + type: u16 + byte-order: big-endian + - + name: prefix + doc: prefix to prepend to log messages type: string + - + name: snaplen + doc: length of payload to include in netlink message + type: u32 + byte-order: big-endian + - + name: qthreshold + doc: queue threshold + type: u16 + byte-order: big-endian + - + name: level + doc: log level + type: u32 + enum: log-level + byte-order: big-endian + - + name: flags + doc: logging flags + type: u32 + enum: log-flags + byte-order: big-endian + + - + # Defined in include/linux/netfilter/nf_tables.h + name: numgen-attrs + doc: nf_tables number generator expression netlink attributes + attributes: + - + name: dreg + doc: destination register + type: u32 + enum: registers + - + name: modulus + doc: maximum counter value + type: u32 + byte-order: big-endian + - + name: type + doc: operation type + type: u32 + byte-order: big-endian + enum: numgen-types + - + name: offset + doc: offset to be added to the counter + type: u32 + byte-order: big-endian + - + # Defined in net/netfilter/nft_range.c + name: range-attrs + attributes: + - + name: sreg + doc: source register of data to compare + type: u32 + byte-order: big-endian + enum: registers + - + name: op + doc: cmp operation + type: u32 + byte-order: big-endian + enum: range-ops + checks: + max: 256 + - + name: from-data + doc: data range from + type: nest + nested-attributes: data-attrs + - + name: to-data + doc: data range to + type: nest + nested-attributes: data-attrs - name: batch-attrs attributes: @@ -371,9 +586,11 @@ attribute-sets: - name: bytes type: u64 + byte-order: big-endian - name: packets type: u64 + byte-order: big-endian - name: rule-attrs attributes: @@ -443,15 +660,18 @@ attribute-sets: selector: name doc: type specific data - + # Mentioned in nft_parse_compat() in net/netfilter/nft_compat.c name: rule-compat-attrs attributes: - name: proto - type: binary + type: u32 + byte-order: big-endian doc: numeric value of the handled protocol - name: flags - type: binary + type: u32 + byte-order: big-endian doc: bitmask of flags - name: set-attrs @@ -814,6 +1034,7 @@ attribute-sets: type: nest nested-attributes: data-attrs - + # Defined as nft_data_attributes in include/linux/netfilter/nf_tables.h name: data-attrs attributes: - @@ -829,25 +1050,31 @@ attribute-sets: attributes: - name: code + doc: nf_tables verdict type: u32 byte-order: big-endian enum: verdict-code - name: chain + doc: jump target chain name type: string - name: chain-id + doc: jump target chain ID type: u32 + byte-order: big-endian # Accessed in nft_chain_lookup_byid - name: expr-counter-attrs attributes: - name: bytes type: u64 + byte-order: big-endian doc: Number of bytes - name: packets type: u64 + byte-order: big-endian doc: Number of packets - name: pad @@ -982,38 +1209,51 @@ attribute-sets: enum: nat-range-flags enum-as-flags: true - + # Defined as nft_payload_attributes in include/linux/netfilter/nf_tables.h name: expr-payload-attrs + doc: nf_tables payload expression netlink attributes attributes: - name: dreg + doc: destination register to load data into type: u32 byte-order: big-endian + enum: registers - name: base + doc: payload base type: u32 + enum: payload-base byte-order: big-endian - name: offset + doc: payload offset relative to base type: u32 byte-order: big-endian - name: len + doc: payload length type: u32 byte-order: big-endian - name: sreg + doc: source register to load data from type: u32 byte-order: big-endian + enum: registers - name: csum-type + doc: checksum type type: u32 byte-order: big-endian - name: csum-offset + doc: checksum offset relative to base type: u32 byte-order: big-endian - name: csum-flags + doc: checksum flags type: u32 byte-order: big-endian - @@ -1079,6 +1319,61 @@ attribute-sets: type: u32 byte-order: big-endian doc: id of object map + - + # Defined as nft_target_attributes in include/uapi/linux/netfilter/nf_tables_compat.h + name: compat-target-attrs + attributes: + - + name: name + type: string + checks: + max-len: 32 + - + name: rev + type: u32 + byte-order: big-endian + checks: + max: 255 + - + name: info + type: binary + - + # Defined as nft_match_attributes in include/uapi/linux/netfilter/nf_tables_compat.h + name: compat-match-attrs + attributes: + - + name: name + type: string + checks: + max-len: 32 + - + name: rev + type: u32 + byte-order: big-endian + checks: + max: 255 + - + name: info + type: binary + - + # Defined in include/uapi/linux/netfilter/nf_tables_compat.h + name: compat-attrs + attributes: + - + name: name + type: string + checks: + max-len: 32 + - + name: rev + type: u32 + byte-order: big-endian + checks: + max: 255 + - + name: type + type: u32 + byte-order: big-endian sub-messages: - @@ -1132,6 +1427,19 @@ sub-messages: - value: tproxy attribute-set: expr-tproxy-attrs + - + value: match + attribute-set: compat-match-attrs + - + value: range + attribute-set: range-attrs + - + value: numgen + attribute-set: numgen-attrs + - + value: log + attribute-set: log-attrs + # There're more to go: grep -A10 nft_expr_type and look for .name\s*=\s*"..." - name: obj-data formats: @@ -1145,6 +1453,27 @@ sub-messages: operations: enum-model: directional list: + - + # Defined as nfnl_compat_subsys in net/netfilter/nft_compat.c + name: getcompat + attribute-set: compat-attrs + fixed-header: nfgenmsg + doc: Get / dump nft_compat info + do: + request: + value: 0xb00 + attributes: + - name + - rev + - type + reply: + value: 0xb00 + attributes: + - name + - rev + - type + dump: + reply: - name: batch-begin doc: Start a batch of operations @@ -1187,12 +1516,17 @@ operations: do: request: value: 0xa01 - attributes: - - name + # TODO: attributes reply: value: 0xa00 + # TODO: attributes + dump: + reply: attributes: - name + - use + - handle + - flags - name: deltable doc: Delete an existing table. @@ -1239,6 +1573,18 @@ operations: value: 0xa03 attributes: - name + dump: + reply: + attributes: + - table + - name + - handle + - hook + - policy + - type + - counters + - id + - use - name: delchain doc: Delete an existing chain. @@ -1270,7 +1616,10 @@ operations: request: value: 0xa06 attributes: - - name + - table + - chain + - expressions + - compat - name: getrule doc: Get / dump rules. @@ -1279,12 +1628,22 @@ operations: do: request: value: 0xa07 - attributes: - - name + # TODO: attributes reply: value: 0xa06 + # TODO: attributes + dump: + request: attributes: - - name + - table + - chain + reply: + attributes: + - table + - chain + - handle + - position + - expressions - name: getrule-reset doc: Get / dump rules and reset stateful expressions. @@ -1293,12 +1652,12 @@ operations: do: request: value: 0xa19 - attributes: - - name + # TODO: attributes reply: value: 0xa06 - attributes: - - name + # TODO: attributes + dump: + reply: - name: delrule doc: Delete an existing rule. @@ -1307,8 +1666,7 @@ operations: do: request: value: 0xa08 - attributes: - - name + # TODO: attributes - name: destroyrule doc: | @@ -1318,8 +1676,7 @@ operations: do: request: value: 0xa1c - attributes: - - name + # TODO: attributes - name: newset doc: Create a new set. @@ -1328,8 +1685,7 @@ operations: do: request: value: 0xa09 - attributes: - - name + # TODO: attributes - name: getset doc: Get / dump sets. @@ -1338,12 +1694,16 @@ operations: do: request: value: 0xa0a - attributes: - - name + # TODO: attributes reply: value: 0xa09 + # TODO: attributes + dump: + request: attributes: - - name + - table + reply: + # TODO: attributes - name: delset doc: Delete an existing set. @@ -1373,8 +1733,7 @@ operations: do: request: value: 0xa0c - attributes: - - name + # TODO: attributes - name: getsetelem doc: Get / dump set elements. @@ -1383,12 +1742,12 @@ operations: do: request: value: 0xa0d - attributes: - - name + # TODO: attributes reply: value: 0xa0c - attributes: - - name + # TODO: attributes + dump: + reply: - name: getsetelem-reset doc: Get / dump set elements and reset stateful expressions. @@ -1397,12 +1756,12 @@ operations: do: request: value: 0xa21 - attributes: - - name + # TODO: attributes reply: value: 0xa0c - attributes: - - name + # TODO: attributes + dump: + reply: - name: delsetelem doc: Delete an existing set element. @@ -1411,8 +1770,7 @@ operations: do: request: value: 0xa0e - attributes: - - name + # TODO: attributes - name: destroysetelem doc: Delete an existing set element with destroy semantics. @@ -1421,8 +1779,7 @@ operations: do: request: value: 0xa1e - attributes: - - name + # TODO: attributes - name: getgen doc: Get / dump rule-set generation. @@ -1431,12 +1788,15 @@ operations: do: request: value: 0xa10 - attributes: - - name + # TODO: attributes reply: value: 0xa0f attributes: - - name + - id + - proc-pid + - proc-name + dump: + reply: - name: newobj doc: Create a new stateful object. @@ -1461,6 +1821,8 @@ operations: value: 0xa12 attributes: - name + dump: + reply: - name: delobj doc: Delete an existing stateful object. @@ -1505,6 +1867,8 @@ operations: value: 0xa16 attributes: - name + dump: + reply: - name: delflowtable doc: Delete an existing flow table. diff --git a/tools/net/ynl/pyynl/ynl_gen_rst.py b/tools/net/ynl/pyynl/ynl_gen_rst.py index 0cb6348e2..35325f37e 100755 --- a/tools/net/ynl/pyynl/ynl_gen_rst.py +++ b/tools/net/ynl/pyynl/ynl_gen_rst.py @@ -157,6 +157,8 @@ def parse_do(do_dict: Dict[str, Any], level: int = 0) -> str: for key in do_dict.keys(): lines.append(rst_paragraph(bold(key), level + 1)) if key in ['request', 'reply']: + if do_dict[key] is None: + continue -- 2.49.0