Install Icinga2 on Ubuntu 16.04
Author: Etienne Barrier
Last modified: 11.11.2016
Background
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 PostgreSQP (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.
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: Official Icinga documentation [1] [2]
For any comments, please write to etienne(dot}barrier{at]itcollege[dot)ee.
What is Icinga?
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.
$ add-apt-repository ppa:formorer/icinga
$ apt update
Install Icinga 2 package.
$ apt install icinga2
Check that Icinga is up and running
$ service icinga2 status
If it is not running, start it.
$ service icinga2 start
Make sure Icinga will start automatically on startup.
$ systemctl enable icinga2.service
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 Monitoring Plugins Project website. We install the main set of plugins that come from Nagios monitoring solution. Note that Icinga service runs as user and group called "Nagios" (for historical reasons).
$ apt install nagios-plugins
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:
$ apt install vim-icinga2 vim-addon-manager</code> $ vim-addon-manager -w install icinga2
Install Apache web server
Install Apache 2. Apache is a web server system that allows to access Icinga web interface.
$ apt install apache2
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.
$ iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT</code> $ iptables-save
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 packages list).
$ 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
Install Icinga Web 2.
$ apt install icingaweb2
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.
$ apt install postgresql
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.
$ apt install icinga2-ido-pgsql
A wizard will start. Say "No" to enable the IDO module for PostgreSQL, we do it manually later. The wizard proposes us to create and configure the database for us. 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.
$ cd /tmp
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!
$ sudo -u postgres psql -c "CREATE ROLE icingaweb WITH LOGIN PASSWORD 'icingawebpass'"
Create the database (“icingawebdb”) and we assign its owner as being “icingaweb” (created earlier) with UTF8 encoding.
$ sudo -u postgres createdb -O icingaweb -E UTF8 icingawebdb
Import the web database schema to the newly created database. This will populate the web database with tables and indexes,...
$ psql -U icingaweb -d icingawebdb < /usr/share/icingaweb2/etc/schema/pgsql.schema.sql
You should see a list of statements such as “CREATE TABLE”, “CREATE INDEX” ...
Create IDO database
Create the main database for Icinga. Make sure you are in the /tmp directory (default unix socket location for PostgreSQL).
$ cd /tmp
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!
$ sudo -u postgres psql -c "CREATE ROLE icingaido WITH LOGIN PASSWORD 'icingaidopass'"
Create the database (“icingaidodb”) and we assign its owner as being “icingaido” (created earlier) with UTF8 encoding.
$ sudo -u postgres createdb -O icingaido -E UTF8 icingaidodb
Import the IDO database schema to the newly created IDO database. This will populate the IDO database with tables, indexes,...
$ psql -U icingaido -d icingaidodb < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql
You should see a long list of statements such as “CREATE FUNCTION”, “CREATE TABLE”, “CREATE INDEX” ...
Edit the file /etc/icinga2/features-enabled/ido-mysql.conf and insert the values you have chosen for the IDO database.
object IdoMysqlConnection "ido-mysql" {
user = "icingaido",
password = "icingaidopass",
host = "localhost",
database = "icingaidodb"
}
Configuration 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.
# 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
Restart PostgreSQL
$ service postgresql restart
Enable Icinga features
Enable Icinga IDO for PostgreSQL and 'command' modules and restart Icinga.
$ icinga2 feature enable ido-pgsql $ service icinga2 restart
Check that ido-pgsql and command modules are enabled.
$ icinga2 feature list
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.
$ usermod -a -G nagios www-data
Set up the web interface
Open a browser and go to http://[server_ip]/icingaweb2/setup. You should see a welcome page asking to insert a token.
To get a token, do in your terminal $ icingacli setup token create and insert it on the page. Note: in case you need to see the token again, do $ icingacli setup token show.
Choose the modules to install for Icinga Web 2. For a normal usage, we suggest “Doc” and “Monitoring” modules.
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.
1. “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 date.timezone = Europe/Tallinn (see the list of php time zones).
2. “The PHP module PDO-PostgreSQL is missing”
Install the missing module.$ apt install php_pgsql
In /etc/php/7.0/apache2/php.ini, add these lines to enable the extension/module
extension=pdo_pgsql.so extension=pgsql.so
3. Restart the web server
$ service apache2 restart
Click the button “Refresh” at the bottom of the page to check the the requirements are now met.
Choose “Database” for authentication unless you specifically want to authenticate using LDAP or another way.
Enter the database credentials that we set up for users and groups, and check that the configuration is correct by clicking on “Validate configuration”.
Use the default backend name “icingaweb2”.
Choose the credentials that will be asked when you will log into Icinga’s web interface to access the monitoring dashboard. Remember these credentials!
Leave the default configuration unless you know what you are doing.
Check that your configuration so far is correct and continue.
You arrive to the configuration of the monitoring module.
Leave the defaults values for the backend.
Insert values you chose for the IDO database and check that the configuration is correct by clicking on “Validate configuration”. You can also see the values in the file /etc/icinga2/features-enabled/ido-pgsql.conf.
