blob: 48cacc69351c37e53b42e2f91c3932c8f3c59cda [file] [log] [blame]
osdl.org!shemmingeraba5acd2004-04-15 20:56:59 +00001<!doctype linuxdoc system>
2
3<article>
4
5<title>NSTAT, IFSTAT and RTACCT Utilities
Stephen Hemmingerdd8fac82015-01-03 09:58:41 -08006<author>Alexey Kuznetsov, <tt/kuznet@ms2.inr.ac.ru/
osdl.org!shemmingeraba5acd2004-04-15 20:56:59 +00007<date>some_negative_number, 20 Sep 2001
8<abstract>
9<tt/nstat/, <tt/ifstat/ and <tt/rtacct/ are simple tools helping
10to monitor kernel snmp counters and network interface statistics.
11</abstract>
12
13<p> These utilities are very similar, so that I describe
14them simultaneously, using name <tt/Xstat/ in the places which apply
15to all of them.
16
17<p>The format of the command is:
18
19<tscreen><verb>
20 Xstat [ OPTIONS ] [ PATTERN [ PATTERN ... ] ]
21</verb></tscreen>
22
23<p>
24<tt/PATTERN/ is shell style pattern, selecting identifier
25of SNMP variables or interfaces to show. Variable is displayed
26if one of patterns matches its name. If no patterns are given,
27<tt/Xstat/ assumes that user wants to see all the variables.
28
29<p> <tt/OPTIONS/ is list of single letter options, using common unix
30conventions.
31
32<itemize>
33<item><tt/-h/ - show help page
34<item><tt/-?/ - the same, of course
35<item><tt/-v/, <tt/-V/ - print version of <tt/Xstat/ and exit
36<item><tt/-z/ - dump zero counters too. By default they are not shown.
37<item><tt/-a/ - dump absolute values of counters. By default <tt/Xstat/
38 calculates increments since the previous use.
39<item><tt/-s/ - do not update history, so that the next time you will
40 see counters including values accumulated to the moment
41 of this measurement too.
42<item><tt/-n/ - do not display anything, only update history.
43<item><tt/-r/ - reset history.
44<item><tt/-d INTERVAL/ - <tt/Xstat/ is run in daemon mode collecting
45 statistics. <tt/INTERVAL/ is interval between measurements
46 in seconds.
47<item><tt/-t INTERVAL/ - time interval to average rates. Default value
48 is 60 seconds.
49<item><tt/-e/ - display extended information about errors (<tt/ifstat/ only).
50</itemize>
51
52<p>
53History is just dump saved in file <tt>/tmp/.Xstat.uUID</tt>
54or in file given by environment variables <tt/NSTAT_HISTORY/,
55<tt/IFSTAT_HISTORY/ and <tt/RTACCT_HISTORY/.
56Each time when you use <tt/Xstat/ values there are updated.
57If you use patterns, only the values which you _really_ see
58are updated. If you want to skip an unintersting period,
59use option <tt/-n/, or just output to <tt>/dev/null</tt>.
60
61<p>
62<tt/Xstat/ understands when history is invalidated by system reboot
63or source of information switched between different instances
64of daemonic <tt/Xstat/ and kernel SNMP tables and does not
65use invalid history.
66
67<p> Beware, <tt/Xstat/ will not produce sane output,
68when many processes use it simultaneously. If several processes
69under single user need this utility they should use environment
70variables to put their history in safe places
71or to use it with options <tt/-a -s/.
72
73<p>
74Well, that's all. The utility is very simple, but nevertheless
75very handy.
76
77<p> <bf/Output of XSTAT/
78<p> The first line of output is <tt/#/ followed by identifier
79of source of information, it may be word <tt/kernel/, when <tt/Xstat/
80gets information from kernel or some dotted decimal number followed
81by parameters, when it obtains information from running <tt/Xstat/ daemon.
82
83<p>In the case of <tt/nstat/ the rest of output consists of three columns:
84SNMP MIB identifier,
85its value (or increment since previous measurement) and average
86rate of increase of the counter per second. <tt/ifstat/ outputs
87interface name followed by pairs of counter and rate of its change.
88
89<p> <bf/Daemonic Xstat/
90<p> <tt/Xstat/ may be started as daemon by any user. This makes sense
91to avoid wrapped counters and to obtain reasonable long counters
92for large time. Also <tt/Xstat/ daemon calculates average rates.
93For the first goal sampling interval (option <tt/-d/) may be large enough,
94f.e. for gigabit rates byte counters overflow not more frequently than
95each 40 seconds and you may select interval of 20 seconds.
96From the other hand, when <tt/Xstat/ is used for estimating rates
97interval should be less than averaging period (option <tt/-t/), otherwise
98estimation loses in quality.
99
100Client <tt/Xstat/, before trying to get information from the kernel,
101contacts daemon started by this user, then it tries system wide
102daemon, which is supposed to be started by superuser. And only if
103none of them replied it gets information from kernel.
104
105<p> <bf/Environment/
106<p> <tt/NSTAT_HISTORY/ - name of history file for <tt/nstat/.
107<p> <tt/IFSTAT_HISTORY/ - name of history file for <tt/ifstat/.
108<p> <tt/RTACCT_HISTORY/ - name of history file for <tt/rtacct/.
109
110</article>