icinga2/doc/02-installation.md

Installation

This tutorial is a step-by-step introduction to install Icinga 2. It assumes that you are familiar with the operating system you're using to install Icinga 2.

Please follow the steps listed for your operating system. Packages for distributions other than the ones listed here may also be available. Please refer to icinga.com/get-started/download for a full list of available community repositories.

Upgrade

In case you are upgrading an existing setup, please ensure to follow the upgrade documentation.

Add Icinga Package Repository

We recommend using our official repositories.

All the following commands should be executed as the root user. As pipes and nested commands are used, it is recommended to switch to a root user session, e.g., using sudo -i.

Here's how to add it to your system:

Debian Repository

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

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

apt install ./icinga-archive-keyring.deb

DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
 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

apt update

Ubuntu Repository

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

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

RHEL Repository

!!! info

A paid repository subscription is required for RHEL repositories. Get more information on
[icinga.com/subscription](https://icinga.com/subscription)

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

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

RHEL 8 or Later

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

RHEL 7

subscription-manager repos --enable rhel-7-server-optional-rpms

yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

Fedora Repository

dnf install -y 'dnf-command(config-manager)'
dnf config-manager --add-repo https://packages.icinga.com/fedora/$(. /etc/os-release; echo "$VERSION_ID")/release

SLES Repository

!!! info

A paid repository subscription is required for SLES repositories. Get more information on
[icinga.com/subscription](https://icinga.com/subscription)

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

zypper ar https://packages.icinga.com/subscription/sles/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

openSUSE Repository

zypper ar https://packages.icinga.com/openSUSE/ICINGA-release.repo
zypper ref

You need to additionally add the server:monitoring repository to fulfill dependencies:

zypper ar https://download.opensuse.org/repositories/server:/monitoring/15.3/server:monitoring.repo

Amazon Linux Repository

!!! info

A paid repository subscription is required for Amazon Linux repositories. Get more information on
[icinga.com/subscription](https://icinga.com/subscription)

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

wget https://packages.icinga.com/subscription/amazon/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo

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

yum install epel-release

The packages for newer versions of Amazon Linux don't require additional repositories.

Icinga for Windows Repository

Icinga for Windows is the recommended way to install and update Icinga 2 on Windows.

We provide a dedicated repository for Windows to simplify the installation. Please refer to the official Icinga for Windows installation docs

Install Icinga 2

You can install Icinga 2 by using your distribution's package manager to install the icinga2 package. The following commands must be executed with root permissions unless noted otherwise.

!!! tip

If you have [SELinux](22-selinux.md) enabled, the package `icinga2-selinux` is also required.

Debian / Ubuntu / Raspberry Pi OS

apt install icinga2

RHEL 8 or Later

dnf install icinga2
systemctl enable icinga2
systemctl start icinga2

RHEL 7

yum install icinga2
systemctl enable icinga2
systemctl start icinga2

Fedora

dnf install icinga2
systemctl enable icinga2
systemctl start icinga2

SLES / openSUSE

zypper install icinga2

Amazon Linux

yum install icinga2
systemctl enable icinga2
systemctl start icinga2

Systemd Service

The majority of supported distributions use systemd. The Icinga 2 packages automatically install the necessary systemd unit files.

If you're stuck with configuration errors, you can manually invoke the configuration validation.

icinga2 daemon -C

!!! tip

If you are running into fork errors with systemd enabled distributions,
please check the [troubleshooting chapter](15-troubleshooting.md#check-fork-errors).

Set up Check Plugins

Without plugins Icinga 2 does not know how to check external services. The Monitoring Plugins Project provides an extensive set of plugins which can be used with Icinga 2 to check whether services are working properly.

These plugins are required to make the example configuration work out-of-the-box.

Depending on which directory your plugins are installed into you may need to update the global PluginDir constant in your Icinga 2 configuration. This constant is used by the check command definitions contained in the Icinga Template Library to determine where to find the plugin binaries.

!!! tip

Please refer to the [service monitoring](05-service-monitoring.md#service-monitoring-plugins) chapter for details about how to integrate
additional check plugins into your Icinga 2 setup.

Debian / Ubuntu / Raspberry Pi OS

apt install monitoring-plugins

RHEL

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

RHEL 8 or Later

dnf install nagios-plugins-all

RHEL 7

yum install nagios-plugins-all

Fedora

dnf install nagios-plugins-all

SLES / openSUSE

The packages depend on other packages which are distributed as part of the server:monitoring repository. Please make sure to enable this repository beforehand.

zypper install --recommends monitoring-plugins-all

Amazon Linux

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

amazon-linux-extras install epel

yum install nagios-plugins-all

Unfortunately newer versions of Amazon Linux don't provide those plugins, yet.

Set up Icinga 2 API

Almost every Icinga 2 setup requires the Icinga 2 API as Icinga Web connects to it, Icinga DB requires it, and it enables cluster communication functionality for highly available and distributed setups.

!!! info

If you set up a highly available and/or distributed Icinga monitoring environment, please read the
[Distributed Monitoring](06-distributed-monitoring.md#distributed-monitoring) chapter as
the commands to set up the API are different from setting up a single node setup.

See the API chapter for details, or follow the steps below to set up the API quickly:

Run the following command to:

• enable the api feature,
• set up certificates, and
• add the API user root with an auto-generated password in the configuration file /etc/icinga2/conf.d/api-users.conf.

icinga2 api setup

Restart Icinga 2 for these changes to take effect.

systemctl restart icinga2

Set up Icinga DB

Icinga DB is a set of components for publishing, synchronizing and visualizing monitoring data in the Icinga ecosystem, consisting of:

• Icinga 2 with its icingadb feature enabled, responsible for publishing monitoring data to a Redis server, i.e. configuration and its runtime updates, check results, state changes, downtimes, acknowledgements, notifications, and other events such as flapping
• The Icinga DB daemon, which synchronizes the data between the Redis server and a database
• And Icinga Web with the Icinga DB Web module enabled, which connects to both Redis and the database to display and work with the most up-to-date data

!!! info

Setting up Icinga 2's Icinga DB feature is only required for Icinga 2 master nodes or single-node setups.

Set up Redis Server

A Redis server from version 6.2 is required.

!!! info

This guide sets up the `icingadb-redis` package provided by Icinga,
which ships a current Redis Server version and is preconfigured for the Icinga DB components.
Using own Redis server setups is supported as long as the version requirements are met.

!!! tip

Although the Redis server can run anywhere in an Icinga environment,
we recommend to install it where the corresponding Icinga 2 node is running to
keep latency between the components low.

Install Icinga DB Redis Package

Use your distribution's package manager to install the icingadb-redis package as follows:

Amazon Linux

yum install icingadb-redis

Debian / Ubuntu / Raspberry Pi OS

apt install icingadb-redis

RHEL 8 or Later

dnf install icingadb-redis

RHEL 7

yum install icingadb-redis

SLES

zypper install icingadb-redis

Run Icinga DB Redis

The icingadb-redis package automatically installs the necessary systemd unit files to run Icinga DB Redis. Please run the following command to enable and start its service:

systemctl enable --now icingadb-redis

Enable Remote Redis Connections

By default, icingadb-redis only listens on 127.0.0.1. If Icinga Web or Icinga 2 is running on another node, remote access to the Redis server must be allowed. This requires the following directives to be set in the /etc/icingadb-redis/icingadb-redis.conf configuration file:

• Set protected-mode to no, i.e. protected-mode no
• Set bind to the desired binding interface or bind all interfaces, e.g. bind 0.0.0.0

!!! warning

By default, Redis has no authentication preventing others from accessing it.
When opening Redis to an external interface, make sure to set a password, set up appropriate firewall rules,
or configure TLS with certificate authentication on Redis and its consumers,
i.e. Icinga 2, Icinga DB and Icinga Web.

Restart Icinga DB Redis for these changes to take effect:

systemctl restart icingadb-redis

Enable Icinga DB Feature

With the Icinga DB feature enabled, Icinga 2 publishes all of its monitoring data to the Redis server. This includes configuration and its runtime updates via the Icinga 2 API, check results, state changes, downtimes, acknowledgments, notifications and other events such as flapping.

Icinga 2 installs the feature configuration file to /etc/icinga2/features-available/icingadb.conf, pre-configured for a local setup. Update this file in case Redis is running on a different host or to set credentials. All available settings are explained in the Icinga DB object chapter.

!!! important

For single-node and high-availability setups, please read the note about the
[environment ID](https://icinga.com/docs/icinga-db/latest/doc/05-Distributed-Setups/#environment-id),
which is common to all Icinga DB components and generated by the Icinga DB feature.

To enable the icingadb feature use the following command:

icinga2 feature enable icingadb

Restart Icinga 2 for these changes to take effect:

systemctl restart icinga2

Install Icinga DB Daemon

After installing Icinga 2, setting up a Redis server and enabling the icingadb feature, the Icinga DB daemon that synchronizes monitoring data between the Redis server and a database is now set up.

!!! tip

Although the Icinga DB daemon can run anywhere in an Icinga environment,
we recommend to install it where the corresponding Icinga 2 node and Redis server is running to
keep latency between the components low.

The Icinga DB daemon package is also included in the Icinga repository, and since it is already set up, you have completed the instructions here and can proceed to

install the Icinga DB daemon on Amazon Linux,

install the Icinga DB daemon on Debian,

install the Icinga DB daemon on RHEL,

install the Icinga DB daemon on SLES,

install the Icinga DB daemon on Ubuntu,

which will also guide you through the setup of the database and Icinga DB Web.

Backup

Ensure to include the following in your backups:

• Configuration files in /etc/icinga2
• Certificate files in /var/lib/icinga2/ca (Master CA key pair) and /var/lib/icinga2/certs (node certificates)
• Runtime files in /var/lib/icinga2