Skip to contentSkip to conversation

doc: Review man page synopses

PATCH New Phil Sutter 1 participant 1 message May 7, 2019 netfilter

lore
Share & tools
lore

Phil Sutter

author reviewer
#0 lore raw

PATCH 1/1 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

---
 doc/nft.txt                |  63 +++++++++----------
 doc/payload-expression.txt |  68 ++++++++++----------
 doc/primary-expression.txt |  18 +++---
 doc/stateful-objects.txt   |   8 +--
 doc/statements.txt         | 125 +++++++++++++++++++++++++------------
 5 files changed, 164 insertions(+), 118 deletions(-)
doc/nft.txt +31 -32
index a82a9c5f34447..4fca5c918b747 100644
@@ -135,7 +135,7 @@ matched by include statements.
 SYMBOLIC VARIABLES
 ~~~~~~~~~~~~~~~~~~
 [verse]
-*define* variable 'expr'
+*define* 'variable' *=* 'expr'
 *$variable*
 
 Symbolic variables can be defined using the *define* statement. Variable
@@ -231,7 +231,7 @@ layer 3 protocol handlers and it can be used for early filtering and policing.
 RULESET
 -------
 [verse]
-{list | flush} *ruleset* ['family']
+{*list* | *flush*} *ruleset* ['family']
 
 The *ruleset* keyword is used to identify the whole set of tables, chains, etc.
 currently in place in kernel. The following *ruleset* commands exist:
@@ -254,10 +254,10 @@ Effectively, this is the nft-equivalent of *iptables-save* and
 TABLES
 ------
 [verse]
-{add | create} *table* ['family'] 'table' [ {flags 'flags'} ]
-{delete | list | flush} *table* ['family'] 'table'
-list *tables*
-delete *table* ['family'] handle 'handle'
+{*add* | *create*} *table* ['family'] 'table' [*{ flags* 'flags' *; }*]
+{*delete* | *list* | *flush*} *table* ['family'] 'table'
+*list tables*
+*delete table* ['family'] *handle* 'handle'
 
 Tables are containers for chains, sets and stateful objects. They are identified
 by their address family and their name. The address family must be one of *ip*,
@@ -307,11 +307,11 @@ add table inet mytable
 CHAINS
 ------
 [verse]
-{add | create} *chain* ['family'] 'table' 'chain' [ { type 'type' hook 'hook' [device 'device'] priority 'priority' ; [policy 'policy' ;] }]
-{delete | list | flush} *chain* ['family'] 'table' 'chain'
-list *chains*
-delete *chain* ['family'] 'table' handle 'handle'
-rename *chain* ['family'] 'table' 'chain' 'newname'
+{*add* | *create*} *chain* ['family'] 'table' 'chain' [*{ type* 'type' *hook* 'hook' [*device* 'device'] *priority* 'priority' *;* [*policy* 'policy' *;*] *}*]
+{*delete* | *list* | *flush*} *chain* ['family'] 'table' 'chain'
+*list chains*
+*delete chain* ['family'] 'table' *handle* 'handle'
+*rename chain* ['family'] 'table' 'chain' 'newname'
 
 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
@@ -406,9 +406,9 @@ values are *accept* (which is the default) or *drop*.
 RULES
 -----
 [verse]
-{add | insert} *rule* ['family'] 'table' 'chain' [ handle 'handle' | index 'index' ] 'statement' ... [ comment 'comment' ]
-replace *rule* ['family'] 'table' 'chain' handle 'handle' 'statement' ... [ comment 'comment' ]
-delete *rule* ['family'] 'table' 'chain' handle 'handle'
+{*add* | *insert*} *rule* ['family'] 'table' 'chain' [*handle* 'handle' | *index* 'index'] 'statement' ... [*comment* 'comment']
+*replace rule* ['family'] 'table' 'chain' *handle* 'handle' 'statement' ... [*comment* 'comment']
+*delete rule* ['family'] 'table' 'chain' *handle* 'handle'
 
 Rules are added to chains in the given table. If the family is not specified, the
 ip family is used. Rules are constructed from two kinds of components according
@@ -485,14 +485,13 @@ The sets allowed_hosts and allowed_ports need to be created first. The next
 section describes nft set syntax in more detail.
 
 [verse]
