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)
71 The attributes `access_control_allow_credentials`, `access_control_allow_headers` and `access_control_allow_methods`
72 are controlled by Icinga 2 and are not changeable by config any more.
75 The ApiListener type expects its certificate files to be in the following locations:
78 ---------------------|-------------------------------------
79 Private key | `DataDir + "/certs/" + NodeName + ".key"`
80 Certificate file | `DataDir + "/certs/" + NodeName + ".crt"`
81 CA certificate file | `DataDir + "/certs/ca.crt"`
83 If the deprecated attributes `cert_path`, `key_path` and/or `ca_path` are specified Icinga 2
84 copies those files to the new location in `DataDir + "/certs"` unless the
85 file(s) there are newer.
87 Please check the [upgrading chapter](16-upgrading-icinga-2.md#upgrading-to-2-8-certificate-paths) for more details.
89 While Icinga 2 and the underlying OpenSSL library use sane and secure defaults, the attributes
90 `cipher_list` and `tls_protocolmin` can be used to increase communication security. A good source
91 for a more secure configuration is provided by the [Mozilla Wiki](https://wiki.mozilla.org/Security/Server_Side_TLS).
92 Ensure to use the same configuration for both attributes on **all** endpoints to avoid communication problems which
93 requires to use `cipher_list` compatible with the endpoint using the oldest version of the OpenSSL library. If using
94 other tools to connect to the API ensure also compatibility with them as this setting affects not only inter-cluster
95 communcation but also the REST API.
97 ## ApiUser <a id="objecttype-apiuser"></a>
99 ApiUser objects are used for authentication against the [Icinga 2 API](12-icinga2-api.md#icinga2-api-authentication).
104 object ApiUser "root" {
105 password = "mysecretapipassword"
106 permissions = [ "*" ]
110 Configuration Attributes:
112 Name | Type | Description
113 --------------------------|-----------------------|----------------------------------
114 password | String | **Optional.** Password string. Note: This attribute is hidden in API responses.
115 client\_cn | String | **Optional.** Client Common Name (CN).
116 permissions | Array | **Required.** Array of permissions. Either as string or dictionary with the keys `permission` and `filter`. The latter must be specified as function.
118 Available permissions are explained in the [API permissions](12-icinga2-api.md#icinga2-api-permissions)
121 ## CheckCommand <a id="objecttype-checkcommand"></a>
123 A check command definition. Additional default command custom attributes can be
129 object CheckCommand "http" {
130 command = [ PluginDir + "/check_http" ]
133 "-H" = "$http_vhost$"
134 "-I" = "$http_address$"
138 set_if = "$http_ssl$"
141 set_if = "$http_sni$"
144 value = "$http_auth_pair$"
145 description = "Username:password on sites with basic authentication"
148 set_if = "$http_ignore_body$"
150 "-r" = "$http_expect_body_regex$"
151 "-w" = "$http_warn_time$"
152 "-c" = "$http_critical_time$"
153 "-e" = "$http_expect$"
156 vars.http_address = "$address$"
157 vars.http_ssl = false
158 vars.http_sni = false
162 Configuration Attributes:
164 Name | Type | Description
165 --------------------------|-----------------------|----------------------------------
166 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.
167 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
168 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
169 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
170 arguments | Dictionary | **Optional.** A dictionary of command arguments.
173 ### CheckCommand Arguments <a id="objecttype-checkcommand-arguments"></a>
175 Command arguments can be defined as key-value-pairs in the `arguments`
176 dictionary. If the argument requires additional configuration, for example
177 a `description` attribute or an optional condition, the value can be defined
178 as dictionary specifying additional options.
183 vars.x_val = "My command argument value."
193 key = "-Xnew" /* optional, set a new key identifier */
194 description = "My plugin requires this argument for doing X."
195 required = false /* optional, no error if not set */
196 skip_key = false /* always use "-X <value>" */
197 set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
198 order = -1 /* first position */
199 repeat_key = true /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
203 description = "My plugin requires this argument for doing Y."
204 required = false /* optional, no error if not set */
205 skip_key = true /* don't prefix "-Y" only use "<value>" */
206 set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
207 order = 0 /* second position */
208 repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
213 Name | Type | Description
214 --------------------------|-----------------------|----------------------------------
215 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).
216 key | String | Optional argument key overriding the key identifier.
217 description | String | Optional argument description.
218 required | Boolean | Required argument. Execution error if not set. Defaults to false (optional).
219 skip\_key | Boolean | Use the value as argument and skip the key.
220 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.
221 order | Number | Set if multiple arguments require a defined argument order.
222 repeat\_key | Boolean | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
227 ..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...
230 Argument array with `repeat_key = true`:
233 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'
236 Argument array with `repeat_key = false`:
239 'key' 'value[0]' 'value[1]' 'value[2]'
242 ## CheckerComponent <a id="objecttype-checkcomponent"></a>
244 The checker component is responsible for scheduling active checks.
245 This configuration object is available as [checker feature](11-cli-commands.md#cli-command-feature).
250 object CheckerComponent "checker" { }
253 Configuration Attributes:
255 Name | Type | Description
256 --------------------------|-----------------------|----------------------------------
257 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`.
259 ## CheckResultReader <a id="objecttype-checkresultreader"></a>
261 Reads Icinga 1.x check result files from a directory. This functionality is provided
262 to help existing Icinga 1.x users and might be useful for migration scenarios.
267 object CheckResultReader "reader" {
268 spool_dir = "/data/check-results"
272 Configuration Attributes:
274 Name | Type | Description
275 --------------------------|-----------------------|----------------------------------
276 spool\_dir | String | **Optional.** The directory which contains the check result files. Defaults to DataDir + "/spool/checkresults/".
278 ## Comment <a id="objecttype-comment"></a>
280 Comments created at runtime are represented as objects.
281 Note: This is for reference only. You can create comments
282 with the [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) API action.
287 object Comment "localhost!my-comment" {
288 host_name = "localhost"
289 author = "icingaadmin"
290 text = "This is a comment."
294 Configuration Attributes:
296 Name | Type | Description
297 --------------------------|-----------------------|----------------------------------
298 host\_name | Object name | **Required.** The name of the host this comment belongs to.
299 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.
300 author | String | **Required.** The author's name.
301 text | String | **Required.** The comment text.
302 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this comment was added.
303 entry\_type | Number | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
304 expire\_time | Timestamp | **Optional.** The comment's expire time as UNIX timestamp.
305 persistent | Boolean | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
307 ## CompatLogger <a id="objecttype-compatlogger"></a>
309 Writes log files in a format that's compatible with Icinga 1.x.
310 This configuration object is available as [compatlog feature](14-features.md#compat-logging).
315 object CompatLogger "compatlog" {
316 log_dir = "/var/log/icinga2/compat"
317 rotation_method = "DAILY"
321 Configuration Attributes:
323 Name | Type | Description
324 --------------------------|-----------------------|----------------------------------
325 log\_dir | String | **Optional.** Path to the compat log directory. Defaults to LogDir + "/compat".
326 rotation\_method | String | **Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
329 ## Dependency <a id="objecttype-dependency"></a>
331 Dependency objects are used to specify dependencies between hosts and services. Dependencies
332 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
337 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
338 > to just create a `Dependency` template and use the `apply` keyword to assign the
339 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
340 > type for `Host` or `Service`.
341 > Check the [dependencies](03-monitoring-basics.md#dependencies) chapter for detailed examples.
343 Service-to-Service Example:
346 object Dependency "webserver-internet" {
347 parent_host_name = "internet"
348 parent_service_name = "ping4"
350 child_host_name = "webserver"
351 child_service_name = "ping4"
353 states = [ OK, Warning ]
355 disable_checks = true
359 Host-to-Host Example:
362 object Dependency "webserver-internet" {
363 parent_host_name = "internet"
365 child_host_name = "webserver"
369 disable_checks = true
373 Configuration Attributes:
375 Name | Type | Description
376 --------------------------|-----------------------|----------------------------------
377 parent\_host\_name | Object name | **Required.** The parent host.
378 parent\_service\_name | Object name | **Optional.** The parent service. If omitted, this dependency object is treated as host dependency.
379 child\_host\_name | Object name | **Required.** The child host.
380 child\_service\_name | Object name | **Optional.** The child service. If omitted, this dependency object is treated as host dependency.
381 disable\_checks | Boolean | **Optional.** Whether to disable checks when this dependency fails. Defaults to false.
382 disable\_notifications | Boolean | **Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
383 ignore\_soft\_states | Boolean | **Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
384 period | Object name | **Optional.** Time period object during which this dependency is enabled.
385 states | Array | **Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
387 Available state filters:
396 When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
397 automatically determined by Icinga 2.
399 Service-to-Host Dependency Example:
402 apply Dependency "internet" to Service {
403 parent_host_name = "dsl-router"
404 disable_checks = true
406 assign where host.name != "dsl-router"
410 This example sets all service objects matching the assign condition into a dependency relation to
411 the parent host object `dsl-router` as implicit child services.
413 Service-to-Service-on-the-same-Host Dependency Example:
416 apply Dependency "disable-agent-checks" to Service {
417 parent_service_name = "agent-health"
419 assign where service.check_command == "ssh"
420 ignore where service.name == "agent-health"
424 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
425 host object matched by the apply rule condition. All services where apply matches are made implicit child services
426 in this dependency relation.
429 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
430 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
431 `child_service_name` attributes has a different value.
433 ## Downtime <a id="objecttype-downtime"></a>
435 Downtimes created at runtime are represented as objects.
436 You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action.
441 object Downtime "my-downtime" {
442 host_name = "localhost"
443 author = "icingaadmin"
444 comment = "This is a downtime."
445 start_time = 1505312869
446 end_time = 1505312924
450 Configuration Attributes:
452 Name | Type | Description
453 --------------------------|-----------------------|----------------------------------
454 host\_name | Object name | **Required.** The name of the host this comment belongs to.
455 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.
456 author | String | **Required.** The author's name.
457 comment | String | **Required.** The comment text.
458 start\_time | Timestamp | **Required.** The start time as UNIX timestamp.
459 end\_time | Timestamp | **Required.** The end time as UNIX timestamp.
460 duration | Number | **Optional.** The duration as number.
461 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this downtime was added.
462 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).
463 triggers | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime.
467 Name | Type | Description
468 --------------------------|-----------------------|----------------------------------
469 trigger\_time | Timestamp | The UNIX timestamp when this downtime was triggered.
470 triggered\_by | Object name | The name of the downtime this downtime was triggered by.
473 ## ElasticsearchWriter <a id="objecttype-elasticsearchwriter"></a>
475 Writes check result metrics and performance data to an Elasticsearch instance.
476 This configuration object is available as [elasticsearch feature](14-features.md#elasticsearch-writer).
481 object ElasticsearchWriter "elasticsearch" {
486 enable_send_perfdata = true
488 flush_threshold = 1024
493 The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
495 Configuration Attributes:
497 Name | Type | Description
498 --------------------------|-----------------------|----------------------------------
499 host | String | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
500 port | Number | **Required.** Elasticsearch port. Defaults to `9200`.
501 index | String | **Required.** Elasticsearch index name. Defaults to `icinga2`.
502 enable\_send\_perfdata | Boolean | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
503 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to Elasticsearch. Defaults to `10s`.
504 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to `1024`.
505 username | String | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
506 password | String | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
507 enable\_tls | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
508 ca\_path | String | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
509 cert\_path | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
510 key\_path | String | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
512 Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
513 Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
515 Basic auth is supported with the `username` and `password` attributes. This requires an
516 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/)
519 TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
520 you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
522 ## Endpoint <a id="objecttype-endpoint"></a>
524 Endpoint objects are used to specify connection information for remote
525 Icinga 2 instances. More details can be found in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
530 object Endpoint "icinga2-client1.localdomain" {
531 host = "192.168.56.111"
537 Example (disable replay log):
540 object Endpoint "icinga2-client1.localdomain" {
541 host = "192.168.5.111"
547 Configuration Attributes:
549 Name | Type | Description
550 --------------------------|-----------------------|----------------------------------
551 host | String | **Optional.** The hostname/IP address of the remote Icinga 2 instance.
552 port | Number | **Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
553 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.
555 Endpoint objects cannot currently be created with the API.
557 ## EventCommand <a id="objecttype-eventcommand"></a>
559 An event command definition.
564 object EventCommand "restart-httpd-event" {
565 command = "/opt/bin/restart-httpd.sh"
570 Configuration Attributes:
572 Name | Type | Description
573 --------------------------|-----------------------|----------------------------------
574 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.
575 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
576 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
577 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
578 arguments | Dictionary | **Optional.** A dictionary of command arguments.
580 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
582 More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
584 ## ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
586 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
587 This configuration object is available as [command feature](14-features.md#external-commands).
592 object ExternalCommandListener "command" {
593 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
597 Configuration Attributes:
599 Name | Type | Description
600 --------------------------|-----------------------|----------------------------------
601 command\_path | String | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
605 ## FileLogger <a id="objecttype-filelogger"></a>
607 Specifies Icinga 2 logging to a file.
608 This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging).
613 object FileLogger "debug-file" {
615 path = "/var/log/icinga2/debug.log"
619 Configuration Attributes:
621 Name | Type | Description
622 --------------------------|-----------------------|----------------------------------
623 path | String | **Required.** The log path.
624 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
627 ## GelfWriter <a id="objecttype-gelfwriter"></a>
629 Writes event log entries to a defined GELF receiver host (Graylog, Logstash).
630 This configuration object is available as [gelf feature](14-features.md#gelfwriter).
635 object GelfWriter "gelf" {
641 Configuration Attributes:
643 Name | Type | Description
644 --------------------------|-----------------------|----------------------------------
645 host | String | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`.
646 port | Number | **Optional.** GELF receiver port. Defaults to `12201`.
647 source | String | **Optional.** Source name for this instance. Defaults to `icinga2`.
648 enable\_send\_perfdata | Boolean | **Optional.** Enable performance data for 'CHECK RESULT' events.
651 ## GraphiteWriter <a id="objecttype-graphitewriter"></a>
653 Writes check result metrics and performance data to a defined
654 Graphite Carbon host.
655 This configuration object is available as [graphite feature](14-features.md#graphite-carbon-cache-writer).
660 object GraphiteWriter "graphite" {
666 Configuration Attributes:
668 Name | Type | Description
669 --------------------------|-----------------------|----------------------------------
670 host | String | **Optional.** Graphite Carbon host address. Defaults to `127.0.0.1`.
671 port | Number | **Optional.** Graphite Carbon port. Defaults to `2003`.
672 host\_name\_template | String | **Optional.** Metric prefix for host name. Defaults to `icinga2.$host.name$.host.$host.check_command$`.
673 service\_name\_template | String | **Optional.** Metric prefix for service name. Defaults to `icinga2.$host.name$.services.$service.name$.$service.check_command$`.
674 enable\_send\_thresholds | Boolean | **Optional.** Send additional threshold metrics. Defaults to `false`.
675 enable\_send\_metadata | Boolean | **Optional.** Send additional metadata metrics. Defaults to `false`.
677 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
681 ## Host <a id="objecttype-host"></a>
688 object Host "icinga2-client1.localdomain" {
689 display_name = "Linux Client 1"
690 address = "192.168.56.111"
691 address6 = "2a00:1450:4001:815::2003"
693 groups = [ "linux-servers" ]
695 check_command = "hostalive"
699 Configuration Attributes:
701 Name | Type | Description
702 --------------------------|-----------------------|----------------------------------
703 display\_name | String | **Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
704 address | String | **Optional.** The host's IPv4 address. Available as command runtime macro `$address$` if set.
705 address6 | String | **Optional.** The host's IPv6 address. Available as command runtime macro `$address6$` if set.
706 groups | Array of object names | **Optional.** A list of host groups this host belongs to.
707 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this host.
708 check\_command | Object name | **Required.** The name of the check command.
709 max\_check\_attempts | Number | **Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
710 check\_period | Object name | **Optional.** The name of a time period which determines when this host should be checked. Not set by default.
711 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
712 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`.
713 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`.
714 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to true.
715 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to true.
716 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to true.
717 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to true.
718 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to false.
719 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to true.
720 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.
721 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a host to be considered flapping. Default `30.0`
722 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a host to be considered not flapping. Default `25.0`
723 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
724 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.
725 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
726 notes | String | **Optional.** Notes for the host.
727 notes\_url | String | **Optional.** URL for notes for the host (for example, in notification commands).
728 action\_url | String | **Optional.** URL for actions for the host (for example, an external graphing tool).
729 icon\_image | String | **Optional.** Icon image for the host. Used by external interfaces only.
730 icon\_image\_alt | String | **Optional.** Icon image description for the host. Used by external interface only.
732 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
733 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
737 > The `address` and `address6` attributes are required for running commands using
738 > the `$address$` and `$address6$` runtime macros.
742 Name | Type | Description
743 --------------------------|-----------------------|----------------------------------
744 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
745 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
746 check\_attempt | Number | The current check attempt number.
747 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
748 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
749 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
750 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
751 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
752 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
753 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
754 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
755 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
756 downtime\_depth | Number | Whether the host has one or more active downtimes.
757 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
758 flapping | Boolean | Whether the host is flapping between states.
759 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
760 state | Number | The current state (0 = UP, 1 = DOWN).
761 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
762 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
763 last\_state\_up | Timestamp | When the last UP state occurred (as a UNIX timestamp).
764 last\_state\_down | Timestamp | When the last DOWN state occurred (as a UNIX timestamp).
768 ## HostGroup <a id="objecttype-hostgroup"></a>
774 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
779 object HostGroup "linux-servers" {
780 display_name = "Linux Servers"
782 assign where host.vars.os == "Linux"
786 Configuration Attributes:
788 Name | Type | Description
789 --------------------------|-----------------------|----------------------------------
790 display\_name | String | **Optional.** A short description of the host group.
791 groups | Array of object names | **Optional.** An array of nested group names.
793 ## IcingaApplication <a id="objecttype-icingaapplication"></a>
795 The IcingaApplication object is required to start Icinga 2.
796 The object name must be `app`. If the object configuration
797 is missing, Icinga 2 will automatically create an IcingaApplication
803 object IcingaApplication "app" {
804 enable_perfdata = false
808 Configuration Attributes:
810 Name | Type | Description
811 --------------------------|-----------------------|----------------------------------
812 enable\_notifications | Boolean | **Optional.** Whether notifications are globally enabled. Defaults to true.
813 enable\_event\_handlers | Boolean | **Optional.** Whether event handlers are globally enabled. Defaults to true.
814 enable\_flapping | Boolean | **Optional.** Whether flap detection is globally enabled. Defaults to true.
815 enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true.
816 enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true.
817 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true.
818 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally.
820 ## IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
822 IDO database adapter for MySQL.
823 This configuration object is available as [ido-mysql feature](14-features.md#db-ido).
828 object IdoMysqlConnection "mysql-ido" {
836 downtimehistory_age = 48h
837 contactnotifications_age = 31d
842 Configuration Attributes:
844 Name | Type | Description
845 --------------------------|-----------------------|----------------------------------
846 host | String | **Optional.** MySQL database host address. Defaults to `localhost`.
847 port | Number | **Optional.** MySQL database port. Defaults to `3306`.
848 socket\_path | String | **Optional.** MySQL socket path.
849 user | String | **Optional.** MySQL database user with read/write permission to the icinga database. Defaults to `icinga`.
850 password | String | **Optional.** MySQL database user's password. Defaults to `icinga`.
851 database | String | **Optional.** MySQL database name. Defaults to `icinga`.
852 enable\_ssl | Boolean | **Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
853 ssl\_key | String | **Optional.** MySQL SSL client key file path.
854 ssl\_cert | String | **Optional.** MySQL SSL certificate file path.
855 ssl\_ca | String | **Optional.** MySQL SSL certificate authority certificate file path.
856 ssl\_capath | String | **Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
857 ssl\_cipher | String | **Optional.** MySQL SSL list of allowed ciphers.
858 table\_prefix | String | **Optional.** MySQL database table prefix. Defaults to `icinga_`.
859 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
860 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
861 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".
862 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`.
863 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
864 categories | Array | **Optional.** Array of information types that should be written to the database.
868 Name | Type | Description
869 --------------------------------|-----------------------|----------------------------------
870 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
871 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
872 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
873 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
874 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
875 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
876 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
877 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
878 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
879 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
880 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
881 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
882 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
883 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
884 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
888 Name | Description | Required by
889 ---------------------|------------------------|--------------------
890 DbCatConfig | Configuration data | Icinga Web 2
891 DbCatState | Current state data | Icinga Web 2
892 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
893 DbCatComment | Comments | Icinga Web 2
894 DbCatDowntime | Downtimes | Icinga Web 2
895 DbCatEventHandler | Event handler data | Icinga Web 2
896 DbCatExternalCommand | External commands | --
897 DbCatFlapping | Flap detection data | Icinga Web 2
898 DbCatCheck | Check results | --
899 DbCatLog | Log messages | --
900 DbCatNotification | Notifications | Icinga Web 2
901 DbCatProgramStatus | Program status data | Icinga Web 2
902 DbCatRetention | Retention data | Icinga Web 2
903 DbCatStateHistory | Historical state data | Icinga Web 2
905 The default value for `categories` includes everything required
906 by Icinga Web 2 in the table above.
908 In addition to the category flags listed above the `DbCatEverything`
909 flag may be used as a shortcut for listing all flags.
911 ## IdoPgsqlConnection <a id="objecttype-idopgsqlconnection"></a>
913 IDO database adapter for PostgreSQL.
914 This configuration object is available as [ido-pgsql feature](14-features.md#db-ido).
919 object IdoPgsqlConnection "pgsql-ido" {
927 downtimehistory_age = 48h
928 contactnotifications_age = 31d
933 Configuration Attributes:
935 Name | Type | Description
936 --------------------------|-----------------------|----------------------------------
937 host | String | **Optional.** PostgreSQL database host address. Defaults to `localhost`.
938 port | Number | **Optional.** PostgreSQL database port. Defaults to `5432`.
939 user | String | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`.
940 password | String | **Optional.** PostgreSQL database user's password. Defaults to `icinga`.
941 database | String | **Optional.** PostgreSQL database name. Defaults to `icinga`.
942 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`.
943 ssl\_key | String | **Optional.** PostgreSQL SSL client key file path.
944 ssl\_cert | String | **Optional.** PostgreSQL SSL certificate file path.
945 ssl\_ca | String | **Optional.** PostgreSQL SSL certificate authority certificate file path.
946 table\_prefix | String | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`.
947 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
948 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
949 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".
950 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`.
951 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
952 categories | Array | **Optional.** Array of information types that should be written to the database.
956 Name | Type | Description
957 --------------------------------|-----------------------|----------------------------------
958 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
959 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
960 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
961 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
962 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
963 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
964 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
965 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
966 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
967 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
968 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
969 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
970 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
971 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
972 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
976 Name | Description | Required by
977 ---------------------|------------------------|--------------------
978 DbCatConfig | Configuration data | Icinga Web 2
979 DbCatState | Current state data | Icinga Web 2
980 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
981 DbCatComment | Comments | Icinga Web 2
982 DbCatDowntime | Downtimes | Icinga Web 2
983 DbCatEventHandler | Event handler data | Icinga Web 2
984 DbCatExternalCommand | External commands | --
985 DbCatFlapping | Flap detection data | Icinga Web 2
986 DbCatCheck | Check results | --
987 DbCatLog | Log messages | --
988 DbCatNotification | Notifications | Icinga Web 2
989 DbCatProgramStatus | Program status data | Icinga Web 2
990 DbCatRetention | Retention data | Icinga Web 2
991 DbCatStateHistory | Historical state data | Icinga Web 2
993 The default value for `categories` includes everything required
994 by Icinga Web 2 in the table above.
996 In addition to the category flags listed above the `DbCatEverything`
997 flag may be used as a shortcut for listing all flags.
999 ## InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
1001 Writes check result metrics and performance data to a defined InfluxDB host.
1002 This configuration object is available as [influxdb feature](14-features.md#influxdb-writer).
1007 object InfluxdbWriter "influxdb" {
1010 database = "icinga2"
1012 flush_threshold = 1024
1013 flush_interval = 10s
1016 measurement = "$host.check_command$"
1018 hostname = "$host.name$"
1021 service_template = {
1022 measurement = "$service.check_command$"
1024 hostname = "$host.name$"
1025 service = "$service.name$"
1031 Configuration Attributes:
1033 Name | Type | Description
1034 --------------------------|-----------------------|----------------------------------
1035 host | String | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
1036 port | Number | **Required.** InfluxDB HTTP port. Defaults to `8086`.
1037 database | String | **Required.** InfluxDB database name. Defaults to `icinga2`.
1038 username | String | **Optional.** InfluxDB user name. Defaults to `none`.
1039 password | String | **Optional.** InfluxDB user password. Defaults to `none`.
1040 ssl\_enable | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`.
1041 ssl\_ca\_cert | String | **Optional.** Path to CA certificate to validate the remote host.
1042 ssl\_cert | String | **Optional.** Path to host certificate to present to the remote host for mutual verification.
1043 ssl\_key | String | **Optional.** Path to host key to accompany the ssl\_cert.
1044 host\_template | String | **Required.** Host template to define the InfluxDB line protocol.
1045 service\_template | String | **Required.** Service template to define the influxDB line protocol.
1046 enable\_send\_thresholds | Boolean | **Optional.** Whether to send warn, crit, min & max tagged data.
1047 enable\_send\_metadata | Boolean | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
1048 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to InfluxDB. Defaults to `10s`.
1049 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`.
1051 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
1052 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
1057 ## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
1059 Livestatus API interface available as TCP or UNIX socket. Historical table queries
1060 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
1061 pointing to the log files using the `compat_log_path` configuration attribute.
1062 This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus).
1067 object LivestatusListener "livestatus-tcp" {
1069 bind_host = "127.0.0.1"
1073 object LivestatusListener "livestatus-unix" {
1074 socket_type = "unix"
1075 socket_path = "/var/run/icinga2/cmd/livestatus"
1079 Configuration Attributes:
1081 Name | Type | Description
1082 --------------------------|-----------------------|----------------------------------
1083 socket\_type | String | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`.
1084 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`.
1085 bind\_port | Number | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`.
1086 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".
1087 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"
1091 > UNIX sockets are not supported on Windows.
1094 ## Notification <a id="objecttype-notification"></a>
1096 Notification objects are used to specify how users should be notified in case
1097 of host and service state changes and other events.
1101 > Rather than creating a `Notification` object for a specific host or service it is
1102 > usually easier to just create a `Notification` template and use the `apply` keyword
1103 > to assign the notification to a number of hosts or services. Use the `to` keyword
1104 > to set the specific target type for `Host` or `Service`.
1105 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
1110 object Notification "localhost-ping-notification" {
1111 host_name = "localhost"
1112 service_name = "ping4"
1114 command = "mail-notification"
1116 users = [ "user1", "user2" ] // reference to User objects
1118 types = [ Problem, Recovery ]
1119 states = [ Critical, Warning, OK ]
1123 Configuration Attributes:
1125 Name | Type | Description
1126 --------------------------|-----------------------|----------------------------------
1127 host\_name | Object name | **Required.** The name of the host this notification belongs to.
1128 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.
1129 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
1130 users | Array of object names | **Required.** A list of user names who should be notified. **Optional.** if the `user_groups` attribute is set.
1131 user\_groups | Array of object names | **Required.** A list of user group names who should be notified. **Optional.** if the `users` attribute is set.
1132 times | Dictionary | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
1133 command | Object name | **Required.** The name of the notification command which should be executed when the notification is triggered.
1134 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.
1135 period | Object name | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
1136 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.
1137 types | Array | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
1138 states | Array | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
1140 Available notification state filters for Service:
1147 Available notification state filters for Host:
1152 Available notification type filters:
1166 Name | Type | Description
1167 ----------------------------|-----------------------|-----------------
1168 last\_notification | Timestamp | When the last notification was sent for this Notification object (as a UNIX timestamp).
1169 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).
1170 notification\_number | Number | The notification number.
1171 last\_problem\_notification | Timestamp | When the last notification was sent for a problem (as a UNIX timestamp).
1174 ## NotificationCommand <a id="objecttype-notificationcommand"></a>
1176 A notification command definition.
1181 object NotificationCommand "mail-service-notification" {
1182 command = [ ConfigDir + "/scripts/mail-service-notification.sh" ]
1187 value = "$notification_address$"
1189 "-6" = "$notification_address6$"
1190 "-b" = "$notification_author$"
1191 "-c" = "$notification_comment$"
1194 value = "$notification_date$"
1198 value = "$notification_servicename$"
1201 value = "$notification_from$"
1202 description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
1204 "-i" = "$notification_icingaweb2url$"
1207 value = "$notification_hostname$"
1211 value = "$notification_hostdisplayname$"
1215 value = "$notification_serviceoutput$"
1219 value = "$notification_useremail$"
1223 value = "$notification_servicestate$"
1227 value = "$notification_type$"
1231 value = "$notification_servicedisplayname$"
1233 "-v" = "$notification_logtosyslog$"
1237 notification_address = "$address$"
1238 notification_address6 = "$address6$"
1239 notification_author = "$notification.author$"
1240 notification_comment = "$notification.comment$"
1241 notification_type = "$notification.type$"
1242 notification_date = "$icinga.long_date_time$"
1243 notification_hostname = "$host.name$"
1244 notification_hostdisplayname = "$host.display_name$"
1245 notification_servicename = "$service.name$"
1246 notification_serviceoutput = "$service.output$"
1247 notification_servicestate = "$service.state$"
1248 notification_useremail = "$user.email$"
1249 notification_servicedisplayname = "$service.display_name$"
1254 Configuration Attributes:
1256 Name | Type | Description
1257 --------------------------|-----------------------|----------------------------------
1258 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.
1259 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1260 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
1261 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
1262 arguments | Dictionary | **Optional.** A dictionary of command arguments.
1264 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
1266 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
1268 ## NotificationComponent <a id="objecttype-notificationcomponent"></a>
1270 The notification component is responsible for sending notifications.
1271 This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature).
1276 object NotificationComponent "notification" { }
1279 Configuration Attributes:
1281 Name | Type | Description
1282 --------------------------|-----------------------|----------------------------------
1283 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".
1285 ## OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1287 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1288 This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer).
1293 object OpenTsdbWriter "opentsdb" {
1299 Configuration Attributes:
1301 Name | Type | Description
1302 --------------------------|-----------------------|----------------------------------
1303 host | String | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`.
1304 port | Number | **Optional.** OpenTSDB port. Defaults to `4242`.
1307 ## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1309 Writes check result performance data to a defined path using macro
1310 pattern consisting of custom attributes and runtime macros.
1311 This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files).
1316 object PerfdataWriter "perfdata" {
1317 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1319 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1321 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$"
1322 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$"
1324 rotation_interval = 15s
1328 Configuration Attributes:
1330 Name | Type | Description
1331 --------------------------|-----------------------|----------------------------------
1332 host\_perfdata\_path | String | **Optional.** Path to the host performance data file. Defaults to SpoolDir + "/perfdata/host-perfdata".
1333 service\_perfdata\_path | String | **Optional.** Path to the service performance data file. Defaults to SpoolDir + "/perfdata/service-perfdata".
1334 host\_temp\_path | String | **Optional.** Path to the temporary host file. Defaults to SpoolDir + "/tmp/host-perfdata".
1335 service\_temp\_path | String | **Optional.** Path to the temporary service file. Defaults to SpoolDir + "/tmp/service-perfdata".
1336 host\_format\_template | String | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1337 service\_format\_template | String | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1338 rotation\_interval | Duration | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`.
1340 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1341 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1344 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
1346 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1350 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1351 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1352 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1353 > type for `Host` or `Service`.
1354 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
1359 object ScheduledDowntime "some-downtime" {
1360 host_name = "localhost"
1361 service_name = "ping4"
1363 author = "icingaadmin"
1364 comment = "Some comment"
1370 "sunday" = "02:00-03:00"
1375 Configuration Attributes:
1377 Name | Type | Description
1378 --------------------------|-----------------------|----------------------------------
1379 host\_name | Object name | **Required.** The name of the host this scheduled downtime belongs to.
1380 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.
1381 author | String | **Required.** The author of the downtime.
1382 comment | String | **Required.** A comment for the downtime.
1383 fixed | Boolean | **Optional.** Whether this is a fixed downtime. Defaults to `true`.
1384 duration | Duration | **Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1385 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1387 ScheduledDowntime objects have composite names, i.e. their names are based
1388 on the `host_name` and `service_name` attributes and the
1389 name you specified. This means you can define more than one object
1390 with the same (short) name as long as one of the `host_name` and
1391 `service_name` attributes has a different value.
1394 ## Service <a id="objecttype-service"></a>
1396 Service objects describe network services and how they should be checked
1401 > Rather than creating a `Service` object for a specific host it is usually easier
1402 > to just create a `Service` template and use the `apply` keyword to assign the
1403 > service to a number of hosts.
1404 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
1409 object Service "uptime" {
1410 host_name = "localhost"
1412 display_name = "localhost Uptime"
1414 check_command = "snmp"
1416 vars.snmp_community = "public"
1417 vars.snmp_oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1419 check_interval = 60s
1420 retry_interval = 15s
1422 groups = [ "all-services", "snmp" ]
1426 Configuration Attributes:
1428 Name | Type | Description
1429 --------------------------|-----------------------|----------------------------------
1430 display\_name | String | **Optional.** A short description of the service.
1431 host\_name | Object name | **Required.** The host this service belongs to. There must be a `Host` object with that name.
1432 groups | Array of object names | **Optional.** The service groups this service belongs to.
1433 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this service.
1434 check\_command | Object name | **Required.** The name of the check command.
1435 max\_check\_attempts | Number | **Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1436 check\_period | Object name | **Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1437 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
1438 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`.
1439 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`.
1440 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to `true`.
1441 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to `true`.
1442 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to `true`.
1443 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to `true`.
1444 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to `false`.
1445 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a service to be considered flapping. `30.0`
1446 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a service to be considered not flapping. `25.0`
1447 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to `true`.
1448 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.
1449 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
1450 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.
1451 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.
1452 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
1453 notes | String | **Optional.** Notes for the service.
1454 notes\_url | String | **Optional.** URL for notes for the service (for example, in notification commands).
1455 action\_url | String | **Optional.** URL for actions for the service (for example, an external graphing tool).
1456 icon\_image | String | **Optional.** Icon image for the service. Used by external interfaces only.
1457 icon\_image\_alt | String | **Optional.** Icon image description for the service. Used by external interface only.
1459 Service objects have composite names, i.e. their names are based on the host\_name attribute and the name you specified. This means
1460 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1462 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
1463 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
1467 Name | Type | Description
1468 --------------------------|-----------------------|----------------------------------
1469 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
1470 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
1471 check\_attempt | Number | The current check attempt number.
1472 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1473 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1474 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1475 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
1476 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
1477 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
1478 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1479 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1480 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1481 downtime\_depth | Number | Whether the service has one or more active downtimes.
1482 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
1483 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
1484 flapping | Boolean | Whether the host is flapping between states.
1485 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1486 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1487 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1488 last\_state\_ok | Timestamp | When the last OK state occurred (as a UNIX timestamp).
1489 last\_state\_warning | Timestamp | When the last WARNING state occurred (as a UNIX timestamp).
1490 last\_state\_critical | Timestamp | When the last CRITICAL state occurred (as a UNIX timestamp).
1491 last\_state\_unknown | Timestamp | When the last UNKNOWN state occurred (as a UNIX timestamp).
1494 ## ServiceGroup <a id="objecttype-servicegroup"></a>
1496 A group of services.
1500 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
1505 object ServiceGroup "snmp" {
1506 display_name = "SNMP services"
1510 Configuration Attributes:
1512 Name | Type | Description
1513 --------------------------|-----------------------|----------------------------------
1514 display\_name | String | **Optional.** A short description of the service group.
1515 groups | Array of object names | **Optional.** An array of nested group names.
1518 ## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1520 Periodically writes status and configuration data files which are used by third-party tools.
1521 This configuration object is available as [statusdata feature](14-features.md#status-data).
1526 object StatusDataWriter "status" {
1527 status_path = "/var/cache/icinga2/status.dat"
1528 objects_path = "/var/cache/icinga2/objects.cache"
1529 update_interval = 30s
1533 Configuration Attributes:
1535 Name | Type | Description
1536 --------------------------|-----------------------|----------------------------------
1537 status\_path | String | **Optional.** Path to the `status.dat` file. Defaults to CacheDir + "/status.dat".
1538 objects\_path | String | **Optional.** Path to the `objects.cache` file. Defaults to CacheDir + "/objects.cache".
1539 update\_interval | Duration | **Optional.** The interval in which the status files are updated. Defaults to `15s`.
1542 ## SyslogLogger <a id="objecttype-sysloglogger"></a>
1544 Specifies Icinga 2 logging to syslog.
1545 This configuration object is available as `syslog` [logging feature](14-features.md#logging).
1550 object SyslogLogger "syslog" {
1551 severity = "warning"
1555 Configuration Attributes:
1557 Name | Type | Description
1558 --------------------------|-----------------------|----------------------------------
1559 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1560 facility | String | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`.
1564 Name | Facility | Description
1565 ---------------------|---------------|----------------
1566 FacilityAuth | LOG\_AUTH | The authorization system.
1567 FacilityAuthPriv | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals.
1568 FacilityCron | LOG\_CRON | The cron daemon.
1569 FacilityDaemon | LOG\_DAEMON | System daemons that are not provided for explicitly by other facilities.
1570 FacilityFtp | LOG\_FTP | The file transfer protocol daemons.
1571 FacilityKern | LOG\_KERN | Messages generated by the kernel. These cannot be generated by any user processes.
1572 FacilityLocal0 | LOG\_LOCAL0 | Reserved for local use.
1573 FacilityLocal1 | LOG\_LOCAL1 | Reserved for local use.
1574 FacilityLocal2 | LOG\_LOCAL2 | Reserved for local use.
1575 FacilityLocal3 | LOG\_LOCAL3 | Reserved for local use.
1576 FacilityLocal4 | LOG\_LOCAL4 | Reserved for local use.
1577 FacilityLocal5 | LOG\_LOCAL5 | Reserved for local use.
1578 FacilityLocal6 | LOG\_LOCAL6 | Reserved for local use.
1579 FacilityLocal7 | LOG\_LOCAL7 | Reserved for local use.
1580 FacilityLpr | LOG\_LPR | The line printer spooling system.
1581 FacilityMail | LOG\_MAIL | The mail system.
1582 FacilityNews | LOG\_NEWS | The network news system.
1583 FacilitySyslog | LOG\_SYSLOG | Messages generated internally by syslogd.
1584 FacilityUser | LOG\_USER | Messages generated by user processes. This is the default facility identifier if none is specified.
1585 FacilityUucp | LOG\_UUCP | The UUCP system.
1587 ## TimePeriod <a id="objecttype-timeperiod"></a>
1589 Time periods can be used to specify when hosts/services should be checked or to limit
1590 when notifications should be sent out.
1595 object TimePeriod "nonworkhours" {
1596 display_name = "Icinga 2 TimePeriod for non working hours"
1599 monday = "00:00-8:00,17:00-24:00"
1600 tuesday = "00:00-8:00,17:00-24:00"
1601 wednesday = "00:00-8:00,17:00-24:00"
1602 thursday = "00:00-8:00,17:00-24:00"
1603 friday = "00:00-8:00,16:00-24:00"
1604 saturday = "00:00-24:00"
1605 sunday = "00:00-24:00"
1609 object TimePeriod "exampledays" {
1610 display_name = "Icinga 2 TimePeriod for random example days"
1613 //We still believe in Santa, no peeking!
1614 //Applies every 25th of December every year
1615 "december 25" = "00:00-24:00"
1617 //Any point in time can be specified,
1618 //but you still have to use a range
1619 "2038-01-19" = "03:13-03:15"
1621 //Evey 3rd day from the second monday of February
1622 //to 8th of November
1623 "monday 2 february - november 8 / 3" = "00:00-24:00"
1628 Additional examples can be found [here](08-advanced-topics.md#timeperiods).
1630 Configuration Attributes:
1632 Name | Type | Description
1633 --------------------------|-----------------------|----------------------------------
1634 display\_name | String | **Optional.** A short description of the time period.
1635 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1636 prefer\_includes | Boolean | **Optional.** Whether to prefer timeperiods `includes` or `excludes`. Default to true.
1637 excludes | Array of object names | **Optional.** An array of timeperiods, which should exclude from your timerange.
1638 includes | Array of object names | **Optional.** An array of timeperiods, which should include into your timerange
1643 Name | Type | Description
1644 --------------------------|-----------------------|----------------------------------
1645 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1648 ## User <a id="objecttype-user"></a>
1655 object User "icingaadmin" {
1656 display_name = "Icinga 2 Admin"
1657 groups = [ "icingaadmins" ]
1658 email = "icinga@localhost"
1659 pager = "icingaadmin@localhost.localdomain"
1663 states = [ OK, Warning, Critical, Unknown ]
1664 types = [ Problem, Recovery ]
1666 vars.additional_notes = "This is the Icinga 2 Admin account."
1670 Available notification state filters:
1679 Available notification type filters:
1691 Configuration Attributes:
1693 Name | Type | Description
1694 --------------------------|-----------------------|----------------------------------
1695 display\_name | String | **Optional.** A short description of the user.
1696 email | String | **Optional.** An email string for this user. Useful for notification commands.
1697 pager | String | **Optional.** A pager string for this user. Useful for notification commands.
1698 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this user.
1699 groups | Array of object names | **Optional.** An array of group names.
1700 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled for this user. Defaults to true.
1701 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.
1702 types | Array | **Optional.** A set of type filters when a notification for this user should be triggered. By default everything is matched.
1703 states | Array | **Optional.** A set of state filters when a notification for this should be triggered. By default everything is matched.
1707 Name | Type | Description
1708 --------------------------|-----------------------|----------------------------------
1709 last\_notification | Timestamp | When the last notification was sent for this user (as a UNIX timestamp).
1711 ## UserGroup <a id="objecttype-usergroup"></a>
1717 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
1722 object UserGroup "icingaadmins" {
1723 display_name = "Icinga 2 Admin Group"
1727 Configuration Attributes:
1729 Name | Type | Description
1730 --------------------------|-----------------------|----------------------------------
1731 display\_name | String | **Optional.** A short description of the user group.
1732 groups | Array of object names | **Optional.** An array of nested group names.
1735 ## Zone <a id="objecttype-zone"></a>
1737 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1738 Please read the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring) for additional details.
1742 object Zone "master" {
1743 endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]
1747 object Zone "satellite" {
1748 endpoints = [ "icinga2-satellite1.localdomain" ]
1753 Configuration Attributes:
1755 Name | Type | Description
1756 --------------------------|-----------------------|----------------------------------
1757 endpoints | Array of object names | **Optional.** Array of endpoint names located in this zone.
1758 parent | Object name | **Optional.** The name of the parent zone.
1759 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`.
1761 Zone objects cannot currently be created with the API.