1 # Config Object Types <a id="object-types"></a>
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 here too.
9 The attributes need to have a specific type value. Many of them are
10 explained in [this chapter](03-monitoring-basics.md#attribute-value-types) already.
11 You should note that the `Timestamp` type is a `Number`.
12 In addition to that `Object name` is an object reference to
13 an existing object name as `String` type.
15 Configuration objects share these runtime attributes which cannot be
16 modified by the user. You can access these attributes using
17 the [Icinga 2 API](12-icinga2-api.md#icinga2-api-config-objects).
19 Name | Type | Description
20 --------------------------|-----------------------|----------------------------------
21 version | Number | Timestamp when the object was created or modified. Synced throughout cluster nodes.
22 type | String | Object type.
23 original\_attributes | Dictionary | Original values of object attributes modified at runtime.
24 active | Boolean | Object is active (e.g. a service being checked).
25 paused | Boolean | Object has been paused at runtime (e.g. [IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection). Defaults to `false`.
26 templates | Array | Templates imported on object compilation.
27 package | String | [Configuration package name](12-icinga2-api.md#icinga2-api-config-management) this object belongs to. Local configuration is set to `_etc`, runtime created objects use `_api`.
28 source\_location | Dictionary | Location information where the configuration files are stored.
31 ## ApiListener <a id="objecttype-apilistener"></a>
33 ApiListener objects are used for distributed monitoring setups
34 and API usage specifying the certificate files used for ssl
35 authorization and additional restrictions.
36 This configuration object is available as [api feature](11-cli-commands.md#cli-command-feature).
38 The `TicketSalt` constant must be defined in [constants.conf](04-configuring-icinga-2.md#constants-conf).
43 object ApiListener "api" {
44 accept_commands = true
47 ticket_salt = TicketSalt
51 Configuration Attributes:
53 Name | Type | Description
54 --------------------------------------|-----------------------|----------------------------------
55 cert\_path | String | **Deprecated.** Path to the public key.
56 key\_path | String | **Deprecated.** Path to the private key.
57 ca\_path | String | **Deprecated.** Path to the CA certificate file.
58 ticket\_salt | String | **Optional.** Private key for [CSR auto-signing](06-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing). **Required** for a signing master instance.
59 crl\_path | String | **Optional.** Path to the CRL file.
60 bind\_host | String | **Optional.** The IP address the api listener should be bound to. Defaults to `0.0.0.0`.
61 bind\_port | Number | **Optional.** The port the api listener should be bound to. Defaults to `5665`.
62 accept\_config | Boolean | **Optional.** Accept zone configuration. Defaults to `false`.
63 accept\_commands | Boolean | **Optional.** Accept remote commands. Defaults to `false`.
64 max\_anonymous\_clients | Number | **Optional.** Limit the number of anonymous client connections (not configured endpoints and signing requests).
65 cipher\_list | String | **Optional.** Cipher list that is allowed. For a list of available ciphers run `openssl ciphers`. Defaults to `ALL:!LOW:!WEAK:!MEDIUM:!EXP:!NULL`.
66 tls\_protocolmin | String | **Optional.** Minimum TLS protocol version. Must be one of `TLSv1`, `TLSv1.1` or `TLSv1.2`. Defaults to `TLSv1`.
67 access\_control\_allow\_origin | Array | **Optional.** Specifies an array of origin URLs that may access the API. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Origin)
68 access\_control\_allow\_credentials | Boolean | **Deprecated.** Indicates whether or not the actual request can be made using credentials. Defaults to `true`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Credentials)
69 access\_control\_allow\_headers | String | **Deprecated.** Used in response to a preflight request to indicate which HTTP headers can be used when making the actual request. Defaults to `Authorization`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Headers)
70 access\_control\_allow\_methods | String | **Deprecated.** Used in response to a preflight request to indicate which HTTP methods can be used when making the actual request. Defaults to `GET, POST, PUT, DELETE`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Methods)
71 environment | String | **Optional.** Used as suffix in TLS SNI extension name; default from constant `ApiEnvironment`, which is empty.
73 The attributes `access_control_allow_credentials`, `access_control_allow_headers` and `access_control_allow_methods`
74 are controlled by Icinga 2 and are not changeable by config any more.
77 The ApiListener type expects its certificate files to be in the following locations:
80 ---------------------|-------------------------------------
81 Private key | `DataDir + "/certs/" + NodeName + ".key"`
82 Certificate file | `DataDir + "/certs/" + NodeName + ".crt"`
83 CA certificate file | `DataDir + "/certs/ca.crt"`
85 If the deprecated attributes `cert_path`, `key_path` and/or `ca_path` are specified Icinga 2
86 copies those files to the new location in `DataDir + "/certs"` unless the
87 file(s) there are newer.
89 Please check the [upgrading chapter](16-upgrading-icinga-2.md#upgrading-to-2-8-certificate-paths) for more details.
91 While Icinga 2 and the underlying OpenSSL library use sane and secure defaults, the attributes
92 `cipher_list` and `tls_protocolmin` can be used to increase communication security. A good source
93 for a more secure configuration is provided by the [Mozilla Wiki](https://wiki.mozilla.org/Security/Server_Side_TLS).
94 Ensure to use the same configuration for both attributes on **all** endpoints to avoid communication problems which
95 requires to use `cipher_list` compatible with the endpoint using the oldest version of the OpenSSL library. If using
96 other tools to connect to the API ensure also compatibility with them as this setting affects not only inter-cluster
97 communcation but also the REST API.
99 ## ApiUser <a id="objecttype-apiuser"></a>
101 ApiUser objects are used for authentication against the [Icinga 2 API](12-icinga2-api.md#icinga2-api-authentication).
106 object ApiUser "root" {
107 password = "mysecretapipassword"
108 permissions = [ "*" ]
112 Configuration Attributes:
114 Name | Type | Description
115 --------------------------|-----------------------|----------------------------------
116 password | String | **Optional.** Password string. Note: This attribute is hidden in API responses.
117 client\_cn | String | **Optional.** Client Common Name (CN).
118 permissions | Array | **Required.** Array of permissions. Either as string or dictionary with the keys `permission` and `filter`. The latter must be specified as function.
120 Available permissions are explained in the [API permissions](12-icinga2-api.md#icinga2-api-permissions)
123 ## CheckCommand <a id="objecttype-checkcommand"></a>
125 A check command definition. Additional default command custom attributes can be
131 object CheckCommand "http" {
132 command = [ PluginDir + "/check_http" ]
135 "-H" = "$http_vhost$"
136 "-I" = "$http_address$"
140 set_if = "$http_ssl$"
143 set_if = "$http_sni$"
146 value = "$http_auth_pair$"
147 description = "Username:password on sites with basic authentication"
150 set_if = "$http_ignore_body$"
152 "-r" = "$http_expect_body_regex$"
153 "-w" = "$http_warn_time$"
154 "-c" = "$http_critical_time$"
155 "-e" = "$http_expect$"
158 vars.http_address = "$address$"
159 vars.http_ssl = false
160 vars.http_sni = false
164 Configuration Attributes:
166 Name | Type | Description
167 --------------------------|-----------------------|----------------------------------
168 command | Array | **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.
169 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
170 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
171 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
172 arguments | Dictionary | **Optional.** A dictionary of command arguments.
175 ### CheckCommand Arguments <a id="objecttype-checkcommand-arguments"></a>
177 Command arguments can be defined as key-value-pairs in the `arguments`
178 dictionary. If the argument requires additional configuration, for example
179 a `description` attribute or an optional condition, the value can be defined
180 as dictionary specifying additional options.
185 vars.x_val = "My command argument value."
195 key = "-Xnew" /* optional, set a new key identifier */
196 description = "My plugin requires this argument for doing X."
197 required = false /* optional, no error if not set */
198 skip_key = false /* always use "-X <value>" */
199 set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
200 order = -1 /* first position */
201 repeat_key = true /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
205 description = "My plugin requires this argument for doing Y."
206 required = false /* optional, no error if not set */
207 skip_key = true /* don't prefix "-Y" only use "<value>" */
208 set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
209 order = 0 /* second position */
210 repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
215 Name | Type | Description
216 --------------------------|-----------------------|----------------------------------
217 value | String/Function | Optional argument value set by a [runtime macro string](03-monitoring-basics.md#runtime-macros) or a [function call](17-language-reference.md#functions).
218 key | String | Optional argument key overriding the key identifier.
219 description | String | Optional argument description.
220 required | Boolean | Required argument. Execution error if not set. Defaults to false (optional).
221 skip\_key | Boolean | Use the value as argument and skip the key.
222 set\_if | String/Function | Argument is added if the [runtime macro string](03-monitoring-basics.md#runtime-macros) resolves to a defined numeric or boolean value. String values are not supported. [Function calls](17-language-reference.md#functions) returning a value are supported too.
223 order | Number | Set if multiple arguments require a defined argument order.
224 repeat\_key | Boolean | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
229 ..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...
232 Argument array with `repeat_key = true`:
235 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'
238 Argument array with `repeat_key = false`:
241 'key' 'value[0]' 'value[1]' 'value[2]'
244 ## CheckerComponent <a id="objecttype-checkcomponent"></a>
246 The checker component is responsible for scheduling active checks.
247 This configuration object is available as [checker feature](11-cli-commands.md#cli-command-feature).
252 object CheckerComponent "checker" { }
255 Configuration Attributes:
257 Name | Type | Description
258 --------------------------|-----------------------|----------------------------------
259 concurrent\_checks | Number | **Optional and deprecated.** The maximum number of concurrent checks. Was replaced by global constant `MaxConcurrentChecks` which will be set if you still use `concurrent_checks`.
261 ## CheckResultReader <a id="objecttype-checkresultreader"></a>
263 Reads Icinga 1.x check result files from a directory. This functionality is provided
264 to help existing Icinga 1.x users and might be useful for migration scenarios.
269 object CheckResultReader "reader" {
270 spool_dir = "/data/check-results"
274 Configuration Attributes:
276 Name | Type | Description
277 --------------------------|-----------------------|----------------------------------
278 spool\_dir | String | **Optional.** The directory which contains the check result files. Defaults to DataDir + "/spool/checkresults/".
280 ## Comment <a id="objecttype-comment"></a>
282 Comments created at runtime are represented as objects.
283 Note: This is for reference only. You can create comments
284 with the [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) API action.
289 object Comment "localhost!my-comment" {
290 host_name = "localhost"
291 author = "icingaadmin"
292 text = "This is a comment."
296 Configuration Attributes:
298 Name | Type | Description
299 --------------------------|-----------------------|----------------------------------
300 host\_name | Object name | **Required.** The name of the host this comment belongs to.
301 service\_name | Object name | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment.
302 author | String | **Required.** The author's name.
303 text | String | **Required.** The comment text.
304 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this comment was added.
305 entry\_type | Number | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
306 expire\_time | Timestamp | **Optional.** The comment's expire time as UNIX timestamp.
307 persistent | Boolean | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
309 ## CompatLogger <a id="objecttype-compatlogger"></a>
311 Writes log files in a format that's compatible with Icinga 1.x.
312 This configuration object is available as [compatlog feature](14-features.md#compat-logging).
317 object CompatLogger "compatlog" {
318 log_dir = "/var/log/icinga2/compat"
319 rotation_method = "DAILY"
323 Configuration Attributes:
325 Name | Type | Description
326 --------------------------|-----------------------|----------------------------------
327 log\_dir | String | **Optional.** Path to the compat log directory. Defaults to LogDir + "/compat".
328 rotation\_method | String | **Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
331 ## Dependency <a id="objecttype-dependency"></a>
333 Dependency objects are used to specify dependencies between hosts and services. Dependencies
334 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
339 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
340 > to just create a `Dependency` template and use the `apply` keyword to assign the
341 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
342 > type for `Host` or `Service`.
343 > Check the [dependencies](03-monitoring-basics.md#dependencies) chapter for detailed examples.
345 Service-to-Service Example:
348 object Dependency "webserver-internet" {
349 parent_host_name = "internet"
350 parent_service_name = "ping4"
352 child_host_name = "webserver"
353 child_service_name = "ping4"
355 states = [ OK, Warning ]
357 disable_checks = true
361 Host-to-Host Example:
364 object Dependency "webserver-internet" {
365 parent_host_name = "internet"
367 child_host_name = "webserver"
371 disable_checks = true
375 Configuration Attributes:
377 Name | Type | Description
378 --------------------------|-----------------------|----------------------------------
379 parent\_host\_name | Object name | **Required.** The parent host.
380 parent\_service\_name | Object name | **Optional.** The parent service. If omitted, this dependency object is treated as host dependency.
381 child\_host\_name | Object name | **Required.** The child host.
382 child\_service\_name | Object name | **Optional.** The child service. If omitted, this dependency object is treated as host dependency.
383 disable\_checks | Boolean | **Optional.** Whether to disable checks when this dependency fails. Defaults to false.
384 disable\_notifications | Boolean | **Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
385 ignore\_soft\_states | Boolean | **Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
386 period | Object name | **Optional.** Time period object during which this dependency is enabled.
387 states | Array | **Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
389 Available state filters:
398 When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
399 automatically determined by Icinga 2.
401 Service-to-Host Dependency Example:
404 apply Dependency "internet" to Service {
405 parent_host_name = "dsl-router"
406 disable_checks = true
408 assign where host.name != "dsl-router"
412 This example sets all service objects matching the assign condition into a dependency relation to
413 the parent host object `dsl-router` as implicit child services.
415 Service-to-Service-on-the-same-Host Dependency Example:
418 apply Dependency "disable-agent-checks" to Service {
419 parent_service_name = "agent-health"
421 assign where service.check_command == "ssh"
422 ignore where service.name == "agent-health"
426 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
427 host object matched by the apply rule condition. All services where apply matches are made implicit child services
428 in this dependency relation.
431 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
432 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
433 `child_service_name` attributes has a different value.
435 ## Downtime <a id="objecttype-downtime"></a>
437 Downtimes created at runtime are represented as objects.
438 You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action.
443 object Downtime "my-downtime" {
444 host_name = "localhost"
445 author = "icingaadmin"
446 comment = "This is a downtime."
447 start_time = 1505312869
448 end_time = 1505312924
452 Configuration Attributes:
454 Name | Type | Description
455 --------------------------|-----------------------|----------------------------------
456 host\_name | Object name | **Required.** The name of the host this comment belongs to.
457 service\_name | Object name | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment.
458 author | String | **Required.** The author's name.
459 comment | String | **Required.** The comment text.
460 start\_time | Timestamp | **Required.** The start time as UNIX timestamp.
461 end\_time | Timestamp | **Required.** The end time as UNIX timestamp.
462 duration | Number | **Optional.** The duration as number.
463 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this downtime was added.
464 fixed | Boolean | **Optional.** Whether the downtime is fixed (true) or flexible (false). Defaults to flexible. Details in the [advanced topics chapter](08-advanced-topics.md#fixed-flexible-downtimes).
465 triggers | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime.
469 Name | Type | Description
470 --------------------------|-----------------------|----------------------------------
471 trigger\_time | Timestamp | The UNIX timestamp when this downtime was triggered.
472 triggered\_by | Object name | The name of the downtime this downtime was triggered by.
475 ## ElasticsearchWriter <a id="objecttype-elasticsearchwriter"></a>
477 Writes check result metrics and performance data to an Elasticsearch instance.
478 This configuration object is available as [elasticsearch feature](14-features.md#elasticsearch-writer).
483 object ElasticsearchWriter "elasticsearch" {
488 enable_send_perfdata = true
490 flush_threshold = 1024
495 The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
497 Configuration Attributes:
499 Name | Type | Description
500 --------------------------|-----------------------|----------------------------------
501 host | String | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
502 port | Number | **Required.** Elasticsearch port. Defaults to `9200`.
503 index | String | **Required.** Elasticsearch index name. Defaults to `icinga2`.
504 enable\_send\_perfdata | Boolean | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
505 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to Elasticsearch. Defaults to `10s`.
506 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to `1024`.
507 username | String | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
508 password | String | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
509 enable\_tls | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
510 ca\_path | String | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
511 cert\_path | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
512 key\_path | String | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
514 Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
515 Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
517 Basic auth is supported with the `username` and `password` attributes. This requires an
518 HTTP proxy (Nginx, etc.) in front of the Elasticsearch instance. Check [this blogpost](https://blog.netways.de/2017/09/14/secure-elasticsearch-and-kibana-with-an-nginx-http-proxy/)
521 TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
522 you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
524 ## Endpoint <a id="objecttype-endpoint"></a>
526 Endpoint objects are used to specify connection information for remote
527 Icinga 2 instances. More details can be found in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
532 object Endpoint "icinga2-client1.localdomain" {
533 host = "192.168.56.111"
539 Example (disable replay log):
542 object Endpoint "icinga2-client1.localdomain" {
543 host = "192.168.5.111"
549 Configuration Attributes:
551 Name | Type | Description
552 --------------------------|-----------------------|----------------------------------
553 host | String | **Optional.** The hostname/IP address of the remote Icinga 2 instance.
554 port | Number | **Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
555 log\_duration | Duration | **Optional.** Duration for keeping replay logs on connection loss. Defaults to `1d` (86400 seconds). Attribute is specified in seconds. If log_duration is set to 0, replaying logs is disabled. You could also specify the value in human readable format like `10m` for 10 minutes or `1h` for one hour.
557 Endpoint objects cannot currently be created with the API.
559 ## EventCommand <a id="objecttype-eventcommand"></a>
561 An event command definition.
566 object EventCommand "restart-httpd-event" {
567 command = "/opt/bin/restart-httpd.sh"
572 Configuration Attributes:
574 Name | Type | Description
575 --------------------------|-----------------------|----------------------------------
576 command | Array | **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.
577 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
578 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
579 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
580 arguments | Dictionary | **Optional.** A dictionary of command arguments.
582 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
584 More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
586 ## ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
588 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
589 This configuration object is available as [command feature](14-features.md#external-commands).
594 object ExternalCommandListener "command" {
595 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
599 Configuration Attributes:
601 Name | Type | Description
602 --------------------------|-----------------------|----------------------------------
603 command\_path | String | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
607 ## FileLogger <a id="objecttype-filelogger"></a>
609 Specifies Icinga 2 logging to a file.
610 This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging).
615 object FileLogger "debug-file" {
617 path = "/var/log/icinga2/debug.log"
621 Configuration Attributes:
623 Name | Type | Description
624 --------------------------|-----------------------|----------------------------------
625 path | String | **Required.** The log path.
626 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
629 ## GelfWriter <a id="objecttype-gelfwriter"></a>
631 Writes event log entries to a defined GELF receiver host (Graylog, Logstash).
632 This configuration object is available as [gelf feature](14-features.md#gelfwriter).
637 object GelfWriter "gelf" {
643 Configuration Attributes:
645 Name | Type | Description
646 --------------------------|-----------------------|----------------------------------
647 host | String | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`.
648 port | Number | **Optional.** GELF receiver port. Defaults to `12201`.
649 source | String | **Optional.** Source name for this instance. Defaults to `icinga2`.
650 enable\_send\_perfdata | Boolean | **Optional.** Enable performance data for 'CHECK RESULT' events.
653 ## GraphiteWriter <a id="objecttype-graphitewriter"></a>
655 Writes check result metrics and performance data to a defined
656 Graphite Carbon host.
657 This configuration object is available as [graphite feature](14-features.md#graphite-carbon-cache-writer).
662 object GraphiteWriter "graphite" {
668 Configuration Attributes:
670 Name | Type | Description
671 --------------------------|-----------------------|----------------------------------
672 host | String | **Optional.** Graphite Carbon host address. Defaults to `127.0.0.1`.
673 port | Number | **Optional.** Graphite Carbon port. Defaults to `2003`.
674 host\_name\_template | String | **Optional.** Metric prefix for host name. Defaults to `icinga2.$host.name$.host.$host.check_command$`.
675 service\_name\_template | String | **Optional.** Metric prefix for service name. Defaults to `icinga2.$host.name$.services.$service.name$.$service.check_command$`.
676 enable\_send\_thresholds | Boolean | **Optional.** Send additional threshold metrics. Defaults to `false`.
677 enable\_send\_metadata | Boolean | **Optional.** Send additional metadata metrics. Defaults to `false`.
679 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
683 ## Host <a id="objecttype-host"></a>
690 object Host "icinga2-client1.localdomain" {
691 display_name = "Linux Client 1"
692 address = "192.168.56.111"
693 address6 = "2a00:1450:4001:815::2003"
695 groups = [ "linux-servers" ]
697 check_command = "hostalive"
701 Configuration Attributes:
703 Name | Type | Description
704 --------------------------|-----------------------|----------------------------------
705 display\_name | String | **Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
706 address | String | **Optional.** The host's IPv4 address. Available as command runtime macro `$address$` if set.
707 address6 | String | **Optional.** The host's IPv6 address. Available as command runtime macro `$address6$` if set.
708 groups | Array of object names | **Optional.** A list of host groups this host belongs to.
709 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this host.
710 check\_command | Object name | **Required.** The name of the check command.
711 max\_check\_attempts | Number | **Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
712 check\_period | Object name | **Optional.** The name of a time period which determines when this host should be checked. Not set by default.
713 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
714 check\_interval | Duration | **Optional.** The check interval (in seconds). This interval is used for checks when the host is in a `HARD` state. Defaults to `5m`.
715 retry\_interval | Duration | **Optional.** The retry interval (in seconds). This interval is used for checks when the host is in a `SOFT` state. Defaults to `1m`.
716 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to true.
717 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to true.
718 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to true.
719 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to true.
720 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to false.
721 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to true.
722 event\_command | Object name | **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.
723 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a host to be considered flapping. Default `30.0`
724 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a host to be considered not flapping. Default `25.0`
725 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
726 zone | Object name | **Optional.** The zone this object is a member of. Please read the [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring) chapter for details.
727 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
728 notes | String | **Optional.** Notes for the host.
729 notes\_url | String | **Optional.** URL for notes for the host (for example, in notification commands).
730 action\_url | String | **Optional.** URL for actions for the host (for example, an external graphing tool).
731 icon\_image | String | **Optional.** Icon image for the host. Used by external interfaces only.
732 icon\_image\_alt | String | **Optional.** Icon image description for the host. Used by external interface only.
734 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
735 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
739 > The `address` and `address6` attributes are required for running commands using
740 > the `$address$` and `$address6$` runtime macros.
744 Name | Type | Description
745 --------------------------|-----------------------|----------------------------------
746 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
747 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
748 check\_attempt | Number | The current check attempt number.
749 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
750 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
751 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
752 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
753 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
754 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
755 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
756 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
757 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
758 downtime\_depth | Number | Whether the host has one or more active downtimes.
759 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
760 flapping | Boolean | Whether the host is flapping between states.
761 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
762 state | Number | The current state (0 = UP, 1 = DOWN).
763 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
764 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
765 last\_state\_up | Timestamp | When the last UP state occurred (as a UNIX timestamp).
766 last\_state\_down | Timestamp | When the last DOWN state occurred (as a UNIX timestamp).
770 ## HostGroup <a id="objecttype-hostgroup"></a>
776 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
781 object HostGroup "linux-servers" {
782 display_name = "Linux Servers"
784 assign where host.vars.os == "Linux"
788 Configuration Attributes:
790 Name | Type | Description
791 --------------------------|-----------------------|----------------------------------
792 display\_name | String | **Optional.** A short description of the host group.
793 groups | Array of object names | **Optional.** An array of nested group names.
795 ## IcingaApplication <a id="objecttype-icingaapplication"></a>
797 The IcingaApplication object is required to start Icinga 2.
798 The object name must be `app`. If the object configuration
799 is missing, Icinga 2 will automatically create an IcingaApplication
805 object IcingaApplication "app" {
806 enable_perfdata = false
810 Configuration Attributes:
812 Name | Type | Description
813 --------------------------|-----------------------|----------------------------------
814 enable\_notifications | Boolean | **Optional.** Whether notifications are globally enabled. Defaults to true.
815 enable\_event\_handlers | Boolean | **Optional.** Whether event handlers are globally enabled. Defaults to true.
816 enable\_flapping | Boolean | **Optional.** Whether flap detection is globally enabled. Defaults to true.
817 enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true.
818 enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true.
819 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true.
820 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally.
821 environment | String | **Optional.** Specify the Icinga environment. This overrides the `Environment` constant specified in the configuration or on the CLI with `--define`. Defaults to empty.
823 ## IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
825 IDO database adapter for MySQL.
826 This configuration object is available as [ido-mysql feature](14-features.md#db-ido).
831 object IdoMysqlConnection "mysql-ido" {
839 downtimehistory_age = 48h
840 contactnotifications_age = 31d
845 Configuration Attributes:
847 Name | Type | Description
848 --------------------------|-----------------------|----------------------------------
849 host | String | **Optional.** MySQL database host address. Defaults to `localhost`.
850 port | Number | **Optional.** MySQL database port. Defaults to `3306`.
851 socket\_path | String | **Optional.** MySQL socket path.
852 user | String | **Optional.** MySQL database user with read/write permission to the icinga database. Defaults to `icinga`.
853 password | String | **Optional.** MySQL database user's password. Defaults to `icinga`.
854 database | String | **Optional.** MySQL database name. Defaults to `icinga`.
855 enable\_ssl | Boolean | **Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
856 ssl\_key | String | **Optional.** MySQL SSL client key file path.
857 ssl\_cert | String | **Optional.** MySQL SSL certificate file path.
858 ssl\_ca | String | **Optional.** MySQL SSL certificate authority certificate file path.
859 ssl\_capath | String | **Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
860 ssl\_cipher | String | **Optional.** MySQL SSL list of allowed ciphers.
861 table\_prefix | String | **Optional.** MySQL database table prefix. Defaults to `icinga_`.
862 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
863 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
864 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to "true".
865 failover\_timeout | Duration | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 60s. Defaults to `60s`.
866 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
867 categories | Array | **Optional.** Array of information types that should be written to the database.
871 Name | Type | Description
872 --------------------------------|-----------------------|----------------------------------
873 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
874 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
875 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
876 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
877 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
878 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
879 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
880 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
881 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
882 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
883 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
884 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
885 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
886 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
887 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
891 Name | Description | Required by
892 ---------------------|------------------------|--------------------
893 DbCatConfig | Configuration data | Icinga Web 2
894 DbCatState | Current state data | Icinga Web 2
895 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
896 DbCatComment | Comments | Icinga Web 2
897 DbCatDowntime | Downtimes | Icinga Web 2
898 DbCatEventHandler | Event handler data | Icinga Web 2
899 DbCatExternalCommand | External commands | --
900 DbCatFlapping | Flap detection data | Icinga Web 2
901 DbCatCheck | Check results | --
902 DbCatLog | Log messages | --
903 DbCatNotification | Notifications | Icinga Web 2
904 DbCatProgramStatus | Program status data | Icinga Web 2
905 DbCatRetention | Retention data | Icinga Web 2
906 DbCatStateHistory | Historical state data | Icinga Web 2
908 The default value for `categories` includes everything required
909 by Icinga Web 2 in the table above.
911 In addition to the category flags listed above the `DbCatEverything`
912 flag may be used as a shortcut for listing all flags.
914 ## IdoPgsqlConnection <a id="objecttype-idopgsqlconnection"></a>
916 IDO database adapter for PostgreSQL.
917 This configuration object is available as [ido-pgsql feature](14-features.md#db-ido).
922 object IdoPgsqlConnection "pgsql-ido" {
930 downtimehistory_age = 48h
931 contactnotifications_age = 31d
936 Configuration Attributes:
938 Name | Type | Description
939 --------------------------|-----------------------|----------------------------------
940 host | String | **Optional.** PostgreSQL database host address. Defaults to `localhost`.
941 port | Number | **Optional.** PostgreSQL database port. Defaults to `5432`.
942 user | String | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`.
943 password | String | **Optional.** PostgreSQL database user's password. Defaults to `icinga`.
944 database | String | **Optional.** PostgreSQL database name. Defaults to `icinga`.
945 ssl\_mode | String | **Optional.** Enable SSL connection mode. Value must be set according to the [sslmode setting](https://www.postgresql.org/docs/9.3/static/libpq-connect.html#LIBPQ-CONNSTRING): `prefer`, `require`, `verify-ca`, `verify-full`, `allow`, `disable`.
946 ssl\_key | String | **Optional.** PostgreSQL SSL client key file path.
947 ssl\_cert | String | **Optional.** PostgreSQL SSL certificate file path.
948 ssl\_ca | String | **Optional.** PostgreSQL SSL certificate authority certificate file path.
949 table\_prefix | String | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`.
950 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
951 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
952 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to "true".
953 failover\_timeout | Duration | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 60s. Defaults to `60s`.
954 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
955 categories | Array | **Optional.** Array of information types that should be written to the database.
959 Name | Type | Description
960 --------------------------------|-----------------------|----------------------------------
961 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
962 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
963 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
964 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
965 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
966 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
967 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
968 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
969 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
970 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
971 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
972 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
973 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
974 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
975 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
979 Name | Description | Required by
980 ---------------------|------------------------|--------------------
981 DbCatConfig | Configuration data | Icinga Web 2
982 DbCatState | Current state data | Icinga Web 2
983 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
984 DbCatComment | Comments | Icinga Web 2
985 DbCatDowntime | Downtimes | Icinga Web 2
986 DbCatEventHandler | Event handler data | Icinga Web 2
987 DbCatExternalCommand | External commands | --
988 DbCatFlapping | Flap detection data | Icinga Web 2
989 DbCatCheck | Check results | --
990 DbCatLog | Log messages | --
991 DbCatNotification | Notifications | Icinga Web 2
992 DbCatProgramStatus | Program status data | Icinga Web 2
993 DbCatRetention | Retention data | Icinga Web 2
994 DbCatStateHistory | Historical state data | Icinga Web 2
996 The default value for `categories` includes everything required
997 by Icinga Web 2 in the table above.
999 In addition to the category flags listed above the `DbCatEverything`
1000 flag may be used as a shortcut for listing all flags.
1002 ## InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
1004 Writes check result metrics and performance data to a defined InfluxDB host.
1005 This configuration object is available as [influxdb feature](14-features.md#influxdb-writer).
1010 object InfluxdbWriter "influxdb" {
1013 database = "icinga2"
1015 flush_threshold = 1024
1016 flush_interval = 10s
1019 measurement = "$host.check_command$"
1021 hostname = "$host.name$"
1024 service_template = {
1025 measurement = "$service.check_command$"
1027 hostname = "$host.name$"
1028 service = "$service.name$"
1034 Configuration Attributes:
1036 Name | Type | Description
1037 --------------------------|-----------------------|----------------------------------
1038 host | String | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
1039 port | Number | **Required.** InfluxDB HTTP port. Defaults to `8086`.
1040 database | String | **Required.** InfluxDB database name. Defaults to `icinga2`.
1041 username | String | **Optional.** InfluxDB user name. Defaults to `none`.
1042 password | String | **Optional.** InfluxDB user password. Defaults to `none`.
1043 ssl\_enable | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`.
1044 ssl\_ca\_cert | String | **Optional.** Path to CA certificate to validate the remote host.
1045 ssl\_cert | String | **Optional.** Path to host certificate to present to the remote host for mutual verification.
1046 ssl\_key | String | **Optional.** Path to host key to accompany the ssl\_cert.
1047 host\_template | String | **Required.** Host template to define the InfluxDB line protocol.
1048 service\_template | String | **Required.** Service template to define the influxDB line protocol.
1049 enable\_send\_thresholds | Boolean | **Optional.** Whether to send warn, crit, min & max tagged data.
1050 enable\_send\_metadata | Boolean | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
1051 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to InfluxDB. Defaults to `10s`.
1052 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`.
1054 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
1055 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
1060 ## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
1062 Livestatus API interface available as TCP or UNIX socket. Historical table queries
1063 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
1064 pointing to the log files using the `compat_log_path` configuration attribute.
1065 This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus).
1070 object LivestatusListener "livestatus-tcp" {
1072 bind_host = "127.0.0.1"
1076 object LivestatusListener "livestatus-unix" {
1077 socket_type = "unix"
1078 socket_path = "/var/run/icinga2/cmd/livestatus"
1082 Configuration Attributes:
1084 Name | Type | Description
1085 --------------------------|-----------------------|----------------------------------
1086 socket\_type | String | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`.
1087 bind\_host | String | **Optional.** Only valid when `socket_type` is set to `tcp`. Host address to listen on for connections. Defaults to `127.0.0.1`.
1088 bind\_port | Number | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`.
1089 socket\_path | String | **Optional.** Only valid when `socket_type` is set to `unix`. Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus".
1090 compat\_log\_path | String | **Optional.** Path to Icinga 1.x log files. Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LogDir + "/compat"
1094 > UNIX sockets are not supported on Windows.
1097 ## Notification <a id="objecttype-notification"></a>
1099 Notification objects are used to specify how users should be notified in case
1100 of host and service state changes and other events.
1104 > Rather than creating a `Notification` object for a specific host or service it is
1105 > usually easier to just create a `Notification` template and use the `apply` keyword
1106 > to assign the notification to a number of hosts or services. Use the `to` keyword
1107 > to set the specific target type for `Host` or `Service`.
1108 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
1113 object Notification "localhost-ping-notification" {
1114 host_name = "localhost"
1115 service_name = "ping4"
1117 command = "mail-notification"
1119 users = [ "user1", "user2" ] // reference to User objects
1121 types = [ Problem, Recovery ]
1122 states = [ Critical, Warning, OK ]
1126 Configuration Attributes:
1128 Name | Type | Description
1129 --------------------------|-----------------------|----------------------------------
1130 host\_name | Object name | **Required.** The name of the host this notification belongs to.
1131 service\_name | Object name | **Optional.** The short name of the service this notification belongs to. If omitted, this notification object is treated as host notification.
1132 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
1133 users | Array of object names | **Required.** A list of user names who should be notified. **Optional.** if the `user_groups` attribute is set.
1134 user\_groups | Array of object names | **Required.** A list of user group names who should be notified. **Optional.** if the `users` attribute is set.
1135 times | Dictionary | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
1136 command | Object name | **Required.** The name of the notification command which should be executed when the notification is triggered.
1137 interval | Duration | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, [re-notifications](03-monitoring-basics.md#disable-renotification) are disabled.
1138 period | Object name | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
1139 zone | Object name | **Optional.** The zone this object is a member of. Please read the [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring) chapter for details.
1140 types | Array | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
1141 states | Array | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched. Note that the states filter is ignored for notifications of type Acknowledgement!
1143 Available notification state filters for Service:
1150 Available notification state filters for Host:
1155 Available notification type filters:
1169 Name | Type | Description
1170 ----------------------------|-----------------------|-----------------
1171 last\_notification | Timestamp | When the last notification was sent for this Notification object (as a UNIX timestamp).
1172 next\_notification | Timestamp | 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).
1173 notification\_number | Number | The notification number.
1174 last\_problem\_notification | Timestamp | When the last notification was sent for a problem (as a UNIX timestamp).
1177 ## NotificationCommand <a id="objecttype-notificationcommand"></a>
1179 A notification command definition.
1184 object NotificationCommand "mail-service-notification" {
1185 command = [ ConfigDir + "/scripts/mail-service-notification.sh" ]
1190 value = "$notification_address$"
1192 "-6" = "$notification_address6$"
1193 "-b" = "$notification_author$"
1194 "-c" = "$notification_comment$"
1197 value = "$notification_date$"
1201 value = "$notification_servicename$"
1204 value = "$notification_from$"
1205 description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
1207 "-i" = "$notification_icingaweb2url$"
1210 value = "$notification_hostname$"
1214 value = "$notification_hostdisplayname$"
1218 value = "$notification_serviceoutput$"
1222 value = "$notification_useremail$"
1226 value = "$notification_servicestate$"
1230 value = "$notification_type$"
1234 value = "$notification_servicedisplayname$"
1236 "-v" = "$notification_logtosyslog$"
1240 notification_address = "$address$"
1241 notification_address6 = "$address6$"
1242 notification_author = "$notification.author$"
1243 notification_comment = "$notification.comment$"
1244 notification_type = "$notification.type$"
1245 notification_date = "$icinga.long_date_time$"
1246 notification_hostname = "$host.name$"
1247 notification_hostdisplayname = "$host.display_name$"
1248 notification_servicename = "$service.name$"
1249 notification_serviceoutput = "$service.output$"
1250 notification_servicestate = "$service.state$"
1251 notification_useremail = "$user.email$"
1252 notification_servicedisplayname = "$service.display_name$"
1257 Configuration Attributes:
1259 Name | Type | Description
1260 --------------------------|-----------------------|----------------------------------
1261 command | Array | **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.
1262 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1263 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
1264 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
1265 arguments | Dictionary | **Optional.** A dictionary of command arguments.
1267 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
1269 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
1271 ## NotificationComponent <a id="objecttype-notificationcomponent"></a>
1273 The notification component is responsible for sending notifications.
1274 This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature).
1279 object NotificationComponent "notification" { }
1282 Configuration Attributes:
1284 Name | Type | Description
1285 --------------------------|-----------------------|----------------------------------
1286 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-notifications). Disabling this currently only affects reminder notifications. Defaults to "true".
1288 ## OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1290 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1291 This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer).
1296 object OpenTsdbWriter "opentsdb" {
1302 Configuration Attributes:
1304 Name | Type | Description
1305 --------------------------|-----------------------|----------------------------------
1306 host | String | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`.
1307 port | Number | **Optional.** OpenTSDB port. Defaults to `4242`.
1310 ## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1312 Writes check result performance data to a defined path using macro
1313 pattern consisting of custom attributes and runtime macros.
1314 This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files).
1319 object PerfdataWriter "perfdata" {
1320 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1322 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1324 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$"
1325 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$"
1327 rotation_interval = 15s
1331 Configuration Attributes:
1333 Name | Type | Description
1334 --------------------------|-----------------------|----------------------------------
1335 host\_perfdata\_path | String | **Optional.** Path to the host performance data file. Defaults to SpoolDir + "/perfdata/host-perfdata".
1336 service\_perfdata\_path | String | **Optional.** Path to the service performance data file. Defaults to SpoolDir + "/perfdata/service-perfdata".
1337 host\_temp\_path | String | **Optional.** Path to the temporary host file. Defaults to SpoolDir + "/tmp/host-perfdata".
1338 service\_temp\_path | String | **Optional.** Path to the temporary service file. Defaults to SpoolDir + "/tmp/service-perfdata".
1339 host\_format\_template | String | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1340 service\_format\_template | String | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1341 rotation\_interval | Duration | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`.
1343 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1344 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1347 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
1349 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1353 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1354 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1355 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1356 > type for `Host` or `Service`.
1357 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
1362 object ScheduledDowntime "some-downtime" {
1363 host_name = "localhost"
1364 service_name = "ping4"
1366 author = "icingaadmin"
1367 comment = "Some comment"
1373 "sunday" = "02:00-03:00"
1378 Configuration Attributes:
1380 Name | Type | Description
1381 --------------------------|-----------------------|----------------------------------
1382 host\_name | Object name | **Required.** The name of the host this scheduled downtime belongs to.
1383 service\_name | Object name | **Optional.** The short name of the service this scheduled downtime belongs to. If omitted, this downtime object is treated as host downtime.
1384 author | String | **Required.** The author of the downtime.
1385 comment | String | **Required.** A comment for the downtime.
1386 fixed | Boolean | **Optional.** Whether this is a fixed downtime. Defaults to `true`.
1387 duration | Duration | **Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1388 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1389 child\_options | String | **Optional.** Schedule child downtimes. `DowntimeNoChildren` does not do anything, `DowntimeTriggeredChildren` schedules child downtimes triggered by this downtime, `DowntimeNonTriggeredChildren` schedules non-triggered downtimes. Defaults to `DowntimeNoChildren`.
1391 ScheduledDowntime objects have composite names, i.e. their names are based
1392 on the `host_name` and `service_name` attributes and the
1393 name you specified. This means you can define more than one object
1394 with the same (short) name as long as one of the `host_name` and
1395 `service_name` attributes has a different value.
1398 ## Service <a id="objecttype-service"></a>
1400 Service objects describe network services and how they should be checked
1405 > Rather than creating a `Service` object for a specific host it is usually easier
1406 > to just create a `Service` template and use the `apply` keyword to assign the
1407 > service to a number of hosts.
1408 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
1413 object Service "uptime" {
1414 host_name = "localhost"
1416 display_name = "localhost Uptime"
1418 check_command = "snmp"
1420 vars.snmp_community = "public"
1421 vars.snmp_oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1423 check_interval = 60s
1424 retry_interval = 15s
1426 groups = [ "all-services", "snmp" ]
1430 Configuration Attributes:
1432 Name | Type | Description
1433 --------------------------|-----------------------|----------------------------------
1434 display\_name | String | **Optional.** A short description of the service.
1435 host\_name | Object name | **Required.** The host this service belongs to. There must be a `Host` object with that name.
1436 groups | Array of object names | **Optional.** The service groups this service belongs to.
1437 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this service.
1438 check\_command | Object name | **Required.** The name of the check command.
1439 max\_check\_attempts | Number | **Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1440 check\_period | Object name | **Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1441 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
1442 check\_interval | Duration | **Optional.** The check interval (in seconds). This interval is used for checks when the service is in a `HARD` state. Defaults to `5m`.
1443 retry\_interval | Duration | **Optional.** The retry interval (in seconds). This interval is used for checks when the service is in a `SOFT` state. Defaults to `1m`.
1444 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to `true`.
1445 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to `true`.
1446 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to `true`.
1447 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to `true`.
1448 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to `false`.
1449 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a service to be considered flapping. `30.0`
1450 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a service to be considered not flapping. `25.0`
1451 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to `true`.
1452 event\_command | Object name | **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.
1453 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
1454 zone | Object name | **Optional.** The zone this object is a member of. Please read the [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring) chapter for details.
1455 name | String | **Required.** The service name. Must be unique on a per-host basis. For advanced usage in [apply rules](03-monitoring-basics.md#using-apply) only.
1456 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
1457 notes | String | **Optional.** Notes for the service.
1458 notes\_url | String | **Optional.** URL for notes for the service (for example, in notification commands).
1459 action\_url | String | **Optional.** URL for actions for the service (for example, an external graphing tool).
1460 icon\_image | String | **Optional.** Icon image for the service. Used by external interfaces only.
1461 icon\_image\_alt | String | **Optional.** Icon image description for the service. Used by external interface only.
1463 Service objects have composite names, i.e. their names are based on the host\_name attribute and the name you specified. This means
1464 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1466 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
1467 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
1471 Name | Type | Description
1472 --------------------------|-----------------------|----------------------------------
1473 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
1474 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
1475 check\_attempt | Number | The current check attempt number.
1476 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1477 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1478 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1479 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
1480 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
1481 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
1482 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1483 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1484 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1485 downtime\_depth | Number | Whether the service has one or more active downtimes.
1486 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
1487 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
1488 flapping | Boolean | Whether the host is flapping between states.
1489 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1490 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1491 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1492 last\_state\_ok | Timestamp | When the last OK state occurred (as a UNIX timestamp).
1493 last\_state\_warning | Timestamp | When the last WARNING state occurred (as a UNIX timestamp).
1494 last\_state\_critical | Timestamp | When the last CRITICAL state occurred (as a UNIX timestamp).
1495 last\_state\_unknown | Timestamp | When the last UNKNOWN state occurred (as a UNIX timestamp).
1498 ## ServiceGroup <a id="objecttype-servicegroup"></a>
1500 A group of services.
1504 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
1509 object ServiceGroup "snmp" {
1510 display_name = "SNMP services"
1514 Configuration Attributes:
1516 Name | Type | Description
1517 --------------------------|-----------------------|----------------------------------
1518 display\_name | String | **Optional.** A short description of the service group.
1519 groups | Array of object names | **Optional.** An array of nested group names.
1522 ## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1524 Periodically writes status and configuration data files which are used by third-party tools.
1525 This configuration object is available as [statusdata feature](14-features.md#status-data).
1530 object StatusDataWriter "status" {
1531 status_path = "/var/cache/icinga2/status.dat"
1532 objects_path = "/var/cache/icinga2/objects.cache"
1533 update_interval = 30s
1537 Configuration Attributes:
1539 Name | Type | Description
1540 --------------------------|-----------------------|----------------------------------
1541 status\_path | String | **Optional.** Path to the `status.dat` file. Defaults to CacheDir + "/status.dat".
1542 objects\_path | String | **Optional.** Path to the `objects.cache` file. Defaults to CacheDir + "/objects.cache".
1543 update\_interval | Duration | **Optional.** The interval in which the status files are updated. Defaults to `15s`.
1546 ## SyslogLogger <a id="objecttype-sysloglogger"></a>
1548 Specifies Icinga 2 logging to syslog.
1549 This configuration object is available as `syslog` [logging feature](14-features.md#logging).
1554 object SyslogLogger "syslog" {
1555 severity = "warning"
1559 Configuration Attributes:
1561 Name | Type | Description
1562 --------------------------|-----------------------|----------------------------------
1563 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1564 facility | String | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`.
1568 Name | Facility | Description
1569 ---------------------|---------------|----------------
1570 FacilityAuth | LOG\_AUTH | The authorization system.
1571 FacilityAuthPriv | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals.
1572 FacilityCron | LOG\_CRON | The cron daemon.
1573 FacilityDaemon | LOG\_DAEMON | System daemons that are not provided for explicitly by other facilities.
1574 FacilityFtp | LOG\_FTP | The file transfer protocol daemons.
1575 FacilityKern | LOG\_KERN | Messages generated by the kernel. These cannot be generated by any user processes.
1576 FacilityLocal0 | LOG\_LOCAL0 | Reserved for local use.
1577 FacilityLocal1 | LOG\_LOCAL1 | Reserved for local use.
1578 FacilityLocal2 | LOG\_LOCAL2 | Reserved for local use.
1579 FacilityLocal3 | LOG\_LOCAL3 | Reserved for local use.
1580 FacilityLocal4 | LOG\_LOCAL4 | Reserved for local use.
1581 FacilityLocal5 | LOG\_LOCAL5 | Reserved for local use.
1582 FacilityLocal6 | LOG\_LOCAL6 | Reserved for local use.
1583 FacilityLocal7 | LOG\_LOCAL7 | Reserved for local use.
1584 FacilityLpr | LOG\_LPR | The line printer spooling system.
1585 FacilityMail | LOG\_MAIL | The mail system.
1586 FacilityNews | LOG\_NEWS | The network news system.
1587 FacilitySyslog | LOG\_SYSLOG | Messages generated internally by syslogd.
1588 FacilityUser | LOG\_USER | Messages generated by user processes. This is the default facility identifier if none is specified.
1589 FacilityUucp | LOG\_UUCP | The UUCP system.
1591 ## TimePeriod <a id="objecttype-timeperiod"></a>
1593 Time periods can be used to specify when hosts/services should be checked or to limit
1594 when notifications should be sent out.
1599 object TimePeriod "nonworkhours" {
1600 display_name = "Icinga 2 TimePeriod for non working hours"
1603 monday = "00:00-8:00,17:00-24:00"
1604 tuesday = "00:00-8:00,17:00-24:00"
1605 wednesday = "00:00-8:00,17:00-24:00"
1606 thursday = "00:00-8:00,17:00-24:00"
1607 friday = "00:00-8:00,16:00-24:00"
1608 saturday = "00:00-24:00"
1609 sunday = "00:00-24:00"
1613 object TimePeriod "exampledays" {
1614 display_name = "Icinga 2 TimePeriod for random example days"
1617 //We still believe in Santa, no peeking!
1618 //Applies every 25th of December every year
1619 "december 25" = "00:00-24:00"
1621 //Any point in time can be specified,
1622 //but you still have to use a range
1623 "2038-01-19" = "03:13-03:15"
1625 //Evey 3rd day from the second monday of February
1626 //to 8th of November
1627 "monday 2 february - november 8 / 3" = "00:00-24:00"
1632 Additional examples can be found [here](08-advanced-topics.md#timeperiods).
1634 Configuration Attributes:
1636 Name | Type | Description
1637 --------------------------|-----------------------|----------------------------------
1638 display\_name | String | **Optional.** A short description of the time period.
1639 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1640 prefer\_includes | Boolean | **Optional.** Whether to prefer timeperiods `includes` or `excludes`. Default to true.
1641 excludes | Array of object names | **Optional.** An array of timeperiods, which should exclude from your timerange.
1642 includes | Array of object names | **Optional.** An array of timeperiods, which should include into your timerange
1647 Name | Type | Description
1648 --------------------------|-----------------------|----------------------------------
1649 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1652 ## User <a id="objecttype-user"></a>
1659 object User "icingaadmin" {
1660 display_name = "Icinga 2 Admin"
1661 groups = [ "icingaadmins" ]
1662 email = "icinga@localhost"
1663 pager = "icingaadmin@localhost.localdomain"
1667 states = [ OK, Warning, Critical, Unknown ]
1668 types = [ Problem, Recovery ]
1670 vars.additional_notes = "This is the Icinga 2 Admin account."
1674 Available notification state filters:
1683 Available notification type filters:
1695 Configuration Attributes:
1697 Name | Type | Description
1698 --------------------------|-----------------------|----------------------------------
1699 display\_name | String | **Optional.** A short description of the user.
1700 email | String | **Optional.** An email string for this user. Useful for notification commands.
1701 pager | String | **Optional.** A pager string for this user. Useful for notification commands.
1702 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this user.
1703 groups | Array of object names | **Optional.** An array of group names.
1704 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled for this user. Defaults to true.
1705 period | Object name | **Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default.
1706 types | Array | **Optional.** A set of type filters when a notification for this user should be triggered. By default everything is matched.
1707 states | Array | **Optional.** A set of state filters when a notification for this should be triggered. By default everything is matched.
1711 Name | Type | Description
1712 --------------------------|-----------------------|----------------------------------
1713 last\_notification | Timestamp | When the last notification was sent for this user (as a UNIX timestamp).
1715 ## UserGroup <a id="objecttype-usergroup"></a>
1721 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
1726 object UserGroup "icingaadmins" {
1727 display_name = "Icinga 2 Admin Group"
1731 Configuration Attributes:
1733 Name | Type | Description
1734 --------------------------|-----------------------|----------------------------------
1735 display\_name | String | **Optional.** A short description of the user group.
1736 groups | Array of object names | **Optional.** An array of nested group names.
1739 ## Zone <a id="objecttype-zone"></a>
1741 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1742 Please read the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring) for additional details.
1746 object Zone "master" {
1747 endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]
1751 object Zone "satellite" {
1752 endpoints = [ "icinga2-satellite1.localdomain" ]
1757 Configuration Attributes:
1759 Name | Type | Description
1760 --------------------------|-----------------------|----------------------------------
1761 endpoints | Array of object names | **Optional.** Array of endpoint names located in this zone.
1762 parent | Object name | **Optional.** The name of the parent zone.
1763 global | Boolean | **Optional.** Whether configuration files for this zone should be [synced](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync) to all endpoints. Defaults to `false`.
1765 Zone objects cannot currently be created with the API.