Docs: Move IDO setup to its feature section

This commit is contained in:
Eric Lippmann 2022-06-02 09:29:43 +02:00
parent f982127bfc
commit cb04995f01
2 changed files with 227 additions and 445 deletions

View File

@ -643,437 +643,6 @@ systemctl restart icinga2
```
<!-- {% endif %} -->
## Set up Database <a id="set-up-database"></a>
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.
We recommend to install and configure the IDO feature before continuing with the installation
of Icinga Web 2.
!!! note
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.
### IDO with MySQL <a id="ido-with-mysql"></a>
#### Install MySQL Server <a id="installing-database-mysql-server"></a>
<!-- {% if debian or ubuntu %} -->
<!-- {% if not icingaDocs %} -->
#### Debian / Ubuntu
<!-- {% endif %} -->
```bash
apt-get install mariadb-server mariadb-client
mysql_secure_installation
```
<!-- {% endif %} -->
<!-- {% if centos %} -->
<!-- {% if not icingaDocs %} -->
#### CentOS
<!-- {% endif %} -->
#### 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
```
<!-- {% endif %} -->
<!-- {% if rhel %} -->
<!-- {% if not icingaDocs %} -->
#### RHEL
<!-- {% endif %} -->
#### 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
```
<!-- {% endif %} -->
<!-- {% if sles or opensuse %} -->
<!-- {% if not icingaDocs %} -->
#### SLES / openSUSE
<!-- {% endif %} -->
```bash
zypper install mariadb mariadb-client
systemctl enable mariadb
systemctl start mariadb
mysql_secure_installation
```
<!-- {% endif %} -->
<!-- {% if amazon_linux %} -->
<!-- {% if not icingaDocs %} -->
#### Amazon Linux 2
<!-- {% endif %} -->
```bash
yum install mariadb-server mariadb
systemctl enable mariadb
systemctl start mariadb
mysql_secure_installation
```
<!-- {% endif %} -->
#### Install IDO Feature <a id="installing-database-mysql-modules"></a>
The next step is to install the `icinga2-ido-mysql` package using your
distribution's package manager.
<!-- {% if debian or ubuntu%} -->
<!-- {% if not icingaDocs %} -->
#### Debian / Ubuntu
<!-- {% endif %} -->
```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.
<!-- {% endif %} -->
<!-- {% if centos %} -->
<!-- {% if not icingaDocs %} -->
#### CentOS
<!-- {% endif %} -->
#### CentOS 8
```bash
dnf install icinga2-ido-mysql
```
#### CentOS 7
```bash
yum install icinga2-ido-mysql
```
<!-- {% endif %} -->
<!-- {% if rhel %} -->
<!-- {% if not icingaDocs %} -->
#### RHEL
<!-- {% endif %} -->
#### RHEL 8
```bash
dnf install icinga2-ido-mysql
```
#### RHEL 7
```bash
yum install icinga2-ido-mysql
```
<!-- {% endif %} -->
<!-- {% if sles or opensuse %} -->
<!-- {% if not icingaDocs %} -->
#### SLES / openSUSE
<!-- {% endif %} -->
```bash
zypper install icinga2-ido-mysql
```
<!-- {% endif %} -->
<!-- {% if amazon_linux %} -->
<!-- {% if not icingaDocs %} -->
#### Amazon Linux 2
<!-- {% endif %} -->
```bash
yum install icinga2-ido-mysql
```
<!-- {% endif %} -->
#### Set up MySQL database <a id="setting-up-mysql-db"></a>
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 <a id="enable-ido-mysql"></a>
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 <a id="ido-with-postgresql"></a>
#### Install PostgreSQL server <a id="installing-database-postgresql-server"></a>
<!-- {% if debian or ubuntu %} -->
<!-- {% if not icingaDocs %} -->
#### Debian / Ubuntu
<!-- {% endif %} -->
```bash
apt-get install postgresql
```
<!-- {% endif %} -->
<!-- {% if centos %} -->
<!-- {% if not icingaDocs %} -->
#### CentOS
<!-- {% endif %} -->
#### 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
```
<!-- {% endif %} -->
<!-- {% if rhel %} -->
<!-- {% if not icingaDocs %} -->
#### RHEL
<!-- {% endif %} -->
#### 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
```
<!-- {% endif %} -->
<!-- {% if sles or opensuse %} -->
<!-- {% if not icingaDocs %} -->
#### SLES / openSUSE
<!-- {% endif %} -->
```bash
zypper install postgresql postgresql-server
chkconfig postgresql on
service postgresql initdb
service postgresql start
```
<!-- {% endif %} -->
<!-- {% if amazon_linux %} -->
<!-- {% if not icingaDocs %} -->
#### Amazon Linux 2
<!-- {% endif %} -->
```bash
yum install postgresql-server postgresql
postgresql-setup initdb
systemctl enable postgresql
systemctl start postgresql
```
<!-- {% endif %} -->
#### Install IDO Feature <a id="installing-database-postgresql-modules"></a>
The next step is to install the `icinga2-ido-pgsql` package using your
distribution's package manager.
<!-- {% if debian or ubuntu %} -->
<!-- {% if not icingaDocs %} -->
#### Debian / Ubuntu
<!-- {% endif %} -->
```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.
<!-- {% endif %} -->
<!-- {% if centos %} -->
<!-- {% if not icingaDocs %} -->
#### CentOS
<!-- {% endif %} -->
#### CentOS 8
```bash
dnf install icinga2-ido-pgsql
```
#### CentOS 7
```bash
yum install icinga2-ido-pgsql
```
<!-- {% endif %} -->
<!-- {% if rhel %} -->
<!-- {% if not icingaDocs %} -->
#### RHEL
<!-- {% endif %} -->
#### RHEL 8
```bash
dnf install icinga2-ido-pgsql
```
#### RHEL 7
```bash
yum install icinga2-ido-pgsql
```
<!-- {% endif %} -->
<!-- {% if sles or opensuse %} -->
<!-- {% if not icingaDocs %} -->
#### SLES / openSUSE
<!-- {% endif %} -->
```bash
zypper install icinga2-ido-pgsql
```
<!-- {% endif %} -->
<!-- {% if amazon_linux %} -->
<!-- {% if not icingaDocs %} -->
#### Amazon Linux 2
<!-- {% endif %} -->
```bash
yum install icinga2-ido-pgsql
```
<!-- {% endif %} -->
#### 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 <a id="enable-ido-postgresql"></a>
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
```
## Install Icinga Web 2
You are now ready to start the installation of Icinga Web 2. Please follow the
@ -1325,16 +894,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 <a id="install-backup-database"></a>
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)
<!-- {% endif %} --><!-- {# end windows else #} -->
<!-- {% endif %} --><!-- {# end index else #} -->

View File

@ -798,10 +798,234 @@ is running on.
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.
by Icinga Web 2 as data backend. You can either use a
[MySQL](#ido-with-mysql) or [PostgreSQL](#ido-with-postgresql) database.
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
#### IDO with MySQL <a id="ido-with-mysql"></a>
##### Install IDO Feature <a id="installing-database-mysql-modules"></a>
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 <a id="setting-up-mysql-db"></a>
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 <a id="enable-ido-mysql"></a>
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 <a id="ido-with-postgresql"></a>
##### Install IDO Feature <a id="installing-database-postgresql-modules"></a>
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 <a id="enable-ido-postgresql"></a>
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.