Install Icinga2 Monitoring on Ubuntu 24.04 / Debian 13 [Guide]

Icinga2 is an open-source monitoring system that checks the availability of network resources, notifies users of outages, and generates performance data for reporting. Originally forked from Nagios, Icinga2 was rebuilt from the ground up with a modern architecture, distributed monitoring support, and a REST API. It monitors hosts and services across your entire infrastructure and alerts you when things go wrong.

This guide walks through a complete Icinga2 monitoring stack installation on Ubuntu 24.04 and Debian 13 – covering Icinga2 core, IcingaDB with MariaDB, Icinga Web, the setup wizard, host monitoring, notifications, firewall rules, and the optional Icinga Director module for web-based configuration management.

Prerequisites

Before starting the installation, confirm the following requirements are in place:

A server running Ubuntu 24.04 LTS or Debian 13 with at least 2 GB RAM and 2 CPU cores
Root or sudo access to the server
A fully qualified domain name (FQDN) pointing to the server – for example monitor.example.com
Ports 80/443 (HTTP/HTTPS), 5665 (Icinga2 API) open on your firewall
Internet access for downloading packages from the Icinga repository

All commands in this guide should run as root. Switch to a root shell before proceeding:

sudo -i

Step 1: Install Icinga2 from Official Repository

The Icinga project maintains official package repositories for Ubuntu and Debian. Using these ensures you get the latest stable release (Icinga2 2.15.x at time of writing) with proper dependency management.

Start by installing the required transport packages and the Icinga archive keyring.

On Ubuntu 24.04:

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

wget -O /tmp/icinga-archive-keyring.deb "https://packages.icinga.com/icinga-archive-keyring_latest+ubuntu24.04.deb"
apt install -y /tmp/icinga-archive-keyring.deb

Add the Icinga repository to your sources list:

. /etc/os-release
if [ ! -z ${UBUNTU_CODENAME+x} ]; then
  DIST="${UBUNTU_CODENAME}"
else
  DIST="$(lsb_release -c| awk '{print $2}')"
fi

echo "deb [signed-by=/usr/share/keyrings/icinga-archive-keyring.gpg] https://packages.icinga.com/ubuntu icinga-${DIST} main" > /etc/apt/sources.list.d/${DIST}-icinga.list
echo "deb-src [signed-by=/usr/share/keyrings/icinga-archive-keyring.gpg] https://packages.icinga.com/ubuntu icinga-${DIST} main" >> /etc/apt/sources.list.d/${DIST}-icinga.list

On Debian 13:

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

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

Add the repository:

. /etc/os-release
DIST=$(lsb_release -c | awk '{print $2}')

echo "deb [signed-by=/usr/share/keyrings/icinga-archive-keyring.gpg] https://packages.icinga.com/debian icinga-${DIST} main" > /etc/apt/sources.list.d/${DIST}-icinga.list
echo "deb-src [signed-by=/usr/share/keyrings/icinga-archive-keyring.gpg] https://packages.icinga.com/debian icinga-${DIST} main" >> /etc/apt/sources.list.d/${DIST}-icinga.list

Now install Icinga2 and the monitoring plugins on both Ubuntu and Debian:

apt update
apt -y install icinga2 monitoring-plugins

Enable and start the Icinga2 service:

systemctl enable --now icinga2

Confirm that Icinga2 is running:

systemctl status icinga2

The output should show the service as active (running):

● icinga2.service - Icinga host/service/network monitoring system
     Loaded: loaded (/usr/lib/systemd/system/icinga2.service; enabled; preset: enabled)
     Active: active (running)

Check the installed version to confirm everything pulled from the official repository:

icinga2 --version

Step 2: Install and Configure MariaDB Database

Icinga2 uses IcingaDB as its data backend, which requires either MySQL or MariaDB. We will use MariaDB since it ships in the default Ubuntu and Debian repositories.

Install MariaDB server:

apt -y install mariadb-server mariadb-client

Enable and start MariaDB:

systemctl enable --now mariadb

Secure the MariaDB installation by setting a root password and removing test databases:

mariadb-secure-installation

Answer the prompts – set a strong root password, remove anonymous users, disallow remote root login, and remove the test database.

Now create the IcingaDB database and user. Log into the MariaDB shell:

mysql -u root -p

Run the following SQL statements to create the database and grant permissions. Replace StrongPassword123 with your own secure password:

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

