nftables wiki - User contributions [en]

Supported features compared to xtables

2024-09-14T10:38:50Z

Phil: linked to my ad-hoc script updating the xlate sample links

Last update: Mar/2022

This page tracks the list of supported and unsupported extensions with comments and suggestions.

== Unsupported extensions ==

=== matches: xt ===

==== bpf ====
* consider native interface
==== rateest ====
* consider native interface
==== string ====
* consider native interface
==== u32 ====
* raw expressions?

=== targets: xt ===

==== CHECKSUM ====
* add nft_payload.
* To the day, the only use case for this was DHCP clients not working with partial checksums. That should be fixed nowadays.
* See https://lwn.net/Articles/396466/ and https://www.spinics.net/lists/kvm/msg37660.html
* See https://bugs.launchpad.net/ubuntu/+source/isc-dhcp/+bug/930962 and https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=832090

==== CT ====
* nft_ct_target. Refer to [[Matching_connection_tracking_stateful_metainformation]].
==== IDLETIMER ====
* consider native interface
==== LED ====
* consider native (need this?)
==== RATEEST ====
* consider native interface
==== TCPOPTSTRIP ====
* consider native interface, need to extend nft_exthdr.c

=== targets: ipv4 ===

==== TTL ====

=== targets: ipv6 ===

==== NPT ====
* consider native interface

=== targets: bridge ===

==== arpreply ====
* consider native interface

=== targets: arp ===

TODO

== Supported extensions ==
(Links updated via [http://nwl.cc/~n0-1/update_nftables_wiki_xlate_links.sh script].)

=== matches: xt ===

==== addrtype ====
* nft_fib, starting with 4.10 kernel. Refer to [[Matching routing information]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_addrtype.txlate Examples from iptables-translate testsuite]

==== cgroup ====
* nft_meta. Refer to [[Quick_reference-nftables_in_10_minutes#Meta]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_cgroup.txlate Examples from iptables-translate testsuite]
[Awaits support for cgroup2]

==== cluster ====
* nft_hash
* [https://git.netfilter.org/iptables/tree/extensions/libxt_cluster.txlate Examples from iptables-translate testsuite]

==== comment ====
* Built-in support via NFTA_RULE_USERDATA, since 3.15 (Pablo Neira). Refer to [[Matching_packet_headers#Matching_UDP.2FTCP_headers_in_the_same_rule|matching UDP/TCP headers in the same rule]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_comment.txlate Examples from iptables-translate testsuite]

==== connbytes ====
* nft_ct, 4.5 kernel. Refer to [[Meters]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_connbytes.txlate Examples from iptables-translate testsuite]
==== connlabel ====
* nft_meta, since 3.16.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_connlabel.txlate Examples from iptables-translate testsuite]
==== connlimit ====
* consider native interface. Refer to [[Meters]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_connlimit.txlate Examples from iptables-translate testsuite]
==== connmark ====
* nft_meta.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_connmark.txlate Examples from iptables-translate testsuite]
==== conntrack ====
* nft_ct.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_conntrack.txlate Examples from iptables-translate testsuite]
==== cpu ====
* nft_meta, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_cpu.txlate Examples from iptables-translate testsuite]
==== dccp ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_dccp.txlate Examples from iptables-translate testsuite]
[Unsupported option : dccp-option]
==== devgroup ====
* nft_meta, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_devgroup.txlate Examples from iptables-translate testsuite]
==== dscp ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_dscp.txlate Examples from iptables-translate testsuite]
==== ecn ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_ecn.txlate Examples from iptables-translate testsuite]
==== esp ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_esp.txlate Examples from iptables-translate testsuite]
==== hashlimit ====
* meter statement. Refer to [[Meters]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_hashlimit.txlate Examples from iptables-translate testsuite]
==== helper ====
* nft_ct.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_helper.txlate Examples from iptables-translate testsuite]
==== ipcomp ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_ipcomp.txlate Examples from iptables-translate testsuite]
[Unsupported option : compres]
==== iprange ====
* nft_payload, through native range support. To emulate iptables --ports you need two rules.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_iprange.txlate Examples from iptables-translate testsuite]
==== ipvs ====
* consider native interface. Refer to [[Load balancing]].
==== length ====
* nft_meta.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_length.txlate Examples from iptables-translate testsuite]
==== limit ====
* nft_limit. Refer to [[Stateful objects]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_limit.txlate Examples from iptables-translate testsuite]
==== mac ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_mac.txlate Examples from iptables-translate testsuite]
==== mark ====
* nft_meta.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_mark.txlate Examples from iptables-translate testsuite]
==== multiport ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_multiport.txlate Examples from iptables-translate testsuite]
==== nfacct ====
* consider native interface. Refer to [[Stateful objects]].
==== osf ====
* consider native interface
==== owner ====
* nft_meta.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_owner.txlate Examples from iptables-translate testsuite]
[Unsupported option : socket-exists]
==== pkttype ====
* nft_meta
* [https://git.netfilter.org/iptables/tree/extensions/libxt_pkttype.txlate Examples from iptables-translate testsuite]
==== policy ====
* nft_xfrm, since 5.0
* [https://git.netfilter.org/iptables/tree/extensions/libxt_policy.txlate Examples from iptables-translate testsuite]
==== recent ====
* consider native interface. Refer to [[Sets]].
==== sctp ====
* nft_payload
* nft_exthdr for --chunk-types
* [https://git.netfilter.org/iptables/tree/extensions/libxt_sctp.txlate Examples from iptables-translate testsuite]
==== socket ====
* consider native interface
* [https://git.netfilter.org/iptables/tree/extensions/libxt_socket.txlate Examples from iptables-translate testsuite]
==== statistic ====
* nft_numgen. Refer to [[Load balancing]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_statistic.txlate Examples from iptables-translate testsuite]
==== set ====
* Use native nf_tables set infrastructure.
==== state ====
* nft_ct
==== tcp ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libxt_tcp.txlate Examples from iptables-translate testsuite]
==== tcpmss ====
* nft_exthdr, since 4.14
* [https://git.netfilter.org/iptables/tree/extensions/libxt_tcpmss.txlate Examples from iptables-translate testsuite]

==== time ====
* nft_meta, since 5.4
* [https://git.netfilter.org/iptables/tree/extensions/libxt_time.txlate Examples from iptables-translate testsuite]

==== udp ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libxt_udp.txlate Examples from iptables-translate testsuite]

=== targets: xt ===

==== AUDIT ====
* nft_log, since 4.18.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_AUDIT.txlate Examples from iptables-translate testsuite]
==== CLASSIFY ====
* nft_meta, since 3.14.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_CLASSIFY.txlate Examples from iptables-translate testsuite]
==== CONNMARK ====
* nft_ct
* [https://git.netfilter.org/iptables/tree/extensions/libxt_CONNMARK.txlate Examples from iptables-translate testsuite]
==== CONNSECMARK ====
* nft_ct, since 4.20
==== DSCP ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libxt_DSCP.txlate Examples from iptables-translate testsuite]
==== HL ====
* nft_payload
==== HMARK ====
* nft_meta + nft_hash.
==== MARK ====
* nft_meta, since 3.14.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_MARK.txlate Examples from iptables-translate testsuite]
==== NETMAP ====
* nft_nat, upcoming 5.8
==== NFLOG ====
* nft_log, since 3.17.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_NFLOG.txlate Examples from iptables-translate testsuite]
==== NFQUEUE ====
* nft_queue, since 3.14.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_NFQUEUE.txlate Examples from iptables-translate testsuite]
==== SECMARK ====
* nft_meta, since 4.20

==== SYNPROXY ====
* nft_synproxy, since 5.3
* [https://git.netfilter.org/iptables/tree/extensions/libxt_SYNPROXY.txlate Examples from iptables-translate testsuite]

==== TEE ====
* nft_dup, since 4.3.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_TEE.txlate Examples from iptables-translate testsuite]
==== TPROXY ====
* nft_tproxy, since 4.19
* [https://git.netfilter.org/iptables/tree/extensions/libxt_TPROXY.txlate Examples from iptables-translate testsuite]

==== TRACE ====
* nft_meta, since 3.14.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_TRACE.txlate Examples from iptables-translate testsuite]

==== TCPMSS ====
* nft_exthdr, since 4.14
* [https://git.netfilter.org/iptables/tree/extensions/libxt_TCPMSS.txlate Examples from iptables-translate testsuite]

=== matches: ipv4 ===

==== ah ====
* nft_payload + nft_cmp
* [https://git.netfilter.org/iptables/tree/extensions/libipt_ah.txlate Examples from iptables-translate testsuite]
==== icmp ====
* nft_payload + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_icmp.txlate Examples from iptables-translate testsuite]
[Unsupported codes: network-unreachable, host-unreachable, protocol-unreachable, port-unreachable, fragmentation-needed, source-route-failed, network-unknown, host-unknown, network-prohibited, host-prohibited, TOS-network-unreachable, TOS-host-unreachable, communication-prohibited, host-precedence-violation, precedence-cutoff, network-redirect, host-redirect, TOS-network-redirect, TOS-host-redirect, ttl-zero-during-transit, ttl-zero-during-reassembly, ip-header-bad and required-option-missing ]
==== realm ====
* nft_meta, through NFT_META_RTCLASSID.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_realm.txlate Examples from iptables-translate testsuite]
==== rp_filter ====
* nft_fib, starting with 4.10 kernel
==== ttl ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libipt_ttl.txlate Examples from iptables-translate testsuite]

=== matches: ipv6 ===

==== rp_filter ====
* nft_fib, starting with 4.10 kernel
==== ah ====
* nft_payload + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_ah.txlate Examples from iptables-translate testsuite]
==== eui64 ====
* nft_payload + nft_cmp.
==== frag ====
* nft_exthdr + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_frag.txlate Examples from iptables-translate testsuite]
==== hbh ====
* nft_exthdr + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_hbh.txlate Examples from iptables-translate testsuite]
HBH options are not supported yet.
[Unsupported option: --hbh-opts]
==== hl ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_hl.txlate Examples from iptables-translate testsuite]
==== icmp6 ====
* nft_payload + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_icmp6.txlate Examples from iptables-translate testsuite]
[Unsupported icmpv6 codes: no-route, communication-prohibited, beyond-scope, address-unreachable, port-unreachable, failed-policy, reject-route, ttl-zero-during-transit, ttl-zero-during-reassembly, bad-header, unknown-header-type and unknown-option]
==== ipv6header ====
* nft_exthdr + nft_cmp.
==== mh ====
* nft_exthdr + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_mh.txlate Examples from iptables-translate testsuite]
[Needs bug fixation for option mh-type with range]
==== rt ====
* nft_exthdr + nft_cmp
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_rt.txlate Examples from iptables-translate testsuite]
[Unsupported options: --rt-0-res, --rt-0-addrs, --rt-0-not-strict]

=== targets: ipv4 ===
==== ECN ====
* nft_payload

==== DNAT ====
* nft_nat, since 3.13.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_DNAT.txlate Examples from iptables-translate testsuite]
==== LOG ====
* nft_log, since 3.17.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_LOG.txlate Examples from iptables-translate testsuite]
[Unsupported options : log-tcp-sequence, log-tcp-options, log-ip-options, log-uid, log-macdecode]
==== MASQUERADE ====
* nft_masq, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_MASQUERADE.txlate Examples from iptables-translate testsuite]
==== REDIRECT ====
* nft_redirect, since 3.19.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_REDIRECT.txlate Examples from iptables-translate testsuite]

==== REJECT ====
* nft_reject_ipv4, since 3.13.
* nft_reject_inet, since 3.14.
* nft_reject_bridge, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_REJECT.txlate Examples from iptables-translate testsuite]
==== SNAT ====
* nft_nat, since 3.13.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_SNAT.txlate Examples from iptables-translate testsuite]

=== targets: ipv6 ===
==== DNAT ====
* nft_nat, since 3.13.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_DNAT.txlate Examples from iptables-translate testsuite]
==== LOG ====
* nft_log, since 3.17.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_LOG.txlate Examples from iptables-translate testsuite]
[Unsupported options : log-tcp-sequence, log-tcp-options, log-ip-options, log-uid, log-macdecode]
==== MASQUERADE ====
* nft_masq, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_MASQUERADE.txlate Examples from iptables-translate testsuite]
==== REDIRECT ====
* nft_redirect, since 3.19.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_REDIRECT.txlate Examples from iptables-translate testsuite]

==== REJECT ====
* nft_reject_ipv6, since 3.14.
* nft_reject_inet, since 3.14.
* nft_reject_bridge, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_REJECT.txlate Examples from iptables-translate testsuite]
==== SNAT ====
* nft_nat, since 3.13.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_SNAT.txlate Examples from iptables-translate testsuite]

=== matches: bridge ===

==== 802.3 ====
* nft_payload

==== among ====
* sets

==== arp ====
* nft_payload

==== ip ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libebt_ip.txlate Examples from iptables-translate testsuite]

==== ip6 ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libebt_ip6.txlate Examples from iptables-translate testsuite]

==== limit ====
* nft_limit
* [https://git.netfilter.org/iptables/tree/extensions/libebt_limit.txlate Examples from iptables-translate testsuite]

==== mark ====
* nft_mark
* [https://git.netfilter.org/iptables/tree/extensions/libebt_mark_m.txlate Examples from iptables-translate testsuite]

==== pkttype ====
* nft_meta
* [https://git.netfilter.org/iptables/tree/extensions/libebt_pkttype.txlate Examples from iptables-translate testsuite]

==== stp ====
* nft_payload

==== vlan ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libebt_vlan.txlate Examples from iptables-translate testsuite]

=== targets: bridge ===

==== dnat ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libebt_dnat.txlate Examples from iptables-translate testsuite]

==== snat ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libebt_snat.txlate Examples from iptables-translate testsuite]

==== redirect ====
* nft_payload + nft_meta (pkttype set unicast)

