path: root/doc/nft.txt
diff options
authorPhil Sutter <>2020-02-06 17:01:23 +0100
committerPhil Sutter <>2020-02-07 18:46:29 +0100
commit2b838df32eb2b878d3053a24601727055fa11353 (patch)
tree599feeccda5a0e2e8d86a620af6dab0fc1f60c1b /doc/nft.txt
parente527e901564f9cb1cb7a42ddc3e5d72236b770bc (diff)
doc: nft.8: Describe element commands in their own section
This unifies the redundant information in sets and maps sections and also covers 'get' command. Signed-off-by: Phil Sutter <>
Diffstat (limited to 'doc/nft.txt')
1 files changed, 37 insertions, 3 deletions
diff --git a/doc/nft.txt b/doc/nft.txt
index 45350253..ba0c8c0b 100644
--- a/doc/nft.txt
+++ b/doc/nft.txt
@@ -507,8 +507,6 @@ be tuned with the flags that can be specified at set creation time.
*delete*:: Delete the specified set.
*list*:: Display the elements in the specified set.
*flush*:: Remove all elements from the specified set.
-*add element*:: Comma-separated list of elements to add into the specified set.
-*delete element*:: Comma-separated list of elements to delete from the specified set.
.Set specifications
@@ -550,7 +548,6 @@ MAPS
*add map* ['family'] 'table' 'map' *{ type* 'type' | *typeof* 'expression' [*flags* 'flags' *;*] [*elements = {* 'element'[*,* ...] *} ;*] [*size* 'size' *;*] [*policy* 'policy' *;*] *}*
{*delete* | *list* | *flush*} *map* ['family'] 'table' 'map'
*list maps* ['family']
-{*add* | *delete*} *element* ['family'] 'table' 'map' *{ elements = {* 'element'[*,* ...] *} ; }*
Maps store data based on some specific key used as input. They are uniquely identified by a user-defined name and attached to tables.
@@ -587,6 +584,43 @@ string: performance [default], memory
+{*add* | *create* | *delete* | *get* } *element* ['family'] 'table' 'set' *{* 'ELEMENT'[*,* ...] *}*
+'ELEMENT' := 'key_expression' 'OPTIONS' [*:* 'value_expression']
+'OPTIONS' := [*timeout* 'TIMESPEC'] [*expires* 'TIMESPEC'] [*comment* 'string']
+'TIMESPEC' := ['num'*d*]['num'*h*]['num'*m*]['num'[*s*]]
+Element-related commands allow to change contents of named sets and maps.
+'key_expression' is typically a value matching the set type.
+'value_expression' is not allowed in sets but mandatory when adding to maps, where it
+matches the data part in it's type definition. When deleting from maps, it may
+be specified but is optional as 'key_expression' uniquely identifies the
+*create* command is similar to *add* with the exception that none of the
+listed elements may already exist.
+*get* command is useful to check if an element is contained in a set which may
+be non-trivial in very large and/or interval sets. In the latter case, the
+containing interval is returned instead of just the element itself.
+.Element options
+|Option | Description
+|timeout |
+timeout value for sets/maps with flag *timeout*
+|expires |
+the time until given element expires, useful for ruleset replication only
+|comment |
+per element comment field