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 Argument array with `repeat_key = true`:
236 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'
239 Argument array with `repeat_key = false`:
242 'key' 'value[0]' 'value[1]' 'value[2]'
245 ## CheckerComponent <a id="objecttype-checkcomponent"></a>
247 The checker component is responsible for scheduling active checks.
248 This configuration object is available as [checker feature](11-cli-commands.md#cli-command-feature).
253 object CheckerComponent "checker" { }
256 Configuration Attributes:
258 Name | Type | Description
259 --------------------------|-----------------------|----------------------------------
260 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`.
262 ## CheckResultReader <a id="objecttype-checkresultreader"></a>
264 Reads Icinga 1.x check result files from a directory. This functionality is provided
265 to help existing Icinga 1.x users and might be useful for migration scenarios.
270 object CheckResultReader "reader" {
271 spool_dir = "/data/check-results"
275 Configuration Attributes:
277 Name | Type | Description
278 --------------------------|-----------------------|----------------------------------
279 spool\_dir | String | **Optional.** The directory which contains the check result files. Defaults to DataDir + "/spool/checkresults/".
281 ## Comment <a id="objecttype-comment"></a>
283 Comments created at runtime are represented as objects.
284 Note: This is for reference only. You can create comments
285 with the [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) API action.
290 object Comment "localhost!my-comment" {
291 host_name = "localhost"
292 author = "icingaadmin"
293 text = "This is a comment."
297 Configuration Attributes:
299 Name | Type | Description
300 --------------------------|-----------------------|----------------------------------
301 host\_name | Object name | **Required.** The name of the host this comment belongs to.
302 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.
303 author | String | **Required.** The author's name.
304 text | String | **Required.** The comment text.
305 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this comment was added.
306 entry\_type | Number | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
307 expire\_time | Timestamp | **Optional.** The comment's expire time as UNIX timestamp.
308 persistent | Boolean | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
310 ## CompatLogger <a id="objecttype-compatlogger"></a>
312 Writes log files in a format that's compatible with Icinga 1.x.
313 This configuration object is available as [compatlog feature](14-features.md#compat-logging).
318 object CompatLogger "compatlog" {
319 log_dir = "/var/log/icinga2/compat"
320 rotation_method = "DAILY"
324 Configuration Attributes:
326 Name | Type | Description
327 --------------------------|-----------------------|----------------------------------
328 log\_dir | String | **Optional.** Path to the compat log directory. Defaults to LogDir + "/compat".
329 rotation\_method | String | **Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
332 ## Dependency <a id="objecttype-dependency"></a>
334 Dependency objects are used to specify dependencies between hosts and services. Dependencies
335 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
340 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
341 > to just create a `Dependency` template and use the `apply` keyword to assign the
342 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
343 > type for `Host` or `Service`.
344 > Check the [dependencies](03-monitoring-basics.md#dependencies) chapter for detailed examples.
346 Service-to-Service Example:
349 object Dependency "webserver-internet" {
350 parent_host_name = "internet"
351 parent_service_name = "ping4"
353 child_host_name = "webserver"
354 child_service_name = "ping4"
356 states = [ OK, Warning ]
358 disable_checks = true
362 Host-to-Host Example:
365 object Dependency "webserver-internet" {
366 parent_host_name = "internet"
368 child_host_name = "webserver"
372 disable_checks = true
376 Configuration Attributes:
378 Name | Type | Description
379 --------------------------|-----------------------|----------------------------------
380 parent\_host\_name | Object name | **Required.** The parent host.
381 parent\_service\_name | Object name | **Optional.** The parent service. If omitted, this dependency object is treated as host dependency.
382 child\_host\_name | Object name | **Required.** The child host.
383 child\_service\_name | Object name | **Optional.** The child service. If omitted, this dependency object is treated as host dependency.
384 disable\_checks | Boolean | **Optional.** Whether to disable checks when this dependency fails. Defaults to false.
385 disable\_notifications | Boolean | **Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
386 ignore\_soft\_states | Boolean | **Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
387 period | Object name | **Optional.** Time period object during which this dependency is enabled.
388 states | Array | **Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
390 Available state filters:
399 When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
400 automatically determined by Icinga 2.
402 Service-to-Host Dependency Example:
405 apply Dependency "internet" to Service {
406 parent_host_name = "dsl-router"
407 disable_checks = true
409 assign where host.name != "dsl-router"
413 This example sets all service objects matching the assign condition into a dependency relation to
414 the parent host object `dsl-router` as implicit child services.
416 Service-to-Service-on-the-same-Host Dependency Example:
419 apply Dependency "disable-agent-checks" to Service {
420 parent_service_name = "agent-health"
422 assign where service.check_command == "ssh"
423 ignore where service.name == "agent-health"
427 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
428 host object matched by the apply rule condition. All services where apply matches are made implicit child services
429 in this dependency relation.
432 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
433 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
434 `child_service_name` attributes has a different value.
436 ## Downtime <a id="objecttype-downtime"></a>
438 Downtimes created at runtime are represented as objects.
439 You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action.
444 object Downtime "my-downtime" {
445 host_name = "localhost"
446 author = "icingaadmin"
447 comment = "This is a downtime."
448 start_time = 1505312869
449 end_time = 1505312924
453 Configuration Attributes:
455 Name | Type | Description
456 --------------------------|-----------------------|----------------------------------
457 host\_name | Object name | **Required.** The name of the host this comment belongs to.
458 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.
459 author | String | **Required.** The author's name.
460 comment | String | **Required.** The comment text.
461 start\_time | Timestamp | **Required.** The start time as UNIX timestamp.
462 end\_time | Timestamp | **Required.** The end time as UNIX timestamp.
463 duration | Number | **Optional.** The duration as number.
464 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this downtime was added.
465 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).
466 triggers | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime.
470 Name | Type | Description
471 --------------------------|-----------------------|----------------------------------
472 trigger\_time | Timestamp | The UNIX timestamp when this downtime was triggered.
473 triggered\_by | Object name | The name of the downtime this downtime was triggered by.
476 ## ElasticsearchWriter <a id="objecttype-elasticsearchwriter"></a>
478 Writes check result metrics and performance data to an Elasticsearch instance.
479 This configuration object is available as [elasticsearch feature](14-features.md#elasticsearch-writer).
484 object ElasticsearchWriter "elasticsearch" {
489 enable_send_perfdata = true
491 flush_threshold = 1024
496 The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
498 Configuration Attributes:
500 Name | Type | Description
501 --------------------------|-----------------------|----------------------------------
502 host | String | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
503 port | Number | **Required.** Elasticsearch port. Defaults to `9200`.
504 index | String | **Required.** Elasticsearch index name. Defaults to `icinga2`.
505 enable\_send\_perfdata | Boolean | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
506 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to Elasticsearch. Defaults to `10s`.
507 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to `1024`.
508 username | String | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
509 password | String | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
510 enable\_tls | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
511 ca\_path | String | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
512 cert\_path | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
513 key\_path | String | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
515 Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
516 Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
518 Basic auth is supported with the `username` and `password` attributes. This requires an
519 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/)
522 TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
523 you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
525 ## Endpoint <a id="objecttype-endpoint"></a>
527 Endpoint objects are used to specify connection information for remote
528 Icinga 2 instances. More details can be found in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
533 object Endpoint "icinga2-client1.localdomain" {
534 host = "192.168.56.111"
540 Example (disable replay log):
543 object Endpoint "icinga2-client1.localdomain" {
544 host = "192.168.5.111"
550 Configuration Attributes:
552 Name | Type | Description
553 --------------------------|-----------------------|----------------------------------
554 host | String | **Optional.** The hostname/IP address of the remote Icinga 2 instance.
555 port | Number | **Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
556 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.
558 Endpoint objects cannot currently be created with the API.
560 ## EventCommand <a id="objecttype-eventcommand"></a>
562 An event command definition.
567 object EventCommand "restart-httpd-event" {
568 command = "/opt/bin/restart-httpd.sh"
573 Configuration Attributes:
575 Name | Type | Description
576 --------------------------|-----------------------|----------------------------------
577 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.
578 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
579 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
580 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
581 arguments | Dictionary | **Optional.** A dictionary of command arguments.
583 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
585 More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
587 ## ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
589 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
590 This configuration object is available as [command feature](14-features.md#external-commands).
595 object ExternalCommandListener "command" {
596 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
600 Configuration Attributes:
602 Name | Type | Description
603 --------------------------|-----------------------|----------------------------------
604 command\_path | String | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
608 ## FileLogger <a id="objecttype-filelogger"></a>
610 Specifies Icinga 2 logging to a file.
611 This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging).
616 object FileLogger "debug-file" {
618 path = "/var/log/icinga2/debug.log"
622 Configuration Attributes:
624 Name | Type | Description
625 --------------------------|-----------------------|----------------------------------
626 path | String | **Required.** The log path.
627 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
630 ## GelfWriter <a id="objecttype-gelfwriter"></a>
632 Writes event log entries to a defined GELF receiver host (Graylog, Logstash).
633 This configuration object is available as [gelf feature](14-features.md#gelfwriter).
638 object GelfWriter "gelf" {
644 Configuration Attributes:
646 Name | Type | Description
647 --------------------------|-----------------------|----------------------------------
648 host | String | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`.
649 port | Number | **Optional.** GELF receiver port. Defaults to `12201`.
650 source | String | **Optional.** Source name for this instance. Defaults to `icinga2`.
651 enable\_send\_perfdata | Boolean | **Optional.** Enable performance data for 'CHECK RESULT' events.
654 ## GraphiteWriter <a id="objecttype-graphitewriter"></a>
656 Writes check result metrics and performance data to a defined
657 Graphite Carbon host.
658 This configuration object is available as [graphite feature](14-features.md#graphite-carbon-cache-writer).
663 object GraphiteWriter "graphite" {
669 Configuration Attributes:
671 Name | Type | Description
672 --------------------------|-----------------------|----------------------------------
673 host | String | **Optional.** Graphite Carbon host address. Defaults to `127.0.0.1`.
674 port | Number | **Optional.** Graphite Carbon port. Defaults to `2003`.
675 host\_name\_template | String | **Optional.** Metric prefix for host name. Defaults to `icinga2.$host.name$.host.$host.check_command$`.
676 service\_name\_template | String | **Optional.** Metric prefix for service name. Defaults to `icinga2.$host.name$.services.$service.name$.$service.check_command$`.
677 enable\_send\_thresholds | Boolean | **Optional.** Send additional threshold metrics. Defaults to `false`.
678 enable\_send\_metadata | Boolean | **Optional.** Send additional metadata metrics. Defaults to `false`.
680 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
684 ## Host <a id="objecttype-host"></a>
691 object Host "icinga2-client1.localdomain" {
692 display_name = "Linux Client 1"
693 address = "192.168.56.111"
694 address6 = "2a00:1450:4001:815::2003"
696 groups = [ "linux-servers" ]
698 check_command = "hostalive"
702 Configuration Attributes:
704 Name | Type | Description
705 --------------------------|-----------------------|----------------------------------
706 display\_name | String | **Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
707 address | String | **Optional.** The host's IPv4 address. Available as command runtime macro `$address$` if set.
708 address6 | String | **Optional.** The host's IPv6 address. Available as command runtime macro `$address6$` if set.
709 groups | Array of object names | **Optional.** A list of host groups this host belongs to.
710 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this host.
711 check\_command | Object name | **Required.** The name of the check command.
712 max\_check\_attempts | Number | **Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
713 check\_period | Object name | **Optional.** The name of a time period which determines when this host should be checked. Not set by default.
714 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
715 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`.
716 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`.
717 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to true.
718 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to true.
719 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to true.
720 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to true.
721 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to false.
722 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to true.
723 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.
724 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a host to be considered flapping. Default `30.0`
725 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a host to be considered not flapping. Default `25.0`
726 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
727 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.
728 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
729 notes | String | **Optional.** Notes for the host.
730 notes\_url | String | **Optional.** URL for notes for the host (for example, in notification commands).
731 action\_url | String | **Optional.** URL for actions for the host (for example, an external graphing tool).
732 icon\_image | String | **Optional.** Icon image for the host. Used by external interfaces only.
733 icon\_image\_alt | String | **Optional.** Icon image description for the host. Used by external interface only.
735 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
736 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
740 > The `address` and `address6` attributes are required for running commands using
741 > the `$address$` and `$address6$` runtime macros.
745 Name | Type | Description
746 --------------------------|-----------------------|----------------------------------
747 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
748 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
749 check\_attempt | Number | The current check attempt number.
750 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
751 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
752 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
753 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
754 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
755 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
756 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
757 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
758 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
759 downtime\_depth | Number | Whether the host has one or more active downtimes.
760 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
761 flapping | Boolean | Whether the host is flapping between states.
762 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
763 state | Number | The current state (0 = UP, 1 = DOWN).
764 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
765 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
766 last\_state\_up | Timestamp | When the last UP state occurred (as a UNIX timestamp).
767 last\_state\_down | Timestamp | When the last DOWN state occurred (as a UNIX timestamp).
771 ## HostGroup <a id="objecttype-hostgroup"></a>
777 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
782 object HostGroup "linux-servers" {
783 display_name = "Linux Servers"
785 assign where host.vars.os == "Linux"
789 Configuration Attributes:
791 Name | Type | Description
792 --------------------------|-----------------------|----------------------------------
793 display\_name | String | **Optional.** A short description of the host group.
794 groups | Array of object names | **Optional.** An array of nested group names.
796 ## IcingaApplication <a id="objecttype-icingaapplication"></a>
798 The IcingaApplication object is required to start Icinga 2.
799 The object name must be `app`. If the object configuration
800 is missing, Icinga 2 will automatically create an IcingaApplication
806 object IcingaApplication "app" {
807 enable_perfdata = false
811 Configuration Attributes:
813 Name | Type | Description
814 --------------------------|-----------------------|----------------------------------
815 enable\_notifications | Boolean | **Optional.** Whether notifications are globally enabled. Defaults to true.
816 enable\_event\_handlers | Boolean | **Optional.** Whether event handlers are globally enabled. Defaults to true.
817 enable\_flapping | Boolean | **Optional.** Whether flap detection is globally enabled. Defaults to true.
818 enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true.
819 enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true.
820 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true.
821 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally.
822 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.
824 ## IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
826 IDO database adapter for MySQL.
827 This configuration object is available as [ido-mysql feature](14-features.md#db-ido).
832 object IdoMysqlConnection "mysql-ido" {
840 downtimehistory_age = 48h
841 contactnotifications_age = 31d
846 Configuration Attributes:
848 Name | Type | Description
849 --------------------------|-----------------------|----------------------------------
850 host | String | **Optional.** MySQL database host address. Defaults to `localhost`.
851 port | Number | **Optional.** MySQL database port. Defaults to `3306`.
852 socket\_path | String | **Optional.** MySQL socket path.
853 user | String | **Optional.** MySQL database user with read/write permission to the icinga database. Defaults to `icinga`.
854 password | String | **Optional.** MySQL database user's password. Defaults to `icinga`.
855 database | String | **Optional.** MySQL database name. Defaults to `icinga`.
856 enable\_ssl | Boolean | **Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
857 ssl\_key | String | **Optional.** MySQL SSL client key file path.
858 ssl\_cert | String | **Optional.** MySQL SSL certificate file path.
859 ssl\_ca | String | **Optional.** MySQL SSL certificate authority certificate file path.
860 ssl\_capath | String | **Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
861 ssl\_cipher | String | **Optional.** MySQL SSL list of allowed ciphers.
862 table\_prefix | String | **Optional.** MySQL database table prefix. Defaults to `icinga_`.
863 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
864 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
865 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".
866 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`.
867 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
868 categories | Array | **Optional.** Array of information types that should be written to the database.
872 Name | Type | Description
873 --------------------------------|-----------------------|----------------------------------
874 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
875 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
876 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
877 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
878 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
879 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
880 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
881 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
882 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
883 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
884 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
885 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
886 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
887 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
888 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
892 Name | Description | Required by
893 ---------------------|------------------------|--------------------
894 DbCatConfig | Configuration data | Icinga Web 2
895 DbCatState | Current state data | Icinga Web 2
896 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
897 DbCatComment | Comments | Icinga Web 2
898 DbCatDowntime | Downtimes | Icinga Web 2
899 DbCatEventHandler | Event handler data | Icinga Web 2
900 DbCatExternalCommand | External commands | --
901 DbCatFlapping | Flap detection data | Icinga Web 2
902 DbCatCheck | Check results | --
903 DbCatLog | Log messages | --
904 DbCatNotification | Notifications | Icinga Web 2
905 DbCatProgramStatus | Program status data | Icinga Web 2
906 DbCatRetention | Retention data | Icinga Web 2
907 DbCatStateHistory | Historical state data | Icinga Web 2
909 The default value for `categories` includes everything required
910 by Icinga Web 2 in the table above.
912 In addition to the category flags listed above the `DbCatEverything`
913 flag may be used as a shortcut for listing all flags.
915 ## IdoPgsqlConnection <a id="objecttype-idopgsqlconnection"></a>
917 IDO database adapter for PostgreSQL.
918 This configuration object is available as [ido-pgsql feature](14-features.md#db-ido).
923 object IdoPgsqlConnection "pgsql-ido" {
931 downtimehistory_age = 48h
932 contactnotifications_age = 31d
937 Configuration Attributes:
939 Name | Type | Description
940 --------------------------|-----------------------|----------------------------------
941 host | String | **Optional.** PostgreSQL database host address. Defaults to `localhost`.
942 port | Number | **Optional.** PostgreSQL database port. Defaults to `5432`.
943 user | String | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`.
944 password | String | **Optional.** PostgreSQL database user's password. Defaults to `icinga`.
945 database | String | **Optional.** PostgreSQL database name. Defaults to `icinga`.
946 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`.
947 ssl\_key | String | **Optional.** PostgreSQL SSL client key file path.
948 ssl\_cert | String | **Optional.** PostgreSQL SSL certificate file path.
949 ssl\_ca | String | **Optional.** PostgreSQL SSL certificate authority certificate file path.
950 table\_prefix | String | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`.
951 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
952 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
953 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".
954 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`.
955 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
956 categories | Array | **Optional.** Array of information types that should be written to the database.
960 Name | Type | Description
961 --------------------------------|-----------------------|----------------------------------
962 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
963 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
964 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
965 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
966 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
967 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
968 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
969 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
970 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
971 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
972 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
973 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
974 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
975 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
976 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
980 Name | Description | Required by
981 ---------------------|------------------------|--------------------
982 DbCatConfig | Configuration data | Icinga Web 2
983 DbCatState | Current state data | Icinga Web 2
984 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
985 DbCatComment | Comments | Icinga Web 2
986 DbCatDowntime | Downtimes | Icinga Web 2
987 DbCatEventHandler | Event handler data | Icinga Web 2
988 DbCatExternalCommand | External commands | --
989 DbCatFlapping | Flap detection data | Icinga Web 2
990 DbCatCheck | Check results | --
991 DbCatLog | Log messages | --
992 DbCatNotification | Notifications | Icinga Web 2
993 DbCatProgramStatus | Program status data | Icinga Web 2
994 DbCatRetention | Retention data | Icinga Web 2
995 DbCatStateHistory | Historical state data | Icinga Web 2
997 The default value for `categories` includes everything required
998 by Icinga Web 2 in the table above.
1000 In addition to the category flags listed above the `DbCatEverything`
1001 flag may be used as a shortcut for listing all flags.
1003 ## InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
1005 Writes check result metrics and performance data to a defined InfluxDB host.
1006 This configuration object is available as [influxdb feature](14-features.md#influxdb-writer).
1011 object InfluxdbWriter "influxdb" {
1014 database = "icinga2"
1016 flush_threshold = 1024
1017 flush_interval = 10s
1020 measurement = "$host.check_command$"
1022 hostname = "$host.name$"
1025 service_template = {
1026 measurement = "$service.check_command$"
1028 hostname = "$host.name$"
1029 service = "$service.name$"
1035 Configuration Attributes:
1037 Name | Type | Description
1038 --------------------------|-----------------------|----------------------------------
1039 host | String | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
1040 port | Number | **Required.** InfluxDB HTTP port. Defaults to `8086`.
1041 database | String | **Required.** InfluxDB database name. Defaults to `icinga2`.
1042 username | String | **Optional.** InfluxDB user name. Defaults to `none`.
1043 password | String | **Optional.** InfluxDB user password. Defaults to `none`.
1044 ssl\_enable | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`.
1045 ssl\_ca\_cert | String | **Optional.** Path to CA certificate to validate the remote host.
1046 ssl\_cert | String | **Optional.** Path to host certificate to present to the remote host for mutual verification.
1047 ssl\_key | String | **Optional.** Path to host key to accompany the ssl\_cert.
1048 host\_template | String | **Required.** Host template to define the InfluxDB line protocol.
1049 service\_template | String | **Required.** Service template to define the influxDB line protocol.
1050 enable\_send\_thresholds | Boolean | **Optional.** Whether to send warn, crit, min & max tagged data.
1051 enable\_send\_metadata | Boolean | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
1052 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to InfluxDB. Defaults to `10s`.
1053 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`.
1055 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
1056 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
1061 ## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
1063 Livestatus API interface available as TCP or UNIX socket. Historical table queries
1064 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
1065 pointing to the log files using the `compat_log_path` configuration attribute.
1066 This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus).
1071 object LivestatusListener "livestatus-tcp" {
1073 bind_host = "127.0.0.1"
1077 object LivestatusListener "livestatus-unix" {
1078 socket_type = "unix"
1079 socket_path = "/var/run/icinga2/cmd/livestatus"
1083 Configuration Attributes:
1085 Name | Type | Description
1086 --------------------------|-----------------------|----------------------------------
1087 socket\_type | String | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`.
1088 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`.
1089 bind\_port | Number | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`.
1090 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".
1091 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"
1095 > UNIX sockets are not supported on Windows.
1098 ## Notification <a id="objecttype-notification"></a>
1100 Notification objects are used to specify how users should be notified in case
1101 of host and service state changes and other events.
1105 > Rather than creating a `Notification` object for a specific host or service it is
1106 > usually easier to just create a `Notification` template and use the `apply` keyword
1107 > to assign the notification to a number of hosts or services. Use the `to` keyword
1108 > to set the specific target type for `Host` or `Service`.
1109 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
1114 object Notification "localhost-ping-notification" {
1115 host_name = "localhost"
1116 service_name = "ping4"
1118 command = "mail-notification"
1120 users = [ "user1", "user2" ] // reference to User objects
1122 types = [ Problem, Recovery ]
1123 states = [ Critical, Warning, OK ]
1127 Configuration Attributes:
1129 Name | Type | Description
1130 --------------------------|-----------------------|----------------------------------
1131 host\_name | Object name | **Required.** The name of the host this notification belongs to.
1132 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.
1133 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
1134 users | Array of object names | **Required.** A list of user names who should be notified. **Optional.** if the `user_groups` attribute is set.
1135 user\_groups | Array of object names | **Required.** A list of user group names who should be notified. **Optional.** if the `users` attribute is set.
1136 times | Dictionary | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
1137 command | Object name | **Required.** The name of the notification command which should be executed when the notification is triggered.
1138 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.
1139 period | Object name | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
1140 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.
1141 types | Array | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
1142 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!
1144 Available notification state filters for Service:
1151 Available notification state filters for Host:
1156 Available notification type filters:
1170 Name | Type | Description
1171 ----------------------------|-----------------------|-----------------
1172 last\_notification | Timestamp | When the last notification was sent for this Notification object (as a UNIX timestamp).
1173 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).
1174 notification\_number | Number | The notification number.
1175 last\_problem\_notification | Timestamp | When the last notification was sent for a problem (as a UNIX timestamp).
1178 ## NotificationCommand <a id="objecttype-notificationcommand"></a>
1180 A notification command definition.
1185 object NotificationCommand "mail-service-notification" {
1186 command = [ ConfigDir + "/scripts/mail-service-notification.sh" ]
1191 value = "$notification_address$"
1193 "-6" = "$notification_address6$"
1194 "-b" = "$notification_author$"
1195 "-c" = "$notification_comment$"
1198 value = "$notification_date$"
1202 value = "$notification_servicename$"
1205 value = "$notification_from$"
1206 description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
1208 "-i" = "$notification_icingaweb2url$"
1211 value = "$notification_hostname$"
1215 value = "$notification_hostdisplayname$"
1219 value = "$notification_serviceoutput$"
1223 value = "$notification_useremail$"
1227 value = "$notification_servicestate$"
1231 value = "$notification_type$"
1235 value = "$notification_servicedisplayname$"
1237 "-v" = "$notification_logtosyslog$"
1241 notification_address = "$address$"
1242 notification_address6 = "$address6$"
1243 notification_author = "$notification.author$"
1244 notification_comment = "$notification.comment$"
1245 notification_type = "$notification.type$"
1246 notification_date = "$icinga.long_date_time$"
1247 notification_hostname = "$host.name$"
1248 notification_hostdisplayname = "$host.display_name$"
1249 notification_servicename = "$service.name$"
1250 notification_serviceoutput = "$service.output$"
1251 notification_servicestate = "$service.state$"
1252 notification_useremail = "$user.email$"
1253 notification_servicedisplayname = "$service.display_name$"
1258 Configuration Attributes:
1260 Name | Type | Description
1261 --------------------------|-----------------------|----------------------------------
1262 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.
1263 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1264 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
1265 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
1266 arguments | Dictionary | **Optional.** A dictionary of command arguments.
1268 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
1270 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
1272 ## NotificationComponent <a id="objecttype-notificationcomponent"></a>
1274 The notification component is responsible for sending notifications.
1275 This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature).
1280 object NotificationComponent "notification" { }
1283 Configuration Attributes:
1285 Name | Type | Description
1286 --------------------------|-----------------------|----------------------------------
1287 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".
1289 ## OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1291 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1292 This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer).
1297 object OpenTsdbWriter "opentsdb" {
1303 Configuration Attributes:
1305 Name | Type | Description
1306 --------------------------|-----------------------|----------------------------------
1307 host | String | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`.
1308 port | Number | **Optional.** OpenTSDB port. Defaults to `4242`.
1311 ## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1313 Writes check result performance data to a defined path using macro
1314 pattern consisting of custom attributes and runtime macros.
1315 This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files).
1320 object PerfdataWriter "perfdata" {
1321 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1323 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1325 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$"
1326 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$"
1328 rotation_interval = 15s
1332 Configuration Attributes:
1334 Name | Type | Description
1335 --------------------------|-----------------------|----------------------------------
1336 host\_perfdata\_path | String | **Optional.** Path to the host performance data file. Defaults to SpoolDir + "/perfdata/host-perfdata".
1337 service\_perfdata\_path | String | **Optional.** Path to the service performance data file. Defaults to SpoolDir + "/perfdata/service-perfdata".
1338 host\_temp\_path | String | **Optional.** Path to the temporary host file. Defaults to SpoolDir + "/tmp/host-perfdata".
1339 service\_temp\_path | String | **Optional.** Path to the temporary service file. Defaults to SpoolDir + "/tmp/service-perfdata".
1340 host\_format\_template | String | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1341 service\_format\_template | String | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1342 rotation\_interval | Duration | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`.
1344 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1345 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1348 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
1350 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1354 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1355 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1356 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1357 > type for `Host` or `Service`.
1358 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
1363 object ScheduledDowntime "some-downtime" {
1364 host_name = "localhost"
1365 service_name = "ping4"
1367 author = "icingaadmin"
1368 comment = "Some comment"
1374 "sunday" = "02:00-03:00"
1379 Configuration Attributes:
1381 Name | Type | Description
1382 --------------------------|-----------------------|----------------------------------
1383 host\_name | Object name | **Required.** The name of the host this scheduled downtime belongs to.
1384 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.
1385 author | String | **Required.** The author of the downtime.
1386 comment | String | **Required.** A comment for the downtime.
1387 fixed | Boolean | **Optional.** Whether this is a fixed downtime. Defaults to `true`.
1388 duration | Duration | **Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1389 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1390 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`.
1392 ScheduledDowntime objects have composite names, i.e. their names are based
1393 on the `host_name` and `service_name` attributes and the
1394 name you specified. This means you can define more than one object
1395 with the same (short) name as long as one of the `host_name` and
1396 `service_name` attributes has a different value.
1399 ## Service <a id="objecttype-service"></a>
1401 Service objects describe network services and how they should be checked
1406 > Rather than creating a `Service` object for a specific host it is usually easier
1407 > to just create a `Service` template and use the `apply` keyword to assign the
1408 > service to a number of hosts.
1409 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
1414 object Service "uptime" {
1415 host_name = "localhost"
1417 display_name = "localhost Uptime"
1419 check_command = "snmp"
1421 vars.snmp_community = "public"
1422 vars.snmp_oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1424 check_interval = 60s
1425 retry_interval = 15s
1427 groups = [ "all-services", "snmp" ]
1431 Configuration Attributes:
1433 Name | Type | Description
1434 --------------------------|-----------------------|----------------------------------
1435 display\_name | String | **Optional.** A short description of the service.
1436 host\_name | Object name | **Required.** The host this service belongs to. There must be a `Host` object with that name.
1437 groups | Array of object names | **Optional.** The service groups this service belongs to.
1438 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this service.
1439 check\_command | Object name | **Required.** The name of the check command.
1440 max\_check\_attempts | Number | **Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1441 check\_period | Object name | **Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1442 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
1443 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`.
1444 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`.
1445 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to `true`.
1446 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to `true`.
1447 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to `true`.
1448 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to `true`.
1449 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to `false`.
1450 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a service to be considered flapping. `30.0`
1451 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a service to be considered not flapping. `25.0`
1452 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to `true`.
1453 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.
1454 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
1455 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.
1456 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.
1457 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
1458 notes | String | **Optional.** Notes for the service.
1459 notes\_url | String | **Optional.** URL for notes for the service (for example, in notification commands).
1460 action\_url | String | **Optional.** URL for actions for the service (for example, an external graphing tool).
1461 icon\_image | String | **Optional.** Icon image for the service. Used by external interfaces only.
1462 icon\_image\_alt | String | **Optional.** Icon image description for the service. Used by external interface only.
1464 Service objects have composite names, i.e. their names are based on the host\_name attribute and the name you specified. This means
1465 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1467 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
1468 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
1472 Name | Type | Description
1473 --------------------------|-----------------------|----------------------------------
1474 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
1475 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
1476 check\_attempt | Number | The current check attempt number.
1477 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1478 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1479 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1480 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
1481 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
1482 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
1483 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1484 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1485 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1486 downtime\_depth | Number | Whether the service has one or more active downtimes.
1487 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
1488 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
1489 flapping | Boolean | Whether the host is flapping between states.
1490 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1491 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1492 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1493 last\_state\_ok | Timestamp | When the last OK state occurred (as a UNIX timestamp).
1494 last\_state\_warning | Timestamp | When the last WARNING state occurred (as a UNIX timestamp).
1495 last\_state\_critical | Timestamp | When the last CRITICAL state occurred (as a UNIX timestamp).
1496 last\_state\_unknown | Timestamp | When the last UNKNOWN state occurred (as a UNIX timestamp).
1499 ## ServiceGroup <a id="objecttype-servicegroup"></a>
1501 A group of services.
1505 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
1510 object ServiceGroup "snmp" {
1511 display_name = "SNMP services"
1515 Configuration Attributes:
1517 Name | Type | Description
1518 --------------------------|-----------------------|----------------------------------
1519 display\_name | String | **Optional.** A short description of the service group.
1520 groups | Array of object names | **Optional.** An array of nested group names.
1523 ## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1525 Periodically writes status and configuration data files which are used by third-party tools.
1526 This configuration object is available as [statusdata feature](14-features.md#status-data).
1531 object StatusDataWriter "status" {
1532 status_path = "/var/cache/icinga2/status.dat"
1533 objects_path = "/var/cache/icinga2/objects.cache"
1534 update_interval = 30s
1538 Configuration Attributes:
1540 Name | Type | Description
1541 --------------------------|-----------------------|----------------------------------
1542 status\_path | String | **Optional.** Path to the `status.dat` file. Defaults to CacheDir + "/status.dat".
1543 objects\_path | String | **Optional.** Path to the `objects.cache` file. Defaults to CacheDir + "/objects.cache".
1544 update\_interval | Duration | **Optional.** The interval in which the status files are updated. Defaults to `15s`.
1547 ## SyslogLogger <a id="objecttype-sysloglogger"></a>
1549 Specifies Icinga 2 logging to syslog.
1550 This configuration object is available as `syslog` [logging feature](14-features.md#logging).
1555 object SyslogLogger "syslog" {
1556 severity = "warning"
1560 Configuration Attributes:
1562 Name | Type | Description
1563 --------------------------|-----------------------|----------------------------------
1564 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1565 facility | String | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`.
1569 Name | Facility | Description
1570 ---------------------|---------------|----------------
1571 FacilityAuth | LOG\_AUTH | The authorization system.
1572 FacilityAuthPriv | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals.
1573 FacilityCron | LOG\_CRON | The cron daemon.
1574 FacilityDaemon | LOG\_DAEMON | System daemons that are not provided for explicitly by other facilities.
1575 FacilityFtp | LOG\_FTP | The file transfer protocol daemons.
1576 FacilityKern | LOG\_KERN | Messages generated by the kernel. These cannot be generated by any user processes.
1577 FacilityLocal0 | LOG\_LOCAL0 | Reserved for local use.
1578 FacilityLocal1 | LOG\_LOCAL1 | Reserved for local use.
1579 FacilityLocal2 | LOG\_LOCAL2 | Reserved for local use.
1580 FacilityLocal3 | LOG\_LOCAL3 | Reserved for local use.
1581 FacilityLocal4 | LOG\_LOCAL4 | Reserved for local use.
1582 FacilityLocal5 | LOG\_LOCAL5 | Reserved for local use.
1583 FacilityLocal6 | LOG\_LOCAL6 | Reserved for local use.
1584 FacilityLocal7 | LOG\_LOCAL7 | Reserved for local use.
1585 FacilityLpr | LOG\_LPR | The line printer spooling system.
1586 FacilityMail | LOG\_MAIL | The mail system.
1587 FacilityNews | LOG\_NEWS | The network news system.
1588 FacilitySyslog | LOG\_SYSLOG | Messages generated internally by syslogd.
1589 FacilityUser | LOG\_USER | Messages generated by user processes. This is the default facility identifier if none is specified.
1590 FacilityUucp | LOG\_UUCP | The UUCP system.
1592 ## TimePeriod <a id="objecttype-timeperiod"></a>
1594 Time periods can be used to specify when hosts/services should be checked or to limit
1595 when notifications should be sent out.
1600 object TimePeriod "nonworkhours" {
1601 display_name = "Icinga 2 TimePeriod for non working hours"
1604 monday = "00:00-8:00,17:00-24:00"
1605 tuesday = "00:00-8:00,17:00-24:00"
1606 wednesday = "00:00-8:00,17:00-24:00"
1607 thursday = "00:00-8:00,17:00-24:00"
1608 friday = "00:00-8:00,16:00-24:00"
1609 saturday = "00:00-24:00"
1610 sunday = "00:00-24:00"
1614 object TimePeriod "exampledays" {
1615 display_name = "Icinga 2 TimePeriod for random example days"
1618 //We still believe in Santa, no peeking!
1619 //Applies every 25th of December every year
1620 "december 25" = "00:00-24:00"
1622 //Any point in time can be specified,
1623 //but you still have to use a range
1624 "2038-01-19" = "03:13-03:15"
1626 //Evey 3rd day from the second monday of February
1627 //to 8th of November
1628 "monday 2 february - november 8 / 3" = "00:00-24:00"
1633 Additional examples can be found [here](08-advanced-topics.md#timeperiods).
1635 Configuration Attributes:
1637 Name | Type | Description
1638 --------------------------|-----------------------|----------------------------------
1639 display\_name | String | **Optional.** A short description of the time period.
1640 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1641 prefer\_includes | Boolean | **Optional.** Whether to prefer timeperiods `includes` or `excludes`. Default to true.
1642 excludes | Array of object names | **Optional.** An array of timeperiods, which should exclude from your timerange.
1643 includes | Array of object names | **Optional.** An array of timeperiods, which should include into your timerange
1648 Name | Type | Description
1649 --------------------------|-----------------------|----------------------------------
1650 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1653 ## User <a id="objecttype-user"></a>
1660 object User "icingaadmin" {
1661 display_name = "Icinga 2 Admin"
1662 groups = [ "icingaadmins" ]
1663 email = "icinga@localhost"
1664 pager = "icingaadmin@localhost.localdomain"
1668 states = [ OK, Warning, Critical, Unknown ]
1669 types = [ Problem, Recovery ]
1671 vars.additional_notes = "This is the Icinga 2 Admin account."
1675 Available notification state filters:
1684 Available notification type filters:
1696 Configuration Attributes:
1698 Name | Type | Description
1699 --------------------------|-----------------------|----------------------------------
1700 display\_name | String | **Optional.** A short description of the user.
1701 email | String | **Optional.** An email string for this user. Useful for notification commands.
1702 pager | String | **Optional.** A pager string for this user. Useful for notification commands.
1703 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this user.
1704 groups | Array of object names | **Optional.** An array of group names.
1705 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled for this user. Defaults to true.
1706 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.
1707 types | Array | **Optional.** A set of type filters when a notification for this user should be triggered. By default everything is matched.
1708 states | Array | **Optional.** A set of state filters when a notification for this should be triggered. By default everything is matched.
1712 Name | Type | Description
1713 --------------------------|-----------------------|----------------------------------
1714 last\_notification | Timestamp | When the last notification was sent for this user (as a UNIX timestamp).
1716 ## UserGroup <a id="objecttype-usergroup"></a>
1722 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
1727 object UserGroup "icingaadmins" {
1728 display_name = "Icinga 2 Admin Group"
1732 Configuration Attributes:
1734 Name | Type | Description
1735 --------------------------|-----------------------|----------------------------------
1736 display\_name | String | **Optional.** A short description of the user group.
1737 groups | Array of object names | **Optional.** An array of nested group names.
1740 ## Zone <a id="objecttype-zone"></a>
1742 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1743 Please read the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring) for additional details.
1747 object Zone "master" {
1748 endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]
1752 object Zone "satellite" {
1753 endpoints = [ "icinga2-satellite1.localdomain" ]
1758 Configuration Attributes:
1760 Name | Type | Description
1761 --------------------------|-----------------------|----------------------------------
1762 endpoints | Array of object names | **Optional.** Array of endpoint names located in this zone.
1763 parent | Object name | **Optional.** The name of the parent zone.
1764 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`.
1766 Zone objects cannot currently be created with the API.