Installation ¶

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

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

Setting up Icinga 2 ¶

First off you have to install Icinga 2. The preferred way of doing this is to use the official package repositories depending on which operating system and distribution you are running.

Official repositories (support matrix):

Distribution	Repository
Debian	Icinga Repository
Ubuntu	Icinga Repository
Raspbian	Icinga Repository. Note that Raspbian `icinga-buster` is required.
RHEL/CentOS	Icinga Repository
openSUSE	Icinga Repository
SLES	Icinga Repository

Community repositories:

Distribution	Repository
Gentoo	Upstream
FreeBSD	Upstream
OpenBSD	Upstream
ArchLinux	Upstream
Alpine Linux	Upstream

Packages for distributions other than the ones listed above may also be available. Please contact your distribution packagers.

Note

Windows is only supported for agent installations. Please refer to the distributed monitoring chapter.

Package Repositories ¶

You need to add the Icinga repository to your package management configuration. The following commands must be executed with root permissions unless noted otherwise.

Debian/Ubuntu/Raspbian Repositories ¶

Debian:

apt-get update
apt-get -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-get update

Ubuntu:

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

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

. /etc/os-release; if [ ! -z ${UBUNTU_CODENAME+x} ]; then DIST="${UBUNTU_CODENAME}"; else DIST="$(lsb_release -c| awk '{print $2}')"; fi; \
 echo "deb https://packages.icinga.com/ubuntu icinga-${DIST} main" > \
 /etc/apt/sources.list.d/${DIST}-icinga.list
 echo "deb-src https://packages.icinga.com/ubuntu icinga-${DIST} main" >> \
 /etc/apt/sources.list.d/${DIST}-icinga.list

apt-get update

Raspbian Buster:

apt-get update
apt-get -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/raspbian icinga-${DIST} main" > \
 /etc/apt/sources.list.d/icinga.list
 echo "deb-src https://packages.icinga.com/raspbian icinga-${DIST} main" >> \
 /etc/apt/sources.list.d/icinga.list

apt-get update

Debian Backports Repository ¶

Note:

This repository is required for Debian Stretch since 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-get update

RHEL/CentOS/Fedora Repositories ¶

RHEL/CentOS 8:

dnf install https://packages.icinga.com/epel/icinga-rpm-release-8-latest.noarch.rpm

RHEL/CentOS 7:

yum install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm

RHEL/CentOS 6 x64:

yum install https://packages.icinga.com/epel/icinga-rpm-release-6-latest.noarch.rpm

Fedora 31:

dnf install https://packages.icinga.com/fedora/icinga-rpm-release-31-latest.noarch.rpm

RHEL/CentOS EPEL Repository ¶

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

CentOS 8 additionally needs the PowerTools repository for EPEL:

dnf install 'dnf-command(config-manager)'
dnf config-manager --set-enabled PowerTools

dnf install epel-release

CentOS 7/6:

yum install epel-release

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

RHEL 8:

ARCH=$( /bin/arch )

subscription-manager repos --enable rhel-8-server-optional-rpms
subscription-manager repos --enable "codeready-builder-for-rhel-8-${ARCH}-rpms"

dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.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

RHEL 6:

subscription-manager repos --enable rhel-6-server-optional-rpms
yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm

SLES/OpenSUSE Repositories ¶

The release repository also provides the required Boost 1.66+ packages since v2.11.

SLES 15/12:

rpm --import https://packages.icinga.com/icinga.key

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

openSUSE:

rpm --import https://packages.icinga.com/icinga.key

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

Alpine Linux Repositories ¶

echo "http://dl-cdn.alpinelinux.org/alpine/edge/main" >> /etc/apk/repositories
echo "http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories
apk update

The example provided assumes that you are running Alpine edge, which is the -dev branch and is a rolling release. If you are using a stable version please “pin” the edge repository on the latest Icinga 2 package version. In order to correctly manage your repository, please follow these instructions

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

Debian/Ubuntu:

apt-get install icinga2

RHEL/CentOS 8 and Fedora:

