1 # Config 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 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](09-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 ## ApiListener <a id="objecttype-apilistener"></a>
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](04-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 ## ApiUser <a id="objecttype-apiuser"></a>
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 ## CheckCommand <a id="objecttype-checkcommand"></a>
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 ### CheckCommand Arguments <a id="objecttype-checkcommand-arguments"></a>
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 ## CheckerComponent <a id="objecttype-checkcomponent"></a>
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 ## CheckResultReader <a id="objecttype-checkresultreader"></a>
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 ## Comment <a id="objecttype-comment"></a>
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.
255 persistent | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
257 ## CompatLogger <a id="objecttype-compatlogger"></a>
259 Writes log files in a format that's compatible with Icinga 1.x.
265 object CompatLogger "my-log" {
266 log_dir = "/var/log/icinga2/compat"
267 rotation_method = "HOURLY"
270 Configuration Attributes:
273 ----------------|----------------
274 log\_dir |**Optional.** Path to the compat log directory. Defaults to LocalStateDir + "/log/icinga2/compat".
275 rotation\_method|**Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
279 ## Dependency <a id="objecttype-dependency"></a>
281 Dependency objects are used to specify dependencies between hosts and services. Dependencies
282 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
287 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
288 > to just create a `Dependency` template and use the `apply` keyword to assign the
289 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
290 > type for `Host` or `Service`.
291 > Check the [dependencies](03-monitoring-basics.md#dependencies) chapter for detailed examples.
293 Service-to-Service Example:
295 object Dependency "webserver-internet" {
296 parent_host_name = "internet"
297 parent_service_name = "ping4"
299 child_host_name = "webserver"
300 child_service_name = "ping4"
302 states = [ OK, Warning ]
304 disable_checks = true
307 Host-to-Host Example:
309 object Dependency "webserver-internet" {
310 parent_host_name = "internet"
312 child_host_name = "webserver"
316 disable_checks = true
319 Configuration Attributes:
322 ----------------------|----------------
323 parent_host_name |**Required.** The parent host.
324 parent_service_name |**Optional.** The parent service. If omitted, this dependency object is treated as host dependency.
325 child_host_name |**Required.** The child host.
326 child_service_name |**Optional.** The child service. If omitted, this dependency object is treated as host dependency.
327 disable_checks |**Optional.** Whether to disable checks when this dependency fails. Defaults to false.
328 disable_notifications |**Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
329 ignore_soft_states |**Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
330 period |**Optional.** Time period during which this dependency is enabled.
331 states |**Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
333 Available state filters:
342 When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
343 automatically determined by Icinga 2.
345 Service-to-Host Dependency Example:
347 apply Dependency "internet" to Service {
348 parent_host_name = "dsl-router"
349 disable_checks = true
351 assign where host.name != "dsl-router"
354 This example sets all service objects matching the assign condition into a dependency relation to
355 the parent host object `dsl-router` as implicit child services.
357 Service-to-Service-on-the-same-Host Dependency Example:
359 apply Dependency "disable-nrpe-checks" to Service {
360 parent_service_name = "nrpe-health"
362 assign where service.check_command == "nrpe"
363 ignore where service.name == "nrpe-health"
366 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
367 host object matched by the apply rule condition. All services where apply matches are made implicit child services
368 in this dependency relation.
371 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
372 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
373 `child_service_name` attributes has a different value.
375 ## Downtime <a id="objecttype-downtime"></a>
377 Downtimes created at runtime are represented as objects.
381 object Downtime "localhost!my-downtime" {
382 host_name = "localhost"
383 author = "icingaadmin"
384 text = "This is a comment."
387 Configuration Attributes:
390 ----------------|----------------
391 host_name | **Required.** The name of the host this comment belongs to.
392 service_name | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment.
393 author | **Required.** The author's name.
394 comment | **Required.** The comment text.
395 start_time | **Required.** The start time as unix timestamp.
396 end_time | **Required.** The end time as unix timestamp.
397 duration | **Required.** The duration as number.
398 entry_time | **Optional.** The unix timestamp when this downtime was added.
399 fixed | **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).
400 triggers | **Optional.** List of downtimes which should be triggered by this downtime.
405 ----------------|----------------
406 trigger_time | The unix timestamp when this downtime was triggered.
407 triggered_by | The name of the downtime this downtime was triggered by.
411 ## Endpoint <a id="objecttype-endpoint"></a>
413 Endpoint objects are used to specify connection information for remote
418 object Endpoint "icinga2b" {
419 host = "192.168.5.46"
424 Example (disable replay log):
426 object Endpoint "icinga2b" {
427 host = "192.168.5.46"
432 Configuration Attributes:
435 ----------------|----------------
436 host |**Optional.** The hostname/IP address of the remote Icinga 2 instance.
437 port |**Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
438 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.
440 Endpoint objects cannot currently be created with the API.
442 ## EventCommand <a id="objecttype-eventcommand"></a>
444 An event command definition.
448 > Icinga 2 versions < 2.6.0 require the import of the [plugin-event-command](10-icinga-template-library.md#itl-plugin-event-command) template.
452 object EventCommand "restart-httpd-event" {
453 command = "/opt/bin/restart-httpd.sh"
457 Configuration Attributes:
460 ----------------|----------------
461 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.
462 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.
463 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
464 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
465 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
466 arguments |**Optional.** A dictionary of command arguments.
468 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
470 More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
472 ## ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
474 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
480 object ExternalCommandListener "external" {
481 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
484 Configuration Attributes:
487 ----------------|----------------
488 command\_path |**Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
492 ## FileLogger <a id="objecttype-filelogger"></a>
494 Specifies Icinga 2 logging to a file.
498 object FileLogger "debug-file" {
500 path = "/var/log/icinga2/debug.log"
503 Configuration Attributes:
506 ----------------|----------------
507 path |**Required.** The log path.
508 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
511 ## GelfWriter <a id="objecttype-gelfwriter"></a>
513 Writes event log entries to a defined GELF receiver host (Graylog2, Logstash).
519 object GelfWriter "gelf" {
524 Configuration Attributes:
527 ----------------------|----------------------
528 host |**Optional.** GELF receiver host address. Defaults to '127.0.0.1'.
529 port |**Optional.** GELF receiver port. Defaults to `12201`.
530 source |**Optional.** Source name for this instance. Defaults to `icinga2`.
531 enable_send_perfdata |**Optional.** Enable performance data for 'CHECK RESULT' events.
534 ## GraphiteWriter <a id="objecttype-graphitewriter"></a>
536 Writes check result metrics and performance data to a defined
537 Graphite Carbon host.
543 object GraphiteWriter "graphite" {
548 Configuration Attributes:
551 ----------------------|----------------------
552 host |**Optional.** Graphite Carbon host address. Defaults to '127.0.0.1'.
553 port |**Optional.** Graphite Carbon port. Defaults to 2003.
554 host_name_template |**Optional.** Metric prefix for host name. Defaults to "icinga2.$host.name$.host.$host.check_command$".
555 service_name_template |**Optional.** Metric prefix for service name. Defaults to "icinga2.$host.name$.services.$service.name$.$service.check_command$".
556 enable_send_thresholds | **Optional.** Send additional threshold metrics. Defaults to `false`.
557 enable_send_metadata | **Optional.** Send additional metadata metrics. Defaults to `false`.
559 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
563 ## Host <a id="objecttype-host"></a>
569 object Host NodeName {
570 display_name = "Local host on this node"
571 address = "127.0.0.1"
574 groups = [ "all-hosts" ]
576 check_command = "hostalive"
579 Configuration Attributes:
582 ----------------|----------------
583 display_name |**Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
584 address |**Optional.** The host's address. Available as command runtime macro `$address$` if set.
585 address6 |**Optional.** The host's address. Available as command runtime macro `$address6$` if set.
586 groups |**Optional.** A list of host groups this host belongs to.
587 vars |**Optional.** A dictionary containing custom attributes that are specific to this host.
588 check\_command |**Required.** The name of the check command.
589 max\_check\_attempts|**Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
590 check\_period |**Optional.** The name of a time period which determines when this host should be checked. Not set by default.
591 check\_timeout |**Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
592 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.
593 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.
594 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
595 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
596 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
597 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
598 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
599 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
600 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.
601 flapping\_threshold|**Optional.** The flapping threshold in percent when a host is considered to be flapping.
602 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
603 zone |**Optional.** The zone this object is a member of.
604 command\_endpoint|**Optional.** The endpoint where commands are executed on.
605 notes |**Optional.** Notes for the host.
606 notes\_url |**Optional.** Url for notes for the host (for example, in notification commands).
607 action\_url |**Optional.** Url for actions for the host (for example, an external graphing tool).
608 icon\_image |**Optional.** Icon image for the host. Used by external interfaces only.
609 icon\_image\_alt|**Optional.** Icon image description for the host. Used by external interface only.
611 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
612 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
616 > The `address` and `address6` attributes are required for running commands using
617 > the `$address$` and `$address6$` runtime macros.
621 Name | Type | Description
622 --------------------------|---------------|-----------------
623 next\_check | Number | When the next check occurs (as a UNIX timestamp).
624 last\_check | Number | When the last check occured (as a UNIX timestamp).
625 check\_attempt | Number | The current check attempt number.
626 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
627 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
628 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
629 last\_check\_result | CheckResult | The current check result.
630 last\_state\_change | Number | When the last state change occurred (as a UNIX timestamp).
631 last\_hard\_state\_change | Number | When the last hard state change occurred (as a UNIX timestamp).
632 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
633 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
634 acknowledgement_expiry | Number | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
635 downtime\_depth | Number | Whether the host has one or more active downtimes.
636 flapping_last_change | Number | When the last flapping change occurred (as a UNIX timestamp).
637 flapping | Boolean | Whether the host is flapping between states.
638 state | Number | The current state (0 = UP, 1 = DOWN).
639 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
640 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
641 last_state_up | Number | When the last UP state occurred (as a UNIX timestamp).
642 last_state_down | Number | When the last DOWN state occurred (as a UNIX timestamp).
646 ## HostGroup <a id="objecttype-hostgroup"></a>
652 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
656 object HostGroup "my-hosts" {
657 display_name = "My hosts"
660 Configuration Attributes:
663 ----------------|----------------
664 display_name |**Optional.** A short description of the host group.
665 groups |**Optional.** An array of nested group names.
667 ## IcingaApplication <a id="objecttype-icingaapplication"></a>
669 The IcingaApplication object is required to start Icinga 2.
670 The object name must be `app`. If the object configuration
671 is missing, Icinga 2 will automatically create an IcingaApplication
676 object IcingaApplication "app" {
677 enable_perfdata = false
680 Configuration Attributes:
683 ----------------------|--------------------------
684 enable_notifications |**Optional.** Whether notifications are globally enabled. Defaults to true.
685 enable_event_handlers |**Optional.** Whether event handlers are globally enabled. Defaults to true.
686 enable_flapping |**Optional.** Whether flap detection is globally enabled. Defaults to true.
687 enable_host_checks |**Optional.** Whether active host checks are globally enabled. Defaults to true.
688 enable_service_checks |**Optional.** Whether active service checks are globally enabled. Defaults to true.
689 enable_perfdata |**Optional.** Whether performance data processing is globally enabled. Defaults to true.
690 vars |**Optional.** A dictionary containing custom attributes that are available globally.
692 ## IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
694 IDO database adapter for MySQL.
698 library "db_ido_mysql"
700 object IdoMysqlConnection "mysql-ido" {
708 downtimehistory_age = 48h
709 contactnotifications_age = 31d
713 Configuration Attributes:
716 ----------------|----------------
717 host |**Optional.** MySQL database host address. Defaults to "localhost".
718 port |**Optional.** MySQL database port. Defaults to 3306.
719 socket_path |**Optional.** MySQL socket path.
720 user |**Optional.** MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
721 password |**Optional.** MySQL database user's password. Defaults to "icinga".
722 database |**Optional.** MySQL database name. Defaults to "icinga".
723 enable\_ssl |**Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
724 ssl\_key |**Optional.** MySQL SSL client key file path.
725 ssl\_cert |**Optional.** MySQL SSL certificate file path.
726 ssl\_ca |**Optional.** MySQL SSL certificate authority certificate file path.
727 ssl\_capath |**Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
728 ssl\_cipher |**Optional.** MySQL SSL list of allowed ciphers.
729 table\_prefix |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
730 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
731 instance\_description|**Optional.** Description for the Icinga 2 instance.
732 enable_ha |**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".
733 failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
734 cleanup |**Optional.** Dictionary with items for historical table cleanup.
735 categories |**Optional.** Array of information types that should be written to the database.
740 ----------------|----------------
741 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
742 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
743 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
744 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
745 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
746 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
747 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
748 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
749 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
750 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
751 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
752 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
753 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
754 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
755 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
759 Name | Description | Required by
760 ---------------------|------------------------|--------------------
761 DbCatConfig | Configuration data | Icinga Web 2
762 DbCatState | Current state data | Icinga Web 2
763 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
764 DbCatComment | Comments | Icinga Web 2
765 DbCatDowntime | Downtimes | Icinga Web 2
766 DbCatEventHandler | Event handler data | Icinga Web 2
767 DbCatExternalCommand | External commands | --
768 DbCatFlapping | Flap detection data | Icinga Web 2
769 DbCatCheck | Check results | --
770 DbCatLog | Log messages | --
771 DbCatNotification | Notifications | Icinga Web 2
772 DbCatProgramStatus | Program status data | Icinga Web 2
773 DbCatRetention | Retention data | Icinga Web 2
774 DbCatStateHistory | Historical state data | Icinga Web 2
776 The default value for `categories` includes everything required
777 by Icinga Web 2 in the table above.
779 In addition to the category flags listed above the `DbCatEverything`
780 flag may be used as a shortcut for listing all flags.
782 ## IdoPgSqlConnection <a id="objecttype-idopgsqlconnection"></a>
784 IDO database adapter for PostgreSQL.
788 library "db_ido_pgsql"
790 object IdoPgsqlConnection "pgsql-ido" {
798 downtimehistory_age = 48h
799 contactnotifications_age = 31d
803 Configuration Attributes:
806 ----------------|----------------
807 host |**Optional.** PostgreSQL database host address. Defaults to "localhost".
808 port |**Optional.** PostgreSQL database port. Defaults to "5432".
809 user |**Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to "icinga".
810 password |**Optional.** PostgreSQL database user's password. Defaults to "icinga".
811 database |**Optional.** PostgreSQL database name. Defaults to "icinga".
812 table\_prefix |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_".
813 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
814 instance\_description|**Optional.** Description for the Icinga 2 instance.
815 enable_ha |**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".
816 failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
817 cleanup |**Optional.** Dictionary with items for historical table cleanup.
818 categories |**Optional.** Array of information types that should be written to the database.
823 ----------------|----------------
824 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
825 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
826 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
827 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
828 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
829 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
830 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
831 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
832 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
833 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
834 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
835 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
836 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
837 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
838 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
842 Name | Description | Required by
843 ---------------------|------------------------|--------------------
844 DbCatConfig | Configuration data | Icinga Web 2
845 DbCatState | Current state data | Icinga Web 2
846 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
847 DbCatComment | Comments | Icinga Web 2
848 DbCatDowntime | Downtimes | Icinga Web 2
849 DbCatEventHandler | Event handler data | Icinga Web 2
850 DbCatExternalCommand | External commands | --
851 DbCatFlapping | Flap detection data | Icinga Web 2
852 DbCatCheck | Check results | --
853 DbCatLog | Log messages | --
854 DbCatNotification | Notifications | Icinga Web 2
855 DbCatProgramStatus | Program status data | Icinga Web 2
856 DbCatRetention | Retention data | Icinga Web 2
857 DbCatStateHistory | Historical state data | Icinga Web 2
859 The default value for `categories` includes everything required
860 by Icinga Web 2 in the table above.
862 In addition to the category flags listed above the `DbCatEverything`
863 flag may be used as a shortcut for listing all flags.
865 ## InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
867 Writes check result metrics and performance data to a defined InfluxDB host.
873 object InfluxdbWriter "influxdb" {
878 flush_threshold = 1024
882 measurement = "$host.check_command$"
884 hostname = "$host.name$"
888 measurement = "$service.check_command$"
890 hostname = "$host.name$"
891 service = "$service.name$"
896 Measurement names and tags are fully configurable by the end user. The InfluxdbWriter
897 object will automatically add a `metric` tag to each data point. This correlates to the
898 perfdata label. Fields (value, warn, crit, min, max) are created from data if available
899 and the configuration allows it. If a value associated with a tag is not able to be
900 resolved, it will be dropped and not sent to the target host.
902 Backslashes are allowed in tag keys, tag values and field keys, however they are also
903 escape characters when followed by a space or comma, but cannot be escaped themselves.
904 As a result all trailling slashes in these fields are replaced with an underscore. This
905 predominantly affects Windows paths e.g. `C:\` becomes `C:_`.
907 The database is assumed to exist so this object will make no attempt to create it currently.
909 Configuration Attributes:
912 -----------------------|---------------------------------------------------------------------------------------------------------
913 host | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
914 port | **Required.** InfluxDB HTTP port. Defaults to `8086`.
915 database | **Required.** InfluxDB database name. Defaults to `icinga2`.
916 username | **Optional.** InfluxDB user name. Defaults to `none`.
917 password | **Optional.** InfluxDB user password. Defaults to `none`.
918 ssl_enable | **Optional.** Whether to use a TLS stream. Defaults to `false`.
919 ssl_ca_cert | **Optional.** CA certificate to validate the remote host.
920 ssl_cert | **Optional.** Host certificate to present to the remote host for mutual verification.
921 ssl_key | **Optional.** Host key to accompany the ssl_cert
922 host_template | **Required.** Host template to define the InfluxDB line protocol.
923 service_template | **Required.** Service template to define the influxDB line protocol.
924 enable_send_thresholds | **Optional.** Whether to send warn, crit, min & max tagged data.
925 enable_send_metadata | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
926 flush_interval | **Optional.** How long to buffer data points before transfering to InfluxDB. Defaults to `10s`.
927 flush_threshold | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`.
929 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
930 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
933 ### Instance Tagging <a id="objecttype-influxdbwriter-instance-tags"></a>
935 Consider the following service check:
937 apply Service "disk" for (disk => attributes in host.vars.disks) {
938 import "generic-service"
939 check_command = "disk"
940 display_name = "Disk " + disk
941 vars.disk_partitions = disk
942 assign where host.vars.disks
945 This is a typical pattern for checking individual disks, NICs, SSL certificates etc associated
946 with a host. What would be useful is to have the data points tagged with the specific instance
947 for that check. This would allow you to query time series data for a check on a host and for a
948 specific instance e.g. /dev/sda. To do this quite simply add the instance to the service variables:
950 apply Service "disk" for (disk => attributes in host.vars.disks) {
956 Then modify your writer configuration to add this tag to your data points if the instance variable
957 is associated with the service:
959 object InfluxdbWriter "influxdb" {
962 measurement = "$service.check_command$"
964 hostname = "$host.name$"
965 service = "$service.name$"
966 instance = "$service.vars.instance$"
972 ## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
974 Livestatus API interface available as TCP or UNIX socket. Historical table queries
975 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
976 pointing to the log files using the `compat_log_path` configuration attribute.
982 object LivestatusListener "livestatus-tcp" {
984 bind_host = "127.0.0.1"
988 object LivestatusListener "livestatus-unix" {
990 socket_path = "/var/run/icinga2/cmd/livestatus"
993 Configuration Attributes:
996 ----------------|----------------
997 socket\_type |**Optional.** Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
998 bind\_host |**Optional.** Only valid when socket\_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
999 bind\_port |**Optional.** Only valid when `socket_type` is "tcp". Port to listen on for connections. Defaults to 6558.
1000 socket\_path |**Optional.** Only valid when `socket_type` is "unix". Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus".
1001 compat\_log\_path |**Optional.** Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"
1005 > UNIX sockets are not supported on Windows.
1008 ## Notification <a id="objecttype-notification"></a>
1010 Notification objects are used to specify how users should be notified in case
1011 of host and service state changes and other events.
1015 > Rather than creating a `Notification` object for a specific host or service it is
1016 > usually easier to just create a `Notification` template and use the `apply` keyword
1017 > to assign the notification to a number of hosts or services. Use the `to` keyword
1018 > to set the specific target type for `Host` or `Service`.
1019 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
1023 object Notification "localhost-ping-notification" {
1024 host_name = "localhost"
1025 service_name = "ping4"
1027 command = "mail-notification"
1029 users = [ "user1", "user2" ]
1031 types = [ Problem, Recovery ]
1034 Configuration Attributes:
1037 --------------------------|----------------
1038 host_name | **Required.** The name of the host this notification belongs to.
1039 service_name | **Optional.** The short name of the service this notification belongs to. If omitted, this notification object is treated as host notification.
1040 vars | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
1041 users | **Optional.** A list of user names who should be notified.
1042 user_groups | **Optional.** A list of user group names who should be notified.
1043 times | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
1044 command | **Required.** The name of the notification command which should be executed when the notification is triggered.
1045 interval | **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.
1046 period | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
1047 zone |**Optional.** The zone this object is a member of.
1048 types | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
1049 states | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
1051 Available notification state filters for Service:
1058 Available notification state filters for Host:
1063 Available notification type filters:
1077 Name | Type | Description
1078 --------------------------|---------------|-----------------
1079 last\_notification | Number | When the last notification was sent for this Notification object (as a UNIX timestamp).
1080 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).
1081 notification\_number | Number | The notification number
1082 last\_problem\_notification | Number | When the last notification was sent for a problem (as a UNIX timestamp).
1085 ## NotificationCommand <a id="objecttype-notificationcommand"></a>
1087 A notification command definition.
1091 > Icinga 2 versions < 2.6.0 require the import of the [plugin-notification-command](10-icinga-template-library.md#itl-plugin-notification-command) template.
1095 object NotificationCommand "mail-service-notification" {
1096 command = [ SysconfDir + "/icinga2/scripts/mail-service-notification.sh" ]
1101 value = "$notification_address$"
1103 "-6" = "$notification_address6$"
1104 "-b" = "$notification_author$"
1105 "-c" = "$notification_comment$"
1108 value = "$notification_date$"
1112 value = "$notification_servicename$"
1115 value = "$notification_from$"
1116 description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
1118 "-i" = "$notification_icingaweb2url$"
1121 value = "$notification_hostname$"
1125 value = "$notification_hostdisplayname$"
1129 value = "$notification_serviceoutput$"
1133 value = "$notification_useremail$"
1137 value = "$notification_servicestate$"
1141 value = "$notification_type$"
1145 value = "$notification_servicedisplayname$"
1147 "-v" = "$notification_logtosyslog$"
1151 notification_address = "$address$"
1152 notification_address6 = "$address6$"
1153 notification_author = "$notification.author$"
1154 notification_comment = "$notification.comment$"
1155 notification_type = "$notification.type$"
1156 notification_date = "$icinga.long_date_time$"
1157 notification_hostname = "$host.name$"
1158 notification_hostdisplayname = "$host.display_name$"
1159 notification_servicename = "$service.name$"
1160 notification_serviceoutput = "$service.output$"
1161 notification_servicestate = "$service.state$"
1162 notification_useremail = "$user.email$"
1163 notification_servicedisplayname = "$service.display_name$"
1168 Configuration Attributes:
1171 ----------------|----------------
1172 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.
1173 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.
1174 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1175 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
1176 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
1177 arguments |**Optional.** A dictionary of command arguments.
1179 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
1181 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
1183 ## NotificationComponent <a id="objecttype-notificationcomponent"></a>
1185 The notification component is responsible for sending notifications. There are no configurable options.
1189 library "notification"
1191 object NotificationComponent "notification" { }
1193 Configuration Attributes:
1196 ----------------|----------------
1197 enable\_ha |**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".
1199 ## OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1201 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1207 object OpenTsdbWriter "opentsdb" {
1212 Configuration Attributes:
1215 ----------------------|----------------------
1216 host |**Optional.** OpenTSDB host address. Defaults to '127.0.0.1'.
1217 port |**Optional.** OpenTSDB port. Defaults to 4242.
1220 ## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1222 Writes check result performance data to a defined path using macro
1223 pattern consisting of custom attributes and runtime macros.
1229 object PerfdataWriter "pnp" {
1230 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1232 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1234 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$"
1235 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$"
1237 rotation_interval = 15s
1240 Configuration Attributes:
1243 ------------------------|----------------
1244 host_perfdata\_path |**Optional.** Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
1245 service_perfdata\_path |**Optional.** Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
1246 host_temp\_path |**Optional.** Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
1247 service_temp\_path |**Optional.** Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
1248 host_format\_template |**Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1249 service_format\_template|**Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1250 rotation\_interval |**Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to 30 seconds.
1252 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1253 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1256 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
1258 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1262 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1263 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1264 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1265 > type for `Host` or `Service`.
1266 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
1270 object ScheduledDowntime "some-downtime" {
1271 host_name = "localhost"
1272 service_name = "ping4"
1274 author = "icingaadmin"
1275 comment = "Some comment"
1281 "sunday" = "02:00-03:00"
1285 Configuration Attributes:
1288 ----------------|----------------
1289 host_name |**Required.** The name of the host this scheduled downtime belongs to.
1290 service_name |**Optional.** The short name of the service this scheduled downtime belongs to. If omitted, this downtime object is treated as host downtime.
1291 author |**Required.** The author of the downtime.
1292 comment |**Required.** A comment for the downtime.
1293 fixed |**Optional.** Whether this is a fixed downtime. Defaults to true.
1294 duration |**Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1295 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1297 ScheduledDowntime objects have composite names, i.e. their names are based
1298 on the `host_name` and `service_name` attributes and the
1299 name you specified. This means you can define more than one object
1300 with the same (short) name as long as one of the `host_name` and
1301 `service_name` attributes has a different value.
1304 ## Service <a id="objecttype-service"></a>
1306 Service objects describe network services and how they should be checked
1311 > Rather than creating a `Service` object for a specific host it is usually easier
1312 > to just create a `Service` template and use the `apply` keyword to assign the
1313 > service to a number of hosts.
1314 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
1318 object Service "uptime" {
1319 host_name = "localhost"
1321 display_name = "localhost Uptime"
1323 check_command = "check_snmp"
1325 vars.community = "public"
1326 vars.oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1328 check_interval = 60s
1329 retry_interval = 15s
1331 groups = [ "all-services", "snmp" ]
1334 Configuration Attributes:
1337 ----------------|----------------
1338 display_name |**Optional.** A short description of the service.
1339 host_name |**Required.** The host this service belongs to. There must be a `Host` object with that name.
1340 name |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
1341 groups |**Optional.** The service groups this service belongs to.
1342 vars |**Optional.** A dictionary containing custom attributes that are specific to this service.
1343 check\_command |**Required.** The name of the check command.
1344 max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1345 check\_period |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1346 check\_timeout |**Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
1347 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.
1348 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.
1349 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
1350 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
1351 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
1352 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
1353 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
1354 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
1355 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.
1356 flapping\_threshold|**Optional.** The flapping threshold in percent when a service is considered to be flapping.
1357 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
1358 zone |**Optional.** The zone this object is a member of.
1359 command\_endpoint|**Optional.** The endpoint where commands are executed on.
1360 notes |**Optional.** Notes for the service.
1361 notes\_url |**Optional.** Url for notes for the service (for example, in notification commands).
1362 action_url |**Optional.** Url for actions for the service (for example, an external graphing tool).
1363 icon\_image |**Optional.** Icon image for the service. Used by external interfaces only.
1364 icon\_image\_alt|**Optional.** Icon image description for the service. Used by external interface only.
1366 Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
1367 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1369 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
1370 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
1374 Name | Type | Description
1375 --------------------------|---------------|-----------------
1376 next\_check | Number | When the next check occurs (as a UNIX timestamp).
1377 last\_check | Number | When the last check occured (as a UNIX timestamp).
1378 check\_attempt | Number | The current check attempt number.
1379 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1380 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1381 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1382 last\_check\_result | CheckResult | The current check result.
1383 last\_state\_change | Number | When the last state change occurred (as a UNIX timestamp).
1384 last\_hard\_state\_change | Number | When the last hard state change occurred (as a UNIX timestamp).
1385 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1386 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1387 acknowledgement_expiry | Number | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1388 downtime\_depth | Number | Whether the service has one or more active downtimes.
1389 flapping_last_change | Number | When the last flapping change occurred (as a UNIX timestamp).
1390 flapping | Boolean | Whether the host is flapping between states.
1391 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1392 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1393 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1394 last_state_ok | Number | When the last OK state occurred (as a UNIX timestamp).
1395 last_state_warning | Number | When the last WARNING state occurred (as a UNIX timestamp).
1396 last_state_critical | Number | When the last CRITICAL state occurred (as a UNIX timestamp).
1397 last_state_unknown | Number | When the last UNKNOWN state occurred (as a UNIX timestamp).
1400 ## ServiceGroup <a id="objecttype-servicegroup"></a>
1402 A group of services.
1406 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
1410 object ServiceGroup "snmp" {
1411 display_name = "SNMP services"
1414 Configuration Attributes:
1417 ----------------|----------------
1418 display_name |**Optional.** A short description of the service group.
1419 groups |**Optional.** An array of nested group names.
1422 ## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1424 Periodically writes status data files which are used by the Classic UI and other third-party tools.
1430 object StatusDataWriter "status" {
1431 status_path = "/var/cache/icinga2/status.dat"
1432 objects_path = "/var/cache/icinga2/objects.cache"
1433 update_interval = 30s
1436 Configuration Attributes:
1439 ----------------|----------------
1440 status\_path |**Optional.** Path to the status.dat file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
1441 objects\_path |**Optional.** Path to the objects.cache file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
1442 update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
1445 ## SyslogLogger <a id="objecttype-sysloglogger"></a>
1447 Specifies Icinga 2 logging to syslog.
1451 object SyslogLogger "crit-syslog" {
1452 severity = "critical"
1455 Configuration Attributes:
1458 ----------------|----------------
1459 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1462 ## TimePeriod <a id="objecttype-timeperiod"></a>
1464 Time periods can be used to specify when hosts/services should be checked or to limit
1465 when notifications should be sent out.
1469 object TimePeriod "nonworkhours" {
1470 import "legacy-timeperiod"
1472 display_name = "Icinga 2 TimePeriod for non working hours"
1475 monday = "00:00-8:00,17:00-24:00"
1476 tuesday = "00:00-8:00,17:00-24:00"
1477 wednesday = "00:00-8:00,17:00-24:00"
1478 thursday = "00:00-8:00,17:00-24:00"
1479 friday = "00:00-8:00,16:00-24:00"
1480 saturday = "00:00-24:00"
1481 sunday = "00:00-24:00"
1485 object TimePeriod "exampledays" {
1486 import "legacy-timeperiod"
1488 display_name = "Icinga 2 TimePeriod for random example days"
1491 //We still believe in Santa, no peeking!
1492 //Applies every 25th of December every year
1493 "december 25" = "00:00-24:00"
1495 //Any point in time can be specified,
1496 //but you still have to use a range
1497 "2038-01-19" = "03:13-03:15"
1499 //Evey 3rd day from the second monday of February
1500 //to 8th of November
1501 "monday 2 february - november 8 / 3" = "00:00-24:00"
1506 Additional examples can be found [here](08-advanced-topics.md#timeperiods).
1508 Configuration Attributes:
1511 ----------------|----------------
1512 display_name |**Optional.** A short description of the time period.
1513 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.
1514 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1515 prefer_includes |**Optional.** Boolean whether to prefer timeperiods `includes` or `excludes`. Default to true.
1516 excludes |**Optional.** An array of timeperiods, which should exclude from your timerange.
1517 includes |**Optional.** An array of timeperiods, which should include into your timerange
1519 The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define
1520 timeperiods including this one.
1524 Name | Type | Description
1525 --------------------------|---------------|-----------------
1526 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1529 ## User <a id="objecttype-user"></a>
1535 object User "icingaadmin" {
1536 display_name = "Icinga 2 Admin"
1537 groups = [ "icingaadmins" ]
1538 email = "icinga@localhost"
1539 pager = "icingaadmin@localhost.localdomain"
1543 states = [ OK, Warning, Critical, Unknown ]
1544 types = [ Problem, Recovery ]
1546 vars.additional_notes = "This is the Icinga 2 Admin account."
1549 Available notification state filters:
1558 Available notification type filters:
1570 Configuration Attributes:
1573 ----------------|----------------
1574 display_name |**Optional.** A short description of the user.
1575 email |**Optional.** An email string for this user. Useful for notification commands.
1576 pager |**Optional.** A pager string for this user. Useful for notification commands.
1577 vars |**Optional.** A dictionary containing custom attributes that are specific to this user.
1578 groups |**Optional.** An array of group names.
1579 enable_notifications|**Optional.** Whether notifications are enabled for this user.
1580 period |**Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default.
1581 types |**Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
1582 states |**Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
1586 Name | Type | Description
1587 --------------------------|---------------|-----------------
1588 last\_notification | Number | When the last notification was sent for this user (as a UNIX timestamp).
1590 ## UserGroup <a id="objecttype-usergroup"></a>
1596 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
1600 object UserGroup "icingaadmins" {
1601 display_name = "Icinga 2 Admin Group"
1604 Configuration Attributes:
1607 ----------------|----------------
1608 display_name |**Optional.** A short description of the user group.
1609 groups |**Optional.** An array of nested group names.
1612 ## Zone <a id="objecttype-zone"></a>
1614 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1618 object Zone "config-ha-master" {
1619 endpoints = [ "icinga2a", "icinga2b" ]
1623 object Zone "check-satellite" {
1624 endpoints = [ "icinga2c" ]
1625 parent = "config-ha-master"
1628 Configuration Attributes:
1631 ----------------|----------------
1632 endpoints |**Optional.** Array of endpoint names located in this zone.
1633 parent |**Optional.** The name of the parent zone.
1634 global |**Optional.** Whether configuration files for this zone should be synced to all endpoints. Defaults to false.
1636 Zone objects cannot currently be created with the API.
1638 # Value Types <a id="value-types"></a>
1640 In addition to [configuration objects](09-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).
1642 ## CheckResult <a id="value-types-checkresult"></a>
1644 Name | Type | Description
1645 --------------------------|---------------|-----------------
1646 exit_status | Number | The exit status returned by the check execution.
1647 output | String | The check output.
1648 performance_data | Array | Array of [performance data values](09-object-types.md#value-types-perfdatavalue).
1649 check_source | String | Name of the node executing the check.
1650 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1651 command | Value | Array of command with shell-escaped arguments or command line string.
1652 execution_start | Number | Check execution start time (as a UNIX timestamp).
1653 execution_end | Number | Check execution end time (as a UNIX timestamp).
1654 schedule_start | Number | Scheduled check execution start time (as a UNIX timestamp).
1655 schedule_end | Number | Scheduled check execution end time (as a UNIX timestamp).
1656 active | Boolean | Whether the result is from an active or passive check.
1657 vars_before | Dictionary | Internal attribute used for calculations.
1658 vars_after | Dictionary | Internal attribute used for calculations.
1660 ## PerfdataValue <a id="value-types-perfdatavalue"></a>
1662 Icinga 2 parses performance data strings returned by check plugins and makes the information available to external interfaces (e.g. [GraphiteWriter](09-object-types.md#objecttype-graphitewriter) or the [Icinga 2 API](12-icinga2-api.md#icinga2-api)).
1664 Name | Type | Description
1665 --------------------------|---------------|-----------------
1666 label | String | Performance data label.
1667 value | Number | Normalized performance data value without unit.
1668 counter | Boolean | Enabled if the original value contains `c` as unit. Defaults to `false`.
1669 unit | String | Unit of measurement (`seconds`, `bytes`. `percent`) according to the [plugin API](05-service-monitoring.md#service-monitoring-plugin-api).
1670 crit | Value | Critical threshold value.
1671 warn | Value | Warning threshold value.
1672 min | Value | Minimum value returned by the check.
1673 max | Value | Maximum value returned by the check.