[PATCH v6 0/6] doc/netlink: Expand nftables specification

[PATCH v6 0/6] doc/netlink: Expand nftables specification

[Remy D. Farley]

Getting out some changes I've accumulated while making nftables work
with Rust netlink-bindings. Hopefully, this will be useful upstream.

v6:
- Sort sub-messages.
- Add description for "Add max check" commit.
- Fix doc comment for expr-bitwise-attrs to match one in nf_tables.h (thanks Donald)

v5: https://lore.kernel.org/netdev/20251120151754.1111675-1-one-d-wide@protonmail.com/
- Fix docgen warnings in enums (avoid interleaving strings and attrsets in a list).
- Remove "# defined in ..." comments in favor of explicit "header" tag.
- Split into smaller commits.

v4: https://lore.kernel.org/netdev/cover.1763574466.git.one-d-wide@protonmail.com/
- Move changes to netlink-raw.yaml into a separate commit.

v3: https://lore.kernel.org/netdev/20251009203324.1444367-1-one-d-wide@protonmail.com/
- Fill out missing attributes in each operation (removing todo comments from v1).
- Add missing annotations: dump ops, byte-order, checks.
- Add max check to netlink-raw specification (suggested by Donald Hunter).
- Revert changes to ynl_gen_rst.py.

v2: https://lore.kernel.org/netdev/20251003175510.1074239-1-one-d-wide@protonmail.com/
- Handle empty request/reply attributes in ynl_gen_rst.py script.

v1: https://lore.kernel.org/netdev/20251002184950.1033210-1-one-d-wide@protonmail.com/
- Add missing byte order annotations.
- Fill out attributes in some operations.
- Replace non-existent "name" attribute with todo comment.
- Add some missing sub-messages (and associated attributes).
- Add (copy over) documentation for some attributes / enum entries.
- Add "getcompat" operation.

Remy D. Farley (6):
  doc/netlink: netlink-raw: Add max check
  doc/netlink: nftables: Add definitions
  doc/netlink: nftables: Update attribute sets
  doc/netlink: nftables: Add sub-messages
  doc/netlink: nftables: Add getcompat operation
  doc/netlink: nftables: Fill out operation attributes

 Documentation/netlink/netlink-raw.yaml    |  11 +-
 Documentation/netlink/specs/nftables.yaml | 695 ++++++++++++++++++++--
 2 files changed, 656 insertions(+), 50 deletions(-)

-- 
2.51.2

[PATCH v6 1/6] doc/netlink: netlink-raw: Add max check

[Remy D. Farley]

Add definitions for max check and len-or-limit type, the same as in other
specifications.

Suggested-by: Donald Hunter <donald.hunter@gmail.com>
Signed-off-by: Remy D. Farley <one-d-wide@protonmail.com>
---
 Documentation/netlink/netlink-raw.yaml | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/Documentation/netlink/netlink-raw.yaml b/Documentation/netlink/netlink-raw.yaml
index 0166a7e4a..dd98dda55 100644
--- a/Documentation/netlink/netlink-raw.yaml
+++ b/Documentation/netlink/netlink-raw.yaml
@@ -19,6 +19,12 @@ $defs:
     type: [ string, integer ]
     pattern: ^[0-9A-Za-z_-]+( - 1)?$
     minimum: 0
+  len-or-limit:
+    # literal int, const name, or limit based on fixed-width type
+    # e.g. u8-min, u16-max, etc.
+    type: [ string, integer ]
+    pattern: ^[0-9A-Za-z_-]+$
+    minimum: 0
 
 # Schema for specs
 title: Protocol
@@ -270,7 +276,10 @@ properties:
                     type: string
                   min:
                     description: Min value for an integer attribute.
-                    type: integer
+                    $ref: '#/$defs/len-or-limit'
+                  max:
+                    description: Max value for an integer attribute.
+                    $ref: '#/$defs/len-or-limit'
                   min-len:
                     description: Min length for a binary attribute.
                     $ref: '#/$defs/len-or-define'
-- 
2.51.2

[PATCH v6 2/6] doc/netlink: nftables: Add definitions

[Remy D. Farley]

New enums/flags:
- payload-base
- range-ops
- registers
- numgen-types
- log-level
- log-flags

Added missing enumerations:
- bitwise-ops

Annotated doc comment or associated enum:
- bitwise-ops

Signed-off-by: Remy D. Farley <one-d-wide@protonmail.com>
---
 Documentation/netlink/specs/nftables.yaml | 157 +++++++++++++++++++++-
 1 file changed, 154 insertions(+), 3 deletions(-)

diff --git a/Documentation/netlink/specs/nftables.yaml b/Documentation/netlink/specs/nftables.yaml
index 17ad707fa..87cd4d201 100644
--- a/Documentation/netlink/specs/nftables.yaml
+++ b/Documentation/netlink/specs/nftables.yaml
@@ -66,9 +66,17 @@ definitions:
     name: bitwise-ops
     type: enum
     entries:
-      - bool
-      - lshift
-      - rshift
+      -
+        name: mask-xor  # aka bool (old name)
+        doc: >-
+          mask-and-xor operation used to implement NOT, AND, OR and XOR boolean
+          operations
+      # Spinx docutils display warning when interleaving attrsets with strings
+      - name: lshift
+      - name: rshift
+      - name: and
+      - name: or
+      - name: xor
   -
     name: cmp-ops
     type: enum
