+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] +