CREATE DATABASE icingaweb2;
CREATE USER 'icingaweb2'@'localhost' IDENTIFIED BY 'StrongPassword123';
GRANT ALL ON icingaweb2.* TO 'icingaweb2'@'localhost';

FLUSH PRIVILEGES;
EXIT;

Step 3: Install IcingaDB and Redis

IcingaDB is the modern replacement for the legacy IDO database module. It uses Redis as a high-performance transport layer between Icinga2 and the database backend.

Install IcingaDB, its Redis component, and import the database schema:

apt -y install icingadb icingadb-redis

Enable and start Redis for IcingaDB:

systemctl enable --now icingadb-redis

Import the IcingaDB database schema into the database you created earlier:

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

Edit the IcingaDB configuration to set your database credentials:

vi /etc/icingadb/config.yml

Update the database section to match your credentials:

database:
  type: mysql
  host: localhost
  port: 3306
  database: icingadb
  user: icingadb
  password: StrongPassword123

Enable the IcingaDB feature in Icinga2 and set up the API:

icinga2 feature enable icingadb
icinga2 api setup

Start the IcingaDB service and restart Icinga2 to apply the changes:

systemctl enable --now icingadb
systemctl restart icinga2

Verify IcingaDB is running correctly:

systemctl status icingadb

The service should show active (running) with no errors in the journal.

Step 4: Install Icinga Web 2

Icinga Web is the web-based frontend for viewing monitoring data, managing configurations, and handling alerts. Install it along with the IcingaDB web module and Apache:

apt -y install icingaweb2 icingadb-web libapache2-mod-php icingacli

This installs Icinga Web 2, the IcingaDB Web module for the dashboard, the Apache PHP module, and the Icinga CLI tool for administration tasks.

Step 5: Configure Apache Web Server

The Icinga Web 2 package automatically installs an Apache configuration file. Enable the required Apache modules and restart the service:

a2enmod rewrite
a2enmod php8.3

Restart Apache to load the modules:

systemctl restart apache2

Verify Apache is running:

systemctl status apache2

The output should confirm that the service is active and running.

If you prefer Nginx instead of Apache, generate the Nginx configuration with the Icinga CLI:

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

Save the generated output to your Nginx sites-enabled directory and adjust it for your domain. You will also need php-fpm installed and configured since Nginx does not process PHP directly.

Step 6: Run Icinga Web 2 Setup Wizard

Generate an authentication token for the web setup wizard:

icingacli setup token create

The command outputs a token string that you will need during the web-based setup:

The newly generated setup token is: a1b2c3d4e5f6g7h8

Open your browser and navigate to the setup wizard at:

http://your-server-ip/icingaweb2/setup

The setup wizard walks you through several configuration screens:

Welcome page - paste the setup token generated above
Modules - enable the IcingaDB module
Requirements - the wizard checks for required PHP modules. If any are missing, install them with apt install php-{module} and refresh the page
Authentication - select "Database" as the authentication type
Database Resource - enter the icingaweb2 database credentials created in Step 2 (database: icingaweb2, user: icingaweb2, password: your chosen password)
Authentication Backend - keep the default name
Administration - create your admin username and password for the web interface
Application Configuration - keep the defaults
IcingaDB Resource - enter the icingadb database credentials (database: icingadb, user: icingadb)
IcingaDB Redis - set the host to localhost and port to 6380
API Transport - enter the API credentials from /etc/icinga2/conf.d/api-users.conf

Review the summary and click Finish to complete the setup. You can then log in at http://your-server-ip/icingaweb2 with the admin credentials you just created.

Find the API user credentials for the wizard by reading the auto-generated configuration file:

cat /etc/icinga2/conf.d/api-users.conf

This file contains the root API user and its password, which you will enter in the transport configuration screen of the wizard.

Step 7: Add Hosts to Monitor

Icinga2 stores host and service definitions in configuration files under /etc/icinga2/conf.d/. To monitor a remote host, create a new configuration file for it.

Create a host definition file:

vi /etc/icinga2/conf.d/hosts/webserver.conf

Add the following host object definition. Replace the address and display name with your actual server details:

object Host "web-server-01" {
  import "generic-host"
  address = "192.168.1.10"
  display_name = "Web Server 01"

