Question about how Sets work in nftables

Question about how Sets work in nftables

[Павел Прибылов]

Hello! I'm new to working with nftables. While mastering this tool, I
had a few questions. Can you help me figure them out? 1) How does the
gc-interval parameter work in Sets? And how is it related to timeout?
2) What is the dynamic flag for? The Add, Update, and Delete actions
in the rules work without it. 3) What are performance and memory
policies? Thank you so much for your answers!

[PATCH nft] doc: expand on gc-interval, size and a few other set/map keywords

[Florian Westphal]

Reported-by: <pavelpribylov01@gmail.com>
Signed-off-by: Florian Westphal <fw@strlen.de>
---
 doc/nft.txt | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/doc/nft.txt b/doc/nft.txt
index 1be2fbac05c1..8712981943d7 100644
--- a/doc/nft.txt
+++ b/doc/nft.txt
@@ -596,6 +596,8 @@ Sets are element containers of a user-defined data type, they are uniquely
 identified by a user-defined name and attached to tables. Their behaviour can
 be tuned with the flags that can be specified at set creation time.
 
+See Set and Map flags below for more details.
+
 [horizontal]
 *add*:: Add a new set in the specified table. See the Set specification table below for more information about how to specify properties of a set.
 *delete*:: Delete the specified set.
@@ -636,6 +638,27 @@ string: performance [default], memory
 automatic merge of adjacent/overlapping set elements (only for interval sets) |
 |=================
 
+The *gc-interval* doesn't affect element timeout, but it does affect memory reclaim.
+A large set that rarely has elements that time out can use a higher (less frequent) garbage
+collection to save cpu time, whereas sets that see many updates with short-lived elements
+will benefit from a lower interval.
+Lower intervals ensure the set stays below its maximum size.
+Internally, a timed-out entry stays around until it is removed by the garbage collector, which
+also decrements the sets element count.
+This also means that it is possible to have a set that can not accept more elements, even
+if all elements timed out, if the *gc-interval* is set too large.
+
+The *size* defines the upper limit of the amount of elements that the set can support.
+Mandatory for sets that are added to from the ruleset with the *add* and *update* keywords.
+Providing the *size* keyword for sets that are only added to via *nft add element* allows for
+a more compact (memory conserving) set implementation selection, but it is not required.
+
+The optional *policy* keyword can be used to request a more memory-conserving set implementation.
+
+*auto-merge* instructs the nftables frontend to merge adjacent and overlapping ranges.
+Example: When the set contains range *1.2.3.1-1.2.3.4*, then adding element *1.2.3.2* has no
+effect.  Adding *1.2.3.5* changes the existing range to cover *1.2.3.1-1.2.3.5*.
+Without this flag, *1.2.3.2* can not be added and *1.2.3.5* is inserted as a new entry.
 
 MAPS
 -----
@@ -684,6 +707,8 @@ If a required flag is missing, the ruleset might still work, as
 nftables will auto-enable features if it can infer this from the ruleset.
 This may not work for all cases, however, so it is recommended to
 specify all required features in the set/map definition manually.
+Also, some features are mutually exclusive.  For example, it is not possible
+for a set to support intervals and insertion from the packet path.
 
 .Set and Map flags
 [options="header"]
@@ -691,7 +716,7 @@ specify all required features in the set/map definition manually.
 |Flag		| Description
 |constant	| Set contents will never change after creation
 |dynamic	| Set must support updates from the packet path with the *add*, *update* or *delete* keywords.
-|interval	| Set must be able to store intervals (ranges)
+|interval	| Set must be able to store intervals (ranges). Cannot be combined with the *dynamic* flag.
 |timeout	| Set must support element timeouts (auto-removal of elements once they expire).
 |=================
 
-- 
2.49.0

Re: [PATCH nft] doc: expand on gc-interval, size and a few other set/map keywords

[Pablo Neira Ayuso]

On Thu, Jul 10, 2025 at 01:07:52AM +0200, Florian Westphal wrote:
> Reported-by: <pavelpribylov01@gmail.com>
> Signed-off-by: Florian Westphal <fw@strlen.de>

Reviewed-by: Pablo Neira Ayuso <pablo@netfilter.org>

Thanks Florian.