Stateful objects

Stateful objects is nftables's umbrella term for objects that maintain information about packet flows and connection states, that are updated by each packet that "hits" them, and that share a common syntax. Strictly speaking, stateful object refers to a named object that is attached to a table. More loosely, anonymous stateful objects can also be used, e.g. an unnamed counter used in a rule. Anonymous stateful objects exist only in the context of the object (i.e. rule) in which they are used. This difference in scope causes some quirks, see the below section on resetting stateful objects.

Initial support for stateful objects was added in Linux kernel 4.10 and nftables 0.8, with support for counters and quotas.

Creating stateful objects

You can create a stateful counter with the following commands:

% nft add table filter
% nft add counter filter https-traffic

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

Creating a quota is similar:

% nft add quota filter https-quota 25 mbytes

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

Referencing stateful objects in rules

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

% nft add chain filter output { type filter hook output priority 0 \; }
% nft add rule filter output tcp dport https counter name https-traffic

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

They can also be used with maps:

% nft add rule filter output counter name tcp dport map { \
          https : "https-traffic", \
          80 : "http-traffic", \
          25 : "foo-counter", \
          50 : "foo-counter", \
          107 : "foo-counter" \
  }

Similarly, dynamic maps can be used:

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

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

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

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

}

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

Listing stateful objects

You can list the stateful information of objects individually via:

% nft list counter filter https-traffic
table ip filter {
	counter https-traffic {
		packets 0 bytes 0
	}
}

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

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

% nft list quotas
table inet filter {
	quota other-inet-quota {
		200 mbytes
	}
}
table ip filter {
	quota https-quota {
		30 mbytes
	}
	quota http-quota {
		25 mbytes
	}
}

Example with counters:

% nft list counters
table inet filter {
	counter mycounter {
		packets 0 bytes 0
	}
	counter mycounter2 {
		packets 0 bytes 0
	}
}
table ip filter {
	counter https-traffic {
		packets 0 bytes 0
	}
}

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

% nft list counters table inet filter
table inet filter {
	counter mycounter {
		packets 0 bytes 0
	}
	counter mycounter2 {
		packets 0 bytes 0
	}
}

Example with quotas:

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

Resetting stateful objects

Resetting an object will atomically dump and reset its content:

% nft reset quota filter https-quota
table ip filter {
	quota https-quota {
		25 mbytes used 217 kbytes
	}
}

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

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

% nft reset counters
% nft reset quotas table filter

At the moment (Jan 2019) resetting quotas does not reset anonymous quotas such as used in rules without names, see bug #1314