==== mark ====
* nft_mark
* [https://git.netfilter.org/iptables/tree/extensions/libebt_mark.txlate Examples from iptables-translate testsuite]

=== watchers: bridge ===

==== log ====
* nft_log
* [https://git.netfilter.org/iptables/tree/extensions/libebt_log.txlate Examples from iptables-translate testsuite]

==== nflog ====
* nft_log
* [https://git.netfilter.org/iptables/tree/extensions/libebt_nflog.txlate Examples from iptables-translate testsuite]

== Deprecated extensions ==

=== matches ===

==== physdev ====
* br_netfilter aims to be deprecated by nftables.
==== quota ====
* nfacct already provides quota support.
==== tos ====
* deprecated by dscp

=== targets ===

==== CLUSTERIP ====
* deprecated by cluster match.
==== TOS ====
* deprecated by DSCP

=== targets: ipv4 ===

==== ULOG ====
* Removed from tree since 3.17.

Supported features compared to xtables

2024-09-13T13:07:03Z

Phil: /* Supported extensions */ Updated with links to new xlate test cases

Last update: Mar/2022

This page tracks the list of supported and unsupported extensions with comments and suggestions.

== Unsupported extensions ==

=== matches: xt ===

==== bpf ====
* consider native interface
==== rateest ====
* consider native interface
==== string ====
* consider native interface
==== u32 ====
* raw expressions?

=== targets: xt ===

==== CHECKSUM ====
* add nft_payload.
* To the day, the only use case for this was DHCP clients not working with partial checksums. That should be fixed nowadays.
* See https://lwn.net/Articles/396466/ and https://www.spinics.net/lists/kvm/msg37660.html
* See https://bugs.launchpad.net/ubuntu/+source/isc-dhcp/+bug/930962 and https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=832090

==== CT ====
* nft_ct_target. Refer to [[Matching_connection_tracking_stateful_metainformation]].
==== IDLETIMER ====
* consider native interface
==== LED ====
* consider native (need this?)
==== RATEEST ====
* consider native interface
==== TCPOPTSTRIP ====
* consider native interface, need to extend nft_exthdr.c

=== targets: ipv4 ===

==== TTL ====

=== targets: ipv6 ===

==== NPT ====
* consider native interface

=== targets: bridge ===

==== arpreply ====
* consider native interface

=== targets: arp ===

TODO

== Supported extensions ==

=== matches: xt ===

==== addrtype ====
* nft_fib, starting with 4.10 kernel. Refer to [[Matching routing information]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_addrtype.txlate Examples from iptables-translate testsuite]

==== cgroup ====
* nft_meta. Refer to [[Quick_reference-nftables_in_10_minutes#Meta]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_cgroup.txlate Examples from iptables-translate testsuite]
[Awaits support for cgroup2]

==== cluster ====
* nft_hash
* [https://git.netfilter.org/iptables/tree/extensions/libxt_cluster.txlate Examples from iptables-translate testsuite]

==== comment ====
* Built-in support via NFTA_RULE_USERDATA, since 3.15 (Pablo Neira). Refer to [[Matching_packet_headers#Matching_UDP.2FTCP_headers_in_the_same_rule|matching UDP/TCP headers in the same rule]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_comment.txlate Examples from iptables-translate testsuite]

==== connbytes ====
* nft_ct, 4.5 kernel. Refer to [[Meters]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_connbytes.txlate Examples from iptables-translate testsuite]
==== connlabel ====
* nft_meta, since 3.16.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_connlabel.txlate Examples from iptables-translate testsuite]
==== connlimit ====
* consider native interface. Refer to [[Meters]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_connlimit.txlate Examples from iptables-translate testsuite]
==== connmark ====
* nft_meta.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_connmark.txlate Examples from iptables-translate testsuite]
==== conntrack ====
* nft_ct.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_conntrack.txlate Examples from iptables-translate testsuite]
==== cpu ====
* nft_meta, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_cpu.txlate Examples from iptables-translate testsuite]
==== dccp ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_dccp.txlate Examples from iptables-translate testsuite]
[Unsupported option : dccp-option]
==== devgroup ====
* nft_meta, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_devgroup.txlate Examples from iptables-translate testsuite]
==== dscp ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_dscp.txlate Examples from iptables-translate testsuite]
==== ecn ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_ecn.txlate Examples from iptables-translate testsuite]
==== esp ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_esp.txlate Examples from iptables-translate testsuite]
==== hashlimit ====
* meter statement. Refer to [[Meters]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_hashlimit.txlate Examples from iptables-translate testsuite]
==== helper ====
* nft_ct.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_helper.txlate Examples from iptables-translate testsuite]
==== ipcomp ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_ipcomp.txlate Examples from iptables-translate testsuite]
[Unsupported option : compres]
==== iprange ====
* nft_payload, through native range support. To emulate iptables --ports you need two rules.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_iprange.txlate Examples from iptables-translate testsuite]
==== ipvs ====
* consider native interface. Refer to [[Load balancing]].
==== length ====
* nft_meta.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_length.txlate Examples from iptables-translate testsuite]
==== limit ====
* nft_limit. Refer to [[Stateful objects]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_limit.txlate Examples from iptables-translate testsuite]
==== mac ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_mac.txlate Examples from iptables-translate testsuite]
==== mark ====
* nft_meta.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_mark.txlate Examples from iptables-translate testsuite]
==== multiport ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_multiport.txlate Examples from iptables-translate testsuite]
==== nfacct ====
* consider native interface. Refer to [[Stateful objects]].
==== osf ====
* consider native interface
==== owner ====
* nft_meta.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_owner.txlate Examples from iptables-translate testsuite]
[Unsupported option : socket-exists]
==== pkttype ====
* nft_meta
* [https://git.netfilter.org/iptables/tree/extensions/libxt_pkttype.txlate Examples from iptables-translate testsuite]
==== policy ====
* nft_xfrm, since 5.0
* [https://git.netfilter.org/iptables/tree/extensions/libxt_policy.txlate Examples from iptables-translate testsuite]
==== recent ====
* consider native interface. Refer to [[Sets]].
==== sctp ====
* nft_payload
* nft_exthdr for --chunk-types
* [https://git.netfilter.org/iptables/tree/extensions/libxt_sctp.txlate Examples from iptables-translate testsuite]
==== socket ====
* consider native interface
* [https://git.netfilter.org/iptables/tree/extensions/libxt_socket.txlate Examples from iptables-translate testsuite]
==== statistic ====
* nft_numgen. Refer to [[Load balancing]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_statistic.txlate Examples from iptables-translate testsuite]
==== set ====
* Use native nf_tables set infrastructure.
==== state ====
* nft_ct
==== tcp ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libxt_tcp.txlate Examples from iptables-translate testsuite]
==== tcpmss ====
* nft_exthdr, since 4.14
* [https://git.netfilter.org/iptables/tree/extensions/libxt_tcpmss.txlate Examples from iptables-translate testsuite]

==== time ====
* nft_meta, since 5.4
* [https://git.netfilter.org/iptables/tree/extensions/libxt_time.txlate Examples from iptables-translate testsuite]

==== udp ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libxt_udp.txlate Examples from iptables-translate testsuite]

=== targets: xt ===

==== AUDIT ====
* nft_log, since 4.18.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_AUDIT.txlate Examples from iptables-translate testsuite]
==== CLASSIFY ====
* nft_meta, since 3.14.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_CLASSIFY.txlate Examples from iptables-translate testsuite]
==== CONNMARK ====
* nft_ct
* [https://git.netfilter.org/iptables/tree/extensions/libxt_CONNMARK.txlate Examples from iptables-translate testsuite]
==== CONNSECMARK ====
* nft_ct, since 4.20
==== DSCP ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libxt_DSCP.txlate Examples from iptables-translate testsuite]
==== HL ====
* nft_payload
==== HMARK ====
* nft_meta + nft_hash.
==== MARK ====
* nft_meta, since 3.14.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_MARK.txlate Examples from iptables-translate testsuite]
==== NETMAP ====
* nft_nat, upcoming 5.8
==== NFLOG ====
* nft_log, since 3.17.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_NFLOG.txlate Examples from iptables-translate testsuite]
==== NFQUEUE ====
* nft_queue, since 3.14.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_NFQUEUE.txlate Examples from iptables-translate testsuite]
==== SECMARK ====
* nft_meta, since 4.20

==== SYNPROXY ====
* nft_synproxy, since 5.3
* [https://git.netfilter.org/iptables/tree/extensions/libxt_SYNPROXY.txlate Examples from iptables-translate testsuite]

==== TEE ====
* nft_dup, since 4.3.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_TEE.txlate Examples from iptables-translate testsuite]
==== TPROXY ====
* nft_tproxy, since 4.19
* [https://git.netfilter.org/iptables/tree/extensions/libxt_TPROXY.txlate Examples from iptables-translate testsuite]

==== TRACE ====
* nft_meta, since 3.14.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_TRACE.txlate Examples from iptables-translate testsuite]

==== TCPMSS ====
* nft_exthdr, since 4.14
* [https://git.netfilter.org/iptables/tree/extensions/libxt_TCPMSS.txlate Examples from iptables-translate testsuite]

=== matches: ipv4 ===

==== ah ====
* nft_payload + nft_cmp
* [https://git.netfilter.org/iptables/tree/extensions/libipt_ah.txlate Examples from iptables-translate testsuite]
==== icmp ====
* nft_payload + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_icmp.txlate Examples from iptables-translate testsuite]
[Unsupported codes: network-unreachable, host-unreachable, protocol-unreachable, port-unreachable, fragmentation-needed, source-route-failed, network-unknown, host-unknown, network-prohibited, host-prohibited, TOS-network-unreachable, TOS-host-unreachable, communication-prohibited, host-precedence-violation, precedence-cutoff, network-redirect, host-redirect, TOS-network-redirect, TOS-host-redirect, ttl-zero-during-transit, ttl-zero-during-reassembly, ip-header-bad and required-option-missing ]
==== realm ====
* nft_meta, through NFT_META_RTCLASSID.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_realm.txlate Examples from iptables-translate testsuite]
==== rp_filter ====
* nft_fib, starting with 4.10 kernel
==== ttl ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libipt_ttl.txlate Examples from iptables-translate testsuite]

=== matches: ipv6 ===

==== rp_filter ====
* nft_fib, starting with 4.10 kernel
==== ah ====
* nft_payload + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_ah.txlate Examples from iptables-translate testsuite]
==== eui64 ====
* nft_payload + nft_cmp.
==== frag ====
* nft_exthdr + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_frag.txlate Examples from iptables-translate testsuite]
==== hbh ====
* nft_exthdr + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_hbh.txlate Examples from iptables-translate testsuite]
HBH options are not supported yet.
[Unsupported option: --hbh-opts]
==== hl ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_hl.txlate Examples from iptables-translate testsuite]
==== icmp6 ====
* nft_payload + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_icmp6.txlate Examples from iptables-translate testsuite]
[Unsupported icmpv6 codes: no-route, communication-prohibited, beyond-scope, address-unreachable, port-unreachable, failed-policy, reject-route, ttl-zero-during-transit, ttl-zero-during-reassembly, bad-header, unknown-header-type and unknown-option]
==== ipv6header ====
* nft_exthdr + nft_cmp.
==== mh ====
* nft_exthdr + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_mh.txlate Examples from iptables-translate testsuite]
[Needs bug fixation for option mh-type with range]
==== rt ====
* nft_exthdr + nft_cmp
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_rt.txlate Examples from iptables-translate testsuite]
[Unsupported options: --rt-0-res, --rt-0-addrs, --rt-0-not-strict]

=== targets: ipv4 ===
==== ECN ====
* nft_payload

==== DNAT ====
* nft_nat, since 3.13.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_DNAT.txlate Examples from iptables-translate testsuite]
==== LOG ====
* nft_log, since 3.17.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_LOG.txlate Examples from iptables-translate testsuite]
[Unsupported options : log-tcp-sequence, log-tcp-options, log-ip-options, log-uid, log-macdecode]
==== MASQUERADE ====
* nft_masq, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_MASQUERADE.txlate Examples from iptables-translate testsuite]
==== REDIRECT ====
* nft_redirect, since 3.19.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_REDIRECT.txlate Examples from iptables-translate testsuite]

==== REJECT ====
* nft_reject_ipv4, since 3.13.
* nft_reject_inet, since 3.14.
* nft_reject_bridge, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_REJECT.txlate Examples from iptables-translate testsuite]
==== SNAT ====
* nft_nat, since 3.13.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_SNAT.txlate Examples from iptables-translate testsuite]

=== targets: ipv6 ===
==== DNAT ====
* nft_nat, since 3.13.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_DNAT.txlate Examples from iptables-translate testsuite]
==== LOG ====
* nft_log, since 3.17.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_LOG.txlate Examples from iptables-translate testsuite]
[Unsupported options : log-tcp-sequence, log-tcp-options, log-ip-options, log-uid, log-macdecode]
==== MASQUERADE ====
* nft_masq, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_MASQUERADE.txlate Examples from iptables-translate testsuite]
==== REDIRECT ====
* nft_redirect, since 3.19.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_REDIRECT.txlate Examples from iptables-translate testsuite]

==== REJECT ====
* nft_reject_ipv6, since 3.14.
* nft_reject_inet, since 3.14.
* nft_reject_bridge, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_REJECT.txlate Examples from iptables-translate testsuite]
==== SNAT ====
* nft_nat, since 3.13.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_SNAT.txlate Examples from iptables-translate testsuite]

=== matches: bridge ===

==== 802.3 ====
* nft_payload

==== among ====
* sets

==== arp ====
* nft_payload

==== ip ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libebt_ip.txlate Examples from iptables-translate testsuite]

==== ip6 ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libebt_ip6.txlate Examples from iptables-translate testsuite]

==== limit ====
* nft_limit
* [https://git.netfilter.org/iptables/tree/extensions/libebt_limit.txlate Examples from iptables-translate testsuite]

==== mark ====
* nft_mark
* [https://git.netfilter.org/iptables/tree/extensions/libebt_mark_m.txlate Examples from iptables-translate testsuite]

==== pkttype ====
* nft_meta
* [https://git.netfilter.org/iptables/tree/extensions/libebt_pkttype.txlate Examples from iptables-translate testsuite]

==== stp ====
* nft_payload

==== vlan ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libebt_vlan.txlate Examples from iptables-translate testsuite]

=== targets: bridge ===

==== dnat ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libebt_dnat.txlate Examples from iptables-translate testsuite]

==== snat ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libebt_snat.txlate Examples from iptables-translate testsuite]

==== redirect ====
* nft_payload + nft_meta (pkttype set unicast)