-add *set* ['family'] 'table' 'set' { type 'type' ; [flags 'flags' ;] [timeout 'timeout' ;] [gc-interval 'gc-interval' ;] [elements = { 'element'[,...]
-} ;] [size size ;] [policy policy ;] [auto-merge auto-merge ;] }
-{delete | list | flush} *set* ['family'] 'table' 'set'
-list *sets*
-delete *set* ['family'] 'table' handle 'handle'
-{add | delete} *element* ['family'] 'table' 'set' { 'element'[,...] }
-
-Sets are elements containers of a user-defined data type, they are uniquely
+*add set* ['family'] 'table' 'set' *{ type* 'type' *;* [*flags* 'flags' *;*] [*timeout* 'timeout' *;*] [*gc-interval* 'gc-interval' *;*] [*elements = {* 'element'[*,* ...] *} ;*] [*size* 'size' *;*] [*policy* 'policy' *;*] [*auto-merge ;*] *}*
+{*delete* | *list* | *flush*} *set* ['family'] 'table' 'set'
+*list sets*
+*delete set* ['family'] 'table' *handle* 'handle'
+{*add* | *delete*} *element* ['family'] 'table' 'set' *{* 'element'[*,* ...] *}*
+
+Sets are element containers of a user-defined data type, they are uniquely
 identified by a user-defined name and attached to tables. Their behaviour can
 be tuned with the flags that can be specified at set creation time.
 
@@ -538,10 +537,10 @@ automatic merge of adjacent/overlapping set elements (only for interval sets) |
 MAPS
 -----
 [verse]
-add *map* ['family'] 'table' 'map' { type 'type' [flags 'flags' ;] [elements = {'elements'[,...] } ;] [size 'size' ;] [policy 'policy' ;] }
-list *maps*
-{delete | list | flush} *map* ['family'] 'table' 'map'
-{add | delete} *element* ['family'] 'table' 'map' { elements = { 'elements'[,...] } ; }
+*add map* ['family'] 'table' 'map' *{ type* 'type' [*flags* 'flags' *;*] [*elements = {* 'element'[*,* ...] *} ;*] [*size* 'size' *;*] [*policy* 'policy' *;*] *}*
+{*delete* | *list* | *flush*} *map* ['family'] 'table' 'map'
+*list maps*
+{*add* | *delete*} *element* ['family'] 'table' 'map' *{ elements = {* 'element'[*,* ...] *} ; }*
 
 Maps store data based on some specific key used as input. They are uniquely identified by a user-defined name and attached to tables.
 
@@ -578,8 +577,8 @@ string: performance [default], memory
 FLOWTABLES
 -----------
 [verse]
-{add | create} *flowtable* ['family'] 'table' 'flowtable' { hook 'hook' priority 'priority' ; devices = { 'device'[,...] } ; }
-{delete | list} *flowtable* ['family'] 'table' 'flowtable'
+{*add* | *create*} *flowtable* ['family'] 'table' 'flowtable' *{ hook* 'hook' *priority* 'priority' *; devices = {* 'device'[*,* ...] *} ; }*
+{*delete* | *list*} *flowtable* ['family'] 'table' 'flowtable'
 
 Flowtables allow you to accelerate packet forwarding in software. Flowtables
 entries are represented through a tuple that is composed of the input interface,
@@ -608,10 +607,10 @@ and subtraction can be used to set relative priority, e.g. filter + 5 equals to
 STATEFUL OBJECTS
 ----------------
 [verse]
-{add | delete | list | reset} type ['family'] 'table' 'object'
-delete type ['family'] 'table' handle 'handle'
-list *counters*
-list *quotas*
+{*add* | *delete* | *list* | *reset*} 'type' ['family'] 'table' 'object'
+*delete* 'type' ['family'] 'table' *handle* 'handle'
+*list counters*
+*list quotas*
 
 Stateful objects are attached to tables and are identified by an unique name.
 They group stateful information from rules, to reference them in rules the
doc/payload-expression.txt +36 -32

196 lines not on this page · raw message

doc/primary-expression.txt +8 -10
index a62ed00eb3140..6eb9583ac9e94 100644
@@ -1,10 +1,8 @@
 META EXPRESSIONS
 ~~~~~~~~~~~~~~~~
 [verse]
-*meta* {length | nfproto | l4proto | protocol | priority}
-[meta] {mark | iif | iifname | iiftype | oif | oifname | oiftype |
-skuid | skgid | nftrace | rtclassid | ibrname | obrname | pkttype | cpu
-| iifgroup | oifgroup | cgroup | random | ipsec | iifkind | oifkind}
+*meta* {*length* | *nfproto* | *l4proto* | *protocol* | *priority*}
+[*meta*] {*mark* | *iif* | *iifname* | *iiftype* | *oif* | *oifname* | *oiftype* | *skuid* | *skgid* | *nftrace* | *rtclassid* | *ibrname* | *obrname* | *pkttype* | *cpu* | *iifgroup* | *oifgroup* | *cgroup* | *random* | *ipsec* | *iifkind* | *oifkind*}
 
 A meta expression refers to meta data associated with a packet.
 
