Icinga 2: Web UI (Part 2)

7 min readFeb 19, 2018

Following on from Part 1 of this series, this guide will cover what you need to know and do in order to have a running Icinga Web 2 installation in place for your monitoring solution. Part 3 is available here.

A user interface is well-designed when the program behaves exactly how the user thought it would.
— Joel Spolsky

The Icinga Web 2 UI is great. It is a vast improvement over the Icinga Web 1 UI. The UI is simple to use (my subjective view) and gets down to the basics. Its important to note that all the configuration is done using the Icinga 2 configuration (more on this in later posts) which leaves the Web UI to be a simple way to view the current state of your infrastructure that you are monitoring.

That being said, you are able to pause notifications and create acknowledgments for incidents and even schedule down time when you are planning to take a server down for maintenance.

Since we want some level of visualisation into our monitoring (rather than using the Icinga 2 API) we are going to install Icinga Web 2.

Software collections repository

Icinga Web 2 makes use of a newer PHP version. I have found the best place to get this dependency is from the CentOS Linux Software Collections. This repository is easy to install.

$ yum install centos-release-scl

PostgreSQL

Icinga Web 2 needs a database. It uses this database to store things such as user information. There are a few options when it comes to which database one can use with Icinga Web 2. Personally, I have had lost of experience with PostgreSQL over the years on Rails and Spring projects. So naturally I start to select PostgreSQL as my database of choice whenever I can.

So for this setup, we are going to use PostgreSQL. Should you wish to choose another database. Please have a look in the Icinga 2 and Icinga Web 2 documentation.

The first step is probably the most complicated one in the whole PostgreSQL install. We need to disable the installation from the base CentOS repositories. We want to run a newer version than those repositories contain.

We must edit the CentOS-base.repo file as follows:

$ vi /etc/yum.repos.d/CentOS-Base.repo

Next, add exclude=postgresql* to the [base] and [updates] sections.

Now that we have disabled the installation and updates from the base repo, we can add the PGDG repository to allow us to install a version of PostgreSQL.

$ yum install https://download.postgresql.org/pub/repos/yum/9.6/redhat/rhel-7-x86_64/pgdg-redhat96-9.6-3.noarch.rpm

Continue with the PostgreSQL install as we normally would:

$ yum install postgresql96-server
$ /usr/pgsql-9.6/bin/postgresql96-setup initdb
$ systemctl enable postgresql-9.6
$ systemctl start postgresql-9.6

Now we have PostgreSQL installed and ready to be used. Icinga Web 2 makes use of IDO modules to interact with the databases. There are different ones available for the different databases. In our case we will be using the PostgreSQL one

$ yum install icinga2-ido-pgsql

PostgreSQL needs to be configured for use by Icinga 2 and Icinga Web 2. We will create a user role for Icinga and set a password. We will also create two databases. One for Icinga 2 and one for Icinga Web 2.

sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'"
sudo -u postgres createdb -O icinga -E UTF8 icinga
sudo -u postgres createdb -O icinga -E UTF8 icingaweb2

We have used a simple password. You are more than welcome (and encouraged) to change it to a better password.

Icinga will look for an environment variable when attempting to use a password to connect to the database. Please update the following command if you have changed the password above.

export PGPASSWORD=icinga

Those of you familiar with PostgreSQL will know that we need to adjust the permissions to allow it to be accessed by other applications. It is worth noting that the permissions can be adjusted for remote access, however in our case we only need access for applications running on the same server. To edit the permissions we will make changes to pg_hba.conf

$ vi /var/lib/pgsql/9.6/data/pg_hba.conf

Adjust the configuration to match the following code snippet

# icinga
local   icinga      icinga                            md5
host    icinga      icinga      127.0.0.1/32          md5
host    icinga      icinga      ::1/128               md5# icinga
local   icingaweb2      icinga                            md5
host    icingaweb2      icinga      127.0.0.1/32          md5
host    icingaweb2      icinga      ::1/128               md5# "local" is for Unix domain socket connections only
local   all         all                               ident
# IPv4 local connections:
host    all         all         127.0.0.1/32          ident
# IPv6 local connections:
host    all         all         ::1/128               ident

Take note of the addition of the user with MD5 authentication to both the icinga and icingaweb2 databases in addition to the change from peer to ident for the local access rule.

To enable to config we just need to restart PostgreSQL

$ systemctl restart postgresql-9.6

As with all databases we need the correct schema. For this we will now load the Icinga 2 IDO schema. We will also enable the Icinga 2 IDO in order for Icinga 2 to be aware that we are using a PostgreSQL database.