==== mark ====
* nft_mark
* [https://git.netfilter.org/iptables/tree/extensions/libebt_mark.txlate Examples from iptables-translate testsuite]

=== watchers: bridge ===

==== log ====
* nft_log
* [https://git.netfilter.org/iptables/tree/extensions/libebt_log.txlate Examples from iptables-translate testsuite]

==== nflog ====
* nft_log
* [https://git.netfilter.org/iptables/tree/extensions/libebt_nflog.txlate Examples from iptables-translate testsuite]

== Deprecated extensions ==

=== matches ===

==== physdev ====
* br_netfilter aims to be deprecated by nftables.
==== quota ====
* nfacct already provides quota support.
==== tos ====
* deprecated by dscp

=== targets ===

==== CLUSTERIP ====
* deprecated by cluster match.
==== TOS ====
* deprecated by DSCP

=== targets: ipv4 ===

==== ULOG ====
* Removed from tree since 3.17.

Main Page

2023-06-23T12:53:23Z

Phil: /* Basic operation */ link to VM code analysis page added

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

= [[News]] =

= Introduction =
* [[What is nftables?]]
* [[How to obtain help/support]]

= Reference =
* [https://www.netfilter.org/projects/nftables/manpage.html man nft - netfilter website]
* [https://www.mankier.com/8/nft man nft - mankier.com]
* [[Quick reference-nftables in 10 minutes|Quick reference, nftables in 10 minutes]]
* [[Netfilter hooks]] and nftables integration with existing Netfilter components
* [[nftables families|Understanding nftables families]]
* [[Data_types|Data types]]
* [[Connection_Tracking_System|Connection tracking system (conntrack)]], used for stateful firewalling and NAT
* [[Troubleshooting|Troubleshooting and FAQ]]
* [[Further_documentation|Additional documentation]]

= Installing nftables =
* [[nftables from distributions|Using nftables from distributions]]
* [[Building and installing nftables from sources]]

= Upgrading from xtables to nftables =
* [[Legacy xtables tools]]
* [[Moving from iptables to nftables]]
* [[Moving from ipset to nftables]]

= 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]]
* [[Ruleset debug/VM code analysis]]
* [[Output text modifiers]]

= Expressions: Matching packets =
* [[Matching packet metainformation]]
* [[Matching packet headers]]
* [[Matching connection tracking stateful metainformation]]
* [[Matching routing information]]
* [[Rate limiting matchings]]

= Statements: Acting on packet matches =
* [[Accepting and dropping packets]]
* [[Rejecting traffic]]
* [[Jumping to chain]]
* [[Counters]]
* [[Logging traffic]]
* [[Performing Network Address Translation (NAT)]]
* [[Setting packet metainformation]]
* [[Setting packet connection tracking metainformation]]
* [[Mangling packet headers]] (including stateless NAT)
* [[Duplicating packets]]
* [[Load balancing]]
* [[Queueing to userspace]]

= Advanced data structures for performance packet classification =
* [[Intervals]]
* [[Concatenations]]
* [[Math operations]]
* [[Stateful objects]]
** [[Counters]]
** [[Quotas]]
** [[Limits]]
** [[Connlimits]] (''ct count'')
* Other objects
** [[Conntrack helpers]] (''ct helper'', Layer 7 ALG)
** [[Ct_timeout|Conntrack timeout policies]] (''ct timeout'')
** [[Ct_expectation|Conntrack expectations]] (''ct expectation'')
** [[Synproxy]]
** [[Secmark|Secmarks]]
* Generic set infrastructure
** [[Sets]]
** [[Element timeouts]]
** [[Updating sets from the packet path]]
** [[Maps]]
** [[Verdict_Maps_(vmaps) | Verdict maps]]
** [[Meters|Metering]] (formerly known as flow tables before nftables 0.8.1)
* [[Flowtables]] (the fastpath network stack bypass)

= Examples =
* [[Simple ruleset for a workstation]]
* [[Simple ruleset for a server]]
* [[Simple ruleset for a home router]]
* [[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.

Portal:DeveloperDocs/nftables internals

2023-06-23T12:52:05Z

Phil: kernel/user expression relation exported into a dedicated article, link to it from here

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/vmap, returns the value for that key.

See [[Ruleset_debug/VM_code_analysis]] for a description of how kernel's expressions relate to expressions and statements in user space and how to visualise this relation.

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

This library provides data structures for entities existing in nf_tables
nomenclature, such as tables, chains and rules. It serves as an intermediate
layer between nftables and iptables-nft user space applications and nfnetlink
messages the kernel sends and receives.

In general, each data structure comes with a set of handling routines:

; allocators : To allocate and free an object of given type
; setters/getters : Data structure fields are accessed via an attribute number (via a specific enum field)
; serializers : Populating a netlink message or vice versa
; printers : Providing a textual representation, mostly for debugging purposes

Where sensible, there is a '''list-variant''', too. If so, it comes with
handling routines as well:

; allocators : Allocating and freeing the list object (and members)
; populators : Add and remove from the list

Where useful, there might be a '''lookup routine''' as well. With
nftnl_chain_list, e.g. the list object contains a hash table for chain names as
well so list lookup by chain name is faster than a linear search.

A typical extra for list objects are '''iterators''': A data structure
containing state while browsing through the list. Usually the only routines
used are allocators and a ''next'' routine.

These are the '''entities defined by libnftnl''':

; table : A rather boring "namespace" for chains
; chain : A container for rules, may attach to a netfilter hook in kernel
; rule : A container for expressions
; expr : An nftables VM code instruction
; flowtable : Similar to a chain, but holds flows between interfaces
; obj : A generic object, typically holding stateful information
; ruleset : A container for lists of tables, chains, sets and rules - not used by nftables application anymore
; set : A container for elements
; set_elem : A set element
; trace : A trace event sent by the kernel

=== nftnl_expr ===

While nftables distinguishes between expressions and statements, such
difference does not quite exist in libnftnl layer. For instance, a statement
like:
ip saddr 192.168.0.1
is actually two expressions:
; payload : loading IPv4 header's source address into a register
; cmp : comparing data from a register against a stored value

Since expressions have access to the packet, its meta data, all nftables
registers (including the verdict register) and may store multiple values
internally, they are mighty and versatile.

=== nftnl_obj ===

This is a common API for various object types. An object's type is defined post
allocation by setting the ''NFTNL_OBJ_TYPE'' attribute. Currently existing
object types are:

* counter
* quota
* ct helper
* limit
* tunnel
* ct timeout
* secmark
* ct expect
* synproxy

=== nftnl_batch ===

This is a wrapper interface around the same functionality in libmnl (which is
used internally). In general, nftnl batches aid in collecting multiple netlink
messages for kernel submission.

== libnftables ==

One goal in nftables development was to provide users with a library for easier
integration into applications than "shelling out" using ''system()'' and trying
to parse ''nft'' command output.

At first, ''libnftnl'' was supposed to achieve this but the fact that it
exposes internal implementation details apart from being pretty low-level in
general made it rather unsuitable from a users' perspective.

To overcome this, ''nft'' backend code was separated into a library which
should fill the gap between ''libnftnl'' on one side and ''nft'' application
itself on the other.

Usage of ''libnftables'' is supposed to be simple and straightforward, almost
like calling ''nft'' itself but with a bit more convenience. First step is to
create a new context:

struct nft_ctx *ctx = nft_ctx_new(0);

The context allows to configure library behaviour on a "per session" basis.
With this in place, nftables commands may be executed:

int rc = nft_run_cmd_from_buffer(ctx, "add table inet t");

or whole dump files loaded:

int rc = nft_run_cmd_from_filename(ctx, "/etc/nftables/all-in-one.nft");

To control output, there are a number of functions:

FILE *nft_ctx_set_output(struct nft_ctx *ctx, FILE *fp);
int nft_ctx_buffer_output(struct nft_ctx *ctx);
int nft_ctx_unbuffer_output(struct nft_ctx *ctx);
const char *nft_ctx_get_output_buffer(struct nft_ctx *ctx);

Same for stderr. See libnftables(3) man page for further details.

= nft: from user space to the kernel =

The following describes the steps and entities involved after a call to
'''nft''' in user space until the actual communication with the kernel.

Since creation of '''libnftables''', '''nft''' is merely a lightweight
front-end, basically just creating a '''libnftables''' handle, allowing to
configure it via command-line options and feeding '''nftables''' syntax into
it. Within the library, the actual work takes place. It may be divided into
several phases:

* Input parsing into internal data structure
* Evaluation and expansion
* Serialization into netlink messages
* nfnetlink message session with kernel
* Error handling

== Input parsing into internal data structures ==

Depending on whether input comes from command line or a file (which may be
''stdin''), '''main()''' calls either '''nft_run_cmd_from_buffer()''' or
'''nft_run_cmd_from_filename()''' library functions.

If JSON output was selected ('''nft -j'''), the JSON parser (in
''src/parser_json.c'') is tried first. If this did not succeed, the standard
("human-readable") syntax parser is called.

Eventually both parsers populate a list of commands ('''struct cmd''') and a
list of error messages ('''struct error_record''') in case errors were
detected.

=== Standard syntax ===

The parser for standard syntax is implemented in lex and yacc, see
''src/scanner.l'' and ''src/parser_bison.y'' for reference. It is entered via
the generated function '''nft_parse()'''.

As a basic rule, in lex/yacc the scanner recognizes the words and the parser
interprets them in their context. There is also (limited) scanner control from
the parser by definition of a scope in which some words are valid or not. The
parser defines recursive patterns to match input against. Here is the top-most
one, '''input''':

<nowiki>
input : /* empty */
| input line
{
if ($2 != NULL) {
$2->location = @2;
list_add_tail(&$2->list, state->cmds);
}
}
;
</nowiki>

So it may be empty or (by recursion) consist of a number of
'''line''' patterns. Each of those lines parses into a command and is appended
to the list. The snippet above also shows how parser-provided '''location'''
data is stored in the command object. This is used for error reporting.

=== JSON syntax ===

The JSON parser lives in ''src/parser_json.c'' and is entered via
'''nft_parse_json_buffer()''' function or '''nft_parse_json_filename()''',
respectively. It uses jansson library for (de-)serialization and value
(un-)packing. To learn about the code and to understand the program flow,
'''json_parse_cmd()''' function is a good starting point.

== Evaluation and expansion ==

Input evaluation is a crucial step and combines several tasks. It extends input
validation from mere syntax checks done by the parser to semantical ones,
taking context into perspective.

Input may be changed, too. Sometimes it is necessary to insert extra statements
as dependency, sometimes types of right hand sides of comparisons must adjust
to left hand side type.

Before all the above, the list of commands is scanned for cache requirements -
see '''nft_cache_evaluate()''' for details. Since caching may be an expensive
operation if in-kernel ruleset is huge, this step attempts to reduce the data
fetched from kernel to the bare minimum needed for correct operation. A final
call to '''nft_cache_update()''' then does the actual fetch.

If evaluation passed, expansion takes place. This is mostly to cover for input
in "dump" notation, i.e. rules nested in chains nested in tables, etc. Such
input is converted into individual "add" commands as required by the netlink
message format. The code is pretty straightforward, see '''nft_cmd_expand()'''
for reference.

== Serialization into netlink messages ==

In this step, '''nftables'''-internal data types are converted into
'''libnftables''' ones (e.g., '''struct table''' into
'''struct nftnl_table'''). The latter abstract their internal layout as
attributes and are therefore opaque to the caller.

'''libnftnl''' provides helpers to convert its own data structures into netlink
message format: A generic '''nftnl_nlmsg_build_hdr()''' for the header and
type-specific ones for the payload (e.g.,
'''nftnl_table_nlmsg_build_payload()''').

The netlink messages are stored in a '''struct nftnl_batch''' which provides
the backing storage. This surrounding data structure serializes into an
introductory '''NFNL_MSG_BATCH_BEGIN''' message and a finalizing one with type
'''NFNL_MSG_BATCH_END'''.

In kernel space, the batch constitutes a transaction: If one of the messages is
rejected, none of them take effect. Ditto, if the final batch end message is
missing the whole batch will undo. This is how '''nft''''s '''--check''' option
is implemented.

== nfnetlink message session with kernel ==

In '''nft''', communication with the kernel takes place in the function
'''mnl_batch_talk()''': It converts the '''nftnl_batch''' into a message
suitable for '''sendmsg()''', adjusts buffer sizes (if needed), transmits the
data and listens for a reply. Any error messages are handled by
'''mnl_batch_extack_cb()''' function which records them for later reporting.
Other messages are relevant for '''--echo''' mode, in which the kernel "echoes"
the requests back after updating them (with handle values, for instance). These
are handled by '''netlink_echo_callback()''', more or less a wrapper around
'''nft''''s event monitoring code.

== Error handling ==

Each '''struct cmd''' object is identified by its own sequence number
(monotonic within the batch). Netlink error messages contain this number and
also an offset value, which allow to identify not only the problematic message
but also the specific attribute of that message which was rejected.

Mapping from message attribute back to line or word(s) of input works via a
mapping from attribute offset to the '''struct location''' object stored while
parsing. That bison parser-provided data holds line and column numbers,
allowing '''nft''' to underline problematic parts of input when reporting back
to the caller.

To follow the above in the source code, see '''nft_cmd_error()''' function
being called for each command and error it caused. The mapping is established
earlier while creating netlink messages, i.e. in code called from
'''do_command()''' - watch out for the various calls to '''cmd_add_loc()'''
populating the field '''attr''' in '''struct cmd'''.

= nft: from the kernel to user space =

Communication between '''nft''' in user space and '''nftables''' in kernel
happens via netlink, a packet-based IPC mechanism for that purpose. Its kernel
source code lives in ''net/netlink'' directory and allows to be extended by
calling '''netlink_kernel_create()''', passing a unique '''unit''' number and a
'''struct netlink_kernel_cfg''' object.

'''nfnetlink''' is such an extension, attempting to serve all netfilter-related
user space applications. It is implemented in ''net/netfilter/nfnetlink.c'' and
itself allows to be extended as well by means of groups (see
'''nfnetlink_groups''' in ''include/uapi/linux/netfilter/nfnetlink.h''). These
in turn map to nfnetlink subsystems, see the constant array
'''nfnl_group2type''' in nfnetlink source file. '''NFNL_SUBSYS_NFTABLES''' is
the relevant one here, implemented in ''net/netfilter/nf_tables_api.c'' (see
'''nf_tables_subsys''' and the call to '''nfnetlink_subsys_register()''' in
there).

For insight, it is worthwhile to remain in generic '''nfnetlink''' code for a
little longer: '''nfnetlink_net_ops''' are registered as a "pernet" subsystem,
i.e. each network namespace gets its own instance. Upon netns creation,
'''nfnetlink_net_init()''' is called which actually creates the
'''NETLINK_NETFILTER''' subsystem. Its receive callback ('''nfnetlink_rcv()''')
checks whether the first message header starts a batch and diverts the code
flow accordingly.

For batch handling, subsystems need to define '''commit''' and '''abort'''
callbacks. Also, for each contained message, there must be a responsible
callback entry with type '''NFNL_CB_BATCH'''. '''nf_tables_subsys''' fulfills
these requirements.

Each callback in '''nf_tables_cb''' (and therefore each supported message type)
decides whether it must be part of a batch or not - nfnetlink code does not
allow for multiple handlers of the same message. In nftables, only getters for
different ruleset elements are non-batch, anything mangling the ruleset is.

== Non-batched handlers ==

These are getters for:

* table
* chain
* rule
* set
* set element
* generation ID
* stateful objects
* flowtable

They all behave similar: Unless '''NLM_F_DUMP''' flag is set in the message,
they perform a lookup based on the required identifiers and return an nfnetlink
message to user space. There are type-specific helpers populating a netlink
message named '''nf_tables_fill_<SOMETHING>_info''', packet sending is done by
a call to '''nfnetlink_unicast()'''.

If '''NLM_F_DUMP''' was given, the getter iterates over all ruleset elements of
given type and fills a netlink message for each. In some cases, filtering the
output by identifiers given in the request is supported - useful to dump e.g.
all rules of a specific chain only.

The iterator code is a bit complicated due to the fact that socket buffer size
may be exceeded. In that case, partial data is submitted to user space and the
dump continued afterwards. The iterators keep a "cursor" (actually a counter)
for where to pick up again.

== Batched handlers ==

To allow for rolling back a transaction which has failed or was aborted,
message handlers of type '''NFNL_CB_BATCH''' allocate a '''struct nft_trans'''
object and add it to the per-net commit list. This "log" of what was done is
also useful to defer actions till the very end of the transaction. See
'''nf_tables_commit()''' for reference of what it is used for in the
success-case. Similar code is found in '''nf_tables_abort()''', reverting the
previous changes.

To make the ruleset update atomic, nftables uses an internal generation ID. Its
value alternates between zero and one upon each commit. Ruleset elements have a
two-bit "generation mask", indicating whether that element is active in the
generation at its bit index. This way, elements may die, get born or stay alive
when the generation ID toggles again.

Ruleset debug/VM code analysis

2023-06-23T12:47:03Z

Phil: Page created

In the kernel, nf_tables is implemented as a virtual machine with its own
instruction set. The kernel's '''expressions''' implement such instructions. In
user space, the mapping is not (necessarily) as direct as this.

= Statements and expressions in user space =

In user space nomenclature, a distinction is made between '''statements''' and
'''expressions'''; the relevant difference is that the former are valid parts
of a rule on their own while the latter usually appear as parameter or input to
a statement. For instance, take the following '''payload statement''':

ip dscp set 42

Here, '''ip dscp''' is an expression identifying what part of the packet
payload to mangle, '''42''' is a constant expression holding the value to
assign. There are certain limits as to what may appear after the '''set'''
keyword, nft does some type checking to make sure it is compatible. But to
illustrate the power this concept has, take the following example:

tcp dport set tcp sport

This will mangle a TCP packet's destination port to match whatever its source
port value may be. Albeit a bit constructed, this is an example of a statement
accepting data from two expressions.

= Expressions in kernel space =

The kernel does not have the concept of a statement. There are merely
expressions (instructions) loading data from or writing to registers, thereby
interacting with each other. Aside from twenty general purpose data registers
(each sized four bytes), there is a single '''verdict''' register used to
terminate rule or even chain traversal available to expressions.

= VM bytecode in action =

When '''nft''' translates user input into VM code for the kernel, it translates
from statements and expressions as user space knows them into VM code calling
kernel's expressions. Passing the '''--debug=netlink''' option makes this visual:

nft --debug=netlink add rule inet t c ip daddr 10.1.2.3 counter accept
inet t c
[ meta load nfproto => reg 1 ]
[ cmp eq reg 1 0x00000002 ]
[ payload load 4b @ network header + 16 => reg 1 ]
[ cmp eq reg 1 0x0302010a ]
[ counter pkts 0 bytes 0 ]
[ immediate reg 0 accept ]

The rule added by the command above matches the packet's
'''IPv4 Destination Address''' field against the value '''10.1.2.3''', counts
matching packets and finally accepts them (thereby ending chain traversal for
this packet.

The printed VM bytecode reveals a few more interesting details:

# The rule actually starts with a match on '''meta nfproto''' value: Because the chain resides in inet family, it may see packets other than IPv4 ones as well. This filtering is necessary because:
# User space's '''ip daddr''' expression is actually very generic: The '''payload''' expression it translates into merely loads 4B from the network header at offset 16B into register 1. With an IPv6 packet, this would happily load parts of the Source Address field, which might even match the value 0x0302010a by accident. To avoid such unexpected (and unforseeable) behaviour, the implicit '''meta nfproto''' match is required.
# Packet matching is often implicit: The second expression, comparing '''meta nfproto''' value against '''0x02''' (= NFPROTO_IPV4) for equality ('''eq'''). If not successful, it will write the value '''NFT_BREAK''' into the verdict register and chain traversal continues with the next rule.
# Contrary to the above, the last expression is an explicit access to the verdict register ('''reg 0'''), writing NF_ACCEPT.

= Statements in VM bytecode =

Picking up one of the examples above:

nft --debug=netlink add rule t c tcp dport set tcp sport
ip t c
[ meta load l4proto => reg 1 ]
[ cmp eq reg 1 0x00000006 ]
[ payload load 2b @ transport header + 0 => reg 1 ]
[ payload write reg 1 => 2b @ transport header + 2 csum_type 1 csum_off 16 csum_flags 0x0 ]

This reveals how '''payload statement''' is actually just a variant of the
kernel's '''payload expression'' which writes instead of reads. Some further
observations:

# There is again an implicit match present, this time to assert '''meta l4proto''' matches the value 0x6 (= IPPROTO_TCP). Again to make sure the following payload expressions don't read garbage or write to odd parts of the packet.
# The second '''payload expression'' also holds extra information for a partial checksum update which is necessary after mangling an IPv4 packet.

Portal:DeveloperDocs/nftables internals

2023-06-22T16:56:33Z

Phil: /* expressions */ Documented relation between expressions in kernel and user space

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/vmap, returns the value for that key.

=== Relation to User Space ===

In user space terminology, there's a distinction between '''statements''' like
''counter'', ''jump'' or ''log'' and '''expressions''' like ''ip saddr'',
''tcp dport'' or ''meta iifname''. What distinguishes them is the fact that
'''statements''' are valid ruleset elements on their own while
'''expressions''' are usually arguments to a statement. For instance, take the
following '''payload statement''':

ip dscp set 42

Here, '''ip dscp''' is an expression identifying what part of the packet
payload to mangle, '''42''' is a constant expression holding the value to
assign. There are certain limits as to what may appear after the '''set'''
keyword, nft does some type checking to make sure it is compatible. But to
illustrate the power this concept has, take the following example:

tcp dport set tcp sport

This will mangle a TCP packet's destination port to match whatever its source
port value may be. Albeit a bit constructed, this is an example of a statement
accepting data from two expressions. Because kernel space does not make the
distinction though, there must be some kind of translation happening. To analyse this, nft's '''--debug=netlink''' flag is handy:

nft --debug=netlink add rule t c tcp dport set tcp sport
ip t c
[ meta load l4proto => reg 1 ]
[ cmp eq reg 1 0x00000006 ]
[ payload load 2b @ transport header + 0 => reg 1 ]
[ payload write reg 1 => 2b @ transport header + 2 csum_type 1 csum_off 16 csum_flags 0x0 ]

It prints the (libnftnl/kernel) expressions a rule consists of. This reveals
some interesting details:

# There is an invisible match on '''meta l4proto''' at the start of the rule. This is a dependency imposed by the '''tcp sport/dport''' expressions which work right with TCP packets only. To avoid unexpected results, nft makes sure non-TCP packets won't match the rule right from the start.

# Registers enable data to pass between expressions: The first expression loads the packet's layer4 protocol value into '''reg 1''', the second expression compares '''reg 1''''s value against the value 0x6.

# There are two "variants" of a payload expression: one that merely loads data from the packet and one that writes it. One could say the first one is the payload expression and the latter the payload statement in nft's nomenclature.

# The second payload expression which writes 2B from '''reg 1''' into the packet at the offset of the transport header plus 2B (the position of the TCP header's '''Destination Port''' field), also holds extra information for a partial checksum update.

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

This library provides data structures for entities existing in nf_tables
nomenclature, such as tables, chains and rules. It serves as an intermediate
layer between nftables and iptables-nft user space applications and nfnetlink
messages the kernel sends and receives.

In general, each data structure comes with a set of handling routines:

; allocators : To allocate and free an object of given type
; setters/getters : Data structure fields are accessed via an attribute number (via a specific enum field)
; serializers : Populating a netlink message or vice versa
; printers : Providing a textual representation, mostly for debugging purposes

Where sensible, there is a '''list-variant''', too. If so, it comes with
handling routines as well:

; allocators : Allocating and freeing the list object (and members)
; populators : Add and remove from the list

Where useful, there might be a '''lookup routine''' as well. With
nftnl_chain_list, e.g. the list object contains a hash table for chain names as
well so list lookup by chain name is faster than a linear search.

A typical extra for list objects are '''iterators''': A data structure
containing state while browsing through the list. Usually the only routines
used are allocators and a ''next'' routine.

These are the '''entities defined by libnftnl''':

; table : A rather boring "namespace" for chains
; chain : A container for rules, may attach to a netfilter hook in kernel
; rule : A container for expressions
; expr : An nftables VM code instruction
; flowtable : Similar to a chain, but holds flows between interfaces
; obj : A generic object, typically holding stateful information
; ruleset : A container for lists of tables, chains, sets and rules - not used by nftables application anymore
; set : A container for elements
; set_elem : A set element
; trace : A trace event sent by the kernel

=== nftnl_expr ===

While nftables distinguishes between expressions and statements, such
difference does not quite exist in libnftnl layer. For instance, a statement
like:
ip saddr 192.168.0.1
is actually two expressions:
; payload : loading IPv4 header's source address into a register
; cmp : comparing data from a register against a stored value

Since expressions have access to the packet, its meta data, all nftables
registers (including the verdict register) and may store multiple values
internally, they are mighty and versatile.

=== nftnl_obj ===

This is a common API for various object types. An object's type is defined post
allocation by setting the ''NFTNL_OBJ_TYPE'' attribute. Currently existing
object types are:

* counter
* quota
* ct helper
* limit
* tunnel
* ct timeout
* secmark
* ct expect
* synproxy

=== nftnl_batch ===

This is a wrapper interface around the same functionality in libmnl (which is
used internally). In general, nftnl batches aid in collecting multiple netlink
messages for kernel submission.

== libnftables ==

One goal in nftables development was to provide users with a library for easier
integration into applications than "shelling out" using ''system()'' and trying
to parse ''nft'' command output.

At first, ''libnftnl'' was supposed to achieve this but the fact that it
exposes internal implementation details apart from being pretty low-level in
general made it rather unsuitable from a users' perspective.

To overcome this, ''nft'' backend code was separated into a library which
should fill the gap between ''libnftnl'' on one side and ''nft'' application
itself on the other.

Usage of ''libnftables'' is supposed to be simple and straightforward, almost
like calling ''nft'' itself but with a bit more convenience. First step is to
create a new context:

struct nft_ctx *ctx = nft_ctx_new(0);

The context allows to configure library behaviour on a "per session" basis.
With this in place, nftables commands may be executed:

int rc = nft_run_cmd_from_buffer(ctx, "add table inet t");

or whole dump files loaded:

int rc = nft_run_cmd_from_filename(ctx, "/etc/nftables/all-in-one.nft");

To control output, there are a number of functions:

FILE *nft_ctx_set_output(struct nft_ctx *ctx, FILE *fp);
int nft_ctx_buffer_output(struct nft_ctx *ctx);
int nft_ctx_unbuffer_output(struct nft_ctx *ctx);
const char *nft_ctx_get_output_buffer(struct nft_ctx *ctx);

Same for stderr. See libnftables(3) man page for further details.

= nft: from user space to the kernel =

The following describes the steps and entities involved after a call to
'''nft''' in user space until the actual communication with the kernel.

Since creation of '''libnftables''', '''nft''' is merely a lightweight
front-end, basically just creating a '''libnftables''' handle, allowing to
configure it via command-line options and feeding '''nftables''' syntax into
it. Within the library, the actual work takes place. It may be divided into
several phases:

* Input parsing into internal data structure
* Evaluation and expansion
* Serialization into netlink messages
* nfnetlink message session with kernel
* Error handling

== Input parsing into internal data structures ==

Depending on whether input comes from command line or a file (which may be
''stdin''), '''main()''' calls either '''nft_run_cmd_from_buffer()''' or
'''nft_run_cmd_from_filename()''' library functions.

If JSON output was selected ('''nft -j'''), the JSON parser (in
''src/parser_json.c'') is tried first. If this did not succeed, the standard
("human-readable") syntax parser is called.

Eventually both parsers populate a list of commands ('''struct cmd''') and a
list of error messages ('''struct error_record''') in case errors were
detected.

=== Standard syntax ===

The parser for standard syntax is implemented in lex and yacc, see
''src/scanner.l'' and ''src/parser_bison.y'' for reference. It is entered via
the generated function '''nft_parse()'''.

As a basic rule, in lex/yacc the scanner recognizes the words and the parser
interprets them in their context. There is also (limited) scanner control from
the parser by definition of a scope in which some words are valid or not. The
parser defines recursive patterns to match input against. Here is the top-most
one, '''input''':

<nowiki>
input : /* empty */
| input line
{
if ($2 != NULL) {
$2->location = @2;
list_add_tail(&$2->list, state->cmds);
}
}
;
</nowiki>

So it may be empty or (by recursion) consist of a number of
'''line''' patterns. Each of those lines parses into a command and is appended
to the list. The snippet above also shows how parser-provided '''location'''
data is stored in the command object. This is used for error reporting.

=== JSON syntax ===

The JSON parser lives in ''src/parser_json.c'' and is entered via
'''nft_parse_json_buffer()''' function or '''nft_parse_json_filename()''',
respectively. It uses jansson library for (de-)serialization and value
(un-)packing. To learn about the code and to understand the program flow,
'''json_parse_cmd()''' function is a good starting point.

== Evaluation and expansion ==

Input evaluation is a crucial step and combines several tasks. It extends input
validation from mere syntax checks done by the parser to semantical ones,
taking context into perspective.

Input may be changed, too. Sometimes it is necessary to insert extra statements
as dependency, sometimes types of right hand sides of comparisons must adjust
to left hand side type.

Before all the above, the list of commands is scanned for cache requirements -
see '''nft_cache_evaluate()''' for details. Since caching may be an expensive
operation if in-kernel ruleset is huge, this step attempts to reduce the data
fetched from kernel to the bare minimum needed for correct operation. A final
call to '''nft_cache_update()''' then does the actual fetch.

If evaluation passed, expansion takes place. This is mostly to cover for input
in "dump" notation, i.e. rules nested in chains nested in tables, etc. Such
input is converted into individual "add" commands as required by the netlink
message format. The code is pretty straightforward, see '''nft_cmd_expand()'''
for reference.

== Serialization into netlink messages ==

In this step, '''nftables'''-internal data types are converted into
'''libnftables''' ones (e.g., '''struct table''' into
'''struct nftnl_table'''). The latter abstract their internal layout as
attributes and are therefore opaque to the caller.

'''libnftnl''' provides helpers to convert its own data structures into netlink
message format: A generic '''nftnl_nlmsg_build_hdr()''' for the header and
type-specific ones for the payload (e.g.,
'''nftnl_table_nlmsg_build_payload()''').

The netlink messages are stored in a '''struct nftnl_batch''' which provides
the backing storage. This surrounding data structure serializes into an
introductory '''NFNL_MSG_BATCH_BEGIN''' message and a finalizing one with type
'''NFNL_MSG_BATCH_END'''.

In kernel space, the batch constitutes a transaction: If one of the messages is
rejected, none of them take effect. Ditto, if the final batch end message is
missing the whole batch will undo. This is how '''nft''''s '''--check''' option
is implemented.

== nfnetlink message session with kernel ==

In '''nft''', communication with the kernel takes place in the function
'''mnl_batch_talk()''': It converts the '''nftnl_batch''' into a message
suitable for '''sendmsg()''', adjusts buffer sizes (if needed), transmits the
data and listens for a reply. Any error messages are handled by
'''mnl_batch_extack_cb()''' function which records them for later reporting.
Other messages are relevant for '''--echo''' mode, in which the kernel "echoes"
the requests back after updating them (with handle values, for instance). These
are handled by '''netlink_echo_callback()''', more or less a wrapper around
'''nft''''s event monitoring code.

== Error handling ==

Each '''struct cmd''' object is identified by its own sequence number
(monotonic within the batch). Netlink error messages contain this number and
also an offset value, which allow to identify not only the problematic message
but also the specific attribute of that message which was rejected.

Mapping from message attribute back to line or word(s) of input works via a
mapping from attribute offset to the '''struct location''' object stored while
parsing. That bison parser-provided data holds line and column numbers,
allowing '''nft''' to underline problematic parts of input when reporting back
to the caller.

To follow the above in the source code, see '''nft_cmd_error()''' function
being called for each command and error it caused. The mapping is established
earlier while creating netlink messages, i.e. in code called from
'''do_command()''' - watch out for the various calls to '''cmd_add_loc()'''
populating the field '''attr''' in '''struct cmd'''.

= nft: from the kernel to user space =

Communication between '''nft''' in user space and '''nftables''' in kernel
happens via netlink, a packet-based IPC mechanism for that purpose. Its kernel
source code lives in ''net/netlink'' directory and allows to be extended by
calling '''netlink_kernel_create()''', passing a unique '''unit''' number and a
'''struct netlink_kernel_cfg''' object.

'''nfnetlink''' is such an extension, attempting to serve all netfilter-related
user space applications. It is implemented in ''net/netfilter/nfnetlink.c'' and
itself allows to be extended as well by means of groups (see
'''nfnetlink_groups''' in ''include/uapi/linux/netfilter/nfnetlink.h''). These
in turn map to nfnetlink subsystems, see the constant array
'''nfnl_group2type''' in nfnetlink source file. '''NFNL_SUBSYS_NFTABLES''' is
the relevant one here, implemented in ''net/netfilter/nf_tables_api.c'' (see
'''nf_tables_subsys''' and the call to '''nfnetlink_subsys_register()''' in
there).

For insight, it is worthwhile to remain in generic '''nfnetlink''' code for a
little longer: '''nfnetlink_net_ops''' are registered as a "pernet" subsystem,
i.e. each network namespace gets its own instance. Upon netns creation,
'''nfnetlink_net_init()''' is called which actually creates the
'''NETLINK_NETFILTER''' subsystem. Its receive callback ('''nfnetlink_rcv()''')
checks whether the first message header starts a batch and diverts the code
flow accordingly.

For batch handling, subsystems need to define '''commit''' and '''abort'''
callbacks. Also, for each contained message, there must be a responsible
callback entry with type '''NFNL_CB_BATCH'''. '''nf_tables_subsys''' fulfills
these requirements.

Each callback in '''nf_tables_cb''' (and therefore each supported message type)
decides whether it must be part of a batch or not - nfnetlink code does not
allow for multiple handlers of the same message. In nftables, only getters for
different ruleset elements are non-batch, anything mangling the ruleset is.

== Non-batched handlers ==

These are getters for:

* table
* chain
* rule
* set
* set element
* generation ID
* stateful objects
* flowtable

They all behave similar: Unless '''NLM_F_DUMP''' flag is set in the message,
they perform a lookup based on the required identifiers and return an nfnetlink
message to user space. There are type-specific helpers populating a netlink
message named '''nf_tables_fill_<SOMETHING>_info''', packet sending is done by
a call to '''nfnetlink_unicast()'''.

If '''NLM_F_DUMP''' was given, the getter iterates over all ruleset elements of
given type and fills a netlink message for each. In some cases, filtering the
output by identifiers given in the request is supported - useful to dump e.g.
all rules of a specific chain only.

The iterator code is a bit complicated due to the fact that socket buffer size
may be exceeded. In that case, partial data is submitted to user space and the
dump continued afterwards. The iterators keep a "cursor" (actually a counter)
for where to pick up again.

== Batched handlers ==

To allow for rolling back a transaction which has failed or was aborted,
message handlers of type '''NFNL_CB_BATCH''' allocate a '''struct nft_trans'''
object and add it to the per-net commit list. This "log" of what was done is
also useful to defer actions till the very end of the transaction. See
'''nf_tables_commit()''' for reference of what it is used for in the
success-case. Similar code is found in '''nf_tables_abort()''', reverting the
previous changes.

To make the ruleset update atomic, nftables uses an internal generation ID. Its
value alternates between zero and one upon each commit. Ruleset elements have a
two-bit "generation mask", indicating whether that element is active in the
generation at its bit index. This way, elements may die, get born or stay alive
when the generation ID toggles again.

Simple rule management

2022-10-18T09:43:21Z

Phil: /* Removing all the rules in a chain */ Fix flush command for removing all rules in a chain: s/flush rule/flush chain/

Rules take action on network packets (e.g. accepting or dropping them) based on whether they match specified criteria.

Each rule consists of zero or more expressions followed by one or more statements. Each expression tests whether a packet matches a specific payload field or packet/flow metadata. Multiple expressions are linearly evaluated from left to right: if the first expression matches, then the next expression is evaluated and so on. If we reach the final expression, then the packet matches all of the expressions in the rule, and the rule's statements are executed. Each statement takes an action, such as setting the netfilter mark, counting the packet, logging the packet, or rendering a verdict such as accepting or dropping the packet or jumping to another chain. As with expressions, multiple statements are linearly evaluated from left to right: a single rule can take multiple actions by using multiple statements. Do note that a verdict statement by its nature ends the rule.

Following are some basic operations and commands for configuring rules:

= 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 -n -a list table filter
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 -n -a list table filter
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 -a list table filter
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 flush chain 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, which you have to find by first listing the ruleset with option ''-a'':

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

To replace the rule with handle 2, specify its handle number and the new rule that you want to replace it:

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

Listing the ruleset after the above replacement:

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

you can see that the old rule that counted TCP packets has been replaced by the new rule that counts all packets.

Portal:DeveloperDocs/nftables internals

2022-09-13T15:30:13Z

Phil: /* nft: from the kernel to the usespace */

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/vmap, 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 ==

This library provides data structures for entities existing in nf_tables
nomenclature, such as tables, chains and rules. It serves as an intermediate
layer between nftables and iptables-nft user space applications and nfnetlink
messages the kernel sends and receives.

In general, each data structure comes with a set of handling routines:

; allocators : To allocate and free an object of given type
; setters/getters : Data structure fields are accessed via an attribute number (via a specific enum field)
; serializers : Populating a netlink message or vice versa
; printers : Providing a textual representation, mostly for debugging purposes

Where sensible, there is a '''list-variant''', too. If so, it comes with
handling routines as well:

; allocators : Allocating and freeing the list object (and members)
; populators : Add and remove from the list

Where useful, there might be a '''lookup routine''' as well. With
nftnl_chain_list, e.g. the list object contains a hash table for chain names as
well so list lookup by chain name is faster than a linear search.

A typical extra for list objects are '''iterators''': A data structure
containing state while browsing through the list. Usually the only routines
used are allocators and a ''next'' routine.

These are the '''entities defined by libnftnl''':

; table : A rather boring "namespace" for chains
; chain : A container for rules, may attach to a netfilter hook in kernel
; rule : A container for expressions
; expr : An nftables VM code instruction
; flowtable : Similar to a chain, but holds flows between interfaces
; obj : A generic object, typically holding stateful information
; ruleset : A container for lists of tables, chains, sets and rules - not used by nftables application anymore
; set : A container for elements
; set_elem : A set element
; trace : A trace event sent by the kernel

=== nftnl_expr ===

While nftables distinguishes between expressions and statements, such
difference does not quite exist in libnftnl layer. For instance, a statement
like:
ip saddr 192.168.0.1
is actually two expressions:
; payload : loading IPv4 header's source address into a register
; cmp : comparing data from a register against a stored value

Since expressions have access to the packet, its meta data, all nftables
registers (including the verdict register) and may store multiple values
internally, they are mighty and versatile.

=== nftnl_obj ===

This is a common API for various object types. An object's type is defined post
allocation by setting the ''NFTNL_OBJ_TYPE'' attribute. Currently existing
object types are:

* counter
* quota
* ct helper
* limit
* tunnel
* ct timeout
* secmark
* ct expect
* synproxy

=== nftnl_batch ===

This is a wrapper interface around the same functionality in libmnl (which is
used internally). In general, nftnl batches aid in collecting multiple netlink
messages for kernel submission.

== libnftables ==

One goal in nftables development was to provide users with a library for easier
integration into applications than "shelling out" using ''system()'' and trying
to parse ''nft'' command output.

At first, ''libnftnl'' was supposed to achieve this but the fact that it
exposes internal implementation details apart from being pretty low-level in
general made it rather unsuitable from a users' perspective.

To overcome this, ''nft'' backend code was separated into a library which
should fill the gap between ''libnftnl'' on one side and ''nft'' application
itself on the other.

Usage of ''libnftables'' is supposed to be simple and straightforward, almost
like calling ''nft'' itself but with a bit more convenience. First step is to
create a new context:

struct nft_ctx *ctx = nft_ctx_new(0);

The context allows to configure library behaviour on a "per session" basis.
With this in place, nftables commands may be executed:

int rc = nft_run_cmd_from_buffer(ctx, "add table inet t");

or whole dump files loaded:

int rc = nft_run_cmd_from_filename(ctx, "/etc/nftables/all-in-one.nft");

To control output, there are a number of functions:

FILE *nft_ctx_set_output(struct nft_ctx *ctx, FILE *fp);
int nft_ctx_buffer_output(struct nft_ctx *ctx);
int nft_ctx_unbuffer_output(struct nft_ctx *ctx);
const char *nft_ctx_get_output_buffer(struct nft_ctx *ctx);

Same for stderr. See libnftables(3) man page for further details.

= nft: from user space to the kernel =

The following describes the steps and entities involved after a call to
'''nft''' in user space until the actual communication with the kernel.

Since creation of '''libnftables''', '''nft''' is merely a lightweight
front-end, basically just creating a '''libnftables''' handle, allowing to
configure it via command-line options and feeding '''nftables''' syntax into
it. Within the library, the actual work takes place. It may be divided into
several phases:

* Input parsing into internal data structure
* Evaluation and expansion
* Serialization into netlink messages
* nfnetlink message session with kernel
* Error handling

== Input parsing into internal data structures ==

Depending on whether input comes from command line or a file (which may be
''stdin''), '''main()''' calls either '''nft_run_cmd_from_buffer()''' or
'''nft_run_cmd_from_filename()''' library functions.

If JSON output was selected ('''nft -j'''), the JSON parser (in
''src/parser_json.c'') is tried first. If this did not succeed, the standard
("human-readable") syntax parser is called.

Eventually both parsers populate a list of commands ('''struct cmd''') and a
list of error messages ('''struct error_record''') in case errors were
detected.

=== Standard syntax ===

The parser for standard syntax is implemented in lex and yacc, see
''src/scanner.l'' and ''src/parser_bison.y'' for reference. It is entered via
the generated function '''nft_parse()'''.

As a basic rule, in lex/yacc the scanner recognizes the words and the parser
interprets them in their context. There is also (limited) scanner control from
the parser by definition of a scope in which some words are valid or not. The
parser defines recursive patterns to match input against. Here is the top-most
one, '''input''':

<nowiki>
input : /* empty */
| input line
{
if ($2 != NULL) {
$2->location = @2;
list_add_tail(&$2->list, state->cmds);
}
}
;
</nowiki>

So it may be empty or (by recursion) consist of a number of
'''line''' patterns. Each of those lines parses into a command and is appended
to the list. The snippet above also shows how parser-provided '''location'''
data is stored in the command object. This is used for error reporting.

=== JSON syntax ===

The JSON parser lives in ''src/parser_json.c'' and is entered via
'''nft_parse_json_buffer()''' function or '''nft_parse_json_filename()''',
respectively. It uses jansson library for (de-)serialization and value
(un-)packing. To learn about the code and to understand the program flow,
'''json_parse_cmd()''' function is a good starting point.

== Evaluation and expansion ==

Input evaluation is a crucial step and combines several tasks. It extends input
validation from mere syntax checks done by the parser to semantical ones,
taking context into perspective.

Input may be changed, too. Sometimes it is necessary to insert extra statements
as dependency, sometimes types of right hand sides of comparisons must adjust
to left hand side type.

Before all the above, the list of commands is scanned for cache requirements -
see '''nft_cache_evaluate()''' for details. Since caching may be an expensive
operation if in-kernel ruleset is huge, this step attempts to reduce the data
fetched from kernel to the bare minimum needed for correct operation. A final
call to '''nft_cache_update()''' then does the actual fetch.

If evaluation passed, expansion takes place. This is mostly to cover for input
in "dump" notation, i.e. rules nested in chains nested in tables, etc. Such
input is converted into individual "add" commands as required by the netlink
message format. The code is pretty straightforward, see '''nft_cmd_expand()'''
for reference.

== Serialization into netlink messages ==

In this step, '''nftables'''-internal data types are converted into
'''libnftables''' ones (e.g., '''struct table''' into
'''struct nftnl_table'''). The latter abstract their internal layout as
attributes and are therefore opaque to the caller.

'''libnftnl''' provides helpers to convert its own data structures into netlink
message format: A generic '''nftnl_nlmsg_build_hdr()''' for the header and
type-specific ones for the payload (e.g.,
'''nftnl_table_nlmsg_build_payload()''').

The netlink messages are stored in a '''struct nftnl_batch''' which provides
the backing storage. This surrounding data structure serializes into an
introductory '''NFNL_MSG_BATCH_BEGIN''' message and a finalizing one with type
'''NFNL_MSG_BATCH_END'''.

In kernel space, the batch constitutes a transaction: If one of the messages is
rejected, none of them take effect. Ditto, if the final batch end message is
missing the whole batch will undo. This is how '''nft''''s '''--check''' option
is implemented.

== nfnetlink message session with kernel ==

In '''nft''', communication with the kernel takes place in the function
'''mnl_batch_talk()''': It converts the '''nftnl_batch''' into a message
suitable for '''sendmsg()''', adjusts buffer sizes (if needed), transmits the
data and listens for a reply. Any error messages are handled by
'''mnl_batch_extack_cb()''' function which records them for later reporting.
Other messages are relevant for '''--echo''' mode, in which the kernel "echoes"
the requests back after updating them (with handle values, for instance). These
are handled by '''netlink_echo_callback()''', more or less a wrapper around
'''nft''''s event monitoring code.

== Error handling ==

Each '''struct cmd''' object is identified by its own sequence number
(monotonic within the batch). Netlink error messages contain this number and
also an offset value, which allow to identify not only the problematic message
but also the specific attribute of that message which was rejected.

Mapping from message attribute back to line or word(s) of input works via a
mapping from attribute offset to the '''struct location''' object stored while
parsing. That bison parser-provided data holds line and column numbers,
allowing '''nft''' to underline problematic parts of input when reporting back
to the caller.

To follow the above in the source code, see '''nft_cmd_error()''' function
being called for each command and error it caused. The mapping is established
earlier while creating netlink messages, i.e. in code called from
'''do_command()''' - watch out for the various calls to '''cmd_add_loc()'''
populating the field '''attr''' in '''struct cmd'''.

= nft: from the kernel to user space =

Communication between '''nft''' in user space and '''nftables''' in kernel
happens via netlink, a packet-based IPC mechanism for that purpose. Its kernel
source code lives in ''net/netlink'' directory and allows to be extended by
calling '''netlink_kernel_create()''', passing a unique '''unit''' number and a
'''struct netlink_kernel_cfg''' object.

'''nfnetlink''' is such an extension, attempting to serve all netfilter-related
user space applications. It is implemented in ''net/netfilter/nfnetlink.c'' and
itself allows to be extended as well by means of groups (see
'''nfnetlink_groups''' in ''include/uapi/linux/netfilter/nfnetlink.h''). These
in turn map to nfnetlink subsystems, see the constant array
'''nfnl_group2type''' in nfnetlink source file. '''NFNL_SUBSYS_NFTABLES''' is
the relevant one here, implemented in ''net/netfilter/nf_tables_api.c'' (see
'''nf_tables_subsys''' and the call to '''nfnetlink_subsys_register()''' in
there).

For insight, it is worthwhile to remain in generic '''nfnetlink''' code for a
little longer: '''nfnetlink_net_ops''' are registered as a "pernet" subsystem,
i.e. each network namespace gets its own instance. Upon netns creation,
'''nfnetlink_net_init()''' is called which actually creates the
'''NETLINK_NETFILTER''' subsystem. Its receive callback ('''nfnetlink_rcv()''')
checks whether the first message header starts a batch and diverts the code
flow accordingly.

For batch handling, subsystems need to define '''commit''' and '''abort'''
callbacks. Also, for each contained message, there must be a responsible
callback entry with type '''NFNL_CB_BATCH'''. '''nf_tables_subsys''' fulfills
these requirements.

Each callback in '''nf_tables_cb''' (and therefore each supported message type)
decides whether it must be part of a batch or not - nfnetlink code does not
allow for multiple handlers of the same message. In nftables, only getters for
different ruleset elements are non-batch, anything mangling the ruleset is.

== Non-batched handlers ==

These are getters for:

* table
* chain
* rule
* set
* set element
* generation ID
* stateful objects
* flowtable

They all behave similar: Unless '''NLM_F_DUMP''' flag is set in the message,
they perform a lookup based on the required identifiers and return an nfnetlink
message to user space. There are type-specific helpers populating a netlink
message named '''nf_tables_fill_<SOMETHING>_info''', packet sending is done by
a call to '''nfnetlink_unicast()'''.

If '''NLM_F_DUMP''' was given, the getter iterates over all ruleset elements of
given type and fills a netlink message for each. In some cases, filtering the
output by identifiers given in the request is supported - useful to dump e.g.
all rules of a specific chain only.

The iterator code is a bit complicated due to the fact that socket buffer size
may be exceeded. In that case, partial data is submitted to user space and the
dump continued afterwards. The iterators keep a "cursor" (actually a counter)
for where to pick up again.

== Batched handlers ==

To allow for rolling back a transaction which has failed or was aborted,
message handlers of type '''NFNL_CB_BATCH''' allocate a '''struct nft_trans'''
object and add it to the per-net commit list. This "log" of what was done is
also useful to defer actions till the very end of the transaction. See
'''nf_tables_commit()''' for reference of what it is used for in the
success-case. Similar code is found in '''nf_tables_abort()''', reverting the
previous changes.

To make the ruleset update atomic, nftables uses an internal generation ID. Its
value alternates between zero and one upon each commit. Ruleset elements have a
two-bit "generation mask", indicating whether that element is active in the
generation at its bit index. This way, elements may die, get born or stay alive
when the generation ID toggles again.

Portal:DeveloperDocs/nftables internals

2022-09-13T12:24:08Z

Phil: /* nft: from userspace to the kernel */

Portal:DeveloperDocs/nftables internals

2022-05-19T16:47:17Z

Phil: Added section about libnftables

Portal:DeveloperDocs/nftables internals

2022-05-06T16:15:16Z

Phil: Add a description of libnftnl

Simple rule management

2022-04-08T09:16:46Z

Phil: nft requires options before commands nowadays

Rules take action on network packets (e.g. accepting or dropping them) based on whether they match specified criteria.

Each rule consists of zero or more expressions followed by one or more statements. Each expression tests whether a packet matches a specific payload field or packet/flow metadata. Multiple expressions are linearly evaluated from left to right: if the first expression matches, then the next expression is evaluated and so on. If we reach the final expression, then the packet matches all of the expressions in the rule, and the rule's statements are executed. Each statement takes an action, such as setting the netfilter mark, counting the packet, logging the packet, or rendering a verdict such as accepting or dropping the packet or jumping to another chain. As with expressions, multiple statements are linearly evaluated from left to right: a single rule can take multiple actions by using multiple statements. Do note that a verdict statement by its nature ends the rule.

Following are some basic operations and commands for configuring rules:

= 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 -n -a list table filter
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 -n -a list table filter
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 -a list table filter
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 flush 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, which you have to find by first listing the ruleset with option ''-a'':

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

To replace the rule with handle 2, specify its handle number and the new rule that you want to replace it:

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

Listing the ruleset after the above replacement:

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

you can see that the old rule that counted TCP packets has been replaced by the new rule that counts all packets.

Supported features compared to xtables

2022-03-11T17:34:00Z

Phil: Review the list, update details, add links to xlate-test cases for samples

Last update: Mar/2022

This page tracks the list of supported and unsupported extensions with comments and suggestions.

== Unsupported extensions ==

=== matches: xt ===

==== bpf ====
* consider native interface
==== rateest ====
* consider native interface
==== string ====
* consider native interface
==== u32 ====
* raw expressions?

=== targets: xt ===

==== CHECKSUM ====
* add nft_payload.
* To the day, the only use case for this was DHCP clients not working with partial checksums. That should be fixed nowadays.
* See https://lwn.net/Articles/396466/ and https://www.spinics.net/lists/kvm/msg37660.html
* See https://bugs.launchpad.net/ubuntu/+source/isc-dhcp/+bug/930962 and https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=832090

==== CT ====
* nft_ct_target. Refer to [[Matching_connection_tracking_stateful_metainformation]].
==== IDLETIMER ====
* consider native interface
==== LED ====
* consider native (need this?)
==== RATEEST ====
* consider native interface
==== TCPOPTSTRIP ====
* consider native interface, need to extend nft_exthdr.c

=== targets: ipv4 ===

==== TTL ====

=== targets: ipv6 ===

==== NPT ====
* consider native interface

=== targets: bridge ===

==== arpreply ====
* consider native interface

=== targets: arp ===

TODO

== Supported extensions ==

=== matches: xt ===

==== addrtype ====
* nft_fib, starting with 4.10 kernel. Refer to [[Matching routing information]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_addrtype.txlate Examples from iptables-translate testsuite]

==== cgroup ====
* nft_meta. Refer to [[Quick_reference-nftables_in_10_minutes#Meta]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_cgroup.txlate Examples from iptables-translate testsuite]
[Awaits support for cgroup2]

==== cluster ====
* nft_hash
* [https://git.netfilter.org/iptables/tree/extensions/libxt_cluster.txlate Examples from iptables-translate testsuite]

==== comment ====
* Built-in support via NFTA_RULE_USERDATA, since 3.15 (Pablo Neira). Refer to [[Matching_packet_headers#Matching_UDP.2FTCP_headers_in_the_same_rule|matching UDP/TCP headers in the same rule]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_comment.txlate Examples from iptables-translate testsuite]

==== connbytes ====
* nft_ct, 4.5 kernel. Refer to [[Meters]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_connbytes.txlate Examples from iptables-translate testsuite]
==== connlabel ====
* nft_meta, since 3.16.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_connlabel.txlate Examples from iptables-translate testsuite]
==== connlimit ====
* consider native interface. Refer to [[Meters]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_connlimit.txlate Examples from iptables-translate testsuite]
==== connmark ====
* nft_meta.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_connmark.txlate Examples from iptables-translate testsuite]
==== conntrack ====
* nft_ct.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_conntrack.txlate Examples from iptables-translate testsuite]
==== cpu ====
* nft_meta, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_cpu.txlate Examples from iptables-translate testsuite]
==== dccp ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_dccp.txlate Examples from iptables-translate testsuite]
[Unsupported option : dccp-option]
==== devgroup ====
* nft_meta, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_devgroup.txlate Examples from iptables-translate testsuite]
==== dscp ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_dscp.txlate Examples from iptables-translate testsuite]
==== ecn ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_ecn.txlate Examples from iptables-translate testsuite]
==== esp ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_esp.txlate Examples from iptables-translate testsuite]
==== hashlimit ====
* meter statement. Refer to [[Meters]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_hashlimit.txlate Examples from iptables-translate testsuite]
==== helper ====
* nft_ct.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_helper.txlate Examples from iptables-translate testsuite]
==== ipcomp ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_ipcomp.txlate Examples from iptables-translate testsuite]
[Unsupported option : compres]
==== iprange ====
* nft_payload, through native range support. To emulate iptables --ports you need two rules.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_iprange.txlate Examples from iptables-translate testsuite]
==== ipvs ====
* consider native interface. Refer to [[Load balancing]].
==== length ====
* nft_meta.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_length.txlate Examples from iptables-translate testsuite]
==== limit ====
* nft_limit. Refer to [[Stateful objects]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_limit.txlate Examples from iptables-translate testsuite]
==== mac ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_mac.txlate Examples from iptables-translate testsuite]
==== mark ====
* nft_meta.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_mark.txlate Examples from iptables-translate testsuite]
==== multiport ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_multiport.txlate Examples from iptables-translate testsuite]
==== nfacct ====
* consider native interface. Refer to [[Stateful objects]].
==== osf ====
* consider native interface
==== owner ====
* nft_meta.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_owner.txlate Examples from iptables-translate testsuite]
[Unsupported option : socket-exists]
==== pkttype ====
* nft_meta
* [https://git.netfilter.org/iptables/tree/extensions/libxt_pkttype.txlate Examples from iptables-translate testsuite]
==== policy ====
* nft_xfrm, since 5.0
* [https://git.netfilter.org/iptables/tree/extensions/libxt_policy.txlate Examples from iptables-translate testsuite]
==== recent ====
* consider native interface. Refer to [[Sets]].
==== sctp ====
* nft_payload
* nft_exthdr for --chunk-types
* [https://git.netfilter.org/iptables/tree/extensions/libxt_sctp.txlate Examples from iptables-translate testsuite]
==== socket ====
* consider native interface
==== statistic ====
* nft_numgen. Refer to [[Load balancing]].
* [https://git.netfilter.org/iptables/tree/extensions/libxt_statistic.txlate Examples from iptables-translate testsuite]
==== set ====
* Use native nf_tables set infrastructure.
==== state ====
* nft_ct
==== tcp ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libxt_tcp.txlate Examples from iptables-translate testsuite]
==== tcpmss ====
* nft_exthdr, since 4.14

==== time ====
* nft_meta, since 5.4
* [https://git.netfilter.org/iptables/tree/extensions/libxt_time.txlate Examples from iptables-translate testsuite]

==== udp ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libxt_udp.txlate Examples from iptables-translate testsuite]

=== targets: xt ===

==== AUDIT ====
* nft_log, since 4.18.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_AUDIT.txlate Examples from iptables-translate testsuite]
==== CLASSIFY ====
* nft_meta, since 3.14.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_CLASSIFY.txlate Examples from iptables-translate testsuite]
==== CONNMARK ====
* nft_ct
* [https://git.netfilter.org/iptables/tree/extensions/libxt_CONNMARK.txlate Examples from iptables-translate testsuite]
==== CONNSECMARK ====
* nft_ct, since 4.20
==== DSCP ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libxt_DSCP.txlate Examples from iptables-translate testsuite]
==== HL ====
* nft_payload
==== HMARK ====
* nft_meta + nft_hash.
==== MARK ====
* nft_meta, since 3.14.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_MARK.txlate Examples from iptables-translate testsuite]
==== NETMAP ====
* nft_nat, upcoming 5.8
==== NFLOG ====
* nft_log, since 3.17.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_NFLOG.txlate Examples from iptables-translate testsuite]
==== NFQUEUE ====
* nft_queue, since 3.14.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_NFQUEUE.txlate Examples from iptables-translate testsuite]
==== SECMARK ====
* nft_meta, since 4.20

==== SYNPROXY ====
* nft_synproxy, since 5.3
* [https://git.netfilter.org/iptables/tree/extensions/libxt_SYNPROXY.txlate Examples from iptables-translate testsuite]

==== TEE ====
* nft_dup, since 4.3.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_TEE.txlate Examples from iptables-translate testsuite]
==== TPROXY ====
* nft_tproxy, since 4.19

==== TRACE ====
* nft_meta, since 3.14.
* [https://git.netfilter.org/iptables/tree/extensions/libxt_TRACE.txlate Examples from iptables-translate testsuite]

==== TCPMSS ====
* nft_exthdr, since 4.14

=== matches: ipv4 ===

==== ah ====
* nft_payload + nft_cmp
* [https://git.netfilter.org/iptables/tree/extensions/libipt_ah.txlate Examples from iptables-translate testsuite]
==== icmp ====
* nft_payload + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_icmp.txlate Examples from iptables-translate testsuite]
[Unsupported codes: network-unreachable, host-unreachable, protocol-unreachable, port-unreachable, fragmentation-needed, source-route-failed, network-unknown, host-unknown, network-prohibited, host-prohibited, TOS-network-unreachable, TOS-host-unreachable, communication-prohibited, host-precedence-violation, precedence-cutoff, network-redirect, host-redirect, TOS-network-redirect, TOS-host-redirect, ttl-zero-during-transit, ttl-zero-during-reassembly, ip-header-bad and required-option-missing ]
==== realm ====
* nft_meta, through NFT_META_RTCLASSID.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_realm.txlate Examples from iptables-translate testsuite]
==== rp_filter ====
* nft_fib, starting with 4.10 kernel
==== ttl ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libipt_ttl.txlate Examples from iptables-translate testsuite]

=== matches: ipv6 ===

==== rp_filter ====
* nft_fib, starting with 4.10 kernel
==== ah ====
* nft_payload + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_ah.txlate Examples from iptables-translate testsuite]
==== eui64 ====
* nft_payload + nft_cmp.
==== frag ====
* nft_exthdr + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_frag.txlate Examples from iptables-translate testsuite]
==== hbh ====
* nft_exthdr + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_hbh.txlate Examples from iptables-translate testsuite]
HBH options are not supported yet.
[Unsupported option: --hbh-opts]
==== hl ====
* nft_payload.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_hl.txlate Examples from iptables-translate testsuite]
==== icmp6 ====
* nft_payload + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_icmp6.txlate Examples from iptables-translate testsuite]
[Unsupported icmpv6 codes: no-route, communication-prohibited, beyond-scope, address-unreachable, port-unreachable, failed-policy, reject-route, ttl-zero-during-transit, ttl-zero-during-reassembly, bad-header, unknown-header-type and unknown-option]
==== ipv6header ====
* nft_exthdr + nft_cmp.
==== mh ====
* nft_exthdr + nft_cmp.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_mh.txlate Examples from iptables-translate testsuite]
[Needs bug fixation for option mh-type with range]
==== rt ====
* nft_exthdr + nft_cmp
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_rt.txlate Examples from iptables-translate testsuite]
[Unsupported options: --rt-0-res, --rt-0-addrs, --rt-0-not-strict]

=== targets: ipv4 ===
==== ECN ====
* nft_payload

==== DNAT ====
* nft_nat, since 3.13.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_DNAT.txlate Examples from iptables-translate testsuite]
==== LOG ====
* nft_log, since 3.17.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_LOG.txlate Examples from iptables-translate testsuite]
[Unsupported options : log-tcp-sequence, log-tcp-options, log-ip-options, log-uid, log-macdecode]
==== MASQUERADE ====
* nft_masq, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_MASQUERADE.txlate Examples from iptables-translate testsuite]
==== REDIRECT ====
* nft_redirect, since 3.19.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_REDIRECT.txlate Examples from iptables-translate testsuite]

==== REJECT ====
* nft_reject_ipv4, since 3.13.
* nft_reject_inet, since 3.14.
* nft_reject_bridge, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_REJECT.txlate Examples from iptables-translate testsuite]
==== SNAT ====
* nft_nat, since 3.13.
* [https://git.netfilter.org/iptables/tree/extensions/libipt_SNAT.txlate Examples from iptables-translate testsuite]

=== targets: ipv6 ===
==== DNAT ====
* nft_nat, since 3.13.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_DNAT.txlate Examples from iptables-translate testsuite]
==== LOG ====
* nft_log, since 3.17.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_LOG.txlate Examples from iptables-translate testsuite]
[Unsupported options : log-tcp-sequence, log-tcp-options, log-ip-options, log-uid, log-macdecode]
==== MASQUERADE ====
* nft_masq, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_MASQUERADE.txlate Examples from iptables-translate testsuite]
==== REDIRECT ====
* nft_redirect, since 3.19.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_REDIRECT.txlate Examples from iptables-translate testsuite]

==== REJECT ====
* nft_reject_ipv6, since 3.14.
* nft_reject_inet, since 3.14.
* nft_reject_bridge, since 3.18.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_REJECT.txlate Examples from iptables-translate testsuite]
==== SNAT ====
* nft_nat, since 3.13.
* [https://git.netfilter.org/iptables/tree/extensions/libip6t_SNAT.txlate Examples from iptables-translate testsuite]

=== matches: bridge ===

==== 802.3 ====
* nft_payload

==== among ====
* sets

==== arp ====
* nft_payload

==== ip ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libebt_ip.txlate Examples from iptables-translate testsuite]

==== ip6 ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libebt_ip6.txlate Examples from iptables-translate testsuite]

==== limit ====
* nft_limit
* [https://git.netfilter.org/iptables/tree/extensions/libebt_limit.txlate Examples from iptables-translate testsuite]

==== mark ====
* nft_mark
* [https://git.netfilter.org/iptables/tree/extensions/libebt_mark_m.txlate Examples from iptables-translate testsuite]

==== pkttype ====
* nft_meta
* [https://git.netfilter.org/iptables/tree/extensions/libebt_pkttype.txlate Examples from iptables-translate testsuite]

==== stp ====
* nft_payload

==== vlan ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libebt_vlan.txlate Examples from iptables-translate testsuite]

=== targets: bridge ===

==== dnat ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libebt_dnat.txlate Examples from iptables-translate testsuite]

==== snat ====
* nft_payload
* [https://git.netfilter.org/iptables/tree/extensions/libebt_snat.txlate Examples from iptables-translate testsuite]

==== redirect ====
* nft_payload + nft_meta (pkttype set unicast)

==== mark ====
* nft_mark
* [https://git.netfilter.org/iptables/tree/extensions/libebt_mark.txlate Examples from iptables-translate testsuite]

=== watchers: bridge ===

==== log ====
* nft_log
* [https://git.netfilter.org/iptables/tree/extensions/libebt_log.txlate Examples from iptables-translate testsuite]

==== nflog ====
* nft_log
* [https://git.netfilter.org/iptables/tree/extensions/libebt_nflog.txlate Examples from iptables-translate testsuite]

== Deprecated extensions ==

=== matches ===

==== physdev ====
* br_netfilter aims to be deprecated by nftables.
==== quota ====
* nfacct already provides quota support.
==== tos ====
* deprecated by dscp

=== targets ===

==== CLUSTERIP ====
* deprecated by cluster match.
==== TOS ====
* deprecated by DSCP

=== targets: ipv4 ===

==== ULOG ====
* Removed from tree since 3.17.

Supported features compared to xtables

2022-03-10T17:40:13Z

Phil: Link to iptables-translate testsuite for examples, libebt_log.txlate only for now

Last update: Aug/2018

This page tracks the list of supported and unsupported extensions with comments and suggestions.

== Unsupported extensions ==

=== matches: xt ===

==== bpf ====
* consider native interface
==== cluster ====
* consider native interface
==== rateest ====
* consider native interface
==== string ====
* consider native interface
==== u32 ====
* raw expressions?

=== targets: xt ===

==== CHECKSUM ====
* add nft_payload.
* To the day, the only use case for this was DHCP clients not working with partial checksums. That should be fixed nowadays.
* See https://lwn.net/Articles/396466/ and https://www.spinics.net/lists/kvm/msg37660.html
* See https://bugs.launchpad.net/ubuntu/+source/isc-dhcp/+bug/930962 and https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=832090

==== CT ====
* nft_ct_target. Refer to [[Matching_connection_tracking_stateful_metainformation]].
==== IDLETIMER ====
* consider native interface
==== LED ====
* consider native (need this?)
==== RATEEST ====
* consider native interface
==== TCPOPTSTRIP ====
* consider native interface, need to extend nft_exthdr.c

=== targets: ipv4 ===

==== TTL ====

=== targets: ipv6 ===

==== NPT ====
* consider native interface

=== targets: bridge ===

==== arpreply ====
* consider native interface

=== watchers: bridge ===

==== log ====
* nft_log
* [https://git.netfilter.org/iptables/tree/extensions/libebt_log.txlate Examples from iptables-translate testsuite]

==== nflog ====
* nft_log

=== targets: arp ===

TODO

== Supported extensions ==

=== matches: xt ===

==== addrtype ====
* nft_fib, starting with 4.10 kernel. Refer to [[Matching routing information]].

==== cgroup ====
* nft_meta. Refer to [[Quick_reference-nftables_in_10_minutes#Meta]].
[Awaits support for cgroup2]
==== comment ====
* Built-in support via NFTA_RULE_USERDATA, since 3.15 (Pablo Neira). Refer to [[Matching_packet_headers#Matching_UDP.2FTCP_headers_in_the_same_rule|matching UDP/TCP headers in the same rule]].

==== connbytes ====
* nft_ct, 4.5 kernel. Refer to [[Meters]].
==== connlabel ====
* nft_meta, since 3.16.
==== connlimit ====
* consider native interface. Refer to [[Meters]].
==== connmark ====
* nft_meta.
==== conntrack ====
* nft_ct.
==== cpu ====
* nft_meta, since 3.18.
==== dccp ====
* nft_payload.
[Unsupported option : dccp-option]
==== devgroup ====
* nft_meta, since 3.18.
==== dscp ====
* nft_payload.
==== ecn ====
* nft_payload.
==== esp ====
* nft_payload.
==== hashlimit ====
* meter statement. Refer to [[Meters]].
==== helper ====
* nft_ct.
==== ipcomp ====
* nft_payload.
[Unsupported option : compres]
==== iprange ====
* nft_payload, through native range support. To emulate iptables --ports you need two rules.
==== ipvs ====
* consider native interface. Refer to [[Load balancing]].
==== length ====
* nft_meta.
==== limit ====
* nft_limit. Refer to [[Stateful objects]].
==== mac ====
* nft_payload.
==== mark ====
* nft_meta.
==== multiport ====
* nft_payload.
[Unsupported option : ports]
==== nfacct ====
* consider native interface. Refer to [[Stateful objects]].
==== osf ====
* consider native interface
==== owner ====
* nft_meta.
[Unsupported option : socket-exists]
==== pkttype ====
* nft_meta
==== policy ====
* nft_xfrm, since 5.0
==== recent ====
* consider native interface. Refer to [[Sets]].
==== sctp ====
* nft_payload
* nft_exthdr for --chunk-types
==== socket ====
* consider native interface
==== statistic ====
* nft_numgen. Refer to [[Load balancing]].
==== set ====
* Use native nf_tables set infrastructure.
==== state ====
* nft_ct
==== tcp ====
* nft_payload
==== tcpmss ====
* nft_exthdr, since 4.14

==== time ====
* nft_meta, since 5.4

==== udp ====
* nft_payload

=== targets: xt ===

==== AUDIT ====
* nft_log, since 4.18.
==== CLASSIFY ====
* nft_meta, since 3.14.
==== CONNMARK ====
* nft_ct
==== CONNSECMARK ====
* nft_ct, since 4.20
==== DSCP ====
==== HL ====
* nft_payload
==== HMARK ====
* nft_meta + nft_hash.
==== MARK ====
* nft_meta, since 3.14.
==== NETMAP ====
* nft_nat, upcoming 5.8
==== NFLOG ====
* nft_log, since 3.17.
==== NFQUEUE ====
* nft_queue, since 3.14.
==== SECMARK ====
* nft_meta, since 4.20

==== SYNPROXY ====
* nft_synproxy, since 5.3

==== TEE ====
* nft_dup, since 4.3.
==== TPROXY ====
* nft_tproxy, since 4.19

==== TRACE ====
* nft_meta, since 3.14.

==== TCPMSS ====
* nft_exthdr, since 4.14

=== matches: ipv4 ===

==== ah ====
* nft_payload + nft_cmp
==== icmp ====
* nft_payload + nft_cmp.
[Unsupported codes: network-unreachable, host-unreachable, protocol-unreachable, port-unreachable, fragmentation-needed, source-route-failed, network-unknown, host-unknown, network-prohibited, host-prohibited, TOS-network-unreachable, TOS-host-unreachable, communication-prohibited, host-precedence-violation, precedence-cutoff, network-redirect, host-redirect, TOS-network-redirect, TOS-host-redirect, ttl-zero-during-transit, ttl-zero-during-reassembly, ip-header-bad and required-option-missing ]
==== realm ====
* nft_meta, through NFT_META_RTCLASSID.
==== rp_filter ====
* nft_fib, starting with 4.10 kernel
==== ttl ====

=== matches: ipv6 ===

==== rp_filter ====
* nft_fib, starting with 4.10 kernel
==== ah ====
* nft_payload + nft_cmp.
==== eui64 ====
* nft_payload + nft_cmp.
==== frag ====
* nft_exthdr + nft_cmp.
==== hbh ====
* nft_exthdr + nft_cmp.
HBH options are not supported yet.
[Unsupported option: --hbh-opts]
==== hl ====
* nft_payload.
==== icmp6 ====
* nft_payload + nft_cmp.
[Unsupported icmpv6 codes: no-route, communication-prohibited, beyond-scope, address-unreachable, port-unreachable, failed-policy, reject-route, ttl-zero-during-transit, ttl-zero-during-reassembly, bad-header, unknown-header-type and unknown-option]
==== ipv6header ====
* nft_exthdr + nft_cmp.
==== mh ====
* nft_exthdr + nft_cmp.
[Needs bug fixation for option mh-type with range]
==== rt ====
* nft_exthdr + nft_cmp
[Unsupported options: --rt-0-res, --rt-0-addrs, --rt-0-not-strict]

=== targets: ipv4 ===
==== ECN ====
* nft_payload

==== DNAT ====
* nft_nat, since 3.13.
==== LOG ====
* nft_log, since 3.17.
[Unsupported options : log-tcp-sequence, log-tcp-options, log-ip-options, log-uid, log-macdecode]
==== MASQUERADE ====
* nft_masq, since 3.18.
==== REDIRECT ====
* nft_redirect, since 3.19.

==== REJECT ====
* nft_reject_ipv4, since 3.13.
* nft_reject_inet, since 3.14.
* nft_reject_bridge, since 3.18.
==== SNAT ====
* nft_nat, since 3.13.

=== targets: ipv6 ===
==== DNAT ====
* nft_nat, since 3.13.
==== LOG ====
* nft_log, since 3.17.
[Unsupported options : log-tcp-sequence, log-tcp-options, log-ip-options, log-uid, log-macdecode]
==== MASQUERADE ====
* nft_masq, since 3.18.
==== REDIRECT ====
* nft_redirect, since 3.19.

==== REJECT ====
* nft_reject_ipv6, since 3.14.
* nft_reject_inet, since 3.14.
* nft_reject_bridge, since 3.18.
==== SNAT ====
* nft_nat, since 3.13.

=== matches: bridge ===

==== 802.3 ====
* nft_payload

==== among ====
* sets

==== arp ====
* nft_payload

==== ip ====
* nft_payload

==== ip6 ====
* nft_payload

==== limit ====
* nft_limit

==== mark ====
* nft_mark

==== pkttype ====
* nft_meta

==== stp ====
* nft_payload

==== vlan ====
* nft_payload

=== targets: bridge ===

==== dnat ====
* nft_payload

==== snat ====
* nft_payload

==== redirect ====
* nft_payload + nft_meta (pkttype set unicast)

==== mark ====
* nft_mark

== Deprecated extensions ==

=== matches ===

==== physdev ====
* br_netfilter aims to be deprecated by nftables.
==== quota ====
* nfacct already provides quota support.
==== tos ====
* deprecated by dscp

=== targets ===

==== CLUSTERIP ====
* deprecated by cluster match.
==== TOS ====
* deprecated by DSCP

=== targets: ipv4 ===

==== ULOG ====
* Removed from tree since 3.17.

Counters

2021-06-10T13:32:13Z

Phil: /* Resetting named counters */ Added workaround to reset anonymous counters

A counter counts both the total number of packets and the total bytes it has seen since it was last reset. With nftables you need to explicitly specify a counter for each rule you want to count.

= Anonymous counters =

An anonymous counter is local to the single rule in which it appears. The following example uses an anonymous counter to count all tcp traffic routed to the local host:

<source>
table ip counter_demo {
chain IN {
type filter hook input priority filter; policy drop;

protocol tcp counter
}
}
</source>

'''Note''' that the position of the ''counter'' statement within your rule is significant, because nftables evaluates expressions and statements linearly from left to right. If the above rule were written instead:
<source>
counter protocol tcp
</source>

then '''every packet''' routed to your host (not just tcp packets) will update the counter!

= Named counters =

== Declaring and using named counters ==

You can also declare named counters, which can be used in multiple rules, e.g.:
<source>
table inet named_counter_demo {

counter cnt_http {
}

counter cnt_smtp {
}

chain IN {
type filter hook input priority filter; policy drop;

tcp dport 25 counter name cnt_smtp
tcp dport 80 counter name cnt_http
tcp dport 443 counter name cnt_http
}
}
</source>

The above example defines two counters named ''cnt_http'' and ''cnt_smtp'' and uses them in rules to count http(s) and smtp packets routed to the local host. (This example is contrived to show using a single named counter in multiple rules; the two rules using cnt_http can easily be combined by using an anonymous [[Sets|set]].)

== Listing / reading named counters ==

=== Listing named counters from nft command line ===

''nft list [counter | counters]'' (as per below) returns the current value(s) of the selected counter(s).

* List a particular counter:
<source>
% nft list counter inet named_counter_demo cnt_http
</source>

* List all counters in a particular table:
<source>
% nft list counters table inet named_counter_demo
</source>

* List all counters in ruleset:
<source>
% nft list counters
</source>

=== Reading named counters from Python ===

The following partial ruleset (note the absence of a [[Configuring_chains#Adding_base_chains|base chain]]) defines two named counters ''voip1'' and ''voip2'' and uses them to count VoIP traffic to udp/5160 and udp/5161. The commented-out rules show how to do this in simple fashion, while the 2 final rules in the ''FORWARD'' chain do the same thing using the ''voipcounters'' [[Maps|map]]. The approach using the map becomes increasingly advantageous when more ports (map elements) are added.

<source>
define ipvoipbox=192.168.0.8

table ip filter {
counter voip1 {
}
counter voip2 {
}
map voipcounters {
type inet_service : counter
elements = {
5160 : "voip1",
5161 : "voip2"
}
}
chain FORWARD {
#ip saddr $ipvoipbox udp dport 5160 counter name voip1 comment "counting packets for SIP1"
#ip daddr $ipvoipbox udp dport 5160 counter name voip1 comment "counting packets for SIP1"
#ip saddr $ipvoipbox udp sport 5161 counter name voip2 comment "counting packets for SIP2"
#ip daddr $ipvoipbox udp dport 5161 counter name voip2 comment "counting packets for SIP2"
ip saddr $ipvoipbox counter name udp sport map @voipcounters
ip daddr $ipvoipbox counter name udp dport map @voipcounters
}
}
</source>

We can read current counter values from [[Scripting#Using_nftables_from_Python|Python using the libnftables library]]:

<source>
from nftables import Nftables
from nftables import json

def getCounter(countername, family='ip'):
nft = Nftables()
nft.set_json_output(True)
_, output, _ = nft.cmd(f"list counter {family} filter {countername}")
j = json.loads(output)
return j['nftables'][1]["counter"]["bytes"]

print(getCounter('voip1'), 'bytes')
print(getCounter('voip2'), 'bytes')
</source>

== Resetting named counters ==

Resetting a counter dumps its current packet and byte counts and then resets the counts to their initial values.

* Reset a particular counter:
<source>
% nft reset counter inet named_counter_demo cnt_http
</source>

* Reset all counters in a particular table:
<source>
% nft reset counters table inet named_counter_demo
</source>

* Reset all counters in ruleset:
<source>
% nft reset counters
</source>

'''Note:''' Resetting counters does not reset anonymous counters, see [https://bugzilla.netfilter.org/show_bug.cgi?id=1401 bug #1401].
A workaround to achieve that is to restore the current ruleset with all stateful information dropped:
<source>
% (echo "flush ruleset"; nft --stateless list ruleset) | nft -f -
</source>
Obviously, this drops all state so might have undesired side-effects, like, e.g. resetting quotas.

Quick reference-nftables in 10 minutes

2021-05-21T14:23:30Z

Phil: /* Sctp */ added 'sctp chunk' docs

Find below some basic concepts to know before using nftables.

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

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

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

= nft command line =

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

== Tables ==

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

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

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

== Chains ==

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

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

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

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

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

'''policy''' is the default verdict statement to control the flow in the chain. Possible values are: ''accept'', ''drop'', ''queue'', ''continue'', ''return''.

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

== Rules ==

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

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

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

=== Matches ===

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

==== Ip ====

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

==== Ip6 ====

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

==== Tcp ====

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

==== Udp ====

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

==== Udplite ====

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

==== Sctp ====

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

==== Dccp ====

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

==== Ah ====

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

==== Esp ====

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

==== Comp ====

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

==== Icmp ====

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

==== Icmpv6 ====

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

==== Ether ====

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

==== Dst ====

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

==== Frag ====

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

==== Hbh ====

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

==== Mh ====

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

==== Rt ====

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

==== Vlan ====

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

==== Arp ====

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

==== Ct ====

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

==== Meta ====

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

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

=== Statements ===

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

==== Verdict statements ====

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

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

==== Log ====

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

==== Reject ====

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

More information on the [[Rejecting_traffic]] page.

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

==== Counter ====

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

==== Limit ====

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

==== Nat ====

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

==== Queue ====

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

== Extras ==

=== Export Configuration ===

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

=== Monitor Events ===

Monitor events from Netlink creating filters.

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

= Nft scripting =

== List ruleset ==

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

== Flush ruleset ==

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

== Load ruleset ==

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

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

or create an executable nft script file,

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

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

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

= Examples =

== Simple IP/IPv6 Firewall ==

<source lang="bash">
flush ruleset

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

# established/related connections
ct state established,related accept

# loopback interface
iifname lo accept

# icmp
icmp type echo-request accept

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

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

# established/related connections
ct state established,related accept

# invalid connections
ct state invalid drop

# loopback interface
iifname lo accept

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

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

Supported features compared to xtables

2021-05-21T14:15:28Z

Phil: chunk-types match is supported now

Last update: Aug/2018

This page tracks the list of supported and unsupported extensions with comments and suggestions.

== Unsupported extensions ==

=== matches: xt ===

==== bpf ====
* consider native interface
==== cluster ====
* consider native interface
==== rateest ====
* consider native interface
==== string ====
* consider native interface
==== u32 ====
* raw expressions?

=== targets: xt ===

==== CHECKSUM ====
* add nft_payload.
* To the day, the only use case for this was DHCP clients not working with partial checksums. That should be fixed nowadays.
* See https://lwn.net/Articles/396466/ and https://www.spinics.net/lists/kvm/msg37660.html
* See https://bugs.launchpad.net/ubuntu/+source/isc-dhcp/+bug/930962 and https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=832090

==== CT ====
* nft_ct_target. Refer to [[Matching_connection_tracking_stateful_metainformation]].
==== IDLETIMER ====
* consider native interface
==== LED ====
* consider native (need this?)
==== RATEEST ====
* consider native interface
==== TCPOPTSTRIP ====
* consider native interface, need to extend nft_exthdr.c

=== targets: ipv4 ===

==== TTL ====

=== targets: ipv6 ===

==== NPT ====
* consider native interface

=== targets: bridge ===

==== arpreply ====
* consider native interface

=== watchers: bridge ===

==== log ====
* nft_log

==== nflog ====
* nft_log

=== targets: arp ===

TODO

== Supported extensions ==

=== matches: xt ===

==== addrtype ====
* nft_fib, starting with 4.10 kernel. Refer to [[Matching routing information]].

==== cgroup ====
* nft_meta. Refer to [[Quick_reference-nftables_in_10_minutes#Meta]].
[Awaits support for cgroup2]
==== comment ====
* Built-in support via NFTA_RULE_USERDATA, since 3.15 (Pablo Neira). Refer to [[Matching_packet_headers#Matching_UDP.2FTCP_headers_in_the_same_rule|matching UDP/TCP headers in the same rule]].

==== connbytes ====
* nft_ct, 4.5 kernel. Refer to [[Meters]].
==== connlabel ====
* nft_meta, since 3.16.
==== connlimit ====
* consider native interface. Refer to [[Meters]].
==== connmark ====
* nft_meta.
==== conntrack ====
* nft_ct.
==== cpu ====
* nft_meta, since 3.18.
==== dccp ====
* nft_payload.
[Unsupported option : dccp-option]
==== devgroup ====
* nft_meta, since 3.18.
==== dscp ====
* nft_payload.
==== ecn ====
* nft_payload.
==== esp ====
* nft_payload.
==== hashlimit ====
* meter statement. Refer to [[Meters]].
==== helper ====
* nft_ct.
==== ipcomp ====
* nft_payload.
[Unsupported option : compres]
==== iprange ====
* nft_payload, through native range support. To emulate iptables --ports you need two rules.
==== ipvs ====
* consider native interface. Refer to [[Load balancing]].
==== length ====
* nft_meta.
==== limit ====
* nft_limit. Refer to [[Stateful objects]].
==== mac ====
* nft_payload.
==== mark ====
* nft_meta.
==== multiport ====
* nft_payload.
[Unsupported option : ports]
==== nfacct ====
* consider native interface. Refer to [[Stateful objects]].
==== osf ====
* consider native interface
==== owner ====
* nft_meta.
[Unsupported option : socket-exists]
==== pkttype ====
* nft_meta
==== policy ====
* nft_xfrm, since 5.0
==== recent ====
* consider native interface. Refer to [[Sets]].
==== sctp ====
* nft_payload
* nft_exthdr for --chunk-types
==== socket ====
* consider native interface
==== statistic ====
* nft_numgen. Refer to [[Load balancing]].
==== set ====
* Use native nf_tables set infrastructure.
==== state ====
* nft_ct
==== tcp ====
* nft_payload
==== tcpmss ====
* nft_exthdr, since 4.14

==== time ====
* nft_meta, since 5.4

==== udp ====
* nft_payload

=== targets: xt ===

==== AUDIT ====
* nft_log, since 4.18.
==== CLASSIFY ====
* nft_meta, since 3.14.
==== CONNMARK ====
* nft_ct
==== CONNSECMARK ====
* nft_ct, since 4.20
==== DSCP ====
==== HL ====
* nft_payload
==== HMARK ====
* nft_meta + nft_hash.
==== MARK ====
* nft_meta, since 3.14.
==== NETMAP ====
* nft_nat, upcoming 5.8
==== NFLOG ====
* nft_log, since 3.17.
==== NFQUEUE ====
* nft_queue, since 3.14.
==== SECMARK ====
* nft_meta, since 4.20

==== SYNPROXY ====
* nft_synproxy, since 5.3

==== TEE ====
* nft_dup, since 4.3.
==== TPROXY ====
* nft_tproxy, since 4.19

==== TRACE ====
* nft_meta, since 3.14.

==== TCPMSS ====
* nft_exthdr, since 4.14

=== matches: ipv4 ===

==== ah ====
* nft_payload + nft_cmp
==== icmp ====
* nft_payload + nft_cmp.
[Unsupported codes: network-unreachable, host-unreachable, protocol-unreachable, port-unreachable, fragmentation-needed, source-route-failed, network-unknown, host-unknown, network-prohibited, host-prohibited, TOS-network-unreachable, TOS-host-unreachable, communication-prohibited, host-precedence-violation, precedence-cutoff, network-redirect, host-redirect, TOS-network-redirect, TOS-host-redirect, ttl-zero-during-transit, ttl-zero-during-reassembly, ip-header-bad and required-option-missing ]
==== realm ====
* nft_meta, through NFT_META_RTCLASSID.
==== rp_filter ====
* nft_fib, starting with 4.10 kernel
==== ttl ====

=== matches: ipv6 ===

==== rp_filter ====
* nft_fib, starting with 4.10 kernel
==== ah ====
* nft_payload + nft_cmp.
==== eui64 ====
* nft_payload + nft_cmp.
==== frag ====
* nft_exthdr + nft_cmp.
==== hbh ====
* nft_exthdr + nft_cmp.
HBH options are not supported yet.
[Unsupported option: --hbh-opts]
==== hl ====
* nft_payload.
==== icmp6 ====
* nft_payload + nft_cmp.
[Unsupported icmpv6 codes: no-route, communication-prohibited, beyond-scope, address-unreachable, port-unreachable, failed-policy, reject-route, ttl-zero-during-transit, ttl-zero-during-reassembly, bad-header, unknown-header-type and unknown-option]
==== ipv6header ====
* nft_exthdr + nft_cmp.
==== mh ====
* nft_exthdr + nft_cmp.
[Needs bug fixation for option mh-type with range]
==== rt ====
* nft_exthdr + nft_cmp
[Unsupported options: --rt-0-res, --rt-0-addrs, --rt-0-not-strict]

=== targets: ipv4 ===
==== ECN ====
* nft_payload

==== DNAT ====
* nft_nat, since 3.13.
==== LOG ====
* nft_log, since 3.17.
[Unsupported options : log-tcp-sequence, log-tcp-options, log-ip-options, log-uid, log-macdecode]
==== MASQUERADE ====
* nft_masq, since 3.18.
==== REDIRECT ====
* nft_redirect, since 3.19.

==== REJECT ====
* nft_reject_ipv4, since 3.13.
* nft_reject_inet, since 3.14.
* nft_reject_bridge, since 3.18.
==== SNAT ====
* nft_nat, since 3.13.

=== targets: ipv6 ===
==== DNAT ====
* nft_nat, since 3.13.
==== LOG ====
* nft_log, since 3.17.
[Unsupported options : log-tcp-sequence, log-tcp-options, log-ip-options, log-uid, log-macdecode]
==== MASQUERADE ====
* nft_masq, since 3.18.
==== REDIRECT ====
* nft_redirect, since 3.19.

==== REJECT ====
* nft_reject_ipv6, since 3.14.
* nft_reject_inet, since 3.14.
* nft_reject_bridge, since 3.18.
==== SNAT ====
* nft_nat, since 3.13.

=== matches: bridge ===

==== 802.3 ====
* nft_payload

==== among ====
* sets

==== arp ====
* nft_payload

==== ip ====
* nft_payload

==== ip6 ====
* nft_payload

==== limit ====
* nft_limit

==== mark ====
* nft_mark

==== pkttype ====
* nft_meta

==== stp ====
* nft_payload

==== vlan ====
* nft_payload

=== targets: bridge ===

==== dnat ====
* nft_payload

==== snat ====
* nft_payload

==== redirect ====
* nft_payload + nft_meta (pkttype set unicast)

==== mark ====
* nft_mark

== Deprecated extensions ==

=== matches ===

==== physdev ====
* br_netfilter aims to be deprecated by nftables.
==== quota ====
* nfacct already provides quota support.
==== tos ====
* deprecated by dscp

=== targets ===

==== CLUSTERIP ====
* deprecated by cluster match.
==== TOS ====
* deprecated by DSCP

=== targets: ipv4 ===

==== ULOG ====
* Removed from tree since 3.17.

Performing Network Address Translation (NAT)

2019-11-27T12:50:41Z

Phil: fixed prerouting priority ** added inet nat support note ** corrected warning about prerouting/postrouting base-chain need in older kernels

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. So make sure that the ''iptable_nat'' module is unloaded:

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

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

Setting packet connection tracking metainformation

2019-04-18T08:46:13Z

Phil: corrected typo "ftp-standar" -> "ftp-standard"

You can set some bits of the packet conntrack metainformation, apart of [[Matching connection tracking stateful metainformation | matching on it]].

== notrack ==

You can use the '''notrack''' support to explicitly skip connection tracking for matching packets.

The example below skips traffic for 80/tcp and 443/tcp:

<source lang="bash">
nft add rule ip raw prerouting tcp dport { 80, 443 } notrack
</source>

Please, note that you should use notrack before the kernel connection tracking is triggered.
Use a chain with priority -300. Example:

<source lang="bash">
nft add table raw
nft add chain raw prerouting { type filter hook prerouting priority -300 \; }
nft add rule raw prerouting tcp dport 80 notrack
</source>

Support for this was added in linux kernel 4.9 and in nftables v0.7.

== helpers ==

You can assign each packet a conntrack helper.

Instantiate a helper, using a named object:

<source>
table filter {
ct helper sip-5060 {
type "sip" protocol udp;
}

ct helper ftp-standard {
type "ftp" protocol tcp;
}

chain c {
}
}
</source>

Then, from the rules:

<source>
nft add rule filter filter c udp dport 5060 ct helper set "sip-5060"
</source>

You can of course use a dictionary, one single rule to assign many helpers:

<source>
nft add rule x y ct helper set udp dport map { \
69 : "tftp-69", \
5060 : "sip-5060" }
</source>

You need nftables >= 0.8 and the kernel >= 4.12 to use this feature.

In case of a previous version of nftables, you can can set automatic assignement with:

<source>
echo 1 > /proc/sys/net/netfilter/nf_conntrack_helper
</source>

Also, with the sysctl parameter:

<source>
net.netfilter.nf_conntrack_helper = 1
</source>

Sets

2016-11-24T11:27:21Z

Phil: Fixed typo: dport 22 -> dport 23

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

= Named sets =

You can create the named sets with the following command:

<source lang="bash">
% nft add set 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 the case. Current maximum name length is 16 characters.

<source lang="bash">
% nft add element filter blackhole { 192.168.3.4 }
% nft add element 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 input ip saddr @blackhole drop
</source>

The supported data types currently 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.

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

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>

= Listing named sets =

You can list the content of a named set via:

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