From: Christoph Anton Mitterer Date: Fri, 24 Oct 2025 01:36:45 +0000 (+0200) Subject: doc: fix/improve documentation of jump/goto/return X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=fe2e6f1975ba4b5a288e974552bcfd524a853401;p=thirdparty%2Fnftables.git doc: fix/improve documentation of jump/goto/return Overhaul the description of `jump`/`goto`/`return`. `jump` only explains what the statement causes from the point of view of the new chain (that is: not, how the returning works), which includes that an implicit `return` is issued at the end of the chain. `goto` is explained in reference to `jump`. `return` describes abstractly how the return position is determined and what happens if there’s no position to return to (but not for example where an implicit `return` is issued). List and explain verdict-like statements like `reject` which internally imply `accept` or `drop`. Further explain that with respect to evaluation these behave like their respectively implied verdicts. Link: https://lore.kernel.org/netfilter-devel/3c7ddca7029fa04baa2402d895f3a594a6480a3a.camel@scientia.org/T/#t Signed-off-by: Christoph Anton Mitterer Signed-off-by: Florian Westphal --- diff --git a/doc/statements.txt b/doc/statements.txt index e275ee39..815002a3 100644 --- a/doc/statements.txt +++ b/doc/statements.txt @@ -1,6 +1,6 @@ -VERDICT STATEMENT -~~~~~~~~~~~~~~~~~ -The verdict statement alters control flow in the ruleset and issues policy decisions for packets. +VERDICT STATEMENTS +~~~~~~~~~~~~~~~~~~ +The verdict statements alter control flow in the ruleset and issue policy decisions for packets. [verse] ____ @@ -25,25 +25,35 @@ are not evaluated anymore for the packet. *queue*:: Terminate ruleset evaluation and queue the packet to userspace. Userspace must provide a drop or accept verdict. In case of accept, processing resumes with the next base chain hook, not the rule following the queue verdict. +*jump* 'CHAIN':: Store the current position in the call stack of chains and + continue evaluation at the first rule of 'CHAIN'. + When the end of 'CHAIN' is reached, an implicit *return* verdict is issued. + When an absolute verdict is issued (respectively implied by a verdict-like + statement) in 'CHAIN', evaluation terminates as described above. +*goto* 'CHAIN':: Equal to *jump* except that the current position is not stored + in the call stack of chains. +*return*:: End evaluation of the current chain, pop the most recently added + position from the call stack of chains and continue evaluation after that + position. + When there’s no position to pop (which is the case when the current chain is + either the base chain or a regular chain that was reached solely via *goto* + verdicts) end evaluation of the current base chain (and any regular chains + called from it) using the base chain’s policy as implicit verdict. *continue*:: Continue evaluation with the next rule. This is the default behaviour in case a rule issues no 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 - 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 - call stack, meaning that after the new chain evaluation will continue at the last - chain instead of the one containing the goto statement. 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. +All the above applies analogously to statements that imply a verdict: +*redirect*, *dnat*, *snat* and *masquerade* internally issue an *accept* +verdict at the end of their respective actions. +*reject* and *synproxy* internally issue a *drop* verdict at the end of their +respective actions. +These statements thus behave like their implied verdicts, but with side effects. + .Using verdict statements ------------------- # process packets from eth0 and the internal network in from_lan