What is a Linux Command Definition

Nagios Core documentation


One of the main features that make Nagios so flexible is the ability to use macros in command definitions. Macros allow you to refer to information from hosts, services, and other sources.

Macro substitutions - how macros work

Before Nagios executes a command, it replaces any macro it finds in the command definition with the appropriate value. This macro substitution is used for all types of commands that Nagios executes - host and service checks, notifications, event handlers, etc.

Certain macros can contain macros again. These include the macros $ HOSTNOTES $, $ HOSTNOTESURL $, $ HOSTACTIONURL $, $ SERVICENOTES $, $ SERVICENOTESURL $ and $ SERVICEACTIONURL $.

Example 1: Host-Address Macro

When you use host and service macros in command definitions, these refer to values ​​for the host or service on which the command is being executed. Let's take an example. Suppose we are using a host definition and a check_pingCommand, which are defined as follows:

the extended / final host check command line to run would look like this:

Pretty easy, right? The beauty is that you can use a single command definition on an unlimited number of hosts. Each host can be checked with the same command definition because each host address is automatically replaced on the command line before execution.

Example 2: Command Argument Macros

You can also pass arguments to commands, which is handy if you want to keep your command definitions fairly generic. Arguments are specified in the object definition (i.e. host or service) by separating them from the command name with an exclamation mark (!):

In the example above, the service check has two arguments (which can be accessed with $ ARGn $ macros). The $ ARG1 $ macro becomes "200.0.80%" and $ ARG2 $ becomes "400.0.40%" (both without the quotation marks). Suppose we use the previously given host definition and one defined as follows check_ping-Command:

the extended / final command line to run for the service check would look like this:

Note: If you have to pass exclamation marks (!) In your arguments, you can do so by escaping them with a backslash (\). If you have to use backslashes in your arguments, these must also be masked with backslashes.

On-demand macros

When you use host and service macros in your command definitions, they usually refer to values ​​of the host or service on which the command is being executed. For example, if a host check is performed on a host named "linuxbox", all of the standard host macros will refer to values ​​for that host ("linuxbox").

If you want the values ​​of a command to refer to another host or service (for which the command is not executed), then you can use the so-called "on-demand macros". On-demand macros look like normal macros, except that they contain an identifier for the host or service from which they are supposed to get their value. Here is the basic format of on-demand macros:

  • $HOSTMACRONAME:host_name$
  • $SERVICE MACRONAME:host_name:service_description$

Replace HOSTMACRONAME and SERVICE MACRONAME by the name of one of the standard host or service macros found here.

Note that the macro name is separated from the host or service identifier by a colon (:). For on-demand service macros, the service identifier consists of a host name and a service description - they are also separated from one another by a colon (:).

Note: On-Demand Service Macros can contain an empty host name field. In this case, the name of the host that is connected to the service is used automatically.

Examples of on-demand host and service macros follow:

On-demand macros are also available for hostgroup, servicegroup, contact and contactgroup macros. For example:

On-demand group macros

You can get the values ​​of a macro across all contacts, hosts, or services in a particular group with a special format of your on-demand macro declaration. You do this by referencing a specific host group, service group, or contact group in an on-demand macro, as follows:

  • $HOSTMACRONAME:hostgroup_name:delimiter$
  • $SERVICE MACRONAME:servicegroup_name:delimiter$
  • $CONTACTMACRONAME:contactgroup_name:delimiter$

Replace HOSTMACRONAME, SERVICE MACRONAME and CONTACTMACRONAME by the name of one of the standard host, service or contact macros that you can find here. The delimiter that you specify is used to separate macro values ​​of the individual group members from one another.

For example, the following macro will return a comma-separated list of host status IDs that are members of the hg1-Host group are:

This macro definition will return something that looks something like this:

User variable macros

Every user object variable that you use in host, service or contact definitions is also available in macros. User variable macros are named as follows:

  • $ _HOSTvarname$
  • $ _SERVICEvarname$
  • $ _CONTACTvarname$

Take the following host definition with a user variable named "_MACADDRESS" ...

The _MACADRESS user variable would be available in a $ _HOSTMACADDRESS $ macro. More information about user variables and how they can be used in macros can be found here.

Macro cleanup

Some macros are cleaned of potentially dangerous shell metacharacters before any substitutions are made in commands. Which characters are removed from the macros depends on the settings of the illegal_macro_output_chars directive. The following macros are cleaned of potentially dangerous characters:


Macros as environment variables

Most macros are made available as environment variables for easy use in scripts or commands that are executed by Nagios. For reasons of security and common sense, $ USERn $ and "on-demand" become host and service macros Not provided as environment variables.

Environment variables that contain standard macros are named in the same way as their corresponding macro names (listed here), preceded by "NAGIOS_". For example, the $ HOSTNAME $ macro would be available as the "NAGIOS_HOSTNAME" environment variable.

Available macros

A list of all macros available in Nagios and a table showing when they can be used can be found here.

See also: List of available macros