nftables wiki - User contributions [en]

Configuring chains

2024-10-08T22:35:39Z

Plushkava: Remove a superfluous newline

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.

= Syntactic conventions =

Naturally, in order to make use of ''nftables'' commands and directives, it is necessary to become familiar with them, along with their supported grammar. Even with that knowledge, users sometimes experience difficulties where passing ''nftables'' commands as arguments to the nft(8) utility. That's because shells recognise certain characters as metacharacters and treat them in a special way unless they are quoted.

Throughout this article, examples that begin with the hash character (U+23) can be taken as examples of valid shell code. That is, they are syntactically valid if entered into any implementation of the Shell Command Language, including bash. By contrast, examples that do not begin with the hash character can be interpreted as either synopses of ''nftables'' grammar, similar in style to the nft(8) man page, or as examples of complete rulesets, if so indicated.

As such, examples of shell code shall generally be of the following form.

<source>
# nft 'nftables commands go here'
</source>

Note that enclosing the ''nftables'' commands within single quotes is a straightforward way of preventing the shell from interpreting characters as metacharacters, most notably the semicolon. Rather, the shell will consider all that is between the pair of single quotes as a single word before passing it on to the nft(8) utility as a single argument, verbatim. Another way to prevent the shell from attempting to parse metacharacters is to run nft(8) in its interactive mode.

<source>
# nft -i
</source>

In that case, nft(8) will directly interpret any further input given until such time as it is either interrupted, encounters the end-of-file (EOF) condition, or encounters the "quit" command. In most terminal emulators, EOF can be conveyed with the Ctrl+D key combination.

Examples describing ''nftables'' grammar shall employ square brackets (U+5B, U+5D) to denote optional components of syntax, and angle brackets (U+3C, U+3D) to denote user-specified values.

= 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 for adding base chains is as follows.

<source>
add chain [<family>] <table_name> <chain_name> { type <type> hook <hook> [device <device>] priority <priority> ; [policy <policy> ;] [comment <comment> ;] }
</source>

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

<source>
# nft 'add chain ip filter input { type filter hook input priority 0; }'
</source>

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:

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; }'
</source>

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'':

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; policy accept; }'
</source>

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:
<source>
# nft 'add chain netdev filter eth0_filter { type filter hook ingress device eth0 priority 0; }'
</source>

== 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 [[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 ip 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!
}
}
</pre>

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 [http://people.netfilter.org/pablo/docs/login.pdf 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, the syntax for which is as follows.

<source>
add chain [family] <table_name> <chain_name> [comment <comment>]
</source>

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 =

The syntax for deleting chains is as follows.

<source>
delete chain [family] <table_name> <chain_name>
</source>

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>
# nft 'delete chain ip filter input'
<cmdline>:1:1-28: Error: Could not delete chain: Device or resource busy
delete chain ip filter input
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
</source>

You will have to [[Simple rule management|flush the ruleset]] in that chain before you can remove the chain.

= Flushing chains =

To flush a chain means to delete all of the rules that it contains, if any. The syntax for doing so is as follows.

<source>
flush chain [family] <table_name> <chain_name>
</source>

= 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:

<source>
# 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; }'
</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.

Here is the exact same policy, only shown in the declarative style. That is, in the same format as would be employed upon issuing the "list ruleset" command. Despite the marked difference in style, it constitutes valid ''nftables'' syntax and is equivalent to the combination of "add table" and "add chain" commands shown above.

<source>
table ip filter {
chain input {
type filter hook input priority filter; policy accept;
}

chain output {
type filter hook output priority filter; policy accept;
}
}
</source>

Configuring chains

2024-10-08T22:31:45Z

Plushkava: Have the syntactic conventions account for the presence of ruleset samples

Configuring chains

2024-10-08T22:24:43Z

Plushkava: Show the example ruleset at the end in the "list ruleset" style as well as a series of incremental commands

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.

= Syntactic conventions =

Naturally, in order to make use of ''nftables'' commands and directives, it is necessary to become familiar with them, along with their supported grammar. Even with that knowledge, users sometimes experience difficulties where passing ''nftables'' commands as arguments to the nft(8) utility. That's because shells recognise certain characters as metacharacters and treat them in a special way unless they are quoted.

Throughout this article, examples that begin with the hash character (U+23) can be taken as examples of valid shell code. That is, they are syntactically valid if entered into any implementation of the Shell Command Language, including bash. By contrast, examples that do not begin with the hash character can be interpreted as synopses of ''nftables'' grammar, similar in style to the nft(8) man page.

As such, examples of shell code shall generally be of the following form.

<source>
# nft 'nftables commands go here'
</source>

Note that enclosing the ''nftables'' commands within single quotes is a straightforward way of preventing the shell from interpreting characters as metacharacters, most notably the semicolon. Rather, the shell will consider all that is between the pair of single quotes as a single word before passing it on to the nft(8) utility as a single argument, verbatim. Another way to prevent the shell from attempting to parse metacharacters is to run nft(8) in its interactive mode.

<source>
# nft -i
</source>

In that case, nft(8) will directly interpret any further input given until such time as it is either interrupted, encounters the end-of-file (EOF) condition, or encounters the "quit" command. In most terminal emulators, EOF can be conveyed with the Ctrl+D key combination.

Examples describing ''nftables'' grammar shall employ square brackets (U+5B, U+5D) to denote optional components of syntax, and angle brackets (U+3C, U+3D) to denote user-specified values.

= 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 for adding base chains is as follows.

<source>
add chain [<family>] <table_name> <chain_name> { type <type> hook <hook> [device <device>] priority <priority> ; [policy <policy> ;] [comment <comment> ;] }
</source>

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

<source>
# nft 'add chain ip filter input { type filter hook input priority 0; }'
</source>

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:

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; }'
</source>

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'':

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; policy accept; }'
</source>

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:
<source>
# nft 'add chain netdev filter eth0_filter { type filter hook ingress device eth0 priority 0; }'
</source>

== 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 [[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 ip 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!
}
}
</pre>

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 [http://people.netfilter.org/pablo/docs/login.pdf 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, the syntax for which is as follows.

<source>
add chain [family] <table_name> <chain_name> [comment <comment>]
</source>

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 =

The syntax for deleting chains is as follows.

<source>
delete chain [family] <table_name> <chain_name>
</source>

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>
# nft 'delete chain ip filter input'
<cmdline>:1:1-28: Error: Could not delete chain: Device or resource busy
delete chain ip filter input
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
</source>

You will have to [[Simple rule management|flush the ruleset]] in that chain before you can remove the chain.

= Flushing chains =

To flush a chain means to delete all of the rules that it contains, if any. The syntax for doing so is as follows.

<source>
flush chain [family] <table_name> <chain_name>
</source>

= 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:

<source>
# 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; }'
</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.

Here is the exact same policy, only shown in the declarative style. That is, in the same format as would be employed upon issuing the "list ruleset" command. Despite the marked difference in style, it constitutes valid ''nftables'' syntax and is equivalent to the combination of "add table" and "add chain" commands shown above.

<source>
table ip filter {
chain input {
type filter hook input priority filter; policy accept;
}

chain output {
type filter hook output priority filter; policy accept;
}
}
</source>

Configuring chains

2024-10-08T22:10:31Z

Plushkava: Replace a stray instance of "foo"

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.

= Syntactic conventions =

Naturally, in order to make use of ''nftables'' commands and directives, it is necessary to become familiar with them, along with their supported grammar. Even with that knowledge, users sometimes experience difficulties where passing ''nftables'' commands as arguments to the nft(8) utility. That's because shells recognise certain characters as metacharacters and treat them in a special way unless they are quoted.

Throughout this article, examples that begin with the hash character (U+23) can be taken as examples of valid shell code. That is, they are syntactically valid if entered into any implementation of the Shell Command Language, including bash. By contrast, examples that do not begin with the hash character can be interpreted as synopses of ''nftables'' grammar, similar in style to the nft(8) man page.

As such, examples of shell code shall generally be of the following form.

<source>
# nft 'nftables commands go here'
</source>

Note that enclosing the ''nftables'' commands within single quotes is a straightforward way of preventing the shell from interpreting characters as metacharacters, most notably the semicolon. Rather, the shell will consider all that is between the pair of single quotes as a single word before passing it on to the nft(8) utility as a single argument, verbatim. Another way to prevent the shell from attempting to parse metacharacters is to run nft(8) in its interactive mode.

<source>
# nft -i
</source>

In that case, nft(8) will directly interpret any further input given until such time as it is either interrupted, encounters the end-of-file (EOF) condition, or encounters the "quit" command. In most terminal emulators, EOF can be conveyed with the Ctrl+D key combination.

Examples describing ''nftables'' grammar shall employ square brackets (U+5B, U+5D) to denote optional components of syntax, and angle brackets (U+3C, U+3D) to denote user-specified values.

= 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 for adding base chains is as follows.

<source>
add chain [<family>] <table_name> <chain_name> { type <type> hook <hook> [device <device>] priority <priority> ; [policy <policy> ;] [comment <comment> ;] }
</source>

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

<source>
# nft 'add chain ip filter input { type filter hook input priority 0; }'
</source>

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:

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; }'
</source>

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'':

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; policy accept; }'
</source>

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:
<source>
# nft 'add chain netdev filter eth0_filter { type filter hook ingress device eth0 priority 0; }'
</source>

== 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 [[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 ip 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!
}
}
</pre>

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 [http://people.netfilter.org/pablo/docs/login.pdf 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, the syntax for which is as follows.

<source>
add chain [family] <table_name> <chain_name> [comment <comment>]
</source>

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 =

The syntax for deleting chains is as follows.

<source>
delete chain [family] <table_name> <chain_name>
</source>

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>
# nft 'delete chain ip filter input'
<cmdline>:1:1-28: Error: Could not delete chain: Device or resource busy
delete chain ip filter input
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
</source>

You will have to [[Simple rule management|flush the ruleset]] in that chain before you can remove the chain.

= Flushing chains =

To flush a chain means to delete all of the rules that it contains, if any. The syntax for doing so is as follows.

<source>
flush chain [family] <table_name> <chain_name>
</source>

= 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:

<source>
# 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; }'
</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.

Configuring chains

2024-10-08T22:08:57Z

Plushkava: Describe the conventions for examples of nftables grammar

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.

= Syntactic conventions =

Naturally, in order to make use of ''nftables'' commands and directives, it is necessary to become familiar with them, along with their supported grammar. Even with that knowledge, users sometimes experience difficulties where passing ''nftables'' commands as arguments to the nft(8) utility. That's because shells recognise certain characters as metacharacters and treat them in a special way unless they are quoted.

Throughout this article, examples that begin with the hash character (U+23) can be taken as examples of valid shell code. That is, they are syntactically valid if entered into any implementation of the Shell Command Language, including bash. By contrast, examples that do not begin with the hash character can be interpreted as synopses of ''nftables'' grammar, similar in style to the nft(8) man page.

As such, examples of shell code shall generally be of the following form.

<source>
# nft 'nftables commands go here'
</source>

Note that enclosing the ''nftables'' commands within single quotes is a straightforward way of preventing the shell from interpreting characters as metacharacters, most notably the semicolon. Rather, the shell will consider all that is between the pair of single quotes as a single word before passing it on to the nft(8) utility as a single argument, verbatim. Another way to prevent the shell from attempting to parse metacharacters is to run nft(8) in its interactive mode.

<source>
# nft -i
</source>

In that case, nft(8) will directly interpret any further input given until such time as it is either interrupted, encounters the end-of-file (EOF) condition, or encounters the "quit" command. In most terminal emulators, EOF can be conveyed with the Ctrl+D key combination.

Examples describing ''nftables'' grammar shall employ square brackets (U+5B, U+5D) to denote optional components of syntax, and angle brackets (U+3C, U+3D) to denote user-specified values.

= 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 for adding base chains is as follows.

<source>
add chain [<family>] <table_name> <chain_name> { type <type> hook <hook> [device <device>] priority <priority> ; [policy <policy> ;] [comment <comment> ;] }
</source>

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

<source>
# nft 'add chain ip filter input { type filter hook input priority 0; }'
</source>

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:

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; }'
</source>

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'':

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; policy accept; }'
</source>

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:
<source>
# nft 'add chain netdev filter eth0_filter { type filter hook ingress device eth0 priority 0; }'
</source>

== 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 [[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 ip 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!
}
}
</pre>

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 [http://people.netfilter.org/pablo/docs/login.pdf 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, the syntax for which is as follows.

<source>
add chain [family] <table_name> <chain_name> [comment <comment>]
</source>

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 =

The syntax for deleting chains is as follows.

<source>
delete chain [family] <table_name> <chain_name>
</source>

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>
# nft 'delete chain ip filter input'
<cmdline>:1:1-28: Error: Could not delete chain: Device or resource busy
delete chain ip filter input
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
</source>

You will have to [[Simple rule management|flush the ruleset]] in that chain before you can remove the chain.

= Flushing chains =

To flush a chain means to delete all of the rules that it contains, if any. The syntax for doing so is as follows.

<source>
flush chain [family] <table_name> <chain_name>
</source>

= 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:

<source>
# 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; }'
</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.

Configuring chains

2024-10-08T21:59:23Z

Plushkava: Extremely minor changes to Syntactic conventions

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.

= Syntactic conventions =

Naturally, in order to make use of ''nftables'' commands and directives, it is necessary to become familiar with them, along with their supported grammar. Even with that knowledge, users sometimes experience difficulties where passing ''nftables'' commands as arguments to the nft(8) utility. That's because shells recognise certain characters as metacharacters and treat them in a special way unless they are quoted.

Throughout this article, examples that begin with the hash character (#) can be taken as examples of valid shell code. That is, they are syntactically valid if entered into any implementation of the Shell Command Language, including bash. By contrast, examples that do not begin with the hash character can be interpreted as synopses of ''nftables'' grammar, similar in style to the nft(8) man page.

As such, examples of shell code shall generally be of the following form.

<source>
# nft 'nftables commands go here'
</source>

Note that enclosing the ''nftables'' commands within single quotes is a straightforward way of preventing the shell from interpreting characters as metacharacters, most notably the semicolon. Rather, the shell will consider all that is between the pair of single quotes as a single word before passing it on to the nft(8) utility as a single argument, verbatim. Another way to prevent the shell from attempting to parse metacharacters is to run nft(8) in its interactive mode.

<source>
# nft -i
</source>

In that case, nft(8) will directly interpret any further input given until such time as it is either interrupted, encounters the end-of-file (EOF) condition, or encounters the "quit" command. In most terminal emulators, EOF can be conveyed with the Ctrl+D key combination.

= 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 for adding base chains is as follows.

<source>
add chain [<family>] <table_name> <chain_name> { type <type> hook <hook> [device <device>] priority <priority> ; [policy <policy> ;] [comment <comment> ;] }
</source>

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

<source>
# nft 'add chain ip filter input { type filter hook input priority 0; }'
</source>

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:

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; }'
</source>

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'':

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; policy accept; }'
</source>

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:
<source>
# nft 'add chain netdev filter eth0_filter { type filter hook ingress device eth0 priority 0; }'
</source>

