upstream/icingadb
1
0
Fork 0
mirror of https://github.com/Icinga/icingadb.git synced 2025-12-18 23:16:16 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Docs: Account Redis' trademark policy

Browse source 
See https://redis.io/legal/trademark-policy/
This commit is contained in:
Eric Lippmann 2024-04-09 16:23:20 +02:00
parent fd4ffdac56
commit 25f39383b1
14 changed files with 75 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
README.md
View file

@ -3,13 +3,14 @@
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)

12
config.example.yml
View file

@ -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

7
doc/01-About.md
View file

@ -3,13 +3,14 @@
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)

12
doc/02-Installation.md
View file

@ -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.
<!-- {% else %} -->
@ -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)

52
doc/03-Configuration.md
View file

@ -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

16
doc/04-Upgrading.md
View file

@ -27,7 +27,7 @@ This release includes fixes for hosts and services reaching check attempt 256. H
the schema upgrade required to fix the history tables isn't automatically applied by `1.1.2.sql` as a rewrite of the
whole `state_history` table is required. This can take a lot of time depending on the history size and the performance
of the database. During this time that table will be locked exclusively and can't be accessed otherwise. This means that
the existing history can't be viewed in Icinga Web and new history entries will be buffered in Redis.
the existing history can't be viewed in Icinga Web and new history entries will be buffered in Redis®.
There is a separate upgrade script `optional/1.1.2-history.sql` to perform the rewrite of the `state_history` table.
This allows you to postpone part of the upgrade to a longer maintenance window in the future, or skip it entirely
@ -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.

16
doc/05-Distributed-Setups.md
View file

@ -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

13
doc/TRADEMARKS.md Normal file
View file

@ -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.

BIN
doc/images/icingadb-architecture.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 550 KiB

After

Width:  |  Height:  |  Size: 444 KiB

BIN
doc/images/icingadb-daemon.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 515 KiB

After

Width:  |  Height:  |  Size: 410 KiB

BIN
doc/images/icingadb-database.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 516 KiB

After

Width:  |  Height:  |  Size: 409 KiB

BIN
doc/images/icingadb-envs.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 645 KiB

After

Width:  |  Height:  |  Size: 459 KiB

BIN
doc/images/icingadb-ha.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 628 KiB

After

Width:  |  Height:  |  Size: 747 KiB

BIN
doc/images/icingadb-web.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 520 KiB

After

Width:  |  Height:  |  Size: 415 KiB