From 2b838df32eb2b878d3053a24601727055fa11353 Mon Sep 17 00:00:00 2001 From: Phil Sutter Date: Thu, 6 Feb 2020 17:01:23 +0100 Subject: 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 --- doc/nft.txt | 40 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) (limited to 'doc/nft.txt') 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 [options="header"] @@ -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 |================= +ELEMENTS +-------- +[verse] +____ +{*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 +element. + +*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 +[options="header"] +|================= +|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 +|================= + + FLOWTABLES ----------- [verse] -- cgit v1.2.3