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 and API usage specifying the certificate files used for ssl
13 authorization and additional restrictions.
15 The `NodeName` constant must be defined in [constants.conf](4-configuring-icinga-2.md#constants-conf).
19 object ApiListener "api" {
20 cert_path = SysconfDir + "/icinga2/pki/" + NodeName + ".crt"
21 key_path = SysconfDir + "/icinga2/pki/" + NodeName + ".key"
22 ca_path = SysconfDir + "/icinga2/pki/ca.crt"
26 Configuration Attributes:
29 --------------------------|--------------------------
30 cert\_path |**Required.** Path to the public key.
31 key\_path |**Required.** Path to the private key.
32 ca\_path |**Required.** Path to the CA certificate file.
33 crl\_path |**Optional.** Path to the CRL file.
34 bind\_host |**Optional.** The IP address the api listener should be bound to. Defaults to `0.0.0.0`.
35 bind\_port |**Optional.** The port the api listener should be bound to. Defaults to `5665`.
36 accept\_config |**Optional.** Accept zone configuration. Defaults to `false`.
37 accept\_commands |**Optional.** Accept remote commands. Defaults to `false`.
39 ## <a id="objecttype-apiuser"></a> ApiUser
41 ApiUser objects are used for authentication against the Icinga 2 API.
45 object ApiUser "root" {
46 password = "mysecretapipassword"
51 Configuration Attributes:
54 --------------------------|--------------------------
55 password |**Optional.** Password string.
56 client\_cn |**Optional.** Client Common Name (CN).
57 permissions |**Required.** Array of permissions. Either as string or dictionary with the keys `permission` and `filter`. The latter must be specified as function.
59 Available permissions are described in the [API permissions](9-icinga2-api.md#icinga2-api-permissions)
62 ## <a id="objecttype-checkcommand"></a> CheckCommand
64 A check command definition. Additional default command custom attributes can be
69 object CheckCommand "check_http" {
70 import "plugin-check-command"
72 command = [ PluginDir + "/check_http" ]
76 "-I" = "$http_address$"
86 value = "$http_auth_pair$"
87 description = "Username:password on sites with basic authentication"
90 set_if = "$http_ignore_body$"
92 "-r" = "$http_expect_body_regex$"
93 "-w" = "$http_warn_time$"
94 "-c" = "$http_critical_time$"
95 "-e" = "$http_expect$"
98 vars.http_address = "$address$"
100 vars.http_sni = false
104 Configuration Attributes:
107 ----------------|----------------
108 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.
109 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.
110 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
111 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
112 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
113 arguments |**Optional.** A dictionary of command arguments.
116 ### <a id="objecttype-checkcommand-arguments"></a> CheckCommand Arguments
118 Command arguments can be defined as key-value-pairs in the `arguments`
119 dictionary. If the argument requires additional configuration for example
120 a `description` attribute or an optional condition, the value can be defined
121 as dictionary specifying additional options.
125 vars.x_val = "My command argument value."
133 key = "-Xnew" /* optional, set a new key identifier */
134 description = "My plugin requires this argument for doing X."
135 required = false /* optional, no error if not set */
136 skip_key = false /* always use "-X <value>" */
137 set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
138 order = -1 /* first position */
139 repeat_key = true /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
143 description = "My plugin requires this argument for doing Y."
144 required = false /* optional, no error if not set */
145 skip_key = true /* don't prefix "-Y" only use "<value>" */
146 set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
147 order = 0 /* second position */
148 repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
153 ------------|--------------
154 value | Optional argument value set by a macro string or a function call.
155 key | Optional argument key overriding the key identifier.
156 description | Optional argument description.
157 required | Required argument. Execution error if not set. Defaults to false (optional).
158 skip_key | Use the value as argument and skip the key.
159 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.
160 order | Set if multiple arguments require a defined argument order.
161 repeat_key | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
165 `..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...`
167 Argument array `repeat_key = true`:
169 `'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'`
171 Argument array `repeat_key = false`:
173 `'key' 'value[0]' 'value[1]' 'value[2]'`
175 ## <a id="objecttype-checkcomponent"></a> CheckerComponent
177 The checker component is responsible for scheduling active checks. There are no configurable options.
183 object CheckerComponent "checker" { }
185 ## <a id="objecttype-checkresultreader"></a> CheckResultReader
187 Reads Icinga 1.x check results from a directory. This functionality is provided
188 to help existing Icinga 1.x users and might be useful for certain cluster
195 object CheckResultReader "reader" {
196 spool_dir = "/data/check-results"
199 Configuration Attributes:
202 ----------------|----------------
203 spool\_dir |**Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/".
205 ## <a id="objecttype-comment"></a> Comment
207 Comments created at runtime are represented as objects.
211 object Comment "localhost!my-comment" {
212 host_name = "localhost"
213 author = "icingaadmin"
214 text = "This is a comment."
217 Configuration Attributes:
220 ----------------|----------------
221 host_name | **Required.** The name of the host this comment belongs to.
222 service_name | **Optional.** The short name of the service this comment belongs to. If omitted this comment object is treated as host comment.
223 author | **Required.** The author's name.
224 text | **Required.** The comment text.
225 entry_time | **Optional.** The unix timestamp when this comment was added.
226 entry_type | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
227 expire_time | **Optional.** The comment's expire time as unix timestamp.
229 ## <a id="objecttype-compatlogger"></a> CompatLogger
231 Writes log files in a format that's compatible with Icinga 1.x.
237 object CompatLogger "my-log" {
238 log_dir = "/var/log/icinga2/compat"
239 rotation_method = "HOURLY"
242 Configuration Attributes:
245 ----------------|----------------
246 log\_dir |**Optional.** Path to the compat log directory. Defaults to LocalStateDir + "/log/icinga2/compat".
247 rotation\_method|**Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
251 ## <a id="objecttype-dependency"></a> Dependency
253 Dependency objects are used to specify dependencies between hosts and services. Dependencies
254 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
259 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
260 > to just create a `Dependency` template and use the `apply` keyword to assign the
261 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
262 > type for `Host` or `Service`.
263 > Check the [dependencies](3-monitoring-basics.md#dependencies) chapter for detailed examples.
265 Service-to-Service Example:
267 object Dependency "webserver-internet" {
268 parent_host_name = "internet"
269 parent_service_name = "ping4"
271 child_host_name = "webserver"
272 child_service_name = "ping4"
274 states = [ OK, Warning ]
276 disable_checks = true
279 Host-to-Host Example:
281 object Dependency "webserver-internet" {
282 parent_host_name = "internet"
284 child_host_name = "webserver"
288 disable_checks = true
291 Configuration Attributes:
294 ----------------------|----------------
295 parent_host_name |**Required.** The parent host.
296 parent_service_name |**Optional.** The parent service. If omitted this dependency object is treated as host dependency.
297 child_host_name |**Required.** The child host.
298 child_service_name |**Optional.** The child service. If omitted this dependency object is treated as host dependency.
299 disable_checks |**Optional.** Whether to disable checks when this dependency fails. Defaults to false.
300 disable_notifications |**Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
301 ignore_soft_states |**Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
302 period |**Optional.** Time period during which this dependency is enabled.
303 states |**Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
305 Available state filters:
314 When using [apply rules](3-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
315 automatically determined by Icinga 2.
317 Service-to-Host Dependency Example:
319 apply Dependency "internet" to Service {
320 parent_host_name = "dsl-router"
321 disable_checks = true
323 assign where host.name != "dsl-router"
326 This example sets all service objects matching the assign condition into a dependency relation to
327 the parent host object `dsl-router` as implicit child services.
329 Service-to-Service-on-the-same-Host Dependency Example:
331 apply Dependency "disable-nrpe-checks" to Service {
332 parent_service_name = "nrpe-health"
334 assign where service.check_command == "nrpe"
335 ignore where service.name == "nrpe-health"
338 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
339 host object matched by the apply rule condition. All services where apply matches are made implicit child services
340 in this dependency relation.
343 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
344 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
345 `child_service_name` attributes has a different value.
347 ## <a id="objecttype-downtime"></a> Downtime
349 Downtimes created at runtime are represented as objects.
353 object Downtime "localhost!my-downtime" {
354 host_name = "localhost"
355 author = "icingaadmin"
356 text = "This is a comment."
359 Configuration Attributes:
362 ----------------|----------------
363 host_name | **Required.** The name of the host this comment belongs to.
364 service_name | **Optional.** The short name of the service this comment belongs to. If omitted this comment object is treated as host comment.
365 author | **Required.** The author's name.
366 comment | **Required.** The comment text.
367 start_time | **Required.** The start time as unix timestamp.
368 end_time | **Required.** The end time as unix timestamp.
369 duration | **Required.** The duration as number.
370 entry_time | **Optional.** The unix timestamp when this downtime was added.
371 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).
372 triggers | **Optional.** List of downtimes which should be triggered by this downtime.
377 ----------------|----------------
378 trigger_time | The unix timestamp when this downtime was triggered.
379 triggered_by | The name of the downtime this downtime was triggered by.
383 ## <a id="objecttype-endpoint"></a> Endpoint
385 Endpoint objects are used to specify connection information for remote
390 object Endpoint "icinga2b" {
391 host = "192.168.5.46"
395 Configuration Attributes:
398 ----------------|----------------
399 host |**Optional.** The hostname/IP address of the remote Icinga 2 instance.
400 port |**Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
401 log_duration |**Optional.** Duration for keeping replay logs on connection loss. Defaults to `1d`.
404 ## <a id="objecttype-eventcommand"></a> EventCommand
406 An event command definition.
410 object EventCommand "restart-httpd-event" {
411 import "plugin-event-command"
413 command = "/opt/bin/restart-httpd.sh"
417 Configuration Attributes:
420 ----------------|----------------
421 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.
422 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.
423 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
424 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
425 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
426 arguments |**Optional.** A dictionary of command arguments.
428 Command arguments can be used the same way as for [CheckCommand objects](6-object-types.md#objecttype-checkcommand-arguments).
431 ## <a id="objecttype-externalcommandlistener"></a> ExternalCommandListener
433 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
439 object ExternalCommandListener "external" {
440 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
443 Configuration Attributes:
446 ----------------|----------------
447 command\_path |**Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
451 ## <a id="objecttype-filelogger"></a> FileLogger
453 Specifies Icinga 2 logging to a file.
457 object FileLogger "debug-file" {
459 path = "/var/log/icinga2/debug.log"
462 Configuration Attributes:
465 ----------------|----------------
466 path |**Required.** The log path.
467 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
470 ## <a id="objecttype-gelfwriter"></a> GelfWriter
472 Writes event log entries to a defined GELF receiver host (Graylog2, Logstash).
478 object GelfWriter "gelf" {
483 Configuration Attributes:
486 ----------------------|----------------------
487 host |**Optional.** GELF receiver host address. Defaults to '127.0.0.1'.
488 port |**Optional.** GELF receiver port. Defaults to `12201`.
489 source |**Optional.** Source name for this instance. Defaults to `icinga2`.
492 ## <a id="objecttype-graphitewriter"></a> GraphiteWriter
494 Writes check result metrics and performance data to a defined
495 Graphite Carbon host.
501 object GraphiteWriter "graphite" {
506 Configuration Attributes:
509 ----------------------|----------------------
510 host |**Optional.** Graphite Carbon host address. Defaults to '127.0.0.1'.
511 port |**Optional.** Graphite Carbon port. Defaults to 2003.
512 host_name_template |**Optional.** Metric prefix for host name. Defaults to "icinga2.$host.name$.host.$host.check_command$".
513 service_name_template |**Optional.** Metric prefix for service name. Defaults to "icinga2.$host.name$.services.$service.name$.$service.check_command$".
514 enable_send_thresholds | **Optional.** Send additional threshold metrics. Defaults to `false`.
515 enable_send_metadata | **Optional.** Send additional metadata metrics. Defaults to `false`.
516 enable_legacy_mode | **Optional.** Enable legacy mode for schema < 2.4. **Note**: This will be removed in future versions.
518 Additional usage examples can be found [here](15-features.md#graphite-carbon-cache-writer).
522 ## <a id="objecttype-host"></a> Host
528 object Host NodeName {
529 display_name = "Local host on this node"
530 address = "127.0.0.1"
533 groups = [ "all-hosts" ]
535 check_command = "hostalive"
538 Configuration Attributes:
541 ----------------|----------------
542 display_name |**Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
543 address |**Optional.** The host's address. Available as command runtime macro `$address$` if set.
544 address6 |**Optional.** The host's address. Available as command runtime macro `$address6$` if set.
545 groups |**Optional.** A list of host groups this host belongs to.
546 vars |**Optional.** A dictionary containing custom attributes that are specific to this host.
547 check\_command |**Required.** The name of the check command.
548 max\_check\_attempts|**Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
549 check\_period |**Optional.** The name of a time period which determines when this host should be checked. Not set by default.
550 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.
551 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.
552 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
553 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
554 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
555 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
556 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
557 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
558 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.
559 flapping\_threshold|**Optional.** The flapping threshold in percent when a host is considered to be flapping.
560 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
561 zone |**Optional.** The zone this object is a member of.
562 command\_endpoint|**Optional.** The endpoint where commands are executed on.
563 notes |**Optional.** Notes for the host.
564 notes\_url |**Optional.** Url for notes for the host (for example, in notification commands).
565 action\_url |**Optional.** Url for actions for the host (for example, an external graphing tool).
566 icon\_image |**Optional.** Icon image for the host. Used by external interfaces only.
567 icon\_image\_alt|**Optional.** Icon image description for the host. Used by external interface only.
571 > The `address` and `address6` attributes are required for running commands using
572 > the `$address$` and `$address6$` runtime macros.
576 Name | Type | Description
577 --------------------------|---------------|-----------------
578 next\_check | Number | When the next check occurs (as a UNIX timestamp).
579 check\_attempt | Number | The current check attempt number.
580 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
581 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
582 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
583 last\_check\_result | CheckResult | The current check result.
584 last\_state\_change | Number | When the last state change occurred (as a UNIX timestamp).
585 last\_hard\_state\_change | Number | When the last hard state change occurred (as a UNIX timestamp).
586 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
587 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
588 acknowledgement_expiry | Number | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
589 comments | Dictionary | The comments for this host.
590 downtimes | Dictionary | The downtimes for this host.
591 state | Number | The current state (0 = UP, 1 = DOWN).
592 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
593 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
597 ## <a id="objecttype-hostgroup"></a> HostGroup
603 > Assign host group members using the [group assign](18-language-reference.md#group-assign) rules.
607 object HostGroup "my-hosts" {
608 display_name = "My hosts"
611 Configuration Attributes:
614 ----------------|----------------
615 display_name |**Optional.** A short description of the host group.
616 groups |**Optional.** An array of nested group names.
618 ## <a id="objecttype-icingaapplication"></a> IcingaApplication
620 The IcingaApplication object is required to start Icinga 2.
621 The object name must be `app`. If the object configuration
622 is missing Icinga 2 will automatically create an IcingaApplication
627 object IcingaApplication "app" {
628 enable_perfdata = false
631 Configuration Attributes:
634 ----------------------|--------------------------
635 enable_notifications |**Optional.** Whether notifications are globally enabled. Defaults to true.
636 enable_event_handlers |**Optional.** Whether event handlers are globally enabled. Defaults to true.
637 enable_flapping |**Optional.** Whether flap detection is globally enabled. Defaults to true.
638 enable_host_checks |**Optional.** Whether active host checks are globally enabled. Defaults to true.
639 enable_service_checks |**Optional.** Whether active service checks are globally enabled. Defaults to true.
640 enable_perfdata |**Optional.** Whether performance data processing is globally enabled. Defaults to true.
641 vars |**Optional.** A dictionary containing custom attributes that are available globally.
643 ## <a id="objecttype-icingastatuswriter"></a> IcingaStatusWriter
647 > This feature was deprecated in 2.4 and will be removed in future releases.
649 The IcingaStatusWriter feature periodically dumps the current status
650 and performance data from Icinga 2 and all registered features into
655 object IcingaStatusWriter "status" {
656 status_path = LocalStateDir + "/cache/icinga2/status.json"
657 update_interval = 15s
660 Configuration Attributes:
663 --------------------------|--------------------------
664 status\_path |**Optional.** Path to cluster status file. Defaults to LocalStateDir + "/cache/icinga2/status.json"
665 update\_interval |**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
668 ## <a id="objecttype-idomysqlconnection"></a> IdoMySqlConnection
670 IDO database adapter for MySQL.
674 library "db_ido_mysql"
676 object IdoMysqlConnection "mysql-ido" {
682 table_prefix = "icinga_"
683 instance_name = "icinga2"
684 instance_description = "icinga2 instance"
687 downtimehistory_age = 48h
691 categories = DbCatConfig | DbCatState
694 Configuration Attributes:
697 ----------------|----------------
698 host |**Optional.** MySQL database host address. Defaults to "localhost".
699 port |**Optional.** MySQL database port. Defaults to 3306.
700 socket_path |**Optional.** MySQL socket path.
701 user |**Optional.** MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
702 password |**Optional.** MySQL database user's password. Defaults to "icinga".
703 database |**Optional.** MySQL database name. Defaults to "icinga".
704 table\_prefix |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
705 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
706 instance\_description|**Optional.** Description for the Icinga 2 instance.
707 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".
708 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".
709 cleanup |**Optional.** Dictionary with items for historical table cleanup.
710 categories |**Optional.** The types of information that should be written to the database.
715 ----------------|----------------
716 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
717 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
718 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
719 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
720 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
721 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
722 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
723 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
724 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
725 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
726 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
727 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
728 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
729 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
730 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
734 Name | Description | Required by
735 ---------------------|------------------------|--------------------
736 DbCatConfig | Configuration data | Icinga Web/Reporting
737 DbCatState | Current state data | Icinga Web/Reporting
738 DbCatAcknowledgement | Acknowledgements | Icinga Web/Reporting
739 DbCatComment | Comments | Icinga Web/Reporting
740 DbCatDowntime | Downtimes | Icinga Web/Reporting
741 DbCatEventHandler | Event handler data | Icinga Web/Reporting
742 DbCatExternalCommand | External commands | Icinga Web/Reporting
743 DbCatFlapping | Flap detection data | Icinga Web/Reporting
744 DbCatCheck | Check results | --
745 DbCatLog | Log messages | Icinga Web/Reporting
746 DbCatNotification | Notifications | Icinga Web/Reporting
747 DbCatProgramStatus | Program status data | Icinga Web/Reporting
748 DbCatRetention | Retention data | Icinga Web/Reporting
749 DbCatStateHistory | Historical state data | Icinga Web/Reporting
751 Multiple categories can be combined using the `|` operator. In addition to
752 the category flags listed above the `DbCatEverything` flag may be used as
753 a shortcut for listing all flags.
755 External interfaces like Icinga Web require everything except `DbCatCheck`
756 which is the default value if `categories` is not set.
758 ## <a id="objecttype-idopgsqlconnection"></a> IdoPgSqlConnection
760 IDO database adapter for PostgreSQL.
764 library "db_ido_pgsql"
766 object IdoMysqlConnection "pgsql-ido" {
772 table_prefix = "icinga_"
773 instance_name = "icinga2"
774 instance_description = "icinga2 instance"
777 downtimehistory_age = 48h
781 categories = DbCatConfig | DbCatState
784 Configuration Attributes:
787 ----------------|----------------
788 host |**Optional.** PostgreSQL database host address. Defaults to "localhost".
789 port |**Optional.** PostgreSQL database port. Defaults to "5432".
790 user |**Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to "icinga".
791 password |**Optional.** PostgreSQL database user's password. Defaults to "icinga".
792 database |**Optional.** PostgreSQL database name. Defaults to "icinga".
793 table\_prefix |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_".
794 instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
795 instance\_description|**Optional.** Description for the Icinga 2 instance.
796 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".
797 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".
798 cleanup |**Optional.** Dictionary with items for historical table cleanup.
799 categories |**Optional.** The types of information that should be written to the database.
804 ----------------|----------------
805 acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
806 commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
807 contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
808 contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
809 downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
810 eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
811 externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
812 flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
813 hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
814 logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
815 notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
816 processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
817 statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
818 servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
819 systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
823 Name | Description | Required by
824 ---------------------|------------------------|--------------------
825 DbCatConfig | Configuration data | Icinga Web/Reporting
826 DbCatState | Current state data | Icinga Web/Reporting
827 DbCatAcknowledgement | Acknowledgements | Icinga Web/Reporting
828 DbCatComment | Comments | Icinga Web/Reporting
829 DbCatDowntime | Downtimes | Icinga Web/Reporting
830 DbCatEventHandler | Event handler data | Icinga Web/Reporting
831 DbCatExternalCommand | External commands | Icinga Web/Reporting
832 DbCatFlapping | Flap detection data | Icinga Web/Reporting
833 DbCatCheck | Check results | --
834 DbCatLog | Log messages | Icinga Web/Reporting
835 DbCatNotification | Notifications | Icinga Web/Reporting
836 DbCatProgramStatus | Program status data | Icinga Web/Reporting
837 DbCatRetention | Retention data | Icinga Web/Reporting
838 DbCatStateHistory | Historical state data | Icinga Web/Reporting
840 Multiple categories can be combined using the `|` operator. In addition to
841 the category flags listed above the `DbCatEverything` flag may be used as
842 a shortcut for listing all flags.
844 External interfaces like Icinga Web require everything except `DbCatCheck`
845 which is the default value if `categories` is not set.
847 ## <a id="objecttype-livestatuslistener"></a> LiveStatusListener
849 Livestatus API interface available as TCP or UNIX socket. Historical table queries
850 require the [CompatLogger](6-object-types.md#objecttype-compatlogger) feature enabled
851 pointing to the log files using the `compat_log_path` configuration attribute.
857 object LivestatusListener "livestatus-tcp" {
859 bind_host = "127.0.0.1"
863 object LivestatusListener "livestatus-unix" {
865 socket_path = "/var/run/icinga2/cmd/livestatus"
868 Configuration Attributes:
871 ----------------|----------------
872 socket\_type |**Optional.** Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
873 bind\_host |**Optional.** Only valid when socket\_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
874 bind\_port |**Optional.** Only valid when `socket_type` is "tcp". Port to listen on for connections. Defaults to 6558.
875 socket\_path |**Optional.** Only valid when `socket_type` is "unix". Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus".
876 compat\_log\_path |**Optional.** Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"
880 > UNIX sockets are not supported on Windows.
883 ## <a id="objecttype-notification"></a> Notification
885 Notification objects are used to specify how users should be notified in case
886 of host and service state changes and other events.
890 > Rather than creating a `Notification` object for a specific host or service it is
891 > usually easier to just create a `Notification` template and use the `apply` keyword
892 > to assign the notification to a number of hosts or services. Use the `to` keyword
893 > to set the specific target type for `Host` or `Service`.
894 > Check the [notifications](3-monitoring-basics.md#notifications) chapter for detailed examples.
898 object Notification "localhost-ping-notification" {
899 host_name = "localhost"
900 service_name = "ping4"
902 command = "mail-notification"
904 users = [ "user1", "user2" ]
906 types = [ Problem, Recovery ]
909 Configuration Attributes:
912 --------------------------|----------------
913 host_name | **Required.** The name of the host this notification belongs to.
914 service_name | **Optional.** The short name of the service this notification belongs to. If omitted this notification object is treated as host notification.
915 vars | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
916 users | **Optional.** A list of user names who should be notified.
917 user_groups | **Optional.** A list of user group names who should be notified.
918 times | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
919 command | **Required.** The name of the notification command which should be executed when the notification is triggered.
920 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.
921 period | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
922 zone |**Optional.** The zone this object is a member of.
923 types | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
924 states | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
926 Available notification state filters for Service:
933 Available notification state filters for Host:
938 Available notification type filters:
952 Name | Type | Description
953 --------------------------|---------------|-----------------
954 last\_notification | Number | When the last notification was sent for this Notification object (as a UNIX timestamp).
955 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).
956 notification\_number | Number | The notification number
957 last\_problem\_notification | Number | When the last notification was sent for a problem (as a UNIX timestamp).
960 ## <a id="objecttype-notificationcommand"></a> NotificationCommand
962 A notification command definition.
966 object NotificationCommand "mail-service-notification" {
967 import "plugin-notification-command"
970 SysconfDir + "/icinga2/scripts/mail-notification.sh"
974 NOTIFICATIONTYPE = "$notification.type$"
975 SERVICEDESC = "$service.name$"
976 HOSTALIAS = "$host.display_name$"
977 HOSTADDRESS = "$address$"
978 SERVICESTATE = "$service.state$"
979 LONGDATETIME = "$icinga.long_date_time$"
980 SERVICEOUTPUT = "$service.output$"
981 NOTIFICATIONAUTHORNAME = "$notification.author$"
982 NOTIFICATIONCOMMENT = "$notification.comment$"
983 HOSTDISPLAYNAME = "$host.display_name$"
984 SERVICEDISPLAYNAME = "$service.display_name$"
985 USEREMAIL = "$user.email$"
989 Configuration Attributes:
992 ----------------|----------------
993 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.
994 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.
995 env |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
996 vars |**Optional.** A dictionary containing custom attributes that are specific to this command.
997 timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
998 arguments |**Optional.** A dictionary of command arguments.
1000 Command arguments can be used the same way as for [CheckCommand objects](6-object-types.md#objecttype-checkcommand-arguments).
1003 ## <a id="objecttype-notificationcomponent"></a> NotificationComponent
1005 The notification component is responsible for sending notifications. There are no configurable options.
1009 library "notification"
1011 object NotificationComponent "notification" { }
1013 Configuration Attributes:
1016 ----------------|----------------
1017 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".
1019 ## <a id="objecttype-opentsdbwriter"></a> OpenTsdbWriter
1021 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1027 object OpenTsdbWriter "opentsdb" {
1032 Configuration Attributes:
1035 ----------------------|----------------------
1036 host |**Optional.** OpenTSDB host address. Defaults to '127.0.0.1'.
1037 port |**Optional.** OpenTSDB port. Defaults to 4242.
1040 ## <a id="objecttype-perfdatawriter"></a> PerfdataWriter
1042 Writes check result performance data to a defined path using macro
1043 pattern consisting of custom attributes and runtime macros.
1049 object PerfdataWriter "pnp" {
1050 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1052 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1054 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$"
1055 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$"
1057 rotation_interval = 15s
1060 Configuration Attributes:
1063 ------------------------|----------------
1064 host_perfdata\_path |**Optional.** Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
1065 service_perfdata\_path |**Optional.** Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
1066 host_temp\_path |**Optional.** Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
1067 service_temp\_path |**Optional.** Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
1068 host_format\_template |**Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1069 service_format\_template|**Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1070 rotation\_interval |**Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to 30 seconds.
1072 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1073 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1076 ## <a id="objecttype-scheduleddowntime"></a> ScheduledDowntime
1078 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1082 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1083 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1084 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1085 > type for `Host` or `Service`.
1086 > Check the [recurring downtimes](5-advanced-topics.md#recurring-downtimes) example for details.
1090 object ScheduledDowntime "some-downtime" {
1091 host_name = "localhost"
1092 service_name = "ping4"
1094 author = "icingaadmin"
1095 comment = "Some comment"
1101 "sunday" = "02:00-03:00"
1105 Configuration Attributes:
1108 ----------------|----------------
1109 host_name |**Required.** The name of the host this scheduled downtime belongs to.
1110 service_name |**Optional.** The short name of the service this scheduled downtime belongs to. If omitted this downtime object is treated as host downtime.
1111 author |**Required.** The author of the downtime.
1112 comment |**Required.** A comment for the downtime.
1113 fixed |**Optional.** Whether this is a fixed downtime. Defaults to true.
1114 duration |**Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1115 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1117 ScheduledDowntime objects have composite names, i.e. their names are based
1118 on the `host_name` and `service_name` attributes and the
1119 name you specified. This means you can define more than one object
1120 with the same (short) name as long as one of the `host_name` and
1121 `service_name` attributes has a different value.
1124 ## <a id="objecttype-service"></a> Service
1126 Service objects describe network services and how they should be checked
1131 > Rather than creating a `Service` object for a specific host it is usually easier
1132 > to just create a `Service` template and use the `apply` keyword to assign the
1133 > service to a number of hosts.
1134 > Check the [apply](3-monitoring-basics.md#using-apply) chapter for details.
1138 object Service "uptime" {
1139 host_name = "localhost"
1141 display_name = "localhost Uptime"
1143 check_command = "check_snmp"
1145 vars.community = "public"
1146 vars.oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1148 check_interval = 60s
1149 retry_interval = 15s
1151 groups = [ "all-services", "snmp" ]
1154 Configuration Attributes:
1157 ----------------|----------------
1158 display_name |**Optional.** A short description of the service.
1159 host_name |**Required.** The host this service belongs to. There must be a `Host` object with that name.
1160 name |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
1161 groups |**Optional.** The service groups this service belongs to.
1162 vars |**Optional.** A dictionary containing custom attributes that are specific to this service.
1163 check\_command |**Required.** The name of the check command.
1164 max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1165 check\_period |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1166 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.
1167 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.
1168 enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
1169 enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
1170 enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
1171 enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
1172 enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to false.
1173 enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
1174 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.
1175 flapping\_threshold|**Optional.** The flapping threshold in percent when a service is considered to be flapping.
1176 volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
1177 zone |**Optional.** The zone this object is a member of.
1178 command\_endpoint|**Optional.** The endpoint where commands are executed on.
1179 notes |**Optional.** Notes for the service.
1180 notes\_url |**Optional.** Url for notes for the service (for example, in notification commands).
1181 action_url |**Optional.** Url for actions for the service (for example, an external graphing tool).
1182 icon\_image |**Optional.** Icon image for the service. Used by external interfaces only.
1183 icon\_image\_alt|**Optional.** Icon image description for the service. Used by external interface only.
1185 Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
1186 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1190 Name | Type | Description
1191 --------------------------|---------------|-----------------
1192 next\_check | Number | When the next check occurs (as a UNIX timestamp).
1193 check\_attempt | Number | The current check attempt number.
1194 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1195 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1196 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1197 last\_check\_result | CheckResult | The current check result.
1198 last\_state\_change | Number | When the last state change occurred (as a UNIX timestamp).
1199 last\_hard\_state\_change | Number | When the last hard state change occurred (as a UNIX timestamp).
1200 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1201 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1202 acknowledgement_expiry | Number | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1203 comments | Dictionary | The comments for this service.
1204 downtimes | Dictionary | The downtimes for this service.
1205 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1206 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1207 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1210 ## <a id="objecttype-servicegroup"></a> ServiceGroup
1212 A group of services.
1216 > Assign service group members using the [group assign](18-language-reference.md#group-assign) rules.
1220 object ServiceGroup "snmp" {
1221 display_name = "SNMP services"
1224 Configuration Attributes:
1227 ----------------|----------------
1228 display_name |**Optional.** A short description of the service group.
1229 groups |**Optional.** An array of nested group names.
1232 ## <a id="objecttype-statusdatawriter"></a> StatusDataWriter
1234 Periodically writes status data files which are used by the Classic UI and other third-party tools.
1240 object StatusDataWriter "status" {
1241 status_path = "/var/cache/icinga2/status.dat"
1242 objects_path = "/var/cache/icinga2/objects.cache"
1243 update_interval = 30s
1246 Configuration Attributes:
1249 ----------------|----------------
1250 status\_path |**Optional.** Path to the status.dat file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
1251 objects\_path |**Optional.** Path to the objects.cache file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
1252 update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
1255 ## <a id="objecttype-sysloglogger"></a> SyslogLogger
1257 Specifies Icinga 2 logging to syslog.
1261 object SyslogLogger "crit-syslog" {
1262 severity = "critical"
1265 Configuration Attributes:
1268 ----------------|----------------
1269 severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1272 ## <a id="objecttype-timeperiod"></a> TimePeriod
1274 Time periods can be used to specify when hosts/services should be checked or to limit
1275 when notifications should be sent out.
1279 object TimePeriod "nonworkhours" {
1280 import "legacy-timeperiod"
1282 display_name = "Icinga 2 TimePeriod for non working hours"
1285 monday = "00:00-8:00,17:00-24:00"
1286 tuesday = "00:00-8:00,17:00-24:00"
1287 wednesday = "00:00-8:00,17:00-24:00"
1288 thursday = "00:00-8:00,17:00-24:00"
1289 friday = "00:00-8:00,16:00-24:00"
1290 saturday = "00:00-24:00"
1291 sunday = "00:00-24:00"
1295 object TimePeriod "exampledays" {
1296 import "legacy-timeperiod"
1298 display_name = "Icinga 2 TimePeriod for random example days"
1301 //We still believe in Santa, no peeking!
1302 //Applies every 25th of December every year
1303 "december 25" = "00:00-24:00"
1305 //Any point in time can be specified,
1306 //but you still have to use a range
1307 "2038-01-19" = "03:13-03:15"
1309 //Evey 3rd day from the second monday of February
1310 //to 8th of November
1311 "monday 2 february - november 8 / 3" = "00:00-24:00"
1316 Additional examples can be found [within the icinga documentation](http://docs.icinga.org/latest/en/objectdefinitions.html#objectdefinitions-timeperiod).
1318 Configuration Attributes:
1321 ----------------|----------------
1322 display_name |**Optional.** A short description of the time period.
1323 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.
1324 ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1326 The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define
1327 timeperiods including this one.
1331 Name | Type | Description
1332 --------------------------|---------------|-----------------
1333 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1336 ## <a id="objecttype-user"></a> User
1342 object User "icingaadmin" {
1343 display_name = "Icinga 2 Admin"
1344 groups = [ "icingaadmins" ]
1345 email = "icinga@localhost"
1346 pager = "icingaadmin@localhost.localdomain"
1350 states = [ OK, Warning, Critical, Unknown ]
1351 types = [ Problem, Recovery ]
1353 vars.additional_notes = "This is the Icinga 2 Admin account."
1356 Available notification state filters:
1365 Available notification type filters:
1377 Configuration Attributes:
1380 ----------------|----------------
1381 display_name |**Optional.** A short description of the user.
1382 email |**Optional.** An email string for this user. Useful for notification commands.
1383 pager |**Optional.** A pager string for this user. Useful for notification commands.
1384 vars |**Optional.** A dictionary containing custom attributes that are specific to this user.
1385 groups |**Optional.** An array of group names.
1386 enable_notifications|**Optional.** Whether notifications are enabled for this user.
1387 period |**Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default.
1388 types |**Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
1389 states |**Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
1393 Name | Type | Description
1394 --------------------------|---------------|-----------------
1395 last\_notification | Number | When the last notification was sent for this user (as a UNIX timestamp).
1397 ## <a id="objecttype-usergroup"></a> UserGroup
1403 > Assign user group members using the [group assign](18-language-reference.md#group-assign) rules.
1407 object UserGroup "icingaadmins" {
1408 display_name = "Icinga 2 Admin Group"
1411 Configuration Attributes:
1414 ----------------|----------------
1415 display_name |**Optional.** A short description of the user group.
1416 groups |**Optional.** An array of nested group names.
1419 ## <a id="objecttype-zone"></a> Zone
1421 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1425 object Zone "config-ha-master" {
1426 endpoints = [ "icinga2a", "icinga2b" ]
1430 object Zone "check-satellite" {
1431 endpoints = [ "icinga2c" ]
1432 parent = "config-ha-master"
1435 Configuration Attributes:
1438 ----------------|----------------
1439 endpoints |**Optional.** Dictionary with endpoints located in this zone.
1440 parent |**Optional.** The name of the parent zone.
1441 global |**Optional.** Whether configuration files for this zone should be synced to all endpoints. Defaults to false.