@@ -132,6 +140,12 @@ definitions:
       - object
       - concat
       - expr
+  -
+    name: set-elem-flags
+    type: flags
+    entries:
+      - interval-end
+      - catchall
   -
     name: lookup-flags
     type: flags
@@ -225,6 +239,127 @@ definitions:
       - icmp-unreach
       - tcp-rst
       - icmpx-unreach
+  -
+    name: reject-inet-code
+    doc: These codes are mapped to real ICMP and ICMPv6 codes.
+    type: enum
+    entries:
+      - icmpx-no-route
+      - icmpx-port-unreach
+      - icmpx-host-unreach
+      - icmpx-admin-prohibited
+  -
+    name: payload-base
+    type: enum
+    entries:
+      - link-layer-header
+      - network-header
+      - transport-header
+      - inner-header
+      - tun-header
+  -
+    name: range-ops
+    doc: Range operator
+    type: enum
+    entries:
+      - eq
+      - neq
+  -
+    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:
+      # Spinx docutils display warning when interleaving attrsets and strings
+      - name: reg-verdict
+      - name: reg-1
+      - name: reg-2
+      - name: reg-3
+      - name: reg-4
+      - name: reg32-00
+        value: 8
+      - name: reg32-01
+      - name: reg32-02
+      - name: reg32-03
+      - name: reg32-04
+      - name: reg32-05
+      - name: reg32-06
+      - name: reg32-07
+      - name: reg32-08
+      - name: reg32-09
+      - name: reg32-10
+      - name: reg32-11
+      - name: reg32-12
+      - name: reg32-13
+      - name: reg32-14
+      - name: reg32-15
+  -
+    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
+  -
+    name: log-flags
+    doc: nf_tables log flags
+    header: linux/netfilter/nf_log.h
+    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:
   -
@@ -767,6 +902,22 @@ attribute-sets:
         nested-attributes: hook-dev-attrs
   -
     name: expr-bitwise-attrs
+    doc: |
+      The bitwise expression supports boolean and shift operations. It
+      implements the boolean operations by performing the following
+      operation::
+
+          dreg = (sreg & mask) ^ xor
+
+          with these mask and xor values:
+
+          op      mask    xor
+          ----    ----    ---
+          NOT:     1       1
+          OR:     ~x       x
+          XOR:     1       x
+          AND:     x       0
+
     attributes:
       -
         name: sreg
-- 
2.51.2

[PATCH v6 3/6] doc/netlink: nftables: Update attribute sets

[Remy D. Farley]

New attribute sets:
- log-attrs
- numgen-attrs
- range-attrs
- compat-target-attrs
- compat-match-attrs
- compat-attrs

Added missing attributes:
- table-attrs (pad, owner)
- set-attrs (type, count)

Added missing checks:
- range-attrs
- expr-bitwise-attrs
- compat-target-attrs
- compat-match-attrs
- compat-attrs

Annotated doc comment or associated enum:
- batch-attrs
- verdict-attrs
- expr-payload-attrs

Fixed byte order:
- nft-counter-attrs
- expr-counter-attrs
- rule-compat-attrs

Signed-off-by: Remy D. Farley <one-d-wide@protonmail.com>
---
 Documentation/netlink/specs/nftables.yaml | 206 +++++++++++++++++++++-
 1 file changed, 202 insertions(+), 4 deletions(-)

diff --git a/Documentation/netlink/specs/nftables.yaml b/Documentation/netlink/specs/nftables.yaml
index 87cd4d201..826d3441b 100644
--- a/Documentation/netlink/specs/nftables.yaml
+++ b/Documentation/netlink/specs/nftables.yaml
@@ -363,16 +363,100 @@ definitions:
 
 attribute-sets:
   -
-    name: empty-attrs
+    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
+  -
+    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
+  -
+    name: range-attrs
+    attributes:
+      # Mentioned in net/netfilter/nft_range.c
+      -
+        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:
       -
         name: genid
+        doc: generation ID for this changeset
         type: u32
         byte-order: big-endian
   -
@@ -399,10 +483,18 @@ attribute-sets:
         type: u64
         byte-order: big-endian
         doc: numeric handle of the table
+      -
+        name: pad
+        type: pad
       -
         name: userdata
         type: binary
         doc: user data
+      -
+        name: owner
+        type: u32
+        byte-order: big-endian
+        doc: owner of this table through netlink portID
   -
     name: chain-attrs
     attributes:
@@ -506,9 +598,11 @@ attribute-sets:
       -
         name: bytes
         type: u64
+        byte-order: big-endian
       -
         name: packets
         type: u64
+        byte-order: big-endian
   -
     name: rule-attrs
     attributes:
@@ -578,15 +672,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
@@ -675,6 +772,15 @@ attribute-sets:
         type: nest
         nested-attributes: set-list-attrs
         doc: list of expressions
+      -
+        name: type
+        type: string
+        doc: set backend type
+      -
+        name: count
+        type: u32
+        byte-order: big-endian
+        doc: number of set elements
   -
     name: set-desc-attrs
     attributes:
@@ -944,6 +1050,8 @@ attribute-sets:
         type: u32
         byte-order: big-endian
         enum: bitwise-ops
+        checks:
+          max: 255
       -
         name: data
         type: nest
@@ -980,25 +1088,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
   -
     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
