A Startup Guide to Setup Icinga2 on Ubuntu 15.04

Hi everybody! today I am going to show you how to install Icinga2 and Icinga-web on Ubuntu 15.05 Vivid, after that we are going learn how to manage its configuration, hosts, services and notifications.

Table of Contents

      • Introduction
        • About Icinga2
        • Requirements
      • Installing packages
        • Installing MySQL
        • Installing Icinga Web
        • Installing Nagios Plugins
      • Setting up Icinga2
        • icinga2.conf
        • Constants
        • Hosts
        • Service checks
        • Notifications


About Icinga2

So, what is Icinga2 ? Icinga2 is an opensource monitoring system that helps to us keep track of systems. Icinga came alive as a fork from Nagios, now it have its set of unique features, but also and if you are like me and loves Nagios you probably love Icinga too.
Installing and setting up packages

Icinga web tatical overview

Icinga web tatical overview


The following software are needed and are going to be installed on the Icinga server,some will be installed automatically, some of them are not critical but for a fully functional setup, I strongly recommend you to install all.

  • MySQL - This will be our database backend
  • Apache - This will be our HTTP server
  • PHP - This is the programming language on which Icinga Web is made
  • Postfix - You will need this if you want to have mail notifications
  • Nagios Plugins - A set of check plugins made originally for Nagios, but also compatible with Icinga
  • Perl - This is the language that many Nagios plugins are made.

Installing packages

Install MySQL server

In order for to run Icinga, you must to have access to a SQL database, you can choose between MySQL or PostgreSQL, as for the sake of simplicity, i am going to cover only minimum MySQL setup, also if you already have a database running you should skip this step.

#apt-get install mysql-server

You will be asked for the root password as follows:

Setup MySQL root password

Setup MySQL root password

You must ensure that at least minimum security exists before any sensitive information touches your database, run the following command and follow the on-screen steps, you should at least set the password for the root user, also allow root login over the network is discouraged for almost any service.


Install Icinga2 packages

Adding Icinga's apt repository:

# add-apt-repository ppa:formorer/icinga

And install packages:

# apt-get install icinga-web-config-icinga2-ido-mysql

So you gonna see dialogs like the following, this will setup ido-mysql, before you continue make sure you have administrative access to MySQL or PostgreSQL. Pay attention to the fact that you are going to be asked to provide passwords to different services, the screens are quite similar, so be careful.

Enable ido-mysql during the installation

Enable ido-mysql on the installation

Configure ido-mysql with dbconfig-common

Configure ido-mysql with dbconfig-common

Set ido-mysql database password

Set ido-mysql database password

Setup icinga web with dbconfig-common

Setup icinga web with dbconfig-common

Select MySQL database as backend

Select MySQL database as backend

Provide administrative password to create database

Provide administrative password to create database

Provide password to icinga-web application database

Provide password to icinga-web application database

Provide the password for the web interface

Provide the password for the web interface

If the above command fail in the post install,it's possible that the call to feature enable on Icinga failed, try changing the post-install script as following:

# sed -i.bak -e s'/icinga2-enable-feature/icinga2 feature enable/'g /var/lib/dpkg/info/icinga-web-config-icinga2-ido-mysql.postinst

Or edit the file with vi, change 'icinga-enable-feature' with 'icinga2 feature enable' as follows:

# vi /var/lib/dpkg/info/icinga-web-config-icinga2-ido-mysql.postinst
Icinga2 Fix postinstall script bug

Fix postinstall script bug

And then run post-install script again:

# dpkg --configure -a

Configure PHP timezone

In order for Icinga2 to work properly, you must assure that PHP timezone correctly reflect yours, use the following command to achieve this:

#tzone="'";tzone="$tzone$(cat /etc/timezone)$tzone"; sed s'|date.timezone =|;\ndate.timezone = '$tzone'\n;|' /etc/php5/apache2/php.ini

Or you can edit php.ini and set the date.timezone by hand:

#vi /etc/php5/apache2/php.ini

Once php.ini is ready, restart Apache:

# service apache2 restart

Let's enable some other Icinga features as needed:

# icinga2 feature enable ido-mysql
# icinga2 feature enable compatlog
# icinga2 feature enable icingastatus
# icinga2 feature enable livestatus
# icinga2 feature enable notification
# icinga2 feature enable perfdata
# icinga2 feature enable statusdata

Note: Some of the above commands may fail in case they are already enabled, just ignore.

Installing Nagios plugins

Just use apt:

# apt-get install nagios-plugins

That is it for the installation, you should now be able to access and login with the credentials we set during the installation.

icinga2 Icinga web login page

Icinga web login page

Setting up Icinga2

For you to configure Icinga2 you must edit text files containing configuration objects, the default location for these files is /etc/icinga2, and there you will find icinga2.conf and sample files.


This is the main configuration file of Icinga2, in fact one may set everything from here, but if you have many services and hosts to or if you configuration management systems, it become easier to identify and change if you have these settings on separate files.

Consider these two parameters for now and you will be fine.

This tells Icinga to search for configuration in files that match filename, this can be one or more files if the filename given has unix-like wildcards.

Include constants.conf, there is important parameters in this file as you will see:

include "constants.conf"

This acts the same as include, but it will work for directories containing configuration files and their subdirectories, it also is used for clustering interface, but it's beyond the scope of this article.

Create an include_recursive to conf.d, we will put our confs there:

include_recursive "conf.d"


Constants are parameters that are immutable during the execution, they are set in constants.conf, by default and you should set at least the following constants to Icinga2 work correctly.

NodeName sets the name of the host in which Icinga2 is running, and you will need this setting to test the localhost.

const NodeName = "icinga-server"

The constant sets where Icinga2 will look for check plugins, you must set this according to your setup, usually /usr/lib/nagios/plugins on systems like Ubuntu:

const PluginDir = "/usr/lib/nagios/plugins"


For you to include hosts in your monitoring environment, you have to declare Host objects, it should have an unique name after the Host term and also an address that is the IP address that Icinga use to connect and make it's checks.

Let's suppose that we have to take care of a machine running sales software in our client's store.

Create and fill the file mynetwork.conf with the following content

# vi /etc/icinga2/conf.d/mynetwork.conf


object Host "pos-terminal" {
address = ""
check_command = "hostalive"

The snippet above tells Icinga2 to create a "pos-terminal" Host object with the IP address "" and check it with the hostalive command, that will basically ping the host.

After making changes to .conf files run the the following command to test if there is any error on it:

# icinga2 daemon -C

Once you assured that there is no error on .conf files, restart the icinga service for the changes take effect.

# service icinga2 restart

Take a look on the web interface to see the host there:

Our Point of Sale terminal was added to Icinga2

Our Point of Sale terminal was added

Services Checks

You have host to be checked you must have also define what should be checked, Icinga2 ships with checking commands for many services and you just need to apply these checks to your hosts, services or networks.

We will set service checks for the status of the MySQL database that take care of the sales data on our point of sale terminal.

Add these lines to mynetwork.conf:

object CheckCommand "sales-db" {
import "plugin-check-command"

command = [
PluginDir + "/check_mysql"

arguments = {
"-H" = "$mysql_address$"
"-d" = "$mysql_database$"
vars.mysql_address = "$address$"
vars.mysql_database = "salesdb"
vars.mysql_user = "nagios_check"
vars.mysql_pass = "password"

env.MYSQLUSER = "$mysql_user$"
env.MYSQLPASS = "$mysql_pass$"

apply Service "sales-db" {
import "generic-service"

check_command = "sales-db"

assign where host.vars.sales_terminal

The above snippet defines a CheckCommand object identified as sales-db, this object imports characteristics of the plugin-check-command of Icinga Template Library (ITL), and use check_mysql plugin of nagios-plugins package, found in the PluginDir directory defined in the constants.conf.

We set the arguments of the check_mysql plugin, -H for the host and -d for database using $mysql_address$ and $mysql_database$ variables.

We set also en environment variables MYSQLUSER and MYSQLPASS on the shell that the command check_mysql will run to $mysql_user$ and $mysql_pass$ respectively.

Finally, we apply a service called "sales-db" that inherited parameters from generic-service of ITL and uses the check_command sales-db that we have created and assign it to hosts having the custom variable sales_terminal set.

Creating salesdb
Let's create the salesdb in the MySQL for our sample service, in a real world scenario you already have your MySQL server running and you don't need to create a database, but remember to grant privileges to the icinga_check user.

Login into MySQL:

mysql -u root -p

And then execute the SQL commands:

create table salesdb;
create table sales(count int);

You need to grant access to icinga_check no the database

grant all privileges to 'icinga_check'@'localhost' on salesdb identified by 'password';

Restart Icinga2 service and check our service on Icinga-web interface

service icinga2 restart

Go to the web interface again and check if salesdb service is there:

Icinga2 Check for the salesdb service

Check for the salesdb service


Now that we have set icinga to check the services running on our hosts, it's a good idea to set up notifications for this services, so that when a problem arises Icinga tells us what is going on, in our case we will receive an email.

Firstly, you must install the mail command to send our emails, we can do it installing mailutils package with apt:

# apt-get install mailutils

Now add these lines to mynetwork.conf:

object User "sysadmin" {
display_name = "System Administrator"
enable_notifications = true
states = [ Warning, Critical ]
types = [ Problem, Recovery ]
email = "root@localhost"

apply Notification "mail-sysadmin" to Service {
import "generic-notification"

command = "mail-notification"
users = [ "sysadmin" ]

assign where service.name == "salesdb"

In the above lines we first created a "sysadmin" user, enabled notifications to this user, then we told it to notify about warning and critical states when the problem arises and when it recover from the problem on the email root@localhost. So we create a notification to the sysadmin user about the salesdb service.


You just installed the icinga2 server with ido-mysql backend, Icinga web interface, nagios plugins, custom hosts and services. Now you are able to make your own conf files, take a look on the sample files inside /etc/icinga2, they have more options for you to check and are well commented. There is many other features available on Icinga that I did not covered for the sake of simplicity, but ammong other things, I recommend you to dig up on custom plugins creation, NRPE checks, clustering, voice alerts, SMS and phone call notifications.


Carlos Alberto 3:00 am


Your email address will not be published. Required fields are marked *

1 Comment

  1. Hey, still running through the guide, but best I have found so far. One note: after "add-apt-repository ppa:formorer/icinga" need to add a line for "apt-get update" before doing the install so it can find the packages.