$ sudo su - postgres
$ psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql$ exit$ icinga2 feature enable ido-pgsql
$ systemctl restart icinga2

Webserver

Icinga Web 2 is a PHP based application and will need to be hosted and served using a webserver. In our case we will use Apache. We can install that now. We will also start and enable the PHP 7 FPM modules needed by Icinga Web 2.

$ yum install httpd
$ systemctl enable httpd
$ systemctl start httpd$ yum install rh-php71-php-fpm
$ systemctl start rh-php71-php-fpm.service
$ systemctl enable rh-php71-php-fpm.service

For Apache to interact with the PostgreSQL database we must install the module as follows:

$ yum install php-pgsql

Firewall

To allow external access to our Icinga Web 2 instance, we will need to allow access through the firewall. The default port is 80.

I enjoy using firewalld when adjusting firewall rules. It is simply a wrapper for iptables so please feel free to use what ever you are most comfortable with.

If firewalld is not installed, do so now

$ yum install firewalld
$ systemctl enable firewalld
$ systemctl start firewalld

We can now add the rule to allow traffic over port 80.

$ firewall-cmd --add-service=http
$ firewall-cmd --permanent --add-service=http

REST API

Icinga Web 2 interacts with Icinga 2 using its Rest API. For this to work, we need to enable the API within Icinga 2. The following command will create a user root with the default generated password. We will change this password later.

$ icinga2 api setup

After the above completes, we must create another user for icingaweb2 to access the API. For this we will edit Icinga 2’s api-users.conf file.

$ vi /etc/icinga2/conf.d/api-users.conf

Add the following snippet to the file. It will add the user. Please adjust this password as needed.

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

Finish this section off with a quick restart of Icinga 2.

$ systemctl restart icinga2

Icinga Web 2: Installation

At long last, we can now install Icinga Web 2 itself. As we did with Icinga 2, we will make use of the yum package manager to install the package. Firstly, we must add the correct repository. This is the same repo that was installed previously, so in most cases you should be able to skip this command.

$ yum install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm

Now we can install the package. Along with the Icinga Web 2 package we will also install the Icinga 2 CLI.

$ yum install icingaweb2 icingacli

Icinga Web 2: Setup

Most of the Icinga 2 setup is done via its web interface. This occurs when you access the url from your browser. It will be available on a fresh installation. However, before we can do this we need to configure Apache to serve the Icinga Web 2 application correctly. There may be different approaches to this depending on your setup, but in our case the following works well:

$ icingacli setup config webserver apache --document-root /usr/share/icingaweb2/public
$ systemctl restart httpd

For Apache to access the files the icinga setup has created, we need to create the correct user group and add the apache user to that group.

$ groupadd -r icingaweb2;
$ usermod -a -G icingaweb2 apache;

If the group already exists, then you can move onto changing the apache users group.

At this point it is a great time to change the default PHP timezone. This is optional but having your application running in the correct timezone is always nice. We will edit the php.ini file to accomplish this.

$ vi /etc/php.ini

Locate the line ;date.timezone = and edit it to look as follows or which ever timezone you require. You can find a list of supported timezones here.

date.timezone = Africa/Johannesburg

Save the file.

In order to continue the setup, we will need to generate a token to allow access to the CLI for Icinga Web 2.

$ icingacli setup token create

This will display a token. We will use this token when setting up Icinga Web 2 via its Web application. If you do forget this token, it can be shown using the following command:

icingacli setup token show

To access the web ui wizard, head over to the following url in your browser. Please insert your servers hostname or public IP address.

Important: Please make sure that if you are running the instance on AWS EC2, that you adjust your security group to allow access to port 80

http://<ip-address>/icingaweb2/setup

You should be presented with a screen that looks similar to the following screenshot:

Final thoughts

This concludes Part 2 of the setup. We have successfully installed PostgreSQL, created the databases and users need, installed the apache webserver to serve the Icinga Web 2 application and adjusted the firewall to allow users to access the web ui.

Subsequent posts will guide you through the wizard. After that we will turn our attention to configuring Icinga 2 and setting up our monitoring configuration.

Part 3 is available here.

References

If you are looking for more information on the PostgreSQL setup, please consult:

https://wiki.postgresql.org/wiki/YUM_Installation

If you get stuck with any of the above steps, the Icinga 2 and Icinga Web 2 documentation is extremely useful. It can be found here:

https://www.icinga.com/docs