linux, server

Installing Icinga2 & IcingaWeb2 on Ubuntu 16.04.3 LTS

Note:
A clean and up2date installation of Ubuntu Server 16.04.3 LTS is expected in this post.
As I'm using the fish shell on all of my machines, there might be commands in this post which need to be translated to bash/zsh syntax!
Also, please note that most of this post is going to be executed in a root shell so execute your commands with caution!
I personally use sudo -i for this but you can also go with sudo su or su if you like.

Process

Preparations

Drop to a root shell: sudo -i.

Optional: Enable mirror autoselect.
To speed up package downloads we can add the following to our sources.list and apt will automatically find the fastest mirror for us. The following command automates this:

sed -i.bak
'
deb mirror://mirrors.ubuntu.com/mirrors.txt xenial main restricted universe multiverse
deb mirror://mirrors.ubuntu.com/mirrors.txt xenial-updates main restricted universe multiverse
deb mirror://mirrors.ubuntu.com/mirrors.txt xenial-backports main restricted universe multiverse
deb mirror://mirrors.ubuntu.com/mirrors.txt xenial-security main restricted universe multiverse
'
> /etc/apt/sources.list

And update the repository cache using apt update.

Install Apache2

To install Apache2 simply install the package with apt:
apt install apache2 -y

Remove the default Apache2 Startpage:
rm /var/www/html/index.html

As a security measure disable Directory Listings:
sed -i "s/Options Indexes FollowSymLinks/Options FollowSymLinks/" /etc/apache2/apache2.conf

Finally set Apache2 to run at startup and start the service:
systemctl enable apache2
systemctl start apache2

Optional: Allow Apache2 through UFW
In case you're using UFW you may need to create an allow rule like this:
ufw allow in "Apache Full"

Install MariaDB

For installing the database we can either use MariaDB or MySQL, whichever package is available will fit as their the same to set up. But as most MySQL admins are moving to MariaDB (including myself), MySQL might be gone soon.

I'll use MariaDB if possible:
apt install mariadb-client mariadb-server -y

Set MariaDB to run at startup and start the service:
systemctl enable mysql
systemctl start mysql

Secure the mysql database using the built-in script:
mysql_secure_installation

  • Enter current password for root (enter for none): Enter
  • Set root password? [Y/n]: Y
  • New password: <your-password>
  • Re-enter new password: <your-password>
  • Remove anonymous users? [Y/n]: Y
  • Disallow root login remotely? [Y/n]: Y
  • Remove test database and access to it? [Y/n]: Y
  • Reload privilege tables now? [Y/n]: Y

Finally log in to the database and set the same password for the authentication plugin:
mysql -u root -p

UPDATE mysql.user SET authentication_string=PASSWORD('<your-password>'), plugin='mysql_native_password' WHERE user='root';
FLUSH PRIVILEGES;
EXIT;

Install PHP7

To get PHP7 up and running a few more packages are needed. There are almost a dozen of PHP7 modules which Icinga2 and IcingaWeb2 need to work. Of course they're all available in the Ubuntu repositories:
apt install php7.0 libapache2-mod-php7.0 php7.0-gd php7.0-intl php7.0-xml php7.0-ldap php7.0-mysql php7.0-pgsql php-curl php-imagick zip unzip -y

After these are installed we need to set the time zone the server is operating in.
For example <timezone> could be "Europe\/Berlin" in the following command:
Note the escaping backslash prior the forwardslash!
sed -i "s/;date.timezone =/date.timezone = <timezone>/" /etc/php/7.0/apache2/php.ini
To verify that it worked we can use the following command:
cat /etc/php/7.0/apache2/php.ini | grep timezone

Finally restart the Apache2 service: systemctl restart apache2

Install Composer