@@ -160,7 +158,7 @@ raw prerouting meta ipsec exists accept
 SOCKET EXPRESSION
 ~~~~~~~~~~~~~~~~~
 [verse]
-*socket* \{transparent\}
+*socket* {*transparent* | *mark*}
 
 Socket expression can be used to search for an existing open TCP/UDP socket and
 its attributes that can be associated with a packet. It looks for an established
@@ -206,7 +204,7 @@ table inet x {
 OSF EXPRESSION
 ~~~~~~~~~~~~~~
 [verse]
-osf {name}
+*osf* [*ttl* {*loose* | *skip*}] {*name* | *version*}
 
 The osf expression does passive operating system fingerprinting. This
 expression compares some data (Window Size, MSS, options and their order, DF,
@@ -249,7 +247,7 @@ table inet x {
 FIB EXPRESSIONS
 ~~~~~~~~~~~~~~~
 [verse]
-*fib* {saddr | daddr | {mark | iif | oif}} {oif | oifname | type}
+*fib* {*saddr* | *daddr* | *mark* | *iif* | *oif*} [*.* ...] {*oif* | *oifname* | *type*}
 
 A fib expression queries the fib (forwarding information base) to obtain
 information such as the output interface index a particular address would use.
@@ -286,7 +284,7 @@ filter prerouting meta mark set 0xdead fib daddr . mark type vmap { blackhole :
 ROUTING EXPRESSIONS
 ~~~~~~~~~~~~~~~~~~~
 [verse]
-*rt* {classid | nexthop}
+*rt* [*ip* | *ip6*] {*classid* | *nexthop* | *mtu* | *ipsec*}
 
 A routing expression refers to routing data associated with a packet.
 
@@ -333,8 +331,8 @@ IPSEC EXPRESSIONS
 ~~~~~~~~~~~~~~~~~
 
 [verse]
-*ipsec* {in | out} [ spnum 'NUM' ]  {reqid | spi }
-*ipsec* {in | out} [ spnum 'NUM' ]  {ip | ip6 } { saddr | daddr }
+*ipsec* {*in* | *out*} [ *spnum* 'NUM' ]  {*reqid* | *spi*}
+*ipsec* {*in* | *out*} [ *spnum* 'NUM' ]  {*ip* | *ip6*} {*saddr* | *daddr*}
 
 An ipsec expression refers to ipsec data associated with a packet.
 
doc/stateful-objects.txt +4 -4
index 6de4e8bd023fb..cc1b698d7831a 100644
@@ -1,7 +1,7 @@
 CT HELPER
 ~~~~~~~~~
 [verse]
-*ct* helper 'helper' {type 'type' protocol 'protocol' ; [l3proto 'family' ;] }
+*ct helper* 'helper' *{ type* 'type' *protocol* 'protocol' *;* [*l3proto* 'family' *;*] *}*
 
 Ct helper is used to define connection tracking helpers that can then be used in
 combination with the *ct helper set* statement. 'type' and 'protocol' are
@@ -43,7 +43,7 @@ table inet myhelpers {
 CT TIMEOUT
 ~~~~~~~~~~
 [verse]
-*ct* timeout 'name' {protocol 'protocol' ; policy = {'state': 'value'} ;[l3proto 'family' ;] }
+*ct timeout* 'name' *{ protocol* 'protocol' *; policy = {* 'state'*:* 'value' [*,* ...] *} ;* [*l3proto* 'family' *;*] *}*
 
 Ct timeout is used to update connection tracking timeout values.Timeout policies are assigned
 with the *ct timeout set* statement. 'protocol' and 'policy' are
@@ -98,7 +98,7 @@ sport=41360 dport=22
 COUNTER
 ~~~~~~~
 [verse]
-*counter* [packets bytes]
+*counter* ['packets bytes']
 
 .Counter specifications
 [options="header"]
@@ -115,7 +115,7 @@ unsigned integer (64 bit)
 QUOTA
 ~~~~~
 [verse]
-*quota* [over | until] [used]
+*quota* [*over* | *until*] ['used']
 
 .Quota specifications
 [options="header"]
doc/statements.txt +85 -40

248 lines not on this page · raw message

Signature · 1 line
2.21.0