1 # <a id="object-types"></a> Object Types
3 This chapter provides an overview of all available 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 ## <a id="objecttype-apilistener"></a> ApiListener
11 ApiListener objects are used for distributed monitoring setups
12 specifying the certificate files used for ssl authorization.
14 The `NodeName` constant must be defined in [constants.conf](5-configuring-icinga-2.md#constants-conf).
18 object ApiListener "api" {
19 cert_path = SysconfDir + "/icinga2/pki/" + NodeName + ".crt"
20 key_path = SysconfDir + "/icinga2/pki/" + NodeName + ".key"
21 ca_path = SysconfDir + "/icinga2/pki/ca.crt"
25 Configuration Attributes:
28 --------------------------|--------------------------
29 cert\_path |**Required.** Path to the public key.
30 key\_path |**Required.** Path to the private key.
31 ca\_path |**Required.** Path to the CA certificate file.
32 crl\_path |**Optional.** Path to the CRL file.
33 bind\_host |**Optional.** The IP address the api listener should be bound to. Defaults to `0.0.0.0`.
34 bind\_port |**Optional.** The port the api listener should be bound to. Defaults to `5665`.
35 accept\_config |**Optional.** Accept zone configuration. Defaults to `false`.
36 accept\_commands |**Optional.** Accept remote commands. Defaults to `false`.
38 ## <a id="objecttype-checkcommand"></a> CheckCommand
40 A check command definition. Additional default command custom attributes can be
45 object CheckCommand "check_http" {
46 import "plugin-check-command"
48 command = [ PluginDir + "/check_http" ]
52 "-I" = "$http_address$"
62 value = "$http_auth_pair$"
63 description = "Username:password on sites with basic authentication"
66 set_if = "$http_ignore_body$"
68 "-r" = "$http_expect_body_regex$"
69 "-w" = "$http_warn_time$"
70 "-c" = "$http_critical_time$"
71 "-e" = "$http_expect$"
74 vars.http_address = "$address$"
80 Configuration Attributes:
83 ----------------|----------------
84 execute |**Required.** The "execute" script method takes care of executing the check. In virtually all cases you should import the "plugin-check-command" template to take care of this setting.
85 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.
86 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
87 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
88 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
89 zone |**Optional.** The zone this object is a member of.
90 arguments |**Optional.** A dictionary of command arguments.
93 ### <a id="objecttype-checkcommand-arguments"></a> CheckCommand Arguments
95 Command arguments can be defined as key-value-pairs in the `arguments`
96 dictionary. If the argument requires additional configuration for example
97 a `description` attribute or an optional condition, the value can be defined
98 as dictionary specifying additional options.
102 vars.x_val = "My command argument value."
110 key = "-Xnew" /* optional, set a new key identifier */
111 description = "My plugin requires this argument for doing X."
112 required = false /* optional, no error if not set */
113 skip_key = false /* always use "-X <value>" */
114 set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
115 order = -1 /* first position */
116 repeat_key = true /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
120 description = "My plugin requires this argument for doing Y."
121 required = false /* optional, no error if not set */
122 skip_key = true /* don't prefix "-Y" only use "<value>" */
123 set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
124 order = 0 /* second position */
125 repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
130 ------------|--------------
131 value | Optional argument value set by a macro string or a function call.
132 key | Optional argument key overriding the key identifier.
133 description | Optional argument description.
134 required | Required argument. Execution error if not set. Defaults to false (optional).
135 skip_key | Use the value as argument and skip the key.
136 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.
137 order | Set if multiple arguments require a defined argument order.
138 repeat_key | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
142 `..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...`
144 Argument array `repeat_key = true`:
146 `'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'`
148 Argument array `repeat_key = false`:
150 `'key' 'value[0]' 'value[1]' 'value[2]'`
152 ## <a id="objecttype-checkcomponent"></a> CheckerComponent
154 The checker component is responsible for scheduling active checks. There are no configurable options.
160 object CheckerComponent "checker" { }
162 ## <a id="objecttype-checkresultreader"></a> CheckResultReader
164 Reads Icinga 1.x check results from a directory. This functionality is provided
165 to help existing Icinga 1.x users and might be useful for certain cluster
172 object CheckResultReader "reader" {
173 spool_dir = "/data/check-results"
176 Configuration Attributes:
179 ----------------|----------------
180 spool\_dir |**Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/".
183 ## <a id="objecttype-compatlogger"></a> CompatLogger
185 Writes log files in a format that's compatible with Icinga 1.x.
191 object CompatLogger "my-log" {
192 log_dir = "/var/log/icinga2/compat"
193 rotation_method = "HOURLY"
196 Configuration Attributes:
199 ----------------|----------------
200 log\_dir |**Optional.** Path to the compat log directory. Defaults to LocalStateDir + "/log/icinga2/compat".
201 rotation\_method|**Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
205 ## <a id="objecttype-dependency"></a> Dependency
207 Dependency objects are used to specify dependencies between hosts and services. Dependencies
208 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
213 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
214 > to just create a `Dependency` template and use the `apply` keyword to assign the
215 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
216 > type for `Host` or `Service`.
217 > Check the [dependencies](3-monitoring-basics.md#dependencies) chapter for detailed examples.
219 Service-to-Service Example:
221 object Dependency "webserver-internet" {
222 parent_host_name = "internet"
223 parent_service_name = "ping4"
225 child_host_name = "webserver"
226 child_service_name = "ping4"
228 states = [ OK, Warning ]
230 disable_checks = true
233 Host-to-Host Example:
235 object Dependency "webserver-internet" {
236 parent_host_name = "internet"
238 child_host_name = "webserver"
242 disable_checks = true
245 Configuration Attributes:
248 ----------------------|----------------
249 parent_host_name |**Required.** The parent host.
250 parent_service_name |**Optional.** The parent service. If omitted this dependency object is treated as host dependency.
251 child_host_name |**Required.** The child host.
252 child_service_name |**Optional.** The child service. If omitted this dependency object is treated as host dependency.
253 disable_checks |**Optional.** Whether to disable checks when this dependency fails. Defaults to false.
254 disable_notifications |**Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
255 ignore_soft_states |**Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
256 period |**Optional.** Time period during which this dependency is enabled.
257 zone |**Optional.** The zone this object is a member of.
258 states |**Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
260 Available state filters:
269 When using [apply rules](3-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
270 automatically determined by Icinga 2.
272 Service-to-Host Dependency Example:
274 apply Dependency "internet" to Service {
275 parent_host_name = "dsl-router"
276 disable_checks = true
278 assign where host.name != "dsl-router"
281 This example sets all service objects matching the assign condition into a dependency relation to
282 the parent host object `dsl-router` as implicit child services.
284 Service-to-Service-on-the-same-Host Dependency Example:
286 apply Dependency "disable-nrpe-checks" to Service {
287 parent_service_name = "nrpe-health"
289 assign where service.check_command == "nrpe"
290 ignore where service.name == "nrpe-health"
293 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
294 host object matched by the apply rule condition. All services where apply matches are made implicit child services
295 in this dependency relation.
298 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
299 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
300 `child_service_name` attributes has a different value.
303 ## <a id="objecttype-endpoint"></a> Endpoint
305 Endpoint objects are used to specify connection information for remote
310 object Endpoint "icinga2b" {
311 host = "192.168.5.46"
315 Configuration Attributes:
318 ----------------|----------------
319 host |**Optional.** The hostname/IP address of the remote Icinga 2 instance.
320 port |**Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
321 log_duration |**Optional.** Duration for keeping replay logs on connection loss. Defaults to `1d`.
324 ## <a id="objecttype-zone"></a> Zone
326 Zone objects are used to specify which Icinga 2 instances are located in a zone.
330 object Zone "config-ha-master" {
331 endpoints = [ "icinga2a", "icinga2b" ]
335 object Zone "check-satellite" {
336 endpoints = [ "icinga2c" ]
337 parent = "config-ha-master"
340 Configuration Attributes:
343 ----------------|----------------
344 endpoints |**Optional.** Dictionary with endpoints located in this zone.
345 parent |**Optional.** The name of the parent zone.
346 global |**Optional.** Whether configuration files for this zone should be synced to all endpoints. Defaults to false.
349 ## <a id="objecttype-eventcommand"></a> EventCommand
351 An event command definition.
355 object EventCommand "restart-httpd-event" {
356 import "plugin-event-command"
358 command = "/opt/bin/restart-httpd.sh"
362 Configuration Attributes:
365 ----------------|----------------
366 execute |**Required.** The "execute" script method takes care of executing the event handler. In virtually all cases you should import the "plugin-event-command" template to take care of this setting.
367 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.
368 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
369 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
370 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
371 arguments |**Optional.** A dictionary of command arguments.
373 Command arguments can be used the same way as for [CheckCommand objects](6-object-types.md#objecttype-checkcommand-arguments).
376 ## <a id="objecttype-externalcommandlistener"></a> ExternalCommandListener
378 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
384 object ExternalCommandListener "external" {
385 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
388 Configuration Attributes:
391 ----------------|----------------
392 command\_path |**Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
396 ## <a id="objecttype-filelogger"></a> FileLogger
398 Specifies Icinga 2 logging to a file.
402 object FileLogger "debug-file" {
404 path = "/var/log/icinga2/debug.log"
407 Configuration Attributes:
410 ----------------|----------------
411 path |**Required.** The log path.
412 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
415 ## <a id="objecttype-gelfwriter"></a> GelfWriter
417 Writes event log entries to a defined GELF receiver host (Graylog2, Logstash).
423 object GelfWriter "gelf" {
428 Configuration Attributes:
431 ----------------------|----------------------
432 host |**Optional.** GELF receiver host address. Defaults to '127.0.0.1'.
433 port |**Optional.** GELF receiver port. Defaults to `12201`.
434 source |**Optional.** Source name for this instance. Defaults to `icinga2`.
437 ## <a id="objecttype-graphitewriter"></a> GraphiteWriter
439 Writes check result metrics and performance data to a defined
440 Graphite Carbon host.
446 object GraphiteWriter "graphite" {
451 Configuration Attributes:
454 ----------------------|----------------------
455 host |**Optional.** Graphite Carbon host address. Defaults to '127.0.0.1'.
456 port |**Optional.** Graphite Carbon port. Defaults to 2003.
457 host_name_template |**Optional.** Metric prefix for host name. Defaults to "icinga.$host.name$".
458 service_name_template |**Optional.** Metric prefix for service name. Defaults to "icinga.$host.name$.$service.name$".
460 Metric prefix names can be modified using [runtime macros](3-monitoring-basics.md#runtime-macros).
462 Example with your custom [global constant](19-language-reference.md#constants) `GraphiteEnv`:
464 const GraphiteEnv = "icinga.env1"
466 host_name_template = GraphiteEnv + ".$host.name$"
467 service_name_template = GraphiteEnv + ".$host.name$.$service.name$"
471 ## <a id="objecttype-host"></a> Host
477 object Host NodeName {
478 display_name = "Local host on this node"
479 address = "127.0.0.1"
482 groups = [ "all-hosts" ]
484 check_command = "hostalive"
487 Configuration Attributes:
490 ----------------|----------------
491 display_name |**Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
492 address |**Optional.** The host's address. Available as command runtime macro `$address$` if set.
493 address6 |**Optional.** The host's address. Available as command runtime macro `$address6$` if set.
494 groups |**Optional.** A list of host groups this host belongs to.
495 vars |**Optional.** A dictionary containing custom attributes that are specific to this host.
496 check\_command |**Required.** The name of the check command.
497 max\_check\_attempts|**Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
498 check\_period |**Optional.** The name of a time period which determines when this host should be checked. Not set by default.
499 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.
500 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.
501 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
502 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
503 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
504 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
505 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
506 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
507 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.
508 flapping\_threshold|**Optional.** The flapping threshold in percent when a host is considered to be flapping.
509 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
510 zone |**Optional.** The zone this object is a member of.
511 command\_endpoint|**Optional.** The endpoint where commands are executed on.
512 notes |**Optional.** Notes for the host.
513 notes\_url |**Optional.** Url for notes for the host (for example, in notification commands).
514 action\_url |**Optional.** Url for actions for the host (for example, an external graphing tool).
515 icon\_image |**Optional.** Icon image for the host. Used by external interfaces only.
516 icon\_image\_alt|**Optional.** Icon image description for the host. Used by external interface only.
520 > The `address` and `address6` attributes are required for running commands using
521 > the `$address$` and `$address6$` runtime macros.
525 Name | Type | Description
526 --------------------------|---------------|-----------------
527 next\_check | Number | When the next check occurs (as a UNIX timestamp).
528 check\_attempt | Number | The current check attempt number.
529 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
530 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
531 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
532 last\_check\_result | CheckResult | The current check result.
533 last\_state\_change | Number | When the last state change occurred (as a UNIX timestamp).
534 last\_hard\_state\_change | Number | When the last hard state change occurred (as a UNIX timestamp).
535 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
536 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
537 acknowledgement_expiry | Number | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
538 comments | Dictionary | The comments for this host.
539 downtimes | Dictionary | The downtimes for this host.
540 state | Number | The current state (0 = UP, 1 = DOWN).
541 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
542 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
546 ## <a id="objecttype-hostgroup"></a> HostGroup
552 > Assign host group members using the [group assign](19-language-reference.md#group-assign) rules.
556 object HostGroup "my-hosts" {
557 display_name = "My hosts"
560 Configuration Attributes:
563 ----------------|----------------
564 display_name |**Optional.** A short description of the host group.
565 groups |**Optional.** An array of nested group names.
568 ## <a id="objecttype-icingastatuswriter"></a> IcingaStatusWriter
570 The IcingaStatusWriter feature periodically dumps the current status
571 and performance data from Icinga 2 and all registered features into
576 object IcingaStatusWriter "status" {
577 status_path = LocalStateDir + "/cache/icinga2/status.json"
578 update_interval = 15s
581 Configuration Attributes:
584 --------------------------|--------------------------
585 status\_path |**Optional.** Path to cluster status file. Defaults to LocalStateDir + "/cache/icinga2/status.json"
586 update\_interval |**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
589 ## <a id="objecttype-idomysqlconnection"></a> IdoMySqlConnection
591 IDO database adapter for MySQL.
595 library "db_ido_mysql"
597 object IdoMysqlConnection "mysql-ido" {
603 table_prefix = "icinga_"
604 instance_name = "icinga2"
605 instance_description = "icinga2 instance"
608 downtimehistory_age = 48h
612 categories = DbCatConfig | DbCatState
615 Configuration Attributes:
618 ----------------|----------------
619 host |**Optional.** MySQL database host address. Defaults to "localhost".
620 port |**Optional.** MySQL database port. Defaults to 3306.
621 socket_path |**Optional.** MySQL socket path.
622 user |**Optional.** MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
623 password |**Optional.** MySQL database user's password. Defaults to "icinga".
624 database |**Optional.** MySQL database name. Defaults to "icinga".
625 table\_prefix |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
626 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
627 instance\_description|**Optional.** Description for the Icinga 2 instance.
628 enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](12-distributed-monitoring-ha.md#high-availability-db-ido). Defaults to "true".
629 failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](12-distributed-monitoring-ha.md#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
630 cleanup |**Optional.** Dictionary with items for historical table cleanup.
631 categories |**Optional.** The types of information that should be written to the database.
636 ----------------|----------------
637 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
638 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
639 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
640 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
641 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
642 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
643 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
644 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
645 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
646 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
647 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
648 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
649 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
650 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
651 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
655 Name | Description | Required by
656 ---------------------|------------------------|--------------------
657 DbCatConfig | Configuration data | Icinga Web/Reporting
658 DbCatState | Current state data | Icinga Web/Reporting
659 DbCatAcknowledgement | Acknowledgements | Icinga Web/Reporting
660 DbCatComment | Comments | Icinga Web/Reporting
661 DbCatDowntime | Downtimes | Icinga Web/Reporting
662 DbCatEventHandler | Event handler data | Icinga Web/Reporting
663 DbCatExternalCommand | External commands | Icinga Web/Reporting
664 DbCatFlapping | Flap detection data | Icinga Web/Reporting
665 DbCatCheck | Check results | --
666 DbCatLog | Log messages | Icinga Web/Reporting
667 DbCatNotification | Notifications | Icinga Web/Reporting
668 DbCatProgramStatus | Program status data | Icinga Web/Reporting
669 DbCatRetention | Retention data | Icinga Web/Reporting
670 DbCatStateHistory | Historical state data | Icinga Web/Reporting
672 Multiple categories can be combined using the `|` operator. In addition to
673 the category flags listed above the `DbCatEverything` flag may be used as
674 a shortcut for listing all flags.
676 External interfaces like Icinga Web require everything except `DbCatCheck`
677 which is the default value if `categories` is not set.
679 ## <a id="objecttype-idopgsqlconnection"></a> IdoPgSqlConnection
681 IDO database adapter for PostgreSQL.
685 library "db_ido_pgsql"
687 object IdoMysqlConnection "pgsql-ido" {
693 table_prefix = "icinga_"
694 instance_name = "icinga2"
695 instance_description = "icinga2 instance"
698 downtimehistory_age = 48h
702 categories = DbCatConfig | DbCatState
705 Configuration Attributes:
708 ----------------|----------------
709 host |**Optional.** PostgreSQL database host address. Defaults to "localhost".
710 port |**Optional.** PostgreSQL database port. Defaults to "5432".
711 user |**Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to "icinga".
712 password |**Optional.** PostgreSQL database user's password. Defaults to "icinga".
713 database |**Optional.** PostgreSQL database name. Defaults to "icinga".
714 table\_prefix |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_".
715 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
716 instance\_description|**Optional.** Description for the Icinga 2 instance.
717 enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](12-distributed-monitoring-ha.md#high-availability-db-ido). Defaults to "true".
718 failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](12-distributed-monitoring-ha.md#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
719 cleanup |**Optional.** Dictionary with items for historical table cleanup.
720 categories |**Optional.** The types of information that should be written to the database.
725 ----------------|----------------
726 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
727 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
728 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
729 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
730 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
731 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
732 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
733 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
734 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
735 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
736 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
737 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
738 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
739 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
740 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
744 Name | Description | Required by
745 ---------------------|------------------------|--------------------
746 DbCatConfig | Configuration data | Icinga Web/Reporting
747 DbCatState | Current state data | Icinga Web/Reporting
748 DbCatAcknowledgement | Acknowledgements | Icinga Web/Reporting
749 DbCatComment | Comments | Icinga Web/Reporting
750 DbCatDowntime | Downtimes | Icinga Web/Reporting
751 DbCatEventHandler | Event handler data | Icinga Web/Reporting
752 DbCatExternalCommand | External commands | Icinga Web/Reporting
753 DbCatFlapping | Flap detection data | Icinga Web/Reporting
754 DbCatCheck | Check results | --
755 DbCatLog | Log messages | Icinga Web/Reporting
756 DbCatNotification | Notifications | Icinga Web/Reporting
757 DbCatProgramStatus | Program status data | Icinga Web/Reporting
758 DbCatRetention | Retention data | Icinga Web/Reporting
759 DbCatStateHistory | Historical state data | Icinga Web/Reporting
761 Multiple categories can be combined using the `|` operator. In addition to
762 the category flags listed above the `DbCatEverything` flag may be used as
763 a shortcut for listing all flags.
765 External interfaces like Icinga Web require everything except `DbCatCheck`
766 which is the default value if `categories` is not set.
768 ## <a id="objecttype-livestatuslistener"></a> LiveStatusListener
770 Livestatus API interface available as TCP or UNIX socket. Historical table queries
771 require the [CompatLogger](6-object-types.md#objecttype-compatlogger) feature enabled
772 pointing to the log files using the `compat_log_path` configuration attribute.
778 object LivestatusListener "livestatus-tcp" {
780 bind_host = "127.0.0.1"
784 object LivestatusListener "livestatus-unix" {
786 socket_path = "/var/run/icinga2/cmd/livestatus"
789 Configuration Attributes:
792 ----------------|----------------
793 socket\_type |**Optional.** Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
794 bind\_host |**Optional.** Only valid when socket\_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
795 bind\_port |**Optional.** Only valid when `socket_type` is "tcp". Port to listen on for connections. Defaults to 6558.
796 socket\_path |**Optional.** Only valid when `socket_type` is "unix". Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus".
797 compat\_log\_path |**Optional.** Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"
801 > UNIX sockets are not supported on Windows.
804 ## <a id="objecttype-notification"></a> Notification
806 Notification objects are used to specify how users should be notified in case
807 of host and service state changes and other events.
811 > Rather than creating a `Notification` object for a specific host or service it is
812 > usually easier to just create a `Notification` template and use the `apply` keyword
813 > to assign the notification to a number of hosts or services. Use the `to` keyword
814 > to set the specific target type for `Host` or `Service`.
815 > Check the [notifications](3-monitoring-basics.md#notifications) chapter for detailed examples.
819 object Notification "localhost-ping-notification" {
820 host_name = "localhost"
821 service_name = "ping4"
823 command = "mail-notification"
825 users = [ "user1", "user2" ]
827 types = [ Problem, Recovery ]
830 Configuration Attributes:
833 --------------------------|----------------
834 host_name | **Required.** The name of the host this notification belongs to.
835 service_name | **Optional.** The short name of the service this notification belongs to. If omitted this notification object is treated as host notification.
836 vars | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
837 users | **Optional.** A list of user names who should be notified.
838 user_groups | **Optional.** A list of user group names who should be notified.
839 times | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
840 command | **Required.** The name of the notification command which should be executed when the notification is triggered.
841 interval | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, [re-notifications](3-monitoring-basics.md#disable-renotification) are disabled.
842 period | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
843 zone |**Optional.** The zone this object is a member of.
844 types | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
845 states | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
847 Available notification state filters:
856 Available notification type filters:
870 Name | Type | Description
871 --------------------------|---------------|-----------------
872 last\_notification | Number | When the last notification was sent for this Notification object (as a UNIX timestamp).
873 next\_notifcation | 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).
874 notification\_number | Number | The notification number
875 last\_problem\_notification | Number | When the last notification was sent for a problem (as a UNIX timestamp).
878 ## <a id="objecttype-notificationcommand"></a> NotificationCommand
880 A notification command definition.
884 object NotificationCommand "mail-service-notification" {
885 import "plugin-notification-command"
888 SysconfDir + "/icinga2/scripts/mail-notification.sh"
892 NOTIFICATIONTYPE = "$notification.type$"
893 SERVICEDESC = "$service.name$"
894 HOSTALIAS = "$host.display_name$"
895 HOSTADDRESS = "$address$"
896 SERVICESTATE = "$service.state$"
897 LONGDATETIME = "$icinga.long_date_time$"
898 SERVICEOUTPUT = "$service.output$"
899 NOTIFICATIONAUTHORNAME = "$notification.author$"
900 NOTIFICATIONCOMMENT = "$notification.comment$"
901 HOSTDISPLAYNAME = "$host.display_name$"
902 SERVICEDISPLAYNAME = "$service.display_name$"
903 USEREMAIL = "$user.email$"
907 Configuration Attributes:
910 ----------------|----------------
911 execute |**Required.** The "execute" script method takes care of executing the notification. In virtually all cases you should import the "plugin-notification-command" template to take care of this setting.
912 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.
913 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
914 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
915 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
916 zone |**Optional.** The zone this object is a member of.
917 arguments |**Optional.** A dictionary of command arguments.
919 Command arguments can be used the same way as for [CheckCommand objects](6-object-types.md#objecttype-checkcommand-arguments).
922 ## <a id="objecttype-notificationcomponent"></a> NotificationComponent
924 The notification component is responsible for sending notifications. There are no configurable options.
928 library "notification"
930 object NotificationComponent "notification" { }
932 Configuration Attributes:
935 ----------------|----------------
936 enable\_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](12-distributed-monitoring-ha.md#high-availability-notifications). Defaults to "true".
938 ## <a id="objecttype-opentsdbwriter"></a> OpenTsdbWriter
940 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
946 object OpenTsdbWriter "opentsdb" {
951 Configuration Attributes:
954 ----------------------|----------------------
955 host |**Optional.** OpenTSDB host address. Defaults to '127.0.0.1'.
956 port |**Optional.** OpenTSDB port. Defaults to 4242.
959 ## <a id="objecttype-perfdatawriter"></a> PerfdataWriter
961 Writes check result performance data to a defined path using macro
962 pattern consisting of custom attributes and runtime macros.
968 object PerfdataWriter "pnp" {
969 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
971 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
973 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$"
974 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$"
976 rotation_interval = 15s
979 Configuration Attributes:
982 ------------------------|----------------
983 host_perfdata\_path |**Optional.** Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
984 service_perfdata\_path |**Optional.** Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
985 host_temp\_path |**Optional.** Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
986 service_temp\_path |**Optional.** Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
987 host_format\_template |**Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
988 service_format\_template|**Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
989 rotation\_interval |**Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to 30 seconds.
991 When rotating the performance data file the current UNIX timestamp is appended to the path specified
992 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
995 ## <a id="objecttype-scheduleddowntime"></a> ScheduledDowntime
997 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1001 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1002 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1003 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1004 > type for `Host` or `Service`.
1005 > Check the [recurring downtimes](4-advanced-topics.md#recurring-downtimes) example for details.
1009 object ScheduledDowntime "some-downtime" {
1010 host_name = "localhost"
1011 service_name = "ping4"
1013 author = "icingaadmin"
1014 comment = "Some comment"
1020 "sunday" = "02:00-03:00"
1024 Configuration Attributes:
1027 ----------------|----------------
1028 host_name |**Required.** The name of the host this scheduled downtime belongs to.
1029 service_name |**Optional.** The short name of the service this scheduled downtime belongs to. If omitted this downtime object is treated as host downtime.
1030 author |**Required.** The author of the downtime.
1031 comment |**Required.** A comment for the downtime.
1032 fixed |**Optional.** Whether this is a fixed downtime. Defaults to true.
1033 duration |**Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1034 zone |**Optional.** The zone this object is a member of.
1035 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1037 ScheduledDowntime objects have composite names, i.e. their names are based
1038 on the `host_name` and `service_name` attributes and the
1039 name you specified. This means you can define more than one object
1040 with the same (short) name as long as one of the `host_name` and
1041 `service_name` attributes has a different value.
1044 ## <a id="objecttype-service"></a> Service
1046 Service objects describe network services and how they should be checked
1051 > Rather than creating a `Service` object for a specific host it is usually easier
1052 > to just create a `Service` template and use the `apply` keyword to assign the
1053 > service to a number of hosts.
1054 > Check the [apply](3-monitoring-basics.md#using-apply) chapter for details.
1058 object Service "uptime" {
1059 host_name = "localhost"
1061 display_name = "localhost Uptime"
1063 check_command = "check_snmp"
1065 vars.community = "public"
1066 vars.oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1068 check_interval = 60s
1069 retry_interval = 15s
1071 groups = [ "all-services", "snmp" ]
1074 Configuration Attributes:
1077 ----------------|----------------
1078 display_name |**Optional.** A short description of the service.
1079 host_name |**Required.** The host this service belongs to. There must be a `Host` object with that name.
1080 name |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
1081 groups |**Optional.** The service groups this service belongs to.
1082 vars |**Optional.** A dictionary containing custom attributes that are specific to this service.
1083 check\_command |**Required.** The name of the check command.
1084 max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1085 check\_period |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1086 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.
1087 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.
1088 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
1089 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
1090 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
1091 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
1092 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
1093 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
1094 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.
1095 flapping\_threshold|**Optional.** The flapping threshold in percent when a service is considered to be flapping.
1096 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
1097 zone |**Optional.** The zone this object is a member of.
1098 command\_endpoint|**Optional.** The endpoint where commands are executed on.
1099 notes |**Optional.** Notes for the service.
1100 notes\_url |**Optional.** Url for notes for the service (for example, in notification commands).
1101 action_url |**Optional.** Url for actions for the service (for example, an external graphing tool).
1102 icon\_image |**Optional.** Icon image for the service. Used by external interfaces only.
1103 icon\_image\_alt|**Optional.** Icon image description for the service. Used by external interface only.
1105 Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
1106 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1110 Name | Type | Description
1111 --------------------------|---------------|-----------------
1112 next\_check | Number | When the next check occurs (as a UNIX timestamp).
1113 check\_attempt | Number | The current check attempt number.
1114 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1115 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1116 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1117 last\_check\_result | CheckResult | The current check result.
1118 last\_state\_change | Number | When the last state change occurred (as a UNIX timestamp).
1119 last\_hard\_state\_change | Number | When the last hard state change occurred (as a UNIX timestamp).
1120 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1121 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1122 acknowledgement_expiry | Number | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1123 comments | Dictionary | The comments for this service.
1124 downtimes | Dictionary | The downtimes for this service.
1125 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1126 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1127 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1130 ## <a id="objecttype-servicegroup"></a> ServiceGroup
1132 A group of services.
1136 > Assign service group members using the [group assign](19-language-reference.md#group-assign) rules.
1140 object ServiceGroup "snmp" {
1141 display_name = "SNMP services"
1144 Configuration Attributes:
1147 ----------------|----------------
1148 display_name |**Optional.** A short description of the service group.
1149 groups |**Optional.** An array of nested group names.
1152 ## <a id="objecttype-statusdatawriter"></a> StatusDataWriter
1154 Periodically writes status data files which are used by the Classic UI and other third-party tools.
1160 object StatusDataWriter "status" {
1161 status_path = "/var/cache/icinga2/status.dat"
1162 objects_path = "/var/cache/icinga2/objects.cache"
1163 update_interval = 30s
1166 Configuration Attributes:
1169 ----------------|----------------
1170 status\_path |**Optional.** Path to the status.dat file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
1171 objects\_path |**Optional.** Path to the objects.cache file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
1172 update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
1175 ## <a id="objecttype-sysloglogger"></a> SyslogLogger
1177 Specifies Icinga 2 logging to syslog.
1181 object SyslogLogger "crit-syslog" {
1182 severity = "critical"
1185 Configuration Attributes:
1188 ----------------|----------------
1189 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "notice", "warning" or "critical". Defaults to "warning".
1192 ## <a id="objecttype-timeperiod"></a> TimePeriod
1194 Time periods can be used to specify when hosts/services should be checked or to limit
1195 when notifications should be sent out.
1199 object TimePeriod "24x7" {
1200 import "legacy-timeperiod"
1202 display_name = "Icinga 2 24x7 TimePeriod"
1205 monday = "00:00-24:00"
1206 tuesday = "00:00-24:00"
1207 wednesday = "00:00-24:00"
1208 thursday = "00:00-24:00"
1209 friday = "00:00-24:00"
1210 saturday = "00:00-24:00"
1211 sunday = "00:00-24:00"
1215 Configuration Attributes:
1218 ----------------|----------------
1219 display_name |**Optional.** A short description of the time period.
1220 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.
1221 zone |**Optional.** The zone this object is a member of.
1222 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1224 The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define
1225 timeperiods including this one.
1229 Name | Type | Description
1230 --------------------------|---------------|-----------------
1231 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1234 ## <a id="objecttype-user"></a> User
1240 object User "icingaadmin" {
1241 display_name = "Icinga 2 Admin"
1242 groups = [ "icingaadmins" ]
1243 email = "icinga@localhost"
1244 pager = "icingaadmin@localhost.localdomain"
1248 states = [ OK, Warning, Critical, Unknown ]
1249 types = [ Problem, Recovery ]
1251 vars.additional_notes = "This is the Icinga 2 Admin account."
1254 Available notification state filters:
1263 Available notification type filters:
1275 Configuration Attributes:
1278 ----------------|----------------
1279 display_name |**Optional.** A short description of the user.
1280 email |**Optional.** An email string for this user. Useful for notification commands.
1281 pager |**Optional.** A pager string for this user. Useful for notification commands.
1282 vars |**Optional.** A dictionary containing custom attributes that are specific to this user.
1283 groups |**Optional.** An array of group names.
1284 enable_notifications|**Optional.** Whether notifications are enabled for this user.
1285 period |**Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default.
1286 types |**Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
1287 states |**Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
1288 zone |**Optional.** The zone this object is a member of.
1292 Name | Type | Description
1293 --------------------------|---------------|-----------------
1294 last\_notification | Number | When the last notification was sent for this user (as a UNIX timestamp).
1296 ## <a id="objecttype-usergroup"></a> UserGroup
1302 > Assign user group members using the [group assign](19-language-reference.md#group-assign) rules.
1306 object UserGroup "icingaadmins" {
1307 display_name = "Icinga 2 Admin Group"
1310 Configuration Attributes:
1313 ----------------|----------------
1314 display_name |**Optional.** A short description of the user group.
1315 groups |**Optional.** An array of nested group names.
1316 zone |**Optional.** The zone this object is a member of.
1319 ## <a id="objecttype-zone"></a> Zone
1321 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1325 object Zone "config-ha-master" {
1326 endpoints = [ "icinga2a", "icinga2b" ]
1330 object Zone "check-satellite" {
1331 endpoints = [ "icinga2c" ]
1332 parent = "config-ha-master"
1335 Configuration Attributes:
1338 ----------------|----------------
1339 endpoints |**Optional.** Dictionary with endpoints located in this zone.
1340 parent |**Optional.** The name of the parent zone.
1341 global |**Optional.** Whether configuration files for this zone should be synced to all endpoints. Defaults to false.