[Bug 1300] New: nft(8) - man page - SETS - missing descriptions and explanations - flags, auto-merge

[bugzilla-daemon at netfilter.org]

https://bugzilla.netfilter.org/show_bug.cgi?id=1300

            Bug ID: 1300
           Summary: nft(8) - man page - SETS - missing descriptions and
                    explanations - flags, auto-merge
           Product: nftables
           Version: unspecified
          Hardware: x86_64
                OS: All
            Status: NEW
          Severity: enhancement
          Priority: P5
         Component: nft
          Assignee: pablo at netfilter.org
          Reporter: james at nurealm.net

Arch Linux
nftables 1:0.9.0-1

nft(8) man page

SETS

add set [<address_family>] <table_name> <set_name> { type <type_spec> ; [flags
<flag_spec> ;] [timeout <timeout_spec> ;] [gc-interval <gc-interval_spec> ;]
[elements = { <element>[,...] } ;] [size <size_spec> ;] [policy <policy_spec>
;] [auto-merge <auto-merge> ;] }

The man page has just:

flags        │ set flags        │ string: constant, interval, timeout
...
auto-merge   │ automatic  merge of adjacent/overlapping set elements (only for
interval sets)        │ <no type specification>

There is not enough information to make use of these these flags or make use of
"auto-merge".  "constant", "interval", and "timeout" have no explanation in the
man page.

The nftables wiki page has:

flags, the available flags are:
constant - set content may not change while bound
interval - set contains intervals
timeout - elements can be added with a timeout

The explanation "interval - set contains intervals" provides no information. 
You cannot "explain" something by simply repeating the name of a thing.  That
represents the logical fallacy of "affirming the consequent" or "presuming the
conclusion", the idea that someone already knows the meaning of the word being
repeated.

What does it mean to "contain intervals"?  Especially when the members of the
element list do not look anything like "intervals", except that they contain
CIDR notation?  Or, is CIDR notation itself considered an "interval"?

In a thread dated 27 Oct 2016, Pablo Neira Ayuso explains "With named sets, you
have to specify this flag since the kernel uses [it] to select what is the best
data structure [to use] to represent what you need."

But, if "flags interval", *always* has to be specified with named sets, then,
when creating a named set, why does this flag have to be specified at all?  I'd
call that a bug.  A named set should instead, then, just automatically include
"interval", whatever that is.

A named set without the redundant "flag interval" configuration causes "add
element" to throw an error, "Error: Set member cannot be prefix, missing
interval flag on declaration".  The error message makes no sense, simply
highlighting a member of the set, and given that "being a prefix" is not
defined and has no explanation itself.

With the configuration "auto-merge", no "Type" description is given, though the
"add set" synopsis shows "auto-merge" requiring a value or type specification. 
Is this value simply "yes" or "on"?  And, if so, why does it require a value at
all?  Simply providing the configuration item "auto-merge" should automatically
turn-on the feature.  Or, does "auto-merge" require some distinct type of
"auto-merge" technique?  Or, is the man page in error?

"auto-merge" is not referenced at all in the nftables wiki.

A mailing list archive entry "[ANNOUNCE] nftables 0.8.2 release", dated Feb 2,
2018, shows an example of "auto-merge" with *no* configuration value or type
specification.  The explanation only says "a new explicit option for interval
sets, that enables auto-merge of adjacent/overlapping elements when adding them
to the set".  The notion of "interval sets" is still undefined.

When would someone ever *not* want an "interval set" to automatically merge an
adjacent or overlapping set?  The idea of *not* merging seems to suggest
redundant CPU cycles in the kernel, when processing network packets.

And, again, if a "named set" must always be an "interval set", then why would a
"flag interval" configuration be required when it should be automatic?

-- 
You are receiving this mail because:
You are watching all bug changes.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.netfilter.org/pipermail/netfilter-buglog/attachments/20181117/c5961271/attachment-0001.html>