View source for Install Icinga2 on Ubuntu 16.04

Author: Etienne Barrier

Last modified: 11.11.2016

==Preliminary notes==
This tutorial shows how to install Icinga 2 on Ubuntu 16.04 LTS, using PostgreSQL (as for database) and Apache 2 (as for webserver).

This tutorial does NOT show:
* how to install Icinga version 1
* how to install/configure databses other than PostgreSQL (for example MySQL, MariaDB, etc.)
* how to install/configure webservers other than Apache2 (for example Nginx)
* how to use Icinga2

It is assumed that you are already familiar with the basics of Linux command line terminal commands. But this tutorial is made so that you can copy paste the commands to your terminal.

Versions used in this tutorial:
* Icinga 2 (version: r2.5.4-1)
* Ubuntu 16.04.1 LTS (Xenial)
* PostgreSQL (version: 9.5.2)
* Apache 2 (version: 2.4.18)
* Php (version 7.0)

Depending on the versions you use, the commands and/or the path shown in this tutorial might be different.

All commands in this tutorial are made as root. You must be root or be able to use "sudo" command to install and configure Icinga.

The version of Icinga used (version 2) is referred sometimes as “Icinga” or “Icinga 2” accross the tutorial.

This tutorial is based on the following tutorials:
*[http://docs.icinga.org/icinga2/latest/doc/module/icinga2/chapter/getting-started Official Icinga 2 documentation]
*[https://github.com/Icinga/icingaweb2/blob/master/doc/02-Installation.md Official Icinga Web 2 installation documentation]
*[http://linoxide.com/ubuntu-how-to/install-icinga2-ubuntu-16-04 Linoxide "how to"]
*[https://lowendbox.com/blog/server-monitoring-with-icinga-2-part-1-the-server-ubuntu-host Lowendbox blog post]

For any comments, please write to ebarrier{at]itcollege[dot)ee.

==What is Icinga?==
Icinga 2 is an open source monitoring system which checks the availability of your network resources, notifies users of outages, and generates performance data for reporting.<ref>[http://docs.icinga.org/icinga2/latest/doc/module/icinga2/toc#!/icinga2/latest/doc/module/icinga2/chapter/about-icinga2#what-is-icinga2] Icinga2 official documentation</ref>

Icinga started as a Nagios fork and did quite well, mostly considering Icinga Web which was better than Nagios’ web interface. Icinga 2 is a complete rewrite and even adds a fancy new (optional) web interface which is responsive and customizable. On top of that, the communication between the monitoring server and the nodes it monitors has become more secure as NRPE has been ditched (it’s still available, just not prefered).<ref>[https://lowendbox.com/blog/server-monitoring-with-icinga-2-part-1-the-server-ubuntu-host] "Lowendbox" blog article about Icinga 2</ref>

Icinga is made of two parts - Icinga 2 and Icinga Web 2. The first one is the core of the software and the second is a web interface.

==Install Icinga 2 core==
Add Icinga's repository to the package management configuration.

<code>$ add-apt-repository ppa:formorer/icinga</code>

<code>$ apt update</code>

Install Icinga 2 package.

<code>$ apt install icinga2</code>

Check that Icinga is up and running

<code>$ service icinga2 status</code>

If it is not running, start it.

<code>$ service icinga2 start</code>

Make sure Icinga will start automatically on startup.

<code>$ systemctl enable icinga2.service</code>


==Install plugins==
===Nagios plugins===
To be able to check external services, Icinga needs monitoring plugins to know about them and to make sure they work properly. Available monitoring plugins are available on the [https://www.monitoring-plugins.org Monitoring Plugins Project website].

We install the main set of plugins that come from [https://www.nagios.org Nagios] monitoring solution. 

''Note that Icinga service runs as user and group called "Nagios" (for historical reasons).''

<code>$ apt install nagios-plugins</code>

===Vim and Nano configuration syntax highlighting===
Icinga provides packages to highlight its configuration files using Nano and Vim utilities. 

The package for Nano is included by default when installinIcinga2.

For Vim, do:

<pre>
$ apt install vim-icinga2 vim-addon-manager</code>
$ vim-addon-manager -w install icinga2
</pre>


==Install Apache web server==
Install Apache 2. Apache is a web server system that allows to access Icinga web interface.

<code>$ apt install apache2</code>

Apply a firewall rule to accept incoming tcp packets with destination port 80 (http). You may ignore this point if you have your own set of rules that you manage.

<pre>
$ iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
$ iptables-save
</pre>


==Install Icinga Web 2==
To install Icinga Web 2 package,add its repository to the package management system. 

For other Ubuntu versions than Xenial, just replace “xenial” below with the desired distribution's code name (see the [http://packages.icinga.org/ubuntu packages list]).
<pre>
$ wget -O - http://packages.icinga.org/icinga.key | apt-key add -
$ add-apt-repository 'deb http://packages.icinga.org/ubuntu icinga-xenial main'
$ apt update
</pre>

Install Icinga Web 2.

<code>$ apt install icingaweb2</code>


==Install and configure PostgreSQL databases==
Icinga needs two databases to work: one main to store monitoring information (DB IDO: Database Icinga Data Output) and one to store Icinga users and groups information for its web interface.
We will install both of them manually.

===Install PostgreSQL===
Install PostgreSQL database system.

<code>$ apt install postgresql</code>

===Install IDO module for PostgreSQL===
Install Icinga IDO module for PostgreSQL.
It installs files and directories to enable the export and storage of monitoring information into a database.
We will install the database manually in our tutorial.

<code>$ apt install icinga2-ido-pgsql</code>

A wizard will start.

Say "'''No'''" to enable the IDO module for PostgreSQL, we do it manually later.

The wizard proposes to create and configure the database with "dbconfig-common". Choose “'''No'''” because we will do it manually (see below).

===Create Icinga users database===
Create the users database for Icinga.

First go to the /tmp directory because that is the default unix socket location for PostgreSQL.

<code>$ cd /tmp</code>

Create a role (similar to a user) for the database. The database will require to login and we choose a password. You can choose a different role name ("icingaweb") and a different password ("icingawebpass") than what is given as an example below. ''Remember them for later!''

<code>$ sudo -u postgres psql -c "CREATE ROLE icingaweb WITH LOGIN PASSWORD 'icingawebpass'"</code>

Create the database (“icingawebdb”) and we assign its owner as being “icingaweb” (created earlier) with UTF8 encoding.

<code>$ sudo -u postgres createdb -O icingaweb -E UTF8 icingawebdb</code>

===Create IDO database===
Create the main database for Icinga.

Make sure you are in the /tmp directory (default unix socket location for PostgreSQL).

<code>$ cd /tmp</code>

Create a role (similar to a user) for the database. 

The database will require to login and we choose a password.

You can choose a different role name ("icingaido") and a different password ("icingaidopass") than what is given as an example below. 

''Remember them for later!''

<code>$ sudo -u postgres psql -c "CREATE ROLE icingaido WITH LOGIN PASSWORD 'icingaidopass'"</code>

Create the database (“icingaidodb”) and we assign its owner as being “icingaido” (created earlier) with UTF8 encoding.

<code>$ sudo -u postgres createdb -O icingaido -E UTF8 icingaidodb</code>

Edit the file ''/etc/icinga2/features-available/ido-mysql.conf'' and insert the values you have chosen for the IDO database.

<pre>
object IdoMysqlConnection "ido-mysql" {
  user = "icingaido",
  password = "icingaidopass",
  host = "localhost",
  database = "icingaidodb"
}
</pre>

===Configure databases authentication===
PostgreSQL handles authentication to databases from a file which states which users can connect to which database using certain methods.
Previously we have created a roles and databases. We must tell PostgreSQL how these databases can be accessed and by whom.

Edit the pg_hba.conf in ''/etc/postgresql/*/main/pg_hba.conf'' and add the roles and databases we defined earlier user with md5 authentication method.
'md5' means that the user needs to authenticate with a password to access the database.

<pre>
# TYPE  DATABASE         USER           ADDRESS               METHOD
#icinga
local   icingaidodb      icingaido                            md5
host    icingaidodb      icingaido      127.0.0.1/32          md5
host    icingaidodb      icingaido      ::1/128               md5

local   icingawebdb      icingaweb                            md5
host    icingawebdb      icingaweb      127.0.0.1/32          md5
host    icingawebdb      icingaweb      ::1/128               md5
</pre>

Restart PostgreSQL

<code>$ service postgresql restart</code>

===Import database schemas===
So far Icinga can access both databases, but they are empty (not a single table, index, function).

Import the respective schemas for each of them.

'''''Import the web database schema'''''

This will populate the web database with tables and indexes,...
The password we setup for this role will be asked.


<source lang="bash">
$ psql -U icingaweb -d icingawebdb < /usr/share/icingaweb2/etc/schema/pgsql.schema.sql
</source>

<pre>
Password for user icingaweb:
</pre>

A list of statements such as “CREATE TABLE”, “CREATE INDEX” appears.

'''''Import the IDO database schema'''''

This will populate the IDO database with tables, indexes,...

<pre>
$ psql -U icingaido -d icingaidodb < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
Password for user icingaido:
</pre>

A long list of statements such as “CREATE FUNCTION”, “CREATE TABLE”, “CREATE INDEX” appears.

==Enable Icinga features==
Enable Icinga IDO for PostgreSQL and 'command' modules and restart Icinga.

<pre>
$ icinga2 feature enable ido-pgsql command
$ service icinga2 restart
</pre>

Check that ido-pgsql and command modules are enabled.

<code>$ icinga2 feature list</code>

By default the command module file is owned by the group "nagios" with read/write permissions. Add Apache user ("www-data") to the group "nagios" to enable sending commands to Icinga 2 through the web interface.

<code>$ usermod -a -G nagios www-data</code>


==Set up the web interface==
Open a browser and go to http://[server_ip]/icingaweb2/setup.

1. First is the welcome page asking to insert a token.

To get a token, do in your terminal <code>$ icingacli setup token create</code> and insert it on the page. 

''Note: in case you need to see the token again, do <code>$ icingacli setup token show</code>.''

[[File:Icinga2 01 token.png|border|1000px|center]]


2. Choose the modules to install for Icinga Web 2.

For a normal usage, we suggest “Doc” and “Monitoring” modules.

[[File:Icinga2 02 modules.png|border|1000px|center]]


3. Icinga checks that all the requirements it needs are met. You may have some missing, in that case, you must fix them. We are not going to detail how to fix all of them but two that are likely to be missing.

[[File:Icinga2 03 modules incomplete.png|border|1000px|center]]


; '''“The PHP config ‘date.timezone’ is not defined”'''

:The page already guides you how to fix the Default TimeZone.

:Go to /etc/php/7.0/apache2/php.ini file, uncomment and set the line '''date.timezone =''' with your time zone. 

:For example <code>date.timezone = Europe/Tallinn</code> (see the [http://php.net/manual/en/timezones.php list of php time zones]).

; '''“The PHP module PDO-PostgreSQL is missing”'''

:Install the missing module.<code>$ apt install php-pgsql</code>

:In /etc/php/7.0/apache2/php.ini, add these lines to enable the extension/module
<pre>
extension=pdo_pgsql.so
extension=pgsql.so
</pre>


Restart the web server to apply the new configuration

<code>$ service apache2 restart</code>

Click the button “Refresh” at the bottom of the page to check the the requirements are now met.

[[File:Icinga2 04 modules complete.png|border|1000px|center]]


4. Choose “Database” for authentication unless you specifically want to authenticate using LDAP or another way.

[[File:Icinga2 05 authentication.png|border|1000px|center]]


5. Enter the credentials that we set up for users and groups database, and check that the configuration is correct by clicking on “Validate configuration”.

[[File:Icinga2 06 database resource.png|border|1000px|center]]


6. Use the default backend name “icingaweb2”.

[[File:Icinga2 07 authentication backend.png|border|1000px|center]]


7. Choose the credentials that will be asked when you will log into Icinga’s web interface to access the monitoring dashboard. 

'''Remember these credentials!''' (for point 16 below).

[[File:Icinga2 08 administration.png|border|1000px|center]]


8. Leave the default application and logging configuration unless you know what you are doing.

[[File:Icinga2 09 application configuration.png|border|1000px|center]]


9. Check that the configuration is correct and continue.

[[File:Icinga2 10 summary.png|border|1000px|center]]


10. You arrive to the configuration of the monitoring module.

[[File:Icinga2 11 monitoring welcome.png|border|1000px|center]]


11. Leave the defaults values for the monitoring backend ("IDO").

[[File:Icinga2 12 monitoring backend.png|border|1000px|center]]


12. Insert values you chose for the IDO database and check that the configuration is correct by clicking on “Validate configuration”. 

''The values are also in the file /etc/icinga2/features-enabled/ido-pgsql.conf.''

[[File:Icinga2 13 monitoring IDO resource.png|border|1000px|center]]


13. Leave the defaults values for the command transport.

[[File:Icinga2 14 command transport.png|border|1000px|center]]


14. Leave the defaults values for the monitoring security.

[[File:Icinga2 15 monitoring security.png|border|1000px|center]]


15. Check that the configuration is correct and finish.

[[File:Icinga2 16 monitoring summary.png|border|1000px|center]]


[[File:Icinga2 17 congratulations.png|border|1000px|center]]


16. Login to Icinga 2 using the credentials on point 7.

[[File:Icinga2 18 login.png|border|300px|center]]

==Summary from the author==
The installation is really difficult.

Although the official documentation is well written and gives detailed commands for different distributions and databases, it lacks crucial explanations to understand to the user what it is being done.

Here are a few problems we encountered:
# The installation documentation for [http://docs.icinga.org/icinga2/latest/doc/module/icinga2/chapter/getting-started Icinga 2] and [https://github.com/Icinga/icingaweb2/blob/master/doc/02-Installation.md Official Icinga Web 2] are not at the same place and are not consistent in their format and style.
# Icinga2 IDO package has a wizard to create and configure the IDO database (which non-experienced users will probably follow), but it is not absolutely clear in the documentation that if you follow the wizard, you do not need to create the IDO database manually afterwards.
# If you follow the wizard, the IDO database name and user will have default values. The user will only have to choose the password. But when the user arrives to web interface where he must enter the credentials of this database, there is no indication that he can find them in a configuration file.
# According to Icinga documentation, the users database can be created automatically by the web interface at the end of the procedure. But experience showed that it never worked (errors occur). The user is left with the documentation that does not explain how to create this users database manually (which we took a long time to figure out).
# In case of problem during installation, a user who is not familiar with his database system will have trouble debugging. The web interface does not provide useful solutions.

I would not recommend Icinga with the experience I have, unless you follow this guide.

==References==
{{reflist|30em}}