How to install icinga2 and icingaweb2

Install Icinga 2 monitoring instance with web-interface. Beware, it is a lengthly article, but the whole process is quite simple, so you should get grasp of it after first execution.

Install host and network monitoring system

Install basic utilities.

$ sudo apt-get install curl gpg wget apt-transport-https

Import repository key.

$ curl -s https://packages.icinga.com/icinga.key | sudo apt-key add -

Configure icinga-stretch repository.

$ cat << EOF | sudo tee /etc/apt/sources.list.d/icinga-strech.list
deb http://packages.icinga.com/debian icinga-stretch main
deb-src http://packages.icinga.com/debian icinga-stretch main 
EOF

Update package index.

$ sudo apt-get update

Install icinga2 utility.

$ sudo apt-get install icinga2

Clear default configuration.

$ echo -n | sudo tee /etc/icinga2/conf.d/{apt.conf,groups.conf,hosts.conf,downtimes.conf,satellite.conf,services.conf,users.conf}

Install monitoring-plugins utility.

$ sudo apt-get install monitoring-plugins

Verify service status.

$ sudo systemctl status icinga2
● icinga2.service - Icinga host/service/network monitoring system
   Loaded: loaded (/lib/systemd/system/icinga2.service; enabled; vendor preset: enabled)
  Drop-In: /etc/systemd/system/icinga2.service.d
           └─limits.conf
   Active: active (running) since Sun 2017-10-22 11:49:01 CDT; 15min ago
 Main PID: 10131 (icinga2)
   CGroup: /system.slice/icinga2.service
           ├─10131 /usr/lib/x86_64-linux-gnu/icinga2/sbin/icinga2 --no-stack-rlimit daemon -e /var/log/
           └─10159 /usr/lib/x86_64-linux-gnu/icinga2/sbin/icinga2 --no-stack-rlimit daemon -e /var/log/

Oct 22 11:49:01 debian systemd[1]: Starting Icinga host/service/network monitoring system...
Oct 22 11:49:01 debian systemd[1]: Started Icinga host/service/network monitoring system.

Verify enabled features: checker, notification and mainlog.

$ sudo icinga2 feature list
Disabled features: api command compatlog debuglog gelf graphite influxdb livestatus opentsdb perfdata statusdata syslog
Enabled features: checker mainlog notification

Install web interface

Install PostgreSQL server.

$ sudo apt-get install postgresql

Create user and password for DB IDO (Database Icinga Data Output) module.

$ sudo -u postgres psql -c "CREATE ROLE icinga_ido WITH LOGIN PASSWORD 'icinga_ido_pwd'"
$ sudo -u postgres createdb -O icinga_ido -E UTF8 icinga_ido

Configure database authentication for created user.

$ cat << EOF | sudo tee -a /etc/postgresql/9.6/main/pg_hba.conf 
# icinga_ido 
host    icinga_ido      icinga_ido      127.0.0.1/32          md5
EOF

Reload PostrgeSQL server configuration.

$ sudo -u postgres psql -c "SELECT pg_reload_conf()"

Install icinga2-ido-pgsql, enable it but skip configuring database during installation.

$ sudo apt-get install icinga2-ido-pgsql

Populade DB IDO database.

$ psql --username=icinga_ido --password --host=localhost icinga_ido < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql 

Create DB IDO configuration file.

$ cat << EOF | sudo tee /etc/icinga2/features-enabled/ido-pgsql.conf 
/**
 * The db_ido_pgsql library implements IDO functionality
 * for PostgreSQL.
 */

library "db_ido_pgsql"

object IdoPgsqlConnection "ido-pgsql" {
  user = "icinga_ido",
  password = "icinga_ido_pwd",
  host = "localhost",
  database = "icinga_ido"
}
EOF

Ensure that ido-pgsql is enabled.

$ sudo icinga2 feature enable ido-pgsql

Display enabled features.

$ sudo icinga2 feature list
Disabled features: api command compatlog debuglog gelf graphite influxdb livestatus opentsdb perfdata statusdata syslog
Enabled features: checker ido-pgsql mainlog notification

Restart icinga2 service.

$ sudo systemctl restart icinga2

Display log file to confirm that database connection is established without any problems.

