granicus.if.org Git - icinga2/blob - doc/3.03-custom-attributes-runtime-macros.md

   1
   2 ## <a id="custom-attributes"></a> Custom Attributes
   3
   4 ### <a id="runtime-custom-attributes"></a> Using Custom Attributes at Runtime
   5
   6 Custom attributes may be used in command definitions to dynamically change how the command
   7 is executed.
   8
   9 Additionally there are Icinga 2 features such as the `PerfDataWriter` type
  10 which use custom attributes to format their output.
  11
  12 > **Tip**
  13 >
  14 > Custom attributes are identified by the 'vars' dictionary attribute as short name.
  15 > Accessing the different attribute keys is possible using the '.' accessor.
  16
  17 Custom attributes in command definitions or performance data templates are evaluated at
  18 runtime when executing a command. These custom attributes cannot be used elsewhere
  19 (e.g. in other configuration attributes).
  20
  21 Here is an example of a command definition which uses user-defined custom attributes:
  22
  23     object CheckCommand "my-ping" {
  24       import "plugin-check-command"
  25
  26       command = [
  27         PluginDir + "/check_ping",
  28         "-4",
  29         "-H", "$address$",
  30         "-w", "$wrta$,$wpl$%",
  31         "-c", "$crta$,$cpl$%",
  32         "-p", "$packets$",
  33         "-t", "$timeout$"
  34       ]
  35
  36       vars.wrta = 100
  37       vars.wpl = 5
  38       vars.crta = 200
  39       vars.cpl = 15
  40       vars.packets = 5
  41       vars.timeout = 0
  42     }
  43
  44 Custom attribute names used at runtime must be enclosed in two `$` signs, e.g.
  45 `$address$`. When using the `$` sign as single character, you need to escape
  46 it with an additional dollar sign (`$$`).
  47
  48 ### <a id="runtime-custom-attributes-evaluation-order"></a> Runtime Custom Attributes Evaluation Order
  49
  50 When executing commands Icinga 2 checks the following objects in this order to look
  51 up custom attributes and their respective values:
  52
  53 1. User object (only for notifications)
  54 2. Service object
  55 3. Host object
  56 4. Command object
  57 5. Global custom attributes in the Vars constant
  58
  59 This execution order allows you to define default values for custom attributes
  60 in your command objects. The `my-ping` command shown above uses this to set
  61 default values for some of the latency thresholds and timeouts.
  62
  63 When using the `my-ping` command you can override all or some of the custom
  64 attributes in the service definition like this:
  65
  66     object Service "ping" {
  67       host_name = "localhost"
  68       check_command = "my-ping"
  69
  70       vars.packets = 10 // Overrides the default value of 5 given in the command
  71     }
  72
  73 If a custom attribute isn't defined anywhere an empty value is used and a warning is
  74 emitted to the Icinga 2 log.
  75
  76
  77 > **Best Practice**
  78 >
  79 > By convention every host should have an `address` custom attribute. Hosts
  80 > which have an IPv6 address should also have an `address6` custom attribute.
  81 > This may also be mandatory requirement for using user interfaces and addons.
  82
  83 ### <a id="runtime-custom-attribute-env-vars"></a> Runtime Custom Attributes as Environment Variables
  84
  85 TODO
  86
  87 The `env` command object attribute specifies a list of environment variables with values calculated
  88 from either runtime macros or custom attributes which should be exported as environment variables
  89 prior to executing the command.
  90
  91 This is useful for example for hiding sensitive information on the command line output
  92 when passing credentials to database checks:
  93
  94     object CheckCommand "mysql-health" {
  95       import "plugin-check-command",
  96
  97       command = PluginDir + "/check_mysql -H $address$ -d $db$",
  98       /* default custom attribute values */
  99       vars = {
 100         mysql_user = "icinga_check",
 101         mysql_pass = "password"
 102       },
 103
 104       env = {
 105         MYSQLUSER = "$mysql_user$",
 106         MYSQLPASS = "$mysql_pass$"
 107       }
 108     }
 109
 110 ## <a id="runtime-macros"></a> Runtime Macros
 111
 112 Next to custom attributes there are additional runtime macros made available by Icinga 2.
 113 These runtime macros reflect the current object state and may change over time while
 114 custom attributes are configured statically (but can be modified at runtime using
 115 external commands).
 116
 117 ### <a id="host-runtime-macros"></a> Host Runtime Macros
 118
 119 The following host custom attributes are available in all commands that are executed for
 120 hosts or services:
 121
 122   Name                         | Description
 123   -----------------------------|--------------
 124   host.name                    | The name of the host object.
 125   host.display_name            | The value of the `display_name` attribute.
 126   host.state                   | The host's current state. Can be one of `UNREACHABLE`, `UP` and `DOWN`.
 127   host.stateid                 | The host's current state. Can be one of `0` (up), `1` (down) and `2` (unreachable).
 128   host.statetype               | The host's current state type. Can be one of `SOFT` and `HARD`.
 129   host.check_attempt           | The current check attempt number.
 130   host.max_check_attempts      | The maximum number of checks which are executed before changing to a hard state.
 131   host.last_state              | The host's previous state. Can be one of `UNREACHABLE`, `UP` and `DOWN`.
 132   host.last_state_id           | The host's previous state. Can be one of `0` (up), `1` (down) and `2` (unreachable).
 133   host.last_state_type         | The host's previous state type. Can be one of `SOFT` and `HARD`.
 134   host.last_state_change       | The last state change's timestamp.
 135   host.duration_sec            | The time since the last state change.
 136   host.latency                 | The host's check latency.
 137   host.execution_time          | The host's check execution time.
 138   host.output                  | The last check's output.
 139   host.perfdata                | The last check's performance data.
 140   host.last_check              | The timestamp when the last check was executed.
 141   host.total_services          | Number of services associated with the host.
 142   host.total_services_ok       | Number of services associated with the host which are in an `OK` state.
 143   host.total_services_warning  | Number of services associated with the host which are in a `WARNING` state.
 144   host.total_services_unknown  | Number of services associated with the host which are in an `UNKNOWN` state.
 145   host.total_services_critical | Number of services associated with the host which are in a `CRITICAL` state.
 146
 147 ### <a id="service-runtime-macros"></a> Service Runtime Macros
 148
 149 The following service macros are available in all commands that are executed for
 150 services:
 151
 152   Name                       | Description
 153   ---------------------------|--------------
 154   service.name               | The short name of the service object.
 155   service.display_name       | The value of the `display_name` attribute.
 156   service.check_command      | This is an alias for the `SERVICEDISPLAYNAME` macro.
 157   service.state              | The service's current state. Can be one of `OK`, `WARNING`, `CRITICAL` and `UNKNOWN`.
 158   service.state_id           | The service's current state. Can be one of `0` (ok), `1` (warning), `2` (critical) and `3` (unknown).
 159   service.state_type         | The service's current state type. Can be one of `SOFT` and `HARD`.
 160   service.check_attempt      | The current check attempt number.
 161   service.max_check_attempts | The maximum number of checks which are executed before changing to a hard state.
 162   service.last_state         | The service's previous state. Can be one of `OK`, `WARNING`, `CRITICAL` and `UNKNOWN`.
 163   service.last_state_id      | The service's previous state. Can be one of `0` (ok), `1` (warning), `2` (critical) and `3` (unknown).
 164   service.last_state_type    | The service's previous state type. Can be one of `SOFT` and `HARD`.
 165   service.last_state_change  | The last state change's timestamp.
 166   service.duration_sec       | The time since the last state change.
 167   service.latency            | The service's check latency.
 168   service.execution_time     | The service's check execution time.
 169   service.output             | The last check's output.
 170   service.perfdata           | The last check's performance data.
 171   service.last_check         | The timestamp when the last check was executed.
 172
 173 ### <a id="command-runtime-macros"></a> Command Runtime Macros
 174
 175 The following custom attributes are available in all commands:
 176
 177   Name                   | Description
 178   -----------------------|--------------
 179   command.name           | The name of the command object.
 180
 181 ### <a id="user-runtime-macros"></a> User Runtime Macros
 182
 183 The following custom attributes are available in all commands that are executed for
 184 users:
 185
 186   Name                   | Description
 187   -----------------------|--------------
 188   user.name              | The name of the user object.
 189   user.display_name      | The value of the display_name attribute.
 190
 191 ### <a id="notification-runtime-macros"></a> Notification Runtime Macros
 192
 193   Name                   | Description
 194   -----------------------|--------------
 195   notification.type      | The type of the notification.
 196   notification.author    | The author of the notification comment, if existing.
 197   notification.comment   | The comment of the notification, if existing.
 198
 199 ### <a id="global-runtime-macros"></a> Global Runtime Macros
 200
 201 The following macros are available in all executed commands:
 202
 203   Name                   | Description
 204   -----------------------|--------------
 205   icinga.timet           | Current UNIX timestamp.
 206   icinga.long_date_time  | Current date and time including timezone information. Example: `2014-01-03 11:23:08 +0000`
 207   icinga.short_date_time | Current date and time. Example: `2014-01-03 11:23:08`
 208   icinga.date            | Current date. Example: `2014-01-03`
 209   icinga.time            | Current time including timezone information. Example: `11:23:08 +0000`