* [PATCH nft] doc: expand on gc-interval, size and a few other set/map keywords
2025-07-08 17:37 Question about how Sets work in nftables Павел Прибылов
@ 2025-07-09 23:07 ` Florian Westphal
2025-07-14 13:30 ` Pablo Neira Ayuso
0 siblings, 1 reply; 3+ messages in thread
From: Florian Westphal @ 2025-07-09 23:07 UTC (permalink / raw)
To: netfilter-devel; +Cc: netfilter, Florian Westphal, pavelpribylov01
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
^ permalink raw reply related [flat|nested] 3+ messages in thread