Project: Icinga (Observability and Analysis / Observability)
File: 02-installation.md

<!-- {% if index %} --> 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 for a full list of available community repositories. In case you are upgrading an existing setup, please ensure to follow the . <!-- {% else %} --> <!-- {% if not windows %} --> 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: <!-- {% endif %} --> <!-- {% if debian %} --> ```bash 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 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 ``` This repository is required for Debian Stretch since Icinga v2.11. Debian Stretch: ```bash 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 ``` <!-- {% endif %} --> <!-- {% if ubuntu %} --> ```bash 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 ${UBUNTUCODENAME+x} ]; then DIST="${UBUNTUCODENAME}"; 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 ``` <!-- {% endif %} --> <!-- {% if raspbian %} --> ```bash 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 DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \ echo "deb [signed-by=/usr/share/keyrings/icinga-archive-keyring.gpg] https://packages.icinga.com/raspbian icinga-${DIST} main" > \ /etc/apt/sources.list.d/icinga.list echo "deb-src [signed-by=/usr/share/keyrings/icinga-archive-keyring.gpg] https://packages.icinga.com/raspbian icinga-${DIST} main" >> \ /etc/apt/sources.list.d/icinga.list apt update ``` <!-- {% endif %} --> <!-- {% if centos %} --> ```bash 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 : ```bash yum install epel-release ``` <!-- {% endif %} --> <!-- {% if rhel %} --> !!! info A paid repository subscription is required for RHEL repositories. Get more information on Don't forget to fill in the username and password section with your credentials in the local .repo file. ```bash 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 `codeready-builder` repository before installing the . ```bash 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 ``` ```bash subscription-manager repos --enable rhel-7-server-optional-rpms yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm ``` <!-- {% endif %} --> <!-- {% if fedora %} --> ```bash rpm --import

dnf install -y 'dnf-command(config-manager)' dnf config-manager --add-repo https://packages.icinga.com/fedora/$(. /etc/os-release; echo "$VERSION_ID")/release ``` <!-- {% endif %} --> <!-- {% if sles %} --> !!! info A paid repository subscription is required for SLES repositories. Get more information on Don't forget to fill in the username and password section with your credentials in the local .repo file. ```bash 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: ```bash source /etc/os-release SUSEConnect -p PackageHub/$VERSIONID/x8664 ``` <!-- {% endif %} --> <!-- {% if opensuse %} --> ```bash 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: ```bash zypper ar https://download.opensuse.org/repositories/server:/monitoring/15.3/server:monitoring.repo ``` <!-- {% endif %} --> <!-- {% if amazon_linux %} --> !!! info A paid repository subscription is required for Amazon Linux repositories. Get more information on Don't forget to fill in the username and password section with your credentials in the local .repo file. ```bash 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 . ```bash yum install epel-release ``` The packages for newer versions of Amazon Linux don't require additional repositories. <!-- {% endif %} --> <!-- {% if 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 <!-- {% else %} --> 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. <!-- {% if centos or rhel or fedora or amazon_linux %} --> !!! tip If you have enabled, the package `icinga2-selinux` is also required. <!-- {% endif %} --> <!-- {% if debian or ubuntu or raspbian %} --> <!-- {% if not icingaDocs %} --> <!-- {% endif %} --> ```bash apt install icinga2 ``` <!-- {% endif %} --> <!-- {% if centos %} --> <!-- {% if not icingaDocs %} --> <!-- {% endif %} --> !!! info Note that installing Icinga 2 is only supported on CentOS 7 as CentOS 8 is

```bash yum install icinga2 systemctl enable icinga2 systemctl start icinga2 ``` <!-- {% endif %} --> <!-- {% if rhel %} --> ```bash dnf install icinga2 systemctl enable icinga2 systemctl start icinga2 ``` ```bash yum install icinga2 systemctl enable icinga2 systemctl start icinga2 ``` <!-- {% endif %} --> <!-- {% if fedora %} --> <!-- {% if not icingaDocs %} --> <!-- {% endif %} --> ```bash dnf install icinga2 systemctl enable icinga2 systemctl start icinga2 ``` <!-- {% endif %} --> <!-- {% if sles or opensuse %} --> <!-- {% if not icingaDocs %} --> <!-- {% endif %} --> ```bash zypper install icinga2 ``` <!-- {% endif %} --> <!-- {% if amazon_linux %} --> <!-- {% if not icingaDocs %} --> <!-- {% endif %} --> ```bash yum install icinga2 systemctl enable icinga2 systemctl start icinga2 ``` <!-- {% endif %} --> 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 . ```bash icinga2 daemon -C ``` !!! tip If you are running into fork errors with systemd enabled distributions, please check the . Without plugins Icinga 2 does not know how to check external services. The 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 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 . 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 chapter for details about how to integrate additional check plugins into your Icinga 2 setup. <!-- {% if debian or ubuntu or raspbian %} --> <!-- {% if not icingaDocs %} --> <!-- {% endif %} --> ```bash apt install monitoring-plugins ``` <!-- {% endif %} --> <!-- {% if centos %} --> <!-- {% if not icingaDocs %} --> <!-- {% endif %} --> The packages for CentOS depend on other packages which are distributed as part of the EPEL repository. ```bash yum install nagios-plugins-all ``` <!-- {% endif %} --> <!-- {% if rhel %} --> <!-- {% if not icingaDocs %} --> <!-- {% endif %} --> The packages for RHEL depend on other packages which are distributed as part of the EPEL repository. ```bash dnf install nagios-plugins-all ``` ```bash yum install nagios-plugins-all ``` <!-- {% endif %} --> <!-- {% if fedora %} --> <!-- {% if not icingaDocs %} --> <!-- {% endif %} --> ```bash dnf install nagios-plugins-all ``` <!-- {% endif %} --> <!-- {% if sles or opensuse %} --> <!-- {% if not icingaDocs %} --> <!-- {% endif %} --> The packages depend on other packages which are distributed as part of the . Please make sure to enable this repository beforehand. ```bash zypper install --recommends monitoring-plugins-all ``` <!-- {% endif %} --> <!-- {% if amazon_linux %} --> <!-- {% if not icingaDocs %} --> <!-- {% endif %} --> The packages for Amazon Linux 2 depend on other packages which are distributed as part of the EPEL repository. ```bash amazon-linux-extras install epel yum install nagios-plugins-all ``` Unfortunately newer versions of Amazon Linux don't provide those plugins, yet. <!-- {% endif %} --> 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

!!! info If you set up a highly available and/or distributed Icinga monitoring environment, please read the chapter as the commands to set up the API are different from setting up a single node setup. See the 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`. ```bash icinga2 api setup ``` Restart Icinga 2 for these changes to take effect. ```bash systemctl restart icinga2 ``` <!-- {% if amazon_linux or centos or debian or rhel or sles or ubuntu %} --> 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 , which synchronizes the data between the Redis server and a database And Icinga Web with the 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. 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. Use your distribution's package manager to install the `icingadb-redis` package as follows: <!-- {% if amazon_linux %} --> <!-- {% if not icingaDocs %} --> <!-- {% endif %} --> ```bash yum install icingadb-redis ``` <!-- {% endif %} --> <!-- {% if centos %} --> <!-- {% if not icingaDocs %} --> <!-- {% endif %} --> !!! info Note that installing Icinga DB Redis is only supported on CentOS 7 as CentOS 8 is EOL. ```bash yum install icingadb-redis ``` <!-- {% endif %} --> <!-- {% if debian or ubuntu %} --> <!-- {% if not icingaDocs %} --> <!-- {% endif %} --> ```bash apt install icingadb-redis ``` <!-- {% endif %} --> <!-- {% if rhel %} --> ```bash dnf install icingadb-redis ``` ```bash yum install icingadb-redis ``` <!-- {% endif %} --> <!-- {% if sles %} --> <!-- {% if not icingaDocs %} --> <!-- {% endif %} --> ```bash zypper install icingadb-redis ``` <!-- {% endif %} --> The `icingadb-redis` package automatically installs the necessary systemd unit files to run Icinga DB

Please run the following command to enable and start its service: ```bash systemctl enable --now icingadb-redis ``` 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: ```bash systemctl restart icingadb-redis ``` With the 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 chapter. !!! important For single-node and high-availability setups, please read the note about the , which is common to all Icinga DB components and generated by the Icinga DB feature. To enable the `icingadb` feature use the following command: ```bash icinga2 feature enable icingadb ``` Restart Icinga 2 for these changes to take effect: ```bash systemctl restart icinga2 ``` 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 <!-- {% if amazon_linux %} --> , <!-- {% endif %} --> <!-- {% if centos %} --> , <!-- {% endif %} --> <!-- {% if debian %} --> , <!-- {% endif %} --> <!-- {% if rhel %} --> , <!-- {% endif %} --> <!-- {% if sles %} --> , <!-- {% endif %} --> <!-- {% if ubuntu %} --> , <!-- {% endif %} --> which will also guide you through the setup of the database and Icinga DB Web. <!-- {% endif %} --> 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` <!-- {% endif %} --><!-- {# end windows else #} --> <!-- {% endif %} --><!-- {# end index else #} -->