How to Install Icinga 2 and Icinga Web 2 on Debian 9

icinga web 2 debian 9

Icinga 2 is an open-source monitoring system which is highly scalable and extensible. It can monitor large, complex environments across multiple locations. It checks the availability of your network resources, notifies users of outages and generates performance data for reporting. It is a network monitoring application which can be configured from the web and its functionality is mainly based on PHP server-side programming language.

Basically, it monitors the state of network protocols, such as HTTP, FTP, SMTP, IMAP or other network services, hosts resources, physical sensors,  software installations, CPU load, memory, disk space and almost all inter-connected network devices via ICMP or ping requests. Furthermore, it can be easily configured to notify system or network administrators via mail, SMS, chat, or other types of alerts about network, systems, services or other related network outage and can also generate graphics about network downtime or performance.

In this article, I'll explain how to install an Icinga2 server with Web 2 interface on our latest  Debian 9.3 server. Let's walk through the step by step instructions on how to build our monitoring system.


Before proceeding with the installation we need to assure that our system meets all the software requirements for compiling and installing the application. On the first step, update your system repositories and software packages by issuing the below command.

# apt update
# apt upgrade
# apt install bash-completion

Next, setup the hostname for your server by executing the following command. I've added icinga2 to my hostname.

# hostnamectl set-hostname icinga2
# hostnamectl
Static hostname: icinga2
Icon name: computer-vm
Chassis: vm
Machine ID: 7f2b1120403449a3b27d2f40de770be2
Boot ID: 321481f419e94e6cb377ae804d9bab42
Virtualization: kvm
Operating System: Debian GNU/Linux 9 (stretch)
Kernel: Linux 4.9.0-4-amd64
Architecture: x86-64
# cat /etc/hostname

Finally, we need to reboot our Debian server in order to apply kernel updates and the hostname changes properly.

Install LAMP stack

As discussed before, Icinga 2 is a network monitoring application written in C++ and Icinga Web 2 is a powerful PHP framework for web applications that comes in a clean and reduced design. In order to execute its file scripts, a web server, such as Apache HTTP server, and a PHP processing gateway must be installed and operational on the server. I've installed Apache web server, MySQL and all required PHP modules needed by Icinga with the command below:

# apt install apache2 libapache2-mod-php7.0 php7.0-xml php7.0-opcache php7.0-xml php7.0-mbstring php7.0-json php7.0-curl php7.0-ldap php7.0-cli php7.0-gd php7.0-intl php7.0-readline php7.0-pgsql
# apt install mariadb-server mariadb-client php7.0-mysql

Start/enable the Apache/MySQL service.

# systemctl enable apache2 mariadb
# systemctl start apache2 mariadb
# systemctl status apache2 mariadb

After Apache, MySQL and PHP have been installed, you can test if the web server is up and running by browsing the server IP or you can even confirm by testing the network connections listening on their corresponding ports or by service using netstat command  from the console with root privileges as below:

# netstat -plan | grep :80
tcp6 0 0 :::80 :::* LISTEN 19097/apache2
tcp6 0 0 TIME_WAIT -
# netstat -plan | grep mysql
tcp 0 0* LISTEN 14240/mysqld 
unix 2 [ ACC ] STREAM LISTENING 52783 14240/mysqld /var/run/mysqld/mysqld.sock

Create MySQL database for Icinga2

Firstly, we need to login to the MySQL console and run the following command to secure MariaDB database and set a root password:

# mysql_secure_installation

Now we can create two databases which can be used by the Icinga2 application and a user with a password to manage these databases. I've created the database namely icingadb and icinga_users and granted privileges for the user icinga_user with a password to access those as below:

~# mysql -u root -p
Enter password:
Welcome to the MariaDB monitor. Commands end with ; or \g.
Your MariaDB connection id is 12
Server version: 10.1.26-MariaDB-0+deb9u1 Debian 9.1

Copyright (c) 2000, 2017, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]> create database icingadb;
Query OK, 1 row affected (0.00 sec)

