All plugins give a short synopsis of their parameters when they are called with an invalid or missing parameter, which includes with no parameter at all. When called with the parameter “-h”, they give a more detailed help.
4.2. Passing Command Line Parameters
4.3. SNMP Communities
Currently only SNMP v1 and v2c are supported. Either uses the infamous “communities” for authorization. This offers little protection and you should consider using a management LAN or at least a packet filter where you configure your management station(s) to be the only computers to be able to access SNMP1. Of course you should also change the default community strings “public” and “private”.
The plugins try to read the community string from:
The plugins will use the first community they find. If no community is given, then the program will use the community “public”.
4.3.1. Community Files
While communities are not very secure, they have still been considered worth protecting. Thus they should not be given on the command line. Even better: If they are kept in a default file, then your command line will probably get simplier.
Community files are simple text files which contain the community string. Only the first line of the file is read. You can create the default community file by issuing the commands:
For the rest of this document, it is expected that you got a working SNMP agent running on localhost and that you set up the SNMP4Nagios default community as described above. Issue the following command:
-v 2c \
If this does not print some general information about your system, then there is something wrong with your SNMP setup.2
4.5. Using the Scanner
The “scanner” is designed to find out which objects can be monitored on a given device.
If the test in the previous section succeeded3, then this should also work:
nagios@host> $BINDIR/check_if_by_snmp -S -H localhost
This should print a result like this:
OK index: 1 ; type: 24 ; aStat: 1 ; descr: lo OK index: 2 ; type: 6 ; aStat: 1 ; descr: eth0 OK index: 3 ; type: 6 ; aStat: 2 ; descr: eth1 OK index: 4 ; type: 131 ; aStat: 2 ; descr: sit0
Each line of the result describes one entity which could be monitored using one Nagios service. The first column is always “OK” or “FAILED”. Plugins which can monitor several entities on a host (like multiple network interfaces) continue with pairs of names and values separated by semicolons.
The first line in the example above means:
This information is needed or at least useful when setting up a service check. The indices (sometimes there are several indices) are used to build the object IDs which are queried. The plugins will simply abort with an error if the indices are missing. The administrative status of an interface can be used to monitor only devices which are actually used. Monitoring an interface which is administratively down will always return a warning. Finally the description is useful for building the service name, at least with systems that return sensible interface descriptions.
A description of the name-value-pairs which are returned by a plugin is included with the description of each plugin in chapter 7..
If the agent does not support the queried objects, then scanning returns the string “FAILED”.
The output is designed to be used by some higher level software to scan hosts for a multitude of services. An excerpt from a shell script doing this could look like this:
$BINDIR/check_if_by_snmp -S -H $HOST \ | while read -r STAT IN IV S1 TN TV S2 SN SV S3 DN DV do # IN, IV ... Index Name, Index Value # TN, TV ... Type Name, Type Value # SN, SV ... administrative Status Name, administrative Status Value # DN, DV ... Description Name, Description Value # S1, S2, S3 ... Semicolons test "$STAT" = "OK" \ && test "$IN" = "index:" \ && test "$S1" = ";" \ && test "$TN" = "type:" \ && test "$S2" = ";" \ && test "$SN" = "aStat:" \ && test "$S3" = ";" \ && test "$DN" = "descr:" \ && WriteInterfaceCheck "$IV" "$TV" "$SV" "$DV" \ || echo "Syntax error" 1>&2 done
4.6. Using the Tester
Using the information from the scanner, one can run a test by issuing e. g.
-T -H localhost \
which returns (in one line):
OK - eth0: I: 1410937 kO, 12672117 Pkt; O: 1339265 kO, 12722878 Pkt |eth0;100000000;1;1444800491;12672117;0;1371407644;12722878;0
Please note that “eth0” in the result string as well as in the performance data ist taken from the “-I” parameter and not read from the agent. This is to help dispatching performance data to the right archive.
The rest of the result string should be more or less self explaining. The performance data however usually needs some explaination which is given in the online help and the plugin description in this manual. For the network interface plugin the online help describes the performance data like this:
Performance data is provided in the format: <addInf>;<speed>;<oStat>;<iOct>;<iPkt>;<iErr>;<oOct>;<oPkt>;<oErr> where addInf ... additional information. speed ... estimated maximum speed of the interface oStat ... operational status, c.f. RFC1573, pp. 28-29 iOct ... Input octet counter iPkt ... Input packet counter iErr ... Input error counter oOct ... Output octet counter oPkt ... Output packet counter oErr ... Output error counter
4.6.1. “Nagios Plugins” Style Performance Data
Performance data as described in the Nagios plug-in development guidelines is supported as of SNMP4Nagios version 0.3. To enable this “Nagios Plugins” style use the command line option “-N”.
For instance issuing the command
-T -H localhost \
returns (in one line):
OK - eth0: I: 1410937 kO, 12672117 Pkt; O: 1339265 kO, 12722878 Pkt |'estimated speed'=100000000 'input octets'=1444800491c 'input packets'=12672117c 'input errors'=0c 'output octets'=1371407644c 'output packets'=12722878c 'output errors'=0c
For an explanation of the values please see the documentation of each plugin.
4.7. Using the Logger
As stated above, the plugins can keep performance logs. As a matter of fact, to make logging a part of their normal operation was a design goal. So plugins which support performance data also support the “-L” and “-P” options.
-T -L -H localhost \
should give you the output described in section 4.6. but it also creates or updates the file $RRDDIR/localhost/check_if_by_snmp_eth0.rrd
If the RRD archive does not exist, then it is initialized with the step and heartbeat given in each plugin's documentation. Thus plugins should be called at “step” intervals, usually every five minutes.
4.8. Using the Plotter
Once performance logs have been created, they can be plotted using commands like:
-P -H localhost \
This will yield a lot of output and is obviously designed to be used through some kind of front end. See appendix A. for details about the output.
Additionally several plot files are created, e. g.
1Yes, I am aware of ARP spoofing.
2Okay, you are right. You can use a different host, another community file and so on … But if you figured that out, you should also be able to figure out how to change the commands given further down in this document, shouldn't you?
3or you know how to change the command
|Copyright © 2006, 2007 Peter Gritsch|