dnf install icinga2
systemctl enable icinga2
systemctl start icinga2

RHEL/CentOS 7:

yum install icinga2
systemctl enable icinga2
systemctl start icinga2

RHEL/CentOS 6:

yum install icinga2
chkconfig icinga2 on
service icinga2 start

SLES/openSUSE:

zypper install icinga2

FreeBSD:

pkg install icinga2

Alpine Linux:

apk add icinga2

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

For your convenience here is a list of package names for some of the more popular operating systems/distributions:

OS/Distribution	Package Name	Repository	Installation Path
RHEL/CentOS	nagios-plugins-all	EPEL	/usr/lib64/nagios/plugins
SLES/OpenSUSE	monitoring-plugins	server:monitoring	/usr/lib/nagios/plugins
Debian/Ubuntu	monitoring-plugins	-	/usr/lib/nagios/plugins
FreeBSD	monitoring-plugins	-	/usr/local/libexec/nagios
Alpine Linux	monitoring-plugins	-	/usr/lib/monitoring-plugins

The recommended way of installing these standard plugins is to use your distribution’s package manager.

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.

Note

Please refer to the service monitoring chapter for details about how to integrate additional check plugins into your Icinga 2 setup.

Debian/Ubuntu ¶

apt-get install monitoring-plugins

RHEL/CentOS/Fedora ¶

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

RHEL/CentOS 8:

dnf install nagios-plugins-all

RHEL/CentOS 7/6:

yum install nagios-plugins-all

Fedora:

dnf install nagios-plugins-all

SLES/openSUSE ¶

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

zypper install monitoring-plugins

FreeBSD ¶

pkg install monitoring-plugins

Alpine Linux ¶

apk add monitoring-plugins

Note: For Alpine you don’t need to explicitly add the monitoring-plugins package since it is a dependency of icinga2 and is pulled automatically.

Running Icinga 2 ¶

Systemd Service ¶

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

The Icinga 2 systemd service can be (re-)started, reloaded, stopped and also queried for its current status.

systemctl status icinga2

icinga2.service - Icinga host/service/network monitoring system
   Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled)
   Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago
  Process: 21692 ExecStart=/usr/sbin/icinga2 -c ${ICINGA2_CONFIG_FILE} -d -e ${ICINGA2_ERROR_LOG} -u ${ICINGA2_USER} -g ${ICINGA2_GROUP} (code=exited, status=0/SUCCESS)
  Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS)
 Main PID: 21727 (icinga2)
   CGroup: /system.slice/icinga2.service
           21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit

Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s).
Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s).
Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s).
Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s).
Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s).
Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s).
Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s).
Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system.

The systemctl command supports the following actions:

Command	Description
start	The `start` action starts the Icinga 2 daemon.
stop	The `stop` action stops the Icinga 2 daemon.
restart	The `restart` action is a shortcut for running the `stop` action followed by `start`.
reload	The `reload` action sends the `HUP` signal to Icinga 2 which causes it to restart. Unlike the `restart` action `reload` does not wait until Icinga 2 has restarted.
status	The `status` action checks if Icinga 2 is running.
enable	The `enable` action enables the service being started at system boot time (similar to `chkconfig`)

Examples:

systemctl enable icinga2

systemctl restart icinga2
Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.

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.

Init Script ¶

Icinga 2’s init script is installed in /etc/init.d/icinga2 (/usr/local/etc/rc.d/icinga2 on FreeBSD) by default:

/etc/init.d/icinga2

Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}

The init script supports the following actions:

Command	Description
start	The `start` action starts the Icinga 2 daemon.
stop	The `stop` action stops the Icinga 2 daemon.
restart	The `restart` action is a shortcut for running the `stop` action followed by `start`.
reload	The `reload` action sends the `HUP` signal to Icinga 2 which causes it to restart. Unlike the `restart` action `reload` does not wait until Icinga 2 has restarted.
checkconfig	The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
status	The `status` action checks if Icinga 2 is running.

