path: root/doc/statements.txt
diff options
authorPhil Sutter <>2019-05-07 15:23:50 +0200
committerFlorian Westphal <>2019-05-08 16:32:01 +0200
commit590ba3efda281f3df125ede59fa547b30b97a643 (patch)
treeaacd0c65efab413ac4a0212e3d7cf0ecc2ba1d05 /doc/statements.txt
parent611a54199b72a0b02c9abc120b9488a4873dffeb (diff)
doc: Review man page synopses
Fix use of font typefaces: - *bold* for terminals - 'italic' for non-terminals - plain for meta-characters Apart from that: * Variable definitions require an equals sign * 'auto-merge' option in set spec does not take a parameter * List header fields in payload expressions instead of unexplained placeholder * Introduce non-terminals in some places to avoid repetitions or clarify syntax * Fix syntax for ip6 header expresssion example * Reorganize ct expression synopsis into four parts: 1) direction not allowed 2) direction optional 3) direction mandatory 4) direction and family mandatory * Add missing 'version' keyword to osf expression * Clarify verdict statements example topic * Add synopses for payload and exthdr statements * Fix typo: differv -> diffserv * Reorganize reject statement synopsis to point out which code type is required for which type arg * Counter statement requires either one of 'packets' or 'bytes' args or both, none is an invalid variant * Limit statement accepts a unit in burst, too * Improve language in limit statement description a bit Signed-off-by: Phil Sutter <> Signed-off-by: Florian Westphal <>
Diffstat (limited to 'doc/statements.txt')
1 files changed, 85 insertions, 40 deletions
diff --git a/doc/statements.txt b/doc/statements.txt
index d51e44c0..bc2f9449 100644
--- a/doc/statements.txt
+++ b/doc/statements.txt
@@ -3,8 +3,8 @@ VERDICT STATEMENT
The verdict statement alters control flow in the ruleset and issues policy decisions for packets.
-{accept | drop | queue | continue | return}
-{jump | goto} 'chain'
+{*accept* | *drop* | *queue* | *continue* | *return*}
+{*jump* | *goto*} 'chain'
*accept* and *drop* are absolute verdicts -- they terminate ruleset evaluation immediately.
@@ -35,7 +35,7 @@ resumes with the next base chain hook, not the rule following the queue verdict.
call stack, meaning that after the new chain evaluation will continue at the last
chain instead of the one containing the goto statement.
-.Verdict statements
+.Using verdict statements
# process packets from eth0 and the internal network in from_lan
# chain, drop all packets from eth0 with different source addresses.
@@ -46,8 +46,11 @@ filter input iif eth0 drop
+'payload_expression' *set* 'value'
The payload statement alters packet content. It can be used for example to
-set ip DSCP (differv) header field or ipv6 flow labels.
+set ip DSCP (diffserv) header field or ipv6 flow labels.
.route some packets instead of bridging
@@ -63,6 +66,9 @@ ip forward ip dscp set 42
+'extension_header_expression' *set* 'value'
The extension header statement alters packet content in variable-sized headers.
This can currently be used to alter the TCP Maximum segment size of packets,
similar to TCPMSS.
@@ -77,9 +83,9 @@ tcp flags syn tcp option maxseg size set rt mtu
-*log* [prefix 'quoted_string'] [level 'syslog-level'] [flags 'log-flags']
-*log* group 'nflog_group' [prefix 'quoted_string'] [queue-threshold 'value'] [snaplen 'size']
-*log* level audit
+*log* [*prefix* 'quoted_string'] [*level* 'syslog-level'] [*flags* 'log-flags']
+*log* *group* 'nflog_group' [*prefix* 'quoted_string'] [*queue-threshold* 'value'] [*snaplen* 'size']
+*log level audit*
The log statement enables logging of matching packets. When this statement is
used from a rule, the Linux kernel will print some information on all matching
@@ -154,8 +160,14 @@ ip6 filter output log flags all
-*reject* [ with {icmp | icmpv6 | icmpx} type {icmp_code | icmpv6_code | icmpx_code} ]
-*reject* [ with tcp reset ]
+*reject* [ *with* 'REJECT_WITH' ]
+'REJECT_WITH' := *icmp type* 'icmp_code' |
+ *icmpv6 type* 'icmpv6_code' |
+ *icmpx type* 'icmpx_code' |
+ *tcp reset*
A reject statement is used to send back an error packet in response to the
matched packet otherwise it is equivalent to drop so it is a terminating
@@ -190,14 +202,15 @@ COUNTER STATEMENT
A counter statement sets the hit count of packets along with the number of bytes.
-*counter* [ packets 'number' bytes 'number' ]
+*counter* *packets* 'number' *bytes* 'number'
+*counter* { *packets* 'number' | *bytes* 'number' }
The conntrack statement can be used to set the conntrack mark and conntrack labels.
-*ct* {mark | event | label | zone} set 'value'
+*ct* {*mark* | *event* | *label* | *zone*} *set* 'value'
The ct statement sets meta data associated with a connection. The zone id
has to be assigned before a conntrack lookup takes place, i.e. this has to be
@@ -254,7 +267,8 @@ META STATEMENT
A meta statement sets the value of a meta expression. The existing meta fields
are: priority, mark, pkttype, nftrace. +
-meta {mark | priority | pkttype | nftrace} set 'value' +
+*meta* {*mark* | *priority* | *pkttype* | *nftrace*} *set* 'value'
A meta statement sets meta data associated with a packet. +
@@ -279,13 +293,18 @@ ruleset packet tracing on/off. Use *monitor trace* command to watch traces|
-*limit* rate [over] 'packet_number' / {second | minute | hour | day} [burst 'packet_number' packets]
-*limit* rate [over] 'byte_number' {bytes | kbytes | mbytes} / {second | minute | hour | day | week} [burst 'byte_number' bytes]
+*limit rate* [*over*] 'packet_number' */* 'TIME_UNIT' [*burst* 'packet_number' *packets*]
+*limit rate* [*over*] 'byte_number' 'BYTE_UNIT' */* 'TIME_UNIT' [*burst* 'byte_number' 'BYTE_UNIT']
+'TIME_UNIT' := *second* | *minute* | *hour* | *day*
+'BYTE_UNIT' := *bytes* | *kbytes* | *mbytes*
A limit statement matches at a limited rate using a token bucket filter. A rule
using this statement will match until this limit is reached. It can be used in
-combination with the log statement to give limited logging. The over keyword,
-that is optional, makes it match over the specified rate.
+combination with the log statement to give limited logging. The optional
+*over* keyword makes it match over the specified rate.
.limit statement values
@@ -302,16 +321,23 @@ unsigned integer (32 bit)
-*snat* to address [:port] [persistent, random, fully-random]
-*snat* to address - address [:port - port] [persistent, random, fully-random]
-*snat* to { ip | ip6 } address - address [:port - port] [persistent, random ]
-*dnat* to address [:port] [persistent, random, fully-random]
-*dnat* to address [:port - port] [persistent, random ]
-*dnat* to { ip | ip6 } address [:port - port] [persistent, random ]
-*masquerade* to [:port] [persistent, random, fully-random]
-*masquerade* to [:port - port] [persistent, random, fully-random]
-*redirect* to [:port] [persistent, random, fully-random]
-*redirect* to [:port - port] [persistent, random, fully-random]
+*snat to* 'address' [*:*'port'] ['PRF_FLAGS']
+*snat to* 'address' *-* 'address' [*:*'port' *-* 'port'] ['PRF_FLAGS']
+*snat to* { *ip* | *ip6* } 'address' *-* 'address' [*:*'port' *-* 'port'] ['PR_FLAGS']
+*dnat to* 'address' [*:*'port'] ['PRF_FLAGS']
+*dnat to* 'address' [*:*'port' *-* 'port'] ['PR_FLAGS']
+*dnat to* { *ip* | *ip6* } 'address' [*:*'port' *-* 'port'] ['PR_FLAGS']
+*masquerade to* [*:*'port'] ['PRF_FLAGS']
+*masquerade to* [*:*'port' *-* 'port'] ['PRF_FLAGS']
+*redirect to* [*:*'port'] ['PRF_FLAGS']
+*redirect to* [*:*'port' *-* 'port'] ['PRF_FLAGS']
+'PR_FLAGS' := 'PR_FLAG' [*,* 'PR_FLAGS']
+'PRF_FLAG' := 'PR_FLAG' | *fully-random*
+'PR_FLAG' := *persistent* | *random*
The nat statements are only valid from nat chain types. +
@@ -407,16 +433,16 @@ is used as parameter. Tproxy matching requires another rule that ensures the
presence of transport protocol header is specified.
-tproxy to 'address' : 'port'
-tproxy to {'address' | : 'port'}
+*tproxy to* 'address'*:*'port'
+*tproxy to* {'address' | *:*'port'}
This syntax can be used in *ip/ip6* tables where network layer protocol is
-obvious. Either ip address or port can be specified, but at least one of them is
+obvious. Either IP address or port can be specified, but at least one of them is
-tproxy {ip | ip6} to 'address' [: 'port']
-tproxy to : 'port'
+*tproxy* {*ip* | *ip6*} *to* 'address'[*:*'port']
+*tproxy to :*'port'
This syntax can be used in *inet* tables. The *ip/ip6* parameter defines the
family the rule will match. The *address* parameter must be of this family.
@@ -463,7 +489,7 @@ A flow statement allows us to select what flows you want to accelerate
forwarding through layer 3 network stack bypass. You have to specify the
flowtable name where you want to offload this flow.
-*flow add* @flowtable
+*flow add @*'flowtable'
@@ -474,8 +500,14 @@ or re-inject the packet into the kernel. See libnetfilter_queue documentation
for details.
-*queue* [num 'queue_number'] [bypass]
-*queue* [num 'queue_number_from' - 'queue_number_to'] [bypass,fanout]
+*queue* [*num* 'queue_number'] [*bypass*]
+*queue* [*num* 'queue_number_from' - 'queue_number_to'] ['QUEUE_FLAGS']
+'QUEUE_FLAG' := *bypass* | *fanout*
.queue statement values
@@ -509,8 +541,8 @@ The dup statement is used to duplicate a packet and send the copy to a different
-*dup* to 'device'
-*dup* to 'address' device '*device*'
+*dup to* 'device'
+*dup to* 'address' *device* 'device'
.Dup statement values
@@ -544,7 +576,7 @@ The fwd statement is used to redirect a raw packet to another interface. It is
only available in the netdev family ingress hook. It is similar to the dup
statement except that no copy is made.
-*fwd* to 'device'
+*fwd to* 'device'
@@ -556,7 +588,7 @@ number of entries in set will not grow indefinitely). The set statement can be
used to e.g. create dynamic blacklists.
-{add | update} '@setname' { 'expression' [timeout 'timeout'] [comment 'string'] }
+{*add* | *update*} *@*'setname' *{* 'expression' [*timeout* 'timeout'] [*comment* 'string'] *}*
.Example for simple blacklist
@@ -588,7 +620,15 @@ MAP STATEMENT
The map statement is used to lookup data based on some specific input key.
-'expression' *map* *{* 'key' *:* 'value' [*,* 'key' *:* 'value' ...] *}*
+'expression' *map* *{* 'MAP_ELEMENTS' *}*
+'MAP_ELEMENT' := 'key' *:* 'value'
+The 'key' is a value returned by 'expression'.
+// XXX: Write about where map statement can be used (list of statements?)
.Using the map statement
@@ -609,7 +649,12 @@ The verdict map (vmap) statement works analogous to the map statement, but
contains verdicts as values.
-'expression' *vmap* *{* 'key' *:* 'verdict' [*,* 'key' *:* 'verdict' ...] *}*
+'expression' *vmap* *{* 'VMAP_ELEMENTS' *}*
+'VMAP_ELEMENT' := 'key' *:* 'verdict'
.Using the vmap statement