diff --git a/doc/02-getting-started.md b/doc/02-getting-started.md index 682ae30b1..244a797de 100644 --- a/doc/02-getting-started.md +++ b/doc/02-getting-started.md @@ -32,56 +32,79 @@ available. Please contact your distribution packagers. ### Package Repositories You need to add the Icinga repository to your package management configuration. -Below is a list with examples for the various distributions. +The following commands must be executed with `root` permissions unless noted otherwise. Debian: - # wget -O - https://packages.icinga.com/icinga.key | apt-key add - - # echo 'deb https://packages.icinga.com/debian icinga-stretch main' >/etc/apt/sources.list.d/icinga.list - # apt-get update +``` +apt-get -y install apt-transport-https + +wget -O - https://packages.icinga.com/icinga.key | apt-key add - +echo 'deb https://packages.icinga.com/debian icinga-stretch main' >/etc/apt/sources.list.d/icinga.list +apt-get update +``` Ubuntu: - # wget -O - https://packages.icinga.com/icinga.key | apt-key add - - # echo 'deb https://packages.icinga.com/ubuntu icinga-xenial main' >/etc/apt/sources.list.d/icinga.list - # apt-get update +``` +apt-get -y install apt-transport-https + +wget -O - https://packages.icinga.com/icinga.key | apt-key add - +echo 'deb https://packages.icinga.com/ubuntu icinga-xenial main' >/etc/apt/sources.list.d/icinga.list +apt-get update +``` RHEL/CentOS 7: - yum install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.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/icinga-rpm-release-6-latest.noarch.rpm +``` +yum install https://packages.icinga.com/epel/icinga-rpm-release-6-latest.noarch.rpm +``` + +Fedora 27: + +``` +dnf install https://packages.icinga.com/fedora/icinga-rpm-release-27-latest.noarch.rpm +``` Fedora 26: - dnf install https://packages.icinga.com/fedora/icinga-rpm-release-26-latest.noarch.rpm - -Fedora 25: - - dnf install https://packages.icinga.com/fedora/icinga-rpm-release-25-latest.noarch.rpm - -SLES 11: - - # zypper ar https://packages.icinga.com/SUSE/ICINGA-release-11.repo - # zypper ref +``` +dnf install https://packages.icinga.com/fedora/icinga-rpm-release-26-latest.noarch.rpm +``` SLES 12: - # zypper ar https://packages.icinga.com/SUSE/ICINGA-release.repo - # zypper ref +``` +zypper ar https://packages.icinga.com/SUSE/ICINGA-release.repo +zypper ref +``` + +SLES 11: + +``` +zypper ar https://packages.icinga.com/SUSE/ICINGA-release-11.repo +zypper ref +``` openSUSE: - # zypper ar https://packages.icinga.com/openSUSE/ICINGA-release.repo - # zypper ref - +``` +zypper ar https://packages.icinga.com/openSUSE/ICINGA-release.repo +zypper ref +``` Alpine Linux: - # echo "http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories - # apk update +``` +echo "http://dl-cdn.alpinelinux.org/alpine/edge/community" >> /etc/apk/repositories +apk update +``` #### RHEL/CentOS EPEL Repository @@ -90,11 +113,19 @@ as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL). CentOS 7/6: - yum install epel-release +``` +yum install epel-release +``` 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). +``` +subscription-manager repos --enable rhel-7-server-optional-rpms +# or +subscription-manager repos --enable rhel-6-server-optional-rpms +``` + #### SLES Security Repository The packages for SLES 11 depend on the `openssl1` package which is distributed @@ -115,36 +146,48 @@ In order to correctly manage your repository, please follow ### Installing Icinga 2 You can install Icinga 2 by using your distribution's package manager -to install the `icinga2` package. +to install the `icinga2` package. The following commands must be executed +with `root` permissions unless noted otherwise. Debian/Ubuntu: - # apt-get install icinga2 +``` +apt-get install icinga2 +``` RHEL/CentOS 6: - # yum install icinga2 - # chkconfig icinga2 on - # service icinga2 start +``` +yum install icinga2 +chkconfig icinga2 on +service icinga2 start +``` RHEL/CentOS 7 and Fedora: - # yum install icinga2 - # systemctl enable icinga2 - # systemctl start icinga2 +``` +yum install icinga2 +systemctl enable icinga2 +systemctl start icinga2 +``` SLES/openSUSE: - # zypper install icinga2 +``` +zypper install icinga2 +``` FreeBSD: - # pkg install icinga2 - +``` +pkg install icinga2 +``` Alpine Linux: - # apk add icinga2 +``` +apk add icinga2 +``` ### Enabled Features during Installation @@ -159,10 +202,11 @@ You can verify that by calling `icinga2 feature list` [CLI command](11-cli-commands.md#cli-command-feature) to see which features are enabled and disabled. - # icinga2 feature list - Disabled features: api command compatlog debuglog gelf graphite icingastatus ido-mysql ido-pgsql influxdb livestatus opentsdb perfdata statusdata syslog - Enabled features: checker mainlog notification - +``` +# icinga2 feature list +Disabled features: api command compatlog debuglog gelf graphite icingastatus ido-mysql ido-pgsql influxdb livestatus opentsdb perfdata statusdata syslog +Enabled features: checker mainlog notification +``` ### Installation Paths @@ -231,11 +275,15 @@ distribution's package manager. Debian/Ubuntu: - # apt-get install monitoring-plugins +``` +apt-get install monitoring-plugins +``` RHEL/CentOS: - # yum install nagios-plugins-all +``` +yum install nagios-plugins-all +``` The packages for RHEL/CentOS depend on other packages which are distributed as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL). Please @@ -244,11 +292,15 @@ make sure to enable this repository by following Fedora: - # dnf install nagios-plugins-all +``` +dnf install nagios-plugins-all +``` SLES/openSUSE: - # zypper install monitoring-plugins +``` +zypper install monitoring-plugins +``` The packages for SLES/OpenSUSE depend on other packages which are distributed as part of the [server:monitoring repository](https://build.opensuse.org/project/repositories/server:monitoring). @@ -256,11 +308,15 @@ Please make sure to enable this repository beforehand. FreeBSD: - # pkg install monitoring-plugins +``` +pkg install monitoring-plugins +``` Alpine Linux: - # apk add monitoring-plugins +``` +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. @@ -277,12 +333,71 @@ to determine where to find the plugin binaries. ## Running Icinga 2 +### Systemd Service + +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 +queried for its current status. + +``` +# systemctl status icinga2 +icinga2.service - Icinga host/service/network monitoring system + Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled) + Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago + Process: 21692 ExecStart=/usr/sbin/icinga2 -c ${ICINGA2_CONFIG_FILE} -d -e ${ICINGA2_ERROR_LOG} -u ${ICINGA2_USER} -g ${ICINGA2_GROUP} (code=exited, status=0/SUCCESS) + Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS) + Main PID: 21727 (icinga2) + CGroup: /system.slice/icinga2.service + 21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit + +Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s). +Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s). +Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s). +Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s). +Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s). +Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s). +Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s). +Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system. +``` + +The `systemctl` command supports the following actions: + + Command | Description + --------------------|------------------------ + start | The `start` action starts the Icinga 2 daemon. + stop | The `stop` action stops the Icinga 2 daemon. + restart | The `restart` action is a shortcut for running the `stop` action followed by `start`. + reload | The `reload` action sends the `HUP` signal to Icinga 2 which causes it to restart. Unlike the `restart` action `reload` does not wait until Icinga 2 has restarted. + status | The `status` action checks if Icinga 2 is running. + enable | The `enable` action enables the service being started at system boot time (similar to `chkconfig`) + +Examples: + +``` +# systemctl enable icinga2 + +# systemctl restart icinga2 +Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details. +``` + +If you're stuck with configuration errors, you can manually invoke the +[configuration validation](11-cli-commands.md#config-validation). + +> **Tip** +> +> If you are running into fork errors with Systemd enabled distributions, +> please check the [troubleshooting chapter](15-troubleshooting.md#check-fork-errors). + ### Init Script Icinga 2's init script is installed in `/etc/init.d/icinga2` (`/usr/local/etc/rc.d/icinga2` on FreeBSD) by default: - # /etc/init.d/icinga2 - Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status} +``` +# /etc/init.d/icinga2 +Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status} +``` The init script supports the following actions: @@ -299,93 +414,16 @@ 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 - -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 -queried for its current status. - - # systemctl status icinga2 - icinga2.service - Icinga host/service/network monitoring system - Loaded: loaded (/usr/lib/systemd/system/icinga2.service; disabled) - Active: active (running) since Mi 2014-07-23 13:39:38 CEST; 15s ago - Process: 21692 ExecStart=/usr/sbin/icinga2 -c ${ICINGA2_CONFIG_FILE} -d -e ${ICINGA2_ERROR_LOG} -u ${ICINGA2_USER} -g ${ICINGA2_GROUP} (code=exited, status=0/SUCCESS) - Process: 21674 ExecStartPre=/usr/sbin/icinga2-prepare-dirs /etc/sysconfig/icinga2 (code=exited, status=0/SUCCESS) - Main PID: 21727 (icinga2) - CGroup: /system.slice/icinga2.service - 21727 /usr/sbin/icinga2 -c /etc/icinga2/icinga2.conf -d -e /var/log/icinga2/error.log -u icinga -g icinga --no-stack-rlimit - - Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 309 Service(s). - Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 User(s). - Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 15 Notification(s). - Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 4 ScheduledDowntime(s). - Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 UserGroup(s). - Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 1 IcingaApplication(s). - Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s). - Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system. - -The `systemctl` command supports the following actions: - - Command | Description - --------------------|------------------------ - start | The `start` action starts the Icinga 2 daemon. - stop | The `stop` action stops the Icinga 2 daemon. - restart | The `restart` action is a shortcut for running the `stop` action followed by `start`. - reload | The `reload` action sends the `HUP` signal to Icinga 2 which causes it to restart. Unlike the `restart` action `reload` does not wait until Icinga 2 has restarted. - status | The `status` action checks if Icinga 2 is running. - enable | The `enable` action enables the service being started at system boot time (similar to `chkconfig`) - -Examples: - - # systemctl enable icinga2 - - # systemctl restart icinga2 - Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details. - -If you're stuck with configuration errors, you can manually invoke the -[configuration validation](11-cli-commands.md#config-validation). - -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 - -Using the watchdog can also help with monitoring Icinga 2, to activate and use it add the following to the override: - - WatchdogSec=30s - -This way Systemd will kill Icinga 2 if does not notify for over 30 seconds, a timout of less than 10 seconds is not -recommended. When the watchdog is activated, `Restart=` can be set to `watchdog` to restart Icinga 2 in the case of a -watchdog timeout. - -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 On FreeBSD you need to enable icinga2 in your rc.conf - # sysrc icinga2_enable=yes - - # service icinga2 restart +``` +# sysrc icinga2_enable=yes +# service icinga2 restart +``` ### SELinux @@ -413,7 +451,7 @@ Read more about SELinux in [this chapter](22-selinux.md#selinux). ## Configuration Syntax Highlighting -Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano` editors. +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`); @@ -425,31 +463,42 @@ Install the package `vim-icinga2` with your distribution's package manager. Debian/Ubuntu: - # apt-get install vim-icinga2 vim-addon-manager - # vim-addon-manager -w install icinga2 - Info: installing removed addon 'icinga2' to /var/lib/vim/addons +``` +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 - +``` +apk add icinga2-vim +``` Ensure that syntax highlighting is enabled e.g. by editing the user's `vimrc` configuration file: - # vim ~/.vimrc - syntax on +``` +# vim ~/.vimrc +syntax on +``` Test it: - # vim /etc/icinga2/conf.d/templates.conf +``` +# vim /etc/icinga2/conf.d/templates.conf +``` ![Vim with syntax highlighting](images/getting-started/vim-syntax.png "Vim with Icinga 2 syntax highlighting") @@ -464,42 +513,46 @@ Debian/Ubuntu: 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. - $ cp /etc/nanorc ~/.nanorc +``` +$ cp /etc/nanorc ~/.nanorc +``` Include the `icinga2.nanorc` file. - $ vim ~/.nanorc +``` +$ vim ~/.nanorc - ## Icinga 2 - include "/usr/share/nano/icinga2.nanorc" +## Icinga 2 +include "/usr/share/nano/icinga2.nanorc" +``` Test it: - $ nano /etc/icinga2/conf.d/templates.conf +``` +$ nano /etc/icinga2/conf.d/templates.conf +``` ![Nano with syntax highlighting](images/getting-started/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 number of other web interfaces. +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) modules for Icinga 2 take care of -exporting all configuration and status information into a database. The IDO -database is used by a number of projects including -[Icinga Web 2](02-getting-started.md#setting-up-icingaweb2), Icinga Reporting -or Icinga Web 1.x. - -There is a separate module for each database backend. At present support for -both MySQL and PostgreSQL has been implemented. +The DB IDO (Database Icinga Data Output) feature for Icinga 2 take care of +exporting all configuration and status information into a database. Please choose whether to install [MySQL](02-getting-started.md#configuring-db-ido-mysql) or [PostgreSQL](02-getting-started.md#configuring-db-ido-postgresql). @@ -510,42 +563,56 @@ Please choose whether to install [MySQL](02-getting-started.md#configuring-db-id Debian/Ubuntu: - # apt-get install mysql-server mysql-client - # mysql_secure_installation +``` +apt-get install mysql-server mysql-client -RHEL/CentOS 6: - - # yum install mysql-server mysql - # chkconfig mysqld on - # service mysqld start - # mysql_secure_installation +mysql_secure_installation +``` RHEL/CentOS 7 and Fedora: - # yum install mariadb-server mariadb - # systemctl enable mariadb - # systemctl start mariadb - # mysql_secure_installation +``` +yum install mariadb-server mariadb +systemctl enable mariadb +systemctl start mariadb +mysql_secure_installation +``` + +RHEL/CentOS 6: + +``` +yum install mysql-server mysql +chkconfig mysqld on +service mysqld start + +mysql_secure_installation +``` SUSE: - # zypper install mysql mysql-client - # chkconfig mysqld on - # service mysqld start +``` +zypper install mysql mysql-client +chkconfig mysqld on +service mysqld start +``` FreeBSD: - # pkg install mysql56-server - # sysrc mysql_enable=yes - # service mysql-server restart - # mysql_secure_installation +``` +pkg install mysql56-server +sysrc mysql_enable=yes +service mysql-server restart +mysql_secure_installation +``` Alpine Linux: - # apk add mariadb - # rc-service mariadb setup - # rc-update add mariadb default - # rc-service mariadb start +``` +apk add mariadb +rc-service mariadb setup +rc-update add mariadb default +rc-service mariadb start +``` #### Installing the IDO modules for MySQL @@ -554,55 +621,64 @@ distribution's package manager. Debian/Ubuntu: - # apt-get install icinga2-ido-mysql +``` +apt-get install icinga2-ido-mysql +``` RHEL/CentOS: - # yum install icinga2-ido-mysql +``` +yum install icinga2-ido-mysql +``` SUSE: - # zypper install icinga2-ido-mysql +``` +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 +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 +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 that. +> database manually if you prefer. #### Setting up the MySQL database Set up a MySQL database for Icinga 2: - # mysql -u root -p +``` +# mysql -u root -p - mysql> CREATE DATABASE icinga; - mysql> GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga'; - mysql> quit +CREATE DATABASE icinga; +GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga'; +quit +``` ![setting up the database on CentOS 7](images/getting-started/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: - - # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql +following command. Enter the root password into the prompt when asked. +``` +mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql +``` #### Enabling the IDO MySQL module The package provides a new configuration file that is installed in -`/etc/icinga2/features-available/ido-mysql.conf`. You will need to -update the database credentials in this file. +`/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) @@ -611,23 +687,23 @@ 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. +``` +# icinga2 feature enable ido-mysql +Module 'ido-mysql' was enabled. +Make sure to restart Icinga 2 for these changes to take effect. +``` -After enabling the ido-mysql feature you have to restart Icinga 2: +Restart Icinga 2. -RHEL/CentOS 7/Fedora, SLES 12/openSUSE > 12.2, Debian Jessie/Stretch, Ubuntu Xenial: - - # systemctl restart icinga2 - -Debian/Ubuntu, RHEL/CentOS 6, SLES 11/openSUSE < 12.3 and FreeBSD: - - # service icinga2 restart +``` +systemctl restart icinga2 +``` Alpine Linux: - # rc-service icinga2 restart +``` +rc-service icinga2 restart +``` Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver). @@ -637,42 +713,54 @@ Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface Debian/Ubuntu: - # apt-get install postgresql +``` +apt-get install postgresql +``` RHEL/CentOS 6: - # yum install postgresql-server postgresql - # chkconfig postgresql on - # service postgresql initdb - # service postgresql start +``` +yum install postgresql-server postgresql +chkconfig postgresql on +service postgresql initdb +service postgresql start +``` RHEL/CentOS 7: - # yum install postgresql-server postgresql - # postgresql-setup initdb - # systemctl enable postgresql - # systemctl start postgresql +``` +yum install postgresql-server postgresql +postgresql-setup initdb +systemctl enable postgresql +systemctl start postgresql +``` SUSE: - # zypper install postgresql postgresql-server - # chkconfig postgresql on - # service postgresql initdb - # service postgresql start +``` +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 +``` +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 +``` +apk add postgresql +rc-update add postgresql default +rc-service postgresql setup +rc-service postgresql start +``` #### Installing the IDO modules for PostgreSQL @@ -681,25 +769,31 @@ distribution's package manager. Debian/Ubuntu: - # apt-get install icinga2-ido-pgsql +``` +apt-get install icinga2-ido-pgsql +``` RHEL/CentOS: - # yum install icinga2-ido-pgsql +``` +yum install icinga2-ido-pgsql +``` SUSE: - # zypper install icinga2-ido-pgsql +``` +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 +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 +and located at `/usr/share/icinga2-ido-pgsql/schema/pgsql.sql`. > **Note** > @@ -711,38 +805,46 @@ and located at /usr/share/icinga2-ido-pgsql/schema/pgsql.sql Set up a PostgreSQL database for Icinga 2: - # cd /tmp - # sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'" - # sudo -u postgres createdb -O icinga -E UTF8 icinga +``` +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 (Debian: `/etc/postgresql/*/main/pg_hba.conf`, -RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5 -authentication method and restart the postgresql server. +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 +``` +# 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 +# "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 +``` - # service postgresql restart +``` +systemctl restart postgresql +``` -After creating the database and permissions you can import the Icinga 2 IDO +After creating the database and permissions you need to import the IDO database schema using the following command: - # export PGPASSWORD=icinga - # psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql +``` +export PGPASSWORD=icinga +psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql +``` ![importing the Icinga 2 IDO schema](images/getting-started/postgr-import-ido.png "Importing the Icinga 2 IDO schema on Debian Jessie") @@ -750,7 +852,7 @@ schema using the following command: #### Enabling the IDO PostgreSQL module The package provides a new configuration file that is installed in -`/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update +`/etc/icinga2/features-available/ido-pgsql.conf`. You can update the database credentials in this file. All available attributes are explained in the @@ -760,80 +862,102 @@ 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. +``` +# icinga2 feature enable ido-pgsql +Module 'ido-pgsql' was enabled. +Make sure to restart Icinga 2 for these changes to take effect. +``` -After enabling the ido-pgsql feature you have to restart Icinga 2: +Restart Icinga 2. -RHEL/CentOS 7/Fedora, SLES 12/openSUSE > 12.2, Debian Jessie/Stretch, Ubuntu Xenial: - - # systemctl restart icinga2 - -Debian/Ubuntu, RHEL/CentOS 6, SLES 11/openSUSE < 12.3 and FreeBSD: - - # service icinga2 restart +``` +systemctl restart icinga2 +``` Alpine Linux: - # rc-service icinga2 restart +``` +rc-service icinga2 restart +``` Continue with the [webserver setup](02-getting-started.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. + Debian/Ubuntu: - # apt-get install apache2 - -RHEL/CentOS 6: - - # yum install httpd - # chkconfig httpd on - # service httpd start +``` +apt-get install apache2 +``` RHEL/CentOS 7, Fedora: - # yum install httpd - # systemctl enable httpd - # systemctl start httpd +``` +yum install httpd +systemctl enable httpd +systemctl start httpd +``` + +RHEL/CentOS 6: + +``` +yum install httpd +chkconfig httpd on +service httpd start +``` SUSE: - # zypper install apache2 - # chkconfig on - # service apache2 start +``` +zypper install apache2 +chkconfig on +service apache2 start +``` -FreeBSD (nginx, but you could also use the apache24 package): +FreeBSD (Nginx, but you could also use the `apache24` package): - # pkg install nginx php56-gettext php56-ldap php56-openssl php56-mysql php56-pdo_mysql php56-pgsql php56-pdo_pgsql php56-sockets php56-gd pecl-imagick pecl-intl - # sysrc php_fpm_enable=yes - # sysrc nginx_enable=yes - # sed -i '' "s/listen\ =\ 127.0.0.1:9000/listen\ =\ \/var\/run\/php5-fpm.sock/" /usr/local/etc/php-fpm.conf - # sed -i '' "s/;listen.owner/listen.owner/" /usr/local/etc/php-fpm.conf - # sed -i '' "s/;listen.group/listen.group/" /usr/local/etc/php-fpm.conf - # sed -i '' "s/;listen.mode/listen.mode/" /usr/local/etc/php-fpm.conf - # service php-fpm start - # service nginx start +``` +pkg install nginx php56-gettext php56-ldap php56-openssl php56-mysql php56-pdo_mysql php56-pgsql php56-pdo_pgsql php56-sockets php56-gd pecl-imagick pecl-intl +sysrc php_fpm_enable=yes +sysrc nginx_enable=yes +sed -i '' "s/listen\ =\ 127.0.0.1:9000/listen\ =\ \/var\/run\/php5-fpm.sock/" /usr/local/etc/php-fpm.conf +sed -i '' "s/;listen.owner/listen.owner/" /usr/local/etc/php-fpm.conf +sed -i '' "s/;listen.group/listen.group/" /usr/local/etc/php-fpm.conf +sed -i '' "s/;listen.mode/listen.mode/" /usr/local/etc/php-fpm.conf +service php-fpm start +service nginx start +``` Alpine Linux: - # apk add apache2 php7-apache2 - # sed -i -e "s/^#LoadModule rewrite_module/LoadModule rewrite_module/" /etc/apache2/httpd.conf - # rc-update add apache2 default - # rc-service apache2 start +``` +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 -Example: +Enable port 80 (http). Best practice is to only enable port 443 (https) and use TLS certificates. - # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT - # service iptables save +firewall-cmd: -RHEL/CentOS 7 specific: +``` +firewall-cmd --add-service=http +firewall-cmd --permanent --add-service=http +``` - # firewall-cmd --add-service=http - # firewall-cmd --permanent --add-service=http +iptables: + +``` +iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT +service iptables save +``` FreeBSD: Please consult the [FreeBSD Handbook](https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/firewalls.html) how to configure one of FreeBSD's firewalls. @@ -849,31 +973,33 @@ You can run the CLI command `icinga2 api setup` to enable the certificates as well as a new API user `root` with an auto-generated password in the `/etc/icinga2/conf.d/api-users.conf` configuration file: - # icinga2 api setup +``` +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 +``` +vim /etc/icinga2/conf.d/api-users.conf - object ApiUser "icingaweb2" { - password = "Wijsn8Z9eRs5E25d" - permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ] - } +object ApiUser "icingaweb2" { + password = "Wijsn8Z9eRs5E25d" + permissions = [ "status/query", "actions/*", "objects/modify/*", "objects/query/*" ] +} +``` -Make sure to restart Icinga 2 to activate the configuration. +Restart Icinga 2 to activate the configuration. -RHEL/CentOS 7/Fedora, SLES 12/openSUSE > 12.2, Debian Jessie/Stretch, Ubuntu Xenial: - - # systemctl restart icinga2 - -Debian/Ubuntu, RHEL/CentOS 6, SLES 11/openSUSE < 12.3 and FreeBSD: - - # service icinga2 restart +``` +systemctl restart icinga2 +``` Alpine Linux: - # rc-service icinga2 restart +``` +rc-service icinga2 restart +``` ### Installing Icinga Web 2 @@ -897,3 +1023,14 @@ Ensure to include the following in your backups: * Certificate files in `/var/lib/icinga2/ca` (Master CA key pair) and `/var/lib/icinga2/certs` (node certificates) * Runtime files in `/var/lib/icinga2` * Optional: IDO database backup + +## Backup: Database + +MySQL/MariaDB: + +* [Documentation](https://mariadb.com/kb/en/library/backup-and-restore-overview/) + +PostgreSQL: + +* [Documentation](https://www.postgresql.org/docs/9.3/static/backup.html) + diff --git a/doc/15-troubleshooting.md b/doc/15-troubleshooting.md index 8e1fc63ff..d78bc9aa0 100644 --- a/doc/15-troubleshooting.md +++ b/doc/15-troubleshooting.md @@ -538,6 +538,34 @@ External Resources: * [Icinga 2 upstream issue](https://github.com/Icinga/icinga2/issues/5611) * [Systemd upstream discussion](https://github.com/systemd/systemd/issues/3211) +### Systemd Watchdog + +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 + +Using the watchdog can also help with monitoring Icinga 2, to activate and use it add the following to the override: + + WatchdogSec=30s + +This way Systemd will kill Icinga 2 if does not notify for over 30 seconds, a timout of less than 10 seconds is not +recommended. When the watchdog is activated, `Restart=` can be set to `watchdog` to restart Icinga 2 in the case of a +watchdog timeout. + +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. + ### Late Check Results [Icinga Web 2](https://www.icinga.com/products/icinga-web-2/) provides