-#
Config Object Types <a id="object-types"></a>
+# Object Types <a id="object-types"></a>
This chapter provides an overview of all available config object types which can be
instantiated using the `object` keyword.
In addition to that `Object name` is an object reference to
an existing object name as `String` type.
+## Overview <a id="object-types-overview"></a>
+
+* [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 <a id="object-types-runtime-attributes"></a>
+
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).
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 <a id="object-types-monitoring"></a>
-## ApiListener <a id="objecttype-apilistener"></a>
-
-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`.
- 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.
-
-## ApiUser <a id="objecttype-apiuser"></a>
+### ApiUser <a id="objecttype-apiuser"></a>
ApiUser objects are used for authentication against the [Icinga 2 API](12-icinga2-api.md#icinga2-api-authentication).
Available permissions are explained in the [API permissions](12-icinga2-api.md#icinga2-api-permissions)
chapter.
-## CheckCommand <a id="objecttype-checkcommand"></a>
+##
# CheckCommand <a id="objecttype-checkcommand"></a>
A check command definition. Additional default command custom attributes can be
defined here.
arguments | Dictionary | **Optional.** A dictionary of command arguments.
-### CheckCommand Arguments <a id="objecttype-checkcommand-arguments"></a>
+###
# CheckCommand Arguments <a id="objecttype-checkcommand-arguments"></a>
Command arguments can be defined as key-value-pairs in the `arguments`
dictionary. If the argument requires additional configuration, for example
'key' 'value[0]' 'value[1]' 'value[2]'
```
-## CheckerComponent <a id="objecttype-checkcomponent"></a>
-
-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 <a id="objecttype-checkresultreader"></a>
-
-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:
-
-```
-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/".
-
-## Comment <a id="objecttype-comment"></a>
-
-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.
-
-## CompatLogger <a id="objecttype-compatlogger"></a>
-
-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:
-
-```
-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".
-
-
## Dependency <a id="objecttype-dependency"></a>
Dependency objects are used to specify dependencies between hosts and services. Dependencies
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.
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 <a id="objecttype-downtime"></a>
-
-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 <a id="objecttype-elasticsearchwriter"></a>
-
-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 `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 <a id="objecttype-endpoint"></a>
Endpoint objects are used to specify connection information for remote
More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
-## ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
-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 id="objecttype-host"></a>
+
+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 <a id="objecttype-filelogger"></a>
-
-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 <a id="objecttype-gelfwriter"></a>
-
-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 `true`.
-
-
-## GraphiteWriter <a id="objecttype-graphitewriter"></a>
-
-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 `true`.
-
-Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer).
-
-
-
-## Host <a id="objecttype-host"></a>
-
-A host.
-
-Example:
-
-```
-object Host "icinga2-client1.localdomain" {
- display_name = "Linux Client 1"
- address = "192.168.56.111"
- address6 = "2a00:1450:4001:815::2003"
+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\_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.
display\_name | String | **Optional.** A short description of the host group.
groups | Array of object names | **Optional.** An array of nested group names.
-## IcingaApplication <a id="objecttype-icingaapplication"></a>
-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 <a id="objecttype-notification"></a>
+
+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 ]
}
```
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 <a id="objecttype-idomysqlconnection"></a>
-
-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 <a id="objecttype-idopgsqlconnection"></a>
+## NotificationCommand <a id="objecttype-notificationcommand"></a>
-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 <a id="objecttype-influxdbwriter"></a>
-
-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 `true`.
-
-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 <a id="objecttype-livestatuslistener"></a>
-
-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 <a id="objecttype-notification"></a>
-
-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. Note that the states filter is ignored for notifications of type Acknowledgement!
-
-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 id="objecttype-notificationcommand"></a>
-
-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" = {
More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
-## NotificationComponent <a id="objecttype-notificationcomponent"></a>
+## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
-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 <a id="objecttype-opentsdbwriter"></a>
-
-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 `true`.
-
-
-## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
-
-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 `true`.
-
-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 <a id="objecttype-scheduleddowntime"></a>
-
-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:
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`.
groups | Array of object names | **Optional.** An array of nested group names.
-## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
-
-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 <a id="objecttype-sysloglogger"></a>
-
-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 <a id="objecttype-timeperiod"></a>
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:
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 <a id="object-types-runtime"></a>
+
+These objects are generated at runtime by the daemon
+from API actions. Downtime objects are also created
+by ScheduledDowntime objects.
+
+### Comment <a id="objecttype-comment"></a>
+
+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 <a id="objecttype-downtime"></a>
+
+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 <a id="object-types-features"></a>
+
+### ApiListener <a id="objecttype-apilistener"></a>
+
+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 <a id="objecttype-checkercomponent"></a>
+
+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 <a id="objecttype-checkresultreader"></a>
+
+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 <a id="objecttype-compatlogger"></a>
+
+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 <a id="objecttype-elasticsearchwriter"></a>
+
+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 <a id="objecttype-externalcommandlistener"></a>
+
+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 <a id="objecttype-filelogger"></a>
+
+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 <a id="objecttype-gelfwriter"></a>
+
+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 <a id="objecttype-graphitewriter"></a>
+
+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 <a id="objecttype-icingaapplication"></a>
+
+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 <a id="objecttype-idomysqlconnection"></a>
+
+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 <a id="objecttype-idopgsqlconnection"></a>
+
+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 <a id="objecttype-influxdbwriter"></a>
+
+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 <a id="objecttype-livestatuslistener"></a>
+
+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 <a id="objecttype-notificationcomponent"></a>
+
+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 <a id="objecttype-opentsdbwriter"></a>
+
+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 <a id="objecttype-perfdatawriter"></a>
+
+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 <a id="objecttype-statusdatawriter"></a>
+
+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 <a id="objecttype-sysloglogger"></a>
+
+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.
+
+
+
projects / icinga2 / blobdiff