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 "my-comment" {
297 host_name = "localhost"
298 author = "icingaadmin"
299 text = "This is a comment."
300 entry_time = 1234567890
304 Configuration Attributes:
306 Name | Type | Description
307 --------------------------|-----------------------|----------------------------------
308 host\_name | Object name | **Required.** The name of the host this comment belongs to.
309 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.
310 author | String | **Required.** The author's name.
311 text | String | **Required.** The comment text.
312 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this comment was added. If omitted, the entry time is volatile!
313 entry\_type | Number | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
314 expire\_time | Timestamp | **Optional.** The comment's expire time as UNIX timestamp.
315 persistent | Boolean | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
317 ## CompatLogger <a id="objecttype-compatlogger"></a>
319 Writes log files in a format that's compatible with Icinga 1.x.
320 This configuration object is available as [compatlog feature](14-features.md#compat-logging).
325 object CompatLogger "compatlog" {
326 log_dir = "/var/log/icinga2/compat"
327 rotation_method = "DAILY"
331 Configuration Attributes:
333 Name | Type | Description
334 --------------------------|-----------------------|----------------------------------
335 log\_dir | String | **Optional.** Path to the compat log directory. Defaults to LogDir + "/compat".
336 rotation\_method | String | **Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
339 ## Dependency <a id="objecttype-dependency"></a>
341 Dependency objects are used to specify dependencies between hosts and services. Dependencies
342 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
347 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
348 > to just create a `Dependency` template and use the `apply` keyword to assign the
349 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
350 > type for `Host` or `Service`.
351 > Check the [dependencies](03-monitoring-basics.md#dependencies) chapter for detailed examples.
353 Service-to-Service Example:
356 object Dependency "webserver-internet" {
357 parent_host_name = "internet"
358 parent_service_name = "ping4"
360 child_host_name = "webserver"
361 child_service_name = "ping4"
363 states = [ OK, Warning ]
365 disable_checks = true
369 Host-to-Host Example:
372 object Dependency "webserver-internet" {
373 parent_host_name = "internet"
375 child_host_name = "webserver"
379 disable_checks = true
383 Configuration Attributes:
385 Name | Type | Description
386 --------------------------|-----------------------|----------------------------------
387 parent\_host\_name | Object name | **Required.** The parent host.
388 parent\_service\_name | Object name | **Optional.** The parent service. If omitted, this dependency object is treated as host dependency.
389 child\_host\_name | Object name | **Required.** The child host.
390 child\_service\_name | Object name | **Optional.** The child service. If omitted, this dependency object is treated as host dependency.
391 disable\_checks | Boolean | **Optional.** Whether to disable checks when this dependency fails. Defaults to false.
392 disable\_notifications | Boolean | **Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
393 ignore\_soft\_states | Boolean | **Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
394 period | Object name | **Optional.** Time period object during which this dependency is enabled.
395 states | Array | **Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
397 Available state filters:
406 When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
407 automatically determined by Icinga 2.
409 Service-to-Host Dependency Example:
412 apply Dependency "internet" to Service {
413 parent_host_name = "dsl-router"
414 disable_checks = true
416 assign where host.name != "dsl-router"
420 This example sets all service objects matching the assign condition into a dependency relation to
421 the parent host object `dsl-router` as implicit child services.
423 Service-to-Service-on-the-same-Host Dependency Example:
426 apply Dependency "disable-agent-checks" to Service {
427 parent_service_name = "agent-health"
429 assign where service.check_command == "ssh"
430 ignore where service.name == "agent-health"
434 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
435 host object matched by the apply rule condition. All services where apply matches are made implicit child services
436 in this dependency relation.
439 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
440 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
441 `child_service_name` attributes has a different value.
443 ## Downtime <a id="objecttype-downtime"></a>
445 Downtimes created at runtime are represented as objects.
446 You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action.
451 object Downtime "my-downtime" {
452 host_name = "localhost"
453 author = "icingaadmin"
454 comment = "This is a downtime."
455 start_time = 1505312869
456 end_time = 1505312924
460 Configuration Attributes:
462 Name | Type | Description
463 --------------------------|-----------------------|----------------------------------
464 host\_name | Object name | **Required.** The name of the host this comment belongs to.
465 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.
466 author | String | **Required.** The author's name.
467 comment | String | **Required.** The comment text.
468 start\_time | Timestamp | **Required.** The start time as UNIX timestamp.
469 end\_time | Timestamp | **Required.** The end time as UNIX timestamp.
470 duration | Number | **Optional.** The duration as number.
471 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this downtime was added.
472 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).
473 triggers | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime.
477 Name | Type | Description
478 --------------------------|-----------------------|----------------------------------
479 trigger\_time | Timestamp | The UNIX timestamp when this downtime was triggered.
480 triggered\_by | Object name | The name of the downtime this downtime was triggered by.
483 ## ElasticsearchWriter <a id="objecttype-elasticsearchwriter"></a>
485 Writes check result metrics and performance data to an Elasticsearch instance.
486 This configuration object is available as [elasticsearch feature](14-features.md#elasticsearch-writer).
491 object ElasticsearchWriter "elasticsearch" {
496 enable_send_perfdata = true
498 flush_threshold = 1024
503 The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
505 Configuration Attributes:
507 Name | Type | Description
508 --------------------------|-----------------------|----------------------------------
509 host | String | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
510 port | Number | **Required.** Elasticsearch port. Defaults to `9200`.
511 index | String | **Required.** Elasticsearch index name. Defaults to `icinga2`.
512 enable\_send\_perfdata | Boolean | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
513 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to Elasticsearch. Defaults to `10s`.
514 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to `1024`.
515 username | String | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
516 password | String | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
517 enable\_tls | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
518 ca\_path | String | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
519 cert\_path | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
520 key\_path | String | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
521 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`.
523 Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
524 Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
526 Basic auth is supported with the `username` and `password` attributes. This requires an
527 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/)
530 TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
531 you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
533 ## Endpoint <a id="objecttype-endpoint"></a>
535 Endpoint objects are used to specify connection information for remote
536 Icinga 2 instances. More details can be found in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
541 object Endpoint "icinga2-client1.localdomain" {
542 host = "192.168.56.111"
548 Example (disable replay log):
551 object Endpoint "icinga2-client1.localdomain" {
552 host = "192.168.5.111"
558 Configuration Attributes:
560 Name | Type | Description
561 --------------------------|-----------------------|----------------------------------
562 host | String | **Optional.** The hostname/IP address of the remote Icinga 2 instance.
563 port | Number | **Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
564 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.
566 Endpoint objects cannot currently be created with the API.
568 ## EventCommand <a id="objecttype-eventcommand"></a>
570 An event command definition.
575 object EventCommand "restart-httpd-event" {
576 command = "/opt/bin/restart-httpd.sh"
581 Configuration Attributes:
583 Name | Type | Description
584 --------------------------|-----------------------|----------------------------------
585 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.
586 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
587 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
588 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
589 arguments | Dictionary | **Optional.** A dictionary of command arguments.
591 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
593 More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
595 ## ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
597 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
598 This configuration object is available as [command feature](14-features.md#external-commands).
603 object ExternalCommandListener "command" {
604 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
608 Configuration Attributes:
610 Name | Type | Description
611 --------------------------|-----------------------|----------------------------------
612 command\_path | String | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
616 ## FileLogger <a id="objecttype-filelogger"></a>
618 Specifies Icinga 2 logging to a file.
619 This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging).
624 object FileLogger "debug-file" {
626 path = "/var/log/icinga2/debug.log"
630 Configuration Attributes:
632 Name | Type | Description
633 --------------------------|-----------------------|----------------------------------
634 path | String | **Required.** The log path.
635 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
638 ## GelfWriter <a id="objecttype-gelfwriter"></a>
640 Writes event log entries to a defined GELF receiver host (Graylog, Logstash).
641 This configuration object is available as [gelf feature](14-features.md#gelfwriter).
646 object GelfWriter "gelf" {
652 Configuration Attributes:
654 Name | Type | Description
655 --------------------------|-----------------------|----------------------------------
656 host | String | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`.
657 port | Number | **Optional.** GELF receiver port. Defaults to `12201`.
658 source | String | **Optional.** Source name for this instance. Defaults to `icinga2`.
659 enable\_send\_perfdata | Boolean | **Optional.** Enable performance data for 'CHECK RESULT' events.
660 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`.
663 ## GraphiteWriter <a id="objecttype-graphitewriter"></a>
665 Writes check result metrics and performance data to a defined
666 Graphite Carbon host.
667 This configuration object is available as [graphite feature](14-features.md#graphite-carbon-cache-writer).
672 object GraphiteWriter "graphite" {
678 Configuration Attributes:
680 Name | Type | Description
681 --------------------------|-----------------------|----------------------------------
682 host | String | **Optional.** Graphite Carbon host address. Defaults to `127.0.0.1`.
683 port | Number | **Optional.** Graphite Carbon port. Defaults to `2003`.
684 host\_name\_template | String | **Optional.** Metric prefix for host name. Defaults to `icinga2.$host.name$.host.$host.check_command$`.
685 service\_name\_template | String | **Optional.** Metric prefix for service name. Defaults to `icinga2.$host.name$.services.$service.name$.$service.check_command$`.
686 enable\_send\_thresholds | Boolean | **Optional.** Send additional threshold metrics. Defaults to `false`.
687 enable\_send\_metadata | Boolean | **Optional.** Send additional metadata metrics. Defaults to `false`.
688 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`.
690 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
694 ## Host <a id="objecttype-host"></a>
701 object Host "icinga2-client1.localdomain" {
702 display_name = "Linux Client 1"
703 address = "192.168.56.111"
704 address6 = "2a00:1450:4001:815::2003"
706 groups = [ "linux-servers" ]
708 check_command = "hostalive"
712 Configuration Attributes:
714 Name | Type | Description
715 --------------------------|-----------------------|----------------------------------
716 display\_name | String | **Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
717 address | String | **Optional.** The host's IPv4 address. Available as command runtime macro `$address$` if set.
718 address6 | String | **Optional.** The host's IPv6 address. Available as command runtime macro `$address6$` if set.
719 groups | Array of object names | **Optional.** A list of host groups this host belongs to.
720 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this host.
721 check\_command | Object name | **Required.** The name of the check command.
722 max\_check\_attempts | Number | **Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
723 check\_period | Object name | **Optional.** The name of a time period which determines when this host should be checked. Not set by default.
724 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
725 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`.
726 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`. Note: This does not affect the scheduling [after a passive check result](08-advanced-topics.md#check-result-freshness).
727 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to true.
728 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to true.
729 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to true.
730 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to true.
731 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to false.
732 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to true.
733 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.
734 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a host to be considered flapping. Default `30.0`
735 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a host to be considered not flapping. Default `25.0`
736 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
737 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.
738 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
739 notes | String | **Optional.** Notes for the host.
740 notes\_url | String | **Optional.** URL for notes for the host (for example, in notification commands).
741 action\_url | String | **Optional.** URL for actions for the host (for example, an external graphing tool).
742 icon\_image | String | **Optional.** Icon image for the host. Used by external interfaces only.
743 icon\_image\_alt | String | **Optional.** Icon image description for the host. Used by external interface only.
745 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
746 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
750 > The `address` and `address6` attributes are required for running commands using
751 > the `$address$` and `$address6$` runtime macros.
755 Name | Type | Description
756 --------------------------|-----------------------|----------------------------------
757 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
758 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
759 check\_attempt | Number | The current check attempt number.
760 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
761 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
762 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
763 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
764 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
765 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
766 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
767 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
768 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
769 downtime\_depth | Number | Whether the host has one or more active downtimes.
770 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
771 flapping | Boolean | Whether the host is flapping between states.
772 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
773 state | Number | The current state (0 = UP, 1 = DOWN).
774 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
775 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
776 last\_state\_up | Timestamp | When the last UP state occurred (as a UNIX timestamp).
777 last\_state\_down | Timestamp | When the last DOWN state occurred (as a UNIX timestamp).
781 ## HostGroup <a id="objecttype-hostgroup"></a>
787 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
792 object HostGroup "linux-servers" {
793 display_name = "Linux Servers"
795 assign where host.vars.os == "Linux"
799 Configuration Attributes:
801 Name | Type | Description
802 --------------------------|-----------------------|----------------------------------
803 display\_name | String | **Optional.** A short description of the host group.
804 groups | Array of object names | **Optional.** An array of nested group names.
806 ## IcingaApplication <a id="objecttype-icingaapplication"></a>
808 The IcingaApplication object is required to start Icinga 2.
809 The object name must be `app`. If the object configuration
810 is missing, Icinga 2 will automatically create an IcingaApplication
816 object IcingaApplication "app" {
817 enable_perfdata = false
821 Configuration Attributes:
823 Name | Type | Description
824 --------------------------|-----------------------|----------------------------------
825 enable\_notifications | Boolean | **Optional.** Whether notifications are globally enabled. Defaults to true.
826 enable\_event\_handlers | Boolean | **Optional.** Whether event handlers are globally enabled. Defaults to true.
827 enable\_flapping | Boolean | **Optional.** Whether flap detection is globally enabled. Defaults to true.
828 enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true.
829 enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true.
830 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true.
831 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally.
832 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.
834 ## IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
836 IDO database adapter for MySQL.
837 This configuration object is available as [ido-mysql feature](14-features.md#db-ido).
842 object IdoMysqlConnection "mysql-ido" {
850 downtimehistory_age = 48h
851 contactnotifications_age = 31d
856 Configuration Attributes:
858 Name | Type | Description
859 --------------------------|-----------------------|----------------------------------
860 host | String | **Optional.** MySQL database host address. Defaults to `localhost`.
861 port | Number | **Optional.** MySQL database port. Defaults to `3306`.
862 socket\_path | String | **Optional.** MySQL socket path.
863 user | String | **Optional.** MySQL database user with read/write permission to the icinga database. Defaults to `icinga`.
864 password | String | **Optional.** MySQL database user's password. Defaults to `icinga`.
865 database | String | **Optional.** MySQL database name. Defaults to `icinga`.
866 enable\_ssl | Boolean | **Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
867 ssl\_key | String | **Optional.** MySQL SSL client key file path.
868 ssl\_cert | String | **Optional.** MySQL SSL certificate file path.
869 ssl\_ca | String | **Optional.** MySQL SSL certificate authority certificate file path.
870 ssl\_capath | String | **Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
871 ssl\_cipher | String | **Optional.** MySQL SSL list of allowed ciphers.
872 table\_prefix | String | **Optional.** MySQL database table prefix. Defaults to `icinga_`.
873 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
874 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
875 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`.
876 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`.
877 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
878 categories | Array | **Optional.** Array of information types that should be written to the database.
882 Name | Type | Description
883 --------------------------------|-----------------------|----------------------------------
884 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
885 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
886 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
887 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
888 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
889 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
890 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
891 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
892 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
893 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
894 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
895 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
896 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
897 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
898 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
902 Name | Description | Required by
903 ---------------------|------------------------|--------------------
904 DbCatConfig | Configuration data | Icinga Web 2
905 DbCatState | Current state data | Icinga Web 2
906 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
907 DbCatComment | Comments | Icinga Web 2
908 DbCatDowntime | Downtimes | Icinga Web 2
909 DbCatEventHandler | Event handler data | Icinga Web 2
910 DbCatExternalCommand | External commands | --
911 DbCatFlapping | Flap detection data | Icinga Web 2
912 DbCatCheck | Check results | --
913 DbCatLog | Log messages | --
914 DbCatNotification | Notifications | Icinga Web 2
915 DbCatProgramStatus | Program status data | Icinga Web 2
916 DbCatRetention | Retention data | Icinga Web 2
917 DbCatStateHistory | Historical state data | Icinga Web 2
919 The default value for `categories` includes everything required
920 by Icinga Web 2 in the table above.
922 In addition to the category flags listed above the `DbCatEverything`
923 flag may be used as a shortcut for listing all flags.
925 ## IdoPgsqlConnection <a id="objecttype-idopgsqlconnection"></a>
927 IDO database adapter for PostgreSQL.
928 This configuration object is available as [ido-pgsql feature](14-features.md#db-ido).
933 object IdoPgsqlConnection "pgsql-ido" {
941 downtimehistory_age = 48h
942 contactnotifications_age = 31d
947 Configuration Attributes:
949 Name | Type | Description
950 --------------------------|-----------------------|----------------------------------
951 host | String | **Optional.** PostgreSQL database host address. Defaults to `localhost`.
952 port | Number | **Optional.** PostgreSQL database port. Defaults to `5432`.
953 user | String | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`.
954 password | String | **Optional.** PostgreSQL database user's password. Defaults to `icinga`.
955 database | String | **Optional.** PostgreSQL database name. Defaults to `icinga`.
956 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`.
957 ssl\_key | String | **Optional.** PostgreSQL SSL client key file path.
958 ssl\_cert | String | **Optional.** PostgreSQL SSL certificate file path.
959 ssl\_ca | String | **Optional.** PostgreSQL SSL certificate authority certificate file path.
960 table\_prefix | String | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`.
961 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
962 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
963 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".
964 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`.
965 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
966 categories | Array | **Optional.** Array of information types that should be written to the database.
970 Name | Type | Description
971 --------------------------------|-----------------------|----------------------------------
972 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
973 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
974 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
975 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
976 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
977 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
978 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
979 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
980 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
981 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
982 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
983 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
984 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
985 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
986 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
990 Name | Description | Required by
991 ---------------------|------------------------|--------------------
992 DbCatConfig | Configuration data | Icinga Web 2
993 DbCatState | Current state data | Icinga Web 2
994 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
995 DbCatComment | Comments | Icinga Web 2
996 DbCatDowntime | Downtimes | Icinga Web 2
997 DbCatEventHandler | Event handler data | Icinga Web 2
998 DbCatExternalCommand | External commands | --
999 DbCatFlapping | Flap detection data | Icinga Web 2
1000 DbCatCheck | Check results | --
1001 DbCatLog | Log messages | --
1002 DbCatNotification | Notifications | Icinga Web 2
1003 DbCatProgramStatus | Program status data | Icinga Web 2
1004 DbCatRetention | Retention data | Icinga Web 2
1005 DbCatStateHistory | Historical state data | Icinga Web 2
1007 The default value for `categories` includes everything required
1008 by Icinga Web 2 in the table above.
1010 In addition to the category flags listed above the `DbCatEverything`
1011 flag may be used as a shortcut for listing all flags.
1013 ## InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
1015 Writes check result metrics and performance data to a defined InfluxDB host.
1016 This configuration object is available as [influxdb feature](14-features.md#influxdb-writer).
1021 object InfluxdbWriter "influxdb" {
1024 database = "icinga2"
1026 flush_threshold = 1024
1027 flush_interval = 10s
1030 measurement = "$host.check_command$"
1032 hostname = "$host.name$"
1035 service_template = {
1036 measurement = "$service.check_command$"
1038 hostname = "$host.name$"
1039 service = "$service.name$"
1045 Configuration Attributes:
1047 Name | Type | Description
1048 --------------------------|-----------------------|----------------------------------
1049 host | String | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
1050 port | Number | **Required.** InfluxDB HTTP port. Defaults to `8086`.
1051 database | String | **Required.** InfluxDB database name. Defaults to `icinga2`.
1052 username | String | **Optional.** InfluxDB user name. Defaults to `none`.
1053 password | String | **Optional.** InfluxDB user password. Defaults to `none`.
1054 ssl\_enable | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`.
1055 ssl\_ca\_cert | String | **Optional.** Path to CA certificate to validate the remote host.
1056 ssl\_cert | String | **Optional.** Path to host certificate to present to the remote host for mutual verification.
1057 ssl\_key | String | **Optional.** Path to host key to accompany the ssl\_cert.
1058 host\_template | String | **Required.** Host template to define the InfluxDB line protocol.
1059 service\_template | String | **Required.** Service template to define the influxDB line protocol.
1060 enable\_send\_thresholds | Boolean | **Optional.** Whether to send warn, crit, min & max tagged data.
1061 enable\_send\_metadata | Boolean | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
1062 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to InfluxDB. Defaults to `10s`.
1063 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`.
1064 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`.
1066 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
1067 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
1072 ## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
1074 Livestatus API interface available as TCP or UNIX socket. Historical table queries
1075 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
1076 pointing to the log files using the `compat_log_path` configuration attribute.
1077 This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus).
1082 object LivestatusListener "livestatus-tcp" {
1084 bind_host = "127.0.0.1"
1088 object LivestatusListener "livestatus-unix" {
1089 socket_type = "unix"
1090 socket_path = "/var/run/icinga2/cmd/livestatus"
1094 Configuration Attributes:
1096 Name | Type | Description
1097 --------------------------|-----------------------|----------------------------------
1098 socket\_type | String | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`.
1099 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`.
1100 bind\_port | Number | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`.
1101 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".
1102 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"
1106 > UNIX sockets are not supported on Windows.
1109 ## Notification <a id="objecttype-notification"></a>
1111 Notification objects are used to specify how users should be notified in case
1112 of host and service state changes and other events.
1116 > Rather than creating a `Notification` object for a specific host or service it is
1117 > usually easier to just create a `Notification` template and use the `apply` keyword
1118 > to assign the notification to a number of hosts or services. Use the `to` keyword
1119 > to set the specific target type for `Host` or `Service`.
1120 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
1125 object Notification "localhost-ping-notification" {
1126 host_name = "localhost"
1127 service_name = "ping4"
1129 command = "mail-notification"
1131 users = [ "user1", "user2" ] // reference to User objects
1133 types = [ Problem, Recovery ]
1134 states = [ Critical, Warning, OK ]
1138 Configuration Attributes:
1140 Name | Type | Description
1141 --------------------------|-----------------------|----------------------------------
1142 host\_name | Object name | **Required.** The name of the host this notification belongs to.
1143 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.
1144 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
1145 users | Array of object names | **Required.** A list of user names who should be notified. **Optional.** if the `user_groups` attribute is set.
1146 user\_groups | Array of object names | **Required.** A list of user group names who should be notified. **Optional.** if the `users` attribute is set.
1147 times | Dictionary | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
1148 command | Object name | **Required.** The name of the notification command which should be executed when the notification is triggered.
1149 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.
1150 period | Object name | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
1151 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.
1152 types | Array | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
1153 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!
1155 Available notification state filters for Service:
1162 Available notification state filters for Host:
1167 Available notification type filters:
1181 Name | Type | Description
1182 ----------------------------|-----------------------|-----------------
1183 last\_notification | Timestamp | When the last notification was sent for this Notification object (as a UNIX timestamp).
1184 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).
1185 notification\_number | Number | The notification number.
1186 last\_problem\_notification | Timestamp | When the last notification was sent for a problem (as a UNIX timestamp).
1189 ## NotificationCommand <a id="objecttype-notificationcommand"></a>
1191 A notification command definition.
1196 object NotificationCommand "mail-service-notification" {
1197 command = [ ConfigDir + "/scripts/mail-service-notification.sh" ]
1202 value = "$notification_address$"
1204 "-6" = "$notification_address6$"
1205 "-b" = "$notification_author$"
1206 "-c" = "$notification_comment$"
1209 value = "$notification_date$"
1213 value = "$notification_servicename$"
1216 value = "$notification_from$"
1217 description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
1219 "-i" = "$notification_icingaweb2url$"
1222 value = "$notification_hostname$"
1226 value = "$notification_hostdisplayname$"
1230 value = "$notification_serviceoutput$"
1234 value = "$notification_useremail$"
1238 value = "$notification_servicestate$"
1242 value = "$notification_type$"
1246 value = "$notification_servicedisplayname$"
1248 "-v" = "$notification_logtosyslog$"
1252 notification_address = "$address$"
1253 notification_address6 = "$address6$"
1254 notification_author = "$notification.author$"
1255 notification_comment = "$notification.comment$"
1256 notification_type = "$notification.type$"
1257 notification_date = "$icinga.long_date_time$"
1258 notification_hostname = "$host.name$"
1259 notification_hostdisplayname = "$host.display_name$"
1260 notification_servicename = "$service.name$"
1261 notification_serviceoutput = "$service.output$"
1262 notification_servicestate = "$service.state$"
1263 notification_useremail = "$user.email$"
1264 notification_servicedisplayname = "$service.display_name$"
1269 Configuration Attributes:
1271 Name | Type | Description
1272 --------------------------|-----------------------|----------------------------------
1273 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.
1274 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1275 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
1276 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
1277 arguments | Dictionary | **Optional.** A dictionary of command arguments.
1279 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
1281 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
1283 ## NotificationComponent <a id="objecttype-notificationcomponent"></a>
1285 The notification component is responsible for sending notifications.
1286 This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature).
1291 object NotificationComponent "notification" { }
1294 Configuration Attributes:
1296 Name | Type | Description
1297 --------------------------|-----------------------|----------------------------------
1298 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".
1300 ## OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1302 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1303 This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer).
1308 object OpenTsdbWriter "opentsdb" {
1314 Configuration Attributes:
1316 Name | Type | Description
1317 --------------------------|-----------------------|----------------------------------
1318 host | String | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`.
1319 port | Number | **Optional.** OpenTSDB port. Defaults to `4242`.
1320 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`.
1323 ## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1325 Writes check result performance data to a defined path using macro
1326 pattern consisting of custom attributes and runtime macros.
1327 This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files).
1332 object PerfdataWriter "perfdata" {
1333 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1335 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1337 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$"
1338 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$"
1340 rotation_interval = 15s
1344 Configuration Attributes:
1346 Name | Type | Description
1347 --------------------------|-----------------------|----------------------------------
1348 host\_perfdata\_path | String | **Optional.** Path to the host performance data file. Defaults to SpoolDir + "/perfdata/host-perfdata".
1349 service\_perfdata\_path | String | **Optional.** Path to the service performance data file. Defaults to SpoolDir + "/perfdata/service-perfdata".
1350 host\_temp\_path | String | **Optional.** Path to the temporary host file. Defaults to SpoolDir + "/tmp/host-perfdata".
1351 service\_temp\_path | String | **Optional.** Path to the temporary service file. Defaults to SpoolDir + "/tmp/service-perfdata".
1352 host\_format\_template | String | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1353 service\_format\_template | String | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1354 rotation\_interval | Duration | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`.
1355 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`.
1357 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1358 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1361 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
1363 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1367 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1368 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1369 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1370 > type for `Host` or `Service`.
1371 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
1376 object ScheduledDowntime "some-downtime" {
1377 host_name = "localhost"
1378 service_name = "ping4"
1380 author = "icingaadmin"
1381 comment = "Some comment"
1387 "sunday" = "02:00-03:00"
1392 Configuration Attributes:
1394 Name | Type | Description
1395 --------------------------|-----------------------|----------------------------------
1396 host\_name | Object name | **Required.** The name of the host this scheduled downtime belongs to.
1397 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.
1398 author | String | **Required.** The author of the downtime.
1399 comment | String | **Required.** A comment for the downtime.
1400 fixed | Boolean | **Optional.** Whether this is a fixed downtime. Defaults to `true`.
1401 duration | Duration | **Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1402 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1403 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`.
1405 ScheduledDowntime objects have composite names, i.e. their names are based
1406 on the `host_name` and `service_name` attributes and the
1407 name you specified. This means you can define more than one object
1408 with the same (short) name as long as one of the `host_name` and
1409 `service_name` attributes has a different value.
1412 ## Service <a id="objecttype-service"></a>
1414 Service objects describe network services and how they should be checked
1419 > Rather than creating a `Service` object for a specific host it is usually easier
1420 > to just create a `Service` template and use the `apply` keyword to assign the
1421 > service to a number of hosts.
1422 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
1427 object Service "uptime" {
1428 host_name = "localhost"
1430 display_name = "localhost Uptime"
1432 check_command = "snmp"
1434 vars.snmp_community = "public"
1435 vars.snmp_oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1437 check_interval = 60s
1438 retry_interval = 15s
1440 groups = [ "all-services", "snmp" ]
1444 Configuration Attributes:
1446 Name | Type | Description
1447 --------------------------|-----------------------|----------------------------------
1448 display\_name | String | **Optional.** A short description of the service.
1449 host\_name | Object name | **Required.** The host this service belongs to. There must be a `Host` object with that name.
1450 groups | Array of object names | **Optional.** The service groups this service belongs to.
1451 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this service.
1452 check\_command | Object name | **Required.** The name of the check command.
1453 max\_check\_attempts | Number | **Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1454 check\_period | Object name | **Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1455 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
1456 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`.
1457 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`. Note: This does not affect the scheduling [after a passive check result](08-advanced-topics.md#check-result-freshness).
1458 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to `true`.
1459 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to `true`.
1460 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to `true`.
1461 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to `true`.
1462 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to `false`.
1463 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a service to be considered flapping. `30.0`
1464 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a service to be considered not flapping. `25.0`
1465 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to `true`.
1466 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.
1467 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
1468 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.
1469 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.
1470 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
1471 notes | String | **Optional.** Notes for the service.
1472 notes\_url | String | **Optional.** URL for notes for the service (for example, in notification commands).
1473 action\_url | String | **Optional.** URL for actions for the service (for example, an external graphing tool).
1474 icon\_image | String | **Optional.** Icon image for the service. Used by external interfaces only.
1475 icon\_image\_alt | String | **Optional.** Icon image description for the service. Used by external interface only.
1477 Service objects have composite names, i.e. their names are based on the host\_name attribute and the name you specified. This means
1478 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1480 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
1481 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
1485 Name | Type | Description
1486 --------------------------|-----------------------|----------------------------------
1487 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
1488 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
1489 check\_attempt | Number | The current check attempt number.
1490 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1491 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1492 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1493 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
1494 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
1495 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
1496 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1497 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1498 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1499 downtime\_depth | Number | Whether the service has one or more active downtimes.
1500 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
1501 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
1502 flapping | Boolean | Whether the host is flapping between states.
1503 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1504 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1505 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1506 last\_state\_ok | Timestamp | When the last OK state occurred (as a UNIX timestamp).
1507 last\_state\_warning | Timestamp | When the last WARNING state occurred (as a UNIX timestamp).
1508 last\_state\_critical | Timestamp | When the last CRITICAL state occurred (as a UNIX timestamp).
1509 last\_state\_unknown | Timestamp | When the last UNKNOWN state occurred (as a UNIX timestamp).
1512 ## ServiceGroup <a id="objecttype-servicegroup"></a>
1514 A group of services.
1518 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
1523 object ServiceGroup "snmp" {
1524 display_name = "SNMP services"
1528 Configuration Attributes:
1530 Name | Type | Description
1531 --------------------------|-----------------------|----------------------------------
1532 display\_name | String | **Optional.** A short description of the service group.
1533 groups | Array of object names | **Optional.** An array of nested group names.
1536 ## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1538 Periodically writes status and configuration data files which are used by third-party tools.
1539 This configuration object is available as [statusdata feature](14-features.md#status-data).
1544 object StatusDataWriter "status" {
1545 status_path = "/var/cache/icinga2/status.dat"
1546 objects_path = "/var/cache/icinga2/objects.cache"
1547 update_interval = 30s
1551 Configuration Attributes:
1553 Name | Type | Description
1554 --------------------------|-----------------------|----------------------------------
1555 status\_path | String | **Optional.** Path to the `status.dat` file. Defaults to CacheDir + "/status.dat".
1556 objects\_path | String | **Optional.** Path to the `objects.cache` file. Defaults to CacheDir + "/objects.cache".
1557 update\_interval | Duration | **Optional.** The interval in which the status files are updated. Defaults to `15s`.
1560 ## SyslogLogger <a id="objecttype-sysloglogger"></a>
1562 Specifies Icinga 2 logging to syslog.
1563 This configuration object is available as `syslog` [logging feature](14-features.md#logging).
1568 object SyslogLogger "syslog" {
1569 severity = "warning"
1573 Configuration Attributes:
1575 Name | Type | Description
1576 --------------------------|-----------------------|----------------------------------
1577 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1578 facility | String | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`.
1582 Name | Facility | Description
1583 ---------------------|---------------|----------------
1584 FacilityAuth | LOG\_AUTH | The authorization system.
1585 FacilityAuthPriv | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals.
1586 FacilityCron | LOG\_CRON | The cron daemon.
1587 FacilityDaemon | LOG\_DAEMON | System daemons that are not provided for explicitly by other facilities.
1588 FacilityFtp | LOG\_FTP | The file transfer protocol daemons.
1589 FacilityKern | LOG\_KERN | Messages generated by the kernel. These cannot be generated by any user processes.
1590 FacilityLocal0 | LOG\_LOCAL0 | Reserved for local use.
1591 FacilityLocal1 | LOG\_LOCAL1 | Reserved for local use.
1592 FacilityLocal2 | LOG\_LOCAL2 | Reserved for local use.
1593 FacilityLocal3 | LOG\_LOCAL3 | Reserved for local use.
1594 FacilityLocal4 | LOG\_LOCAL4 | Reserved for local use.
1595 FacilityLocal5 | LOG\_LOCAL5 | Reserved for local use.
1596 FacilityLocal6 | LOG\_LOCAL6 | Reserved for local use.
1597 FacilityLocal7 | LOG\_LOCAL7 | Reserved for local use.
1598 FacilityLpr | LOG\_LPR | The line printer spooling system.
1599 FacilityMail | LOG\_MAIL | The mail system.
1600 FacilityNews | LOG\_NEWS | The network news system.
1601 FacilitySyslog | LOG\_SYSLOG | Messages generated internally by syslogd.
1602 FacilityUser | LOG\_USER | Messages generated by user processes. This is the default facility identifier if none is specified.
1603 FacilityUucp | LOG\_UUCP | The UUCP system.
1605 ## TimePeriod <a id="objecttype-timeperiod"></a>
1607 Time periods can be used to specify when hosts/services should be checked or to limit
1608 when notifications should be sent out.
1613 object TimePeriod "nonworkhours" {
1614 display_name = "Icinga 2 TimePeriod for non working hours"
1617 monday = "00:00-8:00,17:00-24:00"
1618 tuesday = "00:00-8:00,17:00-24:00"
1619 wednesday = "00:00-8:00,17:00-24:00"
1620 thursday = "00:00-8:00,17:00-24:00"
1621 friday = "00:00-8:00,16:00-24:00"
1622 saturday = "00:00-24:00"
1623 sunday = "00:00-24:00"
1627 object TimePeriod "exampledays" {
1628 display_name = "Icinga 2 TimePeriod for random example days"
1631 //We still believe in Santa, no peeking!
1632 //Applies every 25th of December every year
1633 "december 25" = "00:00-24:00"
1635 //Any point in time can be specified,
1636 //but you still have to use a range
1637 "2038-01-19" = "03:13-03:15"
1639 //Evey 3rd day from the second monday of February
1640 //to 8th of November
1641 "monday 2 february - november 8 / 3" = "00:00-24:00"
1646 Additional examples can be found [here](08-advanced-topics.md#timeperiods).
1648 Configuration Attributes:
1650 Name | Type | Description
1651 --------------------------|-----------------------|----------------------------------
1652 display\_name | String | **Optional.** A short description of the time period.
1653 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1654 prefer\_includes | Boolean | **Optional.** Whether to prefer timeperiods `includes` or `excludes`. Default to true.
1655 excludes | Array of object names | **Optional.** An array of timeperiods, which should exclude from your timerange.
1656 includes | Array of object names | **Optional.** An array of timeperiods, which should include into your timerange
1661 Name | Type | Description
1662 --------------------------|-----------------------|----------------------------------
1663 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1666 ## User <a id="objecttype-user"></a>
1673 object User "icingaadmin" {
1674 display_name = "Icinga 2 Admin"
1675 groups = [ "icingaadmins" ]
1676 email = "icinga@localhost"
1677 pager = "icingaadmin@localhost.localdomain"
1681 states = [ OK, Warning, Critical, Unknown ]
1682 types = [ Problem, Recovery ]
1684 vars.additional_notes = "This is the Icinga 2 Admin account."
1688 Available notification state filters:
1697 Available notification type filters:
1709 Configuration Attributes:
1711 Name | Type | Description
1712 --------------------------|-----------------------|----------------------------------
1713 display\_name | String | **Optional.** A short description of the user.
1714 email | String | **Optional.** An email string for this user. Useful for notification commands.
1715 pager | String | **Optional.** A pager string for this user. Useful for notification commands.
1716 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this user.
1717 groups | Array of object names | **Optional.** An array of group names.
1718 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled for this user. Defaults to true.
1719 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.
1720 types | Array | **Optional.** A set of type filters when a notification for this user should be triggered. By default everything is matched.
1721 states | Array | **Optional.** A set of state filters when a notification for this should be triggered. By default everything is matched.
1725 Name | Type | Description
1726 --------------------------|-----------------------|----------------------------------
1727 last\_notification | Timestamp | When the last notification was sent for this user (as a UNIX timestamp).
1729 ## UserGroup <a id="objecttype-usergroup"></a>
1735 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
1740 object UserGroup "icingaadmins" {
1741 display_name = "Icinga 2 Admin Group"
1745 Configuration Attributes:
1747 Name | Type | Description
1748 --------------------------|-----------------------|----------------------------------
1749 display\_name | String | **Optional.** A short description of the user group.
1750 groups | Array of object names | **Optional.** An array of nested group names.
1753 ## Zone <a id="objecttype-zone"></a>
1755 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1756 Please read the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring) for additional details.
1760 object Zone "master" {
1761 endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]
1765 object Zone "satellite" {
1766 endpoints = [ "icinga2-satellite1.localdomain" ]
1771 Configuration Attributes:
1773 Name | Type | Description
1774 --------------------------|-----------------------|----------------------------------
1775 endpoints | Array of object names | **Optional.** Array of endpoint names located in this zone.
1776 parent | Object name | **Optional.** The name of the parent zone. (Do not specify a global zone)
1777 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`.
1779 Zone objects cannot currently be created with the API.