## Using Macros In Commands

Macros

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.

Macro Validity

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:

1. Service checks
2. Service notifications
3. Host checks
4. Host notifications
5. Service event handlers and/or a global service event handler
6. Host event handlers and/or a global host event handler
7. OCSP command
8. Service performance data commands
9. Host performance data commands

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 Availability Chart

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