Quickstart

Welcome to the Icinga Quickstart Guide! Whether you’re new to system monitoring or an experienced admin, this guide will walk you through the essential steps to get Icinga up and running on your server. By the end of this guide, you’ll be ready to monitor your network, servers, and applications, ensuring your infrastructure stays healthy and reliable.

Icinga consists of multiple components, each responsible for different aspects of monitoring and management. To keep things simple, we’ll be installing everything on a single node in this guide. This setup will give you a complete Icinga environment in one place, perfect for getting started quickly.

You’re going to install:

• Icinga 2
• Icinga DB
• Icinga Web
• Icinga DB Web
• Icinga Director

Requirements

A database is required to store the monitoring data collected by Icinga. For this guide, MySQL > 5.7 or MariaDB > 10.2 is required.

The commands listed below should be run with root permissions unless specified otherwise.

Add Repository

Add the official Icinga Package Repository to your system.

UbuntuDebianSLESRHEL

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

wget -O - https://packages.icinga.com/icinga.key | gpg --dearmor -o /usr/share/keyrings/icinga-archive-keyring.gpg

. /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

apt update

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

wget -O - https://packages.icinga.com/icinga.key | apt-key add -

DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
echo "deb https://packages.icinga.com/debian icinga-${DIST} main" > \
/etc/apt/sources.list.d/${DIST}-icinga.list
echo "deb-src https://packages.icinga.com/debian icinga-${DIST} main" >> \
/etc/apt/sources.list.d/${DIST}-icinga.list

apt update

Debian Backports Repository

This repository is required for Debian Stretch since Icinga v2.11.

Debian Stretch:

DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
echo "deb https://deb.debian.org/debian ${DIST}-backports main" > \
/etc/apt/sources.list.d/${DIST}-backports.list

apt update

Info

A paid repository subscription is required for SLES repositories. Get more information on icinga.com/subscription

Don’t forget to fill in the username and password section with your credentials in the local .repo file.

First add the official repositories:

wget https://packages.icinga.com/subscription/sles/ICINGA-release.repo -O /etc/zypp/repos.d/ICINGA-release.repo
zypper ref

You need to additionally add the PackageHub repository to fulfill dependencies:

source /etc/os-release

SUSEConnect -p PackageHub/$VERSION_ID/x86_64
SUSEConnect -p sle-module-web-scripting/$VERSION_ID/x86_64

Info

A paid repository subscription is required for RHEL repositories. Get more information on icinga.com/subscription

Don’t forget to fill in the username and password section with your credentials in the local .repo file.

rpm --import https://packages.icinga.com/icinga.key
curl https://packages.icinga.com/subscription/rhel/ICINGA-release.repo -o /etc/yum.repos.d/ICINGA-release.repo

If you are using RHEL you need to additionally enable the codeready-builder repository before installing the EPEL rpm package.

ARCH=$(/bin/arch)
OSVER=$(. /etc/os-release; echo "${VERSION_ID%%.*}")

subscription-manager repos --enable "codeready-builder-for-rhel-${OSVER}-${ARCH}-rpms"

dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-${OSVER}.noarch.rpm

Install Packages

UbuntuDebianSLESRHEL

apt install \
    icinga2 \
    icingacli \
    icingadb \
    icingadb-redis \
    icingadb-web \
    icingaweb2 \
    icinga-director \
    monitoring-plugins 

apt install \
    icinga2 \
    icingacli \
    icingadb \
    icingadb-redis \
    icingadb-web \
    icingaweb2 \
    icinga-director \
    monitoring-plugins

zypper install \
    icinga2 \
    icingacli \
    icingadb \
    icingadb-redis \
    icingadb-web \
    icingaweb2 \
    icinga-director

zypper install --recommends monitoring-plugins-all

The packages for RHEL depend on other packages which are distributed as part of the EPEL repository.

dnf install \
    icinga2 \
    icingacli \
    icingadb \
    icingadb-redis \
    icingadb-web \
    icingaweb2 \
    icinga-director \
    nagios-plugins-all

