1 # Object Types <a id="object-types"></a>
3 This chapter provides an overview of all available config object types which can be
4 instantiated using the `object` keyword.
6 Additional details on configuration and runtime attributes and their
7 description are explained here too.
9 The attributes need to have a specific type value. Many of them are
10 explained in [this chapter](03-monitoring-basics.md#attribute-value-types) already.
11 You should note that the `Timestamp` type is a `Number`.
12 In addition to that `Object name` is an object reference to
13 an existing object name as `String` type.
15 ## Overview <a id="object-types-overview"></a>
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.
21 ## Common Runtime Attributes <a id="object-types-runtime-attributes"></a>
23 Configuration objects share these runtime attributes which cannot be
24 modified by the user. You can access these attributes using
25 the [Icinga 2 API](12-icinga2-api.md#icinga2-api-config-objects).
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.
38 ## Monitoring Objects <a id="object-types-monitoring"></a>
40 ### ApiUser <a id="objecttype-apiuser"></a>
42 ApiUser objects are used for authentication against the [Icinga 2 API](12-icinga2-api.md#icinga2-api-authentication).
47 object ApiUser "root" {
48 password = "mysecretapipassword"
53 Configuration Attributes:
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.
61 Available permissions are explained in the [API permissions](12-icinga2-api.md#icinga2-api-permissions)
64 ### CheckCommand <a id="objecttype-checkcommand"></a>
66 A check command definition. Additional default command custom attributes can be
72 object CheckCommand "http" {
73 command = [ PluginDir + "/check_http" ]
77 "-I" = "$http_address$"
87 value = "$http_auth_pair$"
88 description = "Username:password on sites with basic authentication"
91 set_if = "$http_ignore_body$"
93 "-r" = "$http_expect_body_regex$"
94 "-w" = "$http_warn_time$"
95 "-c" = "$http_critical_time$"
96 "-e" = "$http_expect$"
99 vars.http_address = "$address$"
100 vars.http_ssl = false
101 vars.http_sni = false
105 Configuration Attributes:
107 Name | Type | Description
108 --------------------------|-----------------------|----------------------------------
109 command | Array | **Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command. When using the "arguments" attribute this must be an array. Can be specified as function for advanced implementations.
110 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
111 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
112 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
113 arguments | Dictionary | **Optional.** A dictionary of command arguments.
116 #### CheckCommand Arguments <a id="objecttype-checkcommand-arguments"></a>
118 Command arguments can be defined as key-value-pairs in the `arguments`
119 dictionary. If the argument requires additional configuration, for example
120 a `description` attribute or an optional condition, the value can be defined
121 as dictionary specifying additional options.
126 vars.x_val = "My command argument value."
136 key = "-Xnew" /* optional, set a new key identifier */
137 description = "My plugin requires this argument for doing X."
138 required = false /* optional, no error if not set */
139 skip_key = false /* always use "-X <value>" */
140 set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
141 order = -1 /* first position */
142 repeat_key = true /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
146 description = "My plugin requires this argument for doing Y."
147 required = false /* optional, no error if not set */
148 skip_key = true /* don't prefix "-Y" only use "<value>" */
149 set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
150 order = 0 /* second position */
151 repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
156 Name | Type | Description
157 --------------------------|-----------------------|----------------------------------
158 value | String/Function | Optional argument value set by a [runtime macro string](03-monitoring-basics.md#runtime-macros) or a [function call](17-language-reference.md#functions).
159 key | String | Optional argument key overriding the key identifier.
160 description | String | Optional argument description.
161 required | Boolean | Required argument. Execution error if not set. Defaults to false (optional).
162 skip\_key | Boolean | Use the value as argument and skip the key.
163 set\_if | String/Function | Argument is added if the [runtime macro string](03-monitoring-basics.md#runtime-macros) resolves to a defined numeric or boolean value. String values are not supported. [Function calls](17-language-reference.md#functions) returning a value are supported too.
164 order | Number | Set if multiple arguments require a defined argument order.
165 repeat\_key | Boolean | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
170 ..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...
173 Define argument array:
176 value = "[ 'one', 'two', 'three' ]"
179 Argument array with `repeat_key = true`:
182 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'
185 Argument array with `repeat_key = false`:
188 'key' 'value[0]' 'value[1]' 'value[2]'
191 ## Dependency <a id="objecttype-dependency"></a>
193 Dependency objects are used to specify dependencies between hosts and services. Dependencies
194 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
199 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
200 > to just create a `Dependency` template and use the `apply` keyword to assign the
201 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
202 > type for `Host` or `Service`.
203 > Check the [dependencies](03-monitoring-basics.md#dependencies) chapter for detailed examples.
205 Service-to-Service Example:
208 object Dependency "webserver-internet" {
209 parent_host_name = "internet"
210 parent_service_name = "ping4"
212 child_host_name = "webserver"
213 child_service_name = "ping4"
215 states = [ OK, Warning ]
217 disable_checks = true
221 Host-to-Host Example:
224 object Dependency "webserver-internet" {
225 parent_host_name = "internet"
227 child_host_name = "webserver"
231 disable_checks = true
235 Configuration Attributes:
237 Name | Type | Description
238 --------------------------|-----------------------|----------------------------------
239 parent\_host\_name | Object name | **Required.** The parent host.
240 parent\_service\_name | Object name | **Optional.** The parent service. If omitted, this dependency object is treated as host dependency.
241 child\_host\_name | Object name | **Required.** The child host.
242 child\_service\_name | Object name | **Optional.** The child service. If omitted, this dependency object is treated as host dependency.
243 disable\_checks | Boolean | **Optional.** Whether to disable checks when this dependency fails. Defaults to false.
244 disable\_notifications | Boolean | **Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
245 ignore\_soft\_states | Boolean | **Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
246 period | Object name | **Optional.** Time period object during which this dependency is enabled.
247 states | Array | **Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
249 Available state filters:
260 When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
261 automatically determined by Icinga 2.
263 Service-to-Host Dependency Example:
266 apply Dependency "internet" to Service {
267 parent_host_name = "dsl-router"
268 disable_checks = true
270 assign where host.name != "dsl-router"
274 This example sets all service objects matching the assign condition into a dependency relation to
275 the parent host object `dsl-router` as implicit child services.
277 Service-to-Service-on-the-same-Host Dependency Example:
280 apply Dependency "disable-agent-checks" to Service {
281 parent_service_name = "agent-health"
283 assign where service.check_command == "ssh"
284 ignore where service.name == "agent-health"
288 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
289 host object matched by the apply rule condition. All services where apply matches are made implicit child services
290 in this dependency relation.
293 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
294 name you specified. This means you can define more than one object with the same (short) name as long as one of the `child_host_name` and
295 `child_service_name` attributes has a different value.
297 ## Endpoint <a id="objecttype-endpoint"></a>
299 Endpoint objects are used to specify connection information for remote
300 Icinga 2 instances. More details can be found in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
305 object Endpoint "icinga2-client1.localdomain" {
306 host = "192.168.56.111"
312 Example (disable replay log):
315 object Endpoint "icinga2-client1.localdomain" {
316 host = "192.168.5.111"
322 Configuration Attributes:
324 Name | Type | Description
325 --------------------------|-----------------------|----------------------------------
326 host | String | **Optional.** The hostname/IP address of the remote Icinga 2 instance.
327 port | Number | **Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
328 log\_duration | Duration | **Optional.** Duration for keeping replay logs on connection loss. Defaults to `1d` (86400 seconds). Attribute is specified in seconds. If log_duration is set to 0, replaying logs is disabled. You could also specify the value in human readable format like `10m` for 10 minutes or `1h` for one hour.
330 Endpoint objects cannot currently be created with the API.
332 ## EventCommand <a id="objecttype-eventcommand"></a>
334 An event command definition.
339 object EventCommand "restart-httpd-event" {
340 command = "/opt/bin/restart-httpd.sh"
345 Configuration Attributes:
347 Name | Type | Description
348 --------------------------|-----------------------|----------------------------------
349 command | Array | **Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command. When using the "arguments" attribute this must be an array. Can be specified as function for advanced implementations.
350 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
351 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
352 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
353 arguments | Dictionary | **Optional.** A dictionary of command arguments.
355 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
357 More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
360 ## Host <a id="objecttype-host"></a>
367 object Host "icinga2-client1.localdomain" {
368 display_name = "Linux Client 1"
369 address = "192.168.56.111"
370 address6 = "2a00:1450:4001:815::2003"
372 groups = [ "linux-servers" ]
374 check_command = "hostalive"
378 Configuration Attributes:
380 Name | Type | Description
381 --------------------------|-----------------------|----------------------------------
382 display\_name | String | **Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
383 address | String | **Optional.** The host's IPv4 address. Available as command runtime macro `$address$` if set.
384 address6 | String | **Optional.** The host's IPv6 address. Available as command runtime macro `$address6$` if set.
385 groups | Array of object names | **Optional.** A list of host groups this host belongs to.
386 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this host.
387 check\_command | Object name | **Required.** The name of the check command.
388 max\_check\_attempts | Number | **Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
389 check\_period | Object name | **Optional.** The name of a time period which determines when this host should be checked. Not set by default.
390 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
391 check\_interval | Duration | **Optional.** The check interval (in seconds). This interval is used for checks when the host is in a `HARD` state. Defaults to `5m`.
392 retry\_interval | Duration | **Optional.** The retry interval (in seconds). This interval is used for checks when the host is in a `SOFT` state. Defaults to `1m`. Note: This does not affect the scheduling [after a passive check result](08-advanced-topics.md#check-result-freshness).
393 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to true.
394 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to true.
395 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to true.
396 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to true.
397 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to false.
398 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to true.
399 event\_command | Object name | **Optional.** The name of an event command that should be executed every time the host's state changes or the host is in a `SOFT` state.
400 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a host to be considered flapping. Default `30.0`
401 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a host to be considered not flapping. Default `25.0`
402 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
403 zone | Object name | **Optional.** The zone this object is a member of. Please read the [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring) chapter for details.
404 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
405 notes | String | **Optional.** Notes for the host.
406 notes\_url | String | **Optional.** URL for notes for the host (for example, in notification commands).
407 action\_url | String | **Optional.** URL for actions for the host (for example, an external graphing tool).
408 icon\_image | String | **Optional.** Icon image for the host. Used by external interfaces only.
409 icon\_image\_alt | String | **Optional.** Icon image description for the host. Used by external interface only.
411 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
412 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
416 > The `address` and `address6` attributes are required for running commands using
417 > the `$address$` and `$address6$` runtime macros.
421 Name | Type | Description
422 --------------------------|-----------------------|----------------------------------
423 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
424 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
425 check\_attempt | Number | The current check attempt number.
426 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
427 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
428 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
429 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
430 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
431 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
432 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
433 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
434 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
435 downtime\_depth | Number | Whether the host has one or more active downtimes.
436 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
437 flapping | Boolean | Whether the host is flapping between states.
438 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
439 state | Number | The current state (0 = UP, 1 = DOWN).
440 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
441 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
442 last\_state\_up | Timestamp | When the last UP state occurred (as a UNIX timestamp).
443 last\_state\_down | Timestamp | When the last DOWN state occurred (as a UNIX timestamp).
447 ## HostGroup <a id="objecttype-hostgroup"></a>
453 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
458 object HostGroup "linux-servers" {
459 display_name = "Linux Servers"
461 assign where host.vars.os == "Linux"
465 Configuration Attributes:
467 Name | Type | Description
468 --------------------------|-----------------------|----------------------------------
469 display\_name | String | **Optional.** A short description of the host group.
470 groups | Array of object names | **Optional.** An array of nested group names.
474 ## Notification <a id="objecttype-notification"></a>
476 Notification objects are used to specify how users should be notified in case
477 of host and service state changes and other events.
481 > Rather than creating a `Notification` object for a specific host or service it is
482 > usually easier to just create a `Notification` template and use the `apply` keyword
483 > to assign the notification to a number of hosts or services. Use the `to` keyword
484 > to set the specific target type for `Host` or `Service`.
485 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
490 object Notification "localhost-ping-notification" {
491 host_name = "localhost"
492 service_name = "ping4"
494 command = "mail-notification"
496 users = [ "user1", "user2" ] // reference to User objects
498 types = [ Problem, Recovery ]
499 states = [ Critical, Warning, OK ]
503 Configuration Attributes:
505 Name | Type | Description
506 --------------------------|-----------------------|----------------------------------
507 host\_name | Object name | **Required.** The name of the host this notification belongs to.
508 service\_name | Object name | **Optional.** The short name of the service this notification belongs to. If omitted, this notification object is treated as host notification.
509 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
510 users | Array of object names | **Required.** A list of user names who should be notified. **Optional.** if the `user_groups` attribute is set.
511 user\_groups | Array of object names | **Required.** A list of user group names who should be notified. **Optional.** if the `users` attribute is set.
512 times | Dictionary | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
513 command | Object name | **Required.** The name of the notification command which should be executed when the notification is triggered.
514 interval | Duration | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, [re-notifications](03-monitoring-basics.md#disable-renotification) are disabled.
515 period | Object name | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
516 zone | Object name | **Optional.** The zone this object is a member of. Please read the [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring) chapter for details.
517 types | Array | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
518 states | Array | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched. Note that the states filter is ignored for notifications of type Acknowledgement!
520 Available notification state filters for Service:
529 Available notification state filters for Host:
536 Available notification type filters:
552 Name | Type | Description
553 ----------------------------|-----------------------|-----------------
554 last\_notification | Timestamp | When the last notification was sent for this Notification object (as a UNIX timestamp).
555 next\_notification | Timestamp | When the next notification is going to be sent for this assuming the associated host/service is still in a non-OK state (as a UNIX timestamp).
556 notification\_number | Number | The notification number.
557 last\_problem\_notification | Timestamp | When the last notification was sent for a problem (as a UNIX timestamp).
560 ## NotificationCommand <a id="objecttype-notificationcommand"></a>
562 A notification command definition.
567 object NotificationCommand "mail-service-notification" {
568 command = [ ConfigDir + "/scripts/mail-service-notification.sh" ]
573 value = "$notification_address$"
575 "-6" = "$notification_address6$"
576 "-b" = "$notification_author$"
577 "-c" = "$notification_comment$"
580 value = "$notification_date$"
584 value = "$notification_servicename$"
587 value = "$notification_from$"
588 description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
590 "-i" = "$notification_icingaweb2url$"
593 value = "$notification_hostname$"
597 value = "$notification_hostdisplayname$"
601 value = "$notification_serviceoutput$"
605 value = "$notification_useremail$"
609 value = "$notification_servicestate$"
613 value = "$notification_type$"
617 value = "$notification_servicedisplayname$"
619 "-v" = "$notification_logtosyslog$"
623 notification_address = "$address$"
624 notification_address6 = "$address6$"
625 notification_author = "$notification.author$"
626 notification_comment = "$notification.comment$"
627 notification_type = "$notification.type$"
628 notification_date = "$icinga.long_date_time$"
629 notification_hostname = "$host.name$"
630 notification_hostdisplayname = "$host.display_name$"
631 notification_servicename = "$service.name$"
632 notification_serviceoutput = "$service.output$"
633 notification_servicestate = "$service.state$"
634 notification_useremail = "$user.email$"
635 notification_servicedisplayname = "$service.display_name$"
640 Configuration Attributes:
642 Name | Type | Description
643 --------------------------|-----------------------|----------------------------------
644 command | Array | **Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command. When using the "arguments" attribute this must be an array. Can be specified as function for advanced implementations.
645 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
646 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
647 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
648 arguments | Dictionary | **Optional.** A dictionary of command arguments.
650 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
652 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
654 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
656 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
660 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
661 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
662 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
663 > type for `Host` or `Service`.
664 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
669 object ScheduledDowntime "some-downtime" {
670 host_name = "localhost"
671 service_name = "ping4"
673 author = "icingaadmin"
674 comment = "Some comment"
680 "sunday" = "02:00-03:00"
685 Configuration Attributes:
687 Name | Type | Description
688 --------------------------|-----------------------|----------------------------------
689 host\_name | Object name | **Required.** The name of the host this scheduled downtime belongs to.
690 service\_name | Object name | **Optional.** The short name of the service this scheduled downtime belongs to. If omitted, this downtime object is treated as host downtime.
691 author | String | **Required.** The author of the downtime.
692 comment | String | **Required.** A comment for the downtime.
693 fixed | Boolean | **Optional.** Whether this is a fixed downtime. Defaults to `true`.
694 duration | Duration | **Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
695 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
696 child\_options | String | **Optional.** Schedule child downtimes. `DowntimeNoChildren` does not do anything, `DowntimeTriggeredChildren` schedules child downtimes triggered by this downtime, `DowntimeNonTriggeredChildren` schedules non-triggered downtimes. Defaults to `DowntimeNoChildren`.
698 ScheduledDowntime objects have composite names, i.e. their names are based
699 on the `host_name` and `service_name` attributes and the
700 name you specified. This means you can define more than one object
701 with the same (short) name as long as one of the `host_name` and
702 `service_name` attributes has a different value.
705 ## Service <a id="objecttype-service"></a>
707 Service objects describe network services and how they should be checked
712 > Rather than creating a `Service` object for a specific host it is usually easier
713 > to just create a `Service` template and use the `apply` keyword to assign the
714 > service to a number of hosts.
715 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
720 object Service "uptime" {
721 host_name = "localhost"
723 display_name = "localhost Uptime"
725 check_command = "snmp"
727 vars.snmp_community = "public"
728 vars.snmp_oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
733 groups = [ "all-services", "snmp" ]
737 Configuration Attributes:
739 Name | Type | Description
740 --------------------------|-----------------------|----------------------------------
741 display\_name | String | **Optional.** A short description of the service.
742 host\_name | Object name | **Required.** The host this service belongs to. There must be a `Host` object with that name.
743 groups | Array of object names | **Optional.** The service groups this service belongs to.
744 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this service.
745 check\_command | Object name | **Required.** The name of the check command.
746 max\_check\_attempts | Number | **Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
747 check\_period | Object name | **Optional.** The name of a time period which determines when this service should be checked. Not set by default.
748 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
749 check\_interval | Duration | **Optional.** The check interval (in seconds). This interval is used for checks when the service is in a `HARD` state. Defaults to `5m`.
750 retry\_interval | Duration | **Optional.** The retry interval (in seconds). This interval is used for checks when the service is in a `SOFT` state. Defaults to `1m`. Note: This does not affect the scheduling [after a passive check result](08-advanced-topics.md#check-result-freshness).
751 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to `true`.
752 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to `true`.
753 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to `true`.
754 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to `true`.
755 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to `false`.
756 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a service to be considered flapping. `30.0`
757 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a service to be considered not flapping. `25.0`
758 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to `true`.
759 event\_command | Object name | **Optional.** The name of an event command that should be executed every time the service's state changes or the service is in a `SOFT` state.
760 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
761 zone | Object name | **Optional.** The zone this object is a member of. Please read the [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring) chapter for details.
762 name | String | **Required.** The service name. Must be unique on a per-host basis. For advanced usage in [apply rules](03-monitoring-basics.md#using-apply) only.
763 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
764 notes | String | **Optional.** Notes for the service.
765 notes\_url | String | **Optional.** URL for notes for the service (for example, in notification commands).
766 action\_url | String | **Optional.** URL for actions for the service (for example, an external graphing tool).
767 icon\_image | String | **Optional.** Icon image for the service. Used by external interfaces only.
768 icon\_image\_alt | String | **Optional.** Icon image description for the service. Used by external interface only.
770 Service objects have composite names, i.e. their names are based on the host\_name attribute and the name you specified. This means
771 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
773 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
774 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
778 Name | Type | Description
779 --------------------------|-----------------------|----------------------------------
780 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
781 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
782 check\_attempt | Number | The current check attempt number.
783 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
784 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
785 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
786 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
787 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
788 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
789 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
790 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
791 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
792 downtime\_depth | Number | Whether the service has one or more active downtimes.
793 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
794 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
795 flapping | Boolean | Whether the host is flapping between states.
796 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
797 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
798 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
799 last\_state\_ok | Timestamp | When the last OK state occurred (as a UNIX timestamp).
800 last\_state\_warning | Timestamp | When the last WARNING state occurred (as a UNIX timestamp).
801 last\_state\_critical | Timestamp | When the last CRITICAL state occurred (as a UNIX timestamp).
802 last\_state\_unknown | Timestamp | When the last UNKNOWN state occurred (as a UNIX timestamp).
805 ## ServiceGroup <a id="objecttype-servicegroup"></a>
811 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
816 object ServiceGroup "snmp" {
817 display_name = "SNMP services"
821 Configuration Attributes:
823 Name | Type | Description
824 --------------------------|-----------------------|----------------------------------
825 display\_name | String | **Optional.** A short description of the service group.
826 groups | Array of object names | **Optional.** An array of nested group names.
830 ## TimePeriod <a id="objecttype-timeperiod"></a>
832 Time periods can be used to specify when hosts/services should be checked or to limit
833 when notifications should be sent out.
838 object TimePeriod "nonworkhours" {
839 display_name = "Icinga 2 TimePeriod for non working hours"
842 monday = "00:00-8:00,17:00-24:00"
843 tuesday = "00:00-8:00,17:00-24:00"
844 wednesday = "00:00-8:00,17:00-24:00"
845 thursday = "00:00-8:00,17:00-24:00"
846 friday = "00:00-8:00,16:00-24:00"
847 saturday = "00:00-24:00"
848 sunday = "00:00-24:00"
852 object TimePeriod "exampledays" {
853 display_name = "Icinga 2 TimePeriod for random example days"
856 //We still believe in Santa, no peeking!
857 //Applies every 25th of December every year
858 "december 25" = "00:00-24:00"
860 //Any point in time can be specified,
861 //but you still have to use a range
862 "2038-01-19" = "03:13-03:15"
864 //Evey 3rd day from the second monday of February
866 "monday 2 february - november 8 / 3" = "00:00-24:00"
871 Additional examples can be found [here](08-advanced-topics.md#timeperiods).
873 Configuration Attributes:
875 Name | Type | Description
876 --------------------------|-----------------------|----------------------------------
877 display\_name | String | **Optional.** A short description of the time period.
878 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
879 prefer\_includes | Boolean | **Optional.** Whether to prefer timeperiods `includes` or `excludes`. Default to true.
880 excludes | Array of object names | **Optional.** An array of timeperiods, which should exclude from your timerange.
881 includes | Array of object names | **Optional.** An array of timeperiods, which should include into your timerange
886 Name | Type | Description
887 --------------------------|-----------------------|----------------------------------
888 is\_inside | Boolean | Whether we're currently inside this timeperiod.
891 ## User <a id="objecttype-user"></a>
898 object User "icingaadmin" {
899 display_name = "Icinga 2 Admin"
900 groups = [ "icingaadmins" ]
901 email = "icinga@localhost"
902 pager = "icingaadmin@localhost.localdomain"
906 states = [ OK, Warning, Critical, Unknown ]
907 types = [ Problem, Recovery ]
909 vars.additional_notes = "This is the Icinga 2 Admin account."
913 Available notification state filters:
924 Available notification type filters:
938 Configuration Attributes:
940 Name | Type | Description
941 --------------------------|-----------------------|----------------------------------
942 display\_name | String | **Optional.** A short description of the user.
943 email | String | **Optional.** An email string for this user. Useful for notification commands.
944 pager | String | **Optional.** A pager string for this user. Useful for notification commands.
945 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this user.
946 groups | Array of object names | **Optional.** An array of group names.
947 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled for this user. Defaults to true.
948 period | Object name | **Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default.
949 types | Array | **Optional.** A set of type filters when a notification for this user should be triggered. By default everything is matched.
950 states | Array | **Optional.** A set of state filters when a notification for this should be triggered. By default everything is matched.
954 Name | Type | Description
955 --------------------------|-----------------------|----------------------------------
956 last\_notification | Timestamp | When the last notification was sent for this user (as a UNIX timestamp).
958 ## UserGroup <a id="objecttype-usergroup"></a>
964 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
969 object UserGroup "icingaadmins" {
970 display_name = "Icinga 2 Admin Group"
974 Configuration Attributes:
976 Name | Type | Description
977 --------------------------|-----------------------|----------------------------------
978 display\_name | String | **Optional.** A short description of the user group.
979 groups | Array of object names | **Optional.** An array of nested group names.
982 ## Zone <a id="objecttype-zone"></a>
984 Zone objects are used to specify which Icinga 2 instances are located in a zone.
985 Please read the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring) for additional details.
989 object Zone "master" {
990 endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]
994 object Zone "satellite" {
995 endpoints = [ "icinga2-satellite1.localdomain" ]
1000 Configuration Attributes:
1002 Name | Type | Description
1003 --------------------------|-----------------------|----------------------------------
1004 endpoints | Array of object names | **Optional.** Array of endpoint names located in this zone.
1005 parent | Object name | **Optional.** The name of the parent zone. (Do not specify a global zone)
1006 global | Boolean | **Optional.** Whether configuration files for this zone should be [synced](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync) to all endpoints. Defaults to `false`.
1008 Zone objects cannot currently be created with the API.
1011 ## Runtime Objects <a id="object-types-runtime"></a>
1013 These objects are generated at runtime by the daemon
1014 from API actions. Downtime objects are also created
1015 by ScheduledDowntime objects.
1017 ### Comment <a id="objecttype-comment"></a>
1019 Comments created at runtime are represented as objects.
1020 Note: This is for reference only. You can create comments
1021 with the [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) API action.
1026 object Comment "my-comment" {
1027 host_name = "localhost"
1028 author = "icingaadmin"
1029 text = "This is a comment."
1030 entry_time = 1234567890
1034 Configuration Attributes:
1036 Name | Type | Description
1037 --------------------------|-----------------------|----------------------------------
1038 host\_name | Object name | **Required.** The name of the host this comment belongs to.
1039 service\_name | Object name | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment.
1040 author | String | **Required.** The author's name.
1041 text | String | **Required.** The comment text.
1042 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this comment was added. If omitted, the entry time is volatile!
1043 entry\_type | Number | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
1044 expire\_time | Timestamp | **Optional.** The comment's expire time as UNIX timestamp.
1045 persistent | Boolean | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
1047 ### Downtime <a id="objecttype-downtime"></a>
1049 Downtimes created at runtime are represented as objects.
1050 You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action.
1055 object Downtime "my-downtime" {
1056 host_name = "localhost"
1057 author = "icingaadmin"
1058 comment = "This is a downtime."
1059 start_time = 1505312869
1060 end_time = 1505312924
1064 Configuration Attributes:
1066 Name | Type | Description
1067 --------------------------|-----------------------|----------------------------------
1068 host\_name | Object name | **Required.** The name of the host this comment belongs to.
1069 service\_name | Object name | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment.
1070 author | String | **Required.** The author's name.
1071 comment | String | **Required.** The comment text.
1072 start\_time | Timestamp | **Required.** The start time as UNIX timestamp.
1073 end\_time | Timestamp | **Required.** The end time as UNIX timestamp.
1074 duration | Number | **Optional.** The duration as number.
1075 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this downtime was added.
1076 fixed | Boolean | **Optional.** Whether the downtime is fixed (true) or flexible (false). Defaults to flexible. Details in the [advanced topics chapter](08-advanced-topics.md#fixed-flexible-downtimes).
1077 triggers | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime.
1081 Name | Type | Description
1082 --------------------------|-----------------------|----------------------------------
1083 trigger\_time | Timestamp | The UNIX timestamp when this downtime was triggered.
1084 triggered\_by | Object name | The name of the downtime this downtime was triggered by.
1088 ## Features <a id="object-types-features"></a>
1090 ### ApiListener <a id="objecttype-apilistener"></a>
1092 ApiListener objects are used for distributed monitoring setups
1093 and API usage specifying the certificate files used for ssl
1094 authorization and additional restrictions.
1095 This configuration object is available as [api feature](11-cli-commands.md#cli-command-feature).
1097 The `TicketSalt` constant must be defined in [constants.conf](04-configuring-icinga-2.md#constants-conf).
1102 object ApiListener "api" {
1103 accept_commands = true
1104 accept_config = true
1106 ticket_salt = TicketSalt
1110 Configuration Attributes:
1112 Name | Type | Description
1113 --------------------------------------|-----------------------|----------------------------------
1114 cert\_path | String | **Deprecated.** Path to the public key.
1115 key\_path | String | **Deprecated.** Path to the private key.
1116 ca\_path | String | **Deprecated.** Path to the CA certificate file.
1117 ticket\_salt | String | **Optional.** Private key for [CSR auto-signing](06-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing). **Required** for a signing master instance.
1118 crl\_path | String | **Optional.** Path to the CRL file.
1119 bind\_host | String | **Optional.** The IP address the api listener should be bound to. If not specified, the ApiListener is bound to `::` and listens for both IPv4 and IPv6 connections.
1120 bind\_port | Number | **Optional.** The port the api listener should be bound to. Defaults to `5665`.
1121 accept\_config | Boolean | **Optional.** Accept zone configuration. Defaults to `false`.
1122 accept\_commands | Boolean | **Optional.** Accept remote commands. Defaults to `false`.
1123 max\_anonymous\_clients | Number | **Optional.** Limit the number of anonymous client connections (not configured endpoints and signing requests).
1124 cipher\_list | String | **Optional.** Cipher list that is allowed. For a list of available ciphers run `openssl ciphers`. Defaults to `ALL:!LOW:!WEAK:!MEDIUM:!EXP:!NULL`.
1125 tls\_protocolmin | String | **Optional.** Minimum TLS protocol version. Must be one of `TLSv1`, `TLSv1.1` or `TLSv1.2`. Defaults to `TLSv1`.
1126 tls\_handshake\_timeout | Number | **Optional.** TLS Handshake timeout. Defaults to `10s`.
1127 access\_control\_allow\_origin | Array | **Optional.** Specifies an array of origin URLs that may access the API. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Origin)
1128 access\_control\_allow\_credentials | Boolean | **Deprecated.** Indicates whether or not the actual request can be made using credentials. Defaults to `true`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Credentials)
1129 access\_control\_allow\_headers | String | **Deprecated.** Used in response to a preflight request to indicate which HTTP headers can be used when making the actual request. Defaults to `Authorization`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Headers)
1130 access\_control\_allow\_methods | String | **Deprecated.** Used in response to a preflight request to indicate which HTTP methods can be used when making the actual request. Defaults to `GET, POST, PUT, DELETE`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Methods)
1131 environment | String | **Optional.** Used as suffix in TLS SNI extension name; default from constant `ApiEnvironment`, which is empty.
1133 The attributes `access_control_allow_credentials`, `access_control_allow_headers` and `access_control_allow_methods`
1134 are controlled by Icinga 2 and are not changeable by config any more.
1137 The ApiListener type expects its certificate files to be in the following locations:
1140 ---------------------|-------------------------------------
1141 Private key | `DataDir + "/certs/" + NodeName + ".key"`
1142 Certificate file | `DataDir + "/certs/" + NodeName + ".crt"`
1143 CA certificate file | `DataDir + "/certs/ca.crt"`
1145 If the deprecated attributes `cert_path`, `key_path` and/or `ca_path` are specified Icinga 2
1146 copies those files to the new location in `DataDir + "/certs"` unless the
1147 file(s) there are newer.
1149 Please check the [upgrading chapter](16-upgrading-icinga-2.md#upgrading-to-2-8-certificate-paths) for more details.
1151 While Icinga 2 and the underlying OpenSSL library use sane and secure defaults, the attributes
1152 `cipher_list` and `tls_protocolmin` can be used to increase communication security. A good source
1153 for a more secure configuration is provided by the [Mozilla Wiki](https://wiki.mozilla.org/Security/Server_Side_TLS).
1154 Ensure to use the same configuration for both attributes on **all** endpoints to avoid communication problems which
1155 requires to use `cipher_list` compatible with the endpoint using the oldest version of the OpenSSL library. If using
1156 other tools to connect to the API ensure also compatibility with them as this setting affects not only inter-cluster
1157 communcation but also the REST API.
1159 ### CheckerComponent <a id="objecttype-checkercomponent"></a>
1161 The checker component is responsible for scheduling active checks.
1162 This configuration object is available as [checker feature](11-cli-commands.md#cli-command-feature).
1167 object CheckerComponent "checker" { }
1170 In order to limit the concurrent checks on a master/satellite endpoint,
1171 use [MaxConcurrentChecks](17-language-reference.md#icinga-constants-global-config) constant.
1172 This also applies to an agent as command endpoint where the checker
1173 feature is disabled.
1175 ### CheckResultReader <a id="objecttype-checkresultreader"></a>
1177 Reads Icinga 1.x check result files from a directory. This functionality is provided
1178 to help existing Icinga 1.x users and might be useful for migration scenarios.
1182 > This feature is DEPRECATED and will be removed in future releases.
1183 > Check the [roadmap](https://github.com/Icinga/icinga2/milestones).
1188 object CheckResultReader "reader" {
1189 spool_dir = "/data/check-results"
1193 Configuration Attributes:
1195 Name | Type | Description
1196 --------------------------|-----------------------|----------------------------------
1197 spool\_dir | String | **Optional.** The directory which contains the check result files. Defaults to DataDir + "/spool/checkresults/".
1199 ### CompatLogger <a id="objecttype-compatlogger"></a>
1201 Writes log files in a format that's compatible with Icinga 1.x.
1202 This configuration object is available as [compatlog feature](14-features.md#compat-logging).
1206 > This feature is DEPRECATED and will be removed in future releases.
1207 > Check the [roadmap](https://github.com/Icinga/icinga2/milestones).
1212 object CompatLogger "compatlog" {
1213 log_dir = "/var/log/icinga2/compat"
1214 rotation_method = "DAILY"
1218 Configuration Attributes:
1220 Name | Type | Description
1221 --------------------------|-----------------------|----------------------------------
1222 log\_dir | String | **Optional.** Path to the compat log directory. Defaults to LogDir + "/compat".
1223 rotation\_method | String | **Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
1226 ### ElasticsearchWriter <a id="objecttype-elasticsearchwriter"></a>
1228 Writes check result metrics and performance data to an Elasticsearch instance.
1229 This configuration object is available as [elasticsearch feature](14-features.md#elasticsearch-writer).
1234 object ElasticsearchWriter "elasticsearch" {
1239 enable_send_perfdata = true
1241 flush_threshold = 1024
1246 The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
1248 Configuration Attributes:
1250 Name | Type | Description
1251 --------------------------|-----------------------|----------------------------------
1252 host | String | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
1253 port | Number | **Required.** Elasticsearch port. Defaults to `9200`.
1254 index | String | **Required.** Elasticsearch index name. Defaults to `icinga2`.
1255 enable\_send\_perfdata | Boolean | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
1256 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to Elasticsearch. Defaults to `10s`.
1257 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to `1024`.
1258 username | String | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
1259 password | String | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
1260 enable\_tls | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
1261 ca\_path | String | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
1262 cert\_path | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
1263 key\_path | String | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
1264 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
1266 Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
1267 Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
1269 Basic auth is supported with the `username` and `password` attributes. This requires an
1270 HTTP proxy (Nginx, etc.) in front of the Elasticsearch instance. Check [this blogpost](https://blog.netways.de/2017/09/14/secure-elasticsearch-and-kibana-with-an-nginx-http-proxy/)
1273 TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
1274 you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
1276 ### ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
1278 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
1279 This configuration object is available as [command feature](14-features.md#external-commands).
1283 > This feature is DEPRECATED and will be removed in future releases.
1284 > Check the [roadmap](https://github.com/Icinga/icinga2/milestones).
1289 object ExternalCommandListener "command" {
1290 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
1294 Configuration Attributes:
1296 Name | Type | Description
1297 --------------------------|-----------------------|----------------------------------
1298 command\_path | String | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
1302 ### FileLogger <a id="objecttype-filelogger"></a>
1304 Specifies Icinga 2 logging to a file.
1305 This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging).
1310 object FileLogger "debug-file" {
1312 path = "/var/log/icinga2/debug.log"
1316 Configuration Attributes:
1318 Name | Type | Description
1319 --------------------------|-----------------------|----------------------------------
1320 path | String | **Required.** The log path.
1321 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
1324 ### GelfWriter <a id="objecttype-gelfwriter"></a>
1326 Writes event log entries to a defined GELF receiver host (Graylog, Logstash).
1327 This configuration object is available as [gelf feature](14-features.md#gelfwriter).
1332 object GelfWriter "gelf" {
1338 Configuration Attributes:
1340 Name | Type | Description
1341 --------------------------|-----------------------|----------------------------------
1342 host | String | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`.
1343 port | Number | **Optional.** GELF receiver port. Defaults to `12201`.
1344 source | String | **Optional.** Source name for this instance. Defaults to `icinga2`.
1345 enable\_send\_perfdata | Boolean | **Optional.** Enable performance data for 'CHECK RESULT' events.
1346 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
1349 ### GraphiteWriter <a id="objecttype-graphitewriter"></a>
1351 Writes check result metrics and performance data to a defined
1352 Graphite Carbon host.
1353 This configuration object is available as [graphite feature](14-features.md#graphite-carbon-cache-writer).
1358 object GraphiteWriter "graphite" {
1364 Configuration Attributes:
1366 Name | Type | Description
1367 --------------------------|-----------------------|----------------------------------
1368 host | String | **Optional.** Graphite Carbon host address. Defaults to `127.0.0.1`.
1369 port | Number | **Optional.** Graphite Carbon port. Defaults to `2003`.
1370 host\_name\_template | String | **Optional.** Metric prefix for host name. Defaults to `icinga2.$host.name$.host.$host.check_command$`.
1371 service\_name\_template | String | **Optional.** Metric prefix for service name. Defaults to `icinga2.$host.name$.services.$service.name$.$service.check_command$`.
1372 enable\_send\_thresholds | Boolean | **Optional.** Send additional threshold metrics. Defaults to `false`.
1373 enable\_send\_metadata | Boolean | **Optional.** Send additional metadata metrics. Defaults to `false`.
1374 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
1376 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
1379 ### IcingaApplication <a id="objecttype-icingaapplication"></a>
1381 The IcingaApplication object is required to start Icinga 2.
1382 The object name must be `app`. If the object configuration
1383 is missing, Icinga 2 will automatically create an IcingaApplication
1389 object IcingaApplication "app" {
1390 enable_perfdata = false
1394 Configuration Attributes:
1396 Name | Type | Description
1397 --------------------------|-----------------------|----------------------------------
1398 enable\_notifications | Boolean | **Optional.** Whether notifications are globally enabled. Defaults to true.
1399 enable\_event\_handlers | Boolean | **Optional.** Whether event handlers are globally enabled. Defaults to true.
1400 enable\_flapping | Boolean | **Optional.** Whether flap detection is globally enabled. Defaults to true.
1401 enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true.
1402 enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true.
1403 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true.
1404 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally.
1405 environment | String | **Optional.** Specify the Icinga environment. This overrides the `Environment` constant specified in the configuration or on the CLI with `--define`. Defaults to empty.
1407 ### IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
1409 IDO database adapter for MySQL.
1410 This configuration object is available as [ido-mysql feature](14-features.md#db-ido).
1415 object IdoMysqlConnection "mysql-ido" {
1423 downtimehistory_age = 48h
1424 contactnotifications_age = 31d
1429 Configuration Attributes:
1431 Name | Type | Description
1432 --------------------------|-----------------------|----------------------------------
1433 host | String | **Optional.** MySQL database host address. Defaults to `localhost`.
1434 port | Number | **Optional.** MySQL database port. Defaults to `3306`.
1435 socket\_path | String | **Optional.** MySQL socket path.
1436 user | String | **Optional.** MySQL database user with read/write permission to the icinga database. Defaults to `icinga`.
1437 password | String | **Optional.** MySQL database user's password. Defaults to `icinga`.
1438 database | String | **Optional.** MySQL database name. Defaults to `icinga`.
1439 enable\_ssl | Boolean | **Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
1440 ssl\_key | String | **Optional.** MySQL SSL client key file path.
1441 ssl\_cert | String | **Optional.** MySQL SSL certificate file path.
1442 ssl\_ca | String | **Optional.** MySQL SSL certificate authority certificate file path.
1443 ssl\_capath | String | **Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
1444 ssl\_cipher | String | **Optional.** MySQL SSL list of allowed ciphers.
1445 table\_prefix | String | **Optional.** MySQL database table prefix. Defaults to `icinga_`.
1446 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
1447 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
1448 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to `true`.
1449 failover\_timeout | Duration | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 30s. Defaults to `30s`.
1450 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
1451 categories | Array | **Optional.** Array of information types that should be written to the database.
1455 Name | Type | Description
1456 --------------------------------|-----------------------|----------------------------------
1457 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
1458 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
1459 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
1460 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
1461 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
1462 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
1463 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
1464 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
1465 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
1466 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
1467 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
1468 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
1469 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
1470 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
1471 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
1475 Name | Description | Required by
1476 ---------------------|------------------------|--------------------
1477 DbCatConfig | Configuration data | Icinga Web 2
1478 DbCatState | Current state data | Icinga Web 2
1479 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
1480 DbCatComment | Comments | Icinga Web 2
1481 DbCatDowntime | Downtimes | Icinga Web 2
1482 DbCatEventHandler | Event handler data | Icinga Web 2
1483 DbCatExternalCommand | External commands | --
1484 DbCatFlapping | Flap detection data | Icinga Web 2
1485 DbCatCheck | Check results | --
1486 DbCatLog | Log messages | --
1487 DbCatNotification | Notifications | Icinga Web 2
1488 DbCatProgramStatus | Program status data | Icinga Web 2
1489 DbCatRetention | Retention data | Icinga Web 2
1490 DbCatStateHistory | Historical state data | Icinga Web 2
1492 The default value for `categories` includes everything required
1493 by Icinga Web 2 in the table above.
1495 In addition to the category flags listed above the `DbCatEverything`
1496 flag may be used as a shortcut for listing all flags.
1500 Name | Type | Description
1501 ----------------------------|-----------------------|-----------------
1502 last\_failover | Timestamp | When the last failover happened for this connection (only available with `enable_ha = true`.
1504 ### IdoPgsqlConnection <a id="objecttype-idopgsqlconnection"></a>
1506 IDO database adapter for PostgreSQL.
1507 This configuration object is available as [ido-pgsql feature](14-features.md#db-ido).
1512 object IdoPgsqlConnection "pgsql-ido" {
1520 downtimehistory_age = 48h
1521 contactnotifications_age = 31d
1526 Configuration Attributes:
1528 Name | Type | Description
1529 --------------------------|-----------------------|----------------------------------
1530 host | String | **Optional.** PostgreSQL database host address. Defaults to `localhost`.
1531 port | Number | **Optional.** PostgreSQL database port. Defaults to `5432`.
1532 user | String | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`.
1533 password | String | **Optional.** PostgreSQL database user's password. Defaults to `icinga`.
1534 database | String | **Optional.** PostgreSQL database name. Defaults to `icinga`.
1535 ssl\_mode | String | **Optional.** Enable SSL connection mode. Value must be set according to the [sslmode setting](https://www.postgresql.org/docs/9.3/static/libpq-connect.html#LIBPQ-CONNSTRING): `prefer`, `require`, `verify-ca`, `verify-full`, `allow`, `disable`.
1536 ssl\_key | String | **Optional.** PostgreSQL SSL client key file path.
1537 ssl\_cert | String | **Optional.** PostgreSQL SSL certificate file path.
1538 ssl\_ca | String | **Optional.** PostgreSQL SSL certificate authority certificate file path.
1539 table\_prefix | String | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`.
1540 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
1541 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
1542 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to `true`.
1543 failover\_timeout | Duration | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 30s. Defaults to `30s`.
1544 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
1545 categories | Array | **Optional.** Array of information types that should be written to the database.
1549 Name | Type | Description
1550 --------------------------------|-----------------------|----------------------------------
1551 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
1552 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
1553 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
1554 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
1555 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
1556 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
1557 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
1558 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
1559 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
1560 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
1561 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
1562 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
1563 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
1564 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
1565 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
1569 Name | Description | Required by
1570 ---------------------|------------------------|--------------------
1571 DbCatConfig | Configuration data | Icinga Web 2
1572 DbCatState | Current state data | Icinga Web 2
1573 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
1574 DbCatComment | Comments | Icinga Web 2
1575 DbCatDowntime | Downtimes | Icinga Web 2
1576 DbCatEventHandler | Event handler data | Icinga Web 2
1577 DbCatExternalCommand | External commands | --
1578 DbCatFlapping | Flap detection data | Icinga Web 2
1579 DbCatCheck | Check results | --
1580 DbCatLog | Log messages | --
1581 DbCatNotification | Notifications | Icinga Web 2
1582 DbCatProgramStatus | Program status data | Icinga Web 2
1583 DbCatRetention | Retention data | Icinga Web 2
1584 DbCatStateHistory | Historical state data | Icinga Web 2
1586 The default value for `categories` includes everything required
1587 by Icinga Web 2 in the table above.
1589 In addition to the category flags listed above the `DbCatEverything`
1590 flag may be used as a shortcut for listing all flags.
1594 Name | Type | Description
1595 ----------------------------|-----------------------|-----------------
1596 last\_failover | Timestamp | When the last failover happened for this connection (only available with `enable_ha = true`.
1598 ### InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
1600 Writes check result metrics and performance data to a defined InfluxDB host.
1601 This configuration object is available as [influxdb feature](14-features.md#influxdb-writer).
1606 object InfluxdbWriter "influxdb" {
1609 database = "icinga2"
1611 flush_threshold = 1024
1612 flush_interval = 10s
1615 measurement = "$host.check_command$"
1617 hostname = "$host.name$"
1620 service_template = {
1621 measurement = "$service.check_command$"
1623 hostname = "$host.name$"
1624 service = "$service.name$"
1630 Configuration Attributes:
1632 Name | Type | Description
1633 --------------------------|-----------------------|----------------------------------
1634 host | String | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
1635 port | Number | **Required.** InfluxDB HTTP port. Defaults to `8086`.
1636 database | String | **Required.** InfluxDB database name. Defaults to `icinga2`.
1637 username | String | **Optional.** InfluxDB user name. Defaults to `none`.
1638 password | String | **Optional.** InfluxDB user password. Defaults to `none`.
1639 ssl\_enable | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`.
1640 ssl\_ca\_cert | String | **Optional.** Path to CA certificate to validate the remote host.
1641 ssl\_cert | String | **Optional.** Path to host certificate to present to the remote host for mutual verification.
1642 ssl\_key | String | **Optional.** Path to host key to accompany the ssl\_cert.
1643 host\_template | String | **Required.** Host template to define the InfluxDB line protocol.
1644 service\_template | String | **Required.** Service template to define the influxDB line protocol.
1645 enable\_send\_thresholds | Boolean | **Optional.** Whether to send warn, crit, min & max tagged data.
1646 enable\_send\_metadata | Boolean | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
1647 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to InfluxDB. Defaults to `10s`.
1648 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`.
1649 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
1651 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
1652 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
1657 ### LiveStatusListener <a id="objecttype-livestatuslistener"></a>
1659 Livestatus API interface available as TCP or UNIX socket. Historical table queries
1660 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
1661 pointing to the log files using the `compat_log_path` configuration attribute.
1662 This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus).
1667 object LivestatusListener "livestatus-tcp" {
1669 bind_host = "127.0.0.1"
1673 object LivestatusListener "livestatus-unix" {
1674 socket_type = "unix"
1675 socket_path = "/var/run/icinga2/cmd/livestatus"
1679 Configuration Attributes:
1681 Name | Type | Description
1682 --------------------------|-----------------------|----------------------------------
1683 socket\_type | String | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`.
1684 bind\_host | String | **Optional.** Only valid when `socket_type` is set to `tcp`. Host address to listen on for connections. Defaults to `127.0.0.1`.
1685 bind\_port | Number | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`.
1686 socket\_path | String | **Optional.** Only valid when `socket_type` is set to `unix`. Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus".
1687 compat\_log\_path | String | **Optional.** Path to Icinga 1.x log files. Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LogDir + "/compat"
1691 > UNIX sockets are not supported on Windows.
1693 ### NotificationComponent <a id="objecttype-notificationcomponent"></a>
1695 The notification component is responsible for sending notifications.
1696 This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature).
1701 object NotificationComponent "notification" { }
1704 Configuration Attributes:
1706 Name | Type | Description
1707 --------------------------|-----------------------|----------------------------------
1708 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-notifications). Disabling this currently only affects reminder notifications. Defaults to "true".
1710 ### OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1712 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1713 This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer).
1718 object OpenTsdbWriter "opentsdb" {
1724 Configuration Attributes:
1726 Name | Type | Description
1727 --------------------------|-----------------------|----------------------------------
1728 host | String | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`.
1729 port | Number | **Optional.** OpenTSDB port. Defaults to `4242`.
1730 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
1733 ### PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1735 Writes check result performance data to a defined path using macro
1736 pattern consisting of custom attributes and runtime macros.
1737 This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files).
1742 object PerfdataWriter "perfdata" {
1743 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1745 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1747 host_format_template = "DATATYPE::HOSTPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tHOSTPERFDATA::$host.perfdata$\tHOSTCHECKCOMMAND::$host.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$"
1748 service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.name$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.state_type$"
1750 rotation_interval = 15s
1754 Configuration Attributes:
1756 Name | Type | Description
1757 --------------------------|-----------------------|----------------------------------
1758 host\_perfdata\_path | String | **Optional.** Path to the host performance data file. Defaults to SpoolDir + "/perfdata/host-perfdata".
1759 service\_perfdata\_path | String | **Optional.** Path to the service performance data file. Defaults to SpoolDir + "/perfdata/service-perfdata".
1760 host\_temp\_path | String | **Optional.** Path to the temporary host file. Defaults to SpoolDir + "/tmp/host-perfdata".
1761 service\_temp\_path | String | **Optional.** Path to the temporary service file. Defaults to SpoolDir + "/tmp/service-perfdata".
1762 host\_format\_template | String | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1763 service\_format\_template | String | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1764 rotation\_interval | Duration | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`.
1765 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
1767 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1768 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1771 ### StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1773 Periodically writes status and configuration data files which are used by third-party tools.
1774 This configuration object is available as [statusdata feature](14-features.md#status-data).
1778 > This feature is DEPRECATED and will be removed in future releases.
1779 > Check the [roadmap](https://github.com/Icinga/icinga2/milestones).
1784 object StatusDataWriter "status" {
1785 status_path = "/var/cache/icinga2/status.dat"
1786 objects_path = "/var/cache/icinga2/objects.cache"
1787 update_interval = 30s
1791 Configuration Attributes:
1793 Name | Type | Description
1794 --------------------------|-----------------------|----------------------------------
1795 status\_path | String | **Optional.** Path to the `status.dat` file. Defaults to CacheDir + "/status.dat".
1796 objects\_path | String | **Optional.** Path to the `objects.cache` file. Defaults to CacheDir + "/objects.cache".
1797 update\_interval | Duration | **Optional.** The interval in which the status files are updated. Defaults to `15s`.
1799 ### SyslogLogger <a id="objecttype-sysloglogger"></a>
1801 Specifies Icinga 2 logging to syslog.
1802 This configuration object is available as `syslog` [logging feature](14-features.md#logging).
1807 object SyslogLogger "syslog" {
1808 severity = "warning"
1812 Configuration Attributes:
1814 Name | Type | Description
1815 --------------------------|-----------------------|----------------------------------
1816 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1817 facility | String | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`.
1821 Name | Facility | Description
1822 ---------------------|---------------|----------------
1823 FacilityAuth | LOG\_AUTH | The authorization system.
1824 FacilityAuthPriv | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals.
1825 FacilityCron | LOG\_CRON | The cron daemon.
1826 FacilityDaemon | LOG\_DAEMON | System daemons that are not provided for explicitly by other facilities.
1827 FacilityFtp | LOG\_FTP | The file transfer protocol daemons.
1828 FacilityKern | LOG\_KERN | Messages generated by the kernel. These cannot be generated by any user processes.
1829 FacilityLocal0 | LOG\_LOCAL0 | Reserved for local use.
1830 FacilityLocal1 | LOG\_LOCAL1 | Reserved for local use.
1831 FacilityLocal2 | LOG\_LOCAL2 | Reserved for local use.
1832 FacilityLocal3 | LOG\_LOCAL3 | Reserved for local use.
1833 FacilityLocal4 | LOG\_LOCAL4 | Reserved for local use.
1834 FacilityLocal5 | LOG\_LOCAL5 | Reserved for local use.
1835 FacilityLocal6 | LOG\_LOCAL6 | Reserved for local use.
1836 FacilityLocal7 | LOG\_LOCAL7 | Reserved for local use.
1837 FacilityLpr | LOG\_LPR | The line printer spooling system.
1838 FacilityMail | LOG\_MAIL | The mail system.
1839 FacilityNews | LOG\_NEWS | The network news system.
1840 FacilitySyslog | LOG\_SYSLOG | Messages generated internally by syslogd.
1841 FacilityUser | LOG\_USER | Messages generated by user processes. This is the default facility identifier if none is specified.
1842 FacilityUucp | LOG\_UUCP | The UUCP system.