nftables wiki - User contributions [en]

Ruleset debug/tracing

2024-10-16T13:13:50Z

Arturo: add see also section with external links

Since nftables v0.6 and linux kernel 4.6, ruleset debug/tracing is supported.

This is an equivalent of the old iptables method -J TRACE, but with some great improvements.

The steps to enable debug/tracing is the following:
* give support in your ruleset for it (set nftrace in any of your rules)
* monitor the trace events from the nft tool

= Enabling nftrace =

To enable nftrace in a packet, use a rule with this statement:
<source lang="bash">
meta nftrace set 1
</source>

After all, nftrace is part of the [[Setting packet metainformation|metainformation]] of a packet.

Of course, you may only enable nftrace for a given matching packet.
In the example below, we only enable nftrace for tcp packets:

<source lang="bash">
ip protocol tcp meta nftrace set 1
</source>

Adjusting nftrace to only your subset of desired packets is key to properly debug the ruleset, otherwise you may get a lot of debug/tracing information which may be overwhelming.

= Use a chain to enable tracing =

The recommended way to enable tracing is to add a chain for this purpose.

Register a ''trace_chain'' to enable tracing. If you already have a prerouting chain, then make sure your ''trace_chain'' priority comes ''before'' your existing prerouting chain.

<source lang="bash">
% nft add chain filter trace_chain { type filter hook prerouting priority -301\; }
% nft add rule filter trace_chain meta nftrace set 1
</source>

This example assumes you have an existing raw prerouting chain (at priority -300), hence, this is registering a trace chain right before this chain (at priority -301).

Once you are done with rule tracing, you can just delete this chain to disable it:

<source lang="bash">
% nft delete chain filter trace_chain
</source>

= monitoring tracing events =

In nftables, getting the debug/tracing events is a bit different from the iptables world.
Now, we have an event-based monitor for the kernel to notify the nft tool.

The basic syntax is:

<source lang="bash">
% nft monitor trace
</source>

Each trace event is assigned an 'id' for you to easily follow different packets in the same trace session.

= Complete example =

Here is complete example of this debug/tracing mechanism in work.

Assuming you have this ruleset:

<source lang="bash">
table ip filter {
chain input {
type filter hook input priority filter; policy drop;
ct state established,related counter packets 2 bytes 292 accept
ct state new tcp dport 22 counter packets 0 bytes 0 accept
}
}
</source>

Load this ruleset:

<source lang="bash">
% nft -f ruleset.nft
</source>

Then, add a chain that enables tracing:

<source lang="bash">
% nft add chain ip filter trace_chain { type filter hook prerouting priority -1\; }
</source>

This registers the ''trace_chain'' before the existing ''input'' chain.

And the rule to enable the tracing:

<source lang="bash">
% nft add rule ip filter trace_chain meta nftrace set 1
</source>

Simple tracing test, by pinging one host:

<source lang="bash">
% ping -c 1 8.8.8.8
</source>

You run on a different terminal:

<source lang="bash">
% nft monitor trace
trace id a95ea7ef ip filter trace_chain packet: iif "enp0s25" ether saddr 00:0d:b9:4a:49:3d ether daddr 3c:97:0e:39:aa:20 ip saddr 8.8.8.8 ip daddr 192.168.2.118 ip dscp cs0 ip ecn not-ect ip ttl 115 ip id 0 ip length 84 icmp type echo-reply icmp code net-unreachable icmp id 9253 icmp sequence 1 @th,64,96 24106705117628271805883024640
trace id a95ea7ef ip filter trace_chain rule meta nftrace set 1 (verdict continue)
trace id a95ea7ef ip filter trace_chain verdict continue
trace id a95ea7ef ip filter trace_chain policy accept
trace id a95ea7ef ip filter input packet: iif "enp0s25" ether saddr 00:0d:b9:4a:49:3d ether daddr 3c:97:0e:39:aa:20 ip saddr 8.8.8.8 ip daddr 192.168.2.118 ip dscp cs0 ip ecn not-ect ip ttl 115 ip id 0 ip length 84 icmp type echo-reply icmp code net-unreachable icmp id 9253 icmp sequence 1 @th,64,96 24106705117628271805883024640
trace id a95ea7ef ip filter input rule ct state established,related counter packets 168 bytes 53513 accept (verdict accept)
</source>

The trace id uniquely identifies a packet. The trace describes the packet entering the chain initially.

<source lang="bash">
trace id a95ea7ef ip filter trace_chain packet: iif "enp0s25" ether saddr 00:0d:b9:4a:49:3d ether daddr 3c:97:0e:39:aa:20 ip saddr 8.8.8.8 ip daddr 192.168.2.118 ip dscp cs0 ip ecn not-ect ip ttl 115 ip id 0 ip length 84 icmp type echo-reply icmp code net-unreachable icmp id 9253 icmp sequence 1 @th,64,96 24106705117628271805883024640
</source>

Then, the packet travel through the ruleset.

= See also =

Some external tools can automate all the steps described here, see:
* https://github.com/aborrero/nftables-tracer (python based)
* https://github.com/aojea/nftrace (golang based)

Sets

2023-09-15T10:48:56Z

Arturo: /* Named sets specifications */ mention auto-merge

''nftables'' comes with a built-in generic set infrastructure that allows you to use '''any''' supported selector to build sets. This infrastructure makes possible the representation of [[maps]] and [[Verdict_Maps_(vmaps) | verdict maps]].

The set elements are internally represented using performance data structures such as hashtables and red-black trees.

= Anonymous sets =

Anonymous sets are those that are:

* Bound to a rule, if the rule is removed, that set is released too.
* They have no specific name, the kernel internally allocates an identifier.
* They cannot be updated. So you cannot add and delete elements from it once it is bound to a rule.

The following example shows how to create a simple set.

<source lang="bash">
% nft add rule ip filter output tcp dport { 22, 23 } counter
</source>

This rule above catches all traffic going to TCP ports 22 and 23, in case of matching the counters are updated.

