[RFC PATCH] doc: use symbolic names for chain priorities

[RFC PATCH] doc: use symbolic names for chain priorities

[Simon Ruderich]

This replaces the numbers with the matching symbolic names with one
exception: The NAT example used "priority 0" for the prerouting
priority. This is replaced by "dstnat" which has priority -100.

Signed-off-by: Simon Ruderich <simon@ruderich.org>
---

Hello,

this patch has the RFC tag because I'm not sure if the NAT change
mentioned above is actually correct or necessary.

I don't understand how the priority option actually works. The
documentation states that it "specifies the order in which chains
with the same *hook* value are traversed". However, from what I
understand it's not only relevant for the order of multiple
custom hooks but it also maps to the priority used for the
netfilter hooks inside the kernel (e.g. -300 which happens before
conntrack handling in the kernel). Please correct me if this is
wrong.

Assuming the above is more or less correct, I don't understand
why the old rules worked:

    add chain nat prerouting { type nat hook prerouting priority 0; }
    add chain nat postrouting { type nat hook postrouting priority 100; }

Isn't priority 0 "too late" as 0 is also used for filter? Or are
nat and filter types completely separate and the order is only
relevant for hooks of the same type? If so, why does postrouting
require priority 100 (shouldn't the kernel put prerouting before
postrouting automatically)? Or would any value greater than 0
also work as long as it's after postrouting? And why are dstnat
and srcnat set to -100 and 100?

The fact that iptables has separate tables for "mangle" and "raw"
(for which nftables uses the filter type) doesn't help my
confusion. It would be great if you could shed some light on
this.

Regards
Simon

 doc/nft.txt                |  4 ++--
 doc/primary-expression.txt |  8 ++++----
 doc/statements.txt         | 18 +++++++++---------
 3 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/doc/nft.txt b/doc/nft.txt
index e4f32179..55747036 100644
--- a/doc/nft.txt
+++ b/doc/nft.txt
@@ -319,7 +319,7 @@ nft --interactive
 create table inet mytable
 
 # add a new base chain: get input packets
-add chain inet mytable myin { type filter hook input priority 0; }
+add chain inet mytable myin { type filter hook input priority filter; }
 
 # add a single counter to the chain
 add rule inet mytable myin counter
