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 tls\_handshake\_timeout | Number | **Optional.** TLS Handshake timeout. Defaults to `10s`.
68 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)
69 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)
70 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)
71 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)
72 environment | String | **Optional.** Used as suffix in TLS SNI extension name; default from constant `ApiEnvironment`, which is empty.
74 The attributes `access_control_allow_credentials`, `access_control_allow_headers` and `access_control_allow_methods`
75 are controlled by Icinga 2 and are not changeable by config any more.
78 The ApiListener type expects its certificate files to be in the following locations:
81 ---------------------|-------------------------------------
82 Private key | `DataDir + "/certs/" + NodeName + ".key"`
83 Certificate file | `DataDir + "/certs/" + NodeName + ".crt"`
84 CA certificate file | `DataDir + "/certs/ca.crt"`
86 If the deprecated attributes `cert_path`, `key_path` and/or `ca_path` are specified Icinga 2
87 copies those files to the new location in `DataDir + "/certs"` unless the
88 file(s) there are newer.
90 Please check the [upgrading chapter](16-upgrading-icinga-2.md#upgrading-to-2-8-certificate-paths) for more details.
92 While Icinga 2 and the underlying OpenSSL library use sane and secure defaults, the attributes
93 `cipher_list` and `tls_protocolmin` can be used to increase communication security. A good source
94 for a more secure configuration is provided by the [Mozilla Wiki](https://wiki.mozilla.org/Security/Server_Side_TLS).
95 Ensure to use the same configuration for both attributes on **all** endpoints to avoid communication problems which
96 requires to use `cipher_list` compatible with the endpoint using the oldest version of the OpenSSL library. If using
97 other tools to connect to the API ensure also compatibility with them as this setting affects not only inter-cluster
98 communcation but also the REST API.
100 ## ApiUser <a id="objecttype-apiuser"></a>
102 ApiUser objects are used for authentication against the [Icinga 2 API](12-icinga2-api.md#icinga2-api-authentication).
107 object ApiUser "root" {
108 password = "mysecretapipassword"
109 permissions = [ "*" ]
113 Configuration Attributes:
115 Name | Type | Description
116 --------------------------|-----------------------|----------------------------------
117 password | String | **Optional.** Password string. Note: This attribute is hidden in API responses.
118 client\_cn | String | **Optional.** Client Common Name (CN).
119 permissions | Array | **Required.** Array of permissions. Either as string or dictionary with the keys `permission` and `filter`. The latter must be specified as function.
121 Available permissions are explained in the [API permissions](12-icinga2-api.md#icinga2-api-permissions)
124 ## CheckCommand <a id="objecttype-checkcommand"></a>
126 A check command definition. Additional default command custom attributes can be
132 object CheckCommand "http" {
133 command = [ PluginDir + "/check_http" ]
136 "-H" = "$http_vhost$"
137 "-I" = "$http_address$"
141 set_if = "$http_ssl$"
144 set_if = "$http_sni$"
147 value = "$http_auth_pair$"
148 description = "Username:password on sites with basic authentication"
151 set_if = "$http_ignore_body$"
153 "-r" = "$http_expect_body_regex$"
154 "-w" = "$http_warn_time$"
155 "-c" = "$http_critical_time$"
156 "-e" = "$http_expect$"
159 vars.http_address = "$address$"
160 vars.http_ssl = false
161 vars.http_sni = false
165 Configuration Attributes:
167 Name | Type | Description
168 --------------------------|-----------------------|----------------------------------
169 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.
170 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
171 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
172 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
173 arguments | Dictionary | **Optional.** A dictionary of command arguments.
176 ### CheckCommand Arguments <a id="objecttype-checkcommand-arguments"></a>
178 Command arguments can be defined as key-value-pairs in the `arguments`
179 dictionary. If the argument requires additional configuration, for example
180 a `description` attribute or an optional condition, the value can be defined
181 as dictionary specifying additional options.
186 vars.x_val = "My command argument value."
196 key = "-Xnew" /* optional, set a new key identifier */
197 description = "My plugin requires this argument for doing X."
198 required = false /* optional, no error if not set */
199 skip_key = false /* always use "-X <value>" */
200 set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
201 order = -1 /* first position */
202 repeat_key = true /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
206 description = "My plugin requires this argument for doing Y."
207 required = false /* optional, no error if not set */
208 skip_key = true /* don't prefix "-Y" only use "<value>" */
209 set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
210 order = 0 /* second position */
211 repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
216 Name | Type | Description
217 --------------------------|-----------------------|----------------------------------
218 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).
219 key | String | Optional argument key overriding the key identifier.
220 description | String | Optional argument description.
221 required | Boolean | Required argument. Execution error if not set. Defaults to false (optional).
222 skip\_key | Boolean | Use the value as argument and skip the key.
223 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.
224 order | Number | Set if multiple arguments require a defined argument order.
225 repeat\_key | Boolean | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
230 ..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...
233 Define argument array:
236 value = "[ 'one', 'two', 'three' ]"
239 Argument array with `repeat_key = true`:
242 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'
245 Argument array with `repeat_key = false`:
248 'key' 'value[0]' 'value[1]' 'value[2]'
251 ## CheckerComponent <a id="objecttype-checkcomponent"></a>
253 The checker component is responsible for scheduling active checks.
254 This configuration object is available as [checker feature](11-cli-commands.md#cli-command-feature).
259 object CheckerComponent "checker" { }
262 Configuration Attributes:
264 Name | Type | Description
265 --------------------------|-----------------------|----------------------------------
266 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`.
268 ## CheckResultReader <a id="objecttype-checkresultreader"></a>
270 Reads Icinga 1.x check result files from a directory. This functionality is provided
271 to help existing Icinga 1.x users and might be useful for migration scenarios.
276 object CheckResultReader "reader" {
277 spool_dir = "/data/check-results"
281 Configuration Attributes:
283 Name | Type | Description
284 --------------------------|-----------------------|----------------------------------
285 spool\_dir | String | **Optional.** The directory which contains the check result files. Defaults to DataDir + "/spool/checkresults/".
287 ## Comment <a id="objecttype-comment"></a>
289 Comments created at runtime are represented as objects.
290 Note: This is for reference only. You can create comments
291 with the [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) API action.
296 object Comment "localhost!my-comment" {
297 host_name = "localhost"
298 author = "icingaadmin"
299 text = "This is a comment."
303 Configuration Attributes:
305 Name | Type | Description
306 --------------------------|-----------------------|----------------------------------
307 host\_name | Object name | **Required.** The name of the host this comment belongs to.
308 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.
309 author | String | **Required.** The author's name.
310 text | String | **Required.** The comment text.
311 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this comment was added.
312 entry\_type | Number | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
313 expire\_time | Timestamp | **Optional.** The comment's expire time as UNIX timestamp.
314 persistent | Boolean | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
316 ## CompatLogger <a id="objecttype-compatlogger"></a>
318 Writes log files in a format that's compatible with Icinga 1.x.
319 This configuration object is available as [compatlog feature](14-features.md#compat-logging).
324 object CompatLogger "compatlog" {
325 log_dir = "/var/log/icinga2/compat"
326 rotation_method = "DAILY"
330 Configuration Attributes:
332 Name | Type | Description
333 --------------------------|-----------------------|----------------------------------
334 log\_dir | String | **Optional.** Path to the compat log directory. Defaults to LogDir + "/compat".
335 rotation\_method | String | **Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
338 ## Dependency <a id="objecttype-dependency"></a>
340 Dependency objects are used to specify dependencies between hosts and services. Dependencies
341 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
346 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
347 > to just create a `Dependency` template and use the `apply` keyword to assign the
348 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
349 > type for `Host` or `Service`.
350 > Check the [dependencies](03-monitoring-basics.md#dependencies) chapter for detailed examples.
352 Service-to-Service Example:
355 object Dependency "webserver-internet" {
356 parent_host_name = "internet"
357 parent_service_name = "ping4"
359 child_host_name = "webserver"
360 child_service_name = "ping4"
362 states = [ OK, Warning ]
364 disable_checks = true
368 Host-to-Host Example:
371 object Dependency "webserver-internet" {
372 parent_host_name = "internet"
374 child_host_name = "webserver"
378 disable_checks = true
382 Configuration Attributes:
384 Name | Type | Description
385 --------------------------|-----------------------|----------------------------------
386 parent\_host\_name | Object name | **Required.** The parent host.
387 parent\_service\_name | Object name | **Optional.** The parent service. If omitted, this dependency object is treated as host dependency.
388 child\_host\_name | Object name | **Required.** The child host.
389 child\_service\_name | Object name | **Optional.** The child service. If omitted, this dependency object is treated as host dependency.
390 disable\_checks | Boolean | **Optional.** Whether to disable checks when this dependency fails. Defaults to false.
391 disable\_notifications | Boolean | **Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
392 ignore\_soft\_states | Boolean | **Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
393 period | Object name | **Optional.** Time period object during which this dependency is enabled.
394 states | Array | **Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
396 Available state filters:
405 When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
406 automatically determined by Icinga 2.
408 Service-to-Host Dependency Example:
411 apply Dependency "internet" to Service {
412 parent_host_name = "dsl-router"
413 disable_checks = true
415 assign where host.name != "dsl-router"
419 This example sets all service objects matching the assign condition into a dependency relation to
420 the parent host object `dsl-router` as implicit child services.
422 Service-to-Service-on-the-same-Host Dependency Example:
425 apply Dependency "disable-agent-checks" to Service {
426 parent_service_name = "agent-health"
428 assign where service.check_command == "ssh"
429 ignore where service.name == "agent-health"
433 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
434 host object matched by the apply rule condition. All services where apply matches are made implicit child services
435 in this dependency relation.
438 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
439 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
440 `child_service_name` attributes has a different value.
442 ## Downtime <a id="objecttype-downtime"></a>
444 Downtimes created at runtime are represented as objects.
445 You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action.
450 object Downtime "my-downtime" {
451 host_name = "localhost"
452 author = "icingaadmin"
453 comment = "This is a downtime."
454 start_time = 1505312869
455 end_time = 1505312924
459 Configuration Attributes:
461 Name | Type | Description
462 --------------------------|-----------------------|----------------------------------
463 host\_name | Object name | **Required.** The name of the host this comment belongs to.
464 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.
465 author | String | **Required.** The author's name.
466 comment | String | **Required.** The comment text.
467 start\_time | Timestamp | **Required.** The start time as UNIX timestamp.
468 end\_time | Timestamp | **Required.** The end time as UNIX timestamp.
469 duration | Number | **Optional.** The duration as number.
470 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this downtime was added.
471 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).
472 triggers | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime.
476 Name | Type | Description
477 --------------------------|-----------------------|----------------------------------
478 trigger\_time | Timestamp | The UNIX timestamp when this downtime was triggered.
479 triggered\_by | Object name | The name of the downtime this downtime was triggered by.
482 ## ElasticsearchWriter <a id="objecttype-elasticsearchwriter"></a>
484 Writes check result metrics and performance data to an Elasticsearch instance.
485 This configuration object is available as [elasticsearch feature](14-features.md#elasticsearch-writer).
490 object ElasticsearchWriter "elasticsearch" {
495 enable_send_perfdata = true
497 flush_threshold = 1024
502 The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
504 Configuration Attributes:
506 Name | Type | Description
507 --------------------------|-----------------------|----------------------------------
508 host | String | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
509 port | Number | **Required.** Elasticsearch port. Defaults to `9200`.
510 index | String | **Required.** Elasticsearch index name. Defaults to `icinga2`.
511 enable\_send\_perfdata | Boolean | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
512 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to Elasticsearch. Defaults to `10s`.
513 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to `1024`.
514 username | String | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
515 password | String | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
516 enable\_tls | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
517 ca\_path | String | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
518 cert\_path | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
519 key\_path | String | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
521 Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
522 Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
524 Basic auth is supported with the `username` and `password` attributes. This requires an
525 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/)
528 TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
529 you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
531 ## Endpoint <a id="objecttype-endpoint"></a>
533 Endpoint objects are used to specify connection information for remote
534 Icinga 2 instances. More details can be found in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
539 object Endpoint "icinga2-client1.localdomain" {
540 host = "192.168.56.111"
546 Example (disable replay log):
549 object Endpoint "icinga2-client1.localdomain" {
550 host = "192.168.5.111"
556 Configuration Attributes:
558 Name | Type | Description
559 --------------------------|-----------------------|----------------------------------
560 host | String | **Optional.** The hostname/IP address of the remote Icinga 2 instance.
561 port | Number | **Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
562 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.
564 Endpoint objects cannot currently be created with the API.
566 ## EventCommand <a id="objecttype-eventcommand"></a>
568 An event command definition.
573 object EventCommand "restart-httpd-event" {
574 command = "/opt/bin/restart-httpd.sh"
579 Configuration Attributes:
581 Name | Type | Description
582 --------------------------|-----------------------|----------------------------------
583 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.
584 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
585 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
586 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
587 arguments | Dictionary | **Optional.** A dictionary of command arguments.
589 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
591 More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
593 ## ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
595 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
596 This configuration object is available as [command feature](14-features.md#external-commands).
601 object ExternalCommandListener "command" {
602 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
606 Configuration Attributes:
608 Name | Type | Description
609 --------------------------|-----------------------|----------------------------------
610 command\_path | String | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
614 ## FileLogger <a id="objecttype-filelogger"></a>
616 Specifies Icinga 2 logging to a file.
617 This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging).
622 object FileLogger "debug-file" {
624 path = "/var/log/icinga2/debug.log"
628 Configuration Attributes:
630 Name | Type | Description
631 --------------------------|-----------------------|----------------------------------
632 path | String | **Required.** The log path.
633 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
636 ## GelfWriter <a id="objecttype-gelfwriter"></a>
638 Writes event log entries to a defined GELF receiver host (Graylog, Logstash).
639 This configuration object is available as [gelf feature](14-features.md#gelfwriter).
644 object GelfWriter "gelf" {
650 Configuration Attributes:
652 Name | Type | Description
653 --------------------------|-----------------------|----------------------------------
654 host | String | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`.
655 port | Number | **Optional.** GELF receiver port. Defaults to `12201`.
656 source | String | **Optional.** Source name for this instance. Defaults to `icinga2`.
657 enable\_send\_perfdata | Boolean | **Optional.** Enable performance data for 'CHECK RESULT' events.
660 ## GraphiteWriter <a id="objecttype-graphitewriter"></a>
662 Writes check result metrics and performance data to a defined
663 Graphite Carbon host.
664 This configuration object is available as [graphite feature](14-features.md#graphite-carbon-cache-writer).
669 object GraphiteWriter "graphite" {
675 Configuration Attributes:
677 Name | Type | Description
678 --------------------------|-----------------------|----------------------------------
679 host | String | **Optional.** Graphite Carbon host address. Defaults to `127.0.0.1`.
680 port | Number | **Optional.** Graphite Carbon port. Defaults to `2003`.
681 host\_name\_template | String | **Optional.** Metric prefix for host name. Defaults to `icinga2.$host.name$.host.$host.check_command$`.
682 service\_name\_template | String | **Optional.** Metric prefix for service name. Defaults to `icinga2.$host.name$.services.$service.name$.$service.check_command$`.
683 enable\_send\_thresholds | Boolean | **Optional.** Send additional threshold metrics. Defaults to `false`.
684 enable\_send\_metadata | Boolean | **Optional.** Send additional metadata metrics. Defaults to `false`.
686 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
690 ## Host <a id="objecttype-host"></a>
697 object Host "icinga2-client1.localdomain" {
698 display_name = "Linux Client 1"
699 address = "192.168.56.111"
700 address6 = "2a00:1450:4001:815::2003"
702 groups = [ "linux-servers" ]
704 check_command = "hostalive"
708 Configuration Attributes:
710 Name | Type | Description
711 --------------------------|-----------------------|----------------------------------
712 display\_name | String | **Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
713 address | String | **Optional.** The host's IPv4 address. Available as command runtime macro `$address$` if set.
714 address6 | String | **Optional.** The host's IPv6 address. Available as command runtime macro `$address6$` if set.
715 groups | Array of object names | **Optional.** A list of host groups this host belongs to.
716 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this host.
717 check\_command | Object name | **Required.** The name of the check command.
718 max\_check\_attempts | Number | **Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
719 check\_period | Object name | **Optional.** The name of a time period which determines when this host should be checked. Not set by default.
720 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
721 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`.
722 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`.
723 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to true.
724 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to true.
725 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to true.
726 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to true.
727 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to false.
728 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to true.
729 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.
730 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a host to be considered flapping. Default `30.0`
731 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a host to be considered not flapping. Default `25.0`
732 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
733 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.
734 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
735 notes | String | **Optional.** Notes for the host.
736 notes\_url | String | **Optional.** URL for notes for the host (for example, in notification commands).
737 action\_url | String | **Optional.** URL for actions for the host (for example, an external graphing tool).
738 icon\_image | String | **Optional.** Icon image for the host. Used by external interfaces only.
739 icon\_image\_alt | String | **Optional.** Icon image description for the host. Used by external interface only.
741 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
742 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
746 > The `address` and `address6` attributes are required for running commands using
747 > the `$address$` and `$address6$` runtime macros.
751 Name | Type | Description
752 --------------------------|-----------------------|----------------------------------
753 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
754 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
755 check\_attempt | Number | The current check attempt number.
756 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
757 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
758 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
759 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
760 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
761 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
762 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
763 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
764 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
765 downtime\_depth | Number | Whether the host has one or more active downtimes.
766 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
767 flapping | Boolean | Whether the host is flapping between states.
768 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
769 state | Number | The current state (0 = UP, 1 = DOWN).
770 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
771 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
772 last\_state\_up | Timestamp | When the last UP state occurred (as a UNIX timestamp).
773 last\_state\_down | Timestamp | When the last DOWN state occurred (as a UNIX timestamp).
777 ## HostGroup <a id="objecttype-hostgroup"></a>
783 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
788 object HostGroup "linux-servers" {
789 display_name = "Linux Servers"
791 assign where host.vars.os == "Linux"
795 Configuration Attributes:
797 Name | Type | Description
798 --------------------------|-----------------------|----------------------------------
799 display\_name | String | **Optional.** A short description of the host group.
800 groups | Array of object names | **Optional.** An array of nested group names.
802 ## IcingaApplication <a id="objecttype-icingaapplication"></a>
804 The IcingaApplication object is required to start Icinga 2.
805 The object name must be `app`. If the object configuration
806 is missing, Icinga 2 will automatically create an IcingaApplication
812 object IcingaApplication "app" {
813 enable_perfdata = false
817 Configuration Attributes:
819 Name | Type | Description
820 --------------------------|-----------------------|----------------------------------
821 enable\_notifications | Boolean | **Optional.** Whether notifications are globally enabled. Defaults to true.
822 enable\_event\_handlers | Boolean | **Optional.** Whether event handlers are globally enabled. Defaults to true.
823 enable\_flapping | Boolean | **Optional.** Whether flap detection is globally enabled. Defaults to true.
824 enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true.
825 enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true.
826 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true.
827 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally.
828 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.
830 ## IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
832 IDO database adapter for MySQL.
833 This configuration object is available as [ido-mysql feature](14-features.md#db-ido).
838 object IdoMysqlConnection "mysql-ido" {
846 downtimehistory_age = 48h
847 contactnotifications_age = 31d
852 Configuration Attributes:
854 Name | Type | Description
855 --------------------------|-----------------------|----------------------------------
856 host | String | **Optional.** MySQL database host address. Defaults to `localhost`.
857 port | Number | **Optional.** MySQL database port. Defaults to `3306`.
858 socket\_path | String | **Optional.** MySQL socket path.
859 user | String | **Optional.** MySQL database user with read/write permission to the icinga database. Defaults to `icinga`.
860 password | String | **Optional.** MySQL database user's password. Defaults to `icinga`.
861 database | String | **Optional.** MySQL database name. Defaults to `icinga`.
862 enable\_ssl | Boolean | **Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
863 ssl\_key | String | **Optional.** MySQL SSL client key file path.
864 ssl\_cert | String | **Optional.** MySQL SSL certificate file path.
865 ssl\_ca | String | **Optional.** MySQL SSL certificate authority certificate file path.
866 ssl\_capath | String | **Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
867 ssl\_cipher | String | **Optional.** MySQL SSL list of allowed ciphers.
868 table\_prefix | String | **Optional.** MySQL database table prefix. Defaults to `icinga_`.
869 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
870 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
871 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".
872 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`.
873 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
874 categories | Array | **Optional.** Array of information types that should be written to the database.
878 Name | Type | Description
879 --------------------------------|-----------------------|----------------------------------
880 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
881 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
882 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
883 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
884 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
885 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
886 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
887 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
888 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
889 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
890 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
891 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
892 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
893 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
894 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
898 Name | Description | Required by
899 ---------------------|------------------------|--------------------
900 DbCatConfig | Configuration data | Icinga Web 2
901 DbCatState | Current state data | Icinga Web 2
902 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
903 DbCatComment | Comments | Icinga Web 2
904 DbCatDowntime | Downtimes | Icinga Web 2
905 DbCatEventHandler | Event handler data | Icinga Web 2
906 DbCatExternalCommand | External commands | --
907 DbCatFlapping | Flap detection data | Icinga Web 2
908 DbCatCheck | Check results | --
909 DbCatLog | Log messages | --
910 DbCatNotification | Notifications | Icinga Web 2
911 DbCatProgramStatus | Program status data | Icinga Web 2
912 DbCatRetention | Retention data | Icinga Web 2
913 DbCatStateHistory | Historical state data | Icinga Web 2
915 The default value for `categories` includes everything required
916 by Icinga Web 2 in the table above.
918 In addition to the category flags listed above the `DbCatEverything`
919 flag may be used as a shortcut for listing all flags.
921 ## IdoPgsqlConnection <a id="objecttype-idopgsqlconnection"></a>
923 IDO database adapter for PostgreSQL.
924 This configuration object is available as [ido-pgsql feature](14-features.md#db-ido).
929 object IdoPgsqlConnection "pgsql-ido" {
937 downtimehistory_age = 48h
938 contactnotifications_age = 31d
943 Configuration Attributes:
945 Name | Type | Description
946 --------------------------|-----------------------|----------------------------------
947 host | String | **Optional.** PostgreSQL database host address. Defaults to `localhost`.
948 port | Number | **Optional.** PostgreSQL database port. Defaults to `5432`.
949 user | String | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`.
950 password | String | **Optional.** PostgreSQL database user's password. Defaults to `icinga`.
951 database | String | **Optional.** PostgreSQL database name. Defaults to `icinga`.
952 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`.
953 ssl\_key | String | **Optional.** PostgreSQL SSL client key file path.
954 ssl\_cert | String | **Optional.** PostgreSQL SSL certificate file path.
955 ssl\_ca | String | **Optional.** PostgreSQL SSL certificate authority certificate file path.
956 table\_prefix | String | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`.
957 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
958 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
959 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".
960 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`.
961 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
962 categories | Array | **Optional.** Array of information types that should be written to the database.
966 Name | Type | Description
967 --------------------------------|-----------------------|----------------------------------
968 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
969 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
970 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
971 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
972 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
973 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
974 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
975 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
976 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
977 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
978 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
979 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
980 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
981 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
982 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
986 Name | Description | Required by
987 ---------------------|------------------------|--------------------
988 DbCatConfig | Configuration data | Icinga Web 2
989 DbCatState | Current state data | Icinga Web 2
990 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
991 DbCatComment | Comments | Icinga Web 2
992 DbCatDowntime | Downtimes | Icinga Web 2
993 DbCatEventHandler | Event handler data | Icinga Web 2
994 DbCatExternalCommand | External commands | --
995 DbCatFlapping | Flap detection data | Icinga Web 2
996 DbCatCheck | Check results | --
997 DbCatLog | Log messages | --
998 DbCatNotification | Notifications | Icinga Web 2
999 DbCatProgramStatus | Program status data | Icinga Web 2
1000 DbCatRetention | Retention data | Icinga Web 2
1001 DbCatStateHistory | Historical state data | Icinga Web 2
1003 The default value for `categories` includes everything required
1004 by Icinga Web 2 in the table above.
1006 In addition to the category flags listed above the `DbCatEverything`
1007 flag may be used as a shortcut for listing all flags.
1009 ## InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
1011 Writes check result metrics and performance data to a defined InfluxDB host.
1012 This configuration object is available as [influxdb feature](14-features.md#influxdb-writer).
1017 object InfluxdbWriter "influxdb" {
1020 database = "icinga2"
1022 flush_threshold = 1024
1023 flush_interval = 10s
1026 measurement = "$host.check_command$"
1028 hostname = "$host.name$"
1031 service_template = {
1032 measurement = "$service.check_command$"
1034 hostname = "$host.name$"
1035 service = "$service.name$"
1041 Configuration Attributes:
1043 Name | Type | Description
1044 --------------------------|-----------------------|----------------------------------
1045 host | String | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
1046 port | Number | **Required.** InfluxDB HTTP port. Defaults to `8086`.
1047 database | String | **Required.** InfluxDB database name. Defaults to `icinga2`.
1048 username | String | **Optional.** InfluxDB user name. Defaults to `none`.
1049 password | String | **Optional.** InfluxDB user password. Defaults to `none`.
1050 ssl\_enable | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`.
1051 ssl\_ca\_cert | String | **Optional.** Path to CA certificate to validate the remote host.
1052 ssl\_cert | String | **Optional.** Path to host certificate to present to the remote host for mutual verification.
1053 ssl\_key | String | **Optional.** Path to host key to accompany the ssl\_cert.
1054 host\_template | String | **Required.** Host template to define the InfluxDB line protocol.
1055 service\_template | String | **Required.** Service template to define the influxDB line protocol.
1056 enable\_send\_thresholds | Boolean | **Optional.** Whether to send warn, crit, min & max tagged data.
1057 enable\_send\_metadata | Boolean | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
1058 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to InfluxDB. Defaults to `10s`.
1059 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`.
1061 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
1062 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
1067 ## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
1069 Livestatus API interface available as TCP or UNIX socket. Historical table queries
1070 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
1071 pointing to the log files using the `compat_log_path` configuration attribute.
1072 This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus).
1077 object LivestatusListener "livestatus-tcp" {
1079 bind_host = "127.0.0.1"
1083 object LivestatusListener "livestatus-unix" {
1084 socket_type = "unix"
1085 socket_path = "/var/run/icinga2/cmd/livestatus"
1089 Configuration Attributes:
1091 Name | Type | Description
1092 --------------------------|-----------------------|----------------------------------
1093 socket\_type | String | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`.
1094 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`.
1095 bind\_port | Number | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`.
1096 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".
1097 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"
1101 > UNIX sockets are not supported on Windows.
1104 ## Notification <a id="objecttype-notification"></a>
1106 Notification objects are used to specify how users should be notified in case
1107 of host and service state changes and other events.
1111 > Rather than creating a `Notification` object for a specific host or service it is
1112 > usually easier to just create a `Notification` template and use the `apply` keyword
1113 > to assign the notification to a number of hosts or services. Use the `to` keyword
1114 > to set the specific target type for `Host` or `Service`.
1115 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
1120 object Notification "localhost-ping-notification" {
1121 host_name = "localhost"
1122 service_name = "ping4"
1124 command = "mail-notification"
1126 users = [ "user1", "user2" ] // reference to User objects
1128 types = [ Problem, Recovery ]
1129 states = [ Critical, Warning, OK ]
1133 Configuration Attributes:
1135 Name | Type | Description
1136 --------------------------|-----------------------|----------------------------------
1137 host\_name | Object name | **Required.** The name of the host this notification belongs to.
1138 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.
1139 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
1140 users | Array of object names | **Required.** A list of user names who should be notified. **Optional.** if the `user_groups` attribute is set.
1141 user\_groups | Array of object names | **Required.** A list of user group names who should be notified. **Optional.** if the `users` attribute is set.
1142 times | Dictionary | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
1143 command | Object name | **Required.** The name of the notification command which should be executed when the notification is triggered.
1144 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.
1145 period | Object name | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
1146 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.
1147 types | Array | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
1148 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!
1150 Available notification state filters for Service:
1157 Available notification state filters for Host:
1162 Available notification type filters:
1176 Name | Type | Description
1177 ----------------------------|-----------------------|-----------------
1178 last\_notification | Timestamp | When the last notification was sent for this Notification object (as a UNIX timestamp).
1179 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).
1180 notification\_number | Number | The notification number.
1181 last\_problem\_notification | Timestamp | When the last notification was sent for a problem (as a UNIX timestamp).
1184 ## NotificationCommand <a id="objecttype-notificationcommand"></a>
1186 A notification command definition.
1191 object NotificationCommand "mail-service-notification" {
1192 command = [ ConfigDir + "/scripts/mail-service-notification.sh" ]
1197 value = "$notification_address$"
1199 "-6" = "$notification_address6$"
1200 "-b" = "$notification_author$"
1201 "-c" = "$notification_comment$"
1204 value = "$notification_date$"
1208 value = "$notification_servicename$"
1211 value = "$notification_from$"
1212 description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
1214 "-i" = "$notification_icingaweb2url$"
1217 value = "$notification_hostname$"
1221 value = "$notification_hostdisplayname$"
1225 value = "$notification_serviceoutput$"
1229 value = "$notification_useremail$"
1233 value = "$notification_servicestate$"
1237 value = "$notification_type$"
1241 value = "$notification_servicedisplayname$"
1243 "-v" = "$notification_logtosyslog$"
1247 notification_address = "$address$"
1248 notification_address6 = "$address6$"
1249 notification_author = "$notification.author$"
1250 notification_comment = "$notification.comment$"
1251 notification_type = "$notification.type$"
1252 notification_date = "$icinga.long_date_time$"
1253 notification_hostname = "$host.name$"
1254 notification_hostdisplayname = "$host.display_name$"
1255 notification_servicename = "$service.name$"
1256 notification_serviceoutput = "$service.output$"
1257 notification_servicestate = "$service.state$"
1258 notification_useremail = "$user.email$"
1259 notification_servicedisplayname = "$service.display_name$"
1264 Configuration Attributes:
1266 Name | Type | Description
1267 --------------------------|-----------------------|----------------------------------
1268 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.
1269 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1270 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
1271 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
1272 arguments | Dictionary | **Optional.** A dictionary of command arguments.
1274 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
1276 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
1278 ## NotificationComponent <a id="objecttype-notificationcomponent"></a>
1280 The notification component is responsible for sending notifications.
1281 This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature).
1286 object NotificationComponent "notification" { }
1289 Configuration Attributes:
1291 Name | Type | Description
1292 --------------------------|-----------------------|----------------------------------
1293 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".
1295 ## OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1297 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1298 This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer).
1303 object OpenTsdbWriter "opentsdb" {
1309 Configuration Attributes:
1311 Name | Type | Description
1312 --------------------------|-----------------------|----------------------------------
1313 host | String | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`.
1314 port | Number | **Optional.** OpenTSDB port. Defaults to `4242`.
1317 ## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1319 Writes check result performance data to a defined path using macro
1320 pattern consisting of custom attributes and runtime macros.
1321 This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files).
1326 object PerfdataWriter "perfdata" {
1327 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1329 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1331 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$"
1332 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$"
1334 rotation_interval = 15s
1338 Configuration Attributes:
1340 Name | Type | Description
1341 --------------------------|-----------------------|----------------------------------
1342 host\_perfdata\_path | String | **Optional.** Path to the host performance data file. Defaults to SpoolDir + "/perfdata/host-perfdata".
1343 service\_perfdata\_path | String | **Optional.** Path to the service performance data file. Defaults to SpoolDir + "/perfdata/service-perfdata".
1344 host\_temp\_path | String | **Optional.** Path to the temporary host file. Defaults to SpoolDir + "/tmp/host-perfdata".
1345 service\_temp\_path | String | **Optional.** Path to the temporary service file. Defaults to SpoolDir + "/tmp/service-perfdata".
1346 host\_format\_template | String | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1347 service\_format\_template | String | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1348 rotation\_interval | Duration | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`.
1350 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1351 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1354 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
1356 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1360 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1361 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1362 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1363 > type for `Host` or `Service`.
1364 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
1369 object ScheduledDowntime "some-downtime" {
1370 host_name = "localhost"
1371 service_name = "ping4"
1373 author = "icingaadmin"
1374 comment = "Some comment"
1380 "sunday" = "02:00-03:00"
1385 Configuration Attributes:
1387 Name | Type | Description
1388 --------------------------|-----------------------|----------------------------------
1389 host\_name | Object name | **Required.** The name of the host this scheduled downtime belongs to.
1390 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.
1391 author | String | **Required.** The author of the downtime.
1392 comment | String | **Required.** A comment for the downtime.
1393 fixed | Boolean | **Optional.** Whether this is a fixed downtime. Defaults to `true`.
1394 duration | Duration | **Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1395 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1396 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`.
1398 ScheduledDowntime objects have composite names, i.e. their names are based
1399 on the `host_name` and `service_name` attributes and the
1400 name you specified. This means you can define more than one object
1401 with the same (short) name as long as one of the `host_name` and
1402 `service_name` attributes has a different value.
1405 ## Service <a id="objecttype-service"></a>
1407 Service objects describe network services and how they should be checked
1412 > Rather than creating a `Service` object for a specific host it is usually easier
1413 > to just create a `Service` template and use the `apply` keyword to assign the
1414 > service to a number of hosts.
1415 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
1420 object Service "uptime" {
1421 host_name = "localhost"
1423 display_name = "localhost Uptime"
1425 check_command = "snmp"
1427 vars.snmp_community = "public"
1428 vars.snmp_oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1430 check_interval = 60s
1431 retry_interval = 15s
1433 groups = [ "all-services", "snmp" ]
1437 Configuration Attributes:
1439 Name | Type | Description
1440 --------------------------|-----------------------|----------------------------------
1441 display\_name | String | **Optional.** A short description of the service.
1442 host\_name | Object name | **Required.** The host this service belongs to. There must be a `Host` object with that name.
1443 groups | Array of object names | **Optional.** The service groups this service belongs to.
1444 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this service.
1445 check\_command | Object name | **Required.** The name of the check command.
1446 max\_check\_attempts | Number | **Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1447 check\_period | Object name | **Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1448 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
1449 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`.
1450 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`.
1451 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to `true`.
1452 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to `true`.
1453 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to `true`.
1454 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to `true`.
1455 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to `false`.
1456 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a service to be considered flapping. `30.0`
1457 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a service to be considered not flapping. `25.0`
1458 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to `true`.
1459 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.
1460 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
1461 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.
1462 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.
1463 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
1464 notes | String | **Optional.** Notes for the service.
1465 notes\_url | String | **Optional.** URL for notes for the service (for example, in notification commands).
1466 action\_url | String | **Optional.** URL for actions for the service (for example, an external graphing tool).
1467 icon\_image | String | **Optional.** Icon image for the service. Used by external interfaces only.
1468 icon\_image\_alt | String | **Optional.** Icon image description for the service. Used by external interface only.
1470 Service objects have composite names, i.e. their names are based on the host\_name attribute and the name you specified. This means
1471 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1473 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
1474 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
1478 Name | Type | Description
1479 --------------------------|-----------------------|----------------------------------
1480 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
1481 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
1482 check\_attempt | Number | The current check attempt number.
1483 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1484 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1485 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1486 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
1487 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
1488 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
1489 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1490 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1491 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1492 downtime\_depth | Number | Whether the service has one or more active downtimes.
1493 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
1494 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
1495 flapping | Boolean | Whether the host is flapping between states.
1496 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1497 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1498 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1499 last\_state\_ok | Timestamp | When the last OK state occurred (as a UNIX timestamp).
1500 last\_state\_warning | Timestamp | When the last WARNING state occurred (as a UNIX timestamp).
1501 last\_state\_critical | Timestamp | When the last CRITICAL state occurred (as a UNIX timestamp).
1502 last\_state\_unknown | Timestamp | When the last UNKNOWN state occurred (as a UNIX timestamp).
1505 ## ServiceGroup <a id="objecttype-servicegroup"></a>
1507 A group of services.
1511 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
1516 object ServiceGroup "snmp" {
1517 display_name = "SNMP services"
1521 Configuration Attributes:
1523 Name | Type | Description
1524 --------------------------|-----------------------|----------------------------------
1525 display\_name | String | **Optional.** A short description of the service group.
1526 groups | Array of object names | **Optional.** An array of nested group names.
1529 ## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1531 Periodically writes status and configuration data files which are used by third-party tools.
1532 This configuration object is available as [statusdata feature](14-features.md#status-data).
1537 object StatusDataWriter "status" {
1538 status_path = "/var/cache/icinga2/status.dat"
1539 objects_path = "/var/cache/icinga2/objects.cache"
1540 update_interval = 30s
1544 Configuration Attributes:
1546 Name | Type | Description
1547 --------------------------|-----------------------|----------------------------------
1548 status\_path | String | **Optional.** Path to the `status.dat` file. Defaults to CacheDir + "/status.dat".
1549 objects\_path | String | **Optional.** Path to the `objects.cache` file. Defaults to CacheDir + "/objects.cache".
1550 update\_interval | Duration | **Optional.** The interval in which the status files are updated. Defaults to `15s`.
1553 ## SyslogLogger <a id="objecttype-sysloglogger"></a>
1555 Specifies Icinga 2 logging to syslog.
1556 This configuration object is available as `syslog` [logging feature](14-features.md#logging).
1561 object SyslogLogger "syslog" {
1562 severity = "warning"
1566 Configuration Attributes:
1568 Name | Type | Description
1569 --------------------------|-----------------------|----------------------------------
1570 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1571 facility | String | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`.
1575 Name | Facility | Description
1576 ---------------------|---------------|----------------
1577 FacilityAuth | LOG\_AUTH | The authorization system.
1578 FacilityAuthPriv | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals.
1579 FacilityCron | LOG\_CRON | The cron daemon.
1580 FacilityDaemon | LOG\_DAEMON | System daemons that are not provided for explicitly by other facilities.
1581 FacilityFtp | LOG\_FTP | The file transfer protocol daemons.
1582 FacilityKern | LOG\_KERN | Messages generated by the kernel. These cannot be generated by any user processes.
1583 FacilityLocal0 | LOG\_LOCAL0 | Reserved for local use.
1584 FacilityLocal1 | LOG\_LOCAL1 | Reserved for local use.
1585 FacilityLocal2 | LOG\_LOCAL2 | Reserved for local use.
1586 FacilityLocal3 | LOG\_LOCAL3 | Reserved for local use.
1587 FacilityLocal4 | LOG\_LOCAL4 | Reserved for local use.
1588 FacilityLocal5 | LOG\_LOCAL5 | Reserved for local use.
1589 FacilityLocal6 | LOG\_LOCAL6 | Reserved for local use.
1590 FacilityLocal7 | LOG\_LOCAL7 | Reserved for local use.
1591 FacilityLpr | LOG\_LPR | The line printer spooling system.
1592 FacilityMail | LOG\_MAIL | The mail system.
1593 FacilityNews | LOG\_NEWS | The network news system.
1594 FacilitySyslog | LOG\_SYSLOG | Messages generated internally by syslogd.
1595 FacilityUser | LOG\_USER | Messages generated by user processes. This is the default facility identifier if none is specified.
1596 FacilityUucp | LOG\_UUCP | The UUCP system.
1598 ## TimePeriod <a id="objecttype-timeperiod"></a>
1600 Time periods can be used to specify when hosts/services should be checked or to limit
1601 when notifications should be sent out.
1606 object TimePeriod "nonworkhours" {
1607 display_name = "Icinga 2 TimePeriod for non working hours"
1610 monday = "00:00-8:00,17:00-24:00"
1611 tuesday = "00:00-8:00,17:00-24:00"
1612 wednesday = "00:00-8:00,17:00-24:00"
1613 thursday = "00:00-8:00,17:00-24:00"
1614 friday = "00:00-8:00,16:00-24:00"
1615 saturday = "00:00-24:00"
1616 sunday = "00:00-24:00"
1620 object TimePeriod "exampledays" {
1621 display_name = "Icinga 2 TimePeriod for random example days"
1624 //We still believe in Santa, no peeking!
1625 //Applies every 25th of December every year
1626 "december 25" = "00:00-24:00"
1628 //Any point in time can be specified,
1629 //but you still have to use a range
1630 "2038-01-19" = "03:13-03:15"
1632 //Evey 3rd day from the second monday of February
1633 //to 8th of November
1634 "monday 2 february - november 8 / 3" = "00:00-24:00"
1639 Additional examples can be found [here](08-advanced-topics.md#timeperiods).
1641 Configuration Attributes:
1643 Name | Type | Description
1644 --------------------------|-----------------------|----------------------------------
1645 display\_name | String | **Optional.** A short description of the time period.
1646 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1647 prefer\_includes | Boolean | **Optional.** Whether to prefer timeperiods `includes` or `excludes`. Default to true.
1648 excludes | Array of object names | **Optional.** An array of timeperiods, which should exclude from your timerange.
1649 includes | Array of object names | **Optional.** An array of timeperiods, which should include into your timerange
1654 Name | Type | Description
1655 --------------------------|-----------------------|----------------------------------
1656 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1659 ## User <a id="objecttype-user"></a>
1666 object User "icingaadmin" {
1667 display_name = "Icinga 2 Admin"
1668 groups = [ "icingaadmins" ]
1669 email = "icinga@localhost"
1670 pager = "icingaadmin@localhost.localdomain"
1674 states = [ OK, Warning, Critical, Unknown ]
1675 types = [ Problem, Recovery ]
1677 vars.additional_notes = "This is the Icinga 2 Admin account."
1681 Available notification state filters:
1690 Available notification type filters:
1702 Configuration Attributes:
1704 Name | Type | Description
1705 --------------------------|-----------------------|----------------------------------
1706 display\_name | String | **Optional.** A short description of the user.
1707 email | String | **Optional.** An email string for this user. Useful for notification commands.
1708 pager | String | **Optional.** A pager string for this user. Useful for notification commands.
1709 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this user.
1710 groups | Array of object names | **Optional.** An array of group names.
1711 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled for this user. Defaults to true.
1712 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.
1713 types | Array | **Optional.** A set of type filters when a notification for this user should be triggered. By default everything is matched.
1714 states | Array | **Optional.** A set of state filters when a notification for this should be triggered. By default everything is matched.
1718 Name | Type | Description
1719 --------------------------|-----------------------|----------------------------------
1720 last\_notification | Timestamp | When the last notification was sent for this user (as a UNIX timestamp).
1722 ## UserGroup <a id="objecttype-usergroup"></a>
1728 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
1733 object UserGroup "icingaadmins" {
1734 display_name = "Icinga 2 Admin Group"
1738 Configuration Attributes:
1740 Name | Type | Description
1741 --------------------------|-----------------------|----------------------------------
1742 display\_name | String | **Optional.** A short description of the user group.
1743 groups | Array of object names | **Optional.** An array of nested group names.
1746 ## Zone <a id="objecttype-zone"></a>
1748 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1749 Please read the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring) for additional details.
1753 object Zone "master" {
1754 endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]
1758 object Zone "satellite" {
1759 endpoints = [ "icinga2-satellite1.localdomain" ]
1764 Configuration Attributes:
1766 Name | Type | Description
1767 --------------------------|-----------------------|----------------------------------
1768 endpoints | Array of object names | **Optional.** Array of endpoint names located in this zone.
1769 parent | Object name | **Optional.** The name of the parent zone. (Do not specify a global zone)
1770 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`.
1772 Zone objects cannot currently be created with the API.