Skip to content

Commit adffde9

Browse files
oxzioxzi
committed
doc/03-Configuration.md: Environment Variables
New ways to configure Icinga DB were introduced in [icingadb-831] and [igl-113]. The first change allows configuring Icinga DB using environment variables instead of or next to the YAML configuration file. In addition, the second change allows setting certificates and keys as PEM-encoded strings next to referencing files. This was now documented. As a structural change, the order of the Database and Redis sections were changed to reflect the order in the example configuration file. Some words about the Logging Components were written, as the documentation previously that they exist. [icingadb-831]: #831 [igl-113]: Icinga/icinga-go-library#113
1 parent 635e43c commit adffde9

File tree

2 files changed

+97
-35
lines changed

2 files changed

+97
-35
lines changed

‎config.example.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,3 +139,5 @@ redis:
139139
# flapping:
140140
# notification:
141141
# state:
142+
# sla_downtime:
143+
# sla_state:

‎doc/03-Configuration.md

Lines changed: 95 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,27 @@
11
# Configuration
22

3-
For package installations, the configuration is stored in `/etc/icingadb/config.yml`.
4-
See [config.example.yml](../config.example.yml) for an example configuration.
5-
6-
## Redis® Configuration
3+
Icinga DB can be configured using a YAML configuration file, environment variables, or both.
4+
Environment variables take precedence and override previously defined values from the configuration file.
75

