Icinga

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 icinga2^AUR.

You may also want to install monitoring-plugins.

Start/enable the icinga2.service.

Icinga Web 2

Install icingaweb2^AUR and optionally icingaweb2-module-director^AUR.

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