MariaDB [(none)]> grant all privileges on icingadb.* to 'icinga_user'@'localhost' identified by 'password';
Query OK, 0 rows affected (0.00 sec)

MariaDB [(none)]> create database icinga_users;
Query OK, 1 row affected (0.00 sec)

MariaDB [(none)]> grant all privileges on icinga_users.* to 'icinga_user'@'localhost' identified by 'password';
Query OK, 0 rows affected (0.00 sec)

MariaDB [(none)]> flush privileges;
Query OK, 0 rows affected (0.01 sec)

The database icingadb is created for the icinga2 web application and the database icinga_users is created to store Icinga2 web interface users, groups and other web interface custom data.

Installing Icinga2

After completing the installation of all system requirements, we can proceed with the installation of the Icinga2 application alongside with MySQL IDO module.  We are using MySQL as the external database. Hence, we need to install the MySQL IDO module which is used for Icinga2 web interface. It is used for exporting all configuration and status information into its database. Icinga 2 has pre-compiled binary packages offered by Debian 9.3 repositories. Hence, the installation can be performed via their apt package manager as below:

# apt install icinga2 icinga2-ido-mysql

A series of prompts will appear on your screen while installing. Firstly, you will be asked if you want to configure and enable Icinga 2 to use MySQL module. Select Yes from the prompt and hit [enter] key to continue as illustrated in the below image.


In the next prompt, you will be asked if you want to configure the database for icinga2-ido-mysql with the dbconfig-common option. Choose No from the prompt and press [enter] key to finish Icinga 2 installation.


After enabling this module and creating our database we need to restart our Icinga2 service.

# systemctl start icinga2.service
# systemctl status icinga2.service

Please make sure the IDO MySQL configuration file is properly set with correct DB credentials.

# cat /etc/icinga2/features-enabled/ido-mysql.conf
* The db_ido_mysql library implements IDO functionality
* for MySQL.

library "db_ido_mysql"
object IdoMysqlConnection "ido-mysql" {
user = "icinga_user",
password = "password",
host = "localhost",
database = "icingadb"

Enabling the Feature list

By default, Icinga2 enables the following features. We can enable any additional feature to the list by running this command icinga2 feature enable <feature name> .  We can confirm the enabled settings by running this command as below:

~# icinga2 feature list
Disabled features: api command compatlog debuglog gelf graphite influxdb livestatus opentsdb perfdata statusdata syslog
Enabled features: checker ido-mysql mainlog notification

The following features are enabled by default:

Checker: This feature enables the execution of checks.

Mainlog: This feature enables the logging.

Notification: This feature enables notification mechanism.

IDO-mysql:  Provides IDO module for the database.

Installing Icinga Web2 Plugin

Our next step is to install Icinga 2 web interface and command line utility packages from Debian 9.3 repository using its package manager.

#apt install icingaweb2 icingacli

After the installation, you can restart the Icinga 2 daemon to pick-up all changes and verify application status before proceeding with the configuration part.

# systemctl restart icinga2.service
# systemctl status icinga2.service
# systemctl restart apache2

Now install MySQL schema for Icinga database by executing the following command. The MySQL database schema is located in /usr/share/icinga2-ido-mysql/schema/ directory.

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

Finally, we can generate the installation token to complete the Icinga web 2 plugin installation via a web interface.

# icingacli setup token create
The newly generated setup token is: c25b22acfc9f9094
# icingacli setup token show
The current setup token is: c25b22acfc9f9094

Configuring Icinga Web 2 plugin

After generating the token, we can start configuring the Icinga Web 2 plugin by opening this URL >> http://IP//icingaweb2/setup  in your browser.  You can navigate through these screenshots to get more clarity on that.

Step 1: Setting up the Token

As the first step, it will ask you to provide with the token generated before to start the installation phase. If you've not generated a token, then you can follow the instructions provided in the above screenshot for generating a token and proceed to the next step.

Step 2: Selecting the Icinga Web2 Modules

After providing the token, it'll move to the next section for selecting the modules. We can choose the preferred modules to proceed to the next step.

Icinga Web Modules

Step 3: Verifying the PHP settings

To proceed further, we need to install the missing PHP modules and set proper timezone. I've installed the missing PHP module using this command "apt install php7.0-pgsql" and restarted the Apache to make these changes effective. In addition, you can set a proper time zone in the PHP configuration file /etc/php/7.0/apache2/php.ini . After meeting the required settings, you can proceed to the next stage.

Icinga Web PHP settings

Step 5: Authenticating Methods

We need to choose the preferred authentication means to proceed with the installation. As I discussed before, I preferred to choose database type for this.

Icinga Web Authentication

Step 6: Enter the Database details

In this stage add Icinga 2 Web MySQL database name and the access credentials for this database. This database will be used for storing Icinga 2 web interface users and groups. Use the database information for the second database created earlier. Add icingaweb_db as a name for this resource and leave the Host, Port and Character set variables as default. Don’t check Persistent and SSL option. Hit on Validate Configuration button to validate the database connection, as shown in the below image. When you finish hit on Next button to move to the next installer section.

Icinga Web Database
Icinga Web DB auth

Step 7: Creating Icinga Web administration logins

After authenticating our database resources successfully, we need to create the Administrative account for managing the Icinga2 Web interface. Choose a strong password for this account. When you finish hit on Next button to move to the next installation screen.

Administrative logins

Step 8: Choosing the Application configuration options

Next, we need to configure Icinga application and logging configuration with the following settings just as in the screenshot.