@@ -1083,6 +1197,25 @@ attribute-sets:
         type: u32
         byte-order: big-endian
         enum: lookup-flags
+  -
+    name: expr-masq-attrs
+    attributes:
+      -
+        name: flags
+        type: u32
+        byte-order: big-endian
+        enum: nat-range-flags
+        enum-as-flags: true
+      -
+        name: reg-proto-min
+        type: u32
+        byte-order: big-endian
+        enum: registers
+      -
+        name: reg-proto-max
+        type: u32
+        byte-order: big-endian
+        enum: registers
   -
     name: expr-meta-attrs
     attributes:
@@ -1134,37 +1267,49 @@ attribute-sets:
         enum-as-flags: true
   -
     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
   -
@@ -1230,6 +1375,59 @@ attribute-sets:
         type: u32
         byte-order: big-endian
         doc: id of object map
+  -
+    name: compat-target-attrs
+    header: linux/netfilter/nf_tables_compat.h
+    attributes:
+      -
+        name: name
+        type: string
+        checks:
+          max-len: 32
+      -
+        name: rev
+        type: u32
+        byte-order: big-endian
+      -
+        name: info
+        type: binary
+  -
+    name: compat-match-attrs
+    header: linux/netfilter/nf_tables_compat.h
+    attributes:
+      -
+        name: name
+        type: string
+        checks:
+          max-len: 32
+      -
+        name: rev
+        type: u32
+        byte-order: big-endian
+        checks:
+          max: 255
+      -
+        name: info
+        type: binary
+  -
+    name: compat-attrs
+    header: linux/netfilter/nf_tables_compat.h
+    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:
   -
-- 
2.51.2

[PATCH v6 4/6] doc/netlink: nftables: Add sub-messages

[Remy D. Farley]

New sub-messsages:
- log
- match
- numgen
- range

Signed-off-by: Remy D. Farley <one-d-wide@protonmail.com>
---
 Documentation/netlink/specs/nftables.yaml | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/netlink/specs/nftables.yaml b/Documentation/netlink/specs/nftables.yaml
index 826d3441b..4b1f5b107 100644
--- a/Documentation/netlink/specs/nftables.yaml
+++ b/Documentation/netlink/specs/nftables.yaml
@@ -1454,15 +1454,24 @@ sub-messages:
       -
         value: immediate
         attribute-set: expr-immediate-attrs
+      -
+        value: log
+        attribute-set: log-attrs
       -
         value: lookup
         attribute-set: expr-lookup-attrs
+      -
+        value: match
+        attribute-set: compat-match-attrs
       -
         value: meta
         attribute-set: expr-meta-attrs
       -
         value: nat
         attribute-set: expr-nat-attrs
+      -
+        value: numgen
+        attribute-set: numgen-attrs
       -
         value: objref
         attribute-set: expr-objref-attrs
@@ -1472,6 +1481,9 @@ sub-messages:
       -
         value: quota
         attribute-set: quota-attrs
+      -
+        value: range
+        attribute-set: range-attrs
       -
         value: reject
         attribute-set: expr-reject-attrs
@@ -1481,6 +1493,9 @@ sub-messages:
       -
         value: tproxy
         attribute-set: expr-tproxy-attrs
+        # There're more sub-messages to go:
+        #   grep -A10 nft_expr_type
+        # and look for .name\s*=\s*"..."
   -
     name: obj-data
     formats:
-- 
2.51.2

[PATCH v6 5/6] doc/netlink: nftables: Add getcompat operation

[Remy D. Farley]

Signed-off-by: Remy D. Farley <one-d-wide@protonmail.com>
---
 Documentation/netlink/specs/nftables.yaml | 25 +++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/Documentation/netlink/specs/nftables.yaml b/Documentation/netlink/specs/nftables.yaml
index 4b1f5b107..ce11312b9 100644
--- a/Documentation/netlink/specs/nftables.yaml
+++ b/Documentation/netlink/specs/nftables.yaml
@@ -1509,6 +1509,31 @@ 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:
+          attributes:
+            - name
+            - rev
+            - type
     -
       name: batch-begin
       doc: Start a batch of operations
-- 
2.51.2

[PATCH v6 6/6] doc/netlink: nftables: Fill out operation attributes

[Remy D. Farley]

Filled out operation attributes:
- newtable
- gettable
- deltable
- destroytable
- newchain
- getchain
- delchain
- destroychain
- newrule
- getrule
- getrule-reset
- delrule
- destroyrule
- newset
- getset
- delset
- destroyset
- newsetelem
- getsetelem
- getsetelem-reset
- delsetelem
- destroysetelem
- getgen
- newobj
- getobj
- delobj
- destroyobj
- newflowtable
- getflowtable
- delflowtable
- destroyflowtable

Signed-off-by: Remy D. Farley <one-d-wide@protonmail.com>
---
 Documentation/netlink/specs/nftables.yaml | 292 ++++++++++++++++++----
 1 file changed, 250 insertions(+), 42 deletions(-)

diff --git a/Documentation/netlink/specs/nftables.yaml b/Documentation/netlink/specs/nftables.yaml
index ce11312b9..973dcf8a0 100644
--- a/Documentation/netlink/specs/nftables.yaml
+++ b/Documentation/netlink/specs/nftables.yaml
@@ -1567,7 +1567,10 @@ operations:
         request:
           value: 0xa00
           attributes:
+            # Mentioned in nf_tables_newtable()
             - name
+            - flags
+            - userdata
     -
       name: gettable
       doc: Get / dump tables.
@@ -1577,11 +1580,21 @@ operations:
         request:
           value: 0xa01
           attributes:
+            # Mentioned in nf_tables_gettable()
             - name
         reply:
           value: 0xa00
-          attributes:
+          attributes: &get-table
+            # Mentioned in nf_tables_fill_table_info()
             - name
+            - use
+            - handle
+            - flags
+            - owner
+            - userdata
+      dump:
+        reply:
+          attributes: *get-table
     -
       name: deltable
       doc: Delete an existing table.
@@ -1590,8 +1603,10 @@ operations:
       do:
         request:
           value: 0xa02
-          attributes:
+          attributes: &del-table
+            # Mentioned in nf_tables_deltable()
             - name
+            - handle
     -
       name: destroytable
       doc: |
@@ -1602,8 +1617,7 @@ operations:
       do:
         request:
           value: 0xa1a
-          attributes:
-            - name
+          attributes: *del-table
     -
       name: newchain
       doc: Create a new chain.
@@ -1613,7 +1627,23 @@ operations:
         request:
           value: 0xa03
           attributes:
+            # Mentioned in nf_tables_newchain()
+            - table
+            - handle
+            - policy
+            - flags
+            # Mentioned in nf_tables_updchain()
+            - hook
             - name
+            - counters
+            - policy
+            # Mentioned in nf_tables_addchain()
+            - hook
+            - name
+            - counters
+            - userdata
+            # Mentioned in nft_chain_parse_hook()
+            - type
     -
       name: getchain
       doc: Get / dump chains.
@@ -1623,11 +1653,27 @@ operations:
         request:
           value: 0xa04
           attributes:
+            # Mentioned in nf_tables_getchain()
+            - table
             - name
         reply:
           value: 0xa03
-          attributes:
+          attributes: &get-chain
+            # Mentioned in nf_tables_fill_chain_info()
+            - table
             - name
+            - handle
+            - hook
+            - policy
+            - type
+            - flags
+            - counters
+            - id
+            - use
+            - userdata
+      dump:
+        reply:
+          attributes: *get-chain
     -
       name: delchain
       doc: Delete an existing chain.
@@ -1636,8 +1682,12 @@ operations:
       do:
         request:
           value: 0xa05
-          attributes:
+          attributes: &del-chain
+            # Mentioned in nf_tables_delchain()
+            - table
+            - handle
             - name
+            - hook
     -
       name: destroychain
       doc: |
@@ -1648,8 +1698,7 @@ operations:
       do:
         request:
           value: 0xa1b
-          attributes:
-            - name
+          attributes: *del-chain
     -
       name: newrule
       doc: Create a new rule.
@@ -1659,7 +1708,16 @@ operations:
         request:
           value: 0xa06
           attributes:
-            - name
+            # Mentioned in nf_tables_newrule()
+            - table
+            - chain
+            - chain-id
+            - handle
+            - position
+            - position-id
+            - expressions
+            - userdata
+            - compat
     -
       name: getrule
       doc: Get / dump rules.
@@ -1668,12 +1726,30 @@ operations:
       do:
         request:
           value: 0xa07
-          attributes:
-            - name
+          attributes: &get-rule-request
+            # Mentioned in nf_tables_getrule_single()
+            - table
+            - chain
+            - handle
         reply:
           value: 0xa06
+          attributes: &get-rule
+            # Mentioned in nf_tables_fill_rule_info()
+            - table
+            - chain
+            - handle
+            - position
+            - expressions
+            - userdata
+      dump:
+        request:
           attributes:
-            - name
+            # Mentioned in nf_tables_dump_rules_start()
+            - table
+            - chain
+        reply:
+          attributes: *get-rule
+
     -
       name: getrule-reset
       doc: Get / dump rules and reset stateful expressions.
@@ -1682,12 +1758,15 @@ operations:
       do:
         request:
           value: 0xa19
-          attributes:
-            - name
+          attributes: *get-rule-request
         reply:
           value: 0xa06
-          attributes:
-            - name
+          attributes: *get-rule
+      dump:
+        request:
+          attributes: *get-rule-request
+        reply:
+          attributes: *get-rule
     -
       name: delrule
       doc: Delete an existing rule.
@@ -1696,8 +1775,11 @@ operations:
       do:
         request:
           value: 0xa08
-          attributes:
-            - name
+          attributes: &del-rule
+            - table
+            - chain
+            - handle
+            - id
     -
       name: destroyrule
       doc: |
@@ -1707,8 +1789,7 @@ operations:
       do:
         request:
           value: 0xa1c
-          attributes:
-            - name
+          attributes: *del-rule
     -
       name: newset
       doc: Create a new set.
@@ -1718,7 +1799,24 @@ operations:
         request:
           value: 0xa09
           attributes:
+            # Mentioned in nf_tables_newset()
+            - table
             - name
+            - key-len
+            - id
+            - key-type
+            - key-len
+            - flags
+            - data-type
+            - data-len
+            - obj-type
+            - timeout
+            - gc-interval
+            - policy
+            - desc
+            - table
+            - name
+            - userdata
     -
       name: getset
       doc: Get / dump sets.