  vars.os = "Linux"
  vars.http_vhosts["http"] = {
    http_uri = "/"
  }
  vars.disks["disk /"] = {
    disk_partitions = "/"
  }
  vars.notification["mail"] = {
    groups = [ "icingaadmins" ]
  }
}

Create the hosts directory if it does not exist:

mkdir -p /etc/icinga2/conf.d/hosts

To add service checks for the host, you can define them in the same file or create separate service definition files. Here is an example that monitors SSH and HTTP on the host:

object Service "ssh" {
  import "generic-service"
  host_name = "web-server-01"
  check_command = "ssh"
}

object Service "http" {
  import "generic-service"
  host_name = "web-server-01"
  check_command = "http"
}

Validate the configuration before restarting:

icinga2 daemon -C

If validation passes, reload Icinga2 to apply the new host configuration:

systemctl reload icinga2

The new host should appear in the Icinga Web dashboard within a few seconds after the reload.

Step 8: Configure Notifications

Icinga2 ships with email notification commands out of the box. To enable email alerts, you need a working mail transfer agent on the server. Install Postfix or any MTA of your choice:

apt -y install mailutils

Edit the default user notification configuration to set your email address:

vi /etc/icinga2/conf.d/users.conf

Update the icingaadmin user object with your actual email address:

object User "icingaadmin" {
  import "generic-user"
  display_name = "Icinga 2 Admin"
  groups = [ "icingaadmins" ]
  email = "[email protected]"
}

The default notification rules in /etc/icinga2/conf.d/notifications.conf are already configured to send alerts on host and service state changes. Verify the notification feature is enabled:

icinga2 feature list

The output should show notification in the enabled features list. If it is not enabled, activate it:

icinga2 feature enable notification
systemctl restart icinga2

Step 9: Configure Firewall Rules

Open the required ports on your firewall to allow web access and Icinga2 API communication. If you are running Icinga2 in a distributed setup, port 5665 is essential for communication between master and satellite nodes.

Using UFW (Ubuntu/Debian default):

ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 5665/tcp
ufw reload

Verify the rules are active:

ufw status

Using iptables:

iptables -A INPUT -p tcp --dport 80 -j ACCEPT
iptables -A INPUT -p tcp --dport 443 -j ACCEPT
iptables -A INPUT -p tcp --dport 5665 -j ACCEPT

The following table summarizes the ports used by the Icinga2 monitoring stack:

Port	Protocol	Service
80	TCP	Icinga Web 2 (HTTP)
443	TCP	Icinga Web 2 (HTTPS)
5665	TCP	Icinga2 API / Cluster
6380	TCP	IcingaDB Redis (local only)
3306	TCP	MariaDB/MySQL (local only)

Step 10: Install Icinga Director (Optional)

Icinga Director is a web-based configuration module that lets you manage hosts, services, and templates through the Icinga Web interface instead of editing configuration files manually. This is especially useful for large environments where managing hundreds of host definition files becomes impractical.

Install the Director package:

apt -y install icinga-director

Create a dedicated database for the Director. Log into MariaDB:

mysql -u root -p

Run the following SQL to create the Director database and user:

CREATE DATABASE director CHARACTER SET 'utf8';
CREATE USER 'director'@'localhost' IDENTIFIED BY 'StrongPassword123';
GRANT ALL ON director.* TO 'director'@'localhost';
FLUSH PRIVILEGES;
EXIT;

After creating the database, open Icinga Web 2 in your browser and navigate to Configuration - Application - Resources. Add a new database resource with the Director database credentials you just created. Make sure the character set is UTF8.

Then go to the Icinga Director module from the main menu. The kickstart wizard will run automatically on first access and import your existing Icinga2 configuration into the Director database. This process takes a few minutes depending on the size of your monitoring environment.

Once the kickstart completes, you can manage all host, service, and notification configurations from the web interface. The Director deploys changes to Icinga2 through the Icinga2 API, so no manual file editing or service restarts are needed.

Conclusion

You now have a fully functional Icinga2 monitoring stack running on Ubuntu 24.04 or Debian 13 - with IcingaDB for data storage, Redis for high-performance transport, Icinga Web 2 for the dashboard, and optionally the Director module for web-based configuration management.

For production deployments, secure the web interface with HTTPS using Let's Encrypt or a commercial certificate, set up database monitoring for the MariaDB backend, configure regular database backups, and consider setting up a distributed monitoring architecture with satellite nodes for monitoring across multiple networks.