Eric Leblond in his [https://home.regit.org/2014/01/why-you-will-love-nftables/ Why you will love nftables] article shows a very simple example to compare iptables with nftables:

<source lang="bash">
ip6tables -A INPUT -p tcp -m multiport --dports 23,80,443 -j ACCEPT
ip6tables -A INPUT -p icmpv6 --icmpv6-type neighbor-solicitation -j ACCEPT
ip6tables -A INPUT -p icmpv6 --icmpv6-type echo-request -j ACCEPT
ip6tables -A INPUT -p icmpv6 --icmpv6-type router-advertisement -j ACCEPT
ip6tables -A INPUT -p icmpv6 --icmpv6-type neighbor-advertisement -j ACCEPT
</source>

Which can be expressed in ''nftables'' with a couple of rules that provide a set:

<source lang="bash">
% nft add rule ip6 filter input tcp dport {telnet, http, https} accept
% nft add rule ip6 filter input icmpv6 type { nd-neighbor-solicit, echo-request, nd-router-advert, nd-neighbor-advert } accept
</source>

= Named sets =

You can use ''nft add set'' to create a named set. For example:

<source lang="bash">
% nft add set ip filter blackhole { type ipv4_addr\; comment \"drop all packets from these hosts\" \; }
</source>

creates a set named ''blackhole''. Set names must be 16 characters or less. The optional set ''comment'' attribute requires at least nftables 0.9.7 and kernel 5.10. The ''type'' keyword indicates the data type of elements to be stored in the set. In this case ''blackhole'' stores IPv4 addresses, which you can add using ''nft add element'':

<source lang="bash">
% nft add element ip filter blackhole { 192.168.3.4 }
% nft add element ip filter blackhole { 192.168.1.4, 192.168.1.5 }
</source>

You can use named sets from rules, as for example:

<source lang="bash">
% nft add rule ip filter input ip saddr @blackhole drop
% nft add rule ip filter output ip daddr != @blackhole accept
</source>

Named sets can be updated anytime.

== nftables.conf syntax ==

When working with nftables.conf, you can define sets in a number of ways. You can then reference those sets later on using <code>$VARIABLE_NAME</code> notation.

Here are some examples showing sets defined in one line, spanning multiple lines, and sets referencing other sets. The set is then used in a rule to allow incoming traffic from certain IP ranges.

<source lang="bash">
define SIMPLE_SET = { 192.168.1.1, 192.168.1.2 }

define CDN_EDGE = {
192.168.1.1,
192.168.1.2,
192.168.1.3,
10.0.0.0/8
}

define CDN_MONITORS = {
192.168.1.10,
192.168.1.20
}

define CDN = {
$CDN_EDGE,
$CDN_MONITORS
}

# Allow HTTP(S) from approved IP ranges only
tcp dport { http, https } ip saddr $CDN accept
udp dport { http, https } ip saddr $CDN accept
</source>

= Named sets specifications =

Sets specifications are:

* '''type''' or '''typeof''', is obligatory and determines the data type of the set elements.

Supported data types if using the '''type''' keyword are:
** ''ipv4_addr'': IPv4 address
** ''ipv6_addr'': IPv6 address.
** ''ether_addr'': Ethernet address.
** ''inet_proto'': Inet protocol type.
** ''inet_service'': Internet service (read tcp port for example)
** ''mark'': Mark type.
** ''ifname'': Network interface name (eth0, eth1..)

The '''typeof''' keyword is available since '''0.9.4''' and allows you to use a high level expression, then let nftables resolve the base type for you:
<source lang="bash">
table inet mytable {
set s1 {
typeof osf name
elements = { "Linux" }
}
set s2 {
typeof vlan id
elements = { 2, 3, 103 }
}
set s3 {
typeof ip daddr
elements = { 1.1.1.1 }
}
}
</source>

* '''timeout''', it determines how long an element stays in the set. The time string respects the format: ''"v1dv2hv3mv4s"'':

<source lang="bash">
% nft add table ip filter
% nft add set ip filter ports {type inet_service \; timeout 3h45s \;}
</source>

These commands create a table named ''filter'' and add a set named ''ports'' to it, where elements are deleted after 3 hours and 45 seconds of being added.

* '''flags''', the available flags are:
** ''constant'' - set content may not change while bound
** ''interval'' - set contains intervals
** ''timeout'' - elements can be added with a timeout

Multiple flags should be separated by comma:

<source lang="bash">
% nft add set ip filter flags_set {type ipv4_addr\; flags constant, interval\;}
</source>

* '''gc-interval''', stands for garbage collection interval, can only be used if ''timeout'' or ''flags timeout'' are active. The interval follows the same format of ''timeouts'' time string ''"v1dv2hv3mv4s"''.

* '''elements''', initialize the set with some elements in it:

<source lang="bash">
% nft add set ip filter daddrs {type ipv4_addr \; flags timeout \; elements={192.168.1.1 timeout 10s, 192.168.1.2 timeout 30s} \;}
</source>

This command creates a set name ''daddrs'' with elements ''192.168.1.1'', which stays in it for 10s, and ''192.168.1.2'', which stays for 30s.

* '''size''', limits the maximum number of elements of the set. To create a set with maximum 2 elements type:

<source lang="bash">
% nft add set ip filter saddrs {type ipv4_addr \; size 2 \;}
</source>

* '''policy''', determines set selection policy. Available values are:
** ''performance'' [default]
** ''memory''

* '''counter''', (available since version '''0.9.5''') which enables a counter per element:
<source lang="bash">
table inet mytable {
set s {
typeof ip saddr
counter
elements = { 1.1.1.1 counter packets 0 bytes 0, 1.1.1.2 counter packets 0 bytes 0,
1.1.1.3 counter packets 0 bytes 0, 1.1.1.4 counter packets 0 bytes 0 }
}
}
</source>

* '''auto-merge''', to automatic merge adjacent/overlapping set elements. This is only valid for interval sets.

For example, this origin set configuration will collapse the elements into the CIDR:
<source lang="bash">
table inet mytable {
set myset {
typeof ip saddr
flags interval
auto-merge
elements = { 10.0.0.1,
10.0.0.2,
10.0.0.3,
10.0.0.0/8,
}
}
}
</source>

Resulting in this when you list back the ruleset, because the CIDR already contains the individual elements:

<source lang="bash">
table inet mytable {
set myset {
typeof ip saddr
flags interval
auto-merge
elements = { 10.0.0.0/8,
}
}
}
</source>

Also, note that not using '''auto-merge''' will make such ruleset fail to load with something like:

<source>
/etc/nftables/ruleset.nft:38:21-29: Error: conflicting intervals specified
10.0.0.1 ,
~~~~~~~^^^^^^^^^
</source>

= Listing named sets =

You can list the content of a named set via:

<source lang="bash">
% nft list set ip filter myset
</source>

= Query for element membership in a set =

You can also check if an element exists in the set from its key:

<source lang="bash">
% nft get element ip filter myset { 1.1.1.1 }
</source>

The example above checks if the IPv4 address 1.1.1.1 exists in the ''myset'' set.

How to obtain help/support

2021-05-27T09:58:52Z

Arturo: /* Community */ libera.chat

There are several ways of getting '''help and support''' for Netfilter products.

= Community =

Netfilter is a FLOSS community. Among other things this means that community support
is offered in a ''best effort'' approach.

You may direct your help/support request to several support channels, which include:

* The users mailing list: [mailto:netfilter@vger.kernel.org netfilter@vger.kernel.org], [https://marc.info/?l=netfilter archive]
* Our documentation (i.e., this wiki, manpages, [[Further_documentation |further documentation]], and other resources)
* IRC: #netfilter in [https://libera.chat libera.chat]
* External support tools and forums like stackoverflow, distribution specific channels, and so on

Community support is usually not fully real-time, but the amount of knowledge that it contains is huge :-)

= Enterprise =

For some of our users it's important to have a professional paid support service associated with the software they are running.
There are '''a lot''' of enterprise businesses, vendors, and consulting firms who can provide support related to Netfilter software.

The list below is not exhaustive, and contains no specific meaning, order or association with the Netfilter project, but are well-known in the community.

'''TODO: create the list'''

We usually love companies who contribute back to the community :-)

Performing Network Address Translation (NAT)

2021-02-04T10:55:49Z

Arturo: /* NAT pooling */ typo

The ''nat'' chain type allows you to perform 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 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 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 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.

The example below sets IP/port for each packet (also valid in 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 [[Mangle packet header fields | 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)

2021-02-04T10:53:09Z

Arturo: /* Source NAT */ add example of SNAT pooling

The ''nat'' chain type allows you to perform 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 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 have 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 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 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.

The example below sets IP/port for each packet (also valid in 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 [[Mangle packet header fields | 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]]

Using configuration management systems

2020-12-16T10:30:51Z

Arturo: /* puppet */ add community module

This page shows a basic example on how to integrate nftables [[Scripting | scripting]] capabilities with configuration management systems (like puppet, ansible, chef, salt and others).

The basic approach is to have a central point where we deploy nftables, with a ruleset layout that allows other files to be deployed and loaded atomically by nftables.
Other components (modules, or profiles, or whatever) then deploy specific rules or other configuration as required.

= puppet =

For the sake of the example this page uses puppet as reference, but the same concepts and mechanism could be applied to others.

'''NOTE:''' if you copy-paste this example make sure you adapt it to your environment. This code below is an example and hasn't been tested at all.

== community module ==

The community already developed deep integration between puppet and nftables and other related firewalling mechanisms (like firewalld).

* https://forge.puppet.com/tags/nftables
* https://github.com/voxpupuli/puppet-nftables

== raw example ==

This a simplified raw example.

=== a base puppet module ===

A file like named this: '''modules/nftables/manifest/init.pp'''

<source lang="puppet">
class nftables(
) {
# install the package
package { 'nftables':
ensure => 'present',
}

# create a directory to hold the nftables config
file { '/etc/nftables/':
ensure => 'directory',
}

# deploy the basic configuration file, i.e, the basic nftables ruleset skeleton
file { '/etc/nftables/ruleset.nft':
ensure => 'present',
source => 'puppet:///modules/nftables/nftables.nft',
}

# ensure nftables systemd service is running (at boot time, etc)
service { 'nftables':
ensure => 'running',
}
}
</source>

We are installing this file (a file like: '''modules/nftables/files/nftables.nft''')

<source>
#!/usr/sbin/nft -f

flush ruleset

# create the basic ruleset skeleton
add table inet filter
add set inet filter allowed_ports { type inet_service ; }
add chain inet filter input { type filter hook input priority filter ; policy drop ; }
add rule inet filter input iif lo counter accept
add rule inet filter input ct state established,related counter accept
add rule inet filter input tcp dport @allowed_ports accept
add rule inet filter input counter

# include all the other files that may be deployed by puppet
include "/etc/nftables/*puppet.nft"
</source>

=== a module to introduce nftables config ===

This module is responsible for injecting into the system the new nftables config.
A file named like : '''modules/nftables/manifest/rule.pp'''

<source lang="puppet">
define nftables::rule(
String $rule,
) {
require ::nftables

file { "/etc/nftables/${name}_puppet.nft":
ensure => 'present',
content => $rule,
notify => Service['nftables'],
}
}
</source>

=== other modules adding nftables configuration ===

In this example, we have an apache module that creates some additional rules and configuration for nftables.

This is a file named like this: '''modules/apache/manifest/config.pp'''

<source lang="puppet">
class ::apache::config(
) {
package { 'apache':
ensure => 'present',
}

nftables::rule { 'apache_port_80':
rule => 'add element inet filter allowed_ports { 80 }',
}
}
</source>

= ansible =

Check some examples on how people are using nftables with ansible:

* https://github.com/ipr-cnrs/nftables
* https://github.com/Frzk/ansible-role-nftables

Main Page

2020-11-23T11:08:28Z

Arturo: /* External links */ add nftables & python external link

Welcome to the ''nftables'' HOWTO documentation page. Here you will find documentation on how to build, install, configure and use nftables.

If you have any suggestion to improve it, please send your comments to Netfilter users mailing list <netfilter@vger.kernel.org>.

= Introduction =

* [[What is nftables?]]
* [[Why nftables?]]
* [[Main differences with iptables]]
* [[Netfilter hooks]] and integration with existing Netfilter components.
* [[Adoption]]
* [[Legacy xtables tools]]
* [[How to obtain help/support]]

= Getting started =

* [[Building and installing nftables from sources]]
* Using [[nftables from distributions]]
* [[Troubleshooting|Troubleshooting and FAQ]]
* [[Quick reference-nftables in 10 minutes|Quick reference, nftables in 10 minutes]]
* [[nftables families|Understanding nftables families]]

= Basic operation =

* [[Configuring tables]]
* [[Configuring chains]]
* [[Simple rule management]]
* [[Atomic rule replacement]]
* [[Error reporting from the command line]]
* [[Building rules through expressions]]
* [[Operations at ruleset level]]
* [[Monitoring ruleset updates]]
* [[Scripting]]
* [[Ruleset debug/tracing]]
* [[Moving from iptables to nftables]]
* [[Moving from ipset to nftables]]
* [[Output text modifiers]]

= Supported selectors for packet matching =

* [[Matching packet header fields]]
* [[Matching packet metainformation]]
* [[Matching connection tracking stateful metainformation]]
* [[Rate limiting matchings]]
* [[Routing information]]

= Possible actions on packets =

* [[Accepting and dropping packets]]
* [[Jumping to chain]]
* [[Rejecting traffic]]
* [[Logging traffic]]
* [[Performing Network Address Translation (NAT)]]
* [[Setting packet metainformation]]
* [[Queueing to userspace]]
* [[Duplicating packets]]
* [[Mangle packet header fields]]
* [[Mangle TCP options]]
* [[Counters]]
* [[Load balancing]]
* [[Setting packet connection tracking metainformation]]

Note that, unlike ''iptables'', you can perform several actions in one single rule.

= Advanced data structures for performance packet classification =

You will have to redesign your rule-set to benefit from these new nice features:

* [[Sets]]
* [[Dictionaries]]
* [[Intervals]]
* [[Maps]]
* [[Concatenations]]
* [[Meters|Metering]] (formerly known as flow tables before nftables 0.8.1 release)
* [[Updating sets from the packet path]]
* [[Element timeouts]]
* [[Math operations]]
* [[Stateful objects]]
* [[Flowtable]] (the fastpath network stack bypass)

If you are already using [[ipset]] in your ''iptables'' rule-set, that transition may be a bit more simple to you.

= Examples =

* [[Simple ruleset for a workstation]]
* [[Simple ruleset for a server]]
* [[Bridge filtering]]
* [[Multiple NATs using nftables maps]]
* [[Classic perimetral firewall example]]
* [[Port knocking example]]
* [[Classification to tc structure example]]
* [[Using configuration management systems]] (like puppet, ansible, etc)
* [[GeoIP matching]]

= Development =

Check [[Portal:DeveloperDocs|Portal:DeveloperDocs - documentation for netfilter developers]].

Some hints on the general development progress:

* [[List of updates since Linux kernel 3.13]]
* [[List of updates in the nft command line tool]]
* [[Supported features compared to xtables|Supported features compared to {ip,ip6,eb,arp}tables]]
* [[List of available translations via iptables-translate tool]]

= External links =

Watch some videos:

* Watch [https://www.youtube.com/watch?v=FXTRRwXi3b4 Getting a grasp of nftables], thanks to [https://www.nluug.nl/index-en.html NLUUG association] for recording this.
* Watch [https://www.youtube.com/watch?v=CaYp0d2wiuU#t=1m47s The ultimate packet classifier for GNU/Linux], thanks to the FSFE for paying my trip to Barcelona and for recommending me as speaker to the KDE Spanish branch.
* [https://www.youtube.com/watch?v=Sy0JDX451ns Florian Westphal - Why nftables?]
* Watch [https://www.youtube.com/watch?v=0wQfSfDVN94 NLUUG - Goodbye iptables, Hello nftables]
* Watch [https://www.youtube.com/watch?v=Uf5ULkEWPL0 LCA2018 - nftables from a user perspective]

Watch videos to track updates:

* Watch [https://www.youtube.com/watch?v=qXVOA2MKA1s Netdev 2.1 - Netfilter mini-workshop (2017)]
* Watch [https://youtu.be/iCj10vEKPrw Netdev 2.2 - Netf‌ilter mini-workshop (2018)]
* Watch [https://youtu.be/0hqfzp6tpZo Netdev 0x12 - Netf‌ilter mini-workshop (2019)]
* Watch [https://www.youtube.com/watch?v=GqGGo4svj7s&feature=youtu.be Netdev 0x14 - Netfilter mini-Workshop (2020)]

Additional documentations and articles:

* Tutorial [https://zasdfgbnm.github.io/2017/09/07/Extending-nftables/ Extending nftables by Xiang Gao]
* Article [http://ral-arturo.org/2017/05/05/debian-stretch-stable-nftables.html New in Debian stable Stretch: nftables]
* Article [https://ral-arturo.org/2020/11/22/python-nftables-tutorial.html How to use nftables from python] and git repository [https://github.com/aborrero/python-nftables-tutorial python-nftables-tutorial.git]

= Thanks =

To the NLnet foundation for initial sponsorship of this HOWTO:

[https://nlnet.nl https://nlnet.nl/image/logo.gif]

To Eric Leblond, for boostrapping the [https://home.regit.org/netfilter-en/nftables-quick-howto/ Nftables quick howto] in 2013.

Concatenations

2020-09-07T11:08:33Z

Arturo: /* Dictionary declarations */ mention some set options

Since Linux kernel 4.1, nftables supports concatenations.

This new feature allows you to put two or more selectors together to perform very fast lookups by combining them with [[sets]], [[dictionaries]], [[maps]] and [[meters]].

= Literal sets =

<source lang="bash">
% nft add rule ip filter input ip saddr . ip daddr . ip protocol { 1.1.1.1 . 2.2.2.2 . tcp, 1.1.1.1 . 3.3.3.3 . udp} counter accept
</source>

So if the packet's source IP address AND destination IP address AND level 4 protocol match:

* 1.1.1.1 and 2.2.2.2 and TCP.

or

* 1.1.1.1 and 3.3.3.3 and UDP.

nftables updates the counter for this rule and then accepts the packet.

= Dictionary declarations =

The following example creates the ''whitelist'' dictionary using a concatenation of two selectors:

<source lang="bash">
% nft add map filter whitelist { type ipv4_addr . inet_service : verdict \; }
</source>

Once you create the dictionary, you can use it from a rule that creates the following concatenation:

<source lang="bash">
% nft add rule filter input ip saddr . tcp dport vmap @whitelist
</source>

Thus, the rule above looks up for a verdict based on the source IP address AND the TCP destination port.

Since the dictionary is initially empty, you can dynamically populate this dictionary with elements through:

<source lang="bash">
% nft add element filter whitelist { 1.2.3.4 . 22 : accept}
</source>

When declaring concatenations, you can use [[Sets | generic sets options]], such as the '''typeof''' keyword and the '''counter''' feature:

<source lang="bash">
table inet fmytable {
set myset {
typeof ip daddr . tcp dport
counter
elements = { 1.1.1.4 . 22 counter packets 0 bytes 0,
1.1.1.5 . 23 counter packets 0 bytes 0,
1.1.1.6 . 24 counter packets 0 bytes 0 }
}
}
</source>

= Literal maps =

The rule below determines the destination IP address that is used to perform DNAT to the packet based on:

* the source IP address

AND

* the destination TCP port

<source lang="bash">
% nft add rule ip nat prerouting dnat ip saddr . tcp dport map { 1.1.1.1 . 80 : 192.168.1.100, 2.2.2.2 . 8888 : 192.168.1.101 }
</source>

= Examples =

Some concrete example concatenations so you get an idea on how powerful this new feature is.

== Network addresses ==

The example below implements a dictionary using network masks in each element:

<source lang="bash">
table inet mytable {
set myset {
type ipv4_addr . ipv4_addr
flags interval
elements = { 192.168.0.0/16 . 172.16.0.0/25,
10.0.0.0/30 . 192.168.1.0/24,
}
}

chain mychain {
ip saddr . ip daddr @myset counter accept
}
}
</source>

'''NOTE''': before kinux kernel 5.6 and nftables 0.9.4 the CIDR notation wasn't available, you would need to use a workaround:

<source lang="bash">
% nft add rule tablename chainname ip saddr and 255.255.255.0 . ip daddr and 255.255.255.0 vmap { 10.10.10.0 . 10.10.20.0 : accept }
</source>

Note that this is not an interval, this is masking the ip saddr and ip daddr, then concate both results. This concatenation is used to lookup for a matching of this the result in the map. This syntax may be compacted in future releases to support CIDR notation.

This could be easily implemented using a named map as well:

<source lang="bash">
% nft add map tablename myMap { type ipv4_addr . ipv4_addr : verdict \; }
% nft add rule tablename chainname ip saddr and 255.255.255.0 . ip saddr and 255.255.255.0 vmap @myMap
% nft add element tablename myMap { 10.10.10.0 . 10.10.20.0 : accept }
</source>

== Interfaces ==

The example below checks both input and output interfaces of a forwarded packet.

<source lang="bash">
% nft add rule tablename chainname iif . oif vmap { eth0 . eth1 : accept }
</source>

Please note that using strings (for example iifname and oifname) and other variable sized data types is not supported yet.

== Some ipset types ==

These ipset types can be implemented in nftables using concatenations. Probably more equivalences exists, it just a matter of combining data types.
Of course, you could implement these as named maps/sets as well.

See examples in the [[Moving_from_ipset_to_nftables | moving from ipset to nftables]] page.

Maps

2020-09-07T11:02:20Z

Arturo: add link to sets

Maps are yet another interesting feature that has been in ''nftables'' since the very beginning. You can use a map to look up for data based on some specific key that is used as input. Maps internally use the [[Sets | generic set infrastructure]] and therefore share some of their options and semantics.

= Literal maps =

The following example shows how the destination TCP port selects the destination IP address to DNAT the packet:

<source lang="bash">
% nft add rule ip nat prerouting dnat tcp dport map { 80 : 192.168.1.100, 8888 : 192.168.1.101 }
</source>

This is how you can express a classical port redirection when the real server are actually located behind the firewall. This can be read as it follows:

* If the TCP destination port is 80, then the packet is DNAT'ed to 192.168.1.100.
* If the TCP destination port is 8888, then the packet is DNAT'ed to 192.168.1.101.

= Map declarations =

You can also declare maps that you can populate in a dynamic fashion, eg.

<source lang="bash">
% nft add map nat porttoip { type inet_service: ipv4_addr\; }
% nft add element nat porttoip { 80 : 192.168.1.100, 8888 : 192.168.1.101 }
</source>

The example above shows that the ''porttoip'' map maintains the corresponde between Internet services (which is the datatype of a TCP destination port) and IP addresses.

Then, you can use it from a rule like:

<source lang="bash">
% nft add rule ip nat postrouting snat tcp dport map @porttoip
</source>

This rules tells that the source IP address that is used for SNAT depends on TCP destination port. The content of the map can be dynamically updated by adding new elements.

Verdict Maps (vmaps)

2020-09-07T11:01:37Z

Arturo: link to sets

The ''dictionaries'', also known as ''verdict maps'', are one of the most interesting features available in ''nftables''. Basically, they allow you to attach an action to an element. Dictionaries internally use the [[Sets | generic set infrastructure]] and therefore share some semantics and options.

= Literal dictionaries =

The following example shows how to create a tree of chains that whose traversal depends on the layer 4 protocol type:

<source lang="bash">
% nft add rule ip filter input ip protocol vmap { tcp : jump tcp-chain, udp : jump udp-chain , icmp : jump icmp-chain }
</source>

This example above assumes that you've already created the ''tcp-chain'', ''udp-chain'' and ''icmp-chain'' [[Configuring chains|custom chains]]. Then, by attaching simple rules to account the traffic, ie.

<source lang="bash">
% nft add rule filter icmp-chain counter
% nft add rule filter tcp-chain counter
% nft add rule filter udp-chain counter
</source>

You can check that the classification is already happening:

<source lang="bash">
% nft list table filter
table ip filter {
chain input {
type filter hook input priority 0;
ip protocol vmap { udp : jump udp-chain, tcp : jump tcp-chain, icmp : jump icmp-chain}
}

chain tcp-chain {
counter packets 4 bytes 520
}

chain udp-chain {
counter packets 4 bytes 678
}

chain icmp-chain {
counter packets 4 bytes 336
}
}
</source>

As you probably already noticed, one of the the good things of nftables is that you can use ''dictionaries'' to construct performance rule-sets. This rule-set arrangement allows you to reduce the amount of linear list inspections to classify your packets.

= Dictionary declarations =

You can also declarate dictionaries and populate its content dynamically, for example:

<source lang="bash">
% nft add map filter mydict { type ipv4_addr : verdict\; }
</source>

Then, you can add elements:

<source lang="bash">
% nft add element filter mydict { 192.168.0.10 : drop, 192.168.0.11 : accept }
</source>

You can bind this set to a rule using the following command:

<source lang="bash">
% nft add rule filter input ip saddr vmap @mydict
</source>

In case you want to build your own dictionary, but you don't know what is the datatype name. Remember that you can inquire ''nft'' to know the datatype name:

<source lang="bash">
% nft describe tcp dport
payload expression, datatype inet_service (internet network service) (basetype integer), 16 bits
</source>

See the ''inet_service'' string after datatype.

Sets

2020-09-07T11:00:19Z

Arturo: /* Named sets specifications */ add info on counters

''nftables'' comes with a built-in generic set infrastructure that allows you to use '''any''' supported selector to build sets. This infrastructure makes possible the representation of [[dictionaries]] and [[maps]].

The set elements are internally represented using performance data structures such as hashtables and red-black trees.

= Anonymous sets =

Anonymous sets are those that are:

* Bound to a rule, if the rule is removed, that set is released too.
* They have no specific name, the kernel internally allocates an identifier.
* They cannot be updated. So you cannot add and delete elements from it once it is bound to a rule.

The following example shows how to create a simple set.

<source lang="bash">
% nft add rule ip filter output tcp dport { 22, 23 } counter
</source>

This rule above catches all traffic going to TCP ports 22 and 23, in case of matching the counters are updated.

Eric Leblond in his [https://home.regit.org/2014/01/why-you-will-love-nftables/ Why you will love nftables] article shows a very simple example to compare iptables with nftables:

<source lang="bash">
ip6tables -A INPUT -p tcp -m multiport --dports 23,80,443 -j ACCEPT
ip6tables -A INPUT -p icmpv6 --icmpv6-type neighbor-solicitation -j ACCEPT
ip6tables -A INPUT -p icmpv6 --icmpv6-type echo-request -j ACCEPT
ip6tables -A INPUT -p icmpv6 --icmpv6-type router-advertisement -j ACCEPT
ip6tables -A INPUT -p icmpv6 --icmpv6-type neighbor-advertisement -j ACCEPT
</source>

Which can be expressed in ''nftables'' with a couple of rules that provide a set:

<source lang="bash">
% nft add rule ip6 filter input tcp dport {telnet, http, https} accept
% nft add rule ip6 filter input icmpv6 type { nd-neighbor-solicit, echo-request, nd-router-advert, nd-neighbor-advert } accept
</source>

= Named sets =

You can create the named sets with the following command:

<source lang="bash">
% nft add set ip filter blackhole { type ipv4_addr\;}
</source>

Note that ''blackhole'' is the name of the set in this case. The ''type'' option indicates the data type that this set stores, which is an IPv4 address in this case. Current maximum name length is 16 characters.

<source lang="bash">
% nft add element ip filter blackhole { 192.168.3.4 }
% nft add element ip filter blackhole { 192.168.1.4, 192.168.1.5 }
</source>

Then, you can use it from the rule:

<source lang="bash">
% nft add rule ip filter input ip saddr @blackhole drop
</source>

Named sets can be updated anytime, so you can add and delete element from them.

== nftables.conf syntax ==

When working with nftables.conf, you can define sets in a number of ways. You can then reference those sets later on using <code>$VARIABLE_NAME</code> notation.

Here are some examples showing sets defined in one line, spanning multiple lines, and sets referencing other sets. The set is then used in a rule to allow incoming traffic from certain IP ranges.

<source lang="bash">
define SIMPLE_SET = { 192.168.1.1, 192.168.1.2 }

define CDN_EDGE = {
192.168.1.1,
192.168.1.2,
192.168.1.3,
10.0.0.0/8
}

define CDN_MONITORS = {
192.168.1.10,
192.168.1.20
}

define CDN = {
$CDN_EDGE,
$CDN_MONITORS
}

# Allow HTTP(S) from approved IP ranges only
tcp dport { http, https } ip saddr $CDN accept
udp dport { http, https } ip saddr $CDN accept
</source>

= Named sets specifications =

Sets specifications are:

* '''type''' or '''typeof''', is obligatory and determines the data type of the set elements.

Supported data types if using the '''type''' keyword are:
** ''ipv4_addr'': IPv4 address
** ''ipv6_addr'': IPv6 address.
** ''ether_addr'': Ethernet address.
** ''inet_proto'': Inet protocol type.
** ''inet_service'': Internet service (read tcp port for example)
** ''mark'': Mark type.
** ''ifname'': Network interface name (eth0, eth1..)

The '''typeof''' keyword is available since '''0.9.4''' and allows you to use a high level expression, then let nftables resolve the base type for you:
<source lang="bash">
table inet mytable {
set s1 {
typeof osf name
elements = { "Linux" }
}
set s2 {
typeof vlan id
elements = { 2, 3, 103 }
}
set s3 {
typeof ip daddr
elements = { 1.1.1.1 }
}
}
</source>

* '''timeout''', it determines how long an element stays in the set. The time string respects the format: ''"v1dv2hv3mv4s"'':

<source lang="bash">
% nft add table ip filter
% nft add set ip filter ports {type inet_service \; timeout 3h45s \;}
</source>

These commands create a table named ''filter'' and add a set named ''ports'' to it, where elements are deleted after 3 hours and 45 seconds of being added.

* '''flags''', the available flags are:
** ''constant'' - set content may not change while bound
** ''interval'' - set contains intervals
** ''timeout'' - elements can be added with a timeout

Multiple flags should be separated by comma:

<source lang="bash">
% nft add set ip filter flags_set {type ipv4_addr\; flags constant, interval\;}
</source>

* '''gc-interval''', stands for garbage collection interval, can only be used if ''timeout'' or ''flags timeout'' are active. The interval follows the same format of ''timeouts'' time string ''"v1dv2hv3mv4s"''.

* '''elements''', initialize the set with some elements in it:

<source lang="bash">
% nft add set ip filter daddrs {type ipv4_addr \; flags timeout \; elements={192.168.1.1 timeout 10s, 192.168.1.2 timeout 30s} \;}
</source>

This command creates a set name ''daddrs'' with elements ''192.168.1.1'', which stays in it for 10s, and ''192.168.1.2'', which stays for 30s.

* '''size''', limits the maximum number of elements of the set. To create a set with maximum 2 elements type:

<source lang="bash">
% nft add set ip filter saddrs {type ipv4_addr \; size 2 \;}
</source>

* '''policy''', determines set selection policy. Available values are:
** ''performance'' [default]
** ''memory''

* '''counter''', (available since version '''0.9.5''') which enables a counter per element:
<source lang="bash">
table inet mytable {
set s {
typeof ip saddr
counter
elements = { 1.1.1.1 counter packets 0 bytes 0, 1.1.1.2 counter packets 0 bytes 0,
1.1.1.3 counter packets 0 bytes 0, 1.1.1.4 counter packets 0 bytes 0 }
}
}
</source>

= Listing named sets =

You can list the content of a named set via:

<source lang="bash">
% nft list set ip filter myset
</source>

Sets

2020-09-07T10:56:33Z

Arturo: /* Named sets specifications */ mention typeof

''nftables'' comes with a built-in generic set infrastructure that allows you to use '''any''' supported selector to build sets. This infrastructure makes possible the representation of [[dictionaries]] and [[maps]].

The set elements are internally represented using performance data structures such as hashtables and red-black trees.

= Anonymous sets =

Anonymous sets are those that are:

* Bound to a rule, if the rule is removed, that set is released too.
* They have no specific name, the kernel internally allocates an identifier.
* They cannot be updated. So you cannot add and delete elements from it once it is bound to a rule.

The following example shows how to create a simple set.

<source lang="bash">
% nft add rule ip filter output tcp dport { 22, 23 } counter
</source>

This rule above catches all traffic going to TCP ports 22 and 23, in case of matching the counters are updated.

Eric Leblond in his [https://home.regit.org/2014/01/why-you-will-love-nftables/ Why you will love nftables] article shows a very simple example to compare iptables with nftables:

<source lang="bash">
ip6tables -A INPUT -p tcp -m multiport --dports 23,80,443 -j ACCEPT
ip6tables -A INPUT -p icmpv6 --icmpv6-type neighbor-solicitation -j ACCEPT
ip6tables -A INPUT -p icmpv6 --icmpv6-type echo-request -j ACCEPT
ip6tables -A INPUT -p icmpv6 --icmpv6-type router-advertisement -j ACCEPT
ip6tables -A INPUT -p icmpv6 --icmpv6-type neighbor-advertisement -j ACCEPT
</source>

Which can be expressed in ''nftables'' with a couple of rules that provide a set:

<source lang="bash">
% nft add rule ip6 filter input tcp dport {telnet, http, https} accept
% nft add rule ip6 filter input icmpv6 type { nd-neighbor-solicit, echo-request, nd-router-advert, nd-neighbor-advert } accept
</source>

= Named sets =

You can create the named sets with the following command:

<source lang="bash">
% nft add set ip filter blackhole { type ipv4_addr\;}
</source>

Note that ''blackhole'' is the name of the set in this case. The ''type'' option indicates the data type that this set stores, which is an IPv4 address in this case. Current maximum name length is 16 characters.

<source lang="bash">
% nft add element ip filter blackhole { 192.168.3.4 }
% nft add element ip filter blackhole { 192.168.1.4, 192.168.1.5 }
</source>

Then, you can use it from the rule:

<source lang="bash">
% nft add rule ip filter input ip saddr @blackhole drop
</source>

Named sets can be updated anytime, so you can add and delete element from them.

== nftables.conf syntax ==

When working with nftables.conf, you can define sets in a number of ways. You can then reference those sets later on using <code>$VARIABLE_NAME</code> notation.

Here are some examples showing sets defined in one line, spanning multiple lines, and sets referencing other sets. The set is then used in a rule to allow incoming traffic from certain IP ranges.

<source lang="bash">
define SIMPLE_SET = { 192.168.1.1, 192.168.1.2 }

define CDN_EDGE = {
192.168.1.1,
192.168.1.2,
192.168.1.3,
10.0.0.0/8
}

define CDN_MONITORS = {
192.168.1.10,
192.168.1.20
}

define CDN = {
$CDN_EDGE,
$CDN_MONITORS
}

# Allow HTTP(S) from approved IP ranges only
tcp dport { http, https } ip saddr $CDN accept
udp dport { http, https } ip saddr $CDN accept
</source>

= Named sets specifications =

Sets specifications are:

* '''type''' or '''typeof''', is obligatory and determines the data type of the set elements.

Supported data types if using the '''type''' keyword are:
** ''ipv4_addr'': IPv4 address
** ''ipv6_addr'': IPv6 address.
** ''ether_addr'': Ethernet address.
** ''inet_proto'': Inet protocol type.
** ''inet_service'': Internet service (read tcp port for example)
** ''mark'': Mark type.
** ''ifname'': Network interface name (eth0, eth1..)

The '''typeof''' keyword is available since '''0.9.4''' and allows you to use a high level expression, then let nftables resolve the base type for you:
<source lang="bash">
table inet mytable {
set s1 {
typeof osf name
elements = { "Linux" }
}
set s2 {
typeof vlan id
elements = { 2, 3, 103 }
}
set s3 {
typeof ip daddr
elements = { 1.1.1.1 }
}
}
</source>

* '''timeout''', it determines how long an element stays in the set. The time string respects the format: ''"v1dv2hv3mv4s"'':

<source lang="bash">
% nft add table ip filter
% nft add set ip filter ports {type inet_service \; timeout 3h45s \;}
</source>

These commands create a table named ''filter'' and add a set named ''ports'' to it, where elements are deleted after 3 hours and 45 seconds of being added.

* '''flags''', the available flags are:
** ''constant'' - set content may not change while bound
** ''interval'' - set contains intervals
** ''timeout'' - elements can be added with a timeout

Multiple flags should be separated by comma:

<source lang="bash">
% nft add set ip filter flags_set {type ipv4_addr\; flags constant, interval\;}
</source>

* '''gc-interval''', stands for garbage collection interval, can only be used if ''timeout'' or ''flags timeout'' are active. The interval follows the same format of ''timeouts'' time string ''"v1dv2hv3mv4s"''.

* '''elements''', initialize the set with some elements in it:

<source lang="bash">
% nft add set ip filter daddrs {type ipv4_addr \; flags timeout \; elements={192.168.1.1 timeout 10s, 192.168.1.2 timeout 30s} \;}
</source>

This command creates a set name ''daddrs'' with elements ''192.168.1.1'', which stays in it for 10s, and ''192.168.1.2'', which stays for 30s.

* '''size''', limits the maximum number of elements of the set. To create a set with maximum 2 elements type:

<source lang="bash">
% nft add set ip filter saddrs {type ipv4_addr \; size 2 \;}
</source>

* '''policy''', determines set selection policy. Available values are:
** ''performance'' [default]
** ''memory''

= Listing named sets =

You can list the content of a named set via:

<source lang="bash">
% nft list set ip filter myset
</source>

Concatenations

2020-09-03T09:13:25Z

Arturo: /* Network addresses */ refresh example with interval contacts

Since Linux kernel 4.1, nftables supports concatenations.

This new feature allows you to put two or more selectors together to perform very fast lookups by combining them with [[sets]], [[dictionaries]], [[maps]] and [[meters]].

= Literal sets =

<source lang="bash">
% nft add rule ip filter input ip saddr . ip daddr . ip protocol { 1.1.1.1 . 2.2.2.2 . tcp, 1.1.1.1 . 3.3.3.3 . udp} counter accept
</source>

So if the packet's source IP address AND destination IP address AND level 4 protocol match:

* 1.1.1.1 and 2.2.2.2 and TCP.

or

* 1.1.1.1 and 3.3.3.3 and UDP.

nftables updates the counter for this rule and then accepts the packet.

= Dictionary declarations =

The following example creates the ''whitelist'' dictionary using a concatenation of two selectors:

<source lang="bash">
% nft add map filter whitelist { type ipv4_addr . inet_service : verdict \; }
</source>

Once you create the dictionary, you can use it from a rule that creates the following concatenation:

<source lang="bash">
% nft add rule filter input ip saddr . tcp dport vmap @whitelist
</source>

Thus, the rule above looks up for a verdict based on the source IP address AND the TCP destination port.

Since the dictionary is initially empty, you can dynamically populate this dictionary with elements through:

<source lang="bash">
% nft add element filter whitelist { 1.2.3.4 . 22 : accept}
</source>

= Literal maps =

The rule below determines the destination IP address that is used to perform DNAT to the packet based on:

* the source IP address

AND

* the destination TCP port

<source lang="bash">
% nft add rule ip nat prerouting dnat ip saddr . tcp dport map { 1.1.1.1 . 80 : 192.168.1.100, 2.2.2.2 . 8888 : 192.168.1.101 }
</source>

= Examples =

Some concrete example concatenations so you get an idea on how powerful this new feature is.

== Network addresses ==

The example below implements a dictionary using network masks in each element:

<source lang="bash">
table inet mytable {
set myset {
type ipv4_addr . ipv4_addr
flags interval
elements = { 192.168.0.0/16 . 172.16.0.0/25,
10.0.0.0/30 . 192.168.1.0/24,
}
}

chain mychain {
ip saddr . ip daddr @myset counter accept
}
}
</source>

'''NOTE''': before kinux kernel 5.6 and nftables 0.9.4 the CIDR notation wasn't available, you would need to use a workaround:

<source lang="bash">
% nft add rule tablename chainname ip saddr and 255.255.255.0 . ip daddr and 255.255.255.0 vmap { 10.10.10.0 . 10.10.20.0 : accept }
</source>

Note that this is not an interval, this is masking the ip saddr and ip daddr, then concate both results. This concatenation is used to lookup for a matching of this the result in the map. This syntax may be compacted in future releases to support CIDR notation.

This could be easily implemented using a named map as well:

<source lang="bash">
% nft add map tablename myMap { type ipv4_addr . ipv4_addr : verdict \; }
% nft add rule tablename chainname ip saddr and 255.255.255.0 . ip saddr and 255.255.255.0 vmap @myMap
% nft add element tablename myMap { 10.10.10.0 . 10.10.20.0 : accept }
</source>

== Interfaces ==

The example below checks both input and output interfaces of a forwarded packet.

<source lang="bash">
% nft add rule tablename chainname iif . oif vmap { eth0 . eth1 : accept }
</source>

Please note that using strings (for example iifname and oifname) and other variable sized data types is not supported yet.

== Some ipset types ==

These ipset types can be implemented in nftables using concatenations. Probably more equivalences exists, it just a matter of combining data types.
Of course, you could implement these as named maps/sets as well.

See examples in the [[Moving_from_ipset_to_nftables | moving from ipset to nftables]] page.

List of updates since Linux kernel 3.13

2020-09-03T09:06:44Z

Arturo: add 5.6 reference

A listing of the development progress.

== 5.6 ==

* Support for ranges (intervals) in concatenations

== 4.16 ==

* flowtable support

== 4.15 ==

* Fetch single elements of a set (i.e, nft get element)

== 4.10 ==

* notrack support

== 4.3 ==

* Enhancements for the limit expression, support for ratelimit bytes/time unit.
* Dup expression (equivalent to the ''TEE'' target in iptables) for IPv4 and IPv6.
* VLAN header matching support when NIC support offloads.

== 4.2 ==

* New 'netdev' family for filtering from ingress.
* Context to x_tables extensions to know if they run from nft_compat.

== 4.1 ==

Major updates in the generic set infrastructure:

* Concatenations.
* Timeout per set elements.
* Comments per set elements.
* Dynamic set instantiation.

== 4.0 ==

* Mostly fixes.

== 3.19 ==

* redirect support.

== 3.18 ==

* masquerading support.
* meta cpu, devgroup matching.
* reject bridge support.
* destroy table and its content, ie. ''nft flush ruleset''.

== 3.17 ==

* log and nflog support for ip, ip6, arp and bridge families.

== 3.16 ==

* connlabel support.

== 3.15 ==

* Comments per rule support.
* IPv4 reject support.

== 3.14 ==

* set packet mark support.
* nfqueue support (only for ip and ip6 families).
* rule tracing support.
* IPv6 and inet reject support.

== 3.13 ==

* nf_tables merged mainstream.

List of updates since Linux kernel 3.13

2020-09-03T09:05:58Z

Arturo: sort in reverse order

A listing of the development progress.

== 4.16 ==

* flowtable support

== 4.15 ==

* Fetch single elements of a set (i.e, nft get element)

== 4.10 ==

* notrack support

== 4.3 ==

* Enhancements for the limit expression, support for ratelimit bytes/time unit.
* Dup expression (equivalent to the ''TEE'' target in iptables) for IPv4 and IPv6.
* VLAN header matching support when NIC support offloads.

== 4.2 ==

* New 'netdev' family for filtering from ingress.
* Context to x_tables extensions to know if they run from nft_compat.

== 4.1 ==

Major updates in the generic set infrastructure:

* Concatenations.
* Timeout per set elements.
* Comments per set elements.
* Dynamic set instantiation.

== 4.0 ==

* Mostly fixes.

== 3.19 ==

* redirect support.

== 3.18 ==

* masquerading support.
* meta cpu, devgroup matching.
* reject bridge support.
* destroy table and its content, ie. ''nft flush ruleset''.

== 3.17 ==

* log and nflog support for ip, ip6, arp and bridge families.

== 3.16 ==

* connlabel support.

== 3.15 ==

* Comments per rule support.
* IPv4 reject support.

== 3.14 ==

* set packet mark support.
* nfqueue support (only for ip and ip6 families).
* rule tracing support.
* IPv6 and inet reject support.

== 3.13 ==

* nf_tables merged mainstream.

Configuring chains

2020-09-03T08:56:11Z

Arturo: /* Base chain priority */ mention priority strings

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 gets accepted and there is another base chain in the same hook which is ordered with a later priority, the packet will be evaluated '''again'''.
That is, packets will traverse chains in a given hook, until it is dropped or no more base chains exist. Drops take instant effect, no further rules or chains are evaluated.

Example ruleset of this behavior:

<pre>
table inet filter {
# this chain is evaluated first due to priority
chain ssh {
type filter hook input priority 0; policy accept;
# ssh packet accepted
tcp dport ssh accept
}

# this chain is evaluated last due to priority
chain input {
type filter hook input priority 1; policy drop;
# the same ssh packet is dropped here by means of default policy
}
}
</pre>

If priority of the 'input chain' above would be changed to -1, all packets would be dropped.

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

Multiple NATs using nftables maps

2020-08-28T11:02:09Z

Arturo: add see also section with pointer to general docs on NAT

Thanks to nftables [[Maps]], if you have a previous iptables NAT (destination NAT) ruleset like this:

<source lang="bash">
% iptables -t nat -A PREROUTING -p tcp --dport 1000 -j DNAT --to-destination 1.1.1.1:1234
% iptables -t nat -A PREROUTING -p udp --dport 2000 -j DNAT --to-destination 2.2.2.2:2345
% iptables -t nat -A PREROUTING -p tcp --dport 3000 -j DNAT --to-destination 3.3.3.3:3456
</source>

It can be easily translated to nftables in a single line:

<source lang="bash">
% nft add rule nat prerouting dnat \
tcp dport map { 1000 : 1.1.1.1, 2000 : 2.2.2.2, 3000 : 3.3.3.3} \
: tcp dport map { 1000 : 1234, 2000 : 2345, 3000 : 3456 }
</source>

Likewise, in iptables NAT (source NAT):

<source lang="bash">
% iptables -t nat -A POSTROUTING -s 192.168.1.1 -j SNAT --to-source 1.1.1.1
% iptables -t nat -A POSTROUTING -s 192.168.2.2 -j SNAT --to-source 2.2.2.2
% iptables -t nat -A POSTROUTING -s 192.168.3.3 -j SNAT --to-source 3.3.3.3
</source>

Translated to a nftables one-liner:

<source lang="bash">
% nft add rule nat postrouting snat \
ip saddr map { 192.168.1.1 : 1.1.1.1, 192.168.2.2 : 2.2.2.2, 192.168.3.3 : 3.3.3.3 }
</source>

== See also ==

* [[Performing_Network_Address_Translation_(NAT) | Performing NAT with nftables]]

Performing Network Address Translation (NAT)

2020-08-28T11:01:23Z

Arturo: add see also section with pointer to example

The ''nat'' chain type allows you to perform 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 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.

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

Note that: ''redirect'' only makes sense in a prerouting chain 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 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.

The example below sets IP/port for each packet (also valid in 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 [[Mangle packet header fields | 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]]

Simple rule management

2020-07-22T10:38:12Z

Arturo: /* Listing rules */ add pointer to output text modifiers

= Appending new rules =

To add new rules, you have to specify the corresponding table and the chain that you want to use, eg.

<source lang="bash">
% nft add rule filter output ip daddr 8.8.8.8 counter
</source>

Where ''filter'' is the table and ''output'' is the chain. The example above adds a rule to match all packets seen by the output chain whose destination is 8.8.8.8, in case of matching it updates the rule counters. Note that counters are optional in ''nftables''.

For those familiar with iptables, the rule appending is equivalent to ''-A'' command in iptables.

= Listing rules =

You can list the rules that are contained by a table with the following command:

<source lang="bash">
% nft list table filter
table ip filter {
chain input {
type filter hook input priority 0;
}

chain output {
type filter hook output priority 0;
ip daddr 8.8.8.8 counter packets 0 bytes 0
tcp dport ssh counter packets 0 bytes 0
}
}
</source>

You can also list rules by chain, for example:

<source lang="bash">
% nft list chain filter ouput
table ip filter {
chain output {
type filter hook output priority 0;
ip daddr 8.8.8.8 counter packets 0 bytes 0
tcp dport ssh counter packets 0 bytes 0
}
}
</source>

There are plenty of [[Output_text_modifiers | output text modifiers]] than can be used when listing your rules, to for example, translate IP addresses to DNS names, TCP protocols, etc.

= Testing your rule =

Let's test this rule with a simple ping to 8.8.8.8:

<source lang="bash">
% ping -c 1 8.8.8.8
PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
64 bytes from 8.8.8.8: icmp_req=1 ttl=64 time=1.31 ms
</source>

Then, if we list the rule-set, we obtain:

<source lang="bash">
% nft -nn list table filter
table ip filter {
chain input {
type filter hook input priority 0;
}

chain output {
type filter hook output priority 0;
ip daddr 8.8.8.8 counter packets 1 bytes 84
tcp dport 22 counter packets 0 bytes 0
}
}
</source>

Note that the counters have been updated.

= Adding a rule at a given position =

If you want to add a rule at a given position, you have to use the handle as reference:

<source lang="bash">
% nft list table filter -n -a
table filter {
chain output {
type filter hook output priority 0;
ip protocol tcp counter packets 82 bytes 9680 # handle 8
ip saddr 127.0.0.1 ip daddr 127.0.0.6 drop # handle 7
}
}
</source>

If you want to add a rule after the rule with handler number 8, you have to type:

<source lang="bash">
% nft add rule filter output position 8 ip daddr 127.0.0.8 drop
</source>

Now, you can check the effect of that command by listing the rule-set:

<source lang="bash">
% nft list table filter -n -a
table filter {
chain output {
type filter hook output priority 0;
ip protocol tcp counter packets 190 bytes 21908 # handle 8
ip daddr 127.0.0.8 drop # handle 10
ip saddr 127.0.0.1 ip daddr 127.0.0.6 drop # handle 7
}
}
</source>

If you want to insert a rule before the rule with handler number 8, you have to type:

<source lang="bash">
% nft insert rule filter output position 8 ip daddr 127.0.0.8 drop
</source>

= Removing rules =

You have to obtain the ''handle'' to delete a rule via the '''-a''' option. The ''handle'' is automagically assigned by the kernel and it uniquely identifies the rule.

<source lang="bash">
% nft list table filter -a
table ip filter {
chain input {
type filter hook input priority 0;
}

chain output {
type filter hook output priority 0;
ip daddr 192.168.1.1 counter packets 1 bytes 84 # handle 5
}
}
</source>

You can delete the rule whose handle is ''5'' with the following command:

<source lang="bash">
% nft delete rule filter output handle 5
</source>

'''Note''': There are plans to support rule deletion by passing:
<source lang="bash">
% nft delete rule filter output ip saddr 192.168.1.1 counter
</source>

but this is '''not''' yet implemented. So you'll have to use the handle to delete rules until that feature is implemented.

= Removing all the rules in a chain =

You can delete '''all the rules''' in a chain with the following command:

<source lang="bash">
% nft delete rule filter output
</source>

You can also delete '''all the rules''' in a table with the following command:

<source lang="bash">
% nft flush table filter
</source>

= Prepending new rules =

To prepend new rules through the ''insert'' command:

<source lang="bash">
% nft insert rule filter output ip daddr 192.168.1.1 counter
</source>

This prepends a rule that will update per-rule packet and bytes counters for traffic addressed to 192.168.1.1.

The equivalent in iptables is:

<source lang="bash">
% iptables -I OUTPUT -t filter -d 192.168.1.1
</source>

Note that iptables always provides per-rule counters.

= Replacing rules =

You can replace any rule via the ''replace'' command by indicating the rule handle. Therefore, first you have to list the ruleset with option ''-a'' to obtain the rule handle.

<source lang="bash">
# nft list ruleset -a
table ip filter {
chain input {
type filter hook input priority 0; policy accept;
ip protocol tcp counter packets 0 bytes 0 # handle 2
}
}
</source>

Then, assuming you want to replace rule with handle number 2, you have to specify this handle number and the new rule that you want to place instead of it:

<source lang="bash">
nft replace rule filter input handle 2 counter
</source>

Then, when listing back the ruleset:

<source lang="bash">
# nft list ruleset -a
table ip filter {
chain input {
counter packets 0 bytes 0
}
}
</source>

You can effective note that the rule has been replaced by a simple rule that counts any packets, instead of counting TCP packets as the previous rule was doing.

Output text modifiers

2020-07-22T10:36:59Z

Arturo: create page

This page contains information on the several '''output text modifiers''' that nftables support when using the command line interface '''nft'''.

You can generally check all the output modifiers by using '''nft --help''' or reading the manpage '''nft(8)'''.

<pre>
-n, numeric Print fully numerical output.
-s, stateless Omit stateful information of ruleset.
-N, reversedns Translate IP addresses to names.
-S, service Translate ports to service names as described in /etc/services.
-a, handle Output rule handle.
-j, json Format output in JSON
-u, guid Print UID/GID as defined in /etc/passwd and /etc/group.
-y, numeric-priority Print chain priority numerically.
-p, numeric-protocol Print layer 4 protocols numerically.
-T, numeric-time Print time values numerically.
-t, terse Omit contents of sets.
</pre>

The default output prints some information in numeric form and for well-known names it will use a string instead (like icmp types, conntrack status, chain priorities, etc).
Also, state information such as counter values and set elements are printed as well.

<pre>
% nft list ruleset
table inet filter {
set s {
type inet_service
elements = { 80, 443 }
}

chain input {
type filter hook input priority filter; policy accept;
counter packets 4447 bytes 1619415
iif "lo" counter packets 337 bytes 25076 accept
ct state established,related counter packets 44899 bytes 106405802 accept
ip6 nexthdr ipv6-icmp icmpv6 type { nd-router-advert, nd-neighbor-solicit, nd-neighbor-advert } counter packets 1 bytes 72 accept
tcp dport 22 drop
ip saddr 8.8.8.8 drop
}
}
</pre>

== translation modifiers ==

Translate various values to text equivalents, or the other way around. We can group here things like ports, DNS names, service names, UID/GID, etc.

The options can be combined at will. The example below shows service names (instead of the integer number), chain priority value (instead of the well-known string), conntrack/protocol numbers and constants (instead of well-known strings) and shows reverse DNS names (instead of the numeric IP address):

<pre>
% nft -nNSy list ruleset
table inet filter {
set s {
type inet_service
elements = { "http", "https" }
}

chain input {
type filter hook input priority 0; policy accept;
iif "lo" counter packets 365 bytes 27092 accept
ct state 0x2,0x4 counter packets 48535 bytes 142472901 accept
ip6 nexthdr 58 icmpv6 type { 134, 135, 136 } counter packets 1 bytes 72 accept
ip saddr dns.google counter packets 0 bytes 0
tcp dport "ssh" accept
}
}
</pre>

Note that translating some elements might take additional operation time when generating the output. For example translating IP addresses to names require queries to DNS servers, which can be very slow for large rulesets (and therefore is disabled by default).

== operations and parsing modifiers ==

These modifiers add or remove information about the ruleset, generally useful when parsing the output or doing related operations.

You can display the ruleset without stateful information (for example, without counter values), with handles, and with no set contents:

<pre>
% nft -sta list ruleset
table inet filter { # handle 5
set s { # handle 9
type inet_service
}

chain input { # handle 1
type filter hook input priority filter; policy accept;
iif "lo" counter accept # handle 3
ct state established,related counter accept # handle 4
ip6 nexthdr ipv6-icmp icmpv6 type { nd-router-advert, nd-neighbor-solicit, nd-neighbor-advert } counter accept # handle 5
ip saddr 8.8.8.8 counter # handle 8
tcp dport 22 accept # handle 10
}
}
</pre>

Special mention to the JSON representation of the ruleset. The JSON will be printed in a single line fashion. Here we format the JSON using perl's json_pp utility:

<pre>
% nft -j list ruleset | json_pp
{
"nftables" : [
{
"metainfo" : {
"json_schema_version" : 1,
"release_name" : "Capital Idea #2",
"version" : "0.9.6"
}
},
{
"table" : {
"family" : "inet",
"handle" : 5,
"name" : "filter"
}
},
{
"set" : {
"elem" : [
80,
443
],
"family" : "inet",
"handle" : 9,
"name" : "s",
"table" : "filter",
"type" : "inet_service"
}
},
{
"chain" : {
"family" : "inet",
"handle" : 1,
"hook" : "input",
"name" : "input",
"policy" : "accept",
"prio" : 0,
"table" : "filter",
"type" : "filter"
}
},
{
"rule" : {
"chain" : "input",
"expr" : [
{
"counter" : {
"bytes" : 37707381,
"packets" : 8062
}
}
],
"family" : "inet",
"handle" : 7,
"table" : "filter"
}
},
[..]
</pre>

Main Page

2020-07-22T10:10:47Z

Arturo: /* Basic operation */ add link to the new page output text modifiers

Welcome to the ''nftables'' HOWTO documentation page. Here you will find documentation on how to build, install, configure and use nftables.

If you have any suggestion to improve it, please send your comments to Netfilter users mailing list <netfilter@vger.kernel.org>.

= Introduction =

* [[What is nftables?]]
* [[Why nftables?]]
* [[Main differences with iptables]]
* [[Netfilter hooks]] and integration with existing Netfilter components.
* [[Adoption]]
* [[Legacy xtables tools]]
* [[How to obtain help/support]]

= Getting started =

* [[Building and installing nftables from sources]]
* Using [[nftables from distributions]]
* [[Troubleshooting|Troubleshooting and FAQ]]
* [[Quick reference-nftables in 10 minutes|Quick reference, nftables in 10 minutes]]
* [[nftables families|Understanding nftables families]]

= Basic operation =

* [[Configuring tables]]
* [[Configuring chains]]
* [[Simple rule management]]
* [[Atomic rule replacement]]
* [[Error reporting from the command line]]
* [[Building rules through expressions]]
* [[Operations at ruleset level]]
* [[Monitoring ruleset updates]]
* [[Scripting]]
* [[Ruleset debug/tracing]]
* [[Moving from iptables to nftables]]
* [[Moving from ipset to nftables]]
* [[Output text modifiers]]

= Supported selectors for packet matching =

* [[Matching packet header fields]]
* [[Matching packet metainformation]]
* [[Matching connection tracking stateful metainformation]]
* [[Rate limiting matchings]]
* [[Routing information]]

= Possible actions on packets =

* [[Accepting and dropping packets]]
* [[Jumping to chain]]
* [[Rejecting traffic]]
* [[Logging traffic]]
* [[Performing Network Address Translation (NAT)]]
* [[Setting packet metainformation]]
* [[Queueing to userspace]]
* [[Duplicating packets]]
* [[Mangle packet header fields]]
* [[Mangle TCP options]]
* [[Counters]]
* [[Load balancing]]
* [[Setting packet connection tracking metainformation]]

Note that, unlike ''iptables'', you can perform several actions in one single rule.

= Advanced data structures for performance packet classification =

You will have to redesign your rule-set to benefit from these new nice features:

* [[Sets]]
* [[Dictionaries]]
* [[Intervals]]
* [[Maps]]
* [[Concatenations]]
* [[Meters|Metering]] (formerly known as flow tables before nftables 0.8.1 release)
* [[Updating sets from the packet path]]
* [[Element timeouts]]
* [[Math operations]]
* [[Stateful objects]]
* [[Flowtable]] (the fastpath network stack bypass)

If you are already using [[ipset]] in your ''iptables'' rule-set, that transition may be a bit more simple to you.

= Examples =

* [[Simple ruleset for a workstation]]
* [[Simple ruleset for a server]]
* [[Bridge filtering]]
* [[Multiple NATs using nftables maps]]
* [[Classic perimetral firewall example]]
* [[Port knocking example]]
* [[Classification to tc structure example]]
* [[Using configuration management systems]] (like puppet, ansible, etc)
* [[GeoIP matching]]

= Development =

Check [[Portal:DeveloperDocs|Portal:DeveloperDocs - documentation for netfilter developers]].

Some hints on the general development progress:

* [[List of updates since Linux kernel 3.13]]
* [[List of updates in the nft command line tool]]
* [[Supported features compared to xtables|Supported features compared to {ip,ip6,eb,arp}tables]]
* [[List of available translations via iptables-translate tool]]

= External links =

Watch some videos:

* Watch [https://www.youtube.com/watch?v=FXTRRwXi3b4 Getting a grasp of nftables], thanks to [https://www.nluug.nl/index-en.html NLUUG association] for recording this.
* Watch [https://www.youtube.com/watch?v=CaYp0d2wiuU#t=1m47s The ultimate packet classifier for GNU/Linux], thanks to the FSFE for paying my trip to Barcelona and for recommending me as speaker to the KDE Spanish branch.
* [https://www.youtube.com/watch?v=Sy0JDX451ns Florian Westphal - Why nftables?]
* Watch [https://www.youtube.com/watch?v=qXVOA2MKA1s Netdev 2.1 - Netfilter workshop]
* Watch [https://youtu.be/iCj10vEKPrw Netdev 2.2 - Netf‌ilter mini-workshop]
* Watch [https://youtu.be/0hqfzp6tpZo Netdev 0x12 - Netf‌ilter mini-workshop]
* Watch [https://www.youtube.com/watch?v=0wQfSfDVN94 NLUUG - Goodbye iptables, Hello nftables]
* Watch [https://www.youtube.com/watch?v=Uf5ULkEWPL0 LCA2018 - nftables from a user perspective]

Additional documentations and articles:

* Tutorial [https://zasdfgbnm.github.io/2017/09/07/Extending-nftables/ Extending nftables by Xiang Gao]
* Article [http://ral-arturo.org/2017/05/05/debian-stretch-stable-nftables.html New in Debian stable Stretch: nftables]

= Thanks =

To the NLnet foundation for initial sponsorship of this HOWTO:

[https://nlnet.nl https://nlnet.nl/image/logo.gif]

To Eric Leblond, for boostrapping the [https://home.regit.org/netfilter-en/nftables-quick-howto/ Nftables quick howto] in 2013.

Simple rule management

2020-07-22T10:09:18Z

Arturo: /* Listing rules */ modernize this information, will separate output modifiers to other page

= Appending new rules =

To add new rules, you have to specify the corresponding table and the chain that you want to use, eg.

<source lang="bash">
% nft add rule filter output ip daddr 8.8.8.8 counter
</source>

Where ''filter'' is the table and ''output'' is the chain. The example above adds a rule to match all packets seen by the output chain whose destination is 8.8.8.8, in case of matching it updates the rule counters. Note that counters are optional in ''nftables''.

For those familiar with iptables, the rule appending is equivalent to ''-A'' command in iptables.

= Listing rules =

You can list the rules that are contained by a table with the following command:

<source lang="bash">
% nft list table filter
table ip filter {
chain input {
type filter hook input priority 0;
}

chain output {
type filter hook output priority 0;
ip daddr 8.8.8.8 counter packets 0 bytes 0
tcp dport ssh counter packets 0 bytes 0
}
}
</source>

You can also list rules by chain, for example:

<source lang="bash">
% nft list chain filter ouput
table ip filter {
chain output {
type filter hook output priority 0;
ip daddr 8.8.8.8 counter packets 0 bytes 0
tcp dport ssh counter packets 0 bytes 0
}
}
</source>

= Testing your rule =

Let's test this rule with a simple ping to 8.8.8.8:

<source lang="bash">
% ping -c 1 8.8.8.8
PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
64 bytes from 8.8.8.8: icmp_req=1 ttl=64 time=1.31 ms
</source>

Then, if we list the rule-set, we obtain:

<source lang="bash">
% nft -nn list table filter
table ip filter {
chain input {
type filter hook input priority 0;
}

chain output {
type filter hook output priority 0;
ip daddr 8.8.8.8 counter packets 1 bytes 84
tcp dport 22 counter packets 0 bytes 0
}
}
</source>

Note that the counters have been updated.

= Adding a rule at a given position =

If you want to add a rule at a given position, you have to use the handle as reference:

<source lang="bash">
% nft list table filter -n -a
table filter {
chain output {
type filter hook output priority 0;
ip protocol tcp counter packets 82 bytes 9680 # handle 8
ip saddr 127.0.0.1 ip daddr 127.0.0.6 drop # handle 7
}
}
</source>

If you want to add a rule after the rule with handler number 8, you have to type:

<source lang="bash">
% nft add rule filter output position 8 ip daddr 127.0.0.8 drop
</source>

Now, you can check the effect of that command by listing the rule-set:

<source lang="bash">
% nft list table filter -n -a
table filter {
chain output {
type filter hook output priority 0;
ip protocol tcp counter packets 190 bytes 21908 # handle 8
ip daddr 127.0.0.8 drop # handle 10
ip saddr 127.0.0.1 ip daddr 127.0.0.6 drop # handle 7
}
}
</source>

If you want to insert a rule before the rule with handler number 8, you have to type:

<source lang="bash">
% nft insert rule filter output position 8 ip daddr 127.0.0.8 drop
</source>

= Removing rules =

You have to obtain the ''handle'' to delete a rule via the '''-a''' option. The ''handle'' is automagically assigned by the kernel and it uniquely identifies the rule.

<source lang="bash">
% nft list table filter -a
table ip filter {
chain input {
type filter hook input priority 0;
}

chain output {
type filter hook output priority 0;
ip daddr 192.168.1.1 counter packets 1 bytes 84 # handle 5
}
}
</source>

You can delete the rule whose handle is ''5'' with the following command:

<source lang="bash">
% nft delete rule filter output handle 5
</source>

'''Note''': There are plans to support rule deletion by passing:
<source lang="bash">
% nft delete rule filter output ip saddr 192.168.1.1 counter
</source>

but this is '''not''' yet implemented. So you'll have to use the handle to delete rules until that feature is implemented.

= Removing all the rules in a chain =

You can delete '''all the rules''' in a chain with the following command:

<source lang="bash">
% nft delete rule filter output
</source>

You can also delete '''all the rules''' in a table with the following command:

<source lang="bash">
% nft flush table filter
</source>

= Prepending new rules =

To prepend new rules through the ''insert'' command:

<source lang="bash">
% nft insert rule filter output ip daddr 192.168.1.1 counter
</source>

This prepends a rule that will update per-rule packet and bytes counters for traffic addressed to 192.168.1.1.

The equivalent in iptables is:

<source lang="bash">
% iptables -I OUTPUT -t filter -d 192.168.1.1
</source>

Note that iptables always provides per-rule counters.

= Replacing rules =

You can replace any rule via the ''replace'' command by indicating the rule handle. Therefore, first you have to list the ruleset with option ''-a'' to obtain the rule handle.

<source lang="bash">
# nft list ruleset -a
table ip filter {
chain input {
type filter hook input priority 0; policy accept;
ip protocol tcp counter packets 0 bytes 0 # handle 2
}
}
</source>

Then, assuming you want to replace rule with handle number 2, you have to specify this handle number and the new rule that you want to place instead of it:

<source lang="bash">
nft replace rule filter input handle 2 counter
</source>

Then, when listing back the ruleset:

<source lang="bash">
# nft list ruleset -a
table ip filter {
chain input {
counter packets 0 bytes 0
}
}
</source>

You can effective note that the rule has been replaced by a simple rule that counts any packets, instead of counting TCP packets as the previous rule was doing.

Stateful objects

2020-07-21T13:34:22Z

Arturo: /* Listing stateful objects */ add more quota examples

Since Linux Kernel 4.10 and nft v0.8 nftables supports stateful objects.

Stateful objects group stateful information of rules, the supported types are: '''counters''' and '''quotas'''. Stateful objects are attached to tables and have a unique name, defined by the user.

= Creating stateful objects =

You can create a '''stateful counter''' with the following commands:

<source lang="bash">
% nft add table filter
% nft add counter filter https-traffic
</source>

These rules create a table named ''filter'', then a '''stateful counter''' named ''https-traffic'' and attaches it to the ''filter'' table.

Creating a '''quota''' is similar:

<source lang="bash">
% nft add quota filter https-quota 25 mbytes
</source>

A quota named ''https-quota'' is attached to the table ''filter'', notice that you must specify the quota's size on creation.

= Referencing stateful objects in rules =

Stateful objects are referenced in rules by their names. They act as both actions and in the case of quotas also matches the simplest way is:

<source lang="bash">
% nft add chain filter output { type filter hook output priority 0 \; }
% nft add rule filter output tcp dport https counter name https-traffic
</source>

These rules create a chain named ''output'' in the table ''filter'', then a rule to counter the ''https'' packets generated by your machine and display them in the counter ''https-traffic''.

They can also be used with maps:

<source lang="bash">
% nft add rule filter output counter name tcp dport map { \
https : "https-traffic", \
80 : "http-traffic", \
25 : "foo-counter", \
50 : "foo-counter", \
107 : "foo-counter" \
}
</source>

Similarly, dynamic maps can be used:

<source lang="bash">
% nft add map filter ports { type inet_service : quota \; }
% nft add rule filter output quota name tcp dport map @ports
% nft add quota filter http-quota over 25 mbytes
% nft add quota filter ssh-quota 10 kbytes
% nft add element filter ports { 80 : "http-quota" }
% nft add element filter ports { 22 : "ssh-quota" }
</source>

When using quotas, the packet will be counted towards the quota, and if the quota matches (either up-to or over depending on quota type) the remaining actions will take place, otherwise not.

<source lang="bash">

table inet foo {
quota example { over 100 mbytes used 0 bytes }

chain dropafterquota {
type filter hook postrouting priority 0; policy accept;
udp port 5060 quota name "example" drop
}

}

</source>

Will count all udp port 5060 packets towards the quota and drop all packets once the quota hits its "over 100 mbytes" threshold.

= Listing stateful objects =

You can list the stateful information of objects individually via:

<source lang="bash">
% nft list counter filter https-traffic
table ip filter {
counter https-traffic {
packets 0 bytes 0
}
}

% nft list quota ip filter https-quota
table ip filter {
quota https-quota {
25 mbytes
}
}

</source>

Also, it's possible to list all stateful objects of the same type. Example with quotas:

<source lang="bash">
% nft list quotas
table inet filter {
quota other-inet-quota {
200 mbytes
}
}
table ip filter {
quota https-quota {
30 mbytes
}
quota http-quota {
25 mbytes
}
}
</source>

Example with counters:

<source lang="bash">
% nft list counters
table inet filter {
counter mycounter {
packets 0 bytes 0
}
counter mycounter2 {
packets 0 bytes 0
}
}
table ip filter {
counter https-traffic {
packets 0 bytes 0
}
}
</source>

And list all stateful objects of a type in a given table. Example with counters:

<source lang="bash">
% nft list counters table inet filter
table inet filter {
counter mycounter {
packets 0 bytes 0
}
counter mycounter2 {
packets 0 bytes 0
}
}
</source>

Example with quotas:

<source lang="bash">
% nft list quotas table ip filter
table ip filter {
quota https-quota {
30 mbytes
}
quota http-quota {
25 mbytes
}
}
</source>

= Resetting stateful objects =

Resetting an object will atomically dump and reset its content:

<source lang="bash">
% nft reset quota filter https-quota
table ip filter {
quota https-quota {
25 mbytes used 217 kbytes
}
}

% nft list quota filter https-quota
table ip filter {
quota https-quota {
25 mbytes
}
}
</source>

Other usages are similar to the command list, e.g.

<source lang="bash">
% nft reset counters
% nft reset quotas table filter
</source>

At the moment (Jan 2019) resetting quotas does not reset anonymous quotas such as used in rules without names, see [https://bugzilla.netfilter.org/show_bug.cgi?id=1314 bug #1314]

Stateful objects

2020-07-21T13:30:34Z

Arturo: /* Listing stateful objects */ extend examples

Since Linux Kernel 4.10 and nft v0.8 nftables supports stateful objects.

Stateful objects group stateful information of rules, the supported types are: '''counters''' and '''quotas'''. Stateful objects are attached to tables and have a unique name, defined by the user.

= Creating stateful objects =

You can create a '''stateful counter''' with the following commands:

<source lang="bash">
% nft add table filter
% nft add counter filter https-traffic
</source>

These rules create a table named ''filter'', then a '''stateful counter''' named ''https-traffic'' and attaches it to the ''filter'' table.

Creating a '''quota''' is similar:

<source lang="bash">
% nft add quota filter https-quota 25 mbytes
</source>

A quota named ''https-quota'' is attached to the table ''filter'', notice that you must specify the quota's size on creation.

= Referencing stateful objects in rules =

Stateful objects are referenced in rules by their names. They act as both actions and in the case of quotas also matches the simplest way is:

<source lang="bash">
% nft add chain filter output { type filter hook output priority 0 \; }
% nft add rule filter output tcp dport https counter name https-traffic
</source>

These rules create a chain named ''output'' in the table ''filter'', then a rule to counter the ''https'' packets generated by your machine and display them in the counter ''https-traffic''.

They can also be used with maps:

<source lang="bash">
% nft add rule filter output counter name tcp dport map { \
https : "https-traffic", \
80 : "http-traffic", \
25 : "foo-counter", \
50 : "foo-counter", \
107 : "foo-counter" \
}
</source>

Similarly, dynamic maps can be used:

<source lang="bash">
% nft add map filter ports { type inet_service : quota \; }
% nft add rule filter output quota name tcp dport map @ports
% nft add quota filter http-quota over 25 mbytes
% nft add quota filter ssh-quota 10 kbytes
% nft add element filter ports { 80 : "http-quota" }
% nft add element filter ports { 22 : "ssh-quota" }
</source>

When using quotas, the packet will be counted towards the quota, and if the quota matches (either up-to or over depending on quota type) the remaining actions will take place, otherwise not.

<source lang="bash">

table inet foo {
quota example { over 100 mbytes used 0 bytes }

chain dropafterquota {
type filter hook postrouting priority 0; policy accept;
udp port 5060 quota name "example" drop
}

}

</source>

Will count all udp port 5060 packets towards the quota and drop all packets once the quota hits its "over 100 mbytes" threshold.

= Listing stateful objects =

You can list the stateful information of objects individually via:

<source lang="bash">
% nft list counter filter https-traffic
table ip filter {
counter https-traffic {
packets 0 bytes 0
}
}
</source>

Also, it's possible to list all stateful objects of the same type. Example with quotas:

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

Example with counters:

<source lang="bash">
% nft list counters
table inet filter {
counter mycounter {
packets 0 bytes 0
}
counter mycounter2 {
packets 0 bytes 0
}
}
table ip filter {
counter https-traffic {
packets 0 bytes 0
}
}
</source>

And list all stateful objects of a type in a given table. Example with counters:

<source lang="bash">
% nft list counters table inet filter
table inet filter {
counter mycounter {
packets 0 bytes 0
}
counter mycounter2 {
packets 0 bytes 0
}
}
</source>

= Resetting stateful objects =

Resetting an object will atomically dump and reset its content:

<source lang="bash">
% nft reset quota filter https-quota
table ip filter {
quota https-quota {
25 mbytes used 217 kbytes
}
}

% nft list quota filter https-quota
table ip filter {
quota https-quota {
25 mbytes
}
}
</source>

Other usages are similar to the command list, e.g.

<source lang="bash">
% nft reset counters
% nft reset quotas table filter
</source>

At the moment (Jan 2019) resetting quotas does not reset anonymous quotas such as used in rules without names, see [https://bugzilla.netfilter.org/show_bug.cgi?id=1314 bug #1314]

Stateful objects

2020-07-21T13:23:02Z

Arturo: /* Creating stateful objects */ be more precise

Since Linux Kernel 4.10 and nft v0.8 nftables supports stateful objects.

Stateful objects group stateful information of rules, the supported types are: '''counters''' and '''quotas'''. Stateful objects are attached to tables and have a unique name, defined by the user.

= Creating stateful objects =

You can create a '''stateful counter''' with the following commands:

<source lang="bash">
% nft add table filter
% nft add counter filter https-traffic
</source>

These rules create a table named ''filter'', then a '''stateful counter''' named ''https-traffic'' and attaches it to the ''filter'' table.

Creating a '''quota''' is similar:

<source lang="bash">
% nft add quota filter https-quota 25 mbytes
</source>

A quota named ''https-quota'' is attached to the table ''filter'', notice that you must specify the quota's size on creation.

= Referencing stateful objects in rules =

Stateful objects are referenced in rules by their names. They act as both actions and in the case of quotas also matches the simplest way is:

<source lang="bash">
% nft add chain filter output { type filter hook output priority 0 \; }
% nft add rule filter output tcp dport https counter name https-traffic
</source>

These rules create a chain named ''output'' in the table ''filter'', then a rule to counter the ''https'' packets generated by your machine and display them in the counter ''https-traffic''.

They can also be used with maps:

<source lang="bash">
% nft add rule filter output counter name tcp dport map { \
https : "https-traffic", \
80 : "http-traffic", \
25 : "foo-counter", \
50 : "foo-counter", \
107 : "foo-counter" \
}
</source>

Similarly, dynamic maps can be used:

<source lang="bash">
% nft add map filter ports { type inet_service : quota \; }
% nft add rule filter output quota name tcp dport map @ports
% nft add quota filter http-quota over 25 mbytes
% nft add quota filter ssh-quota 10 kbytes
% nft add element filter ports { 80 : "http-quota" }
% nft add element filter ports { 22 : "ssh-quota" }
</source>

When using quotas, the packet will be counted towards the quota, and if the quota matches (either up-to or over depending on quota type) the remaining actions will take place, otherwise not.

<source lang="bash">

table inet foo {
quota example { over 100 mbytes used 0 bytes }

chain dropafterquota {
type filter hook postrouting priority 0; policy accept;
udp port 5060 quota name "example" drop
}

}

</source>

Will count all udp port 5060 packets towards the quota and drop all packets once the quota hits its "over 100 mbytes" threshold.

= Listing stateful objects =

You can list the stateful information of objects individually via:

<source lang="bash">
% nft list counter filter https-traffic
</source>

Also, it's possible to list all stateful objects of the same type:

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

And list all stateful objects of a type in a table:

<source lang="bash">
% nft list counters table filter
</source>

= Resetting stateful objects =

Resetting an object will atomically dump and reset its content:

<source lang="bash">
% nft reset quota filter https-quota
table ip filter {
quota https-quota {
25 mbytes used 217 kbytes
}
}

% nft list quota filter https-quota
table ip filter {
quota https-quota {
25 mbytes
}
}
</source>

Other usages are similar to the command list, e.g.

<source lang="bash">
% nft reset counters
% nft reset quotas table filter
</source>

At the moment (Jan 2019) resetting quotas does not reset anonymous quotas such as used in rules without names, see [https://bugzilla.netfilter.org/show_bug.cgi?id=1314 bug #1314]

Stateful objects

2020-07-21T13:22:34Z

Arturo: more bolding

Since Linux Kernel 4.10 and nft v0.8 nftables supports stateful objects.

Stateful objects group stateful information of rules, the supported types are: '''counters''' and '''quotas'''. Stateful objects are attached to tables and have a unique name, defined by the user.

= Creating stateful objects =

You can create a '''stateful counter''' with the following commands:

<source lang="bash">
% nft add table filter
% nft add counter filter https-traffic
</source>

These rules create a table named ''filter'', then a '''stateful counter''' named ''https-traffic'' and attaches it to ''filter''.

Creating a '''quota''' is similar:

<source lang="bash">
% nft add quota filter https-quota 25 mbytes
</source>

A quota named ''https-quota'' is attached to the table ''filter'', notice that you must specify the quota's size on creation.

= Referencing stateful objects in rules =

Stateful objects are referenced in rules by their names. They act as both actions and in the case of quotas also matches the simplest way is:

<source lang="bash">
% nft add chain filter output { type filter hook output priority 0 \; }
% nft add rule filter output tcp dport https counter name https-traffic
</source>

These rules create a chain named ''output'' in the table ''filter'', then a rule to counter the ''https'' packets generated by your machine and display them in the counter ''https-traffic''.

They can also be used with maps:

<source lang="bash">
% nft add rule filter output counter name tcp dport map { \
https : "https-traffic", \
80 : "http-traffic", \
25 : "foo-counter", \
50 : "foo-counter", \
107 : "foo-counter" \
}
</source>

Similarly, dynamic maps can be used:

<source lang="bash">
% nft add map filter ports { type inet_service : quota \; }
% nft add rule filter output quota name tcp dport map @ports
% nft add quota filter http-quota over 25 mbytes
% nft add quota filter ssh-quota 10 kbytes
% nft add element filter ports { 80 : "http-quota" }
% nft add element filter ports { 22 : "ssh-quota" }
</source>

When using quotas, the packet will be counted towards the quota, and if the quota matches (either up-to or over depending on quota type) the remaining actions will take place, otherwise not.

<source lang="bash">

table inet foo {
quota example { over 100 mbytes used 0 bytes }

chain dropafterquota {
type filter hook postrouting priority 0; policy accept;
udp port 5060 quota name "example" drop
}

}

</source>

Will count all udp port 5060 packets towards the quota and drop all packets once the quota hits its "over 100 mbytes" threshold.

= Listing stateful objects =

You can list the stateful information of objects individually via:

<source lang="bash">
% nft list counter filter https-traffic
</source>

Also, it's possible to list all stateful objects of the same type:

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

And list all stateful objects of a type in a table:

<source lang="bash">
% nft list counters table filter
</source>

= Resetting stateful objects =

Resetting an object will atomically dump and reset its content:

<source lang="bash">
% nft reset quota filter https-quota
table ip filter {
quota https-quota {
25 mbytes used 217 kbytes
}
}

% nft list quota filter https-quota
table ip filter {
quota https-quota {
25 mbytes
}
}
</source>

Other usages are similar to the command list, e.g.

<source lang="bash">
% nft reset counters
% nft reset quotas table filter
</source>

At the moment (Jan 2019) resetting quotas does not reset anonymous quotas such as used in rules without names, see [https://bugzilla.netfilter.org/show_bug.cgi?id=1314 bug #1314]

Counters

2020-07-21T13:21:55Z

Arturo: add pointer to stateful counters

Counters are optional in ''nftables'', thus, you need to explicitly specify them in the rule if you want them.

The following example allows you to account all tcp traffic that you machine receives:

<source lang="bash">
% nft add rule filter input ip protocol tcp counter
</source>

An interesting feature of the counter action is that its position in the rule syntax matters. This rule is '''not''' equivalent to the previous rule:

<source lang="bash">
% nft add rule filter input counter ip protocol tcp
</source>

The rule is evaluated from the left to the right, so '''any kind of packet''' will update the counters, not only TCP packets.

== Stateful counters ==

nftables has native support for '''stateful counters''', i.e, counters not attached to a particular rule. Check the [[Stateful_objects | stateful objects]] page for more details.

Stateful objects

2020-07-21T13:20:23Z

Arturo: /* Creating stateful objects */ add some bolding

Since Linux Kernel 4.10 and nft v0.8 nftables supports stateful objects.

Stateful objects group stateful information of rules, the supported types are: counters and quotas. Stateful objects are attached to tables and have a unique name, defined by the user.

= Creating stateful objects =

You can create a '''stateful counter''' with the following commands:

<source lang="bash">
% nft add table filter
% nft add counter filter https-traffic
</source>

These rules create a table named ''filter'', then a '''stateful counter''' named ''https-traffic'' and attaches it to ''filter''.

Creating a '''quota''' is similar:

<source lang="bash">
% nft add quota filter https-quota 25 mbytes
</source>

A quota named ''https-quota'' is attached to the table ''filter'', notice that you must specify the quota's size on creation.

= Referencing stateful objects in rules =

Stateful objects are referenced in rules by their names. They act as both actions and in the case of quotas also matches the simplest way is:

<source lang="bash">
% nft add chain filter output { type filter hook output priority 0 \; }
% nft add rule filter output tcp dport https counter name https-traffic
</source>

These rules create a chain named ''output'' in the table ''filter'', then a rule to counter the ''https'' packets generated by your machine and display them in the counter ''https-traffic''.

They can also be used with maps:

<source lang="bash">
% nft add rule filter output counter name tcp dport map { \
https : "https-traffic", \
80 : "http-traffic", \
25 : "foo-counter", \
50 : "foo-counter", \
107 : "foo-counter" \
}
</source>

Similarly, dynamic maps can be used:

<source lang="bash">
% nft add map filter ports { type inet_service : quota \; }
% nft add rule filter output quota name tcp dport map @ports
% nft add quota filter http-quota over 25 mbytes
% nft add quota filter ssh-quota 10 kbytes
% nft add element filter ports { 80 : "http-quota" }
% nft add element filter ports { 22 : "ssh-quota" }
</source>

When using quotas, the packet will be counted towards the quota, and if the quota matches (either up-to or over depending on quota type) the remaining actions will take place, otherwise not.

<source lang="bash">

table inet foo {
quota example { over 100 mbytes used 0 bytes }

chain dropafterquota {
type filter hook postrouting priority 0; policy accept;
udp port 5060 quota name "example" drop
}

}

</source>

Will count all udp port 5060 packets towards the quota and drop all packets once the quota hits its "over 100 mbytes" threshold.

= Listing stateful objects =

You can list the stateful information of objects individually via:

<source lang="bash">
% nft list counter filter https-traffic
</source>

Also, it's possible to list all stateful objects of the same type:

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

And list all stateful objects of a type in a table:

<source lang="bash">
% nft list counters table filter
</source>

= Resetting stateful objects =

Resetting an object will atomically dump and reset its content:

<source lang="bash">
% nft reset quota filter https-quota
table ip filter {
quota https-quota {
25 mbytes used 217 kbytes
}
}

% nft list quota filter https-quota
table ip filter {
quota https-quota {
25 mbytes
}
}
</source>

Other usages are similar to the command list, e.g.

<source lang="bash">
% nft reset counters
% nft reset quotas table filter
</source>

At the moment (Jan 2019) resetting quotas does not reset anonymous quotas such as used in rules without names, see [https://bugzilla.netfilter.org/show_bug.cgi?id=1314 bug #1314]

Building and installing nftables from sources

2020-04-14T11:15:13Z

Arturo: /* Validating your installation */ there is no longer a dmesg message now

nftables requires several userspace libraries, the 'nft' userspace command line utility and the kernel modules.

If you are using a major linux distribution, you may consider using [[nftables from distributions]].

= Installing userspace libraries =

You have to install the following userspace libraries:

* [http://www.netfilter.org/projects/libmnl libmnl ], this library provides the interfaces to communicate kernel and userspace via Netlink. ''It is very likely that your distribution already provides a package for libmnl that you can use''. If you decide to use your distributor package, make sure you install the development package as well.

* [http://www.netfilter.org/projects/libnftnl libnftnl], this library provides the low-level API to transform netlink messages to objects.

You also need ''libgmp'' and ''libreadline'', most distributions already provide packages for these two libraries, so make sure you install the development extensions of this packages to successfully compile ''nftables''.

If you plan to give a test to ''nftables'', we recommend you to use git snapshots for ''libnftnl'' and ''nft''.

== Installing userspace libraries from git ==

To install ''libnftnl'', to can type these magic spells:

<source lang="bash">
$ git clone git://git.netfilter.org/libnftnl
$ cd libnftnl
$ sh autogen.sh
$ ./configure
$ make
$ sudo make install
</source>
If you are working behind proxy than it might possible that you are not able to clone using git protocol so try to clone using "http/https:" instead "git:"
 Reasons:- 1) The git protocol, by default, uses the port 9418. It might possible that your traffic is blocked on that port.
 2) Also take help and can relate from the [http://stackoverflow.com/a/28494985 solution]

If you have any compilation problem, please report them to the [https://www.netfilter.org/mailinglists.html netfilter developer mailing list] providing as much detailed information as possible.

== Installing userspace libraries from snapshots ==

You can retrieve daily snapshots of this library from the [ftp://ftp.netfilter.org/pub/libnftnl/snapshot/ Netfilter FTP]. Then, to install it you have to:

<source lang="bash">
$ wget ftp://ftp.netfilter.org/pub/libnftnl/snapshot/libnftnl-20140217.tar.bz2
$ tar xvjf libnftnl-20140217.tar.bz2
$ ./configure
$ make
$ sudo make install
</source>

= Installing userspace nft command line utility =

This is the command line utility that provides a user interface to configure ''nftables''.

== Installing from git ==

Just type these commands:

<source lang="bash">
% git clone git://git.netfilter.org/nftables
% cd nftables
% sh autogen.sh
% ./configure
% make
% make install
</source>

You should check that ''nft'' is installed in your system by typing:

<source lang="bash">
% nft
nft: no command specified
</source>

That means ''nft'' has been correctly installed.

= Installing Linux kernel with nftables support =

Prerequisites: nftables is available in Linux kernels since version 3.13 but this is software under development, so we encourage you to run the latest stable kernel.

== Validating your installation ==

You can validate that your installation is working by checking if you can install the 'nf_tables' kernel module.

<source lang="bash">
% modprobe nf_tables
</source>

Then, you can check that's actually there via ''lsmod'':

<source lang="bash">
# lsmod | grep nf_tables
nf_tables 42349 0
</source>

Make sure you also have loaded the family support, eg.

<source lang="bash">
% modprobe nf_tables_ipv4
</source>

The ''lsmod'' command should show something like:

<source lang="bash">
# lsmod | grep nf_tables
nf_tables_ipv4 12869 0
nf_tables 42349 1 nf_tables_ipv4
</source>

Other family modules are ''nf_tables_ipv6'', ''nf_tables_bridge'', ''nf_tables_arp'' and (since Linux kernel >= 3.14) ''nf_tables_inet''.

These modules provide the corresponding [[Configuring_tables|table]] and the filter [[Configuring_chains|chain]] support for the given family.

You could also check which modules are supported by your current kernel. How to to do this, depends on your distro:
* on debian, look in /boot/config-XXX-YYY, where XXX is your kernel package version, and YYY is your arch, e.g. /boot/config-4.2.0-1-amd64
* on Arch, look in /proc/config.gz. As this is compressed, use a command such as zcat or zgrep.

In the debian example below, CONFIG_NFT_REDIR_IPV4 and CONFIG_NFT_REDIR_IPV6 are not set, so you can't use [http://wiki.nftables.org/wiki-nftables/index.php/Performing_Network_Address_Translation_(NAT)#Redirect redirect] in the ruleset:

<source lang="bash">
% grep CONFIG_NFT_ /boot/config-4.2.0-1-amd64
CONFIG_NFT_EXTHDR=m
CONFIG_NFT_META=m
CONFIG_NFT_CT=m
CONFIG_NFT_RBTREE=m
CONFIG_NFT_HASH=m
CONFIG_NFT_COUNTER=m
CONFIG_NFT_LOG=m
CONFIG_NFT_LIMIT=m
CONFIG_NFT_MASQ=m
CONFIG_NFT_REDIR=m
CONFIG_NFT_NAT=m
CONFIG_NFT_QUEUE=m
CONFIG_NFT_REJECT=m
CONFIG_NFT_REJECT_INET=m
CONFIG_NFT_COMPAT=m
CONFIG_NFT_CHAIN_ROUTE_IPV4=m
CONFIG_NFT_REJECT_IPV4=m
CONFIG_NFT_CHAIN_NAT_IPV4=m
CONFIG_NFT_MASQ_IPV4=m
# CONFIG_NFT_REDIR_IPV4 is not set
CONFIG_NFT_CHAIN_ROUTE_IPV6=m
CONFIG_NFT_REJECT_IPV6=m
CONFIG_NFT_CHAIN_NAT_IPV6=m
CONFIG_NFT_MASQ_IPV6=m
# CONFIG_NFT_REDIR_IPV6 is not set
CONFIG_NFT_BRIDGE_META=m
CONFIG_NFT_BRIDGE_REJECT=m
</source>

== Installing from git ==

This is slower as you will retrieve the Linux kernel git tree for nftables:

<source lang="bash">
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/pablo/nftables.git
</source>

After retrieving the git tree, you have to follow the same steps that described in the installation from sources.

But you will get the most recent changes for the ''nftables'' kernel code there.

When configuring the kernel, be sure to enable all the nftables modules (choose 'm' or 'y'). This is an example:

<source lang="bash">
$ make oldconfig

Netfilter Xtables support (required for ip_tables) (NETFILTER_XTABLES) [M/y/?] m
Netfilter nf_tables support (NF_TABLES) [N/m] (NEW) m
Netfilter nf_tables payload module (NFT_PAYLOAD) [N/m] (NEW) m
Netfilter nf_tables IPv6 exthdr module (NFT_EXTHDR) [N/m] (NEW) m
Netfilter nf_tables meta module (NFT_META) [N/m] (NEW) m
Netfilter nf_tables conntrack module (NFT_CT) [N/m] (NEW) m
Netfilter nf_tables rbtree set module (NFT_RBTREE) [N/m] (NEW) m
Netfilter nf_tables hash set module (NFT_HASH) [N/m] (NEW) m
Netfilter nf_tables counter module (NFT_COUNTER) [N/m] (NEW) m
Netfilter nf_tables log module (NFT_LOG) [N/m] (NEW) m
Netfilter nf_tables limit module (NFT_LIMIT) [N/m] (NEW) m
Netfilter nf_tables nat module (NFT_NAT) [N/m] (NEW) m
Netfilter x_tables over nf_tables module (NFT_COMPAT) [N/m/?] (NEW) m

IPv4 nf_tables support (NF_TABLES_IPV4) [N/m] (NEW) m
nf_tables IPv4 reject support (NFT_REJECT_IPV4) [N/m] (NEW) m
IPv4 nf_tables route chain support (NFT_CHAIN_ROUTE_IPV4) [N/m] (NEW) m
IPv4 nf_tables nat chain support (NFT_CHAIN_NAT_IPV4) [N/m] (NEW) m

IPv6 nf_tables support (NF_TABLES_IPV6) [M/n] m
IPv6 nf_tables route chain support (NFT_CHAIN_ROUTE_IPV6) [M/n] m
IPv6 nf_tables nat chain support (NFT_CHAIN_NAT_IPV6) [M/n] m

Ethernet Bridge nf_tables support (NF_TABLES_BRIDGE) [N/m/y] (NEW) m
</source>

Nftables families

2019-12-18T09:30:37Z

Arturo: /* netdev */ reword

nftables '''families''' are a new concept introduced with this technology which was previously missing in the iptables world.
You may already know that the nftables framework is designed to work with all typical address families (IPv4, IPv6, ARP).
In the past, all the families were handled by different tools: iptables, ip6tables, arptables, ebtables.

Please note that what traffic/packets you see and at which point in the network stack depends on the '''chain hook''' you are using.
You can create tables/chains/sets/rules in any family with the '''nft''' command line interface, out of the box, no need for different tools.
Additional families may be added in the future for extended nftables functionalities.

== ip ==

Tables of this family will see IPv4 traffic/packets.
The iptables tool was the equivalent in the old x_tables world.

== ip6 ==

Tables of this family will see IPv6 traffic/packets.
The ip6tables tool was the equivalent in the old x_tables world.

== inet ==

Tables of this family will see both IPv4/IPv6 traffic/packets, designed to improve dual stack support.
Mixing iptables and ip6tables rules in the same box was the equivalent in the old x_tables world.

Both IPv4/IPv6 packets will traverse the same rules. Rules for IPv4 packets won't affect IPv6 packets.
Rules for both L3 protocol will affect both.

Examples:
<source>
# this rule only affects IPv4 packets
add rule inet filter input ip saddr 1.1.1.1 counter accept
# this rule only affects IPv6 packets
add rule inet filter input ip6 daddr fe00::2 counter accept
# these rules affects both IPv4/IPv6 packets
add rule inet filter input ct state established,related counter accept
add rule inet filter input udp dport 53 accept
</source>

== arp ==

Tables of this family will see ARP-level (i.e, L2) traffic, before any L3 handling is done by the kernel.
The arptables tool was the equivalent in the old x_tables world.

== bridge ==

Tables of this family will see traffic/packets traversing bridges (i.e. switching). No assumptions are made about L3 protocols.
The ebtables tool was the equivalent in the old x_tables world.
Also, some old x_tables modules such as ''physdev'' will eventually be served natively from this family.

Note that there is no nf_conntrack integration for this family. However this may change in the future.

== netdev ==

This family provides the ingress hook, that allows you to classify packets that the driver has just passed up to the networking stack. This means you see '''all''' network traffic for your NIC getting in. No assumptions are made about L2 or L3 protocols, therefore you can filter ARP traffic from here.

Note that there is no equivalent in the old iptables world, this is a new feature available since Linux kernel 4.2 for nftables.

This location is ideal to drop packets that result from DDOS attacks given this is very early in the packet path. Dropping packets from here is much more efficient than from the classic prerouting chain, by a factor of 2x.

You can also use this new ingress hook for [[load balancing]], including Direct Server Return (DSR), [https://netdevconf.org/1.2/slides/oct6/08_nftables_Load_Balancing_with_nftables_II_Slides.pdf that has been reported to be 10x faster].

Matching packet metainformation

2019-12-17T09:59:16Z

Arturo: /* The meta selectors */ mention secpath in ipsec

The meta selectors allows you to match ([[Setting_packet_metainformation |and in some cases, set]]) packet metainformation.

= The meta selectors =

We have 2 types of meta statement, qualified and unqualified. Qualified ones require you use the '''meta''' keyword, and for unqualified ones it can be skipped.

* qualified meta statements:
** length -- packet lenght
** protocol -- packet protocol (as in skb->protocol)
** nfproto -- netfilter packet protocol family (like ipv4, ipv6, etc..).
** l4proto -- layer 4 protocol (tcp, udp, etc..)
** priority -- packet priority, tc handle. [[Setting_packet_metainformation |Can be set]].
** random -- match against a single/simple random number
** secmark -- packet secmark. [[Setting_packet_metainformation |Can be set]].
** ibrvproto -- match the bridge protocol
** ibrpvid -- match the bridge pvid

* unqualified meta statements:
** mark -- packet mark. [[Setting_packet_metainformation |Can be set]].
** iif -- input interface index
** iifname -- input interface name
** iiftype -- input interface type
** oif -- output interface index
** oifname -- output interface name
** oiftype -- output interface type
** skuid -- socket uid
** skgid -- socket gid
** nftrace -- [[Ruleset_debug/tracing|nftrace debugging]] bit. [[Setting_packet_metainformation |Can be set]].
** rtclassid -- realm
** ibriport -- input bridge port
** obriport -- output bridge port
** ibridgename -- input bridge name
** obridgename -- output bridge name
** pkttype -- packet type. [[Setting_packet_metainformation |Can be set]].
** cpu -- cpu number
** iifgroup -- input interface group
** oifgroup -- output interface group
** cgroup -- cgroup number
** ipsec -- ipsec (secpath) packet or not
** time -- packet timestamp
** day -- packet timestamp
** hour -- packet timestamp

= Matching packets by interface name =

You can use one of the following selectors to match the interface name:

* ''iifname'', to match the input network interface name.
* ''oifname'', to match the output network interface name.
* ''iif'', to match the interface index of the network interface name. This is faster than ''iifname'' as it only has to compare a 32-bits unsigned integer instead of a string. The interface index is dynamically allocated, so don't use this for interfaces that are dynamically created and destroyed, eg. ''ppp0''.
* ''oif'', like ''iif'' but it matches the output network interface index.

An example usage of the interface name is the following:

<source lang="bash">
% nft add rule filter input meta oifname lo accept
</source>

This rule accepts all traffic for the loopback pseudodevice ''lo''.

= Matching packets by packet mark =

You can match packets whose mark is 123 with the following rule:

<source lang="bash">
nft add rule filter output meta mark 123 counter
</source>

= Matching packets the socket UID =

You can use your user name to match traffic, eg.

<source lang="bash">
% nft add rule filter output meta skuid pablo counter
</source>

Or the 32-bits unsigned integer (UID) in case there is no entry in /etc/passwd for a given user.

<source lang="bash">
% nft add rule filter output meta skuid 1000 counter
</source>

Let's just generate some HTTP traffic to test this rule:

<source lang="bash">
% wget --spider http://www.google.com
</source>

Then, if you check the counters, you can verify that the packets are matching that rule.

<source lang="bash">
% nft list table filter
table ip filter {
chain output {
type filter hook output priority 0;
skuid pablo counter packets 7 bytes 510
}

chain input {
type filter hook input priority 0;
}
}
</source>

'''Important''': Beware if you test this with ''ping'', it is usually installed with suid so that traffic will match the root user (uid=0).

= Matching packet priority =

* Since nftables v0.7 you can match the packet priority, the tc classid:

<source>
% nft add rule filter forward meta priority abcd:1234
</source>

* Packet without set priority can be matched using meta priority none
<source>
% nft add rule filter forward meta priority none
</source>

Setting packet metainformation

2019-12-17T09:45:40Z

Arturo: add nftrace wiki link

You can set some [[Matching_packet_metainformation |metainformation]] in a packet. Current supported options are:
* mark -- packet mark
* priority -- packet priority
* nftrace -- [[Ruleset_debug/tracing|nftrace debugging]] bit
* pkttype -- packet type
* secmark -- packet secmark

Please note that you require a Linux kernel >= 3.14 to use these features.

== mark ==
The following example shows how to set the packet mark:

<source lang="bash">
% nft add rule route output mark set 123
</source>

== mark and conntrack mark ==

You can save/restore conntrack mark like in iptables.

In this example, the nf_tables engine set the packet mark to 1.
In the last rule, that mark is store in the conntrack entry associated with the flow:

<source lang="bash">
% nft add rule filter forward meta mark set 1
% nft add rule filter forward ct mark set mark
</source>

In this example, the conntrack mark is stored in the packet.
<source lang="bash">
% nft add rule filter forward meta mark set ct mark
</source>

== priority ==
You can set the priority of a packet.

This example shows a similar operation to what "-j CLASSIFY" does in iptables:

<source lang="bash">
% nft add table mangle
% nft add chain postrouting {type route hook output priority -150\; }
% nft add rule mangle postrouting tcp sport 80 meta priority set 1
</source>

'''Warning''': There is a bug in the priority syntax that will be fixed in following versions of nftables.

== nftrace ==

Setting nftrace in a packet will report the journey through the nf_tables stack.

<source lang="bash">
% nft add rule filter forward udp dport 53 meta nftrace set 1
</source>

== combination of options ==

Given the flexible design of nftables, remember you can perform several actions to a packet in one rule:

<source lang="bash">
% nft add rule filter forward ip saddr 192.168.1.1 meta nftrace set 1 meta priority set 2 meta mark set 123
</source>

Matching packet metainformation

2019-12-17T09:45:02Z

Arturo: /* The meta selectors */ add wiki link to nftrace

The meta selectors allows you to match ([[Setting_packet_metainformation |and in some cases, set]]) packet metainformation.

= The meta selectors =

We have 2 types of meta statement, qualified and unqualified. Qualified ones require you use the '''meta''' keyword, and for unqualified ones it can be skipped.

* qualified meta statements:
** length -- packet lenght
** protocol -- packet protocol (as in skb->protocol)
** nfproto -- netfilter packet protocol family (like ipv4, ipv6, etc..).
** l4proto -- layer 4 protocol (tcp, udp, etc..)
** priority -- packet priority, tc handle. [[Setting_packet_metainformation |Can be set]].
** random -- match against a single/simple random number
** secmark -- packet secmark. [[Setting_packet_metainformation |Can be set]].
** ibrvproto -- match the bridge protocol
** ibrpvid -- match the bridge pvid

* unqualified meta statements:
** mark -- packet mark. [[Setting_packet_metainformation |Can be set]].
** iif -- input interface index
** iifname -- input interface name
** iiftype -- input interface type
** oif -- output interface index
** oifname -- output interface name
** oiftype -- output interface type
** skuid -- socket uid
** skgid -- socket gid
** nftrace -- [[Ruleset_debug/tracing|nftrace debugging]] bit. [[Setting_packet_metainformation |Can be set]].
** rtclassid -- realm
** ibriport -- input bridge port
** obriport -- output bridge port
** ibridgename -- input bridge name
** obridgename -- output bridge name
** pkttype -- packet type. [[Setting_packet_metainformation |Can be set]].
** cpu -- cpu number
** iifgroup -- input interface group
** oifgroup -- output interface group
** cgroup -- cgroup number
** ipsec -- ipsec packet or not
** time -- packet timestamp
** day -- packet timestamp
** hour -- packet timestamp

= Matching packets by interface name =

You can use one of the following selectors to match the interface name:

* ''iifname'', to match the input network interface name.
* ''oifname'', to match the output network interface name.
* ''iif'', to match the interface index of the network interface name. This is faster than ''iifname'' as it only has to compare a 32-bits unsigned integer instead of a string. The interface index is dynamically allocated, so don't use this for interfaces that are dynamically created and destroyed, eg. ''ppp0''.
* ''oif'', like ''iif'' but it matches the output network interface index.

An example usage of the interface name is the following:

<source lang="bash">
% nft add rule filter input meta oifname lo accept
</source>

This rule accepts all traffic for the loopback pseudodevice ''lo''.

= Matching packets by packet mark =

You can match packets whose mark is 123 with the following rule:

<source lang="bash">
nft add rule filter output meta mark 123 counter
</source>

= Matching packets the socket UID =

You can use your user name to match traffic, eg.

<source lang="bash">
% nft add rule filter output meta skuid pablo counter
</source>

Or the 32-bits unsigned integer (UID) in case there is no entry in /etc/passwd for a given user.

<source lang="bash">
% nft add rule filter output meta skuid 1000 counter
</source>

Let's just generate some HTTP traffic to test this rule:

<source lang="bash">
% wget --spider http://www.google.com
</source>

Then, if you check the counters, you can verify that the packets are matching that rule.

<source lang="bash">
% nft list table filter
table ip filter {
chain output {
type filter hook output priority 0;
skuid pablo counter packets 7 bytes 510
}

chain input {
type filter hook input priority 0;
}
}
</source>

'''Important''': Beware if you test this with ''ping'', it is usually installed with suid so that traffic will match the root user (uid=0).

= Matching packet priority =

* Since nftables v0.7 you can match the packet priority, the tc classid:

<source>
% nft add rule filter forward meta priority abcd:1234
</source>

* Packet without set priority can be matched using meta priority none
<source>
% nft add rule filter forward meta priority none
</source>

Setting packet metainformation

2019-12-17T09:43:57Z

Arturo: refresh introductory paragraph

You can set some [[Matching_packet_metainformation |metainformation]] in a packet. Current supported options are:
* mark -- packet mark
* priority -- packet priority
* nftrace -- nftrace debugging bit
* pkttype -- packet type
* secmark -- packet secmark

Please note that you require a Linux kernel >= 3.14 to use these features.

== mark ==
The following example shows how to set the packet mark:

<source lang="bash">
% nft add rule route output mark set 123
</source>

== mark and conntrack mark ==

You can save/restore conntrack mark like in iptables.

In this example, the nf_tables engine set the packet mark to 1.
In the last rule, that mark is store in the conntrack entry associated with the flow:

<source lang="bash">
% nft add rule filter forward meta mark set 1
% nft add rule filter forward ct mark set mark
</source>

In this example, the conntrack mark is stored in the packet.
<source lang="bash">
% nft add rule filter forward meta mark set ct mark
</source>

== priority ==
You can set the priority of a packet.

This example shows a similar operation to what "-j CLASSIFY" does in iptables:

<source lang="bash">
% nft add table mangle
% nft add chain postrouting {type route hook output priority -150\; }
% nft add rule mangle postrouting tcp sport 80 meta priority set 1
</source>

'''Warning''': There is a bug in the priority syntax that will be fixed in following versions of nftables.

== nftrace ==

Setting nftrace in a packet will report the journey through the nf_tables stack.

<source lang="bash">
% nft add rule filter forward udp dport 53 meta nftrace set 1
</source>

== combination of options ==

Given the flexible design of nftables, remember you can perform several actions to a packet in one rule:

<source lang="bash">
% nft add rule filter forward ip saddr 192.168.1.1 meta nftrace set 1 meta priority set 2 meta mark set 123
</source>

Matching packet metainformation

2019-12-17T09:41:19Z

Arturo: add a couple more datatypes

The meta selectors allows you to match ([[Setting_packet_metainformation |and in some cases, set]]) packet metainformation.

= The meta selectors =

We have 2 types of meta statement, qualified and unqualified. Qualified ones require you use the '''meta''' keyword, and for unqualified ones it can be skipped.

* qualified meta statements:
** length -- packet lenght
** protocol -- packet protocol (as in skb->protocol)
** nfproto -- netfilter packet protocol family (like ipv4, ipv6, etc..).
** l4proto -- layer 4 protocol (tcp, udp, etc..)
** priority -- packet priority, tc handle. [[Setting_packet_metainformation |Can be set]].
** random -- match against a single/simple random number
** secmark -- packet secmark. [[Setting_packet_metainformation |Can be set]].
** ibrvproto -- match the bridge protocol
** ibrpvid -- match the bridge pvid

* unqualified meta statements:
** mark -- packet mark. [[Setting_packet_metainformation |Can be set]].
** iif -- input interface index
** iifname -- input interface name
** iiftype -- input interface type
** oif -- output interface index
** oifname -- output interface name
** oiftype -- output interface type
** skuid -- socket uid
** skgid -- socket gid
** nftrace -- nftrace debugging bit. [[Setting_packet_metainformation |Can be set]].
** rtclassid -- realm
** ibriport -- input bridge port
** obriport -- output bridge port
** ibridgename -- input bridge name
** obridgename -- output bridge name
** pkttype -- packet type. [[Setting_packet_metainformation |Can be set]].
** cpu -- cpu number
** iifgroup -- input interface group
** oifgroup -- output interface group
** cgroup -- cgroup number
** ipsec -- ipsec packet or not
** time -- packet timestamp
** day -- packet timestamp
** hour -- packet timestamp

= Matching packets by interface name =

You can use one of the following selectors to match the interface name:

* ''iifname'', to match the input network interface name.
* ''oifname'', to match the output network interface name.
* ''iif'', to match the interface index of the network interface name. This is faster than ''iifname'' as it only has to compare a 32-bits unsigned integer instead of a string. The interface index is dynamically allocated, so don't use this for interfaces that are dynamically created and destroyed, eg. ''ppp0''.
* ''oif'', like ''iif'' but it matches the output network interface index.

An example usage of the interface name is the following:

<source lang="bash">
% nft add rule filter input meta oifname lo accept
</source>

This rule accepts all traffic for the loopback pseudodevice ''lo''.

= Matching packets by packet mark =

You can match packets whose mark is 123 with the following rule:

<source lang="bash">
nft add rule filter output meta mark 123 counter
</source>

= Matching packets the socket UID =

You can use your user name to match traffic, eg.

<source lang="bash">
% nft add rule filter output meta skuid pablo counter
</source>

Or the 32-bits unsigned integer (UID) in case there is no entry in /etc/passwd for a given user.

<source lang="bash">
% nft add rule filter output meta skuid 1000 counter
</source>

Let's just generate some HTTP traffic to test this rule:

<source lang="bash">
% wget --spider http://www.google.com
</source>

Then, if you check the counters, you can verify that the packets are matching that rule.

<source lang="bash">
% nft list table filter
table ip filter {
chain output {
type filter hook output priority 0;
skuid pablo counter packets 7 bytes 510
}

chain input {
type filter hook input priority 0;
}
}
</source>

'''Important''': Beware if you test this with ''ping'', it is usually installed with suid so that traffic will match the root user (uid=0).

= Matching packet priority =

* Since nftables v0.7 you can match the packet priority, the tc classid:

<source>
% nft add rule filter forward meta priority abcd:1234
</source>

* Packet without set priority can be matched using meta priority none
<source>
% nft add rule filter forward meta priority none
</source>

Matching packet metainformation

2019-12-17T09:36:42Z

Arturo: refresh layout of the page

The meta selectors allows you to match ([[Setting_packet_metainformation |and in some cases, set]]) packet metainformation.

= The meta selectors =

We have 2 types of meta statement, qualified and unqualified. Qualified ones require you use the '''meta''' keyword, and for unqualified ones it can be skipped.

* qualified meta statements:
** length -- packet lenght
** protocol -- packet protocol
** priority -- packet priority, tc handle. [[Setting_packet_metainformation |Can be set]].
** random -- match against a single/simple random number
** secmark -- packet secmark. [[Setting_packet_metainformation |Can be set]].

* unqualified meta statements:
** mark -- packet mark. [[Setting_packet_metainformation |Can be set]].
** iif -- input interface index
** iifname -- input interface name
** iiftype -- input interface type
** oif -- output interface index
** oifname -- output interface name
** oiftype -- output interface type
** skuid -- socket uid
** skgid -- socket gid
** nftrace -- nftrace debugging bit. [[Setting_packet_metainformation |Can be set]].
** rtclassid -- realm
** ibriport -- input bridge port
** obriport -- output bridge port
** ibridgename -- input bridge name
** obridgename -- output bridge name
** pkttype -- packet type. [[Setting_packet_metainformation |Can be set]].
** cpu -- cpu number
** iifgroup -- input interface group
** oifgroup -- output interface group
** cgroup -- cgroup number
** ipsec -- ipsec packet or not
** time -- packet timestamp
** day -- packet timestamp
** hour -- packet timestamp

= Matching packets by interface name =

You can use one of the following selectors to match the interface name:

* ''iifname'', to match the input network interface name.
* ''oifname'', to match the output network interface name.
* ''iif'', to match the interface index of the network interface name. This is faster than ''iifname'' as it only has to compare a 32-bits unsigned integer instead of a string. The interface index is dynamically allocated, so don't use this for interfaces that are dynamically created and destroyed, eg. ''ppp0''.
* ''oif'', like ''iif'' but it matches the output network interface index.

An example usage of the interface name is the following:

<source lang="bash">
% nft add rule filter input meta oifname lo accept
</source>

This rule accepts all traffic for the loopback pseudodevice ''lo''.

= Matching packets by packet mark =

You can match packets whose mark is 123 with the following rule:

<source lang="bash">
nft add rule filter output meta mark 123 counter
</source>

= Matching packets the socket UID =

You can use your user name to match traffic, eg.

<source lang="bash">
% nft add rule filter output meta skuid pablo counter
</source>

Or the 32-bits unsigned integer (UID) in case there is no entry in /etc/passwd for a given user.

<source lang="bash">
% nft add rule filter output meta skuid 1000 counter
</source>

Let's just generate some HTTP traffic to test this rule:

<source lang="bash">
% wget --spider http://www.google.com
</source>

Then, if you check the counters, you can verify that the packets are matching that rule.

<source lang="bash">
% nft list table filter
table ip filter {
chain output {
type filter hook output priority 0;
skuid pablo counter packets 7 bytes 510
}

chain input {
type filter hook input priority 0;
}
}
</source>

'''Important''': Beware if you test this with ''ping'', it is usually installed with suid so that traffic will match the root user (uid=0).

= Matching packet priority =

* Since nftables v0.7 you can match the packet priority, the tc classid:

<source>
% nft add rule filter forward meta priority abcd:1234
</source>

* Packet without set priority can be matched using meta priority none
<source>
% nft add rule filter forward meta priority none
</source>

Matching packet metainformation

2019-12-17T09:27:20Z

Arturo: /* The meta selectors */ refresh selectors, mention unqualified/qualified ones

''nftables'' comes with the packet metainformation selectors that you can use to match information that is stored in the network packet.

= The meta selectors =

The meta selectors allows you to match ([[Setting_packet_metainformation |and in some cases, set]]) packet metainformation.

We have 2 types of meta statement, qualified and unqualified. Qualified ones require you use the '''meta''' keyword, and for unqualified ones it can be skipped.

* qualified meta statements:
** length -- packet lenght
** protocol -- packet protocol
** priority -- packet priority, tc handle. [[Setting_packet_metainformation |Can be set]].
** random -- match against a single/simple random number
** secmark -- packet secmark. [[Setting_packet_metainformation |Can be set]].

* unqualified meta statements:
** mark -- packet mark. [[Setting_packet_metainformation |Can be set]].
** iif -- input interface index
** iifname -- input interface name
** iiftype -- input interface type
** oif -- output interface index
** oifname -- output interface name
** oiftype -- output interface type
** skuid -- socket uid
** skgid -- socket gid
** nftrace -- nftrace debugging bit. [[Setting_packet_metainformation |Can be set]].
** rtclassid -- realm
** ibriport -- input bridge port
** obriport -- output bridge port
** ibridgename -- input bridge name
** obridgename -- output bridge name
** pkttype -- packet type. [[Setting_packet_metainformation |Can be set]].
** cpu -- cpu number
** iifgroup -- input interface group
** oifgroup -- output interface group
** cgroup -- cgroup number
** ipsec -- ipsec packet or not
** time -- packet timestamp
** day -- packet timestamp
** hour -- packet timestamp

== Matching packets by interface name ==

You can use one of the following selectors to match the interface name:

* ''iifname'', to match the input network interface name.
* ''oifname'', to match the output network interface name.
* ''iif'', to match the interface index of the network interface name. This is faster than ''iifname'' as it only has to compare a 32-bits unsigned integer instead of a string. The interface index is dynamically allocated, so don't use this for interfaces that are dynamically created and destroyed, eg. ''ppp0''.
* ''oif'', like ''iif'' but it matches the output network interface index.

An example usage of the interface name is the following:

<source lang="bash">
% nft add rule filter input meta oifname lo accept
</source>

This rule accepts all traffic for the loopback pseudodevice ''lo''.

== Matching packets by packet mark ==

You can match packets whose mark is 123 with the following rule:

<source lang="bash">
nft add rule filter output meta mark 123 counter
</source>

== Matching packets the socket UID ==

You can use your user name to match traffic, eg.

<source lang="bash">
% nft add rule filter output meta skuid pablo counter
</source>

Or the 32-bits unsigned integer (UID) in case there is no entry in /etc/passwd for a given user.

<source lang="bash">
% nft add rule filter output meta skuid 1000 counter
</source>

Let's just generate some HTTP traffic to test this rule:

<source lang="bash">
% wget --spider http://www.google.com
</source>

Then, if you check the counters, you can verify that the packets are matching that rule.

<source lang="bash">
% nft list table filter
table ip filter {
chain output {
type filter hook output priority 0;
skuid pablo counter packets 7 bytes 510
}

chain input {
type filter hook input priority 0;
}
}
</source>

'''Important''': Beware if you test this with ''ping'', it is usually installed with suid so that traffic will match the root user (uid=0).

== Matching packet priority ==

* Since nftables v0.7 you can match the packet priority, the tc classid:

<source>
% nft add rule filter forward meta priority abcd:1234
</source>

* Packet without set priority can be matched using meta priority none
<source>
% nft add rule filter forward meta priority none
</source>

Load balancing

2019-11-27T14:37:56Z

Arturo: /* Round Robin */ mod 100

Since nftables v0.7, there is support in place to perform [[Performing Network Address Translation (NAT) | NAT]] load balancing.

Don't forget the special NAT chain semantics: Only the first packet evaluates the rule, follow up packets rely on conntrack to apply the NAT information.

== Round Robin ==

This method uses the nftables [[Math operations | number generator]].

The example below is distributing new connections in a round-robin fashion between 192.168.10.100 and 192.168.20.200.

<source>
% nft add rule nat prerouting dnat to numgen inc mod 2 map { \
0 : 192.168.10.100, \
1 : 192.168.20.200 }
</source>

You can also emulate flow distribution with different backend weights using intervals:

<source>
% nft add rule nat prerouting dnat to numgen inc mod 10 map { \
0-5 : 192.168.10.100, \
6-9 : 192.168.20.200 }
</source>

The distribution can be based on ports as well:

<source>
% nft add rule nat prerouting ip protocol tcp dnat to 192.168.1.100 : numgen inc mod 2 map {\
0 : 4040 ,\
1 : 4050 }
</source>

Support for random and probability-based distributions also exists:

<source>
% nft add rule nat prerouting numgen random mod 2 vmap { 0 : jump mychain1, 1 : jump mychain2 }
% nft add rule nat prerouting numgen random mod 100 vmap { 0-49 : jump mychain1, 50-99 : jump mychain2 }
</source>

== Consistent Hash-based Distribution ==

Using the nftables internal [[Math operations | hashing mechanisms]].

<source>
% nft add rule x y dnat to jhash ip saddr . tcp dport mod 2 map { \
0 : 192.168.20.100, \
1 : 192.168.30.100 }
</source>

This relies on the Jenkins hash.

== Using stateless NAT ==

You can perform load balancing through stateless NAT approach as well. You can combine this either with the round robin and consistent hash-based distribution approaches.

The example below uses Round Robin flow distribution:

<source>
% nft add rule t c tcp dport 80 ip daddr set numgen inc mod 2 map { 0 : 192.168.1.100, 1 : 192.168.1.101 }
</source>

This is more lightweight that stateful NAT given there is no flow tracking in place. This is indeed [[Mangle packet header fields | mangling packet header fields]].

== Using Direct Server Return (DSR) ==

This example performs a DSR topology for connectionless flows from ingress:

<source>
% nft add rule netdev t c udp dport 53 ether saddr set aa:bb:cc:dd:ff:ee ether daddr set numgen inc mod 2 map { 0 : xx:xx:xx:xx:xx:xx, 1: yy:yy:yy:yy:yy:yy } fwd to eth0
</source>

An approach for connection oriented flows can be performed as shown below:

<source>
% nft add rule netdev t c tcp dport 80 ether saddr set aa:bb:cc:dd:ff:ee ether daddr set jhash ip saddr . tcp sport mod 2 map { 0 : xx:xx:xx:xx:xx:xx, 1: yy:yy:yy:yy:yy:yy } fwd to eth0
</source>

Note that xx:xx:xx:xx:xx:xx and yy:yy:yy:yy:yy:yy need to be replaced by the real destination MAC address.
This is [[Mangle packet header fields | mangling packet header fields]] as well.

Load balancing

2019-11-27T09:58:23Z

Arturo: /* Round Robin */ add example using random and probability

Since nftables v0.7, there is support in place to perform [[Performing Network Address Translation (NAT) | NAT]] load balancing.

Don't forget the special NAT chain semantics: Only the first packet evaluates the rule, follow up packets rely on conntrack to apply the NAT information.

== Round Robin ==

This method uses the nftables [[Math operations | number generator]].

The example below is distributing new connections in a round-robin fashion between 192.168.10.100 and 192.168.20.200.

<source>
% nft add rule nat prerouting dnat to numgen inc mod 2 map { \
0 : 192.168.10.100, \
1 : 192.168.20.200 }
</source>

You can also emulate flow distribution with different backend weights using intervals:

<source>
% nft add rule nat prerouting dnat to numgen inc mod 10 map { \
0-5 : 192.168.10.100, \
6-9 : 192.168.20.200 }
</source>

The distribution can be based on ports as well:

<source>
% nft add rule nat prerouting ip protocol tcp dnat to 192.168.1.100 : numgen inc mod 2 map {\
0 : 4040 ,\
1 : 4050 }
</source>

Support for random and probability-based distributions also exists:

<source>
% nft add rule nat prerouting numgen random mod 2 vmap { 0 : jump mychain1, 1 : jump mychain2 }
% nft add rule nat prerouting numgen random mod 99 vmap { 0-49 : jump mychain1, 50-99 : jump mychain2 }
</source>

== Consistent Hash-based Distribution ==

Using the nftables internal [[Math operations | hashing mechanisms]].

<source>
% nft add rule x y dnat to jhash ip saddr . tcp dport mod 2 map { \
0 : 192.168.20.100, \
1 : 192.168.30.100 }
</source>

This relies on the Jenkins hash.

== Using stateless NAT ==

You can perform load balancing through stateless NAT approach as well. You can combine this either with the round robin and consistent hash-based distribution approaches.

The example below uses Round Robin flow distribution:

<source>
% nft add rule t c tcp dport 80 ip daddr set numgen inc mod 2 map { 0 : 192.168.1.100, 1 : 192.168.1.101 }
</source>

This is more lightweight that stateful NAT given there is no flow tracking in place. This is indeed [[Mangle packet header fields | mangling packet header fields]].

== Using Direct Server Return (DSR) ==

This example performs a DSR topology for connectionless flows from ingress:

<source>
% nft add rule netdev t c udp dport 53 ether saddr set aa:bb:cc:dd:ff:ee ether daddr set numgen inc mod 2 map { 0 : xx:xx:xx:xx:xx:xx, 1: yy:yy:yy:yy:yy:yy } fwd to eth0
</source>

An approach for connection oriented flows can be performed as shown below:

<source>
% nft add rule netdev t c tcp dport 80 ether saddr set aa:bb:cc:dd:ff:ee ether daddr set jhash ip saddr . tcp sport mod 2 map { 0 : xx:xx:xx:xx:xx:xx, 1: yy:yy:yy:yy:yy:yy } fwd to eth0
</source>

Note that xx:xx:xx:xx:xx:xx and yy:yy:yy:yy:yy:yy need to be replaced by the real destination MAC address.
This is [[Mangle packet header fields | mangling packet header fields]] as well.

Verdict Maps (vmaps)

2019-11-04T14:06:34Z

Arturo: /* Literal dictionaries */ drop unrelated example line

The ''dictionaries'', also known as ''verdict maps'', are one of the most interesting features available in ''nftables''. Basically, they allow you to attach an action to an element. Dictionaries internally use the generic set infrastructure.

= Literal dictionaries =

The following example shows how to create a tree of chains that whose traversal depends on the layer 4 protocol type:

<source lang="bash">
% nft add rule ip filter input ip protocol vmap { tcp : jump tcp-chain, udp : jump udp-chain , icmp : jump icmp-chain }
</source>

This example above assumes that you've already created the ''tcp-chain'', ''udp-chain'' and ''icmp-chain'' [[Configuring chains|custom chains]]. Then, by attaching simple rules to account the traffic, ie.

<source lang="bash">
% nft add rule filter icmp-chain counter
% nft add rule filter tcp-chain counter
% nft add rule filter udp-chain counter
</source>

You can check that the classification is already happening:

<source lang="bash">
% nft list table filter
table ip filter {
chain input {
type filter hook input priority 0;
ip protocol vmap { udp : jump udp-chain, tcp : jump tcp-chain, icmp : jump icmp-chain}
}

chain tcp-chain {
counter packets 4 bytes 520
}

chain udp-chain {
counter packets 4 bytes 678
}

chain icmp-chain {
counter packets 4 bytes 336
}
}
</source>

As you probably already noticed, one of the the good things of nftables is that you can use ''dictionaries'' to construct performance rule-sets. This rule-set arrangement allows you to reduce the amount of linear list inspections to classify your packets.

= Dictionary declarations =

You can also declarate dictionaries and populate its content dynamically, for example:

<source lang="bash">
% nft add map filter mydict { type ipv4_addr : verdict\; }
</source>

Then, you can add elements:

<source lang="bash">
% nft add element filter mydict { 192.168.0.10 : drop, 192.168.0.11 : accept }
</source>

You can bind this set to a rule using the following command:

<source lang="bash">
% nft add rule filter input ip saddr vmap @mydict
</source>

In case you want to build your own dictionary, but you don't know what is the datatype name. Remember that you can inquire ''nft'' to know the datatype name:

<source lang="bash">
% nft describe tcp dport
payload expression, datatype inet_service (internet network service) (basetype integer), 16 bits
</source>

See the ''inet_service'' string after datatype.

Sets

2019-11-04T11:41:11Z

Arturo: /* Named sets specifications */ add ifname

Meters

2019-10-30T10:56:50Z

Arturo: /* Meters */ refresh paragraph

== Meters ==

'''Dynamic sets/maps''' or meters are a way to use maps with stateful objects. They used to be known as ''flow tables'' before nft v0.8.1 and Linux kernel 4.3.

Among other things, they provide a native replacement for the ''hashlimit'' match in iptables. However, meters are a lot more flexible since you can use any selector, one or many through [[concatenations]].

'''Note that the ''meter'' keyword is obsolete, the dynamic set and map syntax is now preferred for consistency.'''

== Using meters ==

The following commands create a table named ''my_filter_table'', a chain named ''my_input_chain'' which hooks incoming traffic and a rule that uses a meter:

<source lang="bash">
% nft add table my_filter_table
% nft add chain my_filter_table my_input_chain {type filter hook input priority 0\;}
% nft add set my_filter_table my_ssh_meter { type ipv4_addr\; flags dynamic \;}
% nft add rule my_filter_table my_input_chain tcp dport 22 ct state new add @my_ssh_meter { ip saddr limit rate 10/second } accept
</source>

In this example we create a rule to match ''new'' TCP ''ssh'' (port 22) connections, which uses a dynamic set named ''my_ssh_meter'' to limit the traffic rate to 10 connections per second for each source IP address. The available time units on limits are: ''second'', ''minute'', ''hour'', ''day'' and ''week''.

You can also use [[concatenations]] to build selectors:

<source lang="bash">
% nft add set my_filter_table my_ssh_meter { type ipv4_addr . inet_service\; flags timeout, dynamic \;}
% nft add rule my_filter_table my_input_chain tcp dport 22 ct state new add @my_ssh_meter { ip saddr . tcp dport timeout 60s limit rate 10/second } accept
</source>

This rule counts incoming connections (packets with state ''new'') based on the tuple ''(IP source address, TCP destination port)'', the counters are dropped after 60 seconds without update.

== Listing meters ==

To list the content matched by the meter use:

<source lang="bash">
% nft list map my_filter_table my_ssh_meter
table ip my_filter_table {
map my_ssh_meter {
type ipv4_addr . inet_service
size 65535
flags dynamic,timeout
elements = { 64.62.190.36 . 55000 expires 38s : counter packets 2 bytes 220, 83.98.201.47 . 35460 expires 39s : counter packets 10 bytes 5988, 172.217.7.142 . 43254 expires 46s : counter packets 1 bytes 98}
}
}
</source>

== Doing connlimit with nft ==

Since 4.18, there is a new ''ct count'' selector that allows you to count the number of existing connections. This extension uses the information available in the Connection Tracking System table, therefore, the counting of connection is based on the existing entries in the table.

The following example shows how to do ''connlimit'' from nftables:

table ip my_filter_table {
set my_connlimit {
type ipv4_addr
size 65535
flags dynamic
}

chain my_output_chain {
type filter hook output priority filter; policy accept;
ct state new add @my_connlimit { ip daddr ct count over 20 } counter packets 0 bytes 0 drop
}
}

The example above dynamically populates the set ''connlimit'' from the packet path. For the first packet of each connection (ie. packets matching ''ct state new''), this adds an entry into ''connlimit'' set, this entry uses the IPv4 destination address as a key. If the number of connections goes over 20, then packets are dropped.

Since ''connlimit'' is a set, you can perform any operation on it, such as listing and flushing its content.

== Doing iptables hashlimit with nft ==

Meters replace iptables hashlimit in nft. From iptables v1.6.2 onward, you can use the tool '''iptables-translate''' to see how to translate hashlimit rules.

Almost all hashlimit options are available in nft, starting with --hashlimit-mode, it is replaced by the selector in a meter. All modes are available except no mode, a meter demands a selector, an iptables rule without hashlimit-mode isn't supported in nft. A simple rule translation is:

<source lang="bash">
$ iptables-translate -A INPUT -m tcp -p tcp --dport 80 -m hashlimit --hashlimit-above 200/sec --hashlimit-mode srcip,dstport --hashlimit-name http1 -j DROP
nft add rule ip filter INPUT tcp dport 80 meter http1 { tcp dport . ip saddr limit rate over 200/second } counter drop
</source>

Notice that a meter is named, like hashlimit, and using multiple hashlimit-modes is similar to using a concatenation of selectors. Also, --hashlimit-above is translated to ''limit rate over'', to simulate --hashlimit-upto just omit or replace ''over'' with ''until'' in the rule.

The options --hashlimit-burst and --hashlimit-htable-expire are translated to ''burst'' and ''timeout'' in a meter:

<source lang="bash">
$ iptables-translate -A INPUT -m tcp -p tcp --dport 80 -m hashlimit --hashlimit-above 200kb/s --hashlimit-burst 1mb --hashlimit-mode srcip,dstport --hashlimit-name http2 --hashlimit-htable-expire 3000 -j DROP
nft add rule ip filter INPUT tcp dport 80 meter http2 { tcp dport . ip saddr timeout 3s limit rate over 200 kbytes/second burst 1 mbytes} counter drop
</source>

This rule shows how ''timeout'' and ''burst'' are used in a meter, also notice that meters, similarly to hashlimit, accepts limiting rates by bytes frequency instead of packets.

Another hashlimit option is to limit the traffic rate on subnets, of IP source or destination addresses, using the options --hashlimit-srcmask and --hashlimit-dstmask. This feature is available in nft by attaching a subnet mask to a meter selector, attach to ''ip saddr'' for source address and to ''ip daddr'' for destination adress:

<source lang="bash">
$ iptables-translate -A INPUT -m tcp -p tcp --dport 80 -m hashlimit --hashlimit-upto 200 --hashlimit-mode srcip --hashlimit-name http3 --hashlimit-srcmask 24 -j DROP
nft add rule ip filter INPUT tcp dport 80 meter http3 { ip saddr and 255.255.255.0 limit rate 200/second } counter drop
</source>

This rule will limit packets rate, grouping subnets determined by the first 24 bits of the IP source address, from the incoming packets on port 80.

The remaining options, --hashlimit-htable-max, --hashlimit-htable-size and --hashlimit-htable-gcinterval don't apply to meters.

Concatenations

2019-10-30T10:46:57Z

Arturo: /* Some ipset types */ refactor examples into the moving from ipset to nftables page

Since Linux kernel 4.1, nftables supports concatenations.

This new feature allows you to put two or more selectors together to perform very fast lookups by combining them with [[sets]], [[dictionaries]], [[maps]] and [[meters]].

= Literal sets =

<source lang="bash">
% nft add rule ip filter input ip saddr . ip daddr . ip protocol { 1.1.1.1 . 2.2.2.2 . tcp, 1.1.1.1 . 3.3.3.3 . udp} counter accept
</source>

So if the packet's source IP address AND destination IP address AND level 4 protocol match:

* 1.1.1.1 and 2.2.2.2 and TCP.

or

* 1.1.1.1 and 3.3.3.3 and UDP.

nftables updates the counter for this rule and then accepts the packet.

= Dictionary declarations =

The following example creates the ''whitelist'' dictionary using a concatenation of two selectors:

<source lang="bash">
% nft add map filter whitelist { type ipv4_addr . inet_service : verdict \; }
</source>

Once you create the dictionary, you can use it from a rule that creates the following concatenation:

<source lang="bash">
% nft add rule filter input ip saddr . tcp dport vmap @whitelist
</source>

Thus, the rule above looks up for a verdict based on the source IP address AND the TCP destination port.

Since the dictionary is initially empty, you can dynamically populate this dictionary with elements through:

<source lang="bash">
% nft add element filter whitelist { 1.2.3.4 . 22 : accept}
</source>

= Literal maps =

The rule below determines the destination IP address that is used to perform DNAT to the packet based on:

* the source IP address

AND

* the destination TCP port

<source lang="bash">
% nft add rule ip nat prerouting dnat ip saddr . tcp dport map { 1.1.1.1 . 80 : 192.168.1.100, 2.2.2.2 . 8888 : 192.168.1.101 }
</source>

= Examples =

Some concrete example concatenations so you get an idea on how powerful this new feature is.

== Network addresses ==

The example below implements a dictionary using network masks as matching element.

<source lang="bash">
% nft add rule tablename chainname ip saddr and 255.255.255.0 . ip daddr and 255.255.255.0 vmap { 10.10.10.0 . 10.10.20.0 : accept }
</source>

Note that this is not an interval, this is masking the ip saddr and ip daddr, then concate both results. This concatenation is used to lookup for a matching of this the result in the map. This syntax may be compacted in future releases to support CIDR notation.

This could be easily implemented using a named map as well:

<source lang="bash">
% nft add map tablename myMap { type ipv4_addr . ipv4_addr : verdict \; }
% nft add rule tablename chainname ip saddr and 255.255.255.0 . ip saddr and 255.255.255.0 vmap @myMap
% nft add element tablename myMap { 10.10.10.0 . 10.10.20.0 : accept }
</source>

== Interfaces ==

The example below checks both input and output interfaces of a forwarded packet.

<source lang="bash">
% nft add rule tablename chainname iif . oif vmap { eth0 . eth1 : accept }
</source>

Please note that using strings (for example iifname and oifname) and other variable sized data types is not supported yet.

== Some ipset types ==

These ipset types can be implemented in nftables using concatenations. Probably more equivalences exists, it just a matter of combining data types.
Of course, you could implement these as named maps/sets as well.

See examples in the [[Moving_from_ipset_to_nftables | moving from ipset to nftables]] page.

Moving from ipset to nftables

2019-10-30T10:45:33Z

Arturo: add more examples, migrated from Concatenations page

If you are [[Moving from iptables to nftables | moving from iptables to nftables]] and you used [[ipset]], some considerations should be taken into account.

* There are no translation/compat tools right now to help in the task. This may change in the future.
* ipset uses explicit set types, like '''hash:net,port,net''' which you need to translate to nftables native data types (like '''ipv4_addr . inet_service . ipv4_addr''')
* nftables support mappings and dictionaries, so you could take actions directly from matching elements in the set.

In most cases, direct equivalencies can be found of ipset features. In most cases, it worth evaluating nftables native features to benefit from them when migrating from ipset to nftables.

Here is an example. This is a basic ipset/iptables setup:

<source>
user@debian:~ $ sudo ipset save
create myset hash:ip,port,ip family inet hashsize 1024 maxelem 65536
add myset 172.16.0.1,tcp:80,10.0.0.1

user@debian:~ $ sudo iptables-save
# Generated by iptables-save v1.8.3 on Wed Oct 30 11:26:41 2019
*filter
:INPUT ACCEPT [3:212]
:FORWARD ACCEPT [0:0]
:OUTPUT ACCEPT [4:250]
-A INPUT -m set --match-set myset src,dst,dst -j ACCEPT
COMMIT
</source>

That would translate into nftables as follows:

<source>
user@debian:~ $ sudo nft list ruleset
table inet filter {
map myset {
type ipv4_addr . inet_service . ipv4_addr : verdict
elements = { 172.16.0.1 . 80 . 10.0.0.1 : accept }
}

chain input {
type filter hook input priority filter; policy accept;
meta nfproto ipv4 ip saddr . tcp dport . ip daddr vmap @myset
}
}
</source>

Note that nftables is capable of storing verdict information per set element, which can drastically reduce the amount of rules required in the ruleset compared to iptables/ipset.

We recommend reading information about [[Concatenations | concatenations]]. Some additional ipset datatype equivalents:

'''hash:net,net'''

<source lang="bash">
% nft add rule tablename chainname ip saddr and 255.255.255.0 . ip daddr and 255.255.255.0 vmap { 10.10.10.0 . 10.10.20.0 : accept }
</source>

'''hash:net,port,net'''

<source lang="bash">
% nft add rule tablename chainname ip saddr and 255.255.255.0 . tcp dport . ip daddr and 255.255.255.0 vmap { 10.10.10.0 . 80 . 10.10.20.0 : accept }
</source>

'''hash:net,iface'''

<source lang="bash">
% nft add rule tablename chainname ip saddr and 255.255.255.0 . iif vmap { 10.10.10.0 . eth0 : accept }
</source>

This syntax may be compacted in the future to support CIDR notation.

== See also ==

* [[Concatenations]]
* [[Sets]]
* [[Dictionaries]]
* [[Maps]]
* [[Legacy xtables tools]]

Moving from ipset to nftables

2019-10-30T10:40:58Z

Arturo: add example

If you are [[Moving from iptables to nftables | moving from iptables to nftables]] and you used [[ipset]], some considerations should be taken into account.

* There are no translation/compat tools right now to help in the task. This may change in the future.
* ipset uses explicit set types, like '''hash:net,port,net''' which you need to translate to nftables native data types (like '''ipv4_addr . inet_service . ipv4_addr''')
* nftables support mappings and dictionaries, so you could take actions directly from matching elements in the set.

In most cases, direct equivalencies can be found of ipset features. In most cases, it worth evaluating nftables native features to benefit from them when migrating from ipset to nftables.

Here is an example. This is a basic ipset/iptables setup:

<source>
user@debian:~ $ sudo ipset save
create myset hash:ip,port,ip family inet hashsize 1024 maxelem 65536
add myset 172.16.0.1,tcp:80,10.0.0.1

user@debian:~ $ sudo iptables-save
# Generated by iptables-save v1.8.3 on Wed Oct 30 11:26:41 2019
*filter
:INPUT ACCEPT [3:212]
:FORWARD ACCEPT [0:0]
:OUTPUT ACCEPT [4:250]
-A INPUT -m set --match-set myset src,dst,dst -j ACCEPT
COMMIT
</source>

That would translate into nftables as follows:

<source>
user@debian:~ $ sudo nft list ruleset
table inet filter {
map myset {
type ipv4_addr . inet_service . ipv4_addr : verdict
elements = { 172.16.0.1 . 80 . 10.0.0.1 : accept }
}

chain input {
type filter hook input priority filter; policy accept;
meta nfproto ipv4 ip saddr . tcp dport . ip daddr vmap @myset
}
}
</source>

Note that nftables is capable of storing verdict information per set element, which can drastically reduce the amount of rules required in the ruleset compared to iptables/ipset.

== See also ==

* [[Concatenations]]
* [[Sets]]
* [[Dictionaries]]
* [[Maps]]
* [[Legacy xtables tools]]

Configuring chains

2019-08-28T22:34:57Z

Arturo: /* Adding non-base chains */ make more explicit that chain name can be arbitrary and clarify the example

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 through the following command:

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

'''Important''': You have to escape the semicolon if you are running this command from ''bash''.

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

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

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 and ip6 table families.
* '''nat''', which is used to perform Networking Address Translation (NAT). The first packet that belongs to a flow always hits this chain, follow up packets not. Therefore, never use this chain for filtering. This is supported by the ip and ip6 table families.

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

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 gets accepted and there is another base chain in the same hook which is ordered with a later priority, the packet will be evaluated '''again'''.
That is, packets will traverse chains in a given hook, until it is dropped or no more base chains exist. Drops take instant effect, no further rules or chains are evaluated.

Example ruleset of this behavior:

<pre>
table inet filter {
# this chain is evaluated first due to priority
chain ssh {
type filter hook input priority 0; policy accept;
# ssh packet accepted
tcp dport ssh accept
}

# this chain is evaluated last due to priority
chain input {
type filter hook input priority 1; policy drop;
# the same ssh packet is dropped here by means of default policy
}
}
</pre>

If priority of the 'input chain' above would be changed to -1, all packets would
be dropped.

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

Portal:DeveloperDocs/nftables internals

2019-08-02T12:25:29Z

Arturo: /* The kernel subsystem */ mentions briefly expressions

This page contains information for Netfilter developers on how '''nftables internals''' work.

= The kernel subsystem =

The '''nf_tables''' kernel subsystem contains 2 key components:

* the netlink API (i.e, control plane API)
* the nf_tables core (i.e, the data plane engine)

Other components, such as external modules, are also in place and are intermixed with both the API and the core.

Generally speaking, the nf_tables subsystem is implementing a virtual machine of low-level expressions that operates on network packets.

'''TODO:''' add info.

== nf_tables netlink API ==

The source code is mostly in '''net/netfilter/nf_tables_api.c''' [https://elixir.bootlin.com/linux/latest/source/net/netfilter/nf_tables_api.c [elixir src]] [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/net/netfilter/nf_tables_api.c [git src]]

'''TODO:''' add info.

== nf_tables core ==

The source code is mostly in '''net/netfilter/nf_tables_core.c''' [https://elixir.bootlin.com/linux/latest/source/net/netfilter/nf_tables_core.c [elixir src]] [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/net/netfilter/nf_tables_core.c [git src]]

You can see there one of the most important functions in the core: '''nft_do_chain()'''. In a nut shell, this is the function that evaluates network packets against the ruleset.

The logic in this function is rather simple:
* for each rule in the chain
** for each low level expression in the rule
*** evaluate the packet against the expression
** evaluate expression return code (break, continue, drop, accept, jump, goto, etc)

'''TODO:''' add info.

== expressions ==

There are many low expressions that allows us to operate over network packets in different ways. You can think on these low level expressions as assembly-like instructions.

* nft_immediate: loads an immediate value into a register.
* nft_cmp: compare a given data with data from a given register.
* nft_payload: set/get arbitrary data from packet headers.
* nft_bitwise: perform bit-wise math operations over data in a given register.
* nft_byteorder: perform byte order operations over data in a given register.
* nft_counter: a basic counter for packet/bytes that gets incremented everything is evaluated for a packet.
* nft_meta: set/get packet meta information, such as related interfaces, timestamps, etc.
* nft_lookup: search for data from a given register (key) into a dataset. If the set is a map/dictionary, returns the value for that key.

'''TODO:''' add info.

= The userspace components =

There are several important components in the userpsace part of nftables:
* '''libmnl''': generic low level library used to communicate with the kernel using netlink sockets.
* '''libnftnl''': low level library that is capable of interacting with the nf_tables subsystem netlink API in the kernel. Is responsible for creating/parsing the nf_tables netlink messages. Uses libmnl under the hood.
* '''libnftables''': high level library that implements the logic to translate from high level statements to netlink objects and the other way around. Uses libnftnl under the hood.
* '''nft''': the command line interface binary. This is what most end users actually use in their systems. It reads user input and calls libnftables under the hood.

Generally speaking, the userspace compiles high level statements (rules, etc) into the netlink bytecode that the kernel API understands
When inspecting the ruleset (i.e, listing it) what it does is the opposite, reconstruct the low level netlink bytecode into high level statements.

== libnftnl ==

'''TODO:''' add info.

== libnftables ==

'''TODO:''' add info.

= nft: from userspace to the kernel =

'''TODO:''' add info.

= nft: from the kernel to the usespace =

'''TODO:''' add info.

Portal:DeveloperDocs/nftables internals

2019-08-02T12:15:28Z

Arturo: create page with basic content

This page contains information for Netfilter developers on how '''nftables internals''' work.

= The kernel subsystem =

The '''nf_tables''' kernel subsystem contains 2 key components:

* the netlink API (i.e, control plane API)
* the nf_tables core (i.e, the data plane engine)

Other components, such as external modules, are also in place and are intermixed with both the API and the core.

Generally speaking, the nf_tables subsystem is implementing a virtual machine of low-level expressions that operates on network packets.

'''TODO:''' add info.

== nf_tables netlink API ==

The source code is mostly in '''net/netfilter/nf_tables_api.c''' [https://elixir.bootlin.com/linux/latest/source/net/netfilter/nf_tables_api.c [elixir src]] [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/net/netfilter/nf_tables_api.c [git src]]

'''TODO:''' add info.

== nf_tables core ==

The source code is mostly in '''net/netfilter/nf_tables_core.c''' [https://elixir.bootlin.com/linux/latest/source/net/netfilter/nf_tables_core.c [elixir src]] [https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/net/netfilter/nf_tables_core.c [git src]]

You can see there one of the most important functions in the core: '''nft_do_chain()'''. In a nut shell, this is the function that evaluates network packets against the ruleset.

The logic in this function is rather simple:
* for each rule in the chain
** for each low level expression in the rule
*** evaluate the packet against the expression
** evaluate expression return code (break, continue, drop, accept, jump, goto, etc)

'''TODO:''' add info.

= The userspace components =

There are several important components in the userpsace part of nftables:
* '''libmnl''': generic low level library used to communicate with the kernel using netlink sockets.
* '''libnftnl''': low level library that is capable of interacting with the nf_tables subsystem netlink API in the kernel. Is responsible for creating/parsing the nf_tables netlink messages. Uses libmnl under the hood.
* '''libnftables''': high level library that implements the logic to translate from high level statements to netlink objects and the other way around. Uses libnftnl under the hood.
* '''nft''': the command line interface binary. This is what most end users actually use in their systems. It reads user input and calls libnftables under the hood.

Generally speaking, the userspace compiles high level statements (rules, etc) into the netlink bytecode that the kernel API understands
When inspecting the ruleset (i.e, listing it) what it does is the opposite, reconstruct the low level netlink bytecode into high level statements.

== libnftnl ==

'''TODO:''' add info.

== libnftables ==

'''TODO:''' add info.

= nft: from userspace to the kernel =

'''TODO:''' add info.

= nft: from the kernel to the usespace =

'''TODO:''' add info.

Using configuration management systems

2019-07-30T15:41:33Z

Arturo: introduce ansible section

This page shows a basic example on how to integrate nftables [[Scripting | scripting]] capabilities with configuration management systems (like puppet, ansible, chef, salt and others).

The basic approach is to have a central point where we deploy nftables, with a ruleset layout that allows other files to be deployed and loaded atomically by nftables.
Other components (modules, or profiles, or whatever) then deploy specific rules or other configuration as required.

= puppet =

For the sake of the example this page uses puppet as reference, but the same concepts and mechanism could be applied to others.

'''NOTE:''' if you copy-paste this example make sure you adapt it to your environment. This code below is an example and hasn't been tested at all.

== a base puppet module ==

A file like named this: '''modules/nftables/manifest/init.pp'''

<source lang="puppet">
class nftables(
) {
# install the package
package { 'nftables':
ensure => 'present',
}

# create a directory to hold the nftables config
file { '/etc/nftables/':
ensure => 'directory',
}

# deploy the basic configuration file, i.e, the basic nftables ruleset skeleton
file { '/etc/nftables/ruleset.nft':
ensure => 'present',
source => 'puppet:///modules/nftables/nftables.nft',
}

# ensure nftables systemd service is running (at boot time, etc)
service { 'nftables':
ensure => 'running',
}
}
</source>

We are installing this file (a file like: '''modules/nftables/files/nftables.nft''')

<source>
#!/usr/sbin/nft -f

flush ruleset

# create the basic ruleset skeleton
add table inet filter
add set inet filter allowed_ports { type inet_service ; }
add chain inet filter input { type filter hook input priority filter ; policy drop ; }
add rule inet filter input iif lo counter accept
add rule inet filter input ct state established,related counter accept
add rule inet filter input tcp dport @allowed_ports accept
add rule inet filter input counter

# include all the other files that may be deployed by puppet
include "/etc/nftables/*puppet.nft"
</source>

== a module to introduce nftables config ==

This module is responsible for injecting into the system the new nftables config.
A file named like : '''modules/nftables/manifest/rule.pp'''

<source lang="puppet">
define nftables::rule(
String $rule,
) {
require ::nftables

file { "/etc/nftables/${name}_puppet.nft":
ensure => 'present',
content => $rule,
notify => Service['nftables'],
}
}
</source>

== other modules adding nftables configuration ==

In this example, we have an apache module that creates some additional rules and configuration for nftables.

This is a file named like this: '''modules/apache/manifest/config.pp'''

<source lang="puppet">
class ::apache::config(
) {
package { 'apache':
ensure => 'present',
}

nftables::rule { 'apache_port_80':
rule => 'add element inet filter allowed_ports { 80 }',
}
}
</source>

= ansible =

Check some examples on how people are using nftables with ansible:

* https://github.com/ipr-cnrs/nftables
* https://github.com/Frzk/ansible-role-nftables

Using configuration management systems

2019-07-30T15:40:23Z

Arturo: create puppet section

This page shows a basic example on how to integrate nftables [[Scripting | scripting]] capabilities with configuration management systems (like puppet, ansible, chef, salt and others).

The basic approach is to have a central point where we deploy nftables, with a ruleset layout that allows other files to be deployed and loaded atomically by nftables.
Other components (modules, or profiles, or whatever) then deploy specific rules or other configuration as required.

= puppet =

For the sake of the example this page uses puppet as reference, but the same concepts and mechanism could be applied to others.

'''NOTE:''' if you copy-paste this example make sure you adapt it to your environment. This code below is an example and hasn't been tested at all.

== a base puppet module ==

A file like named this: '''modules/nftables/manifest/init.pp'''

<source lang="puppet">
class nftables(
) {
# install the package
package { 'nftables':
ensure => 'present',
}

# create a directory to hold the nftables config
file { '/etc/nftables/':
ensure => 'directory',
}

# deploy the basic configuration file, i.e, the basic nftables ruleset skeleton
file { '/etc/nftables/ruleset.nft':
ensure => 'present',
source => 'puppet:///modules/nftables/nftables.nft',
}

# ensure nftables systemd service is running (at boot time, etc)
service { 'nftables':
ensure => 'running',
}
}
</source>

We are installing this file (a file like: '''modules/nftables/files/nftables.nft''')

<source>
#!/usr/sbin/nft -f

flush ruleset

# create the basic ruleset skeleton
add table inet filter
add set inet filter allowed_ports { type inet_service ; }
add chain inet filter input { type filter hook input priority filter ; policy drop ; }
add rule inet filter input iif lo counter accept
add rule inet filter input ct state established,related counter accept
add rule inet filter input tcp dport @allowed_ports accept
add rule inet filter input counter

# include all the other files that may be deployed by puppet
include "/etc/nftables/*puppet.nft"
</source>

== a module to introduce nftables config ==

This module is responsible for injecting into the system the new nftables config.
A file named like : '''modules/nftables/manifest/rule.pp'''

<source lang="puppet">
define nftables::rule(
String $rule,
) {
require ::nftables

file { "/etc/nftables/${name}_puppet.nft":
ensure => 'present',
content => $rule,
notify => Service['nftables'],
}
}
</source>

== other modules adding nftables configuration ==

In this example, we have an apache module that creates some additional rules and configuration for nftables.

This is a file named like this: '''modules/apache/manifest/config.pp'''

<source lang="puppet">
class ::apache::config(
) {
package { 'apache':
ensure => 'present',
}

nftables::rule { 'apache_port_80':
rule => 'add element inet filter allowed_ports { 80 }',
}
}
</source>