Using external commands in Nagios

System monitoring tool Nagios offers a powerful mechanism for receiving events and commands from external applications. External commands are usually sent from event handlers or from the Nagios Web interface. You will find external commands most useful when writing event handlers for your system, or when writing an external application that interacts with Nagios.

This article is excerpted from the newly published book Learning Nagios 3.0 from Packt Publishing.

The external commands pipe is a pipe file created on a filesystem that Nagios uses to receive incoming messages. The communication does not use any authentication or authorization — the only requirement is to have write access to the pipe file, rw/nagios.cmd, which is located in the directory passed as the localstatedir option during compilation.

An external command file is usually writable by the owner and the group; the usual group used is nagioscmd. If you want a user to be able to send commands to the Nagios daemon, simply add that user to this group.

A small limitation of the command pipe is that there is no way to get any results back, so it is not possible to send any query commands to Nagios. Therefore, by just using the command pipe, you have no verification that the command you have passed to Nagios has been processed, or will be processed soon. It is, however, possible to read the Nagios log file and check whether it indicates that the command has been parsed correctly.

The Nagios Web interface uses an external command pipe to control how Nagios works. The Web interface does not use any other means to send commands or apply changes to Nagios.

From the Nagios daemon perspective, there is no clear distinction as to who can perform what operations. Therefore, if you plan to use the external command pipe to allow users to submit commands remotely, you need to make sure that authorization is in place so that unauthorized users cannot send potentially dangerous commands to Nagios.

The syntax for formatting commands is easy. Each command must be placed on a single line and end with a newline character. The syntax is as follows:

[TIMESTAMP] COMMAND_NAME;argument1;argument2;...;argumentN

TIMESTAMP is written as Unix time — that is, the number of seconds since 1970-01-01 00:00:00. You can create this by using the date command. Most programming languages also offer the means to get the current Unix time.

Commands are written in upper case. The arguments depend on the actual command. For example, to add a comment to a host stating that it has passed a security audit, you can use the following shell command:

echo "['date +%s'] ADD_HOST_COMMENT;somehost;1;Security Audit;
This host has passed security audit on 'date +%Y-%m-%d'"
>/var/nagios/rw/nagios.cmd

This will send an ADD_HOST_COMMENT command to Nagios over the external command pipe. Nagios will then add a comment to the host, somehost, stating that the comment originated from Security Audit. The first argument specifies the host name to add the comment to; the second tells Nagios if this comment should be persistent. The next argument describes the author of the comment, and the last argument specifies the actual comment text.

Similarly, adding a comment to a service requires the use of the ADD_SVC_COMMENT command. The command’s syntax is similar to that of the ADD_HOST_COMMENT command except that the command requires the specification of the host name and service name.

You can also delete a single comment or all comments using the DEL_HOST_ COMMENT, DEL_ALL_HOST_COMMENTS, and DEL_SVC_COMMENT or DEL_ALL_SVC_COMMENTS commands.

Other commands worth mentioning are related to scheduling checks on demand. Often, it is necessary to request that a check be carried out as soon as possible; for example, when testing a solution.

You can create a script that schedules a check of a host, all services on that host, and a service on a different host, as follows:

#!/bin/sh

NOW='date +%s'

echo "[$NOW] SCHEDULE_HOST_CHECK;somehost;$NOW" 
>/var/nagios/rw/nagios.cmd
echo "[$NOW] SCHEDULE_HOST_SVC_CHECKS;somehost;$NOW" 
>/var/nagios/rw/nagios.cmd
echo "[$NOW] SCHEDULE_SVC_CHECK;otherhost;Service Name;$NOW" 
>/var/nagios/rw/nagios.cmd

exit 0

The commands SCHEDULE_HOST_CHECK and SCHEDULE_HOST_SVC_CHECKS accept a host name and the time at which the check should be scheduled. The SCHEDULE_SVC_CHECK command requires the specification of a service description as well as the name of the host to schedule the check on.

Normal scheduled checks, such as the ones scheduled above, might not actually take place at the time that you scheduled them. Nagios also needs to take allowed time periods into account as well as checking whether checks were disabled for a particular object or globally for the entire Nagios.

There are cases when you’ll need to force Nagios to do a check — in such cases, you should use SCHEDULE_FORCED_HOST_CHECK, SCHEDULE_FORCED_HOST_SVC_CHECKS, and SCHEDULE_FORCED_SVC_CHECK commands. They work in exactly the same way as described above, but make Nagios skip the checking of time periods, and ensure that the checks are disabled for this particular object. This way, a check will always be performed, regardless of other Nagios parameters.

Other commands worth using are related to custom variables, introduced in Nagios 3. When you define a custom variable for a host, service, or contact, you can change its value on the file with the external command pipe.

As these variables can then be directly used by check or notification commands and event handlers, it is possible to make other applications or event handlers change these attributes directly without modifications to the configuration files.

How might this work? Suppose that the IT staff registers its presence via an application without any GUI. This application periodically sends information about the latest known IP address, and that information is then passed to Nagios assuming that the person is in the office. This would later be sent to a notification command to use that specific IP address while sending a message to the user.

Assuming that the user name is jdoe and the custom variable name is DESKTOPIP, the message that would be sent to the Nagios external command pipe would be as follows:

[1206096000] CHANGE_CUSTOM_CONTACT_VAR;jdoe;DESKTOPIP;12.34.56.78

This would cause a subsequent use of $_CONTACTDESKTOPIP$ to return a value of 12.34.56.78.

Nagios offers the CHANGE_CUSTOM_CONTACT_VAR, CHANGE_CUSTOM_HOST_VAR, and CHANGE_CUSTOM_ SVC_VAR commands for modifying custom variables in contacts, hosts, and services.

The commands explained above are just a small subset of the full capabilities of the Nagios external command pipe. For a complete list of commands, visit the External Command List.