icinga2/doc/3.03-custom-attributes-runtime-macros.md

## <a id="custom-attributes"></a> Custom Attributes and Runtime Macros

> **Note**
>
> There is a limited set of special [global constants](#global-constants) which can be re-used and
> also partly overridden such as `IcingaEnableChecks`. 

### <a id="runtime-custom-attributes"></a> Using Custom Attributes at Runtime

Custom attributes may be used in command definitions to dynamically change how the command
is executed.
Additionally there are Icinga 2 features for example the `PerfDataWriter`
using the available Custom attributes for output formatting.

> **Tip**
>
> Custom attributes are identified by the 'vars' dictionary attribute as short name.
> Accessing the different attribute keys is possible using the '.' accessor.

> **Note**
>
> Custom attributes in command definitions or performance data templates are evaluated at
> runtime when executing a command. These custom attributes cannot be used/accessed inside
> the configuration objects to add references or similar unless stated otherwise.

Here is an example of a command definition which uses user-defined custom attributes:

    object CheckCommand "my-ping" {
      import "plugin-check-command"

      command = [
        PluginDir + "/check_ping",
        "-4",
        "-H", "$address$",
        "-w", "$wrta$,$wpl$%",
        "-c", "$crta$,$cpl$%",
        "-p", "$packets$",
        "-t", "$timeout$"
      ]

      vars.wrta = 100
      vars.wpl = 5
      vars.crta = 200
      vars.cpl = 15
      vars.packets = 5
      vars.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`) and custom variables
> (e.g., `_COMMUNITY public`). Unlike in Icinga 1.x macros may have arbitrary
> names and arguments are no longer specified in the `check_command` setting.
> Custom variables are available as custom attributes in the `vars` dictionary
> without the `_` prefix.

Custom attribute names used at runtime must be enclosed in two `$` signs, e.g.
`$address$`. When using the `$` sign as single character, you need to escape
it with an additional dollar sign (`$$`).

### <a id="runtime-custom-attributes-evaluation-order"></a> Runtime Custom Attributes Evaluation Order

When executing commands Icinga 2 checks the following objects in this order to look
up custom attributes and their respective values:

1. User object (only for notifications)
2. Service object
3. Host object
4. Command object
5. Global custom attributes in the IcingaVars constant

This execution order allows you to define default values for custom attributes
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 custom
attributes in the service definition like this:

    apply Service "ping" {
      check_command = "my-ping"

      vars.packets = 10 // Overrides the default value of 5 given in the command

      assign where host.name == "my-server1"
    }

If a custom attribute isn't defined anywhere an empty value is used and a warning is
emitted to the Icinga 2 log.


> **Best Practice**
>
> By convention every host should have an `address` custom attribute. Hosts
> which have an IPv6 address should also have an `address6` custom attribute.
> This may also be mandatory requirement for using legacy interfaces, user interfaces
> and addons.

### <a id="runtime-custom-attribute-env-vars"></a> Runtime Custom Attributes as Environment Variables

TODO

The `export_macros` command object attribute requires a list of macros which should
be exported as environment variables prior to executing the command.

This is useful for example for hiding sensitive information on the command line output
when passing credentials to database checks:

    object CheckCommand "mysql-health" {
      import "plugin-check-command",

      command = PluginDir + "/check_mysql -H $address$ -d $db$",
      /* default custom attribute values */
      vars = {
        "MYSQLUSER" = "icinga_check",
        "MYSQLPASS" = "1c1ng42r0xx"
      },

      export_macros = [
        "MYSQLUSER",
        "MYSQLPASS"
      ]
    }

### <a id="configuration-macros"></a> Configuration Macros

Icinga 2 allows you to define constants which can be used in a limited
scope. For example, constant expressions can reference a pre-defined global constant
variable and calculate a value for the service check interval.

Example:

    const MyCheckInterval = 10m

    ...

    {
      check_interval = MyCheckInterval / 2.5
    }

More details in the chapter [Constant Expressions](#constant-expressions).



## <a id="runtime-macros"></a> Runtime Macros

Next to custom attributes there are additional runtime macros made available by Icinga 2.
These runtime macros reflect the current object state and may change over time while
custom attributes are configured statically (but can be modified at runtime using
external commands).

### <a id="host-runtime-macros"></a> Host Runtime Macros

TODO

The following host custom attributes 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.

> **Note**
>
> `HOSTADDRESS` and `HOSTADDRESS6` macros are available as legacy vars. The
> Icinga 2 Template Library (`ITL`) examples use the `$address$` macro instead
> requiring that macro key to be defined.

### <a id="service-runtime-macros"></a> Service Runtime Macros

TODO

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.



### <a id="user-runtime-macros"></a> User Runtime Macros

TODO

The following custom attributes 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.



### <a id="notification-runtime-macros"></a> Notification Runtime Macros

Custom variables are made available as macros with the name "_NOTIFICATION<name>"
where <name> is the name of the custom variable.

### <a id="global-runtime-macros"></a> Global Runtime Macros

TODO

The following macros are available in all executed commands:

  Name                   | Description
  -----------------------|--------------
  TIMET                  | Current UNIX timestamp.
  LONGDATETIME           | Current date and time including timezone information. Example: `2014-01-03 11:23:08 +0000`
  SHORTDATETIME          | Current date and time. Example: `2014-01-03 11:23:08`
  DATE                   | Current date. Example: `2014-01-03`
  TIME                   | Current time including timezone information. Example: `11:23:08 +0000`