[PATCH nft v6 2/3] doc: fix/improve documentation of verdicts

[Florian Westphal <fw@strlen.de>]

From: Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>

- 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 the evaluation of the ruleset (which is
  generally used for the whole set of all chains, rules, etc.) but only that of
  the current base chain (and any regular chains 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.
- 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 <mail@christoph.anton.mitterer.name>
Signed-off-by: Florian Westphal <fw@strlen.de>
---
 doc/nft.txt        |  1 +
 doc/statements.txt | 24 ++++++++++++++----------
 2 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/doc/nft.txt b/doc/nft.txt
index d30481677c4d..4615c3ead8be 100644
--- a/doc/nft.txt
+++ b/doc/nft.txt
@@ -572,6 +572,7 @@ table inet filter {
 nft delete rule inet filter input handle 5
 -------------------------
 
+[[OVERALL_EVALUATION_OF_THE_RULESET]]
 OVERALL EVALUATION OF THE RULESET
 ---------------------------------
 This is a summary of how the ruleset is evaluated.
diff --git a/doc/statements.txt b/doc/statements.txt
index 6f438c047b86..5d197aeb0cee 100644
--- a/doc/statements.txt
+++ b/doc/statements.txt
@@ -10,18 +10,22 @@ ____
 'CHAIN' := 'chain_name' | *{* 'statement' ... *}*
 ____
 
-*accept* and *drop* are absolute verdicts -- they terminate ruleset evaluation immediately.
+*accept* and *drop* are absolute verdicts -- they terminate chain evaluation,
+as if the packet would have reached the end of the base chain with the equivalent
+policy decision set.  See <<OVERALL_EVALUATION_OF_THE_RULESET>> for more details.
 
 [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 evaluation early.
+ Evaluation continues in the next base chain of higher or possibly equal
+ priority from the same hook or in the first base chain of a later hook, if any.
+ This means the packet can still be dropped in another base chain as well as
+ any chain called from it.
+ For example, an *accept* verdict in a chain of the *forward* hook still allows one to
+ *drop* the packet in another *forward* hook base chain (or a user-defined chain called from it)
+ that has a higher priority number or in a chain attached to the *postrouting* hook.
+*drop*:: Immediately drop the packet and terminate ruleset evaluation.
+ No further evaluation takes place.  It is not possible to override a *drop*
+ 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.
-- 
2.51.0