Document anonymous chain creation

Document anonymous chain creation

[Folsk Pratima]

Access to the wiki is restricted, so I write here. On this page
https://wiki.nftables.org/wiki-nftables/index.php/Jumping_to_chain
and also in the nft(8), document the possibility of creating anonymous
chains when using `jump` and `goto` statements. The most basic example
is this

table inet doc {
    chain inbound {
        type filter hook input priority filter; policy accept
        counter jump {
            counter accept
        }
        counter goto {
            counter accept
        }
    }
}

The commit which implements the functionality is

c330152b7f7779f15dba3e0862bf5616e7cb3eab

Re: Document anonymous chain creation

[Phil Sutter]

On Wed, Jun 04, 2025 at 10:29:15AM -0000, Folsk Pratima wrote:
> Access to the wiki is restricted, so I write here. On this page

Did you try requesting a user account?

For the time being, you could add the missing documentation to nft man
page and submit a patch. I'll gladly help with that and review results!

Thanks, Phil

Re: Document anonymous chain creation

[Folsk Pratima]

[-- Attachment #1: Type: text/plain, Size: 233 bytes --]

On Wed, 4 Jun 2025 15:52:35 +0200
Phil Sutter <phil@nwl.cc> wrote:
>Did you try requesting a user account?
Frankly, I do not know how.

>you could add the missing documentation to nft man page and submit a
>patch
See the attachment.

[-- Attachment #2: 0001-document-anonymous-chain-creation.patch --]
[-- Type: text/x-patch, Size: 1093 bytes --]

diff --git a/doc/nft.txt b/doc/nft.txt
index c1bb4997..1be2fbac 100644
--- a/doc/nft.txt
+++ b/doc/nft.txt
@@ -397,7 +397,8 @@ CHAINS
 Chains are containers for rules. They exist in two kinds, base chains and
 regular chains. A base chain is an entry point for packets from the networking
 stack, a regular chain may be used as jump target and is used for better rule
-organization.
+organization. Regular chains can be anonymous, see *VERDICT STATEMENT* examples
+for details.
 
 [horizontal]
 *add*:: Add a new chain in the specified table. When a hook and priority value
diff --git a/doc/statements.txt b/doc/statements.txt
index 74af1d1a..384fda51 100644
--- a/doc/statements.txt
+++ b/doc/statements.txt
@@ -42,6 +42,9 @@ resumes with the next base chain hook, not the rule following the queue verdict.
 
 filter input iif eth0 ip saddr 192.168.0.0/24 jump from_lan
 filter input iif eth0 drop
+
+# jump and goto statements support anonymous chain creation
+filter input iif "eth0" jump { ip saddr 192.168.0.0/24 drop ; udp dport domain drop ; }
 -------------------
 
 PAYLOAD STATEMENT

Re: Document anonymous chain creation

[Phil Sutter]

[-- Attachment #1: Type: text/plain, Size: 685 bytes --]

On Wed, Jun 04, 2025 at 03:46:04PM -0000, Folsk Pratima wrote:
> On Wed, 4 Jun 2025 15:52:35 +0200
> Phil Sutter <phil@nwl.cc> wrote:
> >Did you try requesting a user account?
> Frankly, I do not know how.

Oh, indeed. The main page merely states to send "comments" to
netfilter@vger.kernel.org list. I guess you could send diffs to page
source, but it's indeed pretty cumbersome.

Pablo, can we have moderated users? Or was moderation just too much
trouble?

> >you could add the missing documentation to nft man page and submit a
> >patch
> See the attachment.

Thanks! I think we need to update the synopsis as well. What do you
think of my extra (attached) to yours?

Cheers, Phil

[-- Attachment #2: extra.diff --]
[-- Type: text/plain, Size: 1985 bytes --]

diff --git a/doc/statements.txt b/doc/statements.txt
index 79a01384660f6..6d9db011c3fa1 100644
--- a/doc/statements.txt
+++ b/doc/statements.txt
@@ -3,8 +3,12 @@ VERDICT STATEMENT
 The verdict statement alters control flow in the ruleset and issues policy decisions for packets.
 
 [verse]
+____
 {*accept* | *drop* | *queue* | *continue* | *return*}
-{*jump* | *goto*} 'chain'
+{*jump* | *goto*} 'CHAIN'
+
+'CHAIN' := 'chain_name' | *{* 'statement' ... *}*
+____
 
 *accept* and *drop* are absolute verdicts -- they terminate ruleset evaluation immediately.
 
@@ -26,15 +30,20 @@ resumes with the next base chain hook, not the rule following the queue verdict.
 *return*:: Return from the current chain and continue evaluation at the
  next rule in the last chain. If issued in a base chain, it is equivalent to the
  base chain policy.
-*jump* 'chain':: Continue evaluation at the first rule in 'chain'. The current
+*jump* 'CHAIN':: Continue evaluation at the first rule in 'CHAIN'. The current
  position in the ruleset is pushed to a call stack and evaluation will continue
  there when the new chain is entirely evaluated or a *return* verdict is issued.
  In case an absolute verdict is issued by a rule in the chain, ruleset evaluation
  terminates immediately and the specific action is taken.
-*goto* 'chain':: Similar to *jump*, but the current position is not pushed to the
+*goto* 'CHAIN':: Similar to *jump*, but the current position is not pushed to the
  call stack, meaning that after the new chain evaluation will continue at the last
  chain instead of the one containing the goto statement.
 
+Note that an alternative to specifying the name of an existing, regular chain
+in 'CHAIN' is to specify an anonymous chain ad-hoc. Like with anonymous sets,
+it can't be referenced from another rule and will be removed along with the
+rule containing it.
+
 .Using verdict statements
 -------------------
 # process packets from eth0 and the internal network in from_lan

Re: Document anonymous chain creation

[Folsk Pratima]

[-- Attachment #1: Type: text/plain, Size: 422 bytes --]

On Wed, 4 Jun 2025 18:51:23 +0200
Phil Sutter <phil@nwl.cc> wrote:
> Thanks! I think we need to update the synopsis as well. What do you
> think of my extra (attached) to yours?
Good. See the attachment for a bit of style improvement. Removed
the quotes I put around eth0 to look uniform with the previous
examples. Also did not like how 'Note that' sounds, as if anonymous
chains are something unimportant or accidental.

[-- Attachment #2: 0003-document-anonymous-chain-creation-improve-style.patch --]
[-- Type: text/x-patch, Size: 1319 bytes --]

diff --git a/doc/statements.txt b/doc/statements.txt
index ac8b15ec..0b8c4ccb 100644
--- a/doc/statements.txt
+++ b/doc/statements.txt
@@ -39,10 +39,10 @@ resumes with the next base chain hook, not the rule following the queue verdict.
  call stack, meaning that after the new chain evaluation will continue at the last
  chain instead of the one containing the goto statement.
 
-Note that an alternative to specifying the name of an existing, regular chain
-in 'CHAIN' is to specify an anonymous chain ad-hoc. Like with anonymous sets,
-it can't be referenced from another rule and will be removed along with the
-rule containing it.
+An alternative to specifying the name of an existing, regular chain in 'CHAIN'
+is to specify an anonymous chain ad-hoc. Like with anonymous sets, it can't be
+referenced from another rule and will be removed along with the rule containing
+it.
 
 .Using verdict statements
 -------------------
@@ -53,7 +53,7 @@ filter input iif eth0 ip saddr 192.168.0.0/24 jump from_lan
 filter input iif eth0 drop
 
 # jump and goto statements support anonymous chain creation
-filter input iif "eth0" jump { ip saddr 192.168.0.0/24 drop ; udp dport domain drop ; }
+filter input iif eth0 jump { ip saddr 192.168.0.0/24 drop ; udp dport domain drop ; }
 -------------------
 
 PAYLOAD STATEMENT

Re: Document anonymous chain creation

[Phil Sutter]

On Wed, Jun 04, 2025 at 05:32:06PM -0000, Folsk Pratima wrote:
> On Wed, 4 Jun 2025 18:51:23 +0200
> Phil Sutter <phil@nwl.cc> wrote:
> > Thanks! I think we need to update the synopsis as well. What do you
> > think of my extra (attached) to yours?
> Good. See the attachment for a bit of style improvement. Removed
> the quotes I put around eth0 to look uniform with the previous
> examples. Also did not like how 'Note that' sounds, as if anonymous
> chains are something unimportant or accidental.

ACK! Formally submitted now, will push it out in the next few days
unless someone complains. Thanks for your input!

Cheers, Phil