Jump to content

# Icinga

2 languages

- Deutsch
- 日本語

From ArchWiki

Icinga is an open source host, service and network monitoring program. It monitors specified hosts and services, alerting you to any developing issues, errors or improvements. This article describes the installation and configuration of Icinga.

## Installation

Install icinga2AUR.

You may also want to install monitoring-plugins.

Start/enable the `icinga2.service`.

## Icinga Web 2

Install icingaweb2AUR and optionally icingaweb2-module-directorAUR.

Enable the `icinga-director.service` if you installed the director module.

### Configure web server

If you use php-fpm, you will have to override the unit - make sure to replace `php-fpm.service.d` with `php-fpm-legacy.service.d` if you use that:

    /etc/systemd/system/php-fpm.service.d/override_icingaweb2.conf

    [Service]
    ReadWritePaths = /etc/icingaweb2

You will also have to add your webserver to the group `icingaweb2` to be able to create and change configuration files from the web app directly, assuming `http` is the webserver user:

    # usermod -a -G icingaweb2 http

#### nginx

Example server block, with php-legacy, the sock path in the example becomes `/run/php-fpm-legacy/php-fpm.sock` instead:

    server {
    	listen 80;
    	listen [::]:80;
    	server_name localhost;
    	root /usr/share/webapps/icingaweb2/public;
    	location ~ ^/icingaweb2/index\.php(.*)$ {
    		fastcgi_pass unix:/run/php-fpm/php-fpm.sock;
    		fastcgi_index index.php;
    		include fastcgi_params;
    		fastcgi_param SCRIPT_FILENAME /usr/share/webapps/icingaweb2/public/index.php;
    		fastcgi_param ICINGAWEB_CONFIGDIR /etc/icingaweb2;
    		fastcgi_param REMOTE_USER $remote_user;
    	}
    	location ~ ^/icingaweb2(.+)? {
    		alias /usr/share/webapps/icingaweb2/public;
    		index index.php;
    		try_files $1 $uri $uri/ /icingaweb2/index.php$is_args$args;
    	}
    }

#### Apache

If you get HTTP/503 errors, check in the configuration file to see if you are allowed to access the page:

     Order allow,deny
     Allow from all

This has to be located in the `<Directory "/usr/local/icinga-web/lib/ext3/">` and `<Directory "/usr/local/icinga-web/pub/">` sections.

### Configure PHP

Uncomment the following extensions:

    /etc/php/php.ini

    curl
    gettext
    pdo_mysql - MariaDB setups
    pdo_pgsql - PostgreSQL setups
    pgsql - PostgreSQL setups
    intl - Icinga Web 2
    sockets - Director

If `open_basedir` is set in `php.ini`, you need to authorize `/usr/share/icinga-php` and you need to create `ICINGAWEB_LOCALEDIR` environment variable to `/usr/share/icinga-php/icinga-L10n/locale` to avoid an `open_basedir` error on `/usr/share/webapps/icingaweb2/library/Icinga/Application/ApplicationBootstrap.php` at line 740.

## Configure Icinga

You can choose either PostgreSQL or MariaDB to use as a backend for Icinga.

By default Icinga uses the following files and directories:

- `/etc/icinga2` — Contains Icinga 2 configuration files.
- `/usr/sbin/icinga2*` — The Icinga 2 binary.
- `/usr/share/doc/icinga2` — Documentation files that come with Icinga 2.
- `/usr/share/icinga2/include` — The Icinga Template Library and plugin command configuration.
- `/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/lib/icinga2` — Icinga 2 state file, cluster log, local CA and configuration files.
- `/var/log/icinga2` — Log file location and compat/ directory for the CompatLogger feature.

### Automatically

Generate a setup token and let Icinga Web 2 handle it by using the setup page:

    # icingacli setup config directory --group icingaweb2;
    # icingacli setup token create;

http://localhost/icingaweb2/setup

### Manually

In case you do not want to use Icinga Web 2 to configure everything for you.

#### MariaDB

https://icinga.com/docs/icinga-2/latest/doc/02-installation/

https://icinga.com/docs/icinga-web/latest/doc/02-Installation/

Create icinga user and db:

    # mysql -u root -p
    > CREATE DATABASE icinga;
    > GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'supersecretpassword';
    > quit

Create icingaweb2 user and db:

    # mysql -u root -p
    > CREATE DATABASE icingaweb2;
    > GRANT ALL ON icingaweb2.* TO 'icingaweb2'@'localhost' IDENTIFIED BY 'anothersecurepassword';
    > quit

Import the icinga schema:

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

Import the icingaweb2 schema:

    # mysql -p icingaweb2 < /usr/share/webapps/icingaweb2/etc/schema/mysql.schema.sql

Create director database and user:

    # mysql -u root -p
    > CREATE DATABASE director CHARACTER SET 'utf8';
    > CREATE USER director@localhost IDENTIFIED BY 'directorpassword';
    > GRANT ALL ON director.* TO director@localhost;

Create a user to login to Icinga Web 2:

    $ php -r 'echo password_hash("yourwebpassword", PASSWORD_DEFAULT);'

Use the hash you got from the previous command, replacing the hash in this example to insert a new user into the database:

    # mysql -u root -p
    > USE icingaweb2;
    > INSERT INTO icingaweb_user (name, active, password_hash) VALUES ('icingaadmin', 1, '$2y$10$G.qLnALysvw3yr5wP70sF.KtlwB/xDYypRU3x2WZd6x3N0oBAXuIi');

