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 | `LocalStateDir + "/lib/icinga2/certs/" + NodeName + ".key"`
80 Certificate file | `LocalStateDir + "/lib/icinga2/certs/" + NodeName + ".crt"`
81 CA certificate file | `LocalStateDir + "/lib/icinga2/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 `LocalStateDir + "/lib/icinga2/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 password\_hash | String | **Optional.** A hashed password string in the form of /etc/shadow. 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
129 > Icinga 2 versions < 2.6.0 require the import of the [plugin-check-command](10-icinga-template-library.md#itl-plugin-check-command) template.
134 object CheckCommand "http" {
135 command = [ PluginDir + "/check_http" ]
138 "-H" = "$http_vhost$"
139 "-I" = "$http_address$"
143 set_if = "$http_ssl$"
146 set_if = "$http_sni$"
149 value = "$http_auth_pair$"
150 description = "Username:password on sites with basic authentication"
153 set_if = "$http_ignore_body$"
155 "-r" = "$http_expect_body_regex$"
156 "-w" = "$http_warn_time$"
157 "-c" = "$http_critical_time$"
158 "-e" = "$http_expect$"
161 vars.http_address = "$address$"
162 vars.http_ssl = false
163 vars.http_sni = false
167 Configuration Attributes:
169 Name | Type | Description
170 --------------------------|-----------------------|----------------------------------
171 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.
172 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
173 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
174 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
175 arguments | Dictionary | **Optional.** A dictionary of command arguments.
178 ### CheckCommand Arguments <a id="objecttype-checkcommand-arguments"></a>
180 Command arguments can be defined as key-value-pairs in the `arguments`
181 dictionary. If the argument requires additional configuration, for example
182 a `description` attribute or an optional condition, the value can be defined
183 as dictionary specifying additional options.
188 vars.x_val = "My command argument value."
198 key = "-Xnew" /* optional, set a new key identifier */
199 description = "My plugin requires this argument for doing X."
200 required = false /* optional, no error if not set */
201 skip_key = false /* always use "-X <value>" */
202 set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
203 order = -1 /* first position */
204 repeat_key = true /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
208 description = "My plugin requires this argument for doing Y."
209 required = false /* optional, no error if not set */
210 skip_key = true /* don't prefix "-Y" only use "<value>" */
211 set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
212 order = 0 /* second position */
213 repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
218 Name | Type | Description
219 --------------------------|-----------------------|----------------------------------
220 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).
221 key | String | Optional argument key overriding the key identifier.
222 description | String | Optional argument description.
223 required | Boolean | Required argument. Execution error if not set. Defaults to false (optional).
224 skip\_key | Boolean | Use the value as argument and skip the key.
225 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.
226 order | Number | Set if multiple arguments require a defined argument order.
227 repeat\_key | Boolean | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
232 ..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...
235 Argument array with `repeat_key = true`:
238 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'
241 Argument array with `repeat_key = false`:
244 'key' 'value[0]' 'value[1]' 'value[2]'
247 ## CheckerComponent <a id="objecttype-checkcomponent"></a>
249 The checker component is responsible for scheduling active checks.
250 This configuration object is available as [checker feature](11-cli-commands.md#cli-command-feature).
255 object CheckerComponent "checker" { }
258 Configuration Attributes:
260 Name | Type | Description
261 --------------------------|-----------------------|----------------------------------
262 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`.
264 ## CheckResultReader <a id="objecttype-checkresultreader"></a>
266 Reads Icinga 1.x check result files from a directory. This functionality is provided
267 to help existing Icinga 1.x users and might be useful for migration scenarios.
272 object CheckResultReader "reader" {
273 spool_dir = "/data/check-results"
277 Configuration Attributes:
279 Name | Type | Description
280 --------------------------|-----------------------|----------------------------------
281 spool\_dir | String | **Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/".
283 ## Comment <a id="objecttype-comment"></a>
285 Comments created at runtime are represented as objects.
286 Note: This is for reference only. You can create comments
287 with the [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) API action.
292 object Comment "localhost!my-comment" {
293 host_name = "localhost"
294 author = "icingaadmin"
295 text = "This is a comment."
299 Configuration Attributes:
301 Name | Type | Description
302 --------------------------|-----------------------|----------------------------------
303 host\_name | Object name | **Required.** The name of the host this comment belongs to.
304 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.
305 author | String | **Required.** The author's name.
306 text | String | **Required.** The comment text.
307 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this comment was added.
308 entry\_type | Number | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
309 expire\_time | Timestamp | **Optional.** The comment's expire time as UNIX timestamp.
310 persistent | Boolean | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
312 ## CompatLogger <a id="objecttype-compatlogger"></a>
314 Writes log files in a format that's compatible with Icinga 1.x.
315 This configuration object is available as [compatlog feature](14-features.md#compat-logging).
320 object CompatLogger "compatlog" {
321 log_dir = "/var/log/icinga2/compat"
322 rotation_method = "DAILY"
326 Configuration Attributes:
328 Name | Type | Description
329 --------------------------|-----------------------|----------------------------------
330 log\_dir | String | **Optional.** Path to the compat log directory. Defaults to LocalStateDir + "/log/icinga2/compat".
331 rotation\_method | String | **Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
334 ## Dependency <a id="objecttype-dependency"></a>
336 Dependency objects are used to specify dependencies between hosts and services. Dependencies
337 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
342 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
343 > to just create a `Dependency` template and use the `apply` keyword to assign the
344 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
345 > type for `Host` or `Service`.
346 > Check the [dependencies](03-monitoring-basics.md#dependencies) chapter for detailed examples.
348 Service-to-Service Example:
351 object Dependency "webserver-internet" {
352 parent_host_name = "internet"
353 parent_service_name = "ping4"
355 child_host_name = "webserver"
356 child_service_name = "ping4"
358 states = [ OK, Warning ]
360 disable_checks = true
364 Host-to-Host Example:
367 object Dependency "webserver-internet" {
368 parent_host_name = "internet"
370 child_host_name = "webserver"
374 disable_checks = true
378 Configuration Attributes:
380 Name | Type | Description
381 --------------------------|-----------------------|----------------------------------
382 parent\_host\_name | Object name | **Required.** The parent host.
383 parent\_service\_name | Object name | **Optional.** The parent service. If omitted, this dependency object is treated as host dependency.
384 child\_host\_name | Object name | **Required.** The child host.
385 child\_service\_name | Object name | **Optional.** The child service. If omitted, this dependency object is treated as host dependency.
386 disable\_checks | Boolean | **Optional.** Whether to disable checks when this dependency fails. Defaults to false.
387 disable\_notifications | Boolean | **Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
388 ignore\_soft\_states | Boolean | **Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
389 period | Object name | **Optional.** Time period object during which this dependency is enabled.
390 states | Array | **Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
392 Available state filters:
401 When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
402 automatically determined by Icinga 2.
404 Service-to-Host Dependency Example:
407 apply Dependency "internet" to Service {
408 parent_host_name = "dsl-router"
409 disable_checks = true
411 assign where host.name != "dsl-router"
415 This example sets all service objects matching the assign condition into a dependency relation to
416 the parent host object `dsl-router` as implicit child services.
418 Service-to-Service-on-the-same-Host Dependency Example:
421 apply Dependency "disable-agent-checks" to Service {
422 parent_service_name = "agent-health"
424 assign where service.check_command == "ssh"
425 ignore where service.name == "agent-health"
429 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
430 host object matched by the apply rule condition. All services where apply matches are made implicit child services
431 in this dependency relation.
434 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
435 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
436 `child_service_name` attributes has a different value.
438 ## Downtime <a id="objecttype-downtime"></a>
440 Downtimes created at runtime are represented as objects.
441 You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action.
446 object Downtime "my-downtime" {
447 host_name = "localhost"
448 author = "icingaadmin"
449 comment = "This is a downtime."
450 start_time = 1505312869
451 end_time = 1505312924
455 Configuration Attributes:
457 Name | Type | Description
458 --------------------------|-----------------------|----------------------------------
459 host\_name | Object name | **Required.** The name of the host this comment belongs to.
460 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.
461 author | String | **Required.** The author's name.
462 comment | String | **Required.** The comment text.
463 start\_time | Timestamp | **Required.** The start time as UNIX timestamp.
464 end\_time | Timestamp | **Required.** The end time as UNIX timestamp.
465 duration | Number | **Optional.** The duration as number.
466 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this downtime was added.
467 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).
468 triggers | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime.
472 Name | Type | Description
473 --------------------------|-----------------------|----------------------------------
474 trigger\_time | Timestamp | The UNIX timestamp when this downtime was triggered.
475 triggered\_by | Object name | The name of the downtime this downtime was triggered by.
478 ## ElasticsearchWriter <a id="objecttype-elasticsearchwriter"></a>
480 Writes check result metrics and performance data to an Elasticsearch instance.
481 This configuration object is available as [elasticsearch feature](14-features.md#elasticsearch-writer).
486 object ElasticsearchWriter "elasticsearch" {
491 enable_send_perfdata = true
493 flush_threshold = 1024
498 The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
500 Configuration Attributes:
502 Name | Type | Description
503 --------------------------|-----------------------|----------------------------------
504 host | String | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
505 port | Number | **Required.** Elasticsearch port. Defaults to `9200`.
506 index | String | **Required.** Elasticsearch index name. Defaults to `icinga2`.
507 enable\_send\_perfdata | Boolean | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
508 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to Elasticsearch. Defaults to `10s`.
509 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to `1024`.
510 username | String | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
511 password | String | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
512 enable\_tls | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
513 ca\_path | String | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
514 cert\_path | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
515 key\_path | String | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
517 Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
518 Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
520 Basic auth is supported with the `username` and `password` attributes. This requires an
521 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/)
524 TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
525 you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
527 ## Endpoint <a id="objecttype-endpoint"></a>
529 Endpoint objects are used to specify connection information for remote
530 Icinga 2 instances. More details can be found in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
535 object Endpoint "icinga2-client1.localdomain" {
536 host = "192.168.56.111"
542 Example (disable replay log):
545 object Endpoint "icinga2-client1.localdomain" {
546 host = "192.168.5.111"
552 Configuration Attributes:
554 Name | Type | Description
555 --------------------------|-----------------------|----------------------------------
556 host | String | **Optional.** The hostname/IP address of the remote Icinga 2 instance.
557 port | Number | **Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
558 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.
560 Endpoint objects cannot currently be created with the API.
562 ## EventCommand <a id="objecttype-eventcommand"></a>
564 An event command definition.
568 > Icinga 2 versions < 2.6.0 require the import of the [plugin-event-command](10-icinga-template-library.md#itl-plugin-event-command) template.
573 object EventCommand "restart-httpd-event" {
574 command = "/opt/bin/restart-httpd.sh"
579 Configuration Attributes:
581 Name | Type | Description
582 --------------------------|-----------------------|----------------------------------
583 command | Array | **Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command. When using the "arguments" attribute this must be an array. Can be specified as function for advanced implementations.
584 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
585 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
586 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
587 arguments | Dictionary | **Optional.** A dictionary of command arguments.
589 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
591 More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
593 ## ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
595 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
596 This configuration object is available as [command feature](14-features.md#external-commands).
601 object ExternalCommandListener "command" {
602 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
606 Configuration Attributes:
608 Name | Type | Description
609 --------------------------|-----------------------|----------------------------------
610 command\_path | String | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
614 ## FileLogger <a id="objecttype-filelogger"></a>
616 Specifies Icinga 2 logging to a file.
617 This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging).
622 object FileLogger "debug-file" {
624 path = "/var/log/icinga2/debug.log"
628 Configuration Attributes:
630 Name | Type | Description
631 --------------------------|-----------------------|----------------------------------
632 path | String | **Required.** The log path.
633 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
636 ## GelfWriter <a id="objecttype-gelfwriter"></a>
638 Writes event log entries to a defined GELF receiver host (Graylog, Logstash).
639 This configuration object is available as [gelf feature](14-features.md#gelfwriter).
644 object GelfWriter "gelf" {
650 Configuration Attributes:
652 Name | Type | Description
653 --------------------------|-----------------------|----------------------------------
654 host | String | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`.
655 port | Number | **Optional.** GELF receiver port. Defaults to `12201`.
656 source | String | **Optional.** Source name for this instance. Defaults to `icinga2`.
657 enable\_send\_perfdata | Boolean | **Optional.** Enable performance data for 'CHECK RESULT' events.
660 ## GraphiteWriter <a id="objecttype-graphitewriter"></a>
662 Writes check result metrics and performance data to a defined
663 Graphite Carbon host.
664 This configuration object is available as [graphite feature](14-features.md#graphite-carbon-cache-writer).
669 object GraphiteWriter "graphite" {
675 Configuration Attributes:
677 Name | Type | Description
678 --------------------------|-----------------------|----------------------------------
679 host | String | **Optional.** Graphite Carbon host address. Defaults to `127.0.0.1`.
680 port | Number | **Optional.** Graphite Carbon port. Defaults to `2003`.
681 host\_name\_template | String | **Optional.** Metric prefix for host name. Defaults to `icinga2.$host.name$.host.$host.check_command$`.
682 service\_name\_template | String | **Optional.** Metric prefix for service name. Defaults to `icinga2.$host.name$.services.$service.name$.$service.check_command$`.
683 enable\_send\_thresholds | Boolean | **Optional.** Send additional threshold metrics. Defaults to `false`.
684 enable\_send\_metadata | Boolean | **Optional.** Send additional metadata metrics. Defaults to `false`.
686 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
690 ## Host <a id="objecttype-host"></a>
697 object Host "icinga2-client1.localdomain" {
698 display_name = "Linux Client 1"
699 address = "192.168.56.111"
700 address6 = "2a00:1450:4001:815::2003"
702 groups = [ "linux-servers" ]
704 check_command = "hostalive"
708 Configuration Attributes:
710 Name | Type | Description
711 --------------------------|-----------------------|----------------------------------
712 display\_name | String | **Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
713 address | String | **Optional.** The host's IPv4 address. Available as command runtime macro `$address$` if set.
714 address6 | String | **Optional.** The host's IPv6 address. Available as command runtime macro `$address6$` if set.
715 groups | Array of object names | **Optional.** A list of host groups this host belongs to.
716 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this host.
717 check\_command | Object name | **Required.** The name of the check command.
718 max\_check\_attempts | Number | **Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
719 check\_period | Object name | **Optional.** The name of a time period which determines when this host should be checked. Not set by default.
720 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
721 check\_interval | Duration | **Optional.** The check interval (in seconds). This interval is used for checks when the host is in a `HARD` state. Defaults to `5m`.
722 retry\_interval | Duration | **Optional.** The retry interval (in seconds). This interval is used for checks when the host is in a `SOFT` state. Defaults to `1m`.
723 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to true.
724 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to true.
725 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to true.
726 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to true.
727 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to false.
728 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to true.
729 event\_command | Object name | **Optional.** The name of an event command that should be executed every time the host's state changes or the host is in a `SOFT` state.
730 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a host to be considered flapping. Default `30.0`
731 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a host to be considered not flapping. Default `25.0`
732 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
733 zone | Object name | **Optional.** The zone this object is a member of. Please read the [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring) chapter for details.
734 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
735 notes | String | **Optional.** Notes for the host.
736 notes\_url | String | **Optional.** URL for notes for the host (for example, in notification commands).
737 action\_url | String | **Optional.** URL for actions for the host (for example, an external graphing tool).
738 icon\_image | String | **Optional.** Icon image for the host. Used by external interfaces only.
739 icon\_image\_alt | String | **Optional.** Icon image description for the host. Used by external interface only.
741 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
742 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
746 > The `address` and `address6` attributes are required for running commands using
747 > the `$address$` and `$address6$` runtime macros.
751 Name | Type | Description
752 --------------------------|-----------------------|----------------------------------
753 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
754 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
755 check\_attempt | Number | The current check attempt number.
756 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
757 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
758 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
759 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
760 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
761 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
762 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
763 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
764 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
765 downtime\_depth | Number | Whether the host has one or more active downtimes.
766 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
767 flapping | Boolean | Whether the host is flapping between states.
768 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
769 state | Number | The current state (0 = UP, 1 = DOWN).
770 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
771 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
772 last\_state\_up | Timestamp | When the last UP state occurred (as a UNIX timestamp).
773 last\_state\_down | Timestamp | When the last DOWN state occurred (as a UNIX timestamp).
777 ## HostGroup <a id="objecttype-hostgroup"></a>
783 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
788 object HostGroup "linux-servers" {
789 display_name = "Linux Servers"
791 assign where host.vars.os == "Linux"
795 Configuration Attributes:
797 Name | Type | Description
798 --------------------------|-----------------------|----------------------------------
799 display\_name | String | **Optional.** A short description of the host group.
800 groups | Array of object names | **Optional.** An array of nested group names.
802 ## IcingaApplication <a id="objecttype-icingaapplication"></a>
804 The IcingaApplication object is required to start Icinga 2.
805 The object name must be `app`. If the object configuration
806 is missing, Icinga 2 will automatically create an IcingaApplication
812 object IcingaApplication "app" {
813 enable_perfdata = false
817 Configuration Attributes:
819 Name | Type | Description
820 --------------------------|-----------------------|----------------------------------
821 enable\_notifications | Boolean | **Optional.** Whether notifications are globally enabled. Defaults to true.
822 enable\_event\_handlers | Boolean | **Optional.** Whether event handlers are globally enabled. Defaults to true.
823 enable\_flapping | Boolean | **Optional.** Whether flap detection is globally enabled. Defaults to true.
824 enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true.
825 enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true.
826 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true.
827 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally.
829 ## IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
831 IDO database adapter for MySQL.
832 This configuration object is available as [ido-mysql feature](14-features.md#db-ido).
837 object IdoMysqlConnection "mysql-ido" {
845 downtimehistory_age = 48h
846 contactnotifications_age = 31d
851 Configuration Attributes:
853 Name | Type | Description
854 --------------------------|-----------------------|----------------------------------
855 host | String | **Optional.** MySQL database host address. Defaults to `localhost`.
856 port | Number | **Optional.** MySQL database port. Defaults to `3306`.
857 socket\_path | String | **Optional.** MySQL socket path.
858 user | String | **Optional.** MySQL database user with read/write permission to the icinga database. Defaults to `icinga`.
859 password | String | **Optional.** MySQL database user's password. Defaults to `icinga`.
860 database | String | **Optional.** MySQL database name. Defaults to `icinga`.
861 enable\_ssl | Boolean | **Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
862 ssl\_key | String | **Optional.** MySQL SSL client key file path.
863 ssl\_cert | String | **Optional.** MySQL SSL certificate file path.
864 ssl\_ca | String | **Optional.** MySQL SSL certificate authority certificate file path.
865 ssl\_capath | String | **Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
866 ssl\_cipher | String | **Optional.** MySQL SSL list of allowed ciphers.
867 table\_prefix | String | **Optional.** MySQL database table prefix. Defaults to `icinga_`.
868 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
869 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
870 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".
871 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`.
872 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
873 categories | Array | **Optional.** Array of information types that should be written to the database.
877 Name | Type | Description
878 --------------------------------|-----------------------|----------------------------------
879 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
880 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
881 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
882 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
883 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
884 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
885 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
886 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
887 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
888 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
889 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
890 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
891 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
892 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
893 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
897 Name | Description | Required by
898 ---------------------|------------------------|--------------------
899 DbCatConfig | Configuration data | Icinga Web 2
900 DbCatState | Current state data | Icinga Web 2
901 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
902 DbCatComment | Comments | Icinga Web 2
903 DbCatDowntime | Downtimes | Icinga Web 2
904 DbCatEventHandler | Event handler data | Icinga Web 2
905 DbCatExternalCommand | External commands | --
906 DbCatFlapping | Flap detection data | Icinga Web 2
907 DbCatCheck | Check results | --
908 DbCatLog | Log messages | --
909 DbCatNotification | Notifications | Icinga Web 2
910 DbCatProgramStatus | Program status data | Icinga Web 2
911 DbCatRetention | Retention data | Icinga Web 2
912 DbCatStateHistory | Historical state data | Icinga Web 2
914 The default value for `categories` includes everything required
915 by Icinga Web 2 in the table above.
917 In addition to the category flags listed above the `DbCatEverything`
918 flag may be used as a shortcut for listing all flags.
920 ## IdoPgsqlConnection <a id="objecttype-idopgsqlconnection"></a>
922 IDO database adapter for PostgreSQL.
923 This configuration object is available as [ido-pgsql feature](14-features.md#db-ido).
928 object IdoPgsqlConnection "pgsql-ido" {
936 downtimehistory_age = 48h
937 contactnotifications_age = 31d
942 Configuration Attributes:
944 Name | Type | Description
945 --------------------------|-----------------------|----------------------------------
946 host | String | **Optional.** PostgreSQL database host address. Defaults to `localhost`.
947 port | Number | **Optional.** PostgreSQL database port. Defaults to `5432`.
948 user | String | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`.
949 password | String | **Optional.** PostgreSQL database user's password. Defaults to `icinga`.
950 database | String | **Optional.** PostgreSQL database name. Defaults to `icinga`.
951 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`.
952 ssl\_key | String | **Optional.** PostgreSQL SSL client key file path.
953 ssl\_cert | String | **Optional.** PostgreSQL SSL certificate file path.
954 ssl\_ca | String | **Optional.** PostgreSQL SSL certificate authority certificate file path.
955 table\_prefix | String | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`.
956 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
957 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
958 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".
959 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`.
960 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
961 categories | Array | **Optional.** Array of information types that should be written to the database.
965 Name | Type | Description
966 --------------------------------|-----------------------|----------------------------------
967 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
968 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
969 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
970 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
971 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
972 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
973 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
974 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
975 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
976 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
977 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
978 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
979 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
980 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
981 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
985 Name | Description | Required by
986 ---------------------|------------------------|--------------------
987 DbCatConfig | Configuration data | Icinga Web 2
988 DbCatState | Current state data | Icinga Web 2
989 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
990 DbCatComment | Comments | Icinga Web 2
991 DbCatDowntime | Downtimes | Icinga Web 2
992 DbCatEventHandler | Event handler data | Icinga Web 2
993 DbCatExternalCommand | External commands | --
994 DbCatFlapping | Flap detection data | Icinga Web 2
995 DbCatCheck | Check results | --
996 DbCatLog | Log messages | --
997 DbCatNotification | Notifications | Icinga Web 2
998 DbCatProgramStatus | Program status data | Icinga Web 2
999 DbCatRetention | Retention data | Icinga Web 2
1000 DbCatStateHistory | Historical state data | Icinga Web 2
1002 The default value for `categories` includes everything required
1003 by Icinga Web 2 in the table above.
1005 In addition to the category flags listed above the `DbCatEverything`
1006 flag may be used as a shortcut for listing all flags.
1008 ## InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
1010 Writes check result metrics and performance data to a defined InfluxDB host.
1011 This configuration object is available as [influxdb feature](14-features.md#influxdb-writer).
1016 object InfluxdbWriter "influxdb" {
1019 database = "icinga2"
1021 flush_threshold = 1024
1022 flush_interval = 10s
1025 measurement = "$host.check_command$"
1027 hostname = "$host.name$"
1030 service_template = {
1031 measurement = "$service.check_command$"
1033 hostname = "$host.name$"
1034 service = "$service.name$"
1040 Configuration Attributes:
1042 Name | Type | Description
1043 --------------------------|-----------------------|----------------------------------
1044 host | String | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
1045 port | Number | **Required.** InfluxDB HTTP port. Defaults to `8086`.
1046 database | String | **Required.** InfluxDB database name. Defaults to `icinga2`.
1047 username | String | **Optional.** InfluxDB user name. Defaults to `none`.
1048 password | String | **Optional.** InfluxDB user password. Defaults to `none`.
1049 ssl\_enable | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`.
1050 ssl\_ca\_cert | String | **Optional.** Path to CA certificate to validate the remote host.
1051 ssl\_cert | String | **Optional.** Path to host certificate to present to the remote host for mutual verification.
1052 ssl\_key | String | **Optional.** Path to host key to accompany the ssl\_cert.
1053 host\_template | String | **Required.** Host template to define the InfluxDB line protocol.
1054 service\_template | String | **Required.** Service template to define the influxDB line protocol.
1055 enable\_send\_thresholds | Boolean | **Optional.** Whether to send warn, crit, min & max tagged data.
1056 enable\_send\_metadata | Boolean | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
1057 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to InfluxDB. Defaults to `10s`.
1058 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`.
1060 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
1061 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
1066 ## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
1068 Livestatus API interface available as TCP or UNIX socket. Historical table queries
1069 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
1070 pointing to the log files using the `compat_log_path` configuration attribute.
1071 This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus).
1076 object LivestatusListener "livestatus-tcp" {
1078 bind_host = "127.0.0.1"
1082 object LivestatusListener "livestatus-unix" {
1083 socket_type = "unix"
1084 socket_path = "/var/run/icinga2/cmd/livestatus"
1088 Configuration Attributes:
1090 Name | Type | Description
1091 --------------------------|-----------------------|----------------------------------
1092 socket\_type | String | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`.
1093 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`.
1094 bind\_port | Number | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`.
1095 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".
1096 compat\_log\_path | String | **Optional.** Path to Icinga 1.x log files. Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"
1100 > UNIX sockets are not supported on Windows.
1103 ## Notification <a id="objecttype-notification"></a>
1105 Notification objects are used to specify how users should be notified in case
1106 of host and service state changes and other events.
1110 > Rather than creating a `Notification` object for a specific host or service it is
1111 > usually easier to just create a `Notification` template and use the `apply` keyword
1112 > to assign the notification to a number of hosts or services. Use the `to` keyword
1113 > to set the specific target type for `Host` or `Service`.
1114 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
1119 object Notification "localhost-ping-notification" {
1120 host_name = "localhost"
1121 service_name = "ping4"
1123 command = "mail-notification"
1125 users = [ "user1", "user2" ] // reference to User objects
1127 types = [ Problem, Recovery ]
1128 states = [ Critical, Warning, OK ]
1132 Configuration Attributes:
1134 Name | Type | Description
1135 --------------------------|-----------------------|----------------------------------
1136 host\_name | Object name | **Required.** The name of the host this notification belongs to.
1137 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.
1138 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
1139 users | Array of object names | **Required.** A list of user names who should be notified. **Optional.** if the `user_groups` attribute is set.
1140 user\_groups | Array of object names | **Required.** A list of user group names who should be notified. **Optional.** if the `users` attribute is set.
1141 times | Dictionary | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
1142 command | Object name | **Required.** The name of the notification command which should be executed when the notification is triggered.
1143 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.
1144 period | Object name | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
1145 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.
1146 types | Array | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
1147 states | Array | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
1149 Available notification state filters for Service:
1156 Available notification state filters for Host:
1161 Available notification type filters:
1175 Name | Type | Description
1176 ----------------------------|-----------------------|-----------------
1177 last\_notification | Timestamp | When the last notification was sent for this Notification object (as a UNIX timestamp).
1178 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).
1179 notification\_number | Number | The notification number.
1180 last\_problem\_notification | Timestamp | When the last notification was sent for a problem (as a UNIX timestamp).
1183 ## NotificationCommand <a id="objecttype-notificationcommand"></a>
1185 A notification command definition.
1189 > Icinga 2 versions < 2.6.0 require the import of the [plugin-notification-command](10-icinga-template-library.md#itl-plugin-notification-command) template.
1194 object NotificationCommand "mail-service-notification" {
1195 command = [ SysconfDir + "/icinga2/scripts/mail-service-notification.sh" ]
1200 value = "$notification_address$"
1202 "-6" = "$notification_address6$"
1203 "-b" = "$notification_author$"
1204 "-c" = "$notification_comment$"
1207 value = "$notification_date$"
1211 value = "$notification_servicename$"
1214 value = "$notification_from$"
1215 description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
1217 "-i" = "$notification_icingaweb2url$"
1220 value = "$notification_hostname$"
1224 value = "$notification_hostdisplayname$"
1228 value = "$notification_serviceoutput$"
1232 value = "$notification_useremail$"
1236 value = "$notification_servicestate$"
1240 value = "$notification_type$"
1244 value = "$notification_servicedisplayname$"
1246 "-v" = "$notification_logtosyslog$"
1250 notification_address = "$address$"
1251 notification_address6 = "$address6$"
1252 notification_author = "$notification.author$"
1253 notification_comment = "$notification.comment$"
1254 notification_type = "$notification.type$"
1255 notification_date = "$icinga.long_date_time$"
1256 notification_hostname = "$host.name$"
1257 notification_hostdisplayname = "$host.display_name$"
1258 notification_servicename = "$service.name$"
1259 notification_serviceoutput = "$service.output$"
1260 notification_servicestate = "$service.state$"
1261 notification_useremail = "$user.email$"
1262 notification_servicedisplayname = "$service.display_name$"
1267 Configuration Attributes:
1269 Name | Type | Description
1270 --------------------------|-----------------------|----------------------------------
1271 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.
1272 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1273 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
1274 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
1275 arguments | Dictionary | **Optional.** A dictionary of command arguments.
1277 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
1279 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
1281 ## NotificationComponent <a id="objecttype-notificationcomponent"></a>
1283 The notification component is responsible for sending notifications.
1284 This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature).
1289 object NotificationComponent "notification" { }
1292 Configuration Attributes:
1294 Name | Type | Description
1295 --------------------------|-----------------------|----------------------------------
1296 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".
1298 ## OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1300 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1301 This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer).
1306 object OpenTsdbWriter "opentsdb" {
1312 Configuration Attributes:
1314 Name | Type | Description
1315 --------------------------|-----------------------|----------------------------------
1316 host | String | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`.
1317 port | Number | **Optional.** OpenTSDB port. Defaults to `4242`.
1320 ## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1322 Writes check result performance data to a defined path using macro
1323 pattern consisting of custom attributes and runtime macros.
1324 This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files).
1329 object PerfdataWriter "perfdata" {
1330 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1332 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1334 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$"
1335 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$"
1337 rotation_interval = 15s
1341 Configuration Attributes:
1343 Name | Type | Description
1344 --------------------------|-----------------------|----------------------------------
1345 host\_perfdata\_path | String | **Optional.** Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
1346 service\_perfdata\_path | String | **Optional.** Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
1347 host\_temp\_path | String | **Optional.** Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
1348 service\_temp\_path | String | **Optional.** Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
1349 host\_format\_template | String | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1350 service\_format\_template | String | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1351 rotation\_interval | Duration | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`.
1353 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1354 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1357 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
1359 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1363 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1364 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1365 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1366 > type for `Host` or `Service`.
1367 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
1372 object ScheduledDowntime "some-downtime" {
1373 host_name = "localhost"
1374 service_name = "ping4"
1376 author = "icingaadmin"
1377 comment = "Some comment"
1383 "sunday" = "02:00-03:00"
1388 Configuration Attributes:
1390 Name | Type | Description
1391 --------------------------|-----------------------|----------------------------------
1392 host\_name | Object name | **Required.** The name of the host this scheduled downtime belongs to.
1393 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.
1394 author | String | **Required.** The author of the downtime.
1395 comment | String | **Required.** A comment for the downtime.
1396 fixed | Boolean | **Optional.** Whether this is a fixed downtime. Defaults to `true`.
1397 duration | Duration | **Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1398 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1400 ScheduledDowntime objects have composite names, i.e. their names are based
1401 on the `host_name` and `service_name` attributes and the
1402 name you specified. This means you can define more than one object
1403 with the same (short) name as long as one of the `host_name` and
1404 `service_name` attributes has a different value.
1407 ## Service <a id="objecttype-service"></a>
1409 Service objects describe network services and how they should be checked
1414 > Rather than creating a `Service` object for a specific host it is usually easier
1415 > to just create a `Service` template and use the `apply` keyword to assign the
1416 > service to a number of hosts.
1417 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
1422 object Service "uptime" {
1423 host_name = "localhost"
1425 display_name = "localhost Uptime"
1427 check_command = "snmp"
1429 vars.snmp_community = "public"
1430 vars.snmp_oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1432 check_interval = 60s
1433 retry_interval = 15s
1435 groups = [ "all-services", "snmp" ]
1439 Configuration Attributes:
1441 Name | Type | Description
1442 --------------------------|-----------------------|----------------------------------
1443 display\_name | String | **Optional.** A short description of the service.
1444 host\_name | Object name | **Required.** The host this service belongs to. There must be a `Host` object with that name.
1445 groups | Array of object names | **Optional.** The service groups this service belongs to.
1446 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this service.
1447 check\_command | Object name | **Required.** The name of the check command.
1448 max\_check\_attempts | Number | **Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1449 check\_period | Object name | **Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1450 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
1451 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`.
1452 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`.
1453 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to `true`.
1454 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to `true`.
1455 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to `true`.
1456 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to `true`.
1457 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to `false`.
1458 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a service to be considered flapping. `30.0`
1459 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a service to be considered not flapping. `25.0`
1460 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to `true`.
1461 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.
1462 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
1463 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.
1464 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.
1465 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
1466 notes | String | **Optional.** Notes for the service.
1467 notes\_url | String | **Optional.** URL for notes for the service (for example, in notification commands).
1468 action\_url | String | **Optional.** URL for actions for the service (for example, an external graphing tool).
1469 icon\_image | String | **Optional.** Icon image for the service. Used by external interfaces only.
1470 icon\_image\_alt | String | **Optional.** Icon image description for the service. Used by external interface only.
1472 Service objects have composite names, i.e. their names are based on the host\_name attribute and the name you specified. This means
1473 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1475 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
1476 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
1480 Name | Type | Description
1481 --------------------------|-----------------------|----------------------------------
1482 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
1483 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
1484 check\_attempt | Number | The current check attempt number.
1485 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1486 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1487 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1488 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
1489 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
1490 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
1491 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1492 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1493 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1494 downtime\_depth | Number | Whether the service has one or more active downtimes.
1495 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
1496 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
1497 flapping | Boolean | Whether the host is flapping between states.
1498 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1499 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1500 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1501 last\_state\_ok | Timestamp | When the last OK state occurred (as a UNIX timestamp).
1502 last\_state\_warning | Timestamp | When the last WARNING state occurred (as a UNIX timestamp).
1503 last\_state\_critical | Timestamp | When the last CRITICAL state occurred (as a UNIX timestamp).
1504 last\_state\_unknown | Timestamp | When the last UNKNOWN state occurred (as a UNIX timestamp).
1507 ## ServiceGroup <a id="objecttype-servicegroup"></a>
1509 A group of services.
1513 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
1518 object ServiceGroup "snmp" {
1519 display_name = "SNMP services"
1523 Configuration Attributes:
1525 Name | Type | Description
1526 --------------------------|-----------------------|----------------------------------
1527 display\_name | String | **Optional.** A short description of the service group.
1528 groups | Array of object names | **Optional.** An array of nested group names.
1531 ## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1533 Periodically writes status and configuration data files which are used by third-party tools.
1534 This configuration object is available as [statusdata feature](14-features.md#status-data).
1539 object StatusDataWriter "status" {
1540 status_path = "/var/cache/icinga2/status.dat"
1541 objects_path = "/var/cache/icinga2/objects.cache"
1542 update_interval = 30s
1546 Configuration Attributes:
1548 Name | Type | Description
1549 --------------------------|-----------------------|----------------------------------
1550 status\_path | String | **Optional.** Path to the `status.dat` file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
1551 objects\_path | String | **Optional.** Path to the `objects.cache` file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
1552 update\_interval | Duration | **Optional.** The interval in which the status files are updated. Defaults to `15s`.
1555 ## SyslogLogger <a id="objecttype-sysloglogger"></a>
1557 Specifies Icinga 2 logging to syslog.
1558 This configuration object is available as `syslog` [logging feature](14-features.md#logging).
1563 object SyslogLogger "syslog" {
1564 severity = "warning"
1568 Configuration Attributes:
1570 Name | Type | Description
1571 --------------------------|-----------------------|----------------------------------
1572 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1573 facility | String | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`.
1577 Name | Facility | Description
1578 ---------------------|---------------|----------------
1579 FacilityAuth | LOG\_AUTH | The authorization system.
1580 FacilityAuthPriv | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals.
1581 FacilityCron | LOG\_CRON | The cron daemon.
1582 FacilityDaemon | LOG\_DAEMON | System daemons that are not provided for explicitly by other facilities.
1583 FacilityFtp | LOG\_FTP | The file transfer protocol daemons.
1584 FacilityKern | LOG\_KERN | Messages generated by the kernel. These cannot be generated by any user processes.
1585 FacilityLocal0 | LOG\_LOCAL0 | Reserved for local use.
1586 FacilityLocal1 | LOG\_LOCAL1 | Reserved for local use.
1587 FacilityLocal2 | LOG\_LOCAL2 | Reserved for local use.
1588 FacilityLocal3 | LOG\_LOCAL3 | Reserved for local use.
1589 FacilityLocal4 | LOG\_LOCAL4 | Reserved for local use.
1590 FacilityLocal5 | LOG\_LOCAL5 | Reserved for local use.
1591 FacilityLocal6 | LOG\_LOCAL6 | Reserved for local use.
1592 FacilityLocal7 | LOG\_LOCAL7 | Reserved for local use.
1593 FacilityLpr | LOG\_LPR | The line printer spooling system.
1594 FacilityMail | LOG\_MAIL | The mail system.
1595 FacilityNews | LOG\_NEWS | The network news system.
1596 FacilitySyslog | LOG\_SYSLOG | Messages generated internally by syslogd.
1597 FacilityUser | LOG\_USER | Messages generated by user processes. This is the default facility identifier if none is specified.
1598 FacilityUucp | LOG\_UUCP | The UUCP system.
1600 ## TimePeriod <a id="objecttype-timeperiod"></a>
1602 Time periods can be used to specify when hosts/services should be checked or to limit
1603 when notifications should be sent out.
1607 > Icinga 2 versions < 2.6.0 require the import of the [legacy-timeperiod](10-icinga-template-library.md#itl-legacy-timeperiod) template.
1612 object TimePeriod "nonworkhours" {
1613 display_name = "Icinga 2 TimePeriod for non working hours"
1616 monday = "00:00-8:00,17:00-24:00"
1617 tuesday = "00:00-8:00,17:00-24:00"
1618 wednesday = "00:00-8:00,17:00-24:00"
1619 thursday = "00:00-8:00,17:00-24:00"
1620 friday = "00:00-8:00,16:00-24:00"
1621 saturday = "00:00-24:00"
1622 sunday = "00:00-24:00"
1626 object TimePeriod "exampledays" {
1627 display_name = "Icinga 2 TimePeriod for random example days"
1630 //We still believe in Santa, no peeking!
1631 //Applies every 25th of December every year
1632 "december 25" = "00:00-24:00"
1634 //Any point in time can be specified,
1635 //but you still have to use a range
1636 "2038-01-19" = "03:13-03:15"
1638 //Evey 3rd day from the second monday of February
1639 //to 8th of November
1640 "monday 2 february - november 8 / 3" = "00:00-24:00"
1645 Additional examples can be found [here](08-advanced-topics.md#timeperiods).
1647 Configuration Attributes:
1649 Name | Type | Description
1650 --------------------------|-----------------------|----------------------------------
1651 display\_name | String | **Optional.** A short description of the time period.
1652 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1653 prefer\_includes | Boolean | **Optional.** Whether to prefer timeperiods `includes` or `excludes`. Default to true.
1654 excludes | Array of object names | **Optional.** An array of timeperiods, which should exclude from your timerange.
1655 includes | Array of object names | **Optional.** An array of timeperiods, which should include into your timerange
1660 Name | Type | Description
1661 --------------------------|-----------------------|----------------------------------
1662 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1665 ## User <a id="objecttype-user"></a>
1672 object User "icingaadmin" {
1673 display_name = "Icinga 2 Admin"
1674 groups = [ "icingaadmins" ]
1675 email = "icinga@localhost"
1676 pager = "icingaadmin@localhost.localdomain"
1680 states = [ OK, Warning, Critical, Unknown ]
1681 types = [ Problem, Recovery ]
1683 vars.additional_notes = "This is the Icinga 2 Admin account."
1687 Available notification state filters:
1696 Available notification type filters:
1708 Configuration Attributes:
1710 Name | Type | Description
1711 --------------------------|-----------------------|----------------------------------
1712 display\_name | String | **Optional.** A short description of the user.
1713 email | String | **Optional.** An email string for this user. Useful for notification commands.
1714 pager | String | **Optional.** A pager string for this user. Useful for notification commands.
1715 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this user.
1716 groups | Array of object names | **Optional.** An array of group names.
1717 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled for this user.
1718 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.
1719 types | Array | **Optional.** A set of type filters when a notification for this user should be triggered. By default everything is matched.
1720 states | Array | **Optional.** A set of state filters when a notification for this should be triggered. By default everything is matched.
1724 Name | Type | Description
1725 --------------------------|-----------------------|----------------------------------
1726 last\_notification | Timestamp | When the last notification was sent for this user (as a UNIX timestamp).
1728 ## UserGroup <a id="objecttype-usergroup"></a>
1734 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
1739 object UserGroup "icingaadmins" {
1740 display_name = "Icinga 2 Admin Group"
1744 Configuration Attributes:
1746 Name | Type | Description
1747 --------------------------|-----------------------|----------------------------------
1748 display\_name | String | **Optional.** A short description of the user group.
1749 groups | Array of object names | **Optional.** An array of nested group names.
1752 ## Zone <a id="objecttype-zone"></a>
1754 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1755 Please read the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring) for additional details.
1759 object Zone "master" {
1760 endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]
1764 object Zone "satellite" {
1765 endpoints = [ "icinga2-satellite1.localdomain" ]
1770 Configuration Attributes:
1772 Name | Type | Description
1773 --------------------------|-----------------------|----------------------------------
1774 endpoints | Array of object names | **Optional.** Array of endpoint names located in this zone.
1775 parent | Object name | **Optional.** The name of the parent zone.
1776 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`.
1778 Zone objects cannot currently be created with the API.