4. Using

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.1. Types

The descriptions of parameters and outputs contain these types which should be used to interface to the plugins.

4.2. Passing Command Line Parameters

The plugins use very simple command line parsing functions. Therefor some features one might expect are not available.

• Single character options must not be grouped. “-T -1” is correct, “-T1” will not work.
• Values have to be passed as separate parameter. “-r 5” and “--retries 5” should work, “-r5” and “--retries=5” will not work.
• Multiple values which are used as one parameter have to be written as one parameter. “-W 75%,75%” is correct, “-W 75%, 75%” is wrong.

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 SNMP¹. Of course you should also change the default community strings “public” and “private”.

The plugins try to read the community string from:

1. the command line. To pass it directly use the parameter “-C”.
2. a community file which is given on the command line using the parameter “-F”.
3. the built-in community file $HOME/.snmp4nagios/community.
4. the built-in community file home/.snmp4nagios/community, where “home” is the home directory of the user running the plugin as given in /etc/passwd.
5. the built-in community file /etc/snmp4nagios/community.

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:

nagios@host> mkdir $HOME/.snmp4nagios
nagios@host> chmod 700 $HOME/.snmp4nagios
nagios@host> echo "my-community"> $HOME/.snmp4nagios/community

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:

nagios@host> snmpwalk -v 2c \
> -c `cat $HOME/.snmp4nagios/community` localhost \
> .1.3.6.1.2.1.1

If this does not print some general information about your system, then there is something wrong with your SNMP setup.²

4.4. Output

Nagios only uses the first line of output which is insufficient for debugging. Therefor all error or log messages are sent to syslog, per default using the facility LOG_DAEMON.

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 succeeded³, 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:

• there is at least one interface which can be monitored.
• the first pair has the name “index:” and the value “1”.
• the second pair is “type:” and “24”. In the very case this means “softwareLoopback”.
• the third pair is “aStat:” and “1” i.e. “up”.
• the fourth pair is “descr:” and “lo”.

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.

nagios@host>$BINDIR/check_if_by_snmp -T -H localhost \
> -i 2 -I eth0

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

nagios@host>$BINDIR/check_if_by_snmp -T -H localhost \
> -i 2 -I eth0 -N

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.

The archives are actual handled by RRDTool or more precicely by librrd which is a part thereof.

To keep a performance log of an entity simply add “-L” to the command line.

nagios@host>$BINDIR/check_if_by_snmp -T -L -H localhost \
> -i 2 -I eth0

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

The filename is built from:

1. the RRD directory given on the command line (see section 5.4.3.) or the compiled in default (see section 3.1.).
2. a directory named after the hostname as passed by “-H” or the environment variable $NAGIOS_HOSTNAME⁴.
3. the name of the plugin. Note that this is compiled in and does not change if the plugin is renamed.
4. any “additional information” that is given (see section 5.5.).
5. slashes (“/”), underscores (“_”) and suffixes (“.rrd”) as needed.

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:

nagios@host>$BINDIR/check_if_by_snmp -P -H localhost \
> -i 2 -I eth0

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.
$PNGDIR/localhost/check_if_by_snmp_eth0_oct_24h_5m.png

The filename ist built from:

1. the PNG directory given on the command line (see section 5.4.4.) or the compiled in default (see section 3.1.).
2. a directory named after the hostname as passed by “-H” or the environment variable $NAGIOS_HOSTNAME.
3. the name of the plugin. Note that this is compiled in and does not change if the plugin is renamed.
4. any “additional information” that is given (see section 5.5.).
5. information about the contents of the plot: Sometimes a plugin creates several types of plots. “check_if_by_snmp” for instance creates plots for the amount of data and the number of packets which were transferred and the number of errors encountered. These plots have the additional designations “oct”, “pkt” and “err” respectively.
6. the durations of the plotted period and the sample interval. So the example above covers a 24 hour period and uses one sample every five minutes.
7. slashes (“/”), underscores (“_”) and suffixes (“.rrd”) as needed.

¹Yes, I am aware of ARP spoofing.

²Okay, 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?

³or you know how to change the command

⁴c. f. http://nagios.sourceforge.net/docs/2_0/macros.html