1 # Config Object Types <a id="object-types"></a>
3 This chapter provides an overview of all available config object types which can be
4 instantiated using the `object` keyword.
6 Additional details on configuration and runtime attributes and their
7 description are explained here too.
9 The attributes need to have a specific type value. Many of them are
10 explained in [this chapter](03-monitoring-basics.md#attribute-value-types) already.
11 You should note that the `Timestamp` type is a `Number`.
12 In addition to that `Object name` is an object reference to
13 an existing object name as `String` type.
15 Configuration objects share these runtime attributes which cannot be
16 modified by the user. You can access these attributes using
17 the [Icinga 2 API](12-icinga2-api.md#icinga2-api-config-objects).
19 Name | Type | Description
20 --------------------------|-----------------------|----------------------------------
21 version | Number | Timestamp when the object was created or modified. Synced throughout cluster nodes.
22 type | String | Object type.
23 original\_attributes | Dictionary | Original values of object attributes modified at runtime.
24 active | Boolean | Object is active (e.g. a service being checked).
25 paused | Boolean | Object has been paused at runtime (e.g. [IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection). Defaults to `false`.
26 templates | Array | Templates imported on object compilation.
27 package | String | [Configuration package name](12-icinga2-api.md#icinga2-api-config-management) this object belongs to. Local configuration is set to `_etc`, runtime created objects use `_api`.
28 source\_location | Dictionary | Location information where the configuration files are stored.
31 ## ApiListener <a id="objecttype-apilistener"></a>
33 ApiListener objects are used for distributed monitoring setups
34 and API usage specifying the certificate files used for ssl
35 authorization and additional restrictions.
36 This configuration object is available as [api feature](11-cli-commands.md#cli-command-feature).
38 The `TicketSalt` constant must be defined in [constants.conf](04-configuring-icinga-2.md#constants-conf).
43 object ApiListener "api" {
44 accept_commands = true
47 ticket_salt = TicketSalt
51 Configuration Attributes:
53 Name | Type | Description
54 --------------------------------------|-----------------------|----------------------------------
55 cert\_path | String | **Deprecated.** Path to the public key.
56 key\_path | String | **Deprecated.** Path to the private key.
57 ca\_path | String | **Deprecated.** Path to the CA certificate file.
58 ticket\_salt | String | **Optional.** Private key for [CSR auto-signing](06-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing). **Required** for a signing master instance.
59 crl\_path | String | **Optional.** Path to the CRL file.
60 bind\_host | String | **Optional.** The IP address the api listener should be bound to. Defaults to `0.0.0.0`.
61 bind\_port | Number | **Optional.** The port the api listener should be bound to. Defaults to `5665`.
62 accept\_config | Boolean | **Optional.** Accept zone configuration. Defaults to `false`.
63 accept\_commands | Boolean | **Optional.** Accept remote commands. Defaults to `false`.
64 max\_anonymous\_clients | Number | **Optional.** Limit the number of anonymous client connections (not configured endpoints and signing requests).
65 cipher\_list | String | **Optional.** Cipher list that is allowed. For a list of available ciphers run `openssl ciphers`. Defaults to `ALL:!LOW:!WEAK:!MEDIUM:!EXP:!NULL`.
66 tls\_protocolmin | String | **Optional.** Minimum TLS protocol version. Must be one of `TLSv1`, `TLSv1.1` or `TLSv1.2`. Defaults to `TLSv1`.
67 tls\_handshake\_timeout | Number | **Optional.** TLS Handshake timeout. Defaults to `10s`.
68 access\_control\_allow\_origin | Array | **Optional.** Specifies an array of origin URLs that may access the API. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Origin)
69 access\_control\_allow\_credentials | Boolean | **Deprecated.** Indicates whether or not the actual request can be made using credentials. Defaults to `true`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Credentials)
70 access\_control\_allow\_headers | String | **Deprecated.** Used in response to a preflight request to indicate which HTTP headers can be used when making the actual request. Defaults to `Authorization`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Headers)
71 access\_control\_allow\_methods | String | **Deprecated.** Used in response to a preflight request to indicate which HTTP methods can be used when making the actual request. Defaults to `GET, POST, PUT, DELETE`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Methods)
72 environment | String | **Optional.** Used as suffix in TLS SNI extension name; default from constant `ApiEnvironment`, which is empty.
74 The attributes `access_control_allow_credentials`, `access_control_allow_headers` and `access_control_allow_methods`
75 are controlled by Icinga 2 and are not changeable by config any more.
78 The ApiListener type expects its certificate files to be in the following locations:
81 ---------------------|-------------------------------------
82 Private key | `DataDir + "/certs/" + NodeName + ".key"`
83 Certificate file | `DataDir + "/certs/" + NodeName + ".crt"`
84 CA certificate file | `DataDir + "/certs/ca.crt"`
86 If the deprecated attributes `cert_path`, `key_path` and/or `ca_path` are specified Icinga 2
87 copies those files to the new location in `DataDir + "/certs"` unless the
88 file(s) there are newer.
90 Please check the [upgrading chapter](16-upgrading-icinga-2.md#upgrading-to-2-8-certificate-paths) for more details.
92 While Icinga 2 and the underlying OpenSSL library use sane and secure defaults, the attributes
93 `cipher_list` and `tls_protocolmin` can be used to increase communication security. A good source
94 for a more secure configuration is provided by the [Mozilla Wiki](https://wiki.mozilla.org/Security/Server_Side_TLS).
95 Ensure to use the same configuration for both attributes on **all** endpoints to avoid communication problems which
96 requires to use `cipher_list` compatible with the endpoint using the oldest version of the OpenSSL library. If using
97 other tools to connect to the API ensure also compatibility with them as this setting affects not only inter-cluster
98 communcation but also the REST API.
100 ## ApiUser <a id="objecttype-apiuser"></a>
102 ApiUser objects are used for authentication against the [Icinga 2 API](12-icinga2-api.md#icinga2-api-authentication).
107 object ApiUser "root" {
108 password = "mysecretapipassword"
109 permissions = [ "*" ]
113 Configuration Attributes:
115 Name | Type | Description
116 --------------------------|-----------------------|----------------------------------
117 password | String | **Optional.** Password string. Note: This attribute is hidden in API responses.
118 client\_cn | String | **Optional.** Client Common Name (CN).
119 permissions | Array | **Required.** Array of permissions. Either as string or dictionary with the keys `permission` and `filter`. The latter must be specified as function.
121 Available permissions are explained in the [API permissions](12-icinga2-api.md#icinga2-api-permissions)
124 ## CheckCommand <a id="objecttype-checkcommand"></a>
126 A check command definition. Additional default command custom attributes can be
132 object CheckCommand "http" {
133 command = [ PluginDir + "/check_http" ]
136 "-H" = "$http_vhost$"
137 "-I" = "$http_address$"
141 set_if = "$http_ssl$"
144 set_if = "$http_sni$"
147 value = "$http_auth_pair$"
148 description = "Username:password on sites with basic authentication"
151 set_if = "$http_ignore_body$"
153 "-r" = "$http_expect_body_regex$"
154 "-w" = "$http_warn_time$"
155 "-c" = "$http_critical_time$"
156 "-e" = "$http_expect$"
159 vars.http_address = "$address$"
160 vars.http_ssl = false
161 vars.http_sni = false
165 Configuration Attributes:
167 Name | Type | Description
168 --------------------------|-----------------------|----------------------------------
169 command | Array | **Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command. When using the "arguments" attribute this must be an array. Can be specified as function for advanced implementations.
170 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
171 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
172 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
173 arguments | Dictionary | **Optional.** A dictionary of command arguments.
176 ### CheckCommand Arguments <a id="objecttype-checkcommand-arguments"></a>
178 Command arguments can be defined as key-value-pairs in the `arguments`
179 dictionary. If the argument requires additional configuration, for example
180 a `description` attribute or an optional condition, the value can be defined
181 as dictionary specifying additional options.
186 vars.x_val = "My command argument value."
196 key = "-Xnew" /* optional, set a new key identifier */
197 description = "My plugin requires this argument for doing X."
198 required = false /* optional, no error if not set */
199 skip_key = false /* always use "-X <value>" */
200 set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
201 order = -1 /* first position */
202 repeat_key = true /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
206 description = "My plugin requires this argument for doing Y."
207 required = false /* optional, no error if not set */
208 skip_key = true /* don't prefix "-Y" only use "<value>" */
209 set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
210 order = 0 /* second position */
211 repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
216 Name | Type | Description
217 --------------------------|-----------------------|----------------------------------
218 value | String/Function | Optional argument value set by a [runtime macro string](03-monitoring-basics.md#runtime-macros) or a [function call](17-language-reference.md#functions).
219 key | String | Optional argument key overriding the key identifier.
220 description | String | Optional argument description.
221 required | Boolean | Required argument. Execution error if not set. Defaults to false (optional).
222 skip\_key | Boolean | Use the value as argument and skip the key.
223 set\_if | String/Function | Argument is added if the [runtime macro string](03-monitoring-basics.md#runtime-macros) resolves to a defined numeric or boolean value. String values are not supported. [Function calls](17-language-reference.md#functions) returning a value are supported too.
224 order | Number | Set if multiple arguments require a defined argument order.
225 repeat\_key | Boolean | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
230 ..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...
233 Define argument array:
236 value = "[ 'one', 'two', 'three' ]"
239 Argument array with `repeat_key = true`:
242 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'
245 Argument array with `repeat_key = false`:
248 'key' 'value[0]' 'value[1]' 'value[2]'
251 ## CheckerComponent <a id="objecttype-checkcomponent"></a>
253 The checker component is responsible for scheduling active checks.
254 This configuration object is available as [checker feature](11-cli-commands.md#cli-command-feature).
259 object CheckerComponent "checker" { }
262 Configuration Attributes:
264 Name | Type | Description
265 --------------------------|-----------------------|----------------------------------
266 concurrent\_checks | Number | **Optional and deprecated.** The maximum number of concurrent checks. Was replaced by global constant `MaxConcurrentChecks` which will be set if you still use `concurrent_checks`.
268 ## CheckResultReader <a id="objecttype-checkresultreader"></a>
270 Reads Icinga 1.x check result files from a directory. This functionality is provided
271 to help existing Icinga 1.x users and might be useful for migration scenarios.
276 object CheckResultReader "reader" {
277 spool_dir = "/data/check-results"
281 Configuration Attributes:
283 Name | Type | Description
284 --------------------------|-----------------------|----------------------------------
285 spool\_dir | String | **Optional.** The directory which contains the check result files. Defaults to DataDir + "/spool/checkresults/".
287 ## Comment <a id="objecttype-comment"></a>
289 Comments created at runtime are represented as objects.
290 Note: This is for reference only. You can create comments
291 with the [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) API action.
296 object Comment "localhost!my-comment" {
297 host_name = "localhost"
298 author = "icingaadmin"
299 text = "This is a comment."
303 Configuration Attributes:
305 Name | Type | Description
306 --------------------------|-----------------------|----------------------------------
307 host\_name | Object name | **Required.** The name of the host this comment belongs to.
308 service\_name | Object name | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment.
309 author | String | **Required.** The author's name.
310 text | String | **Required.** The comment text.
311 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this comment was added.
312 entry\_type | Number | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
313 expire\_time | Timestamp | **Optional.** The comment's expire time as UNIX timestamp.
314 persistent | Boolean | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
316 ## CompatLogger <a id="objecttype-compatlogger"></a>
318 Writes log files in a format that's compatible with Icinga 1.x.
319 This configuration object is available as [compatlog feature](14-features.md#compat-logging).
324 object CompatLogger "compatlog" {
325 log_dir = "/var/log/icinga2/compat"
326 rotation_method = "DAILY"
330 Configuration Attributes:
332 Name | Type | Description
333 --------------------------|-----------------------|----------------------------------
334 log\_dir | String | **Optional.** Path to the compat log directory. Defaults to LogDir + "/compat".
335 rotation\_method | String | **Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
338 ## Dependency <a id="objecttype-dependency"></a>
340 Dependency objects are used to specify dependencies between hosts and services. Dependencies
341 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
346 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
347 > to just create a `Dependency` template and use the `apply` keyword to assign the
348 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
349 > type for `Host` or `Service`.
350 > Check the [dependencies](03-monitoring-basics.md#dependencies) chapter for detailed examples.
352 Service-to-Service Example:
355 object Dependency "webserver-internet" {
356 parent_host_name = "internet"
357 parent_service_name = "ping4"
359 child_host_name = "webserver"
360 child_service_name = "ping4"
362 states = [ OK, Warning ]
364 disable_checks = true
368 Host-to-Host Example:
371 object Dependency "webserver-internet" {
372 parent_host_name = "internet"
374 child_host_name = "webserver"
378 disable_checks = true
382 Configuration Attributes:
384 Name | Type | Description
385 --------------------------|-----------------------|----------------------------------
386 parent\_host\_name | Object name | **Required.** The parent host.
387 parent\_service\_name | Object name | **Optional.** The parent service. If omitted, this dependency object is treated as host dependency.
388 child\_host\_name | Object name | **Required.** The child host.
389 child\_service\_name | Object name | **Optional.** The child service. If omitted, this dependency object is treated as host dependency.
390 disable\_checks | Boolean | **Optional.** Whether to disable checks when this dependency fails. Defaults to false.
391 disable\_notifications | Boolean | **Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
392 ignore\_soft\_states | Boolean | **Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
393 period | Object name | **Optional.** Time period object during which this dependency is enabled.
394 states | Array | **Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
396 Available state filters:
405 When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
406 automatically determined by Icinga 2.
408 Service-to-Host Dependency Example:
411 apply Dependency "internet" to Service {
412 parent_host_name = "dsl-router"
413 disable_checks = true
415 assign where host.name != "dsl-router"
419 This example sets all service objects matching the assign condition into a dependency relation to
420 the parent host object `dsl-router` as implicit child services.
422 Service-to-Service-on-the-same-Host Dependency Example:
425 apply Dependency "disable-agent-checks" to Service {
426 parent_service_name = "agent-health"
428 assign where service.check_command == "ssh"
429 ignore where service.name == "agent-health"
433 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
434 host object matched by the apply rule condition. All services where apply matches are made implicit child services
435 in this dependency relation.
438 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
439 name you specified. This means you can define more than one object with the same (short) name as long as one of the `child_host_name` and
440 `child_service_name` attributes has a different value.
442 ## Downtime <a id="objecttype-downtime"></a>
444 Downtimes created at runtime are represented as objects.
445 You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action.
450 object Downtime "my-downtime" {
451 host_name = "localhost"
452 author = "icingaadmin"
453 comment = "This is a downtime."
454 start_time = 1505312869
455 end_time = 1505312924
459 Configuration Attributes:
461 Name | Type | Description
462 --------------------------|-----------------------|----------------------------------
463 host\_name | Object name | **Required.** The name of the host this comment belongs to.
464 service\_name | Object name | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment.
465 author | String | **Required.** The author's name.
466 comment | String | **Required.** The comment text.
467 start\_time | Timestamp | **Required.** The start time as UNIX timestamp.
468 end\_time | Timestamp | **Required.** The end time as UNIX timestamp.
469 duration | Number | **Optional.** The duration as number.
470 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this downtime was added.
471 fixed | Boolean | **Optional.** Whether the downtime is fixed (true) or flexible (false). Defaults to flexible. Details in the [advanced topics chapter](08-advanced-topics.md#fixed-flexible-downtimes).
472 triggers | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime.
476 Name | Type | Description
477 --------------------------|-----------------------|----------------------------------
478 trigger\_time | Timestamp | The UNIX timestamp when this downtime was triggered.
479 triggered\_by | Object name | The name of the downtime this downtime was triggered by.
482 ## ElasticsearchWriter <a id="objecttype-elasticsearchwriter"></a>
484 Writes check result metrics and performance data to an Elasticsearch instance.
485 This configuration object is available as [elasticsearch feature](14-features.md#elasticsearch-writer).
490 object ElasticsearchWriter "elasticsearch" {
495 enable_send_perfdata = true
497 flush_threshold = 1024
502 The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
504 Configuration Attributes:
506 Name | Type | Description
507 --------------------------|-----------------------|----------------------------------
508 host | String | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
509 port | Number | **Required.** Elasticsearch port. Defaults to `9200`.
510 index | String | **Required.** Elasticsearch index name. Defaults to `icinga2`.
511 enable\_send\_perfdata | Boolean | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
512 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to Elasticsearch. Defaults to `10s`.
513 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to `1024`.
514 username | String | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
515 password | String | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
516 enable\_tls | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
517 ca\_path | String | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
518 cert\_path | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
519 key\_path | String | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
520 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `true`.
522 Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
523 Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
525 Basic auth is supported with the `username` and `password` attributes. This requires an
526 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/)
529 TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
530 you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
532 ## Endpoint <a id="objecttype-endpoint"></a>
534 Endpoint objects are used to specify connection information for remote
535 Icinga 2 instances. More details can be found in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
540 object Endpoint "icinga2-client1.localdomain" {
541 host = "192.168.56.111"
547 Example (disable replay log):
550 object Endpoint "icinga2-client1.localdomain" {
551 host = "192.168.5.111"
557 Configuration Attributes:
559 Name | Type | Description
560 --------------------------|-----------------------|----------------------------------
561 host | String | **Optional.** The hostname/IP address of the remote Icinga 2 instance.
562 port | Number | **Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
563 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.
565 Endpoint objects cannot currently be created with the API.
567 ## EventCommand <a id="objecttype-eventcommand"></a>
569 An event command definition.
574 object EventCommand "restart-httpd-event" {
575 command = "/opt/bin/restart-httpd.sh"
580 Configuration Attributes:
582 Name | Type | Description
583 --------------------------|-----------------------|----------------------------------
584 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.
585 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
586 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
587 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
588 arguments | Dictionary | **Optional.** A dictionary of command arguments.
590 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
592 More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
594 ## ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
596 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
597 This configuration object is available as [command feature](14-features.md#external-commands).
602 object ExternalCommandListener "command" {
603 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
607 Configuration Attributes:
609 Name | Type | Description
610 --------------------------|-----------------------|----------------------------------
611 command\_path | String | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
615 ## FileLogger <a id="objecttype-filelogger"></a>
617 Specifies Icinga 2 logging to a file.
618 This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging).
623 object FileLogger "debug-file" {
625 path = "/var/log/icinga2/debug.log"
629 Configuration Attributes:
631 Name | Type | Description
632 --------------------------|-----------------------|----------------------------------
633 path | String | **Required.** The log path.
634 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
637 ## GelfWriter <a id="objecttype-gelfwriter"></a>
639 Writes event log entries to a defined GELF receiver host (Graylog, Logstash).
640 This configuration object is available as [gelf feature](14-features.md#gelfwriter).
645 object GelfWriter "gelf" {
651 Configuration Attributes:
653 Name | Type | Description
654 --------------------------|-----------------------|----------------------------------
655 host | String | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`.
656 port | Number | **Optional.** GELF receiver port. Defaults to `12201`.
657 source | String | **Optional.** Source name for this instance. Defaults to `icinga2`.
658 enable\_send\_perfdata | Boolean | **Optional.** Enable performance data for 'CHECK RESULT' events.
659 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `true`.
662 ## GraphiteWriter <a id="objecttype-graphitewriter"></a>
664 Writes check result metrics and performance data to a defined
665 Graphite Carbon host.
666 This configuration object is available as [graphite feature](14-features.md#graphite-carbon-cache-writer).
671 object GraphiteWriter "graphite" {
677 Configuration Attributes:
679 Name | Type | Description
680 --------------------------|-----------------------|----------------------------------
681 host | String | **Optional.** Graphite Carbon host address. Defaults to `127.0.0.1`.
682 port | Number | **Optional.** Graphite Carbon port. Defaults to `2003`.
683 host\_name\_template | String | **Optional.** Metric prefix for host name. Defaults to `icinga2.$host.name$.host.$host.check_command$`.
684 service\_name\_template | String | **Optional.** Metric prefix for service name. Defaults to `icinga2.$host.name$.services.$service.name$.$service.check_command$`.
685 enable\_send\_thresholds | Boolean | **Optional.** Send additional threshold metrics. Defaults to `false`.
686 enable\_send\_metadata | Boolean | **Optional.** Send additional metadata metrics. Defaults to `false`.
687 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `true`.
689 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
693 ## Host <a id="objecttype-host"></a>
700 object Host "icinga2-client1.localdomain" {
701 display_name = "Linux Client 1"
702 address = "192.168.56.111"
703 address6 = "2a00:1450:4001:815::2003"
705 groups = [ "linux-servers" ]
707 check_command = "hostalive"
711 Configuration Attributes:
713 Name | Type | Description
714 --------------------------|-----------------------|----------------------------------
715 display\_name | String | **Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
716 address | String | **Optional.** The host's IPv4 address. Available as command runtime macro `$address$` if set.
717 address6 | String | **Optional.** The host's IPv6 address. Available as command runtime macro `$address6$` if set.
718 groups | Array of object names | **Optional.** A list of host groups this host belongs to.
719 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this host.
720 check\_command | Object name | **Required.** The name of the check command.
721 max\_check\_attempts | Number | **Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
722 check\_period | Object name | **Optional.** The name of a time period which determines when this host should be checked. Not set by default.
723 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
724 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`.
725 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`.
726 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to true.
727 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to true.
728 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to true.
729 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to true.
730 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to false.
731 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to true.
732 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.
733 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a host to be considered flapping. Default `30.0`
734 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a host to be considered not flapping. Default `25.0`
735 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
736 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.
737 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
738 notes | String | **Optional.** Notes for the host.
739 notes\_url | String | **Optional.** URL for notes for the host (for example, in notification commands).
740 action\_url | String | **Optional.** URL for actions for the host (for example, an external graphing tool).
741 icon\_image | String | **Optional.** Icon image for the host. Used by external interfaces only.
742 icon\_image\_alt | String | **Optional.** Icon image description for the host. Used by external interface only.
744 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
745 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
749 > The `address` and `address6` attributes are required for running commands using
750 > the `$address$` and `$address6$` runtime macros.
754 Name | Type | Description
755 --------------------------|-----------------------|----------------------------------
756 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
757 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
758 check\_attempt | Number | The current check attempt number.
759 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
760 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
761 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
762 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
763 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
764 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
765 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
766 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
767 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
768 downtime\_depth | Number | Whether the host has one or more active downtimes.
769 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
770 flapping | Boolean | Whether the host is flapping between states.
771 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
772 state | Number | The current state (0 = UP, 1 = DOWN).
773 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
774 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
775 last\_state\_up | Timestamp | When the last UP state occurred (as a UNIX timestamp).
776 last\_state\_down | Timestamp | When the last DOWN state occurred (as a UNIX timestamp).
780 ## HostGroup <a id="objecttype-hostgroup"></a>
786 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
791 object HostGroup "linux-servers" {
792 display_name = "Linux Servers"
794 assign where host.vars.os == "Linux"
798 Configuration Attributes:
800 Name | Type | Description
801 --------------------------|-----------------------|----------------------------------
802 display\_name | String | **Optional.** A short description of the host group.
803 groups | Array of object names | **Optional.** An array of nested group names.
805 ## IcingaApplication <a id="objecttype-icingaapplication"></a>
807 The IcingaApplication object is required to start Icinga 2.
808 The object name must be `app`. If the object configuration
809 is missing, Icinga 2 will automatically create an IcingaApplication
815 object IcingaApplication "app" {
816 enable_perfdata = false
820 Configuration Attributes:
822 Name | Type | Description
823 --------------------------|-----------------------|----------------------------------
824 enable\_notifications | Boolean | **Optional.** Whether notifications are globally enabled. Defaults to true.
825 enable\_event\_handlers | Boolean | **Optional.** Whether event handlers are globally enabled. Defaults to true.
826 enable\_flapping | Boolean | **Optional.** Whether flap detection is globally enabled. Defaults to true.
827 enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true.
828 enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true.
829 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true.
830 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally.
831 environment | String | **Optional.** Specify the Icinga environment. This overrides the `Environment` constant specified in the configuration or on the CLI with `--define`. Defaults to empty.
833 ## IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
835 IDO database adapter for MySQL.
836 This configuration object is available as [ido-mysql feature](14-features.md#db-ido).
841 object IdoMysqlConnection "mysql-ido" {
849 downtimehistory_age = 48h
850 contactnotifications_age = 31d
855 Configuration Attributes:
857 Name | Type | Description
858 --------------------------|-----------------------|----------------------------------
859 host | String | **Optional.** MySQL database host address. Defaults to `localhost`.
860 port | Number | **Optional.** MySQL database port. Defaults to `3306`.
861 socket\_path | String | **Optional.** MySQL socket path.
862 user | String | **Optional.** MySQL database user with read/write permission to the icinga database. Defaults to `icinga`.
863 password | String | **Optional.** MySQL database user's password. Defaults to `icinga`.
864 database | String | **Optional.** MySQL database name. Defaults to `icinga`.
865 enable\_ssl | Boolean | **Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
866 ssl\_key | String | **Optional.** MySQL SSL client key file path.
867 ssl\_cert | String | **Optional.** MySQL SSL certificate file path.
868 ssl\_ca | String | **Optional.** MySQL SSL certificate authority certificate file path.
869 ssl\_capath | String | **Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
870 ssl\_cipher | String | **Optional.** MySQL SSL list of allowed ciphers.
871 table\_prefix | String | **Optional.** MySQL database table prefix. Defaults to `icinga_`.
872 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
873 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
874 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`.
875 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`.
876 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
877 categories | Array | **Optional.** Array of information types that should be written to the database.
881 Name | Type | Description
882 --------------------------------|-----------------------|----------------------------------
883 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
884 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
885 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
886 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
887 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
888 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
889 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
890 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
891 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
892 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
893 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
894 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
895 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
896 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
897 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
901 Name | Description | Required by
902 ---------------------|------------------------|--------------------
903 DbCatConfig | Configuration data | Icinga Web 2
904 DbCatState | Current state data | Icinga Web 2
905 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
906 DbCatComment | Comments | Icinga Web 2
907 DbCatDowntime | Downtimes | Icinga Web 2
908 DbCatEventHandler | Event handler data | Icinga Web 2
909 DbCatExternalCommand | External commands | --
910 DbCatFlapping | Flap detection data | Icinga Web 2
911 DbCatCheck | Check results | --
912 DbCatLog | Log messages | --
913 DbCatNotification | Notifications | Icinga Web 2
914 DbCatProgramStatus | Program status data | Icinga Web 2
915 DbCatRetention | Retention data | Icinga Web 2
916 DbCatStateHistory | Historical state data | Icinga Web 2
918 The default value for `categories` includes everything required
919 by Icinga Web 2 in the table above.
921 In addition to the category flags listed above the `DbCatEverything`
922 flag may be used as a shortcut for listing all flags.
924 ## IdoPgsqlConnection <a id="objecttype-idopgsqlconnection"></a>
926 IDO database adapter for PostgreSQL.
927 This configuration object is available as [ido-pgsql feature](14-features.md#db-ido).
932 object IdoPgsqlConnection "pgsql-ido" {
940 downtimehistory_age = 48h
941 contactnotifications_age = 31d
946 Configuration Attributes:
948 Name | Type | Description
949 --------------------------|-----------------------|----------------------------------
950 host | String | **Optional.** PostgreSQL database host address. Defaults to `localhost`.
951 port | Number | **Optional.** PostgreSQL database port. Defaults to `5432`.
952 user | String | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`.
953 password | String | **Optional.** PostgreSQL database user's password. Defaults to `icinga`.
954 database | String | **Optional.** PostgreSQL database name. Defaults to `icinga`.
955 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`.
956 ssl\_key | String | **Optional.** PostgreSQL SSL client key file path.
957 ssl\_cert | String | **Optional.** PostgreSQL SSL certificate file path.
958 ssl\_ca | String | **Optional.** PostgreSQL SSL certificate authority certificate file path.
959 table\_prefix | String | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`.
960 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
961 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
962 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".
963 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`.
964 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
965 categories | Array | **Optional.** Array of information types that should be written to the database.
969 Name | Type | Description
970 --------------------------------|-----------------------|----------------------------------
971 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
972 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
973 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
974 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
975 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
976 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
977 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
978 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
979 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
980 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
981 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
982 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
983 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
984 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
985 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
989 Name | Description | Required by
990 ---------------------|------------------------|--------------------
991 DbCatConfig | Configuration data | Icinga Web 2
992 DbCatState | Current state data | Icinga Web 2
993 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
994 DbCatComment | Comments | Icinga Web 2
995 DbCatDowntime | Downtimes | Icinga Web 2
996 DbCatEventHandler | Event handler data | Icinga Web 2
997 DbCatExternalCommand | External commands | --
998 DbCatFlapping | Flap detection data | Icinga Web 2
999 DbCatCheck | Check results | --
1000 DbCatLog | Log messages | --
1001 DbCatNotification | Notifications | Icinga Web 2
1002 DbCatProgramStatus | Program status data | Icinga Web 2
1003 DbCatRetention | Retention data | Icinga Web 2
1004 DbCatStateHistory | Historical state data | Icinga Web 2
1006 The default value for `categories` includes everything required
1007 by Icinga Web 2 in the table above.
1009 In addition to the category flags listed above the `DbCatEverything`
1010 flag may be used as a shortcut for listing all flags.
1012 ## InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
1014 Writes check result metrics and performance data to a defined InfluxDB host.
1015 This configuration object is available as [influxdb feature](14-features.md#influxdb-writer).
1020 object InfluxdbWriter "influxdb" {
1023 database = "icinga2"
1025 flush_threshold = 1024
1026 flush_interval = 10s
1029 measurement = "$host.check_command$"
1031 hostname = "$host.name$"
1034 service_template = {
1035 measurement = "$service.check_command$"
1037 hostname = "$host.name$"
1038 service = "$service.name$"
1044 Configuration Attributes:
1046 Name | Type | Description
1047 --------------------------|-----------------------|----------------------------------
1048 host | String | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
1049 port | Number | **Required.** InfluxDB HTTP port. Defaults to `8086`.
1050 database | String | **Required.** InfluxDB database name. Defaults to `icinga2`.
1051 username | String | **Optional.** InfluxDB user name. Defaults to `none`.
1052 password | String | **Optional.** InfluxDB user password. Defaults to `none`.
1053 ssl\_enable | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`.
1054 ssl\_ca\_cert | String | **Optional.** Path to CA certificate to validate the remote host.
1055 ssl\_cert | String | **Optional.** Path to host certificate to present to the remote host for mutual verification.
1056 ssl\_key | String | **Optional.** Path to host key to accompany the ssl\_cert.
1057 host\_template | String | **Required.** Host template to define the InfluxDB line protocol.
1058 service\_template | String | **Required.** Service template to define the influxDB line protocol.
1059 enable\_send\_thresholds | Boolean | **Optional.** Whether to send warn, crit, min & max tagged data.
1060 enable\_send\_metadata | Boolean | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
1061 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to InfluxDB. Defaults to `10s`.
1062 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`.
1063 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `true`.
1065 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
1066 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
1071 ## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
1073 Livestatus API interface available as TCP or UNIX socket. Historical table queries
1074 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
1075 pointing to the log files using the `compat_log_path` configuration attribute.
1076 This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus).
1081 object LivestatusListener "livestatus-tcp" {
1083 bind_host = "127.0.0.1"
1087 object LivestatusListener "livestatus-unix" {
1088 socket_type = "unix"
1089 socket_path = "/var/run/icinga2/cmd/livestatus"
1093 Configuration Attributes:
1095 Name | Type | Description
1096 --------------------------|-----------------------|----------------------------------
1097 socket\_type | String | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`.
1098 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`.
1099 bind\_port | Number | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`.
1100 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".
1101 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"
1105 > UNIX sockets are not supported on Windows.
1108 ## Notification <a id="objecttype-notification"></a>
1110 Notification objects are used to specify how users should be notified in case
1111 of host and service state changes and other events.
1115 > Rather than creating a `Notification` object for a specific host or service it is
1116 > usually easier to just create a `Notification` template and use the `apply` keyword
1117 > to assign the notification to a number of hosts or services. Use the `to` keyword
1118 > to set the specific target type for `Host` or `Service`.
1119 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
1124 object Notification "localhost-ping-notification" {
1125 host_name = "localhost"
1126 service_name = "ping4"
1128 command = "mail-notification"
1130 users = [ "user1", "user2" ] // reference to User objects
1132 types = [ Problem, Recovery ]
1133 states = [ Critical, Warning, OK ]
1137 Configuration Attributes:
1139 Name | Type | Description
1140 --------------------------|-----------------------|----------------------------------
1141 host\_name | Object name | **Required.** The name of the host this notification belongs to.
1142 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.
1143 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
1144 users | Array of object names | **Required.** A list of user names who should be notified. **Optional.** if the `user_groups` attribute is set.
1145 user\_groups | Array of object names | **Required.** A list of user group names who should be notified. **Optional.** if the `users` attribute is set.
1146 times | Dictionary | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
1147 command | Object name | **Required.** The name of the notification command which should be executed when the notification is triggered.
1148 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.
1149 period | Object name | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
1150 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.
1151 types | Array | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
1152 states | Array | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched. Note that the states filter is ignored for notifications of type Acknowledgement!
1154 Available notification state filters for Service:
1161 Available notification state filters for Host:
1166 Available notification type filters:
1180 Name | Type | Description
1181 ----------------------------|-----------------------|-----------------
1182 last\_notification | Timestamp | When the last notification was sent for this Notification object (as a UNIX timestamp).
1183 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).
1184 notification\_number | Number | The notification number.
1185 last\_problem\_notification | Timestamp | When the last notification was sent for a problem (as a UNIX timestamp).
1188 ## NotificationCommand <a id="objecttype-notificationcommand"></a>
1190 A notification command definition.
1195 object NotificationCommand "mail-service-notification" {
1196 command = [ ConfigDir + "/scripts/mail-service-notification.sh" ]
1201 value = "$notification_address$"
1203 "-6" = "$notification_address6$"
1204 "-b" = "$notification_author$"
1205 "-c" = "$notification_comment$"
1208 value = "$notification_date$"
1212 value = "$notification_servicename$"
1215 value = "$notification_from$"
1216 description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
1218 "-i" = "$notification_icingaweb2url$"
1221 value = "$notification_hostname$"
1225 value = "$notification_hostdisplayname$"
1229 value = "$notification_serviceoutput$"
1233 value = "$notification_useremail$"
1237 value = "$notification_servicestate$"
1241 value = "$notification_type$"
1245 value = "$notification_servicedisplayname$"
1247 "-v" = "$notification_logtosyslog$"
1251 notification_address = "$address$"
1252 notification_address6 = "$address6$"
1253 notification_author = "$notification.author$"
1254 notification_comment = "$notification.comment$"
1255 notification_type = "$notification.type$"
1256 notification_date = "$icinga.long_date_time$"
1257 notification_hostname = "$host.name$"
1258 notification_hostdisplayname = "$host.display_name$"
1259 notification_servicename = "$service.name$"
1260 notification_serviceoutput = "$service.output$"
1261 notification_servicestate = "$service.state$"
1262 notification_useremail = "$user.email$"
1263 notification_servicedisplayname = "$service.display_name$"
1268 Configuration Attributes:
1270 Name | Type | Description
1271 --------------------------|-----------------------|----------------------------------
1272 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.
1273 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1274 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
1275 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
1276 arguments | Dictionary | **Optional.** A dictionary of command arguments.
1278 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
1280 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
1282 ## NotificationComponent <a id="objecttype-notificationcomponent"></a>
1284 The notification component is responsible for sending notifications.
1285 This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature).
1290 object NotificationComponent "notification" { }
1293 Configuration Attributes:
1295 Name | Type | Description
1296 --------------------------|-----------------------|----------------------------------
1297 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".
1299 ## OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1301 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1302 This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer).
1307 object OpenTsdbWriter "opentsdb" {
1313 Configuration Attributes:
1315 Name | Type | Description
1316 --------------------------|-----------------------|----------------------------------
1317 host | String | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`.
1318 port | Number | **Optional.** OpenTSDB port. Defaults to `4242`.
1319 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `true`.
1322 ## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1324 Writes check result performance data to a defined path using macro
1325 pattern consisting of custom attributes and runtime macros.
1326 This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files).
1331 object PerfdataWriter "perfdata" {
1332 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1334 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1336 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$"
1337 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$"
1339 rotation_interval = 15s
1343 Configuration Attributes:
1345 Name | Type | Description
1346 --------------------------|-----------------------|----------------------------------
1347 host\_perfdata\_path | String | **Optional.** Path to the host performance data file. Defaults to SpoolDir + "/perfdata/host-perfdata".
1348 service\_perfdata\_path | String | **Optional.** Path to the service performance data file. Defaults to SpoolDir + "/perfdata/service-perfdata".
1349 host\_temp\_path | String | **Optional.** Path to the temporary host file. Defaults to SpoolDir + "/tmp/host-perfdata".
1350 service\_temp\_path | String | **Optional.** Path to the temporary service file. Defaults to SpoolDir + "/tmp/service-perfdata".
1351 host\_format\_template | String | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1352 service\_format\_template | String | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1353 rotation\_interval | Duration | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`.
1354 enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `true`.
1356 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1357 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1360 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
1362 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1366 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1367 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1368 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1369 > type for `Host` or `Service`.
1370 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
1375 object ScheduledDowntime "some-downtime" {
1376 host_name = "localhost"
1377 service_name = "ping4"
1379 author = "icingaadmin"
1380 comment = "Some comment"
1386 "sunday" = "02:00-03:00"
1391 Configuration Attributes:
1393 Name | Type | Description
1394 --------------------------|-----------------------|----------------------------------
1395 host\_name | Object name | **Required.** The name of the host this scheduled downtime belongs to.
1396 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.
1397 author | String | **Required.** The author of the downtime.
1398 comment | String | **Required.** A comment for the downtime.
1399 fixed | Boolean | **Optional.** Whether this is a fixed downtime. Defaults to `true`.
1400 duration | Duration | **Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1401 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1402 child\_options | String | **Optional.** Schedule child downtimes. `DowntimeNoChildren` does not do anything, `DowntimeTriggeredChildren` schedules child downtimes triggered by this downtime, `DowntimeNonTriggeredChildren` schedules non-triggered downtimes. Defaults to `DowntimeNoChildren`.
1404 ScheduledDowntime objects have composite names, i.e. their names are based
1405 on the `host_name` and `service_name` attributes and the
1406 name you specified. This means you can define more than one object
1407 with the same (short) name as long as one of the `host_name` and
1408 `service_name` attributes has a different value.
1411 ## Service <a id="objecttype-service"></a>
1413 Service objects describe network services and how they should be checked
1418 > Rather than creating a `Service` object for a specific host it is usually easier
1419 > to just create a `Service` template and use the `apply` keyword to assign the
1420 > service to a number of hosts.
1421 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
1426 object Service "uptime" {
1427 host_name = "localhost"
1429 display_name = "localhost Uptime"
1431 check_command = "snmp"
1433 vars.snmp_community = "public"
1434 vars.snmp_oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1436 check_interval = 60s
1437 retry_interval = 15s
1439 groups = [ "all-services", "snmp" ]
1443 Configuration Attributes:
1445 Name | Type | Description
1446 --------------------------|-----------------------|----------------------------------
1447 display\_name | String | **Optional.** A short description of the service.
1448 host\_name | Object name | **Required.** The host this service belongs to. There must be a `Host` object with that name.
1449 groups | Array of object names | **Optional.** The service groups this service belongs to.
1450 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this service.
1451 check\_command | Object name | **Required.** The name of the check command.
1452 max\_check\_attempts | Number | **Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1453 check\_period | Object name | **Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1454 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
1455 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`.
1456 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`.
1457 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to `true`.
1458 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to `true`.
1459 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to `true`.
1460 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to `true`.
1461 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to `false`.
1462 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a service to be considered flapping. `30.0`
1463 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a service to be considered not flapping. `25.0`
1464 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to `true`.
1465 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.
1466 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
1467 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.
1468 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.
1469 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
1470 notes | String | **Optional.** Notes for the service.
1471 notes\_url | String | **Optional.** URL for notes for the service (for example, in notification commands).
1472 action\_url | String | **Optional.** URL for actions for the service (for example, an external graphing tool).
1473 icon\_image | String | **Optional.** Icon image for the service. Used by external interfaces only.
1474 icon\_image\_alt | String | **Optional.** Icon image description for the service. Used by external interface only.
1476 Service objects have composite names, i.e. their names are based on the host\_name attribute and the name you specified. This means
1477 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1479 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
1480 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
1484 Name | Type | Description
1485 --------------------------|-----------------------|----------------------------------
1486 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
1487 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
1488 check\_attempt | Number | The current check attempt number.
1489 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1490 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1491 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1492 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
1493 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
1494 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
1495 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1496 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1497 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1498 downtime\_depth | Number | Whether the service has one or more active downtimes.
1499 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
1500 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
1501 flapping | Boolean | Whether the host is flapping between states.
1502 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1503 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1504 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1505 last\_state\_ok | Timestamp | When the last OK state occurred (as a UNIX timestamp).
1506 last\_state\_warning | Timestamp | When the last WARNING state occurred (as a UNIX timestamp).
1507 last\_state\_critical | Timestamp | When the last CRITICAL state occurred (as a UNIX timestamp).
1508 last\_state\_unknown | Timestamp | When the last UNKNOWN state occurred (as a UNIX timestamp).
1511 ## ServiceGroup <a id="objecttype-servicegroup"></a>
1513 A group of services.
1517 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
1522 object ServiceGroup "snmp" {
1523 display_name = "SNMP services"
1527 Configuration Attributes:
1529 Name | Type | Description
1530 --------------------------|-----------------------|----------------------------------
1531 display\_name | String | **Optional.** A short description of the service group.
1532 groups | Array of object names | **Optional.** An array of nested group names.
1535 ## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1537 Periodically writes status and configuration data files which are used by third-party tools.
1538 This configuration object is available as [statusdata feature](14-features.md#status-data).
1543 object StatusDataWriter "status" {
1544 status_path = "/var/cache/icinga2/status.dat"
1545 objects_path = "/var/cache/icinga2/objects.cache"
1546 update_interval = 30s
1550 Configuration Attributes:
1552 Name | Type | Description
1553 --------------------------|-----------------------|----------------------------------
1554 status\_path | String | **Optional.** Path to the `status.dat` file. Defaults to CacheDir + "/status.dat".
1555 objects\_path | String | **Optional.** Path to the `objects.cache` file. Defaults to CacheDir + "/objects.cache".
1556 update\_interval | Duration | **Optional.** The interval in which the status files are updated. Defaults to `15s`.
1559 ## SyslogLogger <a id="objecttype-sysloglogger"></a>
1561 Specifies Icinga 2 logging to syslog.
1562 This configuration object is available as `syslog` [logging feature](14-features.md#logging).
1567 object SyslogLogger "syslog" {
1568 severity = "warning"
1572 Configuration Attributes:
1574 Name | Type | Description
1575 --------------------------|-----------------------|----------------------------------
1576 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1577 facility | String | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`.
1581 Name | Facility | Description
1582 ---------------------|---------------|----------------
1583 FacilityAuth | LOG\_AUTH | The authorization system.
1584 FacilityAuthPriv | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals.
1585 FacilityCron | LOG\_CRON | The cron daemon.
1586 FacilityDaemon | LOG\_DAEMON | System daemons that are not provided for explicitly by other facilities.
1587 FacilityFtp | LOG\_FTP | The file transfer protocol daemons.
1588 FacilityKern | LOG\_KERN | Messages generated by the kernel. These cannot be generated by any user processes.
1589 FacilityLocal0 | LOG\_LOCAL0 | Reserved for local use.
1590 FacilityLocal1 | LOG\_LOCAL1 | Reserved for local use.
1591 FacilityLocal2 | LOG\_LOCAL2 | Reserved for local use.
1592 FacilityLocal3 | LOG\_LOCAL3 | Reserved for local use.
1593 FacilityLocal4 | LOG\_LOCAL4 | Reserved for local use.
1594 FacilityLocal5 | LOG\_LOCAL5 | Reserved for local use.
1595 FacilityLocal6 | LOG\_LOCAL6 | Reserved for local use.
1596 FacilityLocal7 | LOG\_LOCAL7 | Reserved for local use.
1597 FacilityLpr | LOG\_LPR | The line printer spooling system.
1598 FacilityMail | LOG\_MAIL | The mail system.
1599 FacilityNews | LOG\_NEWS | The network news system.
1600 FacilitySyslog | LOG\_SYSLOG | Messages generated internally by syslogd.
1601 FacilityUser | LOG\_USER | Messages generated by user processes. This is the default facility identifier if none is specified.
1602 FacilityUucp | LOG\_UUCP | The UUCP system.
1604 ## TimePeriod <a id="objecttype-timeperiod"></a>
1606 Time periods can be used to specify when hosts/services should be checked or to limit
1607 when notifications should be sent out.
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. Defaults to true.
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. (Do not specify a global 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.