This tutorial will cover the installation of the Icinga2 monitoring application master node. This includes the base program, the web frontend, and the web-based configuration tool. This guide was made for Debian but should be similar on other distributions.

I have a script available to automate the steps described in this tutorial available from my git repo.

Install Packages

Here we will install the required packages. Icinga can use either MySQL or PostgreSQL, however this tutorial will use MySQL/MariaDB.

apt install icinga2 icingaweb2 icinga2-ido-mysql icingaweb2-module-director monitoring-plugins monitoring-plugins-contrib default-mysql-server

Secure MySQL

This step is optional but strongly recommended. The mysql_secure_installation script will harden your MySQL instance.

mysql_secure_installation

I recommend the following responses:

Switch to unix_socket authentication? Y
Change the root password? Y
Remove anonymous users? Y
Disallow root login remotely? Y
Remove the test database and access to it? Y
Reload privilege tables now? Y

Create Monitoring Database

The next several sections will cover creating databases for the various parts of Icinga. We'll start with the monitoring database. The following command creates a MySQL database named icinga2 and grants permissions to a user named ido_admin. These values are arbitrary, but I use them throughout the tutorial so I recommend leaving them as is. You should definitely change the password though, which in the command is change me. You will need this password and the passwords for the other databases later, so make sure you save them.

mysql -u root -e "CREATE DATABASE icinga2; GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga2.* TO ido_admin@'localhost' IDENTIFIED BY 'change me'; FLUSH PRIVILEGES;

We then need to import the ido schema into the database.

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

After importing the schema, we then write the configuration file that tells the monitoring module how to connect to the database.

/etc/icinga2/features-available/ido-mysql.conf
library "db_ido_mysql"
object IdoMysqlConnection "ido-mysql" {
	user = "ido_admin",
	password = "ido_password",
	host = "localhost",
	database = "icinga2"
}"

And finally we enable the monitoring module in Icinga.

icinga2 feature enable ido-mysql

Create Icingaweb2 Database

This step is nearly identical to the last. This time we create a database named icingaweb2 and grant permissions to the user named icingaweb2_admin.

mysql -u root -e "CREATE DATABASE icingaweb2;GRANT ALL ON icingaweb2.* TO 'icingaweb2_admin'@'localhost' IDENTIFIED BY 'changeme'; FLUSH PRIVILEGES;

Again we will need to import required schema into the database.

mysql -u root icingaweb2 </usr/share/icingawbe2/etc/schema/mysql.schema.sql

In this step we create the initial admin user that will be used to login to the web interface. As is, this would create a user named admin with the password changme. You should at least change the password.

passhash="$(php -r "echo password_hash(\"changeme\", PASSWORD_DEFAULT);")"
mysql -u root -e "USE icingaweb2; INSERT INTO icingaweb_user (name, active, password_hash) VALUES (\"admin\", 1, \"$passhash\"); FLUSH PRIVILEGES;"

Create Icinga Director Database

Here we create the database for Director. Director will require more configuration later, so for now we will just be creating the database.

mysql -u root -e "CREATE DATABASE director CHARACTER SET 'utf8'; GRANT ALL on director.* TO 'director'@'localhost' IDENTIFIED BY '$director_password';FLUSH PRIVILEGES;"

Setup Icinga2 API

Run the following command to initialize the Icinga API.

icinga2 api setup

And then restart Icinga to apply the changes.

systemctl restart icinga2

Configure Web Server

In this section we will configure the web server for accessing Icinga's web interface and Director configuration tool. This tutorial will use nginx but apache could be used as well. We'll start by installing the necessary packages.

apt install nginx php-fpm

Then we need to create the site configuration file.

