diff --git a/doc/02-installation.md b/doc/02-installation.md index 4e0462277..004eaf163 100644 --- a/doc/02-installation.md +++ b/doc/02-installation.md @@ -1,55 +1,26 @@ + # Installation -This tutorial is a step-by-step introduction to installing [Icinga 2](02-installation.md#setting-up-icinga2) -and [Icinga Web 2](02-installation.md#setting-up-icingaweb2). +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](https://icinga.com/get-started/download/#community) +for a full list of available community repositories. + +## Upgrade + 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 +## Add Icinga Package Repository -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. +We recommend using our official repositories. Here's how to add it to your system: -Official repositories ([support matrix](https://icinga.com/subscription/support-details/)): + - Distribution | Repository - ------------------------|--------------------------- - Debian | [Icinga Repository](https://packages.icinga.com/debian/) - Ubuntu | [Icinga Repository](https://packages.icinga.com/ubuntu/) - Raspbian | [Icinga Repository](https://packages.icinga.com/raspbian/). Note that **Raspbian `icinga-buster` is required.** - RHEL/CentOS | [Icinga Repository](https://packages.icinga.com/epel/) - openSUSE | [Icinga Repository](https://packages.icinga.com/openSUSE/) - SLES | [Icinga Repository](https://packages.icinga.com/SUSE/) - -Community repositories: - - Distribution | Repository - ------------------------|--------------------------- - Gentoo | [Upstream](https://packages.gentoo.org/package/net-analyzer/icinga2) - 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) - 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. - -> **Note** -> -> Windows is only supported for agent installations. Please refer -> to the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring-setup-client-windows). - -### 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: +### Debian Repository ```bash apt-get update @@ -66,7 +37,24 @@ DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \ apt-get update ``` -Ubuntu: +#### Debian Backports Repository + +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-get update +``` + + + + +### Ubuntu Repository ```bash apt-get update @@ -82,8 +70,10 @@ wget -O - https://packages.icinga.com/icinga.key | apt-key add - apt-get update ``` + -Raspbian Buster: + +### Raspbian Repository ```bash apt-get update @@ -99,52 +89,17 @@ DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \ apt-get update ``` + -##### Debian Backports Repository - -> **Note**: -> -> This repository is required for Debian Stretch since v2.11. - -Debian Stretch: + +### CentOS Repository ```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-get update +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 ``` -#### RHEL/CentOS/Fedora Repositories - -RHEL/CentOS 8: - -```bash -dnf install https://packages.icinga.com/epel/icinga-rpm-release-8-latest.noarch.rpm -``` - -RHEL/CentOS 7: - -```bash -yum install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm -``` - -RHEL/CentOS 6 x64: - -```bash -yum install https://packages.icinga.com/epel/icinga-rpm-release-6-latest.noarch.rpm -``` - -Fedora 31: - -```bash -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 +The packages for CentOS depend on other packages which are distributed as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL). CentOS 8 additionally needs the PowerTools repository for EPEL: @@ -156,54 +111,89 @@ dnf config-manager --set-enabled powertools dnf install epel-release ``` -CentOS 7/6: +For CentOS 7 run: ```bash 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. + +```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 `optional` and `codeready-builder` repository before installing the [EPEL rpm package](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F). -RHEL 8: +#### RHEL 8 ```bash 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: +#### RHEL 7 ```bash 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: + + +### Fedora Repository ```bash -subscription-manager repos --enable rhel-6-server-optional-rpms -yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-6.noarch.rpm +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/OpenSUSE Repositories + +### SLES Repository -The release repository also provides the required Boost 1.66+ packages -since v2.11. +!!! info -SLES 15/12: + 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. ```bash rpm --import https://packages.icinga.com/icinga.key -zypper ar https://packages.icinga.com/SUSE/ICINGA-release.repo +zypper ar https://packages.icinga.com/subscription/sles/ICINGA-release.repo zypper ref ``` -openSUSE: +You need to additionally add the `PackageHub` repository to fulfill dependencies: + +```bash +source /etc/os-release + +SUSEConnect -p PackageHub/$VERSION_ID/x86_64 +``` + + + +### openSUSE Repository ```bash rpm --import https://packages.icinga.com/icinga.key @@ -212,32 +202,68 @@ zypper ar https://packages.icinga.com/openSUSE/ICINGA-release.repo zypper ref ``` -#### Alpine Linux Repositories +You need to additionally add the `server:monitoring` repository to fulfill dependencies: ```bash -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 +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. + +```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 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) +The packages for Amazon Linux 2 depend on other packages which are distributed +as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL). -### Installing Icinga 2 +```bash +yum install epel-release +``` + + + +### Icinga for Windows Repository +[Icinga for Windows](https://icinga.com/docs/icinga-for-windows/latest/doc/000-Introduction/) 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](https://icinga.com/docs/icinga-for-windows/latest/doc/110-Installation/01-Getting-Started/) + + +## 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. -Debian/Ubuntu: + +!!! tip + If you have [SELinux](22-selinux.md) enabled, the package `icinga2-selinux` is also required. + + + + +#### Debian / Ubuntu / Raspbian + ```bash apt-get install icinga2 ``` + -RHEL/CentOS 8 and Fedora: + +#### CentOS 8 ```bash dnf install icinga2 @@ -245,41 +271,83 @@ systemctl enable icinga2 systemctl start icinga2 ``` -RHEL/CentOS 7: +#### CentOS 7 ```bash yum install icinga2 systemctl enable icinga2 systemctl start icinga2 ``` + -RHEL/CentOS 6: + +#### RHEL 8 + +```bash +dnf install icinga2 +systemctl enable icinga2 +systemctl start icinga2 +``` + +#### RHEL 7 ```bash yum install icinga2 -chkconfig icinga2 on -service icinga2 start +systemctl enable icinga2 +systemctl start icinga2 ``` + -SLES/openSUSE: + + +#### Fedora + +```bash +dnf install icinga2 +systemctl enable icinga2 +systemctl start icinga2 +``` + + + +#### SLES / openSUSE + ```bash zypper install icinga2 ``` + -FreeBSD: + + +#### Amazon Linux 2 + +```bash +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](11-cli-commands.md#config-validation). ```bash -pkg install icinga2 +icinga2 daemon -C ``` -Alpine Linux: +!!! tip -```bash -apk add icinga2 -``` + If you are running into fork errors with systemd enabled distributions, + please check the [troubleshooting chapter](15-troubleshooting.md#check-fork-errors). -## Setting up Check Plugins + +## Set up Check Plugins Without plugins Icinga 2 does not know how to check external services. The [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides @@ -289,251 +357,685 @@ services are working properly. These plugins are required to make the [example configuration](04-configuration.md#configuring-icinga2-overview) 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](02-installation.md#package-repositories-rhel-epel) | /usr/lib64/nagios/plugins -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 - -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](04-configuration.md#constants-conf). 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](05-service-monitoring.md#service-monitoring-plugins) chapter for details about how to integrate -> additional check plugins into your Icinga 2 setup. +!!! tip -### Debian/Ubuntu + 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 + ```bash apt-get install monitoring-plugins ``` + -### RHEL/CentOS/Fedora + + +#### CentOS + +The packages for CentOS depend on other packages which are distributed as part of the EPEL repository. -The packages for RHEL/CentOS depend on other packages which are distributed -as part of the [EPEL repository](02-installation.md#package-repositories-rhel-epel). - -RHEL/CentOS 8: +#### CentOS 8 ```bash dnf install nagios-plugins-all ``` -RHEL/CentOS 7/6: +#### CentOS 7 ```bash yum install nagios-plugins-all ``` + -Fedora: + + +#### RHEL + +The packages for RHEL depend on other packages which are distributed as part of the EPEL repository. + +#### RHEL 8 ```bash dnf install nagios-plugins-all ``` -### SLES/openSUSE +#### RHEL 7 -The packages for SLES/OpenSUSE depend on other packages which are distributed +```bash +yum install nagios-plugins-all +``` + + + + +#### Fedora + +```bash +dnf install nagios-plugins-all +``` + + + + +#### SLES / openSUSE + +The packages depend on other packages which are distributed as part of the [server:monitoring repository](https://build.opensuse.org/project/repositories/server:monitoring). Please make sure to enable this repository beforehand. ```bash zypper install monitoring-plugins ``` + -### FreeBSD + + +#### Amazon Linux 2 + +The packages for Amazon Linux 2 depend on other packages which are distributed as part of the EPEL repository. ```bash -pkg install monitoring-plugins +amazon-linux-extras install epel + +yum install nagios-plugins-all +``` + + +## 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](#ido-with-mysql) or [PostgreSQL](#ido-with-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 + +```bash +apt-get install mariadb-server mariadb-client + +mysql_secure_installation +``` + + + + +#### CentOS + + +#### CentOS 8 +```bash +dnf install mariadb-server mariadb +systemctl enable mariadb +systemctl start mariadb +mysql_secure_installation ``` -### Alpine Linux +#### CentOS 7 +```bash +yum install mariadb-server mariadb +systemctl enable mariadb +systemctl start mariadb +mysql_secure_installation +``` + + + + +#### RHEL + +#### RHEL 8 +```bash +dnf install mariadb-server mariadb +systemctl enable mariadb +systemctl start mariadb +mysql_secure_installation +``` + +#### RHEL 7 +```bash +yum install mariadb-server mariadb +systemctl enable mariadb +systemctl start mariadb +mysql_secure_installation +``` + + + + +#### SLES / openSUSE + +```bash +zypper install mariadb mariadb-client +systemctl enable mariadb +systemctl start mariadb +mysql_secure_installation +``` + + + + +#### Amazon Linux 2 + +```bash +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 + +```bash +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 +```bash +dnf install icinga2-ido-mysql +``` + +#### CentOS 7 +```bash +yum install icinga2-ido-mysql +``` + + + + +#### RHEL + +#### RHEL 8 +```bash +dnf install icinga2-ido-mysql +``` + +#### RHEL 7 +```bash +yum install icinga2-ido-mysql +``` + + + + +#### SLES / openSUSE + +```bash +zypper install icinga2-ido-mysql +``` + + + + +#### Amazon Linux 2 + +```bash +yum install icinga2-ido-mysql +``` + + +#### Set up MySQL database + +Set up a MySQL database for Icinga 2: ```bash -apk add monitoring-plugins +# 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 ``` -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. +Please note that the example above uses the very simple password 'icinga' (in `IDENTIFIED BY 'icinga'`). +Please choose a better password for your installation. -## Running Icinga 2 +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. -### 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. +```bash +mysql -u icinga -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql ``` -The `systemctl` command supports the following actions: +#### Enable the IDO MySQL feature - 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`) +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. -Examples: +All available attributes are explained in the +[IdoMysqlConnection object](09-object-types.md#objecttype-idomysqlconnection) +chapter. +Enable the `ido-mysql` feature configuration file using the `icinga2` command: + +```bash +# icinga2 feature enable ido-mysql +Module 'ido-mysql' was enabled. +Make sure to restart Icinga 2 for these changes to take effect. ``` -systemctl enable icinga2 +Restart Icinga 2. + +```bash 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](11-cli-commands.md#config-validation). +### IDO with PostgreSQL + +#### Install PostgreSQL server + + + +#### Debian / Ubuntu + +```bash +apt-get install postgresql +``` + + + + +#### CentOS + + +#### CentOS 8 +```bash +dnf install postgresql-server postgresql +postgresql-setup initdb +systemctl enable postgresql +systemctl start postgresql +``` + +#### CentOS 7 +```bash +yum install postgresql-server postgresql +postgresql-setup initdb +systemctl enable postgresql +systemctl start postgresql +``` + + + + +#### RHEL + +#### RHEL 8 +```bash +dnf install postgresql-server postgresql +postgresql-setup initdb +systemctl enable postgresql +systemctl start postgresql +``` + +#### RHEL 7 +```bash +yum install postgresql-server postgresql +postgresql-setup initdb +systemctl enable postgresql +systemctl start postgresql +``` + + + + +#### SLES / openSUSE + +```bash +zypper install postgresql postgresql-server +chkconfig postgresql on +service postgresql initdb +service postgresql start +``` + + + + +#### Amazon Linux 2 + +```bash +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 + +```bash +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 +```bash +dnf install icinga2-ido-pgsql +``` + +#### CentOS 7 +```bash +yum install icinga2-ido-pgsql +``` + + + + +#### RHEL + +#### RHEL 8 +```bash +dnf install icinga2-ido-pgsql +``` + +#### RHEL 7 +```bash +yum install icinga2-ido-pgsql +``` + + + + +#### SLES / openSUSE + +```bash +zypper install icinga2-ido-pgsql +``` + + + + +#### Amazon Linux 2 + +```bash +yum install icinga2-ido-pgsql +``` + + +#### Set up PostgreSQL database + +Set up a PostgreSQL database for Icinga 2: ```bash -icinga2 daemon -C +cd /tmp +sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'" +sudo -u postgres createdb -O icinga -E UTF8 icinga ``` -> **Tip** -> -> If you are running into fork errors with systemd enabled distributions, -> please check the [troubleshooting chapter](15-troubleshooting.md#check-fork-errors). +!!! note -### Init Script + It is assumed here that your locale is set to utf-8, you may run into problems otherwise. -Icinga 2's init script is installed in `/etc/init.d/icinga2` (`/usr/local/etc/rc.d/icinga2` on FreeBSD) by default: +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`. ``` -/etc/init.d/icinga2 +# icinga +local icinga icinga md5 +host icinga icinga 127.0.0.1/32 md5 +host icinga icinga ::1/128 md5 -Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status} +# "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 ``` -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 +Restart PostgreSQL: ```bash -sysrc icinga2_enable=yes - -service icinga2 restart +systemctl restart postgresql ``` -### 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: +After creating the database and permissions you need to import the IDO database +schema using the following command: ```bash -dnf install icinga2-selinux +export PGPASSWORD=icinga +psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql ``` -RHEL/CentOS 7: +#### 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](09-object-types.md#objecttype-idopgsqlconnection) +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. ```bash -yum install icinga2-selinux +systemctl restart icinga2 ``` -Read more about SELinux in [this chapter](22-selinux.md#selinux). +### Icinga DB -## Configuration Syntax Highlighting +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. + +#### Configue Icinga DB + +First, make sure to setup Icinga DB itself and its database backends (Redis and MySQL) by following the [installation instructions](https://icinga.com/docs/icingadb/latest/doc/02-Installation/). + +#### Enable 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](09-object-types.md#objecttype-icingadb) +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. + +```bash +systemctl restart icinga2 +``` + +## Set up Icinga 2 REST API + +Icinga Web 2 requires the [REST API](12-icinga2-api.md#icinga2-api-setup) to send actions +(reschedule check, etc.) and query object details. + +You can run the CLI command `icinga2 api setup` to enable the +`api` [feature](11-cli-commands.md#enable-features) 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: + +```bash +icinga2 api setup +``` + +Edit the `api-users.conf` file and add a new ApiUser object. Specify the [permissions](12-icinga2-api.md#icinga2-api-permissions) +attribute with minimal permissions required by Icinga Web 2. + +``` +object ApiUser "icingaweb2" { + password = "Wijsn8Z9eRs5E25d" + permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ] +} +``` + +Restart Icinga 2 to activate the configuration. + +```bash +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](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/). + +!!! 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. -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 +### Using Vim Install the package `vim-icinga2` with your distribution's package manager. -Debian/Ubuntu: - -``` + + +#### Debian / Ubuntu / Raspbian + +```bash 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: + + +#### CentOS + +#### CentOS 8 ```bash dnf install vim-icinga2 ``` -RHEL/CentOS 7/6: - +#### CentOS 7 ```bash yum install vim-icinga2 ``` + -SLES/openSUSE: + + +#### RHEL + +#### RHEL 8 +```bash +dnf install vim-icinga2 +``` +#### RHEL 7 +```bash +yum install vim-icinga2 +``` + + + + +#### Fedora + +```bash +dnf install vim-icinga2 +``` + + + + +#### SLES / openSUSE + ```bash zypper install vim-icinga2 ``` + -Alpine Linux: - + + +#### Amazon Linux 2 + ```bash -apk add icinga2-vim +yum install vim-icinga2 ``` + Ensure that syntax highlighting is enabled e.g. by editing the user's `vimrc` configuration file: @@ -552,31 +1054,74 @@ vim /etc/icinga2/conf.d/templates.conf ![Vim with syntax highlighting](images/installation/vim-syntax.png "Vim with Icinga 2 syntax highlighting") -### Configuration Syntax Highlighting using Nano +### Using Nano Install the package `nano-icinga2` with your distribution's package manager. -Debian/Ubuntu: - + + +#### Debian / Ubuntu / Raspbian + **Note:** The syntax files are installed with the `icinga2-common` package already. + -RHEL/CentOS 8 and Fedora: + + +#### CentOS + +#### CentOS 8 ```bash dnf install nano-icinga2 ``` -RHEL/CentOS 7/6: - +#### CentOS 7 ```bash yum install nano-icinga2 ``` + -SLES/openSUSE: + + +#### RHEL + +#### RHEL 8 +```bash +dnf install nano-icinga2 +``` +#### RHEL 7 +```bash +yum install nano-icinga2 +``` + + + + +#### Fedora + +```bash +dnf install nano-icinga2 +``` + + + + +#### SLES / openSUSE + ```bash zypper install nano-icinga2 ``` + + + + +#### Amazon Linux 2 + +```bash +yum install nano-icinga2 +``` + Copy the `/etc/nanorc` sample file to your home directory. @@ -601,460 +1146,6 @@ nano /etc/icinga2/conf.d/templates.conf ![Nano with syntax highlighting](images/installation/nano-syntax.png "Nano with Icinga 2 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](02-installation.md#icingadb). -> 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: - -```bash -apt-get install mariadb-server mariadb-client - -mysql_secure_installation -``` - -RHEL/CentOS and Fedora: - -```bash -yum install mariadb-server mariadb -systemctl enable mariadb -systemctl start mariadb -mysql_secure_installation -``` - -SUSE: - -```bash -zypper install mysql mysql-client -chkconfig mysqld on -service mysqld start -``` - -FreeBSD: - -```bash -pkg install mysql56-server -sysrc mysql_enable=yes -service mysql-server restart -mysql_secure_installation -``` - -Alpine Linux: - -```bash -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: - -```bash -apt-get install icinga2-ido-mysql -``` - -RHEL/CentOS: - -```bash -yum install icinga2-ido-mysql -``` - -SUSE: - -```bash -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 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. - -![setting up the database on CentOS 7](images/installation/mariadb-centos7.png "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 icinga password into the prompt when asked. - -```bash -mysql -u icinga -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](09-object-types.md#objecttype-idomysqlconnection) -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. - -```bash -systemctl restart icinga2 -``` - -Alpine Linux: - -```bash -rc-service icinga2 restart -``` - -Continue with the [webserver setup](02-installation.md#icinga2-user-interface-webserver). - -### Configuring DB IDO PostgreSQL - -#### Installing PostgreSQL database server - -Debian/Ubuntu: - -```bash -apt-get install postgresql -``` - -RHEL/CentOS: - -```bash -yum install postgresql-server postgresql -postgresql-setup initdb -systemctl enable postgresql -systemctl start postgresql -``` - -SUSE: - -```bash -zypper install postgresql postgresql-server -chkconfig postgresql on -service postgresql initdb -service postgresql start -``` - -FreeBSD: - -```bash -pkg install postgresql93-server -sysrc postgresql_enable=yes -service postgresql initdb -service postgresql start -``` - -Alpine Linux: - -```bash -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: - -```bash -apt-get install icinga2-ido-pgsql -``` - -RHEL/CentOS: - -```bash -yum install icinga2-ido-pgsql -``` - -SUSE: - -```bash -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: - -```bash -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 -``` - -```bash -systemctl restart postgresql -``` - - -After creating the database and permissions you need to import the IDO database -schema using the following command: - -```bash -export PGPASSWORD=icinga -psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql -``` - -![importing the Icinga 2 IDO schema](images/installation/postgr-import-ido.png "Importing the Icinga 2 IDO schema on Debian Jessie") - - -#### 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](09-object-types.md#objecttype-idopgsqlconnection) -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. - -```bash -systemctl restart icinga2 -``` - -Alpine Linux: - -```bash -rc-service icinga2 restart -``` - -Continue with the [webserver setup](02-installation.md#icinga2-user-interface-webserver). - -### 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](https://letsencrypt.org/). - -Debian/Ubuntu: - -```bash -apt-get install apache2 -``` - -RHEL/CentOS/Fedora: - -```bash -yum install httpd -systemctl enable httpd -systemctl start httpd -``` - -SUSE: - -```bash -zypper install apache2 -chkconfig apache2 on -service apache2 start -``` - -FreeBSD (Nginx, but you could also use the `apache24` package): - -```bash -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: - -```bash -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: - -```bash -firewall-cmd --add-service=http -firewall-cmd --permanent --add-service=http -``` - -iptables: - -```bash -iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT -service iptables save -``` - -FreeBSD: -Please consult the [FreeBSD Handbook](https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/firewalls.html) 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](12-icinga2-api.md#icinga2-api-setup) -to send actions (reschedule check, etc.) and query object details. - -You can run the CLI command `icinga2 api setup` to enable the -`api` [feature](11-cli-commands.md#enable-features) 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: - -```bash -icinga2 api setup -``` - -Edit the `api-users.conf` file and add a new ApiUser object. Specify the [permissions](12-icinga2-api.md#icinga2-api-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. - -```bash -systemctl restart icinga2 -``` - -Alpine Linux: - -```bash -rc-service icinga2 restart -``` - -### Installing Icinga Web 2 - -Please consult the [Icinga Web 2 documentation](https://icinga.com/docs/icingaweb2/latest/) -for further instructions on how to install Icinga Web 2. - -If you decided on using Icinga DB, consult the [Icinga DB Web documentation](https://icinga.com/docs/icingadb/latest/icingadb-web/doc/01-About/) 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](13-addons.md#addons) chapter. - ## Installation Overview ### Enabled Features during Installation @@ -1097,25 +1188,11 @@ By default Icinga 2 uses the following files and directories: /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. +## 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](13-addons.md#addons) chapter. ## Backup @@ -1126,7 +1203,7 @@ Ensure to include the following in your backups: * Runtime files in `/var/lib/icinga2` * Optional: IDO database backup -## Backup: Database +### Database Backup MySQL/MariaDB: @@ -1135,50 +1212,5 @@ MySQL/MariaDB: PostgreSQL: * [Documentation](https://www.postgresql.org/docs/9.3/static/backup.html) - -## 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](https://icinga.com/docs/icingadb/latest/doc/02-Installation/). - -#### 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](09-object-types.md#objecttype-icingadb) -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. - -```bash -systemctl restart icinga2 -``` - -Alpine Linux: - -```bash -rc-service icinga2 restart -``` - -Continue with the [webserver setup](02-installation.md#icinga2-user-interface-webserver). + + diff --git a/doc/02-installation.md.d/01-Debian.md b/doc/02-installation.md.d/01-Debian.md new file mode 100644 index 000000000..d3e31434c --- /dev/null +++ b/doc/02-installation.md.d/01-Debian.md @@ -0,0 +1,3 @@ +# Install Icinga 2 on Debian + + diff --git a/doc/02-installation.md.d/02-Ubuntu.md b/doc/02-installation.md.d/02-Ubuntu.md new file mode 100644 index 000000000..aa099d87b --- /dev/null +++ b/doc/02-installation.md.d/02-Ubuntu.md @@ -0,0 +1,3 @@ +# Install Icinga 2 on Ubuntu + + diff --git a/doc/02-installation.md.d/03-Raspbian.md b/doc/02-installation.md.d/03-Raspbian.md new file mode 100644 index 000000000..fc48d6c67 --- /dev/null +++ b/doc/02-installation.md.d/03-Raspbian.md @@ -0,0 +1,3 @@ +# Install Icinga 2 on Raspbian + + diff --git a/doc/02-installation.md.d/04-Fedora.md b/doc/02-installation.md.d/04-Fedora.md new file mode 100644 index 000000000..1f12276b5 --- /dev/null +++ b/doc/02-installation.md.d/04-Fedora.md @@ -0,0 +1,2 @@ + + diff --git a/doc/02-installation.md.d/05-CentOS.md b/doc/02-installation.md.d/05-CentOS.md new file mode 100644 index 000000000..4d766b21c --- /dev/null +++ b/doc/02-installation.md.d/05-CentOS.md @@ -0,0 +1,3 @@ +# Install Icinga 2 on CentOS + + diff --git a/doc/02-installation.md.d/06-RHEL.md b/doc/02-installation.md.d/06-RHEL.md new file mode 100644 index 000000000..568251ad0 --- /dev/null +++ b/doc/02-installation.md.d/06-RHEL.md @@ -0,0 +1,3 @@ +# Install Icinga 2 on RHEL + + diff --git a/doc/02-installation.md.d/07-OpenSUSE.md b/doc/02-installation.md.d/07-OpenSUSE.md new file mode 100644 index 000000000..347831e8a --- /dev/null +++ b/doc/02-installation.md.d/07-OpenSUSE.md @@ -0,0 +1,3 @@ +# Install Icinga 2 on openSUSE + + diff --git a/doc/02-installation.md.d/08-SLES.md b/doc/02-installation.md.d/08-SLES.md new file mode 100644 index 000000000..aa2646d6f --- /dev/null +++ b/doc/02-installation.md.d/08-SLES.md @@ -0,0 +1,3 @@ +# Install Icinga 2 on SLES + + diff --git a/doc/02-installation.md.d/09-Amazon-Linux.md b/doc/02-installation.md.d/09-Amazon-Linux.md new file mode 100644 index 000000000..ec1d9866d --- /dev/null +++ b/doc/02-installation.md.d/09-Amazon-Linux.md @@ -0,0 +1,3 @@ +# Install Icinga 2 on Amazon Linux + + diff --git a/doc/02-installation.md.d/10-Windows.md b/doc/02-installation.md.d/10-Windows.md new file mode 100644 index 000000000..64bc6877c --- /dev/null +++ b/doc/02-installation.md.d/10-Windows.md @@ -0,0 +1,3 @@ +# Install Icinga 2 on Windows + + diff --git a/doc/03-monitoring-basics.md b/doc/03-monitoring-basics.md index 98e97672c..342442cfb 100644 --- a/doc/03-monitoring-basics.md +++ b/doc/03-monitoring-basics.md @@ -1938,7 +1938,7 @@ The check command parameters for ITL provided plugin check command definitions a In order to practice passing command parameters you should [integrate your own plugin](03-monitoring-basics.md#command-plugin-integration). -The following example will use `check_mysql` provided by the [Monitoring Plugins installation](02-installation.md#setting-up-check-plugins). +The following example will use `check_mysql` provided by the [Monitoring Plugins](https://www.monitoring-plugins.org/). Define the default check command custom variables, for example `mysql_user` and `mysql_password` (freely definable naming schema) and optional their default threshold values. You can diff --git a/doc/04-configuration.md b/doc/04-configuration.md index 632cd2776..e16c21060 100644 --- a/doc/04-configuration.md +++ b/doc/04-configuration.md @@ -196,7 +196,7 @@ The `constants.conf` configuration file can be used to define global constants. By default, you need to make sure to set these constants: -* The `PluginDir` constant must be set to the path where the [Monitoring Project plugins](02-installation.md#setting-up-check-plugins) are installed. +* The `PluginDir` constant must be set to the path where the [Monitoring Project](https://www.monitoring-plugins.org/) plugins are installed. This constant is used by a number of [built-in check command definitions](10-icinga-template-library.md#icinga-template-library). * The `NodeName` constant defines your local node name. Should be set to FQDN which is the default @@ -304,7 +304,7 @@ service apply rule defined in [services.conf](04-configuration.md#services-conf) * define notification types (`mail`) and set the groups attribute. This will be used by notification apply rules in [notifications.conf](04-configuration.md#notifications-conf). -If you've installed [Icinga Web 2](02-installation.md#setting-up-icingaweb2), you can +If you've installed [Icinga Web 2](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/), you can uncomment the http vhost attributes and reload Icinga 2. The apply rules in [services.conf](04-configuration.md#services-conf) will automatically generate a new service checking the `/icingaweb2` URI using the `http` @@ -515,8 +515,7 @@ Look into [notifications.conf](04-configuration.md#notifications-conf) how this for applying notifications to hosts and services using their type and user attributes. -Don't forget to install the [check plugins](02-installation.md#setting-up-check-plugins) required by -the hosts and services and their check commands. +Don't forget to install the check plugins required by the hosts and services and their check commands. Further details on the monitoring configuration can be found in the [monitoring basics](03-monitoring-basics.md#monitoring-basics) chapter. diff --git a/doc/06-distributed-monitoring.md b/doc/06-distributed-monitoring.md index ca47bccb5..7d28a9ba2 100644 --- a/doc/06-distributed-monitoring.md +++ b/doc/06-distributed-monitoring.md @@ -44,8 +44,8 @@ simple examples. In case you are planning a huge cluster setup with multiple levels and lots of satellites and agents, read on -- we'll deal with these cases later on. -The installation on each system is the same: You need to install the -[Icinga 2 package](02-installation.md#setting-up-icinga2) and the required [plugins](02-installation.md#setting-up-check-plugins). +The installation on each system is the same: Follow the [installation instructions](02-installation.md) +for the Icinga 2 package and the required check plugins. The required configuration steps are mostly happening on the command line. You can also [automate the setup](06-distributed-monitoring.md#distributed-monitoring-automation). @@ -238,9 +238,8 @@ This section explains how to install a central single master node using the `node wizard` command. If you prefer to do an automated installation, please refer to the [automated setup](06-distributed-monitoring.md#distributed-monitoring-automation) section. -Install the [Icinga 2 package](02-installation.md#setting-up-icinga2) and setup -the required [plugins](02-installation.md#setting-up-check-plugins) if you haven't done -so already. +Follow the [installation instructions](02-installation.md) for the Icinga 2 package and the required +check plugins if you haven't done so already. **Note**: Windows is not supported for a master node setup. @@ -304,7 +303,7 @@ Now restart your Icinga 2 daemon to finish the installation! ``` You can verify that the CA public and private keys are stored in the `/var/lib/icinga2/ca` directory. -Keep this path secure and include it in your [backups](02-installation.md#install-backup). +Keep this path secure and include it in your backups. In case you lose the CA private key you have to generate a new CA for signing new agent/satellite certificate requests. You then have to also re-create new signed certificates for all @@ -512,9 +511,8 @@ Icinga 2 on the master node must be running and accepting connections on port `5 Please ensure that you've run all the steps mentioned in the [agent/satellite section](06-distributed-monitoring.md#distributed-monitoring-setup-agent-satellite). -Install the [Icinga 2 package](02-installation.md#setting-up-icinga2) and setup -the required [plugins](02-installation.md#setting-up-check-plugins) if you haven't done -so already. +Follow the [installation instructions](02-installation.md) for the Icinga 2 package and the required +check plugins if you haven't done so already. The next step is to run the `node wizard` CLI command. @@ -3187,7 +3185,7 @@ to pick the authoritative running one and copy the following content: If you need already deployed config packages from the Director, or synced cluster zones, you can also sync the entire `/var/lib/icinga2/api/packages` directory. This directory should also be -included in your [backup strategy](02-installation.md#install-backup). +included in your backup strategy. Do **not** sync `/var/lib/icinga2/api/zones*` manually - this is an internal directory and handled by the Icinga cluster config sync itself. diff --git a/doc/07-agent-based-monitoring.md b/doc/07-agent-based-monitoring.md index 7a1a73afa..a5a466e11 100644 --- a/doc/07-agent-based-monitoring.md +++ b/doc/07-agent-based-monitoring.md @@ -64,7 +64,7 @@ an arbitrary plugin command line. The output and exit code is returned and used by the core. The `check_by_ssh` plugin takes care of this. It is available in the -[Monitoring Plugins package](02-installation.md#setting-up-check-plugins). +[Monitoring Plugins](https://www.monitoring-plugins.org/) package. For your convenience, the Icinga template library provides the [by_ssh](10-icinga-template-library.md#plugin-check-command-by-ssh) CheckCommand already. @@ -171,7 +171,7 @@ A more advanced example with better arguments is shown in [this blogpost](https: ## SNMP The SNMP daemon runs on the remote system and answers SNMP queries by plugin scripts. -The [Monitoring Plugins package](02-installation.md#setting-up-check-plugins) provides +The [Monitoring Plugins](https://www.monitoring-plugins.org/) package provides the `check_snmp` plugin binary, but there are plenty of [existing plugins](05-service-monitoring.md#service-monitoring-plugins) for specific use cases already around, for example monitoring Cisco routers. @@ -483,5 +483,3 @@ Community examples: * [Icinga 2 check_wmi_plus example by 18pct](https://18pct.com/icinga2-check_wmi_plus-example/) * [Agent-less monitoring with WMI](https://www.devlink.de/linux/icinga2-nagios-agentless-monitoring-von-windows/) - - diff --git a/doc/14-features.md b/doc/14-features.md index 392f98aa6..3007c0a5c 100644 --- a/doc/14-features.md +++ b/doc/14-features.md @@ -63,7 +63,7 @@ Requirements: * IcingaDB service requires Redis and MySQL/MariaDB server * Icinga Web module -Consult the [Icinga DB section](02-installation.md#configuring-icinga-db) in the installation chapter for setup instructions. +Consult the [Icinga DB installation documentation](https://icinga.com/docs/icinga-db/latest/doc/02-Installation/) for setup instructions. We will deprecate the IDO and shift towards the Icinga DB as main backend, but we will not drop the IDO for now. @@ -77,8 +77,8 @@ The IDO (Icinga Data Output) feature for Icinga 2 takes care of exporting all configuration and status information into a database. The IDO database is used by Icinga Web 2 as data backend. -Details on the installation can be found in the [Configuring DB IDO](02-installation.md#configuring-db-ido-mysql) -chapter. Details on the configuration can be found in the +Details on the installation can be found in the "Prepare for Icinga Web 2" chapter +of the [Installation docs](02-installation.md). Details on the configuration can be found in the [IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection) and [IdoPgsqlConnection](09-object-types.md#objecttype-idopgsqlconnection) object configuration documentation. @@ -705,7 +705,7 @@ Functionality exists to modify the built in OpenTSDB metric names that the plugi writes to. By default this is `icinga.host` and `icinga.service.`. These prefixes can be modified as necessary to any arbitary string. The prefix -configuration also supports Icinga macros, so if you rather use `` +configuration also supports Icinga macros, so if you rather use `` or any other variable instead of `` you may do so. To configure OpenTSDB metric name prefixes, create or modify the `host_template` and/or @@ -847,16 +847,16 @@ what attributes are available with links to each object type. > Ensure you do not name your custom attributes with a dot in the name. > Dots located inside a macro tell the interpreter to expand a > dictionary. -> +> > Do not do this in your object configuration: -> +> > `vars["my.attribute"]` -> +> > as you will be unable to reference `my.attribute` because it is not a > dictionary. -> +> > Instead, use underscores or another character: -> +> > `vars.my_attribute` or `vars["my_attribute"]` @@ -1069,7 +1069,7 @@ Livestatus. > > Only install the Livestatus feature if your web interface or addon requires > you to do so. -> [Icinga Web 2](02-installation.md#setting-up-icingaweb2) does not need +> [Icinga Web 2](https://icinga.com/docs/icinga-web-2/latest/doc/02-Installation/) does not need > Livestatus. Details on the available tables and attributes with Icinga 2 can be found diff --git a/doc/15-troubleshooting.md b/doc/15-troubleshooting.md index f4003fb82..727c56c34 100644 --- a/doc/15-troubleshooting.md +++ b/doc/15-troubleshooting.md @@ -856,7 +856,7 @@ $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost: "icinga2-agent1.localdomain" ``` -Whenever a notification command failed to execute, you can fetch the output as well. +Whenever a notification command failed to execute, you can fetch the output as well. ## Feature Troubleshooting @@ -1745,7 +1745,7 @@ object Endpoint "icinga-satellite2.localdomain" { // That's no different to what is explained in the docs as basic zone trust hierarchy, and is intentionally managed outside in zones.conf there. object Zone "master" { - endpoints = [ "icinga-master1.localdomain", "icinga-master2.localdomain" ] + endpoints = [ "icinga-master1.localdomain", "icinga-master2.localdomain" ] } object Zone "satellite" { @@ -1754,21 +1754,21 @@ object Zone "satellite" { } ``` -Prepare the above configuration on all affected nodes, satellites are likely uptodate already. +Prepare the above configuration on all affected nodes, satellites are likely uptodate already. Then continue with the steps below. > * backup your database, just to be on the safe side > * create all non-external Zone/Endpoint-Objects on all related Icinga Master/Satellite-Nodes (manually in your local zones.conf) > * while doing so please do NOT restart Icinga, no deployments > * change the type in the Director DB: -> +> > ```sql > UPDATE icinga_zone SET object_type = 'external_object' WHERE object_type = 'object'; > UPDATE icinga_endpoint SET object_type = 'external_object' WHERE object_type = 'object'; > ``` -> +> > * render and deploy a new configuration in the Director. It will state that there are no changes. Ignore it, deploy anyways -> +> > That's it. All nodes should automatically restart, triggered by the deployed configuration via cluster protocol. @@ -1788,7 +1788,7 @@ certificate's CN, the master will deny all events. > **Tip** > -> [Icinga Web 2](02-installation.md#setting-up-icingaweb2) provides a dashboard view +> [Icinga Web 2](https://icinga.com/docs/icinga-web-2/latest/doc/01-About/) provides a dashboard view > for overdue check results. Enable the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) on the master diff --git a/doc/16-upgrading-icinga-2.md b/doc/16-upgrading-icinga-2.md index b6a7d500c..f90e61192 100644 --- a/doc/16-upgrading-icinga-2.md +++ b/doc/16-upgrading-icinga-2.md @@ -120,11 +120,12 @@ details, please continue reading in [this issue](https://github.com/Icinga/icing Distribution | Repository providing Boost Dependencies ---------------------|------------------------------------- -RHEL/CentOS 7 | [EPEL repository](02-installation.md#package-repositories-rhel-epel) +CentOS 7 | [EPEL repository](02-installation.md#centos-repository) +RHEL 7 | [EPEL repository](02-installation.md#rhel-repository) RHEL/CentOS 6 x64 | [packages.icinga.com](https://packages.icinga.com) Fedora | Fedora Upstream Debian 10 Buster | Debian Upstream -Debian 9 Stretch | [Backports repository](02-installation.md#package-repositories-debian-backports) **New since 2.11** +Debian 9 Stretch | [Backports repository](02-installation.md#debian-backports-repository) **New since 2.11** Debian 8 Jessie | [packages.icinga.com](https://packages.icinga.com) Ubuntu 18 Bionic | [packages.icinga.com](https://packages.icinga.com) Ubuntu 16 Xenial | [packages.icinga.com](https://packages.icinga.com) diff --git a/doc/21-development.md b/doc/21-development.md index 2ae7f398b..cb3fcf262 100644 --- a/doc/21-development.md +++ b/doc/21-development.md @@ -539,7 +539,7 @@ on GitHub and mention that you're testing the snapshot packages. #### RHEL/CentOS -2.11+ requires the [EPEL repository](02-installation.md#package-repositories-rhel-epel) for Boost 1.66+. +2.11+ requires the EPEL repository for Boost 1.66+. In addition to that, the `icinga-rpm-release` package already provides the `icinga-snapshot-builds` repository but it is disabled by default. @@ -1436,7 +1436,7 @@ vim /usr/local/icinga2/etc/icinga2/conf.d/api-users.conf Debian Buster doesn't need updated Boost packages from packages.icinga.com, the distribution already provides 1.66+. For older versions such as Stretch, -include the release repository for packages.icinga.com as shown in the [setup instructions](02-installation.md#package-repositories-debian-ubuntu-raspbian). +include the release repository for packages.icinga.com as shown in the [setup instructions](02-installation.md). ```bash docker run -ti debian:buster bash @@ -2696,4 +2696,3 @@ the duplicate import in your `~/.gdbinit` file. ``` RuntimeError: pretty-printer already registered: libstdc++-v6 ``` - diff --git a/doc/images/installation/mariadb-centos7.png b/doc/images/installation/mariadb-centos7.png deleted file mode 100644 index 7ef54263b..000000000 Binary files a/doc/images/installation/mariadb-centos7.png and /dev/null differ diff --git a/doc/images/installation/postgr-import-ido.png b/doc/images/installation/postgr-import-ido.png deleted file mode 100644 index 6008b6710..000000000 Binary files a/doc/images/installation/postgr-import-ido.png and /dev/null differ