Stateful objects

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

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

Creating stateful objects

You can create a stateful counter with the following commands:

% 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
	}
}

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

% nft list quotas

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

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