[conntrack-tools PATCH v2] conntrack.8: Document --stats counters

[conntrack-tools PATCH v2] conntrack.8: Document --stats counters

[Phil Sutter]

Provide a brief description of each counter's meaning based on
code-analysis in kernel's nf_conntrack_core.c and feedback from
netfilter-devel list.

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
Changes since v1:
- Update descriptions as per feedback from Florian
---
 conntrack.8 | 42 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/conntrack.8 b/conntrack.8
index 2bfd80e5d6aa4..bc78c4823881c 100644
--- a/conntrack.8
+++ b/conntrack.8
@@ -108,7 +108,47 @@ Flush the whole given table
 Show the table counter.
 .TP
 .BI "-S, --stats "
-Show the in-kernel connection tracking system statistics.
+Show the in-kernel connection tracking system statistics. The returned values
+for each CPU are:
+.RS
+.TP
+.B found
+Number of times a tuple was already found and had to be adjusted  when setting
+up a new NAT mapping.
+.TP
+.B invalid
+Number of invalid (e.g., malformed or non-IP) packets encountered.
+.TP
+.B insert
+Number of conntrack entries manually inserted (via netlink or eBPF).
+.TP
+.B insert_failed
+Number of new connections dropped because of unresolvable clashes with existing
+entries.
+.TP
+.B drop
+Number of packets dropped due to memory pressure.
+.TP
+.B early_drop
+Number of connections dropped in an attempt to recover from a full conntrack
+table.
+.TP
+.B error
+Number of invalid ICMP/ICMPv6 packets received.
+.TP
+.B search_restart
+Number of table lookups which had to be restarted. In rare cases a lookup may
+encounter an already deleted entry which causes a search restart.
+.TP
+.B clash_resolve
+Number of entry insert clashes resolved. These happen frequently with DNS
+traffic and thus not neccessarily indicate a problem.
+.TP
+.B chaintoolong
+Number of oversized hash bucket encounters upon inserting a new conntrack
+entry. This is a fatal problem for conntrack and it will drop the packet as a
+consequence.
+.RE
 .TP
 .BI "-R, --load-file "
 Load entries from a given file. To read from stdin, "\-" should be specified.
-- 
2.54.0

Re: [conntrack-tools PATCH v2] conntrack.8: Document --stats counters

[Phil Sutter]

Hi Florian,

On Thu, Jul 30, 2026 at 11:18:24AM +0200, Phil Sutter wrote:
> Provide a brief description of each counter's meaning based on
> code-analysis in kernel's nf_conntrack_core.c and feedback from
> netfilter-devel list.

Are these now good enough to be pushed out? Could you please review to
make sure the description matches what they're intended to count? Fixing
them up in kernel code is a separate task IMO (although I have prepared
a patch already).

Thanks, Phil

> Signed-off-by: Phil Sutter <phil@nwl.cc>
> ---
> Changes since v1:
> - Update descriptions as per feedback from Florian
> ---
>  conntrack.8 | 42 +++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 41 insertions(+), 1 deletion(-)
> 
> diff --git a/conntrack.8 b/conntrack.8
> index 2bfd80e5d6aa4..bc78c4823881c 100644
> --- a/conntrack.8
> +++ b/conntrack.8
> @@ -108,7 +108,47 @@ Flush the whole given table
>  Show the table counter.
>  .TP
>  .BI "-S, --stats "
> -Show the in-kernel connection tracking system statistics.
> +Show the in-kernel connection tracking system statistics. The returned values
> +for each CPU are:
> +.RS
> +.TP
> +.B found
> +Number of times a tuple was already found and had to be adjusted  when setting
> +up a new NAT mapping.
> +.TP
> +.B invalid
> +Number of invalid (e.g., malformed or non-IP) packets encountered.
> +.TP
> +.B insert
> +Number of conntrack entries manually inserted (via netlink or eBPF).
> +.TP
> +.B insert_failed
> +Number of new connections dropped because of unresolvable clashes with existing
> +entries.
> +.TP
> +.B drop
> +Number of packets dropped due to memory pressure.
> +.TP
> +.B early_drop
> +Number of connections dropped in an attempt to recover from a full conntrack
> +table.
> +.TP
> +.B error
> +Number of invalid ICMP/ICMPv6 packets received.
> +.TP
> +.B search_restart
> +Number of table lookups which had to be restarted. In rare cases a lookup may
> +encounter an already deleted entry which causes a search restart.
> +.TP
> +.B clash_resolve
> +Number of entry insert clashes resolved. These happen frequently with DNS
> +traffic and thus not neccessarily indicate a problem.
> +.TP
> +.B chaintoolong
> +Number of oversized hash bucket encounters upon inserting a new conntrack
> +entry. This is a fatal problem for conntrack and it will drop the packet as a
> +consequence.
> +.RE
>  .TP
>  .BI "-R, --load-file "
>  Load entries from a given file. To read from stdin, "\-" should be specified.
> -- 
> 2.54.0
> 
> 
> 

Re: [conntrack-tools PATCH v2] conntrack.8: Document --stats counters

[Florian Westphal]

Phil Sutter <phil@nwl.cc> wrote:
> Provide a brief description of each counter's meaning based on
> code-analysis in kernel's nf_conntrack_core.c and feedback from
> netfilter-devel list.

Reviewed-by: Florian Westphal <fw@strlen.de>

> +Number of entry insert clashes resolved. These happen frequently with DNS

Maybe 'Number of insertion clashes', but up to you. No need for a v3 in
any case.

Re: [conntrack-tools PATCH v2] conntrack.8: Document --stats counters

[Phil Sutter]

On Thu, Sep 03, 2026 at 04:03:26PM +0200, Florian Westphal wrote:
> Phil Sutter <phil@nwl.cc> wrote:
> > Provide a brief description of each counter's meaning based on
> > code-analysis in kernel's nf_conntrack_core.c and feedback from
> > netfilter-devel list.
> 
> Reviewed-by: Florian Westphal <fw@strlen.de>
> 
> > +Number of entry insert clashes resolved. These happen frequently with DNS
> 
> Maybe 'Number of insertion clashes', but up to you. No need for a v3 in
> any case.

Much better than my broken English - patch applied, thanks!