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 arguments |**Optional.** A dictionary of command arguments.
92 ### <a id="objecttype-checkcommand-arguments"></a> CheckCommand Arguments
94 Command arguments can be defined as key-value-pairs in the `arguments`
95 dictionary. If the argument requires additional configuration for example
96 a `description` attribute or an optional condition, the value can be defined
97 as dictionary specifying additional options.
101 vars.x_val = "My command argument value."
109 key = "-Xnew" /* optional, set a new key identifier */
110 description = "My plugin requires this argument for doing X."
111 required = false /* optional, no error if not set */
112 skip_key = false /* always use "-X <value>" */
113 set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
114 order = -1 /* first position */
115 repeat_key = true /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
119 description = "My plugin requires this argument for doing Y."
120 required = false /* optional, no error if not set */
121 skip_key = true /* don't prefix "-Y" only use "<value>" */
122 set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
123 order = 0 /* second position */
124 repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
129 ------------|--------------
130 value | Optional argument value set by a macro string or a function call.
131 key | Optional argument key overriding the key identifier.
132 description | Optional argument description.
133 required | Required argument. Execution error if not set. Defaults to false (optional).
134 skip_key | Use the value as argument and skip the key.
135 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.
136 order | Set if multiple arguments require a defined argument order.
137 repeat_key | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
141 `..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...`
143 Argument array `repeat_key = true`:
145 `'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'`
147 Argument array `repeat_key = false`:
149 `'key' 'value[0]' 'value[1]' 'value[2]'`
151 ## <a id="objecttype-checkcomponent"></a> CheckerComponent
153 The checker component is responsible for scheduling active checks. There are no configurable options.
159 object CheckerComponent "checker" { }
161 ## <a id="objecttype-checkresultreader"></a> CheckResultReader
163 Reads Icinga 1.x check results from a directory. This functionality is provided
164 to help existing Icinga 1.x users and might be useful for certain cluster
171 object CheckResultReader "reader" {
172 spool_dir = "/data/check-results"
175 Configuration Attributes:
178 ----------------|----------------
179 spool\_dir |**Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/".
182 ## <a id="objecttype-compatlogger"></a> CompatLogger
184 Writes log files in a format that's compatible with Icinga 1.x.
190 object CompatLogger "my-log" {
191 log_dir = "/var/log/icinga2/compat"
192 rotation_method = "HOURLY"
195 Configuration Attributes:
198 ----------------|----------------
199 log\_dir |**Optional.** Path to the compat log directory. Defaults to LocalStateDir + "/log/icinga2/compat".
200 rotation\_method|**Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
204 ## <a id="objecttype-dependency"></a> Dependency
206 Dependency objects are used to specify dependencies between hosts and services. Dependencies
207 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
212 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
213 > to just create a `Dependency` template and use the `apply` keyword to assign the
214 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
215 > type for `Host` or `Service`.
216 > Check the [dependencies](3-monitoring-basics.md#dependencies) chapter for detailed examples.
218 Service-to-Service Example:
220 object Dependency "webserver-internet" {
221 parent_host_name = "internet"
222 parent_service_name = "ping4"
224 child_host_name = "webserver"
225 child_service_name = "ping4"
227 states = [ OK, Warning ]
229 disable_checks = true
232 Host-to-Host Example:
234 object Dependency "webserver-internet" {
235 parent_host_name = "internet"
237 child_host_name = "webserver"
241 disable_checks = true
244 Configuration Attributes:
247 ----------------------|----------------
248 parent_host_name |**Required.** The parent host.
249 parent_service_name |**Optional.** The parent service. If omitted this dependency object is treated as host dependency.
250 child_host_name |**Required.** The child host.
251 child_service_name |**Optional.** The child service. If omitted this dependency object is treated as host dependency.
252 disable_checks |**Optional.** Whether to disable checks when this dependency fails. Defaults to false.
253 disable_notifications |**Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
254 ignore_soft_states |**Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
255 period |**Optional.** Time period during which this dependency is enabled.
256 states |**Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
258 Available state filters:
267 When using [apply rules](3-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
268 automatically determined by Icinga 2.
270 Service-to-Host Dependency Example:
272 apply Dependency "internet" to Service {
273 parent_host_name = "dsl-router"
274 disable_checks = true
276 assign where host.name != "dsl-router"
279 This example sets all service objects matching the assign condition into a dependency relation to
280 the parent host object `dsl-router` as implicit child services.
282 Service-to-Service-on-the-same-Host Dependency Example:
284 apply Dependency "disable-nrpe-checks" to Service {
285 parent_service_name = "nrpe-health"
287 assign where service.check_command == "nrpe"
288 ignore where service.name == "nrpe-health"
291 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
292 host object matched by the apply rule condition. All services where apply matches are made implicit child services
293 in this dependency relation.
296 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
297 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
298 `child_service_name` attributes has a different value.
301 ## <a id="objecttype-endpoint"></a> Endpoint
303 Endpoint objects are used to specify connection information for remote
308 object Endpoint "icinga2b" {
309 host = "192.168.5.46"
313 Configuration Attributes:
316 ----------------|----------------
317 host |**Optional.** The hostname/IP address of the remote Icinga 2 instance.
318 port |**Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
319 log_duration |**Optional.** Duration for keeping replay logs on connection loss. Defaults to `1d`.
322 ## <a id="objecttype-zone"></a> Zone
324 Zone objects are used to specify which Icinga 2 instances are located in a zone.
328 object Zone "config-ha-master" {
329 endpoints = [ "icinga2a", "icinga2b" ]
333 object Zone "check-satellite" {
334 endpoints = [ "icinga2c" ]
335 parent = "config-ha-master"
338 Configuration Attributes:
341 ----------------|----------------
342 endpoints |**Optional.** Dictionary with endpoints located in this zone.
343 parent |**Optional.** The name of the parent zone.
344 global |**Optional.** Whether configuration files for this zone should be synced to all endpoints. Defaults to false.
347 ## <a id="objecttype-eventcommand"></a> EventCommand
349 An event command definition.
353 object EventCommand "restart-httpd-event" {
354 import "plugin-event-command"
356 command = "/opt/bin/restart-httpd.sh"
360 Configuration Attributes:
363 ----------------|----------------
364 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.
365 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.
366 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
367 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
368 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
369 arguments |**Optional.** A dictionary of command arguments.
371 Command arguments can be used the same way as for [CheckCommand objects](6-object-types.md#objecttype-checkcommand-arguments).
374 ## <a id="objecttype-externalcommandlistener"></a> ExternalCommandListener
376 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
382 object ExternalCommandListener "external" {
383 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
386 Configuration Attributes:
389 ----------------|----------------
390 command\_path |**Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
394 ## <a id="objecttype-filelogger"></a> FileLogger
396 Specifies Icinga 2 logging to a file.
400 object FileLogger "debug-file" {
402 path = "/var/log/icinga2/debug.log"
405 Configuration Attributes:
408 ----------------|----------------
409 path |**Required.** The log path.
410 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
413 ## <a id="objecttype-gelfwriter"></a> GelfWriter
415 Writes event log entries to a defined GELF receiver host (Graylog2, Logstash).
421 object GelfWriter "gelf" {
426 Configuration Attributes:
429 ----------------------|----------------------
430 host |**Optional.** GELF receiver host address. Defaults to '127.0.0.1'.
431 port |**Optional.** GELF receiver port. Defaults to `12201`.
432 source |**Optional.** Source name for this instance. Defaults to `icinga2`.
435 ## <a id="objecttype-graphitewriter"></a> GraphiteWriter
437 Writes check result metrics and performance data to a defined
438 Graphite Carbon host.
444 object GraphiteWriter "graphite" {
449 Configuration Attributes:
452 ----------------------|----------------------
453 host |**Optional.** Graphite Carbon host address. Defaults to '127.0.0.1'.
454 port |**Optional.** Graphite Carbon port. Defaults to 2003.
455 host_name_template |**Optional.** Metric prefix for host name. Defaults to "icinga.$host.name$".
456 service_name_template |**Optional.** Metric prefix for service name. Defaults to "icinga.$host.name$.$service.name$".
458 Metric prefix names can be modified using [runtime macros](3-monitoring-basics.md#runtime-macros).
460 Example with your custom [global constant](19-language-reference.md#constants) `GraphiteEnv`:
462 const GraphiteEnv = "icinga.env1"
464 host_name_template = GraphiteEnv + ".$host.name$"
465 service_name_template = GraphiteEnv + ".$host.name$.$service.name$"
469 ## <a id="objecttype-host"></a> Host
475 object Host NodeName {
476 display_name = "Local host on this node"
477 address = "127.0.0.1"
480 groups = [ "all-hosts" ]
482 check_command = "hostalive"
485 Configuration Attributes:
488 ----------------|----------------
489 display_name |**Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
490 address |**Optional.** The host's address. Available as command runtime macro `$address$` if set.
491 address6 |**Optional.** The host's address. Available as command runtime macro `$address6$` if set.
492 groups |**Optional.** A list of host groups this host belongs to.
493 vars |**Optional.** A dictionary containing custom attributes that are specific to this host.
494 check\_command |**Required.** The name of the check command.
495 max\_check\_attempts|**Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
496 check\_period |**Optional.** The name of a time period which determines when this host should be checked. Not set by default.
497 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.
498 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.
499 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
500 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
501 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
502 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
503 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
504 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
505 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.
506 flapping\_threshold|**Optional.** The flapping threshold in percent when a host is considered to be flapping.
507 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
508 zone |**Optional.** The zone this object is a member of.
509 command\_endpoint|**Optional.** The endpoint where commands are executed on.
510 notes |**Optional.** Notes for the host.
511 notes\_url |**Optional.** Url for notes for the host (for example, in notification commands).
512 action\_url |**Optional.** Url for actions for the host (for example, an external graphing tool).
513 icon\_image |**Optional.** Icon image for the host. Used by external interfaces only.
514 icon\_image\_alt|**Optional.** Icon image description for the host. Used by external interface only.
518 > The `address` and `address6` attributes are required for running commands using
519 > the `$address$` and `$address6$` runtime macros.
523 Name | Type | Description
524 --------------------------|---------------|-----------------
525 next\_check | Number | When the next check occurs (as a UNIX timestamp).
526 check\_attempt | Number | The current check attempt number.
527 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
528 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
529 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
530 last\_check\_result | CheckResult | The current check result.
531 last\_state\_change | Number | When the last state change occurred (as a UNIX timestamp).
532 last\_hard\_state\_change | Number | When the last hard state change occurred (as a UNIX timestamp).
533 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
534 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
535 acknowledgement_expiry | Number | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
536 comments | Dictionary | The comments for this host.
537 downtimes | Dictionary | The downtimes for this host.
538 state | Number | The current state (0 = UP, 1 = DOWN).
539 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
540 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
544 ## <a id="objecttype-hostgroup"></a> HostGroup
550 > Assign host group members using the [group assign](19-language-reference.md#group-assign) rules.
554 object HostGroup "my-hosts" {
555 display_name = "My hosts"
558 Configuration Attributes:
561 ----------------|----------------
562 display_name |**Optional.** A short description of the host group.
563 groups |**Optional.** An array of nested group names.
566 ## <a id="objecttype-icingastatuswriter"></a> IcingaStatusWriter
568 The IcingaStatusWriter feature periodically dumps the current status
569 and performance data from Icinga 2 and all registered features into
574 object IcingaStatusWriter "status" {
575 status_path = LocalStateDir + "/cache/icinga2/status.json"
576 update_interval = 15s
579 Configuration Attributes:
582 --------------------------|--------------------------
583 status\_path |**Optional.** Path to cluster status file. Defaults to LocalStateDir + "/cache/icinga2/status.json"
584 update\_interval |**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
587 ## <a id="objecttype-idomysqlconnection"></a> IdoMySqlConnection
589 IDO database adapter for MySQL.
593 library "db_ido_mysql"
595 object IdoMysqlConnection "mysql-ido" {
601 table_prefix = "icinga_"
602 instance_name = "icinga2"
603 instance_description = "icinga2 instance"
606 downtimehistory_age = 48h
610 categories = DbCatConfig | DbCatState
613 Configuration Attributes:
616 ----------------|----------------
617 host |**Optional.** MySQL database host address. Defaults to "localhost".
618 port |**Optional.** MySQL database port. Defaults to 3306.
619 socket_path |**Optional.** MySQL socket path.
620 user |**Optional.** MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
621 password |**Optional.** MySQL database user's password. Defaults to "icinga".
622 database |**Optional.** MySQL database name. Defaults to "icinga".
623 table\_prefix |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
624 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
625 instance\_description|**Optional.** Description for the Icinga 2 instance.
626 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".
627 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".
628 cleanup |**Optional.** Dictionary with items for historical table cleanup.
629 categories |**Optional.** The types of information that should be written to the database.
634 ----------------|----------------
635 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
636 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
637 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
638 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
639 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
640 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
641 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
642 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
643 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
644 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
645 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
646 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
647 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
648 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
649 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
653 Name | Description | Required by
654 ---------------------|------------------------|--------------------
655 DbCatConfig | Configuration data | Icinga Web/Reporting
656 DbCatState | Current state data | Icinga Web/Reporting
657 DbCatAcknowledgement | Acknowledgements | Icinga Web/Reporting
658 DbCatComment | Comments | Icinga Web/Reporting
659 DbCatDowntime | Downtimes | Icinga Web/Reporting
660 DbCatEventHandler | Event handler data | Icinga Web/Reporting
661 DbCatExternalCommand | External commands | Icinga Web/Reporting
662 DbCatFlapping | Flap detection data | Icinga Web/Reporting
663 DbCatCheck | Check results | --
664 DbCatLog | Log messages | Icinga Web/Reporting
665 DbCatNotification | Notifications | Icinga Web/Reporting
666 DbCatProgramStatus | Program status data | Icinga Web/Reporting
667 DbCatRetention | Retention data | Icinga Web/Reporting
668 DbCatStateHistory | Historical state data | Icinga Web/Reporting
670 Multiple categories can be combined using the `|` operator. In addition to
671 the category flags listed above the `DbCatEverything` flag may be used as
672 a shortcut for listing all flags.
674 External interfaces like Icinga Web require everything except `DbCatCheck`
675 which is the default value if `categories` is not set.
677 ## <a id="objecttype-idopgsqlconnection"></a> IdoPgSqlConnection
679 IDO database adapter for PostgreSQL.
683 library "db_ido_pgsql"
685 object IdoMysqlConnection "pgsql-ido" {
691 table_prefix = "icinga_"
692 instance_name = "icinga2"
693 instance_description = "icinga2 instance"
696 downtimehistory_age = 48h
700 categories = DbCatConfig | DbCatState
703 Configuration Attributes:
706 ----------------|----------------
707 host |**Optional.** PostgreSQL database host address. Defaults to "localhost".
708 port |**Optional.** PostgreSQL database port. Defaults to "5432".
709 user |**Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to "icinga".
710 password |**Optional.** PostgreSQL database user's password. Defaults to "icinga".
711 database |**Optional.** PostgreSQL database name. Defaults to "icinga".
712 table\_prefix |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_".
713 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
714 instance\_description|**Optional.** Description for the Icinga 2 instance.
715 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".
716 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".
717 cleanup |**Optional.** Dictionary with items for historical table cleanup.
718 categories |**Optional.** The types of information that should be written to the database.
723 ----------------|----------------
724 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
725 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
726 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
727 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
728 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
729 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
730 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
731 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
732 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
733 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
734 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
735 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
736 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
737 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
738 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
742 Name | Description | Required by
743 ---------------------|------------------------|--------------------
744 DbCatConfig | Configuration data | Icinga Web/Reporting
745 DbCatState | Current state data | Icinga Web/Reporting
746 DbCatAcknowledgement | Acknowledgements | Icinga Web/Reporting
747 DbCatComment | Comments | Icinga Web/Reporting
748 DbCatDowntime | Downtimes | Icinga Web/Reporting
749 DbCatEventHandler | Event handler data | Icinga Web/Reporting
750 DbCatExternalCommand | External commands | Icinga Web/Reporting
751 DbCatFlapping | Flap detection data | Icinga Web/Reporting
752 DbCatCheck | Check results | --
753 DbCatLog | Log messages | Icinga Web/Reporting
754 DbCatNotification | Notifications | Icinga Web/Reporting
755 DbCatProgramStatus | Program status data | Icinga Web/Reporting
756 DbCatRetention | Retention data | Icinga Web/Reporting
757 DbCatStateHistory | Historical state data | Icinga Web/Reporting
759 Multiple categories can be combined using the `|` operator. In addition to
760 the category flags listed above the `DbCatEverything` flag may be used as
761 a shortcut for listing all flags.
763 External interfaces like Icinga Web require everything except `DbCatCheck`
764 which is the default value if `categories` is not set.
766 ## <a id="objecttype-livestatuslistener"></a> LiveStatusListener
768 Livestatus API interface available as TCP or UNIX socket. Historical table queries
769 require the [CompatLogger](6-object-types.md#objecttype-compatlogger) feature enabled
770 pointing to the log files using the `compat_log_path` configuration attribute.
776 object LivestatusListener "livestatus-tcp" {
778 bind_host = "127.0.0.1"
782 object LivestatusListener "livestatus-unix" {
784 socket_path = "/var/run/icinga2/cmd/livestatus"
787 Configuration Attributes:
790 ----------------|----------------
791 socket\_type |**Optional.** Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
792 bind\_host |**Optional.** Only valid when socket\_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
793 bind\_port |**Optional.** Only valid when `socket_type` is "tcp". Port to listen on for connections. Defaults to 6558.
794 socket\_path |**Optional.** Only valid when `socket_type` is "unix". Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus".
795 compat\_log\_path |**Optional.** Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"
799 > UNIX sockets are not supported on Windows.
802 ## <a id="objecttype-notification"></a> Notification
804 Notification objects are used to specify how users should be notified in case
805 of host and service state changes and other events.
809 > Rather than creating a `Notification` object for a specific host or service it is
810 > usually easier to just create a `Notification` template and use the `apply` keyword
811 > to assign the notification to a number of hosts or services. Use the `to` keyword
812 > to set the specific target type for `Host` or `Service`.
813 > Check the [notifications](3-monitoring-basics.md#notifications) chapter for detailed examples.
817 object Notification "localhost-ping-notification" {
818 host_name = "localhost"
819 service_name = "ping4"
821 command = "mail-notification"
823 users = [ "user1", "user2" ]
825 types = [ Problem, Recovery ]
828 Configuration Attributes:
831 --------------------------|----------------
832 host_name | **Required.** The name of the host this notification belongs to.
833 service_name | **Optional.** The short name of the service this notification belongs to. If omitted this notification object is treated as host notification.
834 vars | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
835 users | **Optional.** A list of user names who should be notified.
836 user_groups | **Optional.** A list of user group names who should be notified.
837 times | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
838 command | **Required.** The name of the notification command which should be executed when the notification is triggered.
839 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.
840 period | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
841 zone |**Optional.** The zone this object is a member of.
842 types | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
843 states | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
845 Available notification state filters:
854 Available notification type filters:
868 Name | Type | Description
869 --------------------------|---------------|-----------------
870 last\_notification | Number | When the last notification was sent for this Notification object (as a UNIX timestamp).
871 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).
872 notification\_number | Number | The notification number
873 last\_problem\_notification | Number | When the last notification was sent for a problem (as a UNIX timestamp).
876 ## <a id="objecttype-notificationcommand"></a> NotificationCommand
878 A notification command definition.
882 object NotificationCommand "mail-service-notification" {
883 import "plugin-notification-command"
886 SysconfDir + "/icinga2/scripts/mail-notification.sh"
890 NOTIFICATIONTYPE = "$notification.type$"
891 SERVICEDESC = "$service.name$"
892 HOSTALIAS = "$host.display_name$"
893 HOSTADDRESS = "$address$"
894 SERVICESTATE = "$service.state$"
895 LONGDATETIME = "$icinga.long_date_time$"
896 SERVICEOUTPUT = "$service.output$"
897 NOTIFICATIONAUTHORNAME = "$notification.author$"
898 NOTIFICATIONCOMMENT = "$notification.comment$"
899 HOSTDISPLAYNAME = "$host.display_name$"
900 SERVICEDISPLAYNAME = "$service.display_name$"
901 USEREMAIL = "$user.email$"
905 Configuration Attributes:
908 ----------------|----------------
909 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.
910 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.
911 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
912 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
913 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
914 arguments |**Optional.** A dictionary of command arguments.
916 Command arguments can be used the same way as for [CheckCommand objects](6-object-types.md#objecttype-checkcommand-arguments).
919 ## <a id="objecttype-notificationcomponent"></a> NotificationComponent
921 The notification component is responsible for sending notifications. There are no configurable options.
925 library "notification"
927 object NotificationComponent "notification" { }
929 Configuration Attributes:
932 ----------------|----------------
933 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".
935 ## <a id="objecttype-opentsdbwriter"></a> OpenTsdbWriter
937 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
943 object OpenTsdbWriter "opentsdb" {
948 Configuration Attributes:
951 ----------------------|----------------------
952 host |**Optional.** OpenTSDB host address. Defaults to '127.0.0.1'.
953 port |**Optional.** OpenTSDB port. Defaults to 4242.
956 ## <a id="objecttype-perfdatawriter"></a> PerfdataWriter
958 Writes check result performance data to a defined path using macro
959 pattern consisting of custom attributes and runtime macros.
965 object PerfdataWriter "pnp" {
966 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
968 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
970 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$"
971 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$"
973 rotation_interval = 15s
976 Configuration Attributes:
979 ------------------------|----------------
980 host_perfdata\_path |**Optional.** Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
981 service_perfdata\_path |**Optional.** Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
982 host_temp\_path |**Optional.** Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
983 service_temp\_path |**Optional.** Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
984 host_format\_template |**Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
985 service_format\_template|**Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
986 rotation\_interval |**Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to 30 seconds.
988 When rotating the performance data file the current UNIX timestamp is appended to the path specified
989 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
992 ## <a id="objecttype-scheduleddowntime"></a> ScheduledDowntime
994 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
998 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
999 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1000 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1001 > type for `Host` or `Service`.
1002 > Check the [recurring downtimes](4-advanced-topics.md#recurring-downtimes) example for details.
1006 object ScheduledDowntime "some-downtime" {
1007 host_name = "localhost"
1008 service_name = "ping4"
1010 author = "icingaadmin"
1011 comment = "Some comment"
1017 "sunday" = "02:00-03:00"
1021 Configuration Attributes:
1024 ----------------|----------------
1025 host_name |**Required.** The name of the host this scheduled downtime belongs to.
1026 service_name |**Optional.** The short name of the service this scheduled downtime belongs to. If omitted this downtime object is treated as host downtime.
1027 author |**Required.** The author of the downtime.
1028 comment |**Required.** A comment for the downtime.
1029 fixed |**Optional.** Whether this is a fixed downtime. Defaults to true.
1030 duration |**Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1031 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1033 ScheduledDowntime objects have composite names, i.e. their names are based
1034 on the `host_name` and `service_name` attributes and the
1035 name you specified. This means you can define more than one object
1036 with the same (short) name as long as one of the `host_name` and
1037 `service_name` attributes has a different value.
1040 ## <a id="objecttype-service"></a> Service
1042 Service objects describe network services and how they should be checked
1047 > Rather than creating a `Service` object for a specific host it is usually easier
1048 > to just create a `Service` template and use the `apply` keyword to assign the
1049 > service to a number of hosts.
1050 > Check the [apply](3-monitoring-basics.md#using-apply) chapter for details.
1054 object Service "uptime" {
1055 host_name = "localhost"
1057 display_name = "localhost Uptime"
1059 check_command = "check_snmp"
1061 vars.community = "public"
1062 vars.oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1064 check_interval = 60s
1065 retry_interval = 15s
1067 groups = [ "all-services", "snmp" ]
1070 Configuration Attributes:
1073 ----------------|----------------
1074 display_name |**Optional.** A short description of the service.
1075 host_name |**Required.** The host this service belongs to. There must be a `Host` object with that name.
1076 name |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
1077 groups |**Optional.** The service groups this service belongs to.
1078 vars |**Optional.** A dictionary containing custom attributes that are specific to this service.
1079 check\_command |**Required.** The name of the check command.
1080 max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1081 check\_period |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1082 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.
1083 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.
1084 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
1085 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
1086 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
1087 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
1088 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
1089 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
1090 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.
1091 flapping\_threshold|**Optional.** The flapping threshold in percent when a service is considered to be flapping.
1092 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
1093 zone |**Optional.** The zone this object is a member of.
1094 command\_endpoint|**Optional.** The endpoint where commands are executed on.
1095 notes |**Optional.** Notes for the service.
1096 notes\_url |**Optional.** Url for notes for the service (for example, in notification commands).
1097 action_url |**Optional.** Url for actions for the service (for example, an external graphing tool).
1098 icon\_image |**Optional.** Icon image for the service. Used by external interfaces only.
1099 icon\_image\_alt|**Optional.** Icon image description for the service. Used by external interface only.
1101 Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
1102 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1106 Name | Type | Description
1107 --------------------------|---------------|-----------------
1108 next\_check | Number | When the next check occurs (as a UNIX timestamp).
1109 check\_attempt | Number | The current check attempt number.
1110 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1111 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1112 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1113 last\_check\_result | CheckResult | The current check result.
1114 last\_state\_change | Number | When the last state change occurred (as a UNIX timestamp).
1115 last\_hard\_state\_change | Number | When the last hard state change occurred (as a UNIX timestamp).
1116 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1117 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1118 acknowledgement_expiry | Number | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1119 comments | Dictionary | The comments for this service.
1120 downtimes | Dictionary | The downtimes for this service.
1121 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1122 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1123 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1126 ## <a id="objecttype-servicegroup"></a> ServiceGroup
1128 A group of services.
1132 > Assign service group members using the [group assign](19-language-reference.md#group-assign) rules.
1136 object ServiceGroup "snmp" {
1137 display_name = "SNMP services"
1140 Configuration Attributes:
1143 ----------------|----------------
1144 display_name |**Optional.** A short description of the service group.
1145 groups |**Optional.** An array of nested group names.
1148 ## <a id="objecttype-statusdatawriter"></a> StatusDataWriter
1150 Periodically writes status data files which are used by the Classic UI and other third-party tools.
1156 object StatusDataWriter "status" {
1157 status_path = "/var/cache/icinga2/status.dat"
1158 objects_path = "/var/cache/icinga2/objects.cache"
1159 update_interval = 30s
1162 Configuration Attributes:
1165 ----------------|----------------
1166 status\_path |**Optional.** Path to the status.dat file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
1167 objects\_path |**Optional.** Path to the objects.cache file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
1168 update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
1171 ## <a id="objecttype-sysloglogger"></a> SyslogLogger
1173 Specifies Icinga 2 logging to syslog.
1177 object SyslogLogger "crit-syslog" {
1178 severity = "critical"
1181 Configuration Attributes:
1184 ----------------|----------------
1185 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "notice", "warning" or "critical". Defaults to "warning".
1188 ## <a id="objecttype-timeperiod"></a> TimePeriod
1190 Time periods can be used to specify when hosts/services should be checked or to limit
1191 when notifications should be sent out.
1195 object TimePeriod "24x7" {
1196 import "legacy-timeperiod"
1198 display_name = "Icinga 2 24x7 TimePeriod"
1201 monday = "00:00-24:00"
1202 tuesday = "00:00-24:00"
1203 wednesday = "00:00-24:00"
1204 thursday = "00:00-24:00"
1205 friday = "00:00-24:00"
1206 saturday = "00:00-24:00"
1207 sunday = "00:00-24:00"
1211 Configuration Attributes:
1214 ----------------|----------------
1215 display_name |**Optional.** A short description of the time period.
1216 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.
1217 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1219 The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define
1220 timeperiods including this one.
1224 Name | Type | Description
1225 --------------------------|---------------|-----------------
1226 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1229 ## <a id="objecttype-user"></a> User
1235 object User "icingaadmin" {
1236 display_name = "Icinga 2 Admin"
1237 groups = [ "icingaadmins" ]
1238 email = "icinga@localhost"
1239 pager = "icingaadmin@localhost.localdomain"
1243 states = [ OK, Warning, Critical, Unknown ]
1244 types = [ Problem, Recovery ]
1246 vars.additional_notes = "This is the Icinga 2 Admin account."
1249 Available notification state filters:
1258 Available notification type filters:
1270 Configuration Attributes:
1273 ----------------|----------------
1274 display_name |**Optional.** A short description of the user.
1275 email |**Optional.** An email string for this user. Useful for notification commands.
1276 pager |**Optional.** A pager string for this user. Useful for notification commands.
1277 vars |**Optional.** A dictionary containing custom attributes that are specific to this user.
1278 groups |**Optional.** An array of group names.
1279 enable_notifications|**Optional.** Whether notifications are enabled for this user.
1280 period |**Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default.
1281 types |**Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
1282 states |**Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
1286 Name | Type | Description
1287 --------------------------|---------------|-----------------
1288 last\_notification | Number | When the last notification was sent for this user (as a UNIX timestamp).
1290 ## <a id="objecttype-usergroup"></a> UserGroup
1296 > Assign user group members using the [group assign](19-language-reference.md#group-assign) rules.
1300 object UserGroup "icingaadmins" {
1301 display_name = "Icinga 2 Admin Group"
1304 Configuration Attributes:
1307 ----------------|----------------
1308 display_name |**Optional.** A short description of the user group.
1309 groups |**Optional.** An array of nested group names.
1312 ## <a id="objecttype-zone"></a> Zone
1314 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1318 object Zone "config-ha-master" {
1319 endpoints = [ "icinga2a", "icinga2b" ]
1323 object Zone "check-satellite" {
1324 endpoints = [ "icinga2c" ]
1325 parent = "config-ha-master"
1328 Configuration Attributes:
1331 ----------------|----------------
1332 endpoints |**Optional.** Dictionary with endpoints located in this zone.
1333 parent |**Optional.** The name of the parent zone.
1334 global |**Optional.** Whether configuration files for this zone should be synced to all endpoints. Defaults to false.