'\" t -*- coding: us-ascii -*-

.if \n(.g .ds T< \\FC

.if \n(.g .ds T> \\F[\n[.fam]]

.de URL

\\$2 \(la\\$1\(ra\\$3

..

.if \n(.g .mso www.tmac

.TH nft 8 "4 April 2019" "" ""

.SH NAME

nft \- Administration tool for packet filtering and classification 

.SH SYNOPSIS

'nh

.fi

.ad l

\fBnft\fR \kx

.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)

'in \n(.iu+\nxu

[\fB-n\fR | \fB--numeric\fR] [\fB-N\fR | \fB--reversedns\fR] [\fB-s\fR | \fB--stateless\fR] [\fB-c\fR | \fB--check\fR] [\fB-a\fR | \fB--handle\fR] [\fB-e\fR | \fB--echo\fR] [

{\fB-I\fR | \fB--includepath\fR}

\fIdirectory\fR

] [

{\fB-f\fR | \fB--file\fR}

\fIfilename\fR

| 

{\fB-i\fR | \fB--interactive\fR}

| 

\fIcmd\fR

\&...]

'in \n(.iu-\nxu

.ad b

'hy

'nh

.fi

.ad l

\fBnft\fR \kx

.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)

'in \n(.iu+\nxu

[\fB-h\fR | \fB--help\fR] [\fB-v\fR | \fB--version\fR]

'in \n(.iu-\nxu

.ad b

'hy

.SH DESCRIPTION

nft is used to set up, maintain and inspect packet

filtering and classification rules in the Linux kernel.

.SH OPTIONS

For a full summary of options, run \fBnft --help\fR.

.TP 

\*(T<\fB\-h, \-\-help\fR\*(T>

Show help message and all options.

.TP 

\*(T<\fB\-v, \-\-version\fR\*(T>

Show version.

.TP 

\*(T<\fB\-n, \-\-numeric\fR\*(T>

Show data numerically. When used once (the default behaviour), skip

lookup of addresses to symbolic names. Use twice to also show Internet

services (port numbers) numerically. Use three times to also show

protocols and UIDs/GIDs numerically.

.TP 

\*(T<\fB\-s, \-\-stateless\fR\*(T>

Omit stateful information of rules and stateful objects.

.TP 

\*(T<\fB\-c, \-\-check\fR\*(T>

Check commands validity without actually applying the changes.

.TP 

\*(T<\fB\-N, \-\-reversedns\fR\*(T>

Translate IP addresses to names. Usually requires network traffic for DNS lookup.

.TP 

\*(T<\fB\-a, \-\-handle\fR\*(T>

Show rule handles in output.

.TP 

\*(T<\fB\-e, \-\-echo\fR\*(T>

When inserting items into the ruleset using \fBadd\fR,

\fBinsert\fR or \fBreplace\fR commands,

print notifications just like \fBnft monitor\fR.

.TP 

\*(T<\fB\-I, \-\-includepath \fR\*(T>\fIdirectory\fR

Add the directory \fIdirectory\fR to the list of directories to be searched for included files. This option may be specified multiple times.

.TP 

\*(T<\fB\-f, \-\-file \fR\*(T>\fIfilename\fR

Read input from \fIfilename\fR.

.TP 

\*(T<\fB\-i, \-\-interactive\fR\*(T>

Read input from an interactive readline CLI.

.SH "INPUT FILE FORMAT"

.SS "LEXICAL CONVENTIONS"

Input is parsed line-wise. When the last character of a line, just before

the newline character, is a non-quoted backslash (\*(T<\e\*(T>),

the next line is treated as a continuation. Multiple commands on the

same line can be separated using a semicolon (\*(T<;\*(T>).

.PP

A hash sign (\*(T<#\*(T>) begins a comment. All following characters

on the same line are ignored.

.PP

Identifiers begin with an alphabetic character (\*(T<a\-z,A\-Z\*(T>),

followed zero or more alphanumeric characters (\*(T<a\-z,A\-Z,0\-9\*(T>)

and the characters slash (\*(T</\*(T>), backslash (\*(T<\e\*(T>),

underscore (\*(T<_\*(T>) and dot (\*(T<.\*(T>). Identifiers

using different characters or clashing with a keyword need to be enclosed in

double quotes (\*(T<"\*(T>).

.PP

.SS "INCLUDE FILES"

'nh

.fi

.ad l

\fBinclude\fR \kx

.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)

'in \n(.iu+\nxu

\fIfilename\fR

'in \n(.iu-\nxu

.ad b

'hy

.PP

Other files can be included by using the \fBinclude\fR statement.

The directories to be searched for include files can be specified using

the \*(T<\fB\-I/\-\-includepath\fR\*(T> option. You can override this behaviour

either by prepending ./ to your path to force inclusion of files located in the

current working directory (ie. relative path) or / for file location expressed

as an absolute path.

.PP

If -I/--includepath is not specified, then nft relies on the default directory

that is specified at compile time. You can retrieve this default directory via

-h/--help option.

.PP

Include statements support the usual shell wildcard symbols

(\*(T<*,?,[]\*(T>). Having no matches for an include statement is not

an error, if wildcard symbols are used in the include statement. This allows having

potentially empty include directories for statements like

\*(T<include "/etc/firewall/rules/*"\*(T>. The wildcard matches are

loaded in alphabetical order. Files beginning with dot (\*(T<.\*(T>) are

not matched by include statements.

.SS "SYMBOLIC VARIABLES"

'nh

.fi

.ad l

\fBdefine\fR \kx

.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)

'in \n(.iu+\nxu

variable \fIexpr\fR

'in \n(.iu-\nxu

.ad b

'hy

'nh

.fi

.ad l

\fB$variable\fR \kx

.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)

'in \n(.iu+\nxu

'in \n(.iu-\nxu

.ad b

'hy

.PP

Symbolic variables can be defined using the \fBdefine\fR statement.

Variable references are expressions and can be used initialize other variables.

The scope of a definition is the current block and all blocks contained within.

\fBUsing symbolic variables\fR

.PP

.nf

\*(T<

define int_if1 = eth0

define int_if2 = eth1

define int_ifs = { $int_if1, $int_if2 }

filter input iif $int_ifs accept

					\*(T>

.fi

.SH "ADDRESS FAMILIES"

Address families determine the type of packets which are processed. For each address

family the kernel contains so called hooks at specific stages of the packet processing

paths, which invoke nftables if rules for these hooks exist.

.PP

.TP 

\*(T<\fBip\fR\*(T>

IPv4 address family.

.TP 

\*(T<\fBip6\fR\*(T>

IPv6 address family.

.TP 

\*(T<\fBinet\fR\*(T>

Internet (IPv4/IPv6) address family.

.TP 

\*(T<\fBarp\fR\*(T>

ARP address family, handling IPv4 ARP packets.

.TP 

\*(T<\fBbridge\fR\*(T>

Bridge address family, handling packets which traverse a bridge device.

.TP 

\*(T<\fBnetdev\fR\*(T>

Netdev address family, handling packets from ingress.

.PP

All nftables objects exist in address family specific namespaces, therefore

all identifiers include an address family. If an identifier is specified without

an address family, the \*(T<ip\*(T> family is used by default.

.SS "IPV4/IPV6/INET ADDRESS FAMILIES"

The IPv4/IPv6/Inet address families handle IPv4, IPv6 or both types of packets. They

contain five hooks at different packet processing stages in the network stack.

.PP

\fBIPv4/IPv6/Inet address family hooks\fR

.TS

allbox ;

l | l.

T{

Hook

T}	T{

Description

T}

.T&

l | l.

T{

prerouting

T}	T{

All packets entering the system are processed by the prerouting hook. It is invoked

before the routing process and is used for early filtering or changing packet

attributes that affect routing.

T}

T{

input

T}	T{

Packets delivered to the local system are processed by the input hook.

T}

T{

forward

T}	T{

Packets forwarded to a different host are processed by the forward hook.

T}

T{

output

T}	T{

Packets sent by local processes are processed by the output hook.

T}

T{

postrouting

T}	T{

All packets leaving the system are processed by the postrouting hook.

T}

.TE

.SS "ARP ADDRESS FAMILY"

The ARP address family handles ARP packets received and sent by the system. It is commonly used

to mangle ARP packets for clustering.

.PP

\fBARP address family hooks\fR

.TS

allbox ;

l | l.

T{

Hook

T}	T{

Description

T}

.T&

l | l

l | l.

T{

input

T}	T{

Packets delivered to the local system are processed by the input hook.

T}

T{

output

T}	T{

Packets send by the local system are processed by the output hook.

T}

.TE

.SS "BRIDGE ADDRESS FAMILY"

The bridge address family handles ethernet packets traversing bridge devices.

.PP

The list of supported hooks is identical to IPv4/IPv6/Inet address families above.

.SS "NETDEV ADDRESS FAMILY"

The Netdev address family handles packets from ingress.

.PP

\fBNetdev address family hooks\fR

.TS

allbox ;

l | l.

T{

Hook

T}	T{

Description

T}

.T&

l | l.

T{

ingress

T}	T{

All packets entering the system are processed by this hook. It is invoked

before layer 3 protocol handlers and it can be used for early filtering and

policing.

T}

.TE

.SH RULESET

'nh

.fi

.ad l

{list | flush} \fBruleset\fR [\fIfamily\fR]

.ad b

'hy

.PP

The \fBruleset\fR keyword is used to identify the whole

set of tables, chains, etc. currently in place in kernel. The

following \fBruleset\fR commands exist:

.TP 

\*(T<\fBlist\fR\*(T>

Print the ruleset in human-readable format.

.TP 

\*(T<\fBflush\fR\*(T>

Clear the whole ruleset. Note that unlike iptables, this

will remove all tables and whatever they contain,

effectively leading to an empty ruleset - no packet

filtering will happen anymore, so the kernel accepts any

valid packet it receives.

.PP

It is possible to limit \fBlist\fR and

\fBflush\fR to a specific address family only. For a

list of valid family names, see \*(T<ADDRESS FAMILIES\*(T> above.

.PP

By design, \fBlist ruleset\fR command output may be used as

input to \fBnft -f\fR. Effectively, this is the nft-equivalent

of \fBiptables-save\fR and \fBiptables-restore\fR.

.SH TABLES

'nh

.fi

.ad l

{add | delete | list | flush} \fBtable\fR [\fIfamily\fR] {\fItable\fR}

.ad b

'hy

.PP

Tables are containers for chains, sets and stateful objects. They are identified by their address family

and their name. The address family must be one of

\*(T<ip\*(T>, \*(T<ip6\*(T>, \*(T<inet\*(T>, \*(T<arp\*(T>, \*(T<bridge\*(T>, \*(T<netdev\*(T>.

The \*(T<inet\*(T> address family is a dummy family which is used to create

hybrid IPv4/IPv6 tables. The \*(T<meta\*(T> expression \*(T<nfproto\*(T>

keyword can be used to test which family (ipv4 or ipv6) context the packet is being processed in.

When no address family is specified, \*(T<ip\*(T> is used by default.

.TP 

\*(T<\fBadd\fR\*(T>

Add a new table for the given family with the given name.

.TP 

\*(T<\fBdelete\fR\*(T>

Delete the specified table.

.TP 

\*(T<\fBlist\fR\*(T>

List all chains and rules of the specified table.

.TP 

\*(T<\fBflush\fR\*(T>

Flush all chains and rules of the specified table.

.SH CHAINS

'nh

.fi

.ad l

{add | create} \fBchain\fR [\fIfamily\fR] \fItable\fR \fIchain\fR [

{

{\fItype\fR}

{\fIhook\fR}

[\fIdevice\fR]

{\fIpriority\fR ;}

[\fIpolicy\fR ;]

}

]

.ad b

'hy

'nh

.fi

.ad l

{delete | list | flush} \fBchain\fR [\fIfamily\fR] {\fItable\fR} {\fIchain\fR}

.ad b

'hy

'nh

.fi

.ad l

{rename} \fBchain\fR [\fIfamily\fR] {\fItable\fR} {\fIchain\fR} {\fInewname\fR}

.ad b

'hy

.PP

Chains are containers for rules. They exist in two kinds,

base chains and regular chains. A base chain is an entry point for

packets from the networking stack, a regular chain may be used

as jump target and is used for better rule organization.

.TP 

\*(T<\fBadd\fR\*(T>

Add a new chain in the specified table. When a hook and priority

value are specified, the chain is created as a base chain and hooked

up to the networking stack.

.TP 

\*(T<\fBcreate\fR\*(T>

Similar to the \fBadd\fR command, but returns an error if the

chain already exists.

.TP 

\*(T<\fBdelete\fR\*(T>

Delete the specified chain. The chain must not contain any rules or be

used as jump target.

.TP 

\*(T<\fBrename\fR\*(T>

Rename the specified chain.

.TP 

\*(T<\fBlist\fR\*(T>

List all rules of the specified chain.

.TP 

\*(T<\fBflush\fR\*(T>

Flush all rules of the specified chain.

.PP

For base chains, \fBtype\fR, \fBhook\fR and \fBpriority\fR parameters are mandatory.

.PP

\fBSupported chain types\fR

.TS

allbox ;

l | l | l | l.

T{

Type

T}	T{

Families

T}	T{

Hooks

T}	T{

Description

T}

.T&

l | l | l | l

l | l | l | l

l | l | l | l.

T{

filter

T}	T{

all

T}	T{

all

T}	T{

Standard chain type to use in doubt.

T}

T{

nat

T}	T{

ip, ip6

T}	T{

prerouting, input, output, postrouting

T}	T{

Chains of this type perform Native Address Translation based on conntrack entries. Only the first packet of a connection actually traverses this chain - its rules usually define details of the created conntrack entry (NAT statements for instance).

T}

T{

route

T}	T{

ip, ip6

T}	T{

output

T}	T{

If a packet has traversed a chain of this

type and is about to be accepted, a new route

lookup is performed if relevant parts of the IP

header have changed. This allows to e.g.

implement policy routing selectors in

nftables.

T}

.TE

.PP

Apart from the special cases illustrated above (e.g. \*(T<nat\*(T> type not supporting \*(T<forward\*(T> hook or \*(T<route\*(T> type only supporting \*(T<output\*(T> hook), there are two further quirks worth noticing:

.TP 0.2i

\(bu

\*(T<netdev\*(T> family supports merely a single

combination, namely \*(T<filter\*(T> type and

\*(T<ingress\*(T> hook. Base chains in this family also require the \*(T<device\*(T> parameter to be present since they exist per incoming interface only.

.TP 0.2i

\(bu

\*(T<arp\*(T> family supports only

\*(T<input\*(T> and \*(T<output\*(T>

hooks, both in chains of type

\*(T<filter\*(T>.

.PP

The \*(T<priority\*(T> parameter accepts a signed integer value which specifies the order in which chains with same \*(T<hook\*(T> value are traversed. The ordering is ascending, i.e. lower priority values have precedence over higher ones.

.PP

Base chains also allow to set the chain's \*(T<policy\*(T>, i.e. what happens to packets not explicitly accepted or refused in contained rules. Supported policy values are \*(T<accept\*(T> (which is the default) or \*(T<drop\*(T>.

.SH RULES

'nh

.fi

.ad l

[add | insert] \fBrule\fR [\fIfamily\fR] {\fItable\fR} {\fIchain\fR} [

{handle | position}

\fIhandle\fR

] {\fIstatement\fR}\&...

.ad b

'hy

'nh

.fi

.ad l

{replace} \fBrule\fR [\fIfamily\fR] {\fItable\fR} {\fIchain\fR} {handle \fIhandle\fR} {\fIstatement\fR}\&...

.ad b

'hy

'nh

.fi

.ad l

{delete} \fBrule\fR [\fIfamily\fR] {\fItable\fR} {\fIchain\fR} {handle \fIhandle\fR}

.ad b

'hy

.PP

Rules are constructed from two kinds of components according to a set

of grammatical rules: expressions and statements.

.TP 

\*(T<\fBadd\fR\*(T>

Add a new rule described by the list of statements. The rule is appended to the

given chain unless a \*(T<handle\*(T> is specified, in which case the

rule is appended to the rule given by the \fIhandle\fR.

The alternative name \*(T<position\*(T> is deprecated and should not be

used anymore.

.TP 

\*(T<\fBinsert\fR\*(T>

Similar to the \fBadd\fR command, but the rule is prepended to the

beginning of the chain or before the rule with the given

\fIhandle\fR.

.TP 

\*(T<\fBreplace\fR\*(T>

Similar to the \fBadd\fR command, but the rule replaces the specified rule.

.TP 

\*(T<\fBdelete\fR\*(T>

Delete the specified rule.

.SH SETS

'nh

.fi

.ad l

{add} \fBset\fR [\fIfamily\fR] {\fItable\fR} {\fIset\fR}

{

{\fItype\fR} [\fIflags\fR] [\fItimeout\fR] [\fIgc-interval\fR] [\fIelements\fR] [\fIsize\fR] [\fIpolicy\fR]

}

.ad b

'hy

'nh

.fi

.ad l

{delete | list | flush} \fBset\fR [\fIfamily\fR] {\fItable\fR} {\fIset\fR}

.ad b

'hy

'nh

.fi

.ad l

{add | delete} \fBelement\fR [\fIfamily\fR] {\fItable\fR} {\fIset\fR}

{

{\fIelements\fR}

}

.ad b

'hy

.PP

Sets are elements containers of an user-defined data type, they are uniquely identified by an user-defined name and attached to tables.

.TP 

\*(T<\fBadd\fR\*(T>

Add a new set in the specified table.

.TP 

\*(T<\fBdelete\fR\*(T>

Delete the specified set.

.TP 

\*(T<\fBlist\fR\*(T>

Display the elements in the specified set.

.TP 

\*(T<\fBflush\fR\*(T>

Remove all elements from the specified set.

.TP 

\*(T<\fBadd element\fR\*(T>

Comma-separated list of elements to add into the specified set.

.TP 

\*(T<\fBdelete element\fR\*(T>

Comma-separated list of elements to delete from the specified set.

.PP

\fBSet specifications\fR

.TS

allbox ;

l | l | l.

T{

Keyword

T}	T{

Description

T}	T{

Type

T}

.T&

l | l | l.

T{

type

T}	T{

data type of set elements

T}	T{

string: ipv4_addr, ipv6_addr, ether_addr, inet_proto, inet_service, mark

T}

T{

flags

T}	T{

set flags

T}	T{

string: constant, interval, timeout

T}

T{

timeout

T}	T{

time an element stays in the set

T}	T{

string, decimal followed by unit. Units are: d, h, m, s

T}

T{

gc-interval

T}	T{

garbage collection interval, only available when timeout or flag timeout are active

T}	T{

string, decimal followed by unit. Units are: d, h, m, s

T}

T{

elements

T}	T{

elements contained by the set

T}	T{

set data type

T}

T{

size

T}	T{

maximun number of elements in the set

T}	T{

unsigned integer (64 bit)

T}

T{

policy

T}	T{

set policy

T}	T{

string: performance [default], memory

T}

.TE

.SH MAPS

'nh

.fi

.ad l

{add} \fBmap\fR [\fIfamily\fR] {\fItable\fR} {\fImap\fR}

{

{\fItype\fR} [\fIflags\fR] [\fIelements\fR] [\fIsize\fR] [\fIpolicy\fR]

}

.ad b

'hy

'nh

.fi

.ad l

{delete | list | flush} \fBmap\fR [\fIfamily\fR] {\fItable\fR} {\fImap\fR}

.ad b

'hy

'nh

.fi

.ad l

{add | delete} \fBelement\fR [\fIfamily\fR] {\fItable\fR} {\fImap\fR}

{

{\fIelements\fR}

}

.ad b

'hy

.PP

Maps store data based on some specific key used as input, they are uniquely identified by an user-defined name and attached to tables.

.TP 

\*(T<\fBadd\fR\*(T>

Add a new map in the specified table.

.TP 

\*(T<\fBdelete\fR\*(T>

Delete the specified map.

.TP 

\*(T<\fBlist\fR\*(T>

Display the elements in the specified map.

.TP 

\*(T<\fBflush\fR\*(T>

Remove all elements from the specified map.

.TP 

\*(T<\fBadd element\fR\*(T>

Comma-separated list of elements to add into the specified map.

.TP 

\*(T<\fBdelete element\fR\*(T>

Comma-separated list of element keys to delete from the specified map.

.PP

\fBMap specifications\fR

.TS

allbox ;

l | l | l.

T{

Keyword

T}	T{

Description

T}	T{

Type

T}

.T&

l | l | l.

T{

type

T}	T{

data type of map elements

T}	T{

string ':' string: ipv4_addr, ipv6_addr, ether_addr, inet_proto, inet_service, mark, counter, quota. Counter and quota can't be used as keys

T}

T{

flags

T}	T{

map flags

T}	T{

string: constant, interval

T}

T{

elements

T}	T{

elements contained by the map

T}	T{

map data type

T}

T{

size

T}	T{

maximun number of elements in the map

T}	T{

unsigned integer (64 bit)

T}

T{

policy

T}	T{

map policy

T}	T{

string: performance [default], memory

T}

.TE

.SH "STATEFUL OBJECTS"

'nh