  • Check Show Stacktraces
  • Storage Type = Database
  • Logging Type = File
  • Logging Level = Error
  • File path = /var/log/icingaweb2/icingaweb2.log

We need to create this log file from the server backend and set proper permission/ownership to make sure the proper working of the Icinga Web 2 logs.

Icinga Web Application

Step 9: Reviewing all chosen settings.

This screen will inform you that Icinga Web2 has been successfully configured and a detailed report will display all configurations made so far. Review the report and hit on Next button to continue to the next installation section.

Icinga Web installation Recap

Step 10: Configuring Monitoring Module

Now we've completed the authentication part and it follows with the configuration of the monitoring module.

Icinga Web monitoring

As we discussed before, Icinga IDO module exports all status information and configuration parts to the Icinga main database. Hence, we need to select this module and configure it properly to update the database with the information.

Icinga Web IDO

Here we need to provide the main database information to proceed. Fill out the database details here. Make sure to set proper privileges for the database user for any modifications.

Configure Icinga Command Transport with the following settings and hit Next button to continue.

  • Transport Name = icinga2
  • Transport Type = Local Command File
  • Command File = /var/run/icinga2/cmd/icinga2.cmd
Icinga Web transport medium

We don't need to make any modification in this Security stage. We can just proceed with the default settings by clicking 'Next".

Icinga Web Security

Step 11: Reviewing the Monitoring module configuration options

This stage will brief you with all the monitoring module configuration part which you've selected. You can just confirm the settings and proceed further to complete the setup.

Icinga Web Review

Final Step: Login to the Web interface

After the installation process has been successfully completed, a congratulation message will inform you that Icinga Web 2 has been successfully installed. Hit on the Login link in order to redirect to Icinga2 login page.

Icinga Web final stage

Login to Icinga Web 2 with the credentials configured during the installation process and you will be directed to Icinga Web 2 Dashboard,

 Login Icinga Web

Our master node is added by default to this system. We can see the service notifications for our master Icinga server over here. Or you can just browse this URL http://IP/icingaweb2/ to access the web interface.

 Dashboard Icinga Web

We can add any number of nodes to this monitoring system.

Wrapping up

We have successfully installed and configured Icinga 2 network monitoring application on Debian 9.3 server. For more details about the custom configuration, you can refer this Icinga Documentation. I hope this article is useful to you. Please post your valuable comments and suggestions on this.

8 Comments... add one

