From 2ce82b56d480cb0af469cc5d6feb8eb52c3f9c49 Mon Sep 17 00:00:00 2001 From: Michael Friedrich Date: Wed, 3 Apr 2019 15:00:36 +0200 Subject: [PATCH] Docs: Improve config object types chapter --- doc/09-object-types.md | 1679 ++++++++++++++++++++-------------------- 1 file changed, 851 insertions(+), 828 deletions(-) diff --git a/doc/09-object-types.md b/doc/09-object-types.md index f05f4f0f9..2e3ceaf7e 100644 --- a/doc/09-object-types.md +++ b/doc/09-object-types.md @@ -1,4 +1,4 @@ -# Config Object Types +# Object Types This chapter provides an overview of all available config object types which can be instantiated using the `object` keyword. @@ -12,6 +12,14 @@ You should note that the `Timestamp` type is a `Number`. In addition to that `Object name` is an object reference to an existing object name as `String` type. +## Overview + +* [Monitoring Objects](09-object-types.md#object-types-monitoring) such as host, service, etc. +* [Runtime Objects](09-object-types.md#object-types-runtime) generated by Icinga itself. +* [Features](09-object-types.md#object-types-features) available via `icinga2 feature` CLI command. + +## Common Runtime Attributes + Configuration objects share these runtime attributes which cannot be modified by the user. You can access these attributes using the [Icinga 2 API](12-icinga2-api.md#icinga2-api-config-objects). @@ -27,77 +35,9 @@ the [Icinga 2 API](12-icinga2-api.md#icinga2-api-config-objects). package | String | [Configuration package name](12-icinga2-api.md#icinga2-api-config-management) this object belongs to. Local configuration is set to `_etc`, runtime created objects use `_api`. source\_location | Dictionary | Location information where the configuration files are stored. +## Monitoring Objects -## ApiListener - -ApiListener objects are used for distributed monitoring setups -and API usage specifying the certificate files used for ssl -authorization and additional restrictions. -This configuration object is available as [api feature](11-cli-commands.md#cli-command-feature). - -The `TicketSalt` constant must be defined in [constants.conf](04-configuring-icinga-2.md#constants-conf). - -Example: - -``` -object ApiListener "api" { - accept_commands = true - accept_config = true - - ticket_salt = TicketSalt -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------------------|-----------------------|---------------------------------- - cert\_path | String | **Deprecated.** Path to the public key. - key\_path | String | **Deprecated.** Path to the private key. - ca\_path | String | **Deprecated.** Path to the CA certificate file. - ticket\_salt | String | **Optional.** Private key for [CSR auto-signing](06-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing). **Required** for a signing master instance. - crl\_path | String | **Optional.** Path to the CRL file. - bind\_host | String | **Optional.** The IP address the api listener should be bound to. 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. - -## ApiUser +### ApiUser ApiUser objects are used for authentication against the [Icinga 2 API](12-icinga2-api.md#icinga2-api-authentication). @@ -121,7 +61,7 @@ Configuration Attributes: Available permissions are explained in the [API permissions](12-icinga2-api.md#icinga2-api-permissions) chapter. -## CheckCommand +### CheckCommand A check command definition. Additional default command custom attributes can be defined here. @@ -173,7 +113,7 @@ Configuration Attributes: arguments | Dictionary | **Optional.** A dictionary of command arguments. -### CheckCommand Arguments +#### CheckCommand Arguments Command arguments can be defined as key-value-pairs in the `arguments` dictionary. If the argument requires additional configuration, for example @@ -248,104 +188,6 @@ Argument array with `repeat_key = false`: 'key' 'value[0]' 'value[1]' 'value[2]' ``` -## CheckerComponent - -The checker component is responsible for scheduling active checks. -This configuration object is available as [checker feature](11-cli-commands.md#cli-command-feature). - -Example: - -``` -object CheckerComponent "checker" { } -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - concurrent\_checks | Number | **Optional and deprecated.** The maximum number of concurrent checks. Was replaced by global constant `MaxConcurrentChecks` which will be set if you still use `concurrent_checks`. - -## CheckResultReader - -Reads Icinga 1.x check result files from a directory. This functionality is provided -to help existing Icinga 1.x users and might be useful for migration scenarios. - -> **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/". - -## Comment - -Comments created at runtime are represented as objects. -Note: This is for reference only. You can create comments -with the [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) API action. - -Example: - -``` -object Comment "my-comment" { - host_name = "localhost" - author = "icingaadmin" - text = "This is a comment." - entry_time = 1234567890 -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - host\_name | Object name | **Required.** The name of the host this comment belongs to. - service\_name | Object name | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment. - author | String | **Required.** The author's name. - text | String | **Required.** The comment text. - entry\_time | Timestamp | **Optional.** The UNIX timestamp when this comment was added. If omitted, the entry time is volatile! - entry\_type | Number | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4). - expire\_time | Timestamp | **Optional.** The comment's expire time as UNIX timestamp. - persistent | Boolean | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed. - -## CompatLogger - -Writes log files in a format that's compatible with Icinga 1.x. -This configuration object is available as [compatlog feature](14-features.md#compat-logging). - -> **Note** -> -> This feature is DEPRECATED and will be removed in future releases. -> Check the [roadmap](https://github.com/Icinga/icinga2/milestones). - -Example: - -``` -object CompatLogger "compatlog" { - log_dir = "/var/log/icinga2/compat" - rotation_method = "DAILY" -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - log\_dir | String | **Optional.** Path to the compat log directory. Defaults to LogDir + "/compat". - rotation\_method | String | **Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY". - - ## Dependency Dependency objects are used to specify dependencies between hosts and services. Dependencies @@ -452,96 +294,6 @@ Dependency objects have composite names, i.e. their names are based on the `chil name you specified. This means you can define more than one object with the same (short) name as long as one of the `child_host_name` and `child_service_name` attributes has a different value. -## Downtime - -Downtimes created at runtime are represented as objects. -You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action. - -Example: - -``` -object Downtime "my-downtime" { - host_name = "localhost" - author = "icingaadmin" - comment = "This is a downtime." - start_time = 1505312869 - end_time = 1505312924 -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - host\_name | Object name | **Required.** The name of the host this comment belongs to. - service\_name | Object name | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment. - author | String | **Required.** The author's name. - comment | String | **Required.** The comment text. - start\_time | Timestamp | **Required.** The start time as UNIX timestamp. - end\_time | Timestamp | **Required.** The end time as UNIX timestamp. - duration | Number | **Optional.** The duration as number. - entry\_time | Timestamp | **Optional.** The UNIX timestamp when this downtime was added. - fixed | Boolean | **Optional.** Whether the downtime is fixed (true) or flexible (false). Defaults to flexible. Details in the [advanced topics chapter](08-advanced-topics.md#fixed-flexible-downtimes). - triggers | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime. - -Runtime Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - trigger\_time | Timestamp | The UNIX timestamp when this downtime was triggered. - triggered\_by | Object name | The name of the downtime this downtime was triggered by. - - -## ElasticsearchWriter - -Writes check result metrics and performance data to an Elasticsearch instance. -This configuration object is available as [elasticsearch feature](14-features.md#elasticsearch-writer). - -Example: - -``` -object ElasticsearchWriter "elasticsearch" { - host = "127.0.0.1" - port = 9200 - index = "icinga2" - - enable_send_perfdata = true - - flush_threshold = 1024 - flush_interval = 10 -} -``` - -The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`. - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - host | String | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`. - port | Number | **Required.** Elasticsearch port. Defaults to `9200`. - index | String | **Required.** Elasticsearch index name. Defaults to `icinga2`. - enable\_send\_perfdata | Boolean | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`. - flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to Elasticsearch. Defaults to `10s`. - flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to `1024`. - username | String | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy. - password | String | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy. - enable\_tls | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy. - ca\_path | String | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`. - cert\_path | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`. - key\_path | String | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`. - 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. - ## Endpoint Endpoint objects are used to specify connection information for remote @@ -604,109 +356,6 @@ Command arguments can be used the same way as for [CheckCommand objects](09-obje More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands). -## ExternalCommandListener - -Implements the Icinga 1.x command pipe which can be used to send commands to Icinga. -This configuration object is available as [command feature](14-features.md#external-commands). - -> **Note** -> -> This feature is DEPRECATED and will be removed in future releases. -> Check the [roadmap](https://github.com/Icinga/icinga2/milestones). - -Example: - -``` -object ExternalCommandListener "command" { - command_path = "/var/run/icinga2/cmd/icinga2.cmd" -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - command\_path | String | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd". - - - -## FileLogger - -Specifies Icinga 2 logging to a file. -This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging). - -Example: - -``` -object FileLogger "debug-file" { - severity = "debug" - path = "/var/log/icinga2/debug.log" -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - path | String | **Required.** The log path. - severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information". - - -## GelfWriter - -Writes event log entries to a defined GELF receiver host (Graylog, Logstash). -This configuration object is available as [gelf feature](14-features.md#gelfwriter). - -Example: - -``` -object GelfWriter "gelf" { - host = "127.0.0.1" - port = 12201 -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - host | String | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`. - port | Number | **Optional.** GELF receiver port. Defaults to `12201`. - source | String | **Optional.** Source name for this instance. Defaults to `icinga2`. - enable\_send\_perfdata | Boolean | **Optional.** Enable performance data for 'CHECK RESULT' events. - enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`. - - -## GraphiteWriter - -Writes check result metrics and performance data to a defined -Graphite Carbon host. -This configuration object is available as [graphite feature](14-features.md#graphite-carbon-cache-writer). - -Example: - -``` -object GraphiteWriter "graphite" { - host = "127.0.0.1" - port = 2003 -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - host | String | **Optional.** Graphite Carbon host address. Defaults to `127.0.0.1`. - port | Number | **Optional.** Graphite Carbon port. Defaults to `2003`. - host\_name\_template | String | **Optional.** Metric prefix for host name. Defaults to `icinga2.$host.name$.host.$host.check_command$`. - service\_name\_template | String | **Optional.** Metric prefix for service name. Defaults to `icinga2.$host.name$.services.$service.name$.$service.check_command$`. - enable\_send\_thresholds | Boolean | **Optional.** Send additional threshold metrics. Defaults to `false`. - enable\_send\_metadata | Boolean | **Optional.** Send additional metadata metrics. Defaults to `false`. - enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`. - -Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer). - - ## Host @@ -820,319 +469,6 @@ Configuration Attributes: display\_name | String | **Optional.** A short description of the host group. groups | Array of object names | **Optional.** An array of nested group names. -## IcingaApplication - -The IcingaApplication object is required to start Icinga 2. -The object name must be `app`. If the object configuration -is missing, Icinga 2 will automatically create an IcingaApplication -object. - -Example: - -``` -object IcingaApplication "app" { - enable_perfdata = false -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - enable\_notifications | Boolean | **Optional.** Whether notifications are globally enabled. Defaults to true. - enable\_event\_handlers | Boolean | **Optional.** Whether event handlers are globally enabled. Defaults to true. - enable\_flapping | Boolean | **Optional.** Whether flap detection is globally enabled. Defaults to true. - enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true. - enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true. - enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true. - vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally. - environment | String | **Optional.** Specify the Icinga environment. This overrides the `Environment` constant specified in the configuration or on the CLI with `--define`. Defaults to empty. - -## IdoMySqlConnection - -IDO database adapter for MySQL. -This configuration object is available as [ido-mysql feature](14-features.md#db-ido). - -Example: - -``` -object IdoMysqlConnection "mysql-ido" { - host = "127.0.0.1" - port = 3306 - user = "icinga" - password = "icinga" - database = "icinga" - - cleanup = { - downtimehistory_age = 48h - contactnotifications_age = 31d - } -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - host | String | **Optional.** MySQL database host address. Defaults to `localhost`. - port | Number | **Optional.** MySQL database port. Defaults to `3306`. - socket\_path | String | **Optional.** MySQL socket path. - user | String | **Optional.** MySQL database user with read/write permission to the icinga database. Defaults to `icinga`. - password | String | **Optional.** MySQL database user's password. Defaults to `icinga`. - database | String | **Optional.** MySQL database name. Defaults to `icinga`. - enable\_ssl | Boolean | **Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options. - ssl\_key | String | **Optional.** MySQL SSL client key file path. - ssl\_cert | String | **Optional.** MySQL SSL certificate file path. - ssl\_ca | String | **Optional.** MySQL SSL certificate authority certificate file path. - ssl\_capath | String | **Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path. - ssl\_cipher | String | **Optional.** MySQL SSL list of allowed ciphers. - table\_prefix | String | **Optional.** MySQL database table prefix. Defaults to `icinga_`. - instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`. - instance\_description | String | **Optional.** Description for the Icinga 2 instance. - enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to `true`. - failover\_timeout | Duration | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 30s. Defaults to `30s`. - cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup. - categories | Array | **Optional.** Array of information types that should be written to the database. - -Cleanup Items: - - Name | Type | Description - --------------------------------|-----------------------|---------------------------------- - acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never). - commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never). - contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never). - contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never). - downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never). - eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never). - externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never). - flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never). - hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never). - logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never). - notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never). - processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never). - statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never). - servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never). - systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never). - -Data Categories: - - Name | Description | Required by - ---------------------|------------------------|-------------------- - DbCatConfig | Configuration data | Icinga Web 2 - DbCatState | Current state data | Icinga Web 2 - DbCatAcknowledgement | Acknowledgements | Icinga Web 2 - DbCatComment | Comments | Icinga Web 2 - DbCatDowntime | Downtimes | Icinga Web 2 - DbCatEventHandler | Event handler data | Icinga Web 2 - DbCatExternalCommand | External commands | -- - DbCatFlapping | Flap detection data | Icinga Web 2 - DbCatCheck | Check results | -- - DbCatLog | Log messages | -- - DbCatNotification | Notifications | Icinga Web 2 - DbCatProgramStatus | Program status data | Icinga Web 2 - DbCatRetention | Retention data | Icinga Web 2 - DbCatStateHistory | Historical state data | Icinga Web 2 - -The default value for `categories` includes everything required -by Icinga Web 2 in the table above. - -In addition to the category flags listed above the `DbCatEverything` -flag may be used as a shortcut for listing all flags. - -Runtime Attributes: - - Name | Type | Description - ----------------------------|-----------------------|----------------- - last\_failover | Timestamp | When the last failover happened for this connection (only available with `enable_ha = true`. - -## IdoPgsqlConnection - -IDO database adapter for PostgreSQL. -This configuration object is available as [ido-pgsql feature](14-features.md#db-ido). - -Example: - -``` -object IdoPgsqlConnection "pgsql-ido" { - host = "127.0.0.1" - port = 5432 - user = "icinga" - password = "icinga" - database = "icinga" - - cleanup = { - downtimehistory_age = 48h - contactnotifications_age = 31d - } -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - host | String | **Optional.** PostgreSQL database host address. Defaults to `localhost`. - port | Number | **Optional.** PostgreSQL database port. Defaults to `5432`. - user | String | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`. - password | String | **Optional.** PostgreSQL database user's password. Defaults to `icinga`. - database | String | **Optional.** PostgreSQL database name. Defaults to `icinga`. - ssl\_mode | String | **Optional.** Enable SSL connection mode. Value must be set according to the [sslmode setting](https://www.postgresql.org/docs/9.3/static/libpq-connect.html#LIBPQ-CONNSTRING): `prefer`, `require`, `verify-ca`, `verify-full`, `allow`, `disable`. - ssl\_key | String | **Optional.** PostgreSQL SSL client key file path. - ssl\_cert | String | **Optional.** PostgreSQL SSL certificate file path. - ssl\_ca | String | **Optional.** PostgreSQL SSL certificate authority certificate file path. - table\_prefix | String | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`. - instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`. - instance\_description | String | **Optional.** Description for the Icinga 2 instance. - enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to `true`. - failover\_timeout | Duration | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 30s. Defaults to `30s`. - cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup. - categories | Array | **Optional.** Array of information types that should be written to the database. - -Cleanup Items: - - Name | Type | Description - --------------------------------|-----------------------|---------------------------------- - acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never). - commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never). - contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never). - contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never). - downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never). - eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never). - externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never). - flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never). - hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never). - logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never). - notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never). - processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never). - statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never). - servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never). - systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never). - -Data Categories: - - Name | Description | Required by - ---------------------|------------------------|-------------------- - DbCatConfig | Configuration data | Icinga Web 2 - DbCatState | Current state data | Icinga Web 2 - DbCatAcknowledgement | Acknowledgements | Icinga Web 2 - DbCatComment | Comments | Icinga Web 2 - DbCatDowntime | Downtimes | Icinga Web 2 - DbCatEventHandler | Event handler data | Icinga Web 2 - DbCatExternalCommand | External commands | -- - DbCatFlapping | Flap detection data | Icinga Web 2 - DbCatCheck | Check results | -- - DbCatLog | Log messages | -- - DbCatNotification | Notifications | Icinga Web 2 - DbCatProgramStatus | Program status data | Icinga Web 2 - DbCatRetention | Retention data | Icinga Web 2 - DbCatStateHistory | Historical state data | Icinga Web 2 - -The default value for `categories` includes everything required -by Icinga Web 2 in the table above. - -In addition to the category flags listed above the `DbCatEverything` -flag may be used as a shortcut for listing all flags. - -Runtime Attributes: - - Name | Type | Description - ----------------------------|-----------------------|----------------- - last\_failover | Timestamp | When the last failover happened for this connection (only available with `enable_ha = true`. - -## InfluxdbWriter - -Writes check result metrics and performance data to a defined InfluxDB host. -This configuration object is available as [influxdb feature](14-features.md#influxdb-writer). - -Example: - -``` -object InfluxdbWriter "influxdb" { - host = "127.0.0.1" - port = 8086 - database = "icinga2" - - flush_threshold = 1024 - flush_interval = 10s - - host_template = { - measurement = "$host.check_command$" - tags = { - hostname = "$host.name$" - } - } - service_template = { - measurement = "$service.check_command$" - tags = { - hostname = "$host.name$" - service = "$service.name$" - } - } -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - host | String | **Required.** InfluxDB host address. Defaults to `127.0.0.1`. - port | Number | **Required.** InfluxDB HTTP port. Defaults to `8086`. - database | String | **Required.** InfluxDB database name. Defaults to `icinga2`. - username | String | **Optional.** InfluxDB user name. Defaults to `none`. - password | String | **Optional.** InfluxDB user password. Defaults to `none`. - ssl\_enable | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. - ssl\_ca\_cert | String | **Optional.** Path to CA certificate to validate the remote host. - ssl\_cert | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. - ssl\_key | String | **Optional.** Path to host key to accompany the ssl\_cert. - host\_template | String | **Required.** Host template to define the InfluxDB line protocol. - service\_template | String | **Required.** Service template to define the influxDB line protocol. - enable\_send\_thresholds | Boolean | **Optional.** Whether to send warn, crit, min & max tagged data. - enable\_send\_metadata | Boolean | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc. - flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to InfluxDB. Defaults to `10s`. - flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`. - enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`. - -Note: If `flush_threshold` is set too low, this will always force the feature to flush all data -to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second -or similar. - - - -## LiveStatusListener - -Livestatus API interface available as TCP or UNIX socket. Historical table queries -require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled -pointing to the log files using the `compat_log_path` configuration attribute. -This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus). - -Examples: - -``` -object LivestatusListener "livestatus-tcp" { - socket_type = "tcp" - bind_host = "127.0.0.1" - bind_port = "6558" -} - -object LivestatusListener "livestatus-unix" { - socket_type = "unix" - socket_path = "/var/run/icinga2/cmd/livestatus" -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - socket\_type | String | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`. - bind\_host | String | **Optional.** Only valid when `socket_type` is set to `tcp`. Host address to listen on for connections. Defaults to `127.0.0.1`. - bind\_port | Number | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`. - socket\_path | String | **Optional.** Only valid when `socket_type` is set to `unix`. Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus". - compat\_log\_path | String | **Optional.** Path to Icinga 1.x log files. Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LogDir + "/compat" - -> **Note** -> -> UNIX sockets are not supported on Windows. ## Notification @@ -1315,84 +651,6 @@ Command arguments can be used the same way as for [CheckCommand objects](09-obje More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands). -## NotificationComponent - -The notification component is responsible for sending notifications. -This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature). - -Example: - -``` -object NotificationComponent "notification" { } -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-notifications). Disabling this currently only affects reminder notifications. Defaults to "true". - -## OpenTsdbWriter - -Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net). -This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer). - -Example: - -``` -object OpenTsdbWriter "opentsdb" { - host = "127.0.0.1" - port = 4242 -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - host | String | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`. - port | Number | **Optional.** OpenTSDB port. Defaults to `4242`. - enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`. - - -## PerfdataWriter - -Writes check result performance data to a defined path using macro -pattern consisting of custom attributes and runtime macros. -This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files). - -Example: - -``` -object PerfdataWriter "perfdata" { - host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata" - - service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata" - - host_format_template = "DATATYPE::HOSTPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tHOSTPERFDATA::$host.perfdata$\tHOSTCHECKCOMMAND::$host.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$" - service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.name$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.state_type$" - - rotation_interval = 15s -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - host\_perfdata\_path | String | **Optional.** Path to the host performance data file. Defaults to SpoolDir + "/perfdata/host-perfdata". - service\_perfdata\_path | String | **Optional.** Path to the service performance data file. Defaults to SpoolDir + "/perfdata/service-perfdata". - host\_temp\_path | String | **Optional.** Path to the temporary host file. Defaults to SpoolDir + "/tmp/host-perfdata". - service\_temp\_path | String | **Optional.** Path to the temporary service file. Defaults to SpoolDir + "/tmp/service-perfdata". - host\_format\_template | String | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios. - service\_format\_template | String | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios. - rotation\_interval | Duration | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`. - enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`. - -When rotating the performance data file the current UNIX timestamp is appended to the path specified -in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename. - - ## ScheduledDowntime ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services. @@ -1568,79 +826,6 @@ Configuration Attributes: groups | Array of object names | **Optional.** An array of nested group names. -## StatusDataWriter - -Periodically writes status and configuration data files which are used by third-party tools. -This configuration object is available as [statusdata feature](14-features.md#status-data). - -> **Note** -> -> This feature is DEPRECATED and will be removed in future releases. -> Check the [roadmap](https://github.com/Icinga/icinga2/milestones). - -Example: - -``` -object StatusDataWriter "status" { - status_path = "/var/cache/icinga2/status.dat" - objects_path = "/var/cache/icinga2/objects.cache" - update_interval = 30s -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - status\_path | String | **Optional.** Path to the `status.dat` file. Defaults to CacheDir + "/status.dat". - objects\_path | String | **Optional.** Path to the `objects.cache` file. Defaults to CacheDir + "/objects.cache". - update\_interval | Duration | **Optional.** The interval in which the status files are updated. Defaults to `15s`. - - -## SyslogLogger - -Specifies Icinga 2 logging to syslog. -This configuration object is available as `syslog` [logging feature](14-features.md#logging). - -Example: - -``` -object SyslogLogger "syslog" { - severity = "warning" -} -``` - -Configuration Attributes: - - Name | Type | Description - --------------------------|-----------------------|---------------------------------- - severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning". - facility | String | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`. - -Facility Constants: - - Name | Facility | Description - ---------------------|---------------|---------------- - FacilityAuth | LOG\_AUTH | The authorization system. - FacilityAuthPriv | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals. - FacilityCron | LOG\_CRON | The cron daemon. - FacilityDaemon | LOG\_DAEMON | System daemons that are not provided for explicitly by other facilities. - FacilityFtp | LOG\_FTP | The file transfer protocol daemons. - FacilityKern | LOG\_KERN | Messages generated by the kernel. These cannot be generated by any user processes. - FacilityLocal0 | LOG\_LOCAL0 | Reserved for local use. - FacilityLocal1 | LOG\_LOCAL1 | Reserved for local use. - FacilityLocal2 | LOG\_LOCAL2 | Reserved for local use. - FacilityLocal3 | LOG\_LOCAL3 | Reserved for local use. - FacilityLocal4 | LOG\_LOCAL4 | Reserved for local use. - FacilityLocal5 | LOG\_LOCAL5 | Reserved for local use. - FacilityLocal6 | LOG\_LOCAL6 | Reserved for local use. - FacilityLocal7 | LOG\_LOCAL7 | Reserved for local use. - FacilityLpr | LOG\_LPR | The line printer spooling system. - FacilityMail | LOG\_MAIL | The mail system. - FacilityNews | LOG\_NEWS | The network news system. - FacilitySyslog | LOG\_SYSLOG | Messages generated internally by syslogd. - FacilityUser | LOG\_USER | Messages generated by user processes. This is the default facility identifier if none is specified. - FacilityUucp | LOG\_UUCP | The UUCP system. ## TimePeriod @@ -1821,3 +1006,841 @@ 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 + +These objects are generated at runtime by the daemon +from API actions. Downtime objects are also created +by ScheduledDowntime objects. + +### Comment + +Comments created at runtime are represented as objects. +Note: This is for reference only. You can create comments +with the [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) API action. + +Example: + +``` +object Comment "my-comment" { + host_name = "localhost" + author = "icingaadmin" + text = "This is a comment." + entry_time = 1234567890 +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + host\_name | Object name | **Required.** The name of the host this comment belongs to. + service\_name | Object name | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment. + author | String | **Required.** The author's name. + text | String | **Required.** The comment text. + entry\_time | Timestamp | **Optional.** The UNIX timestamp when this comment was added. If omitted, the entry time is volatile! + entry\_type | Number | **Optional.** The comment type (`User` = 1, `Downtime` = 2, `Flapping` = 3, `Acknowledgement` = 4). + expire\_time | Timestamp | **Optional.** The comment's expire time as UNIX timestamp. + persistent | Boolean | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed. + +### Downtime + +Downtimes created at runtime are represented as objects. +You can create downtimes with the [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) API action. + +Example: + +``` +object Downtime "my-downtime" { + host_name = "localhost" + author = "icingaadmin" + comment = "This is a downtime." + start_time = 1505312869 + end_time = 1505312924 +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + host\_name | Object name | **Required.** The name of the host this comment belongs to. + service\_name | Object name | **Optional.** The short name of the service this comment belongs to. If omitted, this comment object is treated as host comment. + author | String | **Required.** The author's name. + comment | String | **Required.** The comment text. + start\_time | Timestamp | **Required.** The start time as UNIX timestamp. + end\_time | Timestamp | **Required.** The end time as UNIX timestamp. + duration | Number | **Optional.** The duration as number. + entry\_time | Timestamp | **Optional.** The UNIX timestamp when this downtime was added. + fixed | Boolean | **Optional.** Whether the downtime is fixed (true) or flexible (false). Defaults to flexible. Details in the [advanced topics chapter](08-advanced-topics.md#fixed-flexible-downtimes). + triggers | Array of object names | **Optional.** List of downtimes which should be triggered by this downtime. + +Runtime Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + trigger\_time | Timestamp | The UNIX timestamp when this downtime was triggered. + triggered\_by | Object name | The name of the downtime this downtime was triggered by. + + + +## Features + +### ApiListener + +ApiListener objects are used for distributed monitoring setups +and API usage specifying the certificate files used for ssl +authorization and additional restrictions. +This configuration object is available as [api feature](11-cli-commands.md#cli-command-feature). + +The `TicketSalt` constant must be defined in [constants.conf](04-configuring-icinga-2.md#constants-conf). + +Example: + +``` +object ApiListener "api" { + accept_commands = true + accept_config = true + + ticket_salt = TicketSalt +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------------------|-----------------------|---------------------------------- + cert\_path | String | **Deprecated.** Path to the public key. + key\_path | String | **Deprecated.** Path to the private key. + ca\_path | String | **Deprecated.** Path to the CA certificate file. + ticket\_salt | String | **Optional.** Private key for [CSR auto-signing](06-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing). **Required** for a signing master instance. + crl\_path | String | **Optional.** Path to the CRL file. + bind\_host | String | **Optional.** The IP address the api listener should be bound to. If not specified, the ApiListener is bound to `::` and listens for both IPv4 and IPv6 connections. + bind\_port | Number | **Optional.** The port the api listener should be bound to. Defaults to `5665`. + accept\_config | Boolean | **Optional.** Accept zone configuration. Defaults to `false`. + accept\_commands | Boolean | **Optional.** Accept remote commands. Defaults to `false`. + max\_anonymous\_clients | Number | **Optional.** Limit the number of anonymous client connections (not configured endpoints and signing requests). + cipher\_list | String | **Optional.** Cipher list that is allowed. For a list of available ciphers run `openssl ciphers`. Defaults to `ALL:!LOW:!WEAK:!MEDIUM:!EXP:!NULL`. + tls\_protocolmin | String | **Optional.** Minimum TLS protocol version. Must be one of `TLSv1`, `TLSv1.1` or `TLSv1.2`. Defaults to `TLSv1`. + tls\_handshake\_timeout | Number | **Optional.** TLS Handshake timeout. Defaults to `10s`. + access\_control\_allow\_origin | Array | **Optional.** Specifies an array of origin URLs that may access the API. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Origin) + access\_control\_allow\_credentials | Boolean | **Deprecated.** Indicates whether or not the actual request can be made using credentials. Defaults to `true`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Credentials) + access\_control\_allow\_headers | String | **Deprecated.** Used in response to a preflight request to indicate which HTTP headers can be used when making the actual request. Defaults to `Authorization`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Headers) + access\_control\_allow\_methods | String | **Deprecated.** Used in response to a preflight request to indicate which HTTP methods can be used when making the actual request. Defaults to `GET, POST, PUT, DELETE`. [(MDN docs)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#Access-Control-Allow-Methods) + environment | String | **Optional.** Used as suffix in TLS SNI extension name; default from constant `ApiEnvironment`, which is empty. + +The attributes `access_control_allow_credentials`, `access_control_allow_headers` and `access_control_allow_methods` +are controlled by Icinga 2 and are not changeable by config any more. + + +The ApiListener type expects its certificate files to be in the following locations: + + Type | Location + ---------------------|------------------------------------- + Private key | `DataDir + "/certs/" + NodeName + ".key"` + Certificate file | `DataDir + "/certs/" + NodeName + ".crt"` + CA certificate file | `DataDir + "/certs/ca.crt"` + +If the deprecated attributes `cert_path`, `key_path` and/or `ca_path` are specified Icinga 2 +copies those files to the new location in `DataDir + "/certs"` unless the +file(s) there are newer. + +Please check the [upgrading chapter](16-upgrading-icinga-2.md#upgrading-to-2-8-certificate-paths) for more details. + +While Icinga 2 and the underlying OpenSSL library use sane and secure defaults, the attributes +`cipher_list` and `tls_protocolmin` can be used to increase communication security. A good source +for a more secure configuration is provided by the [Mozilla Wiki](https://wiki.mozilla.org/Security/Server_Side_TLS). +Ensure to use the same configuration for both attributes on **all** endpoints to avoid communication problems which +requires to use `cipher_list` compatible with the endpoint using the oldest version of the OpenSSL library. If using +other tools to connect to the API ensure also compatibility with them as this setting affects not only inter-cluster +communcation but also the REST API. + +### CheckerComponent + +The checker component is responsible for scheduling active checks. +This configuration object is available as [checker feature](11-cli-commands.md#cli-command-feature). + +Example: + +``` +object CheckerComponent "checker" { } +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + concurrent\_checks | Number | **Optional and deprecated.** The maximum number of concurrent checks. Was replaced by global constant `MaxConcurrentChecks` which will be set if you still use `concurrent_checks`. + +### CheckResultReader + +Reads Icinga 1.x check result files from a directory. This functionality is provided +to help existing Icinga 1.x users and might be useful for migration scenarios. + +> **Note** +> +> This feature is DEPRECATED and will be removed in future releases. +> Check the [roadmap](https://github.com/Icinga/icinga2/milestones). + +Example: + +``` +object CheckResultReader "reader" { + spool_dir = "/data/check-results" +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + spool\_dir | String | **Optional.** The directory which contains the check result files. Defaults to DataDir + "/spool/checkresults/". + +### CompatLogger + +Writes log files in a format that's compatible with Icinga 1.x. +This configuration object is available as [compatlog feature](14-features.md#compat-logging). + +> **Note** +> +> This feature is DEPRECATED and will be removed in future releases. +> Check the [roadmap](https://github.com/Icinga/icinga2/milestones). + +Example: + +``` +object CompatLogger "compatlog" { + log_dir = "/var/log/icinga2/compat" + rotation_method = "DAILY" +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + log\_dir | String | **Optional.** Path to the compat log directory. Defaults to LogDir + "/compat". + rotation\_method | String | **Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY". + + +### ElasticsearchWriter + +Writes check result metrics and performance data to an Elasticsearch instance. +This configuration object is available as [elasticsearch feature](14-features.md#elasticsearch-writer). + +Example: + +``` +object ElasticsearchWriter "elasticsearch" { + host = "127.0.0.1" + port = 9200 + index = "icinga2" + + enable_send_perfdata = true + + flush_threshold = 1024 + flush_interval = 10 +} +``` + +The index is rotated daily, as is recommended by Elastic, meaning the index will be renamed to `$index-$d.$M.$y`. + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + host | String | **Required.** Elasticsearch host address. Defaults to `127.0.0.1`. + port | Number | **Required.** Elasticsearch port. Defaults to `9200`. + index | String | **Required.** Elasticsearch index name. Defaults to `icinga2`. + enable\_send\_perfdata | Boolean | **Optional.** Send parsed performance data metrics for check results. Defaults to `false`. + flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to Elasticsearch. Defaults to `10s`. + flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to Elasticsearch. Defaults to `1024`. + username | String | **Optional.** Basic auth username if Elasticsearch is hidden behind an HTTP proxy. + password | String | **Optional.** Basic auth password if Elasticsearch is hidden behind an HTTP proxy. + enable\_tls | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. Requires an HTTP proxy. + ca\_path | String | **Optional.** Path to CA certificate to validate the remote host. Requires `enable_tls` set to `true`. + cert\_path | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. Requires `enable_tls` set to `true`. + key\_path | String | **Optional.** Path to host key to accompany the cert\_path. Requires `enable_tls` set to `true`. + enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`. + +Note: If `flush_threshold` is set too low, this will force the feature to flush all data to Elasticsearch too often. +Experiment with the setting, if you are processing more than 1024 metrics per second or similar. + +Basic auth is supported with the `username` and `password` attributes. This requires an +HTTP proxy (Nginx, etc.) in front of the Elasticsearch instance. Check [this blogpost](https://blog.netways.de/2017/09/14/secure-elasticsearch-and-kibana-with-an-nginx-http-proxy/) +for an example. + +TLS for the HTTP proxy can be enabled with `enable_tls`. In addition to that +you can specify the certificates with the `ca_path`, `cert_path` and `cert_key` attributes. + +### ExternalCommandListener + +Implements the Icinga 1.x command pipe which can be used to send commands to Icinga. +This configuration object is available as [command feature](14-features.md#external-commands). + +> **Note** +> +> This feature is DEPRECATED and will be removed in future releases. +> Check the [roadmap](https://github.com/Icinga/icinga2/milestones). + +Example: + +``` +object ExternalCommandListener "command" { + command_path = "/var/run/icinga2/cmd/icinga2.cmd" +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + command\_path | String | **Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd". + + + +### FileLogger + +Specifies Icinga 2 logging to a file. +This configuration object is available as `mainlog` and `debuglog` [logging feature](14-features.md#logging). + +Example: + +``` +object FileLogger "debug-file" { + severity = "debug" + path = "/var/log/icinga2/debug.log" +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + path | String | **Required.** The log path. + severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information". + + +### GelfWriter + +Writes event log entries to a defined GELF receiver host (Graylog, Logstash). +This configuration object is available as [gelf feature](14-features.md#gelfwriter). + +Example: + +``` +object GelfWriter "gelf" { + host = "127.0.0.1" + port = 12201 +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + host | String | **Optional.** GELF receiver host address. Defaults to `127.0.0.1`. + port | Number | **Optional.** GELF receiver port. Defaults to `12201`. + source | String | **Optional.** Source name for this instance. Defaults to `icinga2`. + enable\_send\_perfdata | Boolean | **Optional.** Enable performance data for 'CHECK RESULT' events. + enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`. + + +### GraphiteWriter + +Writes check result metrics and performance data to a defined +Graphite Carbon host. +This configuration object is available as [graphite feature](14-features.md#graphite-carbon-cache-writer). + +Example: + +``` +object GraphiteWriter "graphite" { + host = "127.0.0.1" + port = 2003 +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + host | String | **Optional.** Graphite Carbon host address. Defaults to `127.0.0.1`. + port | Number | **Optional.** Graphite Carbon port. Defaults to `2003`. + host\_name\_template | String | **Optional.** Metric prefix for host name. Defaults to `icinga2.$host.name$.host.$host.check_command$`. + service\_name\_template | String | **Optional.** Metric prefix for service name. Defaults to `icinga2.$host.name$.services.$service.name$.$service.check_command$`. + enable\_send\_thresholds | Boolean | **Optional.** Send additional threshold metrics. Defaults to `false`. + enable\_send\_metadata | Boolean | **Optional.** Send additional metadata metrics. Defaults to `false`. + enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`. + +Additional usage examples can be found [here](14-features.md#graphite-carbon-cache-writer). + + +### IcingaApplication + +The IcingaApplication object is required to start Icinga 2. +The object name must be `app`. If the object configuration +is missing, Icinga 2 will automatically create an IcingaApplication +object. + +Example: + +``` +object IcingaApplication "app" { + enable_perfdata = false +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + enable\_notifications | Boolean | **Optional.** Whether notifications are globally enabled. Defaults to true. + enable\_event\_handlers | Boolean | **Optional.** Whether event handlers are globally enabled. Defaults to true. + enable\_flapping | Boolean | **Optional.** Whether flap detection is globally enabled. Defaults to true. + enable\_host\_checks | Boolean | **Optional.** Whether active host checks are globally enabled. Defaults to true. + enable\_service\_checks | Boolean | **Optional.** Whether active service checks are globally enabled. Defaults to true. + enable\_perfdata | Boolean | **Optional.** Whether performance data processing is globally enabled. Defaults to true. + vars | Dictionary | **Optional.** A dictionary containing custom attributes that are available globally. + environment | String | **Optional.** Specify the Icinga environment. This overrides the `Environment` constant specified in the configuration or on the CLI with `--define`. Defaults to empty. + +### IdoMySqlConnection + +IDO database adapter for MySQL. +This configuration object is available as [ido-mysql feature](14-features.md#db-ido). + +Example: + +``` +object IdoMysqlConnection "mysql-ido" { + host = "127.0.0.1" + port = 3306 + user = "icinga" + password = "icinga" + database = "icinga" + + cleanup = { + downtimehistory_age = 48h + contactnotifications_age = 31d + } +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + host | String | **Optional.** MySQL database host address. Defaults to `localhost`. + port | Number | **Optional.** MySQL database port. Defaults to `3306`. + socket\_path | String | **Optional.** MySQL socket path. + user | String | **Optional.** MySQL database user with read/write permission to the icinga database. Defaults to `icinga`. + password | String | **Optional.** MySQL database user's password. Defaults to `icinga`. + database | String | **Optional.** MySQL database name. Defaults to `icinga`. + enable\_ssl | Boolean | **Optional.** Use SSL. Defaults to false. Change to `true` in case you want to use any of the SSL options. + ssl\_key | String | **Optional.** MySQL SSL client key file path. + ssl\_cert | String | **Optional.** MySQL SSL certificate file path. + ssl\_ca | String | **Optional.** MySQL SSL certificate authority certificate file path. + ssl\_capath | String | **Optional.** MySQL SSL trusted SSL CA certificates in PEM format directory path. + ssl\_cipher | String | **Optional.** MySQL SSL list of allowed ciphers. + table\_prefix | String | **Optional.** MySQL database table prefix. Defaults to `icinga_`. + instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`. + instance\_description | String | **Optional.** Description for the Icinga 2 instance. + enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to `true`. + failover\_timeout | Duration | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 30s. Defaults to `30s`. + cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup. + categories | Array | **Optional.** Array of information types that should be written to the database. + +Cleanup Items: + + Name | Type | Description + --------------------------------|-----------------------|---------------------------------- + acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never). + commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never). + contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never). + contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never). + downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never). + eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never). + externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never). + flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never). + hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never). + logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never). + notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never). + processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never). + statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never). + servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never). + systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never). + +Data Categories: + + Name | Description | Required by + ---------------------|------------------------|-------------------- + DbCatConfig | Configuration data | Icinga Web 2 + DbCatState | Current state data | Icinga Web 2 + DbCatAcknowledgement | Acknowledgements | Icinga Web 2 + DbCatComment | Comments | Icinga Web 2 + DbCatDowntime | Downtimes | Icinga Web 2 + DbCatEventHandler | Event handler data | Icinga Web 2 + DbCatExternalCommand | External commands | -- + DbCatFlapping | Flap detection data | Icinga Web 2 + DbCatCheck | Check results | -- + DbCatLog | Log messages | -- + DbCatNotification | Notifications | Icinga Web 2 + DbCatProgramStatus | Program status data | Icinga Web 2 + DbCatRetention | Retention data | Icinga Web 2 + DbCatStateHistory | Historical state data | Icinga Web 2 + +The default value for `categories` includes everything required +by Icinga Web 2 in the table above. + +In addition to the category flags listed above the `DbCatEverything` +flag may be used as a shortcut for listing all flags. + +Runtime Attributes: + + Name | Type | Description + ----------------------------|-----------------------|----------------- + last\_failover | Timestamp | When the last failover happened for this connection (only available with `enable_ha = true`. + +### IdoPgsqlConnection + +IDO database adapter for PostgreSQL. +This configuration object is available as [ido-pgsql feature](14-features.md#db-ido). + +Example: + +``` +object IdoPgsqlConnection "pgsql-ido" { + host = "127.0.0.1" + port = 5432 + user = "icinga" + password = "icinga" + database = "icinga" + + cleanup = { + downtimehistory_age = 48h + contactnotifications_age = 31d + } +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + host | String | **Optional.** PostgreSQL database host address. Defaults to `localhost`. + port | Number | **Optional.** PostgreSQL database port. Defaults to `5432`. + user | String | **Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to `icinga`. + password | String | **Optional.** PostgreSQL database user's password. Defaults to `icinga`. + database | String | **Optional.** PostgreSQL database name. Defaults to `icinga`. + ssl\_mode | String | **Optional.** Enable SSL connection mode. Value must be set according to the [sslmode setting](https://www.postgresql.org/docs/9.3/static/libpq-connect.html#LIBPQ-CONNSTRING): `prefer`, `require`, `verify-ca`, `verify-full`, `allow`, `disable`. + ssl\_key | String | **Optional.** PostgreSQL SSL client key file path. + ssl\_cert | String | **Optional.** PostgreSQL SSL certificate file path. + ssl\_ca | String | **Optional.** PostgreSQL SSL certificate authority certificate file path. + table\_prefix | String | **Optional.** PostgreSQL database table prefix. Defaults to `icinga_`. + instance\_name | String | **Optional.** Unique identifier for the local Icinga 2 instance. Defaults to `default`. + instance\_description | String | **Optional.** Description for the Icinga 2 instance. + enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to `true`. + failover\_timeout | Duration | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 30s. Defaults to `30s`. + cleanup | Dictionary | **Optional.** Dictionary with items for historical table cleanup. + categories | Array | **Optional.** Array of information types that should be written to the database. + +Cleanup Items: + + Name | Type | Description + --------------------------------|-----------------------|---------------------------------- + acknowledgements\_age | Duration | **Optional.** Max age for acknowledgements table rows (entry\_time). Defaults to 0 (never). + commenthistory\_age | Duration | **Optional.** Max age for commenthistory table rows (entry\_time). Defaults to 0 (never). + contactnotifications\_age | Duration | **Optional.** Max age for contactnotifications table rows (start\_time). Defaults to 0 (never). + contactnotificationmethods\_age | Duration | **Optional.** Max age for contactnotificationmethods table rows (start\_time). Defaults to 0 (never). + downtimehistory\_age | Duration | **Optional.** Max age for downtimehistory table rows (entry\_time). Defaults to 0 (never). + eventhandlers\_age | Duration | **Optional.** Max age for eventhandlers table rows (start\_time). Defaults to 0 (never). + externalcommands\_age | Duration | **Optional.** Max age for externalcommands table rows (entry\_time). Defaults to 0 (never). + flappinghistory\_age | Duration | **Optional.** Max age for flappinghistory table rows (event\_time). Defaults to 0 (never). + hostchecks\_age | Duration | **Optional.** Max age for hostalives table rows (start\_time). Defaults to 0 (never). + logentries\_age | Duration | **Optional.** Max age for logentries table rows (logentry\_time). Defaults to 0 (never). + notifications\_age | Duration | **Optional.** Max age for notifications table rows (start\_time). Defaults to 0 (never). + processevents\_age | Duration | **Optional.** Max age for processevents table rows (event\_time). Defaults to 0 (never). + statehistory\_age | Duration | **Optional.** Max age for statehistory table rows (state\_time). Defaults to 0 (never). + servicechecks\_age | Duration | **Optional.** Max age for servicechecks table rows (start\_time). Defaults to 0 (never). + systemcommands\_age | Duration | **Optional.** Max age for systemcommands table rows (start\_time). Defaults to 0 (never). + +Data Categories: + + Name | Description | Required by + ---------------------|------------------------|-------------------- + DbCatConfig | Configuration data | Icinga Web 2 + DbCatState | Current state data | Icinga Web 2 + DbCatAcknowledgement | Acknowledgements | Icinga Web 2 + DbCatComment | Comments | Icinga Web 2 + DbCatDowntime | Downtimes | Icinga Web 2 + DbCatEventHandler | Event handler data | Icinga Web 2 + DbCatExternalCommand | External commands | -- + DbCatFlapping | Flap detection data | Icinga Web 2 + DbCatCheck | Check results | -- + DbCatLog | Log messages | -- + DbCatNotification | Notifications | Icinga Web 2 + DbCatProgramStatus | Program status data | Icinga Web 2 + DbCatRetention | Retention data | Icinga Web 2 + DbCatStateHistory | Historical state data | Icinga Web 2 + +The default value for `categories` includes everything required +by Icinga Web 2 in the table above. + +In addition to the category flags listed above the `DbCatEverything` +flag may be used as a shortcut for listing all flags. + +Runtime Attributes: + + Name | Type | Description + ----------------------------|-----------------------|----------------- + last\_failover | Timestamp | When the last failover happened for this connection (only available with `enable_ha = true`. + +### InfluxdbWriter + +Writes check result metrics and performance data to a defined InfluxDB host. +This configuration object is available as [influxdb feature](14-features.md#influxdb-writer). + +Example: + +``` +object InfluxdbWriter "influxdb" { + host = "127.0.0.1" + port = 8086 + database = "icinga2" + + flush_threshold = 1024 + flush_interval = 10s + + host_template = { + measurement = "$host.check_command$" + tags = { + hostname = "$host.name$" + } + } + service_template = { + measurement = "$service.check_command$" + tags = { + hostname = "$host.name$" + service = "$service.name$" + } + } +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + host | String | **Required.** InfluxDB host address. Defaults to `127.0.0.1`. + port | Number | **Required.** InfluxDB HTTP port. Defaults to `8086`. + database | String | **Required.** InfluxDB database name. Defaults to `icinga2`. + username | String | **Optional.** InfluxDB user name. Defaults to `none`. + password | String | **Optional.** InfluxDB user password. Defaults to `none`. + ssl\_enable | Boolean | **Optional.** Whether to use a TLS stream. Defaults to `false`. + ssl\_ca\_cert | String | **Optional.** Path to CA certificate to validate the remote host. + ssl\_cert | String | **Optional.** Path to host certificate to present to the remote host for mutual verification. + ssl\_key | String | **Optional.** Path to host key to accompany the ssl\_cert. + host\_template | String | **Required.** Host template to define the InfluxDB line protocol. + service\_template | String | **Required.** Service template to define the influxDB line protocol. + enable\_send\_thresholds | Boolean | **Optional.** Whether to send warn, crit, min & max tagged data. + enable\_send\_metadata | Boolean | **Optional.** Whether to send check metadata e.g. states, execution time, latency etc. + flush\_interval | Duration | **Optional.** How long to buffer data points before transferring to InfluxDB. Defaults to `10s`. + flush\_threshold | Number | **Optional.** How many data points to buffer before forcing a transfer to InfluxDB. Defaults to `1024`. + enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`. + +Note: If `flush_threshold` is set too low, this will always force the feature to flush all data +to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second +or similar. + + + +### LiveStatusListener + +Livestatus API interface available as TCP or UNIX socket. Historical table queries +require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled +pointing to the log files using the `compat_log_path` configuration attribute. +This configuration object is available as [livestatus feature](14-features.md#setting-up-livestatus). + +Examples: + +``` +object LivestatusListener "livestatus-tcp" { + socket_type = "tcp" + bind_host = "127.0.0.1" + bind_port = "6558" +} + +object LivestatusListener "livestatus-unix" { + socket_type = "unix" + socket_path = "/var/run/icinga2/cmd/livestatus" +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + socket\_type | String | **Optional.** Specifies the socket type. Can be either `tcp` or `unix`. Defaults to `unix`. + bind\_host | String | **Optional.** Only valid when `socket_type` is set to `tcp`. Host address to listen on for connections. Defaults to `127.0.0.1`. + bind\_port | Number | **Optional.** Only valid when `socket_type` is set to `tcp`. Port to listen on for connections. Defaults to `6558`. + socket\_path | String | **Optional.** Only valid when `socket_type` is set to `unix`. Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus". + compat\_log\_path | String | **Optional.** Path to Icinga 1.x log files. Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LogDir + "/compat" + +> **Note** +> +> UNIX sockets are not supported on Windows. + +### NotificationComponent + +The notification component is responsible for sending notifications. +This configuration object is available as [notification feature](11-cli-commands.md#cli-command-feature). + +Example: + +``` +object NotificationComponent "notification" { } +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-notifications). Disabling this currently only affects reminder notifications. Defaults to "true". + +### OpenTsdbWriter + +Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net). +This configuration object is available as [opentsdb feature](14-features.md#opentsdb-writer). + +Example: + +``` +object OpenTsdbWriter "opentsdb" { + host = "127.0.0.1" + port = 4242 +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + host | String | **Optional.** OpenTSDB host address. Defaults to `127.0.0.1`. + port | Number | **Optional.** OpenTSDB port. Defaults to `4242`. + enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`. + + +### PerfdataWriter + +Writes check result performance data to a defined path using macro +pattern consisting of custom attributes and runtime macros. +This configuration object is available as [perfdata feature](14-features.md#writing-performance-data-files). + +Example: + +``` +object PerfdataWriter "perfdata" { + host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata" + + service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata" + + host_format_template = "DATATYPE::HOSTPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tHOSTPERFDATA::$host.perfdata$\tHOSTCHECKCOMMAND::$host.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$" + service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.name$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.state_type$" + + rotation_interval = 15s +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + host\_perfdata\_path | String | **Optional.** Path to the host performance data file. Defaults to SpoolDir + "/perfdata/host-perfdata". + service\_perfdata\_path | String | **Optional.** Path to the service performance data file. Defaults to SpoolDir + "/perfdata/service-perfdata". + host\_temp\_path | String | **Optional.** Path to the temporary host file. Defaults to SpoolDir + "/tmp/host-perfdata". + service\_temp\_path | String | **Optional.** Path to the temporary service file. Defaults to SpoolDir + "/tmp/service-perfdata". + host\_format\_template | String | **Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios. + service\_format\_template | String | **Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios. + rotation\_interval | Duration | **Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to `30s`. + enable\_ha | Boolean | **Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-features). Defaults to `false`. + +When rotating the performance data file the current UNIX timestamp is appended to the path specified +in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename. + + +### StatusDataWriter + +Periodically writes status and configuration data files which are used by third-party tools. +This configuration object is available as [statusdata feature](14-features.md#status-data). + +> **Note** +> +> This feature is DEPRECATED and will be removed in future releases. +> Check the [roadmap](https://github.com/Icinga/icinga2/milestones). + +Example: + +``` +object StatusDataWriter "status" { + status_path = "/var/cache/icinga2/status.dat" + objects_path = "/var/cache/icinga2/objects.cache" + update_interval = 30s +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + status\_path | String | **Optional.** Path to the `status.dat` file. Defaults to CacheDir + "/status.dat". + objects\_path | String | **Optional.** Path to the `objects.cache` file. Defaults to CacheDir + "/objects.cache". + update\_interval | Duration | **Optional.** The interval in which the status files are updated. Defaults to `15s`. + +### SyslogLogger + +Specifies Icinga 2 logging to syslog. +This configuration object is available as `syslog` [logging feature](14-features.md#logging). + +Example: + +``` +object SyslogLogger "syslog" { + severity = "warning" +} +``` + +Configuration Attributes: + + Name | Type | Description + --------------------------|-----------------------|---------------------------------- + severity | String | **Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning". + facility | String | **Optional.** Defines the facility to use for syslog entries. This can be a facility constant like `FacilityDaemon`. Defaults to `FacilityUser`. + +Facility Constants: + + Name | Facility | Description + ---------------------|---------------|---------------- + FacilityAuth | LOG\_AUTH | The authorization system. + FacilityAuthPriv | LOG\_AUTHPRIV | The same as `FacilityAuth`, but logged to a file readable only by selected individuals. + FacilityCron | LOG\_CRON | The cron daemon. + FacilityDaemon | LOG\_DAEMON | System daemons that are not provided for explicitly by other facilities. + FacilityFtp | LOG\_FTP | The file transfer protocol daemons. + FacilityKern | LOG\_KERN | Messages generated by the kernel. These cannot be generated by any user processes. + FacilityLocal0 | LOG\_LOCAL0 | Reserved for local use. + FacilityLocal1 | LOG\_LOCAL1 | Reserved for local use. + FacilityLocal2 | LOG\_LOCAL2 | Reserved for local use. + FacilityLocal3 | LOG\_LOCAL3 | Reserved for local use. + FacilityLocal4 | LOG\_LOCAL4 | Reserved for local use. + FacilityLocal5 | LOG\_LOCAL5 | Reserved for local use. + FacilityLocal6 | LOG\_LOCAL6 | Reserved for local use. + FacilityLocal7 | LOG\_LOCAL7 | Reserved for local use. + FacilityLpr | LOG\_LPR | The line printer spooling system. + FacilityMail | LOG\_MAIL | The mail system. + FacilityNews | LOG\_NEWS | The network news system. + FacilitySyslog | LOG\_SYSLOG | Messages generated internally by syslogd. + FacilityUser | LOG\_USER | Messages generated by user processes. This is the default facility identifier if none is specified. + FacilityUucp | LOG\_UUCP | The UUCP system. + + +