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](4-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-eventcommand"></a> EventCommand
324 An event command definition.
328 object EventCommand "restart-httpd-event" {
329 import "plugin-event-command"
331 command = "/opt/bin/restart-httpd.sh"
335 Configuration Attributes:
338 ----------------|----------------
339 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.
340 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.
341 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
342 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
343 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
344 arguments |**Optional.** A dictionary of command arguments.
346 Command arguments can be used the same way as for [CheckCommand objects](6-object-types.md#objecttype-checkcommand-arguments).
349 ## <a id="objecttype-externalcommandlistener"></a> ExternalCommandListener
351 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
357 object ExternalCommandListener "external" {
358 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
361 Configuration Attributes:
364 ----------------|----------------
365 command\_path |**Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
369 ## <a id="objecttype-filelogger"></a> FileLogger
371 Specifies Icinga 2 logging to a file.
375 object FileLogger "debug-file" {
377 path = "/var/log/icinga2/debug.log"
380 Configuration Attributes:
383 ----------------|----------------
384 path |**Required.** The log path.
385 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
388 ## <a id="objecttype-gelfwriter"></a> GelfWriter
390 Writes event log entries to a defined GELF receiver host (Graylog2, Logstash).
396 object GelfWriter "gelf" {
401 Configuration Attributes:
404 ----------------------|----------------------
405 host |**Optional.** GELF receiver host address. Defaults to '127.0.0.1'.
406 port |**Optional.** GELF receiver port. Defaults to `12201`.
407 source |**Optional.** Source name for this instance. Defaults to `icinga2`.
410 ## <a id="objecttype-graphitewriter"></a> GraphiteWriter
412 Writes check result metrics and performance data to a defined
413 Graphite Carbon host.
419 object GraphiteWriter "graphite" {
424 Configuration Attributes:
427 ----------------------|----------------------
428 host |**Optional.** Graphite Carbon host address. Defaults to '127.0.0.1'.
429 port |**Optional.** Graphite Carbon port. Defaults to 2003.
430 host_name_template |**Optional.** Metric prefix for host name. Defaults to "icinga.$host.name$".
431 service_name_template |**Optional.** Metric prefix for service name. Defaults to "icinga.$host.name$.$service.name$".
433 Metric prefix names can be modified using [runtime macros](3-monitoring-basics.md#runtime-macros).
435 Example with your custom [global constant](19-language-reference.md#constants) `GraphiteEnv`:
437 const GraphiteEnv = "icinga.env1"
439 host_name_template = GraphiteEnv + ".$host.name$"
440 service_name_template = GraphiteEnv + ".$host.name$.$service.name$"
444 ## <a id="objecttype-host"></a> Host
450 object Host NodeName {
451 display_name = "Local host on this node"
452 address = "127.0.0.1"
455 groups = [ "all-hosts" ]
457 check_command = "hostalive"
460 Configuration Attributes:
463 ----------------|----------------
464 display_name |**Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
465 address |**Optional.** The host's address. Available as command runtime macro `$address$` if set.
466 address6 |**Optional.** The host's address. Available as command runtime macro `$address6$` if set.
467 groups |**Optional.** A list of host groups this host belongs to.
468 vars |**Optional.** A dictionary containing custom attributes that are specific to this host.
469 check\_command |**Required.** The name of the check command.
470 max\_check\_attempts|**Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
471 check\_period |**Optional.** The name of a time period which determines when this host should be checked. Not set by default.
472 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.
473 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.
474 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
475 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
476 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
477 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
478 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
479 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
480 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.
481 flapping\_threshold|**Optional.** The flapping threshold in percent when a host is considered to be flapping.
482 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
483 zone |**Optional.** The zone this object is a member of.
484 command\_endpoint|**Optional.** The endpoint where commands are executed on.
485 notes |**Optional.** Notes for the host.
486 notes\_url |**Optional.** Url for notes for the host (for example, in notification commands).
487 action\_url |**Optional.** Url for actions for the host (for example, an external graphing tool).
488 icon\_image |**Optional.** Icon image for the host. Used by external interfaces only.
489 icon\_image\_alt|**Optional.** Icon image description for the host. Used by external interface only.
493 > The `address` and `address6` attributes are required for running commands using
494 > the `$address$` and `$address6$` runtime macros.
498 Name | Type | Description
499 --------------------------|---------------|-----------------
500 next\_check | Number | When the next check occurs (as a UNIX timestamp).
501 check\_attempt | Number | The current check attempt number.
502 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
503 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
504 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
505 last\_check\_result | CheckResult | The current check result.
506 last\_state\_change | Number | When the last state change occurred (as a UNIX timestamp).
507 last\_hard\_state\_change | Number | When the last hard state change occurred (as a UNIX timestamp).
508 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
509 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
510 acknowledgement_expiry | Number | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
511 comments | Dictionary | The comments for this host.
512 downtimes | Dictionary | The downtimes for this host.
513 state | Number | The current state (0 = UP, 1 = DOWN).
514 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
515 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
519 ## <a id="objecttype-hostgroup"></a> HostGroup
525 > Assign host group members using the [group assign](19-language-reference.md#group-assign) rules.
529 object HostGroup "my-hosts" {
530 display_name = "My hosts"
533 Configuration Attributes:
536 ----------------|----------------
537 display_name |**Optional.** A short description of the host group.
538 groups |**Optional.** An array of nested group names.
541 ## <a id="objecttype-icingastatuswriter"></a> IcingaStatusWriter
543 The IcingaStatusWriter feature periodically dumps the current status
544 and performance data from Icinga 2 and all registered features into
549 object IcingaStatusWriter "status" {
550 status_path = LocalStateDir + "/cache/icinga2/status.json"
551 update_interval = 15s
554 Configuration Attributes:
557 --------------------------|--------------------------
558 status\_path |**Optional.** Path to cluster status file. Defaults to LocalStateDir + "/cache/icinga2/status.json"
559 update\_interval |**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
562 ## <a id="objecttype-idomysqlconnection"></a> IdoMySqlConnection
564 IDO database adapter for MySQL.
568 library "db_ido_mysql"
570 object IdoMysqlConnection "mysql-ido" {
576 table_prefix = "icinga_"
577 instance_name = "icinga2"
578 instance_description = "icinga2 instance"
581 downtimehistory_age = 48h
585 categories = DbCatConfig | DbCatState
588 Configuration Attributes:
591 ----------------|----------------
592 host |**Optional.** MySQL database host address. Defaults to "localhost".
593 port |**Optional.** MySQL database port. Defaults to 3306.
594 socket_path |**Optional.** MySQL socket path.
595 user |**Optional.** MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
596 password |**Optional.** MySQL database user's password. Defaults to "icinga".
597 database |**Optional.** MySQL database name. Defaults to "icinga".
598 table\_prefix |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
599 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
600 instance\_description|**Optional.** Description for the Icinga 2 instance.
601 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".
602 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".
603 cleanup |**Optional.** Dictionary with items for historical table cleanup.
604 categories |**Optional.** The types of information that should be written to the database.
609 ----------------|----------------
610 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
611 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
612 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
613 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
614 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
615 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
616 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
617 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
618 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
619 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
620 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
621 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
622 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
623 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
624 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
628 Name | Description | Required by
629 ---------------------|------------------------|--------------------
630 DbCatConfig | Configuration data | Icinga Web/Reporting
631 DbCatState | Current state data | Icinga Web/Reporting
632 DbCatAcknowledgement | Acknowledgements | Icinga Web/Reporting
633 DbCatComment | Comments | Icinga Web/Reporting
634 DbCatDowntime | Downtimes | Icinga Web/Reporting
635 DbCatEventHandler | Event handler data | Icinga Web/Reporting
636 DbCatExternalCommand | External commands | Icinga Web/Reporting
637 DbCatFlapping | Flap detection data | Icinga Web/Reporting
638 DbCatCheck | Check results | --
639 DbCatLog | Log messages | Icinga Web/Reporting
640 DbCatNotification | Notifications | Icinga Web/Reporting
641 DbCatProgramStatus | Program status data | Icinga Web/Reporting
642 DbCatRetention | Retention data | Icinga Web/Reporting
643 DbCatStateHistory | Historical state data | Icinga Web/Reporting
645 Multiple categories can be combined using the `|` operator. In addition to
646 the category flags listed above the `DbCatEverything` flag may be used as
647 a shortcut for listing all flags.
649 External interfaces like Icinga Web require everything except `DbCatCheck`
650 which is the default value if `categories` is not set.
652 ## <a id="objecttype-idopgsqlconnection"></a> IdoPgSqlConnection
654 IDO database adapter for PostgreSQL.
658 library "db_ido_pgsql"
660 object IdoMysqlConnection "pgsql-ido" {
666 table_prefix = "icinga_"
667 instance_name = "icinga2"
668 instance_description = "icinga2 instance"
671 downtimehistory_age = 48h
675 categories = DbCatConfig | DbCatState
678 Configuration Attributes:
681 ----------------|----------------
682 host |**Optional.** PostgreSQL database host address. Defaults to "localhost".
683 port |**Optional.** PostgreSQL database port. Defaults to "5432".
684 user |**Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to "icinga".
685 password |**Optional.** PostgreSQL database user's password. Defaults to "icinga".
686 database |**Optional.** PostgreSQL database name. Defaults to "icinga".
687 table\_prefix |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_".
688 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
689 instance\_description|**Optional.** Description for the Icinga 2 instance.
690 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".
691 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".
692 cleanup |**Optional.** Dictionary with items for historical table cleanup.
693 categories |**Optional.** The types of information that should be written to the database.
698 ----------------|----------------
699 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
700 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
701 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
702 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
703 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
704 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
705 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
706 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
707 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
708 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
709 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
710 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
711 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
712 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
713 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
717 Name | Description | Required by
718 ---------------------|------------------------|--------------------
719 DbCatConfig | Configuration data | Icinga Web/Reporting
720 DbCatState | Current state data | Icinga Web/Reporting
721 DbCatAcknowledgement | Acknowledgements | Icinga Web/Reporting
722 DbCatComment | Comments | Icinga Web/Reporting
723 DbCatDowntime | Downtimes | Icinga Web/Reporting
724 DbCatEventHandler | Event handler data | Icinga Web/Reporting
725 DbCatExternalCommand | External commands | Icinga Web/Reporting
726 DbCatFlapping | Flap detection data | Icinga Web/Reporting
727 DbCatCheck | Check results | --
728 DbCatLog | Log messages | Icinga Web/Reporting
729 DbCatNotification | Notifications | Icinga Web/Reporting
730 DbCatProgramStatus | Program status data | Icinga Web/Reporting
731 DbCatRetention | Retention data | Icinga Web/Reporting
732 DbCatStateHistory | Historical state data | Icinga Web/Reporting
734 Multiple categories can be combined using the `|` operator. In addition to
735 the category flags listed above the `DbCatEverything` flag may be used as
736 a shortcut for listing all flags.
738 External interfaces like Icinga Web require everything except `DbCatCheck`
739 which is the default value if `categories` is not set.
741 ## <a id="objecttype-livestatuslistener"></a> LiveStatusListener
743 Livestatus API interface available as TCP or UNIX socket. Historical table queries
744 require the [CompatLogger](6-object-types.md#objecttype-compatlogger) feature enabled
745 pointing to the log files using the `compat_log_path` configuration attribute.
751 object LivestatusListener "livestatus-tcp" {
753 bind_host = "127.0.0.1"
757 object LivestatusListener "livestatus-unix" {
759 socket_path = "/var/run/icinga2/cmd/livestatus"
762 Configuration Attributes:
765 ----------------|----------------
766 socket\_type |**Optional.** Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
767 bind\_host |**Optional.** Only valid when socket\_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
768 bind\_port |**Optional.** Only valid when `socket_type` is "tcp". Port to listen on for connections. Defaults to 6558.
769 socket\_path |**Optional.** Only valid when `socket_type` is "unix". Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus".
770 compat\_log\_path |**Optional.** Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"
774 > UNIX sockets are not supported on Windows.
777 ## <a id="objecttype-notification"></a> Notification
779 Notification objects are used to specify how users should be notified in case
780 of host and service state changes and other events.
784 > Rather than creating a `Notification` object for a specific host or service it is
785 > usually easier to just create a `Notification` template and use the `apply` keyword
786 > to assign the notification to a number of hosts or services. Use the `to` keyword
787 > to set the specific target type for `Host` or `Service`.
788 > Check the [notifications](3-monitoring-basics.md#notifications) chapter for detailed examples.
792 object Notification "localhost-ping-notification" {
793 host_name = "localhost"
794 service_name = "ping4"
796 command = "mail-notification"
798 users = [ "user1", "user2" ]
800 types = [ Problem, Recovery ]
803 Configuration Attributes:
806 --------------------------|----------------
807 host_name | **Required.** The name of the host this notification belongs to.
808 service_name | **Optional.** The short name of the service this notification belongs to. If omitted this notification object is treated as host notification.
809 vars | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
810 users | **Optional.** A list of user names who should be notified.
811 user_groups | **Optional.** A list of user group names who should be notified.
812 times | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
813 command | **Required.** The name of the notification command which should be executed when the notification is triggered.
814 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.
815 period | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
816 zone |**Optional.** The zone this object is a member of.
817 types | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
818 states | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
820 Available notification state filters:
829 Available notification type filters:
843 Name | Type | Description
844 --------------------------|---------------|-----------------
845 last\_notification | Number | When the last notification was sent for this Notification object (as a UNIX timestamp).
846 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).
847 notification\_number | Number | The notification number
848 last\_problem\_notification | Number | When the last notification was sent for a problem (as a UNIX timestamp).
851 ## <a id="objecttype-notificationcommand"></a> NotificationCommand
853 A notification command definition.
857 object NotificationCommand "mail-service-notification" {
858 import "plugin-notification-command"
861 SysconfDir + "/icinga2/scripts/mail-notification.sh"
865 NOTIFICATIONTYPE = "$notification.type$"
866 SERVICEDESC = "$service.name$"
867 HOSTALIAS = "$host.display_name$"
868 HOSTADDRESS = "$address$"
869 SERVICESTATE = "$service.state$"
870 LONGDATETIME = "$icinga.long_date_time$"
871 SERVICEOUTPUT = "$service.output$"
872 NOTIFICATIONAUTHORNAME = "$notification.author$"
873 NOTIFICATIONCOMMENT = "$notification.comment$"
874 HOSTDISPLAYNAME = "$host.display_name$"
875 SERVICEDISPLAYNAME = "$service.display_name$"
876 USEREMAIL = "$user.email$"
880 Configuration Attributes:
883 ----------------|----------------
884 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.
885 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.
886 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
887 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
888 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
889 arguments |**Optional.** A dictionary of command arguments.
891 Command arguments can be used the same way as for [CheckCommand objects](6-object-types.md#objecttype-checkcommand-arguments).
894 ## <a id="objecttype-notificationcomponent"></a> NotificationComponent
896 The notification component is responsible for sending notifications. There are no configurable options.
900 library "notification"
902 object NotificationComponent "notification" { }
904 Configuration Attributes:
907 ----------------|----------------
908 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".
910 ## <a id="objecttype-opentsdbwriter"></a> OpenTsdbWriter
912 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
918 object OpenTsdbWriter "opentsdb" {
923 Configuration Attributes:
926 ----------------------|----------------------
927 host |**Optional.** OpenTSDB host address. Defaults to '127.0.0.1'.
928 port |**Optional.** OpenTSDB port. Defaults to 4242.
931 ## <a id="objecttype-perfdatawriter"></a> PerfdataWriter
933 Writes check result performance data to a defined path using macro
934 pattern consisting of custom attributes and runtime macros.
940 object PerfdataWriter "pnp" {
941 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
943 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
945 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$"
946 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$"
948 rotation_interval = 15s
951 Configuration Attributes:
954 ------------------------|----------------
955 host_perfdata\_path |**Optional.** Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
956 service_perfdata\_path |**Optional.** Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
957 host_temp\_path |**Optional.** Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
958 service_temp\_path |**Optional.** Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
959 host_format\_template |**Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
960 service_format\_template|**Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
961 rotation\_interval |**Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to 30 seconds.
963 When rotating the performance data file the current UNIX timestamp is appended to the path specified
964 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
967 ## <a id="objecttype-scheduleddowntime"></a> ScheduledDowntime
969 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
973 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
974 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
975 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
976 > type for `Host` or `Service`.
977 > Check the [recurring downtimes](5-advanced-topics.md#recurring-downtimes) example for details.
981 object ScheduledDowntime "some-downtime" {
982 host_name = "localhost"
983 service_name = "ping4"
985 author = "icingaadmin"
986 comment = "Some comment"
992 "sunday" = "02:00-03:00"
996 Configuration Attributes:
999 ----------------|----------------
1000 host_name |**Required.** The name of the host this scheduled downtime belongs to.
1001 service_name |**Optional.** The short name of the service this scheduled downtime belongs to. If omitted this downtime object is treated as host downtime.
1002 author |**Required.** The author of the downtime.
1003 comment |**Required.** A comment for the downtime.
1004 fixed |**Optional.** Whether this is a fixed downtime. Defaults to true.
1005 duration |**Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1006 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1008 ScheduledDowntime objects have composite names, i.e. their names are based
1009 on the `host_name` and `service_name` attributes and the
1010 name you specified. This means you can define more than one object
1011 with the same (short) name as long as one of the `host_name` and
1012 `service_name` attributes has a different value.
1015 ## <a id="objecttype-service"></a> Service
1017 Service objects describe network services and how they should be checked
1022 > Rather than creating a `Service` object for a specific host it is usually easier
1023 > to just create a `Service` template and use the `apply` keyword to assign the
1024 > service to a number of hosts.
1025 > Check the [apply](3-monitoring-basics.md#using-apply) chapter for details.
1029 object Service "uptime" {
1030 host_name = "localhost"
1032 display_name = "localhost Uptime"
1034 check_command = "check_snmp"
1036 vars.community = "public"
1037 vars.oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1039 check_interval = 60s
1040 retry_interval = 15s
1042 groups = [ "all-services", "snmp" ]
1045 Configuration Attributes:
1048 ----------------|----------------
1049 display_name |**Optional.** A short description of the service.
1050 host_name |**Required.** The host this service belongs to. There must be a `Host` object with that name.
1051 name |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
1052 groups |**Optional.** The service groups this service belongs to.
1053 vars |**Optional.** A dictionary containing custom attributes that are specific to this service.
1054 check\_command |**Required.** The name of the check command.
1055 max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1056 check\_period |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1057 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.
1058 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.
1059 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
1060 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
1061 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
1062 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
1063 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
1064 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
1065 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.
1066 flapping\_threshold|**Optional.** The flapping threshold in percent when a service is considered to be flapping.
1067 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
1068 zone |**Optional.** The zone this object is a member of.
1069 command\_endpoint|**Optional.** The endpoint where commands are executed on.
1070 notes |**Optional.** Notes for the service.
1071 notes\_url |**Optional.** Url for notes for the service (for example, in notification commands).
1072 action_url |**Optional.** Url for actions for the service (for example, an external graphing tool).
1073 icon\_image |**Optional.** Icon image for the service. Used by external interfaces only.
1074 icon\_image\_alt|**Optional.** Icon image description for the service. Used by external interface only.
1076 Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
1077 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1081 Name | Type | Description
1082 --------------------------|---------------|-----------------
1083 next\_check | Number | When the next check occurs (as a UNIX timestamp).
1084 check\_attempt | Number | The current check attempt number.
1085 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1086 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1087 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1088 last\_check\_result | CheckResult | The current check result.
1089 last\_state\_change | Number | When the last state change occurred (as a UNIX timestamp).
1090 last\_hard\_state\_change | Number | When the last hard state change occurred (as a UNIX timestamp).
1091 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1092 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1093 acknowledgement_expiry | Number | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1094 comments | Dictionary | The comments for this service.
1095 downtimes | Dictionary | The downtimes for this service.
1096 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1097 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1098 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1101 ## <a id="objecttype-servicegroup"></a> ServiceGroup
1103 A group of services.
1107 > Assign service group members using the [group assign](19-language-reference.md#group-assign) rules.
1111 object ServiceGroup "snmp" {
1112 display_name = "SNMP services"
1115 Configuration Attributes:
1118 ----------------|----------------
1119 display_name |**Optional.** A short description of the service group.
1120 groups |**Optional.** An array of nested group names.
1123 ## <a id="objecttype-statusdatawriter"></a> StatusDataWriter
1125 Periodically writes status data files which are used by the Classic UI and other third-party tools.
1131 object StatusDataWriter "status" {
1132 status_path = "/var/cache/icinga2/status.dat"
1133 objects_path = "/var/cache/icinga2/objects.cache"
1134 update_interval = 30s
1137 Configuration Attributes:
1140 ----------------|----------------
1141 status\_path |**Optional.** Path to the status.dat file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
1142 objects\_path |**Optional.** Path to the objects.cache file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
1143 update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
1146 ## <a id="objecttype-sysloglogger"></a> SyslogLogger
1148 Specifies Icinga 2 logging to syslog.
1152 object SyslogLogger "crit-syslog" {
1153 severity = "critical"
1156 Configuration Attributes:
1159 ----------------|----------------
1160 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "notice", "warning" or "critical". Defaults to "warning".
1163 ## <a id="objecttype-timeperiod"></a> TimePeriod
1165 Time periods can be used to specify when hosts/services should be checked or to limit
1166 when notifications should be sent out.
1170 object TimePeriod "24x7" {
1171 import "legacy-timeperiod"
1173 display_name = "Icinga 2 24x7 TimePeriod"
1176 monday = "00:00-24:00"
1177 tuesday = "00:00-24:00"
1178 wednesday = "00:00-24:00"
1179 thursday = "00:00-24:00"
1180 friday = "00:00-24:00"
1181 saturday = "00:00-24:00"
1182 sunday = "00:00-24:00"
1186 Configuration Attributes:
1189 ----------------|----------------
1190 display_name |**Optional.** A short description of the time period.
1191 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.
1192 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1194 The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define
1195 timeperiods including this one.
1199 Name | Type | Description
1200 --------------------------|---------------|-----------------
1201 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1204 ## <a id="objecttype-user"></a> User
1210 object User "icingaadmin" {
1211 display_name = "Icinga 2 Admin"
1212 groups = [ "icingaadmins" ]
1213 email = "icinga@localhost"
1214 pager = "icingaadmin@localhost.localdomain"
1218 states = [ OK, Warning, Critical, Unknown ]
1219 types = [ Problem, Recovery ]
1221 vars.additional_notes = "This is the Icinga 2 Admin account."
1224 Available notification state filters:
1233 Available notification type filters:
1245 Configuration Attributes:
1248 ----------------|----------------
1249 display_name |**Optional.** A short description of the user.
1250 email |**Optional.** An email string for this user. Useful for notification commands.
1251 pager |**Optional.** A pager string for this user. Useful for notification commands.
1252 vars |**Optional.** A dictionary containing custom attributes that are specific to this user.
1253 groups |**Optional.** An array of group names.
1254 enable_notifications|**Optional.** Whether notifications are enabled for this user.
1255 period |**Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default.
1256 types |**Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
1257 states |**Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
1261 Name | Type | Description
1262 --------------------------|---------------|-----------------
1263 last\_notification | Number | When the last notification was sent for this user (as a UNIX timestamp).
1265 ## <a id="objecttype-usergroup"></a> UserGroup
1271 > Assign user group members using the [group assign](19-language-reference.md#group-assign) rules.
1275 object UserGroup "icingaadmins" {
1276 display_name = "Icinga 2 Admin Group"
1279 Configuration Attributes:
1282 ----------------|----------------
1283 display_name |**Optional.** A short description of the user group.
1284 groups |**Optional.** An array of nested group names.
1287 ## <a id="objecttype-zone"></a> Zone
1289 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1293 object Zone "config-ha-master" {
1294 endpoints = [ "icinga2a", "icinga2b" ]
1298 object Zone "check-satellite" {
1299 endpoints = [ "icinga2c" ]
1300 parent = "config-ha-master"
1303 Configuration Attributes:
1306 ----------------|----------------
1307 endpoints |**Optional.** Dictionary with endpoints located in this zone.
1308 parent |**Optional.** The name of the parent zone.
1309 global |**Optional.** Whether configuration files for this zone should be synced to all endpoints. Defaults to false.