Using Macros In Commands

One of the features available in Nagios is the ability to use macros in command defintions. Immediately prior to the execution of a command, Nagios will replace all macros in the command with their corresponding values. This allows you to define a few generic commands to handle all your needs.

Although macros can be used in all commands you define, not all macros may be "valid" in a particular type of command. For example, some macros may only be valid during service notification commands, whereas other may only be valid during host check commands. There are nine types of commands that Nagios recognizes and treats differently. They are as follows:

The table below lists all macros currently available in Nagios, along with a brief description of each and the types of commands in which they are valid. If a macro is used in a command in which it is invalid, it is replaced with an empty string. It should be noted that macros consist of all uppercase characters and are enclosed in $ characters.

Macro Name	Macro Description	Service Checks	Service Notifications	Host Checks	Host Notifications	Service Event Handlers & Global Service Event Handler & OCSP Command	Host Event Handlers & Global Host Event Handler	Service Performance Data Commands	Host Performance Data Commands
$CONTACTNAME$	Short name for the contact (i.e. "jdoe") that is being notified of a host or service problem	No	Yes	No	Yes	No	No	No	No
$CONTACTALIAS$	Long name/description for the contact (i.e. "John Doe") being notified	No	Yes	No	Yes	No	No	No	No
$CONTACTEMAIL$	Email address of the contact being notified	No	Yes	No	Yes	No	No	No	No
$CONTACTPAGER$	Pager number/address of the contact being notified	No	Yes	No	Yes	No	No	No	No

$HOSTNAME$	Short name for the host (i.e. "biglinuxbox"). During a service notification, this refers to the host associated with the service.	No	Yes	No	Yes	Yes	Yes	Yes	Yes
$HOSTALIAS$	Long name/description for the host (i.e. "Big Linux Server")	No	Yes	No	Yes	Yes	Yes	Yes	Yes
$HOSTADDRESS$	The IP address of the host	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
$HOSTSTATE$	The current state of the host ("UP", "DOWN", or "UNREACHABLE")	No	Yes	No	Yes	Yes	Yes	Yes	Yes

$ARGn$	The nth argument passed to the service check command. Nagios supports up to 32 argument macros ($ARG1$ through $ARG32$).	Yes	No	No	No	No	No	No	No

$SERVICEDESC$	The long name/description of the service being monitored (i.e. "Main Website")	No	Yes	No	No	Yes	No	Yes	No
$SERVICESTATE$	The current status of the service being monitored ("WARNING", "UNKNOWN", "CRITICAL", or "OK")	No	Yes	No	No	Yes	No	Yes	No
$OUTPUT$	The text output from the service or host check (i.e. "FTP ok - 1 second response time"). For service notifications and event handlers, this will contain the text output from the service check. For host notifications and event handlers, this will contain the text output from the host check.	No	Yes	No	Yes	Yes	Yes	Yes	Yes
$PERFDATA$	This macro contains any performance data that may have been returned by the service or host check.	No	Yes	No	Yes	Yes	Yes	Yes	Yes
$EXECUTIONTIME$	This is the number of seconds that the host or service check took to execute (i.e. the amount of time the check was executing).	No	Yes	No	Yes	Yes	Yes	Yes	Yes
$LATENCY$	This is the number of seconds that a service check lagged behind its scheduled check time. For instance, if a check was scheduled for 03:04:15 and it didn't get executed until 03:14:17, there would be a check latency of 2 seconds.	No	Yes	No	No	Yes	No	Yes	No
$NOTIFICATIONTYPE$	Identifies the type of notification that is being sent ("PROBLEM", "RECOVERY", or "ACKNOWLEDGEMENT").	No	Yes	No	Yes	No	No	No	No
$NOTIFICATIONNUMBER$	The current notification number for the service or host. The notification number increases by one (1) each time a new notification is sent out for a host or service (except for acknowledgements). The notification number is reset to 0 when the host or service recovers (after the recovery notification has gone out). Acknowledgements do not cause the notification number to increase.	No	Yes	No	Yes	No	No	No	No

$DATETIME$	Date/time stamp (i.e. Fri Oct 13 00:30:28 CDT 2000)	No	Yes	No	Yes	Yes	Yes	Yes	Yes
$SHORTDATETIME$	Date/time stamp (i.e. 10-13-2000 00:30:28)	No	Yes	No	Yes	Yes	Yes	Yes	Yes
$DATE$	Date stamp (i.e. 10-13-2000)	No	Yes	No	Yes	Yes	Yes	Yes	Yes
$TIME$	Time stamp (i.e. 00:30:28)	No	Yes	No	Yes	Yes	Yes	Yes	Yes
$TIMET$	Time stamp in time_t format (seconds since the UNIX epoch)	No	Yes	No	Yes	Yes	Yes	Yes	Yes
$LASTCHECK$	This is a timestamp in time_t format (seconds since the UNIX epoch) indicating the time at which a service or host check was last performed.	No	Yes	No	Yes	Yes	Yes	Yes	Yes
$LASTSTATECHANGE$	This is a timestamp in time_t format (seconds since the UNIX epoch) indicating the time at which a service or host last changed state.	No	Yes	No	Yes	Yes	Yes	Yes	Yes

$ADMINEMAIL$	Email address for the local administrator (of the host doing the monitoring)	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
$ADMINPAGER$	Pager number/address for the local administrator	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes

$STATETYPE$	The state type for the current service or host check ("HARD" or "SOFT"). Soft states occur when service or host checks return a non-OK state and are in the process of being retried. Hard states result when service or host checks have been checked a specified maximum number of times. Notifications are sent out only when hard state changes occur.	No	No	No	No	Yes	Yes	Yes	Yes
$SERVICEATTEMPT$	This refers to the number of the current service check retry. For instance, if this is the second time that the service is being rechecked, this will be the number two. Current attempt number is only useful when writing service event handlers for "soft" states that take a specific action based on the service retry number.	No	No	No	No	Yes	No	Yes	No
$HOSTATTEMPT$	This refers to the number of the current host check retry. For instance, if this is the second time that the host is being rechecked, this will be the number two. Current attempt number is only useful when writing host event handlers for "soft" states that take a specific action based on the host retry number.	No	No	No	No	No	Yes	No	Yes

$USERn$	The nth user-definable macro. User macros can be defined in one or more resource files . Nagios supports up to thrity-two user macros ($USER1$ through $USER32$).	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes