icinga2/doc/2.3-setting-up-ido.md

Configuring IDO

The IDO (Icinga Data Output) modules for Icinga 2 takes care of exporting all configuration and status information into a database. The IDO database is used by a number of projects including Icinga Web.

There is a separate module for each database back-end. At present support for both MySQL and PostgreSQL is implemented.

Note

Icinga 2 uses the Icinga 1.x IDOUtils database schema starting with version 1.11.0. Icinga 2 may require additional features not yet released with Icinga 1.x and therefore require manual upgrade steps during pre-final milestone releases.

Tip

Only install the IDO feature if your web interface or reporting tool requires you to do so (for example, Icinga Web or Icinga Web 2). Icinga Classic UI does not use IDO as backend.

Configuring IDO MySQL

Setting up the MySQL database

First of all you have to install the icinga2-ido-mysql package using your distribution's package manager. Once you have done that you can proceed with setting up a MySQL database for Icinga 2:

Note

The Debian packages can optionally create and maintain the database for you using Debian's dbconfig framework. This is the recommended way of setting up the database.

# mysql -u root -p

mysql>  CREATE DATABASE icinga;

mysql>  GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';

mysql> quit

After creating the database you can import the Icinga 2 IDO schema using the following command:

# mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/mysql.sql

Note

The Icinga 2 RPM packages install the schema files into /usr/share/doc/icinga2-ido-mysql-*/schema (* means package version). The Icinga 2 dist tarball ships the schema files in components/db_ido_mysql/schema/.

On SuSE-based distributions the schema files are installed in /usr/share/doc/packages/icinga2-ido-mysql/schema.

The Debian/Ubuntu packages put the schema files into /usr/share/icinga2-ido-mysql/schema.

Upgrading the MySQL database

If the database has been installed and requires an upgrade, verify the current schema version first:

# mysql -u root -p icinga -e 'SELECT version FROM icinga_dbversion;'
+---------+
| version |
+---------+
| 1.11.0  |
+---------+

Check the schema/upgrade directory for an incremental schema upgrade file, e.g. if your database schema version is 1.10.0 look for mysql-upgrade-1.12.0.sql and newer. If there isn't an upgrade file available there's nothing to do.

Note

During pre release status (0.x.y releases) small snippets called for example 0.0.8.sql will ship the required schema updates.

Apply all database schema upgrade files incrementially.

# mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/upgrade/mysql-upgrade-1.12.0.sql

Note

The Icinga 2 IDO module will check for the required database schema version on startup and generate an error message if not satisfied.

Installing the IDO MySQL module

The package provides a new configuration file that is installed in /etc/icinga2/features-available/ido-mysql.conf. You will need to update the database credentials in this file.

You can enable the ido-mysql feature configuration file using icinga2-enable-feature:

# icinga2-enable-feature ido-mysql
Module 'ido-mysql' was enabled.
Make sure to restart Icinga 2 for these changes to take effect.

After enabling the ido-mysql feature you have to restart Icinga 2:

# /etc/init.d/icinga2 restart

Configuring IDO PostgreSQL

Setting up the PostgreSQL database

First of all you have to install the icinga2-ido-pgsql package using your distribution's package manager. Once you have done that you can proceed with setting up a PostgreSQL database for Icinga 2:

Note

The Debian packages can optionally create and maintain the database for you using Debian's dbconfig framework. This is the recommended way of setting up the database.

# cd /tmp
# sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
# sudo -u postgres createdb -O icinga -E UTF8 icinga
# sudo -u postgres createlang plpgsql icinga

Locate your pg_hba.conf (Debian: /etc/postgresql/*/main/pg_hba.conf, RHEL/SUSE: /var/lib/pgsql/data/pg_hba.conf), add the icinga user with md5 authentification method and restart the postgresql server.

# vim /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

# /etc/init.d/postgresql restart

After creating the database and permissions you can import the Icinga 2 IDO schema using the following command:

# export PGPASSWORD=icinga
# psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/pgsql.sql

Note

The Icinga 2 RPM packages install the schema files into /usr/share/doc/icinga2-ido-pgsql-*/schema (* means package version). The Icinga 2 dist tarball ships the schema files in components/db_ido_pgsql/schema/.

On SuSE-based distributions the schema files are installed in /usr/share/doc/packages/icinga2-ido-pgsql/schema.

The Debian/Ubuntu packages put the schema files into /usr/share/icinga2-ido-pgsql/schema.

Upgrading the PostgreSQL database

If the database has been installed and requires an upgrade, verify the current schema version first:

# export PGPASSWORD=icinga
# psql -U icinga -d icinga -c "SELECT version FROM icinga_dbversion;"
version
\---------
1.11.0

Check the schema/upgrade directory for an incremental schema upgrade file, e.g. if your database schema version is 1.11.0 look for pgsql-upgrade-1.12.0.sql and newer. If there isn't an upgrade file available there's nothing to do.

Note

During pre release status (0.x.y releases) small snippets called for example 0.0.8.sql will ship the required schema updates.

Apply all database schema upgrade files incrementially.

# export PGPASSWORD=icinga
# psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/upgrade/pgsql-upgrade-1.12.0.sql

Note

The Icinga 2 IDO module will check for the required database schema version on startup and generate an error message if not satisfied.

Installing the IDO PostgreSQL module

The package provides a new configuration file that is installed in /etc/icinga2/features-available/ido-pgsql.conf. You will need to update the database credentials in this file.

You can enable the ido-pgsql feature configuration file using icinga2-enable-feature:

# icinga2-enable-feature ido-pgsql
Module 'ido-pgsql' was enabled.
Make sure to restart Icinga 2 for these changes to take effect.

After enabling the ido-pgsql feature you have to restart Icinga 2:

# /etc/init.d/icinga2 restart