nftables syntax¶

Synopsis¶

nft [OPTIONS] COMMAND OBJECT [FAMILY] [TABLE [CHAIN]] [SPECIFICATION]
nft [OPTIONS] -f FILE
nft [OPTIONS] -i

ruleset ─┬─ table <family> <name>
         │    ├─ chain <name>        (base chain: type, hook, priority, policy)
         │    │    └─ rule           (expressions … statement)
         │    ├─ chain <name>        (regular chain: jump/goto target)
         │    ├─ set <name>
         │    ├─ map <name>
         │    └─ stateful objects    (counter, quota, limit, ct helper, …)
         └─ table <family> <name> …

Description¶

nft is the userspace command of nftables, the packet classification framework of the Linux kernel (the kernel side is called nf_tables). It parses commands or a ruleset file, compiles them into nf_tables bytecode, and sends them to the kernel over netlink. Every change made by one nft invocation, including a whole file, is applied as a single atomic transaction. Rules exist only in kernel memory: they are lost on reboot unless a service loads them from a file at boot.

nft needs the CAP_NET_ADMIN capability, so it is normally run as root or with sudo. On Debian, nft is installed in /usr/sbin, which isn't in an unprivileged user's PATH.

Checked against nftables 1.1.3 on Debian 13, 1.1.6 on Ubuntu 26.04, 1.1.5 on AlmaLinux 10 and Rocky Linux 10, and 1.1.7 on Arch Linux and Gentoo (November 2026).

Address families¶

Every table belongs to one address family, which determines the packets it sees and the hooks its chains can use. When a command omits the family, ip is assumed.

Tables¶

{add | create} table [FAMILY] NAME [{ [comment "TEXT";] [flags FLAGS;] }]
{delete | destroy | list | flush} table [FAMILY] NAME
list tables [FAMILY]
delete table [FAMILY] handle HANDLE

A table is a namespace for chains, sets, maps and stateful objects. Tables have no hook or priority of their own; only base chains do.

Chains¶

{add | create} chain [FAMILY] TABLE NAME [{ type TYPE hook HOOK [device DEV] priority PRIORITY; [policy POLICY;] [comment "TEXT";] }]
{delete | destroy | list | flush} chain [FAMILY] TABLE NAME
rename chain [FAMILY] TABLE NAME NEWNAME
list chains [FAMILY]

A base chain has type, hook and priority and is attached to a netfilter hook, so packets enter it. A regular chain has none of these; packets reach it only by jump or goto from another chain. add chain on an existing base chain with only { policy POLICY; } changes its policy.

On the command line, the braces and semicolons must be protected from the shell, for example by single quotes:

nft add chain inet filter input '{ type filter hook input priority filter; policy drop; }'

Chain types¶

Base chains in the netdev family, and ingress chains in the inet family, also need device "NAME" (or devices = { "NAME", … }).

Priorities¶

priority is a signed integer or a standard name. On each hook, chains run in ascending priority order, whatever table they are in; the order of chains with equal priority is undefined. A name may be offset by addition or subtraction, for example filter - 5. nat chains must have a priority greater than -200 (the priority of connection tracking).

The bridge family uses different values: dstnat -300 (prerouting), filter -200 (all), out 100 (output), srcnat 300 (postrouting).

Policies¶

Regular chains have no policy; at their end, evaluation returns to the calling chain.

Rules¶

{add | insert} rule [FAMILY] TABLE CHAIN [handle HANDLE | index INDEX] MATCH… STATEMENT… [comment "TEXT"]
replace rule [FAMILY] TABLE CHAIN handle HANDLE MATCH… STATEMENT… [comment "TEXT"]
{delete | reset} rule [FAMILY] TABLE CHAIN handle HANDLE

Each rule has a numeric handle, shown by nft -a list …. Within a rule, matches are evaluated left to right and all must be true; the statements then run in order. A rule with no match applies to every packet. Rules in a chain are evaluated top to bottom until a verdict ends evaluation of the chain.

Operators and values¶

Common matches¶

iif fails to load if the interface doesn't exist; iifname works for interfaces created later, at a small cost per packet.

Statements¶

Verdicts¶

reject is valid only in base chains on the prerouting, input, forward and output hooks, and in regular chains called only from them.

Other statements¶

Statements are non-terminal unless they are verdicts, so counter, log and limit are usually combined with one: tcp dport 22 limit rate 10/minute counter accept.

Sets and maps¶

add set [FAMILY] TABLE NAME { type TYPE | typeof EXPRESSION; [flags FLAGS;] [timeout TIME;] [size N;] [elements = { … };] }
add map [FAMILY] TABLE NAME { type TYPE : TYPE | typeof EXPRESSION : EXPRESSION; [flags FLAGS;] [elements = { KEY : VALUE, … };] }
{add | delete | destroy} element [FAMILY] TABLE SET { ELEMENT, … }
{list | flush | delete} {set | map} [FAMILY] TABLE NAME

Common element types:

The nft command¶

Commands¶

Options¶

Ruleset file¶

A ruleset file uses the same syntax as nft list ruleset prints, so a listing can be saved and loaded back. Loading a file with nft -f is one transaction: if any line fails, none of it is applied.

#!/usr/sbin/nft -f

# Start from an empty ruleset, so reloading doesn't duplicate rules.
flush ruleset

define ssh_port = 22
define admins_v4 = { 192.0.2.0/24 }
define admins_v6 = { 2001:db8:10::/48 }

table inet filter {
    set blocklist {
        type ipv4_addr
        flags interval
        elements = { 198.51.100.0/24 }
    }

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

        ct state vmap { established : accept, related : accept, invalid : drop }
        iif lo accept
        ip saddr @blocklist counter drop
        meta l4proto { icmp, ipv6-icmp } accept
        tcp dport $ssh_port accept
        ip saddr $admins_v4 tcp dport 8080 accept
        ip6 saddr $admins_v6 tcp dport 8080 accept
    }

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

    chain output {
        type filter hook output priority filter; policy accept;
    }
}

include "/etc/nftables.d/*.nft"

A set holds elements of one type, so IPv4 and IPv6 addresses need separate sets, variables and rules, as with $admins_v4 and $admins_v6 above.

Files¶

On Debian, Ubuntu and RHEL, nftables.service runs nft -f on its file when it starts or reloads, and flushes the whole ruleset when it stops. On Arch, the unit only runs nft -f /etc/nftables.conf when it starts; it has no reload or stop action. On RHEL and its rebuilds, firewalld is the default firewall and nftables.service is normally disabled; enabling both makes them overwrite each other's rules.

See also¶

• nft(8), libnftables-json(5) (nftables 1.1.x)
• nftables wiki
• nftables releases
• Netfilter architecture for hooks, priorities and connection tracking in context

Related¶

• Tutorial: Build your first nftables firewall
• How-to: How to open a port in the firewall
• Explanation: Netfilter architecture