5. Common Options

SNMP4Nagios plugins are designed to use as much common code as sensible. A wanted side effect is that they share many common parameters. These parameters will not be discussed with each plugin but in this section.

There are six basic modes: Scanning, testing, logging and plotting as discussed before, “version printing” and “help”.

Scanning, version printing and help are exclusive, that is the program will exit once the scan is complete or the version or help text is printed.

Testing, logging and plotting can be combined. While the plugins are actually designed to test and log at once, plotting should be done on demand. There could be thousands of checks, each running at five minute intervals. There is hardly the time to look at say one thousand plots per minute while creating them would put some serious load on most computers.

5.1. Version printing and Help

5.1.1. --version, -V

Prints the versions of the plugin and SNMP4Nagios, then exit.

5.1.2. --help, -h

Prints the help text of the plugin and exit.

5.2. General Options

Those options can be used in all four main modes (i.e. scanning, testing, logging and plotting).

5.2.1. --host, -H HOSTNAME

Name of the host which should be be checked. A value for the hostname is required for logging and plotting. If it is not given using the command line parameter, then it is read from the environment variable $NAGIOS_HOSTNAME. If this is not set either, the program will abort with an error.

5.2.2. --address, -A IP-ADDRESS

Sets the IP address of the host which is to query. If this is not set, then the environment variable $NAGIOS_HOSTADDRESS is read. If this is set neither, then the hostname is used to make the connection.

5.2.3. --verbose, -v

Increase verbosity. This can be given several times, three is usually a good number for debugging. As usual messages are written to syslog.

5.2.4. --nagios-plugins-format, -N

Print performance data using the “Nagios Plugins” style.

5.3. For scanning and testing

Scanning and testing are the modes which actually use SNMP. Thus most network settings are used only in these modes. Note that “-H” is the exception to the rule. It can be used in these modes (where “-A” is preferred) but it is required with logging and plotting.¹

5.3.1. --scan, -S

Scans the host for services. This disables all other modes. Scanning is discussed more deeply in section 4.5..

5.3.2. --test, -T

Test a given service. Testing is discussed more deeply in section 4.6..

5.3.3. --snmp-v1, -1

Use the SNMP protocol version 1.

5.3.4. --snmp-v2c, -2

Use the SNMP protocol version 2c. This is the default.

5.3.5. --community, -C COMMUNITY

Use the SNMP community COMMUNITY (string).

5.3.6. --community-file, -F FILENAME

Read the SNMP community from the file FILENAME. For more details about community files see section 4.3.1..

5.3.7. --retries, -r RETRIES

Number of times to retry a request given as an integer. Note that Net-SNMP uses increasing timeouts for retries.

5.3.8. --snmp-timeout, -t TIMEOUT

Timeout for the first SNMP request in milliseconds given as an integer.

5.4. For logging and plotting

5.4.1. --log, -L

Log performance data. If “-T” is also given, then the data is passed internally, otherwise it is read from the environment variable $NAGIOS_SERVICEPERFDATA.

Logging is discussed more deeply in section 4.7..

5.4.2. --plot, -P

Create plots. See section 4.8. for more details.

5.4.3. --rrd-directory, -R DIRNAME

RRD archives' base directory. The filename of the archive is built by appending the hostname, the check's name and—depending on the service—other information to DIRNAME. If this option is not given, then the compiled in default (see section 3.1.) is used.

5.4.4. --graph-directory, -G DIRNAME

PNG plots' base directory. The filename of the plots is build by appending the hostname, the check's name and—depending on the service—other information to DIRNAME. If this option is not given, then the compiled in default (see section 3.1.) is used.

5.5. Additional Information

Plugins which support both indices and logging and plotting need a way to distinguish between several entities of the same kind, e. g. multiple ethernet NICs. Obviously the indices would be a way to achive this, but they have a serious drawback: Indices may change, even at a simple reboot.

While this is bad enough—one might have to rescan a host after a boot—loosing the performance logs is certainly worse.²

To solve this problem scanning was designed to present persistent data where possible and the “additional information” was introduced.

5.5.1. --additional-info, -I ADDINF

Additional information used to find the RRD archive and image pathes. See section 4.8..

This string is used as a part of a filename. The plugins do not enforce any restriction about what characters it may contain—but the operating system would most likely object to e. g. “/”.

¹Instead of passing the hostname a/o address on the command line, they can be passed through the environment.

²The logs are not actually lost but they might become inaccessible or data from one entity might be logged to the archive of another entity.