21 KiB

Raw Blame History

Getting Started

This tutorial is a step-by-step introduction to installing Icinga 2 and available Icinga web interfaces. It assumes that you are familiar with the system you're installing Icinga 2 on.

Details on troubleshooting problems can be found here.

Setting up Icinga 2

First off you will 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.

Distribution	Repository
Debian	debmon, Icinga Repository
Ubuntu	Icinga PPA, Icinga Repository
RHEL/CentOS	Icinga Repository
openSUSE	Icinga Repository, Server Monitoring Repository
SLES	Icinga Repository
Gentoo	Upstream
FreeBSD	Upstream
ArchLinux	Upstream

Packages for distributions other than the ones listed above may also be available. Please contact your distribution packagers.

Installing Requirements for Icinga 2

You need to add the Icinga repository to your package management configuration. Below is a list with examples for the various distributions.

Debian (debmon):

# wget -O - http://debmon.org/debmon/repo.key 2>/dev/null | apt-key add -
# echo 'deb http://debmon.org/debmon debmon-wheezy main' >/etc/apt/sources.list.d/debmon.list
# apt-get update

Ubuntu (PPA):

# add-apt-repository ppa:formorer/icinga
# apt-get update

RHEL/CentOS:

# rpm --import http://packages.icinga.org/icinga.key
# wget http://packages.icinga.org/epel/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
# yum makecache

Fedora:

# wget http://packages.icinga.org/fedora/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
# yum makecache

SLES:

# zypper ar http://packages.icinga.org/SUSE/ICINGA-release.repo
# zypper ref

openSUSE:

# zypper ar http://packages.icinga.org/openSUSE/ICINGA-release.repo
# zypper ref

The packages for RHEL/CentOS depend on other packages which are distributed as part of the EPEL repository. Please make sure to enable this repository by following these instructions.

Installing Icinga 2

You can install Icinga 2 by using your distribution's package manager to install the icinga2 package.

Debian/Ubuntu:

# apt-get install icinga2

RHEL/CentOS/Fedora:

# yum install icinga2

SLES/openSUSE:

# zypper install icinga2

On RHEL/CentOS and SLES you will need to use chkconfig and service to enable and start the icinga2 service:

# chkconfig icinga2 on
# service icinga2 start

RHEL/CentOS 7 and Fedora use systemd:

# systemctl enable icinga2
# systemctl start icinga2

Some parts of Icinga 2's functionality are available as separate packages:

Name	Description
icinga2-ido-mysql	DB IDO provider module for MySQL
icinga2-ido-pgsql	DB IDO provider module for PostgreSQL

Enabled Features during Installation

The default installation will enable three features required for a basic Icinga 2 installation:

checker for executing checks
notification for sending notifications
mainlog for writing the icinga2.log file

You can verify that by calling icinga2 feature list CLI command to see which features are enabled and disabled.

# icinga2 feature list
Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog
Enabled features: checker mainlog notification

Installation Paths

By default Icinga 2 uses the following files and directories:

Path	Description
/etc/icinga2	Contains Icinga 2 configuration files.
/etc/init.d/icinga2	The Icinga 2 init script.
/usr/sbin/icinga2*	The Icinga 2 binary.
/usr/share/doc/icinga2	Documentation files that come with Icinga 2.
/usr/share/icinga2/include	The Icinga Template Library and plugin command configuration.
/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/lib/icinga2	Icinga 2 state file, cluster log, local CA and configuration files.
/var/log/icinga2	Log file location and compat/ directory for the CompatLogger feature.

Setting up Check Plugins

Without plugins Icinga 2 does not know how to check external services. The Monitoring Plugins Project provides an extensive set of plugins which can be used with Icinga 2 to check whether services are working properly.

The recommended way of installing these standard plugins is to use your distribution's package manager.

Note

The Nagios Plugins project was renamed to Monitoring Plugins in January 2014. At the time of this writing some packages are still using the old name while some distributions have adopted the new package name monitoring-plugins already.

