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`.
558 enable_legacy_mode | **Optional.** Enable legacy mode for schema < 2.4. **Note**: This will be removed in 2.8.
560 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
564 ## Host <a id="objecttype-host"></a>
570 object Host NodeName {
571 display_name = "Local host on this node"
572 address = "127.0.0.1"
575 groups = [ "all-hosts" ]
577 check_command = "hostalive"
580 Configuration Attributes:
583 ----------------|----------------
584 display_name |**Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
585 address |**Optional.** The host's address. Available as command runtime macro `$address$` if set.
586 address6 |**Optional.** The host's address. Available as command runtime macro `$address6$` if set.
587 groups |**Optional.** A list of host groups this host belongs to.
588 vars |**Optional.** A dictionary containing custom attributes that are specific to this host.
589 check\_command |**Required.** The name of the check command.
590 max\_check\_attempts|**Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
591 check\_period |**Optional.** The name of a time period which determines when this host should be checked. Not set by default.
592 check\_timeout |**Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
593 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.
594 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.
595 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
596 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
597 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
598 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
599 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
600 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
601 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.
602 flapping\_threshold|**Optional.** The flapping threshold in percent when a host is considered to be flapping.
603 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
604 zone |**Optional.** The zone this object is a member of.
605 command\_endpoint|**Optional.** The endpoint where commands are executed on.
606 notes |**Optional.** Notes for the host.
607 notes\_url |**Optional.** Url for notes for the host (for example, in notification commands).
608 action\_url |**Optional.** Url for actions for the host (for example, an external graphing tool).
609 icon\_image |**Optional.** Icon image for the host. Used by external interfaces only.
610 icon\_image\_alt|**Optional.** Icon image description for the host. Used by external interface only.
612 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
613 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
617 > The `address` and `address6` attributes are required for running commands using
618 > the `$address$` and `$address6$` runtime macros.
622 Name | Type | Description
623 --------------------------|---------------|-----------------
624 next\_check | Number | When the next check occurs (as a UNIX timestamp).
625 last\_check | Number | When the last check occured (as a UNIX timestamp).
626 check\_attempt | Number | The current check attempt number.
627 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
628 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
629 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
630 last\_check\_result | CheckResult | The current check result.
631 last\_state\_change | Number | When the last state change occurred (as a UNIX timestamp).
632 last\_hard\_state\_change | Number | When the last hard state change occurred (as a UNIX timestamp).
633 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
634 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
635 acknowledgement_expiry | Number | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
636 downtime\_depth | Number | Whether the host has one or more active downtimes.
637 flapping_last_change | Number | When the last flapping change occurred (as a UNIX timestamp).
638 flapping | Boolean | Whether the host is flapping between states.
639 state | Number | The current state (0 = UP, 1 = DOWN).
640 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
641 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
642 last_state_up | Number | When the last UP state occurred (as a UNIX timestamp).
643 last_state_down | Number | When the last DOWN state occurred (as a UNIX timestamp).
647 ## HostGroup <a id="objecttype-hostgroup"></a>
653 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
657 object HostGroup "my-hosts" {
658 display_name = "My hosts"
661 Configuration Attributes:
664 ----------------|----------------
665 display_name |**Optional.** A short description of the host group.
666 groups |**Optional.** An array of nested group names.
668 ## IcingaApplication <a id="objecttype-icingaapplication"></a>
670 The IcingaApplication object is required to start Icinga 2.
671 The object name must be `app`. If the object configuration
672 is missing, Icinga 2 will automatically create an IcingaApplication
677 object IcingaApplication "app" {
678 enable_perfdata = false
681 Configuration Attributes:
684 ----------------------|--------------------------
685 enable_notifications |**Optional.** Whether notifications are globally enabled. Defaults to true.
686 enable_event_handlers |**Optional.** Whether event handlers are globally enabled. Defaults to true.
687 enable_flapping |**Optional.** Whether flap detection is globally enabled. Defaults to true.
688 enable_host_checks |**Optional.** Whether active host checks are globally enabled. Defaults to true.
689 enable_service_checks |**Optional.** Whether active service checks are globally enabled. Defaults to true.
690 enable_perfdata |**Optional.** Whether performance data processing is globally enabled. Defaults to true.
691 vars |**Optional.** A dictionary containing custom attributes that are available globally.
693 ## IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
695 IDO database adapter for MySQL.
699 library "db_ido_mysql"
701 object IdoMysqlConnection "mysql-ido" {
709 downtimehistory_age = 48h
710 contactnotifications_age = 31d
714 Configuration Attributes:
717 ----------------|----------------
718 host |**Optional.** MySQL database host address. Defaults to "localhost".
719 port |**Optional.** MySQL database port. Defaults to 3306.
720 socket_path |**Optional.** MySQL socket path.
721 user |**Optional.** MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
722 password |**Optional.** MySQL database user's password. Defaults to "icinga".
723 database |**Optional.** MySQL database name. Defaults to "icinga".
724 enable\_ssl |**Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
725 ssl\_key |**Optional.** MySQL SSL client key file path.
726 ssl\_cert |**Optional.** MySQL SSL certificate file path.
727 ssl\_ca |**Optional.** MySQL SSL certificate authority certificate file path.
728 ssl\_capath |**Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
729 ssl\_cipher |**Optional.** MySQL SSL list of allowed ciphers.
730 table\_prefix |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
731 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
732 instance\_description|**Optional.** Description for the Icinga 2 instance.
733 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".
734 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".
735 cleanup |**Optional.** Dictionary with items for historical table cleanup.
736 categories |**Optional.** Array of information types that should be written to the database.
741 ----------------|----------------
742 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
743 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
744 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
745 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
746 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
747 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
748 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
749 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
750 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
751 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
752 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
753 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
754 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
755 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
756 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
760 Name | Description | Required by
761 ---------------------|------------------------|--------------------
762 DbCatConfig | Configuration data | Icinga Web 2
763 DbCatState | Current state data | Icinga Web 2
764 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
765 DbCatComment | Comments | Icinga Web 2
766 DbCatDowntime | Downtimes | Icinga Web 2
767 DbCatEventHandler | Event handler data | Icinga Web 2
768 DbCatExternalCommand | External commands | --
769 DbCatFlapping | Flap detection data | Icinga Web 2
770 DbCatCheck | Check results | --
771 DbCatLog | Log messages | --
772 DbCatNotification | Notifications | Icinga Web 2
773 DbCatProgramStatus | Program status data | Icinga Web 2
774 DbCatRetention | Retention data | Icinga Web 2
775 DbCatStateHistory | Historical state data | Icinga Web 2
777 The default value for `categories` includes everything required
778 by Icinga Web 2 in the table above.
780 In addition to the category flags listed above the `DbCatEverything`
781 flag may be used as a shortcut for listing all flags.
783 ## IdoPgSqlConnection <a id="objecttype-idopgsqlconnection"></a>
785 IDO database adapter for PostgreSQL.
789 library "db_ido_pgsql"
791 object IdoPgsqlConnection "pgsql-ido" {
799 downtimehistory_age = 48h
800 contactnotifications_age = 31d
804 Configuration Attributes:
807 ----------------|----------------
808 host |**Optional.** PostgreSQL database host address. Defaults to "localhost".
809 port |**Optional.** PostgreSQL database port. Defaults to "5432".
810 user |**Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to "icinga".
811 password |**Optional.** PostgreSQL database user's password. Defaults to "icinga".
812 database |**Optional.** PostgreSQL database name. Defaults to "icinga".
813 table\_prefix |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_".
814 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
815 instance\_description|**Optional.** Description for the Icinga 2 instance.
816 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".
817 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".
818 cleanup |**Optional.** Dictionary with items for historical table cleanup.
819 categories |**Optional.** Array of information types that should be written to the database.
824 ----------------|----------------
825 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
826 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
827 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
828 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
829 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
830 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
831 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
832 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
833 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
834 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
835 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
836 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
837 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
838 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
839 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
843 Name | Description | Required by
844 ---------------------|------------------------|--------------------
845 DbCatConfig | Configuration data | Icinga Web 2
846 DbCatState | Current state data | Icinga Web 2
847 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
848 DbCatComment | Comments | Icinga Web 2
849 DbCatDowntime | Downtimes | Icinga Web 2
850 DbCatEventHandler | Event handler data | Icinga Web 2
851 DbCatExternalCommand | External commands | --
852 DbCatFlapping | Flap detection data | Icinga Web 2
853 DbCatCheck | Check results | --
854 DbCatLog | Log messages | --
855 DbCatNotification | Notifications | Icinga Web 2
856 DbCatProgramStatus | Program status data | Icinga Web 2
857 DbCatRetention | Retention data | Icinga Web 2
858 DbCatStateHistory | Historical state data | Icinga Web 2
860 The default value for `categories` includes everything required
861 by Icinga Web 2 in the table above.
863 In addition to the category flags listed above the `DbCatEverything`
864 flag may be used as a shortcut for listing all flags.
866 ## InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
868 Writes check result metrics and performance data to a defined InfluxDB host.
874 object InfluxdbWriter "influxdb" {
879 flush_threshold = 1024
883 measurement = "$host.check_command$"
885 hostname = "$host.name$"
889 measurement = "$service.check_command$"
891 hostname = "$host.name$"
892 service = "$service.name$"
897 Measurement names and tags are fully configurable by the end user. The InfluxdbWriter
898 object will automatically add a `metric` tag to each data point. This correlates to the
899 perfdata label. Fields (value, warn, crit, min, max) are created from data if available
900 and the configuration allows it. If a value associated with a tag is not able to be
901 resolved, it will be dropped and not sent to the target host.
903 Backslashes are allowed in tag keys, tag values and field keys, however they are also
904 escape characters when followed by a space or comma, but cannot be escaped themselves.
905 As a result all trailling slashes in these fields are replaced with an underscore. This
906 predominantly affects Windows paths e.g. `C:\` becomes `C:_`.
908 The database is assumed to exist so this object will make no attempt to create it currently.
910 Configuration Attributes:
913 -----------------------|---------------------------------------------------------------------------------------------------------
914 host | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
915 port | **Required.** InfluxDB HTTP port. Defaults to `8086`.
916 database | **Required.** InfluxDB database name. Defaults to `icinga2`.
917 username | **Optional.** InfluxDB user name. Defaults to `none`.
918 password | **Optional.** InfluxDB user password. Defaults to `none`.
919 ssl_enable | **Optional.** Whether to use a TLS stream. Defaults to `false`.
920 ssl_ca_cert | **Optional.** CA certificate to validate the remote host.
921 ssl_cert | **Optional.** Host certificate to present to the remote host for mutual verification.
922 ssl_key | **Optional.** Host key to accompany the ssl_cert
923 host_template | **Required.** Host template to define the InfluxDB line protocol.
924 service_template | **Required.** Service template to define the influxDB line protocol.
925 enable_send_thresholds | **Optional.** Whether to send warn, crit, min & max tagged data.
926 enable_send_metadata | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
927 flush_interval | **Optional.** How long to buffer data points before transfering to InfluxDB. Defaults to `10s`.
928 flush_threshold | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`.
929 socket_timeout | **Optional.** How long to wait for InfluxDB to respond. Defaults to `5s`.
931 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
932 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
935 ### Instance Tagging <a id="objecttype-influxdbwriter-instance-tags"></a>
937 Consider the following service check:
939 apply Service "disk" for (disk => attributes in host.vars.disks) {
940 import "generic-service"
941 check_command = "disk"
942 display_name = "Disk " + disk
943 vars.disk_partitions = disk
944 assign where host.vars.disks
947 This is a typical pattern for checking individual disks, NICs, SSL certificates etc associated
948 with a host. What would be useful is to have the data points tagged with the specific instance
949 for that check. This would allow you to query time series data for a check on a host and for a
950 specific instance e.g. /dev/sda. To do this quite simply add the instance to the service variables:
952 apply Service "disk" for (disk => attributes in host.vars.disks) {
958 Then modify your writer configuration to add this tag to your data points if the instance variable
959 is associated with the service:
961 object InfluxdbWriter "influxdb" {
964 measurement = "$service.check_command$"
966 hostname = "$host.name$"
967 service = "$service.name$"
968 instance = "$service.vars.instance$"
974 ## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
976 Livestatus API interface available as TCP or UNIX socket. Historical table queries
977 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
978 pointing to the log files using the `compat_log_path` configuration attribute.
984 object LivestatusListener "livestatus-tcp" {
986 bind_host = "127.0.0.1"
990 object LivestatusListener "livestatus-unix" {
992 socket_path = "/var/run/icinga2/cmd/livestatus"
995 Configuration Attributes:
998 ----------------|----------------
999 socket\_type |**Optional.** Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
1000 bind\_host |**Optional.** Only valid when socket\_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
1001 bind\_port |**Optional.** Only valid when `socket_type` is "tcp". Port to listen on for connections. Defaults to 6558.
1002 socket\_path |**Optional.** Only valid when `socket_type` is "unix". Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus".
1003 compat\_log\_path |**Optional.** Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"
1007 > UNIX sockets are not supported on Windows.
1010 ## Notification <a id="objecttype-notification"></a>
1012 Notification objects are used to specify how users should be notified in case
1013 of host and service state changes and other events.
1017 > Rather than creating a `Notification` object for a specific host or service it is
1018 > usually easier to just create a `Notification` template and use the `apply` keyword
1019 > to assign the notification to a number of hosts or services. Use the `to` keyword
1020 > to set the specific target type for `Host` or `Service`.
1021 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
1025 object Notification "localhost-ping-notification" {
1026 host_name = "localhost"
1027 service_name = "ping4"
1029 command = "mail-notification"
1031 users = [ "user1", "user2" ]
1033 types = [ Problem, Recovery ]
1036 Configuration Attributes:
1039 --------------------------|----------------
1040 host_name | **Required.** The name of the host this notification belongs to.
1041 service_name | **Optional.** The short name of the service this notification belongs to. If omitted, this notification object is treated as host notification.
1042 vars | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
1043 users | **Optional.** A list of user names who should be notified.
1044 user_groups | **Optional.** A list of user group names who should be notified.
1045 times | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
1046 command | **Required.** The name of the notification command which should be executed when the notification is triggered.
1047 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.
1048 period | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
1049 zone |**Optional.** The zone this object is a member of.
1050 types | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
1051 states | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
1053 Available notification state filters for Service:
1060 Available notification state filters for Host:
1065 Available notification type filters:
1079 Name | Type | Description
1080 --------------------------|---------------|-----------------
1081 last\_notification | Number | When the last notification was sent for this Notification object (as a UNIX timestamp).
1082 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).
1083 notification\_number | Number | The notification number
1084 last\_problem\_notification | Number | When the last notification was sent for a problem (as a UNIX timestamp).
1087 ## NotificationCommand <a id="objecttype-notificationcommand"></a>
1089 A notification command definition.
1093 > Icinga 2 versions < 2.6.0 require the import of the [plugin-notification-command](10-icinga-template-library.md#itl-plugin-notification-command) template.
1097 object NotificationCommand "mail-service-notification" {
1098 command = [ SysconfDir + "/icinga2/scripts/mail-service-notification.sh" ]
1103 value = "$notification_address$"
1105 "-6" = "$notification_address6$"
1106 "-b" = "$notification_author$"
1107 "-c" = "$notification_comment$"
1110 value = "$notification_date$"
1114 value = "$notification_servicename$"
1117 value = "$notification_from$"
1118 description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
1120 "-i" = "$notification_icingaweb2url$"
1123 value = "$notification_hostname$"
1127 value = "$notification_hostdisplayname$"
1131 value = "$notification_serviceoutput$"
1135 value = "$notification_useremail$"
1139 value = "$notification_servicestate$"
1143 value = "$notification_type$"
1147 value = "$notification_servicedisplayname$"
1149 "-v" = "$notification_logtosyslog$"
1153 notification_address = "$address$"
1154 notification_address6 = "$address6$"
1155 notification_author = "$notification.author$"
1156 notification_comment = "$notification.comment$"
1157 notification_type = "$notification.type$"
1158 notification_date = "$icinga.long_date_time$"
1159 notification_hostname = "$host.name$"
1160 notification_hostdisplayname = "$host.display_name$"
1161 notification_servicename = "$service.name$"
1162 notification_serviceoutput = "$service.output$"
1163 notification_servicestate = "$service.state$"
1164 notification_useremail = "$user.email$"
1165 notification_servicedisplayname = "$service.display_name$"
1170 Configuration Attributes:
1173 ----------------|----------------
1174 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.
1175 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.
1176 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1177 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
1178 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
1179 arguments |**Optional.** A dictionary of command arguments.
1181 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
1183 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
1185 ## NotificationComponent <a id="objecttype-notificationcomponent"></a>
1187 The notification component is responsible for sending notifications. There are no configurable options.
1191 library "notification"
1193 object NotificationComponent "notification" { }
1195 Configuration Attributes:
1198 ----------------|----------------
1199 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".
1201 ## OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1203 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1209 object OpenTsdbWriter "opentsdb" {
1214 Configuration Attributes:
1217 ----------------------|----------------------
1218 host |**Optional.** OpenTSDB host address. Defaults to '127.0.0.1'.
1219 port |**Optional.** OpenTSDB port. Defaults to 4242.
1222 ## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1224 Writes check result performance data to a defined path using macro
1225 pattern consisting of custom attributes and runtime macros.
1231 object PerfdataWriter "pnp" {
1232 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1234 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1236 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$"
1237 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$"
1239 rotation_interval = 15s
1242 Configuration Attributes:
1245 ------------------------|----------------
1246 host_perfdata\_path |**Optional.** Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
1247 service_perfdata\_path |**Optional.** Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
1248 host_temp\_path |**Optional.** Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
1249 service_temp\_path |**Optional.** Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
1250 host_format\_template |**Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1251 service_format\_template|**Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1252 rotation\_interval |**Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to 30 seconds.
1254 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1255 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1258 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
1260 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1264 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1265 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1266 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1267 > type for `Host` or `Service`.
1268 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
1272 object ScheduledDowntime "some-downtime" {
1273 host_name = "localhost"
1274 service_name = "ping4"
1276 author = "icingaadmin"
1277 comment = "Some comment"
1283 "sunday" = "02:00-03:00"
1287 Configuration Attributes:
1290 ----------------|----------------
1291 host_name |**Required.** The name of the host this scheduled downtime belongs to.
1292 service_name |**Optional.** The short name of the service this scheduled downtime belongs to. If omitted, this downtime object is treated as host downtime.
1293 author |**Required.** The author of the downtime.
1294 comment |**Required.** A comment for the downtime.
1295 fixed |**Optional.** Whether this is a fixed downtime. Defaults to true.
1296 duration |**Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1297 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1299 ScheduledDowntime objects have composite names, i.e. their names are based
1300 on the `host_name` and `service_name` attributes and the
1301 name you specified. This means you can define more than one object
1302 with the same (short) name as long as one of the `host_name` and
1303 `service_name` attributes has a different value.
1306 ## Service <a id="objecttype-service"></a>
1308 Service objects describe network services and how they should be checked
1313 > Rather than creating a `Service` object for a specific host it is usually easier
1314 > to just create a `Service` template and use the `apply` keyword to assign the
1315 > service to a number of hosts.
1316 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
1320 object Service "uptime" {
1321 host_name = "localhost"
1323 display_name = "localhost Uptime"
1325 check_command = "check_snmp"
1327 vars.community = "public"
1328 vars.oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1330 check_interval = 60s
1331 retry_interval = 15s
1333 groups = [ "all-services", "snmp" ]
1336 Configuration Attributes:
1339 ----------------|----------------
1340 display_name |**Optional.** A short description of the service.
1341 host_name |**Required.** The host this service belongs to. There must be a `Host` object with that name.
1342 name |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
1343 groups |**Optional.** The service groups this service belongs to.
1344 vars |**Optional.** A dictionary containing custom attributes that are specific to this service.
1345 check\_command |**Required.** The name of the check command.
1346 max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1347 check\_period |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1348 check\_timeout |**Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
1349 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.
1350 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.
1351 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
1352 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
1353 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
1354 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
1355 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
1356 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
1357 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.
1358 flapping\_threshold|**Optional.** The flapping threshold in percent when a service is considered to be flapping.
1359 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
1360 zone |**Optional.** The zone this object is a member of.
1361 command\_endpoint|**Optional.** The endpoint where commands are executed on.
1362 notes |**Optional.** Notes for the service.
1363 notes\_url |**Optional.** Url for notes for the service (for example, in notification commands).
1364 action_url |**Optional.** Url for actions for the service (for example, an external graphing tool).
1365 icon\_image |**Optional.** Icon image for the service. Used by external interfaces only.
1366 icon\_image\_alt|**Optional.** Icon image description for the service. Used by external interface only.
1368 Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
1369 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1371 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
1372 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
1376 Name | Type | Description
1377 --------------------------|---------------|-----------------
1378 next\_check | Number | When the next check occurs (as a UNIX timestamp).
1379 last\_check | Number | When the last check occured (as a UNIX timestamp).
1380 check\_attempt | Number | The current check attempt number.
1381 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1382 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1383 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1384 last\_check\_result | CheckResult | The current check result.
1385 last\_state\_change | Number | When the last state change occurred (as a UNIX timestamp).
1386 last\_hard\_state\_change | Number | When the last hard state change occurred (as a UNIX timestamp).
1387 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1388 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1389 acknowledgement_expiry | Number | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1390 downtime\_depth | Number | Whether the service has one or more active downtimes.
1391 flapping_last_change | Number | When the last flapping change occurred (as a UNIX timestamp).
1392 flapping | Boolean | Whether the host is flapping between states.
1393 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1394 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1395 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1396 last_state_ok | Number | When the last OK state occurred (as a UNIX timestamp).
1397 last_state_warning | Number | When the last WARNING state occurred (as a UNIX timestamp).
1398 last_state_critical | Number | When the last CRITICAL state occurred (as a UNIX timestamp).
1399 last_state_unknown | Number | When the last UNKNOWN state occurred (as a UNIX timestamp).
1402 ## ServiceGroup <a id="objecttype-servicegroup"></a>
1404 A group of services.
1408 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
1412 object ServiceGroup "snmp" {
1413 display_name = "SNMP services"
1416 Configuration Attributes:
1419 ----------------|----------------
1420 display_name |**Optional.** A short description of the service group.
1421 groups |**Optional.** An array of nested group names.
1424 ## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1426 Periodically writes status data files which are used by the Classic UI and other third-party tools.
1432 object StatusDataWriter "status" {
1433 status_path = "/var/cache/icinga2/status.dat"
1434 objects_path = "/var/cache/icinga2/objects.cache"
1435 update_interval = 30s
1438 Configuration Attributes:
1441 ----------------|----------------
1442 status\_path |**Optional.** Path to the status.dat file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
1443 objects\_path |**Optional.** Path to the objects.cache file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
1444 update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
1447 ## SyslogLogger <a id="objecttype-sysloglogger"></a>
1449 Specifies Icinga 2 logging to syslog.
1453 object SyslogLogger "crit-syslog" {
1454 severity = "critical"
1457 Configuration Attributes:
1460 ----------------|----------------
1461 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1464 ## TimePeriod <a id="objecttype-timeperiod"></a>
1466 Time periods can be used to specify when hosts/services should be checked or to limit
1467 when notifications should be sent out.
1471 object TimePeriod "nonworkhours" {
1472 import "legacy-timeperiod"
1474 display_name = "Icinga 2 TimePeriod for non working hours"
1477 monday = "00:00-8:00,17:00-24:00"
1478 tuesday = "00:00-8:00,17:00-24:00"
1479 wednesday = "00:00-8:00,17:00-24:00"
1480 thursday = "00:00-8:00,17:00-24:00"
1481 friday = "00:00-8:00,16:00-24:00"
1482 saturday = "00:00-24:00"
1483 sunday = "00:00-24:00"
1487 object TimePeriod "exampledays" {
1488 import "legacy-timeperiod"
1490 display_name = "Icinga 2 TimePeriod for random example days"
1493 //We still believe in Santa, no peeking!
1494 //Applies every 25th of December every year
1495 "december 25" = "00:00-24:00"
1497 //Any point in time can be specified,
1498 //but you still have to use a range
1499 "2038-01-19" = "03:13-03:15"
1501 //Evey 3rd day from the second monday of February
1502 //to 8th of November
1503 "monday 2 february - november 8 / 3" = "00:00-24:00"
1508 Additional examples can be found [here](08-advanced-topics.md#timeperiods).
1510 Configuration Attributes:
1513 ----------------|----------------
1514 display_name |**Optional.** A short description of the time period.
1515 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.
1516 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1517 prefer_includes |**Optional.** Boolean whether to prefer timeperiods `includes` or `excludes`. Default to true.
1518 excludes |**Optional.** An array of timeperiods, which should exclude from your timerange.
1519 includes |**Optional.** An array of timeperiods, which should include into your timerange
1521 The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define
1522 timeperiods including this one.
1526 Name | Type | Description
1527 --------------------------|---------------|-----------------
1528 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1531 ## User <a id="objecttype-user"></a>
1537 object User "icingaadmin" {
1538 display_name = "Icinga 2 Admin"
1539 groups = [ "icingaadmins" ]
1540 email = "icinga@localhost"
1541 pager = "icingaadmin@localhost.localdomain"
1545 states = [ OK, Warning, Critical, Unknown ]
1546 types = [ Problem, Recovery ]
1548 vars.additional_notes = "This is the Icinga 2 Admin account."
1551 Available notification state filters:
1560 Available notification type filters:
1572 Configuration Attributes:
1575 ----------------|----------------
1576 display_name |**Optional.** A short description of the user.
1577 email |**Optional.** An email string for this user. Useful for notification commands.
1578 pager |**Optional.** A pager string for this user. Useful for notification commands.
1579 vars |**Optional.** A dictionary containing custom attributes that are specific to this user.
1580 groups |**Optional.** An array of group names.
1581 enable_notifications|**Optional.** Whether notifications are enabled for this user.
1582 period |**Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default.
1583 types |**Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
1584 states |**Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
1588 Name | Type | Description
1589 --------------------------|---------------|-----------------
1590 last\_notification | Number | When the last notification was sent for this user (as a UNIX timestamp).
1592 ## UserGroup <a id="objecttype-usergroup"></a>
1598 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
1602 object UserGroup "icingaadmins" {
1603 display_name = "Icinga 2 Admin Group"
1606 Configuration Attributes:
1609 ----------------|----------------
1610 display_name |**Optional.** A short description of the user group.
1611 groups |**Optional.** An array of nested group names.
1614 ## Zone <a id="objecttype-zone"></a>
1616 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1620 object Zone "config-ha-master" {
1621 endpoints = [ "icinga2a", "icinga2b" ]
1625 object Zone "check-satellite" {
1626 endpoints = [ "icinga2c" ]
1627 parent = "config-ha-master"
1630 Configuration Attributes:
1633 ----------------|----------------
1634 endpoints |**Optional.** Array of endpoint names located in this zone.
1635 parent |**Optional.** The name of the parent zone.
1636 global |**Optional.** Whether configuration files for this zone should be synced to all endpoints. Defaults to false.
1638 Zone objects cannot currently be created with the API.
1640 # Value Types <a id="value-types"></a>
1642 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).
1644 ## CheckResult <a id="value-types-checkresult"></a>
1646 Name | Type | Description
1647 --------------------------|---------------|-----------------
1648 exit_status | Number | The exit status returned by the check execution.
1649 output | String | The check output.
1650 performance_data | Array | Array of [performance data values](09-object-types.md#value-types-perfdatavalue).
1651 check_source | String | Name of the node executing the check.
1652 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1653 command | Value | Array of command with shell-escaped arguments or command line string.
1654 execution_start | Number | Check execution start time (as a UNIX timestamp).
1655 execution_end | Number | Check execution end time (as a UNIX timestamp).
1656 schedule_start | Number | Scheduled check execution start time (as a UNIX timestamp).
1657 schedule_end | Number | Scheduled check execution end time (as a UNIX timestamp).
1658 active | Boolean | Whether the result is from an active or passive check.
1659 vars_before | Dictionary | Internal attribute used for calculations.
1660 vars_after | Dictionary | Internal attribute used for calculations.
1662 ## PerfdataValue <a id="value-types-perfdatavalue"></a>
1664 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)).
1666 Name | Type | Description
1667 --------------------------|---------------|-----------------
1668 label | String | Performance data label.
1669 value | Number | Normalized performance data value without unit.
1670 counter | Boolean | Enabled if the original value contains `c` as unit. Defaults to `false`.
1671 unit | String | Unit of measurement (`seconds`, `bytes`. `percent`) according to the [plugin API](05-service-monitoring.md#service-monitoring-plugin-api).
1672 crit | Value | Critical threshold value.
1673 warn | Value | Warning threshold value.
1674 min | Value | Minimum value returned by the check.
1675 max | Value | Maximum value returned by the check.