$ sudo tail /var/log/icinga2/icinga2.log
[2017-10-22 16:06:08 -0500] information/CheckerComponent: 'checker' started.
[2017-10-22 16:06:08 -0500] information/DbConnection: 'ido-pgsql' started.
[2017-10-22 16:06:08 -0500] information/NotificationComponent: 'notification' started.
[2017-10-22 16:06:08 -0500] information/ConfigItem: Activated all objects.
[2017-10-22 16:06:08 -0500] information/DbConnection: Resuming IDO connection: ido-pgsql
[2017-10-22 16:06:08 -0500] information/IdoPgsqlConnection: 'ido-pgsql' resumed.
[2017-10-22 16:06:08 -0500] information/IdoPgsqlConnection: pgSQL IDO instance id: 1 (schema version: '1.14.2')
[2017-10-22 16:06:09 -0500] information/IdoPgsqlConnection: Finished reconnecting to PostgreSQL IDO database in 1.41186 second(s).
[2017-10-22 16:06:18 -0500] information/WorkQueue: #5 (IdoPgsqlConnection, ido-pgsql) items: 0, rate: 4.26667/s (256/min 256/5min 256/15min);

Create database user and password for web interface.

$ sudo -u postgres psql -c "CREATE ROLE icinga_web WITH LOGIN PASSWORD 'icinga_web_pwd'"
$ sudo -u postgres createdb -O icinga_web -E UTF8 icinga_web

Configure database authentication for created user.

$ cat << EOF | sudo tee -a /etc/postgresql/9.6/main/pg_hba.conf
# icinga_web
host    icinga_web      icinga_web      127.0.0.1/32          md5
EOF

Reload PostrgeSQL server configuration.

$ sudo -u postgres psql -c "SELECT pg_reload_conf()"

Install nginx web server.

$ sudo apt-get install nginx-full

Install PHP Fast Process Manager, PostgreSQL module for PHP and GD module for PHP.

$ sudo apt-get install php-fpm php-pgsql php-gd

Specify default PHP timezone and reload PHP Fast Process Manager.

$ sudo sed -i -e "s/^;date.timezone =/date.timezone = Europe\/Warsaw/"  /etc/php/7.0/fpm/php.ini | grep date.timezone
$ sudo systemctl reload php7.0-fpm

Create directory to store SSL certificate.

$ sudo mkdir /etc/nginx/ssl

Create single domain SSL certificate.

$ sudo openssl req -subj "/commonName=icinga.example.org/" -x509 -nodes -days 730 -newkey rsa:2048 -keyout /etc/nginx/ssl/nginx.key -out /etc/nginx/ssl/nginx.crt

Create nginx site configuration.

$ cat << EOF | sudo tee /etc/nginx/sites-available/icinga
server {
  listen 443 ssl;

  ssl_certificate ssl/nginx.crt;
  ssl_certificate_key ssl/nginx.key;

  location ~ ^/index\.php(.*)\$ {
    # fastcgi_pass 127.0.0.1:9000;
    fastcgi_pass unix:/var/run/php/php7.0-fpm.sock;
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME /usr/share/icingaweb2/public/index.php;
    fastcgi_param ICINGAWEB_CONFIGDIR /etc/icingaweb2;
    fastcgi_param REMOTE_USER \$remote_user;
  }

  location ~ ^/(.+)? {
    rewrite ^/\$ /authentication/login;
    alias /usr/share/icingaweb2/public;
    index index.php;
    try_files \$1 \$uri \$uri/ /index.php\$is_args\$args;
  }
}
EOF

Disable default nginx site.

$ sudo unlink /etc/nginx/sites-enabled/default

Enable configured site.

$ sudo ln -s /etc/nginx/sites-available/icinga /etc/nginx/sites-enabled/icinga

Reload nginx configuration.

$ sudo systemctl reload nginx

Install Icinga Web 2 web-interface and a command-line utility.

$ sudo apt-get install icingaweb2 icingacli --install-recommends
[...]
Adding system-group for icingaweb2
Adding user `www-data' to group `icingaweb2' ...
Adding user www-data to group icingaweb2
Done.
[...]

Enable API feature

Create initial API configuration.

$ sudo icinga2 api setup
information/cli: Generating new CA.
information/base: Writing private key to '/var/lib/icinga2/ca/ca.key'.
information/base: Writing X509 certificate to '/var/lib/icinga2/ca/ca.crt'.
information/cli: Generating new CSR in '/etc/icinga2/pki/debian.csr'.
information/base: Writing private key to '/etc/icinga2/pki/debian.key'.
information/base: Writing certificate signing request to '/etc/icinga2/pki/debian.csr'.
information/cli: Signing CSR with CA and writing certificate to '/etc/icinga2/pki/debian.crt'.
information/pki: Writing certificate to file '/etc/icinga2/pki/debian.crt'.
information/cli: Copying CA certificate to '/etc/icinga2/pki/ca.crt'.
information/cli: Adding new ApiUser 'root' in '/etc/icinga2/conf.d/api-users.conf'.
information/cli: Enabling the 'api' feature.
Enabling feature api. Make sure to restart Icinga 2 for these changes to take effect.
Done.

