mirror of https://github.com/Icinga/icinga2.git
203 lines
9.0 KiB
Markdown
203 lines
9.0 KiB
Markdown
|
|
## <a id="custom-attributes"></a> Custom Attributes
|
|
|
|
### <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 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 (`$$`).
|
|
|
|
### <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:
|
|
|
|
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` custom attribute. Hosts
|
|
> which have an IPv6 address should also have an `address6` custom attribute.
|
|
> This may also be mandatory requirement for using user interfaces and addons.
|
|
|
|
### <a id="runtime-custom-attribute-env-vars"></a> 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$"
|
|
}
|
|
}
|
|
|
|
## <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
|
|
|
|
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.displayname | The value of the `display_name` attribute.
|
|
host.state | The host's current state. Can be one of `UNREACHABLE`, `UP` and `DOWN`.
|
|
host.stateid | The host's current state. Can be one of `0` (up), `1` (down) and `2` (unreachable).
|
|
host.statetype | The host's current state type. Can be one of `SOFT` and `HARD`.
|
|
host.attempt | The current check attempt number.
|
|
host.maxattempt | The maximum number of checks which are executed before changing to a hard state.
|
|
host.laststate | The host's previous state. Can be one of `UNREACHABLE`, `UP` and `DOWN`.
|
|
host.laststateid | The host's previous state. Can be one of `0` (up), `1` (down) and `2` (unreachable).
|
|
host.laststatetype | The host's previous state type. Can be one of `SOFT` and `HARD`.
|
|
host.laststatechange | The last state change's timestamp.
|
|
host.durationsec | The time since the last state change.
|
|
host.latency | The host's check latency.
|
|
host.executiontime | The host's check execution time.
|
|
host.output | The last check's output.
|
|
host.perfdata | The last check's performance data.
|
|
host.lastcheck | The timestamp when the last check was executed.
|
|
host.totalservices | Number of services associated with the host.
|
|
host.totalservicesok | Number of services associated with the host which are in an `OK` state.
|
|
host.totalserviceswarning | Number of services associated with the host which are in a `WARNING` state.
|
|
host.totalservicesunknown | Number of services associated with the host which are in an `UNKNOWN` state.
|
|
host.totalservicescritical | Number of services associated with the host which are in a `CRITICAL` state.
|
|
|
|
### <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
|
|
------------------------|--------------
|
|
service.description | The short name of the service object.
|
|
service.displayname | The value of the `display_name` attribute.
|
|
service.checkcommand | 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.stateid | The service's current state. Can be one of `0` (ok), `1` (warning), `2` (critical) and `3` (unknown).
|
|
service.statetype | The service's current state type. Can be one of `SOFT` and `HARD`.
|
|
service.attempt | The current check attempt number.
|
|
service.maxattempt | The maximum number of checks which are executed before changing to a hard state.
|
|
service.laststate | The service's previous state. Can be one of `OK`, `WARNING`, `CRITICAL` and `UNKNOWN`.
|
|
service.laststateid | The service's previous state. Can be one of `0` (ok), `1` (warning), `2` (critical) and `3` (unknown).
|
|
service.laststatetype | The service's previous state type. Can be one of `SOFT` and `HARD`.
|
|
service.laststatechange | The last state change's timestamp.
|
|
service.durationsec | The time since the last state change.
|
|
service.latency | The service's check latency.
|
|
service.executiontime | The service's check execution time.
|
|
service.output | The last check's output.
|
|
service.perfdata | The last check's performance data.
|
|
service.lastcheck | The timestamp when the last check was executed.
|
|
|
|
### <a id="user-runtime-macros"></a> 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.displayname | The value of the display_name attribute.
|
|
|
|
|
|
### <a id="notification-runtime-macros"></a> 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.
|
|
|
|
### <a id="global-runtime-macros"></a> Global Runtime Macros
|
|
|
|
The following macros are available in all executed commands:
|
|
|
|
Name | Description
|
|
-----------------------|--------------
|
|
icinga.timet | Current UNIX timestamp.
|
|
icinga.longdatetime | Current date and time including timezone information. Example: `2014-01-03 11:23:08 +0000`
|
|
icinga.shortdatetime | 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`
|