icinga2/doc/3.03-macros.md

11 KiB

Macros

Note

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

Runtime Macros

Macros 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 runtime macros for output formatting.

Note

Macros are evaluated at runtime when executing a command. These macros cannot be used inside the configuration objects to add references or similar unless stated otherwise.

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 using the $ sign as single character, you need to escape it with an additional dollar sign ($$).

Runtime Macro Evaluation Order

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 constant

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.

Best Practice

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.

Custom Variables as Runtime Macros

Custom variables are made available as macros using an underscore and the object type in uppercase characters as additional prefix. For example _HOSTname "_HOST" where is the name of the custom variable.

Runtime Macro Evaluation Order in Cluster Mode

These macros are evaluated and calculated upon command execution on each node. If a cluster node defines additional macros overriding the default tuples, the calculated macro values will be different and affect only the node executing the command.

Node 1:

const IcingaMacros = {
  plugindir = "/usr/lib/icinga/plugins"
}

Node 2:

const IcingaMacros = {
  plugindir = "/usr/lib/monitoring/plugins"
}

CheckCommand definition:

object CheckCommand "whatever" inherits "plugin-check-command" {
   command = "$plugindir$/check_whatever"
}

On Node 1, this will be evaluated into /usr/lib/icinga/plugins/check_whatever. On Node 2, Icinga 2 will attempt to execute /usr/lib/icinga/monitoring/check_whatever instead.

Host Runtime 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.

Note

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

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

Service Runtime 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.

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

User Runtime Macros

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

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

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

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

Runtime Macros as Environment Variables

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" inherits "plugin-check-command" {
   command = "$plugindir$/check_mysql -H $address$ -d $db$",
   /* default macro values */
   macros = {
     "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.