1 # <a id="object-types"></a> Config Object Types
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 as well.
9 Config objects share these runtime attributes which cannot be
10 modified by the user. You can access these attributes using
11 the [Icinga 2 API](12-icinga2-api.md#icinga2-api-config-objects).
14 --------------------------|--------------------------
15 version | Timestamp when the object was created or modified. Synced throughout cluster nodes.
17 original_attributes | Original values of object attributes modified at runtime.
18 active | Object is active (e.g. a service being checked).
19 paused | Object has been paused at runtime (e.g. [IdoMysqlConnection](9-object-types.md#objecttype-idomysqlconnection). Defaults to `false`.
20 templates | Templates imported on object compilation.
21 package | [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`.
24 ## <a id="objecttype-apilistener"></a> ApiListener
26 ApiListener objects are used for distributed monitoring setups
27 and API usage specifying the certificate files used for ssl
28 authorization and additional restrictions.
30 The `NodeName` constant must be defined in [constants.conf](4-configuring-icinga-2.md#constants-conf).
34 object ApiListener "api" {
35 cert_path = SysconfDir + "/icinga2/pki/" + NodeName + ".crt"
36 key_path = SysconfDir + "/icinga2/pki/" + NodeName + ".key"
37 ca_path = SysconfDir + "/icinga2/pki/ca.crt"
41 Configuration Attributes:
44 --------------------------|--------------------------
45 cert\_path |**Required.** Path to the public key.
46 key\_path |**Required.** Path to the private key.
47 ca\_path |**Required.** Path to the CA certificate file.
48 crl\_path |**Optional.** Path to the CRL file.
49 bind\_host |**Optional.** The IP address the api listener should be bound to. Defaults to `0.0.0.0`.
50 bind\_port |**Optional.** The port the api listener should be bound to. Defaults to `5665`.
51 accept\_config |**Optional.** Accept zone configuration. Defaults to `false`.
52 accept\_commands |**Optional.** Accept remote commands. Defaults to `false`.
53 cipher\_list |**Optional.** Cipher list that is allowed.
54 tls\_protocolmin |**Optional.** Minimum TLS protocol version. Must be one of `TLSv1`, `TLSv1.1` or `TLSv1.2`. Defaults to `TLSv1`.
56 ## <a id="objecttype-apiuser"></a> ApiUser
58 ApiUser objects are used for authentication against the Icinga 2 API.
62 object ApiUser "root" {
63 password = "mysecretapipassword"
68 Configuration Attributes:
71 --------------------------|--------------------------
72 password |**Optional.** Password string.
73 client\_cn |**Optional.** Client Common Name (CN).
74 permissions |**Required.** Array of permissions. Either as string or dictionary with the keys `permission` and `filter`. The latter must be specified as function.
76 Available permissions are described in the [API permissions](12-icinga2-api.md#icinga2-api-permissions)
79 ## <a id="objecttype-checkcommand"></a> CheckCommand
81 A check command definition. Additional default command custom attributes can be
86 > Icinga 2 versions < 2.6.0 require the import of the [plugin-check-command](10-icinga-template-library.md#itl-plugin-check-command) template.
90 object CheckCommand "check_http" {
91 command = [ PluginDir + "/check_http" ]
95 "-I" = "$http_address$"
102 set_if = "$http_sni$"
105 value = "$http_auth_pair$"
106 description = "Username:password on sites with basic authentication"
109 set_if = "$http_ignore_body$"
111 "-r" = "$http_expect_body_regex$"
112 "-w" = "$http_warn_time$"
113 "-c" = "$http_critical_time$"
114 "-e" = "$http_expect$"
117 vars.http_address = "$address$"
118 vars.http_ssl = false
119 vars.http_sni = false
123 Configuration Attributes:
126 ----------------|----------------
127 execute |**Required.** The "execute" script method takes care of executing the check. The default template "plugin-check-command" which is imported into all CheckCommand objects takes care of this setting.
128 command |**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.
129 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
130 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
131 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
132 arguments |**Optional.** A dictionary of command arguments.
135 ### <a id="objecttype-checkcommand-arguments"></a> CheckCommand Arguments
137 Command arguments can be defined as key-value-pairs in the `arguments`
138 dictionary. If the argument requires additional configuration, for example
139 a `description` attribute or an optional condition, the value can be defined
140 as dictionary specifying additional options.
144 vars.x_val = "My command argument value."
152 key = "-Xnew" /* optional, set a new key identifier */
153 description = "My plugin requires this argument for doing X."
154 required = false /* optional, no error if not set */
155 skip_key = false /* always use "-X <value>" */
156 set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
157 order = -1 /* first position */
158 repeat_key = true /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
162 description = "My plugin requires this argument for doing Y."
163 required = false /* optional, no error if not set */
164 skip_key = true /* don't prefix "-Y" only use "<value>" */
165 set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
166 order = 0 /* second position */
167 repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
172 ------------|--------------
173 value | Optional argument value set by a macro string or a function call.
174 key | Optional argument key overriding the key identifier.
175 description | Optional argument description.
176 required | Required argument. Execution error if not set. Defaults to false (optional).
177 skip_key | Use the value as argument and skip the key.
178 set_if | Argument is added if the macro resolves to a defined numeric or boolean value. String values are not supported. Function calls returning a value are supported too.
179 order | Set if multiple arguments require a defined argument order.
180 repeat_key | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
184 `..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...`
186 Argument array `repeat_key = true`:
188 `'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'`
190 Argument array `repeat_key = false`:
192 `'key' 'value[0]' 'value[1]' 'value[2]'`
194 ## <a id="objecttype-checkcomponent"></a> CheckerComponent
196 The checker component is responsible for scheduling active checks.
202 object CheckerComponent "checker" {
203 concurrent_checks = 512
206 Configuration Attributes:
209 --------------------|----------------
210 concurrent\_checks |**Optional.** The maximum number of concurrent checks. Defaults to 512.
212 ## <a id="objecttype-checkresultreader"></a> CheckResultReader
214 Reads Icinga 1.x check results from a directory. This functionality is provided
215 to help existing Icinga 1.x users and might be useful for certain cluster
222 object CheckResultReader "reader" {
223 spool_dir = "/data/check-results"
226 Configuration Attributes:
229 ----------------|----------------
230 spool\_dir |**Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/".
232 ## <a id="objecttype-comment"></a> Comment
234 Comments created at runtime are represented as objects.
238 object Comment "localhost!my-comment" {
239 host_name = "localhost"
240 author = "icingaadmin"
241 text = "This is a comment."
244 Configuration Attributes:
247 ----------------|----------------
248 host_name | **Required.** The name of the host this comment belongs to.
249 service_name | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment.
250 author | **Required.** The author's name.
251 text | **Required.** The comment text.
252 entry_time | **Optional.** The unix timestamp when this comment was added.
253 entry_type | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
254 expire_time | **Optional.** The comment's expire time as unix timestamp.
256 ## <a id="objecttype-compatlogger"></a> CompatLogger
258 Writes log files in a format that's compatible with Icinga 1.x.
264 object CompatLogger "my-log" {
265 log_dir = "/var/log/icinga2/compat"
266 rotation_method = "HOURLY"
269 Configuration Attributes:
272 ----------------|----------------
273 log\_dir |**Optional.** Path to the compat log directory. Defaults to LocalStateDir + "/log/icinga2/compat".
274 rotation\_method|**Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
278 ## <a id="objecttype-dependency"></a> Dependency
280 Dependency objects are used to specify dependencies between hosts and services. Dependencies
281 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
286 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
287 > to just create a `Dependency` template and use the `apply` keyword to assign the
288 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
289 > type for `Host` or `Service`.
290 > Check the [dependencies](3-monitoring-basics.md#dependencies) chapter for detailed examples.
292 Service-to-Service Example:
294 object Dependency "webserver-internet" {
295 parent_host_name = "internet"
296 parent_service_name = "ping4"
298 child_host_name = "webserver"
299 child_service_name = "ping4"
301 states = [ OK, Warning ]
303 disable_checks = true
306 Host-to-Host Example:
308 object Dependency "webserver-internet" {
309 parent_host_name = "internet"
311 child_host_name = "webserver"
315 disable_checks = true
318 Configuration Attributes:
321 ----------------------|----------------
322 parent_host_name |**Required.** The parent host.
323 parent_service_name |**Optional.** The parent service. If omitted, this dependency object is treated as host dependency.
324 child_host_name |**Required.** The child host.
325 child_service_name |**Optional.** The child service. If omitted, this dependency object is treated as host dependency.
326 disable_checks |**Optional.** Whether to disable checks when this dependency fails. Defaults to false.
327 disable_notifications |**Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
328 ignore_soft_states |**Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
329 period |**Optional.** Time period during which this dependency is enabled.
330 states |**Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
332 Available state filters:
341 When using [apply rules](3-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
342 automatically determined by Icinga 2.
344 Service-to-Host Dependency Example:
346 apply Dependency "internet" to Service {
347 parent_host_name = "dsl-router"
348 disable_checks = true
350 assign where host.name != "dsl-router"
353 This example sets all service objects matching the assign condition into a dependency relation to
354 the parent host object `dsl-router` as implicit child services.
356 Service-to-Service-on-the-same-Host Dependency Example:
358 apply Dependency "disable-nrpe-checks" to Service {
359 parent_service_name = "nrpe-health"
361 assign where service.check_command == "nrpe"
362 ignore where service.name == "nrpe-health"
365 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
366 host object matched by the apply rule condition. All services where apply matches are made implicit child services
367 in this dependency relation.
370 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
371 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
372 `child_service_name` attributes has a different value.
374 ## <a id="objecttype-downtime"></a> Downtime
376 Downtimes created at runtime are represented as objects.
380 object Downtime "localhost!my-downtime" {
381 host_name = "localhost"
382 author = "icingaadmin"
383 text = "This is a comment."
386 Configuration Attributes:
389 ----------------|----------------
390 host_name | **Required.** The name of the host this comment belongs to.
391 service_name | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment.
392 author | **Required.** The author's name.
393 comment | **Required.** The comment text.
394 start_time | **Required.** The start time as unix timestamp.
395 end_time | **Required.** The end time as unix timestamp.
396 duration | **Required.** The duration as number.
397 entry_time | **Optional.** The unix timestamp when this downtime was added.
398 fixed | **Optional.** Whether the downtime is fixed (true) or flexible (false). Defaults to flexible. Details in the [advanced topics chapter](8-advanced-topics.md#fixed-flexible-downtimes).
399 triggers | **Optional.** List of downtimes which should be triggered by this downtime.
404 ----------------|----------------
405 trigger_time | The unix timestamp when this downtime was triggered.
406 triggered_by | The name of the downtime this downtime was triggered by.
410 ## <a id="objecttype-endpoint"></a> Endpoint
412 Endpoint objects are used to specify connection information for remote
417 object Endpoint "icinga2b" {
418 host = "192.168.5.46"
423 Example (disable replay log):
425 object Endpoint "icinga2b" {
426 host = "192.168.5.46"
431 Configuration Attributes:
434 ----------------|----------------
435 host |**Optional.** The hostname/IP address of the remote Icinga 2 instance.
436 port |**Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
437 log_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.
439 Endpoint objects cannot currently be created with the API.
441 ## <a id="objecttype-eventcommand"></a> EventCommand
443 An event command definition.
447 > Icinga 2 versions < 2.6.0 require the import of the [plugin-event-command](10-icinga-template-library.md#itl-plugin-event-command) template.
451 object EventCommand "restart-httpd-event" {
452 command = "/opt/bin/restart-httpd.sh"
456 Configuration Attributes:
459 ----------------|----------------
460 execute |**Required.** The "execute" script method takes care of executing the event handler. The default template "plugin-event-command" which is imported into all CheckCommand objects takes care of this setting.
461 command |**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.
462 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
463 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
464 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
465 arguments |**Optional.** A dictionary of command arguments.
467 Command arguments can be used the same way as for [CheckCommand objects](9-object-types.md#objecttype-checkcommand-arguments).
470 ## <a id="objecttype-externalcommandlistener"></a> ExternalCommandListener
472 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
478 object ExternalCommandListener "external" {
479 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
482 Configuration Attributes:
485 ----------------|----------------
486 command\_path |**Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
490 ## <a id="objecttype-filelogger"></a> FileLogger
492 Specifies Icinga 2 logging to a file.
496 object FileLogger "debug-file" {
498 path = "/var/log/icinga2/debug.log"
501 Configuration Attributes:
504 ----------------|----------------
505 path |**Required.** The log path.
506 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
509 ## <a id="objecttype-gelfwriter"></a> GelfWriter
511 Writes event log entries to a defined GELF receiver host (Graylog2, Logstash).
517 object GelfWriter "gelf" {
522 Configuration Attributes:
525 ----------------------|----------------------
526 host |**Optional.** GELF receiver host address. Defaults to '127.0.0.1'.
527 port |**Optional.** GELF receiver port. Defaults to `12201`.
528 source |**Optional.** Source name for this instance. Defaults to `icinga2`.
529 enable_send_perfdata |**Optional.** Enable performance data for 'CHECK RESULT' events.
532 ## <a id="objecttype-graphitewriter"></a> GraphiteWriter
534 Writes check result metrics and performance data to a defined
535 Graphite Carbon host.
541 object GraphiteWriter "graphite" {
546 Configuration Attributes:
549 ----------------------|----------------------
550 host |**Optional.** Graphite Carbon host address. Defaults to '127.0.0.1'.
551 port |**Optional.** Graphite Carbon port. Defaults to 2003.
552 host_name_template |**Optional.** Metric prefix for host name. Defaults to "icinga2.$host.name$.host.$host.check_command$".
553 service_name_template |**Optional.** Metric prefix for service name. Defaults to "icinga2.$host.name$.services.$service.name$.$service.check_command$".
554 enable_send_thresholds | **Optional.** Send additional threshold metrics. Defaults to `false`.
555 enable_send_metadata | **Optional.** Send additional metadata metrics. Defaults to `false`.
556 enable_legacy_mode | **Optional.** Enable legacy mode for schema < 2.4. **Note**: This will be removed in 2.8.
558 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
562 ## <a id="objecttype-host"></a> Host
568 object Host NodeName {
569 display_name = "Local host on this node"
570 address = "127.0.0.1"
573 groups = [ "all-hosts" ]
575 check_command = "hostalive"
578 Configuration Attributes:
581 ----------------|----------------
582 display_name |**Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
583 address |**Optional.** The host's address. Available as command runtime macro `$address$` if set.
584 address6 |**Optional.** The host's address. Available as command runtime macro `$address6$` if set.
585 groups |**Optional.** A list of host groups this host belongs to.
586 vars |**Optional.** A dictionary containing custom attributes that are specific to this host.
587 check\_command |**Required.** The name of the check command.
588 max\_check\_attempts|**Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
589 check\_period |**Optional.** The name of a time period which determines when this host should be checked. Not set by default.
590 check\_timeout |**Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
591 check\_interval |**Optional.** The check interval (in seconds). This interval is used for checks when the host is in a `HARD` state. Defaults to 5 minutes.
592 retry\_interval |**Optional.** The retry interval (in seconds). This interval is used for checks when the host is in a `SOFT` state. Defaults to 1 minute.
593 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
594 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
595 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
596 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
597 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
598 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
599 event\_command |**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.
600 flapping\_threshold|**Optional.** The flapping threshold in percent when a host is considered to be flapping.
601 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
602 zone |**Optional.** The zone this object is a member of.
603 command\_endpoint|**Optional.** The endpoint where commands are executed on.
604 notes |**Optional.** Notes for the host.
605 notes\_url |**Optional.** Url for notes for the host (for example, in notification commands).
606 action\_url |**Optional.** Url for actions for the host (for example, an external graphing tool).
607 icon\_image |**Optional.** Icon image for the host. Used by external interfaces only.
608 icon\_image\_alt|**Optional.** Icon image description for the host. Used by external interface only.
610 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
611 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
615 > The `address` and `address6` attributes are required for running commands using
616 > the `$address$` and `$address6$` runtime macros.
620 Name | Type | Description
621 --------------------------|---------------|-----------------
622 next\_check | Number | When the next check occurs (as a UNIX timestamp).
623 last\_check | Number | When the last check occured (as a UNIX timestamp).
624 check\_attempt | Number | The current check attempt number.
625 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
626 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
627 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
628 last\_check\_result | CheckResult | The current check result.
629 last\_state\_change | Number | When the last state change occurred (as a UNIX timestamp).
630 last\_hard\_state\_change | Number | When the last hard state change occurred (as a UNIX timestamp).
631 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
632 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
633 acknowledgement_expiry | Number | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
634 downtime\_depth | Number | Whether the host has one or more active downtimes.
635 flapping_last_change | Number | When the last flapping change occurred (as a UNIX timestamp).
636 flapping | Boolean | Whether the host is flapping between states.
637 state | Number | The current state (0 = UP, 1 = DOWN).
638 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
639 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
640 last_state_up | Number | When the last UP state occurred (as a UNIX timestamp).
641 last_state_down | Number | When the last DOWN state occurred (as a UNIX timestamp).
645 ## <a id="objecttype-hostgroup"></a> HostGroup
651 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
655 object HostGroup "my-hosts" {
656 display_name = "My hosts"
659 Configuration Attributes:
662 ----------------|----------------
663 display_name |**Optional.** A short description of the host group.
664 groups |**Optional.** An array of nested group names.
666 ## <a id="objecttype-icingaapplication"></a> IcingaApplication
668 The IcingaApplication object is required to start Icinga 2.
669 The object name must be `app`. If the object configuration
670 is missing, Icinga 2 will automatically create an IcingaApplication
675 object IcingaApplication "app" {
676 enable_perfdata = false
679 Configuration Attributes:
682 ----------------------|--------------------------
683 enable_notifications |**Optional.** Whether notifications are globally enabled. Defaults to true.
684 enable_event_handlers |**Optional.** Whether event handlers are globally enabled. Defaults to true.
685 enable_flapping |**Optional.** Whether flap detection is globally enabled. Defaults to true.
686 enable_host_checks |**Optional.** Whether active host checks are globally enabled. Defaults to true.
687 enable_service_checks |**Optional.** Whether active service checks are globally enabled. Defaults to true.
688 enable_perfdata |**Optional.** Whether performance data processing is globally enabled. Defaults to true.
689 vars |**Optional.** A dictionary containing custom attributes that are available globally.
691 ## <a id="objecttype-idomysqlconnection"></a> IdoMySqlConnection
693 IDO database adapter for MySQL.
697 library "db_ido_mysql"
699 object IdoMysqlConnection "mysql-ido" {
707 downtimehistory_age = 48h
708 contactnotifications_age = 31d
712 Configuration Attributes:
715 ----------------|----------------
716 host |**Optional.** MySQL database host address. Defaults to "localhost".
717 port |**Optional.** MySQL database port. Defaults to 3306.
718 socket_path |**Optional.** MySQL socket path.
719 user |**Optional.** MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
720 password |**Optional.** MySQL database user's password. Defaults to "icinga".
721 database |**Optional.** MySQL database name. Defaults to "icinga".
722 enable\_ssl |**Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
723 ssl\_key |**Optional.** MySQL SSL client key file path.
724 ssl\_cert |**Optional.** MySQL SSL certificate file path.
725 ssl\_ca |**Optional.** MySQL SSL certificate authority certificate file path.
726 ssl\_capath |**Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
727 ssl\_cipher |**Optional.** MySQL SSL list of allowed ciphers.
728 table\_prefix |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
729 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
730 instance\_description|**Optional.** Description for the Icinga 2 instance.
731 enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](6-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to "true".
732 failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](6-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
733 cleanup |**Optional.** Dictionary with items for historical table cleanup.
734 categories |**Optional.** Array of information types that should be written to the database.
739 ----------------|----------------
740 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
741 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
742 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
743 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
744 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
745 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
746 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
747 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
748 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
749 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
750 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
751 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
752 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
753 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
754 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
758 Name | Description | Required by
759 ---------------------|------------------------|--------------------
760 DbCatConfig | Configuration data | Icinga Web 2
761 DbCatState | Current state data | Icinga Web 2
762 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
763 DbCatComment | Comments | Icinga Web 2
764 DbCatDowntime | Downtimes | Icinga Web 2
765 DbCatEventHandler | Event handler data | Icinga Web 2
766 DbCatExternalCommand | External commands | Icinga Web 2
767 DbCatFlapping | Flap detection data | Icinga Web 2
768 DbCatCheck | Check results | --
769 DbCatLog | Log messages | --
770 DbCatNotification | Notifications | Icinga Web 2
771 DbCatProgramStatus | Program status data | Icinga Web 2
772 DbCatRetention | Retention data | Icinga Web 2
773 DbCatStateHistory | Historical state data | Icinga Web 2
775 In addition to the category flags listed above the `DbCatEverything`
776 flag may be used as a shortcut for listing all flags.
780 > The previous way of defining the `categories` attribute e.g.
781 > `DbCatProgramStatus | DbCatState` was deprecated in 2.5 and will
782 > be removed in future versions.
784 External interfaces like Icinga Web 2 require everything except `DbCatCheck`
785 and `DbCatLog` which is the default value if `categories` is not set.
787 ## <a id="objecttype-idopgsqlconnection"></a> IdoPgSqlConnection
789 IDO database adapter for PostgreSQL.
793 library "db_ido_pgsql"
795 object IdoPgsqlConnection "pgsql-ido" {
803 downtimehistory_age = 48h
804 contactnotifications_age = 31d
808 Configuration Attributes:
811 ----------------|----------------
812 host |**Optional.** PostgreSQL database host address. Defaults to "localhost".
813 port |**Optional.** PostgreSQL database port. Defaults to "5432".
814 user |**Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to "icinga".
815 password |**Optional.** PostgreSQL database user's password. Defaults to "icinga".
816 database |**Optional.** PostgreSQL database name. Defaults to "icinga".
817 table\_prefix |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_".
818 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
819 instance\_description|**Optional.** Description for the Icinga 2 instance.
820 enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](6-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to "true".
821 failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](6-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
822 cleanup |**Optional.** Dictionary with items for historical table cleanup.
823 categories |**Optional.** Array of information types that should be written to the database.
828 ----------------|----------------
829 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
830 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
831 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
832 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
833 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
834 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
835 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
836 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
837 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
838 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
839 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
840 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
841 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
842 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
843 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
847 Name | Description | Required by
848 ---------------------|------------------------|--------------------
849 DbCatConfig | Configuration data | Icinga Web 2
850 DbCatState | Current state data | Icinga Web 2
851 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
852 DbCatComment | Comments | Icinga Web 2
853 DbCatDowntime | Downtimes | Icinga Web 2
854 DbCatEventHandler | Event handler data | Icinga Web 2
855 DbCatExternalCommand | External commands | Icinga Web 2
856 DbCatFlapping | Flap detection data | Icinga Web 2
857 DbCatCheck | Check results | --
858 DbCatLog | Log messages | --
859 DbCatNotification | Notifications | Icinga Web 2
860 DbCatProgramStatus | Program status data | Icinga Web 2
861 DbCatRetention | Retention data | Icinga Web 2
862 DbCatStateHistory | Historical state data | Icinga Web 2
864 In addition to the category flags listed above the `DbCatEverything`
865 flag may be used as a shortcut for listing all flags.
869 > The previous way of defining the `categories` attribute e.g.
870 > `DbCatProgramStatus | DbCatState` was deprecated in 2.5 and will
871 > be removed in future versions.
873 External interfaces like Icinga Web 2 require everything except `DbCatCheck`
874 and `DbCatLog` which is the default value if `categories` is not set.
877 ## <a id="objecttype-influxdbwriter"></a> InfluxdbWriter
879 Writes check result metrics and performance data to a defined InfluxDB host.
885 object InfluxdbWriter "influxdb" {
890 measurement = "$host.check_command$"
892 hostname = "$host.name$"
896 measurement = "$service.check_command$"
898 hostname = "$host.name$"
899 service = "$service.name$"
904 Measurement names and tags are fully configurable by the end user. The InfluxdbWriter
905 object will automatically add a `metric` tag to each data point. This correlates to the
906 perfdata label. Fields (value, warn, crit, min, max) are created from data if available
907 and the configuration allows it. If a value associated with a tag is not able to be
908 resolved, it will be dropped and not sent to the target host.
910 Backslashes are allowed in tag keys, tag values and field keys, however they are also
911 escape characters when followed by a space or comma, but cannot be escaped themselves.
912 As a result all trailling slashes in these fields are replaced with an underscore. This
913 predominantly affects Windows paths e.g. `C:\` becomes `C:_`.
915 The database is assumed to exist so this object will make no attempt to create it currently.
917 Configuration Attributes:
920 -----------------------|---------------------------------------------------------------------------------------------------------
921 host | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
922 port | **Required.** InfluxDB HTTP port. Defaults to `8086`.
923 database | **Required.** InfluxDB database name. Defaults to `icinga2`.
924 username | **Optional.** InfluxDB user name. Defaults to `none`.
925 password | **Optional.** InfluxDB user password. Defaults to `none`.
926 ssl_enable | **Optional.** Whether to use a TLS stream. Defaults to `false`.
927 ssl_ca_cert | **Optional.** CA certificate to validate the remote host.
928 ssl_cert | **Optional.** Host certificate to present to the remote host for mutual verification.
929 ssl_key | **Optional.** Host key to accompany the ssl_cert
930 host_template | **Required.** Host template to define the InfluxDB line protocol.
931 service_template | **Required.** Service template to define the influxDB line protocol.
932 enable_send_thresholds | **Optional.** Whether to send warn, crit, min & max tagged data.
933 enable_send_metadata | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
934 flush_interval | **Optional.** How long to buffer data points before transfering to InfluxDB. Defaults to `10s`.
935 flush_threshold | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`.
936 socket_timeout | **Optional.** How long to wait for InfluxDB to respond. Defaults to `5s`.
938 ### <a id="objecttype-influxdbwriter-instance-tags"></a> Instance Tagging
940 Consider the following service check:
942 apply Service "disk" for (disk => attributes in host.vars.disks) {
943 import "generic-service"
944 check_command = "disk"
945 display_name = "Disk " + disk
946 vars.disk_partitions = disk
947 assign where host.vars.disks
950 This is a typical pattern for checking individual disks, NICs, SSL certificates etc associated
951 with a host. What would be useful is to have the data points tagged with the specific instance
952 for that check. This would allow you to query time series data for a check on a host and for a
953 specific instance e.g. /dev/sda. To do this quite simply add the instance to the service variables:
955 apply Service "disk" for (disk => attributes in host.vars.disks) {
961 Then modify your writer configuration to add this tag to your data points if the instance variable
962 is associated with the service:
964 object InfluxdbWriter "influxdb" {
967 measurement = "$service.check_command$"
969 hostname = "$host.name$"
970 service = "$service.name$"
971 instance = "$service.vars.instance$"
977 ## <a id="objecttype-livestatuslistener"></a> LiveStatusListener
979 Livestatus API interface available as TCP or UNIX socket. Historical table queries
980 require the [CompatLogger](9-object-types.md#objecttype-compatlogger) feature enabled
981 pointing to the log files using the `compat_log_path` configuration attribute.
987 object LivestatusListener "livestatus-tcp" {
989 bind_host = "127.0.0.1"
993 object LivestatusListener "livestatus-unix" {
995 socket_path = "/var/run/icinga2/cmd/livestatus"
998 Configuration Attributes:
1001 ----------------|----------------
1002 socket\_type |**Optional.** Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
1003 bind\_host |**Optional.** Only valid when socket\_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
1004 bind\_port |**Optional.** Only valid when `socket_type` is "tcp". Port to listen on for connections. Defaults to 6558.
1005 socket\_path |**Optional.** Only valid when `socket_type` is "unix". Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus".
1006 compat\_log\_path |**Optional.** Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"
1010 > UNIX sockets are not supported on Windows.
1013 ## <a id="objecttype-notification"></a> Notification
1015 Notification objects are used to specify how users should be notified in case
1016 of host and service state changes and other events.
1020 > Rather than creating a `Notification` object for a specific host or service it is
1021 > usually easier to just create a `Notification` template and use the `apply` keyword
1022 > to assign the notification to a number of hosts or services. Use the `to` keyword
1023 > to set the specific target type for `Host` or `Service`.
1024 > Check the [notifications](3-monitoring-basics.md#notifications) chapter for detailed examples.
1028 object Notification "localhost-ping-notification" {
1029 host_name = "localhost"
1030 service_name = "ping4"
1032 command = "mail-notification"
1034 users = [ "user1", "user2" ]
1036 types = [ Problem, Recovery ]
1039 Configuration Attributes:
1042 --------------------------|----------------
1043 host_name | **Required.** The name of the host this notification belongs to.
1044 service_name | **Optional.** The short name of the service this notification belongs to. If omitted, this notification object is treated as host notification.
1045 vars | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
1046 users | **Optional.** A list of user names who should be notified.
1047 user_groups | **Optional.** A list of user group names who should be notified.
1048 times | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
1049 command | **Required.** The name of the notification command which should be executed when the notification is triggered.
1050 interval | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, [re-notifications](3-monitoring-basics.md#disable-renotification) are disabled.
1051 period | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
1052 zone |**Optional.** The zone this object is a member of.
1053 types | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
1054 states | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
1056 Available notification state filters for Service:
1063 Available notification state filters for Host:
1068 Available notification type filters:
1082 Name | Type | Description
1083 --------------------------|---------------|-----------------
1084 last\_notification | Number | When the last notification was sent for this Notification object (as a UNIX timestamp).
1085 next\_notification | Number | 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).
1086 notification\_number | Number | The notification number
1087 last\_problem\_notification | Number | When the last notification was sent for a problem (as a UNIX timestamp).
1090 ## <a id="objecttype-notificationcommand"></a> NotificationCommand
1092 A notification command definition.
1096 > Icinga 2 versions < 2.6.0 require the import of the [plugin-notification-command](10-icinga-template-library.md#itl-plugin-notification-command) template.
1100 object NotificationCommand "mail-service-notification" {
1102 SysconfDir + "/icinga2/scripts/mail-notification.sh"
1106 NOTIFICATIONTYPE = "$notification.type$"
1107 SERVICEDESC = "$service.name$"
1108 HOSTALIAS = "$host.display_name$"
1109 HOSTADDRESS = "$address$"
1110 SERVICESTATE = "$service.state$"
1111 LONGDATETIME = "$icinga.long_date_time$"
1112 SERVICEOUTPUT = "$service.output$"
1113 NOTIFICATIONAUTHORNAME = "$notification.author$"
1114 NOTIFICATIONCOMMENT = "$notification.comment$"
1115 HOSTDISPLAYNAME = "$host.display_name$"
1116 SERVICEDISPLAYNAME = "$service.display_name$"
1117 USEREMAIL = "$user.email$"
1121 Configuration Attributes:
1124 ----------------|----------------
1125 execute |**Required.** The "execute" script method takes care of executing the notification. The default template "plugin-notification-command" which is imported into all CheckCommand objects takes care of this setting.
1126 command |**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.
1127 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1128 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
1129 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
1130 arguments |**Optional.** A dictionary of command arguments.
1132 Command arguments can be used the same way as for [CheckCommand objects](9-object-types.md#objecttype-checkcommand-arguments).
1135 ## <a id="objecttype-notificationcomponent"></a> NotificationComponent
1137 The notification component is responsible for sending notifications. There are no configurable options.
1141 library "notification"
1143 object NotificationComponent "notification" { }
1145 Configuration Attributes:
1148 ----------------|----------------
1149 enable\_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](6-distributed-monitoring.md#distributed-monitoring-high-availability-notifications). Disabling this currently only affects reminder notifications. Defaults to "true".
1151 ## <a id="objecttype-opentsdbwriter"></a> OpenTsdbWriter
1153 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1159 object OpenTsdbWriter "opentsdb" {
1164 Configuration Attributes:
1167 ----------------------|----------------------
1168 host |**Optional.** OpenTSDB host address. Defaults to '127.0.0.1'.
1169 port |**Optional.** OpenTSDB port. Defaults to 4242.
1172 ## <a id="objecttype-perfdatawriter"></a> PerfdataWriter
1174 Writes check result performance data to a defined path using macro
1175 pattern consisting of custom attributes and runtime macros.
1181 object PerfdataWriter "pnp" {
1182 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1184 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1186 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$"
1187 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$"
1189 rotation_interval = 15s
1192 Configuration Attributes:
1195 ------------------------|----------------
1196 host_perfdata\_path |**Optional.** Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
1197 service_perfdata\_path |**Optional.** Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
1198 host_temp\_path |**Optional.** Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
1199 service_temp\_path |**Optional.** Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
1200 host_format\_template |**Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1201 service_format\_template|**Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1202 rotation\_interval |**Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to 30 seconds.
1204 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1205 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1208 ## <a id="objecttype-scheduleddowntime"></a> ScheduledDowntime
1210 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1214 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1215 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1216 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1217 > type for `Host` or `Service`.
1218 > Check the [recurring downtimes](8-advanced-topics.md#recurring-downtimes) example for details.
1222 object ScheduledDowntime "some-downtime" {
1223 host_name = "localhost"
1224 service_name = "ping4"
1226 author = "icingaadmin"
1227 comment = "Some comment"
1233 "sunday" = "02:00-03:00"
1237 Configuration Attributes:
1240 ----------------|----------------
1241 host_name |**Required.** The name of the host this scheduled downtime belongs to.
1242 service_name |**Optional.** The short name of the service this scheduled downtime belongs to. If omitted, this downtime object is treated as host downtime.
1243 author |**Required.** The author of the downtime.
1244 comment |**Required.** A comment for the downtime.
1245 fixed |**Optional.** Whether this is a fixed downtime. Defaults to true.
1246 duration |**Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1247 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1249 ScheduledDowntime objects have composite names, i.e. their names are based
1250 on the `host_name` and `service_name` attributes and the
1251 name you specified. This means you can define more than one object
1252 with the same (short) name as long as one of the `host_name` and
1253 `service_name` attributes has a different value.
1256 ## <a id="objecttype-service"></a> Service
1258 Service objects describe network services and how they should be checked
1263 > Rather than creating a `Service` object for a specific host it is usually easier
1264 > to just create a `Service` template and use the `apply` keyword to assign the
1265 > service to a number of hosts.
1266 > Check the [apply](3-monitoring-basics.md#using-apply) chapter for details.
1270 object Service "uptime" {
1271 host_name = "localhost"
1273 display_name = "localhost Uptime"
1275 check_command = "check_snmp"
1277 vars.community = "public"
1278 vars.oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1280 check_interval = 60s
1281 retry_interval = 15s
1283 groups = [ "all-services", "snmp" ]
1286 Configuration Attributes:
1289 ----------------|----------------
1290 display_name |**Optional.** A short description of the service.
1291 host_name |**Required.** The host this service belongs to. There must be a `Host` object with that name.
1292 name |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
1293 groups |**Optional.** The service groups this service belongs to.
1294 vars |**Optional.** A dictionary containing custom attributes that are specific to this service.
1295 check\_command |**Required.** The name of the check command.
1296 max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1297 check\_period |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1298 check\_timeout |**Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
1299 check\_interval |**Optional.** The check interval (in seconds). This interval is used for checks when the service is in a `HARD` state. Defaults to 5 minutes.
1300 retry\_interval |**Optional.** The retry interval (in seconds). This interval is used for checks when the service is in a `SOFT` state. Defaults to 1 minute.
1301 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
1302 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
1303 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
1304 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
1305 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
1306 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
1307 event\_command |**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.
1308 flapping\_threshold|**Optional.** The flapping threshold in percent when a service is considered to be flapping.
1309 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
1310 zone |**Optional.** The zone this object is a member of.
1311 command\_endpoint|**Optional.** The endpoint where commands are executed on.
1312 notes |**Optional.** Notes for the service.
1313 notes\_url |**Optional.** Url for notes for the service (for example, in notification commands).
1314 action_url |**Optional.** Url for actions for the service (for example, an external graphing tool).
1315 icon\_image |**Optional.** Icon image for the service. Used by external interfaces only.
1316 icon\_image\_alt|**Optional.** Icon image description for the service. Used by external interface only.
1318 Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
1319 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1321 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
1322 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
1326 Name | Type | Description
1327 --------------------------|---------------|-----------------
1328 next\_check | Number | When the next check occurs (as a UNIX timestamp).
1329 last\_check | Number | When the last check occured (as a UNIX timestamp).
1330 check\_attempt | Number | The current check attempt number.
1331 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1332 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1333 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1334 last\_check\_result | CheckResult | The current check result.
1335 last\_state\_change | Number | When the last state change occurred (as a UNIX timestamp).
1336 last\_hard\_state\_change | Number | When the last hard state change occurred (as a UNIX timestamp).
1337 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1338 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1339 acknowledgement_expiry | Number | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1340 downtime\_depth | Number | Whether the service has one or more active downtimes.
1341 flapping_last_change | Number | When the last flapping change occurred (as a UNIX timestamp).
1342 flapping | Boolean | Whether the host is flapping between states.
1343 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1344 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1345 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1346 last_state_ok | Number | When the last OK state occurred (as a UNIX timestamp).
1347 last_state_warning | Number | When the last WARNING state occurred (as a UNIX timestamp).
1348 last_state_critical | Number | When the last CRITICAL state occurred (as a UNIX timestamp).
1349 last_state_unknown | Number | When the last UNKNOWN state occurred (as a UNIX timestamp).
1352 ## <a id="objecttype-servicegroup"></a> ServiceGroup
1354 A group of services.
1358 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
1362 object ServiceGroup "snmp" {
1363 display_name = "SNMP services"
1366 Configuration Attributes:
1369 ----------------|----------------
1370 display_name |**Optional.** A short description of the service group.
1371 groups |**Optional.** An array of nested group names.
1374 ## <a id="objecttype-statusdatawriter"></a> StatusDataWriter
1376 Periodically writes status data files which are used by the Classic UI and other third-party tools.
1382 object StatusDataWriter "status" {
1383 status_path = "/var/cache/icinga2/status.dat"
1384 objects_path = "/var/cache/icinga2/objects.cache"
1385 update_interval = 30s
1388 Configuration Attributes:
1391 ----------------|----------------
1392 status\_path |**Optional.** Path to the status.dat file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
1393 objects\_path |**Optional.** Path to the objects.cache file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
1394 update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
1397 ## <a id="objecttype-sysloglogger"></a> SyslogLogger
1399 Specifies Icinga 2 logging to syslog.
1403 object SyslogLogger "crit-syslog" {
1404 severity = "critical"
1407 Configuration Attributes:
1410 ----------------|----------------
1411 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1414 ## <a id="objecttype-timeperiod"></a> TimePeriod
1416 Time periods can be used to specify when hosts/services should be checked or to limit
1417 when notifications should be sent out.
1421 object TimePeriod "nonworkhours" {
1422 import "legacy-timeperiod"
1424 display_name = "Icinga 2 TimePeriod for non working hours"
1427 monday = "00:00-8:00,17:00-24:00"
1428 tuesday = "00:00-8:00,17:00-24:00"
1429 wednesday = "00:00-8:00,17:00-24:00"
1430 thursday = "00:00-8:00,17:00-24:00"
1431 friday = "00:00-8:00,16:00-24:00"
1432 saturday = "00:00-24:00"
1433 sunday = "00:00-24:00"
1437 object TimePeriod "exampledays" {
1438 import "legacy-timeperiod"
1440 display_name = "Icinga 2 TimePeriod for random example days"
1443 //We still believe in Santa, no peeking!
1444 //Applies every 25th of December every year
1445 "december 25" = "00:00-24:00"
1447 //Any point in time can be specified,
1448 //but you still have to use a range
1449 "2038-01-19" = "03:13-03:15"
1451 //Evey 3rd day from the second monday of February
1452 //to 8th of November
1453 "monday 2 february - november 8 / 3" = "00:00-24:00"
1458 Additional examples can be found [here](8-advanced-topics.md#timeperiods).
1460 Configuration Attributes:
1463 ----------------|----------------
1464 display_name |**Optional.** A short description of the time period.
1465 update |**Required.** The "update" script method takes care of updating the internal representation of the time period. In virtually all cases you should import the "legacy-timeperiod" template to take care of this setting.
1466 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1467 prefer_includes |**Optional.** Boolean whether to prefer timeperiods `includes` or `excludes`. Default to true.
1468 excludes |**Optional.** An array of timeperiods, which should exclude from your timerange.
1469 includes |**Optional.** An array of timeperiods, which should include into your timerange
1471 The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define
1472 timeperiods including this one.
1476 Name | Type | Description
1477 --------------------------|---------------|-----------------
1478 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1481 ## <a id="objecttype-user"></a> User
1487 object User "icingaadmin" {
1488 display_name = "Icinga 2 Admin"
1489 groups = [ "icingaadmins" ]
1490 email = "icinga@localhost"
1491 pager = "icingaadmin@localhost.localdomain"
1495 states = [ OK, Warning, Critical, Unknown ]
1496 types = [ Problem, Recovery ]
1498 vars.additional_notes = "This is the Icinga 2 Admin account."
1501 Available notification state filters:
1510 Available notification type filters:
1522 Configuration Attributes:
1525 ----------------|----------------
1526 display_name |**Optional.** A short description of the user.
1527 email |**Optional.** An email string for this user. Useful for notification commands.
1528 pager |**Optional.** A pager string for this user. Useful for notification commands.
1529 vars |**Optional.** A dictionary containing custom attributes that are specific to this user.
1530 groups |**Optional.** An array of group names.
1531 enable_notifications|**Optional.** Whether notifications are enabled for this user.
1532 period |**Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default.
1533 types |**Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
1534 states |**Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
1538 Name | Type | Description
1539 --------------------------|---------------|-----------------
1540 last\_notification | Number | When the last notification was sent for this user (as a UNIX timestamp).
1542 ## <a id="objecttype-usergroup"></a> UserGroup
1548 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
1552 object UserGroup "icingaadmins" {
1553 display_name = "Icinga 2 Admin Group"
1556 Configuration Attributes:
1559 ----------------|----------------
1560 display_name |**Optional.** A short description of the user group.
1561 groups |**Optional.** An array of nested group names.
1564 ## <a id="objecttype-zone"></a> Zone
1566 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1570 object Zone "config-ha-master" {
1571 endpoints = [ "icinga2a", "icinga2b" ]
1575 object Zone "check-satellite" {
1576 endpoints = [ "icinga2c" ]
1577 parent = "config-ha-master"
1580 Configuration Attributes:
1583 ----------------|----------------
1584 endpoints |**Optional.** Array of endpoint names located in this zone.
1585 parent |**Optional.** The name of the parent zone.
1586 global |**Optional.** Whether configuration files for this zone should be synced to all endpoints. Defaults to false.
1588 Zone objects cannot currently be created with the API.
1590 # <a id="value-types"></a> Value Types
1592 In addition to [configuration objects](9-object-types.md#object-types) Icinga 2 also uses a few other types to represent its internal state. The following types are exposed via the [API](12-icinga2-api.md#icinga2-api).
1594 ## <a id="value-types-checkresult"></a> CheckResult
1596 Name | Type | Description
1597 --------------------------|---------------|-----------------
1598 exit_status | Number | The exit status returned by the check execution.
1599 output | String | The check output.
1600 performance_data | Array | Array of [performance data values](9-object-types.md#value-types-perfdatavalue).
1601 check_source | String | Name of the node executing the check.
1602 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1603 command | Value | Array of command with shell-escaped arguments or command line string.
1604 execution_start | Number | Check execution start time (as a UNIX timestamp).
1605 execution_end | Number | Check execution end time (as a UNIX timestamp).
1606 schedule_start | Number | Scheduled check execution start time (as a UNIX timestamp).
1607 schedule_end | Number | Scheduled check execution end time (as a UNIX timestamp).
1608 active | Boolean | Whether the result is from an active or passive check.
1609 vars_before | Dictionary | Internal attribute used for calculations.
1610 vars_after | Dictionary | Internal attribute used for calculations.
1612 ## <a id="value-types-perfdatavalue"></a> PerfdataValue
1614 Icinga 2 parses performance data strings returned by check plugins and makes the information available to external interfaces (e.g. [GraphiteWriter](9-object-types.md#objecttype-graphitewriter) or the [Icinga 2 API](12-icinga2-api.md#icinga2-api)).
1616 Name | Type | Description
1617 --------------------------|---------------|-----------------
1618 label | String | Performance data label.
1619 value | Number | Normalized performance data value without unit.
1620 counter | Boolean | Enabled if the original value contains `c` as unit. Defaults to `false`.
1621 unit | String | Unit of measurement (`seconds`, `bytes`. `percent`) according to the [plugin API](5-service-monitoring.md#service-monitoring-plugin-api).
1622 crit | Value | Critical threshold value.
1623 warn | Value | Warning threshold value.
1624 min | Value | Minimum value returned by the check.
1625 max | Value | Maximum value returned by the check.