By default, the Icinga 2 daemon is running as icinga user and group using the init script. Using Debian packages the user and group are set to nagios for historical reasons.

FreeBSD ¶

On FreeBSD you need to enable icinga2 in your rc.conf

sysrc icinga2_enable=yes

service icinga2 restart

SELinux ¶

SELinux is a mandatory access control (MAC) system on Linux which adds a fine-grained permission system for access to all system resources such as files, devices, networks and inter-process communication.

Icinga 2 provides its own SELinux policy. icinga2-selinux is a policy package for Red Hat Enterprise Linux 7 and derivatives. The package runs the targeted policy which confines Icinga 2 including enabled features and running commands.

RHEL/CentOS 8 and Fedora:

dnf install icinga2-selinux

RHEL/CentOS 7:

yum install icinga2-selinux

Read more about SELinux in this chapter.

Configuration Syntax Highlighting ¶

Icinga 2 provides configuration examples for syntax highlighting using the vim and nano editors. The RHEL and SUSE package icinga2-common installs these files into /usr/share/doc/icinga2-common-[x.x.x]/syntax (where [x.x.x] is the version number, e.g. 2.4.3 or 2.4.4). Sources provide these files in tools/syntax. On Debian systems the icinga2-common package provides only the Nano configuration file (/usr/share/nano/icinga2.nanorc); to obtain the Vim configuration, please install the extra package vim-icinga2. The files are located in /usr/share/vim/addons.

Configuration Syntax Highlighting using Vim ¶

Install the package vim-icinga2 with your distribution’s package manager.

Debian/Ubuntu:

apt-get install vim-icinga2 vim-addon-manager
vim-addon-manager -w install icinga2
Info: installing removed addon 'icinga2' to /var/lib/vim/addons

RHEL/CentOS 8 and Fedora:

dnf install vim-icinga2

RHEL/CentOS 7/6:

yum install vim-icinga2

SLES/openSUSE:

zypper install vim-icinga2

Alpine Linux:

apk add icinga2-vim

Ensure that syntax highlighting is enabled e.g. by editing the user’s vimrc configuration file:

# vim ~/.vimrc
syntax on

Test it:

# vim /etc/icinga2/conf.d/templates.conf

Vim with syntax highlighting

Configuration Syntax Highlighting using Nano ¶

Install the package nano-icinga2 with your distribution’s package manager.

Debian/Ubuntu:

Note: The syntax files are installed with the icinga2-common package already.

RHEL/CentOS 8 and Fedora:

dnf install nano-icinga2

RHEL/CentOS 7/6:

yum install nano-icinga2

SLES/openSUSE:

zypper install nano-icinga2

Copy the /etc/nanorc sample file to your home directory.

$ cp /etc/nanorc ~/.nanorc

Include the icinga2.nanorc file.

$ vim ~/.nanorc

## Icinga 2
include "/usr/share/nano/icinga2.nanorc"

Test it:

$ nano /etc/icinga2/conf.d/templates.conf

Nano with syntax highlighting

Setting up Icinga Web 2 ¶

Icinga 2 can be used with Icinga Web 2 and a variety of modules. This chapter explains how to set up Icinga Web 2.

The DB IDO (Database Icinga Data Output) feature for Icinga 2 takes care of exporting all configuration and status information into a database.

Note

We’re currently working on a new data backend called Icinga DB. If you want to try the latest release candidate skip to the Icinga DB Chapter. Please keep in mind, that this version is not ready for use in production and currently only supports MySQL.

Configuring DB IDO MySQL ¶

Installing MySQL database server ¶

Debian/Ubuntu:

apt-get install mysql-server mysql-client

mysql_secure_installation

RHEL/CentOS and Fedora:

yum install mariadb-server mariadb
systemctl enable mariadb
systemctl start mariadb
mysql_secure_installation

SUSE:

zypper install mysql mysql-client
chkconfig mysqld on
service mysqld start

FreeBSD:

pkg install mysql56-server
sysrc mysql_enable=yes
service mysql-server restart
mysql_secure_installation

Alpine Linux:

