35 KiB
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. Here's how to add it to your system:
Debian Repository
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
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-get update
Ubuntu Repository
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 Repository
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
CentOS Repository
rpm --import https://packages.icinga.com/icinga.key
wget https://packages.icinga.com/centos/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
The packages for 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
For CentOS 7 run:
yum install epel-release
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.
rpm --import https://packages.icinga.com/icinga.key
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 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
Fedora Repository
rpm --import https://packages.icinga.com/icinga.key
dnf install https://packages.icinga.com/fedora/icinga-rpm-release-$(. /etc/os-release; echo "$VERSION_ID")-latest.noarch.rpm
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.
rpm --import https://packages.icinga.com/icinga.key
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
rpm --import https://packages.icinga.com/icinga.key
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 2 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.
rpm --import https://packages.icinga.com/icinga.key
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
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 / Raspbian
apt-get install icinga2
CentOS 8
dnf install icinga2
systemctl enable icinga2
systemctl start icinga2
CentOS 7
yum install icinga2
systemctl enable icinga2
systemctl start icinga2
RHEL 8
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 2
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 / Raspbian
apt-get install monitoring-plugins
CentOS
The packages for CentOS depend on other packages which are distributed as part of the EPEL repository.
CentOS 8
dnf install nagios-plugins-all
CentOS 7
yum install nagios-plugins-all
RHEL
The packages for RHEL depend on other packages which are distributed as part of the EPEL repository.
RHEL 8
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 monitoring-plugins
Amazon Linux 2
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
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 2
yum install icingadb-redis
CentOS
!!! info
Note that installing Icinga DB Redis is only supported on CentOS 7 as CentOS 8 is EOL.
yum install icingadb-redis
Debian / Ubuntu
apt-get 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
tono
, 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
Set up Database
The IDO (Icinga Data Output) feature for Icinga 2 stores all configuration and status information into a database. Icinga Web 2 connects to the IDO database to visualize the data properly. You can either use a MySQL or PostgreSQL database.
We recommend to install and configure the IDO feature before continuing with the installation of Icinga Web 2.
!!! 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](#icingadb). Please keep in mind, that this version
is not ready for use in production and currently only supports MySQL.
IDO with MySQL
Install MySQL Server
Debian / Ubuntu
apt-get install mariadb-server mariadb-client
mysql_secure_installation
CentOS
CentOS 8
dnf install mariadb-server mariadb
systemctl enable mariadb
systemctl start mariadb
mysql_secure_installation
CentOS 7
yum install mariadb-server mariadb
systemctl enable mariadb
systemctl start mariadb
mysql_secure_installation
RHEL
RHEL 8
dnf install mariadb-server mariadb
systemctl enable mariadb
systemctl start mariadb
mysql_secure_installation
RHEL 7
yum install mariadb-server mariadb
systemctl enable mariadb
systemctl start mariadb
mysql_secure_installation
SLES / openSUSE
zypper install mariadb mariadb-client
systemctl enable mariadb
systemctl start mariadb
mysql_secure_installation
Amazon Linux 2
yum install mariadb-server mariadb
systemctl enable mariadb
systemctl start mariadb
mysql_secure_installation
Install IDO Feature
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
!!! note
The packages provide a database configuration wizard by
default. You can skip the automated setup and install/upgrade the
database manually if you prefer.
CentOS
CentOS 8
dnf install icinga2-ido-mysql
CentOS 7
yum install icinga2-ido-mysql
RHEL
RHEL 8
dnf install icinga2-ido-mysql
RHEL 7
yum install icinga2-ido-mysql
SLES / openSUSE
zypper install icinga2-ido-mysql
Amazon Linux 2
yum install icinga2-ido-mysql
Set up MySQL database
Set up a MySQL database for Icinga 2:
# mysql -u root -p
CREATE DATABASE icinga;
GRANT ALTER, CREATE, SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
quit
Please note that the example above uses the very simple password 'icinga' (in IDENTIFIED BY 'icinga'
).
Please choose a better password for your installation.
After creating the database you can import the Icinga 2 IDO schema using the following command. Enter the icinga password into the prompt when asked.
mysql -u icinga -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
Enable the IDO MySQL feature
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.
Enable the ido-mysql
feature configuration file using the icinga2
command:
# 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
IDO with PostgreSQL
Install PostgreSQL server
Debian / Ubuntu
apt-get install postgresql
CentOS
CentOS 8
dnf install postgresql-server postgresql
postgresql-setup initdb
systemctl enable postgresql
systemctl start postgresql
CentOS 7
yum install postgresql-server postgresql
postgresql-setup initdb
systemctl enable postgresql
systemctl start postgresql
RHEL
RHEL 8
dnf install postgresql-server postgresql
postgresql-setup initdb
systemctl enable postgresql
systemctl start postgresql
RHEL 7
yum install postgresql-server postgresql
postgresql-setup initdb
systemctl enable postgresql
systemctl start postgresql
SLES / openSUSE
zypper install postgresql postgresql-server
chkconfig postgresql on
service postgresql initdb
service postgresql start
Amazon Linux 2
yum install postgresql-server postgresql
postgresql-setup initdb
systemctl enable postgresql
systemctl start postgresql
Install IDO Feature
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
!!! 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.
CentOS
CentOS 8
dnf install icinga2-ido-pgsql
CentOS 7
yum install icinga2-ido-pgsql
RHEL
RHEL 8
dnf install icinga2-ido-pgsql
RHEL 7
yum install icinga2-ido-pgsql
SLES / openSUSE
zypper install icinga2-ido-pgsql
Amazon Linux 2
yum install icinga2-ido-pgsql
Set up 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 and add the icinga user with md5
as authentication method
and restart the postgresql server. Common locations for pg_hba.conf
are either
/etc/postgresql/*/main/pg_hba.conf
or /var/lib/pgsql/data/pg_hba.conf
.
# 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
Restart PostgreSQL:
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
Enable the IDO PostgreSQL feature
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.
Enable the ido-pgsql
feature configuration file using the icinga2
command:
# 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
Install Icinga Web 2
You are now ready to start the installation of Icinga Web 2. Please follow the Icinga Web 2 installation instructions.
!!! note
If you're using Icinga DB, follow the [installation instructions](https://icinga.com/docs/icinga-db/latest/icinga-db-web/doc/02-Installation/)
to install and enable the Icinga DB Web module.
Syntax Highlighting
Icinga 2 provides configuration examples for syntax highlighting using the vim
and nano
editors.
Using Vim
Install the package vim-icinga2
with your distribution's package manager.
Debian / Ubuntu / Raspbian
apt-get install vim-icinga2 vim-addon-manager
vim-addon-manager -w install icinga2
Info: installing removed addon 'icinga2' to /var/lib/vim/addons
CentOS
CentOS 8
dnf install vim-icinga2
CentOS 7
yum install vim-icinga2
RHEL
RHEL 8
dnf install vim-icinga2
RHEL 7
yum install vim-icinga2
Fedora
dnf install vim-icinga2
SLES / openSUSE
zypper install vim-icinga2
Amazon Linux 2
yum install vim-icinga2
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
Using Nano
Install the package nano-icinga2
with your distribution's package manager.
Debian / Ubuntu / Raspbian
Note: The syntax files are installed with the icinga2-common
package already.
CentOS
CentOS 8
dnf install nano-icinga2
CentOS 7
yum install nano-icinga2
RHEL
RHEL 8
dnf install nano-icinga2
RHEL 7
yum install nano-icinga2
Fedora
dnf install nano-icinga2
SLES / openSUSE
zypper install nano-icinga2
Amazon Linux 2
yum 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
Installation Overview
Enabled Features during Installation
The default installation will enable three features required for a basic Icinga 2 installation:
checker
for executing checksnotification
for sending notificationsmainlog
for writing theicinga2.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. |
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.
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
Database Backup
MySQL/MariaDB:
PostgreSQL: