[PATCH NOMERGE iptables 0/2] man: xt_set: Describe existing behaviour and new counters update flag

[PATCH NOMERGE iptables 0/2] man: xt_set: Describe existing behaviour and new counters update flag

[Stefano Brivio]

Patch 1/2 adjusts flag description to the current behaviour flags related
to counters, and patch 2/2 describes the new --update-counters-first flag
as proposed by Kadlecsik József.

Please don't merge before --update-counters-first is actually introduced.

Stefano Brivio (2):
  man: xt_set: Reflect current behaviour of counter update and match
    flags
  man: xt_set: Describe --update-counters-first flag

 extensions/libxt_set.man | 44 ++++++++++++++++++++++++++--------------
 1 file changed, 29 insertions(+), 15 deletions(-)

-- 
2.24.1

[PATCH NOMERGE iptables 1/2] man: xt_set: Reflect current behaviour of counter update and match flags

[Stefano Brivio]

Since kernel commit 4750005a85f7 ("netfilter: ipset: Fix "don't
update counters" mode when counters used at the matching"), if
a rule doesn't match, counters are not updated, and counter
comparison flags are also evaluated before, and regardless of,
set element matching.

The current description for counter options seems instead to
suggest that counters are updated whenever set elements match,
and the user might assume that comparisons are performed against
updated counter values.

Reflect, instead, the fact that counter flags are updated only
if *rules* (not elements) match, and that packets and bytes
counter specifiers are evaluated against the existing counter
value, before updates (that might not take place).

Signed-off-by: Stefano Brivio <sbrivio@redhat.com>
---
 extensions/libxt_set.man | 36 +++++++++++++++++++++---------------
 1 file changed, 21 insertions(+), 15 deletions(-)

diff --git a/extensions/libxt_set.man b/extensions/libxt_set.man
index 5c6f64e3..451400dc 100644
--- a/extensions/libxt_set.man
+++ b/extensions/libxt_set.man
@@ -23,37 +23,43 @@ match with a plain element returns \fBfalse\fP.
 .TP
 \fB!\fP \fB\-\-update\-counters\fP
 If the \fB\-\-update\-counters\fP flag is negated, then the packet and
-byte counters of the matching element in the set won't be updated. Default
-the packet and byte counters are updated.
+byte counters of the matching element in the set won't be updated. By
+default, packet and byte counters are updated if the \fIrule\fP
+matches.
+.IP
+Note that a rule might not match (hence, counters won't be updated)
+even if a set element matches, depending on further options described
+below.
 .TP
 \fB!\fP \fB\-\-update\-subcounters\fP
 If the \fB\-\-update\-subcounters\fP flag is negated, then the packet and
 byte counters of the matching element in the member set of a list type of
-set won't be updated. Default the packet and byte counters are updated.
+set won't be updated. By default, packet and byte counters of the member
+set are updated if the \fIrule\fP matches.
 .TP
 [\fB!\fP] \fB\-\-packets\-eq\fP \fIvalue\fP
-If the packet is matched an element in the set, match only if the
-packet counter of the element matches the given value too.
+The rule will match only if the counter for the matching set
+element reports the given amount of packets.
 .TP
 \fB\-\-packets\-lt\fP \fIvalue\fP
-If the packet is matched an element in the set, match only if the
-packet counter of the element is less than the given value as well.
+The rule will match only if the counter for the matching set
+element reports fewer packets than the given value.
 .TP
 \fB\-\-packets\-gt\fP \fIvalue\fP
-If the packet is matched an element in the set, match only if the
-packet counter of the element is greater than the given value as well.
+The rule will match only if the counter for the matching set
+element reports more packets than the given value.
 .TP
 [\fB!\fP] \fB\-\-bytes\-eq\fP \fIvalue\fP
-If the packet is matched an element in the set, match only if the
-byte counter of the element matches the given value too.
+The rule will match only if the counter for the matching set
+element reports the given amount of bytes.
 .TP
 \fB\-\-bytes\-lt\fP \fIvalue\fP
-If the packet is matched an element in the set, match only if the
-byte counter of the element is less than the given value as well.
+The rule will match only if the counter for the matching set
+element reports fewer bytes than the given value.
 .TP
 \fB\-\-bytes\-gt\fP \fIvalue\fP
-If the packet is matched an element in the set, match only if the
-byte counter of the element is greater than the given value as well.
+The rule will match only if the counter for the matching set
+element reports more packets than the given value.
 .PP
 The packet and byte counters related options and flags are ignored
 when the set was defined without counter support.
-- 
2.24.1

[PATCH NOMERGE iptables 2/2] man: xt_set: Describe --update-counters-first flag

[Stefano Brivio]

If this flag is set, counters are updated when elements (not
necessarily rules) match, and before rule match is evaluated
as a whole.

Signed-off-by: Stefano Brivio <sbrivio@redhat.com>
---
 extensions/libxt_set.man | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/extensions/libxt_set.man b/extensions/libxt_set.man
index 451400dc..fb5411be 100644
--- a/extensions/libxt_set.man
+++ b/extensions/libxt_set.man
@@ -27,9 +27,17 @@ byte counters of the matching element in the set won't be updated. By
 default, packet and byte counters are updated if the \fIrule\fP
 matches.
 .IP
-Note that a rule might not match (hence, counters won't be updated)
-even if a set element matches, depending on further options described
-below.
+Note that a rule might not match even if a set element matches,
+depending on further options described below, hence counters won't be
+updated unless the \fB\-\-update\-counters-first\fP option is given.
+.TP
+\fB\-\-update\-counters-first\fP
+Update counters before evaluating options that might affect rule
+matching: counters are updated whenever a set element matches, and
+counter comparison options described below are evaluated against the
+resulting counter values.
+.IP
+This is mutually exclusive with \fB!\fP \fB\-\-update\-counters\fP.
 .TP
 \fB!\fP \fB\-\-update\-subcounters\fP
 If the \fB\-\-update\-subcounters\fP flag is negated, then the packet and
-- 
2.24.1