/etc/nginx/sites-available/icingaweb2.conf
server {
  listen 80;
  server_name monitoring.example.com
  location ~ ^/icingaweb2/index\.php(.*)$ {
    fastcgi_pass unix:/var/run/php/php-fpm.sock;
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME /usr/share/icingaweb2/public/index.php;
    fastcgi_param ICINGAWEB_CONFIGDIR /etc/icingaweb2;
    fastcgi_param REMOTE_USER $remote_user;
  }

  location ~ ^/icingaweb2(.+)? {
    alias /usr/share/icingaweb2/public;
    index index.php;
    try_files $1 $uri $uri/ /icingaweb2/index.php$is_args$args;
  }

  # Not strictly necessary but allows you to get to icinga without 
  # specifying /icingaweb2 in the URL.
  location = / {
    return 302 http://$host/icingaweb2;
  }

}

And then restart nginx to pick up the changes.

systemctl restart nginx

At this point we are done with the Icinga setup module and so we can disable it.

icingacli module disable setup

Write Configuration Files

In this section we will write several configuration files. Icinga uses the INI format for its web interface configuration files.

In this first file we tell Icinga about the various resources it should have access to. These resources are the three databases created previously. Replace the password in each section with the corresponding password you set for that database earlier.

/etc/icingaweb2/resources.ini
[icinga2]
type = "db"
db = "mysql"
host = "localhost"
port = ""
dbname = "icinga2"
username = "ido_admin"
password = "ido password"
charset = ""
use_ssl = "0"

[icingaweb2]
type = "db"
db = "mysql"
host = "localhost"
port = ""
dbname = "icingaweb2"
username = "icingaweb2_admin"
password = "ido password"
charset = ""
use_ssl = "0"


[director]
type = "db"
db = "mysql"
host = "localhost"
port = ""
dbname = "director"
username = "director"
password = "director password"
charset = "utf8"
use_ssl = "0"

This file controls the authentication settings for the web interface. Here we tell Icinga to look at the icingaweb2 database for authentication purposes.

/etc/icingaweb2/authentication.ini
[icingaweb2]
backend = "db"
resource = "icingaweb2"

Now we tell icinga which users should have admin permissions. If you changed the username value from admin previously, be sure to update it here.

/etc/icingaweb2/roles.ini
[admins]
users = "admin"
resource = "icingaweb2"

Enable the web interface monitoring module.

icingacli module enable monitoring

Then write the configuration file pointing the monitoring module to the monitoring database.

/etc/icingaweb2/modules/monitoring/backends.ini
[icinga]
type = "ido"
resource = "icinga2"

Here we configure Icinga to use the API for communication. You will need to get your unique API password generated during the API setup from from /etc/icinga2/conf.d/api-users.conf. hostname should be the FQDN of the server.

/etc/icingaweb2/modules/monitoring/commandtransports.ini
[icinga2]
transport = "api"
host = hostname
port = "5665"
username = "root"
password = "api password"

Lastly, tell Icinga to protect variables with potentially sensitive values.

/etc/icingaweb2/modules/monitoring/config.ini
[security]
protected_customvars = "*pw*,*pass*,*community*"

Configure Director

This section will cover configuring Director configuration tool.

Create Director module configuration directory.

mkdir -p /etc/icingaweb2/modules/director

Write the Director configuration file.

/etc/icingaweb2/modules/director/config.ini
[db]
resource = "director"

Enable Director module and run the initial migration.

icingacli module enable director
icingacli director migration run

Write Director kickstart configuration file.

/etc/icingaweb2/modules/director/kickstart.ini
[config]
endpoint = "hostname"
username = "root"
password = "api password"

Kickstart Director, then render and deploy the configuration.

icingacli director kickstart run
icingacli director config render
icingacli director config deploy

Director is setup at this point so we will shred the unneeded configuration file containing sensitive information.

shred -uz /etc/icingaweb2/modules/director/kickstart.ini

Login to your Monitoring Instance

You are now ready to login to your monitoring instance with the admin user created previously. Open a web browser and go to http://hostname/icingaweb2. You should see a screen similar to this:

Next Steps

In the following articles we will go through setting up Icinga2 agents on servers, and configure your monitoring instance through Icinga Director.

Consider donating if this article was useful. [BTC]