@@ -487,7 +487,7 @@ nft add rule ip filter output ip daddr 192.168.0.0/24 accept
 # nft -a list ruleset
 table inet filter {
 	chain input {
-		type filter hook input priority 0; policy accept;
+		type filter hook input priority filter; policy accept;
 		ct state established,related accept # handle 4
 		ip saddr 10.1.1.1 tcp dport ssh accept # handle 5
 	  ...
diff --git a/doc/primary-expression.txt b/doc/primary-expression.txt
index e87e8cc2..97461104 100644
--- a/doc/primary-expression.txt
+++ b/doc/primary-expression.txt
@@ -221,7 +221,7 @@ boolean (1 bit)
 # exactly what you want).
 table inet x {
     chain y {
-	type filter hook prerouting priority -150; policy accept;
+	type filter hook prerouting priority mangle; policy accept;
         socket transparent 1 socket wildcard 0 mark set 0x00000001 accept
     }
 }
@@ -229,7 +229,7 @@ table inet x {
 # Trace packets that corresponds to a socket with a mark value of 15
 table inet x {
     chain y {
-        type filter hook prerouting priority -150; policy accept;
+        type filter hook prerouting priority mangle; policy accept;
         socket mark 0x0000000f nftrace set 1
     }
 }
@@ -237,7 +237,7 @@ table inet x {
 # Set packet mark to socket mark
 table inet x {
     chain y {
-        type filter hook prerouting priority -150; policy accept;
+        type filter hook prerouting priority mangle; policy accept;
         tcp dport 8080 mark set socket mark
     }
 }
@@ -280,7 +280,7 @@ If no TTL attribute is passed, make a true IP header and fingerprint TTL true co
 # Accept packets that match the "Linux" OS genre signature without comparing TTL.
 table inet x {
     chain y {
-	type filter hook input priority 0; policy accept;
+	type filter hook input priority filter; policy accept;
         osf ttl skip name "Linux"
     }
 }
diff --git a/doc/statements.txt b/doc/statements.txt
index 0973e5ef..c1fd5e55 100644
--- a/doc/statements.txt
+++ b/doc/statements.txt
@@ -216,7 +216,7 @@ The conntrack statement can be used to set the conntrack mark and conntrack labe
 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
 done in prerouting and possibly output (if locally generated packets need to be
-placed in a distinct zone), with a hook priority of -300.
+placed in a distinct zone), with a hook priority of *raw* (-300).
 
 Unlike iptables, where the helper assignment happens in the raw table,
 the helper needs to be assigned after a conntrack entry has been
@@ -253,11 +253,11 @@ ct mark set meta mark
 ------------------------------
 table inet raw {
   chain prerouting {
-      type filter hook prerouting priority -300;
+      type filter hook prerouting priority raw;
       ct zone set iif map { "eth1" : 1, "veth1" : 2 }
   }
   chain output {
-      type filter hook output priority -300;
+      type filter hook output priority raw;
       ct zone set oif map { "eth1" : 1, "veth1" : 2 }
   }
 }
@@ -278,7 +278,7 @@ packets.
 
 Note that for this statement to be effective, it has to be applied to packets
 before a conntrack lookup happens. Therefore, it needs to sit in a chain with
-either prerouting or output hook and a hook priority of -300 or less.
+either prerouting or output hook and a hook priority of -300 (*raw*) or less.
 
 See SYNPROXY STATEMENT for an example usage.
 
@@ -420,8 +420,8 @@ If used then port mapping is generated based on a 32-bit pseudo-random algorithm
 ---------------------
 # create a suitable table/chain setup for all further examples
 add table nat
-add chain nat prerouting { type nat hook prerouting priority 0; }
-add chain nat postrouting { type nat hook postrouting priority 100; }
+add chain nat prerouting { type nat hook prerouting priority dstnat; }
+add chain nat postrouting { type nat hook postrouting priority srcnat; }
 
 # translate source addresses of all packets leaving via eth0 to address 1.2.3.4
 add rule nat postrouting oif eth0 snat to 1.2.3.4
@@ -482,21 +482,21 @@ this case the rule will match for both families.
 -------------------------------------
 table ip x {
     chain y {
-        type filter hook prerouting priority -150; policy accept;
+        type filter hook prerouting priority mangle; policy accept;
         tcp dport ntp tproxy to 1.1.1.1
         udp dport ssh tproxy to :2222
     }
 }
 table ip6 x {
     chain y {
-       type filter hook prerouting priority -150; policy accept;
+       type filter hook prerouting priority mangle; policy accept;
        tcp dport ntp tproxy to [dead::beef]
        udp dport ssh tproxy to :2222
     }
 }
 table inet x {
     chain y {
-        type filter hook prerouting priority -150; policy accept;
+        type filter hook prerouting priority mangle; policy accept;
         tcp dport 321 tproxy to :ssh
         tcp dport 99 tproxy ip to 1.1.1.1:999
         udp dport 155 tproxy ip6 to [dead::beef]:smux
-- 
2.30.1

Re: [RFC PATCH] doc: use symbolic names for chain priorities

[Frank Myhr]

On 2021/03/07 09:43, Simon Ruderich wrote:

> I don't understand how the priority option actually works. The
> documentation states that it "specifies the order in which chains
> with the same *hook* value are traversed". However, from what I
> understand it's not only relevant for the order of multiple
> custom hooks but it also maps to the priority used for the
> netfilter hooks inside the kernel (e.g. -300 which happens before
> conntrack handling in the kernel). Please correct me if this is
> wrong.
> 
> Assuming the above is more or less correct, I don't understand
> why the old rules worked:
> 
>      add chain nat prerouting { type nat hook prerouting priority 0; }
>      add chain nat postrouting { type nat hook postrouting priority 100; }
> 
> Isn't priority 0 "too late" as 0 is also used for filter? Or are
> nat and filter types completely separate and the order is only
> relevant for hooks of the same type? If so, why does postrouting
> require priority 100 (shouldn't the kernel put prerouting before
> postrouting automatically)? Or would any value greater than 0
> also work as long as it's after postrouting? And why are dstnat
> and srcnat set to -100 and 100?

Hi Simon,

Priority is only relevant _within a given hook_. So comparing priorities 
of base chains hooked to prerouting and postrouting (as in your example 
above) does not make sense. Please see:

https://wiki.nftables.org/wiki-nftables/index.php/Configuring_chains#Base_chain_priority

https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks

Hope that clears things up for you.

Best Wishes,
Frank

Re: [RFC PATCH] doc: use symbolic names for chain priorities

[Simon Ruderich]

[-- Attachment #1: Type: text/plain, Size: 1751 bytes --]

On Sun, Mar 07, 2021 at 10:02:52AM -0500, Frank Myhr wrote:
> Hi Simon,
>
> Priority is only relevant _within a given hook_. So comparing priorities of
> base chains hooked to prerouting and postrouting (as in your example above)
> does not make sense. Please see:
>
> https://wiki.nftables.org/wiki-nftables/index.php/Configuring_chains#Base_chain_priority
> https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks

Hello Frank,

thank you. This helped, somewhat.

The image https://people.netfilter.org/pablo/nf-hooks.png in the
wiki lists netfilter hooks. Do these correspond to nftables
hooks? So all prerouting hooks (type nat, type filter, etc.) for
IP are applied to the green "Prerouting Hook" in the IP part of
the diagram? And the "Netfilter Internal Priority" applies only
within such a hook to order them?

If this is correct this leads me to three questions:

Why is there a global order of netfilter hooks (via the priority,
-450 to INT_MAX)? Wouldn't it also work to set for example
NF_IP_PRI_NAT_SRC to -400 because it only applies in postrouting
anyway? Or is it designed that way to "hint" at the packet flow
(lower numbers first, independent of the actual hooks)?

For type nat and hook prerouting priorities like -100, 0 and 500
would all work because we have no other hooks in that range.
However, using priority -250 would be problematic because it puts
it before the netfilter connection tracking?

What exactly is the difference between the chain types? Is it
relevant for netfilter or is it only for nftables so it knows
which rules to expect in the given chain?

Regards
Simon
-- 
+ privacy is necessary
+ using gnupg http://gnupg.org
+ public key id: 0x92FEFDB7E44C32F9

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [RFC PATCH] doc: use symbolic names for chain priorities

[Frank Myhr]

On 2021/03/08 00:36, Simon Ruderich wrote:
> On Sun, Mar 07, 2021 at 10:02:52AM -0500, Frank Myhr wrote:
>> Hi Simon,
>>
>> Priority is only relevant _within a given hook_. So comparing priorities of
>> base chains hooked to prerouting and postrouting (as in your example above)
>> does not make sense. Please see:
>>
>> https://wiki.nftables.org/wiki-nftables/index.php/Configuring_chains#Base_chain_priority
>> https://wiki.nftables.org/wiki-nftables/index.php/Netfilter_hooks
> 
> Hello Frank,
> 
> thank you. This helped, somewhat.

I'm glad. If you have suggestions for how to make the wiki clearer I'd 
love to hear them. (Probably better to use the regular netfilter list, 
where developers are also present, rather than this netfilter-devel list.)


> The image https://people.netfilter.org/pablo/nf-hooks.png in the
> wiki lists netfilter hooks. Do these correspond to nftables
> hooks? So all prerouting hooks (type nat, type filter, etc.) for
> IP are applied to the green "Prerouting Hook" in the IP part of
> the diagram? And the "Netfilter Internal Priority" applies only
> within such a hook to order them?

Yes, nftables & the rest of netfilter (defrag, conntrack, nat, etc) use 
the same hooks. And relative priority within a hook determines the order 
in which the various processes _at that hook_ happen.


> Why is there a global order of netfilter hooks (via the priority,
> -450 to INT_MAX)? ... is it designed that way to "hint" at the packet flow
> (lower numbers first, independent of the actual hooks)?

I think such hinting is the idea, yes.


 > Wouldn't it also work to set for example
 > NF_IP_PRI_NAT_SRC to -400 because it only applies in postrouting
 > anyway?

Just to be clear, NF_IP_PRI_NAT_SRC is a named constant in the netfilter 
codebase. So not something you can change unless you edit the source 
code and compile it yourself. But you could create a base chain using 
"hook postrouting priority -400" and add rules with "snat to" statements 
to said chain, and this will happily snat your packets as you specify. 
Whether this overall config does what you want, depends on what else is 
hooked to postrouting, and their relative priorities. For example:

* Conntrack is almost always used. Using -400 for snat doesn't change 
its relative order to NF_IP_PRI_CONNTRACK_HELPER and 
NF_IP_PRI_CONNTRACK_CONFIRM (both of which are also at postrouting hook).

* If you are also mangling packets (in ways other than snat) at 
postrouting, NF_IP_PRI_MANGLE = -150. By moving your snat from usual 100 
to -400, you've re-ordered the mangle and snat processes -- unless you 
also use a nonstandard priority for your base chain that does mangling.

* There's also NF_IP_PRI_SECURITY, maybe important if you're using SELINUX.

General point: you should have a good reason for using priorities other 
than the traditional ones.


> For type nat and hook prerouting priorities like -100, 0 and 500
> would all work because we have no other hooks in that range. > However, using priority -250 would be problematic because it puts
> it before the netfilter connection tracking?

It's pretty common to filter in prerouting. And maybe to set secmark as 
well... So using priority 0 or 500 for dnat could cause trouble. Using 
-250 for dnat is problematic for the reason you state. And if you're 
using SELINUX you also have to consider NF_IP_PRI_SELINUX_FIRST at -225.


> What exactly is the difference between the chain types? Is it
> relevant for netfilter or is it only for nftables so it knows
> which rules to expect in the given chain?

I think you mean?:
https://wiki.nftables.org/wiki-nftables/index.php/Nftables_families


~
Disclosure: I'm not an nftables or netfilter developer, just a user with 
an interest in clear documentation.

Best Wishes,
Frank

Re: [RFC PATCH] doc: use symbolic names for chain priorities

[Simon Ruderich]

[-- Attachment #1: Type: text/plain, Size: 2943 bytes --]

On Mon, Mar 08, 2021 at 04:46:34AM -0500, Frank Myhr wrote:
> I'm glad. If you have suggestions for how to make the wiki clearer I'd love
> to hear them. (Probably better to use the regular netfilter list, where
> developers are also present, rather than this netfilter-devel list.)

Hello Frank,

I'm not sure what exactly tripped me up (or is still confusing
me). I think it's mainly that the concepts of hooks (prerouting,
postrouting, etc.), chain types (filter, nat, etc.) and netfilter
hook priority was never really spelled out in a way that all the
pieces fit together (for me). The fact that the order of
priorities is not directly related to hooks made it worse (I
didn't realize that the priorities only order entries for a
single hook).

>> Wouldn't it also work to set for example
>> NF_IP_PRI_NAT_SRC to -400 because it only applies in postrouting
>> anyway?
>
> Just to be clear, NF_IP_PRI_NAT_SRC is a named constant in the netfilter
> codebase. So not something you can change unless you edit the source code
> and compile it yourself. But you could create a base chain using "hook
> postrouting priority -400" and add rules with "snat to" statements to said
> chain, and this will happily snat your packets as you specify. Whether this
> overall config does what you want, depends on what else is hooked to
> postrouting, and their relative priorities. For example:
>
> * Conntrack is almost always used. Using -400 for snat doesn't change its
> relative order to NF_IP_PRI_CONNTRACK_HELPER and NF_IP_PRI_CONNTRACK_CONFIRM
> (both of which are also at postrouting hook).
>
> * If you are also mangling packets (in ways other than snat) at postrouting,
> NF_IP_PRI_MANGLE = -150. By moving your snat from usual 100 to -400, you've
> re-ordered the mangle and snat processes -- unless you also use a
> nonstandard priority for your base chain that does mangling.
>
> * There's also NF_IP_PRI_SECURITY, maybe important if you're using SELINUX.

Thank you. That made it clearer for me.

> General point: you should have a good reason for using priorities other than
> the traditional ones.

Of course.

>> What exactly is the difference between the chain types? Is it
>> relevant for netfilter or is it only for nftables so it knows
>> which rules to expect in the given chain?
>
> I think you mean?:
> https://wiki.nftables.org/wiki-nftables/index.php/Nftables_families

No. I was talking about the chain types:
https://wiki.nftables.org/wiki-nftables/index.php/Configuring_chains#Base_chain_types

And I'm curious what's the difference in regard to netfilter
between these types. They are all added to the same netfilter
hook (e.g. prerouting can use filter, nat, etc. chains). Does
netfilter see any difference or is this just relevant to
nftables?

Regards
Simon
-- 
+ privacy is necessary
+ using gnupg http://gnupg.org
+ public key id: 0x92FEFDB7E44C32F9

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]