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

Custom Attributes

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 such as the PerfDataWriter type which use custom attributes to format their output.

Tip

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

Custom attributes in command definitions or performance data templates are evaluated at runtime when executing a command. These custom attributes cannot be used elsewhere (e.g. in other configuration attributes).

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
}

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 ($$).

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 Vars 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:

object Service "ping" {
  host_name = "localhost"
  check_command = "my-ping"

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

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 attribute. Hosts which have an IPv6 address should also have an address6 attribute.

Runtime Custom Attributes as Environment Variables

TODO

The env command object attribute specifies a list of environment variables with values calculated from either runtime macros or custom attributes 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 = {
    mysql_user = "icinga_check",
    mysql_pass = "password"
  },

  env = {
    MYSQLUSER = "$mysql_user$",
    MYSQLPASS = "$mysql_pass$"
  }
}

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).

Host Runtime Macros

The following host custom attributes are available in all commands that are executed for hosts or services:

Name	Description
host.name	The name of the host object.
host.display_name	The value of the display_name attribute.
host.state	The host's current state. Can be one of UNREACHABLE, UP and DOWN.
host.state_id	The host's current state. Can be one of 0 (up), 1 (down) and 2 (unreachable).
host.state_type	The host's current state type. Can be one of SOFT and HARD.
host.check_attempt	The current check attempt number.
host.max_check_attempts	The maximum number of checks which are executed before changing to a hard state.
host.last_state	The host's previous state. Can be one of UNREACHABLE, UP and DOWN.
host.last_state_id	The host's previous state. Can be one of 0 (up), 1 (down) and 2 (unreachable).
host.last_state_type	The host's previous state type. Can be one of SOFT and HARD.
host.last_state_change	The last state change's timestamp.
host.duration_sec	The time since the last state change.
host.latency	The host's check latency.
host.execution_time	The host's check execution time.
host.output	The last check's output.
host.perfdata	The last check's performance data.
host.last_check	The timestamp when the last check was executed.
host.total_services	Number of services associated with the host.
host.total_services_ok	Number of services associated with the host which are in an OK state.
host.total_services_warning	Number of services associated with the host which are in a WARNING state.
host.total_services_unknown	Number of services associated with the host which are in an UNKNOWN state.
host.total_services_critical	Number of services associated with the host which are in a CRITICAL state.

Service Runtime Macros

The following service macros are available in all commands that are executed for services:

Name	Description
service.name	The short name of the service object.
service.display_name	The value of the display_name attribute.
service.check_command	This is an alias for the SERVICEDISPLAYNAME macro.
service.state	The service's current state. Can be one of OK, WARNING, CRITICAL and UNKNOWN.
service.state_id	The service's current state. Can be one of 0 (ok), 1 (warning), 2 (critical) and 3 (unknown).
service.state_type	The service's current state type. Can be one of SOFT and HARD.
service.check_attempt	The current check attempt number.
service.max_check_attempts	The maximum number of checks which are executed before changing to a hard state.
service.last_state	The service's previous state. Can be one of OK, WARNING, CRITICAL and UNKNOWN.
service.last_state_id	The service's previous state. Can be one of 0 (ok), 1 (warning), 2 (critical) and 3 (unknown).
service.last_state_type	The service's previous state type. Can be one of SOFT and HARD.
service.last_state_change	The last state change's timestamp.
service.duration_sec	The time since the last state change.
service.latency	The service's check latency.
service.execution_time	The service's check execution time.
service.output	The last check's output.
service.perfdata	The last check's performance data.
service.last_check	The timestamp when the last check was executed.

Command Runtime Macros

The following custom attributes are available in all commands:

Name	Description
command.name	The name of the command object.

User Runtime Macros

The following custom attributes are available in all commands that are executed for users:

Name	Description
user.name	The name of the user object.
user.display_name	The value of the display_name attribute.

Notification Runtime Macros

Name	Description
notification.type	The type of the notification.
notification.author	The author of the notification comment, if existing.
notification.comment	The comment of the notification, if existing.

Global Runtime Macros

The following macros are available in all executed commands:

Name	Description
icinga.timet	Current UNIX timestamp.
icinga.long_date_time	Current date and time including timezone information. Example: 2014-01-03 11:23:08 +0000
icinga.short_date_time	Current date and time. Example: 2014-01-03 11:23:08
icinga.date	Current date. Example: 2014-01-03
icinga.time	Current time including timezone information. Example: 11:23:08 +0000