systemctl enable --now icinga2

Warning

If SELinux is enabled on your server, you may have to allow connections from the web server to Redis® explicitly.

setsebool -P httpd_can_network_connect 1

and install additional packages to configure SELinux properly:

dnf install icinga-selinux-common icingaweb2-selinux icinga2-selinux

Set up API

The Icinga 2 API is required by other components to transmit commands, read data and deploy new Icinga configuration. Set up the API by running the API wizard:

icinga2 api setup
systemctl restart icinga2

The API setup wizard will guide you through the following steps:

• It enables the api feature
• It generates a Certification Authority (CA) and initial certificates, since Icinga always communicates through secured channels.
• It creates a new API user called root - with full permissions. Credentials are stored under /etc/icinga2/conf.d/api-users.conf

You will need the API user credentials later when setting up the Icinga web interface.

Set up MySQL Databases

Icinga requires multiple database to store and manage different aspects of the monitoring environment.

Create databases

Make sure you have sufficient permissions to create the databases, for example by connecting as root:

mysql -u root -p

Database for Icinga Web

mysql>
    CREATE DATABASE icingaweb2;
    CREATE USER 'icingaweb2'@'localhost' IDENTIFIED BY 'CHANGEME';
    GRANT ALL PRIVILEGES ON icingaweb2.* TO 'icingaweb2'@'localhost';

Database for Director (only necessary if you want want to use the director)

mysql>
    CREATE DATABASE director CHARACTER SET 'utf8';
    CREATE USER director@localhost IDENTIFIED BY 'CHANGEME';
    GRANT ALL ON director.* TO director@localhost;

Database for Icinga DB

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

After creating the database, import the Icinga DB schema using the following command:

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

Set up Icinga DB

Icinga DB is respnsible for storing the collected monitoring data. It uses a dedicated Redis®* instance for caching.

Start Redis® for Icinga DB

Start and enable Redis® for Icinga DB.

systemctl enable --now icingadb-redis

Warning

If the following error occurs: “Failed to enable unit: Refusing to operate on alias name or linked unit file: icingadb-redis.service” Check the service’s status with:

systemctl status icingadb-redis

If it’s already running, everything is okay.

Enable Icinga DB Feature

Ensure Icinga 2 sends the collected data to Icinga DB by enabling the icingadb feature:

icinga2 feature enable icingadb
systemctl restart icinga2

Start Icinga DB

The Icinga DB configuration is stored under /etc/icingadb/config.yml. Make sure to adjust connection settings properly before starting Icinga DB. Start Icinga DB by executing the following command.

systemctl enable --now icingadb

Set up Icinga Web

Next, we’ll set up Icinga Web, the user-friendly interface for monitoring your infrastructure. Follow these steps to get the web interface up and running, so you can easily visualize and control your Icinga setup.

Depending on your operating systems, additional steps may be required for the web server:

UbuntuDebianSLESRHEL

apt install libapache2-mod-php

The additional package libapache2-mod-php is necessary on Ubuntu to automatically install a web server and PHP and make Icinga Web work out-of-the-box.

On Debian there is no additional step necessary.

systemctl enable --now apache2
a2enmod rewrite
systemctl restart apache2

systemctl enable --now httpd

Prepare Web Setup

Icinga Web can be set up easily by using it’s built in setup wizard. It will open automatically when you visit Icinga Web for the first time. By creating a setup token upfront, you ensure that you are authorized to to run the setup wizard. You will be asked for the token during the web setup.

To generate a token use the icingacli:

icingacli setup token create

In case the output gets lost, you can display the token on the CLI at any time by running:

icingacli setup token show

Start Web Setup

Open your browser and point it to your server’s hostname, eg. http://localhost/icingaweb2. You will be lead to the setup wizard automatically.

Tip

Use the same database name, user and password details created above when asked.

The setup wizard automatically detects and validates requirements. If anything is missing, use your package manager to install required packages and restart your web server.

Info

The API user credentials are auto-generated and stored in /etc/icinga2/conf.d/api-users.conf

Continue with the Setup Wizard