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 cert_path = LocalStateDir + "/lib/icinga2/certs/" + NodeName + ".crt"
45 key_path = LocalStateDir + "/lib/icinga2/certs/" + NodeName + ".key"
46 ca_path = LocalStateDir + "/lib/icinga2/certs/ca.crt"
48 ticket_salt = TicketSalt
52 Configuration Attributes:
54 Name | Type | Description
55 --------------------------------------|-----------------------|----------------------------------
56 cert\_path | String | **Required.** Path to the public key.
57 key\_path | String | **Required.** Path to the private key.
58 ca\_path | String | **Required.** Path to the CA certificate file.
59 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.
60 crl\_path | String | **Optional.** Path to the CRL file.
61 bind\_host | String | **Optional.** The IP address the api listener should be bound to. Defaults to `0.0.0.0`.
62 bind\_port | Number | **Optional.** The port the api listener should be bound to. Defaults to `5665`.
63 accept\_config | Boolean | **Optional.** Accept zone configuration. Defaults to `false`.
64 accept\_commands | Boolean | **Optional.** Accept remote commands. Defaults to `false`.
65 cipher\_list | String | **Optional.** Cipher list that is allowed.
66 tls\_protocolmin | String | **Optional.** Minimum TLS protocol version. Must be one of `TLSv1`, `TLSv1.1` or `TLSv1.2`. Defaults to `TLSv1`.
67 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)
68 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)
69 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)
70 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)
72 ## ApiUser <a id="objecttype-apiuser"></a>
74 ApiUser objects are used for authentication against the [Icinga 2 API](12-icinga2-api.md#icinga2-api-authentication).
79 object ApiUser "root" {
80 password = "mysecretapipassword"
85 Configuration Attributes:
87 Name | Type | Description
88 --------------------------|-----------------------|----------------------------------
89 password | String | **Optional.** Password string. Note: This attribute is hidden in API responses.
90 client\_cn | String | **Optional.** Client Common Name (CN).
91 permissions | Array | **Required.** Array of permissions. Either as string or dictionary with the keys `permission` and `filter`. The latter must be specified as function.
93 Available permissions are explained in the [API permissions](12-icinga2-api.md#icinga2-api-permissions)
96 ## CheckCommand <a id="objecttype-checkcommand"></a>
98 A check command definition. Additional default command custom attributes can be
103 > Icinga 2 versions < 2.6.0 require the import of the [plugin-check-command](10-icinga-template-library.md#itl-plugin-check-command) template.
108 object CheckCommand "http" {
109 command = [ PluginDir + "/check_http" ]
112 "-H" = "$http_vhost$"
113 "-I" = "$http_address$"
117 set_if = "$http_ssl$"
120 set_if = "$http_sni$"
123 value = "$http_auth_pair$"
124 description = "Username:password on sites with basic authentication"
127 set_if = "$http_ignore_body$"
129 "-r" = "$http_expect_body_regex$"
130 "-w" = "$http_warn_time$"
131 "-c" = "$http_critical_time$"
132 "-e" = "$http_expect$"
135 vars.http_address = "$address$"
136 vars.http_ssl = false
137 vars.http_sni = false
141 Configuration Attributes:
143 Name | Type | Description
144 --------------------------|-----------------------|----------------------------------
145 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.
146 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
147 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
148 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
149 arguments | Dictionary | **Optional.** A dictionary of command arguments.
152 ### CheckCommand Arguments <a id="objecttype-checkcommand-arguments"></a>
154 Command arguments can be defined as key-value-pairs in the `arguments`
155 dictionary. If the argument requires additional configuration, for example
156 a `description` attribute or an optional condition, the value can be defined
157 as dictionary specifying additional options.
162 vars.x_val = "My command argument value."
172 key = "-Xnew" /* optional, set a new key identifier */
173 description = "My plugin requires this argument for doing X."
174 required = false /* optional, no error if not set */
175 skip_key = false /* always use "-X <value>" */
176 set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
177 order = -1 /* first position */
178 repeat_key = true /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
182 description = "My plugin requires this argument for doing Y."
183 required = false /* optional, no error if not set */
184 skip_key = true /* don't prefix "-Y" only use "<value>" */
185 set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
186 order = 0 /* second position */
187 repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
192 Name | Type | Description
193 --------------------------|-----------------------|----------------------------------
194 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).
195 key | String | Optional argument key overriding the key identifier.
196 description | String | Optional argument description.
197 required | Boolean | Required argument. Execution error if not set. Defaults to false (optional).
198 skip\_key | Boolean | Use the value as argument and skip the key.
199 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.
200 order | Number | Set if multiple arguments require a defined argument order.
201 repeat\_key | Boolean | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
206 ..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...
209 Argument array with `repeat_key = true`:
212 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'
215 Argument array with `repeat_key = false`:
218 'key' 'value[0]' 'value[1]' 'value[2]'
221 ## CheckerComponent <a id="objecttype-checkcomponent"></a>
223 The checker component is responsible for scheduling active checks.
224 This configuration object is available as [checker feature](11-cli-commands.md#cli-command-feature).
231 object CheckerComponent "checker" {
232 concurrent_checks = 512
236 Configuration Attributes:
238 Name | Type | Description
239 --------------------------|-----------------------|----------------------------------
240 concurrent\_checks | Number | **Optional.** The maximum number of concurrent checks. Defaults to 512.
242 ## CheckResultReader <a id="objecttype-checkresultreader"></a>
244 Reads Icinga 1.x check result files from a directory. This functionality is provided
245 to help existing Icinga 1.x users and might be useful for migration scenarios.
252 object CheckResultReader "reader" {
253 spool_dir = "/data/check-results"
257 Configuration Attributes:
259 Name | Type | Description
260 --------------------------|-----------------------|----------------------------------
261 spool\_dir | String | **Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/".
263 ## Comment <a id="objecttype-comment"></a>
265 Comments created at runtime are represented as objects.
266 Note: This is for reference only. You can create comments
267 with the [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) API action.
272 object Comment "localhost!my-comment" {
273 host_name = "localhost"
274 author = "icingaadmin"
275 text = "This is a comment."
279 Configuration Attributes:
281 Name | Type | Description
282 --------------------------|-----------------------|----------------------------------
283 host\_name | Object name | **Required.** The name of the host this comment belongs to.
284 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.
285 author | String | **Required.** The author's name.
286 text | String | **Required.** The comment text.
287 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this comment was added.
288 entry\_type | Number | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
289 expire\_time | Timestamp | **Optional.** The comment's expire time as UNIX timestamp.
290 persistent | Boolean | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
292 ## CompatLogger <a id="objecttype-compatlogger"></a>
294 Writes log files in a format that's compatible with Icinga 1.x.
295 This configuration object is available as [compatlog feature](14-features.md#compat-logging).
302 object CompatLogger "compatlog" {
303 log_dir = "/var/log/icinga2/compat"
304 rotation_method = "DAILY"
308 Configuration Attributes:
310 Name | Type | Description
311 --------------------------|-----------------------|----------------------------------
312 log\_dir | String | **Optional.** Path to the compat log directory. Defaults to LocalStateDir + "/log/icinga2/compat".
313 rotation\_method | String | **Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
316 ## Dependency <a id="objecttype-dependency"></a>
318 Dependency objects are used to specify dependencies between hosts and services. Dependencies
319 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
324 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
325 > to just create a `Dependency` template and use the `apply` keyword to assign the
326 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
327 > type for `Host` or `Service`.
328 > Check the [dependencies](03-monitoring-basics.md#dependencies) chapter for detailed examples.
330 Service-to-Service Example:
333 object Dependency "webserver-internet" {
334 parent_host_name = "internet"
335 parent_service_name = "ping4"
337 child_host_name = "webserver"
338 child_service_name = "ping4"
340 states = [ OK, Warning ]
342 disable_checks = true
346 Host-to-Host Example:
349 object Dependency "webserver-internet" {
350 parent_host_name = "internet"
352 child_host_name = "webserver"
356 disable_checks = true
360 Configuration Attributes:
362 Name | Type | Description
363 --------------------------|-----------------------|----------------------------------
364 parent\_host\_name | Object name | **Required.** The parent host.
365 parent\_service\_name | Object name | **Optional.** The parent service. If omitted, this dependency object is treated as host dependency.
366 child\_host\_name | Object name | **Required.** The child host.
367 child\_service\_name | Object name | **Optional.** The child service. If omitted, this dependency object is treated as host dependency.
368 disable\_checks | Boolean | **Optional.** Whether to disable checks when this dependency fails. Defaults to false.
369 disable\_notifications | Boolean | **Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
370 ignore\_soft\_states | Boolean | **Optional.** Whether to ignore soft states for the reachability calculation. Defaults to true.
371 period | Object name | **Optional.** Time period object during which this dependency is enabled.
372 states | Array | **Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
374 Available state filters:
383 When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
384 automatically determined by Icinga 2.
386 Service-to-Host Dependency Example:
389 apply Dependency "internet" to Service {
390 parent_host_name = "dsl-router"
391 disable_checks = true
393 assign where host.name != "dsl-router"
397 This example sets all service objects matching the assign condition into a dependency relation to
398 the parent host object `dsl-router` as implicit child services.
400 Service-to-Service-on-the-same-Host Dependency Example:
403 apply Dependency "disable-agent-checks" to Service {
404 parent_service_name = "agent-health"
406 assign where service.check_command == "ssh"
407 ignore where service.name == "agent-health"
411 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
412 host object matched by the apply rule condition. All services where apply matches are made implicit child services
413 in this dependency relation.
416 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
417 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
418 `child_service_name` attributes has a different value.
420 ## Downtime <a id="objecttype-downtime"></a>
422 Downtimes created at runtime are represented as objects.
423 You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action.
428 object Downtime "localhost!my-downtime" {
429 host_name = "localhost"
430 author = "icingaadmin"
431 comment = "This is a downtime."
432 start_time = 1505312869
433 end_time = 1505312924
437 Configuration Attributes:
439 Name | Type | Description
440 --------------------------|-----------------------|----------------------------------
441 host\_name | Object name | **Required.** The name of the host this comment belongs to.
442 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.
443 author | String | **Required.** The author's name.
444 comment | String | **Required.** The comment text.
445 start\_time | Timestamp | **Required.** The start time as UNIX timestamp.
446 end\_time | Timestamp | **Required.** The end time as UNIX timestamp.
447 duration | Number | **Optional.** The duration as number.
448 entry\_time | Timestamp | **Optional.** The UNIX timestamp when this downtime was added.
449 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).
450 triggers | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime.
454 Name | Type | Description
455 --------------------------|-----------------------|----------------------------------
456 trigger\_time | Timestamp | The UNIX timestamp when this downtime was triggered.
457 triggered\_by | Object name | The name of the downtime this downtime was triggered by.
460 ## ElasticWriter <a id="objecttype-elasticwriter"></a>
462 Writes check result metrics and performance data to an Elasticsearch instance.
463 This configuration object is available as [elastic feature](14-features.md#elastic-writer).
470 object ElasticWriter "elastic" {
475 enable_send_perfdata = true
477 flush_threshold = 1024
482 The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
484 Configuration Attributes:
486 Name | Type | Description
487 --------------------------|-----------------------|----------------------------------
488 host | String | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
489 port | Number | **Required.** Elasticsearch port. Defaults to `9200`.
490 index | String | **Required.** Elasticsearch index name. Defaults to `icinga2`.
491 enable\_send\_perfdata | Boolean | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
492 flush\_interval | Duration | **Optional.** How long to buffer data points before transfering to Elasticsearch. Defaults to `10s`.
493 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to `1024`.
494 username | String | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
495 password | String | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
496 enable\_tls | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
497 ca\_path | String | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
498 cert\_path | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
499 key\_path | String | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
501 Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
502 Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
504 Basic auth is supported with the `username` and `password` attributes. This requires an
505 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/)
508 TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
509 you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
511 ## Endpoint <a id="objecttype-endpoint"></a>
513 Endpoint objects are used to specify connection information for remote
514 Icinga 2 instances. More details can be found in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
519 object Endpoint "icinga2-client1.localdomain" {
520 host = "192.168.56.111"
526 Example (disable replay log):
529 object Endpoint "icinga2-client1.localdomain" {
530 host = "192.168.5.111"
536 Configuration Attributes:
538 Name | Type | Description
539 --------------------------|-----------------------|----------------------------------
540 host | String | **Optional.** The hostname/IP address of the remote Icinga 2 instance.
541 port | Number | **Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
542 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.
544 Endpoint objects cannot currently be created with the API.
546 ## EventCommand <a id="objecttype-eventcommand"></a>
548 An event command definition.
552 > Icinga 2 versions < 2.6.0 require the import of the [plugin-event-command](10-icinga-template-library.md#itl-plugin-event-command) template.
557 object EventCommand "restart-httpd-event" {
558 command = "/opt/bin/restart-httpd.sh"
563 Configuration Attributes:
565 Name | Type | Description
566 --------------------------|-----------------------|----------------------------------
567 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.
568 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
569 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
570 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
571 arguments | Dictionary | **Optional.** A dictionary of command arguments.
573 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
575 More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
577 ## ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
579 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
580 This configuration object is available as [command feature](14-features.md#external-commands).
587 object ExternalCommandListener "command" {
588 command_path = "/var/run/icinga2/cmd/icinga2.cmd"
592 Configuration Attributes:
594 Name | Type | Description
595 --------------------------|-----------------------|----------------------------------
596 command\_path | String | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
600 ## FileLogger <a id="objecttype-filelogger"></a>
602 Specifies Icinga 2 logging to a file.
603 This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging).
608 object FileLogger "debug-file" {
610 path = "/var/log/icinga2/debug.log"
614 Configuration Attributes:
616 Name | Type | Description
617 --------------------------|-----------------------|----------------------------------
618 path | String | **Required.** The log path.
619 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
622 ## GelfWriter <a id="objecttype-gelfwriter"></a>
624 Writes event log entries to a defined GELF receiver host (Graylog, Logstash).
625 This configuration object is available as [gelf feature](14-features.md#gelfwriter).
632 object GelfWriter "gelf" {
638 Configuration Attributes:
640 Name | Type | Description
641 --------------------------|-----------------------|----------------------------------
642 host | String | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`.
643 port | Number | **Optional.** GELF receiver port. Defaults to `12201`.
644 source | String | **Optional.** Source name for this instance. Defaults to `icinga2`.
645 enable\_send\_perfdata | Boolean | **Optional.** Enable performance data for 'CHECK RESULT' events.
648 ## GraphiteWriter <a id="objecttype-graphitewriter"></a>
650 Writes check result metrics and performance data to a defined
651 Graphite Carbon host.
652 This configuration object is available as [graphite feature](14-features.md#graphite-carbon-cache-writer).
659 object GraphiteWriter "graphite" {
665 Configuration Attributes:
667 Name | Type | Description
668 --------------------------|-----------------------|----------------------------------
669 host | String | **Optional.** Graphite Carbon host address. Defaults to `127.0.0.1`.
670 port | Number | **Optional.** Graphite Carbon port. Defaults to `2003`.
671 host\_name\_template | String | **Optional.** Metric prefix for host name. Defaults to `icinga2.$host.name$.host.$host.check_command$`.
672 service\_name\_template | String | **Optional.** Metric prefix for service name. Defaults to `icinga2.$host.name$.services.$service.name$.$service.check_command$`.
673 enable\_send\_thresholds | Boolean | **Optional.** Send additional threshold metrics. Defaults to `false`.
674 enable\_send\_metadata | Boolean | **Optional.** Send additional metadata metrics. Defaults to `false`.
676 Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
680 ## Host <a id="objecttype-host"></a>
687 object Host "icinga2-client1.localdomain" {
688 display_name = "Linux Client 1"
689 address = "192.168.56.111"
690 address6 = "2a00:1450:4001:815::2003"
692 groups = [ "linux-servers" ]
694 check_command = "hostalive"
698 Configuration Attributes:
700 Name | Type | Description
701 --------------------------|-----------------------|----------------------------------
702 display\_name | String | **Optional.** A short description of the host (e.g. displayed by external interfaces instead of the name if set).
703 address | String | **Optional.** The host's IPv4 address. Available as command runtime macro `$address$` if set.
704 address6 | String | **Optional.** The host's IPv6 address. Available as command runtime macro `$address6$` if set.
705 groups | Array of object names | **Optional.** A list of host groups this host belongs to.
706 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this host.
707 check\_command | Object name | **Required.** The name of the check command.
708 max\_check\_attempts | Number | **Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
709 check\_period | Object name | **Optional.** The name of a time period which determines when this host should be checked. Not set by default.
710 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
711 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`.
712 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`.
713 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to true.
714 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to true.
715 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to true.
716 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to true.
717 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to false.
718 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to true.
719 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.
720 flapping\_threshold | Number | **Optional.** The flapping threshold in percent when a host is considered to be flapping.
721 volatile | Boolean | **Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur. Defaults to false.
722 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.
723 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
724 notes | String | **Optional.** Notes for the host.
725 notes\_url | String | **Optional.** URL for notes for the host (for example, in notification commands).
726 action\_url | String | **Optional.** URL for actions for the host (for example, an external graphing tool).
727 icon\_image | String | **Optional.** Icon image for the host. Used by external interfaces only.
728 icon\_image\_alt | String | **Optional.** Icon image description for the host. Used by external interface only.
730 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
731 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
735 > The `address` and `address6` attributes are required for running commands using
736 > the `$address$` and `$address6$` runtime macros.
740 Name | Type | Description
741 --------------------------|-----------------------|----------------------------------
742 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
743 last\_check | Timestamp | When the last check occured (as a UNIX timestamp).
744 check\_attempt | Number | The current check attempt number.
745 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
746 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
747 last\_reachable | Boolean | Whether the host was reachable when the last check occurred.
748 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
749 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
750 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
751 last\_in\_downtime | Boolean | Whether the host was in a downtime when the last check occurred.
752 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
753 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
754 downtime\_depth | Number | Whether the host has one or more active downtimes.
755 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
756 flapping | Boolean | Whether the host is flapping between states.
757 state | Number | The current state (0 = UP, 1 = DOWN).
758 last\_state | Number | The previous state (0 = UP, 1 = DOWN).
759 last\_hard\_state | Number | The last hard state (0 = UP, 1 = DOWN).
760 last\_state\_up | Timestamp | When the last UP state occurred (as a UNIX timestamp).
761 last\_state\_down | Timestamp | When the last DOWN state occurred (as a UNIX timestamp).
765 ## HostGroup <a id="objecttype-hostgroup"></a>
771 > Assign host group members using the [group assign](17-language-reference.md#group-assign) rules.
776 object HostGroup "linux-servers" {
777 display_name = "Linux Servers"
779 assign where host.vars.os == "Linux"
783 Configuration Attributes:
785 Name | Type | Description
786 --------------------------|-----------------------|----------------------------------
787 display\_name | String | **Optional.** A short description of the host group.
788 groups | Array of object names | **Optional.** An array of nested group names.
790 ## IcingaApplication <a id="objecttype-icingaapplication"></a>
792 The IcingaApplication object is required to start Icinga 2.
793 The object name must be `app`. If the object configuration
794 is missing, Icinga 2 will automatically create an IcingaApplication
800 object IcingaApplication "app" {
801 enable_perfdata = false
805 Configuration Attributes:
807 Name | Type | Description
808 --------------------------|-----------------------|----------------------------------
809 enable\_notifications | Boolean | **Optional.** Whether notifications are globally enabled. Defaults to true.
810 enable\_event\_handlers | Boolean | **Optional.** Whether event handlers are globally enabled. Defaults to true.
811 enable\_flapping | Boolean | **Optional.** Whether flap detection is globally enabled. Defaults to true.
812 enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true.
813 enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true.
814 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true.
815 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally.
817 ## IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
819 IDO database adapter for MySQL.
820 This configuration object is available as [ido-mysql feature](14-features.md#db-ido).
825 library "db_ido_mysql"
827 object IdoMysqlConnection "mysql-ido" {
835 downtimehistory_age = 48h
836 contactnotifications_age = 31d
841 Configuration Attributes:
843 Name | Type | Description
844 --------------------------|-----------------------|----------------------------------
845 host | String | **Optional.** MySQL database host address. Defaults to `localhost`.
846 port | Number | **Optional.** MySQL database port. Defaults to `3306`.
847 socket\_path | String | **Optional.** MySQL socket path.
848 user | String | **Optional.** MySQL database user with read/write permission to the icinga database. Defaults to `icinga`.
849 password | String | **Optional.** MySQL database user's password. Defaults to `icinga`.
850 database | String | **Optional.** MySQL database name. Defaults to `icinga`.
851 enable\_ssl | Boolean | **Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
852 ssl\_key | String | **Optional.** MySQL SSL client key file path.
853 ssl\_cert | String | **Optional.** MySQL SSL certificate file path.
854 ssl\_ca | String | **Optional.** MySQL SSL certificate authority certificate file path.
855 ssl\_capath | String | **Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
856 ssl\_cipher | String | **Optional.** MySQL SSL list of allowed ciphers.
857 table\_prefix | String | **Optional.** MySQL database table prefix. Defaults to `icinga_`.
858 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
859 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
860 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".
861 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`.
862 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
863 categories | Array | **Optional.** Array of information types that should be written to the database.
867 Name | Type | Description
868 --------------------------------|-----------------------|----------------------------------
869 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
870 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
871 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
872 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
873 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
874 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
875 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
876 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
877 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
878 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
879 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
880 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
881 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
882 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
883 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
887 Name | Description | Required by
888 ---------------------|------------------------|--------------------
889 DbCatConfig | Configuration data | Icinga Web 2
890 DbCatState | Current state data | Icinga Web 2
891 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
892 DbCatComment | Comments | Icinga Web 2
893 DbCatDowntime | Downtimes | Icinga Web 2
894 DbCatEventHandler | Event handler data | Icinga Web 2
895 DbCatExternalCommand | External commands | --
896 DbCatFlapping | Flap detection data | Icinga Web 2
897 DbCatCheck | Check results | --
898 DbCatLog | Log messages | --
899 DbCatNotification | Notifications | Icinga Web 2
900 DbCatProgramStatus | Program status data | Icinga Web 2
901 DbCatRetention | Retention data | Icinga Web 2
902 DbCatStateHistory | Historical state data | Icinga Web 2
904 The default value for `categories` includes everything required
905 by Icinga Web 2 in the table above.
907 In addition to the category flags listed above the `DbCatEverything`
908 flag may be used as a shortcut for listing all flags.
910 ## IdoPgsqlConnection <a id="objecttype-idopgsqlconnection"></a>
912 IDO database adapter for PostgreSQL.
913 This configuration object is available as [ido-pgsql feature](14-features.md#db-ido).
918 library "db_ido_pgsql"
920 object IdoPgsqlConnection "pgsql-ido" {
928 downtimehistory_age = 48h
929 contactnotifications_age = 31d
934 Configuration Attributes:
936 Name | Type | Description
937 --------------------------|-----------------------|----------------------------------
938 host | String | **Optional.** PostgreSQL database host address. Defaults to `localhost`.
939 port | Number | **Optional.** PostgreSQL database port. Defaults to `5432`.
940 user | String | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`.
941 password | String | **Optional.** PostgreSQL database user's password. Defaults to `icinga`.
942 database | String | **Optional.** PostgreSQL database name. Defaults to `icinga`.
943 table\_prefix | String | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`.
944 instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
945 instance\_description | String | **Optional.** Description for the Icinga 2 instance.
946 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".
947 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`.
948 cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
949 categories | Array | **Optional.** Array of information types that should be written to the database.
953 Name | Type | Description
954 --------------------------------|-----------------------|----------------------------------
955 acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
956 commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
957 contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
958 contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
959 downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
960 eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
961 externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
962 flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
963 hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
964 logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
965 notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
966 processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
967 statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
968 servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
969 systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
973 Name | Description | Required by
974 ---------------------|------------------------|--------------------
975 DbCatConfig | Configuration data | Icinga Web 2
976 DbCatState | Current state data | Icinga Web 2
977 DbCatAcknowledgement | Acknowledgements | Icinga Web 2
978 DbCatComment | Comments | Icinga Web 2
979 DbCatDowntime | Downtimes | Icinga Web 2
980 DbCatEventHandler | Event handler data | Icinga Web 2
981 DbCatExternalCommand | External commands | --
982 DbCatFlapping | Flap detection data | Icinga Web 2
983 DbCatCheck | Check results | --
984 DbCatLog | Log messages | --
985 DbCatNotification | Notifications | Icinga Web 2
986 DbCatProgramStatus | Program status data | Icinga Web 2
987 DbCatRetention | Retention data | Icinga Web 2
988 DbCatStateHistory | Historical state data | Icinga Web 2
990 The default value for `categories` includes everything required
991 by Icinga Web 2 in the table above.
993 In addition to the category flags listed above the `DbCatEverything`
994 flag may be used as a shortcut for listing all flags.
996 ## InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
998 Writes check result metrics and performance data to a defined InfluxDB host.
999 This configuration object is available as [influxdb feature](14-features.md#influxdb-writer).
1006 object InfluxdbWriter "influxdb" {
1009 database = "icinga2"
1011 flush_threshold = 1024
1012 flush_interval = 10s
1015 measurement = "$host.check_command$"
1017 hostname = "$host.name$"
1020 service_template = {
1021 measurement = "$service.check_command$"
1023 hostname = "$host.name$"
1024 service = "$service.name$"
1030 Configuration Attributes:
1032 Name | Type | Description
1033 --------------------------|-----------------------|----------------------------------
1034 host | String | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
1035 port | Number | **Required.** InfluxDB HTTP port. Defaults to `8086`.
1036 database | String | **Required.** InfluxDB database name. Defaults to `icinga2`.
1037 username | String | **Optional.** InfluxDB user name. Defaults to `none`.
1038 password | String | **Optional.** InfluxDB user password. Defaults to `none`.
1039 ssl\_enable | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`.
1040 ssl\_ca\_cert | String | **Optional.** Path to CA certificate to validate the remote host.
1041 ssl\_cert | String | **Optional.** Path to host certificate to present to the remote host for mutual verification.
1042 ssl\_key | String | **Optional.** Path to host key to accompany the ssl\_cert.
1043 host\_template | String | **Required.** Host template to define the InfluxDB line protocol.
1044 service\_template | String | **Required.** Service template to define the influxDB line protocol.
1045 enable\_send\_thresholds | Boolean | **Optional.** Whether to send warn, crit, min & max tagged data.
1046 enable\_send\_metadata | Boolean | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
1047 flush\_interval | Duration | **Optional.** How long to buffer data points before transfering to InfluxDB. Defaults to `10s`.
1048 flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`.
1050 Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
1051 to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
1056 ## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
1058 Livestatus API interface available as TCP or UNIX socket. Historical table queries
1059 require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
1060 pointing to the log files using the `compat_log_path` configuration attribute.
1061 This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus).
1066 library "livestatus"
1068 object LivestatusListener "livestatus-tcp" {
1070 bind_host = "127.0.0.1"
1074 object LivestatusListener "livestatus-unix" {
1075 socket_type = "unix"
1076 socket_path = "/var/run/icinga2/cmd/livestatus"
1080 Configuration Attributes:
1082 Name | Type | Description
1083 --------------------------|-----------------------|----------------------------------
1084 socket\_type | String | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`.
1085 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`.
1086 bind\_port | Number | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`.
1087 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".
1088 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"
1092 > UNIX sockets are not supported on Windows.
1095 ## Notification <a id="objecttype-notification"></a>
1097 Notification objects are used to specify how users should be notified in case
1098 of host and service state changes and other events.
1102 > Rather than creating a `Notification` object for a specific host or service it is
1103 > usually easier to just create a `Notification` template and use the `apply` keyword
1104 > to assign the notification to a number of hosts or services. Use the `to` keyword
1105 > to set the specific target type for `Host` or `Service`.
1106 > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
1111 object Notification "localhost-ping-notification" {
1112 host_name = "localhost"
1113 service_name = "ping4"
1115 command = "mail-notification"
1117 users = [ "user1", "user2" ]
1119 types = [ Problem, Recovery ]
1123 Configuration Attributes:
1125 Name | Type | Description
1126 --------------------------|-----------------------|----------------------------------
1127 host\_name | Object name | **Required.** The name of the host this notification belongs to.
1128 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.
1129 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
1130 users | Array of object names | **Optional.** A list of user names who should be notified.
1131 user\_groups | Array of object names | **Optional.** A list of user group names who should be notified.
1132 times | Dictionary | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
1133 command | Object name | **Required.** The name of the notification command which should be executed when the notification is triggered.
1134 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.
1135 period | Object name | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
1136 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.
1137 types | Array | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
1138 states | Array | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
1140 Available notification state filters for Service:
1147 Available notification state filters for Host:
1152 Available notification type filters:
1166 Name | Type | Description
1167 ----------------------------|-----------------------|-----------------
1168 last\_notification | Timestamp | When the last notification was sent for this Notification object (as a UNIX timestamp).
1169 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).
1170 notification\_number | Number | The notification number.
1171 last\_problem\_notification | Timestamp | When the last notification was sent for a problem (as a UNIX timestamp).
1174 ## NotificationCommand <a id="objecttype-notificationcommand"></a>
1176 A notification command definition.
1180 > Icinga 2 versions < 2.6.0 require the import of the [plugin-notification-command](10-icinga-template-library.md#itl-plugin-notification-command) template.
1185 object NotificationCommand "mail-service-notification" {
1186 command = [ SysconfDir + "/icinga2/scripts/mail-service-notification.sh" ]
1191 value = "$notification_address$"
1193 "-6" = "$notification_address6$"
1194 "-b" = "$notification_author$"
1195 "-c" = "$notification_comment$"
1198 value = "$notification_date$"
1202 value = "$notification_servicename$"
1205 value = "$notification_from$"
1206 description = "Set from address. Requires GNU mailutils (Debian/Ubuntu) or mailx (RHEL/SUSE)"
1208 "-i" = "$notification_icingaweb2url$"
1211 value = "$notification_hostname$"
1215 value = "$notification_hostdisplayname$"
1219 value = "$notification_serviceoutput$"
1223 value = "$notification_useremail$"
1227 value = "$notification_servicestate$"
1231 value = "$notification_type$"
1235 value = "$notification_servicedisplayname$"
1237 "-v" = "$notification_logtosyslog$"
1241 notification_address = "$address$"
1242 notification_address6 = "$address6$"
1243 notification_author = "$notification.author$"
1244 notification_comment = "$notification.comment$"
1245 notification_type = "$notification.type$"
1246 notification_date = "$icinga.long_date_time$"
1247 notification_hostname = "$host.name$"
1248 notification_hostdisplayname = "$host.display_name$"
1249 notification_servicename = "$service.name$"
1250 notification_serviceoutput = "$service.output$"
1251 notification_servicestate = "$service.state$"
1252 notification_useremail = "$user.email$"
1253 notification_servicedisplayname = "$service.display_name$"
1258 Configuration Attributes:
1260 Name | Type | Description
1261 --------------------------|-----------------------|----------------------------------
1262 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.
1263 env | Dictionary | **Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1264 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this command.
1265 timeout | Duration | **Optional.** The command timeout in seconds. Defaults to `1m`.
1266 arguments | Dictionary | **Optional.** A dictionary of command arguments.
1268 Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
1270 More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
1272 ## NotificationComponent <a id="objecttype-notificationcomponent"></a>
1274 The notification component is responsible for sending notifications.
1275 This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature).
1280 library "notification"
1282 object NotificationComponent "notification" { }
1285 Configuration Attributes:
1287 Name | Type | Description
1288 --------------------------|-----------------------|----------------------------------
1289 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".
1291 ## OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
1293 Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
1294 This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer).
1301 object OpenTsdbWriter "opentsdb" {
1307 Configuration Attributes:
1309 Name | Type | Description
1310 --------------------------|-----------------------|----------------------------------
1311 host | String | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`.
1312 port | Number | **Optional.** OpenTSDB port. Defaults to `4242`.
1315 ## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
1317 Writes check result performance data to a defined path using macro
1318 pattern consisting of custom attributes and runtime macros.
1319 This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files).
1326 object PerfdataWriter "perfdata" {
1327 host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1329 service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1331 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$"
1332 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$"
1334 rotation_interval = 15s
1338 Configuration Attributes:
1340 Name | Type | Description
1341 --------------------------|-----------------------|----------------------------------
1342 host\_perfdata\_path | String | **Optional.** Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
1343 service\_perfdata\_path | String | **Optional.** Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
1344 host\_temp\_path | String | **Optional.** Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
1345 service\_temp\_path | String | **Optional.** Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
1346 host\_format\_template | String | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1347 service\_format\_template | String | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1348 rotation\_interval | Duration | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`.
1350 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1351 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1354 ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
1356 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1360 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1361 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1362 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1363 > type for `Host` or `Service`.
1364 > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
1369 object ScheduledDowntime "some-downtime" {
1370 host_name = "localhost"
1371 service_name = "ping4"
1373 author = "icingaadmin"
1374 comment = "Some comment"
1380 "sunday" = "02:00-03:00"
1385 Configuration Attributes:
1387 Name | Type | Description
1388 --------------------------|-----------------------|----------------------------------
1389 host\_name | Object name | **Required.** The name of the host this scheduled downtime belongs to.
1390 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.
1391 author | String | **Required.** The author of the downtime.
1392 comment | String | **Required.** A comment for the downtime.
1393 fixed | Boolean | **Optional.** Whether this is a fixed downtime. Defaults to `true`.
1394 duration | Duration | **Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1395 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1397 ScheduledDowntime objects have composite names, i.e. their names are based
1398 on the `host_name` and `service_name` attributes and the
1399 name you specified. This means you can define more than one object
1400 with the same (short) name as long as one of the `host_name` and
1401 `service_name` attributes has a different value.
1404 ## Service <a id="objecttype-service"></a>
1406 Service objects describe network services and how they should be checked
1411 > Rather than creating a `Service` object for a specific host it is usually easier
1412 > to just create a `Service` template and use the `apply` keyword to assign the
1413 > service to a number of hosts.
1414 > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
1419 object Service "uptime" {
1420 host_name = "localhost"
1422 display_name = "localhost Uptime"
1424 check_command = "snmp"
1426 vars.snmp_community = "public"
1427 vars.snmp_oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
1429 check_interval = 60s
1430 retry_interval = 15s
1432 groups = [ "all-services", "snmp" ]
1436 Configuration Attributes:
1438 Name | Type | Description
1439 --------------------------|-----------------------|----------------------------------
1440 display\_name | String | **Optional.** A short description of the service.
1441 host\_name | Object name | **Required.** The host this service belongs to. There must be a `Host` object with that name.
1442 groups | Array of object names | **Optional.** The service groups this service belongs to.
1443 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this service.
1444 check\_command | Object name | **Required.** The name of the check command.
1445 max\_check\_attempts | Number | **Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
1446 check\_period | Object name | **Optional.** The name of a time period which determines when this service should be checked. Not set by default.
1447 check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
1448 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`.
1449 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`.
1450 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to `true`.
1451 enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to `true`.
1452 enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to `true`.
1453 enable\_event\_handler | Boolean | **Optional.** Enables event handlers for this host. Defaults to `true`.
1454 enable\_flapping | Boolean | **Optional.** Whether flap detection is enabled. Defaults to `false`.
1455 enable\_perfdata | Boolean | **Optional.** Whether performance data processing is enabled. Defaults to `true`.
1456 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.
1457 flapping\_threshold | Number | **Optional.** The flapping threshold in percent when a service is considered to be flapping.
1458 volatile | Boolean | **Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur. Defaults to `false`.
1459 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.
1460 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.
1461 command\_endpoint | Object name | **Optional.** The endpoint where commands are executed on.
1462 notes | String | **Optional.** Notes for the service.
1463 notes\_url | String | **Optional.** URL for notes for the service (for example, in notification commands).
1464 action\_url | String | **Optional.** URL for actions for the service (for example, an external graphing tool).
1465 icon\_image | String | **Optional.** Icon image for the service. Used by external interfaces only.
1466 icon\_image\_alt | String | **Optional.** Icon image description for the service. Used by external interface only.
1468 Service objects have composite names, i.e. their names are based on the host\_name attribute and the name you specified. This means
1469 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
1471 The actual check interval might deviate slightly from the configured values due to the fact that Icinga tries
1472 to evenly distribute all checks over a certain period of time, i.e. to avoid load spikes.
1476 Name | Type | Description
1477 --------------------------|-----------------------|----------------------------------
1478 next\_check | Timestamp | When the next check occurs (as a UNIX timestamp).
1479 last\_check | Timestamp | When the last check occurred (as a UNIX timestamp).
1480 check\_attempt | Number | The current check attempt number.
1481 state\_type | Number | The current state type (0 = SOFT, 1 = HARD).
1482 last\_state\_type | Number | The previous state type (0 = SOFT, 1 = HARD).
1483 last\_reachable | Boolean | Whether the service was reachable when the last check occurred.
1484 last\_check\_result | CheckResult | The current [check result](08-advanced-topics.md#advanced-value-types-checkresult).
1485 last\_state\_change | Timestamp | When the last state change occurred (as a UNIX timestamp).
1486 last\_hard\_state\_change | Timestamp | When the last hard state change occurred (as a UNIX timestamp).
1487 last\_in\_downtime | Boolean | Whether the service was in a downtime when the last check occurred.
1488 acknowledgement | Number | The acknowledgement type (0 = NONE, 1 = NORMAL, 2 = STICKY).
1489 acknowledgement\_expiry | Timestamp | When the acknowledgement expires (as a UNIX timestamp; 0 = no expiry).
1490 downtime\_depth | Number | Whether the service has one or more active downtimes.
1491 flapping\_last\_change | Timestamp | When the last flapping change occurred (as a UNIX timestamp).
1492 flapping | Boolean | Whether the host is flapping between states.
1493 state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1494 last\_state | Number | The previous state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1495 last\_hard\_state | Number | The last hard state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
1496 last\_state\_ok | Timestamp | When the last OK state occurred (as a UNIX timestamp).
1497 last\_state\_warning | Timestamp | When the last WARNING state occurred (as a UNIX timestamp).
1498 last\_state\_critical | Timestamp | When the last CRITICAL state occurred (as a UNIX timestamp).
1499 last\_state\_unknown | Timestamp | When the last UNKNOWN state occurred (as a UNIX timestamp).
1502 ## ServiceGroup <a id="objecttype-servicegroup"></a>
1504 A group of services.
1508 > Assign service group members using the [group assign](17-language-reference.md#group-assign) rules.
1513 object ServiceGroup "snmp" {
1514 display_name = "SNMP services"
1518 Configuration Attributes:
1520 Name | Type | Description
1521 --------------------------|-----------------------|----------------------------------
1522 display\_name | String | **Optional.** A short description of the service group.
1523 groups | Array of object names | **Optional.** An array of nested group names.
1526 ## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
1528 Periodically writes status and configuration data files which are used by third-party tools.
1529 This configuration object is available as [statusdata feature](14-features.md#status-data).
1536 object StatusDataWriter "status" {
1537 status_path = "/var/cache/icinga2/status.dat"
1538 objects_path = "/var/cache/icinga2/objects.cache"
1539 update_interval = 30s
1543 Configuration Attributes:
1545 Name | Type | Description
1546 --------------------------|-----------------------|----------------------------------
1547 status\_path | String | **Optional.** Path to the `status.dat` file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
1548 objects\_path | String | **Optional.** Path to the `objects.cache` file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
1549 update\_interval | Duration | **Optional.** The interval in which the status files are updated. Defaults to `15s`.
1552 ## SyslogLogger <a id="objecttype-sysloglogger"></a>
1554 Specifies Icinga 2 logging to syslog.
1555 This configuration object is available as `syslog` [logging feature](14-features.md#logging).
1560 object SyslogLogger "syslog" {
1561 severity = "warning"
1565 Configuration Attributes:
1567 Name | Type | Description
1568 --------------------------|-----------------------|----------------------------------
1569 severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
1570 facility | String | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`.
1574 Name | Facility | Description
1575 ---------------------|---------------|----------------
1576 FacilityAuth | LOG\_AUTH | The authorization system.
1577 FacilityAuthPriv | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals.
1578 FacilityCron | LOG\_CRON | The cron daemon.
1579 FacilityDaemon | LOG\_DAEMON | System daemons that are not provided for explicitly by other facilities.
1580 FacilityFtp | LOG\_FTP | The file transfer protocol daemons.
1581 FacilityKern | LOG\_KERN | Messages generated by the kernel. These cannot be generated by any user processes.
1582 FacilityLocal0 | LOG\_LOCAL0 | Reserved for local use.
1583 FacilityLocal1 | LOG\_LOCAL1 | Reserved for local use.
1584 FacilityLocal2 | LOG\_LOCAL2 | Reserved for local use.
1585 FacilityLocal3 | LOG\_LOCAL3 | Reserved for local use.
1586 FacilityLocal4 | LOG\_LOCAL4 | Reserved for local use.
1587 FacilityLocal5 | LOG\_LOCAL5 | Reserved for local use.
1588 FacilityLocal6 | LOG\_LOCAL6 | Reserved for local use.
1589 FacilityLocal7 | LOG\_LOCAL7 | Reserved for local use.
1590 FacilityLpr | LOG\_LPR | The line printer spooling system.
1591 FacilityMail | LOG\_MAIL | The mail system.
1592 FacilityNews | LOG\_NEWS | The network news system.
1593 FacilitySyslog | LOG\_SYSLOG | Messages generated internally by syslogd.
1594 FacilityUser | LOG\_USER | Messages generated by user processes. This is the default facility identifier if none is specified.
1595 FacilityUucp | LOG\_UUCP | The UUCP system.
1597 ## TimePeriod <a id="objecttype-timeperiod"></a>
1599 Time periods can be used to specify when hosts/services should be checked or to limit
1600 when notifications should be sent out.
1604 > Icinga 2 versions < 2.6.0 require the import of the [legacy-timeperiod](10-icinga-template-library.md#itl-legacy-timeperiod) template.
1609 object TimePeriod "nonworkhours" {
1610 display_name = "Icinga 2 TimePeriod for non working hours"
1613 monday = "00:00-8:00,17:00-24:00"
1614 tuesday = "00:00-8:00,17:00-24:00"
1615 wednesday = "00:00-8:00,17:00-24:00"
1616 thursday = "00:00-8:00,17:00-24:00"
1617 friday = "00:00-8:00,16:00-24:00"
1618 saturday = "00:00-24:00"
1619 sunday = "00:00-24:00"
1623 object TimePeriod "exampledays" {
1624 display_name = "Icinga 2 TimePeriod for random example days"
1627 //We still believe in Santa, no peeking!
1628 //Applies every 25th of December every year
1629 "december 25" = "00:00-24:00"
1631 //Any point in time can be specified,
1632 //but you still have to use a range
1633 "2038-01-19" = "03:13-03:15"
1635 //Evey 3rd day from the second monday of February
1636 //to 8th of November
1637 "monday 2 february - november 8 / 3" = "00:00-24:00"
1642 Additional examples can be found [here](08-advanced-topics.md#timeperiods).
1644 Configuration Attributes:
1646 Name | Type | Description
1647 --------------------------|-----------------------|----------------------------------
1648 display\_name | String | **Optional.** A short description of the time period.
1649 ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
1650 prefer\_includes | Boolean | **Optional.** Whether to prefer timeperiods `includes` or `excludes`. Default to true.
1651 excludes | Array of object names | **Optional.** An array of timeperiods, which should exclude from your timerange.
1652 includes | Array of object names | **Optional.** An array of timeperiods, which should include into your timerange
1657 Name | Type | Description
1658 --------------------------|-----------------------|----------------------------------
1659 is\_inside | Boolean | Whether we're currently inside this timeperiod.
1662 ## User <a id="objecttype-user"></a>
1669 object User "icingaadmin" {
1670 display_name = "Icinga 2 Admin"
1671 groups = [ "icingaadmins" ]
1672 email = "icinga@localhost"
1673 pager = "icingaadmin@localhost.localdomain"
1677 states = [ OK, Warning, Critical, Unknown ]
1678 types = [ Problem, Recovery ]
1680 vars.additional_notes = "This is the Icinga 2 Admin account."
1684 Available notification state filters:
1693 Available notification type filters:
1705 Configuration Attributes:
1707 Name | Type | Description
1708 --------------------------|-----------------------|----------------------------------
1709 display\_name | String | **Optional.** A short description of the user.
1710 email | String | **Optional.** An email string for this user. Useful for notification commands.
1711 pager | String | **Optional.** A pager string for this user. Useful for notification commands.
1712 vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this user.
1713 groups | Array of object names | **Optional.** An array of group names.
1714 enable\_notifications | Boolean | **Optional.** Whether notifications are enabled for this user.
1715 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.
1716 types | Array | **Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
1717 states | Array | **Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
1721 Name | Type | Description
1722 --------------------------|-----------------------|----------------------------------
1723 last\_notification | Timestamp | When the last notification was sent for this user (as a UNIX timestamp).
1725 ## UserGroup <a id="objecttype-usergroup"></a>
1731 > Assign user group members using the [group assign](17-language-reference.md#group-assign) rules.
1736 object UserGroup "icingaadmins" {
1737 display_name = "Icinga 2 Admin Group"
1741 Configuration Attributes:
1743 Name | Type | Description
1744 --------------------------|-----------------------|----------------------------------
1745 display\_name | String | **Optional.** A short description of the user group.
1746 groups | Array of object names | **Optional.** An array of nested group names.
1749 ## Zone <a id="objecttype-zone"></a>
1751 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1752 Please read the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring) for additional details.
1756 object Zone "master" {
1757 endpoints = [ "icinga2-master1.localdomain", "icinga2-master2.localdomain" ]
1761 object Zone "satellite" {
1762 endpoints = [ "icinga2-satellite1.localdomain" ]
1767 Configuration Attributes:
1769 Name | Type | Description
1770 --------------------------|-----------------------|----------------------------------
1771 endpoints | Array of object names | **Optional.** Array of endpoint names located in this zone.
1772 parent | Object name | **Optional.** The name of the parent zone.
1773 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`.
1775 Zone objects cannot currently be created with the API.