Icinga 2 Server Monitoring Setup on Ubuntu (Icinga DB, Icinga Web)

This article is a localized edition of the Japanese original. Read the Japanese original

Icinga 2 is open-source monitoring software that checks the state of servers and services at regular intervals and alerts you to problems. It can use Nagios-compatible monitoring plugins as they are. To view the state in a web interface (Icinga Web), you combine it with Icinga DB, which stores monitoring results, and the Icinga Web application.

This article installs Icinga 2, Icinga DB and Icinga Web together on one Ubuntu monitoring server, and goes as far as monitoring another web server's availability (ping) and HTTP response. The commands follow the official Icinga documentation as of November 2026.

Overall architecture

Do all of the work as root (sudo -i).

Step 1: Add the Icinga package repository

The official Icinga instructions install packages from the repository that Icinga provides.

apt update
apt -y install apt-transport-https wget

wget -O icinga-archive-keyring.deb "https://packages.icinga.com/icinga-archive-keyring_latest+ubuntu$(
 . /etc/os-release; echo "$VERSION_ID"
).deb"
apt install ./icinga-archive-keyring.deb

cat >/etc/apt/sources.list.d/icinga.sources <<EOF
Types: deb deb-src
URIs: https://packages.icinga.com/ubuntu/
Suites: icinga-$(. /etc/os-release; echo "$VERSION_CODENAME")
Components: main
Signed-By: /usr/share/keyrings/icinga-archive-keyring.gpg
EOF

apt update

Step 2: Install Icinga 2 and the monitoring plugins

apt install icinga2 monitoring-plugins

# Validate the configuration files (make sure there are no errors)
icinga2 daemon -C

systemctl status icinga2

icinga2 daemon -C only loads the configuration files and checks them for errors. Run it every time you change the configuration, before applying the change.

Next, enable the REST API. It is used when you trigger actions such as "Check now" from Icinga DB Web.

icinga2 api setup

The official documentation recommends adding the following line to ApiListener in /etc/icinga2/features-enabled/api.conf.

object ApiListener "api" {
  enforce_filter_expression_permission = true
}

Add this one line inside the object ApiListener "api" { ... } block that already exists in the file (do not create a new block). After editing, restart Icinga 2.

icinga2 daemon -C && systemctl restart icinga2

Step 3: Define the hosts and services to monitor

The Icinga 2 configuration lives in /etc/icinga2/, and right after installation conf.d/ contains examples.

services.conf already contains rules like these:

• Assign a ping4 check to every host that has an address
• Assign an ssh check to hosts whose vars.os is "Linux"
• Assign an http check for each entry written in the host's vars.http_vhosts

Using these rules, you can start monitoring just by adding a host. Create a new file, /etc/icinga2/conf.d/web01.conf.

object Host "web01" {
  import "generic-host"

  address = "192.0.2.10"   // IP address of the server to monitor

  vars.http_vhosts["https"] = {
    http_vhost = "www.example.com"
    http_ssl = true
    http_uri = "/"
  }
}

Importing generic-host makes the host's availability check use hostalive (ping). From the contents of vars.http_vhosts, an HTTP check named https is created. If you add vars.os = "Linux", an SSH port check is assigned as well (when the monitoring server can connect to SSH).

Validate the configuration and apply it.

icinga2 daemon -C && systemctl reload icinga2

You can confirm the assigned services with the following command.

icinga2 object list --type Service --name 'web01*'

What you can monitor this way is what the monitoring server can see from the outside (ping, HTTP, ports). To check free disk space or load inside the monitored server, you need to install Icinga 2 on that server too and connect it as an agent (explained in the "Distributed Monitoring" chapter of the official documentation).

Step 4: Install Icinga DB and Redis

To view monitoring state in Icinga Web, set up Icinga DB. First install Redis and enable the icingadb feature of Icinga 2.

apt install icingadb-redis
systemctl enable --now icingadb-redis

icinga2 feature enable icingadb
systemctl restart icinga2

Next, prepare Icinga DB itself and the MySQL database it stores data in (if MySQL is not installed yet, install it with apt install mysql-server or similar).

apt install icingadb
mysql -u root -p

CREATE DATABASE icingadb;
CREATE USER 'icingadb'@'localhost' IDENTIFIED BY 'CHANGEME';
GRANT ALL ON icingadb.* TO 'icingadb'@'localhost';

Replace CHANGEME with a password that is hard to guess. Then import the schema.

mysql -u root -p icingadb < /usr/share/icingadb/schema/mysql/schema.sql

In the database: section of /etc/icingadb/config.yml, enter the name, user and password of the database you created, and start Icinga DB.

systemctl enable --now icingadb
systemctl status icingadb

Step 5: Install Icinga Web

Icinga Web is a PHP web application (PHP 8.2 or later is required). On Ubuntu 24.04 you can run it with the standard PHP 8.3 and Apache.

apt install apache2 libapache2-mod-php icingaweb2 icingadb-web

Create a database to store Icinga Web's own configuration (users and so on).

CREATE DATABASE icingaweb;
CREATE USER 'icingaweb'@'localhost' IDENTIFIED BY 'CHANGEME';
GRANT ALL ON icingaweb.* TO 'icingaweb'@'localhost';

mysql -u icingaweb -p icingaweb < /usr/share/icingaweb2/schema/mysql.schema.sql

If you use Nginx, save the configuration printed by the following command into the Nginx configuration directory.

icingacli setup config webserver nginx --document-root /usr/share/icingaweb2/public

Add an API user that Icinga DB Web uses to send actions to Icinga 2 in /etc/icinga2/conf.d/api-users.conf.

object ApiUser "icingadb-web" {
  password = "CHANGEME"
  permissions = [ "actions/*", "objects/modify/*", "objects/query/*", "status/query" ]
}

icinga2 daemon -C && systemctl reload icinga2

Step 6: Finish with the setup wizard

Create a token for entering the wizard.

icingacli setup token create
# To show the token you created again
icingacli setup token show

Open http://monitoring-server-address/icingaweb2/setup in a browser, enter the token and proceed. In the wizard, you mainly enter the following information.

When it is done, log in as the administrator and confirm that the web01 host and the ping4 and https services are shown.

The setting that lets Icinga DB Web send actions to Icinga 2 (re-checks, acknowledgements, scheduling downtime and so on) is registered, as the official Icinga DB Web documentation describes, under "Configuration → Modules → icingadb → Command Transports" in the interface, using the API user from Step 5 (icingadb-web). If you registered it in the wizard, this is not needed.

Operational notes

• Serve the monitoring server's web interface over HTTPS and restrict which IP addresses can reach it. Replace every placeholder password such as CHANGEME.
• After changing the configuration, validate it with icinga2 daemon -C and then apply it with systemctl reload icinga2. If you restart with a configuration that fails validation, Icinga 2 will not start.
• To send alerts, configure how notifications are delivered (email and so on) and which users receive them (there are examples in conf.d/users.conf and conf.d/notifications.conf). To notify by email, make sure the monitoring server can send mail.

To compare with other monitoring software, see also Installing and configuring Nagios and Monitoring servers with Zabbix.

Summary

1. Add the official Icinga repository and install icinga2 and monitoring-plugins.
2. Enable the API with icinga2 api setup.
3. Define hosts in conf.d/ and get services assigned by the existing rules, for example with vars.http_vhosts. Validate the configuration with icinga2 daemon -C before applying it.
4. Install Redis, Icinga DB and Icinga Web (Icinga DB Web) and prepare the databases.
5. Create a token with icingacli setup token create and finish in the wizard at /icingaweb2/setup.

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)