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 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`.
65 tls\_protocolmin | String | **Optional.** Minimum TLS protocol version. Must be one of `TLSv1`, `TLSv1.1` or `TLSv1.2`. Defaults to `TLSv1`.
66 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)
67 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)
68 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)
69 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)
70 environment | String | **Optional.** Used as suffix in TLS SNI extension name; default from constant `ApiEnvironment`, which is empty.
72 The attributes `access_control_allow_credentials`, `access_control_allow_headers` and `access_control_allow_methods`
73 are controlled by Icinga 2 and are not changeable by config any more.
76 The ApiListener type expects its certificate files to be in the following locations:
79 ---------------------|-------------------------------------
80 Private key | `DataDir + "/certs/" + NodeName + ".key"`
81 Certificate file | `DataDir + "/certs/" + NodeName + ".crt"`
82 CA certificate file | `DataDir + "/certs/ca.crt"`
84 If the deprecated attributes `cert_path`, `key_path` and/or `ca_path` are specified Icinga 2
85 copies those files to the new location in `DataDir + "/certs"` unless the
86 file(s) there are newer.
88 Please check the [upgrading chapter](16-upgrading-icinga-2.md#upgrading-to-2-8-certificate-paths) for more details.
90 While Icinga 2 and the underlying OpenSSL library use sane and secure defaults, the attributes
91 `cipher_list` and `tls_protocolmin` can be used to increase communication security. A good source
92 for a more secure configuration is provided by the [Mozilla Wiki](https://wiki.mozilla.org/Security/Server_Side_TLS).
93 Ensure to use the same configuration for both attributes on **all** endpoints to avoid communication problems which
94 requires to use `cipher_list` compatible with the endpoint using the oldest version of the OpenSSL library. If using
95 other tools to connect to the API ensure also compatibility with them as this setting affects not only inter-cluster
96 communcation but also the REST API.
98 ## ApiUser <a id="objecttype-apiuser"></a>
100 ApiUser objects are used for authentication against the [Icinga 2 API](12-icinga2-api.md#icinga2-api-authentication).
105 object ApiUser "root" {
106 password = "mysecretapipassword"
107 permissions = [ "*" ]
111 Configuration Attributes:
113 Name | Type | Description
114 --------------------------|-----------------------|----------------------------------
115 password | String | **Optional.** Password string. Note: This attribute is hidden in API responses.
116 client\_cn | String | **Optional.** Client Common Name (CN).
117 permissions | Array | **Required.** Array of permissions. Either as string or dictionary with the keys `permission` and `filter`. The latter must be specified as function.
119 Available permissions are explained in the [API permissions](12-icinga2-api.md#icinga2-api-permissions)
122 ## CheckCommand <a id="objecttype-checkcommand"></a>
124 A check command definition. Additional default command custom attributes can be
130 object CheckCommand "http" {
131 command = [ PluginDir + "/check_http" ]
134 "-H" = "$http_vhost$"
135 "-I" = "$http_address$"
139 set_if = "$http_ssl$"
142 set_if = "$http_sni$"
145 value = "$http_auth_pair$"
146 description = "Username:password on sites with basic authentication"
149 set_if = "$http_ignore_body$"
151 "-r" = "$http_expect_body_regex$"
152 "-w" = "$http_warn_time$"
153 "-c" = "$http_critical_time$"
154 "-e" = "$http_expect$"
157 vars.http_address = "$address$"
158 vars.http_ssl = false
159 vars.http_sni = false
163 Configuration Attributes:
165 Name | Type | Description
166 --------------------------|-----------------------|----------------------------------
167 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.
168 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
169 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
170 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
171 arguments | Dictionary | **Optional.** A dictionary of command arguments.
174 ### CheckCommand Arguments <a id="objecttype-checkcommand-arguments"></a>
176 Command arguments can be defined as key-value-pairs in the `arguments`
177 dictionary. If the argument requires additional configuration, for example
178 a `description` attribute or an optional condition, the value can be defined
179 as dictionary specifying additional options.
184 vars.x_val = "My command argument value."
194 key = "-Xnew" /* optional, set a new key identifier */
195 description = "My plugin requires this argument for doing X."
196 required = false /* optional, no error if not set */
197 skip_key = false /* always use "-X <value>" */
198 set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
199 order = -1 /* first position */
200 repeat_key = true /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
204 description = "My plugin requires this argument for doing Y."
205 required = false /* optional, no error if not set */
206 skip_key = true /* don't prefix "-Y" only use "<value>" */
207 set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
208 order = 0 /* second position */
209 repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
214 Name | Type | Description
215 --------------------------|-----------------------|----------------------------------
216 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).
217 key | String | Optional argument key overriding the key identifier.
218 description | String | Optional argument description.
219 required | Boolean | Required argument. Execution error if not set. Defaults to false (optional).
220 skip\_key | Boolean | Use the value as argument and skip the key.
221 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.
222 order | Number | Set if multiple arguments require a defined argument order.
223 repeat\_key | Boolean | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
228 ..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...
231 Argument array with `repeat_key = true`:
234 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'
237 Argument array with `repeat_key = false`:
240 'key' 'value[0]' 'value[1]' 'value[2]'
243 ## CheckerComponent <a id="objecttype-checkcomponent"></a>
245 The checker component is responsible for scheduling active checks.
246 This configuration object is available as [checker feature](11-cli-commands.md#cli-command-feature).
251 object CheckerComponent "checker" { }
254 Configuration Attributes:
256 Name | Type | Description
257 --------------------------|-----------------------|----------------------------------
258 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`.
260 ## CheckResultReader <a id="objecttype-checkresultreader"></a>
262 Reads Icinga 1.x check result files from a directory. This functionality is provided
263 to help existing Icinga 1.x users and might be useful for migration scenarios.
268 object CheckResultReader "reader" {
269 spool_dir = "/data/check-results"
273 Configuration Attributes:
275 Name | Type | Description
276 --------------------------|-----------------------|----------------------------------
277 spool\_dir | String | **Optional.** The directory which contains the check result files. Defaults to DataDir + "/spool/checkresults/".
279 ## Comment <a id="objecttype-comment"></a>
281 Comments created at runtime are represented as objects.
282 Note: This is for reference only. You can create comments
283 with the [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) API action.
288 object Comment "localhost!my-comment" {
289 host_name = "localhost"
290 author = "icingaadmin"
291 text = "This is a comment."
295 Configuration Attributes:
297 Name | Type | Description
298 --------------------------|-----------------------|----------------------------------
299 host\_name | Object name | **Required.** The name of the host this comment belongs to.
300 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.
301 author | String | **Required.** The author's name.
302 text | String | **Required.** The comment text.
303 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this comment was added.
304 entry\_type | Number | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
305 expire\_time | Timestamp | **Optional.** The comment's expire time as UNIX timestamp.
306 persistent | Boolean | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
308 ## CompatLogger <a id="objecttype-compatlogger"></a>
310 Writes log files in a format that's compatible with Icinga 1.x.
311 This configuration object is available as [compatlog feature](14-features.md#compat-logging).
316 object CompatLogger "compatlog" {
317 log_dir = "/var/log/icinga2/compat"
318 rotation_method = "DAILY"
322 Configuration Attributes:
324 Name | Type | Description
325 --------------------------|-----------------------|----------------------------------
326 log\_dir | String | **Optional.** Path to the compat log directory. Defaults to LogDir + "/compat".
327 rotation\_method | String | **Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
330 ## Dependency <a id="objecttype-dependency"></a>
332 Dependency objects are used to specify dependencies between hosts and services. Dependencies
333 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
338 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
339 > to just create a `Dependency` template and use the `apply` keyword to assign the
340 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
341 > type for `Host` or `Service`.
342 > Check the [dependencies](03-monitoring-basics.md#dependencies) chapter for detailed examples.
344 Service-to-Service Example:
347 object Dependency "webserver-internet" {
348 parent_host_name = "internet"
349 parent_service_name = "ping4"
351 child_host_name = "webserver"
352 child_service_name = "ping4"
354 states = [ OK, Warning ]
356 disable_checks = true
360 Host-to-Host Example:
363 object Dependency "webserver-internet" {
364 parent_host_name = "internet"
366 child_host_name = "webserver"
370 disable_checks = true
374 Configuration Attributes:
376 Name | Type | Description
377 --------------------------|-----------------------|----------------------------------
378 parent\_host\_name | Object name | **Required.** The parent host.
379 parent\_service\_name | Object name | **Optional.** The parent service. If omitted, this dependency object is treated as host dependency.
380 child\_host\_name | Object name | **Required.** The child host.
381 child\_service\_name | Object name | **Optional.** The child service. If omitted, this dependency object is treated as host dependency.
382 disable\_checks | Boolean | **Optional.** Whether to disable checks when this dependency fails. Defaults to false.
383 disable\_notifications | Boolean | **Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
384 ignore\_soft\_states | Boolean | **Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
385 period | Object name | **Optional.** Time period object during which this dependency is enabled.
386 states | Array | **Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
388 Available state filters:
397 When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
398 automatically determined by Icinga 2.
400 Service-to-Host Dependency Example:
403 apply Dependency "internet" to Service {
404 parent_host_name = "dsl-router"
405 disable_checks = true
407 assign where host.name != "dsl-router"
411 This example sets all service objects matching the assign condition into a dependency relation to
412 the parent host object `dsl-router` as implicit child services.
414 Service-to-Service-on-the-same-Host Dependency Example:
417 apply Dependency "disable-agent-checks" to Service {
418 parent_service_name = "agent-health"
420 assign where service.check_command == "ssh"
421 ignore where service.name == "agent-health"
425 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
426 host object matched by the apply rule condition. All services where apply matches are made implicit child services
427 in this dependency relation.
430 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
431 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
432 `child_service_name` attributes has a different value.
434 ## Downtime <a id="objecttype-downtime"></a>
436 Downtimes created at runtime are represented as objects.
437 You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action.
442 object Downtime "my-downtime" {
443 host_name = "localhost"
444 author = "icingaadmin"
445 comment = "This is a downtime."
446 start_time = 1505312869
447 end_time = 1505312924
451 Configuration Attributes:
453 Name | Type | Description
454 --------------------------|-----------------------|----------------------------------
455 host\_name | Object name | **Required.** The name of the host this comment belongs to.
456 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.
457 author | String | **Required.** The author's name.
458 comment | String | **Required.** The comment text.
459 start\_time | Timestamp | **Required.** The start time as UNIX timestamp.
460 end\_time | Timestamp | **Required.** The end time as UNIX timestamp.
461 duration | Number | **Optional.** The duration as number.
462 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this downtime was added.
463 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).
464 triggers | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime.
468 Name | Type | Description
469 --------------------------|-----------------------|----------------------------------
470 trigger\_time | Timestamp | The UNIX timestamp when this downtime was triggered.
471 triggered\_by | Object name | The name of the downtime this downtime was triggered by.
474 ## ElasticsearchWriter <a id="objecttype-elasticsearchwriter"></a>
476 Writes check result metrics and performance data to an Elasticsearch instance.
477 This configuration object is available as [elasticsearch feature](14-features.md#elasticsearch-writer).
482 object ElasticsearchWriter "elasticsearch" {
487 enable_send_perfdata = true
489 flush_threshold = 1024
494 The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
496 Configuration Attributes:
498 Name | Type | Description
499 --------------------------|-----------------------|----------------------------------
500 host | String | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
501 port | Number | **Required.** Elasticsearch port. Defaults to `9200`.
502 index | String | **Required.** Elasticsearch index name. Defaults to `icinga2`.
503 enable\_send\_perfdata | Boolean | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
504 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to Elasticsearch. Defaults to `10s`.
505 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to `1024`.
506 username | String | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
507 password | String | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
508 enable\_tls | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
509 ca\_path | String | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
510 cert\_path | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
511 key\_path | String | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
513 Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
514 Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
516 Basic auth is supported with the `username` and `password` attributes. This requires an
517 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/)
520 TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
521 you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
523 ## Endpoint <a id="objecttype-endpoint"></a>
525 Endpoint objects are used to specify connection information for remote
526 Icinga 2 instances. More details can be found in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
531 object Endpoint "icinga2-client1.localdomain" {
532 host = "192.168.56.111"
538 Example (disable replay log):
541 object Endpoint "icinga2-client1.localdomain" {
542 host = "192.168.5.111"
548 Configuration Attributes:
550 Name | Type | Description
551 --------------------------|-----------------------|----------------------------------
552 host | String | **Optional.** The hostname/IP address of the remote Icinga 2 instance.
553 port | Number | **Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
554 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.
556 Endpoint objects cannot currently be created with the API.
558 ## EventCommand <a id="objecttype-eventcommand"></a>
560 An event command definition.
565 object EventCommand "restart-httpd-event" {
566 command = "/opt/bin/restart-httpd.sh"
571 Configuration Attributes:
573 Name | Type | Description
574 --------------------------|-----------------------|----------------------------------
575 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.
576 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
577 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
578 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
579 arguments | Dictionary | **Optional.** A dictionary of command arguments.
581 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
583 More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
585 ## ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
587 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
588 This configuration object is available as [command feature](14-features.md#external-commands).
593 object ExternalCommandListener "command" {
594 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
598 Configuration Attributes:
600 Name | Type | Description
601 --------------------------|-----------------------|----------------------------------
602 command\_path | String | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
606 ## FileLogger <a id="objecttype-filelogger"></a>
608 Specifies Icinga 2 logging to a file.
609 This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging).
614 object FileLogger "debug-file" {
616 path = "/var/log/icinga2/debug.log"
620 Configuration Attributes:
622 Name | Type | Description
623 --------------------------|-----------------------|----------------------------------
624 path | String | **Required.** The log path.
625 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
628 ## GelfWriter <a id="objecttype-gelfwriter"></a>
630 Writes event log entries to a defined GELF receiver host (Graylog, Logstash).
631 This configuration object is available as [gelf feature](14-features.md#gelfwriter).
636 object GelfWriter "gelf" {
642 Configuration Attributes:
644 Name | Type | Description
645 --------------------------|-----------------------|----------------------------------
646 host | String | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`.
647 port | Number | **Optional.** GELF receiver port. Defaults to `12201`.
648 source | String | **Optional.** Source name for this instance. Defaults to `icinga2`.
649 enable\_send\_perfdata | Boolean | **Optional.** Enable performance data for 'CHECK RESULT' events.
652 ## GraphiteWriter <a id="objecttype-graphitewriter"></a>
654 Writes check result metrics and performance data to a defined
655 Graphite Carbon host.
656 This configuration object is available as [graphite feature](14-features.md#graphite-carbon-cache-writer).
661 object GraphiteWriter "graphite" {
667 Configuration Attributes:
669 Name | Type | Description
670 --------------------------|-----------------------|----------------------------------
671 host | String | **Optional.** Graphite Carbon host address. Defaults to `127.0.0.1`.
672 port | Number | **Optional.** Graphite Carbon port. Defaults to `2003`.
673 host\_name\_template | String | **Optional.** Metric prefix for host name. Defaults to `icinga2.$host.name$.host.$host.check_command$`.
674 service\_name\_template | String | **Optional.** Metric prefix for service name. Defaults to `icinga2.$host.name$.services.$service.name$.$service.check_command$`.
675 enable\_send\_thresholds | Boolean | **Optional.** Send additional threshold metrics. Defaults to `false`.
676 enable\_send\_metadata | Boolean | **Optional.** Send additional metadata metrics. Defaults to `false`.
678 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
682 ## Host <a id="objecttype-host"></a>
689 object Host "icinga2-client1.localdomain" {
690 display_name = "Linux Client 1"
691 address = "192.168.56.111"
692 address6 = "2a00:1450:4001:815::2003"
694 groups = [ "linux-servers" ]
696 check_command = "hostalive"
700 Configuration Attributes:
702 Name | Type | Description
703 --------------------------|-----------------------|----------------------------------
704 display\_name | String | **Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
705 address | String | **Optional.** The host's IPv4 address. Available as command runtime macro `$address$` if set.
706 address6 | String | **Optional.** The host's IPv6 address. Available as command runtime macro `$address6$` if set.
707 groups | Array of object names | **Optional.** A list of host groups this host belongs to.
708 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this host.
709 check\_command | Object name | **Required.** The name of the check command.
710 max\_check\_attempts | Number | **Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
711 check\_period | Object name | **Optional.** The name of a time period which determines when this host should be checked. Not set by default.
712 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
713 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`.
714 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`.
715 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to true.
716 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to true.
717 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to true.
718 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to true.
719 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to false.
720 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to true.
721 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.
722 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a host to be considered flapping. Default `30.0`
723 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a host to be considered not flapping. Default `25.0`
724 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
725 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.
726 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
727 notes | String | **Optional.** Notes for the host.
728 notes\_url | String | **Optional.** URL for notes for the host (for example, in notification commands).
729 action\_url | String | **Optional.** URL for actions for the host (for example, an external graphing tool).
730 icon\_image | String | **Optional.** Icon image for the host. Used by external interfaces only.
731 icon\_image\_alt | String | **Optional.** Icon image description for the host. Used by external interface only.
733 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
734 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
738 > The `address` and `address6` attributes are required for running commands using
739 > the `$address$` and `$address6$` runtime macros.
743 Name | Type | Description
744 --------------------------|-----------------------|----------------------------------
745 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
746 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
747 check\_attempt | Number | The current check attempt number.
748 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
749 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
750 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
751 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
752 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
753 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
754 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
755 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
756 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
757 downtime\_depth | Number | Whether the host has one or more active downtimes.
758 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
759 flapping | Boolean | Whether the host is flapping between states.
760 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
761 state | Number | The current state (0 = UP, 1 = DOWN).
762 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
763 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
764 last\_state\_up | Timestamp | When the last UP state occurred (as a UNIX timestamp).
765 last\_state\_down | Timestamp | When the last DOWN state occurred (as a UNIX timestamp).
769 ## HostGroup <a id="objecttype-hostgroup"></a>
775 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
780 object HostGroup "linux-servers" {
781 display_name = "Linux Servers"
783 assign where host.vars.os == "Linux"
787 Configuration Attributes:
789 Name | Type | Description
790 --------------------------|-----------------------|----------------------------------
791 display\_name | String | **Optional.** A short description of the host group.
792 groups | Array of object names | **Optional.** An array of nested group names.
794 ## IcingaApplication <a id="objecttype-icingaapplication"></a>
796 The IcingaApplication object is required to start Icinga 2.
797 The object name must be `app`. If the object configuration
798 is missing, Icinga 2 will automatically create an IcingaApplication
804 object IcingaApplication "app" {
805 enable_perfdata = false
809 Configuration Attributes:
811 Name | Type | Description
812 --------------------------|-----------------------|----------------------------------
813 enable\_notifications | Boolean | **Optional.** Whether notifications are globally enabled. Defaults to true.
814 enable\_event\_handlers | Boolean | **Optional.** Whether event handlers are globally enabled. Defaults to true.
815 enable\_flapping | Boolean | **Optional.** Whether flap detection is globally enabled. Defaults to true.
816 enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true.
817 enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true.
818 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true.
819 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally.
820 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.
822 ## IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
824 IDO database adapter for MySQL.
825 This configuration object is available as [ido-mysql feature](14-features.md#db-ido).
830 object IdoMysqlConnection "mysql-ido" {
838 downtimehistory_age = 48h
839 contactnotifications_age = 31d
844 Configuration Attributes:
846 Name | Type | Description
847 --------------------------|-----------------------|----------------------------------
848 host | String | **Optional.** MySQL database host address. Defaults to `localhost`.
849 port | Number | **Optional.** MySQL database port. Defaults to `3306`.
850 socket\_path | String | **Optional.** MySQL socket path.
851 user | String | **Optional.** MySQL database user with read/write permission to the icinga database. Defaults to `icinga`.
852 password | String | **Optional.** MySQL database user's password. Defaults to `icinga`.
853 database | String | **Optional.** MySQL database name. Defaults to `icinga`.
854 enable\_ssl | Boolean | **Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
855 ssl\_key | String | **Optional.** MySQL SSL client key file path.
856 ssl\_cert | String | **Optional.** MySQL SSL certificate file path.
857 ssl\_ca | String | **Optional.** MySQL SSL certificate authority certificate file path.
858 ssl\_capath | String | **Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
859 ssl\_cipher | String | **Optional.** MySQL SSL list of allowed ciphers.
860 table\_prefix | String | **Optional.** MySQL database table prefix. Defaults to `icinga_`.
861 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
862 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
863 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".
864 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`.
865 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
866 categories | Array | **Optional.** Array of information types that should be written to the database.
870 Name | Type | Description
871 --------------------------------|-----------------------|----------------------------------
872 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
873 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
874 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
875 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
876 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
877 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
878 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
879 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
880 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
881 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
882 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
883 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
884 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
885 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
886 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
890 Name | Description | Required by
891 ---------------------|------------------------|--------------------
892 DbCatConfig | Configuration data | Icinga Web 2
893 DbCatState | Current state data | Icinga Web 2
894 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
895 DbCatComment | Comments | Icinga Web 2
896 DbCatDowntime | Downtimes | Icinga Web 2
897 DbCatEventHandler | Event handler data | Icinga Web 2
898 DbCatExternalCommand | External commands | --
899 DbCatFlapping | Flap detection data | Icinga Web 2
900 DbCatCheck | Check results | --
901 DbCatLog | Log messages | --
902 DbCatNotification | Notifications | Icinga Web 2
903 DbCatProgramStatus | Program status data | Icinga Web 2
904 DbCatRetention | Retention data | Icinga Web 2
905 DbCatStateHistory | Historical state data | Icinga Web 2
907 The default value for `categories` includes everything required
908 by Icinga Web 2 in the table above.
910 In addition to the category flags listed above the `DbCatEverything`
911 flag may be used as a shortcut for listing all flags.
913 ## IdoPgsqlConnection <a id="objecttype-idopgsqlconnection"></a>
915 IDO database adapter for PostgreSQL.
916 This configuration object is available as [ido-pgsql feature](14-features.md#db-ido).
921 object IdoPgsqlConnection "pgsql-ido" {
929 downtimehistory_age = 48h
930 contactnotifications_age = 31d
935 Configuration Attributes:
937 Name | Type | Description
938 --------------------------|-----------------------|----------------------------------
939 host | String | **Optional.** PostgreSQL database host address. Defaults to `localhost`.
940 port | Number | **Optional.** PostgreSQL database port. Defaults to `5432`.
941 user | String | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`.
942 password | String | **Optional.** PostgreSQL database user's password. Defaults to `icinga`.
943 database | String | **Optional.** PostgreSQL database name. Defaults to `icinga`.
944 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`.
945 ssl\_key | String | **Optional.** PostgreSQL SSL client key file path.
946 ssl\_cert | String | **Optional.** PostgreSQL SSL certificate file path.
947 ssl\_ca | String | **Optional.** PostgreSQL SSL certificate authority certificate file path.
948 table\_prefix | String | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`.
949 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
950 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
951 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".
952 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`.
953 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
954 categories | Array | **Optional.** Array of information types that should be written to the database.
958 Name | Type | Description
959 --------------------------------|-----------------------|----------------------------------
960 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
961 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
962 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
963 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
964 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
965 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
966 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
967 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
968 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
969 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
970 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
971 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
972 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
973 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
974 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
978 Name | Description | Required by
979 ---------------------|------------------------|--------------------
980 DbCatConfig | Configuration data | Icinga Web 2
981 DbCatState | Current state data | Icinga Web 2
982 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
983 DbCatComment | Comments | Icinga Web 2
984 DbCatDowntime | Downtimes | Icinga Web 2
985 DbCatEventHandler | Event handler data | Icinga Web 2
986 DbCatExternalCommand | External commands | --
987 DbCatFlapping | Flap detection data | Icinga Web 2
988 DbCatCheck | Check results | --
989 DbCatLog | Log messages | --
990 DbCatNotification | Notifications | Icinga Web 2
991 DbCatProgramStatus | Program status data | Icinga Web 2
992 DbCatRetention | Retention data | Icinga Web 2
993 DbCatStateHistory | Historical state data | Icinga Web 2
995 The default value for `categories` includes everything required
996 by Icinga Web 2 in the table above.
998 In addition to the category flags listed above the `DbCatEverything`
999 flag may be used as a shortcut for listing all flags.
1001 ## InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
1003 Writes check result metrics and performance data to a defined InfluxDB host.
1004 This configuration object is available as [influxdb feature](14-features.md#influxdb-writer).
1009 object InfluxdbWriter "influxdb" {
1012 database = "icinga2"
1014 flush_threshold = 1024
1015 flush_interval = 10s
1018 measurement = "$host.check_command$"
1020 hostname = "$host.name$"
1023 service_template = {
1024 measurement = "$service.check_command$"
1026 hostname = "$host.name$"
1027 service = "$service.name$"
1033 Configuration Attributes:
1035 Name | Type | Description
1036 --------------------------|-----------------------|----------------------------------
1037 host | String | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
1038 port | Number | **Required.** InfluxDB HTTP port. Defaults to `8086`.
1039 database | String | **Required.** InfluxDB database name. Defaults to `icinga2`.
1040 username | String | **Optional.** InfluxDB user name. Defaults to `none`.
1041 password | String | **Optional.** InfluxDB user password. Defaults to `none`.
1042 ssl\_enable | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`.
1043 ssl\_ca\_cert | String | **Optional.** Path to CA certificate to validate the remote host.
1044 ssl\_cert | String | **Optional.** Path to host certificate to present to the remote host for mutual verification.
1045 ssl\_key | String | **Optional.** Path to host key to accompany the ssl\_cert.
1046 host\_template | String | **Required.** Host template to define the InfluxDB line protocol.
1047 service\_template | String | **Required.** Service template to define the influxDB line protocol.
1048 enable\_send\_thresholds | Boolean | **Optional.** Whether to send warn, crit, min & max tagged data.
1049 enable\_send\_metadata | Boolean | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
1050 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to InfluxDB. Defaults to `10s`.
1051 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`.
1053 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
1054 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
1059 ## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
1061 Livestatus API interface available as TCP or UNIX socket. Historical table queries
1062 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
1063 pointing to the log files using the `compat_log_path` configuration attribute.
1064 This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus).
1069 object LivestatusListener "livestatus-tcp" {
1071 bind_host = "127.0.0.1"
1075 object LivestatusListener "livestatus-unix" {
1076 socket_type = "unix"
1077 socket_path = "/var/run/icinga2/cmd/livestatus"
1081 Configuration Attributes:
1083 Name | Type | Description
1084 --------------------------|-----------------------|----------------------------------
1085 socket\_type | String | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`.
1086 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`.
1087 bind\_port | Number | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`.
1088 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".
1089 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"
1093 > UNIX sockets are not supported on Windows.
1096 ## Notification <a id="objecttype-notification"></a>
1098 Notification objects are used to specify how users should be notified in case
1099 of host and service state changes and other events.
1103 > Rather than creating a `Notification` object for a specific host or service it is
1104 > usually easier to just create a `Notification` template and use the `apply` keyword
1105 > to assign the notification to a number of hosts or services. Use the `to` keyword
1106 > to set the specific target type for `Host` or `Service`.
1107 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
1112 object Notification "localhost-ping-notification" {
1113 host_name = "localhost"
1114 service_name = "ping4"
1116 command = "mail-notification"
1118 users = [ "user1", "user2" ] // reference to User objects
1120 types = [ Problem, Recovery ]
1121 states = [ Critical, Warning, OK ]
1125 Configuration Attributes:
1127 Name | Type | Description
1128 --------------------------|-----------------------|----------------------------------
1129 host\_name | Object name | **Required.** The name of the host this notification belongs to.
1130 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.
1131 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
1132 users | Array of object names | **Required.** A list of user names who should be notified. **Optional.** if the `user_groups` attribute is set.
1133 user\_groups | Array of object names | **Required.** A list of user group names who should be notified. **Optional.** if the `users` attribute is set.
1134 times | Dictionary | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
1135 command | Object name | **Required.** The name of the notification command which should be executed when the notification is triggered.
1136 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.
1137 period | Object name | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
1138 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.
1139 types | Array | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
1140 states | Array | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
1142 Available notification state filters for Service:
1149 Available notification state filters for Host:
1154 Available notification type filters:
1168 Name | Type | Description
1169 ----------------------------|-----------------------|-----------------
1170 last\_notification | Timestamp | When the last notification was sent for this Notification object (as a UNIX timestamp).
1171 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).
1172 notification\_number | Number | The notification number.
1173 last\_problem\_notification | Timestamp | When the last notification was sent for a problem (as a UNIX timestamp).
1176 ## NotificationCommand <a id="objecttype-notificationcommand"></a>
1178 A notification command definition.
1183 object NotificationCommand "mail-service-notification" {
1184 command = [ ConfigDir + "/scripts/mail-service-notification.sh" ]
1189 value = "$notification_address$"
1191 "-6" = "$notification_address6$"
1192 "-b" = "$notification_author$"
1193 "-c" = "$notification_comment$"
1196 value = "$notification_date$"
1200 value = "$notification_servicename$"
1203 value = "$notification_from$"
1204 description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
1206 "-i" = "$notification_icingaweb2url$"
1209 value = "$notification_hostname$"
1213 value = "$notification_hostdisplayname$"
1217 value = "$notification_serviceoutput$"
1221 value = "$notification_useremail$"
1225 value = "$notification_servicestate$"
1229 value = "$notification_type$"
1233 value = "$notification_servicedisplayname$"
1235 "-v" = "$notification_logtosyslog$"
1239 notification_address = "$address$"
1240 notification_address6 = "$address6$"
1241 notification_author = "$notification.author$"
1242 notification_comment = "$notification.comment$"
1243 notification_type = "$notification.type$"
1244 notification_date = "$icinga.long_date_time$"
1245 notification_hostname = "$host.name$"
1246 notification_hostdisplayname = "$host.display_name$"
1247 notification_servicename = "$service.name$"
1248 notification_serviceoutput = "$service.output$"
1249 notification_servicestate = "$service.state$"
1250 notification_useremail = "$user.email$"
1251 notification_servicedisplayname = "$service.display_name$"
1256 Configuration Attributes:
1258 Name | Type | Description
1259 --------------------------|-----------------------|----------------------------------
1260 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.
1261 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1262 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
1263 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
1264 arguments | Dictionary | **Optional.** A dictionary of command arguments.
1266 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
1268 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
1270 ## NotificationComponent <a id="objecttype-notificationcomponent"></a>
1272 The notification component is responsible for sending notifications.
1273 This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature).
1278 object NotificationComponent "notification" { }
1281 Configuration Attributes:
1283 Name | Type | Description
1284 --------------------------|-----------------------|----------------------------------
1285 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".
1287 ## OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1289 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1290 This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer).
1295 object OpenTsdbWriter "opentsdb" {
1301 Configuration Attributes:
1303 Name | Type | Description
1304 --------------------------|-----------------------|----------------------------------
1305 host | String | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`.
1306 port | Number | **Optional.** OpenTSDB port. Defaults to `4242`.
1309 ## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1311 Writes check result performance data to a defined path using macro
1312 pattern consisting of custom attributes and runtime macros.
1313 This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files).
1318 object PerfdataWriter "perfdata" {
1319 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1321 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1323 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$"
1324 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$"
1326 rotation_interval = 15s
1330 Configuration Attributes:
1332 Name | Type | Description
1333 --------------------------|-----------------------|----------------------------------
1334 host\_perfdata\_path | String | **Optional.** Path to the host performance data file. Defaults to SpoolDir + "/perfdata/host-perfdata".
1335 service\_perfdata\_path | String | **Optional.** Path to the service performance data file. Defaults to SpoolDir + "/perfdata/service-perfdata".
1336 host\_temp\_path | String | **Optional.** Path to the temporary host file. Defaults to SpoolDir + "/tmp/host-perfdata".
1337 service\_temp\_path | String | **Optional.** Path to the temporary service file. Defaults to SpoolDir + "/tmp/service-perfdata".
1338 host\_format\_template | String | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1339 service\_format\_template | String | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1340 rotation\_interval | Duration | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`.
1342 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1343 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1346 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
1348 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1352 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1353 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1354 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1355 > type for `Host` or `Service`.
1356 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
1361 object ScheduledDowntime "some-downtime" {
1362 host_name = "localhost"
1363 service_name = "ping4"
1365 author = "icingaadmin"
1366 comment = "Some comment"
1372 "sunday" = "02:00-03:00"
1377 Configuration Attributes:
1379 Name | Type | Description
1380 --------------------------|-----------------------|----------------------------------
1381 host\_name | Object name | **Required.** The name of the host this scheduled downtime belongs to.
1382 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.
1383 author | String | **Required.** The author of the downtime.
1384 comment | String | **Required.** A comment for the downtime.
1385 fixed | Boolean | **Optional.** Whether this is a fixed downtime. Defaults to `true`.
1386 duration | Duration | **Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1387 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1389 ScheduledDowntime objects have composite names, i.e. their names are based
1390 on the `host_name` and `service_name` attributes and the
1391 name you specified. This means you can define more than one object
1392 with the same (short) name as long as one of the `host_name` and
1393 `service_name` attributes has a different value.
1396 ## Service <a id="objecttype-service"></a>
1398 Service objects describe network services and how they should be checked
1403 > Rather than creating a `Service` object for a specific host it is usually easier
1404 > to just create a `Service` template and use the `apply` keyword to assign the
1405 > service to a number of hosts.
1406 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
1411 object Service "uptime" {
1412 host_name = "localhost"
1414 display_name = "localhost Uptime"
1416 check_command = "snmp"
1418 vars.snmp_community = "public"
1419 vars.snmp_oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1421 check_interval = 60s
1422 retry_interval = 15s
1424 groups = [ "all-services", "snmp" ]
1428 Configuration Attributes:
1430 Name | Type | Description
1431 --------------------------|-----------------------|----------------------------------
1432 display\_name | String | **Optional.** A short description of the service.
1433 host\_name | Object name | **Required.** The host this service belongs to. There must be a `Host` object with that name.
1434 groups | Array of object names | **Optional.** The service groups this service belongs to.
1435 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this service.
1436 check\_command | Object name | **Required.** The name of the check command.
1437 max\_check\_attempts | Number | **Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1438 check\_period | Object name | **Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1439 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
1440 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`.
1441 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`.
1442 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to `true`.
1443 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to `true`.
1444 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to `true`.
1445 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to `true`.
1446 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to `false`.
1447 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a service to be considered flapping. `30.0`
1448 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a service to be considered not flapping. `25.0`
1449 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to `true`.
1450 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.
1451 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
1452 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.
1453 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.
1454 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
1455 notes | String | **Optional.** Notes for the service.
1456 notes\_url | String | **Optional.** URL for notes for the service (for example, in notification commands).
1457 action\_url | String | **Optional.** URL for actions for the service (for example, an external graphing tool).
1458 icon\_image | String | **Optional.** Icon image for the service. Used by external interfaces only.
1459 icon\_image\_alt | String | **Optional.** Icon image description for the service. Used by external interface only.
1461 Service objects have composite names, i.e. their names are based on the host\_name attribute and the name you specified. This means
1462 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1464 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
1465 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
1469 Name | Type | Description
1470 --------------------------|-----------------------|----------------------------------
1471 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
1472 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
1473 check\_attempt | Number | The current check attempt number.
1474 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1475 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1476 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1477 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
1478 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
1479 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
1480 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1481 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1482 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1483 downtime\_depth | Number | Whether the service has one or more active downtimes.
1484 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
1485 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
1486 flapping | Boolean | Whether the host is flapping between states.
1487 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1488 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1489 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1490 last\_state\_ok | Timestamp | When the last OK state occurred (as a UNIX timestamp).
1491 last\_state\_warning | Timestamp | When the last WARNING state occurred (as a UNIX timestamp).
1492 last\_state\_critical | Timestamp | When the last CRITICAL state occurred (as a UNIX timestamp).
1493 last\_state\_unknown | Timestamp | When the last UNKNOWN state occurred (as a UNIX timestamp).
1496 ## ServiceGroup <a id="objecttype-servicegroup"></a>
1498 A group of services.
1502 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
1507 object ServiceGroup "snmp" {
1508 display_name = "SNMP services"
1512 Configuration Attributes:
1514 Name | Type | Description
1515 --------------------------|-----------------------|----------------------------------
1516 display\_name | String | **Optional.** A short description of the service group.
1517 groups | Array of object names | **Optional.** An array of nested group names.
1520 ## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1522 Periodically writes status and configuration data files which are used by third-party tools.
1523 This configuration object is available as [statusdata feature](14-features.md#status-data).
1528 object StatusDataWriter "status" {
1529 status_path = "/var/cache/icinga2/status.dat"
1530 objects_path = "/var/cache/icinga2/objects.cache"
1531 update_interval = 30s
1535 Configuration Attributes:
1537 Name | Type | Description
1538 --------------------------|-----------------------|----------------------------------
1539 status\_path | String | **Optional.** Path to the `status.dat` file. Defaults to CacheDir + "/status.dat".
1540 objects\_path | String | **Optional.** Path to the `objects.cache` file. Defaults to CacheDir + "/objects.cache".
1541 update\_interval | Duration | **Optional.** The interval in which the status files are updated. Defaults to `15s`.
1544 ## SyslogLogger <a id="objecttype-sysloglogger"></a>
1546 Specifies Icinga 2 logging to syslog.
1547 This configuration object is available as `syslog` [logging feature](14-features.md#logging).
1552 object SyslogLogger "syslog" {
1553 severity = "warning"
1557 Configuration Attributes:
1559 Name | Type | Description
1560 --------------------------|-----------------------|----------------------------------
1561 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1562 facility | String | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`.
1566 Name | Facility | Description
1567 ---------------------|---------------|----------------
1568 FacilityAuth | LOG\_AUTH | The authorization system.
1569 FacilityAuthPriv | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals.
1570 FacilityCron | LOG\_CRON | The cron daemon.
1571 FacilityDaemon | LOG\_DAEMON | System daemons that are not provided for explicitly by other facilities.
1572 FacilityFtp | LOG\_FTP | The file transfer protocol daemons.
1573 FacilityKern | LOG\_KERN | Messages generated by the kernel. These cannot be generated by any user processes.
1574 FacilityLocal0 | LOG\_LOCAL0 | Reserved for local use.
1575 FacilityLocal1 | LOG\_LOCAL1 | Reserved for local use.
1576 FacilityLocal2 | LOG\_LOCAL2 | Reserved for local use.
1577 FacilityLocal3 | LOG\_LOCAL3 | Reserved for local use.
1578 FacilityLocal4 | LOG\_LOCAL4 | Reserved for local use.
1579 FacilityLocal5 | LOG\_LOCAL5 | Reserved for local use.
1580 FacilityLocal6 | LOG\_LOCAL6 | Reserved for local use.
1581 FacilityLocal7 | LOG\_LOCAL7 | Reserved for local use.
1582 FacilityLpr | LOG\_LPR | The line printer spooling system.
1583 FacilityMail | LOG\_MAIL | The mail system.
1584 FacilityNews | LOG\_NEWS | The network news system.
1585 FacilitySyslog | LOG\_SYSLOG | Messages generated internally by syslogd.
1586 FacilityUser | LOG\_USER | Messages generated by user processes. This is the default facility identifier if none is specified.
1587 FacilityUucp | LOG\_UUCP | The UUCP system.
1589 ## TimePeriod <a id="objecttype-timeperiod"></a>
1591 Time periods can be used to specify when hosts/services should be checked or to limit
1592 when notifications should be sent out.
1597 object TimePeriod "nonworkhours" {
1598 display_name = "Icinga 2 TimePeriod for non working hours"
1601 monday = "00:00-8:00,17:00-24:00"
1602 tuesday = "00:00-8:00,17:00-24:00"
1603 wednesday = "00:00-8:00,17:00-24:00"
1604 thursday = "00:00-8:00,17:00-24:00"
1605 friday = "00:00-8:00,16:00-24:00"
1606 saturday = "00:00-24:00"
1607 sunday = "00:00-24:00"
1611 object TimePeriod "exampledays" {
1612 display_name = "Icinga 2 TimePeriod for random example days"
1615 //We still believe in Santa, no peeking!
1616 //Applies every 25th of December every year
1617 "december 25" = "00:00-24:00"
1619 //Any point in time can be specified,
1620 //but you still have to use a range
1621 "2038-01-19" = "03:13-03:15"
1623 //Evey 3rd day from the second monday of February
1624 //to 8th of November
1625 "monday 2 february - november 8 / 3" = "00:00-24:00"
1630 Additional examples can be found [here](08-advanced-topics.md#timeperiods).
1632 Configuration Attributes:
1634 Name | Type | Description
1635 --------------------------|-----------------------|----------------------------------
1636 display\_name | String | **Optional.** A short description of the time period.
1637 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1638 prefer\_includes | Boolean | **Optional.** Whether to prefer timeperiods `includes` or `excludes`. Default to true.
1639 excludes | Array of object names | **Optional.** An array of timeperiods, which should exclude from your timerange.
1640 includes | Array of object names | **Optional.** An array of timeperiods, which should include into your timerange
1645 Name | Type | Description
1646 --------------------------|-----------------------|----------------------------------
1647 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1650 ## User <a id="objecttype-user"></a>
1657 object User "icingaadmin" {
1658 display_name = "Icinga 2 Admin"
1659 groups = [ "icingaadmins" ]
1660 email = "icinga@localhost"
1661 pager = "icingaadmin@localhost.localdomain"
1665 states = [ OK, Warning, Critical, Unknown ]
1666 types = [ Problem, Recovery ]
1668 vars.additional_notes = "This is the Icinga 2 Admin account."
1672 Available notification state filters:
1681 Available notification type filters:
1693 Configuration Attributes:
1695 Name | Type | Description
1696 --------------------------|-----------------------|----------------------------------
1697 display\_name | String | **Optional.** A short description of the user.
1698 email | String | **Optional.** An email string for this user. Useful for notification commands.
1699 pager | String | **Optional.** A pager string for this user. Useful for notification commands.
1700 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this user.
1701 groups | Array of object names | **Optional.** An array of group names.
1702 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled for this user. Defaults to true.
1703 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.
1704 types | Array | **Optional.** A set of type filters when a notification for this user should be triggered. By default everything is matched.
1705 states | Array | **Optional.** A set of state filters when a notification for this should be triggered. By default everything is matched.
1709 Name | Type | Description
1710 --------------------------|-----------------------|----------------------------------
1711 last\_notification | Timestamp | When the last notification was sent for this user (as a UNIX timestamp).
1713 ## UserGroup <a id="objecttype-usergroup"></a>
1719 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
1724 object UserGroup "icingaadmins" {
1725 display_name = "Icinga 2 Admin Group"
1729 Configuration Attributes:
1731 Name | Type | Description
1732 --------------------------|-----------------------|----------------------------------
1733 display\_name | String | **Optional.** A short description of the user group.
1734 groups | Array of object names | **Optional.** An array of nested group names.
1737 ## Zone <a id="objecttype-zone"></a>
1739 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1740 Please read the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring) for additional details.
1744 object Zone "master" {
1745 endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]
1749 object Zone "satellite" {
1750 endpoints = [ "icinga2-satellite1.localdomain" ]
1755 Configuration Attributes:
1757 Name | Type | Description
1758 --------------------------|-----------------------|----------------------------------
1759 endpoints | Array of object names | **Optional.** Array of endpoint names located in this zone.
1760 parent | Object name | **Optional.** The name of the parent zone.
1761 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`.
1763 Zone objects cannot currently be created with the API.