- Include that `reject` behaves like `drop` with respect to ending the evaluations of rules (causing later statements to be not executed) and the whole ruleset (preventing any further evaluation of any other base chains with higher priorities at the same hook or any at later hooks. - Clarify that a terminating statement also prevents the execution of later statements in the same rule and give an example about that. - Correct that `accept` won’t terminate ruleset (which is generally used for the whole set of all chains, rules, etc.) but only that of the current base chain respectively any regular ones called from that. Indicate that `accept` only accepts the packet from the current base chain’s point of view. Clarify that not only chains of a later hook could still drop the packet, but also ones from the same hook if they have a higher priority. - With respect to `return`/`jump`/`goto`, remove the “call stack” which seems rather an implementation detail and simply mention that the calling position is remembered. Also don’t use the wording “last chain”, which seems ambiguous. If the called chain itself called another chain and evaluation just returned from that, that might be misunderstood as the (chronologically) “last” one. “Calling chain” should be clear. Also don’t use the wording “new chain” (the chain isn’t strictly speaking “new”) and some places where merely “chain” was used, with `'CHAIN'` as the symbol for the called chain. - For `return`, more clearly differentiate between the types of chains and added the missing description of `return` in a regular chain called via `goto`. - For `jump`/`goto`, clarify, that their called chains return when a `return` verdict is issued *in them* not just when any `return` verdict (for example in another sub-chain) is issued. - For `goto`, I intentionally listed the cases when evaluation does not return to the calling case - because I guess it might actually do so, namely when the called chain itself explicitly jumps or go(to)es back. - Various other minor improvements/clarifications to wording. Link: https://lore.kernel.org/netfilter-devel/3c7ddca7029fa04baa2402d895f3a594a6480a3a.camel@scientia.org/T/#t Signed-off-by: Christoph Anton Mitterer --- doc/statements.txt | 61 ++++++++++++++++++++++++++++++---------------- 1 file changed, 40 insertions(+), 21 deletions(-) diff --git a/doc/statements.txt b/doc/statements.txt index 6226713b..b085b3ab 100644 --- a/doc/statements.txt +++ b/doc/statements.txt @@ -10,34 +10,53 @@ ____ 'CHAIN' := 'chain_name' | *{* 'statement' ... *}* ____ -*accept* and *drop* are absolute verdicts -- they terminate ruleset evaluation immediately. +*accept* and *drop*/*reject* are absolute verdicts, which immediately terminate +the evaluation of the current rule, i.e. even any later statements of the +current rule won’t get executed. + +.*counter* will get executed: +------------------------------ +… counter accept +------------------------------ + +.*counter* won’t get executed: +------------------------------ +… accept counter +------------------------------ + +Further: [horizontal] -*accept*:: Terminate ruleset evaluation and accept the packet. -The packet can still be dropped later by another hook, for instance accept -in the forward hook still allows one to drop the packet later in the postrouting hook, -or another forward base chain that has a higher priority number and is evaluated -afterwards in the processing pipeline. -*drop*:: Terminate ruleset evaluation and drop the packet. -The drop occurs instantly, no further chains or hooks are evaluated. -It is not possible to accept the packet in a later chain again, as those -are not evaluated anymore for the packet. +*accept*:: Terminate the evaluation of the current base chain (and any regular +chains called from it) and accept the packet from their point of view. +The packet may however still be dropped/rejected by another chain with a higher +priority of the same hook or by any chain of a later hook. +For example an accept in the forward hook still allows one to drop the packet +later in the postrouting hook, or another forward base chain that has a higher +priority number and is evaluated afterwards in the processing pipeline. +*drop*/*reject*:: Terminate ruleset evaluation and drop/reject the packet. This +occurs instantly, no further chains of any hooks are evaluated and it is thus +not possible to again accept the packet in a later chain, as those 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. *continue*:: Continue ruleset 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. +*return*:: In a regular chain that was called via *jump*, end evaluation of that + chain and return to the calling chain, continuing evaluation there at the rule + after the calling rule. + In a regular chain that was called via *goto* or in a base chain, the *return* + verdict is equivalent to the base chain’s policy. +*jump* 'CHAIN':: Continue evaluation at the first rule of 'CHAIN'. The position + in the current chain is remembered and evaluation will continue there with the + next rule when 'CHAIN' is entirely evaluated or a *return* verdict is issued in + 'CHAIN' itself. + In case an absolute verdict is issued by a rule in 'CHAIN', evaluation + terminates as described above. +*goto* 'CHAIN':: Similar to *jump*, but the position in the current chain is not + remembered and evaluation will neihter return at the current chain when 'CHAIN' + is entirely evaluated nor when a *return* verdict is issued in 'CHAIN' itself. 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 -- 2.51.0