1 # <a id="object-types"></a> Config Object Types
3 This chapter provides an overview of all available config object types which can be
4 instantiated using the `object` keyword.
6 Additional details on configuration and runtime attributes and their
7 description are explained as well.
9 Config objects share these runtime attributes which cannot be
10 modified by the user. You can access these attributes using
11 the [Icinga 2 API](9-icinga2-api.md#icinga2-api-config-objects).
14 --------------------------|--------------------------
15 version | Timestamp when the object was created or modified. Synced throughout cluster nodes.
17 original_attributes | Original values of object attributes modified at runtime.
18 active | Object is active (e.g. a service being checked).
19 paused | Object has been paused at runtime (e.g. [IdoMysqlConnection](6-object-types.md#objecttype-idomysqlconnection). Defaults to `false`.
20 templates | Templates imported on object compilation.
21 package | [Configuration package name](9-icinga2-api.md#icinga2-api-config-management) this object belongs to. Local configuration is set to `_etc`, runtime created objects use `_api`.
24 ## <a id="objecttype-apilistener"></a> ApiListener
26 ApiListener objects are used for distributed monitoring setups
27 and API usage specifying the certificate files used for ssl
28 authorization and additional restrictions.
30 The `NodeName` constant must be defined in [constants.conf](4-configuring-icinga-2.md#constants-conf).
34 object ApiListener "api" {
35 cert_path = SysconfDir + "/icinga2/pki/" + NodeName + ".crt"
36 key_path = SysconfDir + "/icinga2/pki/" + NodeName + ".key"
37 ca_path = SysconfDir + "/icinga2/pki/ca.crt"
41 Configuration Attributes:
44 --------------------------|--------------------------
45 cert\_path |**Required.** Path to the public key.
46 key\_path |**Required.** Path to the private key.
47 ca\_path |**Required.** Path to the CA certificate file.
48 crl\_path |**Optional.** Path to the CRL file.
49 bind\_host |**Optional.** The IP address the api listener should be bound to. Defaults to `0.0.0.0`.
50 bind\_port |**Optional.** The port the api listener should be bound to. Defaults to `5665`.
51 accept\_config |**Optional.** Accept zone configuration. Defaults to `false`.
52 accept\_commands |**Optional.** Accept remote commands. Defaults to `false`.
54 ## <a id="objecttype-apiuser"></a> ApiUser
56 ApiUser objects are used for authentication against the Icinga 2 API.
60 object ApiUser "root" {
61 password = "mysecretapipassword"
66 Configuration Attributes:
69 --------------------------|--------------------------
70 password |**Optional.** Password string.
71 client\_cn |**Optional.** Client Common Name (CN).
72 permissions |**Required.** Array of permissions. Either as string or dictionary with the keys `permission` and `filter`. The latter must be specified as function.
74 Available permissions are described in the [API permissions](9-icinga2-api.md#icinga2-api-permissions)
77 ## <a id="objecttype-checkcommand"></a> CheckCommand
79 A check command definition. Additional default command custom attributes can be
84 object CheckCommand "check_http" {
85 import "plugin-check-command"
87 command = [ PluginDir + "/check_http" ]
91 "-I" = "$http_address$"
101 value = "$http_auth_pair$"
102 description = "Username:password on sites with basic authentication"
105 set_if = "$http_ignore_body$"
107 "-r" = "$http_expect_body_regex$"
108 "-w" = "$http_warn_time$"
109 "-c" = "$http_critical_time$"
110 "-e" = "$http_expect$"
113 vars.http_address = "$address$"
114 vars.http_ssl = false
115 vars.http_sni = false
119 Configuration Attributes:
122 ----------------|----------------
123 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.
124 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.
125 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
126 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
127 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
128 arguments |**Optional.** A dictionary of command arguments.
131 ### <a id="objecttype-checkcommand-arguments"></a> CheckCommand Arguments
133 Command arguments can be defined as key-value-pairs in the `arguments`
134 dictionary. If the argument requires additional configuration for example
135 a `description` attribute or an optional condition, the value can be defined
136 as dictionary specifying additional options.
140 vars.x_val = "My command argument value."
148 key = "-Xnew" /* optional, set a new key identifier */
149 description = "My plugin requires this argument for doing X."
150 required = false /* optional, no error if not set */
151 skip_key = false /* always use "-X <value>" */
152 set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
153 order = -1 /* first position */
154 repeat_key = true /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
158 description = "My plugin requires this argument for doing Y."
159 required = false /* optional, no error if not set */
160 skip_key = true /* don't prefix "-Y" only use "<value>" */
161 set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
162 order = 0 /* second position */
163 repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
168 ------------|--------------
169 value | Optional argument value set by a macro string or a function call.
170 key | Optional argument key overriding the key identifier.
171 description | Optional argument description.
172 required | Required argument. Execution error if not set. Defaults to false (optional).
173 skip_key | Use the value as argument and skip the key.
174 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.
175 order | Set if multiple arguments require a defined argument order.
176 repeat_key | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
180 `..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...`
182 Argument array `repeat_key = true`:
184 `'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'`
186 Argument array `repeat_key = false`:
188 `'key' 'value[0]' 'value[1]' 'value[2]'`
190 ## <a id="objecttype-checkcomponent"></a> CheckerComponent
192 The checker component is responsible for scheduling active checks. There are no configurable options.
198 object CheckerComponent "checker" { }
200 ## <a id="objecttype-checkresultreader"></a> CheckResultReader
202 Reads Icinga 1.x check results from a directory. This functionality is provided
203 to help existing Icinga 1.x users and might be useful for certain cluster
210 object CheckResultReader "reader" {
211 spool_dir = "/data/check-results"
214 Configuration Attributes:
217 ----------------|----------------
218 spool\_dir |**Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/".
220 ## <a id="objecttype-comment"></a> Comment
222 Comments created at runtime are represented as objects.
226 object Comment "localhost!my-comment" {
227 host_name = "localhost"
228 author = "icingaadmin"
229 text = "This is a comment."
232 Configuration Attributes:
235 ----------------|----------------
236 host_name | **Required.** The name of the host this comment belongs to.
237 service_name | **Optional.** The short name of the service this comment belongs to. If omitted this comment object is treated as host comment.
238 author | **Required.** The author's name.
239 text | **Required.** The comment text.
240 entry_time | **Optional.** The unix timestamp when this comment was added.
241 entry_type | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
242 expire_time | **Optional.** The comment's expire time as unix timestamp.
244 ## <a id="objecttype-compatlogger"></a> CompatLogger
246 Writes log files in a format that's compatible with Icinga 1.x.
252 object CompatLogger "my-log" {
253 log_dir = "/var/log/icinga2/compat"
254 rotation_method = "HOURLY"
257 Configuration Attributes:
260 ----------------|----------------
261 log\_dir |**Optional.** Path to the compat log directory. Defaults to LocalStateDir + "/log/icinga2/compat".
262 rotation\_method|**Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
266 ## <a id="objecttype-dependency"></a> Dependency
268 Dependency objects are used to specify dependencies between hosts and services. Dependencies
269 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
274 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
275 > to just create a `Dependency` template and use the `apply` keyword to assign the
276 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
277 > type for `Host` or `Service`.
278 > Check the [dependencies](3-monitoring-basics.md#dependencies) chapter for detailed examples.
280 Service-to-Service Example:
282 object Dependency "webserver-internet" {
283 parent_host_name = "internet"
284 parent_service_name = "ping4"
286 child_host_name = "webserver"
287 child_service_name = "ping4"
289 states = [ OK, Warning ]
291 disable_checks = true
294 Host-to-Host Example:
296 object Dependency "webserver-internet" {
297 parent_host_name = "internet"
299 child_host_name = "webserver"
303 disable_checks = true
306 Configuration Attributes:
309 ----------------------|----------------
310 parent_host_name |**Required.** The parent host.
311 parent_service_name |**Optional.** The parent service. If omitted this dependency object is treated as host dependency.
312 child_host_name |**Required.** The child host.
313 child_service_name |**Optional.** The child service. If omitted this dependency object is treated as host dependency.
314 disable_checks |**Optional.** Whether to disable checks when this dependency fails. Defaults to false.
315 disable_notifications |**Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
316 ignore_soft_states |**Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
317 period |**Optional.** Time period during which this dependency is enabled.
318 states |**Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
320 Available state filters:
329 When using [apply rules](3-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
330 automatically determined by Icinga 2.
332 Service-to-Host Dependency Example:
334 apply Dependency "internet" to Service {
335 parent_host_name = "dsl-router"
336 disable_checks = true
338 assign where host.name != "dsl-router"
341 This example sets all service objects matching the assign condition into a dependency relation to
342 the parent host object `dsl-router` as implicit child services.
344 Service-to-Service-on-the-same-Host Dependency Example:
346 apply Dependency "disable-nrpe-checks" to Service {
347 parent_service_name = "nrpe-health"
349 assign where service.check_command == "nrpe"
350 ignore where service.name == "nrpe-health"
353 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
354 host object matched by the apply rule condition. All services where apply matches are made implicit child services
355 in this dependency relation.
358 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
359 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
360 `child_service_name` attributes has a different value.
362 ## <a id="objecttype-downtime"></a> Downtime
364 Downtimes created at runtime are represented as objects.
368 object Downtime "localhost!my-downtime" {
369 host_name = "localhost"
370 author = "icingaadmin"
371 text = "This is a comment."
374 Configuration Attributes:
377 ----------------|----------------
378 host_name | **Required.** The name of the host this comment belongs to.
379 service_name | **Optional.** The short name of the service this comment belongs to. If omitted this comment object is treated as host comment.
380 author | **Required.** The author's name.
381 comment | **Required.** The comment text.
382 start_time | **Required.** The start time as unix timestamp.
383 end_time | **Required.** The end time as unix timestamp.
384 duration | **Required.** The duration as number.
385 entry_time | **Optional.** The unix timestamp when this downtime was added.
386 fixed | **Optional.** Whether the downtime is fixed (true) or flexible (false). Defaults to flexible. Details in the [advanced topics chapter](5-advanced-topics.md#fixed-flexible-downtimes).
387 triggers | **Optional.** List of downtimes which should be triggered by this downtime.
392 ----------------|----------------
393 trigger_time | The unix timestamp when this downtime was triggered.
394 triggered_by | The name of the downtime this downtime was triggered by.
398 ## <a id="objecttype-endpoint"></a> Endpoint
400 Endpoint objects are used to specify connection information for remote
405 object Endpoint "icinga2b" {
406 host = "192.168.5.46"
410 Configuration Attributes:
413 ----------------|----------------
414 host |**Optional.** The hostname/IP address of the remote Icinga 2 instance.
415 port |**Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
416 log_duration |**Optional.** Duration for keeping replay logs on connection loss. Defaults to `1d`.
419 ## <a id="objecttype-eventcommand"></a> EventCommand
421 An event command definition.
425 object EventCommand "restart-httpd-event" {
426 import "plugin-event-command"
428 command = "/opt/bin/restart-httpd.sh"
432 Configuration Attributes:
435 ----------------|----------------
436 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.
437 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.
438 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
439 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
440 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
441 arguments |**Optional.** A dictionary of command arguments.
443 Command arguments can be used the same way as for [CheckCommand objects](6-object-types.md#objecttype-checkcommand-arguments).
446 ## <a id="objecttype-externalcommandlistener"></a> ExternalCommandListener
448 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
454 object ExternalCommandListener "external" {
455 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
458 Configuration Attributes:
461 ----------------|----------------
462 command\_path |**Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
466 ## <a id="objecttype-filelogger"></a> FileLogger
468 Specifies Icinga 2 logging to a file.
472 object FileLogger "debug-file" {
474 path = "/var/log/icinga2/debug.log"
477 Configuration Attributes:
480 ----------------|----------------
481 path |**Required.** The log path.
482 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
485 ## <a id="objecttype-gelfwriter"></a> GelfWriter
487 Writes event log entries to a defined GELF receiver host (Graylog2, Logstash).
493 object GelfWriter "gelf" {
498 Configuration Attributes:
501 ----------------------|----------------------
502 host |**Optional.** GELF receiver host address. Defaults to '127.0.0.1'.
503 port |**Optional.** GELF receiver port. Defaults to `12201`.
504 source |**Optional.** Source name for this instance. Defaults to `icinga2`.
507 ## <a id="objecttype-graphitewriter"></a> GraphiteWriter
509 Writes check result metrics and performance data to a defined
510 Graphite Carbon host.
516 object GraphiteWriter "graphite" {
521 Configuration Attributes:
524 ----------------------|----------------------
525 host |**Optional.** Graphite Carbon host address. Defaults to '127.0.0.1'.
526 port |**Optional.** Graphite Carbon port. Defaults to 2003.
527 host_name_template |**Optional.** Metric prefix for host name. Defaults to "icinga2.$host.name$.host.$host.check_command$".
528 service_name_template |**Optional.** Metric prefix for service name. Defaults to "icinga2.$host.name$.services.$service.name$.$service.check_command$".
529 enable_send_thresholds | **Optional.** Send additional threshold metrics. Defaults to `false`.
530 enable_send_metadata | **Optional.** Send additional metadata metrics. Defaults to `false`.
531 enable_legacy_mode | **Optional.** Enable legacy mode for schema < 2.4. **Note**: This will be removed in future versions.
533 Additional usage examples can be found [here](15-features.md#graphite-carbon-cache-writer).
537 ## <a id="objecttype-host"></a> Host
543 object Host NodeName {
544 display_name = "Local host on this node"
545 address = "127.0.0.1"
548 groups = [ "all-hosts" ]
550 check_command = "hostalive"
553 Configuration Attributes:
556 ----------------|----------------
557 display_name |**Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
558 address |**Optional.** The host's address. Available as command runtime macro `$address$` if set.
559 address6 |**Optional.** The host's address. Available as command runtime macro `$address6$` if set.
560 groups |**Optional.** A list of host groups this host belongs to.
561 vars |**Optional.** A dictionary containing custom attributes that are specific to this host.
562 check\_command |**Required.** The name of the check command.
563 max\_check\_attempts|**Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
564 check\_period |**Optional.** The name of a time period which determines when this host should be checked. Not set by default.
565 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.
566 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.
567 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
568 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
569 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
570 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
571 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
572 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
573 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.
574 flapping\_threshold|**Optional.** The flapping threshold in percent when a host is considered to be flapping.
575 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
576 zone |**Optional.** The zone this object is a member of.
577 command\_endpoint|**Optional.** The endpoint where commands are executed on.
578 notes |**Optional.** Notes for the host.
579 notes\_url |**Optional.** Url for notes for the host (for example, in notification commands).
580 action\_url |**Optional.** Url for actions for the host (for example, an external graphing tool).
581 icon\_image |**Optional.** Icon image for the host. Used by external interfaces only.
582 icon\_image\_alt|**Optional.** Icon image description for the host. Used by external interface only.
586 > The `address` and `address6` attributes are required for running commands using
587 > the `$address$` and `$address6$` runtime macros.
591 Name | Type | Description
592 --------------------------|---------------|-----------------
593 next\_check | Number | When the next check occurs (as a UNIX timestamp).
594 check\_attempt | Number | The current check attempt number.
595 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
596 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
597 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
598 last\_check\_result | CheckResult | The current check result.
599 last\_state\_change | Number | When the last state change occurred (as a UNIX timestamp).
600 last\_hard\_state\_change | Number | When the last hard state change occurred (as a UNIX timestamp).
601 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
602 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
603 acknowledgement_expiry | Number | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
604 flapping_last_change | Number | When the last flapping change occurred (as a UNIX timestamp).
605 flapping | Boolean | Whether the host is flapping between states.
606 state | Number | The current state (0 = UP, 1 = DOWN).
607 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
608 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
612 ## <a id="objecttype-hostgroup"></a> HostGroup
618 > Assign host group members using the [group assign](18-language-reference.md#group-assign) rules.
622 object HostGroup "my-hosts" {
623 display_name = "My hosts"
626 Configuration Attributes:
629 ----------------|----------------
630 display_name |**Optional.** A short description of the host group.
631 groups |**Optional.** An array of nested group names.
633 ## <a id="objecttype-icingaapplication"></a> IcingaApplication
635 The IcingaApplication object is required to start Icinga 2.
636 The object name must be `app`. If the object configuration
637 is missing Icinga 2 will automatically create an IcingaApplication
642 object IcingaApplication "app" {
643 enable_perfdata = false
646 Configuration Attributes:
649 ----------------------|--------------------------
650 enable_notifications |**Optional.** Whether notifications are globally enabled. Defaults to true.
651 enable_event_handlers |**Optional.** Whether event handlers are globally enabled. Defaults to true.
652 enable_flapping |**Optional.** Whether flap detection is globally enabled. Defaults to true.
653 enable_host_checks |**Optional.** Whether active host checks are globally enabled. Defaults to true.
654 enable_service_checks |**Optional.** Whether active service checks are globally enabled. Defaults to true.
655 enable_perfdata |**Optional.** Whether performance data processing is globally enabled. Defaults to true.
656 vars |**Optional.** A dictionary containing custom attributes that are available globally.
658 ## <a id="objecttype-icingastatuswriter"></a> IcingaStatusWriter
662 > This feature was deprecated in 2.4 and will be removed in future releases.
664 The IcingaStatusWriter feature periodically dumps the current status
665 and performance data from Icinga 2 and all registered features into
670 object IcingaStatusWriter "status" {
671 status_path = LocalStateDir + "/cache/icinga2/status.json"
672 update_interval = 15s
675 Configuration Attributes:
678 --------------------------|--------------------------
679 status\_path |**Optional.** Path to cluster status file. Defaults to LocalStateDir + "/cache/icinga2/status.json"
680 update\_interval |**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
683 ## <a id="objecttype-idomysqlconnection"></a> IdoMySqlConnection
685 IDO database adapter for MySQL.
689 library "db_ido_mysql"
691 object IdoMysqlConnection "mysql-ido" {
697 table_prefix = "icinga_"
698 instance_name = "icinga2"
699 instance_description = "icinga2 instance"
702 downtimehistory_age = 48h
706 categories = DbCatConfig | DbCatState
709 Configuration Attributes:
712 ----------------|----------------
713 host |**Optional.** MySQL database host address. Defaults to "localhost".
714 port |**Optional.** MySQL database port. Defaults to 3306.
715 socket_path |**Optional.** MySQL socket path.
716 user |**Optional.** MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
717 password |**Optional.** MySQL database user's password. Defaults to "icinga".
718 database |**Optional.** MySQL database name. Defaults to "icinga".
719 table\_prefix |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
720 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
721 instance\_description|**Optional.** Description for the Icinga 2 instance.
722 enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](13-distributed-monitoring-ha.md#high-availability-db-ido). Defaults to "true".
723 failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](13-distributed-monitoring-ha.md#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
724 cleanup |**Optional.** Dictionary with items for historical table cleanup.
725 categories |**Optional.** The types of information that should be written to the database.
730 ----------------|----------------
731 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
732 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
733 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
734 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
735 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
736 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
737 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
738 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
739 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
740 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
741 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
742 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
743 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
744 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
745 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
749 Name | Description | Required by
750 ---------------------|------------------------|--------------------
751 DbCatConfig | Configuration data | Icinga Web 2
752 DbCatState | Current state data | Icinga Web 2
753 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
754 DbCatComment | Comments | Icinga Web 2
755 DbCatDowntime | Downtimes | Icinga Web 2
756 DbCatEventHandler | Event handler data | Icinga Web 2
757 DbCatExternalCommand | External commands | Icinga Web 2
758 DbCatFlapping | Flap detection data | Icinga Web 2
759 DbCatCheck | Check results | --
760 DbCatLog | Log messages | Icinga Web 2
761 DbCatNotification | Notifications | Icinga Web 2
762 DbCatProgramStatus | Program status data | Icinga Web 2
763 DbCatRetention | Retention data | Icinga Web 2
764 DbCatStateHistory | Historical state data | Icinga Web 2
766 Multiple categories can be combined using the `|` operator. In addition to
767 the category flags listed above the `DbCatEverything` flag may be used as
768 a shortcut for listing all flags.
770 External interfaces like Icinga Web 2 require everything except `DbCatCheck`
771 which is the default value if `categories` is not set.
773 ## <a id="objecttype-idopgsqlconnection"></a> IdoPgSqlConnection
775 IDO database adapter for PostgreSQL.
779 library "db_ido_pgsql"
781 object IdoMysqlConnection "pgsql-ido" {
787 table_prefix = "icinga_"
788 instance_name = "icinga2"
789 instance_description = "icinga2 instance"
792 downtimehistory_age = 48h
796 categories = DbCatConfig | DbCatState
799 Configuration Attributes:
802 ----------------|----------------
803 host |**Optional.** PostgreSQL database host address. Defaults to "localhost".
804 port |**Optional.** PostgreSQL database port. Defaults to "5432".
805 user |**Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to "icinga".
806 password |**Optional.** PostgreSQL database user's password. Defaults to "icinga".
807 database |**Optional.** PostgreSQL database name. Defaults to "icinga".
808 table\_prefix |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_".
809 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
810 instance\_description|**Optional.** Description for the Icinga 2 instance.
811 enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](13-distributed-monitoring-ha.md#high-availability-db-ido). Defaults to "true".
812 failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](13-distributed-monitoring-ha.md#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
813 cleanup |**Optional.** Dictionary with items for historical table cleanup.
814 categories |**Optional.** The types of information that should be written to the database.
819 ----------------|----------------
820 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
821 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
822 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
823 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
824 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
825 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
826 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
827 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
828 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
829 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
830 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
831 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
832 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
833 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
834 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
838 Name | Description | Required by
839 ---------------------|------------------------|--------------------
840 DbCatConfig | Configuration data | Icinga Web 2
841 DbCatState | Current state data | Icinga Web 2
842 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
843 DbCatComment | Comments | Icinga Web 2
844 DbCatDowntime | Downtimes | Icinga Web 2
845 DbCatEventHandler | Event handler data | Icinga Web 2
846 DbCatExternalCommand | External commands | Icinga Web 2
847 DbCatFlapping | Flap detection data | Icinga Web 2
848 DbCatCheck | Check results | --
849 DbCatLog | Log messages | Icinga Web 2
850 DbCatNotification | Notifications | Icinga Web 2
851 DbCatProgramStatus | Program status data | Icinga Web 2
852 DbCatRetention | Retention data | Icinga Web 2
853 DbCatStateHistory | Historical state data | Icinga Web 2
855 Multiple categories can be combined using the `|` operator. In addition to
856 the category flags listed above the `DbCatEverything` flag may be used as
857 a shortcut for listing all flags.
859 External interfaces like Icinga Web 2 require everything except `DbCatCheck`
860 which is the default value if `categories` is not set.
863 ## <a id="objecttype-livestatuslistener"></a> LiveStatusListener
865 Livestatus API interface available as TCP or UNIX socket. Historical table queries
866 require the [CompatLogger](6-object-types.md#objecttype-compatlogger) feature enabled
867 pointing to the log files using the `compat_log_path` configuration attribute.
873 object LivestatusListener "livestatus-tcp" {
875 bind_host = "127.0.0.1"
879 object LivestatusListener "livestatus-unix" {
881 socket_path = "/var/run/icinga2/cmd/livestatus"
884 Configuration Attributes:
887 ----------------|----------------
888 socket\_type |**Optional.** Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
889 bind\_host |**Optional.** Only valid when socket\_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
890 bind\_port |**Optional.** Only valid when `socket_type` is "tcp". Port to listen on for connections. Defaults to 6558.
891 socket\_path |**Optional.** Only valid when `socket_type` is "unix". Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus".
892 compat\_log\_path |**Optional.** Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"
896 > UNIX sockets are not supported on Windows.
899 ## <a id="objecttype-notification"></a> Notification
901 Notification objects are used to specify how users should be notified in case
902 of host and service state changes and other events.
906 > Rather than creating a `Notification` object for a specific host or service it is
907 > usually easier to just create a `Notification` template and use the `apply` keyword
908 > to assign the notification to a number of hosts or services. Use the `to` keyword
909 > to set the specific target type for `Host` or `Service`.
910 > Check the [notifications](3-monitoring-basics.md#notifications) chapter for detailed examples.
914 object Notification "localhost-ping-notification" {
915 host_name = "localhost"
916 service_name = "ping4"
918 command = "mail-notification"
920 users = [ "user1", "user2" ]
922 types = [ Problem, Recovery ]
925 Configuration Attributes:
928 --------------------------|----------------
929 host_name | **Required.** The name of the host this notification belongs to.
930 service_name | **Optional.** The short name of the service this notification belongs to. If omitted this notification object is treated as host notification.
931 vars | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
932 users | **Optional.** A list of user names who should be notified.
933 user_groups | **Optional.** A list of user group names who should be notified.
934 times | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
935 command | **Required.** The name of the notification command which should be executed when the notification is triggered.
936 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.
937 period | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
938 zone |**Optional.** The zone this object is a member of.
939 types | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
940 states | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
942 Available notification state filters for Service:
949 Available notification state filters for Host:
954 Available notification type filters:
968 Name | Type | Description
969 --------------------------|---------------|-----------------
970 last\_notification | Number | When the last notification was sent for this Notification object (as a UNIX timestamp).
971 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).
972 notification\_number | Number | The notification number
973 last\_problem\_notification | Number | When the last notification was sent for a problem (as a UNIX timestamp).
976 ## <a id="objecttype-notificationcommand"></a> NotificationCommand
978 A notification command definition.
982 object NotificationCommand "mail-service-notification" {
983 import "plugin-notification-command"
986 SysconfDir + "/icinga2/scripts/mail-notification.sh"
990 NOTIFICATIONTYPE = "$notification.type$"
991 SERVICEDESC = "$service.name$"
992 HOSTALIAS = "$host.display_name$"
993 HOSTADDRESS = "$address$"
994 SERVICESTATE = "$service.state$"
995 LONGDATETIME = "$icinga.long_date_time$"
996 SERVICEOUTPUT = "$service.output$"
997 NOTIFICATIONAUTHORNAME = "$notification.author$"
998 NOTIFICATIONCOMMENT = "$notification.comment$"
999 HOSTDISPLAYNAME = "$host.display_name$"
1000 SERVICEDISPLAYNAME = "$service.display_name$"
1001 USEREMAIL = "$user.email$"
1005 Configuration Attributes:
1008 ----------------|----------------
1009 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.
1010 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.
1011 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1012 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
1013 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
1014 arguments |**Optional.** A dictionary of command arguments.
1016 Command arguments can be used the same way as for [CheckCommand objects](6-object-types.md#objecttype-checkcommand-arguments).
1019 ## <a id="objecttype-notificationcomponent"></a> NotificationComponent
1021 The notification component is responsible for sending notifications. There are no configurable options.
1025 library "notification"
1027 object NotificationComponent "notification" { }
1029 Configuration Attributes:
1032 ----------------|----------------
1033 enable\_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](13-distributed-monitoring-ha.md#high-availability-notifications). Defaults to "true".
1035 ## <a id="objecttype-opentsdbwriter"></a> OpenTsdbWriter
1037 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1043 object OpenTsdbWriter "opentsdb" {
1048 Configuration Attributes:
1051 ----------------------|----------------------
1052 host |**Optional.** OpenTSDB host address. Defaults to '127.0.0.1'.
1053 port |**Optional.** OpenTSDB port. Defaults to 4242.
1056 ## <a id="objecttype-perfdatawriter"></a> PerfdataWriter
1058 Writes check result performance data to a defined path using macro
1059 pattern consisting of custom attributes and runtime macros.
1065 object PerfdataWriter "pnp" {
1066 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1068 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1070 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$"
1071 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$"
1073 rotation_interval = 15s
1076 Configuration Attributes:
1079 ------------------------|----------------
1080 host_perfdata\_path |**Optional.** Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
1081 service_perfdata\_path |**Optional.** Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
1082 host_temp\_path |**Optional.** Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
1083 service_temp\_path |**Optional.** Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
1084 host_format\_template |**Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1085 service_format\_template|**Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1086 rotation\_interval |**Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to 30 seconds.
1088 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1089 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1092 ## <a id="objecttype-scheduleddowntime"></a> ScheduledDowntime
1094 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1098 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1099 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1100 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1101 > type for `Host` or `Service`.
1102 > Check the [recurring downtimes](5-advanced-topics.md#recurring-downtimes) example for details.
1106 object ScheduledDowntime "some-downtime" {
1107 host_name = "localhost"
1108 service_name = "ping4"
1110 author = "icingaadmin"
1111 comment = "Some comment"
1117 "sunday" = "02:00-03:00"
1121 Configuration Attributes:
1124 ----------------|----------------
1125 host_name |**Required.** The name of the host this scheduled downtime belongs to.
1126 service_name |**Optional.** The short name of the service this scheduled downtime belongs to. If omitted this downtime object is treated as host downtime.
1127 author |**Required.** The author of the downtime.
1128 comment |**Required.** A comment for the downtime.
1129 fixed |**Optional.** Whether this is a fixed downtime. Defaults to true.
1130 duration |**Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1131 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1133 ScheduledDowntime objects have composite names, i.e. their names are based
1134 on the `host_name` and `service_name` attributes and the
1135 name you specified. This means you can define more than one object
1136 with the same (short) name as long as one of the `host_name` and
1137 `service_name` attributes has a different value.
1140 ## <a id="objecttype-service"></a> Service
1142 Service objects describe network services and how they should be checked
1147 > Rather than creating a `Service` object for a specific host it is usually easier
1148 > to just create a `Service` template and use the `apply` keyword to assign the
1149 > service to a number of hosts.
1150 > Check the [apply](3-monitoring-basics.md#using-apply) chapter for details.
1154 object Service "uptime" {
1155 host_name = "localhost"
1157 display_name = "localhost Uptime"
1159 check_command = "check_snmp"
1161 vars.community = "public"
1162 vars.oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1164 check_interval = 60s
1165 retry_interval = 15s
1167 groups = [ "all-services", "snmp" ]
1170 Configuration Attributes:
1173 ----------------|----------------
1174 display_name |**Optional.** A short description of the service.
1175 host_name |**Required.** The host this service belongs to. There must be a `Host` object with that name.
1176 name |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
1177 groups |**Optional.** The service groups this service belongs to.
1178 vars |**Optional.** A dictionary containing custom attributes that are specific to this service.
1179 check\_command |**Required.** The name of the check command.
1180 max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1181 check\_period |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1182 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.
1183 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.
1184 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
1185 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
1186 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
1187 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
1188 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
1189 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
1190 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.
1191 flapping\_threshold|**Optional.** The flapping threshold in percent when a service is considered to be flapping.
1192 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
1193 zone |**Optional.** The zone this object is a member of.
1194 command\_endpoint|**Optional.** The endpoint where commands are executed on.
1195 notes |**Optional.** Notes for the service.
1196 notes\_url |**Optional.** Url for notes for the service (for example, in notification commands).
1197 action_url |**Optional.** Url for actions for the service (for example, an external graphing tool).
1198 icon\_image |**Optional.** Icon image for the service. Used by external interfaces only.
1199 icon\_image\_alt|**Optional.** Icon image description for the service. Used by external interface only.
1201 Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
1202 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1206 Name | Type | Description
1207 --------------------------|---------------|-----------------
1208 next\_check | Number | When the next check occurs (as a UNIX timestamp).
1209 check\_attempt | Number | The current check attempt number.
1210 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1211 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1212 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1213 last\_check\_result | CheckResult | The current check result.
1214 last\_state\_change | Number | When the last state change occurred (as a UNIX timestamp).
1215 last\_hard\_state\_change | Number | When the last hard state change occurred (as a UNIX timestamp).
1216 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1217 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1218 acknowledgement_expiry | Number | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1219 flapping_last_change | Number | When the last flapping change occurred (as a UNIX timestamp).
1220 flapping | Boolean | Whether the host is flapping between states.
1221 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1222 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1223 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1226 ## <a id="objecttype-servicegroup"></a> ServiceGroup
1228 A group of services.
1232 > Assign service group members using the [group assign](18-language-reference.md#group-assign) rules.
1236 object ServiceGroup "snmp" {
1237 display_name = "SNMP services"
1240 Configuration Attributes:
1243 ----------------|----------------
1244 display_name |**Optional.** A short description of the service group.
1245 groups |**Optional.** An array of nested group names.
1248 ## <a id="objecttype-statusdatawriter"></a> StatusDataWriter
1250 Periodically writes status data files which are used by the Classic UI and other third-party tools.
1256 object StatusDataWriter "status" {
1257 status_path = "/var/cache/icinga2/status.dat"
1258 objects_path = "/var/cache/icinga2/objects.cache"
1259 update_interval = 30s
1262 Configuration Attributes:
1265 ----------------|----------------
1266 status\_path |**Optional.** Path to the status.dat file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
1267 objects\_path |**Optional.** Path to the objects.cache file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
1268 update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
1271 ## <a id="objecttype-sysloglogger"></a> SyslogLogger
1273 Specifies Icinga 2 logging to syslog.
1277 object SyslogLogger "crit-syslog" {
1278 severity = "critical"
1281 Configuration Attributes:
1284 ----------------|----------------
1285 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1288 ## <a id="objecttype-timeperiod"></a> TimePeriod
1290 Time periods can be used to specify when hosts/services should be checked or to limit
1291 when notifications should be sent out.
1295 object TimePeriod "nonworkhours" {
1296 import "legacy-timeperiod"
1298 display_name = "Icinga 2 TimePeriod for non working hours"
1301 monday = "00:00-8:00,17:00-24:00"
1302 tuesday = "00:00-8:00,17:00-24:00"
1303 wednesday = "00:00-8:00,17:00-24:00"
1304 thursday = "00:00-8:00,17:00-24:00"
1305 friday = "00:00-8:00,16:00-24:00"
1306 saturday = "00:00-24:00"
1307 sunday = "00:00-24:00"
1311 object TimePeriod "exampledays" {
1312 import "legacy-timeperiod"
1314 display_name = "Icinga 2 TimePeriod for random example days"
1317 //We still believe in Santa, no peeking!
1318 //Applies every 25th of December every year
1319 "december 25" = "00:00-24:00"
1321 //Any point in time can be specified,
1322 //but you still have to use a range
1323 "2038-01-19" = "03:13-03:15"
1325 //Evey 3rd day from the second monday of February
1326 //to 8th of November
1327 "monday 2 february - november 8 / 3" = "00:00-24:00"
1332 Additional examples can be found [within the icinga documentation](http://docs.icinga.org/latest/en/objectdefinitions.html#objectdefinitions-timeperiod).
1334 Configuration Attributes:
1337 ----------------|----------------
1338 display_name |**Optional.** A short description of the time period.
1339 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.
1340 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1342 The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define
1343 timeperiods including this one.
1347 Name | Type | Description
1348 --------------------------|---------------|-----------------
1349 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1352 ## <a id="objecttype-user"></a> User
1358 object User "icingaadmin" {
1359 display_name = "Icinga 2 Admin"
1360 groups = [ "icingaadmins" ]
1361 email = "icinga@localhost"
1362 pager = "icingaadmin@localhost.localdomain"
1366 states = [ OK, Warning, Critical, Unknown ]
1367 types = [ Problem, Recovery ]
1369 vars.additional_notes = "This is the Icinga 2 Admin account."
1372 Available notification state filters:
1381 Available notification type filters:
1393 Configuration Attributes:
1396 ----------------|----------------
1397 display_name |**Optional.** A short description of the user.
1398 email |**Optional.** An email string for this user. Useful for notification commands.
1399 pager |**Optional.** A pager string for this user. Useful for notification commands.
1400 vars |**Optional.** A dictionary containing custom attributes that are specific to this user.
1401 groups |**Optional.** An array of group names.
1402 enable_notifications|**Optional.** Whether notifications are enabled for this user.
1403 period |**Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default.
1404 types |**Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
1405 states |**Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
1409 Name | Type | Description
1410 --------------------------|---------------|-----------------
1411 last\_notification | Number | When the last notification was sent for this user (as a UNIX timestamp).
1413 ## <a id="objecttype-usergroup"></a> UserGroup
1419 > Assign user group members using the [group assign](18-language-reference.md#group-assign) rules.
1423 object UserGroup "icingaadmins" {
1424 display_name = "Icinga 2 Admin Group"
1427 Configuration Attributes:
1430 ----------------|----------------
1431 display_name |**Optional.** A short description of the user group.
1432 groups |**Optional.** An array of nested group names.
1435 ## <a id="objecttype-zone"></a> Zone
1437 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1441 object Zone "config-ha-master" {
1442 endpoints = [ "icinga2a", "icinga2b" ]
1446 object Zone "check-satellite" {
1447 endpoints = [ "icinga2c" ]
1448 parent = "config-ha-master"
1451 Configuration Attributes:
1454 ----------------|----------------
1455 endpoints |**Optional.** Dictionary with endpoints located in this zone.
1456 parent |**Optional.** The name of the parent zone.
1457 global |**Optional.** Whether configuration files for this zone should be synced to all endpoints. Defaults to false.
1461 # <a id="value-types"></a> Value Types
1463 In addition to [expressions](18-language-reference.md#expressions)
1464 used in object attribute assignments such as
1466 * [Numeric](18-language-reference.md#numeric-literals), [duration](8-language-reference.md#duration-literals), [string](18-language-reference.md#string-literals) and [boolean](18-language-reference.md#boolean-literals) literals
1467 * [Array](18-language-reference.md#array)
1468 * [Dictionary](18-language-reference.md#dictionary)
1470 Icinga 2 uses the following value types for runtime attributes
1471 exposed via the [Icinga 2 API](9-icinga2-api.md#icinga2-api).
1473 ## <a id="value-types-checkresult"></a> CheckResult
1475 Name | Type | Description
1476 --------------------------|---------------|-----------------
1477 exit_status | Number | The exit status returned by the check execution.
1478 output | String | The check output.
1479 performance_data | Array | Array of [performance data values](6-object-types.md#value-types-perfdatavalue).
1480 check_source | String | Name of the node executing the check.
1481 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1482 command | Value | Array of command with shell-escaped arguments or command line string.
1483 execution_start | Number | Check execution start time (as a UNIX timestamp).
1484 execution_end | Number | Check execution end time (as a UNIX timestamp).
1485 schedule_start | Number | Scheduled check execution start time (as a UNIX timestamp).
1486 schedule_end | Number | Scheduled check execution end time (as a UNIX timestamp).
1487 active | Boolean | Whether the result is from an active or passive check.
1488 vars_before | Dictionary | Internal attribute used for calculations.
1489 vars_after | Dictionary | Internal attribute used for calculations.
1491 ## <a id="value-types-perfdatavalue"></a> PerfdataValue
1493 Icinga 2 parses performance data strings and exposes
1494 the object to external interfaces (e.g. [GraphiteWriter](6-object-types.md#objecttype-graphitewriter) or the [Icinga 2 API](9-icinga2-api.md#icinga2-api)).
1496 Name | Type | Description
1497 --------------------------|---------------|-----------------
1498 label | String | Performance data label.
1499 value | Number | Normalized performance data value without unit.
1500 counter | Boolean | Enabled if the original value contains `c` as unit. Defaults to `false`.
1501 unit | String | Unit of measurement (`seconds`, `bytes`. `percent`) according to the [plugin API](14-addons-plugins.md#plugin-api).
1502 crit | Value | Critical threshold value.
1503 warn | Value | Warning threshold value.
1504 min | Value | Minimum value returned by the check.
1505 max | Value | Maximum value returned by the check.