* [PATCH] doc/netlink: Expand nftables specification
@ 2025-10-02 18:50 Remy D. Farley
2025-10-02 22:11 ` Jakub Kicinski
` (2 more replies)
0 siblings, 3 replies; 9+ messages in thread
From: Remy D. Farley @ 2025-10-02 18:50 UTC (permalink / raw)
To: Donald Hunter, Jakub Kicinski, netdev; +Cc: Remy D. Farley
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 .
Signed-off-by: Remy D. Farley <one-d-wide@protonmail.com>
---
Documentation/netlink/specs/nftables.yaml | 433 ++++++++++++++++++++--
1 file changed, 408 insertions(+), 25 deletions(-)
diff --git a/Documentation/netlink/specs/nftables.yaml b/Documentation/netlink/specs/nftables.yaml
index 2ee10d92d..fac0cf483 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,26 @@ 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
+ 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
@@ -1188,11 +1516,18 @@ operations:
request:
value: 0xa01
attributes:
- - name
+ # TODO:
reply:
value: 0xa00
+ attributes:
+ # TODO:
+ dump:
+ reply:
attributes:
- name
+ - use
+ - handle
+ - flags
-
name: deltable
doc: Delete an existing table.
@@ -1239,6 +1574,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 +1617,11 @@ operations:
request:
value: 0xa06
attributes:
- - name
+ - table
+ - chain
+ - expressions
+ - compat
+ reply:
-
name: getrule
doc: Get / dump rules.
@@ -1280,11 +1631,23 @@ operations:
request:
value: 0xa07
attributes:
- - name
+ # TODO:
reply:
value: 0xa06
attributes:
- - name
+ # TODO:
+ dump:
+ request:
+ attributes:
+ - table
+ - chain
+ reply:
+ attributes:
+ - table
+ - chain
+ - handle
+ - position
+ - expressions
-
name: getrule-reset
doc: Get / dump rules and reset stateful expressions.
@@ -1294,11 +1657,13 @@ operations:
request:
value: 0xa19
attributes:
- - name
+ # TODO:
reply:
value: 0xa06
attributes:
- - name
+ # TODO:
+ dump:
+ reply:
-
name: delrule
doc: Delete an existing rule.
@@ -1308,7 +1673,7 @@ operations:
request:
value: 0xa08
attributes:
- - name
+ # TODO:
-
name: destroyrule
doc: |
@@ -1319,7 +1684,7 @@ operations:
request:
value: 0xa1c
attributes:
- - name
+ # TODO:
-
name: newset
doc: Create a new set.
@@ -1329,7 +1694,7 @@ operations:
request:
value: 0xa09
attributes:
- - name
+ # TODO:
-
name: getset
doc: Get / dump sets.
@@ -1339,11 +1704,17 @@ operations:
request:
value: 0xa0a
attributes:
- - name
+ # TODO:
reply:
value: 0xa09
attributes:
- - name
+ # TODO:
+ dump:
+ request:
+ attributes:
+ - table
+ reply:
+ # TODO:
-
name: delset
doc: Delete an existing set.
@@ -1374,7 +1745,7 @@ operations:
request:
value: 0xa0c
attributes:
- - name
+ # TODO:
-
name: getsetelem
doc: Get / dump set elements.
@@ -1384,11 +1755,13 @@ operations:
request:
value: 0xa0d
attributes:
- - name
+ # TODO:
reply:
value: 0xa0c
attributes:
- - name
+ # TODO:
+ dump:
+ reply:
-
name: getsetelem-reset
doc: Get / dump set elements and reset stateful expressions.
@@ -1398,11 +1771,13 @@ operations:
request:
value: 0xa21
attributes:
- - name
+ # TODO:
reply:
value: 0xa0c
attributes:
- - name
+ # TODO:
+ dump:
+ reply:
-
name: delsetelem
doc: Delete an existing set element.
@@ -1412,7 +1787,7 @@ operations:
request:
value: 0xa0e
attributes:
- - name
+ # TODO:
-
name: destroysetelem
doc: Delete an existing set element with destroy semantics.
@@ -1422,7 +1797,7 @@ operations:
request:
value: 0xa1e
attributes:
- - name
+ # TODO:
-
name: getgen
doc: Get / dump rule-set generation.
@@ -1432,11 +1807,15 @@ operations:
request:
value: 0xa10
attributes:
- - name
+ # TODO:
reply:
value: 0xa0f
attributes:
- - name
+ - id
+ - proc-pid
+ - proc-name
+ dump:
+ reply:
-
name: newobj
doc: Create a new stateful object.
@@ -1461,6 +1840,8 @@ operations:
value: 0xa12
attributes:
- name
+ dump:
+ reply:
-
name: delobj
doc: Delete an existing stateful object.
@@ -1505,6 +1886,8 @@ operations:
value: 0xa16
attributes:
- name
+ dump:
+ reply:
-
name: delflowtable
doc: Delete an existing flow table.
--
2.49.0
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH] doc/netlink: Expand nftables specification
2025-10-02 18:50 [PATCH] doc/netlink: Expand nftables specification Remy D. Farley
@ 2025-10-02 22:11 ` Jakub Kicinski
2025-10-03 17:51 ` Remy D. Farley
2025-10-06 8:27 ` Donald Hunter
2025-10-09 20:33 ` [PATCH] doc/netlink: Expand nftables specificaion Remy D. Farley
2 siblings, 1 reply; 9+ messages in thread
From: Jakub Kicinski @ 2025-10-02 22:11 UTC (permalink / raw)
To: Remy D. Farley; +Cc: Donald Hunter, netdev
On Thu, 02 Oct 2025 18:50:17 +0000 Remy D. Farley wrote:
> Getting out changes I've accumulated while making nftables spec to work with
> Rust netlink-bindings. Hopefully, this will be useful upstream.
Hi Remy!
Could you try running
make -C tools/net/ynl/ -j
in the kernel tree?
Looks like there is an issue either with this patch or the ReST
generator we have to render the docs. I get:
WARNING:root:Failed to parse ../../../../Documentation/netlink/specs/nftables.yaml.
WARNING:root:'doc'
And also the test bot spits out:
Sphinx parallel build error:
KeyError: 'doc'
https://netdev-3.bots.linux.dev/doc-build/results/323981/stderr
--
pw-bot: cr
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] doc/netlink: Expand nftables specification
2025-10-02 22:11 ` Jakub Kicinski
@ 2025-10-03 17:51 ` Remy D. Farley
2025-10-03 18:05 ` Jakub Kicinski
0 siblings, 1 reply; 9+ messages in thread
From: Remy D. Farley @ 2025-10-03 17:51 UTC (permalink / raw)
To: Jakub Kicinski; +Cc: Donald Hunter, netdev
On Thursday, October 2nd, 2025 at 10:11 PM, Jakub Kicinski <kuba@kernel.org> wrote:
> Could you try running
>
> make -C tools/net/ynl/ -j
>
> in the kernel tree?
Oops, will do :)
> Looks like there is an issue either with this patch or the ReST
> generator we have to render the docs. I get:
>
> WARNING:root:Failed to parse ../../../../Documentation/netlink/specs/nftables.yaml.
> WARNING:root:'doc'
This one was because of a missing doc comment in "getcompat" operation (fixed in v2).
Also, it caught another issue. Python yaml doesn't distinguish an empty
attrset/list and a null-value:
```yaml
dump: # attrset
reply: # null (but attrset expected in code)
# no attribute here => dump["reply"] is None
```
I think it's useful to have a machine readable mark to signal that the
operation supports dump flag, even though there're no attributes outlined yet.
I fixed it by simply checking for null in ynl_gen_rst.py .
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] doc/netlink: Expand nftables specification
2025-10-03 17:51 ` Remy D. Farley
@ 2025-10-03 18:05 ` Jakub Kicinski
0 siblings, 0 replies; 9+ messages in thread
From: Jakub Kicinski @ 2025-10-03 18:05 UTC (permalink / raw)
To: Remy D. Farley; +Cc: Donald Hunter, netdev
On Fri, 03 Oct 2025 17:51:54 +0000 Remy D. Farley wrote:
> Also, it caught another issue. Python yaml doesn't distinguish an empty
> attrset/list and a null-value:
>
> ```yaml
> dump: # attrset
> reply: # null (but attrset expected in code)
> # no attribute here => dump["reply"] is None
> ```
>
> I think it's useful to have a machine readable mark to signal that the
> operation supports dump flag, even though there're no attributes outlined yet.
> I fixed it by simply checking for null in ynl_gen_rst.py .
Hm, hm, hm. So for "do" we use empty replies to mean that the reply
_will actually arrive_ but it will have no attributes. Whether an
operation returns a reply or not cannot be changed once operation
was added without breaking uAPI. So the empty reply is a way for us
to "reserve" the reply because we think we may need it in the future.
Or at least that's what my faulty memory of the situation is.
What an empty dump reply is I do not know. How we could have a dump
enumerating objects without producing replies!? :$
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] doc/netlink: Expand nftables specification
2025-10-02 18:50 [PATCH] doc/netlink: Expand nftables specification Remy D. Farley
2025-10-02 22:11 ` Jakub Kicinski
@ 2025-10-06 8:27 ` Donald Hunter
2025-10-06 14:08 ` Donald Hunter
2025-10-09 20:33 ` [PATCH] doc/netlink: Expand nftables specificaion Remy D. Farley
2 siblings, 1 reply; 9+ messages in thread
From: Donald Hunter @ 2025-10-06 8:27 UTC (permalink / raw)
To: Remy D. Farley; +Cc: Jakub Kicinski, netdev
"Remy D. Farley" <one-d-wide@protonmail.com> writes:
> 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 .
Can you run
yamllint Documentation/netlink/specs
The patch adds several errors and warnings.
Cheers!
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH] doc/netlink: Expand nftables specification
2025-10-06 8:27 ` Donald Hunter
@ 2025-10-06 14:08 ` Donald Hunter
2025-10-09 20:24 ` Remy D. Farley
0 siblings, 1 reply; 9+ messages in thread
From: Donald Hunter @ 2025-10-06 14:08 UTC (permalink / raw)
To: Remy D. Farley; +Cc: Jakub Kicinski, netdev
On Mon, 6 Oct 2025 at 09:29, Donald Hunter <donald.hunter@gmail.com> wrote:
>
> "Remy D. Farley" <one-d-wide@protonmail.com> writes:
>
> > 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 .
>
> Can you run
>
> yamllint Documentation/netlink/specs
>
> The patch adds several errors and warnings.
>
> Cheers!
Can you also use the nftables schema with the python cli, or at least run:
./tools/net/ynl/pyynl/cli.py --spec Documentation/netlink/specs/nftables.yaml
(This is something we should automate as part of make -C tools/net/ynl)
The spec has a lot of schema errors to resolve. You'll also need
changes to the netlink-raw.yaml schema because it is missing the 'max'
check.
diff --git a/Documentation/netlink/netlink-raw.yaml
b/Documentation/netlink/netlink-raw.yaml
index 246fa07bccf6..9cb3cc78a0af 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'
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH] doc/netlink: Expand nftables specification
2025-10-06 14:08 ` Donald Hunter
@ 2025-10-09 20:24 ` Remy D. Farley
0 siblings, 0 replies; 9+ messages in thread
From: Remy D. Farley @ 2025-10-09 20:24 UTC (permalink / raw)
To: Donald Hunter; +Cc: Jakub Kicinski, netdev
On Friday, October 3rd, 2025 at 6:05 PM, Jakub Kicinski <kuba@kernel.org> wrote:
> Hm, hm, hm. So for "do" we use empty replies to mean that the reply
> will actually arrive but it will have no attributes. Whether an
> operation returns a reply or not cannot be changed once operation
> was added without breaking uAPI. So the empty reply is a way for us
> to "reserve" the reply because we think we may need it in the future.
>
> Or at least that's what my faulty memory of the situation is.
>
> What an empty dump reply is I do not know. How we could have a dump
> enumerating objects without producing replies!? :$
I spent some time annotating the missing attributes, so fixing the rst script
isn't required, at least for this patch. Thanks for clarifying though, I didn't
notice the distinction at first.
On Friday, October 3rd, 2025 at 9:04 PM, Jakub Kicinski <kuba@kernel.org> wrote:
> Please don't send a reply in a previous thread and 4 min later a new
> version of the patch :(
Sorry ._. I will use this (older) thread.
On Monday, October 6th, 2025 at 2:08 PM, Donald Hunter <donald.hunter@gmail.com> wrote:
> On Mon, 6 Oct 2025 at 09:29, Donald Hunter donald.hunter@gmail.com wrote:
> > Can you run
> >
> > yamllint Documentation/netlink/specs
> >
> > The patch adds several errors and warnings.
> >
> > Cheers!
>
>
> Can you also use the nftables schema with the python cli, or at least run:
>
> ./tools/net/ynl/pyynl/cli.py --spec Documentation/netlink/specs/nftables.yaml
>
> (This is something we should automate as part of make -C tools/net/ynl)
Done. All 3 are working in patch v3.
> The spec has a lot of schema errors to resolve. You'll also need
> changes to the netlink-raw.yaml schema because it is missing the 'max'
> check.
>
> diff --git a/Documentation/netlink/netlink-raw.yaml
> b/Documentation/netlink/netlink-raw.yaml
> index 246fa07bccf6..9cb3cc78a0af 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'
Thanks, will use. I would've otherwise ended up just removing these annotations :)
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH] doc/netlink: Expand nftables specificaion
2025-10-02 18:50 [PATCH] doc/netlink: Expand nftables specification Remy D. Farley
2025-10-02 22:11 ` Jakub Kicinski
2025-10-06 8:27 ` Donald Hunter
@ 2025-10-09 20:33 ` Remy D. Farley
2025-10-10 9:21 ` Donald Hunter
2 siblings, 1 reply; 9+ messages in thread
From: Remy D. Farley @ 2025-10-09 20:33 UTC (permalink / raw)
To: Donald Hunter, Jakub Kicinski, netdev; +Cc: Remy D. Farley
Getting out some changes I've accumulated while making nftables to work with
Rust netlink-bindings. Hopefully, this will be useful upstream.
This patch:
- Fills out missing attributes in operations.
- Adds missing annotations: dump ops, byte-order, checks.
- Adds some missing sub-options (and their associated attributes).
- Adds (copying over) documentation for some attributes/enum members.
- Adds "getcompat" operation.
- Adds max check in netlink-raw specification (suggested by Donald Hunter).
Signed-off-by: Remy D. Farley <one-d-wide@protonmail.com>
---
Documentation/netlink/netlink-raw.yaml | 11 +-
Documentation/netlink/specs/nftables.yaml | 656 ++++++++++++++++++++--
2 files changed, 617 insertions(+), 50 deletions(-)
diff --git a/Documentation/netlink/netlink-raw.yaml b/Documentation/netlink/netlink-raw.yaml
index 246fa07bc..9cb3cc78a 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'
diff --git a/Documentation/netlink/specs/nftables.yaml b/Documentation/netlink/specs/nftables.yaml
index cce88819b..38adb684e 100644
--- a/Documentation/netlink/specs/nftables.yaml
+++ b/Documentation/netlink/specs/nftables.yaml
@@ -4,7 +4,7 @@ name: nftables
protocol: netlink-raw
protonum: 12
-doc: >-
+doc: |
Netfilter nftables configuration over netlink.
definitions:
@@ -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
+ 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,19 +238,221 @@ 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:
-
name: genid
+ doc: generation ID for this changeset
type: u32
byte-order: big-endian
-
@@ -264,10 +479,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:
@@ -371,9 +594,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 +668,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
@@ -540,6 +768,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:
@@ -793,6 +1030,8 @@ attribute-sets:
type: u32
byte-order: big-endian
enum: bitwise-ops
+ checks:
+ max: 255
-
name: data
type: nest
@@ -814,6 +1053,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 +1069,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
@@ -915,7 +1161,7 @@ attribute-sets:
type: string
doc: Name of set to use
-
- name: set id
+ name: set-id
type: u32
byte-order: big-endian
doc: ID of set to use
@@ -982,38 +1228,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 +1338,59 @@ attribute-sets:
type: u32
byte-order: big-endian
doc: id of object map
+ -
+ # Defined 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
+ -
+ name: info
+ type: binary
+ -
+ # Defined 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 +1444,21 @@ 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 sub-messages to go:
+ # grep -A10 nft_expr_type
+ # and look for .name\s*=\s*"..."
-
name: obj-data
formats:
@@ -1145,6 +1472,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
@@ -1178,7 +1530,10 @@ operations:
request:
value: 0xa00
attributes:
+ # Mentioned in nf_tables_newtable()
- name
+ - flags
+ - userdata
-
name: gettable
doc: Get / dump tables.
@@ -1188,11 +1543,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.
@@ -1201,8 +1566,10 @@ operations:
do:
request:
value: 0xa02
- attributes:
+ attributes: &del-table
+ # Mentioned in nf_tables_deltable()
- name
+ - handle
-
name: destroytable
doc: |
@@ -1213,8 +1580,7 @@ operations:
do:
request:
value: 0xa1a
- attributes:
- - name
+ attributes: *del-table
-
name: newchain
doc: Create a new chain.
@@ -1224,7 +1590,21 @@ 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
-
name: getchain
doc: Get / dump chains.
@@ -1234,11 +1614,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.
@@ -1247,8 +1643,12 @@ operations:
do:
request:
value: 0xa05
- attributes:
+ attributes: &del-chain
+ # Mentioned in nf_tables_delchain()
+ - table
+ - handle
- name
+ - hook
-
name: destroychain
doc: |
@@ -1259,8 +1659,7 @@ operations:
do:
request:
value: 0xa1b
- attributes:
- - name
+ attributes: *del-chain
-
name: newrule
doc: Create a new rule.
@@ -1270,7 +1669,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.
@@ -1279,12 +1687,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.
@@ -1293,12 +1719,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.
@@ -1307,8 +1736,11 @@ operations:
do:
request:
value: 0xa08
- attributes:
- - name
+ attributes: &del-rule
+ - table
+ - chain
+ - handle
+ - id
-
name: destroyrule
doc: |
@@ -1318,8 +1750,7 @@ operations:
do:
request:
value: 0xa1c
- attributes:
- - name
+ attributes: *del-rule
-
name: newset
doc: Create a new set.
@@ -1329,7 +1760,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.
@@ -1339,11 +1787,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.
@@ -1352,7 +1824,10 @@ operations:
do:
request:
value: 0xa0b
- attributes:
+ attributes: &del-set
+ # Mentioned in nf_tables_delset()
+ - table
+ - handle
- name
-
name: destroyset
@@ -1363,8 +1838,7 @@ operations:
do:
request:
value: 0xa1d
- attributes:
- - name
+ attributes: *del-set
-
name: newsetelem
doc: Create a new set element.
@@ -1374,7 +1848,11 @@ operations:
request:
value: 0xa0c
attributes:
- - name
+ # Mentioned in nf_tables_newsetelem()
+ - table
+ - set
+ - set-id
+ - elements
-
name: getsetelem
doc: Get / dump set elements.
@@ -1384,11 +1862,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.
@@ -1398,11 +1892,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.
@@ -1411,8 +1914,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.
@@ -1421,8 +1927,7 @@ operations:
do:
request:
value: 0xa1e
- attributes:
- - name
+ attributes: *del-setelem
-
name: getgen
doc: Get / dump rule-set generation.
@@ -1431,12 +1936,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.
@@ -1446,7 +1955,12 @@ operations:
request:
value: 0xa12
attributes:
+ # Mentioned in nf_tables_newobj()
+ - type
- name
+ - data
+ - table
+ - userdata
-
name: getobj
doc: Get / dump stateful objects.
@@ -1456,11 +1970,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.
@@ -1470,7 +2002,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.
@@ -1480,7 +2016,11 @@ operations:
request:
value: 0xa1f
attributes:
+ # Mentioned in nf_tables_delobj()
+ - table
- name
+ - type
+ - handle
-
name: newflowtable
doc: Create a new flow table.
@@ -1490,7 +2030,11 @@ operations:
request:
value: 0xa16
attributes:
+ # Mentioned in nf_tables_newflowtable()
+ - table
- name
+ - hook
+ - flags
-
name: getflowtable
doc: Get / dump flow tables.
@@ -1500,11 +2044,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.
@@ -1513,8 +2068,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.
@@ -1523,8 +2082,7 @@ operations:
do:
request:
value: 0xa20
- attributes:
- - name
+ attributes: *del-flowtable
mcast-groups:
list:
--
2.49.0
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH] doc/netlink: Expand nftables specificaion
2025-10-09 20:33 ` [PATCH] doc/netlink: Expand nftables specificaion Remy D. Farley
@ 2025-10-10 9:21 ` Donald Hunter
0 siblings, 0 replies; 9+ messages in thread
From: Donald Hunter @ 2025-10-10 9:21 UTC (permalink / raw)
To: Remy D. Farley; +Cc: Jakub Kicinski, netdev
"Remy D. Farley" <one-d-wide@protonmail.com> writes:
> Getting out some changes I've accumulated while making nftables to work with
> Rust netlink-bindings. Hopefully, this will be useful upstream.
>
> This patch:
>
> - Fills out missing attributes in operations.
> - Adds missing annotations: dump ops, byte-order, checks.
> - Adds some missing sub-options (and their associated attributes).
> - Adds (copying over) documentation for some attributes/enum members.
> - Adds "getcompat" operation.
> - Adds max check in netlink-raw specification (suggested by Donald Hunter).
>
> Signed-off-by: Remy D. Farley <one-d-wide@protonmail.com>
Hi Remy,
Is this v3? It should say v3 in the subject and it should contain a list
of the changes since v2 and v1. It's hard for reviewers to follow what
is going on otherwise.
https://docs.kernel.org/process/submitting-patches.html#commentary
> On Friday, October 3rd, 2025 at 9:04 PM, Jakub Kicinski <kuba@kernel.org> wrote:
>> Please don't send a reply in a previous thread and 4 min later a new
>> version of the patch :(
You did it again, reply and new patch minutes apart. The commentary in
the reply could instead have been in the changelog of this patch.
> ---
> Documentation/netlink/netlink-raw.yaml | 11 +-
> Documentation/netlink/specs/nftables.yaml | 656 ++++++++++++++++++++--
> 2 files changed, 617 insertions(+), 50 deletions(-)
I think this should a 2 patch series since the schema update is a
logical change that is independent of the nftables.yaml changes.
Also, net-next is closed until Oct 13 so you should resubmit when net-next
is open again.
https://netdev.bots.linux.dev/net-next.html
I will review the rest of the nftables.yaml changes in the meantime.
Thanks,
Donald.
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2025-10-10 9:30 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2025-10-02 18:50 [PATCH] doc/netlink: Expand nftables specification Remy D. Farley
2025-10-02 22:11 ` Jakub Kicinski
2025-10-03 17:51 ` Remy D. Farley
2025-10-03 18:05 ` Jakub Kicinski
2025-10-06 8:27 ` Donald Hunter
2025-10-06 14:08 ` Donald Hunter
2025-10-09 20:24 ` Remy D. Farley
2025-10-09 20:33 ` [PATCH] doc/netlink: Expand nftables specificaion Remy D. Farley
2025-10-10 9:21 ` Donald Hunter
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).