From: Michael Friedrich Date: Wed, 29 Jan 2014 12:31:43 +0000 (+0100) Subject: Documentation: Add IDO PostgreSQL setup. X-Git-Tag: v0.0.7~23 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=06e703e26bb1caa740a755cb82ab8c4490581213;p=icinga2 Documentation: Add IDO PostgreSQL setup. Fixes #5574 --- diff --git a/doc/2.3-setting-up-ido.md b/doc/2.3-setting-up-ido.md index e341b4248..2b0e4ad00 100644 --- a/doc/2.3-setting-up-ido.md +++ b/doc/2.3-setting-up-ido.md @@ -5,15 +5,16 @@ 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. This installation guide assumed that -you are using MySQL. +both MySQL and PostgreSQL is implemented. > **Note** > > Icinga 2 uses the Icinga 1.x IDOUtils database schema starting with version > `1.11.0`. -### Setting up the database +### 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 @@ -27,22 +28,13 @@ setting up a MySQL database for Icinga 2: # mysql -u root -p - mysql> CREATE DATABASE icinga; - Query OK, 1 row affected (0.01 sec) - - mysql> GRANT USAGE ON icinga.* TO 'icinga'@'localhost' - IDENTIFIED BY 'icinga' - WITH MAX_QUERIES_PER_HOUR 0 - MAX_CONNECTIONS_PER_HOUR 0 - MAX_UPDATES_PER_HOUR 0; + mysql> CREATE DATABASE icinga; - mysql> GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE - ON icinga.* TO 'icinga'@'localhost'; - - mysql> FLUSH PRIVILEGES; + 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: @@ -57,7 +49,7 @@ following command: > On SuSE-based distributions the schema files are installed in > `/usr/share/doc/packages/icinga2-ido-mysql/schema`. -### Upgrading the database +#### Upgrading the MySQL database If the database has been installed and requires an upgrade, verify the current schema version first: @@ -66,22 +58,22 @@ schema version first: +---------+ | version | +---------+ - | 1.10.0 | + | 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.11.0.sql` -and newer. +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. Apply all database schema upgrade files incrementially. - # mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/upgrade/mysql-upgrade-1.11.0.sql + # 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 module +#### 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 @@ -96,3 +88,103 @@ You can enable the `ido-mysql` feature configuration file using `icinga2-enable- 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`. + + +#### 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. +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 + +