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:
408 When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
409 automatically determined by Icinga 2.
411 Service-to-Host Dependency Example:
414 apply Dependency "internet" to Service {
415 parent_host_name = "dsl-router"
416 disable_checks = true
418 assign where host.name != "dsl-router"
422 This example sets all service objects matching the assign condition into a dependency relation to
423 the parent host object `dsl-router` as implicit child services.
425 Service-to-Service-on-the-same-Host Dependency Example:
428 apply Dependency "disable-agent-checks" to Service {
429 parent_service_name = "agent-health"
431 assign where service.check_command == "ssh"
432 ignore where service.name == "agent-health"
436 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
437 host object matched by the apply rule condition. All services where apply matches are made implicit child services
438 in this dependency relation.
441 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
442 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
443 `child_service_name` attributes has a different value.
445 ## Downtime <a id="objecttype-downtime"></a>
447 Downtimes created at runtime are represented as objects.
448 You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action.
453 object Downtime "my-downtime" {
454 host_name = "localhost"
455 author = "icingaadmin"
456 comment = "This is a downtime."
457 start_time = 1505312869
458 end_time = 1505312924
462 Configuration Attributes:
464 Name | Type | Description
465 --------------------------|-----------------------|----------------------------------
466 host\_name | Object name | **Required.** The name of the host this comment belongs to.
467 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.
468 author | String | **Required.** The author's name.
469 comment | String | **Required.** The comment text.
470 start\_time | Timestamp | **Required.** The start time as UNIX timestamp.
471 end\_time | Timestamp | **Required.** The end time as UNIX timestamp.
472 duration | Number | **Optional.** The duration as number.
473 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this downtime was added.
474 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).
475 triggers | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime.
479 Name | Type | Description
480 --------------------------|-----------------------|----------------------------------
481 trigger\_time | Timestamp | The UNIX timestamp when this downtime was triggered.
482 triggered\_by | Object name | The name of the downtime this downtime was triggered by.
485 ## ElasticsearchWriter <a id="objecttype-elasticsearchwriter"></a>
487 Writes check result metrics and performance data to an Elasticsearch instance.
488 This configuration object is available as [elasticsearch feature](14-features.md#elasticsearch-writer).
493 object ElasticsearchWriter "elasticsearch" {
498 enable_send_perfdata = true
500 flush_threshold = 1024
505 The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
507 Configuration Attributes:
509 Name | Type | Description
510 --------------------------|-----------------------|----------------------------------
511 host | String | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
512 port | Number | **Required.** Elasticsearch port. Defaults to `9200`.
513 index | String | **Required.** Elasticsearch index name. Defaults to `icinga2`.
514 enable\_send\_perfdata | Boolean | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
515 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to Elasticsearch. Defaults to `10s`.
516 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to `1024`.
517 username | String | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
518 password | String | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
519 enable\_tls | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
520 ca\_path | String | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
521 cert\_path | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
522 key\_path | String | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
523 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 `false`.
525 Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
526 Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
528 Basic auth is supported with the `username` and `password` attributes. This requires an
529 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/)
532 TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
533 you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
535 ## Endpoint <a id="objecttype-endpoint"></a>
537 Endpoint objects are used to specify connection information for remote
538 Icinga 2 instances. More details can be found in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
543 object Endpoint "icinga2-client1.localdomain" {
544 host = "192.168.56.111"
550 Example (disable replay log):
553 object Endpoint "icinga2-client1.localdomain" {
554 host = "192.168.5.111"
560 Configuration Attributes:
562 Name | Type | Description
563 --------------------------|-----------------------|----------------------------------
564 host | String | **Optional.** The hostname/IP address of the remote Icinga 2 instance.
565 port | Number | **Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
566 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.
568 Endpoint objects cannot currently be created with the API.
570 ## EventCommand <a id="objecttype-eventcommand"></a>
572 An event command definition.
577 object EventCommand "restart-httpd-event" {
578 command = "/opt/bin/restart-httpd.sh"
583 Configuration Attributes:
585 Name | Type | Description
586 --------------------------|-----------------------|----------------------------------
587 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.
588 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
589 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
590 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
591 arguments | Dictionary | **Optional.** A dictionary of command arguments.
593 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
595 More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
597 ## ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
599 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
600 This configuration object is available as [command feature](14-features.md#external-commands).
605 object ExternalCommandListener "command" {
606 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
610 Configuration Attributes:
612 Name | Type | Description
613 --------------------------|-----------------------|----------------------------------
614 command\_path | String | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
618 ## FileLogger <a id="objecttype-filelogger"></a>
620 Specifies Icinga 2 logging to a file.
621 This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging).
626 object FileLogger "debug-file" {
628 path = "/var/log/icinga2/debug.log"
632 Configuration Attributes:
634 Name | Type | Description
635 --------------------------|-----------------------|----------------------------------
636 path | String | **Required.** The log path.
637 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
640 ## GelfWriter <a id="objecttype-gelfwriter"></a>
642 Writes event log entries to a defined GELF receiver host (Graylog, Logstash).
643 This configuration object is available as [gelf feature](14-features.md#gelfwriter).
648 object GelfWriter "gelf" {
654 Configuration Attributes:
656 Name | Type | Description
657 --------------------------|-----------------------|----------------------------------
658 host | String | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`.
659 port | Number | **Optional.** GELF receiver port. Defaults to `12201`.
660 source | String | **Optional.** Source name for this instance. Defaults to `icinga2`.
661 enable\_send\_perfdata | Boolean | **Optional.** Enable performance data for 'CHECK RESULT' events.
662 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 `false`.
665 ## GraphiteWriter <a id="objecttype-graphitewriter"></a>
667 Writes check result metrics and performance data to a defined
668 Graphite Carbon host.
669 This configuration object is available as [graphite feature](14-features.md#graphite-carbon-cache-writer).
674 object GraphiteWriter "graphite" {
680 Configuration Attributes:
682 Name | Type | Description
683 --------------------------|-----------------------|----------------------------------
684 host | String | **Optional.** Graphite Carbon host address. Defaults to `127.0.0.1`.
685 port | Number | **Optional.** Graphite Carbon port. Defaults to `2003`.
686 host\_name\_template | String | **Optional.** Metric prefix for host name. Defaults to `icinga2.$host.name$.host.$host.check_command$`.
687 service\_name\_template | String | **Optional.** Metric prefix for service name. Defaults to `icinga2.$host.name$.services.$service.name$.$service.check_command$`.
688 enable\_send\_thresholds | Boolean | **Optional.** Send additional threshold metrics. Defaults to `false`.
689 enable\_send\_metadata | Boolean | **Optional.** Send additional metadata metrics. Defaults to `false`.
690 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 `false`.
692 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
696 ## Host <a id="objecttype-host"></a>
703 object Host "icinga2-client1.localdomain" {
704 display_name = "Linux Client 1"
705 address = "192.168.56.111"
706 address6 = "2a00:1450:4001:815::2003"
708 groups = [ "linux-servers" ]
710 check_command = "hostalive"
714 Configuration Attributes:
716 Name | Type | Description
717 --------------------------|-----------------------|----------------------------------
718 display\_name | String | **Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
719 address | String | **Optional.** The host's IPv4 address. Available as command runtime macro `$address$` if set.
720 address6 | String | **Optional.** The host's IPv6 address. Available as command runtime macro `$address6$` if set.
721 groups | Array of object names | **Optional.** A list of host groups this host belongs to.
722 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this host.
723 check\_command | Object name | **Required.** The name of the check command.
724 max\_check\_attempts | Number | **Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
725 check\_period | Object name | **Optional.** The name of a time period which determines when this host should be checked. Not set by default.
726 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
727 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`.
728 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).
729 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to true.
730 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to true.
731 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to true.
732 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to true.
733 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to false.
734 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to true.
735 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.
736 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a host to be considered flapping. Default `30.0`
737 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a host to be considered not flapping. Default `25.0`
738 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
739 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.
740 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
741 notes | String | **Optional.** Notes for the host.
742 notes\_url | String | **Optional.** URL for notes for the host (for example, in notification commands).
743 action\_url | String | **Optional.** URL for actions for the host (for example, an external graphing tool).
744 icon\_image | String | **Optional.** Icon image for the host. Used by external interfaces only.
745 icon\_image\_alt | String | **Optional.** Icon image description for the host. Used by external interface only.
747 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
748 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
752 > The `address` and `address6` attributes are required for running commands using
753 > the `$address$` and `$address6$` runtime macros.
757 Name | Type | Description
758 --------------------------|-----------------------|----------------------------------
759 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
760 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
761 check\_attempt | Number | The current check attempt number.
762 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
763 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
764 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
765 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
766 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
767 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
768 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
769 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
770 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
771 downtime\_depth | Number | Whether the host has one or more active downtimes.
772 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
773 flapping | Boolean | Whether the host is flapping between states.
774 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
775 state | Number | The current state (0 = UP, 1 = DOWN).
776 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
777 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
778 last\_state\_up | Timestamp | When the last UP state occurred (as a UNIX timestamp).
779 last\_state\_down | Timestamp | When the last DOWN state occurred (as a UNIX timestamp).
783 ## HostGroup <a id="objecttype-hostgroup"></a>
789 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
794 object HostGroup "linux-servers" {
795 display_name = "Linux Servers"
797 assign where host.vars.os == "Linux"
801 Configuration Attributes:
803 Name | Type | Description
804 --------------------------|-----------------------|----------------------------------
805 display\_name | String | **Optional.** A short description of the host group.
806 groups | Array of object names | **Optional.** An array of nested group names.
808 ## IcingaApplication <a id="objecttype-icingaapplication"></a>
810 The IcingaApplication object is required to start Icinga 2.
811 The object name must be `app`. If the object configuration
812 is missing, Icinga 2 will automatically create an IcingaApplication
818 object IcingaApplication "app" {
819 enable_perfdata = false
823 Configuration Attributes:
825 Name | Type | Description
826 --------------------------|-----------------------|----------------------------------
827 enable\_notifications | Boolean | **Optional.** Whether notifications are globally enabled. Defaults to true.
828 enable\_event\_handlers | Boolean | **Optional.** Whether event handlers are globally enabled. Defaults to true.
829 enable\_flapping | Boolean | **Optional.** Whether flap detection is globally enabled. Defaults to true.
830 enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true.
831 enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true.
832 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true.
833 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally.
834 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.
836 ## IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
838 IDO database adapter for MySQL.
839 This configuration object is available as [ido-mysql feature](14-features.md#db-ido).
844 object IdoMysqlConnection "mysql-ido" {
852 downtimehistory_age = 48h
853 contactnotifications_age = 31d
858 Configuration Attributes:
860 Name | Type | Description
861 --------------------------|-----------------------|----------------------------------
862 host | String | **Optional.** MySQL database host address. Defaults to `localhost`.
863 port | Number | **Optional.** MySQL database port. Defaults to `3306`.
864 socket\_path | String | **Optional.** MySQL socket path.
865 user | String | **Optional.** MySQL database user with read/write permission to the icinga database. Defaults to `icinga`.
866 password | String | **Optional.** MySQL database user's password. Defaults to `icinga`.
867 database | String | **Optional.** MySQL database name. Defaults to `icinga`.
868 enable\_ssl | Boolean | **Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
869 ssl\_key | String | **Optional.** MySQL SSL client key file path.
870 ssl\_cert | String | **Optional.** MySQL SSL certificate file path.
871 ssl\_ca | String | **Optional.** MySQL SSL certificate authority certificate file path.
872 ssl\_capath | String | **Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
873 ssl\_cipher | String | **Optional.** MySQL SSL list of allowed ciphers.
874 table\_prefix | String | **Optional.** MySQL database table prefix. Defaults to `icinga_`.
875 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
876 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
877 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`.
878 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 30s. Defaults to `30s`.
879 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
880 categories | Array | **Optional.** Array of information types that should be written to the database.
884 Name | Type | Description
885 --------------------------------|-----------------------|----------------------------------
886 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
887 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
888 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
889 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
890 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
891 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
892 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
893 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
894 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
895 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
896 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
897 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
898 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
899 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
900 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
904 Name | Description | Required by
905 ---------------------|------------------------|--------------------
906 DbCatConfig | Configuration data | Icinga Web 2
907 DbCatState | Current state data | Icinga Web 2
908 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
909 DbCatComment | Comments | Icinga Web 2
910 DbCatDowntime | Downtimes | Icinga Web 2
911 DbCatEventHandler | Event handler data | Icinga Web 2
912 DbCatExternalCommand | External commands | --
913 DbCatFlapping | Flap detection data | Icinga Web 2
914 DbCatCheck | Check results | --
915 DbCatLog | Log messages | --
916 DbCatNotification | Notifications | Icinga Web 2
917 DbCatProgramStatus | Program status data | Icinga Web 2
918 DbCatRetention | Retention data | Icinga Web 2
919 DbCatStateHistory | Historical state data | Icinga Web 2
921 The default value for `categories` includes everything required
922 by Icinga Web 2 in the table above.
924 In addition to the category flags listed above the `DbCatEverything`
925 flag may be used as a shortcut for listing all flags.
929 Name | Type | Description
930 ----------------------------|-----------------------|-----------------
931 last\_failover | Timestamp | When the last failover happened for this connection (only available with `enable_ha = true`.
933 ## IdoPgsqlConnection <a id="objecttype-idopgsqlconnection"></a>
935 IDO database adapter for PostgreSQL.
936 This configuration object is available as [ido-pgsql feature](14-features.md#db-ido).
941 object IdoPgsqlConnection "pgsql-ido" {
949 downtimehistory_age = 48h
950 contactnotifications_age = 31d
955 Configuration Attributes:
957 Name | Type | Description
958 --------------------------|-----------------------|----------------------------------
959 host | String | **Optional.** PostgreSQL database host address. Defaults to `localhost`.
960 port | Number | **Optional.** PostgreSQL database port. Defaults to `5432`.
961 user | String | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`.
962 password | String | **Optional.** PostgreSQL database user's password. Defaults to `icinga`.
963 database | String | **Optional.** PostgreSQL database name. Defaults to `icinga`.
964 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`.
965 ssl\_key | String | **Optional.** PostgreSQL SSL client key file path.
966 ssl\_cert | String | **Optional.** PostgreSQL SSL certificate file path.
967 ssl\_ca | String | **Optional.** PostgreSQL SSL certificate authority certificate file path.
968 table\_prefix | String | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`.
969 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
970 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
971 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`.
972 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 30s. Defaults to `30s`.
973 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
974 categories | Array | **Optional.** Array of information types that should be written to the database.
978 Name | Type | Description
979 --------------------------------|-----------------------|----------------------------------
980 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
981 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
982 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
983 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
984 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
985 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
986 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
987 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
988 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
989 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
990 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
991 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
992 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
993 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
994 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
998 Name | Description | Required by
999 ---------------------|------------------------|--------------------
1000 DbCatConfig | Configuration data | Icinga Web 2
1001 DbCatState | Current state data | Icinga Web 2
1002 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
1003 DbCatComment | Comments | Icinga Web 2
1004 DbCatDowntime | Downtimes | Icinga Web 2
1005 DbCatEventHandler | Event handler data | Icinga Web 2
1006 DbCatExternalCommand | External commands | --
1007 DbCatFlapping | Flap detection data | Icinga Web 2
1008 DbCatCheck | Check results | --
1009 DbCatLog | Log messages | --
1010 DbCatNotification | Notifications | Icinga Web 2
1011 DbCatProgramStatus | Program status data | Icinga Web 2
1012 DbCatRetention | Retention data | Icinga Web 2
1013 DbCatStateHistory | Historical state data | Icinga Web 2
1015 The default value for `categories` includes everything required
1016 by Icinga Web 2 in the table above.
1018 In addition to the category flags listed above the `DbCatEverything`
1019 flag may be used as a shortcut for listing all flags.
1023 Name | Type | Description
1024 ----------------------------|-----------------------|-----------------
1025 last\_failover | Timestamp | When the last failover happened for this connection (only available with `enable_ha = true`.
1027 ## InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
1029 Writes check result metrics and performance data to a defined InfluxDB host.
1030 This configuration object is available as [influxdb feature](14-features.md#influxdb-writer).
1035 object InfluxdbWriter "influxdb" {
1038 database = "icinga2"
1040 flush_threshold = 1024
1041 flush_interval = 10s
1044 measurement = "$host.check_command$"
1046 hostname = "$host.name$"
1049 service_template = {
1050 measurement = "$service.check_command$"
1052 hostname = "$host.name$"
1053 service = "$service.name$"
1059 Configuration Attributes:
1061 Name | Type | Description
1062 --------------------------|-----------------------|----------------------------------
1063 host | String | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
1064 port | Number | **Required.** InfluxDB HTTP port. Defaults to `8086`.
1065 database | String | **Required.** InfluxDB database name. Defaults to `icinga2`.
1066 username | String | **Optional.** InfluxDB user name. Defaults to `none`.
1067 password | String | **Optional.** InfluxDB user password. Defaults to `none`.
1068 ssl\_enable | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`.
1069 ssl\_ca\_cert | String | **Optional.** Path to CA certificate to validate the remote host.
1070 ssl\_cert | String | **Optional.** Path to host certificate to present to the remote host for mutual verification.
1071 ssl\_key | String | **Optional.** Path to host key to accompany the ssl\_cert.
1072 host\_template | String | **Required.** Host template to define the InfluxDB line protocol.
1073 service\_template | String | **Required.** Service template to define the influxDB line protocol.
1074 enable\_send\_thresholds | Boolean | **Optional.** Whether to send warn, crit, min & max tagged data.
1075 enable\_send\_metadata | Boolean | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
1076 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to InfluxDB. Defaults to `10s`.
1077 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`.
1078 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 `false`.
1080 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
1081 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
1086 ## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
1088 Livestatus API interface available as TCP or UNIX socket. Historical table queries
1089 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
1090 pointing to the log files using the `compat_log_path` configuration attribute.
1091 This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus).
1096 object LivestatusListener "livestatus-tcp" {
1098 bind_host = "127.0.0.1"
1102 object LivestatusListener "livestatus-unix" {
1103 socket_type = "unix"
1104 socket_path = "/var/run/icinga2/cmd/livestatus"
1108 Configuration Attributes:
1110 Name | Type | Description
1111 --------------------------|-----------------------|----------------------------------
1112 socket\_type | String | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`.
1113 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`.
1114 bind\_port | Number | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`.
1115 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".
1116 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"
1120 > UNIX sockets are not supported on Windows.
1123 ## Notification <a id="objecttype-notification"></a>
1125 Notification objects are used to specify how users should be notified in case
1126 of host and service state changes and other events.
1130 > Rather than creating a `Notification` object for a specific host or service it is
1131 > usually easier to just create a `Notification` template and use the `apply` keyword
1132 > to assign the notification to a number of hosts or services. Use the `to` keyword
1133 > to set the specific target type for `Host` or `Service`.
1134 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
1139 object Notification "localhost-ping-notification" {
1140 host_name = "localhost"
1141 service_name = "ping4"
1143 command = "mail-notification"
1145 users = [ "user1", "user2" ] // reference to User objects
1147 types = [ Problem, Recovery ]
1148 states = [ Critical, Warning, OK ]
1152 Configuration Attributes:
1154 Name | Type | Description
1155 --------------------------|-----------------------|----------------------------------
1156 host\_name | Object name | **Required.** The name of the host this notification belongs to.
1157 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.
1158 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
1159 users | Array of object names | **Required.** A list of user names who should be notified. **Optional.** if the `user_groups` attribute is set.
1160 user\_groups | Array of object names | **Required.** A list of user group names who should be notified. **Optional.** if the `users` attribute is set.
1161 times | Dictionary | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
1162 command | Object name | **Required.** The name of the notification command which should be executed when the notification is triggered.
1163 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.
1164 period | Object name | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
1165 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.
1166 types | Array | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
1167 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!
1169 Available notification state filters for Service:
1178 Available notification state filters for Host:
1185 Available notification type filters:
1201 Name | Type | Description
1202 ----------------------------|-----------------------|-----------------
1203 last\_notification | Timestamp | When the last notification was sent for this Notification object (as a UNIX timestamp).
1204 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).
1205 notification\_number | Number | The notification number.
1206 last\_problem\_notification | Timestamp | When the last notification was sent for a problem (as a UNIX timestamp).
1209 ## NotificationCommand <a id="objecttype-notificationcommand"></a>
1211 A notification command definition.
1216 object NotificationCommand "mail-service-notification" {
1217 command = [ ConfigDir + "/scripts/mail-service-notification.sh" ]
1222 value = "$notification_address$"
1224 "-6" = "$notification_address6$"
1225 "-b" = "$notification_author$"
1226 "-c" = "$notification_comment$"
1229 value = "$notification_date$"
1233 value = "$notification_servicename$"
1236 value = "$notification_from$"
1237 description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
1239 "-i" = "$notification_icingaweb2url$"
1242 value = "$notification_hostname$"
1246 value = "$notification_hostdisplayname$"
1250 value = "$notification_serviceoutput$"
1254 value = "$notification_useremail$"
1258 value = "$notification_servicestate$"
1262 value = "$notification_type$"
1266 value = "$notification_servicedisplayname$"
1268 "-v" = "$notification_logtosyslog$"
1272 notification_address = "$address$"
1273 notification_address6 = "$address6$"
1274 notification_author = "$notification.author$"
1275 notification_comment = "$notification.comment$"
1276 notification_type = "$notification.type$"
1277 notification_date = "$icinga.long_date_time$"
1278 notification_hostname = "$host.name$"
1279 notification_hostdisplayname = "$host.display_name$"
1280 notification_servicename = "$service.name$"
1281 notification_serviceoutput = "$service.output$"
1282 notification_servicestate = "$service.state$"
1283 notification_useremail = "$user.email$"
1284 notification_servicedisplayname = "$service.display_name$"
1289 Configuration Attributes:
1291 Name | Type | Description
1292 --------------------------|-----------------------|----------------------------------
1293 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.
1294 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1295 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
1296 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
1297 arguments | Dictionary | **Optional.** A dictionary of command arguments.
1299 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
1301 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
1303 ## NotificationComponent <a id="objecttype-notificationcomponent"></a>
1305 The notification component is responsible for sending notifications.
1306 This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature).
1311 object NotificationComponent "notification" { }
1314 Configuration Attributes:
1316 Name | Type | Description
1317 --------------------------|-----------------------|----------------------------------
1318 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".
1320 ## OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1322 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1323 This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer).
1328 object OpenTsdbWriter "opentsdb" {
1334 Configuration Attributes:
1336 Name | Type | Description
1337 --------------------------|-----------------------|----------------------------------
1338 host | String | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`.
1339 port | Number | **Optional.** OpenTSDB port. Defaults to `4242`.
1340 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 `false`.
1343 ## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1345 Writes check result performance data to a defined path using macro
1346 pattern consisting of custom attributes and runtime macros.
1347 This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files).
1352 object PerfdataWriter "perfdata" {
1353 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1355 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1357 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$"
1358 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$"
1360 rotation_interval = 15s
1364 Configuration Attributes:
1366 Name | Type | Description
1367 --------------------------|-----------------------|----------------------------------
1368 host\_perfdata\_path | String | **Optional.** Path to the host performance data file. Defaults to SpoolDir + "/perfdata/host-perfdata".
1369 service\_perfdata\_path | String | **Optional.** Path to the service performance data file. Defaults to SpoolDir + "/perfdata/service-perfdata".
1370 host\_temp\_path | String | **Optional.** Path to the temporary host file. Defaults to SpoolDir + "/tmp/host-perfdata".
1371 service\_temp\_path | String | **Optional.** Path to the temporary service file. Defaults to SpoolDir + "/tmp/service-perfdata".
1372 host\_format\_template | String | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1373 service\_format\_template | String | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1374 rotation\_interval | Duration | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`.
1375 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 `false`.
1377 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1378 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1381 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
1383 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1387 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1388 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1389 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1390 > type for `Host` or `Service`.
1391 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
1396 object ScheduledDowntime "some-downtime" {
1397 host_name = "localhost"
1398 service_name = "ping4"
1400 author = "icingaadmin"
1401 comment = "Some comment"
1407 "sunday" = "02:00-03:00"
1412 Configuration Attributes:
1414 Name | Type | Description
1415 --------------------------|-----------------------|----------------------------------
1416 host\_name | Object name | **Required.** The name of the host this scheduled downtime belongs to.
1417 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.
1418 author | String | **Required.** The author of the downtime.
1419 comment | String | **Required.** A comment for the downtime.
1420 fixed | Boolean | **Optional.** Whether this is a fixed downtime. Defaults to `true`.
1421 duration | Duration | **Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1422 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1423 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`.
1425 ScheduledDowntime objects have composite names, i.e. their names are based
1426 on the `host_name` and `service_name` attributes and the
1427 name you specified. This means you can define more than one object
1428 with the same (short) name as long as one of the `host_name` and
1429 `service_name` attributes has a different value.
1432 ## Service <a id="objecttype-service"></a>
1434 Service objects describe network services and how they should be checked
1439 > Rather than creating a `Service` object for a specific host it is usually easier
1440 > to just create a `Service` template and use the `apply` keyword to assign the
1441 > service to a number of hosts.
1442 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
1447 object Service "uptime" {
1448 host_name = "localhost"
1450 display_name = "localhost Uptime"
1452 check_command = "snmp"
1454 vars.snmp_community = "public"
1455 vars.snmp_oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1457 check_interval = 60s
1458 retry_interval = 15s
1460 groups = [ "all-services", "snmp" ]
1464 Configuration Attributes:
1466 Name | Type | Description
1467 --------------------------|-----------------------|----------------------------------
1468 display\_name | String | **Optional.** A short description of the service.
1469 host\_name | Object name | **Required.** The host this service belongs to. There must be a `Host` object with that name.
1470 groups | Array of object names | **Optional.** The service groups this service belongs to.
1471 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this service.
1472 check\_command | Object name | **Required.** The name of the check command.
1473 max\_check\_attempts | Number | **Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1474 check\_period | Object name | **Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1475 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
1476 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`.
1477 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).
1478 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to `true`.
1479 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to `true`.
1480 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to `true`.
1481 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to `true`.
1482 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to `false`.
1483 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a service to be considered flapping. `30.0`
1484 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a service to be considered not flapping. `25.0`
1485 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to `true`.
1486 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.
1487 volatile | Boolean | **Optional.** Treat all state changes as HARD changes. See [here](08-advanced-topics.md#volatile-services-hosts) for details. Defaults to `false`.
1488 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.
1489 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.
1490 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
1491 notes | String | **Optional.** Notes for the service.
1492 notes\_url | String | **Optional.** URL for notes for the service (for example, in notification commands).
1493 action\_url | String | **Optional.** URL for actions for the service (for example, an external graphing tool).
1494 icon\_image | String | **Optional.** Icon image for the service. Used by external interfaces only.
1495 icon\_image\_alt | String | **Optional.** Icon image description for the service. Used by external interface only.
1497 Service objects have composite names, i.e. their names are based on the host\_name attribute and the name you specified. This means
1498 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1500 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
1501 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
1505 Name | Type | Description
1506 --------------------------|-----------------------|----------------------------------
1507 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
1508 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
1509 check\_attempt | Number | The current check attempt number.
1510 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1511 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1512 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1513 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
1514 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
1515 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
1516 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1517 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1518 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1519 downtime\_depth | Number | Whether the service has one or more active downtimes.
1520 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
1521 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
1522 flapping | Boolean | Whether the host is flapping between states.
1523 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1524 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1525 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1526 last\_state\_ok | Timestamp | When the last OK state occurred (as a UNIX timestamp).
1527 last\_state\_warning | Timestamp | When the last WARNING state occurred (as a UNIX timestamp).
1528 last\_state\_critical | Timestamp | When the last CRITICAL state occurred (as a UNIX timestamp).
1529 last\_state\_unknown | Timestamp | When the last UNKNOWN state occurred (as a UNIX timestamp).
1532 ## ServiceGroup <a id="objecttype-servicegroup"></a>
1534 A group of services.
1538 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
1543 object ServiceGroup "snmp" {
1544 display_name = "SNMP services"
1548 Configuration Attributes:
1550 Name | Type | Description
1551 --------------------------|-----------------------|----------------------------------
1552 display\_name | String | **Optional.** A short description of the service group.
1553 groups | Array of object names | **Optional.** An array of nested group names.
1556 ## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1558 Periodically writes status and configuration data files which are used by third-party tools.
1559 This configuration object is available as [statusdata feature](14-features.md#status-data).
1564 object StatusDataWriter "status" {
1565 status_path = "/var/cache/icinga2/status.dat"
1566 objects_path = "/var/cache/icinga2/objects.cache"
1567 update_interval = 30s
1571 Configuration Attributes:
1573 Name | Type | Description
1574 --------------------------|-----------------------|----------------------------------
1575 status\_path | String | **Optional.** Path to the `status.dat` file. Defaults to CacheDir + "/status.dat".
1576 objects\_path | String | **Optional.** Path to the `objects.cache` file. Defaults to CacheDir + "/objects.cache".
1577 update\_interval | Duration | **Optional.** The interval in which the status files are updated. Defaults to `15s`.
1580 ## SyslogLogger <a id="objecttype-sysloglogger"></a>
1582 Specifies Icinga 2 logging to syslog.
1583 This configuration object is available as `syslog` [logging feature](14-features.md#logging).
1588 object SyslogLogger "syslog" {
1589 severity = "warning"
1593 Configuration Attributes:
1595 Name | Type | Description
1596 --------------------------|-----------------------|----------------------------------
1597 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1598 facility | String | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`.
1602 Name | Facility | Description
1603 ---------------------|---------------|----------------
1604 FacilityAuth | LOG\_AUTH | The authorization system.
1605 FacilityAuthPriv | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals.
1606 FacilityCron | LOG\_CRON | The cron daemon.
1607 FacilityDaemon | LOG\_DAEMON | System daemons that are not provided for explicitly by other facilities.
1608 FacilityFtp | LOG\_FTP | The file transfer protocol daemons.
1609 FacilityKern | LOG\_KERN | Messages generated by the kernel. These cannot be generated by any user processes.
1610 FacilityLocal0 | LOG\_LOCAL0 | Reserved for local use.
1611 FacilityLocal1 | LOG\_LOCAL1 | Reserved for local use.
1612 FacilityLocal2 | LOG\_LOCAL2 | Reserved for local use.
1613 FacilityLocal3 | LOG\_LOCAL3 | Reserved for local use.
1614 FacilityLocal4 | LOG\_LOCAL4 | Reserved for local use.
1615 FacilityLocal5 | LOG\_LOCAL5 | Reserved for local use.
1616 FacilityLocal6 | LOG\_LOCAL6 | Reserved for local use.
1617 FacilityLocal7 | LOG\_LOCAL7 | Reserved for local use.
1618 FacilityLpr | LOG\_LPR | The line printer spooling system.
1619 FacilityMail | LOG\_MAIL | The mail system.
1620 FacilityNews | LOG\_NEWS | The network news system.
1621 FacilitySyslog | LOG\_SYSLOG | Messages generated internally by syslogd.
1622 FacilityUser | LOG\_USER | Messages generated by user processes. This is the default facility identifier if none is specified.
1623 FacilityUucp | LOG\_UUCP | The UUCP system.
1625 ## TimePeriod <a id="objecttype-timeperiod"></a>
1627 Time periods can be used to specify when hosts/services should be checked or to limit
1628 when notifications should be sent out.
1633 object TimePeriod "nonworkhours" {
1634 display_name = "Icinga 2 TimePeriod for non working hours"
1637 monday = "00:00-8:00,17:00-24:00"
1638 tuesday = "00:00-8:00,17:00-24:00"
1639 wednesday = "00:00-8:00,17:00-24:00"
1640 thursday = "00:00-8:00,17:00-24:00"
1641 friday = "00:00-8:00,16:00-24:00"
1642 saturday = "00:00-24:00"
1643 sunday = "00:00-24:00"
1647 object TimePeriod "exampledays" {
1648 display_name = "Icinga 2 TimePeriod for random example days"
1651 //We still believe in Santa, no peeking!
1652 //Applies every 25th of December every year
1653 "december 25" = "00:00-24:00"
1655 //Any point in time can be specified,
1656 //but you still have to use a range
1657 "2038-01-19" = "03:13-03:15"
1659 //Evey 3rd day from the second monday of February
1660 //to 8th of November
1661 "monday 2 february - november 8 / 3" = "00:00-24:00"
1666 Additional examples can be found [here](08-advanced-topics.md#timeperiods).
1668 Configuration Attributes:
1670 Name | Type | Description
1671 --------------------------|-----------------------|----------------------------------
1672 display\_name | String | **Optional.** A short description of the time period.
1673 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1674 prefer\_includes | Boolean | **Optional.** Whether to prefer timeperiods `includes` or `excludes`. Default to true.
1675 excludes | Array of object names | **Optional.** An array of timeperiods, which should exclude from your timerange.
1676 includes | Array of object names | **Optional.** An array of timeperiods, which should include into your timerange
1681 Name | Type | Description
1682 --------------------------|-----------------------|----------------------------------
1683 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1686 ## User <a id="objecttype-user"></a>
1693 object User "icingaadmin" {
1694 display_name = "Icinga 2 Admin"
1695 groups = [ "icingaadmins" ]
1696 email = "icinga@localhost"
1697 pager = "icingaadmin@localhost.localdomain"
1701 states = [ OK, Warning, Critical, Unknown ]
1702 types = [ Problem, Recovery ]
1704 vars.additional_notes = "This is the Icinga 2 Admin account."
1708 Available notification state filters:
1719 Available notification type filters:
1733 Configuration Attributes:
1735 Name | Type | Description
1736 --------------------------|-----------------------|----------------------------------
1737 display\_name | String | **Optional.** A short description of the user.
1738 email | String | **Optional.** An email string for this user. Useful for notification commands.
1739 pager | String | **Optional.** A pager string for this user. Useful for notification commands.
1740 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this user.
1741 groups | Array of object names | **Optional.** An array of group names.
1742 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled for this user. Defaults to true.
1743 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.
1744 types | Array | **Optional.** A set of type filters when a notification for this user should be triggered. By default everything is matched.
1745 states | Array | **Optional.** A set of state filters when a notification for this should be triggered. By default everything is matched.
1749 Name | Type | Description
1750 --------------------------|-----------------------|----------------------------------
1751 last\_notification | Timestamp | When the last notification was sent for this user (as a UNIX timestamp).
1753 ## UserGroup <a id="objecttype-usergroup"></a>
1759 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
1764 object UserGroup "icingaadmins" {
1765 display_name = "Icinga 2 Admin Group"
1769 Configuration Attributes:
1771 Name | Type | Description
1772 --------------------------|-----------------------|----------------------------------
1773 display\_name | String | **Optional.** A short description of the user group.
1774 groups | Array of object names | **Optional.** An array of nested group names.
1777 ## Zone <a id="objecttype-zone"></a>
1779 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1780 Please read the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring) for additional details.
1784 object Zone "master" {
1785 endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]
1789 object Zone "satellite" {
1790 endpoints = [ "icinga2-satellite1.localdomain" ]
1795 Configuration Attributes:
1797 Name | Type | Description
1798 --------------------------|-----------------------|----------------------------------
1799 endpoints | Array of object names | **Optional.** Array of endpoint names located in this zone.
1800 parent | Object name | **Optional.** The name of the parent zone. (Do not specify a global zone)
1801 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`.
1803 Zone objects cannot currently be created with the API.