mirror of https://github.com/Icinga/icinga2.git
281 lines
11 KiB
Markdown
281 lines
11 KiB
Markdown
|
|
## <a id="macros"></a> 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-macros"></a> 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 (`$$`).
|
|
|
|
### <a id="runtime-macro-evaluation-order"></a> 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 `_HOST`name "_HOST<name>"
|
|
where <name> 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.
|
|
|
|
### <a id="host-runtime-macros"></a> 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<name>"
|
|
where <name> is the name of the custom variable.
|
|
|
|
### <a id="service-runtime-macros"></a> 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<name>"
|
|
where <name> is the name of the custom variable.
|
|
|
|
### <a id="user-runtime-macros"></a> 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<name>" and
|
|
"_CONTACT<name>" where <name> is the name of the custom variable. "_CONTACT<name>"
|
|
|
|
|
|
### <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
|
|
|
|
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`
|
|
|
|
### <a id="runtime-macros-env-vars"></a> 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"
|
|
]
|
|
}
|
|
|
|
### <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).
|
|
|