summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorPhil Sutter <phil@nwl.cc>2017-08-10 19:29:19 +0200
committerPablo Neira Ayuso <pablo@netfilter.org>2017-08-14 11:32:21 +0200
commitd20fbc6e5a7b3ec89050e67d1aa0a15f770b7a58 (patch)
tree44c789f7d514759ac29144d0f8249301a769725b
parent51f2d6fe6dc0e28b0173af57ef8eec002fc1962f (diff)
nft.8: Describe base chain details
This mostly covers base chain types, but also tries to clarify meaning of priority values, chain policy and the ominous device parameter. Command synopsis is adjusted as well to point out which parts of a base chain definition are optional and which are not. Signed-off-by: Phil Sutter <phil@nwl.cc> Signed-off-by: Pablo Neira Ayuso <pablo@netfilter.org>
-rw-r--r--doc/nft.xml94
1 files changed, 85 insertions, 9 deletions
diff --git a/doc/nft.xml b/doc/nft.xml
index c9eb48cf..0e795e3c 100644
--- a/doc/nft.xml
+++ b/doc/nft.xml
@@ -626,20 +626,26 @@ filter input iif $int_ifs accept
<title>Chains</title>
<para>
<cmdsynopsis>
- <arg choice="req">add</arg>
+ <group choice="req">
+ <arg>add</arg>
+ <arg>create</arg>
+ </group>
<command>chain</command>
<arg choice="opt"><replaceable>family</replaceable></arg>
- <arg choice="req"><replaceable>table</replaceable></arg>
- <arg choice="req"><replaceable>chain</replaceable></arg>
- <arg choice="req"><replaceable>hook</replaceable></arg>
- <arg choice="req"><replaceable>priority</replaceable></arg>
- <arg choice="req"><replaceable>policy</replaceable></arg>
- <arg choice="req"><replaceable>device</replaceable></arg>
+ <arg choice="plain"><replaceable>table</replaceable></arg>
+ <arg choice="plain"><replaceable>chain</replaceable></arg>
+ <arg choice="opt">
+ <arg choice="req">
+ <arg choice="req"><replaceable>type</replaceable></arg>
+ <arg choice="req"><replaceable>hook</replaceable></arg>
+ <arg choice="opt"><replaceable>device</replaceable></arg>
+ <arg choice="req"><replaceable>priority</replaceable></arg>
+ </arg>
+ <arg choice="opt"><replaceable>policy</replaceable></arg>
+ </arg>
</cmdsynopsis>
<cmdsynopsis>
<group choice="req">
- <arg>add</arg>
- <arg>create</arg>
<arg>delete</arg>
<arg>list</arg>
<arg>flush</arg>
@@ -720,6 +726,76 @@ filter input iif $int_ifs accept
</listitem>
</varlistentry>
</variablelist>
+
+ <para>
+ For base chains, <command>type</command>, <command>hook</command> and <command>priority</command> parameters are mandatory.
+ </para>
+ <para>
+ <table frame="all">
+ <title>Supported chain types</title>
+ <tgroup cols="4" align="left" colsep="1" rowsep="1">
+ <colspec colname="c1"/>
+ <colspec colname="c2"/>
+ <colspec colname="c3"/>
+ <colspec colname="c4"/>
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Families</entry>
+ <entry>Hooks</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>filter</entry>
+ <entry>all</entry>
+ <entry>all</entry>
+ <entry>Standard chain type to use in doubt.</entry>
+ </row>
+ <row>
+ <entry>nat</entry>
+ <entry>ip, ip6</entry>
+ <entry>prerouting, input, output, postrouting</entry>
+ <entry>Chains of this type perform Native Address Translation based on conntrack entries. Only the first packet of a connection actually traverses this chain - its rules usually define details of the created conntrack entry (NAT statements for instance).</entry>
+ </row>
+ <row>
+ <entry>route</entry>
+ <entry>ip, ip6</entry>
+ <entry>output</entry>
+ <entry>If a packet has traversed a chain of this
+ type and is about to be accepted, a new route
+ lookup is performed if relevant parts of the IP
+ header have changed. This allows to e.g.
+ implement policy routing selectors in
+ nftables.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ <para>
+ Apart from the special cases illustrated above (e.g. <literal>nat</literal> type not supporting <literal>forward</literal> hook or <literal>route</literal> type only supporting <literal>output</literal> hook), there are two further quirks worth noticing:
+ <itemizedlist>
+ <listitem>
+ <literal>netdev</literal> family supports merely a single
+ combination, namely <literal>filter</literal> type and
+ <literal>ingress</literal> hook. Base chains in this family also require the <literal>device</literal> parameter to be present since they exist per incoming interface only.
+ </listitem>
+ <listitem>
+ <literal>arp</literal> family supports only
+ <literal>input</literal> and <literal>output</literal>
+ hooks, both in chains of type
+ <literal>filter</literal>.
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ The <literal>priority</literal> parameter accepts a signed integer value which specifies the order in which chains with same <literal>hook</literal> value are traversed. The ordering is ascending, i.e. lower priority values have precedence over higher ones.
+ </para>
+ <para>
+ Base chains also allow to set the chain's <literal>policy</literal>, i.e. what happens to packets not explicitly accepted or refused in contained rules. Supported policy values are <literal>accept</literal> (which is the default) or <literal>drop</literal>.
+ </para>
</refsect1>
<refsect1>