apk add mariadb
rc-service mariadb setup
rc-update add mariadb default
rc-service mariadb start

Installing the IDO modules for MySQL ¶

The next step is to install the icinga2-ido-mysql package using your distribution’s package manager.

Debian/Ubuntu:

apt-get install icinga2-ido-mysql

RHEL/CentOS:

yum install icinga2-ido-mysql

SUSE:

zypper install icinga2-ido-mysql

FreeBSD:

On FreeBSD the IDO modules for MySQL are included with the icinga2 package and located at /usr/local/share/icinga2-ido-mysql/schema/mysql.sql.

Alpine Linux:

On Alpine Linux the IDO modules for MySQL are included with the icinga2 package and located at /usr/share/icinga2-ido-mysql/schema/mysql.sql.

Note

The Debian/Ubuntu packages provide a database configuration wizard by default. You can skip the automated setup and install/upgrade the database manually if you prefer.

Setting up the MySQL database ¶

Set up a MySQL database for Icinga 2:

# mysql -u root -p

CREATE DATABASE icinga;
GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
quit

setting up the database on CentOS 7

After creating the database you can import the Icinga 2 IDO schema using the following command. Enter the root password into the prompt when asked.

mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql

Enabling the IDO MySQL module ¶

The package provides a new configuration file that is installed in /etc/icinga2/features-available/ido-mysql.conf. You can update the database credentials in this file.

All available attributes are explained in the IdoMysqlConnection object chapter.

You can enable the ido-mysql feature configuration file using icinga2 feature enable:

# icinga2 feature enable ido-mysql
Module 'ido-mysql' was enabled.
Make sure to restart Icinga 2 for these changes to take effect.

Restart Icinga 2.

systemctl restart icinga2

Alpine Linux:

rc-service icinga2 restart

Continue with the webserver setup.

Configuring DB IDO PostgreSQL ¶

Installing PostgreSQL database server ¶

Debian/Ubuntu:

apt-get install postgresql

RHEL/CentOS:

yum install postgresql-server postgresql
postgresql-setup initdb
systemctl enable postgresql
systemctl start postgresql

SUSE:

zypper install postgresql postgresql-server
chkconfig postgresql on
service postgresql initdb
service postgresql start

FreeBSD:

pkg install postgresql93-server
sysrc postgresql_enable=yes
service postgresql initdb
service postgresql start

Alpine Linux:

apk add postgresql
rc-update add postgresql default
rc-service postgresql setup
rc-service postgresql start

Installing the IDO modules for PostgreSQL ¶

The next step is to install the icinga2-ido-pgsql package using your distribution’s package manager.

Debian/Ubuntu:

apt-get install icinga2-ido-pgsql

RHEL/CentOS:

yum install icinga2-ido-pgsql

SUSE:

zypper install icinga2-ido-pgsql

FreeBSD:

On FreeBSD the IDO modules for PostgreSQL are included with the icinga2 package and located at /usr/local/share/icinga2-ido-pgsql/schema/pgsql.sql.

Alpine Linux:

On Alpine Linux the IDO modules for PostgreSQL are included with the icinga2 package and located at /usr/share/icinga2-ido-pgsql/schema/pgsql.sql.

Note

Upstream Debian packages provide a database configuration wizard by default. You can skip the automated setup and install/upgrade the database manually if you prefer that.

Setting up the PostgreSQL database¶

Set up a PostgreSQL database for Icinga 2:

cd /tmp
sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'"
sudo -u postgres createdb -O icinga -E UTF8 icinga

Note

It is assumed here that your locale is set to utf-8, you may run into problems otherwise.