== 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 [[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 ip 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!
}
}
</pre>

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 [http://people.netfilter.org/pablo/docs/login.pdf 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, the syntax for which is as follows.

<source>
add chain [family] <table_name> <chain_name> [comment <comment>]
</source>

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 =

The syntax for deleting chains is as follows.

<source>
delete chain [family] <table_name> <chain_name>
</source>

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>
# nft 'delete chain ip filter input'
<cmdline>:1:1-28: Error: Could not delete chain: Device or resource busy
delete chain ip filter input
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
</source>

You will have to [[Simple rule management|flush the ruleset]] in that chain before you can remove the chain.

= Flushing chains =

To flush a chain means to delete all of the rules that it contains, if any. The syntax for doing so is as follows.

<source>
flush chain [family] <table_name> <chain_name>
</source>

= 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:

<source>
# 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; }'
</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.

Configuring chains

2024-10-08T21:56:30Z

Plushkava: Add a "Syntactic conventions" section in an attempt to bring the standard closer to that of formal documentation; have it subsume the aside regarding matters of shell quoting that was previously in the "Adding base chains" section

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.

= Syntactic conventions =

Naturally, in order to make use of ''nftables'' commands and directives, it is necessary to become familiar with them, along with their supported grammar. Even with that knowledge, users sometimes experience difficulties where passing nftables commands as arguments to the nft(8) utility. That's because shells recognise certain characters as metacharacters and treat them in a special way unless they are quoted.

Throughout this article, examples that begin with the hash character (#) can be taken as examples of valid shell code. That is, they are syntactically valid if entered into any implementation of the Shell Command Language, including bash. By contrast, examples that do not begin with the hash character can be interpreted as synopses of ''nftables'' grammar, similar in style to the nft(8) man page.

As such, examples of shell code shall generally be of the following form.

<source>
# nft 'nftables commands go here'
</source>

Note that enclosing the ''nftables'' command(s) within single quotes is a straightforward way of preventing the shell from interpreting characters as metacharacters, most notably the semicolon. Rather, the shell will consider all that is between the pair of single quotes as a single word before it on to the nft(8) utility as single argument, verbatim. Another way to prevent the shell from attempting to parse metacharacters is to run nft(8) in its interactive mode.

<source>
# nft -i
</source>

In that case, nft(8) will directly interpret any further input given until such time as it is either interrupted, encounters the end-of-file (EOF) condition, or encounters the "quit" command. In most terminal emulators, EOF can be conveyed with the Ctrl+D key combination.

= 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 for adding base chains is as follows.

<source>
add chain [<family>] <table_name> <chain_name> { type <type> hook <hook> [device <device>] priority <priority> ; [policy <policy> ;] [comment <comment> ;] }
</source>

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

<source>
# nft 'add chain ip filter input { type filter hook input priority 0; }'
</source>

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:

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; }'
</source>

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'':

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; policy accept; }'
</source>

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:
<source>
# nft 'add chain netdev filter eth0_filter { type filter hook ingress device eth0 priority 0; }'
</source>

== 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 [[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 ip 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!
}
}
</pre>

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 [http://people.netfilter.org/pablo/docs/login.pdf 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, the syntax for which is as follows.

<source>
add chain [family] <table_name> <chain_name> [comment <comment>]
</source>

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 =

The syntax for deleting chains is as follows.

<source>
delete chain [family] <table_name> <chain_name>
</source>

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>
# nft 'delete chain ip filter input'
<cmdline>:1:1-28: Error: Could not delete chain: Device or resource busy
delete chain ip filter input
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
</source>

You will have to [[Simple rule management|flush the ruleset]] in that chain before you can remove the chain.

= Flushing chains =

To flush a chain means to delete all of the rules that it contains, if any. The syntax for doing so is as follows.

<source>
flush chain [family] <table_name> <chain_name>
</source>

= 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:

<source>
# 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; }'
</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.

Configuring chains

2024-10-08T21:22:05Z

Plushkava: Introduce nft grammar with a consistent style of English; make the flush chain example an example of grammar rather than an example of a shell command (just like how the section on deleting begins)

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 =

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 for adding base chains is as follows.

<source>
add chain [<family>] <table_name> <chain_name> { type <type> hook <hook> [device <device>] priority <priority> ; [policy <policy> ;] [comment <comment> ;] }
</source>

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

<source>
# nft 'add chain ip filter input { type filter hook input priority 0; }'
</source>

'''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>
# nft -i
</source>

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:

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; }'
</source>

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'':

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; policy accept; }'
</source>

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:
<source>
# nft 'add chain netdev filter eth0_filter { type filter hook ingress device eth0 priority 0; }'
</source>

== 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 [[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 ip 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!
}
}
</pre>

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 [http://people.netfilter.org/pablo/docs/login.pdf 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, the syntax for which is as follows.

<source>
add chain [family] <table_name> <chain_name> [comment <comment>]
</source>

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 =

The syntax for deleting chains is as follows.

<source>
delete chain [family] <table_name> <chain_name>
</source>

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>
# nft 'delete chain ip filter input'
<cmdline>:1:1-28: Error: Could not delete chain: Device or resource busy
delete chain ip filter input
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
</source>

You will have to [[Simple rule management|flush the ruleset]] in that chain before you can remove the chain.

= Flushing chains =

To flush a chain means to delete all of the rules that it contains, if any. The syntax for doing so is as follows.

<source>
flush chain [family] <table_name> <chain_name>
</source>

= 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:

<source>
# 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; }'
</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.

Configuring chains

2024-10-08T20:57:10Z

Plushkava: Employ a chain name of eth0_filter rather than dev0filter in the ingress hook example (it seems a little clearer)

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 =

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>
add chain [<family>] <table_name> <chain_name> { type <type> hook <hook> [device <device>] priority <priority> ; [policy <policy> ;] [comment <comment> ;] }
</source>

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

<source>
# nft 'add chain ip filter input { type filter hook input priority 0; }'
</source>

'''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>
# nft -i
</source>

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:

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; }'
</source>

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'':

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; policy accept; }'
</source>

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:
<source>
# nft 'add chain netdev filter eth0_filter { type filter hook ingress device eth0 priority 0; }'
</source>

