diff --git a/doc/02-installation.md b/doc/02-installation.md index 004eaf163..cd23ab8c9 100644 --- a/doc/02-installation.md +++ b/doc/02-installation.md @@ -100,18 +100,7 @@ wget https://packages.icinga.com/centos/ICINGA-release.repo -O /etc/yum.repos.d/ ``` The packages for CentOS depend on other packages which are distributed -as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL). - -CentOS 8 additionally needs the PowerTools repository for EPEL: - -```bash -dnf install 'dnf-command(config-manager)' -dnf config-manager --set-enabled powertools - -dnf install epel-release -``` - -For CentOS 7 run: +as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL): ```bash yum install epel-release @@ -263,15 +252,12 @@ apt-get install icinga2 -#### CentOS 8 + +#### CentOS + +!!! info -```bash -dnf install icinga2 -systemctl enable icinga2 -systemctl start icinga2 -``` - -#### CentOS 7 + Note that installing Icinga 2 is only supported on CentOS 7 as CentOS 8 is EOL. ```bash yum install icinga2 @@ -383,14 +369,6 @@ apt-get install monitoring-plugins The packages for CentOS depend on other packages which are distributed as part of the EPEL repository. -#### CentOS 8 - -```bash -dnf install nagios-plugins-all -``` - -#### CentOS 7 - ```bash yum install nagios-plugins-all ``` @@ -450,750 +428,234 @@ yum install nagios-plugins-all ``` -## Set up Database +## Set up Icinga 2 API -The IDO (Icinga Data Output) feature for Icinga 2 stores all configuration and status information into a database. -Icinga Web 2 connects to the IDO database to visualize the data properly. You can either use a -[MySQL](#ido-with-mysql) or [PostgreSQL](#ido-with-postgresql) database. +Almost every Icinga 2 setup requires the Icinga 2 API as Icinga Web connects to it, Icinga DB requires it, +and it enables cluster communication functionality for highly available and distributed setups. -We recommend to install and configure the IDO feature before continuing with the installation -of Icinga Web 2. +!!! info -!!! note + If you set up a highly available and/or distributed Icinga monitoring environment, please read the + [Distributed Monitoring](06-distributed-monitoring.md#distributed-monitoring) chapter as + the commands to set up the API are different from setting up a single node setup. - We're currently working on a new data backend called Icinga DB. If you want to try the latest - release candidate skip to the [Icinga DB Chapter](#icingadb). Please keep in mind, that this version - is not ready for use in production and currently only supports MySQL. +See the [API](12-icinga2-api.md#icinga2-api-setup) chapter for details, +or follow the steps below to set up the API quickly: -### IDO with MySQL +Run the following command to: -#### Install MySQL Server - - - -#### Debian / Ubuntu - -```bash -apt-get install mariadb-server mariadb-client - -mysql_secure_installation -``` - - - - -#### CentOS - - -#### CentOS 8 -```bash -dnf install mariadb-server mariadb -systemctl enable mariadb -systemctl start mariadb -mysql_secure_installation -``` - -#### CentOS 7 -```bash -yum install mariadb-server mariadb -systemctl enable mariadb -systemctl start mariadb -mysql_secure_installation -``` - - - - -#### RHEL - -#### RHEL 8 -```bash -dnf install mariadb-server mariadb -systemctl enable mariadb -systemctl start mariadb -mysql_secure_installation -``` - -#### RHEL 7 -```bash -yum install mariadb-server mariadb -systemctl enable mariadb -systemctl start mariadb -mysql_secure_installation -``` - - - - -#### SLES / openSUSE - -```bash -zypper install mariadb mariadb-client -systemctl enable mariadb -systemctl start mariadb -mysql_secure_installation -``` - - - - -#### Amazon Linux 2 - -```bash -yum install mariadb-server mariadb -systemctl enable mariadb -systemctl start mariadb -mysql_secure_installation -``` - - -#### Install IDO Feature - -The next step is to install the `icinga2-ido-mysql` package using your -distribution's package manager. - - - -#### Debian / Ubuntu - -```bash -apt-get install icinga2-ido-mysql -``` - -!!! note - - The packages provide a database configuration wizard by - default. You can skip the automated setup and install/upgrade the - database manually if you prefer. - - - - -#### CentOS - - -#### CentOS 8 -```bash -dnf install icinga2-ido-mysql -``` - -#### CentOS 7 -```bash -yum install icinga2-ido-mysql -``` - - - - -#### RHEL - -#### RHEL 8 -```bash -dnf install icinga2-ido-mysql -``` - -#### RHEL 7 -```bash -yum install icinga2-ido-mysql -``` - - - - -#### SLES / openSUSE - -```bash -zypper install icinga2-ido-mysql -``` - - - - -#### Amazon Linux 2 - -```bash -yum install icinga2-ido-mysql -``` - - -#### Set up MySQL database - -Set up a MySQL database for Icinga 2: - -```bash -# mysql -u root -p - -CREATE DATABASE icinga; -GRANT ALTER, CREATE, SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga'; -quit -``` - -Please note that the example above uses the very simple password 'icinga' (in `IDENTIFIED BY 'icinga'`). -Please choose a better password for your installation. - -After creating the database you can import the Icinga 2 IDO schema using the -following command. Enter the icinga password into the prompt when asked. - -```bash -mysql -u icinga -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql -``` - -#### Enable the IDO MySQL feature - -The package provides a new configuration file that is installed in -`/etc/icinga2/features-available/ido-mysql.conf`. You can update -the database credentials in this file. - -All available attributes are explained in the -[IdoMysqlConnection object](09-object-types.md#objecttype-idomysqlconnection) -chapter. - -Enable the `ido-mysql` feature configuration file using the `icinga2` command: - -```bash -# icinga2 feature enable ido-mysql -Module 'ido-mysql' was enabled. -Make sure to restart Icinga 2 for these changes to take effect. -``` - -Restart Icinga 2. - -```bash -systemctl restart icinga2 -``` - -### IDO with PostgreSQL - -#### Install PostgreSQL server - - - -#### Debian / Ubuntu - -```bash -apt-get install postgresql -``` - - - - -#### CentOS - - -#### CentOS 8 -```bash -dnf install postgresql-server postgresql -postgresql-setup initdb -systemctl enable postgresql -systemctl start postgresql -``` - -#### CentOS 7 -```bash -yum install postgresql-server postgresql -postgresql-setup initdb -systemctl enable postgresql -systemctl start postgresql -``` - - - - -#### RHEL - -#### RHEL 8 -```bash -dnf install postgresql-server postgresql -postgresql-setup initdb -systemctl enable postgresql -systemctl start postgresql -``` - -#### RHEL 7 -```bash -yum install postgresql-server postgresql -postgresql-setup initdb -systemctl enable postgresql -systemctl start postgresql -``` - - - - -#### SLES / openSUSE - -```bash -zypper install postgresql postgresql-server -chkconfig postgresql on -service postgresql initdb -service postgresql start -``` - - - - -#### Amazon Linux 2 - -```bash -yum install postgresql-server postgresql -postgresql-setup initdb -systemctl enable postgresql -systemctl start postgresql -``` - - -#### Install IDO Feature - -The next step is to install the `icinga2-ido-pgsql` package using your -distribution's package manager. - - - -#### Debian / Ubuntu - -```bash -apt-get install icinga2-ido-pgsql -``` - -!!! note - - Upstream Debian packages provide a database configuration wizard by default. - You can skip the automated setup and install/upgrade the database manually - if you prefer that. - - - - -#### CentOS - - -#### CentOS 8 -```bash -dnf install icinga2-ido-pgsql -``` - -#### CentOS 7 -```bash -yum install icinga2-ido-pgsql -``` - - - - -#### RHEL - -#### RHEL 8 -```bash -dnf install icinga2-ido-pgsql -``` - -#### RHEL 7 -```bash -yum install icinga2-ido-pgsql -``` - - - - -#### SLES / openSUSE - -```bash -zypper install icinga2-ido-pgsql -``` - - - - -#### Amazon Linux 2 - -```bash -yum install icinga2-ido-pgsql -``` - - -#### Set up PostgreSQL database - -Set up a PostgreSQL database for Icinga 2: - -```bash -cd /tmp -sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'" -sudo -u postgres createdb -O icinga -E UTF8 icinga -``` - -!!! note - - It is assumed here that your locale is set to utf-8, you may run into problems otherwise. - -Locate your `pg_hba.conf` configuration file and add the icinga user with `md5` as authentication method -and restart the postgresql server. Common locations for `pg_hba.conf` are either -`/etc/postgresql/*/main/pg_hba.conf` or `/var/lib/pgsql/data/pg_hba.conf`. - -``` -# icinga -local icinga icinga md5 -host icinga icinga 127.0.0.1/32 md5 -host icinga icinga ::1/128 md5 - -# "local" is for Unix domain socket connections only -local all all ident -# IPv4 local connections: -host all all 127.0.0.1/32 ident -# IPv6 local connections: -host all all ::1/128 ident -``` - -Restart PostgreSQL: - -```bash -systemctl restart postgresql -``` - -After creating the database and permissions you need to import the IDO database -schema using the following command: - -```bash -export PGPASSWORD=icinga -psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql -``` - -#### Enable the IDO PostgreSQL feature - -The package provides a new configuration file that is installed in -`/etc/icinga2/features-available/ido-pgsql.conf`. You can update -the database credentials in this file. - -All available attributes are explained in the -[IdoPgsqlConnection object](09-object-types.md#objecttype-idopgsqlconnection) -chapter. - -Enable the `ido-pgsql` feature configuration file using the `icinga2` command: - -``` -# icinga2 feature enable ido-pgsql -Module 'ido-pgsql' was enabled. -Make sure to restart Icinga 2 for these changes to take effect. -``` - -Restart Icinga 2. - -```bash -systemctl restart icinga2 -``` - -### Icinga DB - -Icinga DB is a new data backend currently in development. -It's purpose is to synchronise data between Icinga 2 (Redis) and Icinga Web 2 (MySQL), some day replacing the IDO. -Don't worry, we won't drop support on the IDO any time soon. - -!!! note - - Icinga DB is not ready to be used in production and should only be used for testing purposes. - -#### Configue Icinga DB - -First, make sure to setup Icinga DB itself and its database backends (Redis and MySQL) by following the [installation instructions](https://icinga.com/docs/icingadb/latest/doc/02-Installation/). - -#### Enable Icinga DB feature - -Icinga 2 provides a configuration file that is installed in -`/etc/icinga2/features-available/icingadb.conf`. You can update -the Redis credentials in this file. - -All available attributes are explained in the -[IcingaDB object](09-object-types.md#objecttype-icingadb) -chapter. - -You can enable the `icingadb` feature configuration file using -`icinga2 feature enable`: - -``` -# icinga2 feature enable icingadb -Module 'icingadb' was enabled. -Make sure to restart Icinga 2 for these changes to take effect. -``` - -Restart Icinga 2. - -```bash -systemctl restart icinga2 -``` - -## Set up Icinga 2 REST API - -Icinga Web 2 requires the [REST API](12-icinga2-api.md#icinga2-api-setup) to send actions -(reschedule check, etc.) and query object details. - -You can run the CLI command `icinga2 api setup` to enable the -`api` [feature](11-cli-commands.md#enable-features) and set up -certificates as well as a new API user `root` with an auto-generated password in the -`/etc/icinga2/conf.d/api-users.conf` configuration file: +* enable the `api` feature, +* set up certificates, and +* add the API user `root` with an auto-generated password in the configuration file + `/etc/icinga2/conf.d/api-users.conf`. ```bash icinga2 api setup ``` -Edit the `api-users.conf` file and add a new ApiUser object. Specify the [permissions](12-icinga2-api.md#icinga2-api-permissions) -attribute with minimal permissions required by Icinga Web 2. - -``` -object ApiUser "icingaweb2" { - password = "Wijsn8Z9eRs5E25d" - permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ] -} -``` - -Restart Icinga 2 to activate the configuration. +Restart Icinga 2 for these changes to take effect. ```bash systemctl restart icinga2 ``` -## Install Icinga Web 2 + +## Set up Icinga DB -You are now ready to start the installation of Icinga Web 2. Please follow the -[Icinga Web 2 installation instructions](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/). +Icinga DB is a set of components for publishing, synchronizing and +visualizing monitoring data in the Icinga ecosystem, consisting of: -!!! note +* Icinga 2 with its `icingadb` feature enabled, + responsible for publishing monitoring data to a Redis server, i.e. configuration and its runtime updates, + check results, state changes, downtimes, acknowledgements, notifications, and other events such as flapping +* The [Icinga DB daemon](https://icinga.com/docs/icinga-db), + which synchronizes the data between the Redis server and a database +* 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 - If you're using Icinga DB, follow the [installation instructions](https://icinga.com/docs/icinga-db/latest/icinga-db-web/doc/02-Installation/) - to install and enable the Icinga DB Web module. +![Icinga DB Architecture](images/icingadb/icingadb-architecture.png) -## Syntax Highlighting +!!! info -Icinga 2 provides configuration examples for syntax highlighting using the `vim` and `nano` editors. + Setting up Icinga 2's Icinga DB feature is only required for Icinga 2 master nodes or single-node setups. -### Using Vim +### Set up Redis Server -Install the package `vim-icinga2` with your distribution's package manager. +A Redis server from version 6.2 is required. - +!!! info + + This guide sets up the `icingadb-redis` package provided by Icinga, + which ships a current Redis Server version and is preconfigured for the Icinga DB components. + Using own Redis server setups is supported as long as the version requirements are met. + +![Icinga DB Redis](images/icingadb/icingadb-redis.png) + +!!! tip + + Although the Redis server can run anywhere in an Icinga environment, + we recommend to install it where the corresponding Icinga 2 node is running to + keep latency between the components low. + +#### Install Icinga DB Redis Package + +Use your distribution's package manager to install the `icingadb-redis` package as follows: + + -#### Debian / Ubuntu / Raspbian +##### Amazon Linux 2 ```bash -apt-get install vim-icinga2 vim-addon-manager -vim-addon-manager -w install icinga2 -Info: installing removed addon 'icinga2' to /var/lib/vim/addons +yum install icingadb-redis ``` -#### CentOS +##### CentOS -#### CentOS 8 -```bash -dnf install vim-icinga2 -``` +!!! info + + Note that installing Icinga DB Redis is only supported on CentOS 7 as CentOS 8 is EOL. -#### CentOS 7 ```bash -yum install vim-icinga2 +yum install icingadb-redis +``` + + + + +##### Debian / Ubuntu + +```bash +apt-get install icingadb-redis ``` +##### RHEL 8 or Later + +```bash +dnf install icingadb-redis +``` + +##### RHEL 7 + +```bash +yum install icingadb-redis +``` + + + -#### RHEL +##### SLES -#### RHEL 8 ```bash -dnf install vim-icinga2 -``` - -#### RHEL 7 -```bash -yum install vim-icinga2 +zypper install icingadb-redis ``` - - -#### Fedora - -```bash -dnf install vim-icinga2 -``` - +#### Run Icinga DB Redis - - -#### SLES / openSUSE - -```bash -zypper install vim-icinga2 -``` - +The `icingadb-redis` package automatically installs the necessary systemd unit files to run Icinga DB Redis. +Please run the following command to enable and start its service: +```bash +systemctl enable --now icingadb-redis +``` + +#### Enable Remote Redis Connections + +By default, `icingadb-redis` only listens on `127.0.0.1`. If Icinga Web or Icinga 2 is running on another node, +remote access to the Redis server must be allowed. This requires the following directives to be set in +the `/etc/icingadb-redis/icingadb-redis.conf` configuration file: + +* Set `protected-mode` to `no`, i.e. `protected-mode no` +* Set `bind` to the desired binding interface or bind all interfaces, e.g. `bind 0.0.0.0` + +!!! warning + + By default, Redis has no authentication preventing others from accessing it. + When opening Redis to an external interface, make sure to set a password, set up appropriate firewall rules, + or configure TLS with certificate authentication on Redis and its consumers, + i.e. Icinga 2, Icinga DB and Icinga Web. + +Restart Icinga DB Redis for these changes to take effect: + +```bash +systemctl restart icingadb-redis +``` + +### Enable Icinga DB Feature + +With the [Icinga DB feature](14-features.md#icinga-db) enabled, +Icinga 2 publishes all of its monitoring data to the Redis server. This includes configuration and +its runtime updates via the Icinga 2 API, check results, state changes, downtimes, acknowledgments, notifications and +other events such as flapping. + +![Icinga DB Icinga 2](images/icingadb/icingadb-icinga2.png) + +Icinga 2 installs the feature configuration file to `/etc/icinga2/features-available/icingadb.conf`, +pre-configured for a local setup. +Update this file in case Redis is running on a different host or to set credentials. +All available settings are explained in the [Icinga DB object](09-object-types.md#icingadb) chapter. + +!!! important + + For single-node and high-availability setups, please read the note about the + [environment ID](https://icinga.com/docs/icinga-db/latest/doc/05-Distributed-Setups/#environment-id), + which is common to all Icinga DB components and generated by the Icinga DB feature. + +To enable the `icingadb` feature use the following command: + +```bash +icinga2 feature enable icingadb +``` + +Restart Icinga 2 for these changes to take effect: + +```bash +systemctl restart icinga2 +``` + +### Install Icinga DB Daemon + +After installing Icinga 2, setting up a Redis server and enabling the `icingadb` feature, +the Icinga DB daemon that synchronizes monitoring data between the Redis server and a database is now set up. + +![Icinga DB Daemon](images/icingadb/icingadb-daemon.png) + +!!! tip + + Although the Icinga DB daemon can run anywhere in an Icinga environment, + we recommend to install it where the corresponding Icinga 2 node and Redis server is running to + keep latency between the components low. + +The Icinga DB daemon package is also included in the Icinga repository, and since it is already set up, +you have completed the instructions here and can proceed to - -#### Amazon Linux 2 +[install the Icinga DB daemon on Amazon Linux](https://icinga.com/docs/icinga-db/latest/doc/02-Installation/01-Amazon-Linux/#installing-icinga-db-package), -```bash -yum install vim-icinga2 -``` - - -Ensure that syntax highlighting is enabled e.g. by editing the user's `vimrc` -configuration file: - -``` -# vim ~/.vimrc -syntax on -``` - -Test it: - -```bash -vim /etc/icinga2/conf.d/templates.conf -``` - -![Vim with syntax highlighting](images/installation/vim-syntax.png "Vim with Icinga 2 syntax highlighting") - - -### Using Nano - -Install the package `nano-icinga2` with your distribution's package manager. - - - -#### Debian / Ubuntu / Raspbian - -**Note:** The syntax files are installed with the `icinga2-common` package already. - - - -#### CentOS +[install the Icinga DB daemon on CentOS](https://icinga.com/docs/icinga-db/latest/doc/02-Installation/02-CentOS/#installing-icinga-db-package), - -#### CentOS 8 -```bash -dnf install nano-icinga2 -``` - -#### CentOS 7 -```bash -yum install nano-icinga2 -``` + +[install the Icinga DB daemon on Debian](https://icinga.com/docs/icinga-db/latest/doc/02-Installation/03-Debian/#installing-icinga-db-package), - - -#### RHEL +[install the Icinga DB daemon on RHEL](https://icinga.com/docs/icinga-db/latest/doc/02-Installation/04-RHEL/#installing-icinga-db-package), -#### RHEL 8 -```bash -dnf install nano-icinga2 -``` - -#### RHEL 7 -```bash -yum install nano-icinga2 -``` + +[install the Icinga DB daemon on SLES](https://icinga.com/docs/icinga-db/latest/doc/02-Installation/05-SLES/#installing-icinga-db-package), - - - -#### Fedora + +[install the Icinga DB daemon on Ubuntu](https://icinga.com/docs/icinga-db/latest/doc/02-Installation/06-Ubuntu/#installing-icinga-db-package), -```bash -dnf install nano-icinga2 -``` +which will also guide you through the setup of the database and Icinga DB Web. - - -#### SLES / openSUSE - -```bash -zypper install nano-icinga2 -``` - - - - -#### Amazon Linux 2 - -```bash -yum install nano-icinga2 -``` - - -Copy the `/etc/nanorc` sample file to your home directory. - -```bash -cp /etc/nanorc ~/.nanorc -``` - -Include the `icinga2.nanorc` file. - -``` -$ vim ~/.nanorc - -## Icinga 2 -include "/usr/share/nano/icinga2.nanorc" -``` - -Test it: - -```bash -nano /etc/icinga2/conf.d/templates.conf -``` - -![Nano with syntax highlighting](images/installation/nano-syntax.png "Nano with Icinga 2 syntax highlighting") - -## Installation Overview - -### Enabled Features during Installation - -The default installation will enable three features required for a basic -Icinga 2 installation: - -* `checker` for executing checks -* `notification` for sending notifications -* `mainlog` for writing the `icinga2.log` file - -You can verify that by calling `icinga2 feature list` -[CLI command](11-cli-commands.md#cli-command-feature) to see which features are -enabled and disabled. - -``` -# icinga2 feature list -Disabled features: api command compatlog debuglog gelf graphite icingastatus ido-mysql ido-pgsql influxdb livestatus opentsdb perfdata statusdata syslog -Enabled features: checker mainlog notification -``` - -### Installation Paths - -By default Icinga 2 uses the following files and directories: - - Path | Description - ----------------------------------------------|------------------------------------ - /etc/icinga2 | Contains Icinga 2 configuration files. - /usr/lib/systemd/system/icinga2.service | The Icinga 2 systemd service file on systems using systemd. - /etc/systemd/system/icinga2.service.d/limits.conf | On distributions with systemd >227, additional service limits are required. - /etc/init.d/icinga2 | The Icinga 2 init script on systems using SysVinit or OpenRC. - /usr/sbin/icinga2 | Shell wrapper for the Icinga 2 binary. - /usr/lib\*/icinga2 | Libraries and the Icinga 2 binary (use `find /usr -type f -name icinga2` to locate the binary path). - /usr/share/doc/icinga2 | Documentation files that come with Icinga 2. - /usr/share/icinga2/include | The Icinga Template Library and plugin command configuration. - /var/lib/icinga2 | Icinga 2 state file, cluster log, master CA, node certificates and configuration files (cluster, api). - /var/run/icinga2 | PID file. - /var/run/icinga2/cmd | Command pipe and Livestatus socket. - /var/cache/icinga2 | status.dat/objects.cache, icinga2.debug files. - /var/spool/icinga2 | Used for performance data spool files. - /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature. - -## Addons - -A number of additional features are available in the form of addons. A list of -popular addons is available in the -[Addons and Plugins](13-addons.md#addons) chapter. - ## Backup Ensure to include the following in your backups: @@ -1201,16 +663,5 @@ Ensure to include the following in your backups: * Configuration files in `/etc/icinga2` * Certificate files in `/var/lib/icinga2/ca` (Master CA key pair) and `/var/lib/icinga2/certs` (node certificates) * Runtime files in `/var/lib/icinga2` -* Optional: IDO database backup - -### Database Backup - -MySQL/MariaDB: - -* [Documentation](https://mariadb.com/kb/en/library/backup-and-restore-overview/) - -PostgreSQL: - -* [Documentation](https://www.postgresql.org/docs/9.3/static/backup.html) diff --git a/doc/09-object-types.md b/doc/09-object-types.md index e2ee1bfd5..cdb6db5fb 100644 --- a/doc/09-object-types.md +++ b/doc/09-object-types.md @@ -1393,7 +1393,7 @@ Configuration Attributes: ### IcingaDB -The IcingaDB object implements the [icingadb feauture](14-features.md#core-backends-icingadb). +The `IcingaDB` object implements the [Icinga DB feature](14-features.md#icinga-db). Example: @@ -1409,10 +1409,10 @@ Configuration Attributes: Name | Type | Description --------------------------|-----------------------|---------------------------------- - host | String | **Optional.** Redis host for IcingaDB. Defaults to `127.0.0.1`. - port | Number | **Optional.** Redis port for IcingaDB. Defaults to `6380`. - path | String | **Optional.** Redix unix socket path. Can be used instead of `host` and `port` attributes. - password | String | **Optional.** Redis auth password for IcingaDB. + host | String | **Optional.** Redis host. Defaults to `127.0.0.1`. + port | Number | **Optional.** Redis port. Defaults to `6380` since the Redis server provided by the `icingadb-redis` package listens on that port. + path | String | **Optional.** Redis unix socket path. Can be used instead of `host` and `port` attributes. + password | String | **Optional.** Redis auth password. enable\_tls | Boolean | **Optional.** Whether to use TLS. cert\_path | String | **Optional.** Path to the certificate. key\_path | String | **Optional.** Path to the private key. @@ -1425,6 +1425,11 @@ Configuration Attributes: ### IdoMySqlConnection +> **Note** +> +> This feature is DEPRECATED and may be removed in future releases. +> Check the [roadmap](https://github.com/Icinga/icinga2/milestones). + IDO database adapter for MySQL. This configuration object is available as [ido-mysql feature](14-features.md#db-ido). @@ -1527,6 +1532,11 @@ Runtime Attributes: ### IdoPgsqlConnection +> **Note** +> +> This feature is DEPRECATED and may be removed in future releases. +> Check the [roadmap](https://github.com/Icinga/icinga2/milestones). + IDO database adapter for PostgreSQL. This configuration object is available as [ido-pgsql feature](14-features.md#db-ido). diff --git a/doc/13-addons.md b/doc/13-addons.md index e212c3734..953b7f0bb 100644 --- a/doc/13-addons.md +++ b/doc/13-addons.md @@ -3,6 +3,59 @@ For an uptodate overview of all integrations and modules, please visit [https://icinga.com/products/](https://icinga.com/products/). +## Syntax Highlighting + +Icinga 2 provides configuration examples for syntax highlighting using the `vim` and `nano` editors. + +### Using Vim + +Install the package `vim-icinga2` with your distribution's package manager. + +Ensure that syntax highlighting is enabled e.g. by editing the user's `vimrc` +configuration file: + +``` +# vim ~/.vimrc +syntax on +``` + +Test it: + +```bash +vim /etc/icinga2/conf.d/templates.conf +``` + +![Vim with syntax highlighting](images/addons/vim-syntax.png "Vim with Icinga 2 syntax highlighting") + + +### Using Nano + +Install the package `nano-icinga2` with your distribution's package manager. + +**Note:** On Debian, Ubuntu and Raspbian, the syntax files are installed with the `icinga2-common` package already. + +Copy the `/etc/nanorc` sample file to your home directory. + +```bash +cp /etc/nanorc ~/.nanorc +``` + +Include the `icinga2.nanorc` file. + +``` +$ vim ~/.nanorc + +## Icinga 2 +include "/usr/share/nano/icinga2.nanorc" +``` + +Test it: + +```bash +nano /etc/icinga2/conf.d/templates.conf +``` + +![Nano with syntax highlighting](images/addons/nano-syntax.png "Nano with Icinga 2 syntax highlighting") ## Icinga Reporting @@ -203,5 +256,3 @@ Checkout these specific integrations: If you're looking for different config management integrations -- we're happy to add them upstream, so please get in touch with the [Icinga team](https://icinga.com/community/). - - diff --git a/doc/14-features.md b/doc/14-features.md index 3007c0a5c..e1b279c72 100644 --- a/doc/14-features.md +++ b/doc/14-features.md @@ -48,173 +48,23 @@ The REST API is documented [here](12-icinga2-api.md#icinga2-api) as a core featu ### Icinga DB -Icinga DB provides a new core backend and aims to replace the IDO backend -output. It consists of different components: +Icinga DB is a set of components for publishing, synchronizing and +visualizing monitoring data in the Icinga ecosystem, consisting of: -* Icinga 2 provides the `icingadb` feature which stores monitoring data in a memory database -* The [IcingaDB service](https://github.com/icinga/icingadb) collects and synchronizes monitoring data into its backend -* Icinga Web reads monitoring data from the new IcingaDB backend +* Icinga 2 with its `icingadb` feature enabled, + responsible for publishing monitoring data to a Redis server, i.e. configuration and its runtime updates, + check results, state changes, downtimes, acknowledgements, notifications, and other events such as flapping +* The [Icinga DB daemon](https://icinga.com/docs/icinga-db), + which synchronizes the data between the Redis server and a database +* 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 -Requirements: - -* Local Redis instance -* MySQL/MariaDB server with `icingadb` database, user and schema imports -* Icinga 2's `icingadb` feature enabled -* IcingaDB service requires Redis and MySQL/MariaDB server -* Icinga Web module - -Consult the [Icinga DB installation documentation](https://icinga.com/docs/icinga-db/latest/doc/02-Installation/) for setup instructions. - -We will deprecate the IDO and shift towards the Icinga DB as main backend, -but we will not drop the IDO for now. -We know that it takes time until the Icinga DB is adopted -(maybe even up to one to two years) -and we won’t drop the IDO until it is comfortable to do so. - -### IDO Database (DB IDO) - -The IDO (Icinga Data Output) feature for Icinga 2 takes care of exporting all -configuration and status information into a database. The IDO database is used -by Icinga Web 2 as data backend. - -Details on the installation can be found in the "Prepare for Icinga Web 2" chapter -of the [Installation docs](02-installation.md). Details on the configuration can be found in the -[IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection) and -[IdoPgsqlConnection](09-object-types.md#objecttype-idopgsqlconnection) -object configuration documentation. - -#### DB IDO Health - -If the monitoring health indicator is critical in Icinga Web 2, -you can use the following queries to manually check whether Icinga 2 -is actually updating the IDO database. - -Icinga 2 writes its current status to the `icinga_programstatus` table -every 10 seconds. The query below checks 60 seconds into the past which is a reasonable -amount of time -- adjust it for your requirements. If the condition is not met, -the query returns an empty result. - -> **Tip** -> -> Use [check plugins](05-service-monitoring.md#service-monitoring-plugins) to monitor the backend. - -Replace the `default` string with your instance name if different. - -Example for MySQL: - -``` -# mysql -u root -p icinga -e "SELECT status_update_time FROM icinga_programstatus ps - JOIN icinga_instances i ON ps.instance_id=i.instance_id - WHERE (UNIX_TIMESTAMP(ps.status_update_time) > UNIX_TIMESTAMP(NOW())-60) - AND i.instance_name='default';" - -+---------------------+ -| status_update_time | -+---------------------+ -| 2014-05-29 14:29:56 | -+---------------------+ -``` - -Example for PostgreSQL: - -``` -# export PGPASSWORD=icinga; psql -U icinga -d icinga -c "SELECT ps.status_update_time FROM icinga_programstatus AS ps - JOIN icinga_instances AS i ON ps.instance_id=i.instance_id - WHERE ((SELECT extract(epoch from status_update_time) FROM icinga_programstatus) > (SELECT extract(epoch from now())-60)) - AND i.instance_name='default'"; - -status_update_time ------------------------- - 2014-05-29 15:11:38+02 -(1 Zeile) -``` - -A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](24-appendix.md#schema-db-ido). - -#### DB IDO in Cluster HA Zones - -The DB IDO feature supports [High Availability](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido) in -the Icinga 2 cluster. - -By default, both endpoints in a zone calculate the -endpoint which activates the feature, the other endpoint -automatically pauses it. If the cluster connection -breaks at some point, the paused IDO feature automatically -does a failover. - -You can disable this behaviour by setting `enable_ha = false` -in both feature configuration files. - -#### DB IDO Cleanup - -Objects get deactivated when they are deleted from the configuration. -This is visible with the `is_active` column in the `icinga_objects` table. -Therefore all queries need to join this table and add `WHERE is_active=1` as -condition. Deleted objects preserve their history table entries for later SLA -reporting. - -Historical data isn't purged by default. You can enable the least -kept data age inside the `cleanup` configuration attribute for the -IDO features [IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection) -and [IdoPgsqlConnection](09-object-types.md#objecttype-idopgsqlconnection). - -Example if you prefer to keep notification history for 30 days: - -``` - cleanup = { - notifications_age = 30d - contactnotifications_age = 30d - } -``` - -The historical tables are populated depending on the data `categories` specified. -Some tables are empty by default. - -#### DB IDO Tuning - -As with any application database, there are ways to optimize and tune the database performance. - -General tips for performance tuning: - -* [MariaDB KB](https://mariadb.com/kb/en/library/optimization-and-tuning/) -* [PostgreSQL Wiki](https://wiki.postgresql.org/wiki/Performance_Optimization) - -Re-creation of indexes, changed column values, etc. will increase the database size. Ensure to -add health checks for this, and monitor the trend in your Grafana dashboards. - -In order to optimize the tables, there are different approaches. Always keep in mind to have a -current backup and schedule maintenance downtime for these kind of tasks! - -MySQL: - -``` -mariadb> OPTIMIZE TABLE icinga_statehistory; -``` - -> **Important** -> -> Tables might not support optimization at runtime. This can take a **long** time. -> -> `Table does not support optimize, doing recreate + analyze instead`. - -If you want to optimize all tables in a specified database, there is a script called `mysqlcheck`. -This also allows to repair broken tables in the case of emergency. - -```bash -mysqlcheck --optimize icinga -``` - -PostgreSQL: - -``` -icinga=# vacuum; -VACUUM -``` - -> **Note** -> -> Don't use `VACUUM FULL` as this has a severe impact on performance. +![Icinga DB Architecture](images/icingadb/icingadb-architecture.png) +To set up a Redis server and the Icinga DB feature, please follow the steps from the +Icinga 2 [Installation](02-installation.md) guide. For the feature configuration options, +see its [Icinga DB object type](09-object-types.md#icingadb) documentation. ## Metrics @@ -934,6 +784,379 @@ is running on. ## Deprecated Features +### IDO Database (DB IDO) + +> **Note** +> +> This feature is DEPRECATED and may be removed in future releases. +> Check the [roadmap](https://github.com/Icinga/icinga2/milestones). + +The IDO (Icinga Data Output) feature for Icinga 2 takes care of exporting all +configuration and status information into a database. The IDO database is used +by Icinga Web 2 as data backend. You can either use a +[MySQL](#ido-with-mysql) or [PostgreSQL](#ido-with-postgresql) database. + +#### IDO with MySQL + +##### Install IDO Feature + +The next step is to install the `icinga2-ido-mysql` package using your +distribution's package manager. + +###### Debian / Ubuntu + +```bash +apt-get install icinga2-ido-mysql +``` + +!!! note + + The packages provide a database configuration wizard by + default. You can skip the automated setup and install/upgrade the + database manually if you prefer. + +###### CentOS 7 + +!!! info + + Note that installing `icinga2-ido-mysql` is only supported on CentOS 7 as CentOS 8 is EOL. + +```bash +yum install icinga2-ido-mysql +``` + +###### RHEL 8 + +```bash +dnf install icinga2-ido-mysql +``` + +###### RHEL 7 + +```bash +yum install icinga2-ido-mysql +``` + +###### SLES + +```bash +zypper install icinga2-ido-mysql +``` + +###### Amazon Linux 2 + +```bash +yum install icinga2-ido-mysql +``` + +##### Set up MySQL database + +Set up a MySQL database for Icinga 2: + +```bash +# mysql -u root -p + +CREATE DATABASE icinga; +GRANT ALTER, CREATE, SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga'; +quit +``` + +Please note that the example above uses the very simple password 'icinga' (in `IDENTIFIED BY 'icinga'`). +Please choose a better password for your installation. + +After creating the database you can import the Icinga 2 IDO schema using the +following command. Enter the icinga password into the prompt when asked. + +```bash +mysql -u icinga -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql +``` + +##### Enable the IDO MySQL feature + +The package provides a new configuration file that is installed in +`/etc/icinga2/features-available/ido-mysql.conf`. You can update +the database credentials in this file. + +All available attributes are explained in the +[IdoMysqlConnection object](09-object-types.md#objecttype-idomysqlconnection) +chapter. + +Enable the `ido-mysql` feature configuration file using the `icinga2` command: + +```bash +# icinga2 feature enable ido-mysql +Module 'ido-mysql' was enabled. +Make sure to restart Icinga 2 for these changes to take effect. +``` + +Restart Icinga 2. + +```bash +systemctl restart icinga2 +``` + +#### IDO with PostgreSQL + +##### Install IDO Feature + +The next step is to install the `icinga2-ido-pgsql` package using your +distribution's package manager. + +###### Debian / Ubuntu + +```bash +apt-get install icinga2-ido-pgsql +``` + +!!! note + + Upstream Debian packages provide a database configuration wizard by default. + You can skip the automated setup and install/upgrade the database manually + if you prefer that. + +###### CentOS 7 + +!!! info + + Note that installing `icinga2-ido-pgsql` is only supported on CentOS 7 as CentOS 8 is EOL. + +```bash +yum install icinga2-ido-pgsql +``` + +###### RHEL 8 + +```bash +dnf install icinga2-ido-pgsql +``` + +###### RHEL 7 + +```bash +yum install icinga2-ido-pgsql +``` + +###### SLES + +```bash +zypper install icinga2-ido-pgsql +``` + +###### Amazon Linux 2 + +```bash +yum install icinga2-ido-pgsql +``` + +##### Set up PostgreSQL database + +Set up a PostgreSQL database for Icinga 2: + +```bash +cd /tmp +sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'" +sudo -u postgres createdb -O icinga -E UTF8 icinga +``` + +!!! note + + It is assumed here that your locale is set to utf-8, you may run into problems otherwise. + +Locate your `pg_hba.conf` configuration file and add the icinga user with `md5` as authentication method +and restart the postgresql server. Common locations for `pg_hba.conf` are either +`/etc/postgresql/*/main/pg_hba.conf` or `/var/lib/pgsql/data/pg_hba.conf`. + +``` +# icinga +local icinga icinga md5 +host icinga icinga 127.0.0.1/32 md5 +host icinga icinga ::1/128 md5 + +# "local" is for Unix domain socket connections only +local all all ident +# IPv4 local connections: +host all all 127.0.0.1/32 ident +# IPv6 local connections: +host all all ::1/128 ident +``` + +Restart PostgreSQL: + +```bash +systemctl restart postgresql +``` + +After creating the database and permissions you need to import the IDO database +schema using the following command: + +```bash +export PGPASSWORD=icinga +psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql +``` + +##### Enable the IDO PostgreSQL feature + +The package provides a new configuration file that is installed in +`/etc/icinga2/features-available/ido-pgsql.conf`. You can update +the database credentials in this file. + +All available attributes are explained in the +[IdoPgsqlConnection object](09-object-types.md#objecttype-idopgsqlconnection) +chapter. + +Enable the `ido-pgsql` feature configuration file using the `icinga2` command: + +``` +# icinga2 feature enable ido-pgsql +Module 'ido-pgsql' was enabled. +Make sure to restart Icinga 2 for these changes to take effect. +``` + +Restart Icinga 2. + +```bash +systemctl restart icinga2 +``` + +#### Configuration + +Details on the configuration can be found in the +[IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection) and +[IdoPgsqlConnection](09-object-types.md#objecttype-idopgsqlconnection) +object configuration documentation. + +#### DB IDO Health + +If the monitoring health indicator is critical in Icinga Web 2, +you can use the following queries to manually check whether Icinga 2 +is actually updating the IDO database. + +Icinga 2 writes its current status to the `icinga_programstatus` table +every 10 seconds. The query below checks 60 seconds into the past which is a reasonable +amount of time -- adjust it for your requirements. If the condition is not met, +the query returns an empty result. + +> **Tip** +> +> Use [check plugins](05-service-monitoring.md#service-monitoring-plugins) to monitor the backend. + +Replace the `default` string with your instance name if different. + +Example for MySQL: + +``` +# mysql -u root -p icinga -e "SELECT status_update_time FROM icinga_programstatus ps + JOIN icinga_instances i ON ps.instance_id=i.instance_id + WHERE (UNIX_TIMESTAMP(ps.status_update_time) > UNIX_TIMESTAMP(NOW())-60) + AND i.instance_name='default';" + ++---------------------+ +| status_update_time | ++---------------------+ +| 2014-05-29 14:29:56 | ++---------------------+ +``` + +Example for PostgreSQL: + +``` +# export PGPASSWORD=icinga; psql -U icinga -d icinga -c "SELECT ps.status_update_time FROM icinga_programstatus AS ps + JOIN icinga_instances AS i ON ps.instance_id=i.instance_id + WHERE ((SELECT extract(epoch from status_update_time) FROM icinga_programstatus) > (SELECT extract(epoch from now())-60)) + AND i.instance_name='default'"; + +status_update_time +------------------------ + 2014-05-29 15:11:38+02 +(1 Zeile) +``` + +A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](24-appendix.md#schema-db-ido). + +#### DB IDO in Cluster HA Zones + +The DB IDO feature supports [High Availability](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido) in +the Icinga 2 cluster. + +By default, both endpoints in a zone calculate the +endpoint which activates the feature, the other endpoint +automatically pauses it. If the cluster connection +breaks at some point, the paused IDO feature automatically +does a failover. + +You can disable this behaviour by setting `enable_ha = false` +in both feature configuration files. + +#### DB IDO Cleanup + +Objects get deactivated when they are deleted from the configuration. +This is visible with the `is_active` column in the `icinga_objects` table. +Therefore all queries need to join this table and add `WHERE is_active=1` as +condition. Deleted objects preserve their history table entries for later SLA +reporting. + +Historical data isn't purged by default. You can enable the least +kept data age inside the `cleanup` configuration attribute for the +IDO features [IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection) +and [IdoPgsqlConnection](09-object-types.md#objecttype-idopgsqlconnection). + +Example if you prefer to keep notification history for 30 days: + +``` + cleanup = { + notifications_age = 30d + contactnotifications_age = 30d + } +``` + +The historical tables are populated depending on the data `categories` specified. +Some tables are empty by default. + +#### DB IDO Tuning + +As with any application database, there are ways to optimize and tune the database performance. + +General tips for performance tuning: + +* [MariaDB KB](https://mariadb.com/kb/en/library/optimization-and-tuning/) +* [PostgreSQL Wiki](https://wiki.postgresql.org/wiki/Performance_Optimization) + +Re-creation of indexes, changed column values, etc. will increase the database size. Ensure to +add health checks for this, and monitor the trend in your Grafana dashboards. + +In order to optimize the tables, there are different approaches. Always keep in mind to have a +current backup and schedule maintenance downtime for these kind of tasks! + +MySQL: + +``` +mariadb> OPTIMIZE TABLE icinga_statehistory; +``` + +> **Important** +> +> Tables might not support optimization at runtime. This can take a **long** time. +> +> `Table does not support optimize, doing recreate + analyze instead`. + +If you want to optimize all tables in a specified database, there is a script called `mysqlcheck`. +This also allows to repair broken tables in the case of emergency. + +```bash +mysqlcheck --optimize icinga +``` + +PostgreSQL: + +``` +icinga=# vacuum; +VACUUM +``` + +> **Note** +> +> Don't use `VACUUM FULL` as this has a severe impact on performance. + ### Status Data Files > **Note** diff --git a/doc/images/installation/nano-syntax.png b/doc/images/addons/nano-syntax.png similarity index 100% rename from doc/images/installation/nano-syntax.png rename to doc/images/addons/nano-syntax.png diff --git a/doc/images/installation/vim-syntax.png b/doc/images/addons/vim-syntax.png similarity index 100% rename from doc/images/installation/vim-syntax.png rename to doc/images/addons/vim-syntax.png diff --git a/doc/images/icingadb/icingadb-architecture.png b/doc/images/icingadb/icingadb-architecture.png new file mode 100644 index 000000000..3d55ff757 Binary files /dev/null and b/doc/images/icingadb/icingadb-architecture.png differ diff --git a/doc/images/icingadb/icingadb-daemon.png b/doc/images/icingadb/icingadb-daemon.png new file mode 100644 index 000000000..de3f4c733 Binary files /dev/null and b/doc/images/icingadb/icingadb-daemon.png differ diff --git a/doc/images/icingadb/icingadb-icinga2.png b/doc/images/icingadb/icingadb-icinga2.png new file mode 100644 index 000000000..7b7aafa70 Binary files /dev/null and b/doc/images/icingadb/icingadb-icinga2.png differ diff --git a/doc/images/icingadb/icingadb-redis.png b/doc/images/icingadb/icingadb-redis.png new file mode 100644 index 000000000..d6eafab58 Binary files /dev/null and b/doc/images/icingadb/icingadb-redis.png differ