@@ -1728,11 +1826,35 @@ operations:
         request:
           value: 0xa0a
           attributes:
+            # Mentioned in nf_tables_getset()
+            - table
             - name
         reply:
           value: 0xa09
-          attributes:
+          attributes: &get-set
+            # Mentioned in nf_tables_fill_set()
+            - table
             - name
+            - handle
+            - flags
+            - key-len
+            - key-type
+            - data-type
+            - data-len
+            - obj-type
+            - gc-interval
+            - policy
+            - userdata
+            - desc
+            - expr
+            - expressions
+      dump:
+        request:
+          attributes:
+            # Mentioned in nf_tables_getset()
+            - table
+        reply:
+          attributes: *get-set
     -
       name: delset
       doc: Delete an existing set.
@@ -1741,7 +1863,10 @@ operations:
       do:
         request:
           value: 0xa0b
-          attributes:
+          attributes: &del-set
+            # Mentioned in nf_tables_delset()
+            - table
+            - handle
             - name
     -
       name: destroyset
@@ -1752,8 +1877,7 @@ operations:
       do:
         request:
           value: 0xa1d
-          attributes:
-            - name
+          attributes: *del-set
     -
       name: newsetelem
       doc: Create a new set element.
@@ -1763,7 +1887,11 @@ operations:
         request:
           value: 0xa0c
           attributes:
-            - name
+            # Mentioned in nf_tables_newsetelem()
+            - table
+            - set
+            - set-id
+            - elements
     -
       name: getsetelem
       doc: Get / dump set elements.
@@ -1773,11 +1901,27 @@ operations:
         request:
           value: 0xa0d
           attributes:
-            - name
+            # Mentioned in nf_tables_getsetelem()
+            - table
+            - set
+            - elements
         reply:
           value: 0xa0c
           attributes:
-            - name
+            # Mentioned in nf_tables_fill_setelem_info()
+            - elements
+      dump:
+        request:
+          attributes: &dump-set-request
+            # Mentioned in nft_set_dump_ctx_init()
+            - table
+            - set
+        reply:
+          attributes: &dump-set
+            # Mentioned in nf_tables_dump_set()
+            - table
+            - set
+            - elements
     -
       name: getsetelem-reset
       doc: Get / dump set elements and reset stateful expressions.
@@ -1787,11 +1931,20 @@ operations:
         request:
           value: 0xa21
           attributes:
-            - name
+            # Mentioned in nf_tables_getsetelem_reset()
+            - elements
         reply:
           value: 0xa0c
           attributes:
-            - name
+            # Mentioned in nf_tables_dumpreset_set()
+            - table
+            - set
+            - elements
+      dump:
+        request:
+          attributes: *dump-set-request
+        reply:
+          attributes: *dump-set
     -
       name: delsetelem
       doc: Delete an existing set element.
@@ -1800,8 +1953,11 @@ operations:
       do:
         request:
           value: 0xa0e
-          attributes:
-            - name
+          attributes: &del-setelem
+            # Mentioned in nf_tables_delsetelem()
+            - table
+            - set
+            - elements
     -
       name: destroysetelem
       doc: Delete an existing set element with destroy semantics.
@@ -1810,8 +1966,7 @@ operations:
       do:
         request:
           value: 0xa1e
-          attributes:
-            - name
+          attributes: *del-setelem
     -
       name: getgen
       doc: Get / dump rule-set generation.
@@ -1820,12 +1975,16 @@ operations:
       do:
         request:
           value: 0xa10
-          attributes:
-            - name
         reply:
           value: 0xa0f
-          attributes:
-            - name
+          attributes: &get-gen
+            # Mentioned in nf_tables_fill_gen_info()
+            - id
+            - proc-pid
+            - proc-name
+      dump:
+        reply:
+          attributes: *get-gen
     -
       name: newobj
       doc: Create a new stateful object.
@@ -1835,7 +1994,12 @@ operations:
         request:
           value: 0xa12
           attributes:
+            # Mentioned in nf_tables_newobj()
+            - type
             - name
+            - data
+            - table
+            - userdata
     -
       name: getobj
       doc: Get / dump stateful objects.
@@ -1845,11 +2009,29 @@ operations:
         request:
           value: 0xa13
           attributes:
+            # Mentioned in nf_tables_getobj_single()
             - name
+            - type
+            - table
         reply:
           value: 0xa12
-          attributes:
+          attributes: &obj-info
+            # Mentioned in nf_tables_fill_obj_info()
+            - table
             - name
+            - type
+            - handle
+            - use
+            - data
+            - userdata
+      dump:
+        request:
+          attributes:
+            # Mentioned in nf_tables_dump_obj_start()
+            - table
+            - type
+        reply:
+          attributes: *obj-info
     -
       name: delobj
       doc: Delete an existing stateful object.
@@ -1859,7 +2041,11 @@ operations:
         request:
           value: 0xa14
           attributes:
+            # Mentioned in nf_tables_delobj()
+            - table
             - name
+            - type
+            - handle
     -
       name: destroyobj
       doc: Delete an existing stateful object with destroy semantics.
@@ -1869,7 +2055,11 @@ operations:
         request:
           value: 0xa1f
           attributes:
+            # Mentioned in nf_tables_delobj()
+            - table
             - name
+            - type
+            - handle
     -
       name: newflowtable
       doc: Create a new flow table.
