Presentation

The initial Icinga was a fork of the most famous monitoring engine, the well knowned Nagios. The team has worked on this first version during 5 years. And in 2014 they delivered a brand new version (v2) who have been completely built from scratch in C++.

For the ones who simply want to test Icinga2 & IcingaWeb2 with everything packaged, you can run the excellent docker container made by jjethwa. For the braves who want to install from scratch and instance of Icinga2 & IcingaWeb2 follow this guide ...


Icinga2 installation

Add key to the apt package manager + populate sources.list

apt install apt-transport-https
wget -O - https://packages.icinga.com/icinga.key | apt-key add -
DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release)
echo "deb https://packages.icinga.com/debian icinga-${DIST} main" > /etc/apt/sources.list.d/${DIST}-icinga.list
echo "deb-src https://packages.icinga.com/debian icinga-${DIST} main" >> /etc/apt/sources.list.d/${DIST}-icinga.list
apt update

Add Debian Backport repository in order to be compliant with libboost version prerequisites

DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
 echo "deb https://deb.debian.org/debian ${DIST}-backports main" > \
 /etc/apt/sources.list.d/${DIST}-backports.list

apt-get update

Install icinga2 core and nagios monitoring-plugins that will add more than fifty standard plugins. Each one of them works in as a standalone binary and can be used by the most knowned Open Source monitoring solution (Icinga, Nagios, Shinken, Sensu, …)

apt install -y icinga2 monitoring-plugins

At the end of the installation, the server must be already running. But you can double check that with.

systemctl status icinga2

One very useful trick is to activate the syntax highlighting with vim. This will avoid mistyping errors when filling our configuration files.

apt install -y vim-icinga2 vim-addon-manager
vim-addon-manager -w install icinga2

IcingaWeb2 prerequisites

IcingaWeb2 is the Web UI that will transcribe configuration files to web interface. In order to make it works we will need a MySQL database, a Web server and the IDO feature which is in charge of exporting configuration & status informations to the DB. This last feature will be used by IcingaWeb2 as data backend.

MySQL

First we will install the MySQL server, in order to store configuration and status informations of the Icinga2 instance.

apt install mysql-server mysql-client
mysql_secure_installation
(Leave answers by default, and change the root password)

Second, we will install the IDO feature and create the MySQL database. IDO feature which is in charge of exporting configuration & status informations to the DB. This last feature will be used by IcingaWeb2 as data backend.

apt install -y icinga2-ido-mysql
mysql -u root -p
CREATE DATABASE icinga;
GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY ‘STRONG_PASSWORD';
quit;

Now the user and the databases are created we can import Icinga2 IDO schema to the DB.

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

Then finish the Database / IDO part by enabling the module.

# 1- Edit credentials in /etc/icinga2/features-available/ido-mysql.conf
# 2- Enable the IDO feature
icinga2 feature enable ido-mysql
# 3- Restart icinga2
systemctl restart icinga2

Apache2

Obviously, a Web Server is needed to server the application. Apache is the recommanded one by the official team.

apt install -y apache2

IcingaWeb2 and the web interface needs REST API to send actions toi the differents nodes like forced checks, check reschedules, ….

Launching the default API setup will enable the feature, setup certificates and create a new API user with an auto-generated password in the /etc/icinga2/conf.d/api-users.conf

icinga2 api setup
vim /etc/icinga2/conf.d/api-users.conf

object ApiUser "icingaweb2" {
  password = "XXXXXXXXXXXXX"
  permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ]
}

To finish IcingaWeb pre-requisites installation, restart the daemon.

systemctl restart icinga2

IcingaWeb2 installation

Preparation

Begin by installing binary and associated dependencies.

apt install -y icingaweb2 icingacli php7.0-gd

A token is required to authenticate during the web setup process. Generate it with :

icingacli setup token create

Now edit the PHP timezone to match your current location.

vim /etc/php/7.0/apache2/php.ini
...
date.timezone = Europe/Paris

Debian requires to create the Database and a new user due to local security restrictions because the web wizard cannot create a DB and an user through a local Unix socket.

mysql -u root -p
create database icingaweb2;
GRANT ALL ON icingaweb2.* TO icingaweb2@localhost IDENTIFIED BY 'STRONG_PASSWORD’;
quit

Finish by restarting the Web Server.

systemctl restart apache2

WebUI installer

Start the Web Wizard, by opening a browser and point it to http://YOUR_HOST/icingaweb2

I will not include the numerous screenshots during the installation process, but rather text details you must include.

Specify the previously generated token
Welcome to the configuration of Icinga Web 2!
    Setup Token: <- Paste the token created on the “Prepare Web Setup” step
Modules -> leave by default
Global Check -> leave by default
Authentication 
    Authentication Type -> Database
Database Resource
    Resource Name -> icingaweb2
    Database Type -> MySQL
    Host -> localhost
    Port -> 3306
    Database Name -> icingaweb2
    Username -> icingaweb2
    Password -> …
    “Validate Configuration” to be sure everything is working properly
Authentication Backend
    Backend Name -> icingaweb2
Administration
    Username -> YOUR_USERNAME
    Password -> …
Application Configuration -> leave by default
Resume -> next
Monitoring Backend
    Backend Name -> icinga
    Backend Type -> IDO
Monitoring IDO Resource
    Resource Name -> icinga_ido
    Database Type -> MySQL
    Host -> localhost
    Port -> 3306
    Database Name -> icinga
    Username -> icinga
    Password -> …
Command Transport
    Transport Name -> icinga2
    Transport Type -> Local Command File
    Command File -> /var/run/icinga2/cmd/icinga2.cmd
Monitoring Security -> leave by default
Finish

You can now log into IcingaWeb2 => http://YOUR_HOST/icingaweb2