Difference between revisions of "Configuring chains"

From nftables wiki
Jump to navigation Jump to search
(→‎Adding base chains: Add optional text comment parameter to base chain)
 
(40 intermediate revisions by 6 users not shown)
Line 1: Line 1:
As in ''iptables'', you attach your [[Simple rule management|rules]] to chains. However, contrary to the ''iptables'' modus operandi, the ''nftables'' infrastructure comes with no predefined chains, so you need to register your base chains in first place before you can add any rule. This allows very flexible configurations.
As in ''iptables'', with ''nftables'' you attach your [[Simple rule management|rules]] to chains. Unlike in ''iptables'', there are no predefined chains like INPUT, OUTPUT, etc. Instead, to filter packets at a particular processing step, you explicitly create a '''base chain''' with name of your choosing, and attach it to the appropriate [[Netfilter hooks | Netfilter hook]]. This allows very flexible configurations without slowing Netfilter down with built-in chains not needed by your ruleset.


= Adding base chains =
= Adding base chains =


The syntax to add base chains is the following:
Base chains are those that are registered into the [[Netfilter hooks]], i.e. these chains see packets flowing through your Linux TCP/IP stack.
 
The syntax to add a base chain is:


<source lang="bash">
<source lang="bash">
% nft add chain [<family>] <table-name> <chain-name> { type <type> hook <hook> priority <value> \; }  
% nft add chain [<family>] <table_name> <chain_name> { type <type> hook <hook> priority <value> \; [policy <policy> \;] [comment \"text comment\" \;] }  
</source>
</source>


Base chains are those that are registered into the [[Netfilter hooks]], ie. these chains see packets flowing through your Linux TCP/IP stack.
The following example shows how to add a new base chain ''input'' to the ''foo'' table (which must have been previously created):
 
<source lang="bash">
% nft 'add chain ip foo input { type filter hook input priority 0 ; }'
</source>


The following example show how you can add new base chains to the ''foo'' table through the following command:
'''Important''': ''nft'' re-uses special characters, such as curly braces and the semicolon. If you are running these commands from a shell such as ''bash'', all the special characters need to be escaped. The simplest way to prevent the shell from attempting to parse the ''nft'' syntax is to quote everything within single quotes.  Alternatively, you can run the command


<source lang="bash">
<source lang="bash">
% nft add chain ip foo input { type filter hook input priority 0 \; }
% nft -i
</source>
</source>


'''Important''': You have to escape the semicolon if you are running this command from ''bash''.
and run nft in interactive mode.


This command registers the ''input'' chain, that it attached to the ''input'' hook so it will see packets that are addressed to the local processes.
The ''add chain'' command registers the ''input'' chain, that it attached to the ''input'' hook so it will see packets that are addressed to the local processes.


The ''priority'' is important since it determines the ordering of the chains, thus, if you have several chains in the ''input'' hook, you can decide which one sees packets before another.
The ''priority'' is important since it determines the ordering of the chains, thus, if you have several chains in the ''input'' hook, you can decide which one sees packets before another. For example, input chains with priorities -12, -1, 0, 10 would be consulted exactly in that order. It's possible to give two base chains the same priority, but there is no guaranteed evaluation order of base chains with identical priority that are attached to the same hook location.


If you want to use ''nftables'' to filter traffic for desktop Linux computers, ie. a computer which does not forward traffic, you can also register the output chain:
If you want to use ''nftables'' to filter traffic for desktop Linux computers, i.e. a computer which does not forward traffic, you can also register the output chain:


<source lang="bash">
<source lang="bash">
% nft add chain ip foo output { type filter hook output priority 0 \; }  
% nft 'add chain ip foo output { type filter hook output priority 0 ; }'
</source>
</source>


Now you are ready to filter incoming (directed to local processes) and outgoing (generated by local processes) traffic.
Now you are ready to filter incoming (directed to local processes) and outgoing (generated by local processes) traffic.


'''Important note''': If you don't include the chain configuration that is specified enclosed in the curly braces, you are creating a non-base chain that will not see any packets (similar to ''iptables -N chain-name'').
'''Important note''': If you don't include the chain configuration that is specified enclosed in the curly braces, you are creating a regular chain that will not see any packets (similar to ''iptables -N chain-name'').


Since nftables 0.5, you can also specify the default policy for base chains as in ''iptables'':
Since nftables 0.5, you can also specify the default policy for base chains as in ''iptables'':


<source lang="bash">
<source lang="bash">
% nft add chain ip foo output { type filter hook output priority 0 \; policy accept\; }  
% nft 'add chain ip foo output { type filter hook output priority 0 ; policy accept; }'
</source>
</source>


Line 43: Line 49:
When adding a chain on '''ingress''' hook, it is mandatory to specify the device where the chain will be attached:  
When adding a chain on '''ingress''' hook, it is mandatory to specify the device where the chain will be attached:  
<source lang="bash">
<source lang="bash">
% nft add chain netdev foo dev0filter { type filter hook ingress device eth0 priority 0 \; }  
% nft 'add chain netdev foo dev0filter { type filter hook ingress device eth0 priority 0 ; }'
</source>
</source>


Line 50: Line 56:
The possible chain types are:
The possible chain types are:


* '''filter''', which is obviously used to filter packets. This is supported by the arp, bridge, ip, ip6 and inet table families.
* '''filter''', which is used to filter packets. This is supported by the arp, bridge, ip, ip6 and inet table families.
* '''route''', which is used to reroute packets if any relevant IP header field or the packet mark is modified. If you are familiar with ''iptables'', this chain type provides equivalent semantics to the ''mangle'' table but only for the ''output'' hook (for other hooks use type ''filter'' instead). This is supported by the ip and ip6 table families.
* '''route''', which is used to reroute packets if any relevant IP header field or the packet mark is modified. If you are familiar with ''iptables'', this chain type provides equivalent semantics to the ''mangle'' table but only for the ''output'' hook (for other hooks use type ''filter'' instead). This is supported by the ip, ip6 and inet table families.
* '''nat''', which is used to perform Networking Address Translation (NAT). The first packet that belongs to a flow always hits this chain, follow up packets not. Therefore, never use this chain for filtering. This is supported by the ip and ip6 table families.
* '''nat''', which is used to perform Networking Address Translation (NAT). Only the first packet of a given flow hits this chain; subsequent packets bypass it. Therefore, never use this chain for filtering. The ''nat'' chain type is supported by the ip, ip6 and inet table families.
 
== Base chain hooks ==
 
The possible [[Netfilter_hooks | '''hooks''']] that you can use when you configure your base chain are:
 
* '''ingress''' (only in ''netdev'' family since Linux kernel 4.2, and ''inet'' family since Linux kernel 5.10): sees packets immediately after they are passed up from the NIC driver, before even prerouting. So you have an alternative to ''tc''.
* '''prerouting''': sees all incoming packets, before any routing decision has been made. Packets may be addressed to the local or remote systems.
* '''input''': sees incoming packets that are addressed to and have now been routed to the local system and processes running there.
* '''forward''': sees incoming packets that are not addressed to the local system.
* '''output''': sees packets that originated from processes in the local machine.
* '''postrouting''': sees all packets after routing, just before they leave the local system.
 
== Base chain priority ==
 
Each nftables base chain is assigned a [[Netfilter_hooks#Priority_within_hook|'''priority''']] that defines its ordering among other base chains, flowtables, and Netfilter internal operations at the same hook. For example, a chain on the ''prerouting'' hook with priority ''-300'' will be placed before connection tracking operations.
 
'''NOTE''': If a packet is accepted and there is another chain, bearing the same hook type and with a later priority, then the packet will subsequently traverse this other chain. Hence, an accept verdict - be it by way of a rule or the default chain policy - isn't necessarily final. However, the same is ''not'' true of packets that are subjected to a drop verdict. Instead, drops take immediate effect, with no further rules or chains being evaluated.
 
The following ruleset demonstrates this potentially surprising distinction in behaviour:
 
<pre>
table inet filter {
        # This chain is evaluated first due to priority
        chain services {
                type filter hook input priority 0; policy accept;
 
                # If matched, this rule will prevent any further evaluation
                tcp dport http drop
 
                # If matched, and despite the accept verdict, the packet proceeds to enter the chain below
                tcp dport ssh accept
 
                # Likewise for any packets that get this far and hit the default policy
        }


The possible hooks that you can use when you configure your chain are:
        # This chain is evaluated last due to priority
        chain input {
                type filter hook input priority 1; policy drop;
                # All ingress packets end up being dropped here!
        }
}
</pre>


* '''prerouting''': the routing decision for those packets didn't happen yet, so you don't know if they are addressed to the local or remote systems.
If the priority of the 'input' chain above were to be changed to -1, the only difference would be that no packets have the opportunity to enter the 'services' chain. Either way, this ruleset will result in all ingress packets being dropped.
* '''input''': It happens after the routing decision, you can see packets that are directed to the local system and processes running in system.
* '''forward''': It also happens after the routing decision, you can see packet that are not directed to the local machine.
* '''output''': to catch packets that are originated from processes in the local machine.
* '''postrouting''': After the routing decision for packets leaving the local system.
* '''ingress''' (only available at the ''netdev'' family): Since Linux kernel 4.2, you can filter traffic way before prerouting, after the packet is passed up from the NIC driver. So you have an alternative to ''tc''.


The priority can be used to order the chains or to put them before or after some Netfilter internal operations. For example, a chain on the ''prerouting'' hook with the priority ''-300'' will be placed before connection tracking operations.  
In summary, packets will traverse all of the chains within the scope of a given hook until they are either dropped or no more base chains exist. An accept verdict is only guaranteed to be final in the case that there is no later chain bearing the same type of hook as the chain that the packet originally entered.


For reference, here's the list of different priority used in iptables:
Netfilter's hook execution mechanism is described in more detail in [http://people.netfilter.org/pablo/docs/login.pdf Pablo's paper on connection tracking].


* NF_IP_PRI_CONNTRACK_DEFRAG (-400): priority of defragmentation
== Base chain policy ==
* NF_IP_PRI_RAW (-300): traditional priority of the raw table placed before connection tracking operation
* NF_IP_PRI_SELINUX_FIRST (-225): SELinux operations
* NF_IP_PRI_CONNTRACK (-200): Connection tracking operations
* NF_IP_PRI_MANGLE (-150): mangle operation
* NF_IP_PRI_NAT_DST (-100): destination NAT
* NF_IP_PRI_FILTER (0): filtering operation, the filter table
* NF_IP_PRI_SECURITY (50): Place of security table where secmark can be set for example
* NF_IP_PRI_NAT_SRC (100): source NAT
* NF_IP_PRI_SELINUX_LAST (225): SELinux at packet exit
* NF_IP_PRI_CONNTRACK_HELPER (300): connection tracking at exit


= Adding non-base chains =
This is the default verdict that will be applied to packets reaching the end of the chain (i.e, no more rules to be evaluated against).


You can also create non-base chains as in ''iptables'' via:
Currently there are 2 policies: '''accept''' (default) or '''drop'''.


<source lang="bash">
* The ''accept'' verdict means that the packet will keep traversing the network stack (default).
% nft add chain ip foo test
* The ''drop'' verdict means that the packet is discarded if the packet reaches the end of the base chain.
 
'''NOTE''': If no policy is explicitly selected, the default policy '''accept''' will be used.
 
= Adding regular chains =
 
You can also create regular chains, analogous to ''iptables'' user-defined chains:
 
<source>
# nft -i
nft> add chain [family] <table_name> <chain_name> [{ [policy <policy> ;] [comment "text comment about this chain" ;] }]
</source>
</source>


Note that this chain does '''not''' see any traffic as it is not attached to any hook, but it can be very useful to arrange your rule-set in a tree of chains by using the [[jumping to chain|jump to chain]] action.
The chain name is an arbitrary string, with arbitrary case.
 
Note that no ''hook'' keyword is included when adding a regular chain. Because it is not attached to a Netfilter hook, '''by itself a regular chain does not see any traffic'''. But one or more base chains can include rules that [[jumping to chain|jump]] or goto this chain -- following which, the regular chain processes packets in exactly the same way as the calling base chain. It can be very useful to arrange your ruleset into a tree of base and regular chains by using the [[jumping to chain|jump]] and/or goto actions. (Though we're getting a bit ahead of ourselves, nftables [[Verdict_Maps_(vmaps)|vmaps]] provide an even more powerful way to construct highly-efficient branched rulesets.)


= Deleting chains =
= Deleting chains =


You can delete the chains that you don't need, eg.
You can delete chains as:


<source lang="bash">
<source lang="bash">
% nft delete chain ip foo input
% nft delete chain [family] <table_name> <chain_name>
</source>
</source>


The only condition is that the chain you want to delete needs to be empty, otherwise the kernel will tell you that such chain is in used.
The only condition is that the chain you want to delete needs to be empty, otherwise the kernel will complain that the chain is still in use.


<source lang="bash">
<source lang="bash">
Line 108: Line 151:
You will have to [[Simple rule management|flush the ruleset]] in that chain before you can remove the chain.
You will have to [[Simple rule management|flush the ruleset]] in that chain before you can remove the chain.


= Flushing chain =
= Flushing chains =


You can also flush the content of a chain. If you want to flush all the rule in the chain ''input'' of the ''foo'' table, you have to type:
To flush (delete all of the rules in) the chain ''input'' of the ''foo'' table:


<source lang="bash">
<source lang="bash">
Line 122: Line 165:
<source lang="bash">
<source lang="bash">
% nft add table ip filter
% nft add table ip filter
% nft add chain ip filter input { type filter hook input priority 0 \; }
% nft 'add chain ip filter input { type filter hook input priority 0 ; }'
% nft add chain ip filter output { type filter hook output priority 0 \; }
% nft 'add chain ip filter output { type filter hook output priority 0 ; }'
</source>
</source>


Now, you can start attaching [[Simple rule management|rules]] to these two base chains. Note that you don't need the ''forward'' chain in this case since this example assumes that you're configuring nftables to filter traffic for a standalone computer that doesn't behave as router.
Now, you can start attaching [[Simple rule management|rules]] to these two base chains. Note that you don't need the ''forward'' chain in this case since this example assumes that you're configuring nftables to filter traffic for a standalone computer that doesn't behave as router.

Latest revision as of 18:14, 1 November 2021

As in iptables, with nftables you attach your rules to chains. Unlike in iptables, there are no predefined chains like INPUT, OUTPUT, etc. Instead, to filter packets at a particular processing step, you explicitly create a base chain with name of your choosing, and attach it to the appropriate Netfilter hook. This allows very flexible configurations without slowing Netfilter down with built-in chains not needed by your ruleset.

Adding base chains

Base chains are those that are registered into the Netfilter hooks, i.e. these chains see packets flowing through your Linux TCP/IP stack.

The syntax to add a base chain is:

% nft add chain [<family>] <table_name> <chain_name> { type <type> hook <hook> priority <value> \; [policy <policy> \;] [comment \"text comment\" \;] }

The following example shows how to add a new base chain input to the foo table (which must have been previously created):

% nft 'add chain ip foo input { type filter hook input priority 0 ; }'

Important: nft re-uses special characters, such as curly braces and the semicolon. If you are running these commands from a shell such as bash, all the special characters need to be escaped. The simplest way to prevent the shell from attempting to parse the nft syntax is to quote everything within single quotes. Alternatively, you can run the command

% nft -i

and run nft in interactive mode.

The add chain command registers the input chain, that it attached to the input hook so it will see packets that are addressed to the local processes.

The priority is important since it determines the ordering of the chains, thus, if you have several chains in the input hook, you can decide which one sees packets before another. For example, input chains with priorities -12, -1, 0, 10 would be consulted exactly in that order. It's possible to give two base chains the same priority, but there is no guaranteed evaluation order of base chains with identical priority that are attached to the same hook location.

If you want to use nftables to filter traffic for desktop Linux computers, i.e. a computer which does not forward traffic, you can also register the output chain:

% nft 'add chain ip foo output { type filter hook output priority 0 ; }'

Now you are ready to filter incoming (directed to local processes) and outgoing (generated by local processes) traffic.

Important note: If you don't include the chain configuration that is specified enclosed in the curly braces, you are creating a regular chain that will not see any packets (similar to iptables -N chain-name).

Since nftables 0.5, you can also specify the default policy for base chains as in iptables:

% nft 'add chain ip foo output { type filter hook output priority 0 ; policy accept; }'

As in iptables, the two possible default policies are accept and drop.

When adding a chain on ingress hook, it is mandatory to specify the device where the chain will be attached:

% nft 'add chain netdev foo dev0filter { type filter hook ingress device eth0 priority 0 ; }'

Base chain types

The possible chain types are:

  • filter, which is used to filter packets. This is supported by the arp, bridge, ip, ip6 and inet table families.
  • route, which is used to reroute packets if any relevant IP header field or the packet mark is modified. If you are familiar with iptables, this chain type provides equivalent semantics to the mangle table but only for the output hook (for other hooks use type filter instead). This is supported by the ip, ip6 and inet table families.
  • nat, which is used to perform Networking Address Translation (NAT). Only the first packet of a given flow hits this chain; subsequent packets bypass it. Therefore, never use this chain for filtering. The nat chain type is supported by the ip, ip6 and inet table families.

Base chain hooks

The possible hooks that you can use when you configure your base chain are:

  • ingress (only in netdev family since Linux kernel 4.2, and inet family since Linux kernel 5.10): sees packets immediately after they are passed up from the NIC driver, before even prerouting. So you have an alternative to tc.
  • prerouting: sees all incoming packets, before any routing decision has been made. Packets may be addressed to the local or remote systems.
  • input: sees incoming packets that are addressed to and have now been routed to the local system and processes running there.
  • forward: sees incoming packets that are not addressed to the local system.
  • output: sees packets that originated from processes in the local machine.
  • postrouting: sees all packets after routing, just before they leave the local system.

Base chain priority

Each nftables base chain is assigned a priority that defines its ordering among other base chains, flowtables, and Netfilter internal operations at the same hook. For example, a chain on the prerouting hook with priority -300 will be placed before connection tracking operations.

NOTE: If a packet is accepted and there is another chain, bearing the same hook type and with a later priority, then the packet will subsequently traverse this other chain. Hence, an accept verdict - be it by way of a rule or the default chain policy - isn't necessarily final. However, the same is not true of packets that are subjected to a drop verdict. Instead, drops take immediate effect, with no further rules or chains being evaluated.

The following ruleset demonstrates this potentially surprising distinction in behaviour:

table inet filter {
        # This chain is evaluated first due to priority
        chain services {
                type filter hook input priority 0; policy accept;

                # If matched, this rule will prevent any further evaluation
                tcp dport http drop

                # If matched, and despite the accept verdict, the packet proceeds to enter the chain below
                tcp dport ssh accept

                # Likewise for any packets that get this far and hit the default policy
        }

        # This chain is evaluated last due to priority
        chain input {
                type filter hook input priority 1; policy drop;
                # All ingress packets end up being dropped here!
        }
}

If the priority of the 'input' chain above were to be changed to -1, the only difference would be that no packets have the opportunity to enter the 'services' chain. Either way, this ruleset will result in all ingress packets being dropped.

In summary, packets will traverse all of the chains within the scope of a given hook until they are either dropped or no more base chains exist. An accept verdict is only guaranteed to be final in the case that there is no later chain bearing the same type of hook as the chain that the packet originally entered.

Netfilter's hook execution mechanism is described in more detail in Pablo's paper on connection tracking.

Base chain policy

This is the default verdict that will be applied to packets reaching the end of the chain (i.e, no more rules to be evaluated against).

Currently there are 2 policies: accept (default) or drop.

  • The accept verdict means that the packet will keep traversing the network stack (default).
  • The drop verdict means that the packet is discarded if the packet reaches the end of the base chain.

NOTE: If no policy is explicitly selected, the default policy accept will be used.

Adding regular chains

You can also create regular chains, analogous to iptables user-defined chains:

# nft -i
nft> add chain [family] <table_name> <chain_name> [{ [policy <policy> ;] [comment "text comment about this chain" ;] }]

The chain name is an arbitrary string, with arbitrary case.

Note that no hook keyword is included when adding a regular chain. Because it is not attached to a Netfilter hook, by itself a regular chain does not see any traffic. But one or more base chains can include rules that jump or goto this chain -- following which, the regular chain processes packets in exactly the same way as the calling base chain. It can be very useful to arrange your ruleset into a tree of base and regular chains by using the jump and/or goto actions. (Though we're getting a bit ahead of ourselves, nftables vmaps provide an even more powerful way to construct highly-efficient branched rulesets.)

Deleting chains

You can delete chains as:

% nft delete chain [family] <table_name> <chain_name>

The only condition is that the chain you want to delete needs to be empty, otherwise the kernel will complain that the chain is still in use.

% nft delete chain ip foo input
<cmdline>:1:1-28: Error: Could not delete chain: Device or resource busy
delete chain ip foo input
^^^^^^^^^^^^^^^^^^^^^^^^^

You will have to flush the ruleset in that chain before you can remove the chain.

Flushing chains

To flush (delete all of the rules in) the chain input of the foo table:

nft flush chain foo input

Example configuration: Filtering traffic for your standalone computer

You can create a table with two base chains to define rule to filter traffic coming to and leaving from your computer, asumming IPv4 connectivity:

% nft add table ip filter
% nft 'add chain ip filter input { type filter hook input priority 0 ; }'
% nft 'add chain ip filter output { type filter hook output priority 0 ; }'

Now, you can start attaching rules to these two base chains. Note that you don't need the forward chain in this case since this example assumes that you're configuring nftables to filter traffic for a standalone computer that doesn't behave as router.