Locate your pg_hba.conf configuration file (Debian: /etc/postgresql/*/main/pg_hba.conf, RHEL/SUSE: /var/lib/pgsql/data/pg_hba.conf), add the icinga user with md5 as authentication method and restart the postgresql server.

# icinga
local   icinga      icinga                            md5
host    icinga      icinga      127.0.0.1/32          md5
host    icinga      icinga      ::1/128               md5

# "local" is for Unix domain socket connections only
local   all         all                               ident
# IPv4 local connections:
host    all         all         127.0.0.1/32          ident
# IPv6 local connections:
host    all         all         ::1/128               ident

systemctl restart postgresql

After creating the database and permissions you need to import the IDO database schema using the following command:

export PGPASSWORD=icinga
psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql

importing the Icinga 2 IDO schema

Enabling the IDO PostgreSQL module ¶

The package provides a new configuration file that is installed in /etc/icinga2/features-available/ido-pgsql.conf. You can update the database credentials in this file.

All available attributes are explained in the IdoPgsqlConnection object chapter.

You can enable the ido-pgsql feature configuration file using icinga2 feature enable:

# icinga2 feature enable ido-pgsql
Module 'ido-pgsql' was enabled.
Make sure to restart Icinga 2 for these changes to take effect.

Restart Icinga 2.

systemctl restart icinga2

Alpine Linux:

rc-service icinga2 restart

Continue with the webserver setup.

Webserver ¶

The preferred way of installing Icinga Web 2 is to use Apache as webserver in combination with PHP-FPM. If you prefer Nginx, please refer to the Icinga Web 2 documentation.

Note

These instructions follow HTTP. In order to secure your webserver, please use HTTPS and TLS certificates e.g. from Let’s Encrypt.

Debian/Ubuntu:

apt-get install apache2

RHEL/CentOS/Fedora:

yum install httpd
systemctl enable httpd
systemctl start httpd

SUSE:

zypper install apache2
chkconfig apache2 on
service apache2 start

FreeBSD (Nginx, but you could also use the apache24 package):

pkg install nginx php56-gettext php56-ldap php56-openssl php56-mysql php56-pdo_mysql php56-pgsql php56-pdo_pgsql php56-sockets php56-gd pecl-imagick pecl-intl
sysrc php_fpm_enable=yes
sysrc nginx_enable=yes
sed -i '' "s/listen\ =\ 127.0.0.1:9000/listen\ =\ \/var\/run\/php5-fpm.sock/" /usr/local/etc/php-fpm.conf
sed -i '' "s/;listen.owner/listen.owner/" /usr/local/etc/php-fpm.conf
sed -i '' "s/;listen.group/listen.group/" /usr/local/etc/php-fpm.conf
sed -i '' "s/;listen.mode/listen.mode/" /usr/local/etc/php-fpm.conf
service php-fpm start
service nginx start

Alpine Linux:

apk add apache2 php7-apache2
sed -i -e "s/^#LoadModule rewrite_module/LoadModule rewrite_module/" /etc/apache2/httpd.conf
rc-update add apache2 default
rc-service apache2 start

Firewall Rules ¶

Enable port 80 (http). Best practice is to only enable port 443 (https) and use TLS certificates.

firewall-cmd:

firewall-cmd --add-service=http
firewall-cmd --permanent --add-service=http

iptables:

iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
service iptables save

FreeBSD: Please consult the FreeBSD Handbook how to configure one of FreeBSD’s firewalls.

Setting Up Icinga 2 REST API ¶

Icinga Web 2 and other web interfaces require the REST API to send actions (reschedule check, etc.) and query object details.

You can run the CLI command icinga2 api setup to enable the api feature and set up certificates as well as a new API user root with an auto-generated password in the /etc/icinga2/conf.d/api-users.conf configuration file:

icinga2 api setup

Edit the api-users.conf file and add a new ApiUser object. Specify the permissions attribute with minimal permissions required by Icinga Web 2.

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

object ApiUser "icingaweb2" {
  password = "Wijsn8Z9eRs5E25d"
  permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ]
}

Restart Icinga 2 to activate the configuration.

systemctl restart icinga2

Alpine Linux:

rc-service icinga2 restart

Installing Icinga Web 2 ¶

Please consult the Icinga Web 2 documentation for further instructions on how to install Icinga Web 2.

If you decided on using Icinga DB, consult the Icinga DB Web documentation on how to connect Icinga Web 2 with Icinga DB.

Addons ¶

A number of additional features are available in the form of addons. A list of popular addons is available in the Addons and Plugins chapter.

Installation Overview ¶

Enabled Features during Installation ¶

The default installation will enable three features required for a basic Icinga 2 installation:

checker for executing checks
notification for sending notifications
mainlog for writing the icinga2.log file

You can verify that by calling icinga2 feature list CLI command to see which features are enabled and disabled.

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

Installation Paths ¶

By default Icinga 2 uses the following files and directories:

Path	Description
/etc/icinga2	Contains Icinga 2 configuration files.
/usr/lib/systemd/system/icinga2.service	The Icinga 2 systemd service file on systems using systemd.
/etc/systemd/system/icinga2.service.d/limits.conf	On distributions with systemd >227, additional service limits are required.
/etc/init.d/icinga2	The Icinga 2 init script on systems using SysVinit or OpenRC.
/usr/sbin/icinga2	Shell wrapper for the Icinga 2 binary.
/usr/lib*/icinga2	Libraries and the Icinga 2 binary (use `find /usr -type f -name icinga2` to locate the binary path).
/usr/share/doc/icinga2	Documentation files that come with Icinga 2.
/usr/share/icinga2/include	The Icinga Template Library and plugin command configuration.
/var/lib/icinga2	Icinga 2 state file, cluster log, master CA, node certificates and configuration files (cluster, api).
/var/run/icinga2	PID file.
/var/run/icinga2/cmd	Command pipe and Livestatus socket.
/var/cache/icinga2	status.dat/objects.cache, icinga2.debug files.
/var/spool/icinga2	Used for performance data spool files.
/var/log/icinga2	Log file location and compat/ directory for the CompatLogger feature.

FreeBSD uses slightly different paths:

By default Icinga 2 uses the following files and directories:

Path	Description
/usr/local/etc/icinga2	Contains Icinga 2 configuration files.
/usr/local/etc/rc.d/icinga2	The Icinga 2 init script.
/usr/local/sbin/icinga2	Shell wrapper for the Icinga 2 binary.
/usr/local/lib/icinga2	Libraries and the Icinga 2 binary.
/usr/local/share/doc/icinga2	Documentation files that come with Icinga 2.
/usr/local/share/icinga2/include	The Icinga Template Library and plugin command configuration.
/var/lib/icinga2	Icinga 2 state file, cluster log, master CA, node certificates and configuration files (cluster, api).
/var/run/icinga2	PID file.
/var/run/icinga2/cmd	Command pipe and Livestatus socket.
/var/cache/icinga2	status.dat/objects.cache, icinga2.debug files.
/var/spool/icinga2	Used for performance data spool files.
/var/log/icinga2	Log file location and compat/ directory for the CompatLogger feature.

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
Optional: IDO database backup

Backup: Database ¶

MySQL/MariaDB:

Documentation

PostgreSQL:

Documentation

Icinga DB ¶

Icinga DB is a new data backend currently in development. It’s purpose is to synchronise data between Icinga 2 (Redis) and Icinga Web 2 (MySQL), some day replacing the IDO. Don’t worry, we won’t drop support on the IDO any time soon.

Note Icinga DB is not ready to be used in production
and should only be used for testing purposes.

Configuring Icinga DB ¶

First, make sure to setup Icinga DB itself and its database backends (Redis and MySQL) by following the installation instructions.

Enabling the Icinga DB feature ¶

Icinga 2 provides a configuration file that is installed in /etc/icinga2/features-available/icingadb.conf. You can update the Redis credentials in this file.

All available attributes are explained in the IcingaDB object chapter.

You can enable the icingadb feature configuration file using icinga2 feature enable:

# icinga2 feature enable icingadb
Module 'icingadb' was enabled.
Make sure to restart Icinga 2 for these changes to take effect.

Restart Icinga 2.

systemctl restart icinga2

Alpine Linux:

rc-service icinga2 restart

Continue with the webserver setup.