Signed-off-by: Christoph Anton Mitterer --- doc/data-types.txt | 31 +++++++++++++++++++++++++++++++ doc/nft.txt | 5 +++++ 2 files changed, 36 insertions(+) diff --git a/doc/data-types.txt b/doc/data-types.txt index 18af266a..b36ca768 100644 --- a/doc/data-types.txt +++ b/doc/data-types.txt @@ -26,6 +26,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 4cd3fa8e..4ae998ed 100644 --- a/doc/nft.txt +++ b/doc/nft.txt @@ -775,6 +775,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] -- 2.51.0