== 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 [[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 ip 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!
}
}
</pre>

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 [http://people.netfilter.org/pablo/docs/login.pdf 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:

<source>
add chain [family] <table_name> <chain_name> [comment <comment>]
</source>

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 =

You can delete chains as:

<source>
delete chain [family] <table_name> <chain_name>
</source>

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>
# nft 'delete chain ip filter input'
<cmdline>:1:1-28: Error: Could not delete chain: Device or resource busy
delete chain ip filter input
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
</source>

You will have to [[Simple rule management|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 ''filter'' table associated with the ''ip' family:

<source>
# nft 'flush chain ip filter input'
</source>

= 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:

<source>
# 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; }'
</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.

Configuring chains

2024-10-08T20:49:22Z

Plushkava: Consistently use table/chain names that reflect iptables norms, just as the final <source> block already does

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 =

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>
add chain [<family>] <table_name> <chain_name> { type <type> hook <hook> [device <device>] priority <priority> ; [policy <policy> ;] [comment <comment> ;] }
</source>

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

<source>
# nft 'add chain ip filter input { type filter hook input priority 0; }'
</source>

'''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>
# nft -i
</source>

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:

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; }'
</source>

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'':

<source>
# nft 'add chain ip filter output { type filter hook output priority 0; policy accept; }'
</source>

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:
<source>
# nft 'add chain netdev filter dev0filter { type filter hook ingress device eth0 priority 0; }'
</source>

== 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 [[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 ip 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!
}
}
</pre>

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 [http://people.netfilter.org/pablo/docs/login.pdf 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:

<source>
add chain [family] <table_name> <chain_name> [comment <comment>]
</source>

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 =

You can delete chains as:

<source>
delete chain [family] <table_name> <chain_name>
</source>

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>
# nft 'delete chain ip filter input'
<cmdline>:1:1-28: Error: Could not delete chain: Device or resource busy
delete chain ip filter input
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
</source>

You will have to [[Simple rule management|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 ''filter'' table associated with the ''ip' family:

<source>
# nft 'flush chain ip filter input'
</source>

= 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:

<source>
# 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; }'
</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.

Configuring chains

2024-10-08T20:40:01Z

Plushkava: Use # to denote a shell prompt (as is typical for a root session in virtually any sh implementation, including the ever-popular bash); only include a faux-prompt in examples intended to show shell commands rather than those that act as synopses of nft(8) grammar; don't apply bash syntax highlighting (it hinders more than it helps); employ shell quoting consistently in all examples

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 =

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>
add chain [<family>] <table_name> <chain_name> { type <type> hook <hook> [device <device>] priority <priority> ; [policy <policy> ;] [comment <comment> ;] }
</source>

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

<source>
# nft 'add chain ip foo input { type filter hook input priority 0; }'
</source>

'''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>
# nft -i
</source>

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:

<source>
# nft 'add chain ip foo output { type filter hook output priority 0; }'
</source>

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'':

<source>
# nft 'add chain ip foo output { type filter hook output priority 0; policy accept; }'
</source>

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:
<source>
# nft 'add chain netdev foo dev0filter { type filter hook ingress device eth0 priority 0; }'
</source>

== 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 [[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
}

# 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>

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 [http://people.netfilter.org/pablo/docs/login.pdf 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:

<source>
add chain [family] <table_name> <chain_name> [comment <comment>]
</source>

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 =

You can delete chains as:

<source>
delete chain [family] <table_name> <chain_name>
</source>

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>
# nft 'delete chain ip foo input'
<cmdline>:1:1-28: Error: Could not delete chain: Device or resource busy
delete chain ip foo input
^^^^^^^^^^^^^^^^^^^^^^^^^
</source>

You will have to [[Simple rule management|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:

<source>
# nft 'flush chain foo input'
</source>

= 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:

<source>
# 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; }'
</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.

Configuring chains

2024-10-08T20:29:08Z

Plushkava: Clean up the synopsis for adding base chains; have it cover "device"

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 =

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">
# nft add chain [<family>] <table_name> <chain_name> { type <type> hook <hook> [device <device>] priority <priority> ; [policy <policy> ;] [comment <comment> ;] }
</source>

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>

'''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">
% nft -i
</source>

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:

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

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'':

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

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:
<source lang="bash">
% nft 'add chain netdev foo dev0filter { type filter hook ingress device eth0 priority 0 ; }'
</source>

== 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 [[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
}

# 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>

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 [http://people.netfilter.org/pablo/docs/login.pdf 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:

<source>
# nft add chain [family] <table_name> <chain_name> [comment <comment>]
</source>

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 =

You can delete chains as:

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

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">
% nft delete chain ip foo input
<cmdline>:1:1-28: Error: Could not delete chain: Device or resource busy
delete chain ip foo input
^^^^^^^^^^^^^^^^^^^^^^^^^
</source>

You will have to [[Simple rule management|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:

<source lang="bash">
nft flush chain foo input
</source>

= 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:

<source lang="bash">
% 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 ; }'
</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.

Configuring chains

2024-10-08T20:20:07Z

Plushkava: Correct the synopsis for adding 'regular' chains

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 =

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">
% nft add chain [<family>] <table_name> <chain_name> { type <type> hook <hook> priority <value> \; [policy <policy> \;] [comment \"text comment\" \;] }
</source>

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>

'''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">
% nft -i
</source>

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:

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

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'':

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

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:
<source lang="bash">
% nft 'add chain netdev foo dev0filter { type filter hook ingress device eth0 priority 0 ; }'
</source>

== 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 [[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
}

# 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>

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 [http://people.netfilter.org/pablo/docs/login.pdf 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:

<source>
# nft add chain [family] <table_name> <chain_name> [comment <comment>]
</source>

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 =

You can delete chains as:

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

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">
% nft delete chain ip foo input
<cmdline>:1:1-28: Error: Could not delete chain: Device or resource busy
delete chain ip foo input
^^^^^^^^^^^^^^^^^^^^^^^^^
</source>

You will have to [[Simple rule management|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:

<source lang="bash">
nft flush chain foo input
</source>

= 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:

<source lang="bash">
% 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 ; }'
</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.

Performing Network Address Translation (NAT)

2024-02-07T22:51:16Z

Plushkava: Refrain from over-using "note that" as a phrase

The ''nat'' chain type allows you to perform [https://en.wikipedia.org/wiki/Network_address_translation NAT]. This chain type comes with special semantics:

* The first packet of a flow is used to look up for a matching rule which sets up the NAT binding for this flow. This also manipulates this first packet accordingly.
* No rule lookup happens for follow up packets in the flow: the NAT engine uses the NAT binding information already set up by the first packet to perform the packet manipulation.

Adding a NAT rule to a filter type chain will result in an error.

= Stateful NAT =

The stateful NAT involves the nf_conntrack kernel engine to match/set packet stateful information and will engage according to the state of connections.
This is the most common way of performing NAT and the approach we recommend you to follow.

Be aware that '''with kernel versions before 4.18, you have to register the prerouting/postrouting chains even if you have no rules there''' since these chain will invoke the NAT engine for the packets coming in the reply direction. The remaining documentation in this article assumes a newer kernel which doesn't require this inconvenience anymore.

== Source NAT ==

If you want to source NAT the traffic that leaves from your local area network to the Internet, you can create a new table ''nat'' with the postrouting chain:

<source lang="bash">
% nft add table nat
% nft 'add chain nat postrouting { type nat hook postrouting priority 100 ; }'
</source>

Then, add the following rule:

<source lang="bash">
% nft add rule nat postrouting ip saddr 192.168.1.0/24 oif eth0 snat to 1.2.3.4
</source>

This matches for all traffic from the 192.168.1.0/24 network to the interface ''eth0''. The IPv4 address 1.2.3.4 is used as source for the packets that match this rule.

=== NAT pooling ===

It is possible to specify source NAT pooling:

<source lang="bash">
% nft add rule inet nat postrouting snat ip to 10.0.0.2/31
% nft add rule inet nat postrouting snat ip to 10.0.0.4-10.0.0.127
</source>

With transport protocol source port mapping:

<source lang="bash">
% nft add rule inet nat postrouting ip protocol tcp snat ip to 10.0.0.1-10.0.0.100:3000-4000
</source>

== Destination NAT ==

You need to add the following table and chain configuration:

<source lang="bash">
% nft add table nat
% nft 'add chain nat prerouting { type nat hook prerouting priority -100; }'
</source>

Then, you can add the following rule:

<source lang="bash">
% nft 'add rule nat prerouting iif eth0 tcp dport { 80, 443 } dnat to 192.168.1.120'
</source>

This redirects the incoming traffic for TCP ports 80 and 443 to 192.168.1.120.

== Masquerading ==

NOTE: ''masquerade'' is available starting with Linux Kernel 3.18.

Masquerade is a special case of SNAT, where the source address is automagically set to the address of the output interface. For example:

<source lang="bash">
% nft add rule nat postrouting masquerade
</source>

Note that ''masquerade'' only makes sense from postrouting chain of NAT type.

== Redirect ==

NOTE: ''redirect'' is available starting with Linux Kernel 3.19.

By using redirect, packets will be forwarded to local machine. Is a special case of DNAT where the destination is the current machine.

<source lang="bash">
% nft add rule nat prerouting redirect
</source>

This example redirects 22/tcp traffic to 2222/tcp:

<source lang="bash">
% nft add rule nat prerouting tcp dport 22 redirect to 2222
</source>

This example redirects outgoing 53/tcp traffic to a local proxy listening on port 10053/tcp:

<source lang="bash">
% nft add rule nat output tcp dport 853 redirect to 10053
</source>

Note that: ''redirect'' only makes sense in prerouting and output chains of NAT type.

== NAT flags ==

Since Linux kernel 3.18, you can combine the following flags with your NAT statements:

* random: randomize source port mapping.
* fully-random: full port randomization.
* persistent: gives a client the same source-/destination-address for each connection.

For example:

<source lang="bash">
% nft add rule nat postrouting masquerade random,persistent
% nft add rule nat postrouting ip saddr 192.168.1.0/24 oif eth0 snat to 1.2.3.4 fully-random
</source>

== Inet family NAT ==

Since Linux kernel 5.2, there is support for performing stateful NAT in ''inet'' family chains. Syntax and semantics are equivalent to ''ip''/''ip6'' families; the only exception being if IP addresses are specified, a prefix of either ''ip'' or ''ip6'' to clarify the address family is required:

<source lang="bash">
% nft add rule inet nat prerouting dnat ip to 10.0.0.2
% nft add rule inet nat prerouting dnat ip6 to feed::c0fe
</source>

== Incompatibilities ==

You cannot use iptables and nft to perform NAT at the same time before kernel 4.18. So make sure that the ''iptable_nat'' module is unloaded:

<source lang="bash">
% rmmod iptable_nat
</source>

With later kernels, it is possible to use iptables and nftables nat at the same time.
The nat chains are consulted according to their priorities, the first matching rule
that adds a nat mapping (dnat, snat, masquerade) is the one that will be used for the connection.

= Stateless NAT =

This type of NAT just modifies each packet according to your rules without any other state/connection tracking. This is valid for 1:1 mappings and is faster than stateful NAT. However, it's easy to shoot yourself in the foot. If your environment doesn't require this approach, better stick to stateful NAT.

You have to disable connection tracking for modified packets. This can be accomplished by incorporating the '''notrack''' keyword into the rule. Doing so attaches a template connection tracking entry to the packet that instructs the conntrack core not to initialize a new entry in the conntrack table. The use of a hook at - or below - a priority level of '''raw''' is required. Otherwise, '''notrack''' will not be dealt with prior to the consultation of the conntrack table.

The ruleset below demonstrates how to rewrite both the destination IP and port for each packet (also covering IPv6). Note that the rules presented affect ''all'' TCP packets arriving at ''all'' interfaces and are intended only for demonstrative purposes.

<source>
table inet raw {
chain prerouting {
type filter hook prerouting priority raw; policy accept;
ip protocol tcp ip daddr set 192.168.1.100 tcp dport set 10 notrack
ip6 nexthdr tcp ip6 daddr set fe00::1 tcp dport set 10 notrack
}
}
</source>

Be sure to check our documentation regarding [[Mangling_packet_headers|mangling packets]] and [[setting packet connection tracking metainformation]].

To use this feature you require nftables >=0.7 and linux kernel >= 4.9.

= See also =

* [[Multiple_NATs_using_nftables_maps | Example: multiple NATs using nftables maps]]

Performing Network Address Translation (NAT)

2024-02-07T20:41:34Z

Plushkava: Clarify wording regarding stateless rule specificity

The ''nat'' chain type allows you to perform [https://en.wikipedia.org/wiki/Network_address_translation NAT]. This chain type comes with special semantics:

* The first packet of a flow is used to look up for a matching rule which sets up the NAT binding for this flow. This also manipulates this first packet accordingly.
* No rule lookup happens for follow up packets in the flow: the NAT engine uses the NAT binding information already set up by the first packet to perform the packet manipulation.

Adding a NAT rule to a filter type chain will result in an error.

= Stateful NAT =

The stateful NAT involves the nf_conntrack kernel engine to match/set packet stateful information and will engage according to the state of connections.
This is the most common way of performing NAT and the approach we recommend you to follow.

Be aware that '''with kernel versions before 4.18, you have to register the prerouting/postrouting chains even if you have no rules there''' since these chain will invoke the NAT engine for the packets coming in the reply direction. The remaining documentation in this article assumes a newer kernel which doesn't require this inconvenience anymore.

== Source NAT ==

If you want to source NAT the traffic that leaves from your local area network to the Internet, you can create a new table ''nat'' with the postrouting chain:

<source lang="bash">
% nft add table nat
% nft 'add chain nat postrouting { type nat hook postrouting priority 100 ; }'
</source>

Then, add the following rule:

<source lang="bash">
% nft add rule nat postrouting ip saddr 192.168.1.0/24 oif eth0 snat to 1.2.3.4
</source>

This matches for all traffic from the 192.168.1.0/24 network to the interface ''eth0''. The IPv4 address 1.2.3.4 is used as source for the packets that match this rule.

=== NAT pooling ===

It is possible to specify source NAT pooling:

<source lang="bash">
% nft add rule inet nat postrouting snat ip to 10.0.0.2/31
% nft add rule inet nat postrouting snat ip to 10.0.0.4-10.0.0.127
</source>

With transport protocol source port mapping:

<source lang="bash">
% nft add rule inet nat postrouting ip protocol tcp snat ip to 10.0.0.1-10.0.0.100:3000-4000
</source>

== Destination NAT ==

You need to add the following table and chain configuration:

<source lang="bash">
% nft add table nat
% nft 'add chain nat prerouting { type nat hook prerouting priority -100; }'
</source>

Then, you can add the following rule:

<source lang="bash">
% nft 'add rule nat prerouting iif eth0 tcp dport { 80, 443 } dnat to 192.168.1.120'
</source>

This redirects the incoming traffic for TCP ports 80 and 443 to 192.168.1.120.

== Masquerading ==

NOTE: ''masquerade'' is available starting with Linux Kernel 3.18.

Masquerade is a special case of SNAT, where the source address is automagically set to the address of the output interface. For example:

<source lang="bash">
% nft add rule nat postrouting masquerade
</source>

Note that ''masquerade'' only makes sense from postrouting chain of NAT type.

== Redirect ==

NOTE: ''redirect'' is available starting with Linux Kernel 3.19.

By using redirect, packets will be forwarded to local machine. Is a special case of DNAT where the destination is the current machine.

<source lang="bash">
% nft add rule nat prerouting redirect
</source>

This example redirects 22/tcp traffic to 2222/tcp:

<source lang="bash">
% nft add rule nat prerouting tcp dport 22 redirect to 2222
</source>

This example redirects outgoing 53/tcp traffic to a local proxy listening on port 10053/tcp:

<source lang="bash">
% nft add rule nat output tcp dport 853 redirect to 10053
</source>

Note that: ''redirect'' only makes sense in prerouting and output chains of NAT type.

== NAT flags ==

Since Linux kernel 3.18, you can combine the following flags with your NAT statements:

* random: randomize source port mapping.
* fully-random: full port randomization.
* persistent: gives a client the same source-/destination-address for each connection.

For example:

<source lang="bash">
% nft add rule nat postrouting masquerade random,persistent
% nft add rule nat postrouting ip saddr 192.168.1.0/24 oif eth0 snat to 1.2.3.4 fully-random
</source>

== Inet family NAT ==

Since Linux kernel 5.2, there is support for performing stateful NAT in ''inet'' family chains. Syntax and semantics are equivalent to ''ip''/''ip6'' families; the only exception being if IP addresses are specified, a prefix of either ''ip'' or ''ip6'' to clarify the address family is required:

<source lang="bash">
% nft add rule inet nat prerouting dnat ip to 10.0.0.2
% nft add rule inet nat prerouting dnat ip6 to feed::c0fe
</source>

== Incompatibilities ==

You cannot use iptables and nft to perform NAT at the same time before kernel 4.18. So make sure that the ''iptable_nat'' module is unloaded:

<source lang="bash">
% rmmod iptable_nat
</source>

With later kernels, it is possible to use iptables and nftables nat at the same time.
The nat chains are consulted according to their priorities, the first matching rule
that adds a nat mapping (dnat, snat, masquerade) is the one that will be used for the connection.

= Stateless NAT =

This type of NAT just modifies each packet according to your rules without any other state/connection tracking. This is valid for 1:1 mappings and is faster than stateful NAT. However, it's easy to shoot yourself in the foot. If your environment doesn't require this approach, better stick to stateful NAT.

You have to disable connection tracking for modified packets. This can be accomplished by incorporating the '''notrack''' keyword into the rule. Doing so attaches a template connection tracking entry to the packet that instructs the conntrack core not to initialize a new entry in the conntrack table. Note that this requires the use of a hook at - or below - a priority level of '''raw'''. Otherwise, '''notrack''' will not be dealt with prior to the consultation of the conntrack table.

The ruleset below demonstrates how to rewrite both the destination IP and port for each packet (also covering IPv6). Note that the rules affect ''all'' TCP packets arriving at ''all'' interfaces and are intended only for demonstrative purposes.

<source>
table inet raw {
chain prerouting {
type filter hook prerouting priority raw; policy accept;
ip protocol tcp ip daddr set 192.168.1.100 tcp dport set 10 notrack
ip6 nexthdr tcp ip6 daddr set fe00::1 tcp dport set 10 notrack
}
}
</source>

Be sure to check our documentation regarding [[Mangling_packet_headers|mangling packets]] and [[setting packet connection tracking metainformation]].

To use this feature you require nftables >=0.7 and linux kernel >= 4.9.

= See also =

* [[Multiple_NATs_using_nftables_maps | Example: multiple NATs using nftables maps]]

Performing Network Address Translation (NAT)

2024-02-07T20:38:10Z

Plushkava: Indicate that the sample stateless NAT rules are loose in nature

The ''nat'' chain type allows you to perform [https://en.wikipedia.org/wiki/Network_address_translation NAT]. This chain type comes with special semantics:

* The first packet of a flow is used to look up for a matching rule which sets up the NAT binding for this flow. This also manipulates this first packet accordingly.
* No rule lookup happens for follow up packets in the flow: the NAT engine uses the NAT binding information already set up by the first packet to perform the packet manipulation.

Adding a NAT rule to a filter type chain will result in an error.

= Stateful NAT =

The stateful NAT involves the nf_conntrack kernel engine to match/set packet stateful information and will engage according to the state of connections.
This is the most common way of performing NAT and the approach we recommend you to follow.

Be aware that '''with kernel versions before 4.18, you have to register the prerouting/postrouting chains even if you have no rules there''' since these chain will invoke the NAT engine for the packets coming in the reply direction. The remaining documentation in this article assumes a newer kernel which doesn't require this inconvenience anymore.

== Source NAT ==

If you want to source NAT the traffic that leaves from your local area network to the Internet, you can create a new table ''nat'' with the postrouting chain:

<source lang="bash">
% nft add table nat
% nft 'add chain nat postrouting { type nat hook postrouting priority 100 ; }'
</source>

Then, add the following rule:

<source lang="bash">
% nft add rule nat postrouting ip saddr 192.168.1.0/24 oif eth0 snat to 1.2.3.4
</source>

This matches for all traffic from the 192.168.1.0/24 network to the interface ''eth0''. The IPv4 address 1.2.3.4 is used as source for the packets that match this rule.

=== NAT pooling ===

It is possible to specify source NAT pooling:

<source lang="bash">
% nft add rule inet nat postrouting snat ip to 10.0.0.2/31
% nft add rule inet nat postrouting snat ip to 10.0.0.4-10.0.0.127
</source>

With transport protocol source port mapping:

<source lang="bash">
% nft add rule inet nat postrouting ip protocol tcp snat ip to 10.0.0.1-10.0.0.100:3000-4000
</source>

== Destination NAT ==

You need to add the following table and chain configuration:

<source lang="bash">
% nft add table nat
% nft 'add chain nat prerouting { type nat hook prerouting priority -100; }'
</source>

Then, you can add the following rule:

<source lang="bash">
% nft 'add rule nat prerouting iif eth0 tcp dport { 80, 443 } dnat to 192.168.1.120'
</source>

This redirects the incoming traffic for TCP ports 80 and 443 to 192.168.1.120.

== Masquerading ==

NOTE: ''masquerade'' is available starting with Linux Kernel 3.18.

Masquerade is a special case of SNAT, where the source address is automagically set to the address of the output interface. For example:

<source lang="bash">
% nft add rule nat postrouting masquerade
</source>

Note that ''masquerade'' only makes sense from postrouting chain of NAT type.

== Redirect ==

NOTE: ''redirect'' is available starting with Linux Kernel 3.19.

By using redirect, packets will be forwarded to local machine. Is a special case of DNAT where the destination is the current machine.

<source lang="bash">
% nft add rule nat prerouting redirect
</source>

This example redirects 22/tcp traffic to 2222/tcp:

<source lang="bash">
% nft add rule nat prerouting tcp dport 22 redirect to 2222
</source>

This example redirects outgoing 53/tcp traffic to a local proxy listening on port 10053/tcp:

<source lang="bash">
% nft add rule nat output tcp dport 853 redirect to 10053
</source>

Note that: ''redirect'' only makes sense in prerouting and output chains of NAT type.

== NAT flags ==

Since Linux kernel 3.18, you can combine the following flags with your NAT statements:

* random: randomize source port mapping.
* fully-random: full port randomization.
* persistent: gives a client the same source-/destination-address for each connection.

For example:

<source lang="bash">
% nft add rule nat postrouting masquerade random,persistent
% nft add rule nat postrouting ip saddr 192.168.1.0/24 oif eth0 snat to 1.2.3.4 fully-random
</source>

== Inet family NAT ==

Since Linux kernel 5.2, there is support for performing stateful NAT in ''inet'' family chains. Syntax and semantics are equivalent to ''ip''/''ip6'' families; the only exception being if IP addresses are specified, a prefix of either ''ip'' or ''ip6'' to clarify the address family is required:

<source lang="bash">
% nft add rule inet nat prerouting dnat ip to 10.0.0.2
% nft add rule inet nat prerouting dnat ip6 to feed::c0fe
</source>

== Incompatibilities ==

You cannot use iptables and nft to perform NAT at the same time before kernel 4.18. So make sure that the ''iptable_nat'' module is unloaded:

<source lang="bash">
% rmmod iptable_nat
</source>

With later kernels, it is possible to use iptables and nftables nat at the same time.
The nat chains are consulted according to their priorities, the first matching rule
that adds a nat mapping (dnat, snat, masquerade) is the one that will be used for the connection.

= Stateless NAT =

This type of NAT just modifies each packet according to your rules without any other state/connection tracking. This is valid for 1:1 mappings and is faster than stateful NAT. However, it's easy to shoot yourself in the foot. If your environment doesn't require this approach, better stick to stateful NAT.

You have to disable connection tracking for modified packets. This can be accomplished by incorporating the '''notrack''' keyword into the rule. Doing so attaches a template connection tracking entry to the packet that instructs the conntrack core not to initialize a new entry in the conntrack table. Note that this requires the use of a hook at - or below - a priority level of '''raw'''. Otherwise, '''notrack''' will not be dealt with prior to the consultation of the conntrack table.

The ruleset below demonstrates how to rewrite both the destination IP and port for each packet (also covering IPv6). Note that the rules affect ''all'' packets arriving at ''all'' interfaces and are intended only for demonstrative purposes.

<source>
table inet raw {
chain prerouting {
type filter hook prerouting priority raw; policy accept;
ip protocol tcp ip daddr set 192.168.1.100 tcp dport set 10 notrack
ip6 nexthdr tcp ip6 daddr set fe00::1 tcp dport set 10 notrack
}
}
</source>

Be sure to check our documentation regarding [[Mangling_packet_headers|mangling packets]] and [[setting packet connection tracking metainformation]].

To use this feature you require nftables >=0.7 and linux kernel >= 4.9.

= See also =

* [[Multiple_NATs_using_nftables_maps | Example: multiple NATs using nftables maps]]

Performing Network Address Translation (NAT)

2024-02-07T20:34:41Z

Plushkava: Very minor wording change

The ''nat'' chain type allows you to perform [https://en.wikipedia.org/wiki/Network_address_translation NAT]. This chain type comes with special semantics:

* The first packet of a flow is used to look up for a matching rule which sets up the NAT binding for this flow. This also manipulates this first packet accordingly.
* No rule lookup happens for follow up packets in the flow: the NAT engine uses the NAT binding information already set up by the first packet to perform the packet manipulation.

Adding a NAT rule to a filter type chain will result in an error.

= Stateful NAT =

The stateful NAT involves the nf_conntrack kernel engine to match/set packet stateful information and will engage according to the state of connections.
This is the most common way of performing NAT and the approach we recommend you to follow.

Be aware that '''with kernel versions before 4.18, you have to register the prerouting/postrouting chains even if you have no rules there''' since these chain will invoke the NAT engine for the packets coming in the reply direction. The remaining documentation in this article assumes a newer kernel which doesn't require this inconvenience anymore.

== Source NAT ==

If you want to source NAT the traffic that leaves from your local area network to the Internet, you can create a new table ''nat'' with the postrouting chain:

<source lang="bash">
% nft add table nat
% nft 'add chain nat postrouting { type nat hook postrouting priority 100 ; }'
</source>

Then, add the following rule:

<source lang="bash">
% nft add rule nat postrouting ip saddr 192.168.1.0/24 oif eth0 snat to 1.2.3.4
</source>

This matches for all traffic from the 192.168.1.0/24 network to the interface ''eth0''. The IPv4 address 1.2.3.4 is used as source for the packets that match this rule.

=== NAT pooling ===

It is possible to specify source NAT pooling:

<source lang="bash">
% nft add rule inet nat postrouting snat ip to 10.0.0.2/31
% nft add rule inet nat postrouting snat ip to 10.0.0.4-10.0.0.127
</source>

With transport protocol source port mapping:

<source lang="bash">
% nft add rule inet nat postrouting ip protocol tcp snat ip to 10.0.0.1-10.0.0.100:3000-4000
</source>

== Destination NAT ==

You need to add the following table and chain configuration:

<source lang="bash">
% nft add table nat
% nft 'add chain nat prerouting { type nat hook prerouting priority -100; }'
</source>

Then, you can add the following rule:

<source lang="bash">
% nft 'add rule nat prerouting iif eth0 tcp dport { 80, 443 } dnat to 192.168.1.120'
</source>

This redirects the incoming traffic for TCP ports 80 and 443 to 192.168.1.120.

== Masquerading ==

NOTE: ''masquerade'' is available starting with Linux Kernel 3.18.

Masquerade is a special case of SNAT, where the source address is automagically set to the address of the output interface. For example:

<source lang="bash">
% nft add rule nat postrouting masquerade
</source>

Note that ''masquerade'' only makes sense from postrouting chain of NAT type.

== Redirect ==

NOTE: ''redirect'' is available starting with Linux Kernel 3.19.

By using redirect, packets will be forwarded to local machine. Is a special case of DNAT where the destination is the current machine.

<source lang="bash">
% nft add rule nat prerouting redirect
</source>

This example redirects 22/tcp traffic to 2222/tcp:

<source lang="bash">
% nft add rule nat prerouting tcp dport 22 redirect to 2222
</source>

This example redirects outgoing 53/tcp traffic to a local proxy listening on port 10053/tcp:

<source lang="bash">
% nft add rule nat output tcp dport 853 redirect to 10053
</source>

Note that: ''redirect'' only makes sense in prerouting and output chains of NAT type.

== NAT flags ==

Since Linux kernel 3.18, you can combine the following flags with your NAT statements:

* random: randomize source port mapping.
* fully-random: full port randomization.
* persistent: gives a client the same source-/destination-address for each connection.

For example:

<source lang="bash">
% nft add rule nat postrouting masquerade random,persistent
% nft add rule nat postrouting ip saddr 192.168.1.0/24 oif eth0 snat to 1.2.3.4 fully-random
</source>

== Inet family NAT ==

Since Linux kernel 5.2, there is support for performing stateful NAT in ''inet'' family chains. Syntax and semantics are equivalent to ''ip''/''ip6'' families; the only exception being if IP addresses are specified, a prefix of either ''ip'' or ''ip6'' to clarify the address family is required:

<source lang="bash">
% nft add rule inet nat prerouting dnat ip to 10.0.0.2
% nft add rule inet nat prerouting dnat ip6 to feed::c0fe
</source>

== Incompatibilities ==

You cannot use iptables and nft to perform NAT at the same time before kernel 4.18. So make sure that the ''iptable_nat'' module is unloaded:

<source lang="bash">
% rmmod iptable_nat
</source>

With later kernels, it is possible to use iptables and nftables nat at the same time.
The nat chains are consulted according to their priorities, the first matching rule
that adds a nat mapping (dnat, snat, masquerade) is the one that will be used for the connection.

= Stateless NAT =

This type of NAT just modifies each packet according to your rules without any other state/connection tracking. This is valid for 1:1 mappings and is faster than stateful NAT. However, it's easy to shoot yourself in the foot. If your environment doesn't require this approach, better stick to stateful NAT.

You have to disable connection tracking for modified packets. This can be accomplished by incorporating the '''notrack''' keyword into the rule. Doing so attaches a template connection tracking entry to the packet that instructs the conntrack core not to initialize a new entry in the conntrack table. Note that this requires the use of a hook at - or below - a priority level of '''raw'''. Otherwise, '''notrack''' will not be dealt with prior to the consultation of the conntrack table.

The ruleset below demonstrates how to rewrite both the destination IP and port for each packet (also covering IPv6):

<source>
table inet raw {
chain prerouting {
type filter hook prerouting priority raw; policy accept;
ip protocol tcp ip daddr set 192.168.1.100 tcp dport set 10 notrack
ip6 nexthdr tcp ip6 daddr set fe00::1 tcp dport set 10 notrack
}
}
</source>

Be sure to check our documentation regarding [[Mangling_packet_headers|mangling packets]] and [[setting packet connection tracking metainformation]].

To use this feature you require nftables >=0.7 and linux kernel >= 4.9.

= See also =

* [[Multiple_NATs_using_nftables_maps | Example: multiple NATs using nftables maps]]

Performing Network Address Translation (NAT)

2024-02-07T20:32:57Z

Plushkava: Further clarify the use of stateless NAT

The ''nat'' chain type allows you to perform [https://en.wikipedia.org/wiki/Network_address_translation NAT]. This chain type comes with special semantics:

* The first packet of a flow is used to look up for a matching rule which sets up the NAT binding for this flow. This also manipulates this first packet accordingly.
* No rule lookup happens for follow up packets in the flow: the NAT engine uses the NAT binding information already set up by the first packet to perform the packet manipulation.

Adding a NAT rule to a filter type chain will result in an error.

= Stateful NAT =

The stateful NAT involves the nf_conntrack kernel engine to match/set packet stateful information and will engage according to the state of connections.
This is the most common way of performing NAT and the approach we recommend you to follow.

Be aware that '''with kernel versions before 4.18, you have to register the prerouting/postrouting chains even if you have no rules there''' since these chain will invoke the NAT engine for the packets coming in the reply direction. The remaining documentation in this article assumes a newer kernel which doesn't require this inconvenience anymore.

== Source NAT ==

If you want to source NAT the traffic that leaves from your local area network to the Internet, you can create a new table ''nat'' with the postrouting chain:

<source lang="bash">
% nft add table nat
% nft 'add chain nat postrouting { type nat hook postrouting priority 100 ; }'
</source>

Then, add the following rule:

<source lang="bash">
% nft add rule nat postrouting ip saddr 192.168.1.0/24 oif eth0 snat to 1.2.3.4
</source>

This matches for all traffic from the 192.168.1.0/24 network to the interface ''eth0''. The IPv4 address 1.2.3.4 is used as source for the packets that match this rule.

=== NAT pooling ===

It is possible to specify source NAT pooling:

<source lang="bash">
% nft add rule inet nat postrouting snat ip to 10.0.0.2/31
% nft add rule inet nat postrouting snat ip to 10.0.0.4-10.0.0.127
</source>

With transport protocol source port mapping:

<source lang="bash">
% nft add rule inet nat postrouting ip protocol tcp snat ip to 10.0.0.1-10.0.0.100:3000-4000
</source>

== Destination NAT ==

You need to add the following table and chain configuration:

<source lang="bash">
% nft add table nat
% nft 'add chain nat prerouting { type nat hook prerouting priority -100; }'
</source>

Then, you can add the following rule:

<source lang="bash">
% nft 'add rule nat prerouting iif eth0 tcp dport { 80, 443 } dnat to 192.168.1.120'
</source>

This redirects the incoming traffic for TCP ports 80 and 443 to 192.168.1.120.

== Masquerading ==

NOTE: ''masquerade'' is available starting with Linux Kernel 3.18.

Masquerade is a special case of SNAT, where the source address is automagically set to the address of the output interface. For example:

<source lang="bash">
% nft add rule nat postrouting masquerade
</source>

Note that ''masquerade'' only makes sense from postrouting chain of NAT type.

== Redirect ==

NOTE: ''redirect'' is available starting with Linux Kernel 3.19.

By using redirect, packets will be forwarded to local machine. Is a special case of DNAT where the destination is the current machine.

<source lang="bash">
% nft add rule nat prerouting redirect
</source>

This example redirects 22/tcp traffic to 2222/tcp:

<source lang="bash">
% nft add rule nat prerouting tcp dport 22 redirect to 2222
</source>

This example redirects outgoing 53/tcp traffic to a local proxy listening on port 10053/tcp:

<source lang="bash">
% nft add rule nat output tcp dport 853 redirect to 10053
</source>

Note that: ''redirect'' only makes sense in prerouting and output chains of NAT type.

== NAT flags ==

Since Linux kernel 3.18, you can combine the following flags with your NAT statements:

* random: randomize source port mapping.
* fully-random: full port randomization.
* persistent: gives a client the same source-/destination-address for each connection.

For example:

<source lang="bash">
% nft add rule nat postrouting masquerade random,persistent
% nft add rule nat postrouting ip saddr 192.168.1.0/24 oif eth0 snat to 1.2.3.4 fully-random
</source>

== Inet family NAT ==

Since Linux kernel 5.2, there is support for performing stateful NAT in ''inet'' family chains. Syntax and semantics are equivalent to ''ip''/''ip6'' families; the only exception being if IP addresses are specified, a prefix of either ''ip'' or ''ip6'' to clarify the address family is required:

<source lang="bash">
% nft add rule inet nat prerouting dnat ip to 10.0.0.2
% nft add rule inet nat prerouting dnat ip6 to feed::c0fe
</source>

== Incompatibilities ==

You cannot use iptables and nft to perform NAT at the same time before kernel 4.18. So make sure that the ''iptable_nat'' module is unloaded:

<source lang="bash">
% rmmod iptable_nat
</source>

With later kernels, it is possible to use iptables and nftables nat at the same time.
The nat chains are consulted according to their priorities, the first matching rule
that adds a nat mapping (dnat, snat, masquerade) is the one that will be used for the connection.

= Stateless NAT =

This type of NAT just modifies each packet according to your rules without any other state/connection tracking. This is valid for 1:1 mappings and is faster than stateful NAT. However, it's easy to shoot yourself in the foot. If your environment doesn't require this approach, better stick to stateful NAT.

You have to disable connection tracking for modified packets. This can be accomplished by incorporating the '''notrack''' keyword into the rule. Doing so attaches a template connection tracking entry to the packet that instructs the conntrack core not to initialize a new entry in the connection tracking table. Note that this requires the use of a hook at - or below - a priority level of '''raw'''. Otherwise, '''notrack''' will not be dealt with prior to the consultation of the conntrack table.

The ruleset below demonstrates how to rewrite both the destination IP and port for each packet (also covering IPv6):

<source>
table inet raw {
chain prerouting {
type filter hook prerouting priority raw; policy accept;
ip protocol tcp ip daddr set 192.168.1.100 tcp dport set 10 notrack
ip6 nexthdr tcp ip6 daddr set fe00::1 tcp dport set 10 notrack
}
}
</source>

Be sure to check our documentation regarding [[Mangling_packet_headers|mangling packets]] and [[setting packet connection tracking metainformation]].

To use this feature you require nftables >=0.7 and linux kernel >= 4.9.

= See also =

* [[Multiple_NATs_using_nftables_maps | Example: multiple NATs using nftables maps]]

Performing Network Address Translation (NAT)

2024-02-07T20:18:23Z

Plushkava: Clarify the use of notrack

The ''nat'' chain type allows you to perform [https://en.wikipedia.org/wiki/Network_address_translation NAT]. This chain type comes with special semantics:

* The first packet of a flow is used to look up for a matching rule which sets up the NAT binding for this flow. This also manipulates this first packet accordingly.
* No rule lookup happens for follow up packets in the flow: the NAT engine uses the NAT binding information already set up by the first packet to perform the packet manipulation.

Adding a NAT rule to a filter type chain will result in an error.

= Stateful NAT =

The stateful NAT involves the nf_conntrack kernel engine to match/set packet stateful information and will engage according to the state of connections.
This is the most common way of performing NAT and the approach we recommend you to follow.

Be aware that '''with kernel versions before 4.18, you have to register the prerouting/postrouting chains even if you have no rules there''' since these chain will invoke the NAT engine for the packets coming in the reply direction. The remaining documentation in this article assumes a newer kernel which doesn't require this inconvenience anymore.

== Source NAT ==

If you want to source NAT the traffic that leaves from your local area network to the Internet, you can create a new table ''nat'' with the postrouting chain:

<source lang="bash">
% nft add table nat
% nft 'add chain nat postrouting { type nat hook postrouting priority 100 ; }'
</source>

Then, add the following rule:

<source lang="bash">
% nft add rule nat postrouting ip saddr 192.168.1.0/24 oif eth0 snat to 1.2.3.4
</source>

This matches for all traffic from the 192.168.1.0/24 network to the interface ''eth0''. The IPv4 address 1.2.3.4 is used as source for the packets that match this rule.

=== NAT pooling ===

It is possible to specify source NAT pooling:

<source lang="bash">
% nft add rule inet nat postrouting snat ip to 10.0.0.2/31
% nft add rule inet nat postrouting snat ip to 10.0.0.4-10.0.0.127
</source>

With transport protocol source port mapping:

<source lang="bash">
% nft add rule inet nat postrouting ip protocol tcp snat ip to 10.0.0.1-10.0.0.100:3000-4000
</source>

== Destination NAT ==

You need to add the following table and chain configuration:

<source lang="bash">
% nft add table nat
% nft 'add chain nat prerouting { type nat hook prerouting priority -100; }'
</source>

Then, you can add the following rule:

<source lang="bash">
% nft 'add rule nat prerouting iif eth0 tcp dport { 80, 443 } dnat to 192.168.1.120'
</source>

This redirects the incoming traffic for TCP ports 80 and 443 to 192.168.1.120.

== Masquerading ==

NOTE: ''masquerade'' is available starting with Linux Kernel 3.18.

Masquerade is a special case of SNAT, where the source address is automagically set to the address of the output interface. For example:

<source lang="bash">
% nft add rule nat postrouting masquerade
</source>

Note that ''masquerade'' only makes sense from postrouting chain of NAT type.

== Redirect ==

NOTE: ''redirect'' is available starting with Linux Kernel 3.19.

By using redirect, packets will be forwarded to local machine. Is a special case of DNAT where the destination is the current machine.

<source lang="bash">
% nft add rule nat prerouting redirect
</source>

This example redirects 22/tcp traffic to 2222/tcp:

<source lang="bash">
% nft add rule nat prerouting tcp dport 22 redirect to 2222
</source>

This example redirects outgoing 53/tcp traffic to a local proxy listening on port 10053/tcp:

<source lang="bash">
% nft add rule nat output tcp dport 853 redirect to 10053
</source>

Note that: ''redirect'' only makes sense in prerouting and output chains of NAT type.

== NAT flags ==

Since Linux kernel 3.18, you can combine the following flags with your NAT statements:

* random: randomize source port mapping.
* fully-random: full port randomization.
* persistent: gives a client the same source-/destination-address for each connection.

For example:

<source lang="bash">
% nft add rule nat postrouting masquerade random,persistent
% nft add rule nat postrouting ip saddr 192.168.1.0/24 oif eth0 snat to 1.2.3.4 fully-random
</source>

== Inet family NAT ==

Since Linux kernel 5.2, there is support for performing stateful NAT in ''inet'' family chains. Syntax and semantics are equivalent to ''ip''/''ip6'' families; the only exception being if IP addresses are specified, a prefix of either ''ip'' or ''ip6'' to clarify the address family is required:

<source lang="bash">
% nft add rule inet nat prerouting dnat ip to 10.0.0.2
% nft add rule inet nat prerouting dnat ip6 to feed::c0fe
</source>

== Incompatibilities ==

You cannot use iptables and nft to perform NAT at the same time before kernel 4.18. So make sure that the ''iptable_nat'' module is unloaded:

<source lang="bash">
% rmmod iptable_nat
</source>

With later kernels, it is possible to use iptables and nftables nat at the same time.
The nat chains are consulted according to their priorities, the first matching rule
that adds a nat mapping (dnat, snat, masquerade) is the one that will be used for the connection.

= Stateless NAT =

This type of NAT just modifies each packet according to your rules without any other state/connection tracking.

This is valid for 1:1 mappings and is faster than stateful NAT. However, it's easy to shoot yourself in the foot.
If your environment doesn't require this approach, better stick to stateful NAT.

You have to disable connection tracking for modified packets. This can be accomplished by incorporating the "notrack" keyword into the rule. Doing so attaches a template connection tracking entry to the packet that instructs the conntrack core not to initialize a new entry in the connection tracking table.

The examples below set IP/port for each packet (also for IPv6):

<source>
% nft add rule ip raw prerouting ip protocol tcp ip daddr set 192.168.1.100 tcp dport set 10 notrack
% nft add rule ip6 raw prerouting ip6 nexthdr tcp ip6 daddr set fe00::1 tcp dport set 10 notrack
</source>

Be sure to check our documentation regarding [[Mangling_packet_headers|mangling packets]] and [[setting packet connection tracking metainformation]].

To use this feature you require nftables >=0.7 and linux kernel >= 4.9.

= See also =

* [[Multiple_NATs_using_nftables_maps | Example: multiple NATs using nftables maps]]

Logging traffic

2023-12-19T13:24:05Z

Plushkava: Employ the https:// scheme for the links

'''Note''': Full logging support is available starting Linux kernel 3.17. If you run an older kernel, you have to modprobe ipt_LOG to enable logging.

You can log packets using the ''log'' action. The most simple rule to log all incoming traffic is:

<source lang="bash">
% nft add rule filter input log
</source>

A typical rule match, log and accept incoming ''ssh'' traffic looks like:

<source lang="bash">
% nft add rule filter input tcp dport 22 ct state new log prefix \"New SSH connection: \" accept
</source>

The prefix indicates the initial string that is used as prefix for the log message.

Note that nftables allows to perform two actions in one single rule, contrary to ''iptables'' which required two rules for this.

Also note that the rule is evaluated from the left to the right. So the following rule:
<source lang="bash">
nft add rule filter input iif lo log tcp dport 22 accept
</source>
will log all packets coming on lo interface and not only the ones with destination port 22.

= Queueing logging to userspace =

As in iptables, you can use the existing ''nflog'' infrastructure to send log messages to [https://www.netfilter.org/projects/ulogd/ ulogd] or your custom userspace application based on [https://www.netfilter.org/projects/libnetfilter_log/ libnetfilter_log].

To do so, you only have to indicate the ''nflog'' group:

<source lang="bash">
% nft add rule filter input tcp dport 22 ct state new log prefix \"New SSH connection: \" group 0 accept
</source>

Then, run the example test application:

<source lang="bash">
libnetfilter_log/utils% ./nfulnl_test
</source>

And you'll start seeing log messages for each new ''ssh'' connection.

= Log flags =

Since nftables v0.7, log flags are supported.

Enable logging of TCP sequence and options:

<source>
% nft add rule x y log flags tcp sequence,options
</source>

Enable IP options:

<source>
% nft add rule x y log flags ip options
</source>

Enable socket UID:

<source>
% nft add rule x y log flags skuid
</source>

Enable ethernet link layer address:

<source>
% nft add rule x y log flags ether
</source>

Enable all flags:

<source>
% nft add rule x y log flags all
</source>

= Additional options =

Some additional options exist to fine-tune logging in different scenarios:

* '''level''': Syslog level of logging, a string of value: emerg, alert, crit, err, warn [default], notice, info, debug
* '''snaplen''': Length of packet payload to include in netlink message (unsigned integer, 32 bit)
* '''queue-threshold''': If queing logging to userspace, number of packets to queue inside the kernel before sending them to userspace (unsigned integer, 32 bit)

In the example below, a queue-threshold parameter is used to increment ulogd2 daemon performance in userspace:

<source>
% nft add rule filter forward ct state invalid log queue-threshold 20 prefix "ct_invalid" group 0 drop
</source>

Logging traffic

2023-12-19T13:21:53Z

Plushkava: Correct the link to the ulogd project

'''Note''': Full logging support is available starting Linux kernel 3.17. If you run an older kernel, you have to modprobe ipt_LOG to enable logging.

You can log packets using the ''log'' action. The most simple rule to log all incoming traffic is:

<source lang="bash">
% nft add rule filter input log
</source>

A typical rule match, log and accept incoming ''ssh'' traffic looks like:

<source lang="bash">
% nft add rule filter input tcp dport 22 ct state new log prefix \"New SSH connection: \" accept
</source>

The prefix indicates the initial string that is used as prefix for the log message.

Note that nftables allows to perform two actions in one single rule, contrary to ''iptables'' which required two rules for this.

Also note that the rule is evaluated from the left to the right. So the following rule:
<source lang="bash">
nft add rule filter input iif lo log tcp dport 22 accept
</source>
will log all packets coming on lo interface and not only the ones with destination port 22.

= Queueing logging to userspace =

As in iptables, you can use the existing ''nflog'' infrastructure to send log messages to [http://www.netfilter.org/projects/ulogd/ ulogd] or your custom userspace application based on [http://www.netfilter.org/projects/libnetfilter_log/ libnetfilter_log].

To do so, you only have to indicate the ''nflog'' group:

<source lang="bash">
% nft add rule filter input tcp dport 22 ct state new log prefix \"New SSH connection: \" group 0 accept
</source>

Then, run the example test application:

<source lang="bash">
libnetfilter_log/utils% ./nfulnl_test
</source>

And you'll start seeing log messages for each new ''ssh'' connection.

= Log flags =

Since nftables v0.7, log flags are supported.

Enable logging of TCP sequence and options:

<source>
% nft add rule x y log flags tcp sequence,options
</source>

Enable IP options:

<source>
% nft add rule x y log flags ip options
</source>

Enable socket UID:

<source>
% nft add rule x y log flags skuid
</source>

Enable ethernet link layer address:

<source>
% nft add rule x y log flags ether
</source>

Enable all flags:

<source>
% nft add rule x y log flags all
</source>

= Additional options =

Some additional options exist to fine-tune logging in different scenarios:

* '''level''': Syslog level of logging, a string of value: emerg, alert, crit, err, warn [default], notice, info, debug
* '''snaplen''': Length of packet payload to include in netlink message (unsigned integer, 32 bit)
* '''queue-threshold''': If queing logging to userspace, number of packets to queue inside the kernel before sending them to userspace (unsigned integer, 32 bit)

In the example below, a queue-threshold parameter is used to increment ulogd2 daemon performance in userspace:

<source>
% nft add rule filter forward ct state invalid log queue-threshold 20 prefix "ct_invalid" group 0 drop
</source>

Quick reference-nftables in 10 minutes

2023-08-29T13:20:41Z

Plushkava: Correct one of the udp sport examples

Find below some basic concepts to know before using nftables.

'''table''' refers to a container of [[Configuring chains|chains]] with no specific semantics.

'''chain''' within a [[Configuring tables|table]] refers to a container of [[Simple rule management|rules]].

'''rule''' refers to an action to be configured within a ''chain''.

= nft command line =

''nft'' is the command line tool in order to interact with nftables at userspace.

== Tables ==

'''family''' refers to a one of the following table types: ''ip'', ''arp'', ''ip6'', ''bridge'', ''inet'', ''netdev''.

<source lang="bash">
% nft list tables [<family>]
% nft list table [<family>] <name> [-n] [-a]
% nft (add | delete | flush) table [<family>] <name>
</source>

The argument ''-n'' shows the addresses and other information that uses names in numeric format. The ''-a'' argument is used to display the ''handle''.

== Chains ==

'''type''' refers to the kind of chain to be created. Possible types are:

* ''filter'': Supported by ''arp'', ''bridge'', ''ip'', ''ip6'' and ''inet'' table families.
* ''route'': Mark packets (like mangle for the ''output'' hook, for other hooks use the type ''filter'' instead), supported by ''ip'' and ''ip6''.
* ''nat'': In order to perform Network Address Translation, supported by ''ip'' and ''ip6''.

'''hook''' refers to an specific stage of the packet while it's being processed through the kernel. More info in [[Netfilter_hooks|Netfilter hooks]].

* The hooks for ''ip'', ''ip6'' and ''inet'' families are: ''prerouting'', ''input'', ''forward'', ''output'', ''postrouting''.
* The hooks for ''arp'' family are: '' input'', ''output''.
* The ''bridge'' family handles ethernet packets traversing bridge devices.
* The hook for ''netdev'' is: ''ingress''.

'''priority''' refers to a number used to order the chains or to set them between some Netfilter operations. Possible values are: ''NF_IP_PRI_CONNTRACK_DEFRAG (-400)'', ''NF_IP_PRI_RAW (-300)'', ''NF_IP_PRI_SELINUX_FIRST (-225)'', ''NF_IP_PRI_CONNTRACK (-200)'', ''NF_IP_PRI_MANGLE (-150)'', ''NF_IP_PRI_NAT_DST (-100)'', ''NF_IP_PRI_FILTER (0)'', ''NF_IP_PRI_SECURITY (50)'', ''NF_IP_PRI_NAT_SRC (100)'', ''NF_IP_PRI_SELINUX_LAST (225)'', ''NF_IP_PRI_CONNTRACK_HELPER (300)''.

'''policy''' is the default verdict statement to control the flow in the base chain. Possible values are: ''accept'' (default) and ''drop''. Warning: Setting the policy to ''drop'' discards all packets that
have not been accepted by the ruleset.

<source lang="bash">
% nft (add | create) chain [<family>] <table> <name> [ { type <type> hook <hook> [device <device>] priority <priority> \; [policy <policy> \;] } ]
% nft (delete | list | flush) chain [<family>] <table> <name>
% nft rename chain [<family>] <table> <name> <newname>
</source>

== Rules ==

'''handle''' is an internal number that identifies a certain ''rule''.

'''position''' is an internal number that is used to insert a ''rule'' before a certain ''handle''.

<source lang="bash">
% nft add rule [<family>] <table> <chain> <matches> <statements>
% nft insert rule [<family>] <table> <chain> [position <position>] <matches> <statements>
% nft replace rule [<family>] <table> <chain> [handle <handle>] <matches> <statements>
% nft delete rule [<family>] <table> <chain> [handle <handle>]
</source>

=== Matches ===

'''matches''' are clues used to access to certain packet information and create filters according to them.

==== Ip ====

{| class="wikitable"
!colspan="6"|ip match
|-
| | ''dscp <value>''
|
|<source lang="bash">
ip dscp cs1
ip dscp != cs1
ip dscp 0x38
ip dscp != 0x20
ip dscp {cs0, cs1, cs2, cs3, cs4, cs5, cs6, cs7, af11, af12, af13, af21,
af22, af23, af31, af32, af33, af41, af42, af43, ef}
</source>
|-
| ''length <length>''
| Total packet length
|<source lang="bash">
ip length 232
ip length != 233
ip length 333-435
ip length != 333-453
ip length { 333, 553, 673, 838}
</source>
|-
| ''id <id>''
| IP ID
|<source lang="bash">
ip id 22
ip id != 233
ip id 33-45
ip id != 33-45
ip id { 33, 55, 67, 88 }
</source>
|-
| ''frag-off <value>''
| Fragmentation offset
|<source lang="bash">
ip frag-off 222
ip frag-off != 233
ip frag-off 33-45
ip frag-off != 33-45
ip frag-off { 33, 55, 67, 88 }
</source>
|-
| ''ttl <ttl>''
| Time to live
|<source lang="bash">
ip ttl 0
ip ttl 233
ip ttl 33-55
ip ttl != 45-50
ip ttl { 43, 53, 45 }
ip ttl { 33-55 }
</source>
|-
| ''protocol <protocol>''
| Upper layer protocol
|<source lang="bash">
ip protocol tcp
ip protocol 6
ip protocol != tcp
ip protocol { icmp, esp, ah, comp, udp, udplite, tcp, dccp, sctp }
</source>
|-
| ''checksum <checksum>''
| IP header checksum
|<source lang="bash">
ip checksum 13172
ip checksum 22
ip checksum != 233
ip checksum 33-45
ip checksum != 33-45
ip checksum { 33, 55, 67, 88 }
ip checksum { 33-55 }
</source>
|-
| ''saddr <ip source address>''
| Source address
|<source lang="bash">
ip saddr 192.168.2.0/24
ip saddr != 192.168.2.0/24
ip saddr 192.168.3.1 ip daddr 192.168.3.100
ip saddr != 1.1.1.1
ip saddr 1.1.1.1
ip saddr & 0xff == 1
ip saddr & 0.0.0.255 < 0.0.0.127
</source>
|-
| ''daddr <ip destination address>''
| Destination address
|<source lang="bash">
ip daddr 192.168.0.1
ip daddr != 192.168.0.1
ip daddr 192.168.0.1-192.168.0.250
ip daddr 10.0.0.0-10.255.255.255
ip daddr 172.16.0.0-172.31.255.255
ip daddr 192.168.3.1-192.168.4.250
ip daddr != 192.168.0.1-192.168.0.250
ip daddr { 192.168.0.1-192.168.0.250 }
ip daddr { 192.168.5.1, 192.168.5.2, 192.168.5.3 }
</source>
|-
| ''version <version>''
| Ip Header version
|<source lang="bash">
ip version 4
</source>
|-
| ''hdrlength <header length>''
| IP header length
|<source lang="bash">
ip hdrlength 0
ip hdrlength 15
</source>
|}

==== Ip6 ====

{| class="wikitable"
!colspan="6"|ip6 match
|-
| ''dscp <value>''
|
|<source lang="bash">
ip6 dscp cs1
ip6 dscp != cs1
ip6 dscp 0x38
ip6 dscp != 0x20
ip6 dscp {cs0, cs1, cs2, cs3, cs4, cs5, cs6, cs7, af11, af12, af13, af21, af22, af23, af31, af32, af33, af41, af42, af43, ef}
</source>
|-
| ''flowlabel <label>''
| Flow label
|<source lang="bash">
ip6 flowlabel 22
ip6 flowlabel != 233
ip6 flowlabel { 33, 55, 67, 88 }
ip6 flowlabel { 33-55 }
</source>
|-
| ''length <length>''
| Payload length
|<source lang="bash">
ip6 length 232
ip6 length != 233
ip6 length 333-435
ip6 length != 333-453
ip6 length { 333, 553, 673, 838}
</source>
|-
| ''nexthdr <header>''
| Next header type (Upper layer protocol number)
|<source lang="bash">
ip6 nexthdr {esp, udp, ah, comp, udplite, tcp, dccp, sctp, icmpv6}
ip6 nexthdr esp
ip6 nexthdr != esp
ip6 nexthdr { 33-44 }
ip6 nexthdr 33-44
ip6 nexthdr != 33-44
</source>
|-
| ''hoplimit <hoplimit>''
| Hop limit
|<source lang="bash">
ip6 hoplimit 1
ip6 hoplimit != 233
ip6 hoplimit 33-45
ip6 hoplimit != 33-45
ip6 hoplimit {33, 55, 67, 88}
ip6 hoplimit {33-55}
</source>
|-
| ''saddr <ip source address>''
| Source Address
|<source lang="bash">
ip6 saddr 1234:1234:1234:1234:1234:1234:1234:1234
ip6 saddr ::1234:1234:1234:1234:1234:1234:1234
ip6 saddr ::/64
ip6 saddr ::1 ip6 daddr ::2
</source>
|-
| ''daddr <ip destination address>''
| Destination Address
|<source lang="bash">
ip6 daddr 1234:1234:1234:1234:1234:1234:1234:1234
ip6 daddr != ::1234:1234:1234:1234:1234:1234:1234-1234:1234::1234:1234:1234:1234:1234
</source>
|-
| ''version <version>''
| IP header version
|<source lang="bash">
ip6 version 6
</source>
|}

==== Tcp ====

{| class="wikitable"
!colspan="6"|tcp match
|-
| ''dport <destination port>''
| Destination port
|<source lang="bash">
tcp dport 22
tcp dport != 33-45
tcp dport { 33-55 }
tcp dport {telnet, http, https }
tcp dport vmap { 22 : accept, 23 : drop }
tcp dport vmap { 25:accept, 28:drop }
</source>
|-
| ''sport < source port>''
| Source port
|<source lang="bash">
tcp sport 22
tcp sport != 33-45
tcp sport { 33, 55, 67, 88}
tcp sport { 33-55}
tcp sport vmap { 25:accept, 28:drop }
tcp sport 1024 tcp dport 22
</source>
|-
| ''sequence <value>''
| Sequence number
|<source lang="bash">
tcp sequence 22
tcp sequence != 33-45
</source>
|-
| ''ackseq <value>''
| Acknowledgement number
|<source lang="bash">
tcp ackseq 22
tcp ackseq != 33-45
tcp ackseq { 33, 55, 67, 88 }
tcp ackseq { 33-55 }
</source>
|-
| ''flags <flags>''
| TCP flags
|<source lang="bash">
tcp flags { fin, syn, rst, psh, ack, urg, ecn, cwr}
tcp flags cwr
tcp flags != cwr
</source>
|-
| ''window <value>''
| Window
|<source lang="bash">
tcp window 22
tcp window != 33-45
tcp window { 33, 55, 67, 88 }
tcp window { 33-55 }
</source>
|-
| ''checksum <checksum>''
| IP header checksum
|<source lang="bash">
tcp checksum 22
tcp checksum != 33-45
tcp checksum { 33, 55, 67, 88 }
tcp checksum { 33-55 }
</source>
|-
| ''urgptr <pointer>''
| Urgent pointer
|<source lang="bash">
tcp urgptr 22
tcp urgptr != 33-45
tcp urgptr { 33, 55, 67, 88 }
</source>
|-
| ''doff <offset>''
| Data offset
|<source lang="bash">
tcp doff 8
</source>
|}

==== Udp ====

{| class="wikitable"
!colspan="6"|udp match
|-
| ''dport <destination port>''
| Destination port
|<source lang="bash">
udp dport 22
udp dport != 33-45
udp dport { 33-55 }
udp dport {telnet, http, https }
udp dport vmap { 22 : accept, 23 : drop }
udp dport vmap { 25:accept, 28:drop }
</source>
|-
| ''sport < source port>''
| Source port
|<source lang="bash">
udp sport 22
udp sport != 33-45
udp sport { 33, 55, 67, 88}
udp sport { 33-55}
udp sport vmap { 25:accept, 28:drop }
udp sport 1024 udp dport 22
</source>
|-
| ''length <length>''
| Total packet length
|<source lang="bash">
udp length 6666
udp length != 50-65
udp length { 50, 65 }
udp length { 35-50 }
</source>
|-
| ''checksum <checksum>''
| UDP checksum
|<source lang="bash">
udp checksum 22
udp checksum != 33-45
udp checksum { 33, 55, 67, 88 }
udp checksum { 33-55 }
</source>
|}

==== Udplite ====

{| class="wikitable"
!colspan="6"|udplite match
|-
| ''dport <destination port>''
| Destination port
|<source lang="bash">
udplite dport 22
udplite dport != 33-45
udplite dport { 33-55 }
udplite dport {telnet, http, https }
udplite dport vmap { 22 : accept, 23 : drop }
udplite dport vmap { 25:accept, 28:drop }
</source>
|-
| ''sport < source port>''
| Source port
|<source lang="bash">
udplite sport 22
udplite sport != 33-45
udplite sport { 33, 55, 67, 88}
udplite sport { 33-55}
udplite sport vmap { 25:accept, 28:drop }
udplite sport 1024 tcp dport 22
</source>
|-
| ''checksum <checksum>''
| Checksum
|<source lang="bash">
udplite checksum 22
udplite checksum != 33-45
udplite checksum { 33, 55, 67, 88 }
udplite checksum { 33-55 }
</source>
|}

==== Sctp ====

{| class="wikitable"
!colspan="6"|sctp match
|-
| ''dport <destination port>''
| Destination port
|<source lang="bash">
sctp dport 22
sctp dport != 33-45
sctp dport { 33-55 }
sctp dport {telnet, http, https }
sctp dport vmap { 22 : accept, 23 : drop }
sctp dport vmap { 25:accept, 28:drop }
</source>
|-
| ''sport < source port>''
| Source port
|<source lang="bash">
sctp sport 22
sctp sport != 33-45
sctp sport { 33, 55, 67, 88}
sctp sport { 33-55}
sctp sport vmap { 25:accept, 28:drop }
sctp sport 1024 tcp dport 22
</source>
|-
| ''checksum <checksum>''
| Checksum
|<source lang="bash">
sctp checksum 22
sctp checksum != 33-45
sctp checksum { 33, 55, 67, 88 }
sctp checksum { 33-55 }
</source>
|-
| ''vtag <tag>''
| Verification tag
|<source lang="bash">
sctp vtag 22
sctp vtag != 33-45
sctp vtag { 33, 55, 67, 88 }
sctp vtag { 33-55 }
</source>
|-
| ''chunk <type>''
| Existence of a chunk with given type in packet
|<source lang="bash">
sctp chunk init exists
sctp chunk error missing
</source>
|-
| ''chunk <type> <field>''
| A chunk's field value (implies chunk existence)
|<sourcex lang="bash">
sctp chunk init flags 0x1
sctp chunk data tsn 0x23
</source>
|}

==== Dccp ====

{| class="wikitable"
!colspan="6"|dccp match
|-
| ''dport <destination port>''
| Destination port
|<source lang="bash">
dccp dport 22
dccp dport != 33-45
dccp dport { 33-55 }
dccp dport {telnet, http, https }
dccp dport vmap { 22 : accept, 23 : drop }
dccp dport vmap { 25:accept, 28:drop }
</source>
|-
| ''sport < source port>''
| Source port
|<source lang="bash">
dccp sport 22
dccp sport != 33-45
dccp sport { 33, 55, 67, 88}
dccp sport { 33-55}
dccp sport vmap { 25:accept, 28:drop }
dccp sport 1024 tcp dport 22
</source>
|-
| ''type <type>''
| Type of packet
|<source lang="bash">
dccp type {request, response, data, ack, dataack, closereq, close, reset, sync, syncack}
dccp type request
dccp type != request
</source>
|}

==== Ah ====

{| class="wikitable"
!colspan="6"|ah match
|-
| ''hdrlength <length>''
| AH header length
|<source lang="bash">
ah hdrlength 11-23
ah hdrlength != 11-23
ah hdrlength {11, 23, 44 }
</source>
|-
| ''reserved <value>''
|
|<source lang="bash">
ah reserved 22
ah reserved != 33-45
ah reserved {23, 100 }
ah reserved { 33-55 }
</source>
|-
| ''spi <value>''
|
|<source lang="bash">
ah spi 111
ah spi != 111-222
ah spi {111, 122 }
</source>
|-
| ''sequence <sequence>''
| Sequence Number
|<source lang="bash">
ah sequence 123
ah sequence {23, 25, 33}
ah sequence != 23-33
</source>
|}

==== Esp ====

{| class="wikitable"
!colspan="6"|esp match
|-
| ''spi <value>''
|
|<source lang="bash">
esp spi 111
esp spi != 111-222
esp spi {111, 122 }
</source>
|-
| ''sequence <sequence>''
| Sequence Number
|<source lang="bash">
esp sequence 123
esp sequence {23, 25, 33}
esp sequence != 23-33
</source>
|}

==== Comp ====

{| class="wikitable"
!colspan="6"|comp match
|-
| ''nexthdr <protocol>''
| Next header protocol (Upper layer protocol)
|<source lang="bash">
comp nexthdr != esp
comp nexthdr {esp, ah, comp, udp, udplite, tcp, tcp, dccp, sctp}
</source>
|-
| ''flags <flags>''
| Flags
|<source lang="bash">
comp flags 0x0
comp flags != 0x33-0x45
comp flags {0x33, 0x55, 0x67, 0x88}
</source>
|-
| ''cpi <value>''
| Compression Parameter Index
|<source lang="bash">
comp cpi 22
comp cpi != 33-45
comp cpi {33, 55, 67, 88}
</source>
|}

==== Icmp ====

{| class="wikitable"
!colspan="6"|icmp match
|-
| ''type <type>''
| ICMP packet type
|<source lang="bash">
icmp type {echo-reply, destination-unreachable, source-quench, redirect, echo-request, time-exceeded, parameter-problem, timestamp-request, timestamp-reply, info-request, info-reply, address-mask-request, address-mask-reply, router-advertisement, router-solicitation}
</source>
|-
| ''code <code>''
| ICMP packet code
|<source lang="bash">
icmp code 111
icmp code != 33-55
icmp code { 2, 4, 54, 33, 56}
</source>
|-
| ''checksum <value>''
| ICMP packet checksum
|<source lang="bash">
icmp checksum 12343
icmp checksum != 11-343
icmp checksum { 1111, 222, 343 }
</source>
|-
| ''id <value>''
| ICMP packet id
|<source lang="bash">
icmp id 12343
icmp id != 11-343
icmp id { 1111, 222, 343 }
</source>
|-
| ''sequence <value>''
| ICMP packet sequence
|<source lang="bash">
icmp sequence 12343
icmp sequence != 11-343
icmp sequence { 1111, 222, 343 }
</source>
|-
| ''mtu <value>''
| ICMP packet mtu
|<source lang="bash">
icmp mtu 12343
icmp mtu != 11-343
icmp mtu { 1111, 222, 343 }
</source>
|-
| ''gateway <value>''
| ICMP packet gateway
|<source lang="bash">
icmp gateway 12343
icmp gateway != 11-343
icmp gateway { 1111, 222, 343 }
</source>
|}

==== Icmpv6 ====

{| class="wikitable"
!colspan="6"|icmpv6 match
|-
| ''type <type>''
| ICMPv6 packet type
|<source lang="bash">
icmpv6 type {destination-unreachable, packet-too-big, time-exceeded, echo-request, echo-reply, mld-listener-query, mld-listener-report, mld-listener-reduction, nd-router-solicit, nd-router-advert, nd-neighbor-solicit, nd-neighbor-advert, nd-redirect, parameter-problem, router-renumbering}
</source>
|-
| ''code <code>''
| ICMPv6 packet code
|<source lang="bash">
icmpv6 code 4
icmpv6 code 3-66
icmpv6 code {5, 6, 7}
</source>
|-
| ''checksum <value>''
| ICMPv6 packet checksum
|<source lang="bash">
icmpv6 checksum 12343
icmpv6 checksum != 11-343
icmpv6 checksum { 1111, 222, 343 }
</source>
|-
| ''id <value>''
| ICMPv6 packet id
|<source lang="bash">
icmpv6 id 12343
icmpv6 id != 11-343
icmpv6 id { 1111, 222, 343 }
</source>
|-
| ''sequence <value>''
| ICMPv6 packet sequence
|<source lang="bash">
icmpv6 sequence 12343
icmpv6 sequence != 11-343
icmpv6 sequence { 1111, 222, 343 }
</source>
|-
| ''mtu <value>''
| ICMPv6 packet mtu
|<source lang="bash">
icmpv6 mtu 12343
icmpv6 mtu != 11-343
icmpv6 mtu { 1111, 222, 343 }
</source>
|-
| ''max-delay <value>''
| ICMPv6 packet max delay
|<source lang="bash">
icmpv6 max-delay 33-45
icmpv6 max-delay != 33-45
icmpv6 max-delay {33, 55, 67, 88}
</source>
|}

==== Ether ====

{| class="wikitable"
!colspan="6"|ether match
|-
| ''saddr <mac address>''
| Source mac address
|<source lang="bash">
ether saddr 00:0f:54:0c:11:04
</source>
|-
| ''type <type>''
|
|<source lang="bash">
ether type vlan
</source>
|}

==== Dst ====

{| class="wikitable"
!colspan="6"|dst match
|-
| ''nexthdr <proto>''
| Next protocol header
|<source lang="bash">
dst nexthdr { udplite, ipcomp, udp, ah, sctp, esp, dccp, tcp, ipv6-icmp}
dst nexthdr 22
dst nexthdr != 33-45
</source>
|-
| ''hdrlength <length>''
| Header Length
|<source lang="bash">
dst hdrlength 22
dst hdrlength != 33-45
dst hdrlength { 33, 55, 67, 88 }
</source>
|}

==== Frag ====

{| class="wikitable"
!colspan="6"|frag match
|-
| ''nexthdr <proto>''
| Next protocol header
|<source lang="bash">
frag nexthdr { udplite, comp, udp, ah, sctp, esp, dccp, tcp, ipv6-icmp, icmp}
frag nexthdr 6
frag nexthdr != 50-51
</source>
|-
| ''reserved <value>''
|
|<source lang="bash">
frag reserved 22
frag reserved != 33-45
frag reserved { 33, 55, 67, 88}
</source>
|-
| ''frag-off <value>''
|
|<source lang="bash">
frag frag-off 22
frag frag-off != 33-45
frag frag-off { 33, 55, 67, 88}
</source>
|-
| ''more-fragments <value>''
|
|<source lang="bash">
frag more-fragments 0
frag more-fragments 0
</source>
|-
| ''id <value>''
|
|<source lang="bash">
frag id 1
frag id 33-45
</source>
|}

==== Hbh ====

{| class="wikitable"
!colspan="6"|hbh match
|-
| ''nexthdr <proto>''
| Next protocol header
|<source lang="bash">
hbh nexthdr { udplite, comp, udp, ah, sctp, esp, dccp, tcp, icmpv6}
hbh nexthdr 22
hbh nexthdr != 33-45
</source>
|-
| ''hdrlength <length>''
| Header Length
|<source lang="bash">
hbh hdrlength 22
hbh hdrlength != 33-45
hbh hdrlength { 33, 55, 67, 88 }
</source>
|}

==== Mh ====

{| class="wikitable"
!colspan="6"|mh match
|-
| ''nexthdr <proto>''
| Next protocol header
|<source lang="bash">
mh nexthdr { udplite, ipcomp, udp, ah, sctp, esp, dccp, tcp, ipv6-icmp }
mh nexthdr 22
mh nexthdr != 33-45
</source>
|-
| ''hdrlength <length>''
| Header Length
|<source lang="bash">
mh hdrlength 22
mh hdrlength != 33-45
mh hdrlength { 33, 55, 67, 88 }
</source>
|-
| ''type <type>''
|
|<source lang="bash">
mh type {binding-refresh-request, home-test-init, careof-test-init, home-test, careof-test, binding-update, binding-acknowledgement, binding-error, fast-binding-update, fast-binding-acknowledgement, fast-binding-advertisement, experimental-mobility-header, home-agent-switch-message}
mh type home-agent-switch-message
mh type != home-agent-switch-message
</source>
|-
| ''reserved <value>''
|
|<source lang="bash">
mh reserved 22
mh reserved != 33-45
mh reserved { 33, 55, 67, 88}
</source>
|-
| ''checksum <value>''
|
|<source lang="bash">
mh checksum 22
mh checksum != 33-45
mh checksum { 33, 55, 67, 88}
</source>
|}

==== Rt ====

{| class="wikitable"
!colspan="6"|rt match
|-
| ''nexthdr <proto>''
| Next protocol header
|<source lang="bash">
rt nexthdr { udplite, ipcomp, udp, ah, sctp, esp, dccp, tcp, ipv6-icmp }
rt nexthdr 22
rt nexthdr != 33-45
</source>
|-
| ''hdrlength <length>''
| Header Length
|<source lang="bash">
rt hdrlength 22
rt hdrlength != 33-45
rt hdrlength { 33, 55, 67, 88 }
</source>
|-
| ''type <type>''
|
|<source lang="bash">
rt type 22
rt type != 33-45
rt type { 33, 55, 67, 88 }
</source>
|-
| ''seg-left <value>''
|
|<source lang="bash">
rt seg-left 22
rt seg-left != 33-45
rt seg-left { 33, 55, 67, 88}
</source>
|}

==== Vlan ====

{| class="wikitable"
!colspan="6"|vlan match
|-
| ''id <value>''
| Vlan tag ID
|<source lang="bash">
vlan id 4094
vlan id 0
</source>
|-
| ''cfi <value>''
|
|<source lang="bash">
vlan cfi 0
vlan cfi 1
</source>
|-
| ''pcp <value>''
|
|<source lang="bash">
vlan pcp 7
vlan pcp 3
</source>
|}

==== Arp ====

{| class="wikitable"
!colspan="6"|arp match
|-
| ''ptype <value>''
| Payload type
|<source lang="bash">
arp ptype 0x0800
</source>
|-
| ''htype <value>''
| Header type
|<source lang="bash">
arp htype 1
arp htype != 33-45
arp htype { 33, 55, 67, 88}
</source>
|-
| ''hlen <length>''
| Header Length
|<source lang="bash">
arp hlen 1
arp hlen != 33-45
arp hlen { 33, 55, 67, 88}
</source>
|-
| ''plen <length>''
| Payload length
|<source lang="bash">
arp plen 1
arp plen != 33-45
arp plen { 33, 55, 67, 88}
</source>
|-
| ''operation <value>''
|
|<source lang="bash">
arp operation {nak, inreply, inrequest, rreply, rrequest, reply, request}
</source>
|}

==== Ct ====

{| class="wikitable"
!colspan="6"|ct match
|-
| ''state <state>''
| State of the connection
|<source lang="bash">
ct state { new, established, related, untracked }
ct state != related
ct state established
ct state 8
</source>
|-
| ''direction <value>''
| Direction of the packet relative to the connection
|<source lang="bash">
ct direction original
ct direction != original
ct direction {reply, original}
</source>
|-
| ''status <status>''
| Status of the connection
|<source lang="bash">
ct status expected
(ct status & expected) != expected
ct status {expected,seen-reply,assured,confirmed,snat,dnat,dying}
</source>
|-
| ''mark [set] <mark>''
| Mark of the connection
|<source lang="bash">
ct mark 0
ct mark or 0x23 == 0x11
ct mark or 0x3 != 0x1
ct mark and 0x23 == 0x11
ct mark and 0x3 != 0x1
ct mark xor 0x23 == 0x11
ct mark xor 0x3 != 0x1
ct mark 0x00000032
ct mark != 0x00000032
ct mark 0x00000032-0x00000045
ct mark != 0x00000032-0x00000045
ct mark {0x32, 0x2222, 0x42de3}
ct mark {0x32-0x2222, 0x4444-0x42de3}
ct mark set 0x11 xor 0x1331
ct mark set 0x11333 and 0x11
ct mark set 0x12 or 0x11
ct mark set 0x11
ct mark set mark
ct mark set mark map { 1 : 10, 2 : 20, 3 : 30 }
</source>
|-
| ''expiration <time>''
| Connection expiration time
|<source lang="bash">
ct expiration 30
ct expiration 30s
ct expiration != 233
ct expiration != 3m53s
ct expiration 33-45
ct expiration 33s-45s
ct expiration != 33-45
ct expiration != 33s-45s
ct expiration {33, 55, 67, 88}
ct expiration { 1m7s, 33s, 55s, 1m28s}
</source>
|-
| ''helper "<helper>"''
| Helper associated with the connection
|<source lang="bash">
ct helper "ftp"
</source>
|-
| | ''[original | reply] bytes <value>''
|
|<source lang="bash">
ct original bytes > 100000
ct bytes > 100000
</source>
|-
| | ''[original | reply] packets <value>''
|
|<source lang="bash">
ct reply packets < 100
</source>
|-
| | ''[original | reply] ip saddr <ip source address>''
|
|<source lang="bash">
ct original ip saddr 192.168.0.1
ct reply ip saddr 192.168.0.1
ct original ip saddr 192.168.1.0/24
ct reply ip saddr 192.168.1.0/24
</source>
|-
| | ''[original | reply] ip daddr <ip destination address>''
|
|<source lang="bash">
ct original ip daddr 192.168.0.1
ct reply ip daddr 192.168.0.1
ct original ip daddr 192.168.1.0/24
ct reply ip daddr 192.168.1.0/24
</source>
|-
| | ''[original | reply] l3proto <protocol>''
|
|<source lang="bash">
ct original l3proto ipv4
</source>
|-
| | ''[original | reply] protocol <protocol>''
|
|<source lang="bash">
ct original protocol 6
</source>
|-
| | ''[original | reply] proto-dst <port>''
|
|<source lang="bash">
ct original proto-dst 22
</source>
|-
| | ''[original | reply] proto-src <port>''
|
|<source lang="bash">
ct reply proto-src 53
</source>
|-
| | ''count [over] <number of connections>''
|
|<source lang="bash">
ct count over 2

tcp dport 22 add @ssh_flood { ip saddr ct count over 2 } reject
[ which requires an existing ssh_flood set, ie. add set filter ssh_flood { type ipv4_addr; flags dynamic; } ]
</source>
|}

==== Meta ====

[[Matching packet metainformation|''meta'']] matches packet by metainformation.

{| class="wikitable"
!colspan="6"|meta match
|-
| ''iifname <input interface name>''
| Input interface name
|<source lang="bash">
meta iifname "eth0"
meta iifname != "eth0"
meta iifname {"eth0", "lo"}
meta iifname "eth*"
</source>
|-
| ''oifname <output interface name>''
| Output interface name
|<source lang="bash">
meta oifname "eth0"
meta oifname != "eth0"
meta oifname {"eth0", "lo"}
meta oifname "eth*"
</source>
|-
| ''iif <input interface index>''
| Input interface index
|<source lang="bash">
meta iif eth0
meta iif != eth0
</source>
|-
| ''oif <output interface index>''
| Output interface index
|<source lang="bash">
meta oif lo
meta oif != lo
meta oif {eth0, lo}
</source>
|-
| ''iiftype <input interface type>''
| Input interface type
|<source lang="bash">
meta iiftype {ether, ppp, ipip, ipip6, loopback, sit, ipgre}
meta iiftype != ether
meta iiftype ether
</source>
|-
| ''oiftype <output interface type>''
| Output interface hardware type
|<source lang="bash">
meta oiftype {ether, ppp, ipip, ipip6, loopback, sit, ipgre}
meta oiftype != ether
meta oiftype ether
</source>
|-
| ''length <length>''
| Length of the packet in bytes
|<source lang="bash">
meta length 1000
meta length != 1000
meta length > 1000
meta length 33-45
meta length != 33-45
meta length { 33, 55, 67, 88 }
meta length { 33-55, 67-88 }
</source>
|-
| ''protocol <protocol>''
| ethertype protocol
|<source lang="bash">
meta protocol ip
meta protocol != ip
meta protocol { ip, arp, ip6, vlan }
</source>
|-
| ''nfproto <protocol>''
|
|<source lang="bash">
meta nfproto ipv4
meta nfproto != ipv6
meta nfproto { ipv4, ipv6 }
</source>
|-
| ''l4proto <protocol>''
|
|<source lang="bash">
meta l4proto 22
meta l4proto != 233
meta l4proto 33-45
meta l4proto { 33, 55, 67, 88 }
meta l4proto { 33-55 }
</source>
|-
| ''mark [set] <mark>''
| Packet mark
|<source lang="bash">
meta mark 0x4
meta mark 0x00000032
meta mark and 0x03 == 0x01
meta mark and 0x03 != 0x01
meta mark != 0x10
meta mark or 0x03 == 0x01
meta mark or 0x03 != 0x01
meta mark xor 0x03 == 0x01
meta mark xor 0x03 != 0x01
meta mark set 0xffffffc8 xor 0x16
meta mark set 0x16 and 0x16
meta mark set 0xffffffe9 or 0x16
meta mark set 0xffffffde and 0x16
meta mark set 0x32 or 0xfffff
meta mark set 0xfffe xor 0x16
</source>
|-
| ''priority [set] <priority>''
| tc class id
|<source lang="bash">
meta priority none
meta priority 0x1:0x1
meta priority 0x1:0xffff
meta priority 0xffff:0xffff
meta priority set 0x1:0x1
meta priority set 0x1:0xffff
meta priority set 0xffff:0xffff
</source>
|-
| ''skuid <user id>''
| UID associated with originating socket
|<source lang="bash">
meta skuid {bin, root, daemon}
meta skuid root
meta skuid != root
meta skuid lt 3000
meta skuid gt 3000
meta skuid eq 3000
meta skuid 3001-3005
meta skuid != 2001-2005
meta skuid { 2001-2005 }
</source>
|-
| ''skgid <group id>''
| GID associated with originating socket
|<source lang="bash">
meta skgid {bin, root, daemon}
meta skgid root
meta skgid != root
meta skgid lt 3000
meta skgid gt 3000
meta skgid eq 3000
meta skgid 3001-3005
meta skgid != 2001-2005
meta skgid { 2001-2005 }
</source>
|-
| ''rtclassid <class>''
| Routing realm
|<source lang="bash">
meta rtclassid cosmos
</source>
|-
| ''pkttype <type>''
| Packet type
|<source lang="bash">
meta pkttype broadcast
meta pkttype != broadcast
meta pkttype { broadcast, unicast, multicast}
</source>
|-
| ''cpu <cpu index>''
| CPU ID
|<source lang="bash">
meta cpu 1
meta cpu != 1
meta cpu 1-3
meta cpu != 1-2
meta cpu { 2,3 }
meta cpu { 2-3, 5-7 }
</source>
|-
| ''iifgroup <input group>''
| Input interface group
|<source lang="bash">
meta iifgroup 0
meta iifgroup != 0
meta iifgroup default
meta iifgroup != default
meta iifgroup {default}
meta iifgroup { 11,33 }
meta iifgroup {11-33}
</source>
|-
| ''oifgroup <group>''
| Output interface group
|<source lang="bash">
meta oifgroup 0
meta oifgroup != 0
meta oifgroup default
meta oifgroup != default
meta oifgroup {default}
meta oifgroup { 11,33 }
meta oifgroup {11-33}
</source>
|-
| ''cgroup <group>''
|
|<source lang="bash">
meta cgroup 1048577
meta cgroup != 1048577
meta cgroup { 1048577, 1048578 }
meta cgroup 1048577-1048578
meta cgroup != 1048577-1048578
meta cgroup {1048577-1048578}
</source>
|}

=== Statements ===

'''statement''' is the action performed when the packet match the rule. It could be ''terminal'' and ''non-terminal''. In a certain rule we can consider several non-terminal statements but only a single terminal statement.

==== Verdict statements ====

The '''verdict statement''' alters control flow in the ruleset and issues policy decisions for packets. The valid verdict statements are:

* ''accept'': Accept the packet and stop the remain rules evaluation.
* ''drop'': Drop the packet and stop the remain rules evaluation.
* ''queue'': Queue the packet to userspace and stop the remain rules evaluation.
* ''continue'': Continue the ruleset evaluation with the next rule.
* ''return'': Return from the current chain and continue at the next rule of the last chain. In a base chain it is equivalent to accept
* ''jump <chain>'': Continue at the first rule of <chain>. It will continue at the next rule after a return statement is issued
* ''goto <chain>'': Similar to jump, but after the new chain the evaluation will continue at the last chain instead of the one containing the goto statement

==== Log ====

{| class="wikitable"
!colspan="6"|log statement
|-
| ''level [over] <value> <unit> [burst <value> <unit>]''
| Log level
|<source lang="bash">
log
log level emerg
log level alert
log level crit
log level err
log level warn
log level notice
log level info
log level debug
</source>
|-
| ''group <value> [queue-threshold <value>] [snaplen <value>] [prefix "<prefix>"]''
|
|<source lang="bash">
log prefix aaaaa-aaaaaa group 2 snaplen 33
log group 2 queue-threshold 2
log group 2 snaplen 33
</source>
|}

==== Reject ====

The default '''reject''' will be the ICMP type '''port-unreachable'''. The '''icmpx''' is only used for inet family support.

More information on the [[Rejecting_traffic]] page.

{| class="wikitable"
!colspan="6"|reject statement
|-
| ''with <protocol> type <type>''
|
|<source lang="bash">
reject
reject with icmp type host-unreachable
reject with icmp type net-unreachable
reject with icmp type prot-unreachable
reject with icmp type port-unreachable
reject with icmp type net-prohibited
reject with icmp type host-prohibited
reject with icmp type admin-prohibited
reject with icmpv6 type no-route
reject with icmpv6 type admin-prohibited
reject with icmpv6 type addr-unreachable
reject with icmpv6 type port-unreachable
reject with icmpx type host-unreachable
reject with icmpx type no-route
reject with icmpx type admin-prohibited
reject with icmpx type port-unreachable
ip protocol tcp reject with tcp reset
</source>
|}

==== Counter ====

{| class="wikitable"
!colspan="6"|counter statement
|-
| ''packets <packets> bytes <bytes>''
|
|<source lang="bash">
counter
counter packets 0 bytes 0
</source>
|}

==== Limit ====

{| class="wikitable"
!colspan="6"|limit statement
|-
| ''rate [over] <value> <unit> [burst <value> <unit>]''
| Rate limit
|<source lang="bash">
limit rate 400/minute
limit rate 400/hour
limit rate over 40/day
limit rate over 400/week
limit rate over 1023/second burst 10 packets
limit rate 1025 kbytes/second
limit rate 1023000 mbytes/second
limit rate 1025 bytes/second burst 512 bytes
limit rate 1025 kbytes/second burst 1023 kbytes
limit rate 1025 mbytes/second burst 1025 kbytes
limit rate 1025000 mbytes/second burst 1023 mbytes
</source>
|}

==== Nat ====

{| class="wikitable"
!colspan="6"|nat statement
|-
| ''dnat to <destination address>''
| Destination address translation
|<source lang="bash">
dnat to 192.168.3.2
dnat to ct mark map { 0x00000014 : 1.2.3.4}
</source>
|-
| ''snat to <ip source address>''
| Source address translation
|<source lang="bash">
snat to 192.168.3.2
snat to 2001:838:35f:1::-2001:838:35f:2:::100
</source>
|-
| ''masquerade [<type>] [to :<port>]''
| Masquerade
|<source lang="bash">
masquerade
masquerade persistent,fully-random,random
masquerade to :1024
masquerade to :1024-2048
</source>
|}

==== Queue ====

{| class="wikitable"
!colspan="6"|queue statement
|-
| ''num <value> <scheduler>''
|
|<source lang="bash">
queue
queue num 2
queue num 2-3
queue num 4-5 fanout bypass
queue num 4-5 fanout
queue num 4-5 bypass
</source>
|}

== Extras ==

=== Export Configuration ===

<source lang="bash">
% nft export (xml | json)
</source>

=== Monitor Events ===

Monitor events from Netlink creating filters.

<source lang="bash">
% nft monitor [new | destroy] [tables | chains | sets | rules | elements] [xml | json]
</source>

= Nft scripting =

== List ruleset ==

<source lang="bash">
% nft list ruleset
</source>

== Flush ruleset ==

<source lang="bash">
% nft flush ruleset
</source>

== Load ruleset ==

Create a command batch file and load it with the nft interpreter,

<source lang="bash">
% echo "flush ruleset" > /etc/nftables.rules
% echo "add table filter" >> /etc/nftables.rules
% echo "add chain filter input" >> /etc/nftables.rules
% echo "add rule filter input meta iifname lo accept" >> /etc/nftables.rules
% nft -f /etc/nftables.rules
</source>

or create an executable nft script file,

<source lang="bash">
% cat << EOF > /etc/nftables.rules
> #!/usr/local/sbin/nft -f
> flush ruleset
> add table filter
> add chain filter input
> add rule filter input meta iifname lo accept
> EOF
% chmod u+x /etc/nftables.rules
% /etc/nftables.rules
</source>

or create an executable nft script file from an already created ruleset,

<source lang="bash">
% nft list ruleset > /etc/nftables.rules
% nft flush ruleset
% nft -f /etc/nftables.rules
</source>

= Examples =

== Simple IP/IPv6 Firewall ==

<source lang="bash">
flush ruleset

table firewall {
chain incoming {
type filter hook input priority 0; policy drop;

# established/related connections
ct state established,related accept

# loopback interface
iifname lo accept

# icmp
icmp type echo-request accept

# open tcp ports: sshd (22), httpd (80)
tcp dport {ssh, http} accept
}
}

table ip6 firewall {
chain incoming {
type filter hook input priority 0; policy drop;

# established/related connections
ct state established,related accept

# invalid connections
ct state invalid drop

# loopback interface
iifname lo accept

# icmp
# routers may also want: mld-listener-query, nd-router-solicit
icmpv6 type {echo-request,nd-neighbor-solicit} accept

# open tcp ports: sshd (22), httpd (80)
tcp dport {ssh, http} accept
}
}
</source>

Flowtables

2022-06-24T06:35:20Z

Plushkava: Add missing semi-colon in hook.

'''NOTE''': [[Meters]] were formerly known as flowtables before nftables 0.8.1 release. Now they are 2 separated, unrelated things.

Flowtables allow you to accelerate packet forwarding in software (and in hardware if your NIC supports it) by using a conntrack-based network stack bypass.

Entries are represented through a tuple that is composed of the input interface, source and destination address, source and destination port; and layer 3/4
protocols. Each entry also caches the destination interface and the gateway address (to update the destination link-layer address) to forward packets.

The TTL and hoplimit fields are also decremented. Hence, flowtables provides an alternative path that allow packets to bypass the classic forwarding path.

<pre>
userspace process
^ |
| |
_____|____ ____\/___
/ \ / \
| input | | output |
\__________/ \_________/
^ |
| |
_________ __________ --------- _____\/_____
/ \ / \ |Routing | / \
--> ingress ---> prerouting ---> |decision| | postrouting|--> neigh_xmit
\_________/ \__________/ ---------- \____________/ ^
| ^ | ^ |
flowtable | ____\/___ | |
| | / \ | |
__\/___ | | forward |------------ |
|-----| | \_________/ |
|-----| | 'flow offload' rule |
|-----| | adds entry to |
|_____| | flowtable |
| | |
/ \ | |
/hit\_no_| |
\ ? / |
\ / |
|__yes_________________fastpath bypass ____________________________|

Fig.1 Netfilter hooks and flowtable interactions
</pre>

Flowtables reside in the ingress hook that is located before the prerouting hook. You can select which flows you want to offload through the flow expression from the forward chain. Flowtables are identified by their address [[Nftables_families|family]] and their name. The address family must be one of ip, ip6, or inet. When no address family is specified, ip is used by default.

Flows are offloaded after the state is created. That means that usually the first reply packet will create the flowtable entry.
A firewall rule to accept the initial traffic is required.
The flow expression on the forward chain must match the return traffic of the initial connection.
Be aware that the return route is deducted from the packet, that creates the flowtable entry.
This also means if you are using special ip rules, you need to make sure that they match the reply packet traffic as well as the original traffic.

The *priority* can be a signed integer or *filter* which stands for 0. Addition and subtraction can be used to set relative priority, e.g. filter + 5 equals to 5.

The *devices* are specified as [[Data_types|iifname]](s) of the input interface(s) of the traffic that should be offloaded. Devices are required for both traffic directions.

Example:

<pre>
table inet x {

flowtable f {
hook ingress priority 0; devices = { eth0, eth1 };
}

chain forward {
type filter hook forward priority 0; policy drop;

# offload established connections
ip protocol { tcp, udp } flow offload @f
ip6 nexthdr { tcp, udp } flow offload @f
counter packets 0 bytes 0

# established/related connections
ct state established,related counter accept

# allow initial connection
ip protocol { tcp, udp } accept
ip6 nexthdr { tcp, udp } accept
}
}
</pre>

== See also ==

* [https://www.kernel.org/doc/html/latest/networking/nf_flowtable.html Linux kernel documentation on Netfilter flowtable]
* [https://netdevconf.info/0x13/session.html?workshop-netfilter-mini Netfilter Mini-Workshop, Netdev 0x13, 2019-03]
* [https://lwn.net/Articles/804384/ Mellanox flowtable hardware offload]
* [https://www.programmersought.com/article/11833283913/ Some Mellanox flowtable hardware offload performance measurements by Wen Xu of UCloud]
* [https://linuxplumbersconf.org/event/4/contributions/463/ Netfilter hardware offloads, Pablo Neira Ayuso, Linux Plumbers Conference, 2019-09]

Configuring chains

2020-12-30T22:45:04Z

Plushkava: Correct wording concerning the default chain policy

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.

= Adding base chains =

The syntax to add base chains is the following:

<source lang="bash">
% nft add chain [<family>] <table-name> <chain-name> { type <type> hook <hook> priority <value> \; [policy <policy>] }
</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 show how you can add new base chains to the ''foo'' table (that need to be created prior) through the following command:

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

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

<source lang="bash">
% nft -i
</source>

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. Its 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:

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

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'').

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

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

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:
<source lang="bash">
% nft 'add chain netdev foo dev0filter { type filter hook ingress device eth0 priority 0 ; }'
</source>

== Base chain types ==

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.
* '''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, ip6 and inet table families.

== Base chain hooks ==

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

* '''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.
* '''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''.

== Base chain priority ==

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.

'''NOTE''': starting with nftables 0.9.6 you may use keywords instead of numbers to configure the chain priority. Check the nft manpage for reference.

For reference, here's the list of different priority used in iptables:

* NF_IP_PRI_CONNTRACK_DEFRAG (-400): priority of defragmentation
* 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

'''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
}

# 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>

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.

== 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 non-base chains =

You can also create non-base chains as in ''iptables'' via:

<source lang="bash">
% nft add chain ip <table_name> <chain_name>
</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.

= Deleting chains =

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

<source lang="bash">
% nft delete chain ip foo input
</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.

<source lang="bash">
% nft delete chain ip foo input
<cmdline>:1:1-28: Error: Could not delete chain: Device or resource busy
delete chain ip foo input
^^^^^^^^^^^^^^^^^^^^^^^^^
</source>

You will have to [[Simple rule management|flush the ruleset]] in that chain before you can remove the chain.

= Flushing chain =

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:

<source lang="bash">
nft flush chain foo input
</source>

= 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:

<source lang="bash">
% 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 ; }'
</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.

Configuring chains

2020-12-30T22:28:53Z

Plushkava: Explain base chain traversal in the case of multiple equivalent hooks in slightly more detail

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.

= Adding base chains =

The syntax to add base chains is the following:

<source lang="bash">
% nft add chain [<family>] <table-name> <chain-name> { type <type> hook <hook> priority <value> \; [policy <policy>] }
</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 show how you can add new base chains to the ''foo'' table (that need to be created prior) through the following command:

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

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

<source lang="bash">
% nft -i
</source>

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. Its 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:

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

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'').

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

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

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:
<source lang="bash">
% nft 'add chain netdev foo dev0filter { type filter hook ingress device eth0 priority 0 ; }'
</source>

== Base chain types ==

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.
* '''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, ip6 and inet table families.

== Base chain hooks ==

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

* '''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.
* '''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''.

== Base chain priority ==

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.

'''NOTE''': starting with nftables 0.9.6 you may use keywords instead of numbers to configure the chain priority. Check the nft manpage for reference.

For reference, here's the list of different priority used in iptables:

* NF_IP_PRI_CONNTRACK_DEFRAG (-400): priority of defragmentation
* 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

'''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 hook 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
}

# 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>

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.

== 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 non-base chains =

You can also create non-base chains as in ''iptables'' via:

<source lang="bash">
% nft add chain ip <table_name> <chain_name>
</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.

= Deleting chains =

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

<source lang="bash">
% nft delete chain ip foo input
</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.

<source lang="bash">
% nft delete chain ip foo input
<cmdline>:1:1-28: Error: Could not delete chain: Device or resource busy
delete chain ip foo input
^^^^^^^^^^^^^^^^^^^^^^^^^
</source>

You will have to [[Simple rule management|flush the ruleset]] in that chain before you can remove the chain.

= Flushing chain =

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:

<source lang="bash">
nft flush chain foo input
</source>

= 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:

<source lang="bash">
% 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 ; }'
</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.

Adoption

2020-12-02T21:55:03Z

Plushkava: /* system / firewalling / management */ Mention projects with no plans to support nftables, at the suggestion of anarcat

This page offers some light and data about current '''nftables adoption''' in the wider community.
As you probably know, the focus of the Netfilter project and community is in replacing the iptables framework with nftables, adding brand new features and refreshing some workflows along the way.

Lots of upstream projects use iptables to handle NAT, filtering, mangling or other networking stuff.
Here, the info we know about them, their relationship with nftables and the possibilities for them to migrate to nftables.

= Cases =

Known cases and examples we could heard of. '''TODO: extend with more current data'''.

All major Linux distributions contains the nftables framework ready to use. Check [[Nftables from distributions]].

== system / firewalling / management ==

=== Supporting nftables ===

The following projects are known to either directly support nftables or have authors actively working on nftables integration.

* https://www.fail2ban.org/ -- the fail2ban tool already includes native support for nftables.
* https://firewalld.org/ -- firewalld by RedHat is currently developing a native integration with nftables.
* https://suricata-ids.org/ -- suricata can work natively with nftables ([https://home.regit.org/2014/02/suricata-and-nftables/ link])

=== Supporting iptables only ===

The following projects are known to only support iptables/iptables-nft, with no plans to support nftables in the future.

* http://ferm.foo-projects.org/ -- [https://github.com/MaxKellermann/ferm/issues/35#issuecomment-386091563 citation]
* https://shorewall.org/ -- [https://sourceforge.net/p/shorewall/mailman/message/35458915/ citation]

== virtualization / cloud / infrastructure ==

* https://github.com/zevenet/nftlb -- nftlb by Zevenet is a nftables-based loadbalancer which can outperform LVS by 10x
* https://www.docker.com/ -- Some discussion happened in the Docker community regarding a native integration with nftables, which could ease some of their use cases ([https://github.com/moby/moby/issues/26824 link]) ([https://github.com/robbertkl/docker-ipv6nat/issues/17 link]) ([https://stephank.nl/p/2017-06-05-ipv6-on-production-docker.html running docker with IPv6 using nftables])
* https://kubernetes.io/ -- Kubernetes does not support nftables yes, but some discussion happened already ([https://github.com/kubernetes/kubernetes/issues/45385 link]). Compat tools may be used to trick kubernetes into using nftables transparently.
* http://openstack.org/ -- Openstack does not support nftables yet. Compat tools may be used to trick neutron and other components into using nftables transparently.
* https://libvirt.org/ -- there are reports of people running libvirt with nftables for bridge filtering for virtual machines
* https://saltstack.com/ -- SaltStack includes native support for nftables ([https://docs.saltstack.com/en/latest/ref/states/all/salt.states.nftables.html link]).
* https://coreos.com/ -- the CoreOS ecosystem includes native support for nftables ([https://github.com/coreos/coreos-overlay/pull/2662 link])

== others ==

* https://openwrt.org/ -- there are reports of people running nftables rather than iptables in openwrt systems
* https://www.cica.es/ -- this regional [https://en.wikipedia.org/wiki/National_research_and_education_network NREN] uses nftables in the datacenter for their perimetral firewalls ([http://workshop.netfilter.org/2017/wiki/index.php/Developer_days.html#nftables_at_CICA.2C_our_experience slides])
* [[Nftables from distributions]] -- all major Linux distribution already include nftables ready to use
* https://www.nano-editor.org/ -- The nano editor includes syntax highlighting for nftables in files with .nft name extension or nft shebang
* https://github.com/nfnty/vim-nftables -- the VIM editor includes syntax highlighting for nftables
* [https://github.com/ipr-cnrs Institut de Physique de Rennes] -- this french research entity seems to be using nftables with ansible ([https://github.com/ipr-cnrs/nftables link])
* VPN -- nftables can be combined with other software packages like OpenVPN to build great VPN solutions ([http://ral-arturo.org/2017/04/07/openvpn-debian-stretch.html link])
* [https://github.com/mdlayher/netlink netlink golang package] -- the Golang Netlink package got batching support to be able to work with nftables ([https://github.com/mdlayher/netlink/issues/81 link])
* [https://github.com/google/nftables nftables golang library] -- This nftables golang integration library was made by Google

= See also =

* [[Moving from iptables to nftables]]
* [[Moving from ipset to nftables]]
* [[List of updates since Linux kernel 3.13]]
* [[Supported features compared to xtables]]
* [[List of available translations via iptables-translate tool]]