Now restart your Icinga 2 daemon to finish the installation!

Inspect API user credentials. You can edit this file at this moment.

$ sudo cat /etc/icinga2/conf.d/api-users.conf
/**
 * The APIUser objects are used for authentication against the API.
 */
object ApiUser "root" {
  password = "f40b1360f3a35988"
  // client_cn = ""

  permissions = [ "*" ]
}

Restart Icinga 2.

$ sudo systemctl restart icinga2

Enable command feature

Display enabled features.

$ sudo icinga2 feature list
Disabled features: command compatlog debuglog gelf graphite influxdb livestatus opentsdb perfdata statusdata syslog
Enabled features: api checker ido-pgsql mainlog notification

Enable command feature.

$ sudo icinga2 feature enable command
Enabling feature command. Make sure to restart Icinga 2 for these changes to take effect.

Restart icinga2 service.

$ sudo systemctl restart icinga2

Verify that named pipe exists.

$ sudo ls -l /var/run/icinga2/cmd/icinga2.cmd
prw-rw---- 1 nagios www-data 0 Oct 24 17:38 /var/run/icinga2/cmd/icinga2.cmd

Install master setup

Execute wizard to start the master setup routine.

$ sudo icinga2 node wizard
Welcome to the Icinga 2 Setup Wizard!

We'll guide you through all required configuration details.



Please specify if this is a satellite setup ('n' installs a master setup) [Y/n]: n
Starting the Master setup routine...
Please specify the common name (CN) [monitoring]: icinga.example.org
Checking for existing certificates for common name 'icinga.example.org'...
Certificates not yet generated. Running 'api setup' now.
information/cli: Generating new CA.
critical/cli: CA files '/var/lib/icinga2/ca/ca.crt' and '/var/lib/icinga2/ca/ca.key' already exist.
warning/cli: Found CA, skipping and using the existing one.
information/cli: Generating new CSR in '/etc/icinga2/pki/icinga.example.org.csr'.
information/base: Writing private key to '/etc/icinga2/pki/icinga.example.org.key'.
information/base: Writing certificate signing request to '/etc/icinga2/pki/icinga.example.org.csr'.
information/cli: Signing CSR with CA and writing certificate to '/etc/icinga2/pki/icinga.example.org.crt'.
information/pki: Writing certificate to file '/etc/icinga2/pki/icinga.example.org.crt'.
information/cli: Copying CA certificate to '/etc/icinga2/pki/ca.crt'.
information/cli: Created backup file '/etc/icinga2/pki/ca.crt.orig'.
Generating master configuration for Icinga 2.
information/cli: API user config file '/etc/icinga2/conf.d/api-users.conf' already exists, not creating config file.
'api' feature already enabled.
information/cli: Dumping config items to file '/etc/icinga2/zones.conf'.
information/cli: Created backup file '/etc/icinga2/zones.conf.orig'.
Please specify the API bind host/port (optional):
Bind Host []: 
Bind Port []: 
information/cli: Created backup file '/etc/icinga2/features-available/api.conf.orig'.
warning/cli: CN 'icinga.example.org' does not match the default FQDN 'monitoring'. Requires update for NodeName constant in constants.conf!
information/cli: Updating constants.conf.
information/cli: Created backup file '/etc/icinga2/constants.conf.orig'.
information/cli: Updating constants file '/etc/icinga2/constants.conf'.
information/cli: Updating constants file '/etc/icinga2/constants.conf'.
information/cli: Updating constants file '/etc/icinga2/constants.conf'.
Done.

Now restart your Icinga 2 daemon to finish the installation!

Restart Icinga 2.

$ sudo systemctl restart icinga2

Configure Icinga Web 2 web-interface

$ sudo icingacli setup token create
The newly generated setup token is: db8d4cedd077c771

Continue setup process using web-browser.

https://icinga.example.org/setup

Use generated setup tocket to start configuration process.

Enable and configure monitoring plugin.

Make sure that requirements are met.

Use database authentication backend.

Configure authentication backend.

Define name for authentication backend

Define administrative account.

Define essential logging settings.

Initiate configuration of the monitoring backend.

Use IDO (Icinga Data Output) as basckend type.

Configure IDO database.

Use API or named pipe to communicate with the monitoring instance.

Define protected variables.

Installation is complete

Log in to access web-interface.

Done.

Additional information

Icinga 2 Documentation

About Milosz Galazka

Milosz is a Linux Foundation Certified Engineer working for a successful Polish company as a system administrator and a long time supporter of Free Software Foundation and Debian operating system. He is also open for new opportunities and challenges.