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 `NodeName` constant must be defined in [constants.conf](04-configuring-icinga-2.md#constants-conf).
43 object ApiListener "api" {
44 accept_commands = true
47 ticket_salt = TicketSalt
51 Configuration Attributes:
53 Name | Type | Description
54 --------------------------------------|-----------------------|----------------------------------
55 cert\_path | String | **Deprecated.** Path to the public key.
56 key\_path | String | **Deprecated.** Path to the private key.
57 ca\_path | String | **Deprecated.** Path to the CA certificate file.
58 ticket\_salt | String | **Optional.** Private key for [CSR auto-signing](06-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing). **Required** for a signing master instance.
59 crl\_path | String | **Optional.** Path to the CRL file.
60 bind\_host | String | **Optional.** The IP address the api listener should be bound to. Defaults to `0.0.0.0`.
61 bind\_port | Number | **Optional.** The port the api listener should be bound to. Defaults to `5665`.
62 accept\_config | Boolean | **Optional.** Accept zone configuration. Defaults to `false`.
63 accept\_commands | Boolean | **Optional.** Accept remote commands. Defaults to `false`.
64 cipher\_list | String | **Optional.** Cipher list that is allowed.
65 tls\_protocolmin | String | **Optional.** Minimum TLS protocol version. Must be one of `TLSv1`, `TLSv1.1` or `TLSv1.2`. Defaults to `TLSv1`.
66 access\_control\_allow\_origin | Array | **Optional.** Specifies an array of origin URLs that may access the API. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Origin)
67 access\_control\_allow\_credentials | Boolean | **Optional.** Indicates whether or not the actual request can be made using credentials. Defaults to `true`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Credentials)
68 access\_control\_allow\_headers | String | **Optional.** Used in response to a preflight request to indicate which HTTP headers can be used when making the actual request. Defaults to `Authorization`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Headers)
69 access\_control\_allow\_methods | String | **Optional.** Used in response to a preflight request to indicate which HTTP methods can be used when making the actual request. Defaults to `GET, POST, PUT, DELETE`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Methods)
71 The ApiListener type expects its certificate files to be in the following locations:
74 ---------------------|-------------------------------------
75 Private key | `LocalStateDir + "/lib/icinga2/certs/" + NodeName + ".key"`
76 Certificate file | `LocalStateDir + "/lib/icinga2/certs/" + NodeName + ".crt"`
77 CA certificate file | `LocalStateDir + "/lib/icinga2/certs/ca.crt"`
79 If the deprecated attributes `cert_path`, `key_path` and/or `ca_path` are specified Icinga 2
80 copies those files to the new location in `LocalStateDir + "/lib/icinga2/certs"` unless the
81 file(s) there are newer.
83 Please check the [upgrading chapter](16-upgrading-icinga-2.md#upgrading-to-2-8-certificate-paths) for more details.
85 ## ApiUser <a id="objecttype-apiuser"></a>
87 ApiUser objects are used for authentication against the [Icinga 2 API](12-icinga2-api.md#icinga2-api-authentication).
92 object ApiUser "root" {
93 password = "mysecretapipassword"
98 Configuration Attributes:
100 Name | Type | Description
101 --------------------------|-----------------------|----------------------------------
102 password | String | **Optional.** Password string. Note: This attribute is hidden in API responses.
103 client\_cn | String | **Optional.** Client Common Name (CN).
104 permissions | Array | **Required.** Array of permissions. Either as string or dictionary with the keys `permission` and `filter`. The latter must be specified as function.
106 Available permissions are explained in the [API permissions](12-icinga2-api.md#icinga2-api-permissions)
109 ## CheckCommand <a id="objecttype-checkcommand"></a>
111 A check command definition. Additional default command custom attributes can be
116 > Icinga 2 versions < 2.6.0 require the import of the [plugin-check-command](10-icinga-template-library.md#itl-plugin-check-command) template.
121 object CheckCommand "http" {
122 command = [ PluginDir + "/check_http" ]
125 "-H" = "$http_vhost$"
126 "-I" = "$http_address$"
130 set_if = "$http_ssl$"
133 set_if = "$http_sni$"
136 value = "$http_auth_pair$"
137 description = "Username:password on sites with basic authentication"
140 set_if = "$http_ignore_body$"
142 "-r" = "$http_expect_body_regex$"
143 "-w" = "$http_warn_time$"
144 "-c" = "$http_critical_time$"
145 "-e" = "$http_expect$"
148 vars.http_address = "$address$"
149 vars.http_ssl = false
150 vars.http_sni = false
154 Configuration Attributes:
156 Name | Type | Description
157 --------------------------|-----------------------|----------------------------------
158 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.
159 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
160 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
161 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
162 arguments | Dictionary | **Optional.** A dictionary of command arguments.
165 ### CheckCommand Arguments <a id="objecttype-checkcommand-arguments"></a>
167 Command arguments can be defined as key-value-pairs in the `arguments`
168 dictionary. If the argument requires additional configuration, for example
169 a `description` attribute or an optional condition, the value can be defined
170 as dictionary specifying additional options.
175 vars.x_val = "My command argument value."
185 key = "-Xnew" /* optional, set a new key identifier */
186 description = "My plugin requires this argument for doing X."
187 required = false /* optional, no error if not set */
188 skip_key = false /* always use "-X <value>" */
189 set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
190 order = -1 /* first position */
191 repeat_key = true /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
195 description = "My plugin requires this argument for doing Y."
196 required = false /* optional, no error if not set */
197 skip_key = true /* don't prefix "-Y" only use "<value>" */
198 set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
199 order = 0 /* second position */
200 repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
205 Name | Type | Description
206 --------------------------|-----------------------|----------------------------------
207 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).
208 key | String | Optional argument key overriding the key identifier.
209 description | String | Optional argument description.
210 required | Boolean | Required argument. Execution error if not set. Defaults to false (optional).
211 skip\_key | Boolean | Use the value as argument and skip the key.
212 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.
213 order | Number | Set if multiple arguments require a defined argument order.
214 repeat\_key | Boolean | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
219 ..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...
222 Argument array with `repeat_key = true`:
225 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'
228 Argument array with `repeat_key = false`:
231 'key' 'value[0]' 'value[1]' 'value[2]'
234 ## CheckerComponent <a id="objecttype-checkcomponent"></a>
236 The checker component is responsible for scheduling active checks.
237 This configuration object is available as [checker feature](11-cli-commands.md#cli-command-feature).
244 object CheckerComponent "checker" {
245 concurrent_checks = 512
249 Configuration Attributes:
251 Name | Type | Description
252 --------------------------|-----------------------|----------------------------------
253 concurrent\_checks | Number | **Optional.** The maximum number of concurrent checks. Defaults to 512.
255 ## CheckResultReader <a id="objecttype-checkresultreader"></a>
257 Reads Icinga 1.x check result files from a directory. This functionality is provided
258 to help existing Icinga 1.x users and might be useful for migration scenarios.
265 object CheckResultReader "reader" {
266 spool_dir = "/data/check-results"
270 Configuration Attributes:
272 Name | Type | Description
273 --------------------------|-----------------------|----------------------------------
274 spool\_dir | String | **Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/".
276 ## Comment <a id="objecttype-comment"></a>
278 Comments created at runtime are represented as objects.
279 Note: This is for reference only. You can create comments
280 with the [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) API action.
285 object Comment "localhost!my-comment" {
286 host_name = "localhost"
287 author = "icingaadmin"
288 text = "This is a comment."
292 Configuration Attributes:
294 Name | Type | Description
295 --------------------------|-----------------------|----------------------------------
296 host\_name | Object name | **Required.** The name of the host this comment belongs to.
297 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.
298 author | String | **Required.** The author's name.
299 text | String | **Required.** The comment text.
300 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this comment was added.
301 entry\_type | Number | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
302 expire\_time | Timestamp | **Optional.** The comment's expire time as UNIX timestamp.
303 persistent | Boolean | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
305 ## CompatLogger <a id="objecttype-compatlogger"></a>
307 Writes log files in a format that's compatible with Icinga 1.x.
308 This configuration object is available as [compatlog feature](14-features.md#compat-logging).
315 object CompatLogger "compatlog" {
316 log_dir = "/var/log/icinga2/compat"
317 rotation_method = "DAILY"
321 Configuration Attributes:
323 Name | Type | Description
324 --------------------------|-----------------------|----------------------------------
325 log\_dir | String | **Optional.** Path to the compat log directory. Defaults to LocalStateDir + "/log/icinga2/compat".
326 rotation\_method | String | **Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
329 ## Dependency <a id="objecttype-dependency"></a>
331 Dependency objects are used to specify dependencies between hosts and services. Dependencies
332 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
337 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
338 > to just create a `Dependency` template and use the `apply` keyword to assign the
339 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
340 > type for `Host` or `Service`.
341 > Check the [dependencies](03-monitoring-basics.md#dependencies) chapter for detailed examples.
343 Service-to-Service Example:
346 object Dependency "webserver-internet" {
347 parent_host_name = "internet"
348 parent_service_name = "ping4"
350 child_host_name = "webserver"
351 child_service_name = "ping4"
353 states = [ OK, Warning ]
355 disable_checks = true
359 Host-to-Host Example:
362 object Dependency "webserver-internet" {
363 parent_host_name = "internet"
365 child_host_name = "webserver"
369 disable_checks = true
373 Configuration Attributes:
375 Name | Type | Description
376 --------------------------|-----------------------|----------------------------------
377 parent\_host\_name | Object name | **Required.** The parent host.
378 parent\_service\_name | Object name | **Optional.** The parent service. If omitted, this dependency object is treated as host dependency.
379 child\_host\_name | Object name | **Required.** The child host.
380 child\_service\_name | Object name | **Optional.** The child service. If omitted, this dependency object is treated as host dependency.
381 disable\_checks | Boolean | **Optional.** Whether to disable checks when this dependency fails. Defaults to false.
382 disable\_notifications | Boolean | **Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
383 ignore\_soft\_states | Boolean | **Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
384 period | Object name | **Optional.** Time period object during which this dependency is enabled.
385 states | Array | **Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
387 Available state filters:
396 When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
397 automatically determined by Icinga 2.
399 Service-to-Host Dependency Example:
402 apply Dependency "internet" to Service {
403 parent_host_name = "dsl-router"
404 disable_checks = true
406 assign where host.name != "dsl-router"
410 This example sets all service objects matching the assign condition into a dependency relation to
411 the parent host object `dsl-router` as implicit child services.
413 Service-to-Service-on-the-same-Host Dependency Example:
416 apply Dependency "disable-agent-checks" to Service {
417 parent_service_name = "agent-health"
419 assign where service.check_command == "ssh"
420 ignore where service.name == "agent-health"
424 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
425 host object matched by the apply rule condition. All services where apply matches are made implicit child services
426 in this dependency relation.
429 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
430 name you specified. This means you can define more than one object with the same (short) name as long as one of the `child_host_name` and
431 `child_service_name` attributes has a different value.
433 ## Downtime <a id="objecttype-downtime"></a>
435 Downtimes created at runtime are represented as objects.
436 You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action.
441 object Downtime "localhost!my-downtime" {
442 host_name = "localhost"
443 author = "icingaadmin"
444 comment = "This is a downtime."
445 start_time = 1505312869
446 end_time = 1505312924
450 Configuration Attributes:
452 Name | Type | Description
453 --------------------------|-----------------------|----------------------------------
454 host\_name | Object name | **Required.** The name of the host this comment belongs to.
455 service\_name | Object name | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment.
456 author | String | **Required.** The author's name.
457 comment | String | **Required.** The comment text.
458 start\_time | Timestamp | **Required.** The start time as UNIX timestamp.
459 end\_time | Timestamp | **Required.** The end time as UNIX timestamp.
460 duration | Number | **Optional.** The duration as number.
461 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this downtime was added.
462 fixed | Boolean | **Optional.** Whether the downtime is fixed (true) or flexible (false). Defaults to flexible. Details in the [advanced topics chapter](08-advanced-topics.md#fixed-flexible-downtimes).
463 triggers | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime.
467 Name | Type | Description
468 --------------------------|-----------------------|----------------------------------
469 trigger\_time | Timestamp | The UNIX timestamp when this downtime was triggered.
470 triggered\_by | Object name | The name of the downtime this downtime was triggered by.
473 ## ElasticsearchWriter <a id="objecttype-elasticsearchwriter"></a>
475 Writes check result metrics and performance data to an Elasticsearch instance.
476 This configuration object is available as [elasticsearch feature](14-features.md#elasticsearch-writer).
483 object ElasticsearchWriter "elasticsearch" {
488 enable_send_perfdata = true
490 flush_threshold = 1024
495 The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
497 Configuration Attributes:
499 Name | Type | Description
500 --------------------------|-----------------------|----------------------------------
501 host | String | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
502 port | Number | **Required.** Elasticsearch port. Defaults to `9200`.
503 index | String | **Required.** Elasticsearch index name. Defaults to `icinga2`.
504 enable\_send\_perfdata | Boolean | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
505 flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to Elasticsearch. Defaults to `10s`.
506 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to `1024`.
507 username | String | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
508 password | String | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
509 enable\_tls | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
510 ca\_path | String | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
511 cert\_path | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
512 key\_path | String | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
514 Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
515 Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
517 Basic auth is supported with the `username` and `password` attributes. This requires an
518 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/)
521 TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
522 you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
524 ## Endpoint <a id="objecttype-endpoint"></a>
526 Endpoint objects are used to specify connection information for remote
527 Icinga 2 instances. More details can be found in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
532 object Endpoint "icinga2-client1.localdomain" {
533 host = "192.168.56.111"
539 Example (disable replay log):
542 object Endpoint "icinga2-client1.localdomain" {
543 host = "192.168.5.111"
549 Configuration Attributes:
551 Name | Type | Description
552 --------------------------|-----------------------|----------------------------------
553 host | String | **Optional.** The hostname/IP address of the remote Icinga 2 instance.
554 port | Number | **Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
555 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.
557 Endpoint objects cannot currently be created with the API.
559 ## EventCommand <a id="objecttype-eventcommand"></a>
561 An event command definition.
565 > Icinga 2 versions < 2.6.0 require the import of the [plugin-event-command](10-icinga-template-library.md#itl-plugin-event-command) template.
570 object EventCommand "restart-httpd-event" {
571 command = "/opt/bin/restart-httpd.sh"
576 Configuration Attributes:
578 Name | Type | Description
579 --------------------------|-----------------------|----------------------------------
580 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.
581 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
582 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
583 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
584 arguments | Dictionary | **Optional.** A dictionary of command arguments.
586 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
588 More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
590 ## ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
592 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
593 This configuration object is available as [command feature](14-features.md#external-commands).
600 object ExternalCommandListener "command" {
601 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
605 Configuration Attributes:
607 Name | Type | Description
608 --------------------------|-----------------------|----------------------------------
609 command\_path | String | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
613 ## FileLogger <a id="objecttype-filelogger"></a>
615 Specifies Icinga 2 logging to a file.
616 This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging).
621 object FileLogger "debug-file" {
623 path = "/var/log/icinga2/debug.log"
627 Configuration Attributes:
629 Name | Type | Description
630 --------------------------|-----------------------|----------------------------------
631 path | String | **Required.** The log path.
632 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
635 ## GelfWriter <a id="objecttype-gelfwriter"></a>
637 Writes event log entries to a defined GELF receiver host (Graylog, Logstash).
638 This configuration object is available as [gelf feature](14-features.md#gelfwriter).
645 object GelfWriter "gelf" {
651 Configuration Attributes:
653 Name | Type | Description
654 --------------------------|-----------------------|----------------------------------
655 host | String | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`.
656 port | Number | **Optional.** GELF receiver port. Defaults to `12201`.
657 source | String | **Optional.** Source name for this instance. Defaults to `icinga2`.
658 enable\_send\_perfdata | Boolean | **Optional.** Enable performance data for 'CHECK RESULT' events.
661 ## GraphiteWriter <a id="objecttype-graphitewriter"></a>
663 Writes check result metrics and performance data to a defined
664 Graphite Carbon host.
665 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`.
689 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
693 ## Host <a id="objecttype-host"></a>
700 object Host "icinga2-client1.localdomain" {
701 display_name = "Linux Client 1"
702 address = "192.168.56.111"
703 address6 = "2a00:1450:4001:815::2003"
705 groups = [ "linux-servers" ]
707 check_command = "hostalive"
711 Configuration Attributes:
713 Name | Type | Description
714 --------------------------|-----------------------|----------------------------------
715 display\_name | String | **Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
716 address | String | **Optional.** The host's IPv4 address. Available as command runtime macro `$address$` if set.
717 address6 | String | **Optional.** The host's IPv6 address. Available as command runtime macro `$address6$` if set.
718 groups | Array of object names | **Optional.** A list of host groups this host belongs to.
719 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this host.
720 check\_command | Object name | **Required.** The name of the check command.
721 max\_check\_attempts | Number | **Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
722 check\_period | Object name | **Optional.** The name of a time period which determines when this host should be checked. Not set by default.
723 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
724 check\_interval | Duration | **Optional.** The check interval (in seconds). This interval is used for checks when the host is in a `HARD` state. Defaults to `5m`.
725 retry\_interval | Duration | **Optional.** The retry interval (in seconds). This interval is used for checks when the host is in a `SOFT` state. Defaults to `1m`.
726 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to true.
727 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to true.
728 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to true.
729 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to true.
730 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to false.
731 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to true.
732 event\_command | Object name | **Optional.** The name of an event command that should be executed every time the host's state changes or the host is in a `SOFT` state.
733 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a host to be considered flapping. Default `30.0`
734 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a host to be considered not flapping. Default `25.0`
735 volatile | Boolean | **Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur. Defaults to false.
736 zone | Object name | **Optional.** The zone this object is a member of. Please read the [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring) chapter for details.
737 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
738 notes | String | **Optional.** Notes for the host.
739 notes\_url | String | **Optional.** URL for notes for the host (for example, in notification commands).
740 action\_url | String | **Optional.** URL for actions for the host (for example, an external graphing tool).
741 icon\_image | String | **Optional.** Icon image for the host. Used by external interfaces only.
742 icon\_image\_alt | String | **Optional.** Icon image description for the host. Used by external interface only.
744 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
745 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
749 > The `address` and `address6` attributes are required for running commands using
750 > the `$address$` and `$address6$` runtime macros.
754 Name | Type | Description
755 --------------------------|-----------------------|----------------------------------
756 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
757 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
758 check\_attempt | Number | The current check attempt number.
759 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
760 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
761 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
762 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
763 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
764 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
765 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
766 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
767 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
768 downtime\_depth | Number | Whether the host has one or more active downtimes.
769 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
770 flapping | Boolean | Whether the host is flapping between states.
771 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
772 state | Number | The current state (0 = UP, 1 = DOWN).
773 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
774 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
775 last\_state\_up | Timestamp | When the last UP state occurred (as a UNIX timestamp).
776 last\_state\_down | Timestamp | When the last DOWN state occurred (as a UNIX timestamp).
780 ## HostGroup <a id="objecttype-hostgroup"></a>
786 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
791 object HostGroup "linux-servers" {
792 display_name = "Linux Servers"
794 assign where host.vars.os == "Linux"
798 Configuration Attributes:
800 Name | Type | Description
801 --------------------------|-----------------------|----------------------------------
802 display\_name | String | **Optional.** A short description of the host group.
803 groups | Array of object names | **Optional.** An array of nested group names.
805 ## IcingaApplication <a id="objecttype-icingaapplication"></a>
807 The IcingaApplication object is required to start Icinga 2.
808 The object name must be `app`. If the object configuration
809 is missing, Icinga 2 will automatically create an IcingaApplication
815 object IcingaApplication "app" {
816 enable_perfdata = false
820 Configuration Attributes:
822 Name | Type | Description
823 --------------------------|-----------------------|----------------------------------
824 enable\_notifications | Boolean | **Optional.** Whether notifications are globally enabled. Defaults to true.
825 enable\_event\_handlers | Boolean | **Optional.** Whether event handlers are globally enabled. Defaults to true.
826 enable\_flapping | Boolean | **Optional.** Whether flap detection is globally enabled. Defaults to true.
827 enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true.
828 enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true.
829 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true.
830 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally.
832 ## IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
834 IDO database adapter for MySQL.
835 This configuration object is available as [ido-mysql feature](14-features.md#db-ido).
840 library "db_ido_mysql"
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 library "db_ido_pgsql"
935 object IdoPgsqlConnection "pgsql-ido" {
943 downtimehistory_age = 48h
944 contactnotifications_age = 31d
949 Configuration Attributes:
951 Name | Type | Description
952 --------------------------|-----------------------|----------------------------------
953 host | String | **Optional.** PostgreSQL database host address. Defaults to `localhost`.
954 port | Number | **Optional.** PostgreSQL database port. Defaults to `5432`.
955 user | String | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`.
956 password | String | **Optional.** PostgreSQL database user's password. Defaults to `icinga`.
957 database | String | **Optional.** PostgreSQL database name. Defaults to `icinga`.
958 table\_prefix | String | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`.
959 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
960 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
961 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".
962 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`.
963 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
964 categories | Array | **Optional.** Array of information types that should be written to the database.
968 Name | Type | Description
969 --------------------------------|-----------------------|----------------------------------
970 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
971 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
972 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
973 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
974 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
975 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
976 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
977 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
978 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
979 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
980 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
981 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
982 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
983 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
984 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
988 Name | Description | Required by
989 ---------------------|------------------------|--------------------
990 DbCatConfig | Configuration data | Icinga Web 2
991 DbCatState | Current state data | Icinga Web 2
992 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
993 DbCatComment | Comments | Icinga Web 2
994 DbCatDowntime | Downtimes | Icinga Web 2
995 DbCatEventHandler | Event handler data | Icinga Web 2
996 DbCatExternalCommand | External commands | --
997 DbCatFlapping | Flap detection data | Icinga Web 2
998 DbCatCheck | Check results | --
999 DbCatLog | Log messages | --
1000 DbCatNotification | Notifications | Icinga Web 2
1001 DbCatProgramStatus | Program status data | Icinga Web 2
1002 DbCatRetention | Retention data | Icinga Web 2
1003 DbCatStateHistory | Historical state data | Icinga Web 2
1005 The default value for `categories` includes everything required
1006 by Icinga Web 2 in the table above.
1008 In addition to the category flags listed above the `DbCatEverything`
1009 flag may be used as a shortcut for listing all flags.
1011 ## InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
1013 Writes check result metrics and performance data to a defined InfluxDB host.
1014 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`.
1065 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
1066 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
1071 ## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
1073 Livestatus API interface available as TCP or UNIX socket. Historical table queries
1074 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
1075 pointing to the log files using the `compat_log_path` configuration attribute.
1076 This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus).
1081 library "livestatus"
1083 object LivestatusListener "livestatus-tcp" {
1085 bind_host = "127.0.0.1"
1089 object LivestatusListener "livestatus-unix" {
1090 socket_type = "unix"
1091 socket_path = "/var/run/icinga2/cmd/livestatus"
1095 Configuration Attributes:
1097 Name | Type | Description
1098 --------------------------|-----------------------|----------------------------------
1099 socket\_type | String | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`.
1100 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`.
1101 bind\_port | Number | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`.
1102 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".
1103 compat\_log\_path | String | **Optional.** Path to Icinga 1.x log files. Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"
1107 > UNIX sockets are not supported on Windows.
1110 ## Notification <a id="objecttype-notification"></a>
1112 Notification objects are used to specify how users should be notified in case
1113 of host and service state changes and other events.
1117 > Rather than creating a `Notification` object for a specific host or service it is
1118 > usually easier to just create a `Notification` template and use the `apply` keyword
1119 > to assign the notification to a number of hosts or services. Use the `to` keyword
1120 > to set the specific target type for `Host` or `Service`.
1121 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
1126 object Notification "localhost-ping-notification" {
1127 host_name = "localhost"
1128 service_name = "ping4"
1130 command = "mail-notification"
1132 users = [ "user1", "user2" ]
1134 types = [ Problem, Recovery ]
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 | **Optional.** A list of user names who should be notified.
1146 user\_groups | Array of object names | **Optional.** A list of user group names who should be notified.
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.
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.
1195 > Icinga 2 versions < 2.6.0 require the import of the [plugin-notification-command](10-icinga-template-library.md#itl-plugin-notification-command) template.
1200 object NotificationCommand "mail-service-notification" {
1201 command = [ SysconfDir + "/icinga2/scripts/mail-service-notification.sh" ]
1206 value = "$notification_address$"
1208 "-6" = "$notification_address6$"
1209 "-b" = "$notification_author$"
1210 "-c" = "$notification_comment$"
1213 value = "$notification_date$"
1217 value = "$notification_servicename$"
1220 value = "$notification_from$"
1221 description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
1223 "-i" = "$notification_icingaweb2url$"
1226 value = "$notification_hostname$"
1230 value = "$notification_hostdisplayname$"
1234 value = "$notification_serviceoutput$"
1238 value = "$notification_useremail$"
1242 value = "$notification_servicestate$"
1246 value = "$notification_type$"
1250 value = "$notification_servicedisplayname$"
1252 "-v" = "$notification_logtosyslog$"
1256 notification_address = "$address$"
1257 notification_address6 = "$address6$"
1258 notification_author = "$notification.author$"
1259 notification_comment = "$notification.comment$"
1260 notification_type = "$notification.type$"
1261 notification_date = "$icinga.long_date_time$"
1262 notification_hostname = "$host.name$"
1263 notification_hostdisplayname = "$host.display_name$"
1264 notification_servicename = "$service.name$"
1265 notification_serviceoutput = "$service.output$"
1266 notification_servicestate = "$service.state$"
1267 notification_useremail = "$user.email$"
1268 notification_servicedisplayname = "$service.display_name$"
1273 Configuration Attributes:
1275 Name | Type | Description
1276 --------------------------|-----------------------|----------------------------------
1277 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.
1278 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1279 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
1280 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
1281 arguments | Dictionary | **Optional.** A dictionary of command arguments.
1283 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
1285 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
1287 ## NotificationComponent <a id="objecttype-notificationcomponent"></a>
1289 The notification component is responsible for sending notifications.
1290 This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature).
1295 library "notification"
1297 object NotificationComponent "notification" { }
1300 Configuration Attributes:
1302 Name | Type | Description
1303 --------------------------|-----------------------|----------------------------------
1304 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".
1306 ## OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1308 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1309 This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer).
1316 object OpenTsdbWriter "opentsdb" {
1322 Configuration Attributes:
1324 Name | Type | Description
1325 --------------------------|-----------------------|----------------------------------
1326 host | String | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`.
1327 port | Number | **Optional.** OpenTSDB port. Defaults to `4242`.
1330 ## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1332 Writes check result performance data to a defined path using macro
1333 pattern consisting of custom attributes and runtime macros.
1334 This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files).
1341 object PerfdataWriter "perfdata" {
1342 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1344 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1346 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$"
1347 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$"
1349 rotation_interval = 15s
1353 Configuration Attributes:
1355 Name | Type | Description
1356 --------------------------|-----------------------|----------------------------------
1357 host\_perfdata\_path | String | **Optional.** Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
1358 service\_perfdata\_path | String | **Optional.** Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
1359 host\_temp\_path | String | **Optional.** Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
1360 service\_temp\_path | String | **Optional.** Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
1361 host\_format\_template | String | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1362 service\_format\_template | String | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1363 rotation\_interval | Duration | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`.
1365 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1366 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1369 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
1371 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1375 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1376 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1377 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1378 > type for `Host` or `Service`.
1379 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
1384 object ScheduledDowntime "some-downtime" {
1385 host_name = "localhost"
1386 service_name = "ping4"
1388 author = "icingaadmin"
1389 comment = "Some comment"
1395 "sunday" = "02:00-03:00"
1400 Configuration Attributes:
1402 Name | Type | Description
1403 --------------------------|-----------------------|----------------------------------
1404 host\_name | Object name | **Required.** The name of the host this scheduled downtime belongs to.
1405 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.
1406 author | String | **Required.** The author of the downtime.
1407 comment | String | **Required.** A comment for the downtime.
1408 fixed | Boolean | **Optional.** Whether this is a fixed downtime. Defaults to `true`.
1409 duration | Duration | **Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1410 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1412 ScheduledDowntime objects have composite names, i.e. their names are based
1413 on the `host_name` and `service_name` attributes and the
1414 name you specified. This means you can define more than one object
1415 with the same (short) name as long as one of the `host_name` and
1416 `service_name` attributes has a different value.
1419 ## Service <a id="objecttype-service"></a>
1421 Service objects describe network services and how they should be checked
1426 > Rather than creating a `Service` object for a specific host it is usually easier
1427 > to just create a `Service` template and use the `apply` keyword to assign the
1428 > service to a number of hosts.
1429 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
1434 object Service "uptime" {
1435 host_name = "localhost"
1437 display_name = "localhost Uptime"
1439 check_command = "snmp"
1441 vars.snmp_community = "public"
1442 vars.snmp_oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1444 check_interval = 60s
1445 retry_interval = 15s
1447 groups = [ "all-services", "snmp" ]
1451 Configuration Attributes:
1453 Name | Type | Description
1454 --------------------------|-----------------------|----------------------------------
1455 display\_name | String | **Optional.** A short description of the service.
1456 host\_name | Object name | **Required.** The host this service belongs to. There must be a `Host` object with that name.
1457 groups | Array of object names | **Optional.** The service groups this service belongs to.
1458 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this service.
1459 check\_command | Object name | **Required.** The name of the check command.
1460 max\_check\_attempts | Number | **Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1461 check\_period | Object name | **Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1462 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
1463 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`.
1464 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`.
1465 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to `true`.
1466 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to `true`.
1467 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to `true`.
1468 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to `true`.
1469 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to `false`.
1470 flapping\_threshold\_high | Number | **Optional.** Flapping upper bound in percent for a service to be considered flapping. `30.0`
1471 flapping\_threshold\_low | Number | **Optional.** Flapping lower bound in percent for a service to be considered not flapping. `25.0`
1472 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to `true`.
1473 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.
1474 volatile | Boolean | **Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur. Defaults to `false`.
1475 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.
1476 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.
1477 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
1478 notes | String | **Optional.** Notes for the service.
1479 notes\_url | String | **Optional.** URL for notes for the service (for example, in notification commands).
1480 action\_url | String | **Optional.** URL for actions for the service (for example, an external graphing tool).
1481 icon\_image | String | **Optional.** Icon image for the service. Used by external interfaces only.
1482 icon\_image\_alt | String | **Optional.** Icon image description for the service. Used by external interface only.
1484 Service objects have composite names, i.e. their names are based on the host\_name attribute and the name you specified. This means
1485 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1487 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
1488 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
1492 Name | Type | Description
1493 --------------------------|-----------------------|----------------------------------
1494 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
1495 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
1496 check\_attempt | Number | The current check attempt number.
1497 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1498 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1499 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1500 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
1501 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
1502 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
1503 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1504 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1505 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1506 downtime\_depth | Number | Whether the service has one or more active downtimes.
1507 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
1508 flapping\_current | Number | Current flapping value in percent (see flapping\_thresholds)
1509 flapping | Boolean | Whether the host is flapping between states.
1510 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1511 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1512 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1513 last\_state\_ok | Timestamp | When the last OK state occurred (as a UNIX timestamp).
1514 last\_state\_warning | Timestamp | When the last WARNING state occurred (as a UNIX timestamp).
1515 last\_state\_critical | Timestamp | When the last CRITICAL state occurred (as a UNIX timestamp).
1516 last\_state\_unknown | Timestamp | When the last UNKNOWN state occurred (as a UNIX timestamp).
1519 ## ServiceGroup <a id="objecttype-servicegroup"></a>
1521 A group of services.
1525 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
1530 object ServiceGroup "snmp" {
1531 display_name = "SNMP services"
1535 Configuration Attributes:
1537 Name | Type | Description
1538 --------------------------|-----------------------|----------------------------------
1539 display\_name | String | **Optional.** A short description of the service group.
1540 groups | Array of object names | **Optional.** An array of nested group names.
1543 ## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1545 Periodically writes status and configuration data files which are used by third-party tools.
1546 This configuration object is available as [statusdata feature](14-features.md#status-data).
1553 object StatusDataWriter "status" {
1554 status_path = "/var/cache/icinga2/status.dat"
1555 objects_path = "/var/cache/icinga2/objects.cache"
1556 update_interval = 30s
1560 Configuration Attributes:
1562 Name | Type | Description
1563 --------------------------|-----------------------|----------------------------------
1564 status\_path | String | **Optional.** Path to the `status.dat` file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
1565 objects\_path | String | **Optional.** Path to the `objects.cache` file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
1566 update\_interval | Duration | **Optional.** The interval in which the status files are updated. Defaults to `15s`.
1569 ## SyslogLogger <a id="objecttype-sysloglogger"></a>
1571 Specifies Icinga 2 logging to syslog.
1572 This configuration object is available as `syslog` [logging feature](14-features.md#logging).
1577 object SyslogLogger "syslog" {
1578 severity = "warning"
1582 Configuration Attributes:
1584 Name | Type | Description
1585 --------------------------|-----------------------|----------------------------------
1586 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1587 facility | String | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`.
1591 Name | Facility | Description
1592 ---------------------|---------------|----------------
1593 FacilityAuth | LOG\_AUTH | The authorization system.
1594 FacilityAuthPriv | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals.
1595 FacilityCron | LOG\_CRON | The cron daemon.
1596 FacilityDaemon | LOG\_DAEMON | System daemons that are not provided for explicitly by other facilities.
1597 FacilityFtp | LOG\_FTP | The file transfer protocol daemons.
1598 FacilityKern | LOG\_KERN | Messages generated by the kernel. These cannot be generated by any user processes.
1599 FacilityLocal0 | LOG\_LOCAL0 | Reserved for local use.
1600 FacilityLocal1 | LOG\_LOCAL1 | Reserved for local use.
1601 FacilityLocal2 | LOG\_LOCAL2 | Reserved for local use.
1602 FacilityLocal3 | LOG\_LOCAL3 | Reserved for local use.
1603 FacilityLocal4 | LOG\_LOCAL4 | Reserved for local use.
1604 FacilityLocal5 | LOG\_LOCAL5 | Reserved for local use.
1605 FacilityLocal6 | LOG\_LOCAL6 | Reserved for local use.
1606 FacilityLocal7 | LOG\_LOCAL7 | Reserved for local use.
1607 FacilityLpr | LOG\_LPR | The line printer spooling system.
1608 FacilityMail | LOG\_MAIL | The mail system.
1609 FacilityNews | LOG\_NEWS | The network news system.
1610 FacilitySyslog | LOG\_SYSLOG | Messages generated internally by syslogd.
1611 FacilityUser | LOG\_USER | Messages generated by user processes. This is the default facility identifier if none is specified.
1612 FacilityUucp | LOG\_UUCP | The UUCP system.
1614 ## TimePeriod <a id="objecttype-timeperiod"></a>
1616 Time periods can be used to specify when hosts/services should be checked or to limit
1617 when notifications should be sent out.
1621 > Icinga 2 versions < 2.6.0 require the import of the [legacy-timeperiod](10-icinga-template-library.md#itl-legacy-timeperiod) template.
1626 object TimePeriod "nonworkhours" {
1627 display_name = "Icinga 2 TimePeriod for non working hours"
1630 monday = "00:00-8:00,17:00-24:00"
1631 tuesday = "00:00-8:00,17:00-24:00"
1632 wednesday = "00:00-8:00,17:00-24:00"
1633 thursday = "00:00-8:00,17:00-24:00"
1634 friday = "00:00-8:00,16:00-24:00"
1635 saturday = "00:00-24:00"
1636 sunday = "00:00-24:00"
1640 object TimePeriod "exampledays" {
1641 display_name = "Icinga 2 TimePeriod for random example days"
1644 //We still believe in Santa, no peeking!
1645 //Applies every 25th of December every year
1646 "december 25" = "00:00-24:00"
1648 //Any point in time can be specified,
1649 //but you still have to use a range
1650 "2038-01-19" = "03:13-03:15"
1652 //Evey 3rd day from the second monday of February
1653 //to 8th of November
1654 "monday 2 february - november 8 / 3" = "00:00-24:00"
1659 Additional examples can be found [here](08-advanced-topics.md#timeperiods).
1661 Configuration Attributes:
1663 Name | Type | Description
1664 --------------------------|-----------------------|----------------------------------
1665 display\_name | String | **Optional.** A short description of the time period.
1666 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1667 prefer\_includes | Boolean | **Optional.** Whether to prefer timeperiods `includes` or `excludes`. Default to true.
1668 excludes | Array of object names | **Optional.** An array of timeperiods, which should exclude from your timerange.
1669 includes | Array of object names | **Optional.** An array of timeperiods, which should include into your timerange
1674 Name | Type | Description
1675 --------------------------|-----------------------|----------------------------------
1676 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1679 ## User <a id="objecttype-user"></a>
1686 object User "icingaadmin" {
1687 display_name = "Icinga 2 Admin"
1688 groups = [ "icingaadmins" ]
1689 email = "icinga@localhost"
1690 pager = "icingaadmin@localhost.localdomain"
1694 states = [ OK, Warning, Critical, Unknown ]
1695 types = [ Problem, Recovery ]
1697 vars.additional_notes = "This is the Icinga 2 Admin account."
1701 Available notification state filters:
1710 Available notification type filters:
1722 Configuration Attributes:
1724 Name | Type | Description
1725 --------------------------|-----------------------|----------------------------------
1726 display\_name | String | **Optional.** A short description of the user.
1727 email | String | **Optional.** An email string for this user. Useful for notification commands.
1728 pager | String | **Optional.** A pager string for this user. Useful for notification commands.
1729 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this user.
1730 groups | Array of object names | **Optional.** An array of group names.
1731 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled for this user.
1732 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.
1733 types | Array | **Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
1734 states | Array | **Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
1738 Name | Type | Description
1739 --------------------------|-----------------------|----------------------------------
1740 last\_notification | Timestamp | When the last notification was sent for this user (as a UNIX timestamp).
1742 ## UserGroup <a id="objecttype-usergroup"></a>
1748 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
1753 object UserGroup "icingaadmins" {
1754 display_name = "Icinga 2 Admin Group"
1758 Configuration Attributes:
1760 Name | Type | Description
1761 --------------------------|-----------------------|----------------------------------
1762 display\_name | String | **Optional.** A short description of the user group.
1763 groups | Array of object names | **Optional.** An array of nested group names.
1766 ## Zone <a id="objecttype-zone"></a>
1768 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1769 Please read the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring) for additional details.
1773 object Zone "master" {
1774 endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]
1778 object Zone "satellite" {
1779 endpoints = [ "icinga2-satellite1.localdomain" ]
1784 Configuration Attributes:
1786 Name | Type | Description
1787 --------------------------|-----------------------|----------------------------------
1788 endpoints | Array of object names | **Optional.** Array of endpoint names located in this zone.
1789 parent | Object name | **Optional.** The name of the parent zone.
1790 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`.
1792 Zone objects cannot currently be created with the API.