For your convenience here is a list of package names for some of the more popular operating systems/distributions:

OS/Distribution	Package Name	Installation Path
RHEL/CentOS (EPEL)	nagios-plugins-all	/usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
Debian	nagios-plugins	/usr/lib/nagios/plugins
FreeBSD	nagios-plugins	/usr/local/libexec/nagios
OS X (MacPorts)	nagios-plugins	/opt/local/libexec

Depending on which directory your plugins are installed into you may need to update the global PluginDir constant in your Icinga 2 configuration. This macro is used by the check command definitions contained in the Icinga Template Library to determine where to find the plugin binaries.

Please refer to the plugins chapter for details about how to integrate additional check plugins into your Icinga 2 setup.

Configuring DB IDO

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, Icinga Reporting or Icinga Web 1.x.

You only need to set up the IDO modules if you're planning to use one of the web interfaces or another external project which uses the IDO database.

There is a separate module for each database backend. At present support for both MySQL and PostgreSQL is implemented.

Configuring DB IDO MySQL

Installing MySQL database server

Debian/Ubuntu:

# apt-get install mysql-server mysql-client

RHEL/CentOS 5/6:

# yum install mysql-server mysql
# chkconfig mysqld on
# service mysqld start

RHEL/CentOS 7 and Fedora:

# yum install mariadb-server mariadb
# systemctl enable mariadb
# systemctl start mariadb

SUSE:

# zypper install mysql mysql-client
# chkconfig mysqld on
# service mysqld start

RHEL based distributions do not automatically set a secure root password. Do that now:

# /usr/bin/mysql_secure_installation

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:

# apt-get install icinga2-ido-mysql

RHEL/CentOS:

# yum install icinga2-ido-mysql

SUSE:

# zypper install icinga2-ido-mysql

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 MySQL database

Set up a MySQL database for Icinga 2:

# mysql -u root -p

mysql>  CREATE DATABASE icinga;
        GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
        quit

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

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. All available attributes are listed in the IdoMysqlConnection object configuration details.

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.

After enabling the ido-mysql feature you have to restart Icinga 2:

Debian/Ubuntu, RHEL/CentOS 6 and SUSE:

# service icinga2 restart

RHEL/CentOS 7 and Fedora:

# systemctl restart icinga2

Configuring DB IDO PostgreSQL

Installing PostgreSQL database server

Debian/Ubuntu:

# apt-get install postgresql

RHEL/CentOS 5/6:

# yum install postgresql-server postgresql
# chkconfig postgresql on
# service postgresql start

RHEL/CentOS 7:

# yum install postgresql-server postgresql
# systemctl enable postgresql
# systemctl start postgresql

SUSE:

# zypper install postgresql postgresql-server
# chkconfig postgresql on
# 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:

# apt-get install icinga2-ido-pgsql

RHEL/CentOS:

# yum install icinga2-ido-pgsql

SUSE:

# zypper 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.

Setting up the PostgreSQL database

Set up a PostgreSQL database for Icinga 2:

# cd /tmp
# sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
# sudo -u postgres createdb -O icinga -E UTF8 icinga
# sudo -u postgres createlang plpgsql icinga

Note

Using PostgreSQL 9.x you can omit the createlang command.

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.

# vim /var/lib/pgsql/data/pg_hba.conf

# icinga
local   icinga      icinga                            md5
host    icinga      icinga      127.0.0.1/32          md5
host    icinga      icinga      ::1/128               md5

# "local" is for Unix domain socket connections only
local   all         all                               ident
# IPv4 local connections:
host    all         all         127.0.0.1/32          ident
# IPv6 local connections:
host    all         all         ::1/128               ident

# /etc/init.d/postgresql restart

After creating the database and permissions you can import the Icinga 2 IDO schema using the following command:

# export PGPASSWORD=icinga
# psql -U icinga -d icinga < /usr/share/icinga2-ido-pgsql/schema/pgsql.sql

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 the database credentials in this file. All available attributes are listed in the IdoPgsqlConnection object configuration details.

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.

After enabling the ido-pgsql feature you have to restart Icinga 2:

Debian/Ubuntu, RHEL/CentOS 6 and SUSE:

# service icinga2 restart

RHEL/CentOS 7 and Fedora:

# systemctl restart icinga2

Setting Up External Command Pipe

Web interfaces and other Icinga addons are able to send commands to Icinga 2 through the external command pipe.

You can enable the External Command Pipe using the CLI:

# icinga2 feature enable command

After that you will have to restart Icinga 2:

Debian/Ubuntu, RHEL/CentOS 6 and SUSE:

# service icinga2 restart

RHEL/CentOS 7 and Fedora:

# systemctl restart icinga2

By default the command pipe file is owned by the group icingacmd with read/write permissions. Add your webserver's user to the group icingacmd to enable sending commands to Icinga 2 through your web interface:

# usermod -a -G icingacmd www-data

Debian packages use nagios as the default user and group name. Therefore change icingacmd to nagios. The webserver's user is different between distributions so you might have to change www-data to wwwrun, www, or apache.

Change "www-data" to the user you're using to run queries.

Note

Packages will do that automatically. Verify that by running id <your-webserver-user> and skip this step.

Running Icinga 2

Init Script

Icinga 2's init script is installed in /etc/init.d/icinga2 by default:

# /etc/init.d/icinga2
Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}

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.

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`)

If you're stuck with configuration errors, you can manually invoke the configuration validation.

# systemctl enable icinga2

# systemctl restart icinga2
Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.

Setting up the User Interface

Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces. This chapter explains how to set up Icinga Web 2. The Alternative Frontends chapter can be used as a starting point for installing some of the other web interfaces which are also available.

Webserver

Debian/Ubuntu:

# apt-get install apache2

RHEL/CentOS/Fedora:

# yum install httpd
# chkconfig httpd on && service httpd start
## RHEL7
# systemctl enable httpd && systemctl start httpd

SUSE:

# zypper install apache2
# chkconfig on && service apache2 start

Firewall Rules

Example:

# iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT
# service iptables save

RHEL/CentOS 7 specific:

# firewall-cmd --add-service=http
# firewall-cmd --permanent --add-service=http

Setting up Icinga Web 2

Icinga Web 2 supports DB IDO or Livestatus as backends.

Using DB IDO as backend, you need to install and configure the DB IDO backend.

In order to use commands in Web 2 you need to set up the external command pipe.

Icinga Web 2 ships its own web-based setup wizard which will guide you through the entire setup process.

Generate the Webserver configuration and a setup token using its local cli and proceed with the web setup when accessing /icingaweb2 after reloading your webserver configuration.

Please consult the installation documentation shipped with Icinga Web 2 for further instructions on how to install Icinga Web 2 and to configure backends, resources and instances manually.

Check the Icinga website for release announcements and packages.

Addons

A number of additional features are available in the form of plugins. A list of popular addons is available in the Addons and Plugins chapter.

21 KiB Raw Blame History

Getting Started

Setting up Icinga 2

Installing Requirements for Icinga 2

Installing Icinga 2

Enabled Features during Installation

Installation Paths

Setting up Check Plugins

Configuring DB IDO

Configuring DB IDO MySQL

Installing MySQL database server

Installing the IDO modules for MySQL

Setting up the MySQL database

Enabling the IDO MySQL module

Configuring DB IDO PostgreSQL

Installing PostgreSQL database server

Installing the IDO modules for PostgreSQL

Setting up the PostgreSQL database

Enabling the IDO PostgreSQL module

Setting Up External Command Pipe

Running Icinga 2

Init Script

systemd Service

Setting up the User Interface

Webserver

Firewall Rules

Setting up Icinga Web 2

Addons

21 KiB

Raw Blame History