@@ -1879,7 +2069,11 @@ operations:
         request:
           value: 0xa16
           attributes:
+            # Mentioned in nf_tables_newflowtable()
+            - table
             - name
+            - hook
+            - flags
     -
       name: getflowtable
       doc: Get / dump flow tables.
@@ -1889,11 +2083,22 @@ operations:
         request:
           value: 0xa17
           attributes:
+            # Mentioned in nf_tables_getflowtable()
             - name
+            - table
         reply:
           value: 0xa16
-          attributes:
+          attributes: &flowtable-info
+            # Mentioned in nf_tables_fill_flowtable_info()
+            - table
             - name
+            - handle
+            - use
+            - flags
+            - hook
+      dump:
+        reply:
+          attributes: *flowtable-info
     -
       name: delflowtable
       doc: Delete an existing flow table.
@@ -1902,8 +2107,12 @@ operations:
       do:
         request:
           value: 0xa18
-          attributes:
+          attributes: &del-flowtable
+            # Mentioned in nf_tables_delflowtable()
+            - table
             - name
+            - handle
+            - hook
     -
       name: destroyflowtable
       doc: Delete an existing flow table with destroy semantics.
@@ -1912,8 +2121,7 @@ operations:
       do:
         request:
           value: 0xa20
-          attributes:
-            - name
+          attributes: *del-flowtable
 
 mcast-groups:
   list:
-- 
2.51.2

Re: [PATCH v6 5/6] doc/netlink: nftables: Add getcompat operation

[Paolo Abeni]

On 1/21/26 7:47 PM, Remy D. Farley wrote:
> Signed-off-by: Remy D. Farley <one-d-wide@protonmail.com>

Some (even minimal) description is needed in every change.

Thanks,

Paolo

Re: [PATCH v6 0/6] doc/netlink: Expand nftables specification

[Donald Hunter]

On Wed, 21 Jan 2026 at 18:47, Remy D. Farley <one-d-wide@protonmail.com> wrote:
>
> Getting out some changes I've accumulated while making nftables work
> with Rust netlink-bindings. Hopefully, this will be useful upstream.

Hi Remy,

Can you please cc the netfilter maintainers (and we should add
nftables.yaml to the NETFILTER entry in MAINTAINERS).

./scripts/get_maintainer.pl net/netfilter/nfnetlink.c
Pablo Neira Ayuso <pablo@netfilter.org> (maintainer:NETFILTER)
Florian Westphal <fw@strlen.de> (maintainer:NETFILTER)
Phil Sutter <phil@nwl.cc> (reviewer:NETFILTER)
...
netfilter-devel@vger.kernel.org (open list:NETFILTER)
coreteam@netfilter.org (open list:NETFILTER)
...

Re: [PATCH v6 1/6] doc/netlink: netlink-raw: Add max check

[Donald Hunter]

On Wed, 21 Jan 2026 at 18:47, Remy D. Farley <one-d-wide@protonmail.com> wrote:
>
> Add definitions for max check and len-or-limit type, the same as in other
> specifications.
>
> Suggested-by: Donald Hunter <donald.hunter@gmail.com>
> Signed-off-by: Remy D. Farley <one-d-wide@protonmail.com>

Reviewed-by: Donald Hunter <donald.hunter@gmail.com>

> ---
>  Documentation/netlink/netlink-raw.yaml | 11 ++++++++++-
>  1 file changed, 10 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/netlink/netlink-raw.yaml b/Documentation/netlink/netlink-raw.yaml
> index 0166a7e4a..dd98dda55 100644
> --- a/Documentation/netlink/netlink-raw.yaml
> +++ b/Documentation/netlink/netlink-raw.yaml
> @@ -19,6 +19,12 @@ $defs:
>      type: [ string, integer ]
>      pattern: ^[0-9A-Za-z_-]+( - 1)?$
>      minimum: 0
> +  len-or-limit:
> +    # literal int, const name, or limit based on fixed-width type
> +    # e.g. u8-min, u16-max, etc.
> +    type: [ string, integer ]
> +    pattern: ^[0-9A-Za-z_-]+$
> +    minimum: 0
>
>  # Schema for specs
>  title: Protocol
> @@ -270,7 +276,10 @@ properties:
>                      type: string
>                    min:
>                      description: Min value for an integer attribute.
> -                    type: integer
> +                    $ref: '#/$defs/len-or-limit'
> +                  max:
> +                    description: Max value for an integer attribute.
> +                    $ref: '#/$defs/len-or-limit'
>                    min-len:
>                      description: Min length for a binary attribute.
>                      $ref: '#/$defs/len-or-define'
> --
> 2.51.2
>
>

Re: [PATCH v6 2/6] doc/netlink: nftables: Add definitions

[Donald Hunter]

