doc: Basic documentation of anonymous chains

Joint work with Folsk Pratima.

Signed-off-by: Folsk Pratima <folsk0pratima@cock.li>
Signed-off-by: Phil Sutter <phil@nwl.cc>

diff --git a/doc/nft.txt b/doc/nft.txt
index c1bb49970a22302525d0cccacc5df7b9eee7b9cf..1be2fbac05c1d2c78de1e39a7535fe16f53a6ff6 100644 (file)
--- 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 79a01384660f65d157b2f766f6402bdec1959e0f..f9460dd7fa77f1cd87f9136fe4f1c4dc34733627 100644 (file)
--- 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.
 
+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
@@ -42,6 +51,10 @@ 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