8-
Connection configuration for the Redis® server where Icinga 2 writes its configuration, state and history items.
9-
This is the same connection as configured in the
10-
[Icinga DB feature](https://icinga.com/docs/icinga-2/latest/doc/14-features/#icinga-db) of
11-
the corresponding Icinga 2 node. High availability setups require a dedicated Redis® server per Icinga 2 node and
12-
therefore a dedicated Icinga DB instance that connects to it.
6+
For package installations, the configuration file is stored in `/etc/icingadb/config.yml`.
7+
See [config.example.yml](../config.example.yml) for an example configuration.
138

14-
| Option | Description |
15-
|----------|-------------------------------------------------------------------------------------------------------------------------|
16-
| host | **Required.** Host name or address, or absolute Unix socket path. |
17-
| port | **Optional.** TCP port. Defaults to `6380` matching the Redis® open source server port in the `icingadb-redis` package. |
18-
| username | **Optional.** Authentication username, requires a `password` being set as well. |
19-
| password | **Optional.** Authentication password. May be used alone or together with a `username`. |
20-
| database | **Optional.** Numerical database identifier, defaults to `0`. |
21-
| tls | **Optional.** Whether to use TLS. |
22-
| cert | **Optional.** Path to TLS client certificate. |
23-
| key | **Optional.** Path to TLS private key. |
24-
| ca | **Optional.** Path to TLS CA certificate. |
25-
| insecure | **Optional.** Whether not to verify the peer. |
9+
The following subsections describe the configurations of the various modules.
10+
For the YAML configuration file, each option is written in lowercase, as shown in the tables.
11+
When using environment variables, the variable name is constructed by concatenating `ICINGADB_`, the module name in uppercase followed by an underscore, and the option name in uppercase.
12+
The hyphens in the names are to be replaced by underscores.
13+
For example, to set the database host, the `ICINGADB_DATABASE_HOST` environment variable is used.
2614

2715
## Database Configuration
2816

29-
Connection configuration for the database to which Icinga DB synchronizes monitoring data.
17+
Connection configuration for the SQL database to which Icinga DB synchronizes monitoring data.
3018
This is also the database used in
3119
[Icinga DB Web](https://icinga.com/docs/icinga-db-web) to view and work with the data.
32-
In high availability setups, all Icinga DB instances must write to the same database.
20+
21+
In [high availability setups](05-Distributed-Setups.md), all Icinga DB instances must write to the same database.
22+
23+
For YAML configuration, the options are part of the `database` dictionary.
24+
For environment variables, each option is prefixed with`ICINGADB_DATABASE_`.
3325

3426
| Option | Description |
3527
|----------|------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -40,9 +32,9 @@ In high availability setups, all Icinga DB instances must write to the same data
4032
| user | **Required.** Database username. |
4133
| password | **Optional.** Database password. |
4234
| tls | **Optional.** Whether to use TLS. |
43-
| cert | **Optional.** Path to TLS client certificate. |
44-
| key | **Optional.** Path to TLS private key. |
45-
| ca | **Optional.** Path to TLS CA certificate. |
35+
| cert | **Optional.** TLS client certificate, either file path or PEM-encoded multiline string. |
36+
| key | **Optional.** TLS client private key, either file path or PEM-encoded multiline string. |
37+
| ca | **Optional.** TLS CA certificate, either file path or PEM-encoded multiline string. |
4638
| insecure | **Optional.** Whether not to verify the peer. |
4739
| options | **Optional.** List of low-level [database options](#database-options) that can be set to influence some Icinga DB internal default behaviours. |
4840

@@ -55,7 +47,10 @@ do not need any manual adjustments.
5547

5648
!!! important
5749

58-
Do not change the defaults if you do not have to!
50+
Do not change the defaults unless you have to!
51+
52+
For YAML configuration, the options are part of the `database.options` dictionary.
53+
For environment variables, each option is prefixed with `ICINGADB_DATABASE_OPTIONS_`.
5954

6055
| Option | Description |
6156
|--------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -65,11 +60,39 @@ do not need any manual adjustments.
6560
| 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`. |
6661
| wsrep_sync_wait | **Optional.** Enforce [Galera cluster](#galera-cluster) nodes to perform strict cluster-wide causality checks. Defaults to `7`. |
6762

63+
## Redis® Configuration
64+
65+
Connection configuration for the Redis® server where Icinga 2 writes its configuration, state and history items.
66+
This is the same connection as configured in the
67+
[Icinga DB feature](https://icinga.com/docs/icinga-2/latest/doc/14-features/#icinga-db) of
68+
the corresponding Icinga 2 node.
69+
70+
High availability setups require a dedicated Redis® server per Icinga 2 node and therefore a dedicated Icinga DB instance that connects to it.
71+
72+
For YAML configuration, the options are part of the `redis` dictionary.
73+
For environment variables, each option is prefixed with `ICINGADB_REDIS_`.
74+
75+
| Option | Description |
76+
|----------|-------------------------------------------------------------------------------------------------------------------------|
77+
| host | **Required.** Host name or address, or absolute Unix socket path. |
78+
| port | **Optional.** TCP port. Defaults to `6380` matching the Redis® open source server port in the `icingadb-redis` package. |
79+
| username | **Optional.** Authentication username, requires a `password` being set as well. |
80+
| password | **Optional.** Authentication password. May be used alone or together with a `username`. |
81+
| database | **Optional.** Numerical database identifier, defaults to `0`. |
82+
| tls | **Optional.** Whether to use TLS. |
83+
| cert | **Optional.** TLS client certificate, either file path or PEM-encoded multiline string. |
84+
| key | **Optional.** TLS client private key, either file path or PEM-encoded multiline string. |
85+
| ca | **Optional.** TLS CA certificate, either file path or PEM-encoded multiline string. |
86+
| insecure | **Optional.** Whether not to verify the peer. |
87+
6888
## Logging Configuration
6989

7090
Configuration of the logging component used by Icinga DB.
7191

72-
| Option | Description |
92+
For YAML configuration, the options are part of the `logging` dictionary.
93+
For environment variables, each option is prefixed with `ICINGADB_LOGGING_`.
94+
95+
| Option | Description |
7396
|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
7497
| level | **Optional.** Specifies the default logging level. Can be set to `fatal`, `error`, `warn`, `info` or `debug`. Defaults to `info`. |
7598
| output | **Optional.** Configures the logging output. Can be set to `console` (stderr) or `systemd-journald`. Defaults to systemd-journald when running under systemd, otherwise to console. See notes below for [systemd-journald](#systemd-journald-fields). |
@@ -78,6 +101,32 @@ Configuration of the logging component used by Icinga DB.
78101

79102
### Logging Components
80103

104+
The independent components of Icinga DB produce log entries.
105+
Each log entry is linked to its component and a log level.
106+
107+
By default, any log message will be displayed if its log level is at or above the `level` configured above.
108+
However, it is possible to override the log level for each component individually to show more or less information.
109+
110+
For YAML configuration, the options are part of the `logging.options` dictionary.
111+
For environment variables, `ICINGADB_LOGGING_OPTIONS` expects a single string of `component:level` pairs joined with `,`.
112+
113+
The following example would log everything with at least info level, except database and high availability entries, where the level is one time raised and one time lowered.
114+
115+
```yaml
116+
# YAML Configuration File
117+
logging:
118+
level: info
119+
options:
120+
database: error
121+
high-availability: debug
122+
```
123+
124+
```
125+
# Environment Variables
126+
ICINGADB_LOGGING_LEVEL=error
127+
ICINGADB_LOGGING_OPTIONS=database:error,high-availability:debug
128+
```
129+
81130
| Component | Description |
82131
|-------------------|---------------------------------------------------------------------------------|
83132
| config-sync | Config object synchronization between Redis® and MySQL. |
@@ -101,13 +150,24 @@ There are separate options for the full history tables used to display history i
101150
SLA tables which store the minimal information required for SLA reporting,
102151
allowing to keep this information for longer with a smaller storage footprint.
103152

104-
| Option | Description |
105-
|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
106-
| 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. |
107-
| sla-days | **Optional.** Number of days to retain historical data for SLA reporting. |
108-
| interval | **Optional.** Interval for periodically cleaning up the historical data, defined as [duration string](#duration-string). Defaults to `"1h"`. |
109-
| count | **Optional.** Number of old historical data a single query can delete in a `"DELETE FROM ... LIMIT count"` manner. Defaults to `5000`. |
110-
| 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`. |
153+
For YAML configuration, the options are part of the `retention` dictionary.
154+
For environment variables, each option is prefixed with `ICINGADB_RETENTION_`.
155+
156+
When using environment variables, the Retention `options` are formatted similar to the [logging components](#logging-components) from above.
157+
158+
```
159+
# Environment Variables
160+
ICINGADB_RETENTION_HISTORY_DAYS=14
161+
ICINGADB_RETENTION_OPTIONS=comment:356,sla_downtime:90,sla_state:90
162+
```
163+
164+
| Option | Description |
165+
|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
166+
| 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. |
167+
| sla-days | **Optional.** Number of days to retain historical data for SLA reporting. |
168+
| interval | **Optional.** Interval for periodically cleaning up the historical data, defined as [duration string](#duration-string). Defaults to `"1h"`. |
169+
| count | **Optional.** Number of old historical data a single query can delete in a `"DELETE FROM ... LIMIT count"` manner. Defaults to `5000`. |
170+
| options | **Optional.** Map of history category to number of days to retain its data. Available categories are `acknowledgement`, `comment`, `downtime`, `flapping`, `notification`, `state`, `sla_downtime` and `sla_state`. |
111171

112172
## Appendix
113173

0 commit comments

Comments
 (0)