Configuring and Monitoring Nagios Plugins

Ubersmith can run external monitoring scripts, such as Nagios plugins, as device monitors. To do this, use the Command Monitor device module. This article shows how to add the module, configure a monitor that runs a Nagios plugin, and test the monitor.

Note: Ubersmith runs each command on the Ubersmith appliance, not on the monitored device. Install the Nagios plugin, or any other script, on the Ubersmith appliance before you use it in a monitor. If the command is not found, the command returns the value 127 and the monitor fails.

Add the Command Monitor module

You add the Command Monitor module to a device type group or to a device type. The module then becomes available to the devices of that group or type.

Go to Settings > Device Types.
Find the device type group or the device type. Click its modules link.
Click add module. The Add Device Module popup opens.
On the Details tab, set Module to Command Monitor.
Click the Config tab.
In commands, type the commands that monitors can use. Type one command on each line. Include the full path to the plugin and its arguments.
Click Save.

The Config tab of the Add Device Module popup, with two commands

In a command, use ##address## to refer to the address of the monitor. When the monitor runs, Ubersmith replaces ##address## with the address that you select for the monitor. For example:

/usr/lib/nagios/plugins/check_ping -H ##address## -w 100,20% -c 500,60%

Tip: The commands in the module are a list of choices. You can also type a different command for one monitor. See the next section.

Add a monitor that runs the command

Go to the device in the Device Manager. The device must be of the type, or in the group, that has the Command Monitor module.
Click the Monitors tab.
Click Add Monitor. The Add Monitor popup opens.
On the Details tab, set these fields:

Label: Type a name for the monitor.
Protocol: Select Module.
Address: Select the address to use for ##address##.
Module: Select Command Monitor.

Set the notification fields. For more information, refer to the article "Adding Monitors".
Click the Config tab.
Set the fields for Command 1:

Command 1: Select a command from the list. To change the command for this monitor only, click edit and type the command. To go back to the list, click select.
Expected Return Value 1: Type the return value (exit code) that means the check is correct. To accept more than one value, separate the values with commas. For example, 0,1.
Regex 1: Type a regular expression that the output of the command must match. Include the delimiters. For example, /^PING OK/.
Limits 1: If the command gives only a number as output, type a Min value, a Max value, or both. The monitor fails if the number is less than Min or more than Max.

To run more commands in the same monitor, click More. Each click adds one more command, to a maximum of five.
Click Save.

The Config tab of the Add Monitor popup, with a check_ping command, an expected return value of 0, and a regex

All fields except Command are optional. If you leave the other fields empty, the monitor does not check the result, and the command always passes. Set at least Expected Return Value or Regex.

Nagios return values

Nagios plugins use their return value to show the result of the check:

Return value	Nagios status
0	OK
1	WARNING
2	CRITICAL
3	UNKNOWN

To mark the monitor as up only when the plugin returns OK, set Expected Return Value to 0. To also mark the monitor as up when the plugin returns WARNING, set Expected Return Value to 0,1.

How Ubersmith checks each command

Ubersmith runs the commands in order. For each command, it does these checks in this sequence:

It compares the return value with Expected Return Value.
It compares the output with Regex.
If the output is a number, it compares the output with Limits.

If one check fails, the monitor is down. Ubersmith does not run the remaining commands. The monitor is up only when all of the commands pass all of their checks.

Note: If the regular expression is not valid, or if the monitor has no commands, the monitor does not go down. Ubersmith shows a warning instead.

Test the monitor

On the Monitors tab of the device, find the monitor.
Click test. The Monitor Test popup opens.

The popup shows each command after Ubersmith replaces ##address##. It also shows the return value (retval), the output, the regex, and the result.

The Monitor Test popup, with a command that passes the regex check

When the test passes, the Status column on the Monitors tab shows the monitor as up.

The Device Monitors list, with the Command Monitor monitor shown as up

When the test fails, the popup shows the reason. In the example below, the return value is 127. This value means that the command was not found on the Ubersmith appliance. Make sure that the plugin is installed at the path in the command.

The Monitor Test popup, with a failed check_ping command that returned 127

Use other plugins and scripts

The procedure is the same for other Nagios plugins and for other monitoring scripts. For each plugin or script, change these items:

The path and the arguments of the command
The expected return value
The regular expression