## Macros Macros may be used in command definitions to dynamically change how the command is executed. Here is an example of a command definition which uses user-defined macros: object CheckCommand "my-ping" inherits "plugin-check-command" { command = [ "$plugindir$/check_ping", "-4", "-H", "$address$", "-w", "$wrta$,$wpl$%", "-c", "$crta$,$cpl$%", "-p", "$packets$", "-t", "$timeout$" ], macros = { wrta = 100, wpl = 5, crta = 200, cpl = 15, packets = 5, timeout = 0 } } > **Note** > > If you have previously used Icinga 1.x you may already be familiar with > user and argument macros (e.g., `USER1` or `ARG1`). Unlike in Icinga 1.x macros > may have arbitrary names and arguments are no longer specified in the > `check_command` setting. Macro names must be enclosed in two `$` signs, e.g. `$plugindir$`. When executing commands Icinga 2 checks the following objects in this order to look up macros: 1. User object (only for notifications) 2. Service object 3. Host object 4. Command object 5. Global macros in the IcingaMacros variable This execution order allows you to define default values for macros in your command objects. The `my-ping` command shown above uses this to set default values for some of the latency thresholds and timeouts. When using the `my-ping` command you can override all or some of the macros in the service definition like this: object Host "my-server1" { services["ping"] = { check_command = "my-ping", macros["packets"] = 10 // Overrides the default value of 5 given in the command }, macros["address"] = "10.0.0.1" } If a macro isn't defined anywhere an empty value is used and a warning is emitted to the Icinga 2 log. > **Note** > > Macros in capital letters (e.g. `HOSTNAME`) are reserved for use by Icinga 2 > and should not be overwritten by users. By convention every host should have an `address` macro. Hosts which have an IPv6 address should also have an `address6` macro. The `plugindir` macro should be set to the path of your check plugins. The `/etc/icinga2/conf.d/macros.conf` file is usually used to define global macros including this one. ### Host Macros The following host macros are available in all commands that are executed for hosts or services: Name | Description -----------------------|-------------- HOSTNAME | The name of the host object. HOSTDISPLAYNAME | The value of the `display_name` attribute. HOSTALIAS | This is an alias for the `HOSTDISPLAYNAME` macro. HOSTSTATE | The host's current state. Can be one of `UNREACHABLE`, `UP` and `DOWN`. HOSTSTATEID | The host's current state. Can be one of `0` (up), `1` (down) and `2` (unreachable). HOSTSTATETYPE | The host's current state type. Can be one of `SOFT` and `HARD`. HOSTATTEMPT | The current check attempt number. MAXHOSTATTEMPT | The maximum number of checks which are executed before changing to a hard state. LASTHOSTSTATE | The host's previous state. Can be one of `UNREACHABLE`, `UP` and `DOWN`. LASTHOSTSTATEID | The host's previous state. Can be one of `0` (up), `1` (down) and `2` (unreachable). LASTHOSTSTATETYPE | The host's previous state type. Can be one of `SOFT` and `HARD`. LASTHOSTSTATECHANGE | The last state change's timestamp. HOSTDURATIONSEC | The time since the last state change. HOSTLATENCY | The host's check latency. HOSTEXECUTIONTIME | The host's check execution time. HOSTOUTPUT | The last check's output. HOSTPERFDATA | The last check's performance data. LASTHOSTCHECK | The timestamp when the last check was executed. HOSTADDRESS | This is an alias for the `address` macro. If the `address` macro is not defined the host object's name is used instead. HOSTADDRESS6 | This is an alias for the `address6` macro. If the `address` macro is not defined the host object's name is used instead. ### Service Macros The following service macros are available in all commands that are executed for services: Name | Description -----------------------|-------------- SERVICEDESC | The short name of the service object. SERVICEDISPLAYNAME | The value of the `display_name` attribute. SERVICECHECKCOMMAND | This is an alias for the `SERVICEDISPLAYNAME` macro. SERVICESTATE | The service's current state. Can be one of `OK`, `WARNING`, `CRITICAL` and `UNKNOWN`. SERVICESTATEID | The service's current state. Can be one of `0` (ok), `1` (warning), `2` (critical) and `3` (unknown). SERVICESTATETYPE | The service's current state type. Can be one of `SOFT` and `HARD`. SERVICEATTEMPT | The current check attempt number. MAXSERVICEATTEMPT | The maximum number of checks which are executed before changing to a hard state. LASTSERVICESTATE | The service's previous state. Can be one of `OK`, `WARNING`, `CRITICAL` and `UNKNOWN`. LASTSERVICESTATEID | The service's previous state. Can be one of `0` (ok), `1` (warning), `2` (critical) and `3` (unknown). LASTSERVICESTATETYPE | The service's previous state type. Can be one of `SOFT` and `HARD`. LASTSERVICESTATECHANGE | The last state change's timestamp. SERVICEDURATIONSEC | The time since the last state change. SERVICELATENCY | The service's check latency. SERVICEEXECUTIONTIME | The service's check execution time. SERVICEOUTPUT | The last check's output. SERVICEPERFDATA | The last check's performance data. LASTSERVICECHECK | The timestamp when the last check was executed. TOTALHOSTSERVICES | Number of services associated with the host. TOTALHOSTSERVICESOK | Number of services associated with the host which are in an `OK` state. TOTALHOSTSERVICESWARNING | Number of services associated with the host which are in a `WARNING` state. TOTALHOSTSERVICESUNKNOWN | Number of services associated with the host which are in an `UNKNOWN` state. TOTALHOSTSERVICESCRITICAL | Number of services associated with the host which are in a `CRITICAL` state. ### User Macros The following service macros are available in all commands that are executed for users: Name | Description -----------------------|-------------- USERNAME | The name of the user object. USERDISPLAYNAME | The value of the display_name attribute. USEREMAIL | This is an alias for the `email` macro. USERPAGER | This is an alias for the `pager` macro. ### Global Macros The following macros are available in all commands: Name | Description -----------------------|-------------- TIMET | Current UNIX timestamp. LONGDATETIME | Current date and time including timezone information. SHORTDATETIME | Current date and time. DATE | Current date. TIME | Current time including timezone information.