From: Christoph Anton Mitterer Date: Fri, 24 Oct 2025 01:36:47 +0000 (+0200) Subject: doc: add more documentation on bitmasks and sets X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=bc81386c2b4084a42b191044fbf0352a722cb5f2;p=thirdparty%2Fnftables.git doc: add more documentation on bitmasks and sets Signed-off-by: Christoph Anton Mitterer Signed-off-by: Florian Westphal --- diff --git a/doc/data-types.txt b/doc/data-types.txt index 18af266a..e44308b5 100644 --- a/doc/data-types.txt +++ b/doc/data-types.txt @@ -13,6 +13,7 @@ The integer type is used for numeric values. It may be specified as a decimal, hexadecimal or octal number. The integer type does not have a fixed size, its size is determined by the expression for which it is used. +[[BITMASK_TYPE]] BITMASK TYPE ~~~~~~~~~~~~ [options="header"] @@ -26,6 +27,37 @@ integer The bitmask type (*bitmask*) is used for bitmasks. +In expressions the bits of a bitmask may be specified as *'bit'[,'bit']...* with +'bit' being the value of the bit or a pre-defined symbolic constant, if any (for +example *ct state*’s bit 0x1 has the symbolic constant `new`). + +Equality of a value with such bitmask is given, if the value has any of the +bitmask’s bits set (and optionally others). + +The syntax *'expression' 'value' / 'mask'* is identical to +*'expression' and 'mask' == 'value'*. +For example `tcp flags syn,ack / syn,ack,fin,rst` is the same as +`tcp flags and (syn|ack|fin|rst) == syn|ack`. + +Note that *'expression' 'bit'[,'bit']...* is not generally the same as +*'expression' {'bit'[,'bit']...}* and analogously with a named set. +The latter forms are lookups in a set and will match only if the set contains +exactly one value that matches. +They are however effectively the same (with matching bitmasks typically being +faster) when all bits are semantically mutually exclusive. + +Examples: +* *tcp flags syn,ack* matches packets that have the SYN, the ACK or both SYN and + ACK flags set. Other flags are ignored. + *tcp flags { syn, ack }* matches packets that have either only the SYN or only + the ACK flag set. All other flags must be unset. +* *ct state established,related* and *ct state { established, related } * match + exactly the same packets, because the bits of *ct state* are all mutually + exclusive. + +As usual, the the *nft describe* command may be used to get details on a data +type, which for bitmasks shows the symbolic names and values of the bits. + STRING TYPE ~~~~~~~~~~~~ [options="header"] diff --git a/doc/nft.txt b/doc/nft.txt index e0a3d173..b4c889af 100644 --- a/doc/nft.txt +++ b/doc/nft.txt @@ -674,6 +674,11 @@ Example: When the set contains range *1.2.3.1-1.2.3.4*, then adding element *1.2 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. +Equality of a value with a set is given if the value matches exactly one value +in the set (which for intervals means that it’s contained in any of them). +See <> for the subtle differences between syntactically similarly +looking equiality checks of sets and bitmasks. + MAPS ----- [verse]