On Wed, 21 Jan 2026 at 18:47, Remy D. Farley <one-d-wide@protonmail.com> wrote:
>
> New enums/flags:
> - payload-base
> - range-ops
> - registers
> - numgen-types
> - log-level
> - log-flags
>
> Added missing enumerations:
> - bitwise-ops
>
> Annotated doc comment or associated enum:
> - bitwise-ops
>
> Signed-off-by: Remy D. Farley <one-d-wide@protonmail.com>
> ---
>  Documentation/netlink/specs/nftables.yaml | 157 +++++++++++++++++++++-
>  1 file changed, 154 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/netlink/specs/nftables.yaml b/Documentation/netlink/specs/nftables.yaml
> index 17ad707fa..87cd4d201 100644
> --- a/Documentation/netlink/specs/nftables.yaml
> +++ b/Documentation/netlink/specs/nftables.yaml
> @@ -66,9 +66,17 @@ definitions:
>      name: bitwise-ops
>      type: enum
>      entries:
> -      - bool
> -      - lshift
> -      - rshift
> +      -
> +        name: mask-xor  # aka bool (old name)
> +        doc: >-
> +          mask-and-xor operation used to implement NOT, AND, OR and XOR boolean
> +          operations
> +      # Spinx docutils display warning when interleaving attrsets with strings

No need for the comment here. Better to explain the refactor in the
patch description

> +      - name: lshift
> +      - name: rshift
> +      - name: and
> +      - name: or
> +      - name: xor

I'd prefer to see the list marker and attribute on separate lines, we
only use the compact format for pure lists of names.

>    -
>      name: cmp-ops
>      type: enum
> @@ -132,6 +140,12 @@ definitions:
>        - object
>        - concat
>        - expr
> +  -
> +    name: set-elem-flags
> +    type: flags
> +    entries:
> +      - interval-end
> +      - catchall
>    -
>      name: lookup-flags
>      type: flags
> @@ -225,6 +239,127 @@ definitions:
>        - icmp-unreach
>        - tcp-rst
>        - icmpx-unreach
> +  -
> +    name: reject-inet-code
> +    doc: These codes are mapped to real ICMP and ICMPv6 codes.
> +    type: enum
> +    entries:
> +      - icmpx-no-route
> +      - icmpx-port-unreach
> +      - icmpx-host-unreach
> +      - icmpx-admin-prohibited
> +  -
> +    name: payload-base
> +    type: enum
> +    entries:
> +      - link-layer-header
> +      - network-header
> +      - transport-header
> +      - inner-header
> +      - tun-header
> +  -
> +    name: range-ops
> +    doc: Range operator
> +    type: enum
> +    entries:
> +      - eq
> +      - neq
> +  -
> +    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:
> +      # Spinx docutils display warning when interleaving attrsets and strings

Same here, please remove sphinx comment and use the preferred list formatting.

> +      - name: reg-verdict
> +      - name: reg-1
> +      - name: reg-2
> +      - name: reg-3
> +      - name: reg-4
> +      - name: reg32-00
> +        value: 8
> +      - name: reg32-01
> +      - name: reg32-02
> +      - name: reg32-03
> +      - name: reg32-04
> +      - name: reg32-05
> +      - name: reg32-06
> +      - name: reg32-07
> +      - name: reg32-08
> +      - name: reg32-09
> +      - name: reg32-10
> +      - name: reg32-11
> +      - name: reg32-12
> +      - name: reg32-13
> +      - name: reg32-14
> +      - name: reg32-15

Re: [PATCH v6 3/6] doc/netlink: nftables: Update attribute sets

[Donald Hunter]

On Wed, 21 Jan 2026 at 18:47, Remy D. Farley <one-d-wide@protonmail.com> wrote:
>
> New attribute sets:
> - log-attrs
> - numgen-attrs
> - range-attrs
> - compat-target-attrs
> - compat-match-attrs
> - compat-attrs
>
> Added missing attributes:
> - table-attrs (pad, owner)
> - set-attrs (type, count)
>
> Added missing checks:
> - range-attrs
> - expr-bitwise-attrs
> - compat-target-attrs
> - compat-match-attrs
> - compat-attrs
>
> Annotated doc comment or associated enum:
> - batch-attrs
> - verdict-attrs
> - expr-payload-attrs
>
> Fixed byte order:
> - nft-counter-attrs
> - expr-counter-attrs
> - rule-compat-attrs
>
> Signed-off-by: Remy D. Farley <one-d-wide@protonmail.com>

Reviewed-by: Donald Hunter <donald.hunter@gmail.com>

Re: [PATCH v6 4/6] doc/netlink: nftables: Add sub-messages

[Donald Hunter]

On Wed, 21 Jan 2026 at 18:47, Remy D. Farley <one-d-wide@protonmail.com> wrote:
>
> New sub-messsages:
> - log
> - match
> - numgen
> - range
>
> Signed-off-by: Remy D. Farley <one-d-wide@protonmail.com>

Reviewed-by: Donald Hunter <donald.hunter@gmail.com>

Re: [PATCH v6 5/6] doc/netlink: nftables: Add getcompat operation

[Florian Westphal]

Remy D. Farley <one-d-wide@protonmail.com> wrote:
> Signed-off-by: Remy D. Farley <one-d-wide@protonmail.com>
> ---
>  Documentation/netlink/specs/nftables.yaml | 25 +++++++++++++++++++++++
>  1 file changed, 25 insertions(+)
> 
> diff --git a/Documentation/netlink/specs/nftables.yaml b/Documentation/netlink/specs/nftables.yaml
> index 4b1f5b107..ce11312b9 100644
> --- a/Documentation/netlink/specs/nftables.yaml
> +++ b/Documentation/netlink/specs/nftables.yaml
> @@ -1509,6 +1509,31 @@ 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

Whats the intent here?  nft_compat isn't used by nftables, this
is iptables-nft compatibility glue.