  1. Hi,

    thanks for the nice article. One note - Icinga 2 as core does not require PHP at all, it is a compiled C++ binary.
    Icinga Web 2 as web application framework does, and its good that you‘re going the PHP 7 route already.

    Small note - this guide was written for 2.4.x as can be seen in the screenshots. Would love to see it updated for 2.5 :)


  2. I think you forgot the line 'mysql -u root icinga_users -p < /usr/share/icingaweb2/etc/schema/mysql.schema.sql'. My setup couldn't be finished because the tables in icinga_users wheren't present.

    • Thank you for your update! I've included a step to install MySQL schema for my Icinga DB "icingadb" from the MySQL database schema located in /usr/share/icinga2-ido-mysql/schema/ directory.
      mysql -u root icingadb -p < /usr/share/icinga2-ido-mysql/schema/mysql.sql

      The DB "icinga_users" should be updated during our Icingaweb2 installation via web. You just need to make sure the assigned DB user is granted proper privileges to modify the DB. I mean proper DB connection and access. I hope it helps :)

  3. Hi,
    I have problem when I do "Step 6: Enter the Database details" Database resources The configuration has been successfully validated but my next step don't authentication backend only Database Setup and statement: "The provided credentials cannot be used to create the database and/or the user." Maybe you now what is wrong if I skip validation every next step are ok and last veryfication successfuly but finish I have statement: Sorry! Failed to set up Icinga Web 2 successfully and log:
    General configuration has been successfully written to: /etc/icingaweb2/config.ini

    Authentication configuration has been successfully written to: /etc/icingaweb2/authentication.ini
    Account "icinga2_admin" has been successfully defined as initial administrator.

    User Group Backend configuration has been successfully written to: /etc/icingaweb2/groups.ini
    Unable to create user group "Administrators". An error occured:
    ERROR: Zend_Db_Statement_Exception in /usr/share/icingaweb2/library/vendor/Zend/Db/Statement/Pdo.php:225 with message: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'icinga_users.icingaweb_group' doesn't exist, query was: SELECT COUNT(*) AS cnt FROM icingaweb_group AS g WHERE ( = 'Administrators')

    Resource configuration has been successfully written to: /etc/icingaweb2/resources.ini

    Monitoring backend configuration has been successfully written to: /etc/icingaweb2/modules/monitoring/backends.ini
    Resource configuration has been successfully updated: /etc/icingaweb2/resources.ini

    Command transport configuration has been successfully created: /etc/icingaweb2/modules/monitoring/commandtransports.ini

    Monitoring security configuration has been successfully created: /etc/icingaweb2/modules/monitoring/config.ini

    Module "monitoring" has been successfully enabled.
    Thanks for the help.

  4. hello
    nice article and i followed them.
    question how to add some Logfile from a Raspberry into Icinga or from a Cisco Switch add some Information?
    have a nice day

  5. just at the end i got a !

    Sorry! Failed to set up Icinga Web 2 successfully.

    User Group Backend configuration has been successfully written to: /etc/icingaweb2/groups.ini
    Unable to create user group "Administrators". An error occured:
    ERROR: Zend_Db_Statement_Exception in /usr/share/icingaweb2/library/vendor/Zend/Db/Statement/Pdo.php:225 with message: SQLSTATE[42S02]: Base table or view not found: 1146 Table 'icingadb.icingaweb_group' doesn't exist, query was: SELECT COUNT(*) AS cnt FROM icingaweb_group AS g WHERE ( = 'Administrators')

  6. Great tutorial. Just followed the instructions to get it done on a Debian 10 (buster) with Packages out of the default Repositories.
    Just forgot to restart icinga2 after creation of /etc/icinga2/features-enabled/ido-mysql.conf which leads to a Error "There is currently no icinga instance writing to the IDO. Make sure that a icinga instance is configured and able to write to the IDO." later on.

    Beside of this, it works like a charm.
    Thanks a lot for this. It saves a lot of time for the initial installation.


Leave a Comment