About Commands

The Commands option is used to define commands that execute for host and service checks, host and service notifications, and host and service event handlers. Commands are referenced in host and service templates, host and service checks, profiles, contact templates and contact definitions, and the global Nagios™ setup for event handling.

A Command line which is part of the Command definition specifies the details of how the command is run, including the path to a particular program and its arguments, if any. Typically, some parts of those arguments are defined to be substituted at run time with values specific to the context in which the command is run, by means of macro references. This allows you to define a few generic commands to handle all your needs.

Command customization is automatically applied by Nagios at run time, just before the command is executed, such as substituting the obvious value for a $HOSTADDRESS$ macro reference in the defined Command line. Some of those macros may refer to static values which are fixed in the configuration, and some may refer to dynamic values which are only known at run time. Either way, you must make sure you mention only those macros which are valid for the circumstances where the command is to be used.

Service-check commands are special, in that the setup for a Service Check allows the Command line to be further customized for an individual application of the command, by providing specific values to be substituted for macro references named $ARG1$, $ARG2$, and so forth. These values can be tweaked on a per-generic-service or per-host-service basis to tune how a command operates in that context. Such values may represent service-check return values, parts of service-check status text, port numbers, thresholds, or anything else you find useful for that command.

In the configuration setup generated during a Commit operation for a Standalone or Parent server, check command definitions are stored in the /usr/local/nagios/etc/check_commands.cfg file in the nagios container. Conversely, notification and global event-handling command definitions are stored in the /usr/local/nagios/etc/misccommands.cfg file in the nagios container.

Configuring a New Command

1. To create a command from scratch, select Configuration > Nagios Monitoring > Commands, then select New. You also have the option to Copy, Search, and Modify existing commands.
2. In the Select Resource screen, you will find the set of Nagios $USERn$ resource macros displayed. Nagios supports up to thirty-two user macros ($USER1$ through $USER32$), which are defined under Configuration > Nagios Monitoring > Control > Nagios resource macros. 
   • $USERn$ macros are useful for storing usernames, passwords, directory paths, and other locally customized items commonly used in command definitions. They are shown here in the Commands area so you may select one of the the resource macros that defines the absolute pathname of a directory in which command programs (such as service-check plugins) are stored. This makes it easier to specify the individual programs that are available on the system, by having the system look them up for you and provide a list you can select from.
   • Typically, USER1 is selected here, because by our convention it defines the directory in which the standard Nagios check commands are stored. (If you don't have a resource macro that corresponds to the directory containing the program you wish to run, you can skip this step, just click on the Next button at the bottom of the screen, and go directly to the Command Definition section, below. In that case, be careful to remove the $$/ that shows up in the Command line, and start the Command line with the absolute path to your desired program.)
     
     
3. After selecting a resource macro, the screen will change and the names of the files that are available in the specified directory will be shown in a dropdown list at the top of the screen. In that list, select the filename for the program you want to run for this command. Then select Next to continue.
4. To finish the rest of the new command setup, continue on to the Command Definition section, below.

Command Definition

A command has several parts that are referenced elsewhere in the configuration: its Name, Type, and Command line. Those are all set in the Command Wizard screen you see at this point, as a result of a New, Copy, or Modify action for a command.

1. In the Command Wizard screen, if this is a New or Copy action, enter a name for the command.
2. Next, specify a command type: check = host/service check commands and event handlers; notify = notification commands; other = other commands (e.g., global event handlers). This classification affects which drop-down lists elsewhere in the configuration screens that this command will appear in, so those lists only contain command names that are appropriate for those contexts.

3. The Command line directive is used to define what is actually executed by Nagios when the command is used for service or host checks, notifications, or event handlers. This field can be edited here.

   • It begins with the absolute path to the command program; this part is often parameterized using a $USERn$ resource macro. You must add whatever arguments you expect to be passed to the program, either as literal characters or including references to various macros ($HOSTADDRESS$, $USER5$, $ARG2$, etc.).
   • Before the Command line is executed, all valid macro references in the Command line are replaced with their respective values.

   • See the Nagios documentation on macros for determining when you can use different macros.

     

     The Command line as a whole is not surrounded in quotes, though individual command arguments may need quoting in case they might sometimes be empty or contain spaces or other special characters. Also, if you want to pass a literal dollar sign ($) on the Command line, you have to escape it with another dollar sign.

4. The Test area within the Command Wizard screen enables you to test the Command line, with some limitations. When you click the Test button, it parses through the command definition, performs macro substitutions as best it can, puts the resulting command into a shell command line and executes that, returning the results of the execution in the box to the right. Specifically, the Test fields are used as follows when you click the Test button:
   • Host: Specifies the name of an existing host within Monarch, assuming that makes sense for this command. Used to substitute corresponding values for $HOSTNAME$, $HOSTALIAS$, and $HOSTADDRESS$ macro references in the command.
   • Arguments: Specifies a set of command-argument values, separated by ! characters (exclamation points). These will be used to substitute corresponding values for $ARG1$, $ARG2$, and similar macro references in the command.
   • Service description: Specifies the name of a host service within Monarch, assuming that makes sense for this command. This will be used to substitute a value for $SERVICEDESC$ macro references in the command.
   • A few macro references which are dynamically determined by the running Nagios process will be substituted with certain dummy values, such as UP for $HOSTSTATE$ and the current time for some timestamp fields like $SHORTDATETIME$ and $TIME$. The values of other non-resource and non-Argument macros are generally not accessible to the Test button, so they will be substituted with a single "-" character as a kind of placeholder. These substitutions may or may not be appropriate for correct operation of your command; that is a constraint of the testing context.
5. Select Add to add a new command, or Save to accept changes to an existing command. Cancel will exit the command wizard without saving. A follow-on screen will confirm that the command has been saved. The Continue button there is just a dummy action with no further effect on the configuration.

Related Resources

• Page:
  Nagios Monitoring