Edit `/etc/icinga2/features-available/ido-mysql.conf` with your SQL details.

Enable ido-mysql:

    # icinga2 feature enable ido-mysql

#### PostgreSQL

https://icinga.com/docs/icinga2/latest/doc/02-installation/#installing-postgresql-database-server

As the postgres user, create icinga user and db:

    [postgres]$ psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'supersecretpassword'"
    [postgres]$ createdb -O icinga -E UTF8 icinga

Create icingaweb2 user and db:

    [postgres]$ psql -c "CREATE ROLE icingaweb2 WITH LOGIN PASSWORD 'anothersecurepassword'"
    [postgres]$ createdb -O icingaweb2 -E UTF8 icingaweb2

Import the icinga schema:

    # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql

Import the icingaweb2 schema:

    # psql -U icingaweb2 -d icingaweb2 < /usr/share/webapps/icingaweb2/etc/schema/pgsql.schema.sql

Create director database and user:

    [postgres]$ psql -q -c "CREATE DATABASE director WITH ENCODING 'UTF8';"
    [postgres]$ psql director -q -c "CREATE USER director WITH PASSWORD 'directorpassword'; GRANT ALL PRIVILEGES ON DATABASE director TO director; CREATE EXTENSION pgcrypto;"

Create a user to login to Icinga Web 2:

    $ php -r 'echo password_hash("yourwebpassword", PASSWORD_DEFAULT);'

Use the hash you got from the previous command, replacing the hash in this example to insert a new user into the database:

    [postgres]$ psql -d icingaweb2
    icingaweb2=# INSERT INTO icingaweb_user (name, active, password_hash) VALUES ('icingaadmin', 1, '$2y$10$G.qLnALysvw3yr5wP70sF.KtlwB/xDYypRU3x2WZd6x3N0oBAXuIi');

Edit `/etc/icinga2/features-available/ido-pgsql.conf` with your SQL details.

Enable ido-pgsql:

    # icinga2 feature enable ido-pgsql

#### Finally

Enable Icinga api:

    # icinga2 api setup

Enable director module and its dependencies:

    # icingacli module enable incubator
    # icingacli module enable director

Create Director database schema:

    # icingacli director migration run --verbose

Restart `icinga2.service` for the changes to apply.

If you chose to use Icinga Web 2, create appropriate .ini files (Use `mysql` and `3306` for db and port if you use MariaDB):

    /etc/icingaweb2/authentication.ini

    [icingaweb2]
    backend  = db
    resource = icingaweb2

    /etc/icingaweb2/resources.ini

    [icingaweb2]
    type                = "db"
    db                  = "pgsql"
    host                = "localhost"
    port                = "5432"
    dbname              = "icingaweb2"
    username            = "icingaweb2"
    password            = "anothersecurepassword"

    [icinga2]
    type                = "db"
    db                  = "pgsql"
    host                = "localhost"
    port                = "5432"
    dbname              = "icinga"
    username            = "icinga"
    password            = "supersecretpassword"

    [director]
    type                = "db"
    db                  = "pgsql"
    host                = "localhost"
    port                = "5432"
    dbname              = "director"
    username            = "director"
    password            = "directorpassword"
    charset             = "utf8"

The following is the currently default config, the important non-default part is `config_resource`.

One can instead generate this file through http://localhost/icingaweb2/config/general instead.

    /etc/icingaweb2/config.ini

    [global]
    show_stacktraces = "1"
    show_application_state_messages = "1"
    module_path = "/usr/share/webapps/icingaweb2/modules"
    config_resource = "icingaweb2"

    [security]
    use_strict_csp = "0"

    [logging]
    log = "syslog"
    level = "ERROR"
    application = "icingaweb2"
    facility = "user"

    /etc/icingaweb2/roles.ini

    [admins]
    users               = "icingaadmin"
    permissions         = "*"

    /etc/icingaweb2/modules/director/config.ini

    [db]
    resource = "director"

Go to http://localhost/icingaweb2/ and try to login as 'icingaadmin' and your chosen password - if all works, you are done with the basic setup!

## Upgrade database

New versions usually require an upgrade of the database. You can find the SQL upgrade scripts in the following folders:

    /usr/share/icinga2-ido-mysql/schema/upgrade
    /usr/share/icinga2-ido-pgsql/schema/upgrade
    /usr/share/webapps/icingaweb2/schema/mysql-upgrades
    /usr/share/webapps/icingaweb2/schema/pgsql-upgrades

To do the upgrade, `cd` into the appropriate folder as written above and import the schema, examples:

    # mysql -u root -p icinga < ./2.8.1.sql
    # mysql -u root -p icingaweb2 < ./2.12.0.sql
    # psql -U icinga -d icinga < ./2.8.1.sql
    # psql -U icingaweb2 -d icingaweb2 < ./2.12.0.sql

Restart `icinga2.service` for the changes to apply.

## See also

- Documentation - Official documentation
- monitoring-plugins - Default plugins for Icinga and other monitoring applications
- Nagios Plugins - The home of the legacy plugins
- Wikipedia article
- NagiosExchange - Overview of plugins, addons, mailing lists for Icinga

Category:

- Network monitoring