diff --git a/README.md b/README.md index 8cc7c16ce..64416f4cc 100644 --- a/README.md +++ b/README.md @@ -3,13 +3,13 @@ Icinga DB is a set of components for publishing, synchronizing and visualizing monitoring data in the Icinga ecosystem, consisting of: -* The Icinga DB daemon, which synchronizes monitoring data between a Redis server and a database +* The Icinga DB daemon, which synchronizes monitoring data between a Redis®[*](doc/TRADEMARKS.md#redis) server and a database * Icinga 2 with its [Icinga DB feature](https://icinga.com/docs/icinga-2/latest/doc/14-features/#icinga-db) enabled, - responsible for publishing the data to the Redis server, i.e. configuration and its runtime updates, check results, + responsible for publishing the data to the Redis® server, i.e. configuration and its runtime updates, check results, state changes, downtimes, acknowledgements, notifications, and other events such as flapping * And Icinga Web with the [Icinga DB Web](https://icinga.com/docs/icinga-db-web) module enabled, - which connects to both Redis and the database to display and work with the most up-to-date data + which connects to both Redis® and the database to display and work with the most up-to-date data ![Icinga DB Architecture](doc/images/icingadb-architecture.png) diff --git a/config.example.yml b/config.example.yml index 73b9934fe..90fea96d3 100644 --- a/config.example.yml +++ b/config.example.yml @@ -57,19 +57,19 @@ database: # See https://icinga.com/docs/icinga-db/latest/doc/03-Configuration/#galera-cluster # wsrep_sync_wait: 7 -# 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 'icingadb' feature of the corresponding Icinga 2 node. -# High availability setups require a dedicated Redis server per Icinga 2 node and +# High availability setups require a dedicated Redis® server per Icinga 2 node and # therefore a dedicated Icinga DB instance that connects to it. redis: - # Redis host or absolute Unix socket path. + # Host name or address, or absolute Unix socket path. host: localhost - # Redis port. - # Defaults to '6380' since the Redis server provided by the 'icingadb-redis' package listens on that port. + # TCP port. + # Defaults to '6380' as the Redis® open source server provided by the 'icingadb-redis' package listens on that port. # port: 6380 - # Redis password. + # Authentication password. # password: # Icinga DB logs its activities at various severity levels and any errors that occur either diff --git a/doc/01-About.md b/doc/01-About.md index 8211e57c9..2ca821f72 100644 --- a/doc/01-About.md +++ b/doc/01-About.md @@ -3,13 +3,13 @@ Icinga DB is a set of components for publishing, synchronizing and visualizing monitoring data in the Icinga ecosystem, consisting of: -* The Icinga DB daemon, which synchronizes monitoring data between a Redis server and a database +* The Icinga DB daemon, which synchronizes monitoring data between a Redis®[*](TRADEMARKS.md#redis) server and a database * Icinga 2 with its [Icinga DB feature](https://icinga.com/docs/icinga-2/latest/doc/14-features/#icinga-db) enabled, - responsible for publishing the data to the Redis server, i.e. configuration and its runtime updates, check results, + responsible for publishing the data to the Redis® server, i.e. configuration and its runtime updates, check results, state changes, downtimes, acknowledgements, notifications, and other events such as flapping * And Icinga Web with the [Icinga DB Web](https://icinga.com/docs/icinga-db-web) module enabled, - which connects to both Redis and the database to display and work with the most up-to-date data + which connects to both Redis® and the database to display and work with the most up-to-date data ![Icinga DB Architecture](images/icingadb-architecture.png) diff --git a/doc/02-Installation.md b/doc/02-Installation.md index 8e04a1f7b..d5bd20b50 100644 --- a/doc/02-Installation.md +++ b/doc/02-Installation.md @@ -12,15 +12,15 @@ see the [Upgrading](04-Upgrading.md) documentation for the necessary steps. ![Icinga DB Daemon](images/icingadb-daemon.png) Before installing Icinga DB, make sure you have installed [Icinga 2](https://icinga.com/docs/icinga-2), -set up a Redis server, and enabled the `icingadb` feature. +set up a Redis® server, and enabled the `icingadb` feature. The Icinga 2 installation documentation covers all the necessary steps. Additionally, Icinga offers the `icingadb-redis` package for all supported operating systems, -which ships an up-to-date Redis server version and is pre-configured for the Icinga DB components. +which ships an up-to-date Redis® open source server version and is pre-configured for the Icinga DB components. !!! tip Although Icinga DB can run anywhere in an Icinga environment, - we recommend to install it where the corresponding Icinga 2 node and Redis server is running to + we recommend to install it where the corresponding Icinga 2 node and Redis® server is running to keep latency between the components low. @@ -271,7 +271,7 @@ psql -U icingadb icingadb < /usr/share/icingadb/schema/pgsql/schema.sql Icinga DB installs its configuration file to `/etc/icingadb/config.yml`, pre-populating most of the settings for a local setup. Before running Icinga DB, -adjust the Redis and database credentials and, if necessary, the connection configuration. +adjust the Redis® and database credentials and, if necessary, the connection configuration. The configuration file explains general settings. All available settings can be found under [Configuration](03-Configuration.md). @@ -286,8 +286,8 @@ systemctl enable --now icingadb ## Installing Icinga DB Web -With Icinga 2, Redis, Icinga DB and the database fully set up, it is now time to install Icinga DB Web, -which connects to both Redis and the database to display and work with the monitoring data. +With Icinga 2, Redis®, Icinga DB and the database fully set up, it is now time to install Icinga DB Web, +which connects to both Redis® and the database to display and work with the monitoring data. ![Icinga DB Web](images/icingadb-web.png) diff --git a/doc/03-Configuration.md b/doc/03-Configuration.md index aa8781b61..21edcf54d 100644 --- a/doc/03-Configuration.md +++ b/doc/03-Configuration.md @@ -3,24 +3,24 @@ 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 @@ -76,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 diff --git a/doc/04-Upgrading.md b/doc/04-Upgrading.md index f5a1bead0..250fde430 100644 --- a/doc/04-Upgrading.md +++ b/doc/04-Upgrading.md @@ -103,7 +103,7 @@ For package installations, you can find this file at `/usr/share/icingadb/schema Note that this upgrade will change the `history` table, which can take some time depending on the size of the table and the performance of the database. While the upgrade is running, that table will be locked and can't be accessed. This -means that the existing history can't be viewed in Icinga Web and new history entries will be buffered in Redis. +means that the existing history can't be viewed in Icinga Web and new history entries will be buffered in Redis®. As the daemon checks the schema version, the recommended way to perform the upgrade is to stop the daemon, apply the schema upgrade and then start the new daemon version. If you want to minimize downtime as much as possible, it is safe @@ -124,20 +124,20 @@ restart the daemon when upgrading the package. ## Upgrading to Icinga DB RC2 -Icinga DB RC2 is a complete rewrite compared to RC1. Because of this, a lot has changed in the Redis and database +Icinga DB RC2 is a complete rewrite compared to RC1. Because of this, a lot has changed in the Redis® and database schema, which is why they have to be deleted and recreated. The configuration file has changed from `icingadb.ini` to `config.yml`. Instead of the INI format, we are now using YAML and have introduced more configuration options. We -have also changed the packages of `icingadb-redis`, which is why the Redis CLI commands are now prefixed with `icingadb` -instead of just `icinga`, i.e. the Redis CLI is now accessed via `icingadb-redis-cli`. +have also changed the packages of `icingadb-redis`, which is why the Redis® CLI commands are now prefixed with `icingadb` +instead of just `icinga`, i.e. the Redis® CLI is now accessed via `icingadb-redis-cli`. Please follow the steps below to upgrade to Icinga DB RC2: 1. Stop Icinga 2 and Icinga DB. -2. Flush your Redis instances using `icinga-redis-cli flushall` (note the `icinga` prefix as we did not +2. Flush your Redis® instances using `icinga-redis-cli flushall` (note the `icinga` prefix as we did not upgrade `icingadb-redis` yet) and stop them afterwards. 3. Upgrade Icinga 2 to version 2.13.2 or newer. 4. Remove the `icinga-redis` package where installed as it may conflict with `icingadb-redis`. -5. Install Icinga DB Redis (`icingadb-redis`) on your primary Icinga 2 nodes to version 6.2.6 or newer. +5. Install Redis® (`icingadb-redis`) on your primary Icinga 2 nodes to version 6.2.6 or newer. 6. Upgrade Icinga DB to RC2. 7. Drop the Icinga DB MySQL database and recreate it using the provided schema. -8. Start Icinga DB Redis, Icinga 2 and Icinga DB. +8. Start Redis®, Icinga 2 and Icinga DB. diff --git a/doc/05-Distributed-Setups.md b/doc/05-Distributed-Setups.md index a324a65ee..9954e4c3e 100644 --- a/doc/05-Distributed-Setups.md +++ b/doc/05-Distributed-Setups.md @@ -11,22 +11,22 @@ First, you need an Icinga 2 high availability setup with two master nodes, such [here](https://icinga.com/docs/icinga-2/latest/doc/06-distributed-monitoring#high-availability-master-with-agents). Each of the master nodes must have the Icinga DB feature enabled and -have their own dedicated Redis server set up for it, so that each node writes the monitoring data separately. +have their own dedicated Redis® server set up for it, so that each node writes the monitoring data separately. The setup steps per node are no different from a single node setup and can be found in the [Icinga 2 installation documentation](https://icinga.com/docs/icinga-2/latest/doc/02-installation). -Each Redis server will always have the complete data available as long as -its corresponding Icinga 2 master is running and writing to its Redis. +Each Redis® server will always have the complete data available as long as +its corresponding Icinga 2 master is running and writing to its Redis®. This is because the Icinga 2 master nodes synchronize their data and events with each other as long as they are connected, and each takes over the entire configuration in case the other node or their connection to each other fails. -For each Redis server you need to set up its own dedicated Icinga DB instance that connects to it, +For each Redis® server you need to set up its own dedicated Icinga DB instance that connects to it, but the Icinga DB instances must write to the same database, which of course can be replicated or a cluster. So the steps from the standard [Icinga DB installation documentation](https://icinga.com/docs/icinga-db/latest/doc/02-installation) can be followed. However, as mentioned, the database only needs to be set up once. -All in all, an Icinga DB HA environment involves setting up two Icinga 2 master nodes, two Redis servers, +All in all, an Icinga DB HA environment involves setting up two Icinga 2 master nodes, two Redis® servers, two Icinga DB instances and one database. Please read the note about the [environment ID](#environment-id), @@ -48,9 +48,9 @@ Which Icinga DB instance is responsible is determined by a specific database ope can only be performed by one instance first. In the case of concurrent operations, simply put, only one wins via a locking mechanism. Of course, this is only true if the environment is healthy. -Icinga DB is not trying to be responsible if its corresponding Redis server is unavailable or -Icinga 2 is not writing data to Redis. -If Icinga 2 or Redis become unavailable for more than 60 seconds, +Icinga DB is not trying to be responsible if its corresponding Redis® server is unavailable or +Icinga 2 is not writing data to Redis®. +If Icinga 2 or Redis® become unavailable for more than 60 seconds, Icinga DB releases responsibility so the other instance can take over. ## Multiple Environments diff --git a/doc/TRADEMARKS.md b/doc/TRADEMARKS.md new file mode 100644 index 000000000..952751dca --- /dev/null +++ b/doc/TRADEMARKS.md @@ -0,0 +1,13 @@ +# Third-party Trademarks + +All trademarks, logos, and brand names are the property of their respective owners. +Any mention of company, product, or service names in our documentations, product descriptions, +or websites is solely for identification purposes. The use of these names, trademarks, +and brands does not imply endorsement. This document acknowledges trademarks of companies and products, +which are the property of their respective owners, whether registered or unregistered. + +## Redis® + +Redis is a registered trademark of Redis Ltd. Any rights therein are reserved to Redis Ltd. +Any use by Icinga GmbH is for referential purposes only and does not indicate any sponsorship, +endorsement or affiliation between Redis and Icinga GmbH. diff --git a/doc/images/icingadb-architecture.png b/doc/images/icingadb-architecture.png index 3d55ff757..c4af6eb3f 100644 Binary files a/doc/images/icingadb-architecture.png and b/doc/images/icingadb-architecture.png differ diff --git a/doc/images/icingadb-daemon.png b/doc/images/icingadb-daemon.png index de3f4c733..1c8415284 100644 Binary files a/doc/images/icingadb-daemon.png and b/doc/images/icingadb-daemon.png differ diff --git a/doc/images/icingadb-database.png b/doc/images/icingadb-database.png index c300095b5..fc7972532 100644 Binary files a/doc/images/icingadb-database.png and b/doc/images/icingadb-database.png differ diff --git a/doc/images/icingadb-envs.png b/doc/images/icingadb-envs.png index e9938d8b3..abff44212 100644 Binary files a/doc/images/icingadb-envs.png and b/doc/images/icingadb-envs.png differ diff --git a/doc/images/icingadb-ha.png b/doc/images/icingadb-ha.png index a86b6a038..051689ccb 100644 Binary files a/doc/images/icingadb-ha.png and b/doc/images/icingadb-ha.png differ diff --git a/doc/images/icingadb-web.png b/doc/images/icingadb-web.png index 05a3e3185..2d983349a 100644 Binary files a/doc/images/icingadb-web.png and b/doc/images/icingadb-web.png differ