osdl.org!shemminger | aba5acd | 2004-04-15 20:56:59 +0000 | [diff] [blame] | 1 | <!doctype linuxdoc system> |
| 2 | |
| 3 | <article> |
| 4 | |
| 5 | <title>NSTAT, IFSTAT and RTACCT Utilities |
| 6 | <author>Alexey Kuznetosv, <tt/kuznet@ms2.inr.ac.ru/ |
| 7 | <date>some_negative_number, 20 Sep 2001 |
| 8 | <abstract> |
| 9 | <tt/nstat/, <tt/ifstat/ and <tt/rtacct/ are simple tools helping |
| 10 | to monitor kernel snmp counters and network interface statistics. |
| 11 | </abstract> |
| 12 | |
| 13 | <p> These utilities are very similar, so that I describe |
| 14 | them simultaneously, using name <tt/Xstat/ in the places which apply |
| 15 | to 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 |
| 25 | of SNMP variables or interfaces to show. Variable is displayed |
| 26 | if 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 |
| 30 | conventions. |
| 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> |
| 53 | History is just dump saved in file <tt>/tmp/.Xstat.uUID</tt> |
| 54 | or in file given by environment variables <tt/NSTAT_HISTORY/, |
| 55 | <tt/IFSTAT_HISTORY/ and <tt/RTACCT_HISTORY/. |
| 56 | Each time when you use <tt/Xstat/ values there are updated. |
| 57 | If you use patterns, only the values which you _really_ see |
| 58 | are updated. If you want to skip an unintersting period, |
| 59 | use 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 |
| 63 | or source of information switched between different instances |
| 64 | of daemonic <tt/Xstat/ and kernel SNMP tables and does not |
| 65 | use invalid history. |
| 66 | |
| 67 | <p> Beware, <tt/Xstat/ will not produce sane output, |
| 68 | when many processes use it simultaneously. If several processes |
| 69 | under single user need this utility they should use environment |
| 70 | variables to put their history in safe places |
| 71 | or to use it with options <tt/-a -s/. |
| 72 | |
| 73 | <p> |
| 74 | Well, that's all. The utility is very simple, but nevertheless |
| 75 | very handy. |
| 76 | |
| 77 | <p> <bf/Output of XSTAT/ |
| 78 | <p> The first line of output is <tt/#/ followed by identifier |
| 79 | of source of information, it may be word <tt/kernel/, when <tt/Xstat/ |
| 80 | gets information from kernel or some dotted decimal number followed |
| 81 | by 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: |
| 84 | SNMP MIB identifier, |
| 85 | its value (or increment since previous measurement) and average |
| 86 | rate of increase of the counter per second. <tt/ifstat/ outputs |
| 87 | interface 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 |
| 91 | to avoid wrapped counters and to obtain reasonable long counters |
| 92 | for large time. Also <tt/Xstat/ daemon calculates average rates. |
| 93 | For the first goal sampling interval (option <tt/-d/) may be large enough, |
| 94 | f.e. for gigabit rates byte counters overflow not more frequently than |
| 95 | each 40 seconds and you may select interval of 20 seconds. |
| 96 | From the other hand, when <tt/Xstat/ is used for estimating rates |
| 97 | interval should be less than averaging period (option <tt/-t/), otherwise |
| 98 | estimation loses in quality. |
| 99 | |
| 100 | Client <tt/Xstat/, before trying to get information from the kernel, |
| 101 | contacts daemon started by this user, then it tries system wide |
| 102 | daemon, which is supposed to be started by superuser. And only if |
| 103 | none 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> |