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

## <a id="configuring-ido"></a> 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.

### <a id="configuring-ido-mysql"></a> Configuring IDO MySQL

#### <a id="setting-up-mysql-db"></a> 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`.

#### <a id="upgrading-mysql-db"></a> 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.

#### <a id="installing-ido-mysql"></a> 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


### <a id="configuring-ido-postgresql"></a> 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`.


#### <a id="upgrading-postgresql-db"></a> 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.


#### <a id="installing-ido-postgresql"></a> 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