From b5c8d07b3e6c4c4b86636b6cb85f812eb634ea34 Mon Sep 17 00:00:00 2001

From: Phil Sutter <psutter@redhat.com>

Date: Tue, 16 Feb 2016 20:03:30 +0100

Subject: [PATCH] man: lnstat: rewrite manpage

Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=1269133

Upstream Status: commit f3737abf8ca5e

commit f3737abf8ca5e446f71d99b4f8e77460ede6f7ef

Author: Phil Sutter <phil@nwl.cc>

Date:   Fri Sep 18 20:17:04 2015 +0200

    man: lnstat: rewrite manpage

    Signed-off-by: Phil Sutter <phil@nwl.cc>

---

 man/man8/lnstat.8 | 197 ++++++++++++++++++++++++++++++++++++++++++++++++++++--

 1 file changed, 192 insertions(+), 5 deletions(-)

diff --git a/man/man8/lnstat.8 b/man/man8/lnstat.8

index a76940b..b817bcf 100644

--- a/man/man8/lnstat.8

+++ b/man/man8/lnstat.8

@@ -9,9 +9,21 @@ This manual page documents briefly the

 .B lnstat

 command.

 .PP

-\fBlnstat\fP is a generalized and more feature-complete replacement for the old rtstat program.

-In addition to routing cache statistics, it supports any kind of statistics the linux kernel

-exports via a file in /proc/net/stat/.

+\fBlnstat\fP is a generalized and more feature-complete replacement for the old

+rtstat program. It is commonly used to periodically print a selection of

+statistical values exported by the kernel.

+In addition to routing cache statistics, it supports any kind of statistics the

+linux kernel exports via a file in /proc/net/stat/.

+.PP

+Each file in /proc/net/stat/ contains a header line listing the column names.

+These names are used by \fBlnstat\fP as keys for selecting which statistics to

+print. For every CPU present in the system, a line follows which lists the

+actual values for each column of the file. \fBlnstat\fP sums these values up

+(which in fact are counters) before printing them. After each interval, only

+the difference to the last value is printed.

+.PP

+Files and columns may be selected by using the \fB-f\fP and \fB-k\fP

+parameters. By default, all columns of all files are printed.

 .SH OPTIONS

 lnstat supports the following options.

 .TP

@@ -28,13 +40,15 @@ Print <count> number of intervals.

 Dump list of available files/keys.

 .TP

 .B \-f, \-\-file <file>

-Statistics file to use.

+Statistics file to use, may be specified multiple times. By default all files in /proc/net/stat are scanned.

 .TP

 .B \-i, \-\-interval <intv>

 Set interval to 'intv' seconds.

 .TP

 .B \-k, \-\-keys k,k,k,...

-Display only keys specified.

+Display only keys specified. Each key \fBk\fP is of the form \fB[file:]key\fP. If \fB<file>\fP

+is given, the search for the given key is limited to that file. Otherwise the first file containing

+the searched key is being used.

 .TP

 .B \-s, \-\-subject [0-2]

 Specify display of subject/header. '0' means no header at all, '1' prints a header only at start of the program and '2' prints a header every 20 lines.

@@ -63,6 +77,179 @@ Print a header at start and every 20 lines.

 .TP

 .B # lnstat -c -1 -i 1 -f rt_cache -k entries,in_hit,in_slow_tot

 Display statistics for keys entries, in_hit and in_slow_tot of field rt_cache every second.

+

+.SH FILES

+.TP

+.B /proc/net/stat/arp_cache, /proc/net/stat/ndisc_cache

+Statistics around neighbor cache and ARP. \fBarp_cache\fP is for IPv4, \fBndisc_cache\fP is the same for IPv6.

+.sp

+.B entries

+Number of entries in the neighbor table.

+.sp

+.B allocs

+How many neighbor entries have been allocated.

+.sp

+.B destroys

+How many neighbor entries have been removed.

+.sp

+.B hash_grows

+How often the neighbor (hash) table was increased.

+.sp

+.B lookups

+How many lookups were performed.

+.sp

+.B hits

+How many \fBlookups\fP were successful.

+.sp

+.B res_failed

+How many neighbor lookups failed.

+.sp

+.B rcv_probes_mcast

+How many multicast neighbor solicitations were received. (IPv6 only.)

+.sp

+.B rcv_probes_ucast

+How many unicast neighbor solicitations were received. (IPv6 only.)

