granicus.if.org Git - icinga2/blob - doc/09-object-types.md

   1 # Object Types <a id="object-types"></a>
   2
   3 This chapter provides an overview of all available config object types which can be
   4 instantiated using the `object` keyword.
   5
   6 Additional details on configuration and runtime attributes and their
   7 description are explained here too.
   8
   9 The attributes need to have a specific type value. Many of them are
  10 explained in [this chapter](03-monitoring-basics.md#attribute-value-types) already.
  11 You should note that the `Timestamp` type is a `Number`.
  12 In addition to that `Object name` is an object reference to
  13 an existing object name as `String` type.
  14
  15 ## Overview <a id="object-types-overview"></a>
  16
  17 * [Monitoring Objects](09-object-types.md#object-types-monitoring) such as host, service, etc.
  18 * [Runtime Objects](09-object-types.md#object-types-runtime) generated by Icinga itself.
  19 * [Features](09-object-types.md#object-types-features) available via `icinga2 feature` CLI command.
  20
  21 ## Common Runtime Attributes <a id="object-types-runtime-attributes"></a>
  22
  23 Configuration objects share these runtime attributes which cannot be
  24 modified by the user. You can access these attributes using
  25 the [Icinga 2 API](12-icinga2-api.md#icinga2-api-config-objects).
  26
  27   Name                      | Type                  | Description
  28   --------------------------|-----------------------|----------------------------------
  29   version                   | Number                | Timestamp when the object was created or modified. Synced throughout cluster nodes.
  30   type                      | String                | Object type.
  31   original\_attributes      | Dictionary            | Original values of object attributes modified at runtime.
  32   active                    | Boolean               | Object is active (e.g. a service being checked).
  33   paused                    | Boolean               | Object has been paused at runtime (e.g. [IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection). Defaults to `false`.
  34   templates                 | Array                 | Templates imported on object compilation.
  35   package                   | String                | [Configuration package name](12-icinga2-api.md#icinga2-api-config-management) this object belongs to. Local configuration is set to `_etc`, runtime created objects use `_api`.
  36   source\_location          | Dictionary            | Location information where the configuration files are stored.
  37
  38 ## Monitoring Objects <a id="object-types-monitoring"></a>
  39
  40 ### ApiUser <a id="objecttype-apiuser"></a>
  41
  42 ApiUser objects are used for authentication against the [Icinga 2 API](12-icinga2-api.md#icinga2-api-authentication).
  43
  44 Example:
  45
  46 ```
  47 object ApiUser "root" {
  48   password = "mysecretapipassword"
  49   permissions = [ "*" ]
  50 }
  51 ```
  52
  53 Configuration Attributes:
  54
  55   Name                      | Type                  | Description
  56   --------------------------|-----------------------|----------------------------------
  57   password                  | String                | **Optional.** Password string. Note: This attribute is hidden in API responses.
  58   client\_cn                | String                | **Optional.** Client Common Name (CN).
  59   permissions               | Array                 | **Required.** Array of permissions. Either as string or dictionary with the keys `permission` and `filter`. The latter must be specified as function.
  60
  61 Available permissions are explained in the [API permissions](12-icinga2-api.md#icinga2-api-permissions)
  62 chapter.
  63
  64 ### CheckCommand <a id="objecttype-checkcommand"></a>
  65
  66 A check command definition. Additional default command custom attributes can be
  67 defined here.
  68
  69 Example:
  70
  71 ```
  72 object CheckCommand "http" {
  73   command = [ PluginDir + "/check_http" ]
  74
  75   arguments = {
  76     "-H" = "$http_vhost$"
  77     "-I" = "$http_address$"
  78     "-u" = "$http_uri$"
  79     "-p" = "$http_port$"
  80     "-S" = {
  81       set_if = "$http_ssl$"
  82     }
  83     "--sni" = {
  84       set_if = "$http_sni$"
  85     }
  86     "-a" = {
  87       value = "$http_auth_pair$"
  88       description = "Username:password on sites with basic authentication"
  89     }
  90     "--no-body" = {
  91       set_if = "$http_ignore_body$"
  92     }
  93     "-r" = "$http_expect_body_regex$"
  94     "-w" = "$http_warn_time$"
  95     "-c" = "$http_critical_time$"
  96     "-e" = "$http_expect$"
  97   }
  98
  99   vars.http_address = "$address$"
 100   vars.http_ssl = false
 101   vars.http_sni = false
 102 }
 103 ```
 104
 105 Configuration Attributes:
 106
 107   Name                      | Type                  | Description
 108   --------------------------|-----------------------|----------------------------------
 109   command                   | Array                 | **Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command. When using the "arguments" attribute this must be an array. Can be specified as function for advanced implementations.
 110   env                       | Dictionary            | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
 111   vars                      | Dictionary            | **Optional.** A dictionary containing custom attributes that are specific to this command.
 112   timeout                   | Duration              | **Optional.** The command timeout in seconds. Defaults to `1m`.
 113   arguments                 | Dictionary            | **Optional.** A dictionary of command arguments.
 114
 115
 116 #### CheckCommand Arguments <a id="objecttype-checkcommand-arguments"></a>
 117
 118 Command arguments can be defined as key-value-pairs in the `arguments`
 119 dictionary. If the argument requires additional configuration, for example
 120 a `description` attribute or an optional condition, the value can be defined
 121 as dictionary specifying additional options.
 122
 123 Service:
 124
 125 ```
 126 vars.x_val = "My command argument value."
 127 vars.have_x = "true"
 128 ```
 129
 130 CheckCommand:
 131
 132 ```
 133 arguments = {
 134   "-X" = {
 135     value = "$x_val$"
 136     key = "-Xnew"           /* optional, set a new key identifier */
 137     description = "My plugin requires this argument for doing X."
 138     required = false    /* optional, no error if not set */
 139     skip_key = false    /* always use "-X <value>" */
 140     set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
 141     order = -1          /* first position */
 142     repeat_key = true   /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
 143   }
 144   "-Y" = {
 145     value = "$y_val$"
 146     description = "My plugin requires this argument for doing Y."
 147     required = false    /* optional, no error if not set */
 148     skip_key = true     /* don't prefix "-Y" only use "<value>" */
 149     set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
 150     order = 0           /* second position */
 151     repeat_key = false  /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
 152   }
 153 }
 154 ```
 155
 156   Name                      | Type                  | Description
 157   --------------------------|-----------------------|----------------------------------
 158   value                     | String/Function       | Optional argument value set by a [runtime macro string](03-monitoring-basics.md#runtime-macros) or a [function call](17-language-reference.md#functions).
 159   key                       | String                | Optional argument key overriding the key identifier.
 160   description               | String                | Optional argument description.
 161   required                  | Boolean               | Required argument. Execution error if not set. Defaults to false (optional).
 162   skip\_key                 | Boolean               | Use the value as argument and skip the key.
 163   set\_if                   | String/Function       | Argument is added if the [runtime macro string](03-monitoring-basics.md#runtime-macros) resolves to a defined numeric or boolean value. String values are not supported. [Function calls](17-language-reference.md#functions) returning a value are supported too.
 164   order                     | Number                | Set if multiple arguments require a defined argument order.
 165   repeat\_key               | Boolean               | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
 166
 167 Argument order:
 168
 169 ```
 170 ..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...
 171 ```
 172
 173 Define argument array:
 174
 175 ```
 176 value = "[ 'one', 'two', 'three' ]"
 177 ```
 178
 179 Argument array with `repeat_key = true`:
 180
 181 ```
 182 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'
 183 ```
 184
 185 Argument array with `repeat_key = false`:
 186
 187 ```
 188 'key' 'value[0]' 'value[1]' 'value[2]'
 189 ```
 190
 191 ## Dependency <a id="objecttype-dependency"></a>
 192
 193 Dependency objects are used to specify dependencies between hosts and services. Dependencies
 194 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
 195 relations.
 196
 197 > **Best Practice**
 198 >
 199 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
 200 > to just create a `Dependency` template and use the `apply` keyword to assign the
 201 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
 202 > type for `Host` or `Service`.
 203 > Check the [dependencies](03-monitoring-basics.md#dependencies) chapter for detailed examples.
 204
 205 Service-to-Service Example:
 206
 207 ```
 208 object Dependency "webserver-internet" {
 209   parent_host_name = "internet"
 210   parent_service_name = "ping4"
 211
 212   child_host_name = "webserver"
 213   child_service_name = "ping4"
 214
 215   states = [ OK, Warning ]
 216
 217   disable_checks = true
 218 }
 219 ```
 220
 221 Host-to-Host Example:
 222
 223 ```
 224 object Dependency "webserver-internet" {
 225   parent_host_name = "internet"
 226
 227   child_host_name = "webserver"
 228
 229   states = [ Up ]
 230
 231   disable_checks = true
 232 }
 233 ```
 234
 235 Configuration Attributes:
 236
 237   Name                      | Type                  | Description
 238   --------------------------|-----------------------|----------------------------------
 239   parent\_host\_name        | Object name           | **Required.** The parent host.
 240   parent\_service\_name     | Object name           | **Optional.** The parent service. If omitted, this dependency object is treated as host dependency.
 241   child\_host\_name         | Object name           | **Required.** The child host.
 242   child\_service\_name      | Object name           | **Optional.** The child service. If omitted, this dependency object is treated as host dependency.
 243   disable\_checks           | Boolean               | **Optional.** Whether to disable checks when this dependency fails. Defaults to false.
 244   disable\_notifications    | Boolean               | **Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
 245   ignore\_soft\_states      | Boolean               | **Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
 246   period                    | Object name           | **Optional.** Time period object during which this dependency is enabled.
 247   states                    | Array                 | **Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
 248
 249 Available state filters:
 250
 251 ```
 252 OK
 253 Warning
 254 Critical
 255 Unknown
 256 Up
 257 Down
 258 ```
 259
 260 When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
 261 automatically determined by Icinga 2.
 262
 263 Service-to-Host Dependency Example:
 264
 265 ```
 266 apply Dependency "internet" to Service {
 267   parent_host_name = "dsl-router"
 268   disable_checks = true
 269
 270   assign where host.name != "dsl-router"
 271 }
 272 ```
 273
 274 This example sets all service objects matching the assign condition into a dependency relation to
 275 the parent host object `dsl-router` as implicit child services.
 276
 277 Service-to-Service-on-the-same-Host Dependency Example:
 278
 279 ```
 280 apply Dependency "disable-agent-checks" to Service {
 281   parent_service_name = "agent-health"
 282
 283   assign where service.check_command == "ssh"
 284   ignore where service.name == "agent-health"
 285 }
 286 ```
 287
 288 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
 289 host object matched by the apply rule condition. All services where apply matches are made implicit child services
 290 in this dependency relation.
 291
 292
 293 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
 294 name you specified. This means you can define more than one object with the same (short) name as long as one of the `child_host_name` and
 295 `child_service_name` attributes has a different value.
 296
 297 ## Endpoint <a id="objecttype-endpoint"></a>
 298
 299 Endpoint objects are used to specify connection information for remote
 300 Icinga 2 instances. More details can be found in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
 301
 302 Example:
 303
 304 ```
 305 object Endpoint "icinga2-client1.localdomain" {
 306   host = "192.168.56.111"
 307   port = 5665
 308   log_duration = 1d
 309 }
 310 ```
 311
 312 Example (disable replay log):
 313
 314 ```
 315 object Endpoint "icinga2-client1.localdomain" {
 316   host = "192.168.5.111"
 317   port = 5665
 318   log_duration = 0
 319 }
 320 ```
 321
 322 Configuration Attributes:
 323
 324   Name                      | Type                  | Description
 325   --------------------------|-----------------------|----------------------------------
 326   host                      | String                | **Optional.** The hostname/IP address of the remote Icinga 2 instance.
 327   port                      | Number                | **Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
 328   log\_duration             | Duration              | **Optional.** Duration for keeping replay logs on connection loss. Defaults to `1d` (86400 seconds). Attribute is specified in seconds. If log_duration is set to 0, replaying logs is disabled. You could also specify the value in human readable format like `10m` for 10 minutes or `1h` for one hour.
 329
 330 Endpoint objects cannot currently be created with the API.
 331
 332 ## EventCommand <a id="objecttype-eventcommand"></a>
 333
 334 An event command definition.
 335
 336 Example:
 337
 338 ```
 339 object EventCommand "restart-httpd-event" {
 340   command = "/opt/bin/restart-httpd.sh"
 341 }
 342 ```
 343
 344
 345 Configuration Attributes:
 346
 347   Name                      | Type                  | Description
 348   --------------------------|-----------------------|----------------------------------
 349   command                   | Array                 | **Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command. When using the "arguments" attribute this must be an array. Can be specified as function for advanced implementations.
 350   env                       | Dictionary            | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
 351   vars                      | Dictionary            | **Optional.** A dictionary containing custom attributes that are specific to this command.
 352   timeout                   | Duration              | **Optional.** The command timeout in seconds. Defaults to `1m`.
 353   arguments                 | Dictionary            | **Optional.** A dictionary of command arguments.
 354
 355 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
 356
 357 More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
 358
 359
 360 ## Host <a id="objecttype-host"></a>
 361
 362 A host.
 363
 364 Example:
 365
 366 ```
 367 object Host "icinga2-client1.localdomain" {
 368   display_name = "Linux Client 1"
 369   address = "192.168.56.111"
 370   address6 = "2a00:1450:4001:815::2003"
 371
 372   groups = [ "linux-servers" ]
 373
 374   check_command = "hostalive"
 375 }
 376 ```
 377
 378 Configuration Attributes:
 379
 380   Name                      | Type                  | Description
 381   --------------------------|-----------------------|----------------------------------
 382   display\_name             | String                | **Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
 383   address                   | String                | **Optional.** The host's IPv4 address. Available as command runtime macro `$address$` if set.
 384   address6                  | String                | **Optional.** The host's IPv6 address. Available as command runtime macro `$address6$` if set.
 385   groups                    | Array of object names | **Optional.** A list of host groups this host belongs to.
 386   vars                      | Dictionary            | **Optional.** A dictionary containing custom attributes that are specific to this host.
 387   check\_command            | Object name           | **Required.** The name of the check command.
 388   max\_check\_attempts      | Number                | **Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
 389   check\_period             | Object name           | **Optional.** The name of a time period which determines when this host should be checked. Not set by default.
 390   check\_timeout            | Duration              | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
 391   check\_interval           | Duration              | **Optional.** The check interval (in seconds). This interval is used for checks when the host is in a `HARD` state. Defaults to `5m`.
 392   retry\_interval           | Duration              | **Optional.** The retry interval (in seconds). This interval is used for checks when the host is in a `SOFT` state. Defaults to `1m`. Note: This does not affect the scheduling [after a passive check result](08-advanced-topics.md#check-result-freshness).
 393   enable\_notifications     | Boolean               | **Optional.** Whether notifications are enabled. Defaults to true.
 394   enable\_active\_checks    | Boolean               | **Optional.** Whether active checks are enabled. Defaults to true.
 395   enable\_passive\_checks   | Boolean               | **Optional.** Whether passive checks are enabled. Defaults to true.
 396   enable\_event\_handler    | Boolean               | **Optional.** Enables event handlers for this host. Defaults to true.
 397   enable\_flapping          | Boolean               | **Optional.** Whether flap detection is enabled. Defaults to false.
 398   enable\_perfdata          | Boolean               | **Optional.** Whether performance data processing is enabled. Defaults to true.
 399   event\_command            | Object name           | **Optional.** The name of an event command that should be executed every time the host's state changes or the host is in a `SOFT` state.
 400   flapping\_threshold\_high | Number                | **Optional.** Flapping upper bound in percent for a host to be considered flapping. Default `30.0`
 401   flapping\_threshold\_low  | Number                | **Optional.** Flapping lower bound in percent for a host to be considered  not flapping. Default `25.0`
 402   volatile                  | Boolean               | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
 403   zone                      | Object name           | **Optional.** The zone this object is a member of. Please read the [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring) chapter for details.
 404   command\_endpoint         | Object name           | **Optional.** The endpoint where commands are executed on.
 405   notes                     | String                | **Optional.** Notes for the host.
 406   notes\_url                | String                | **Optional.** URL for notes for the host (for example, in notification commands).
 407   action\_url               | String                | **Optional.** URL for actions for the host (for example, an external graphing tool).
 408   icon\_image               | String                | **Optional.** Icon image for the host. Used by external interfaces only.
 409   icon\_image\_alt          | String                | **Optional.** Icon image description for the host. Used by external interface only.
 410
 411 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
 412 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
 413
 414 > **Best Practice**
 415 >
 416 > The `address` and `address6` attributes are required for running commands using
 417 > the `$address$` and `$address6$` runtime macros.
 418
 419 Runtime Attributes:
 420
 421   Name                      | Type                  | Description
 422   --------------------------|-----------------------|----------------------------------
 423   next\_check               | Timestamp             | When the next check occurs (as a UNIX timestamp).
 424   last\_check               | Timestamp             | When the last check occurred (as a UNIX timestamp).
 425   check\_attempt            | Number                | The current check attempt number.
 426   state\_type               | Number                | The current state type (0 = SOFT, 1 = HARD).
 427   last\_state\_type         | Number                | The previous state type (0 = SOFT, 1 = HARD).
 428   last\_reachable           | Boolean               | Whether the host was reachable when the last check occurred.
 429   last\_check\_result       | CheckResult           | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
 430   last\_state\_change       | Timestamp             | When the last state change occurred (as a UNIX timestamp).
 431   last\_hard\_state\_change | Timestamp             | When the last hard state change occurred (as a UNIX timestamp).
 432   last\_in\_downtime        | Boolean               | Whether the host was in a downtime when the last check occurred.
 433   acknowledgement           | Number                | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
 434   acknowledgement\_expiry   | Timestamp             | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
 435   downtime\_depth           | Number                | Whether the host has one or more active downtimes.
 436   flapping\_last\_change    | Timestamp             | When the last flapping change occurred (as a UNIX timestamp).
 437   flapping                  | Boolean               | Whether the host is flapping between states.
 438   flapping\_current         | Number                | Current flapping value in percent (see flapping\_thresholds)
 439   state                     | Number                | The current state (0 = UP, 1 = DOWN).
 440   last\_state               | Number                | The previous state (0 = UP, 1 = DOWN).
 441   last\_hard\_state         | Number                | The last hard state (0 = UP, 1 = DOWN).
 442   last\_state\_up           | Timestamp             | When the last UP state occurred (as a UNIX timestamp).
 443   last\_state\_down         | Timestamp             | When the last DOWN state occurred (as a UNIX timestamp).
 444
 445
 446
 447 ## HostGroup <a id="objecttype-hostgroup"></a>
 448
 449 A group of hosts.
 450
 451 > **Best Practice**
 452 >
 453 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
 454
 455 Example:
 456
 457 ```
 458 object HostGroup "linux-servers" {
 459   display_name = "Linux Servers"
 460
 461   assign where host.vars.os == "Linux"
 462 }
 463 ```
 464
 465 Configuration Attributes:
 466
 467   Name                      | Type                  | Description
 468   --------------------------|-----------------------|----------------------------------
 469   display\_name             | String                | **Optional.** A short description of the host group.
 470   groups                    | Array of object names | **Optional.** An array of nested group names.
 471
 472
 473
 474 ## Notification <a id="objecttype-notification"></a>
 475
 476 Notification objects are used to specify how users should be notified in case
 477 of host and service state changes and other events.
 478
 479 > **Best Practice**
 480 >
 481 > Rather than creating a `Notification` object for a specific host or service it is
 482 > usually easier to just create a `Notification` template and use the `apply` keyword
 483 > to assign the notification to a number of hosts or services. Use the `to` keyword
 484 > to set the specific target type for `Host` or `Service`.
 485 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
 486
 487 Example:
 488
 489 ```
 490 object Notification "localhost-ping-notification" {
 491   host_name = "localhost"
 492   service_name = "ping4"
 493
 494   command = "mail-notification"
 495
 496   users = [ "user1", "user2" ] // reference to User objects
 497
 498   types = [ Problem, Recovery ]
 499   states = [ Critical, Warning, OK ]
 500 }
 501 ```
 502
 503 Configuration Attributes:
 504
 505   Name                      | Type                  | Description
 506   --------------------------|-----------------------|----------------------------------
 507   host\_name                | Object name           | **Required.** The name of the host this notification belongs to.
 508   service\_name             | Object name           | **Optional.** The short name of the service this notification belongs to. If omitted, this notification object is treated as host notification.
 509   vars                      | Dictionary            | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
 510   users                     | Array of object names | **Required.** A list of user names who should be notified. **Optional.** if the `user_groups` attribute is set.
 511   user\_groups              | Array of object names | **Required.** A list of user group names who should be notified. **Optional.** if the `users` attribute is set.
 512   times                     | Dictionary            | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
 513   command                   | Object name           | **Required.** The name of the notification command which should be executed when the notification is triggered.
 514   interval                  | Duration              | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, [re-notifications](03-monitoring-basics.md#disable-renotification) are disabled.
 515   period                    | Object name           | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
 516   zone                      | Object name           | **Optional.** The zone this object is a member of. Please read the [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring) chapter for details.
 517   types                     | Array                 | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
 518   states                    | Array                 | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched. Note that the states filter is ignored for notifications of type Acknowledgement!
 519
 520 Available notification state filters for Service:
 521
 522 ```
 523 OK
 524 Warning
 525 Critical
 526 Unknown
 527 ```
 528
 529 Available notification state filters for Host:
 530
 531 ```
 532 Up
 533 Down
 534 ```
 535
 536 Available notification type filters:
 537
 538 ```
 539 DowntimeStart
 540 DowntimeEnd
 541 DowntimeRemoved
 542 Custom
 543 Acknowledgement
 544 Problem
 545 Recovery
 546 FlappingStart
 547 FlappingEnd
 548 ```
 549
 550 Runtime Attributes:
 551
 552   Name                        | Type                  | Description
 553   ----------------------------|-----------------------|-----------------
 554   last\_notification          | Timestamp             | When the last notification was sent for this Notification object (as a UNIX timestamp).
 555   next\_notification          | Timestamp             | When the next notification is going to be sent for this assuming the associated host/service is still in a non-OK state (as a UNIX timestamp).
 556   notification\_number        | Number                | The notification number.
 557   last\_problem\_notification | Timestamp             | When the last notification was sent for a problem (as a UNIX timestamp).
 558
 559
 560 ## NotificationCommand <a id="objecttype-notificationcommand"></a>
 561
 562 A notification command definition.
 563
 564 Example:
 565
 566 ```
 567 object NotificationCommand "mail-service-notification" {
 568   command = [ ConfigDir + "/scripts/mail-service-notification.sh" ]
 569
 570   arguments += {
 571     "-4" = {
 572       required = true
 573       value = "$notification_address$"
 574     }
 575     "-6" = "$notification_address6$"
 576     "-b" = "$notification_author$"
 577     "-c" = "$notification_comment$"
 578     "-d" = {
 579       required = true
 580       value = "$notification_date$"
 581     }
 582     "-e" = {
 583       required = true
 584       value = "$notification_servicename$"
 585     }
 586     "-f" = {
 587       value = "$notification_from$"
 588       description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
 589     }
 590     "-i" = "$notification_icingaweb2url$"
 591     "-l" = {
 592       required = true
 593       value = "$notification_hostname$"
 594     }
 595     "-n" = {
 596       required = true
 597       value = "$notification_hostdisplayname$"
 598     }
 599     "-o" = {
 600       required = true
 601       value = "$notification_serviceoutput$"
 602     }
 603     "-r" = {
 604       required = true
 605       value = "$notification_useremail$"
 606     }
 607     "-s" = {
 608       required = true
 609       value = "$notification_servicestate$"
 610     }
 611     "-t" = {
 612       required = true
 613       value = "$notification_type$"
 614     }
 615     "-u" = {
 616       required = true
 617       value = "$notification_servicedisplayname$"
 618     }
 619     "-v" = "$notification_logtosyslog$"
 620   }
 621
 622   vars += {
 623     notification_address = "$address$"
 624     notification_address6 = "$address6$"
 625     notification_author = "$notification.author$"
 626     notification_comment = "$notification.comment$"
 627     notification_type = "$notification.type$"
 628     notification_date = "$icinga.long_date_time$"
 629     notification_hostname = "$host.name$"
 630     notification_hostdisplayname = "$host.display_name$"
 631     notification_servicename = "$service.name$"
 632     notification_serviceoutput = "$service.output$"
 633     notification_servicestate = "$service.state$"
 634     notification_useremail = "$user.email$"
 635     notification_servicedisplayname = "$service.display_name$"
 636   }
 637 }
 638 ```
 639
 640 Configuration Attributes:
 641
 642   Name                      | Type                  | Description
 643   --------------------------|-----------------------|----------------------------------
 644   command                   | Array                 | **Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command. When using the "arguments" attribute this must be an array. Can be specified as function for advanced implementations.
 645   env                       | Dictionary            | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
 646   vars                      | Dictionary            | **Optional.** A dictionary containing custom attributes that are specific to this command.
 647   timeout                   | Duration              | **Optional.** The command timeout in seconds. Defaults to `1m`.
 648   arguments                 | Dictionary            | **Optional.** A dictionary of command arguments.
 649
 650 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
 651
 652 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
 653
 654 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
 655
 656 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
 657
 658 > **Best Practice**
 659 >
 660 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
 661 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
 662 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
 663 > type for `Host` or `Service`.
 664 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
 665
 666 Example:
 667
 668 ```
 669 object ScheduledDowntime "some-downtime" {
 670   host_name = "localhost"
 671   service_name = "ping4"
 672
 673   author = "icingaadmin"
 674   comment = "Some comment"
 675
 676   fixed = false
 677   duration = 30m
 678
 679   ranges = {
 680     "sunday" = "02:00-03:00"
 681   }
 682 }
 683 ```
 684
 685 Configuration Attributes:
 686
 687   Name                      | Type                  | Description
 688   --------------------------|-----------------------|----------------------------------
 689   host\_name                | Object name           | **Required.** The name of the host this scheduled downtime belongs to.
 690   service\_name             | Object name           | **Optional.** The short name of the service this scheduled downtime belongs to. If omitted, this downtime object is treated as host downtime.
 691   author                    | String                | **Required.** The author of the downtime.
 692   comment                   | String                | **Required.** A comment for the downtime.
 693   fixed                     | Boolean               | **Optional.** Whether this is a fixed downtime. Defaults to `true`.
 694   duration                  | Duration              | **Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
 695   ranges                    | Dictionary            | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
 696   child\_options            | String                | **Optional.** Schedule child downtimes. `DowntimeNoChildren` does not do anything, `DowntimeTriggeredChildren` schedules child downtimes triggered by this downtime, `DowntimeNonTriggeredChildren` schedules non-triggered downtimes. Defaults to `DowntimeNoChildren`.
 697
 698 ScheduledDowntime objects have composite names, i.e. their names are based
 699 on the `host_name` and `service_name` attributes and the
 700 name you specified. This means you can define more than one object
 701 with the same (short) name as long as one of the `host_name` and
 702 `service_name` attributes has a different value.
 703
 704
 705 ## Service <a id="objecttype-service"></a>
 706
 707 Service objects describe network services and how they should be checked
 708 by Icinga 2.
 709
 710 > **Best Practice**
 711 >
 712 > Rather than creating a `Service` object for a specific host it is usually easier
 713 > to just create a `Service` template and use the `apply` keyword to assign the
 714 > service to a number of hosts.
 715 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
 716
 717 Example:
 718
 719 ```
 720 object Service "uptime" {
 721   host_name = "localhost"
 722
 723   display_name = "localhost Uptime"
 724
 725   check_command = "snmp"
 726
 727   vars.snmp_community = "public"
 728   vars.snmp_oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
 729
 730   check_interval = 60s
 731   retry_interval = 15s
 732
 733   groups = [ "all-services", "snmp" ]
 734 }
 735 ```
 736
 737 Configuration Attributes:
 738
 739   Name                      | Type                  | Description
 740   --------------------------|-----------------------|----------------------------------
 741   display\_name             | String                | **Optional.** A short description of the service.
 742   host\_name                | Object name           | **Required.** The host this service belongs to. There must be a `Host` object with that name.
 743   groups                    | Array of object names | **Optional.** The service groups this service belongs to.
 744   vars                      | Dictionary            | **Optional.** A dictionary containing custom attributes that are specific to this service.
 745   check\_command            | Object name           | **Required.** The name of the check command.
 746   max\_check\_attempts      | Number                | **Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
 747   check\_period             | Object name           | **Optional.** The name of a time period which determines when this service should be checked. Not set by default.
 748   check\_timeout            | Duration              | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
 749   check\_interval           | Duration              | **Optional.** The check interval (in seconds). This interval is used for checks when the service is in a `HARD` state. Defaults to `5m`.
 750   retry\_interval           | Duration              | **Optional.** The retry interval (in seconds). This interval is used for checks when the service is in a `SOFT` state. Defaults to `1m`. Note: This does not affect the scheduling [after a passive check result](08-advanced-topics.md#check-result-freshness).
 751   enable\_notifications     | Boolean               | **Optional.** Whether notifications are enabled. Defaults to `true`.
 752   enable\_active\_checks    | Boolean               | **Optional.** Whether active checks are enabled. Defaults to `true`.
 753   enable\_passive\_checks   | Boolean               | **Optional.** Whether passive checks are enabled. Defaults to `true`.
 754   enable\_event\_handler    | Boolean               | **Optional.** Enables event handlers for this host. Defaults to `true`.
 755   enable\_flapping          | Boolean               | **Optional.** Whether flap detection is enabled. Defaults to `false`.
 756   flapping\_threshold\_high | Number                | **Optional.** Flapping upper bound in percent for a service to be considered flapping. `30.0`
 757   flapping\_threshold\_low  | Number                | **Optional.** Flapping lower bound in percent for a service to be considered  not flapping. `25.0`
 758   enable\_perfdata          | Boolean               | **Optional.** Whether performance data processing is enabled. Defaults to `true`.
 759   event\_command            | Object name           | **Optional.** The name of an event command that should be executed every time the service's state changes or the service is in a `SOFT` state.
 760   volatile                  | Boolean               | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
 761   zone                      | Object name           | **Optional.** The zone this object is a member of. Please read the [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring) chapter for details.
 762   name                      | String                | **Required.** The service name. Must be unique on a per-host basis. For advanced usage in [apply rules](03-monitoring-basics.md#using-apply) only.
 763   command\_endpoint         | Object name           | **Optional.** The endpoint where commands are executed on.
 764   notes                     | String                | **Optional.** Notes for the service.
 765   notes\_url                | String                | **Optional.** URL for notes for the service (for example, in notification commands).
 766   action\_url               | String                | **Optional.** URL for actions for the service (for example, an external graphing tool).
 767   icon\_image               | String                | **Optional.** Icon image for the service. Used by external interfaces only.
 768   icon\_image\_alt          | String                | **Optional.** Icon image description for the service. Used by external interface only.
 769
 770 Service objects have composite names, i.e. their names are based on the host\_name attribute and the name you specified. This means
 771 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
 772
 773 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
 774 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
 775
 776 Runtime Attributes:
 777
 778   Name                      | Type                  | Description
 779   --------------------------|-----------------------|----------------------------------
 780   next\_check               | Timestamp             | When the next check occurs (as a UNIX timestamp).
 781   last\_check               | Timestamp             | When the last check occurred (as a UNIX timestamp).
 782   check\_attempt            | Number                | The current check attempt number.
 783   state\_type               | Number                | The current state type (0 = SOFT, 1 = HARD).
 784   last\_state\_type         | Number                | The previous state type (0 = SOFT, 1 = HARD).
 785   last\_reachable           | Boolean               | Whether the service was reachable when the last check occurred.
 786   last\_check\_result       | CheckResult           | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
 787   last\_state\_change       | Timestamp             | When the last state change occurred (as a UNIX timestamp).
 788   last\_hard\_state\_change | Timestamp             | When the last hard state change occurred (as a UNIX timestamp).
 789   last\_in\_downtime        | Boolean               | Whether the service was in a downtime when the last check occurred.
 790   acknowledgement           | Number                | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
 791   acknowledgement\_expiry   | Timestamp             | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
 792   downtime\_depth           | Number                | Whether the service has one or more active downtimes.
 793   flapping\_last\_change    | Timestamp             | When the last flapping change occurred (as a UNIX timestamp).
 794   flapping\_current         | Number                | Current flapping value in percent (see flapping\_thresholds)
 795   flapping                  | Boolean               | Whether the host is flapping between states.
 796   state                     | Number                | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
 797   last\_state               | Number                | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
 798   last\_hard\_state         | Number                | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
 799   last\_state\_ok           | Timestamp             | When the last OK state occurred (as a UNIX timestamp).
 800   last\_state\_warning      | Timestamp             | When the last WARNING state occurred (as a UNIX timestamp).
 801   last\_state\_critical     | Timestamp             | When the last CRITICAL state occurred (as a UNIX timestamp).
 802   last\_state\_unknown      | Timestamp             | When the last UNKNOWN state occurred (as a UNIX timestamp).
 803
 804
 805 ## ServiceGroup <a id="objecttype-servicegroup"></a>
 806
 807 A group of services.
 808
 809 > **Best Practice**
 810 >
 811 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
 812
 813 Example:
 814
 815 ```
 816 object ServiceGroup "snmp" {
 817   display_name = "SNMP services"
 818 }
 819 ```
 820
 821 Configuration Attributes:
 822
 823   Name                      | Type                  | Description
 824   --------------------------|-----------------------|----------------------------------
 825   display\_name             | String                | **Optional.** A short description of the service group.
 826   groups                    | Array of object names | **Optional.** An array of nested group names.
 827
 828
 829
 830 ## TimePeriod <a id="objecttype-timeperiod"></a>
 831
 832 Time periods can be used to specify when hosts/services should be checked or to limit
 833 when notifications should be sent out.
 834
 835 Examples:
 836
 837 ```
 838 object TimePeriod "nonworkhours" {
 839   display_name = "Icinga 2 TimePeriod for non working hours"
 840
 841   ranges = {
 842     monday = "00:00-8:00,17:00-24:00"
 843     tuesday = "00:00-8:00,17:00-24:00"
 844     wednesday = "00:00-8:00,17:00-24:00"
 845     thursday = "00:00-8:00,17:00-24:00"
 846     friday = "00:00-8:00,16:00-24:00"
 847     saturday = "00:00-24:00"
 848     sunday = "00:00-24:00"
 849   }
 850 }
 851
 852 object TimePeriod "exampledays" {
 853     display_name = "Icinga 2 TimePeriod for random example days"
 854
 855     ranges = {
 856         //We still believe in Santa, no peeking!
 857         //Applies every 25th of December every year
 858         "december 25" = "00:00-24:00"
 859
 860         //Any point in time can be specified,
 861         //but you still have to use a range
 862         "2038-01-19" = "03:13-03:15"
 863
 864         //Evey 3rd day from the second monday of February
 865         //to 8th of November
 866         "monday 2 february - november 8 / 3" = "00:00-24:00"
 867     }
 868 }
 869 ```
 870
 871 Additional examples can be found [here](08-advanced-topics.md#timeperiods).
 872
 873 Configuration Attributes:
 874
 875   Name                      | Type                  | Description
 876   --------------------------|-----------------------|----------------------------------
 877   display\_name             | String                | **Optional.** A short description of the time period.
 878   ranges                    | Dictionary            | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
 879   prefer\_includes          | Boolean               | **Optional.** Whether to prefer timeperiods `includes` or `excludes`. Default to true.
 880   excludes                  | Array of object names | **Optional.** An array of timeperiods, which should exclude from your timerange.
 881   includes                  | Array of object names | **Optional.** An array of timeperiods, which should include into your timerange
 882
 883
 884 Runtime Attributes:
 885
 886   Name                      | Type                  | Description
 887   --------------------------|-----------------------|----------------------------------
 888   is\_inside                | Boolean               | Whether we're currently inside this timeperiod.
 889
 890
 891 ## User <a id="objecttype-user"></a>
 892
 893 A user.
 894
 895 Example:
 896
 897 ```
 898 object User "icingaadmin" {
 899   display_name = "Icinga 2 Admin"
 900   groups = [ "icingaadmins" ]
 901   email = "icinga@localhost"
 902   pager = "icingaadmin@localhost.localdomain"
 903
 904   period = "24x7"
 905
 906   states = [ OK, Warning, Critical, Unknown ]
 907   types = [ Problem, Recovery ]
 908
 909   vars.additional_notes = "This is the Icinga 2 Admin account."
 910 }
 911 ```
 912
 913 Available notification state filters:
 914
 915 ```
 916 OK
 917 Warning
 918 Critical
 919 Unknown
 920 Up
 921 Down
 922 ```
 923
 924 Available notification type filters:
 925
 926 ```
 927 DowntimeStart
 928 DowntimeEnd
 929 DowntimeRemoved
 930 Custom
 931 Acknowledgement
 932 Problem
 933 Recovery
 934 FlappingStart
 935 FlappingEnd
 936 ```
 937
 938 Configuration Attributes:
 939
 940   Name                      | Type                  | Description
 941   --------------------------|-----------------------|----------------------------------
 942   display\_name             | String                | **Optional.** A short description of the user.
 943   email                     | String                | **Optional.** An email string for this user. Useful for notification commands.
 944   pager                     | String                | **Optional.** A pager string for this user. Useful for notification commands.
 945   vars                      | Dictionary            | **Optional.** A dictionary containing custom attributes that are specific to this user.
 946   groups                    | Array of object names | **Optional.** An array of group names.
 947   enable\_notifications     | Boolean               | **Optional.** Whether notifications are enabled for this user. Defaults to true.
 948   period                    | Object name           | **Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default.
 949   types                     | Array                 | **Optional.** A set of type filters when a notification for this user should be triggered. By default everything is matched.
 950   states                    | Array                 | **Optional.** A set of state filters when a notification for this should be triggered. By default everything is matched.
 951
 952 Runtime Attributes:
 953
 954   Name                      | Type                  | Description
 955   --------------------------|-----------------------|----------------------------------
 956   last\_notification        | Timestamp             | When the last notification was sent for this user (as a UNIX timestamp).
 957
 958 ## UserGroup <a id="objecttype-usergroup"></a>
 959
 960 A user group.
 961
 962 > **Best Practice**
 963 >
 964 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
 965
 966 Example:
 967
 968 ```
 969 object UserGroup "icingaadmins" {
 970     display_name = "Icinga 2 Admin Group"
 971 }
 972 ```
 973
 974 Configuration Attributes:
 975
 976   Name                      | Type                  | Description
 977   --------------------------|-----------------------|----------------------------------
 978   display\_name             | String                | **Optional.** A short description of the user group.
 979   groups                    | Array of object names | **Optional.** An array of nested group names.
 980
 981
 982 ## Zone <a id="objecttype-zone"></a>
 983
 984 Zone objects are used to specify which Icinga 2 instances are located in a zone.
 985 Please read the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring) for additional details.
 986 Example:
 987
 988 ```
 989 object Zone "master" {
 990   endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]
 991
 992 }
 993
 994 object Zone "satellite" {
 995   endpoints = [ "icinga2-satellite1.localdomain" ]
 996   parent = "master"
 997 }
 998 ```
 999
1000 Configuration Attributes:
1001
1002   Name                      | Type                  | Description
1003   --------------------------|-----------------------|----------------------------------
1004   endpoints                 | Array of object names | **Optional.** Array of endpoint names located in this zone.
1005   parent                    | Object name           | **Optional.** The name of the parent zone. (Do not specify a global zone)
1006   global                    | Boolean               | **Optional.** Whether configuration files for this zone should be [synced](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync) to all endpoints. Defaults to `false`.
1007
1008 Zone objects cannot currently be created with the API.
1009
1010
1011 ## Runtime Objects <a id="object-types-runtime"></a>
1012
1013 These objects are generated at runtime by the daemon
1014 from API actions. Downtime objects are also created
1015 by ScheduledDowntime objects.
1016
1017 ### Comment <a id="objecttype-comment"></a>
1018
1019 Comments created at runtime are represented as objects.
1020 Note: This is for reference only. You can create comments
1021 with the [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) API action.
1022
1023 Example:
1024
1025 ```
1026 object Comment "my-comment" {
1027   host_name = "localhost"
1028   author = "icingaadmin"
1029   text = "This is a comment."
1030   entry_time = 1234567890
1031 }
1032 ```
1033
1034 Configuration Attributes:
1035
1036   Name                      | Type                  | Description
1037   --------------------------|-----------------------|----------------------------------
1038   host\_name                | Object name           | **Required.** The name of the host this comment belongs to.
1039   service\_name             | Object name           | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment.
1040   author                    | String                | **Required.** The author's name.
1041   text                      | String                | **Required.** The comment text.
1042   entry\_time               | Timestamp             | **Optional.** The UNIX timestamp when this comment was added. If omitted, the entry time is volatile!
1043   entry\_type               | Number                | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
1044   expire\_time              | Timestamp             | **Optional.** The comment's expire time as UNIX timestamp.
1045   persistent                | Boolean               | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
1046
1047 ### Downtime <a id="objecttype-downtime"></a>
1048
1049 Downtimes created at runtime are represented as objects.
1050 You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action.
1051
1052 Example:
1053
1054 ```
1055 object Downtime "my-downtime" {
1056   host_name = "localhost"
1057   author = "icingaadmin"
1058   comment = "This is a downtime."
1059   start_time = 1505312869
1060   end_time = 1505312924
1061 }
1062 ```
1063
1064 Configuration Attributes:
1065
1066   Name                      | Type                  | Description
1067   --------------------------|-----------------------|----------------------------------
1068   host\_name                | Object name           | **Required.** The name of the host this comment belongs to.
1069   service\_name             | Object name           | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment.
1070   author                    | String                | **Required.** The author's name.
1071   comment                   | String                | **Required.** The comment text.
1072   start\_time               | Timestamp             | **Required.** The start time as UNIX timestamp.
1073   end\_time                 | Timestamp             | **Required.** The end time as UNIX timestamp.
1074   duration                  | Number                | **Optional.** The duration as number.
1075   entry\_time               | Timestamp             | **Optional.** The UNIX timestamp when this downtime was added.
1076   fixed                     | Boolean               | **Optional.** Whether the downtime is fixed (true) or flexible (false). Defaults to flexible. Details in the [advanced topics chapter](08-advanced-topics.md#fixed-flexible-downtimes).
1077   triggers                  | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime.
1078
1079 Runtime Attributes:
1080
1081   Name                      | Type                  | Description
1082   --------------------------|-----------------------|----------------------------------
1083   trigger\_time             | Timestamp             | The UNIX timestamp when this downtime was triggered.
1084   triggered\_by             | Object name           | The name of the downtime this downtime was triggered by.
1085
1086
1087
1088 ## Features <a id="object-types-features"></a>
1089
1090 ### ApiListener <a id="objecttype-apilistener"></a>
1091
1092 ApiListener objects are used for distributed monitoring setups
1093 and API usage specifying the certificate files used for ssl
1094 authorization and additional restrictions.
1095 This configuration object is available as [api feature](11-cli-commands.md#cli-command-feature).
1096
1097 The `TicketSalt` constant must be defined in [constants.conf](04-configuring-icinga-2.md#constants-conf).
1098
1099 Example:
1100
1101 ```
1102 object ApiListener "api" {
1103   accept_commands = true
1104   accept_config = true
1105
1106   ticket_salt = TicketSalt
1107 }
1108 ```
1109
1110 Configuration Attributes:
1111
1112   Name                                  | Type                  | Description
1113   --------------------------------------|-----------------------|----------------------------------
1114   cert\_path                            | String                | **Deprecated.** Path to the public key.
1115   key\_path                             | String                | **Deprecated.** Path to the private key.
1116   ca\_path                              | String                | **Deprecated.** Path to the CA certificate file.
1117   ticket\_salt                          | String                | **Optional.** Private key for [CSR auto-signing](06-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing). **Required** for a signing master instance.
1118   crl\_path                             | String                | **Optional.** Path to the CRL file.
1119   bind\_host                            | String                | **Optional.** The IP address the api listener should be bound to. If not specified, the ApiListener is bound to `::` and listens for both IPv4 and IPv6 connections.
1120   bind\_port                            | Number                | **Optional.** The port the api listener should be bound to. Defaults to `5665`.
1121   accept\_config                        | Boolean               | **Optional.** Accept zone configuration. Defaults to `false`.
1122   accept\_commands                      | Boolean               | **Optional.** Accept remote commands. Defaults to `false`.
1123   max\_anonymous\_clients               | Number                | **Optional.** Limit the number of anonymous client connections (not configured endpoints and signing requests).
1124   cipher\_list                          | String                | **Optional.** Cipher list that is allowed. For a list of available ciphers run `openssl ciphers`. Defaults to `ALL:!LOW:!WEAK:!MEDIUM:!EXP:!NULL`.
1125   tls\_protocolmin                      | String                | **Optional.** Minimum TLS protocol version. Must be one of `TLSv1`, `TLSv1.1` or `TLSv1.2`. Defaults to `TLSv1`.
1126   tls\_handshake\_timeout               | Number                | **Optional.** TLS Handshake timeout. Defaults to `10s`.
1127   access\_control\_allow\_origin        | Array                 | **Optional.** Specifies an array of origin URLs that may access the API. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Origin)
1128   access\_control\_allow\_credentials   | Boolean               | **Deprecated.** Indicates whether or not the actual request can be made using credentials. Defaults to `true`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Credentials)
1129   access\_control\_allow\_headers       | String                | **Deprecated.** Used in response to a preflight request to indicate which HTTP headers can be used when making the actual request. Defaults to `Authorization`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Headers)
1130   access\_control\_allow\_methods       | String                | **Deprecated.** Used in response to a preflight request to indicate which HTTP methods can be used when making the actual request. Defaults to `GET, POST, PUT, DELETE`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Methods)
1131   environment                           | String                | **Optional.** Used as suffix in TLS SNI extension name; default from constant `ApiEnvironment`, which is empty.
1132
1133 The attributes `access_control_allow_credentials`, `access_control_allow_headers` and `access_control_allow_methods`
1134 are controlled by Icinga 2 and are not changeable by config any more.
1135
1136
1137 The ApiListener type expects its certificate files to be in the following locations:
1138
1139   Type                 | Location
1140   ---------------------|-------------------------------------
1141   Private key          | `DataDir + "/certs/" + NodeName + ".key"`
1142   Certificate file     | `DataDir + "/certs/" + NodeName + ".crt"`
1143   CA certificate file  | `DataDir + "/certs/ca.crt"`
1144
1145 If the deprecated attributes `cert_path`, `key_path` and/or `ca_path` are specified Icinga 2
1146 copies those files to the new location in `DataDir + "/certs"` unless the
1147 file(s) there are newer.
1148
1149 Please check the [upgrading chapter](16-upgrading-icinga-2.md#upgrading-to-2-8-certificate-paths) for more details.
1150
1151 While Icinga 2 and the underlying OpenSSL library use sane and secure defaults, the attributes
1152 `cipher_list` and `tls_protocolmin` can be used to increase communication security. A good source
1153 for a more secure configuration is provided by the [Mozilla Wiki](https://wiki.mozilla.org/Security/Server_Side_TLS).
1154 Ensure to use the same configuration for both attributes on **all** endpoints to avoid communication problems which
1155 requires to use `cipher_list` compatible with the endpoint using the oldest version of the OpenSSL library. If using
1156 other tools to connect to the API ensure also compatibility with them as this setting affects not only inter-cluster
1157 communcation but also the REST API.
1158
1159 ### CheckerComponent <a id="objecttype-checkercomponent"></a>
1160
1161 The checker component is responsible for scheduling active checks.
1162 This configuration object is available as [checker feature](11-cli-commands.md#cli-command-feature).
1163
1164 Example:
1165
1166 ```
1167 object CheckerComponent "checker" { }
1168 ```
1169
1170 In order to limit the concurrent checks on a master/satellite endpoint,
1171 use [MaxConcurrentChecks](17-language-reference.md#icinga-constants-global-config) constant.
1172 This also applies to an agent as command endpoint where the checker
1173 feature is disabled.
1174
1175 ### CheckResultReader <a id="objecttype-checkresultreader"></a>
1176
1177 Reads Icinga 1.x check result files from a directory. This functionality is provided
1178 to help existing Icinga 1.x users and might be useful for migration scenarios.
1179
1180 > **Note**
1181 >
1182 > This feature is DEPRECATED and will be removed in future releases.
1183 > Check the [roadmap](https://github.com/Icinga/icinga2/milestones).
1184
1185 Example:
1186
1187 ```
1188 object CheckResultReader "reader" {
1189   spool_dir = "/data/check-results"
1190 }
1191 ```
1192
1193 Configuration Attributes:
1194
1195   Name                      | Type                  | Description
1196   --------------------------|-----------------------|----------------------------------
1197   spool\_dir                | String                | **Optional.** The directory which contains the check result files. Defaults to DataDir + "/spool/checkresults/".
1198
1199 ### CompatLogger <a id="objecttype-compatlogger"></a>
1200
1201 Writes log files in a format that's compatible with Icinga 1.x.
1202 This configuration object is available as [compatlog feature](14-features.md#compat-logging).
1203
1204 > **Note**
1205 >
1206 > This feature is DEPRECATED and will be removed in future releases.
1207 > Check the [roadmap](https://github.com/Icinga/icinga2/milestones).
1208
1209 Example:
1210
1211 ```
1212 object CompatLogger "compatlog" {
1213   log_dir = "/var/log/icinga2/compat"
1214   rotation_method = "DAILY"
1215 }
1216 ```
1217
1218 Configuration Attributes:
1219
1220   Name                      | Type                  | Description
1221   --------------------------|-----------------------|----------------------------------
1222   log\_dir                  | String                | **Optional.** Path to the compat log directory. Defaults to LogDir + "/compat".
1223   rotation\_method          | String                | **Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
1224
1225
1226 ### ElasticsearchWriter <a id="objecttype-elasticsearchwriter"></a>
1227
1228 Writes check result metrics and performance data to an Elasticsearch instance.
1229 This configuration object is available as [elasticsearch feature](14-features.md#elasticsearch-writer).
1230
1231 Example:
1232
1233 ```
1234 object ElasticsearchWriter "elasticsearch" {
1235   host = "127.0.0.1"
1236   port = 9200
1237   index = "icinga2"
1238
1239   enable_send_perfdata = true
1240
1241   flush_threshold = 1024
1242   flush_interval = 10
1243 }
1244 ```
1245
1246 The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
1247
1248 Configuration Attributes:
1249
1250   Name                      | Type                  | Description
1251   --------------------------|-----------------------|----------------------------------
1252   host                      | String                | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
1253   port                      | Number                | **Required.** Elasticsearch port. Defaults to `9200`.
1254   index                     | String                | **Required.** Elasticsearch index name. Defaults to `icinga2`.
1255   enable\_send\_perfdata    | Boolean               | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
1256   flush\_interval           | Duration              | **Optional.** How long to buffer data points before transferring to Elasticsearch. Defaults to `10s`.
1257   flush\_threshold          | Number                | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch.  Defaults to `1024`.
1258   username                  | String                | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
1259   password                  | String                | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
1260   enable\_tls               | Boolean               | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
1261   ca\_path                  | String                | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
1262   cert\_path                | String                | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
1263   key\_path                 | String                | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
1264   enable\_ha                | Boolean               | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
1265
1266 Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
1267 Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
1268
1269 Basic auth is supported with the `username` and `password` attributes. This requires an
1270 HTTP proxy (Nginx, etc.) in front of the Elasticsearch instance. Check [this blogpost](https://blog.netways.de/2017/09/14/secure-elasticsearch-and-kibana-with-an-nginx-http-proxy/)
1271 for an example.
1272
1273 TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
1274 you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
1275
1276 ### ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
1277
1278 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
1279 This configuration object is available as [command feature](14-features.md#external-commands).
1280
1281 > **Note**
1282 >
1283 > This feature is DEPRECATED and will be removed in future releases.
1284 > Check the [roadmap](https://github.com/Icinga/icinga2/milestones).
1285
1286 Example:
1287
1288 ```
1289 object ExternalCommandListener "command" {
1290     command_path = "/var/run/icinga2/cmd/icinga2.cmd"
1291 }
1292 ```
1293
1294 Configuration Attributes:
1295
1296   Name                      | Type                  | Description
1297   --------------------------|-----------------------|----------------------------------
1298   command\_path             | String                | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
1299
1300
1301
1302 ### FileLogger <a id="objecttype-filelogger"></a>
1303
1304 Specifies Icinga 2 logging to a file.
1305 This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging).
1306
1307 Example:
1308
1309 ```
1310 object FileLogger "debug-file" {
1311   severity = "debug"
1312   path = "/var/log/icinga2/debug.log"
1313 }
1314 ```
1315
1316 Configuration Attributes:
1317
1318   Name                      | Type                  | Description
1319   --------------------------|-----------------------|----------------------------------
1320   path                      | String                | **Required.** The log path.
1321   severity                  | String                | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
1322
1323
1324 ### GelfWriter <a id="objecttype-gelfwriter"></a>
1325
1326 Writes event log entries to a defined GELF receiver host (Graylog, Logstash).
1327 This configuration object is available as [gelf feature](14-features.md#gelfwriter).
1328
1329 Example:
1330
1331 ```
1332 object GelfWriter "gelf" {
1333   host = "127.0.0.1"
1334   port = 12201
1335 }
1336 ```
1337
1338 Configuration Attributes:
1339
1340   Name                      | Type                  | Description
1341   --------------------------|-----------------------|----------------------------------
1342   host                      | String                | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`.
1343   port                      | Number                | **Optional.** GELF receiver port. Defaults to `12201`.
1344   source                    | String                | **Optional.** Source name for this instance. Defaults to `icinga2`.
1345   enable\_send\_perfdata    | Boolean               | **Optional.** Enable performance data for 'CHECK RESULT' events.
1346   enable\_ha                | Boolean               | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
1347
1348
1349 ### GraphiteWriter <a id="objecttype-graphitewriter"></a>
1350
1351 Writes check result metrics and performance data to a defined
1352 Graphite Carbon host.
1353 This configuration object is available as [graphite feature](14-features.md#graphite-carbon-cache-writer).
1354
1355 Example:
1356
1357 ```
1358 object GraphiteWriter "graphite" {
1359   host = "127.0.0.1"
1360   port = 2003
1361 }
1362 ```
1363
1364 Configuration Attributes:
1365
1366   Name                      | Type                  | Description
1367   --------------------------|-----------------------|----------------------------------
1368   host                      | String                | **Optional.** Graphite Carbon host address. Defaults to `127.0.0.1`.
1369   port                      | Number                | **Optional.** Graphite Carbon port. Defaults to `2003`.
1370   host\_name\_template      | String                | **Optional.** Metric prefix for host name. Defaults to `icinga2.$host.name$.host.$host.check_command$`.
1371   service\_name\_template   | String                | **Optional.** Metric prefix for service name. Defaults to `icinga2.$host.name$.services.$service.name$.$service.check_command$`.
1372   enable\_send\_thresholds  | Boolean               | **Optional.** Send additional threshold metrics. Defaults to `false`.
1373   enable\_send\_metadata    | Boolean               | **Optional.** Send additional metadata metrics. Defaults to `false`.
1374   enable\_ha                | Boolean               | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
1375
1376 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
1377
1378
1379 ### IcingaApplication <a id="objecttype-icingaapplication"></a>
1380
1381 The IcingaApplication object is required to start Icinga 2.
1382 The object name must be `app`. If the object configuration
1383 is missing, Icinga 2 will automatically create an IcingaApplication
1384 object.
1385
1386 Example:
1387
1388 ```
1389 object IcingaApplication "app" {
1390   enable_perfdata = false
1391 }
1392 ```
1393
1394 Configuration Attributes:
1395
1396   Name                      | Type                  | Description
1397   --------------------------|-----------------------|----------------------------------
1398   enable\_notifications     | Boolean               | **Optional.** Whether notifications are globally enabled. Defaults to true.
1399   enable\_event\_handlers   | Boolean               | **Optional.** Whether event handlers are globally enabled. Defaults to true.
1400   enable\_flapping          | Boolean               | **Optional.** Whether flap detection is globally enabled. Defaults to true.
1401   enable\_host\_checks      | Boolean               | **Optional.** Whether active host checks are globally enabled. Defaults to true.
1402   enable\_service\_checks   | Boolean               | **Optional.** Whether active service checks are globally enabled. Defaults to true.
1403   enable\_perfdata          | Boolean               | **Optional.** Whether performance data processing is globally enabled. Defaults to true.
1404   vars                      | Dictionary            | **Optional.** A dictionary containing custom attributes that are available globally.
1405   environment               | String                | **Optional.** Specify the Icinga environment. This overrides the `Environment` constant specified in the configuration or on the CLI with `--define`. Defaults to empty.
1406
1407 ### IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
1408
1409 IDO database adapter for MySQL.
1410 This configuration object is available as [ido-mysql feature](14-features.md#db-ido).
1411
1412 Example:
1413
1414 ```
1415 object IdoMysqlConnection "mysql-ido" {
1416   host = "127.0.0.1"
1417   port = 3306
1418   user = "icinga"
1419   password = "icinga"
1420   database = "icinga"
1421
1422   cleanup = {
1423     downtimehistory_age = 48h
1424     contactnotifications_age = 31d
1425   }
1426 }
1427 ```
1428
1429 Configuration Attributes:
1430
1431   Name                      | Type                  | Description
1432   --------------------------|-----------------------|----------------------------------
1433   host                      | String                | **Optional.** MySQL database host address. Defaults to `localhost`.
1434   port                      | Number                | **Optional.** MySQL database port. Defaults to `3306`.
1435   socket\_path              | String                | **Optional.** MySQL socket path.
1436   user                      | String                | **Optional.** MySQL database user with read/write permission to the icinga database. Defaults to `icinga`.
1437   password                  | String                | **Optional.** MySQL database user's password. Defaults to `icinga`.
1438   database                  | String                | **Optional.** MySQL database name. Defaults to `icinga`.
1439   enable\_ssl               | Boolean               | **Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
1440   ssl\_key                  | String                | **Optional.** MySQL SSL client key file path.
1441   ssl\_cert                 | String                | **Optional.** MySQL SSL certificate file path.
1442   ssl\_ca                   | String                | **Optional.** MySQL SSL certificate authority certificate file path.
1443   ssl\_capath               | String                | **Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
1444   ssl\_cipher               | String                | **Optional.** MySQL SSL list of allowed ciphers.
1445   table\_prefix             | String                | **Optional.** MySQL database table prefix. Defaults to `icinga_`.
1446   instance\_name            | String                | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
1447   instance\_description     | String                | **Optional.** Description for the Icinga 2 instance.
1448   enable\_ha                | Boolean               | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to `true`.
1449   failover\_timeout         | Duration              | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 30s. Defaults to `30s`.
1450   cleanup                   | Dictionary            | **Optional.** Dictionary with items for historical table cleanup.
1451   categories                | Array                 | **Optional.** Array of information types that should be written to the database.
1452
1453 Cleanup Items:
1454
1455   Name                            | Type                  | Description
1456   --------------------------------|-----------------------|----------------------------------
1457   acknowledgements\_age           | Duration              | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
1458   commenthistory\_age             | Duration              | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
1459   contactnotifications\_age       | Duration              | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
1460   contactnotificationmethods\_age | Duration              | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
1461   downtimehistory\_age            | Duration              | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
1462   eventhandlers\_age              | Duration              | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
1463   externalcommands\_age           | Duration              | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
1464   flappinghistory\_age            | Duration              | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
1465   hostchecks\_age                 | Duration              | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
1466   logentries\_age                 | Duration              | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
1467   notifications\_age              | Duration              | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
1468   processevents\_age              | Duration              | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
1469   statehistory\_age               | Duration              | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
1470   servicechecks\_age              | Duration              | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
1471   systemcommands\_age             | Duration              | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
1472
1473 Data Categories:
1474
1475   Name                 | Description            | Required by
1476   ---------------------|------------------------|--------------------
1477   DbCatConfig          | Configuration data     | Icinga Web 2
1478   DbCatState           | Current state data     | Icinga Web 2
1479   DbCatAcknowledgement | Acknowledgements       | Icinga Web 2
1480   DbCatComment         | Comments               | Icinga Web 2
1481   DbCatDowntime        | Downtimes              | Icinga Web 2
1482   DbCatEventHandler    | Event handler data     | Icinga Web 2
1483   DbCatExternalCommand | External commands      | --
1484   DbCatFlapping        | Flap detection data    | Icinga Web 2
1485   DbCatCheck           | Check results          | --
1486   DbCatLog             | Log messages           | --
1487   DbCatNotification    | Notifications          | Icinga Web 2
1488   DbCatProgramStatus   | Program status data    | Icinga Web 2
1489   DbCatRetention       | Retention data         | Icinga Web 2
1490   DbCatStateHistory    | Historical state data  | Icinga Web 2
1491
1492 The default value for `categories` includes everything required
1493 by Icinga Web 2 in the table above.
1494
1495 In addition to the category flags listed above the `DbCatEverything`
1496 flag may be used as a shortcut for listing all flags.
1497
1498 Runtime Attributes:
1499
1500   Name                        | Type                  | Description
1501   ----------------------------|-----------------------|-----------------
1502   last\_failover              | Timestamp             | When the last failover happened for this connection (only available with `enable_ha = true`.
1503
1504 ### IdoPgsqlConnection <a id="objecttype-idopgsqlconnection"></a>
1505
1506 IDO database adapter for PostgreSQL.
1507 This configuration object is available as [ido-pgsql feature](14-features.md#db-ido).
1508
1509 Example:
1510
1511 ```
1512 object IdoPgsqlConnection "pgsql-ido" {
1513   host = "127.0.0.1"
1514   port = 5432
1515   user = "icinga"
1516   password = "icinga"
1517   database = "icinga"
1518
1519   cleanup = {
1520     downtimehistory_age = 48h
1521     contactnotifications_age = 31d
1522   }
1523 }
1524 ```
1525
1526 Configuration Attributes:
1527
1528   Name                      | Type                  | Description
1529   --------------------------|-----------------------|----------------------------------
1530   host                      | String                | **Optional.** PostgreSQL database host address. Defaults to `localhost`.
1531   port                      | Number                | **Optional.** PostgreSQL database port. Defaults to `5432`.
1532   user                      | String                | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`.
1533   password                  | String                | **Optional.** PostgreSQL database user's password. Defaults to `icinga`.
1534   database                  | String                | **Optional.** PostgreSQL database name. Defaults to `icinga`.
1535   ssl\_mode                 | String                | **Optional.** Enable SSL connection mode. Value must be set according to the [sslmode setting](https://www.postgresql.org/docs/9.3/static/libpq-connect.html#LIBPQ-CONNSTRING): `prefer`, `require`, `verify-ca`, `verify-full`, `allow`, `disable`.
1536   ssl\_key                  | String                | **Optional.** PostgreSQL SSL client key file path.
1537   ssl\_cert                 | String                | **Optional.** PostgreSQL SSL certificate file path.
1538   ssl\_ca                   | String                | **Optional.** PostgreSQL SSL certificate authority certificate file path.
1539   table\_prefix             | String                | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`.
1540   instance\_name            | String                | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
1541   instance\_description     | String                | **Optional.** Description for the Icinga 2 instance.
1542   enable\_ha                | Boolean               | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to `true`.
1543   failover\_timeout         | Duration              | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 30s. Defaults to `30s`.
1544   cleanup                   | Dictionary            | **Optional.** Dictionary with items for historical table cleanup.
1545   categories                | Array                 | **Optional.** Array of information types that should be written to the database.
1546
1547 Cleanup Items:
1548
1549   Name                            | Type                  | Description
1550   --------------------------------|-----------------------|----------------------------------
1551   acknowledgements\_age           | Duration              | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
1552   commenthistory\_age             | Duration              | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
1553   contactnotifications\_age       | Duration              | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
1554   contactnotificationmethods\_age | Duration              | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
1555   downtimehistory\_age            | Duration              | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
1556   eventhandlers\_age              | Duration              | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
1557   externalcommands\_age           | Duration              | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
1558   flappinghistory\_age            | Duration              | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
1559   hostchecks\_age                 | Duration              | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
1560   logentries\_age                 | Duration              | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
1561   notifications\_age              | Duration              | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
1562   processevents\_age              | Duration              | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
1563   statehistory\_age               | Duration              | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
1564   servicechecks\_age              | Duration              | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
1565   systemcommands\_age             | Duration              | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
1566
1567 Data Categories:
1568
1569   Name                 | Description            | Required by
1570   ---------------------|------------------------|--------------------
1571   DbCatConfig          | Configuration data     | Icinga Web 2
1572   DbCatState           | Current state data     | Icinga Web 2
1573   DbCatAcknowledgement | Acknowledgements       | Icinga Web 2
1574   DbCatComment         | Comments               | Icinga Web 2
1575   DbCatDowntime        | Downtimes              | Icinga Web 2
1576   DbCatEventHandler    | Event handler data     | Icinga Web 2
1577   DbCatExternalCommand | External commands      | --
1578   DbCatFlapping        | Flap detection data    | Icinga Web 2
1579   DbCatCheck           | Check results          | --
1580   DbCatLog             | Log messages           | --
1581   DbCatNotification    | Notifications          | Icinga Web 2
1582   DbCatProgramStatus   | Program status data    | Icinga Web 2
1583   DbCatRetention       | Retention data         | Icinga Web 2
1584   DbCatStateHistory    | Historical state data  | Icinga Web 2
1585
1586 The default value for `categories` includes everything required
1587 by Icinga Web 2 in the table above.
1588
1589 In addition to the category flags listed above the `DbCatEverything`
1590 flag may be used as a shortcut for listing all flags.
1591
1592 Runtime Attributes:
1593
1594   Name                        | Type                  | Description
1595   ----------------------------|-----------------------|-----------------
1596   last\_failover              | Timestamp             | When the last failover happened for this connection (only available with `enable_ha = true`.
1597
1598 ### InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
1599
1600 Writes check result metrics and performance data to a defined InfluxDB host.
1601 This configuration object is available as [influxdb feature](14-features.md#influxdb-writer).
1602
1603 Example:
1604
1605 ```
1606 object InfluxdbWriter "influxdb" {
1607   host = "127.0.0.1"
1608   port = 8086
1609   database = "icinga2"
1610
1611   flush_threshold = 1024
1612   flush_interval = 10s
1613
1614   host_template = {
1615     measurement = "$host.check_command$"
1616     tags = {
1617       hostname = "$host.name$"
1618     }
1619   }
1620   service_template = {
1621     measurement = "$service.check_command$"
1622     tags = {
1623       hostname = "$host.name$"
1624       service = "$service.name$"
1625     }
1626   }
1627 }
1628 ```
1629
1630 Configuration Attributes:
1631
1632   Name                      | Type                  | Description
1633   --------------------------|-----------------------|----------------------------------
1634   host                      | String                | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
1635   port                      | Number                | **Required.** InfluxDB HTTP port. Defaults to `8086`.
1636   database                  | String                | **Required.** InfluxDB database name. Defaults to `icinga2`.
1637   username                  | String                | **Optional.** InfluxDB user name. Defaults to `none`.
1638   password                  | String                | **Optional.** InfluxDB user password.  Defaults to `none`.
1639   ssl\_enable               | Boolean               | **Optional.** Whether to use a TLS stream. Defaults to `false`.
1640   ssl\_ca\_cert             | String                | **Optional.** Path to CA certificate to validate the remote host.
1641   ssl\_cert                 | String                | **Optional.** Path to host certificate to present to the remote host for mutual verification.
1642   ssl\_key                  | String                | **Optional.** Path to host key to accompany the ssl\_cert.
1643   host\_template            | String                | **Required.** Host template to define the InfluxDB line protocol.
1644   service\_template         | String                | **Required.** Service template to define the influxDB line protocol.
1645   enable\_send\_thresholds  | Boolean               | **Optional.** Whether to send warn, crit, min & max tagged data.
1646   enable\_send\_metadata    | Boolean               | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
1647   flush\_interval           | Duration              | **Optional.** How long to buffer data points before transferring to InfluxDB. Defaults to `10s`.
1648   flush\_threshold          | Number                | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB.  Defaults to `1024`.
1649   enable\_ha                | Boolean               | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
1650
1651 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
1652 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
1653 or similar.
1654
1655
1656
1657 ### LiveStatusListener <a id="objecttype-livestatuslistener"></a>
1658
1659 Livestatus API interface available as TCP or UNIX socket. Historical table queries
1660 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
1661 pointing to the log files using the `compat_log_path` configuration attribute.
1662 This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus).
1663
1664 Examples:
1665
1666 ```
1667 object LivestatusListener "livestatus-tcp" {
1668   socket_type = "tcp"
1669   bind_host = "127.0.0.1"
1670   bind_port = "6558"
1671 }
1672
1673 object LivestatusListener "livestatus-unix" {
1674   socket_type = "unix"
1675   socket_path = "/var/run/icinga2/cmd/livestatus"
1676 }
1677 ```
1678
1679 Configuration Attributes:
1680
1681   Name                      | Type                  | Description
1682   --------------------------|-----------------------|----------------------------------
1683   socket\_type              | String                | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`.
1684   bind\_host                | String                | **Optional.** Only valid when `socket_type` is set to `tcp`. Host address to listen on for connections. Defaults to `127.0.0.1`.
1685   bind\_port                | Number                | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`.
1686   socket\_path              | String                | **Optional.** Only valid when `socket_type` is set to `unix`. Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus".
1687   compat\_log\_path         | String                | **Optional.** Path to Icinga 1.x log files. Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LogDir + "/compat"
1688
1689 > **Note**
1690 >
1691 > UNIX sockets are not supported on Windows.
1692
1693 ### NotificationComponent <a id="objecttype-notificationcomponent"></a>
1694
1695 The notification component is responsible for sending notifications.
1696 This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature).
1697
1698 Example:
1699
1700 ```
1701 object NotificationComponent "notification" { }
1702 ```
1703
1704 Configuration Attributes:
1705
1706   Name                      | Type                  | Description
1707   --------------------------|-----------------------|----------------------------------
1708   enable\_ha                | Boolean               | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-notifications). Disabling this currently only affects reminder notifications. Defaults to "true".
1709
1710 ### OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1711
1712 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1713 This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer).
1714
1715 Example:
1716
1717 ```
1718 object OpenTsdbWriter "opentsdb" {
1719   host = "127.0.0.1"
1720   port = 4242
1721 }
1722 ```
1723
1724 Configuration Attributes:
1725
1726   Name                      | Type                  | Description
1727   --------------------------|-----------------------|----------------------------------
1728   host                      | String                | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`.
1729   port                      | Number                | **Optional.** OpenTSDB port. Defaults to `4242`.
1730   enable\_ha                | Boolean               | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
1731
1732
1733 ### PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1734
1735 Writes check result performance data to a defined path using macro
1736 pattern consisting of custom attributes and runtime macros.
1737 This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files).
1738
1739 Example:
1740
1741 ```
1742 object PerfdataWriter "perfdata" {
1743   host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1744
1745   service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1746
1747   host_format_template = "DATATYPE::HOSTPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tHOSTPERFDATA::$host.perfdata$\tHOSTCHECKCOMMAND::$host.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$"
1748   service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.name$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.state_type$"
1749
1750   rotation_interval = 15s
1751 }
1752 ```
1753
1754 Configuration Attributes:
1755
1756   Name                      | Type                  | Description
1757   --------------------------|-----------------------|----------------------------------
1758   host\_perfdata\_path      | String                | **Optional.** Path to the host performance data file. Defaults to SpoolDir + "/perfdata/host-perfdata".
1759   service\_perfdata\_path   | String                | **Optional.** Path to the service performance data file. Defaults to SpoolDir + "/perfdata/service-perfdata".
1760   host\_temp\_path          | String                | **Optional.** Path to the temporary host file. Defaults to SpoolDir + "/tmp/host-perfdata".
1761   service\_temp\_path       | String                | **Optional.** Path to the temporary service file. Defaults to SpoolDir + "/tmp/service-perfdata".
1762   host\_format\_template    | String                | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1763   service\_format\_template | String                | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1764   rotation\_interval        | Duration              | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`.
1765   enable\_ha                | Boolean               | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
1766
1767 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1768 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1769
1770
1771 ### StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1772
1773 Periodically writes status and configuration data files which are used by third-party tools.
1774 This configuration object is available as [statusdata feature](14-features.md#status-data).
1775
1776 > **Note**
1777 >
1778 > This feature is DEPRECATED and will be removed in future releases.
1779 > Check the [roadmap](https://github.com/Icinga/icinga2/milestones).
1780
1781 Example:
1782
1783 ```
1784 object StatusDataWriter "status" {
1785     status_path = "/var/cache/icinga2/status.dat"
1786     objects_path = "/var/cache/icinga2/objects.cache"
1787     update_interval = 30s
1788 }
1789 ```
1790
1791 Configuration Attributes:
1792
1793   Name                      | Type                  | Description
1794   --------------------------|-----------------------|----------------------------------
1795   status\_path              | String                | **Optional.** Path to the `status.dat` file. Defaults to CacheDir + "/status.dat".
1796   objects\_path             | String                | **Optional.** Path to the `objects.cache` file. Defaults to CacheDir + "/objects.cache".
1797   update\_interval          | Duration              | **Optional.** The interval in which the status files are updated. Defaults to `15s`.
1798
1799 ### SyslogLogger <a id="objecttype-sysloglogger"></a>
1800
1801 Specifies Icinga 2 logging to syslog.
1802 This configuration object is available as `syslog` [logging feature](14-features.md#logging).
1803
1804 Example:
1805
1806 ```
1807 object SyslogLogger "syslog" {
1808   severity = "warning"
1809 }
1810 ```
1811
1812 Configuration Attributes:
1813
1814   Name                      | Type                  | Description
1815   --------------------------|-----------------------|----------------------------------
1816   severity                  | String                | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1817   facility                  | String                | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`.
1818
1819 Facility Constants:
1820
1821   Name                 | Facility      | Description
1822   ---------------------|---------------|----------------
1823   FacilityAuth         | LOG\_AUTH     | The authorization system.
1824   FacilityAuthPriv     | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals.
1825   FacilityCron         | LOG\_CRON     | The cron daemon.
1826   FacilityDaemon       | LOG\_DAEMON   | System daemons that are not provided for explicitly by other facilities.
1827   FacilityFtp          | LOG\_FTP      | The file transfer protocol daemons.
1828   FacilityKern         | LOG\_KERN     | Messages generated by the kernel. These cannot be generated by any user processes.
1829   FacilityLocal0       | LOG\_LOCAL0   | Reserved for local use.
1830   FacilityLocal1       | LOG\_LOCAL1   | Reserved for local use.
1831   FacilityLocal2       | LOG\_LOCAL2   | Reserved for local use.
1832   FacilityLocal3       | LOG\_LOCAL3   | Reserved for local use.
1833   FacilityLocal4       | LOG\_LOCAL4   | Reserved for local use.
1834   FacilityLocal5       | LOG\_LOCAL5   | Reserved for local use.
1835   FacilityLocal6       | LOG\_LOCAL6   | Reserved for local use.
1836   FacilityLocal7       | LOG\_LOCAL7   | Reserved for local use.
1837   FacilityLpr          | LOG\_LPR      | The line printer spooling system.
1838   FacilityMail         | LOG\_MAIL     | The mail system.
1839   FacilityNews         | LOG\_NEWS     | The network news system.
1840   FacilitySyslog       | LOG\_SYSLOG   | Messages generated internally by syslogd.
1841   FacilityUser         | LOG\_USER     | Messages generated by user processes. This is the default facility identifier if none is specified.
1842   FacilityUucp         | LOG\_UUCP     | The UUCP system.
1843
1844
1845