Re: [PATCH v6 5/6] doc/netlink: nftables: Add getcompat operation

[Remy D. Farley]

On Tuesday, January 27th, 2026 at 11:32, Florian Westphal <fw@strlen.de> wrote:

> Remy D. Farley one-d-wide@protonmail.com wrote:
> 
> > Signed-off-by: Remy D. Farley one-d-wide@protonmail.com
> > ---
> > Documentation/netlink/specs/nftables.yaml | 25 +++++++++++++++++++++++
> > 1 file changed, 25 insertions(+)
> > 
> > diff --git a/Documentation/netlink/specs/nftables.yaml b/Documentation/netlink/specs/nftables.yaml
> > index 4b1f5b107..ce11312b9 100644
> > --- a/Documentation/netlink/specs/nftables.yaml
> > +++ b/Documentation/netlink/specs/nftables.yaml
> > @@ -1509,6 +1509,31 @@ 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
> 
> 
> Whats the intent here? nft_compat isn't used by nftables, this
> is iptables-nft compatibility glue.

I noticed getcompat operation used by `nft list ruleset` command, and it
doesn't seem to be defined anywhere else. Should I re/move it?

Re: [PATCH v6 5/6] doc/netlink: nftables: Add getcompat operation

[Florian Westphal]

Remy D. Farley <one-d-wide@protonmail.com> wrote:
> > Whats the intent here? nft_compat isn't used by nftables, this
> > is iptables-nft compatibility glue.
> 
> I noticed getcompat operation used by `nft list ruleset` command, and it
> doesn't seem to be defined anywhere else. Should I re/move it?

Its used by compatibility mode, it requires an nft binary linked
to libxtables, native nftables doesn't need it.

I would prefer not to mention its existence.

Re: [PATCH v6 5/6] doc/netlink: nftables: Add getcompat operation

[Remy D. Farley]

On Tuesday, January 27th, 2026 at 12:33, Florian Westphal <fw@strlen.de> wrote:

> Remy D. Farley one-d-wide@protonmail.com wrote:
> 
> > > Whats the intent here? nft_compat isn't used by nftables, this
> > > is iptables-nft compatibility glue.
> > 
> > I noticed getcompat operation used by `nft list ruleset` command, and it
> > doesn't seem to be defined anywhere else. Should I re/move it?
> 
> 
> Its used by compatibility mode, it requires an nft binary linked
> to libxtables, native nftables doesn't need it.
> 
> I would prefer not to mention its existence.

Ah, I see. Netlink-bindings have a tool to decode netlink communication, so
it's a bit awkward to show a bunch of unkown-operations on a common command.
I'm fine keeping it downstream.

Re: [PATCH v6 5/6] doc/netlink: nftables: Add getcompat operation

[Florian Westphal]

Remy D. Farley <one-d-wide@protonmail.com> wrote:
> > Its used by compatibility mode, it requires an nft binary linked
> > to libxtables, native nftables doesn't need it.
> > 
> > I would prefer not to mention its existence.
> 
> Ah, I see. Netlink-bindings have a tool to decode netlink communication, so
> it's a bit awkward to show a bunch of unkown-operations on a common command.
> I'm fine keeping it downstream.

No, showing unknown-operations is even worse.
Maybe just document in commit message that this is to avoid
clutter and present something more readable.

And perhaps mention that this is only for iptables-nft in the yaml file too.
(nft uses it on 'nft list' only if it encounters a rule added by iptables-nft).

Re: [PATCH v6 5/6] doc/netlink: nftables: Add getcompat operation

[Remy D. Farley]

On Tuesday, January 27th, 2026 at 13:00, Florian Westphal <fw@strlen.de> wrote:

> Remy D. Farley one-d-wide@protonmail.com wrote:
> 
> > > Its used by compatibility mode, it requires an nft binary linked
> > > to libxtables, native nftables doesn't need it.
> > > 
> > > I would prefer not to mention its existence.
> > 
> > Ah, I see. Netlink-bindings have a tool to decode netlink communication, so
> > it's a bit awkward to show a bunch of unkown-operations on a common command.
> > I'm fine keeping it downstream.
> 
> 
> No, showing unknown-operations is even worse.
> Maybe just document in commit message that this is to avoid
> clutter and present something more readable.
> 
> And perhaps mention that this is only for iptables-nft in the yaml file too.
> (nft uses it on 'nft list' only if it encounters a rule added by iptables-nft).

Do you mean to still add getcompat operation to spec in the kernel tree?
In case I misrepresented it, netlink-bindings is not a kernel project. And
AFACT, this issue isn't relevant for ynl C library, as it would only try to
decodes messages from operations you sent.

https://github.com/one-d-wide/netlink-bindings

Re: [PATCH v6 5/6] doc/netlink: nftables: Add getcompat operation

[Florian Westphal]

Remy D. Farley <one-d-wide@protonmail.com> wrote:
> > And perhaps mention that this is only for iptables-nft in the yaml file too.
> > (nft uses it on 'nft list' only if it encounters a rule added by iptables-nft).
> 
> Do you mean to still add getcompat operation to spec in the kernel tree?
> In case I misrepresented it, netlink-bindings is not a kernel project. And
> AFACT, this issue isn't relevant for ynl C library, as it would only try to
> decodes messages from operations you sent.

Oh, indeed, I misunderstood.  In that case I think its better to not add
it to the yaml spec.