[PATCH 4/7] doc: add overall description of the ruleset evaluation

[Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>]

Signed-off-by: Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
---
 doc/nft.txt | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/doc/nft.txt b/doc/nft.txt
index f52b7fef..4bbb6b56 100644
--- a/doc/nft.txt
+++ b/doc/nft.txt
@@ -560,6 +560,85 @@ table inet filter {
 nft delete rule inet filter input handle 5
 -------------------------
 
+OVERALL EVALUATION OF THE RULESET
+---------------------------------
+This is a summary of how the ruleset is evaluated.
+
+* Even if a packet is accepted by the ruleset (and thus by netfilter), it may
+  still get discarded by other means, for example Linux generally ignores
+  various ICMP types and are sysctl options lik
+  `net.ipv{4,6}.conf.*.forwarding` or `net.ipv4.conf.*.rp_filter`.
+* With respect to the evaluation tables don’t matter at all and are not known by
+  netfilter.
+  They’re merely used to structure the ruleset.
+* Packets traverse the network stack and at various hooks they’re evaluated by
+  any base chains attached to these hooks.
+* Base chains may call regular chains and regular chains may call other regular
+  chains (via *jump* or *goto* verdicts), in which case evaluation continues in
+  the called chain.
+  Base chains themsevlves cannot be called and only chains of the same table can
+  be called.
+* For each hook, the attached chains are evaluated in order of their priorities
+  (with chains with lower priority values being evaluated before those with
+  higher values and the order of chains with the same value being undefined).
+* An *accept* verdict (including an implict one via the base chain’s policy,
+  even if caused in certain cases by a *return* verdict) ends the evaluation of
+  the current base chain and any regular chains called from that.
+  It accepts the packet only with respect to the current base chain, which does
+  not mean that the packet is ultimately accepted.
+  Any other base chain (or regular chain called by such) with a higher priority
+  of the same hook as well as any other base chain (or regular chain called by
+  such) of any later hook may still utlimately *deny*/*reject* the packet with
+  an according verdict (with consequences as described below for
+  *deny*/*reject*).
+  Thus and merely from netfilter’s point of view, a packet is only accepted if
+  none of the chains (regardless of their tables) that are attached to any of
+  the respectively relevant hooks issues a *deny*/*reject* verdict (be it
+  explicitly or implicitly by policy) and if there’s at least on *accept*
+  verdict (be it explicitly or implicitly by policy).
+  In that, the ordering	of the various base chains per hook via their priorities
+  matters (with respect to the packets utlimate fate) only in so far, if any of
+  then would modify the packet or its meta data and that has an influence on the
+  verdicts – if not, the ordering shouldn’t matter (except for performance).
+* A *drop*/*reject* verdict (including an implict one via the base chain’s
+  policy even if caused in certain cases by a *return* verdict) immediately ends
+  the evaluation of the whole ruleset and ultimately drops/rejects the packet.
+  Unlike with an *accept* verdict, no further chains of any hook and regardless
+  of their table get evaluated and it’s therefore not possible to have an
+  *drop*/*reject* verdict overturned.
+  Thus, if any base chain uses drop as it’s policy, the same base chain or any
+  regular chain directly or indirectly called by it must accept a packet or it
+  is ensured to be ultimately dropped by it.
+* A *jump* verdict causes evaluation to continue at the first rule of the
+  regular chain it calls. Called chains must be of the same table and cannot be
+  base chains.
+  If no other verdict is issued in the called chain and if all rules of that
+  have been evaluated, evaluation will continue with the next rule after the
+  calling rule of the calling chain.
+  That is, reaching the end of the called chain causes a “jump back to the
+  calling chain” respectively an implicit *return* verdict.
+  Other verdicts are processed as described above and below.
+* A *goto* verdict causes evaluation to continue at the first rule of the
+  regular chain it calls. Called chains must be of the same table and cannot be
+  base chains.
+  If no other verdict is issued in the called chain and if all rules of that
+  have been evaluated, evaluation of the current base chain and the regular
+  chains called by it end with an implicit verdict of the base chain’s policy.
+  That is, unlike with *jump*, reaching the end of the called chain does not
+  cause a “jump back to the calling chain”.
+  Other verdicts are processed as described above and below.
+* A *return* verdict’s processing depend upon in which chain it is issued.
+  In a regular chain that was called via *jump* it ends evaluation of that chain
+  and return to the calling chain as described above.
+  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.
+* All verdicts described above (that is: *accept*, *drop*, *reject*, *jump*,
+  *goto* and *return*) also end the evaluation of any later statements in their
+  respective rules (or even cause an error when loadin such rules) with the
+  exception of the `comment` statement.
+  That is, for example in `… counter accept` the `counter` statement is
+  processed, but in `… accept counter` it is not.
+
 SETS
 ----
 nftables offers two kinds of set concepts. Anonymous sets are sets that have no
-- 
2.51.0