+.sp

+.B periodic_gc_runs

+How many garbage collection runs were executed.

+.sp

+.B forced_gc_runs

+How many forced garbage collection runs were executed. Happens when adding an

+entry and the table is too full.

+.sp

+.B unresolved_discards

+How many neighbor table entries were discarded due to lookup failure.

+.sp

+.B table_fulls

+Number of table overflows. Happens if table is full and forced GC run (see

+\fBforced_gc_runs\fP) has failed.

+

+.TP

+.B /proc/net/stat/ip_conntrack, /proc/net/stat/nf_conntrack

+Conntrack related counters. \fBip_conntrack\fP is for backwards compatibility

+with older userspace only and shows the same data as \fBnf_conntrack\fP.

+.sp

+.B entries

+Number of entries in conntrack table.

+.sp

+.B searched

+Number of conntrack table lookups performed.

+.sp

+.B found

+Number of \fBsearched\fP entries which were successful.

+.sp

+.B new

+Number of conntrack entries added which were not expected before.

+.sp

+.B invalid

+Number of packets seen which can not be tracked.

+.sp

+.B ignore

+Number of packets seen which are already connected to a conntrack entry.

+.sp

+.B delete

+Number of conntrack entries which were removed.

+.sp

+.B delete_list

+Number of conntrack entries which were put to dying list.

+.sp

+.B insert

+Number of entries inserted into the list.

+.sp

+.B insert_failed

+Number of entries for which list insertion was attempted but failed (happens if

+the same entry is already present).

+.sp

+.B drop

+Number of packets dropped due to conntrack failure. Either new conntrack entry

+allocation failed, or protocol helper dropped the packet.

+.sp

+.B early_drop

+Number of dropped conntrack entries to make room for new ones, if maximum table

+size was reached.

+.sp

+.B icmp_error

+Number of packets wich could not be tracked due to error situation. This is a

+subset of \fBinvalid\fP.

+.sp

+.B expect_new

+Number of conntrack entries added after an expectation for them was already

+present.

+.sp

+.B expect_create

+Number of expectations added.

+.sp

+.B expect_delete

+Number of expectations deleted.

+.sp

+.B search_restart

+Number of conntrack table lookups which had to be restarted due to hashtable

+resizes.

+

+.TP

+.B /proc/net/stat/rt_cache

+Routing cache statistics.

+.sp

+.B entries

+Number of entries in routing cache.

+.sp

+.B in_hit

+Number of route cache hits for incoming packets. Deprecated since IP route

+cache removal, therefore always zero.

+.sp

+.B in_slow_tot

+Number of routing cache entries added for input traffic.

+.sp

+.B in_slow_mc

+Number of multicast routing cache entries added for input traffic.

+.sp

+.B in_no_route

+Number of input packets for which no routing table entry was found.

+.sp

+.B in_brd

+Number of matched input broadcast packets.

+.sp

+.B in_martian_dst

+Number of incoming martian destination packets.

+.sp

+.B in_martian_src

+Number of incoming martian source packets.

+.sp

+.B out_hit

+Number of route cache hits for outgoing packets. Deprecated since IP route

+cache removal, therefore always zero.

+.sp

+.B out_slow_tot

+Number of routing cache entries added for output traffic.

+.sp

+.B out_slow_mc

+Number of multicast routing cache entries added for output traffic.

+.sp

+.B gc_total

+Total number of garbage collection runs. Deprecated since IP route cache

+removal, therefore always zero.

+.sp

+.B gc_ignored

+Number of ignored garbage collection runs due to minimum GC interval not

+reached and routing cache not full. Deprecated since IP route cache removal,

+therefore always zero.

+.sp

+.B gc_goal_miss

+Number of garbage collector goal misses. Deprecated since IP route cache

+removal, therefore always zero.

+.sp

+.B gc_dst_overflow

+Number of destination cache overflows. Deprecated since IP route cache removal,

+therefore always zero.

+.sp

+.B in_hlist_search

+Number of hash table list traversals for input traffic. Deprecated since IP

+route cache removal, therefore always zero.

+.sp

+.B out_hlist_search

+Number of hash table list traversals for output traffic. Deprecated since IP

+route cache removal, therefore always zero.

+

 .SH SEE ALSO

 .BR ip (8),

 and /usr/share/doc/iproute-doc/README.lnstat (package iproute-doc on Debian)

-- 

1.8.3.1