Adding upstream version 1.2.0.upstream/1.2.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 80 insertions, 40 deletions

diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md
index af92783..21edcf5 100644
--- a/doc/03-Configuration.md
+++ b/doc/03-Configuration.md
@@ -3,45 +3,65 @@
 The configuration is stored in `/etc/icingadb/config.yml`.
 See [config.example.yml](../config.example.yml) for an example configuration.
 
-## Redis Configuration
+## Redis® Configuration
 
-Connection configuration for the Redis server where Icinga 2 writes its configuration, state and history items.
+Connection configuration for the Redis® server where Icinga 2 writes its configuration, state and history items.
 This is the same connection as configured in the
 [Icinga DB feature](https://icinga.com/docs/icinga-2/latest/doc/14-features/#icinga-db) of
-the corresponding Icinga 2 node. High availability setups require a dedicated Redis server per Icinga 2 node and
+the corresponding Icinga 2 node. High availability setups require a dedicated Redis® server per Icinga 2 node and
 therefore a dedicated Icinga DB instance that connects to it.
 
-| Option   | Description                                                                                                                        |
-|----------|------------------------------------------------------------------------------------------------------------------------------------|
-| host     | **Required.** Redis host or absolute Unix socket path.                                                                             |
-| port     | **Optional.** Redis port. Defaults to `6380` since the Redis server provided by the `icingadb-redis` package listens on that port. |
-| password | **Optional.** The password to use.                                                                                                 |
-| tls      | **Optional.** Whether to use TLS.                                                                                                  |
-| cert     | **Optional.** Path to TLS client certificate.                                                                                      |
-| key      | **Optional.** Path to TLS private key.                                                                                             |
-| ca       | **Optional.** Path to TLS CA certificate.                                                                                          |
-| insecure | **Optional.** Whether not to verify the peer.                                                                                      |
+| Option   | Description                                                                                                             |
+|----------|-------------------------------------------------------------------------------------------------------------------------|
+| host     | **Required.** Host name or address, or absolute Unix socket path.                                                       |
+| port     | **Optional.** TCP port. Defaults to `6380` matching the Redis® open source server port in the `icingadb-redis` package. |
+| password | **Optional.** Authentication password.                                                                                  |
+| tls      | **Optional.** Whether to use TLS.                                                                                       |
+| cert     | **Optional.** Path to TLS client certificate.                                                                           |
+| key      | **Optional.** Path to TLS private key.                                                                                  |
+| ca       | **Optional.** Path to TLS CA certificate.                                                                               |
+| insecure | **Optional.** Whether not to verify the peer.                                                                           |
 
 ## Database Configuration
 
 Connection configuration for the database to which Icinga DB synchronizes monitoring data.
 This is also the database used in
-[Icinga DB Web](https://icinga.com/docs/icinga-db/latest/icinga-db-web/doc/01-About/) to view and work with the data.
+[Icinga DB Web](https://icinga.com/docs/icinga-db-web) to view and work with the data.
 In high availability setups, all Icinga DB instances must write to the same database.
 
-| Option   | Description                                                                                            |
-|----------|--------------------------------------------------------------------------------------------------------|
-| type     | **Optional.** Either `mysql` (default) or `pgsql`.                                                     |
-| host     | **Required.** Database host or absolute Unix socket path.                                              |
-| port     | **Optional.** Database port. By default, the MySQL or PostgreSQL port, depending on the database type. |
-| database | **Required.** Database name.                                                                           |
-| user     | **Required.** Database username.                                                                       |
-| password | **Optional.** Database password.                                                                       |
-| tls      | **Optional.** Whether to use TLS.                                                                      |
-| cert     | **Optional.** Path to TLS client certificate.                                                          |
-| key      | **Optional.** Path to TLS private key.                                                                 |
-| ca       | **Optional.** Path to TLS CA certificate.                                                              |
-| insecure | **Optional.** Whether not to verify the peer.                                                          |
+| Option   | Description                                                                                                                                    |
+|----------|------------------------------------------------------------------------------------------------------------------------------------------------|
+| type     | **Optional.** Either `mysql` (default) or `pgsql`.                                                                                             |
+| host     | **Required.** Database host or absolute Unix socket path.                                                                                      |
+| port     | **Optional.** Database port. By default, the MySQL or PostgreSQL port, depending on the database type.                                         |
+| database | **Required.** Database name.                                                                                                                   |
+| user     | **Required.** Database username.                                                                                                               |
+| password | **Optional.** Database password.                                                                                                               |
+| tls      | **Optional.** Whether to use TLS.                                                                                                              |
+| cert     | **Optional.** Path to TLS client certificate.                                                                                                  |
+| key      | **Optional.** Path to TLS private key.                                                                                                         |
+| ca       | **Optional.** Path to TLS CA certificate.                                                                                                      |
+| insecure | **Optional.** Whether not to verify the peer.                                                                                                  |
+| options  | **Optional.** List of low-level [database options](#database-options) that can be set to influence some Icinga DB internal default behaviours. |
+
+### Database Options
+
+Each of these configuration options are highly technical with thoroughly considered and tested default values that you
+should only change when you exactly know what you are doing. You can use these options to influence the Icinga DB default
+behaviour, how it interacts with databases, thus the defaults are usually sufficient for most users and do not need any
+manual adjustments.
+
+!!! important
+
+    Do not change the defaults if you do not have to!
+
+| Option                         | Description                                                                                                                                      |
+|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
+| max_connections                | **Optional.** Maximum number of database connections Icinga DB is allowed to open in parallel if necessary. Defaults to `16`.                    |
+| max_connections_per_table      | **Optional.** Maximum number of queries Icinga DB is allowed to execute on a single table concurrently. Defaults to `8`.                         |
+| max_placeholders_per_statement | **Optional.** Maximum number of placeholders Icinga DB is allowed to use for a single SQL statement. Defaults to `8192`.                         |
+| max_rows_per_transaction       | **Optional.** Maximum number of rows Icinga DB is allowed to `SELECT`,`DELETE`,`UPDATE` or `INSERT` in a single transaction. Defaults to `8192`. |
+| wsrep_sync_wait                | **Optional.** Enforce [Galera cluster](#galera-cluster) nodes to perform strict cluster-wide causality checks. Defaults to `7`.                  |
 
 ## Logging Configuration
 
@@ -56,19 +76,19 @@ Configuration of the logging component used by Icinga DB.
 
 ### Logging Components
 
-| Component         | Description                                                                    |
-|-------------------|--------------------------------------------------------------------------------|
-| config-sync       | Config object synchronization between Redis and MySQL.                         |
-| database          | Database connection status and queries.                                        |
-| dump-signals      | Dump signals received from Icinga.                                             |
-| heartbeat         | Icinga heartbeats received through Redis.                                      |
-| high-availability | Manages responsibility of Icinga DB instances.                                 |
-| history-sync      | Synchronization of history entries from Redis to MySQL.                        |
-| overdue-sync      | Calculation and synchronization of the overdue status of checkables.           |
-| redis             | Redis connection status and queries.                                           |
-| retention         | Deletes historical data that exceed their configured retention period.         |
-| runtime-updates   | Runtime updates of config objects after the initial config synchronization.    |
-| telemetry         | Reporting of Icinga DB status to Icinga 2 via Redis (for monitoring purposes). |
+| Component         | Description                                                                     |
+|-------------------|---------------------------------------------------------------------------------|
+| config-sync       | Config object synchronization between Redis® and MySQL.                         |
+| database          | Database connection status and queries.                                         |
+| dump-signals      | Dump signals received from Icinga.                                              |
+| heartbeat         | Icinga heartbeats received through Redis®.                                      |
+| high-availability | Manages responsibility of Icinga DB instances.                                  |
+| history-sync      | Synchronization of history entries from Redis® to MySQL.                        |
+| overdue-sync      | Calculation and synchronization of the overdue status of checkables.            |
+| redis             | Redis® connection status and queries.                                           |
+| retention         | Deletes historical data that exceed their configured retention period.          |
+| runtime-updates   | Runtime updates of config objects after the initial config synchronization.     |
+| telemetry         | Reporting of Icinga DB status to Icinga 2 via Redis® (for monitoring purposes). |
 
 ## Retention
 
@@ -83,6 +103,8 @@ allowing to keep this information for longer with a smaller storage footprint.
 |--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | history-days | **Optional.** Number of days to retain historical data for all history categories. Use `options` in order to enable retention only for specific categories or to override the retention days configured here. |
 | sla-days     | **Optional.** Number of days to retain historical data for SLA reporting.                                                                                                                                     |
+| interval     | **Optional.** Interval for periodically cleaning up the historical data, defined as [duration string](#duration-string). Defaults to `"1h"`.                                                                  |
+| count        | **Optional.** Number of old historical data a single query can delete in a `"DELETE FROM ... LIMIT count"` manner. Defaults to `5000`.                                                                        |
 | options      | **Optional.** Map of history category to number of days to retain its data. Available categories are `acknowledgement`, `comment`, `downtime`, `flapping`, `notification`, `sla` and `state`.                 |
 
 ## Appendix
@@ -91,3 +113,21 @@ allowing to keep this information for longer with a smaller storage footprint.
 
 A duration string is a sequence of decimal numbers and a unit suffix, such as `"20s"`.
 Valid units are `"ms"`, `"s"`, `"m"` and `"h"`.
+
+### Galera Cluster
+
+Icinga DB expects a more consistent behaviour from its database than a
+[Galera cluster](https://mariadb.com/kb/en/what-is-mariadb-galera-cluster/) provides by default. To accommodate this,
+Icinga DB sets the [wsrep_sync_wait](https://mariadb.com/kb/en/galera-cluster-system-variables/#wsrep_sync_wait) system
+variable for all its database connections. Consequently, strict cluster-wide causality checks are enforced before
+executing specific SQL queries, which are determined by the value set in the `wsrep_sync_wait` system variable.
+By default, Icinga DB sets this to `7`, which includes `READ, UPDATE, DELETE, INSERT, REPLACE` query types and is
+usually sufficient. Unfortunately, this also has the downside that every single Icinga DB query will be blocked until
+the cluster nodes resynchronise their states after each executed query, and may result in degraded performance.
+
+However, this does not necessarily have to be the case if, for instance, Icinga DB is only allowed to connect to a
+single cluster node at a time. This is the case when a load balancer does not randomly route connections to all the
+nodes evenly, but always to the same node until it fails, or if your database cluster nodes have a virtual IP address
+fail over assigned. In such situations, you can set the `wsrep_sync_wait` system variable to `0` in the 
+`/etc/icingadb/config.yml` file to disable it entirely, as Icinga DB doesn't have to wait for cluster
+synchronisation then.