For now we need to exit the root shell and use our regular user account, therefore we either create a new pane (assuming we're in a tmux session) by hitting <prefix> + c or simply exit our current root shell.
Note: The hash in the following script will change in the future, if you get a hash mismatch error, go to getcomposer.org and download the current version of the 'composer-setup.php' file.

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"`
php -r "if (hash_file('SHA384', 'composer-setup.php') === '669656bab3166a7aff8a7506b8cb2d1c292f042046c5a994c43155c0be6190fa0355160742ab2e1c88d40d5be660b410') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink('composer-setup.php');"
sudo mv ~/composer.phar /usr/local/bin/composer
composer require zendframework/zend-db

Recap:
The first line downloads the composer setup into the current directory.
The second verifies its SHA384 hash to be sure the file is not corrupted or modified. If so it deletes it and exits.
The third line runs the Composer's setup itself.
In the fourth line the setup will be removed.
Five: move the composer to the users bin directory.
Lastly let composer install the dependency "zend-db".

Install Icinga2 & Plugins

Now that Composer is installed under our regular user account we can drop back into our root shell to finalize the installation: sudo -i.

To install Icinga2 we need to add their PGP publickey to our apt sources keyring like so:
wget -O - http://packages.icinga.org/icinga.key | apt-key add -
Then add their repository to our sources.list using:
add-apt-repository 'deb http://packages.icinga.org/ubuntu icinga-xenial main'

Finally update our apt cache and install the packages:
apt update
apt install icinga2 nagios-plugins -y

After the service is installed set it to run at startup and start it:
systemctl enable icinga2
systemctl start icinga2

To make Icinga2 work with our MariaDB we need to install and set up a feature called 'icinga2-ido-mysql':
apt install icinga2-ido-mysql -y
As we are going to setup our instance manually to have full control you will need to select No twice when prompted by the installer.

Now its time to set up the databases for Icinga2, IcingaWeb2 and the Director module. To do so, log into the MariaDB/MySQL database as root (mysql -u root -p) and execute the following queries:

CREATE DATABASE icinga;

GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';

CREATE DATABASE icingaweb2;

CREATE DATABASE director CHARACTER SET 'utf8';
GRANT ALL ON director.* TO director@localhost IDENTIFIED BY '<pass>';

FLUSH PRIVILEGES;
EXIT;

Recap:
The first line creates the Icinga2 database we're going to call 'icinga'.
The second query grants almost all privileges (rights) to the user 'icinga' if the connection is coming from localhost (meaning any other client is denied) and provides the password 'icinga'.
Next we're creating the database for IcingaWeb2 and the Director.
The Director's requirements are somewhat different as it needs the UTF8 charset to be set for the database.
Like for Icinga2 we're going to create a user called 'director' who needs to identify from localhost with a password but in this case he's getting full control over the database.
Finally flush the privilege cache and quit.

As the databases are created it's time to give them a form. To import the Icinga2 schema into the database run the following command and enter your MariaDB root password when asked:
mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql

Update the configuration file for the IcingaWeb2 feature so it can connect to the database:
nano /etc/icinga2/features-available/ido-mysql.conf
Change the existing 'ido-mysql' object to look like this:

user = "icinga"
password = "icinga"
host = "localhost"
database = "icinga"

Install IcingaWeb2 & Director

Now that the IDO feature is configured, enable it along with the command feature:
icinga2 feature enable ido-mysql command

Restart Icinga2 for changes to take effect:
systemctl restart icinga2

Create a group and a user for the Icinga2 command feature and add it to the group www-data:
groupadd icingacmd
usermod -a -G icingacmd www-data

Now it's time to install the packages for IcingaWeb2:
apt install icingaweb2 icingaweb2-module-monitoring icingaweb2-module-doc icingacli -y

Let IcingaWeb2 configure Apache2 for us:
icingacli setup config webserver apache --document-root /usr/share/icingaweb2/public

Restart Apache2:
systemctl restart apache2

Import the schema for IcingaWeb2 into it's database:
mysql -u root -p icingaweb2 < /usr/share/icingaweb2/etc/schema/mysql.schema.sql

If you don't want Icinga2 to log to the Syslog but to it's own log file, prepare it like this:
mkdir /var/log/icingaweb2
touch /var/log/icingaweb2/icingaweb2.log
chown www-data:www-data /var/log/icingaweb2/ -R

The Director can be installed and updated (!) from GitHub anytime if stored in IcingaWeb2's modules directory:
git clone https://github.com/Icinga/icingaweb2-module-director.git /usr/share/icingaweb2/modules/director

Finally create a setup token for the IcingaWeb2 GUI installation.
icingacli setup token create

Configure IcingaWeb2

Open the IcingaWeb2 WebUI by browsing to:
http://<IP>/icingaweb2/setup
and run the setup using this little walkthrough:

  • Insert Token

3x Next

  • Select Database

Next

  • Resource Name*: icingaweb_db
  • Database Type*: MySQL
  • Host*: localhost
  • Database Name*: icingaweb2
  • Username*: root
  • Password*: <MariaDB-root-password>

Validate Configuration - Next

  • icingaweb2

Next

  • Username: <admin>
  • Password: <pass>
  • Repeat password: <pass>

Next

  • Show Stacktraces: Checked
  • User Preference Storage Type*: Database
  • Logging Type*: File
  • Logging Level*: Error
  • File path*: /var/log/icingaweb2/icingaweb2.log

3 x Next

  • Backend Name*: icinga
  • Backend Type*: IDO

Next

  • Resource Name*: icinga_ido
  • Database Type*: MySQL
  • Host*: localhost
  • Database Name*: icinga
  • Username*: icinga
  • Password*: icinga

Validate Configuration - Next

  • Transport Name*: icinga2
  • Transport Type*: Local Command File
  • Command File*: /var/run/icinga2/cmd/icinga2.cmd

Next

  • Protected Custom Variables: *pw*,*pass*,community

Next

Finish

Thats it for now. Back to the shell.
Enable the API feature of Icinga2 for the director:
icinga2 feature enable api
Restart Icinga2:
systemctl restart icinga2
Let Icinga2 create certificates and set up its own API:
icinga2 api setup
Restart Icinga2 again:
systemctl restart icinga2
Run the node wizard to initalize Icinga2 as a server:
icinga2 node wizard

  • n
  • Enter
  • Enter
  • Enter
  • Enter

Restart Icinga2 yet another time:
systemctl restart icinga2

Configure Director

At this stage, Icinga2 and IcingaWeb2 are up and running. But to get the Director working we need to create an API user and initialize the 'director' database as a resource within Icinga2.

To create the API user edit the configuration file for api users:
nano /etc/icinga2/conf.d/api-users.conf
and create a new ApiUser object like this:

object ApiUser "director" {
  password = "<pass>"
  permissions = [ "*" ]
}

To add the database as a resource in Icinga2 go to the following path in the IcingaWeb2 UI:
Configuration -> Application -> Resources -> Create a New Resource

  • Resource Type*: SQL Database
  • Resource Name*: director
  • Database Type*: MySQL
  • Host*: localhost
  • Database Name*: director
  • Username*: director
  • Password*: <pass>
  • Character Set: utf8

Validate Configuration - Save Changes

As the Director is set up now, enable it:
Configuration -> Modules -> director -> State: enable
and click on the 'Icinga Director' button in the left navigation bar.

Now we're going to point the Director to the newly created resource:

  • DB Resource*: director

Create database schema

  • Endpoint Name*: this is usually the hostname [1]
  • Icinga Host: localhost
  • API user*: director
  • Password*: <pass>

WIP (forgotten)


Go to top

  1. if the hostname doesn't work you need to check the certificates name in /etc/icinga2/pki/*.crt ↩︎