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

Custom Attributes and Runtime Macros

Note

There is a limited set of special global constants which can be re-used and also partly overridden such as IcingaEnableChecks.

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

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.

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"
  ]
}

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.

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

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.

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.

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.

Notification Runtime Macros

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

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