and [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2).
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](16-upgrading-icinga-2.md#upgrading-icinga-2).
+
## Setting up Icinga 2 <a id="setting-up-icinga2"></a>
First off you have to install Icinga 2. The preferred way of doing this
FreeBSD | [Upstream](https://www.freshports.org/net-mgmt/icinga2)
OpenBSD | [Upstream](http://ports.su/net/icinga/core2,-main)
ArchLinux | [Upstream](https://aur.archlinux.org/packages/icinga2)
- AlpineLinux | [Upstream](https://pkgs.alpinelinux.org/package/edge/community/x86_64/icinga2)
+ Alpine Linux | [Upstream](https://pkgs.alpinelinux.org/package/edge/community/x86_64/icinga2)
Packages for distributions other than the ones listed above may also be
available. Please contact your distribution packagers.
RHEL/CentOS 7:
- yum install https://packages.icinga.com/epel/7/release/noarch/icinga-rpm-release-7-1.el7.centos.noarch.rpm
+ yum install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm
RHEL/CentOS 6:
- yum install https://packages.icinga.com/epel/6/release/noarch/icinga-rpm-release-6-1.el6.noarch.rpm
+ yum install https://packages.icinga.com/epel/icinga-rpm-release-6-latest.noarch.rpm
-Fedora 25:
+Fedora 26:
- dnf install https://packages.icinga.com/fedora/25/release/noarch/icinga-rpm-release-25-1.fc25.noarch.rpm
+ dnf install https://packages.icinga.com/fedora/icinga-rpm-release-26-latest.noarch.rpm
-Fedora 24:
+Fedora 25:
- dnf install https://packages.icinga.com/fedora/24/release/noarch/icinga-rpm-release-24-1.fc24.noarch.rpm
+ dnf install https://packages.icinga.com/fedora/icinga-rpm-release-25-latest.noarch.rpm
SLES 11:
# zypper ref
+Alpine Linux:
+
+ # echo "http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories
+ # apk update
+
#### RHEL/CentOS EPEL Repository <a id="package-repositories-rhel-epel"></a>
The packages for RHEL/CentOS depend on other packages which are distributed
yum install epel-release
-If you are using RHEL you need enable the `optional` repository and then install
+If you are using RHEL you need to enable the `optional` repository and then install
the [EPEL rpm package](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
#### SLES Security Repository <a id="package-repositories-sles-security"></a>
Icinga 2 requires the `libboost_chrono1_54_0` package from the `SLES 12 SDK` repository. Refer to the SUSE Enterprise
Linux documentation for further information.
+#### Alpine Linux Notes <a id="package-repositories-alpine-notes"></a>
+
+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](https://wiki.alpinelinux.org/wiki/Alpine_Linux_package_management)
+
### Installing Icinga 2 <a id="installing-icinga2"></a>
You can install Icinga 2 by using your distribution's package manager
# pkg install icinga2
+
+Alpine Linux:
+
+ # apk add icinga2
+
### Enabled Features during Installation <a id="installation-enabled-features"></a>
The default installation will enable three features required for a basic
----------------------------------------------|------------------------------------
/etc/icinga2 | Contains Icinga 2 configuration files.
/usr/lib/systemd/system/icinga2.service | The Icinga 2 Systemd service file on systems using Systemd.
- /etc/init.d/icinga2 | The Icinga 2 init script on systems using SysVinit.
+ /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/cache/icinga2 | status.dat/objects.cache, icinga2.debug files.
/var/spool/icinga2 | Used for performance data spool files.
- /var/lib/icinga2 | Icinga 2 state file, cluster log, local CA and configuration files (cluster, api).
/var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
FreeBSD uses slightly different paths:
/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/cache/icinga2 | status.dat/objects.cache, icinga2.debug files.
/var/spool/icinga2 | Used for performance data spool files.
- /var/lib/icinga2 | Icinga 2 state file, cluster log, local CA and configuration files (cluster, api).
/var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
## Setting up Check Plugins <a id="setting-up-check-plugins"></a>
SLES/OpenSUSE | monitoring-plugins | [server:monitoring](https://build.opensuse.org/project/repositories/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
OS X | nagios-plugins | [MacPorts](https://www.macports.org), [Homebrew](https://brew.sh) | /opt/local/libexec or /usr/local/sbin
The recommended way of installing these standard plugins is to use your
# 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.
+
Depending on which directory your plugins are installed into you may need to
update the global `PluginDir` constant in your [Icinga 2 configuration](04-configuring-icinga-2.md#constants-conf).
This constant is used by the check command definitions contained in the Icinga Template Library
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
+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.
-###
systemd Service <a id="systemd-service"></a>
+###
Systemd Service <a id="systemd-service"></a>
-Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The
-Icinga 2 packages automatically install the necessary systemd unit files.
+Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) 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
+The Icinga 2 Systemd service can be (re-)started, reloaded, stopped and also
queried for its current status.
# systemctl status icinga2
If you're stuck with configuration errors, you can manually invoke the
[configuration validation](11-cli-commands.md#config-validation).
-### FreeBSD
+Usually Icinga 2 is a mission critical part of infrastructure and should be
+online at all times. In case of a recoverable crash (e.g. OOM) you may want to
+restart Icinga 2 automatically. With Systemd it is as easy as overriding some
+settings of the Icinga 2 Systemd service by creating
+`/etc/systemd/system/icinga2.service.d/override.conf` with the following
+content:
+
+ [Service]
+ Restart=always
+ RestartSec=1
+ StartLimitInterval=10
+ StartLimitBurst=3
+
+Run `systemctl daemon-reload && systemctl restart icinga2` to apply the changes.
+Now Systemd will always try to restart Icinga 2 (except if you run
+`systemctl stop icinga2`). After three failures in ten seconds it will stop
+trying because you probably have a problem that requires manual intervention.
+
+> **Tip**
+>
+> If you are running into fork errors with Systemd enabled distributions,
+> please check the [troubleshooting chapter](15-troubleshooting.md#check-fork-errors).
+
+### FreeBSD <a id="running-icinga2-freebsd"></a>
On FreeBSD you need to enable icinga2 in your rc.conf
# service icinga2 restart
+
+### SELinux <a id="running-icinga2-selinux"></a>
+
+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 7:
+
+```
+yum install icinga2-selinux
+```
+
+Fedora:
+
+```
+dnf install icinga2-selinux
+```
+
+Read more about SELinux in [this chapter](22-selinux.md#selinux).
+
## Configuration Syntax Highlighting <a id="configuration-syntax-highlighting"></a>
Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano` editors.
Debian/Ubuntu:
- $ apt-get install vim-icinga2 vim-addon-manager
- $ vim-addon-manager -w install icinga2
+ # 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/Fedora:
- $ yum install vim-icinga2
+ # yum install vim-icinga2
SLES/openSUSE:
- $ zypper install vim-icinga2
+ # 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
+ # vim ~/.vimrc
syntax on
Test it:
- $ vim /etc/icinga2/conf.d/templates.conf
+ # vim /etc/icinga2/conf.d/templates.conf
RHEL/CentOS/Fedora:
- $ yum install nano-icinga2
+ # yum install nano-icinga2
SLES/openSUSE:
- $ zypper install nano-icinga2
+ # zypper install nano-icinga2
Copy the `/etc/nanorc` sample file to your home directory.
or Icinga Web 1.x.
There is a separate module for each database backend. At present support for
-both MySQL and PostgreSQL is implemented.
+both MySQL and PostgreSQL has been implemented.
Please choose whether to install [MySQL](02-getting-started.md#configuring-db-ido-mysql) or
[PostgreSQL](02-getting-started.md#configuring-db-ido-postgresql).
# 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 <a id="installing-database-mysql-modules"></a>
The next step is to install the `icinga2-ido-mysql` package using your
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
After enabling the ido-mysql feature you have to restart Icinga 2:
-RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
+RHEL/CentOS 7/Fedora, SLES 12/openSUSE > 12.2, Debian Jessie/Stretch, Ubuntu Xenial:
# systemctl restart icinga2
-Debian/Ubuntu, RHEL/CentOS 6 and SUSE 11:
+Debian/Ubuntu, RHEL/CentOS 6, SLES 11/openSUSE < 12.3 and FreeBSD:
# service icinga2 restart
-FreeBSD:
-
- # service icinga2 restart
+Alpine Linux:
+ # rc-service icinga2 restart
Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver).
# yum install postgresql-server postgresql
# chkconfig postgresql on
+ # service postgresql initdb
# service postgresql start
RHEL/CentOS 7:
# 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 <a id="installing-database-postgresql-modules"></a>
The next step is to install the `icinga2-ido-pgsql` package using your
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.
After enabling the ido-pgsql feature you have to restart Icinga 2:
-RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
+RHEL/CentOS 7/Fedora, SLES 12/openSUSE > 12.2, Debian Jessie/Stretch, Ubuntu Xenial:
# systemctl restart icinga2
-Debian/Ubuntu, RHEL/CentOS 6, SUSE and FreeBSD:
+Debian/Ubuntu, RHEL/CentOS 6, SLES 11/openSUSE < 12.3 and FreeBSD:
# service icinga2 restart
-FreeBSD:
+Alpine Linux:
- # service icinga2 restart
+ # rc-service icinga2 restart
Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver).
# 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 <a id="icinga2-user-interface-firewall-rules"></a>
Example:
Make sure to restart Icinga 2 to activate the configuration.
-RHEL/CentOS 7/Fedora, SLES 12, Debian Jessie/Stretch, Ubuntu Xenial:
+RHEL/CentOS 7/Fedora, SLES 12/openSUSE > 12.2, Debian Jessie/Stretch, Ubuntu Xenial:
# systemctl restart icinga2
-Debian/Ubuntu, RHEL/CentOS 6 and SUSE:
+Debian/Ubuntu, RHEL/CentOS 6, SLES 11/openSUSE < 12.3 and FreeBSD:
# service icinga2 restart
-FreeBSD:
+Alpine Linux:
- # service icinga2 restart
+ # rc-service icinga2 restart
### Installing Icinga Web 2 <a id="installing-icingaweb2"></a>
-Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/02-Installation.md)
+Please consult the [installation documentation](https://www.icinga.com/docs/icingaweb2/latest/doc/02-Installation/)
for further instructions on how to install Icinga Web 2.
-The Icinga 2 API can be defined as [command transport](https://github.com/Icinga/icingaweb2/blob/master/modules/monitoring/doc/commandtransports.md)
+The Icinga 2 API can be defined as [command transport](https://www.icinga.com/docs/icingaweb2/latest/modules/monitoring/doc/05-Command-Transports/)
in Icinga Web 2 >= 2.4.
## Addons <a id="install-addons"></a>
Ensure to include the following in your backups:
* Configuration files in `/etc/icinga2`
-* Runtime files in `/var/lib/icinga2` (the master's CA is stored here as well)
+* 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
projects / icinga2 / blobdiff