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