X-Git-Url: https://granicus.if.org/sourcecode?a=blobdiff_plain;f=doc%2F09-object-types.md;h=d73fa8894f169a60591c409c24dcf83c00f79830;hb=1078a0a824d7d78fa60c694fc645bf0e69ce882b;hp=904e31b23908c052954bbdbc4d0d489bb28d1edd;hpb=a80c8259211382da760c4e9d42167046ff7fa508;p=icinga2
diff --git a/doc/09-object-types.md b/doc/09-object-types.md
index 904e31b23..d73fa8894 100644
--- a/doc/09-object-types.md
+++ b/doc/09-object-types.md
@@ -1,4 +1,4 @@
-# Config Object Types
+# Object Types
This chapter provides an overview of all available config object types which can be
instantiated using the `object` keyword.
@@ -12,6 +12,14 @@ You should note that the `Timestamp` type is a `Number`.
In addition to that `Object name` is an object reference to
an existing object name as `String` type.
+## Overview
+
+* [Monitoring Objects](09-object-types.md#object-types-monitoring) such as host, service, etc.
+* [Runtime Objects](09-object-types.md#object-types-runtime) generated by Icinga itself.
+* [Features](09-object-types.md#object-types-features) available via `icinga2 feature` CLI command.
+
+## Common Runtime Attributes
+
Configuration objects share these runtime attributes which cannot be
modified by the user. You can access these attributes using
the [Icinga 2 API](12-icinga2-api.md#icinga2-api-config-objects).
@@ -27,74 +35,9 @@ the [Icinga 2 API](12-icinga2-api.md#icinga2-api-config-objects).
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`.
source\_location | Dictionary | Location information where the configuration files are stored.
+## Monitoring Objects
-## ApiListener
-
-ApiListener objects are used for distributed monitoring setups
-and API usage specifying the certificate files used for ssl
-authorization and additional restrictions.
-This configuration object is available as [api feature](11-cli-commands.md#cli-command-feature).
-
-The `TicketSalt` constant must be defined in [constants.conf](04-configuring-icinga-2.md#constants-conf).
-
-Example:
-
-```
-object ApiListener "api" {
- accept_commands = true
- accept_config = true
-
- ticket_salt = TicketSalt
-}
-```
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------------------|-----------------------|----------------------------------
- cert\_path | String | **Deprecated.** Path to the public key.
- key\_path | String | **Deprecated.** Path to the private key.
- ca\_path | String | **Deprecated.** Path to the CA certificate file.
- 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.
- crl\_path | String | **Optional.** Path to the CRL file.
- bind\_host | String | **Optional.** The IP address the api listener should be bound to. Defaults to `0.0.0.0`.
- bind\_port | Number | **Optional.** The port the api listener should be bound to. Defaults to `5665`.
- accept\_config | Boolean | **Optional.** Accept zone configuration. Defaults to `false`.
- accept\_commands | Boolean | **Optional.** Accept remote commands. Defaults to `false`.
- cipher\_list | String | **Optional.** Cipher list that is allowed. For a list of available ciphers run `openssl ciphers`. Defaults to `ALL:!LOW:!WEAK:!MEDIUM:!EXP:!NULL`.
- tls\_protocolmin | String | **Optional.** Minimum TLS protocol version. Must be one of `TLSv1`, `TLSv1.1` or `TLSv1.2`. Defaults to `TLSv1`.
- 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)
- access\_control\_allow\_credentials | Boolean | **Deprecated.** Indicates whether or not the actual request can be made using credentials. Defaults to `true`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Credentials)
- access\_control\_allow\_headers | String | **Deprecated.** Used in response to a preflight request to indicate which HTTP headers can be used when making the actual request. Defaults to `Authorization`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Headers)
- access\_control\_allow\_methods | String | **Deprecated.** Used in response to a preflight request to indicate which HTTP methods can be used when making the actual request. Defaults to `GET, POST, PUT, DELETE`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Methods)
-
-The attributes `access_control_allow_credentials`, `access_control_allow_headers` and `access_control_allow_methods`
-are controlled by Icinga 2 and are not changeable by config any more.
-
-
-The ApiListener type expects its certificate files to be in the following locations:
-
- Type | Location
- ---------------------|-------------------------------------
- Private key | `DataDir + "/certs/" + NodeName + ".key"`
- Certificate file | `DataDir + "/certs/" + NodeName + ".crt"`
- CA certificate file | `DataDir + "/certs/ca.crt"`
-
-If the deprecated attributes `cert_path`, `key_path` and/or `ca_path` are specified Icinga 2
-copies those files to the new location in `DataDir + "/certs"` unless the
-file(s) there are newer.
-
-Please check the [upgrading chapter](16-upgrading-icinga-2.md#upgrading-to-2-8-certificate-paths) for more details.
-
-While Icinga 2 and the underlying OpenSSL library use sane and secure defaults, the attributes
-`cipher_list` and `tls_protocolmin` can be used to increase communication security. A good source
-for a more secure configuration is provided by the [Mozilla Wiki](https://wiki.mozilla.org/Security/Server_Side_TLS).
-Ensure to use the same configuration for both attributes on **all** endpoints to avoid communication problems which
-requires to use `cipher_list` compatible with the endpoint using the oldest version of the OpenSSL library. If using
-other tools to connect to the API ensure also compatibility with them as this setting affects not only inter-cluster
-communcation but also the REST API.
-
-## ApiUser
+### ApiUser
ApiUser objects are used for authentication against the [Icinga 2 API](12-icinga2-api.md#icinga2-api-authentication).
@@ -118,7 +61,7 @@ Configuration Attributes:
Available permissions are explained in the [API permissions](12-icinga2-api.md#icinga2-api-permissions)
chapter.
-## CheckCommand
+### CheckCommand
A check command definition. Additional default command custom attributes can be
defined here.
@@ -170,7 +113,7 @@ Configuration Attributes:
arguments | Dictionary | **Optional.** A dictionary of command arguments.
-### CheckCommand Arguments
+#### CheckCommand Arguments
Command arguments can be defined as key-value-pairs in the `arguments`
dictionary. If the argument requires additional configuration, for example
@@ -227,106 +170,25 @@ Argument order:
..., -3, -2, -1, , 1, 2, 3, ...
```
-Argument array with `repeat_key = true`:
-
-```
-'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'
-```
-
-Argument array with `repeat_key = false`:
-
-```
-'key' 'value[0]' 'value[1]' 'value[2]'
-```
-
-## CheckerComponent
-
-The checker component is responsible for scheduling active checks.
-This configuration object is available as [checker feature](11-cli-commands.md#cli-command-feature).
-
-Example:
-
-```
-object CheckerComponent "checker" { }
-```
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- concurrent\_checks | Number | **Optional and deprecated.** The maximum number of concurrent checks. Was replaced by global constant `MaxConcurrentChecks` which will be set if you still use `concurrent_checks`.
-
-## CheckResultReader
-
-Reads Icinga 1.x check result files from a directory. This functionality is provided
-to help existing Icinga 1.x users and might be useful for migration scenarios.
-
-Example:
+Define argument array:
```
-object CheckResultReader "reader" {
- spool_dir = "/data/check-results"
-}
+value = "[ 'one', 'two', 'three' ]"
```
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- spool\_dir | String | **Optional.** The directory which contains the check result files. Defaults to DataDir + "/spool/checkresults/".
-
-## Comment
-
-Comments created at runtime are represented as objects.
-Note: This is for reference only. You can create comments
-with the [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) API action.
-
-Example:
+Argument array with `repeat_key = true`:
```
-object Comment "localhost!my-comment" {
- host_name = "localhost"
- author = "icingaadmin"
- text = "This is a comment."
-}
+'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'
```
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- host\_name | Object name | **Required.** The name of the host this comment belongs to.
- 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.
- author | String | **Required.** The author's name.
- text | String | **Required.** The comment text.
- entry\_time | Timestamp | **Optional.** The UNIX timestamp when this comment was added.
- entry\_type | Number | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
- expire\_time | Timestamp | **Optional.** The comment's expire time as UNIX timestamp.
- persistent | Boolean | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
-
-## CompatLogger
-
-Writes log files in a format that's compatible with Icinga 1.x.
-This configuration object is available as [compatlog feature](14-features.md#compat-logging).
-
-Example:
+Argument array with `repeat_key = false`:
```
-object CompatLogger "compatlog" {
- log_dir = "/var/log/icinga2/compat"
- rotation_method = "DAILY"
-}
+'key' 'value[0]' 'value[1]' 'value[2]'
```
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- log\_dir | String | **Optional.** Path to the compat log directory. Defaults to LogDir + "/compat".
- rotation\_method | String | **Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
-
-
-## Dependency
+### Dependency
Dependency objects are used to specify dependencies between hosts and services. Dependencies
can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
@@ -386,12 +248,14 @@ Configuration Attributes:
Available state filters:
- OK
- Warning
- Critical
- Unknown
- Up
- Down
+```
+OK
+Warning
+Critical
+Unknown
+Up
+Down
+```
When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
automatically determined by Icinga 2.
@@ -430,96 +294,7 @@ Dependency objects have composite names, i.e. their names are based on the `chil
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
`child_service_name` attributes has a different value.
-## Downtime
-
-Downtimes created at runtime are represented as objects.
-You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action.
-
-Example:
-
-```
-object Downtime "my-downtime" {
- host_name = "localhost"
- author = "icingaadmin"
- comment = "This is a downtime."
- start_time = 1505312869
- end_time = 1505312924
-}
-```
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- host\_name | Object name | **Required.** The name of the host this comment belongs to.
- 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.
- author | String | **Required.** The author's name.
- comment | String | **Required.** The comment text.
- start\_time | Timestamp | **Required.** The start time as UNIX timestamp.
- end\_time | Timestamp | **Required.** The end time as UNIX timestamp.
- duration | Number | **Optional.** The duration as number.
- entry\_time | Timestamp | **Optional.** The UNIX timestamp when this downtime was added.
- 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).
- triggers | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime.
-
-Runtime Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- trigger\_time | Timestamp | The UNIX timestamp when this downtime was triggered.
- triggered\_by | Object name | The name of the downtime this downtime was triggered by.
-
-
-## ElasticsearchWriter
-
-Writes check result metrics and performance data to an Elasticsearch instance.
-This configuration object is available as [elasticsearch feature](14-features.md#elasticsearch-writer).
-
-Example:
-
-```
-object ElasticsearchWriter "elasticsearch" {
- host = "127.0.0.1"
- port = 9200
- index = "icinga2"
-
- enable_send_perfdata = true
-
- flush_threshold = 1024
- flush_interval = 10
-}
-```
-
-The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- host | String | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
- port | Number | **Required.** Elasticsearch port. Defaults to `9200`.
- index | String | **Required.** Elasticsearch index name. Defaults to `icinga2`.
- enable\_send\_perfdata | Boolean | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
- flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to Elasticsearch. Defaults to `10s`.
- flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to `1024`.
- username | String | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
- password | String | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
- enable\_tls | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
- ca\_path | String | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
- cert\_path | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
- key\_path | String | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
-
-Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
-Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
-
-Basic auth is supported with the `username` and `password` attributes. This requires an
-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/)
-for an example.
-
-TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
-you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
-
-## Endpoint
+### Endpoint
Endpoint objects are used to specify connection information for remote
Icinga 2 instances. More details can be found in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
@@ -554,7 +329,7 @@ Configuration Attributes:
Endpoint objects cannot currently be created with the API.
-## EventCommand
+### EventCommand
An event command definition.
@@ -581,118 +356,22 @@ Command arguments can be used the same way as for [CheckCommand objects](09-obje
More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
-## ExternalCommandListener
-Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
-This configuration object is available as [command feature](14-features.md#external-commands).
+### Host
+
+A host.
Example:
```
-object ExternalCommandListener "command" {
- command_path = "/var/run/icinga2/cmd/icinga2.cmd"
-}
-```
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- command\_path | String | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
-
-
-
-## FileLogger
-
-Specifies Icinga 2 logging to a file.
-This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging).
-
-Example:
-
-```
-object FileLogger "debug-file" {
- severity = "debug"
- path = "/var/log/icinga2/debug.log"
-}
-```
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- path | String | **Required.** The log path.
- severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
-
-
-## GelfWriter
-
-Writes event log entries to a defined GELF receiver host (Graylog, Logstash).
-This configuration object is available as [gelf feature](14-features.md#gelfwriter).
-
-Example:
-
-```
-object GelfWriter "gelf" {
- host = "127.0.0.1"
- port = 12201
-}
-```
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- host | String | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`.
- port | Number | **Optional.** GELF receiver port. Defaults to `12201`.
- source | String | **Optional.** Source name for this instance. Defaults to `icinga2`.
- enable\_send\_perfdata | Boolean | **Optional.** Enable performance data for 'CHECK RESULT' events.
-
-
-## GraphiteWriter
-
-Writes check result metrics and performance data to a defined
-Graphite Carbon host.
-This configuration object is available as [graphite feature](14-features.md#graphite-carbon-cache-writer).
-
-Example:
-
-```
-object GraphiteWriter "graphite" {
- host = "127.0.0.1"
- port = 2003
-}
-```
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- host | String | **Optional.** Graphite Carbon host address. Defaults to `127.0.0.1`.
- port | Number | **Optional.** Graphite Carbon port. Defaults to `2003`.
- host\_name\_template | String | **Optional.** Metric prefix for host name. Defaults to `icinga2.$host.name$.host.$host.check_command$`.
- service\_name\_template | String | **Optional.** Metric prefix for service name. Defaults to `icinga2.$host.name$.services.$service.name$.$service.check_command$`.
- enable\_send\_thresholds | Boolean | **Optional.** Send additional threshold metrics. Defaults to `false`.
- enable\_send\_metadata | Boolean | **Optional.** Send additional metadata metrics. Defaults to `false`.
-
-Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
-
-
-
-## Host
-
-A host.
-
-Example:
-
-```
-object Host "icinga2-client1.localdomain" {
- display_name = "Linux Client 1"
- address = "192.168.56.111"
- address6 = "2a00:1450:4001:815::2003"
-
- groups = [ "linux-servers" ]
-
- check_command = "hostalive"
+object Host "icinga2-client1.localdomain" {
+ display_name = "Linux Client 1"
+ address = "192.168.56.111"
+ address6 = "2a00:1450:4001:815::2003"
+
+ groups = [ "linux-servers" ]
+
+ check_command = "hostalive"
}
```
@@ -710,7 +389,7 @@ Configuration Attributes:
check\_period | Object name | **Optional.** The name of a time period which determines when this host should be checked. Not set by default.
check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
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`.
- 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`.
+ retry\_interval | Duration | **Optional.** The retry interval (in seconds). This interval is used for checks when the host is in a `SOFT` state. Defaults to `1m`. Note: This does not affect the scheduling [after a passive check result](08-advanced-topics.md#check-result-freshness).
enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to true.
enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to true.
enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to true.
@@ -765,7 +444,7 @@ Runtime Attributes:
-## HostGroup
+### HostGroup
A group of hosts.
@@ -790,18 +469,34 @@ Configuration Attributes:
display\_name | String | **Optional.** A short description of the host group.
groups | Array of object names | **Optional.** An array of nested group names.
-## IcingaApplication
-The IcingaApplication object is required to start Icinga 2.
-The object name must be `app`. If the object configuration
-is missing, Icinga 2 will automatically create an IcingaApplication
-object.
+
+### Notification
+
+Notification objects are used to specify how users should be notified in case
+of host and service state changes and other events.
+
+> **Best Practice**
+>
+> Rather than creating a `Notification` object for a specific host or service it is
+> usually easier to just create a `Notification` template and use the `apply` keyword
+> to assign the notification to a number of hosts or services. Use the `to` keyword
+> to set the specific target type for `Host` or `Service`.
+> Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
Example:
```
-object IcingaApplication "app" {
- enable_perfdata = false
+object Notification "localhost-ping-notification" {
+ host_name = "localhost"
+ service_name = "ping4"
+
+ command = "mail-notification"
+
+ users = [ "user1", "user2" ] // reference to User objects
+
+ types = [ Problem, Recovery ]
+ states = [ Critical, Warning, OK ]
}
```
@@ -809,377 +504,68 @@ Configuration Attributes:
Name | Type | Description
--------------------------|-----------------------|----------------------------------
- enable\_notifications | Boolean | **Optional.** Whether notifications are globally enabled. Defaults to true.
- enable\_event\_handlers | Boolean | **Optional.** Whether event handlers are globally enabled. Defaults to true.
- enable\_flapping | Boolean | **Optional.** Whether flap detection is globally enabled. Defaults to true.
- enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true.
- enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true.
- enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true.
- vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally.
-
-## IdoMySqlConnection
-
-IDO database adapter for MySQL.
-This configuration object is available as [ido-mysql feature](14-features.md#db-ido).
+ host\_name | Object name | **Required.** The name of the host this notification belongs to.
+ 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.
+ vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
+ users | Array of object names | **Required.** A list of user names who should be notified. **Optional.** if the `user_groups` attribute is set.
+ user\_groups | Array of object names | **Required.** A list of user group names who should be notified. **Optional.** if the `users` attribute is set.
+ times | Dictionary | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
+ command | Object name | **Required.** The name of the notification command which should be executed when the notification is triggered.
+ 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.
+ period | Object name | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
+ 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.
+ types | Array | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
+ states | Array | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched. Note that the states filter is ignored for notifications of type Acknowledgement!
-Example:
+Available notification state filters for Service:
```
-object IdoMysqlConnection "mysql-ido" {
- host = "127.0.0.1"
- port = 3306
- user = "icinga"
- password = "icinga"
- database = "icinga"
-
- cleanup = {
- downtimehistory_age = 48h
- contactnotifications_age = 31d
- }
-}
+OK
+Warning
+Critical
+Unknown
```
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- host | String | **Optional.** MySQL database host address. Defaults to `localhost`.
- port | Number | **Optional.** MySQL database port. Defaults to `3306`.
- socket\_path | String | **Optional.** MySQL socket path.
- user | String | **Optional.** MySQL database user with read/write permission to the icinga database. Defaults to `icinga`.
- password | String | **Optional.** MySQL database user's password. Defaults to `icinga`.
- database | String | **Optional.** MySQL database name. Defaults to `icinga`.
- enable\_ssl | Boolean | **Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
- ssl\_key | String | **Optional.** MySQL SSL client key file path.
- ssl\_cert | String | **Optional.** MySQL SSL certificate file path.
- ssl\_ca | String | **Optional.** MySQL SSL certificate authority certificate file path.
- ssl\_capath | String | **Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
- ssl\_cipher | String | **Optional.** MySQL SSL list of allowed ciphers.
- table\_prefix | String | **Optional.** MySQL database table prefix. Defaults to `icinga_`.
- instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
- instance\_description | String | **Optional.** Description for the Icinga 2 instance.
- 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".
- 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`.
- cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
- categories | Array | **Optional.** Array of information types that should be written to the database.
+Available notification state filters for Host:
-Cleanup Items:
+```
+Up
+Down
+```
- Name | Type | Description
- --------------------------------|-----------------------|----------------------------------
- acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
- commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
- contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
- contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
- downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
- eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
- externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
- flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
- hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
- logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
- notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
- processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
- statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
- servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
- systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
+Available notification type filters:
-Data Categories:
+```
+DowntimeStart
+DowntimeEnd
+DowntimeRemoved
+Custom
+Acknowledgement
+Problem
+Recovery
+FlappingStart
+FlappingEnd
+```
- Name | Description | Required by
- ---------------------|------------------------|--------------------
- DbCatConfig | Configuration data | Icinga Web 2
- DbCatState | Current state data | Icinga Web 2
- DbCatAcknowledgement | Acknowledgements | Icinga Web 2
- DbCatComment | Comments | Icinga Web 2
- DbCatDowntime | Downtimes | Icinga Web 2
- DbCatEventHandler | Event handler data | Icinga Web 2
- DbCatExternalCommand | External commands | --
- DbCatFlapping | Flap detection data | Icinga Web 2
- DbCatCheck | Check results | --
- DbCatLog | Log messages | --
- DbCatNotification | Notifications | Icinga Web 2
- DbCatProgramStatus | Program status data | Icinga Web 2
- DbCatRetention | Retention data | Icinga Web 2
- DbCatStateHistory | Historical state data | Icinga Web 2
+Runtime Attributes:
-The default value for `categories` includes everything required
-by Icinga Web 2 in the table above.
+ Name | Type | Description
+ ----------------------------|-----------------------|-----------------
+ last\_notification | Timestamp | When the last notification was sent for this Notification object (as a UNIX timestamp).
+ 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).
+ notification\_number | Number | The notification number.
+ last\_problem\_notification | Timestamp | When the last notification was sent for a problem (as a UNIX timestamp).
-In addition to the category flags listed above the `DbCatEverything`
-flag may be used as a shortcut for listing all flags.
-## IdoPgsqlConnection
+### NotificationCommand
-IDO database adapter for PostgreSQL.
-This configuration object is available as [ido-pgsql feature](14-features.md#db-ido).
+A notification command definition.
Example:
```
-object IdoPgsqlConnection "pgsql-ido" {
- host = "127.0.0.1"
- port = 5432
- user = "icinga"
- password = "icinga"
- database = "icinga"
-
- cleanup = {
- downtimehistory_age = 48h
- contactnotifications_age = 31d
- }
-}
-```
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- host | String | **Optional.** PostgreSQL database host address. Defaults to `localhost`.
- port | Number | **Optional.** PostgreSQL database port. Defaults to `5432`.
- user | String | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`.
- password | String | **Optional.** PostgreSQL database user's password. Defaults to `icinga`.
- database | String | **Optional.** PostgreSQL database name. Defaults to `icinga`.
- ssl\_mode | String | **Optional.** Enable SSL connection mode. Value must be set according to the [sslmode setting](https://www.postgresql.org/docs/9.3/static/libpq-connect.html#LIBPQ-CONNSTRING): `prefer`, `require`, `verify-ca`, `verify-full`, `allow`, `disable`.
- ssl\_key | String | **Optional.** PostgreSQL SSL client key file path.
- ssl\_cert | String | **Optional.** PostgreSQL SSL certificate file path.
- ssl\_ca | String | **Optional.** PostgreSQL SSL certificate authority certificate file path.
- table\_prefix | String | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`.
- instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
- instance\_description | String | **Optional.** Description for the Icinga 2 instance.
- 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".
- 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`.
- cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
- categories | Array | **Optional.** Array of information types that should be written to the database.
-
-Cleanup Items:
-
- Name | Type | Description
- --------------------------------|-----------------------|----------------------------------
- acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
- commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
- contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
- contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
- downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
- eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
- externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
- flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
- hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
- logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
- notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
- processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
- statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
- servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
- systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
-
-Data Categories:
-
- Name | Description | Required by
- ---------------------|------------------------|--------------------
- DbCatConfig | Configuration data | Icinga Web 2
- DbCatState | Current state data | Icinga Web 2
- DbCatAcknowledgement | Acknowledgements | Icinga Web 2
- DbCatComment | Comments | Icinga Web 2
- DbCatDowntime | Downtimes | Icinga Web 2
- DbCatEventHandler | Event handler data | Icinga Web 2
- DbCatExternalCommand | External commands | --
- DbCatFlapping | Flap detection data | Icinga Web 2
- DbCatCheck | Check results | --
- DbCatLog | Log messages | --
- DbCatNotification | Notifications | Icinga Web 2
- DbCatProgramStatus | Program status data | Icinga Web 2
- DbCatRetention | Retention data | Icinga Web 2
- DbCatStateHistory | Historical state data | Icinga Web 2
-
-The default value for `categories` includes everything required
-by Icinga Web 2 in the table above.
-
-In addition to the category flags listed above the `DbCatEverything`
-flag may be used as a shortcut for listing all flags.
-
-## InfluxdbWriter
-
-Writes check result metrics and performance data to a defined InfluxDB host.
-This configuration object is available as [influxdb feature](14-features.md#influxdb-writer).
-
-Example:
-
-```
-object InfluxdbWriter "influxdb" {
- host = "127.0.0.1"
- port = 8086
- database = "icinga2"
-
- flush_threshold = 1024
- flush_interval = 10s
-
- host_template = {
- measurement = "$host.check_command$"
- tags = {
- hostname = "$host.name$"
- }
- }
- service_template = {
- measurement = "$service.check_command$"
- tags = {
- hostname = "$host.name$"
- service = "$service.name$"
- }
- }
-}
-```
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- host | String | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
- port | Number | **Required.** InfluxDB HTTP port. Defaults to `8086`.
- database | String | **Required.** InfluxDB database name. Defaults to `icinga2`.
- username | String | **Optional.** InfluxDB user name. Defaults to `none`.
- password | String | **Optional.** InfluxDB user password. Defaults to `none`.
- ssl\_enable | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`.
- ssl\_ca\_cert | String | **Optional.** Path to CA certificate to validate the remote host.
- ssl\_cert | String | **Optional.** Path to host certificate to present to the remote host for mutual verification.
- ssl\_key | String | **Optional.** Path to host key to accompany the ssl\_cert.
- host\_template | String | **Required.** Host template to define the InfluxDB line protocol.
- service\_template | String | **Required.** Service template to define the influxDB line protocol.
- enable\_send\_thresholds | Boolean | **Optional.** Whether to send warn, crit, min & max tagged data.
- enable\_send\_metadata | Boolean | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
- flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to InfluxDB. Defaults to `10s`.
- flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`.
-
-Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
-to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
-or similar.
-
-
-
-## LiveStatusListener
-
-Livestatus API interface available as TCP or UNIX socket. Historical table queries
-require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
-pointing to the log files using the `compat_log_path` configuration attribute.
-This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus).
-
-Examples:
-
-```
-object LivestatusListener "livestatus-tcp" {
- socket_type = "tcp"
- bind_host = "127.0.0.1"
- bind_port = "6558"
-}
-
-object LivestatusListener "livestatus-unix" {
- socket_type = "unix"
- socket_path = "/var/run/icinga2/cmd/livestatus"
-}
-```
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- socket\_type | String | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`.
- 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`.
- bind\_port | Number | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`.
- 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".
- compat\_log\_path | String | **Optional.** Path to Icinga 1.x log files. Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LogDir + "/compat"
-
-> **Note**
->
-> UNIX sockets are not supported on Windows.
-
-
-## Notification
-
-Notification objects are used to specify how users should be notified in case
-of host and service state changes and other events.
-
-> **Best Practice**
->
-> Rather than creating a `Notification` object for a specific host or service it is
-> usually easier to just create a `Notification` template and use the `apply` keyword
-> to assign the notification to a number of hosts or services. Use the `to` keyword
-> to set the specific target type for `Host` or `Service`.
-> Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
-
-Example:
-
-```
-object Notification "localhost-ping-notification" {
- host_name = "localhost"
- service_name = "ping4"
-
- command = "mail-notification"
-
- users = [ "user1", "user2" ] // reference to User objects
-
- types = [ Problem, Recovery ]
- states = [ Critical, Warning, OK ]
-}
-```
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- host\_name | Object name | **Required.** The name of the host this notification belongs to.
- 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.
- vars | Dictionary | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
- users | Array of object names | **Required.** A list of user names who should be notified. **Optional.** if the `user_groups` attribute is set.
- user\_groups | Array of object names | **Required.** A list of user group names who should be notified. **Optional.** if the `users` attribute is set.
- times | Dictionary | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
- command | Object name | **Required.** The name of the notification command which should be executed when the notification is triggered.
- 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.
- period | Object name | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
- 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.
- types | Array | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
- states | Array | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
-
-Available notification state filters for Service:
-
- OK
- Warning
- Critical
- Unknown
-
-Available notification state filters for Host:
-
- Up
- Down
-
-Available notification type filters:
-
- DowntimeStart
- DowntimeEnd
- DowntimeRemoved
- Custom
- Acknowledgement
- Problem
- Recovery
- FlappingStart
- FlappingEnd
-
-Runtime Attributes:
-
- Name | Type | Description
- ----------------------------|-----------------------|-----------------
- last\_notification | Timestamp | When the last notification was sent for this Notification object (as a UNIX timestamp).
- 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).
- notification\_number | Number | The notification number.
- last\_problem\_notification | Timestamp | When the last notification was sent for a problem (as a UNIX timestamp).
-
-
-## NotificationCommand
-
-A notification command definition.
-
-Example:
-
-```
-object NotificationCommand "mail-service-notification" {
- command = [ ConfigDir + "/scripts/mail-service-notification.sh" ]
+object NotificationCommand "mail-service-notification" {
+ command = [ ConfigDir + "/scripts/mail-service-notification.sh" ]
arguments += {
"-4" = {
@@ -1265,111 +651,35 @@ Command arguments can be used the same way as for [CheckCommand objects](09-obje
More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
-## NotificationComponent
+### ScheduledDowntime
-The notification component is responsible for sending notifications.
-This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature).
+ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
+
+> **Best Practice**
+>
+> Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
+> to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
+> scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
+> type for `Host` or `Service`.
+> Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
Example:
```
-object NotificationComponent "notification" { }
-```
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- 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".
-
-## OpenTsdbWriter
-
-Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
-This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer).
-
-Example:
-
-```
-object OpenTsdbWriter "opentsdb" {
- host = "127.0.0.1"
- port = 4242
-
-```
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- host | String | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`.
- port | Number | **Optional.** OpenTSDB port. Defaults to `4242`.
-
-
-## PerfdataWriter
-
-Writes check result performance data to a defined path using macro
-pattern consisting of custom attributes and runtime macros.
-This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files).
-
-Example:
-
-```
-object PerfdataWriter "perfdata" {
- host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
-
- service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
-
- 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$"
- 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$"
-
- rotation_interval = 15s
-}
-```
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- host\_perfdata\_path | String | **Optional.** Path to the host performance data file. Defaults to SpoolDir + "/perfdata/host-perfdata".
- service\_perfdata\_path | String | **Optional.** Path to the service performance data file. Defaults to SpoolDir + "/perfdata/service-perfdata".
- host\_temp\_path | String | **Optional.** Path to the temporary host file. Defaults to SpoolDir + "/tmp/host-perfdata".
- service\_temp\_path | String | **Optional.** Path to the temporary service file. Defaults to SpoolDir + "/tmp/service-perfdata".
- host\_format\_template | String | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
- service\_format\_template | String | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
- rotation\_interval | Duration | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`.
-
-When rotating the performance data file the current UNIX timestamp is appended to the path specified
-in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
-
-
-## ScheduledDowntime
-
-ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
-
-> **Best Practice**
->
-> Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
-> to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
-> scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
-> type for `Host` or `Service`.
-> Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
-
-Example:
-
-```
-object ScheduledDowntime "some-downtime" {
- host_name = "localhost"
- service_name = "ping4"
-
- author = "icingaadmin"
- comment = "Some comment"
-
- fixed = false
- duration = 30m
-
- ranges = {
- "sunday" = "02:00-03:00"
- }
-}
+object ScheduledDowntime "some-downtime" {
+ host_name = "localhost"
+ service_name = "ping4"
+
+ author = "icingaadmin"
+ comment = "Some comment"
+
+ fixed = false
+ duration = 30m
+
+ ranges = {
+ "sunday" = "02:00-03:00"
+ }
+}
```
Configuration Attributes:
@@ -1383,6 +693,7 @@ Configuration Attributes:
fixed | Boolean | **Optional.** Whether this is a fixed downtime. Defaults to `true`.
duration | Duration | **Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
ranges | Dictionary | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
+ child\_options | String | **Optional.** Schedule child downtimes. `DowntimeNoChildren` does not do anything, `DowntimeTriggeredChildren` schedules child downtimes triggered by this downtime, `DowntimeNonTriggeredChildren` schedules non-triggered downtimes. Defaults to `DowntimeNoChildren`.
ScheduledDowntime objects have composite names, i.e. their names are based
on the `host_name` and `service_name` attributes and the
@@ -1391,7 +702,7 @@ with the same (short) name as long as one of the `host_name` and
`service_name` attributes has a different value.
-## Service
+### Service
Service objects describe network services and how they should be checked
by Icinga 2.
@@ -1436,7 +747,7 @@ Configuration Attributes:
check\_period | Object name | **Optional.** The name of a time period which determines when this service should be checked. Not set by default.
check\_timeout | Duration | **Optional.** Check command timeout in seconds. Overrides the CheckCommand's `timeout` attribute.
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`.
- 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`.
+ retry\_interval | Duration | **Optional.** The retry interval (in seconds). This interval is used for checks when the service is in a `SOFT` state. Defaults to `1m`. Note: This does not affect the scheduling [after a passive check result](08-advanced-topics.md#check-result-freshness).
enable\_notifications | Boolean | **Optional.** Whether notifications are enabled. Defaults to `true`.
enable\_active\_checks | Boolean | **Optional.** Whether active checks are enabled. Defaults to `true`.
enable\_passive\_checks | Boolean | **Optional.** Whether passive checks are enabled. Defaults to `true`.
@@ -1491,7 +802,7 @@ Runtime Attributes:
last\_state\_unknown | Timestamp | When the last UNKNOWN state occurred (as a UNIX timestamp).
-## ServiceGroup
+### ServiceGroup
A group of services.
@@ -1515,76 +826,8 @@ Configuration Attributes:
groups | Array of object names | **Optional.** An array of nested group names.
-## StatusDataWriter
-
-Periodically writes status and configuration data files which are used by third-party tools.
-This configuration object is available as [statusdata feature](14-features.md#status-data).
-
-Example:
-
-```
-object StatusDataWriter "status" {
- status_path = "/var/cache/icinga2/status.dat"
- objects_path = "/var/cache/icinga2/objects.cache"
- update_interval = 30s
-}
-```
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- status\_path | String | **Optional.** Path to the `status.dat` file. Defaults to CacheDir + "/status.dat".
- objects\_path | String | **Optional.** Path to the `objects.cache` file. Defaults to CacheDir + "/objects.cache".
- update\_interval | Duration | **Optional.** The interval in which the status files are updated. Defaults to `15s`.
-
-
-## SyslogLogger
-
-Specifies Icinga 2 logging to syslog.
-This configuration object is available as `syslog` [logging feature](14-features.md#logging).
-
-Example:
-
-```
-object SyslogLogger "syslog" {
- severity = "warning"
-}
-```
-
-Configuration Attributes:
-
- Name | Type | Description
- --------------------------|-----------------------|----------------------------------
- severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
- facility | String | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`.
-
-Facility Constants:
-
- Name | Facility | Description
- ---------------------|---------------|----------------
- FacilityAuth | LOG\_AUTH | The authorization system.
- FacilityAuthPriv | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals.
- FacilityCron | LOG\_CRON | The cron daemon.
- FacilityDaemon | LOG\_DAEMON | System daemons that are not provided for explicitly by other facilities.
- FacilityFtp | LOG\_FTP | The file transfer protocol daemons.
- FacilityKern | LOG\_KERN | Messages generated by the kernel. These cannot be generated by any user processes.
- FacilityLocal0 | LOG\_LOCAL0 | Reserved for local use.
- FacilityLocal1 | LOG\_LOCAL1 | Reserved for local use.
- FacilityLocal2 | LOG\_LOCAL2 | Reserved for local use.
- FacilityLocal3 | LOG\_LOCAL3 | Reserved for local use.
- FacilityLocal4 | LOG\_LOCAL4 | Reserved for local use.
- FacilityLocal5 | LOG\_LOCAL5 | Reserved for local use.
- FacilityLocal6 | LOG\_LOCAL6 | Reserved for local use.
- FacilityLocal7 | LOG\_LOCAL7 | Reserved for local use.
- FacilityLpr | LOG\_LPR | The line printer spooling system.
- FacilityMail | LOG\_MAIL | The mail system.
- FacilityNews | LOG\_NEWS | The network news system.
- FacilitySyslog | LOG\_SYSLOG | Messages generated internally by syslogd.
- FacilityUser | LOG\_USER | Messages generated by user processes. This is the default facility identifier if none is specified.
- FacilityUucp | LOG\_UUCP | The UUCP system.
-## TimePeriod
+### TimePeriod
Time periods can be used to specify when hosts/services should be checked or to limit
when notifications should be sent out.
@@ -1645,7 +888,7 @@ Runtime Attributes:
is\_inside | Boolean | Whether we're currently inside this timeperiod.
-## User
+### User
A user.
@@ -1669,24 +912,28 @@ object User "icingaadmin" {
Available notification state filters:
- OK
- Warning
- Critical
- Unknown
- Up
- Down
+```
+OK
+Warning
+Critical
+Unknown
+Up
+Down
+```
Available notification type filters:
- DowntimeStart
- DowntimeEnd
- DowntimeRemoved
- Custom
- Acknowledgement
- Problem
- Recovery
- FlappingStart
- FlappingEnd
+```
+DowntimeStart
+DowntimeEnd
+DowntimeRemoved
+Custom
+Acknowledgement
+Problem
+Recovery
+FlappingStart
+FlappingEnd
+```
Configuration Attributes:
@@ -1708,7 +955,7 @@ Runtime Attributes:
--------------------------|-----------------------|----------------------------------
last\_notification | Timestamp | When the last notification was sent for this user (as a UNIX timestamp).
-## UserGroup
+### UserGroup
A user group.
@@ -1732,7 +979,7 @@ Configuration Attributes:
groups | Array of object names | **Optional.** An array of nested group names.
-## Zone
+### Zone
Zone objects are used to specify which Icinga 2 instances are located in a zone.
Please read the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring) for additional details.
@@ -1755,7 +1002,844 @@ Configuration Attributes:
Name | Type | Description
--------------------------|-----------------------|----------------------------------
endpoints | Array of object names | **Optional.** Array of endpoint names located in this zone.
- parent | Object name | **Optional.** The name of the parent zone.
+ parent | Object name | **Optional.** The name of the parent zone. (Do not specify a global zone)
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`.
Zone objects cannot currently be created with the API.
+
+
+## Runtime Objects
+
+These objects are generated at runtime by the daemon
+from API actions. Downtime objects are also created
+by ScheduledDowntime objects.
+
+### Comment
+
+Comments created at runtime are represented as objects.
+Note: This is for reference only. You can create comments
+with the [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) API action.
+
+Example:
+
+```
+object Comment "my-comment" {
+ host_name = "localhost"
+ author = "icingaadmin"
+ text = "This is a comment."
+ entry_time = 1234567890
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ host\_name | Object name | **Required.** The name of the host this comment belongs to.
+ 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.
+ author | String | **Required.** The author's name.
+ text | String | **Required.** The comment text.
+ entry\_time | Timestamp | **Optional.** The UNIX timestamp when this comment was added. If omitted, the entry time is volatile!
+ entry\_type | Number | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4).
+ expire\_time | Timestamp | **Optional.** The comment's expire time as UNIX timestamp.
+ persistent | Boolean | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
+
+### Downtime
+
+Downtimes created at runtime are represented as objects.
+You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action.
+
+Example:
+
+```
+object Downtime "my-downtime" {
+ host_name = "localhost"
+ author = "icingaadmin"
+ comment = "This is a downtime."
+ start_time = 1505312869
+ end_time = 1505312924
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ host\_name | Object name | **Required.** The name of the host this comment belongs to.
+ 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.
+ author | String | **Required.** The author's name.
+ comment | String | **Required.** The comment text.
+ start\_time | Timestamp | **Required.** The start time as UNIX timestamp.
+ end\_time | Timestamp | **Required.** The end time as UNIX timestamp.
+ duration | Number | **Optional.** The duration as number.
+ entry\_time | Timestamp | **Optional.** The UNIX timestamp when this downtime was added.
+ 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).
+ triggers | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime.
+
+Runtime Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ trigger\_time | Timestamp | The UNIX timestamp when this downtime was triggered.
+ triggered\_by | Object name | The name of the downtime this downtime was triggered by.
+
+
+
+## Features
+
+### ApiListener
+
+ApiListener objects are used for distributed monitoring setups
+and API usage specifying the certificate files used for ssl
+authorization and additional restrictions.
+This configuration object is available as [api feature](11-cli-commands.md#cli-command-feature).
+
+The `TicketSalt` constant must be defined in [constants.conf](04-configuring-icinga-2.md#constants-conf).
+
+Example:
+
+```
+object ApiListener "api" {
+ accept_commands = true
+ accept_config = true
+
+ ticket_salt = TicketSalt
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------------------|-----------------------|----------------------------------
+ cert\_path | String | **Deprecated.** Path to the public key.
+ key\_path | String | **Deprecated.** Path to the private key.
+ ca\_path | String | **Deprecated.** Path to the CA certificate file.
+ 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.
+ crl\_path | String | **Optional.** Path to the CRL file.
+ bind\_host | String | **Optional.** The IP address the api listener should be bound to. If not specified, the ApiListener is bound to `::` and listens for both IPv4 and IPv6 connections.
+ bind\_port | Number | **Optional.** The port the api listener should be bound to. Defaults to `5665`.
+ accept\_config | Boolean | **Optional.** Accept zone configuration. Defaults to `false`.
+ accept\_commands | Boolean | **Optional.** Accept remote commands. Defaults to `false`.
+ max\_anonymous\_clients | Number | **Optional.** Limit the number of anonymous client connections (not configured endpoints and signing requests).
+ cipher\_list | String | **Optional.** Cipher list that is allowed. For a list of available ciphers run `openssl ciphers`. Defaults to `ALL:!LOW:!WEAK:!MEDIUM:!EXP:!NULL`.
+ tls\_protocolmin | String | **Optional.** Minimum TLS protocol version. Must be one of `TLSv1`, `TLSv1.1` or `TLSv1.2`. Defaults to `TLSv1`.
+ tls\_handshake\_timeout | Number | **Optional.** TLS Handshake timeout. Defaults to `10s`.
+ 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)
+ access\_control\_allow\_credentials | Boolean | **Deprecated.** Indicates whether or not the actual request can be made using credentials. Defaults to `true`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Credentials)
+ access\_control\_allow\_headers | String | **Deprecated.** Used in response to a preflight request to indicate which HTTP headers can be used when making the actual request. Defaults to `Authorization`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Headers)
+ access\_control\_allow\_methods | String | **Deprecated.** Used in response to a preflight request to indicate which HTTP methods can be used when making the actual request. Defaults to `GET, POST, PUT, DELETE`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Methods)
+ environment | String | **Optional.** Used as suffix in TLS SNI extension name; default from constant `ApiEnvironment`, which is empty.
+
+The attributes `access_control_allow_credentials`, `access_control_allow_headers` and `access_control_allow_methods`
+are controlled by Icinga 2 and are not changeable by config any more.
+
+
+The ApiListener type expects its certificate files to be in the following locations:
+
+ Type | Location
+ ---------------------|-------------------------------------
+ Private key | `DataDir + "/certs/" + NodeName + ".key"`
+ Certificate file | `DataDir + "/certs/" + NodeName + ".crt"`
+ CA certificate file | `DataDir + "/certs/ca.crt"`
+
+If the deprecated attributes `cert_path`, `key_path` and/or `ca_path` are specified Icinga 2
+copies those files to the new location in `DataDir + "/certs"` unless the
+file(s) there are newer.
+
+Please check the [upgrading chapter](16-upgrading-icinga-2.md#upgrading-to-2-8-certificate-paths) for more details.
+
+While Icinga 2 and the underlying OpenSSL library use sane and secure defaults, the attributes
+`cipher_list` and `tls_protocolmin` can be used to increase communication security. A good source
+for a more secure configuration is provided by the [Mozilla Wiki](https://wiki.mozilla.org/Security/Server_Side_TLS).
+Ensure to use the same configuration for both attributes on **all** endpoints to avoid communication problems which
+requires to use `cipher_list` compatible with the endpoint using the oldest version of the OpenSSL library. If using
+other tools to connect to the API ensure also compatibility with them as this setting affects not only inter-cluster
+communcation but also the REST API.
+
+### CheckerComponent
+
+The checker component is responsible for scheduling active checks.
+This configuration object is available as [checker feature](11-cli-commands.md#cli-command-feature).
+
+Example:
+
+```
+object CheckerComponent "checker" { }
+```
+
+In order to limit the concurrent checks on a master/satellite endpoint,
+use [MaxConcurrentChecks](17-language-reference.md#icinga-constants-global-config) constant.
+This also applies to an agent as command endpoint where the checker
+feature is disabled.
+
+### CheckResultReader
+
+Reads Icinga 1.x check result files from a directory. This functionality is provided
+to help existing Icinga 1.x users and might be useful for migration scenarios.
+
+> **Note**
+>
+> This feature is DEPRECATED and will be removed in future releases.
+> Check the [roadmap](https://github.com/Icinga/icinga2/milestones).
+
+Example:
+
+```
+object CheckResultReader "reader" {
+ spool_dir = "/data/check-results"
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ spool\_dir | String | **Optional.** The directory which contains the check result files. Defaults to DataDir + "/spool/checkresults/".
+
+### CompatLogger
+
+Writes log files in a format that's compatible with Icinga 1.x.
+This configuration object is available as [compatlog feature](14-features.md#compat-logging).
+
+> **Note**
+>
+> This feature is DEPRECATED and will be removed in future releases.
+> Check the [roadmap](https://github.com/Icinga/icinga2/milestones).
+
+Example:
+
+```
+object CompatLogger "compatlog" {
+ log_dir = "/var/log/icinga2/compat"
+ rotation_method = "DAILY"
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ log\_dir | String | **Optional.** Path to the compat log directory. Defaults to LogDir + "/compat".
+ rotation\_method | String | **Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
+
+
+### ElasticsearchWriter
+
+Writes check result metrics and performance data to an Elasticsearch instance.
+This configuration object is available as [elasticsearch feature](14-features.md#elasticsearch-writer).
+
+Example:
+
+```
+object ElasticsearchWriter "elasticsearch" {
+ host = "127.0.0.1"
+ port = 9200
+ index = "icinga2"
+
+ enable_send_perfdata = true
+
+ flush_threshold = 1024
+ flush_interval = 10
+}
+```
+
+The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`.
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ host | String | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`.
+ port | Number | **Required.** Elasticsearch port. Defaults to `9200`.
+ index | String | **Required.** Elasticsearch index name. Defaults to `icinga2`.
+ enable\_send\_perfdata | Boolean | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`.
+ flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to Elasticsearch. Defaults to `10s`.
+ flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to `1024`.
+ username | String | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy.
+ password | String | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy.
+ enable\_tls | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy.
+ ca\_path | String | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`.
+ cert\_path | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`.
+ key\_path | String | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`.
+ enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
+
+Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often.
+Experiment with the setting, if you are processing more than 1024 metrics per second or similar.
+
+Basic auth is supported with the `username` and `password` attributes. This requires an
+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/)
+for an example.
+
+TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that
+you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes.
+
+### ExternalCommandListener
+
+Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
+This configuration object is available as [command feature](14-features.md#external-commands).
+
+> **Note**
+>
+> This feature is DEPRECATED and will be removed in future releases.
+> Check the [roadmap](https://github.com/Icinga/icinga2/milestones).
+
+Example:
+
+```
+object ExternalCommandListener "command" {
+ command_path = "/var/run/icinga2/cmd/icinga2.cmd"
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ command\_path | String | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
+
+
+
+### FileLogger
+
+Specifies Icinga 2 logging to a file.
+This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging).
+
+Example:
+
+```
+object FileLogger "debug-file" {
+ severity = "debug"
+ path = "/var/log/icinga2/debug.log"
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ path | String | **Required.** The log path.
+ severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
+
+
+### GelfWriter
+
+Writes event log entries to a defined GELF receiver host (Graylog, Logstash).
+This configuration object is available as [gelf feature](14-features.md#gelfwriter).
+
+Example:
+
+```
+object GelfWriter "gelf" {
+ host = "127.0.0.1"
+ port = 12201
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ host | String | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`.
+ port | Number | **Optional.** GELF receiver port. Defaults to `12201`.
+ source | String | **Optional.** Source name for this instance. Defaults to `icinga2`.
+ enable\_send\_perfdata | Boolean | **Optional.** Enable performance data for 'CHECK RESULT' events.
+ enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
+
+
+### GraphiteWriter
+
+Writes check result metrics and performance data to a defined
+Graphite Carbon host.
+This configuration object is available as [graphite feature](14-features.md#graphite-carbon-cache-writer).
+
+Example:
+
+```
+object GraphiteWriter "graphite" {
+ host = "127.0.0.1"
+ port = 2003
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ host | String | **Optional.** Graphite Carbon host address. Defaults to `127.0.0.1`.
+ port | Number | **Optional.** Graphite Carbon port. Defaults to `2003`.
+ host\_name\_template | String | **Optional.** Metric prefix for host name. Defaults to `icinga2.$host.name$.host.$host.check_command$`.
+ service\_name\_template | String | **Optional.** Metric prefix for service name. Defaults to `icinga2.$host.name$.services.$service.name$.$service.check_command$`.
+ enable\_send\_thresholds | Boolean | **Optional.** Send additional threshold metrics. Defaults to `false`.
+ enable\_send\_metadata | Boolean | **Optional.** Send additional metadata metrics. Defaults to `false`.
+ enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
+
+Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
+
+
+### IcingaApplication
+
+The IcingaApplication object is required to start Icinga 2.
+The object name must be `app`. If the object configuration
+is missing, Icinga 2 will automatically create an IcingaApplication
+object.
+
+Example:
+
+```
+object IcingaApplication "app" {
+ enable_perfdata = false
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ enable\_notifications | Boolean | **Optional.** Whether notifications are globally enabled. Defaults to true.
+ enable\_event\_handlers | Boolean | **Optional.** Whether event handlers are globally enabled. Defaults to true.
+ enable\_flapping | Boolean | **Optional.** Whether flap detection is globally enabled. Defaults to true.
+ enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true.
+ enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true.
+ enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true.
+ vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally.
+ environment | String | **Optional.** Specify the Icinga environment. This overrides the `Environment` constant specified in the configuration or on the CLI with `--define`. Defaults to empty.
+
+### IdoMySqlConnection
+
+IDO database adapter for MySQL.
+This configuration object is available as [ido-mysql feature](14-features.md#db-ido).
+
+Example:
+
+```
+object IdoMysqlConnection "mysql-ido" {
+ host = "127.0.0.1"
+ port = 3306
+ user = "icinga"
+ password = "icinga"
+ database = "icinga"
+
+ cleanup = {
+ downtimehistory_age = 48h
+ contactnotifications_age = 31d
+ }
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ host | String | **Optional.** MySQL database host address. Defaults to `localhost`.
+ port | Number | **Optional.** MySQL database port. Defaults to `3306`.
+ socket\_path | String | **Optional.** MySQL socket path.
+ user | String | **Optional.** MySQL database user with read/write permission to the icinga database. Defaults to `icinga`.
+ password | String | **Optional.** MySQL database user's password. Defaults to `icinga`.
+ database | String | **Optional.** MySQL database name. Defaults to `icinga`.
+ enable\_ssl | Boolean | **Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options.
+ ssl\_key | String | **Optional.** MySQL SSL client key file path.
+ ssl\_cert | String | **Optional.** MySQL SSL certificate file path.
+ ssl\_ca | String | **Optional.** MySQL SSL certificate authority certificate file path.
+ ssl\_capath | String | **Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path.
+ ssl\_cipher | String | **Optional.** MySQL SSL list of allowed ciphers.
+ table\_prefix | String | **Optional.** MySQL database table prefix. Defaults to `icinga_`.
+ instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
+ instance\_description | String | **Optional.** Description for the Icinga 2 instance.
+ 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`.
+ failover\_timeout | Duration | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 30s. Defaults to `30s`.
+ cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
+ categories | Array | **Optional.** Array of information types that should be written to the database.
+
+Cleanup Items:
+
+ Name | Type | Description
+ --------------------------------|-----------------------|----------------------------------
+ acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
+ commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
+ contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
+ contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
+ downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
+ eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
+ externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
+ flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
+ hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
+ logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
+ notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
+ processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
+ statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
+ servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
+ systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
+
+Data Categories:
+
+ Name | Description | Required by
+ ---------------------|------------------------|--------------------
+ DbCatConfig | Configuration data | Icinga Web 2
+ DbCatState | Current state data | Icinga Web 2
+ DbCatAcknowledgement | Acknowledgements | Icinga Web 2
+ DbCatComment | Comments | Icinga Web 2
+ DbCatDowntime | Downtimes | Icinga Web 2
+ DbCatEventHandler | Event handler data | Icinga Web 2
+ DbCatExternalCommand | External commands | --
+ DbCatFlapping | Flap detection data | Icinga Web 2
+ DbCatCheck | Check results | --
+ DbCatLog | Log messages | --
+ DbCatNotification | Notifications | Icinga Web 2
+ DbCatProgramStatus | Program status data | Icinga Web 2
+ DbCatRetention | Retention data | Icinga Web 2
+ DbCatStateHistory | Historical state data | Icinga Web 2
+
+The default value for `categories` includes everything required
+by Icinga Web 2 in the table above.
+
+In addition to the category flags listed above the `DbCatEverything`
+flag may be used as a shortcut for listing all flags.
+
+Runtime Attributes:
+
+ Name | Type | Description
+ ----------------------------|-----------------------|-----------------
+ last\_failover | Timestamp | When the last failover happened for this connection (only available with `enable_ha = true`.
+
+### IdoPgsqlConnection
+
+IDO database adapter for PostgreSQL.
+This configuration object is available as [ido-pgsql feature](14-features.md#db-ido).
+
+Example:
+
+```
+object IdoPgsqlConnection "pgsql-ido" {
+ host = "127.0.0.1"
+ port = 5432
+ user = "icinga"
+ password = "icinga"
+ database = "icinga"
+
+ cleanup = {
+ downtimehistory_age = 48h
+ contactnotifications_age = 31d
+ }
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ host | String | **Optional.** PostgreSQL database host address. Defaults to `localhost`.
+ port | Number | **Optional.** PostgreSQL database port. Defaults to `5432`.
+ user | String | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`.
+ password | String | **Optional.** PostgreSQL database user's password. Defaults to `icinga`.
+ database | String | **Optional.** PostgreSQL database name. Defaults to `icinga`.
+ ssl\_mode | String | **Optional.** Enable SSL connection mode. Value must be set according to the [sslmode setting](https://www.postgresql.org/docs/9.3/static/libpq-connect.html#LIBPQ-CONNSTRING): `prefer`, `require`, `verify-ca`, `verify-full`, `allow`, `disable`.
+ ssl\_key | String | **Optional.** PostgreSQL SSL client key file path.
+ ssl\_cert | String | **Optional.** PostgreSQL SSL certificate file path.
+ ssl\_ca | String | **Optional.** PostgreSQL SSL certificate authority certificate file path.
+ table\_prefix | String | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`.
+ instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`.
+ instance\_description | String | **Optional.** Description for the Icinga 2 instance.
+ 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`.
+ failover\_timeout | Duration | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 30s. Defaults to `30s`.
+ cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup.
+ categories | Array | **Optional.** Array of information types that should be written to the database.
+
+Cleanup Items:
+
+ Name | Type | Description
+ --------------------------------|-----------------------|----------------------------------
+ acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never).
+ commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never).
+ contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never).
+ contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never).
+ downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never).
+ eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never).
+ externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never).
+ flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never).
+ hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never).
+ logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never).
+ notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never).
+ processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never).
+ statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never).
+ servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never).
+ systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never).
+
+Data Categories:
+
+ Name | Description | Required by
+ ---------------------|------------------------|--------------------
+ DbCatConfig | Configuration data | Icinga Web 2
+ DbCatState | Current state data | Icinga Web 2
+ DbCatAcknowledgement | Acknowledgements | Icinga Web 2
+ DbCatComment | Comments | Icinga Web 2
+ DbCatDowntime | Downtimes | Icinga Web 2
+ DbCatEventHandler | Event handler data | Icinga Web 2
+ DbCatExternalCommand | External commands | --
+ DbCatFlapping | Flap detection data | Icinga Web 2
+ DbCatCheck | Check results | --
+ DbCatLog | Log messages | --
+ DbCatNotification | Notifications | Icinga Web 2
+ DbCatProgramStatus | Program status data | Icinga Web 2
+ DbCatRetention | Retention data | Icinga Web 2
+ DbCatStateHistory | Historical state data | Icinga Web 2
+
+The default value for `categories` includes everything required
+by Icinga Web 2 in the table above.
+
+In addition to the category flags listed above the `DbCatEverything`
+flag may be used as a shortcut for listing all flags.
+
+Runtime Attributes:
+
+ Name | Type | Description
+ ----------------------------|-----------------------|-----------------
+ last\_failover | Timestamp | When the last failover happened for this connection (only available with `enable_ha = true`.
+
+### InfluxdbWriter
+
+Writes check result metrics and performance data to a defined InfluxDB host.
+This configuration object is available as [influxdb feature](14-features.md#influxdb-writer).
+
+Example:
+
+```
+object InfluxdbWriter "influxdb" {
+ host = "127.0.0.1"
+ port = 8086
+ database = "icinga2"
+
+ flush_threshold = 1024
+ flush_interval = 10s
+
+ host_template = {
+ measurement = "$host.check_command$"
+ tags = {
+ hostname = "$host.name$"
+ }
+ }
+ service_template = {
+ measurement = "$service.check_command$"
+ tags = {
+ hostname = "$host.name$"
+ service = "$service.name$"
+ }
+ }
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ host | String | **Required.** InfluxDB host address. Defaults to `127.0.0.1`.
+ port | Number | **Required.** InfluxDB HTTP port. Defaults to `8086`.
+ database | String | **Required.** InfluxDB database name. Defaults to `icinga2`.
+ username | String | **Optional.** InfluxDB user name. Defaults to `none`.
+ password | String | **Optional.** InfluxDB user password. Defaults to `none`.
+ ssl\_enable | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`.
+ ssl\_ca\_cert | String | **Optional.** Path to CA certificate to validate the remote host.
+ ssl\_cert | String | **Optional.** Path to host certificate to present to the remote host for mutual verification.
+ ssl\_key | String | **Optional.** Path to host key to accompany the ssl\_cert.
+ host\_template | String | **Required.** Host template to define the InfluxDB line protocol.
+ service\_template | String | **Required.** Service template to define the influxDB line protocol.
+ enable\_send\_thresholds | Boolean | **Optional.** Whether to send warn, crit, min & max tagged data.
+ enable\_send\_metadata | Boolean | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc.
+ flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to InfluxDB. Defaults to `10s`.
+ flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`.
+ enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
+
+Note: If `flush_threshold` is set too low, this will always force the feature to flush all data
+to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
+or similar.
+
+
+
+### LiveStatusListener
+
+Livestatus API interface available as TCP or UNIX socket. Historical table queries
+require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
+pointing to the log files using the `compat_log_path` configuration attribute.
+This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus).
+
+Examples:
+
+```
+object LivestatusListener "livestatus-tcp" {
+ socket_type = "tcp"
+ bind_host = "127.0.0.1"
+ bind_port = "6558"
+}
+
+object LivestatusListener "livestatus-unix" {
+ socket_type = "unix"
+ socket_path = "/var/run/icinga2/cmd/livestatus"
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ socket\_type | String | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`.
+ 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`.
+ bind\_port | Number | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`.
+ 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".
+ compat\_log\_path | String | **Optional.** Path to Icinga 1.x log files. Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LogDir + "/compat"
+
+> **Note**
+>
+> UNIX sockets are not supported on Windows.
+
+### NotificationComponent
+
+The notification component is responsible for sending notifications.
+This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature).
+
+Example:
+
+```
+object NotificationComponent "notification" { }
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ 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".
+
+### OpenTsdbWriter
+
+Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
+This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer).
+
+Example:
+
+```
+object OpenTsdbWriter "opentsdb" {
+ host = "127.0.0.1"
+ port = 4242
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ host | String | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`.
+ port | Number | **Optional.** OpenTSDB port. Defaults to `4242`.
+ enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
+
+
+### PerfdataWriter
+
+Writes check result performance data to a defined path using macro
+pattern consisting of custom attributes and runtime macros.
+This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files).
+
+Example:
+
+```
+object PerfdataWriter "perfdata" {
+ host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
+
+ service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
+
+ 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$"
+ 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$"
+
+ rotation_interval = 15s
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ host\_perfdata\_path | String | **Optional.** Path to the host performance data file. Defaults to SpoolDir + "/perfdata/host-perfdata".
+ service\_perfdata\_path | String | **Optional.** Path to the service performance data file. Defaults to SpoolDir + "/perfdata/service-perfdata".
+ host\_temp\_path | String | **Optional.** Path to the temporary host file. Defaults to SpoolDir + "/tmp/host-perfdata".
+ service\_temp\_path | String | **Optional.** Path to the temporary service file. Defaults to SpoolDir + "/tmp/service-perfdata".
+ host\_format\_template | String | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
+ service\_format\_template | String | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
+ rotation\_interval | Duration | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`.
+ enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`.
+
+When rotating the performance data file the current UNIX timestamp is appended to the path specified
+in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
+
+
+### StatusDataWriter
+
+Periodically writes status and configuration data files which are used by third-party tools.
+This configuration object is available as [statusdata feature](14-features.md#status-data).
+
+> **Note**
+>
+> This feature is DEPRECATED and will be removed in future releases.
+> Check the [roadmap](https://github.com/Icinga/icinga2/milestones).
+
+Example:
+
+```
+object StatusDataWriter "status" {
+ status_path = "/var/cache/icinga2/status.dat"
+ objects_path = "/var/cache/icinga2/objects.cache"
+ update_interval = 30s
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ status\_path | String | **Optional.** Path to the `status.dat` file. Defaults to CacheDir + "/status.dat".
+ objects\_path | String | **Optional.** Path to the `objects.cache` file. Defaults to CacheDir + "/objects.cache".
+ update\_interval | Duration | **Optional.** The interval in which the status files are updated. Defaults to `15s`.
+
+### SyslogLogger
+
+Specifies Icinga 2 logging to syslog.
+This configuration object is available as `syslog` [logging feature](14-features.md#logging).
+
+Example:
+
+```
+object SyslogLogger "syslog" {
+ severity = "warning"
+}
+```
+
+Configuration Attributes:
+
+ Name | Type | Description
+ --------------------------|-----------------------|----------------------------------
+ severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
+ facility | String | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`.
+
+Facility Constants:
+
+ Name | Facility | Description
+ ---------------------|---------------|----------------
+ FacilityAuth | LOG\_AUTH | The authorization system.
+ FacilityAuthPriv | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals.
+ FacilityCron | LOG\_CRON | The cron daemon.
+ FacilityDaemon | LOG\_DAEMON | System daemons that are not provided for explicitly by other facilities.
+ FacilityFtp | LOG\_FTP | The file transfer protocol daemons.
+ FacilityKern | LOG\_KERN | Messages generated by the kernel. These cannot be generated by any user processes.
+ FacilityLocal0 | LOG\_LOCAL0 | Reserved for local use.
+ FacilityLocal1 | LOG\_LOCAL1 | Reserved for local use.
+ FacilityLocal2 | LOG\_LOCAL2 | Reserved for local use.
+ FacilityLocal3 | LOG\_LOCAL3 | Reserved for local use.
+ FacilityLocal4 | LOG\_LOCAL4 | Reserved for local use.
+ FacilityLocal5 | LOG\_LOCAL5 | Reserved for local use.
+ FacilityLocal6 | LOG\_LOCAL6 | Reserved for local use.
+ FacilityLocal7 | LOG\_LOCAL7 | Reserved for local use.
+ FacilityLpr | LOG\_LPR | The line printer spooling system.
+ FacilityMail | LOG\_MAIL | The mail system.
+ FacilityNews | LOG\_NEWS | The network news system.
+ FacilitySyslog | LOG\_SYSLOG | Messages generated internally by syslogd.
+ FacilityUser | LOG\_USER | Messages generated by user processes. This is the default facility identifier if none is specified.
+ FacilityUucp | LOG\_UUCP | The UUCP system.
+
+
+