Distribution | Repository
------------------------|---------------------------
- Debian | [Icinga Repository](http://packages.icinga.org/debian/), [Upstream](https://packages.debian.org/sid/icinga2), [DebMon](http://debmon.org/packages/debmon-wheezy/icinga2)
- Ubuntu | [Icinga Repository](http://packages.icinga.org/ubuntu/), [Upstream](https://launchpad.net/ubuntu/+source/icinga2)
+ Debian | [Upstream](https://packages.debian.org/sid/icinga2), [DebMon](http://debmon.org/packages/debmon-wheezy/icinga2), [Icinga Repository](http://packages.icinga.org/debian/)
+ Ubuntu | [Upstream](https://launchpad.net/ubuntu/+source/icinga2), [Icinga PPA](https://launchpad.net/~formorer/+archive/ubuntu/icinga), [Icinga Repository](http://packages.icinga.org/ubuntu/)
RHEL/CentOS | [Icinga Repository](http://packages.icinga.org/epel/)
OpenSUSE | [Icinga Repository](http://packages.icinga.org/openSUSE/), [Server Monitoring Repository](https://build.opensuse.org/package/show/server:monitoring/icinga2)
SLES | [Icinga Repository](http://packages.icinga.org/SUSE/)
Packages for distributions other than the ones listed above may also be
available. Please contact your distribution packagers.
-The packages for RHEL/CentOS 5 depend on other packages which are distributed
+### <a id="installing-requirements"></a> 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 -
+ # cat >/etc/apt/sources.list.d/debmon.list<<EOF
+ deb http://debmon.org/debmon debmon-wheezy main
+ EOF
+ # 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](http://fedoraproject.org/wiki/EPEL). Please
-make sure to enable this repository.
+make sure to enable this repository by following
+[these instructions](#http://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
+
+### <a id="installing-icinga2"></a> 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` to enable the
-`icinga2` service. You can manually start Icinga 2 using `/etc/init.d/icinga2 start`.
+`icinga2` service. You can manually start Icinga 2 using `service icinga2 start`.
+
+ # chkconfig icinga2 on
+ # service icinga2 start
+
RHEL/CentOS 7 use [Systemd](#systemd-service) with `systemctl {enable,start} icinga2`.
+ # systemctl enable icinga2
+ # systemctl start icinga2
+
Some parts of Icinga 2's functionality are available as separate packages:
Name | Description
/var/lib/icinga2 | Icinga 2 state file, cluster feature replay log and configuration files.
/var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
+## <a id="setting-up-check-plugins"></a> Setting 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
+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.
+
+> **Note**
+>
+> EPEL for RHEL/CentOS 7 is still in beta mode at the time of writing and does
+> not provide a `monitoring-plugins` package. You are required to manually install
+> them.
+
+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 service templates contained in the Icinga Template Library to determine
+where to find the plugin binaries.
+
+### <a id="integrate-additional-plugins"></a> Integrate Additional Plugins
+
+For some services you may need additional 'check plugins' which are not provided
+by the official Monitoring Plugins project.
+
+All existing Nagios or Icinga 1.x plugins work with Icinga 2. Here's a
+list of popular community sites which host check plugins:
+
+* [MonitoringExchange](https://www.monitoringexchange.org)
+* [Icinga Wiki](https://wiki.icinga.org)
+
+The recommended way of setting up these plugins is to copy them to a common directory
+and create an extra global constant, e.g. `CustomPluginDir` in your [constants.conf](#constants-conf)
+configuration file:
+
+ # cp check_snmp_int.pl /opt/plugins
+ # chmod +x /opt/plugins/check_snmp_int.pl
+
+ # cat /etc/icinga2/constants.conf
+ /**
+ * This file defines global constants which can be used in
+ * the other configuration files. At a minimum the
+ * PluginDir constant should be defined.
+ */
+
+ const PluginDir = "/usr/lib/nagios/plugins"
+ const CustomPluginDir = "/opt/monitoring"
+
+Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
+by trying to run it on the console using whichever user Icinga 2 is running as:
+
+ # su - icinga -s /bin/bash
+ $ /opt/plugins/check_snmp_int.pl --help
+
+Additional libraries may be required for some plugins. Please consult the plugin
+documentation and/or plugin provided README for installation instructions.
+
+Each plugin requires a [CheckCommand](#objecttype-checkcommand) object in your
+configuration which can be used in the [Service](#objecttype-service) or
+[Host](#objecttype-host) object definition. Examples for `CheckCommand`
+objects can be found in the [Plugin Check Commands](#plugin-check-commands) shipped
+with Icinga 2.
+For further information on your monitoring configuration read the
+[monitoring basics](#monitoring-basics).
+
+
+## <a id="configuring-icinga2-first-steps"></a> Configuring Icinga 2: First Steps
+
### <a id="icinga2-conf"></a> icinga2.conf
An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`.
Further details on the monitoring configuration can be found in the
[monitoring basics](#monitoring-basics) chapter.
-## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
+## <a id="configuring-db-ido"></a> Configuring DB IDO
-Without plugins
-Icinga 2 does not know how to check external services. The
-[Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
-an extensive set of plugins which can be used with Icinga 2 to check whether
-services are working properly.
+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 1.x, Reporting or Icinga Web 2.
-The recommended way of installing these standard plugins is to use your
-distribution's package manager.
+There is a separate module for each database back-end. At present support for
+both MySQL and PostgreSQL is implemented.
+
+Icinga 2 uses the Icinga 1.x IDOUtils database schema. Icinga 2 requires additional
+features not yet released with older Icinga 1.x versions.
> **Note**
>
-> The `Nagios Plugins` project was renamed to `Monitoring Plugins`
-> in January 2014. At the time of this writing the packages are still
-> using the old name.
-
-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 service templates contained in the Icinga Template Library to determine
-where to find the plugin binaries.
-
-### <a id="integrate-additional-plugins"></a> Integrate Additional Plugins
+> Please check the [what's new](#whats-new) section for the required schema version.
-For some services you may need additional 'check plugins' which are not provided
-by the official Monitoring Plugins project.
+> **Tip**
+>
+> Only install the IDO feature if your web interface or reporting tool requires
+> you to do so (for example, [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2)).
+> [Icinga Classic UI](#setting-up-icinga-classic-ui) does not use IDO as backend.
-All existing Nagios or Icinga 1.x plugins should work with Icinga 2. Here's a
-list of popular community sites which host check plugins:
+### <a id="installing-database"></a> Installing the Database Server
-* [MonitoringExchange](https://www.monitoringexchange.org)
-* [Icinga Wiki](https://wiki.icinga.org)
+In order to use DB IDO you need to setup either [MySQL](#installing-database-mysql-server)
+or [PostgreSQL](#installing-database-postgresql-server) as supported database server.
-The recommended way of setting up these plugins is to copy them to a common directory
-and create an extra global constant, e.g. `CustomPluginDir` in your `constants.conf`
-configuration file:
+> **Note**
+>
+> It's up to you whether you choose to install it on the same server where Icinga 2 is running on,
+> or on a dedicated database host (or cluster).
- # cp check_snmp_int.pl /opt/plugins
- # chmod +x /opt/plugins/check_snmp_int.pl
+#### <a id="installing-database-mysql-server"></a> Installing MySQL database server
- # cat /etc/icinga2/constants.conf
- /**
- * This file defines global constants which can be used in
- * the other configuration files. At a minimum the
- * PluginDir constant should be defined.
- */
+Debian/Ubuntu:
+ # apt-get install mysql-server mysql-client
- const PluginDir = "/usr/lib/nagios/plugins"
- const CustomPluginDir = "/opt/monitoring"
+RHEL/CentOS 5/6:
+ # yum install mysql-server mysql
+ # chkconfig mysqld on
+ # service mysqld start
-Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
-by trying to run it on the console using whichever user Icinga 2 is running as:
+RHEL/CentOS 7 and Fedora 20 prefer MariaDB over MySQL:
+ # yum install mariadb-server mariadb
+ # systemctl enable mariadb.service
+ # systemctl start mariadb.service
- # su - icinga -s /bin/bash
- $ /opt/plugins/check_snmp_int.pl --help
+SUSE:
+ # zypper install mysql mysql-client
+ # chkconfig mysqld on
+ # service mysqld start
-Additional libraries may be required for some plugins. Please consult the plugin
-documentation and/or plugin provided README for installation instructions.
+RHEL based distributions do not automatically set a secure root password. Do that **now**:
-Each plugin requires a [CheckCommand](#objecttype-checkcommand) object in your
-configuration which can be used in the [Service](#objecttype-service) or
-[Host](#objecttype-host) object definition. Examples for `CheckCommand`
-objects can be found in the [Plugin Check Commands](#plugin-check-commands) shipped
-with Icinga 2.
-For further information on your monitoring configuration read the
-[monitoring basics](#monitoring-basics).
+ # /usr/bin/mysql_secure_installation
-## <a id="configuring-db-ido"></a> Configuring DB IDO
+#### <a id="installing-database-postgresql-server"></a> Installing PostgreSQL database server
-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 1.x, Reporting or Icinga Web 2.
+Debian/Ubuntu:
+ # apt-get install postgresql
-There is a separate module for each database back-end. At present support for
-both MySQL and PostgreSQL is implemented.
+RHEL/CentOS 5/6:
+ # yum install postgresql-server postgresql
+ # chkconfig postgresql on
+ # service postgresql start
-Icinga 2 uses the Icinga 1.x IDOUtils database schema. Icinga 2 requires additional
-features not yet released with older Icinga 1.x versions.
+RHEL/CentOS 7 and Fedora 20 use [systemd](#systemd-service):
+ # yum install postgresql-server postgresql
+ # systemctl enable postgresql.service
+ # systemctl start postgresql.service
-* Current required schema version: `1.11.6`.
+SUSE:
+ # zypper install postgresql postgresql-server
+ # chkconfig postgresql on
+ # service postgresql start
+### <a id="configuring-db-ido-mysql"></a> Configuring DB IDO MySQL
-> **Tip**
+> **Note**
>
-> Only install the IDO feature if your web interface or reporting tool requires
-> you to do so (for example, [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2)).
-> [Icinga Classic UI](#setting-up-icinga-classic-ui) does not use IDO as backend.
-
-### <a id="configuring-db-ido-mysql"></a> Configuring DB IDO MySQL
+> 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.
#### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
# mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
+
#### <a id="upgrading-mysql-db"></a> Upgrading the MySQL database
Check the `/usr/share/icinga2-ido-mysql/schema/upgrade` directory for an
After enabling the ido-mysql feature you have to restart Icinga 2:
- # /etc/init.d/icinga2 restart
+ # service icinga2 restart
### <a id="configuring-db-ido-postgresql"></a> Configuring DB IDO PostgreSQL
+> **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
First of all you have to install the `icinga2-ido-pgsql` package using your
After enabling the ido-pgsql feature you have to restart Icinga 2:
- # /etc/init.d/icinga2 restart
+ # service icinga2 restart
## <a id="setting-up-livestatus"></a> Setting up Livestatus
> Choose your preferred interface. There's no need to install [Classic UI](#setting-up-icinga-classic-ui)
> if you prefer [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2) for example.
+### <a id="icinga2-user-interface-requirements"></a> Requirements
+
+* Web server (Apache2/Httpd, Nginx, Lighttp, etc)
+* User credentials
+* Firewall ports (tcp/80)
+
+The Debian, RHEL and SUSE packages for Icinga [Classic UI](#setting-up-icinga-classic-ui),
+[Web](#setting-up-icinga-web) and [Icingaweb 2](#setting-up-icingaweb2) depend on Apache2
+as web server.
+
+#### <a id="icinga2-user-interface-webserver"></a> Webserver
+
+Debian/Ubuntu packages will automatically fetch and install the required packages.
+
+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
+
+#### <a id="icinga2-user-interface-firewall-rules"></a> 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
+
### <a id="setting-up-icinga-classic-ui"></a> Setting up Icinga Classic UI
Icinga 2 can write `status.dat` and `objects.cache` files in the format that
Distribution | Packages
--------------|---------------------
Debian | icinga2-classicui
- all others | icinga2-classicui-config icinga-gui
+ RHEL/SUSE | icinga2-classicui-config icinga-gui
The Debian packages require additional packages which are provided by the
[Debian Monitoring Project](http://www.debmon.org) (`DebMon`) repository.
### <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
-Icinga Web 2 currently supports `status.dat`, `DB IDO`, or `Livestatus` as backends.
+Icinga Web 2 will support `status.dat`, `DB IDO`, or `Livestatus` as backends.
Using DB IDO as backend, you need to install and configure the [DB IDO backend](#configuring-db-ido).
Once finished, you can enable the feature for DB IDO MySQL:
# icinga2-enable-feature ido-mysql
-furthermore [external commands](#external-commands) are supported through the external
+Furthermore [external commands](#external-commands) are supported through the external
command pipe.
# icinga2-enable-feature command
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](#config-validation).
+ # systemctl enable icinga2
+ # systemctl restart icinga2
+ Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.
### <a id="cmdline"></a> Command-line Options
EnablePerfdata |**Read-write.** Whether performance data processing is globally enabled. Defaults to true.
UseVfork |**Read-write.** Whether to use vfork(). Only available on *NIX. Defaults to true.
+## <a id="reserved-keywords"></a> Reserved Keywords
+
+These keywords are reserved by the configuration parser and must not be
+used as constants or custom attributes.
+
+ object
+ template
+ include
+ include_recursive
+ library
+ null
+ partial
+ true
+ false
+ const
+ apply
+ to
+ where
+ import
+ assign
+ ignore
+ zone
+ in
+
## <a id="configuration-syntax"></a> Configuration Syntax
notes |**Optional.** Notes for the host.
notes_url |**Optional.** Url for notes for the host (for example, in notification commands).
action_url |**Optional.** Url for actions for the host (for example, an external graphing tool).
- icon_image |**Optional.** Icon image for the host. Required for external interfaces only.
- icon_image_alt |**Optional.** Icon image description for the host. Required for external interface only.
+ icon_image |**Optional.** Icon image for the host. Used by external interfaces only.
+ icon_image_alt |**Optional.** Icon image description for the host. Used by external interface only.
> **Best Practice**
>
> The `address` and `address6` attributes are required for running commands using
-> the `$address$` and `$address6` runtime macros.
+> the `$address$` and `$address6$` runtime macros.
### <a id="objecttype-hostgroup"></a> HostGroup
notes |**Optional.** Notes for the service.
notes_url |**Optional.** Url for notes for the service (for example, in notification commands).
action_url |**Optional.** Url for actions for the service (for example, an external graphing tool).
- icon_image |**Optional.** Icon image for the service. Required for external interfaces only.
- icon_image_alt |**Optional.** Icon image description for the service. Required for external interface only.
+ icon_image |**Optional.** Icon image for the service. Used by external interfaces only.
+ icon_image_alt |**Optional.** Icon image description for the service. Used by external interface only.
Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
description = "My plugin requires this argument for doing X."
required = false /* optional, no error if not set */
skip_key = false /* always use "-X <value>" */
- set_if = "$have_x$" /* only set if variable defined */
- order = 0 /* first position */
+ set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
+ order = -1 /* first position */
+ }
+ "-Y" = {
+ value = "$y_val$"
+ description = "My plugin requires this argument for doing Y."
+ required = false /* optional, no error if not set */
+ skip_key = true /* don't prefix "-Y" only use "<value>" */
+ set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
+ order = 0 /* second position */
}
}
description | Optional argument description.
required | Required argument. Execution error if not set. Defaults to false (optional).
skip_key | Use the value as argument and skip the key.
- set_if | Argument added if value is set (macro resolves to a defined value).
+ set_if | Argument is added if the macro resolves to a defined numeric value. String values are not supported.
order | Set if multiple arguments require a defined argument order.
+Argument order:
+ `..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...`
+
### <a id="objecttype-notificationcommand"></a> NotificationCommand
user_groups | **Optional.** A list of user group names who should be notified.
times | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
command | **Required.** The name of the notification command which should be executed when the notification is triggered.
- interval | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes.
+ interval | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, [re-notifications](#disable-renotification) are disabled.
period | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
types | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
states | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
projects / icinga2 / commitdiff