tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update docs for better compatibility with mkdocs 

* Rename files to allow easy ordering
* Update links inside markdown according to new file names
* Move HTML links (<a>...</a>) to the end of the header lines
  * This is necessary to allow mkdocs to parse headers correctly and display them in the TOC
  * Following sed command was used: sed -i .bu 's/\(<a.*a>\) \(.*\)/\2 \1/g' $filename
This commit is contained in:
Blerim Sheqa 2017-07-12 20:46:12 +02:00
parent 8c8cf4bfe7
commit eb88217e2d
23 changed files with 1436 additions and 1436 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
doc/1-about.md → doc/01-about.md
View File

@ -1,6 +1,6 @@
# <a id="about-icinga2"></a> About Icinga 2 # About Icinga 2 <a id="about-icinga2"></a>
## <a id="what-is-icinga2"></a> What is Icinga 2? ## What is Icinga 2? <a id="what-is-icinga2"></a>
Icinga 2 is an open source monitoring system which checks the availability of Icinga 2 is an open source monitoring system which checks the availability of
your network resources, notifies users of outages, and generates performance your network resources, notifies users of outages, and generates performance
@ -9,19 +9,19 @@ data for reporting.
Scalable and extensible, Icinga 2 can monitor large, complex environments across Scalable and extensible, Icinga 2 can monitor large, complex environments across
multiple locations. multiple locations.
## <a id="licensing"></a> Licensing ## Licensing <a id="licensing"></a>
Icinga 2 and the Icinga 2 documentation are licensed under the terms of the GNU Icinga 2 and the Icinga 2 documentation are licensed under the terms of the GNU
General Public License Version 2, you will find a copy of this license in the General Public License Version 2, you will find a copy of this license in the
LICENSE file included in the source package. LICENSE file included in the source package.
## <a id="support"></a> Support ## Support <a id="support"></a>
Check the project website at https://www.icinga.com for status updates. Join the Check the project website at https://www.icinga.com for status updates. Join the
[community channels](https://www.icinga.com/community/get-involved/) for questions [community channels](https://www.icinga.com/community/get-involved/) for questions
or ask an Icinga partner for [professional support](https://www.icinga.com/services/support/). or ask an Icinga partner for [professional support](https://www.icinga.com/services/support/).
## <a id="contribute"></a> Contribute ## Contribute <a id="contribute"></a>
There are many ways to contribute to Icinga -- whether it be sending patches, There are many ways to contribute to Icinga -- whether it be sending patches,
testing, reporting bugs, or reviewing and updating the documentation. Every testing, reporting bugs, or reviewing and updating the documentation. Every
@ -29,7 +29,7 @@ contribution is appreciated!
Please continue reading in the [Contributing chapter](https://github.com/Icinga/icinga2/blob/master/CONTRIBUTING.md). Please continue reading in the [Contributing chapter](https://github.com/Icinga/icinga2/blob/master/CONTRIBUTING.md).
### <a id="development-info"></a> Icinga 2 Development ### Icinga 2 Development <a id="development-info"></a>
The Git repository is located on [GitHub](https://github.com/Icinga/icinga2). The Git repository is located on [GitHub](https://github.com/Icinga/icinga2).
@ -37,7 +37,7 @@ Icinga 2 is written in C++ and can be built on Linux/Unix and Windows.
Read more about development builds in the [INSTALL.md](https://github.com/Icinga/icinga2/blob/master/INSTALL.md) Read more about development builds in the [INSTALL.md](https://github.com/Icinga/icinga2/blob/master/INSTALL.md)
file. file.
## <a id="whats-new"></a> What's New ## What's New <a id="whats-new"></a>
### What's New in Version 2.6.3 ### What's New in Version 2.6.3
@ -56,7 +56,7 @@ documentation.
* Feature [5029](https://github.com/Icinga/icinga2/issues/5029) (Documentation): Advanced topics: Wrong acknowledgement notification filter * Feature [5029](https://github.com/Icinga/icinga2/issues/5029) (Documentation): Advanced topics: Wrong acknowledgement notification filter
* Feature [5030](https://github.com/Icinga/icinga2/issues/5030) (Documentation): Advanced topics: Mention the API and explain stick acks, fixed/flexible downtimes * Feature [5030](https://github.com/Icinga/icinga2/issues/5030) (Documentation): Advanced topics: Mention the API and explain stick acks, fixed/flexible downtimes
* Feature [3133](https://github.com/Icinga/icinga2/issues/3133) (Documentation): [dev.icinga.com #9583] Add practical examples for apply expressions * Feature [3133](https://github.com/Icinga/icinga2/issues/3133) (Documentation): [dev.icinga.com #9583] Add practical examples for apply expressions
* Feature [4996](https://github.com/Icinga/icinga2/issues/4996) (Documentation): documentation: mixed up host names in 6-distributed-monitoring.md * Feature [4996](https://github.com/Icinga/icinga2/issues/4996) (Documentation): documentation: mixed up host names in 06-distributed-monitoring.md
* Feature [4980](https://github.com/Icinga/icinga2/issues/4980) (Documentation): Add OpenBSD and AlpineLinux package repositories to the documentation * Feature [4980](https://github.com/Icinga/icinga2/issues/4980) (Documentation): Add OpenBSD and AlpineLinux package repositories to the documentation
* Feature [4954](https://github.com/Icinga/icinga2/issues/4954) (Documentation): Add an example for /v1/actions/process-check-result which uses filter/type * Feature [4954](https://github.com/Icinga/icinga2/issues/4954) (Documentation): Add an example for /v1/actions/process-check-result which uses filter/type
@ -87,7 +87,7 @@ reflect our recent move to GitHub.
#### Feature #### Feature
* Feature [4950](https://github.com/Icinga/icinga2/issues/4950) (Documentation): doc/6-distributed-monitoring.md: Fix typo * Feature [4950](https://github.com/Icinga/icinga2/issues/4950) (Documentation): doc/06-distributed-monitoring.md: Fix typo
* Feature [4934](https://github.com/Icinga/icinga2/issues/4934) (Documentation): Update contribution section for GitHub * Feature [4934](https://github.com/Icinga/icinga2/issues/4934) (Documentation): Update contribution section for GitHub
* Feature [4923](https://github.com/Icinga/icinga2/issues/4923) (Documentation): [dev.icinga.com #14011] Migration to Github * Feature [4923](https://github.com/Icinga/icinga2/issues/4923) (Documentation): [dev.icinga.com #14011] Migration to Github
* Feature [4917](https://github.com/Icinga/icinga2/issues/4917) (Documentation): [dev.icinga.com #13969] Incorrect license file mentioned in README.md * Feature [4917](https://github.com/Icinga/icinga2/issues/4917) (Documentation): [dev.icinga.com #13969] Incorrect license file mentioned in README.md

88
doc/2-getting-started.md → doc/02-getting-started.md
View File

@ -1,10 +1,10 @@
# <a id="getting-started"></a> Getting Started # Getting Started <a id="getting-started"></a>
This tutorial is a step-by-step introduction to installing [Icinga 2](2-getting-started.md#setting-up-icinga2) This tutorial is a step-by-step introduction to installing [Icinga 2](02-getting-started.md#setting-up-icinga2)
and [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2). and [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2).
It assumes that you are familiar with the operating system you're using to install Icinga 2. It assumes that you are familiar with the operating system you're using to install Icinga 2.
## <a id="setting-up-icinga2"></a> Setting up Icinga 2 ## Setting up Icinga 2 <a id="setting-up-icinga2"></a>
First off you have to install Icinga 2. The preferred way of doing this 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 is to use the official package repositories depending on which operating system
@ -26,7 +26,7 @@ and distribution you are running.
Packages for distributions other than the ones listed above may also be Packages for distributions other than the ones listed above may also be
available. Please contact your distribution packagers. available. Please contact your distribution packagers.
### <a id="package-repositories"></a> Package Repositories ### Package Repositories <a id="package-repositories"></a>
You need to add the Icinga repository to your package management configuration. You need to add the Icinga repository to your package management configuration.
Below is a list with examples for the various distributions. Below is a list with examples for the various distributions.
@ -75,7 +75,7 @@ openSUSE:
# zypper ref # zypper ref
#### <a id="package-repositories-rhel-epel"></a> RHEL/CentOS EPEL Repository #### RHEL/CentOS EPEL Repository <a id="package-repositories-rhel-epel"></a>
The packages for RHEL/CentOS depend on other packages which are distributed The packages for RHEL/CentOS depend on other packages which are distributed
as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL). as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL).
@ -87,17 +87,17 @@ CentOS 7/6:
If you are using RHEL you need enable the `optional` repository and then install If you are using RHEL you need enable the `optional` repository and then install
the [EPEL rpm package](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F). the [EPEL rpm package](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F).
#### <a id="package-repositories-sles-security"></a> SLES Security Repository #### SLES Security Repository <a id="package-repositories-sles-security"></a>
The packages for SLES 11 depend on the `openssl1` package which is distributed The packages for SLES 11 depend on the `openssl1` package which is distributed
as part of the [SLES 11 Security Module](https://www.suse.com/communities/conversations/introducing-the-suse-linux-enterprise-11-security-module/). as part of the [SLES 11 Security Module](https://www.suse.com/communities/conversations/introducing-the-suse-linux-enterprise-11-security-module/).
#### <a id="package-sles-sdk"></a> SLES 12 SDK #### SLES 12 SDK <a id="package-sles-sdk"></a>
Icinga 2 requires the `libboost_chrono1_54_0` package from the `SLES 12 SDK` repository. Refer to the SUSE Enterprise Icinga 2 requires the `libboost_chrono1_54_0` package from the `SLES 12 SDK` repository. Refer to the SUSE Enterprise
Linux documentation for further information. Linux documentation for further information.
### <a id="installing-icinga2"></a> Installing Icinga 2 ### Installing Icinga 2 <a id="installing-icinga2"></a>
You can install Icinga 2 by using your distribution's package manager You can install Icinga 2 by using your distribution's package manager
to install the `icinga2` package. to install the `icinga2` package.
@ -126,7 +126,7 @@ FreeBSD:
# pkg install icinga2 # pkg install icinga2
### <a id="installation-enabled-features"></a> Enabled Features during Installation ### Enabled Features during Installation <a id="installation-enabled-features"></a>
The default installation will enable three features required for a basic The default installation will enable three features required for a basic
Icinga 2 installation: Icinga 2 installation:
@ -144,7 +144,7 @@ enabled and disabled.
Enabled features: checker mainlog notification Enabled features: checker mainlog notification
### <a id="installation-paths"></a> Installation Paths ### Installation Paths <a id="installation-paths"></a>
By default Icinga 2 uses the following files and directories: By default Icinga 2 uses the following files and directories:
@ -183,14 +183,14 @@ By default Icinga 2 uses the following files and directories:
/var/lib/icinga2 | Icinga 2 state file, cluster log, local CA and configuration files (cluster, api). /var/lib/icinga2 | Icinga 2 state file, cluster log, local CA and configuration files (cluster, api).
/var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature. /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
## <a id="setting-up-check-plugins"></a> Setting up Check Plugins ## Setting up Check Plugins <a id="setting-up-check-plugins"></a>
Without plugins Icinga 2 does not know how to check external services. The Without plugins Icinga 2 does not know how to check external services. The
[Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
an extensive set of plugins which can be used with Icinga 2 to check whether an extensive set of plugins which can be used with Icinga 2 to check whether
services are working properly. services are working properly.
These plugins are required to make the [example configuration](4-configuring-icinga-2.md#configuring-icinga2-overview) These plugins are required to make the [example configuration](04-configuring-icinga-2.md#configuring-icinga2-overview)
work out-of-the-box. work out-of-the-box.
For your convenience here is a list of package names for some of the more For your convenience here is a list of package names for some of the more
@ -237,18 +237,18 @@ FreeBSD:
# pkg install monitoring-plugins # pkg install monitoring-plugins
Depending on which directory your plugins are installed into you may need to Depending on which directory your plugins are installed into you may need to
update the global `PluginDir` constant in your [Icinga 2 configuration](4-configuring-icinga-2.md#constants-conf). update the global `PluginDir` constant in your [Icinga 2 configuration](04-configuring-icinga-2.md#constants-conf).
This constant is used by the check command definitions contained in the Icinga Template Library This constant is used by the check command definitions contained in the Icinga Template Library
to determine where to find the plugin binaries. to determine where to find the plugin binaries.
> **Note** > **Note**
> >
> Please refer to the [service monitoring](5-service-monitoring.md#service-monitoring-plugins) chapter for details about how to integrate > 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. > additional check plugins into your Icinga 2 setup.
## <a id="running-icinga2"></a> Running Icinga 2 ## Running Icinga 2 <a id="running-icinga2"></a>
### <a id="init-script"></a> Init Script ### Init Script <a id="init-script"></a>
Icinga 2's init script is installed in `/etc/init.d/icinga2` (`/usr/local/etc/rc.d/icinga2` on FreeBSD) by default: Icinga 2's init script is installed in `/etc/init.d/icinga2` (`/usr/local/etc/rc.d/icinga2` on FreeBSD) by default:
@ -270,7 +270,7 @@ 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 using the init script. Using Debian packages the user and group are set to
`nagios` for historical reasons. `nagios` for historical reasons.
### <a id="systemd-service"></a> systemd Service ### systemd Service <a id="systemd-service"></a>
Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The
Icinga 2 packages automatically install the necessary systemd unit files. Icinga 2 packages automatically install the necessary systemd unit files.
@ -326,7 +326,7 @@ On FreeBSD you need to enable icinga2 in your rc.conf
# service icinga2 restart # service icinga2 restart
## <a id="configuration-syntax-highlighting"></a> Configuration Syntax Highlighting ## Configuration Syntax Highlighting <a id="configuration-syntax-highlighting"></a>
Icinga 2 ships configuration examples for syntax highlighting using the `vim` and `nano` editors. Icinga 2 ships 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` The RHEL and SUSE package `icinga2-common` installs these files into `/usr/share/doc/icinga2-common-[x.x.x]/syntax`
@ -334,7 +334,7 @@ The RHEL and SUSE package `icinga2-common` installs these files into `/usr/share
On Debian systems the `icinga2-common` package provides only the Nano configuration file (`/usr/share/nano/icinga2.nanorc`); 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`. to obtain the Vim configuration, please install the extra package `vim-icinga2`. The files are located in `/usr/share/vim/addons`.
### <a id="configuration-syntax-highlighting-vim"></a> Configuration Syntax Highlighting using Vim ### Configuration Syntax Highlighting using Vim <a id="configuration-syntax-highlighting-vim"></a>
Install the package `vim-icinga2` with your distribution's package manager. Install the package `vim-icinga2` with your distribution's package manager.
@ -365,7 +365,7 @@ Test it:
![Vim with syntax highlighting](images/getting-started/vim-syntax.png "Vim with Icinga 2 syntax highlighting") ![Vim with syntax highlighting](images/getting-started/vim-syntax.png "Vim with Icinga 2 syntax highlighting")
### <a id="configuration-syntax-highlighting-nano"></a> Configuration Syntax Highlighting using Nano ### Configuration Syntax Highlighting using Nano <a id="configuration-syntax-highlighting-nano"></a>
Install the package `nano-icinga2` with your distribution's package manager. Install the package `nano-icinga2` with your distribution's package manager.
@ -398,7 +398,7 @@ Test it:
![Nano with syntax highlighting](images/getting-started/nano-syntax.png "Nano with Icinga 2 syntax highlighting") ![Nano with syntax highlighting](images/getting-started/nano-syntax.png "Nano with Icinga 2 syntax highlighting")
## <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2 ## Setting up Icinga Web 2 <a id="setting-up-icingaweb2"></a>
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 number of other web interfaces.
This chapter explains how to set up Icinga Web 2. This chapter explains how to set up Icinga Web 2.
@ -406,18 +406,18 @@ This chapter explains how to set up Icinga Web 2.
The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of 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 exporting all configuration and status information into a database. The IDO
database is used by a number of projects including database is used by a number of projects including
[Icinga Web 2](2-getting-started.md#setting-up-icingaweb2), Icinga Reporting [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2), Icinga Reporting
or Icinga Web 1.x. or Icinga Web 1.x.
There is a separate module for each database backend. At present support for There is a separate module for each database backend. At present support for
both MySQL and PostgreSQL is implemented. both MySQL and PostgreSQL is implemented.
Please choose whether to install [MySQL](2-getting-started.md#configuring-db-ido-mysql) or Please choose whether to install [MySQL](02-getting-started.md#configuring-db-ido-mysql) or
[PostgreSQL](2-getting-started.md#configuring-db-ido-postgresql). [PostgreSQL](02-getting-started.md#configuring-db-ido-postgresql).
### <a id="configuring-db-ido-mysql"></a> Configuring DB IDO MySQL ### Configuring DB IDO MySQL <a id="configuring-db-ido-mysql"></a>
#### <a id="installing-database-mysql-server"></a> Installing MySQL database server #### Installing MySQL database server <a id="installing-database-mysql-server"></a>
Debian/Ubuntu: Debian/Ubuntu:
@ -451,7 +451,7 @@ FreeBSD:
# service mysql-server restart # service mysql-server restart
# mysql_secure_installation # mysql_secure_installation
#### <a id="installing-database-mysql-modules"></a> Installing the IDO modules for MySQL #### Installing the IDO modules for MySQL <a id="installing-database-mysql-modules"></a>
The next step is to install the `icinga2-ido-mysql` package using your The next step is to install the `icinga2-ido-mysql` package using your
distribution's package manager. distribution's package manager.
@ -479,7 +479,7 @@ and located at /usr/local/share/icinga2-ido-mysql/schema/mysql.sql
> default. You can skip the automated setup and install/upgrade the > default. You can skip the automated setup and install/upgrade the
> database manually if you prefer that. > database manually if you prefer that.
#### <a id="setting-up-mysql-db"></a> Setting up the MySQL database #### Setting up the MySQL database <a id="setting-up-mysql-db"></a>
Set up a MySQL database for Icinga 2: Set up a MySQL database for Icinga 2:
@ -497,14 +497,14 @@ following command:
# mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql
#### <a id="enabling-ido-mysql"></a> Enabling the IDO MySQL module #### Enabling the IDO MySQL module <a id="enabling-ido-mysql"></a>
The package provides a new configuration file that is installed in The package provides a new configuration file that is installed in
`/etc/icinga2/features-available/ido-mysql.conf`. You will need to `/etc/icinga2/features-available/ido-mysql.conf`. You will need to
update the database credentials in this file. update the database credentials in this file.
All available attributes are explained in the All available attributes are explained in the
[IdoMysqlConnection object](9-object-types.md#objecttype-idomysqlconnection) [IdoMysqlConnection object](09-object-types.md#objecttype-idomysqlconnection)
chapter. chapter.
You can enable the `ido-mysql` feature configuration file using You can enable the `ido-mysql` feature configuration file using
@ -529,11 +529,11 @@ FreeBSD:
# service icinga2 restart # service icinga2 restart
Continue with the [webserver setup](2-getting-started.md#icinga2-user-interface-webserver). Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver).
### <a id="configuring-db-ido-postgresql"></a> Configuring DB IDO PostgreSQL ### Configuring DB IDO PostgreSQL <a id="configuring-db-ido-postgresql"></a>
#### <a id="installing-database-postgresql-server"></a> Installing PostgreSQL database server #### Installing PostgreSQL database server <a id="installing-database-postgresql-server"></a>
Debian/Ubuntu: Debian/Ubuntu:
@ -564,7 +564,7 @@ FreeBSD:
# sysrc postgresql_enable=yes # sysrc postgresql_enable=yes
# service postgresql start # service postgresql start
#### <a id="installing-database-postgresql-modules"></a> Installing the IDO modules for PostgreSQL #### Installing the IDO modules for PostgreSQL <a id="installing-database-postgresql-modules"></a>
The next step is to install the `icinga2-ido-pgsql` package using your The next step is to install the `icinga2-ido-pgsql` package using your
distribution's package manager. distribution's package manager.
@ -635,14 +635,14 @@ schema using the following command:
![importing the Icinga 2 IDO schema](images/getting-started/postgr-import-ido.png "Importing the Icinga 2 IDO schema on Debian Jessie") ![importing the Icinga 2 IDO schema](images/getting-started/postgr-import-ido.png "Importing the Icinga 2 IDO schema on Debian Jessie")
#### <a id="enabling-ido-postgresql"></a> Enabling the IDO PostgreSQL module #### Enabling the IDO PostgreSQL module <a id="enabling-ido-postgresql"></a>
The package provides a new configuration file that is installed in 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 will need to update
the database credentials in this file. the database credentials in this file.
All available attributes are explained in the All available attributes are explained in the
[IdoPgsqlConnection object](9-object-types.md#objecttype-idopgsqlconnection) [IdoPgsqlConnection object](09-object-types.md#objecttype-idopgsqlconnection)
chapter. chapter.
You can enable the `ido-pgsql` feature configuration file using You can enable the `ido-pgsql` feature configuration file using
@ -666,9 +666,9 @@ FreeBSD:
# service icinga2 restart # service icinga2 restart
Continue with the [webserver setup](2-getting-started.md#icinga2-user-interface-webserver). Continue with the [webserver setup](02-getting-started.md#icinga2-user-interface-webserver).
### <a id="icinga2-user-interface-webserver"></a> Webserver ### Webserver <a id="icinga2-user-interface-webserver"></a>
Debian/Ubuntu: Debian/Ubuntu:
@ -704,7 +704,7 @@ FreeBSD (nginx, but you could also use the apache24 package):
# service php-fpm start # service php-fpm start
# service nginx start # service nginx start
### <a id="icinga2-user-interface-firewall-rules"></a> Firewall Rules ### Firewall Rules <a id="icinga2-user-interface-firewall-rules"></a>
Example: Example:
@ -720,7 +720,7 @@ 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. 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.
### <a id="setting-up-rest-api"></a> Setting Up Icinga 2 REST API ### Setting Up Icinga 2 REST API <a id="setting-up-rest-api"></a>
Icinga Web 2 and other web interfaces require the [REST API](12-icinga2-api.md#icinga2-api-setup) 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. to send actions (reschedule check, etc.) and query object details.
@ -756,7 +756,7 @@ FreeBSD:
# service icinga2 restart # service icinga2 restart
### <a id="installing-icingaweb2"></a> Installing Icinga Web 2 ### Installing Icinga Web 2 <a id="installing-icingaweb2"></a>
Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/02-Installation.md) Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/02-Installation.md)
for further instructions on how to install Icinga Web 2. for further instructions on how to install Icinga Web 2.
@ -764,13 +764,13 @@ for further instructions on how to install Icinga Web 2.
The Icinga 2 API can be defined as [command transport](https://github.com/Icinga/icingaweb2/blob/master/modules/monitoring/doc/commandtransports.md) The Icinga 2 API can be defined as [command transport](https://github.com/Icinga/icingaweb2/blob/master/modules/monitoring/doc/commandtransports.md)
in Icinga Web 2 >= 2.4. in Icinga Web 2 >= 2.4.
## <a id="install-addons"></a> Addons ## Addons <a id="install-addons"></a>
A number of additional features are available in the form of addons. A list of A number of additional features are available in the form of addons. A list of
popular addons is available in the popular addons is available in the
[Addons and Plugins](13-addons.md#addons) chapter. [Addons and Plugins](13-addons.md#addons) chapter.
## <a id="install-backup"></a> Backup ## Backup <a id="install-backup"></a>
Ensure to include the following in your backups: Ensure to include the following in your backups:

250
doc/3-monitoring-basics.md → doc/03-monitoring-basics.md
View File

@ -1,4 +1,4 @@
# <a id="monitoring-basics"></a> Monitoring Basics # Monitoring Basics <a id="monitoring-basics"></a>
This part of the Icinga 2 documentation provides an overview of all the basic This part of the Icinga 2 documentation provides an overview of all the basic
monitoring concepts you need to know to run Icinga 2. monitoring concepts you need to know to run Icinga 2.
@ -6,7 +6,7 @@ Keep in mind these examples are made with a Linux server. If you are
using Windows, you will need to change the services accordingly. See the [ITL reference](10-icinga-template-library.md#windows-plugins) using Windows, you will need to change the services accordingly. See the [ITL reference](10-icinga-template-library.md#windows-plugins)
for further information. for further information.
## <a id="hosts-services"></a> Hosts and Services ## Hosts and Services <a id="hosts-services"></a>
Icinga 2 can be used to monitor the availability of hosts and services. Hosts Icinga 2 can be used to monitor the availability of hosts and services. Hosts
and services can be virtually anything which can be checked in some way: and services can be virtually anything which can be checked in some way:
@ -48,7 +48,7 @@ address is associated with the host object.
Details on troubleshooting check problems can be found [here](15-troubleshooting.md#troubleshooting). Details on troubleshooting check problems can be found [here](15-troubleshooting.md#troubleshooting).
### <a id="host-states"></a> Host States ### Host States <a id="host-states"></a>
Hosts can be in any of the following states: Hosts can be in any of the following states:
@ -57,7 +57,7 @@ Hosts can be in any of the following states:
UP | The host is available. UP | The host is available.
DOWN | The host is unavailable. DOWN | The host is unavailable.
### <a id="service-states"></a> Service States ### Service States <a id="service-states"></a>
Services can be in any of the following states: Services can be in any of the following states:
@ -68,7 +68,7 @@ Services can be in any of the following states:
CRITICAL | The service is in a critical state. CRITICAL | The service is in a critical state.
UNKNOWN | The check could not determine the service's state. UNKNOWN | The check could not determine the service's state.
### <a id="hard-soft-states"></a> Hard and Soft States ### Hard and Soft States <a id="hard-soft-states"></a>
When detecting a problem with a host/service Icinga re-checks the object a number of When detecting a problem with a host/service Icinga re-checks the object a number of
times (based on the `max_check_attempts` and `retry_interval` settings) before sending times (based on the `max_check_attempts` and `retry_interval` settings) before sending
@ -83,7 +83,7 @@ state the host/service switches to a `HARD` state and notifications are sent.
HARD | The host/service's state hasn't recently changed. HARD | The host/service's state hasn't recently changed.
SOFT | The host/service has recently changed state and is being re-checked. SOFT | The host/service has recently changed state and is being re-checked.
### <a id="host-service-checks"></a> Host and Service Checks ### Host and Service Checks <a id="host-service-checks"></a>
Hosts and services determine their state by running checks in a regular interval. Hosts and services determine their state by running checks in a regular interval.
@ -101,7 +101,7 @@ available. In addition to these commands the next few chapters will explain in
detail how to set up your own check commands. detail how to set up your own check commands.
## <a id="object-inheritance-using-templates"></a> Templates ## Templates <a id="object-inheritance-using-templates"></a>
Templates may be used to apply a set of identical attributes to more than one Templates may be used to apply a set of identical attributes to more than one
object: object:
@ -142,7 +142,7 @@ and objects share the same namespace, i.e. you can't define a template
that has the same name like an object. that has the same name like an object.
## <a id="custom-attributes"></a> Custom Attributes ## Custom Attributes <a id="custom-attributes"></a>
In addition to built-in attributes you can define your own attributes: In addition to built-in attributes you can define your own attributes:
@ -154,9 +154,9 @@ Valid values for custom attributes include:
* [Strings](17-language-reference.md#string-literals), [numbers](17-language-reference.md#numeric-literals) and [booleans](17-language-reference.md#boolean-literals) * [Strings](17-language-reference.md#string-literals), [numbers](17-language-reference.md#numeric-literals) and [booleans](17-language-reference.md#boolean-literals)
* [Arrays](17-language-reference.md#array) and [dictionaries](17-language-reference.md#dictionary) * [Arrays](17-language-reference.md#array) and [dictionaries](17-language-reference.md#dictionary)
* [Functions](3-monitoring-basics.md#custom-attributes-functions) * [Functions](03-monitoring-basics.md#custom-attributes-functions)
### <a id="custom-attributes-functions"></a> Functions as Custom Attributes ### Functions as Custom Attributes <a id="custom-attributes-functions"></a>
Icinga 2 lets you specify [functions](17-language-reference.md#functions) for custom attributes. Icinga 2 lets you specify [functions](17-language-reference.md#functions) for custom attributes.
The special case here is that whenever Icinga 2 needs the value for such a custom attribute it runs The special case here is that whenever Icinga 2 needs the value for such a custom attribute it runs
@ -218,9 +218,9 @@ command and arguments that should be executed via SSH:
} }
Acessing object attributes at runtime inside these functions is described in the Acessing object attributes at runtime inside these functions is described in the
[advanced topics](8-advanced-topics.md#access-object-attributes-at-runtime) chapter. [advanced topics](08-advanced-topics.md#access-object-attributes-at-runtime) chapter.
## <a id="runtime-macros"></a> Runtime Macros ## Runtime Macros <a id="runtime-macros"></a>
Macros can be used to access other objects' attributes at runtime. For example they Macros can be used to access other objects' attributes at runtime. For example they
are used in command definitions to figure out which IP address a check should be are used in command definitions to figure out which IP address a check should be
@ -264,7 +264,7 @@ exact rules for this are explained in the next section.
> additional dollar character (`$$`). > additional dollar character (`$$`).
### <a id="macro-evaluation-order"></a> Evaluation Order ### Evaluation Order <a id="macro-evaluation-order"></a>
When executing commands Icinga 2 checks the following objects in this order to look When executing commands Icinga 2 checks the following objects in this order to look
up macros and their respective values: up macros and their respective values:
@ -301,7 +301,7 @@ returns an empty value if the service does not have such a custom attribute no m
whether another object such as the host has this attribute. whether another object such as the host has this attribute.
### <a id="host-runtime-macros"></a> Host Runtime Macros ### Host Runtime Macros <a id="host-runtime-macros"></a>
The following host custom attributes are available in all commands that are executed for The following host custom attributes are available in all commands that are executed for
hosts or services: hosts or services:
@ -333,7 +333,7 @@ hosts or services:
host.num_services_unknown | Number of services associated with the host which are in an `UNKNOWN` state. host.num_services_unknown | Number of services associated with the host which are in an `UNKNOWN` state.
host.num_services_critical | Number of services associated with the host which are in a `CRITICAL` state. host.num_services_critical | Number of services associated with the host which are in a `CRITICAL` state.
### <a id="service-runtime-macros"></a> Service Runtime Macros ### Service Runtime Macros <a id="service-runtime-macros"></a>
The following service macros are available in all commands that are executed for The following service macros are available in all commands that are executed for
services: services:
@ -361,7 +361,7 @@ services:
service.last_check | The timestamp when the last check was executed. service.last_check | The timestamp when the last check was executed.
service.check_source | The monitoring instance that performed the last check. service.check_source | The monitoring instance that performed the last check.
### <a id="command-runtime-macros"></a> Command Runtime Macros ### Command Runtime Macros <a id="command-runtime-macros"></a>
The following custom attributes are available in all commands: The following custom attributes are available in all commands:
@ -369,7 +369,7 @@ The following custom attributes are available in all commands:
-----------------------|-------------- -----------------------|--------------
command.name | The name of the command object. command.name | The name of the command object.
### <a id="user-runtime-macros"></a> User Runtime Macros ### User Runtime Macros <a id="user-runtime-macros"></a>
The following custom attributes are available in all commands that are executed for The following custom attributes are available in all commands that are executed for
users: users:
@ -379,7 +379,7 @@ users:
user.name | The name of the user object. user.name | The name of the user object.
user.display_name | The value of the display_name attribute. user.display_name | The value of the display_name attribute.
### <a id="notification-runtime-macros"></a> Notification Runtime Macros ### Notification Runtime Macros <a id="notification-runtime-macros"></a>
Name | Description Name | Description
-----------------------|-------------- -----------------------|--------------
@ -387,7 +387,7 @@ users:
notification.author | The author of the notification comment if existing. notification.author | The author of the notification comment if existing.
notification.comment | The comment of the notification if existing. notification.comment | The comment of the notification if existing.
### <a id="global-runtime-macros"></a> Global Runtime Macros ### Global Runtime Macros <a id="global-runtime-macros"></a>
The following macros are available in all executed commands: The following macros are available in all executed commands:
@ -422,12 +422,12 @@ The following macros provide global statistics:
icinga.num_hosts_acknowledged | Current number of acknowledged host problems. icinga.num_hosts_acknowledged | Current number of acknowledged host problems.
## <a id="using-apply"></a> Apply Rules ## Apply Rules <a id="using-apply"></a>
Several object types require an object relation, e.g. [Service](9-object-types.md#objecttype-service), Several object types require an object relation, e.g. [Service](09-object-types.md#objecttype-service),
[Notification](9-object-types.md#objecttype-notification), [Dependency](9-object-types.md#objecttype-dependency), [Notification](09-object-types.md#objecttype-notification), [Dependency](09-object-types.md#objecttype-dependency),
[ScheduledDowntime](9-object-types.md#objecttype-scheduleddowntime) objects. [ScheduledDowntime](09-object-types.md#objecttype-scheduleddowntime) objects.
If you for example create a service object you have to specify the [host_name](9-object-types.md#objecttype-service) If you for example create a service object you have to specify the [host_name](09-object-types.md#objecttype-service)
attribute and reference an existing host attribute. attribute and reference an existing host attribute.
object Service "ping4" { object Service "ping4" {
@ -436,7 +436,7 @@ attribute and reference an existing host attribute.
} }
This isn't comfortable when managing a huge set of configuration objects which could This isn't comfortable when managing a huge set of configuration objects which could
[match](3-monitoring-basics.md#using-apply-expressions) on a common pattern. [match](03-monitoring-basics.md#using-apply-expressions) on a common pattern.
Instead you want to use **[apply](17-language-reference.md#apply) rules**. Instead you want to use **[apply](17-language-reference.md#apply) rules**.
@ -449,36 +449,36 @@ instead of 1000 service objects. Apply rules will automatically generate them fo
assign where host.address assign where host.address
} }
More explanations on assign where expressions can be found [here](3-monitoring-basics.md#using-apply-expressions). More explanations on assign where expressions can be found [here](03-monitoring-basics.md#using-apply-expressions).
Before you start with apply rules keep the following in mind: Before you start with apply rules keep the following in mind:
* Define the best match. * Define the best match.
* A set of unique [custom attributes](3-monitoring-basics.md#custom-attributes) for these hosts/services? * A set of unique [custom attributes](03-monitoring-basics.md#custom-attributes) for these hosts/services?
* Or [group](3-monitoring-basics.md#groups) memberships, e.g. a host being a member of a hostgroup which should have a service set? * Or [group](03-monitoring-basics.md#groups) memberships, e.g. a host being a member of a hostgroup which should have a service set?
* A generic pattern [match](18-library-reference.md#global-functions-match) on the host/service name? * A generic pattern [match](18-library-reference.md#global-functions-match) on the host/service name?
* [Multiple expressions combined](3-monitoring-basics.md#using-apply-expressions) with `&&` or `||` [operators](17-language-reference.md#expression-operators) * [Multiple expressions combined](03-monitoring-basics.md#using-apply-expressions) with `&&` or `||` [operators](17-language-reference.md#expression-operators)
* All expressions must return a boolean value (an empty string is equal to `false` e.g.) * All expressions must return a boolean value (an empty string is equal to `false` e.g.)
More specific object type requirements are described in these chapters: More specific object type requirements are described in these chapters:
* [Apply services to hosts](3-monitoring-basics.md#using-apply-services) * [Apply services to hosts](03-monitoring-basics.md#using-apply-services)
* [Apply notifications to hosts and services](3-monitoring-basics.md#using-apply-notifications) * [Apply notifications to hosts and services](03-monitoring-basics.md#using-apply-notifications)
* [Apply dependencies to hosts and services](3-monitoring-basics.md#using-apply-dependencies) * [Apply dependencies to hosts and services](03-monitoring-basics.md#using-apply-dependencies)
* [Apply scheduled downtimes to hosts and services](3-monitoring-basics.md#using-apply-scheduledowntimes) * [Apply scheduled downtimes to hosts and services](03-monitoring-basics.md#using-apply-scheduledowntimes)
You can set/override object attributes in apply rules using the respectively available You can set/override object attributes in apply rules using the respectively available
objects in that scope (host and/or service objects). objects in that scope (host and/or service objects).
vars.application_type = host.vars.application_type vars.application_type = host.vars.application_type
[Custom attributes](3-monitoring-basics.md#custom-attributes) can also store nested dictionaries and arrays. That way you can use them [Custom attributes](03-monitoring-basics.md#custom-attributes) can also store nested dictionaries and arrays. That way you can use them
for not only matching for their existence or values in apply expressions, but also assign for not only matching for their existence or values in apply expressions, but also assign
("inherit") their values into the generated objected from apply rules. ("inherit") their values into the generated objected from apply rules.
A more advanced example is to use [apply rules with for loops on arrays or A more advanced example is to use [apply rules with for loops on arrays or
dictionaries](3-monitoring-basics.md#using-apply-for) provided by dictionaries](03-monitoring-basics.md#using-apply-for) provided by
[custom atttributes](3-monitoring-basics.md#custom-attributes) or groups. [custom atttributes](03-monitoring-basics.md#custom-attributes) or groups.
> **Tip** > **Tip**
> >
@ -487,7 +487,7 @@ dictionaries](3-monitoring-basics.md#using-apply-for) provided by
> after successful [configuration validation](11-cli-commands.md#config-validation). > after successful [configuration validation](11-cli-commands.md#config-validation).
### <a id="using-apply-expressions"></a> Apply Rules Expressions ### Apply Rules Expressions <a id="using-apply-expressions"></a>
You can use simple or advanced combinations of apply rule expressions. Each You can use simple or advanced combinations of apply rule expressions. Each
expression must evaluate into the boolean `true` value. An empty string expression must evaluate into the boolean `true` value. An empty string
@ -504,7 +504,7 @@ You can combine multiple expressions for matching only a subset of objects. In s
you want to be able to add more than one assign/ignore where expression which matches you want to be able to add more than one assign/ignore where expression which matches
a specific condition. To achieve this you can use the logical `and` and `or` operators. a specific condition. To achieve this you can use the logical `and` and `or` operators.
#### <a id="using-apply-expressions-examples"></a> Apply Rules Expressions Examples #### Apply Rules Expressions Examples <a id="using-apply-expressions-examples"></a>
Assign a service to a specific host in a host group [array](18-library-reference.md#array-type) using the [in operator](17-language-reference.md#expression-operators): Assign a service to a specific host in a host group [array](18-library-reference.md#array-type) using the [in operator](17-language-reference.md#expression-operators):
@ -561,12 +561,12 @@ The notification is ignored for services whose host name ends with `*internal`
ignore where match("*internal", host.name) || (service.vars.priority < 2 && host.vars.is_clustered == true) ignore where match("*internal", host.name) || (service.vars.priority < 2 && host.vars.is_clustered == true)
} }
More advanced examples are covered [here](8-advanced-topics.md#use-functions-assign-where). More advanced examples are covered [here](08-advanced-topics.md#use-functions-assign-where).
### <a id="using-apply-services"></a> Apply Services to Hosts ### Apply Services to Hosts <a id="using-apply-services"></a>
The sample configuration already includes a detailed example in [hosts.conf](4-configuring-icinga-2.md#hosts-conf) The sample configuration already includes a detailed example in [hosts.conf](04-configuring-icinga-2.md#hosts-conf)
and [services.conf](4-configuring-icinga-2.md#services-conf) for this use case. and [services.conf](04-configuring-icinga-2.md#services-conf) for this use case.
The example for `ssh` applies a service object to all hosts with the `address` The example for `ssh` applies a service object to all hosts with the `address`
attribute being defined and the custom attribute `os` set to the string `Linux` in `vars`. attribute being defined and the custom attribute `os` set to the string `Linux` in `vars`.
@ -580,9 +580,9 @@ attribute being defined and the custom attribute `os` set to the string `Linux`
} }
Other detailed examples are used in their respective chapters, for example Other detailed examples are used in their respective chapters, for example
[apply services with custom command arguments](3-monitoring-basics.md#command-passing-parameters). [apply services with custom command arguments](03-monitoring-basics.md#command-passing-parameters).
### <a id="using-apply-notifications"></a> Apply Notifications to Hosts and Services ### Apply Notifications to Hosts and Services <a id="using-apply-notifications"></a>
Notifications are applied to specific targets (`Host` or `Service`) and work in a similar Notifications are applied to specific targets (`Host` or `Service`) and work in a similar
manner: manner:
@ -647,25 +647,25 @@ The corresponding host object could look like this:
vars.notification_type = "sms" vars.notification_type = "sms"
} }
### <a id="using-apply-dependencies"></a> Apply Dependencies to Hosts and Services ### Apply Dependencies to Hosts and Services <a id="using-apply-dependencies"></a>
Detailed examples can be found in the [dependencies](3-monitoring-basics.md#dependencies) chapter. Detailed examples can be found in the [dependencies](03-monitoring-basics.md#dependencies) chapter.
### <a id="using-apply-scheduledowntimes"></a> Apply Recurring Downtimes to Hosts and Services ### Apply Recurring Downtimes to Hosts and Services <a id="using-apply-scheduledowntimes"></a>
The sample configuration includes an example in [downtimes.conf](4-configuring-icinga-2.md#downtimes-conf). The sample configuration includes an example in [downtimes.conf](04-configuring-icinga-2.md#downtimes-conf).
Detailed examples can be found in the [recurring downtimes](8-advanced-topics.md#recurring-downtimes) chapter. Detailed examples can be found in the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) chapter.
### <a id="using-apply-for"></a> Using Apply For Rules ### Using Apply For Rules <a id="using-apply-for"></a>
Next to the standard way of using [apply rules](3-monitoring-basics.md#using-apply) Next to the standard way of using [apply rules](03-monitoring-basics.md#using-apply)
there is the requirement of applying objects based on a set (array or there is the requirement of applying objects based on a set (array or
dictionary) using [apply for](17-language-reference.md#apply-for) expressions. dictionary) using [apply for](17-language-reference.md#apply-for) expressions.
The sample configuration already includes a detailed example in [hosts.conf](4-configuring-icinga-2.md#hosts-conf) The sample configuration already includes a detailed example in [hosts.conf](04-configuring-icinga-2.md#hosts-conf)
and [services.conf](4-configuring-icinga-2.md#services-conf) for this use case. and [services.conf](04-configuring-icinga-2.md#services-conf) for this use case.
Take the following example: A host provides the snmp oids for different service check Take the following example: A host provides the snmp oids for different service check
types. This could look like the following example: types. This could look like the following example:
@ -710,7 +710,7 @@ That way you'll save duplicated apply rules by combining them into one
generic `apply for` rule generating the object name with or without a prefix. generic `apply for` rule generating the object name with or without a prefix.
#### <a id="using-apply-for-custom-attribute-override"></a> Apply For and Custom Attribute Override #### Apply For and Custom Attribute Override <a id="using-apply-for-custom-attribute-override"></a>
Imagine a different more advanced example: You are monitoring your network device (host) Imagine a different more advanced example: You are monitoring your network device (host)
with many interfaces (services). The following requirements/problems apply: with many interfaces (services). The following requirements/problems apply:
@ -722,12 +722,12 @@ with many interfaces (services). The following requirements/problems apply:
dynamically generated dynamically generated
Tip: Define the snmp community as global constant in your [constants.conf](4-configuring-icinga-2.md#constants-conf) file. Tip: Define the snmp community as global constant in your [constants.conf](04-configuring-icinga-2.md#constants-conf) file.
const IftrafficSnmpCommunity = "public" const IftrafficSnmpCommunity = "public"
By defining the `interfaces` dictionary with three example interfaces on the `cisco-catalyst-6509-34` By defining the `interfaces` dictionary with three example interfaces on the `cisco-catalyst-6509-34`
host object, you'll make sure to pass the [custom attribute](3-monitoring-basics.md#custom-attributes) host object, you'll make sure to pass the [custom attribute](03-monitoring-basics.md#custom-attributes)
storage required by the for loop in the service apply rule. storage required by the for loop in the service apply rule.
object Host "cisco-catalyst-6509-34" { object Host "cisco-catalyst-6509-34" {
@ -840,7 +840,7 @@ The other way around you can override specific custom attributes inherited from
This example makes use of the [check_iftraffic](https://exchange.icinga.com/exchange/iftraffic) plugin. This example makes use of the [check_iftraffic](https://exchange.icinga.com/exchange/iftraffic) plugin.
The `CheckCommand` definition can be found in the The `CheckCommand` definition can be found in the
[contributed plugin check commands](10-icinga-template-library.md#plugin-contrib-command-iftraffic) [contributed plugin check commands](10-icinga-template-library.md#plugin-contrib-command-iftraffic)
-- make sure to include them in your [icinga2 configuration file](4-configuring-icinga-2.md#icinga2-conf). -- make sure to include them in your [icinga2 configuration file](04-configuring-icinga-2.md#icinga2-conf).
> **Tip** > **Tip**
@ -904,7 +904,7 @@ inherited custom attributes:
* vlan = "mgmt" * vlan = "mgmt"
### <a id="using-apply-object-attributes"></a> Use Object Attributes in Apply Rules ### Use Object Attributes in Apply Rules <a id="using-apply-object-attributes"></a>
Since apply rules are evaluated after the generic objects, you Since apply rules are evaluated after the generic objects, you
can reference existing host and/or service object attributes as can reference existing host and/or service object attributes as
@ -946,7 +946,7 @@ values for any object attribute specified in that apply rule.
action_url = "http://snmp.checker.company.com/" + host.name + "/" + vars.customer_id action_url = "http://snmp.checker.company.com/" + host.name + "/" + vars.customer_id
} }
## <a id="groups"></a> Groups ## Groups <a id="groups"></a>
A group is a collection of similar objects. Groups are primarily used as a A group is a collection of similar objects. Groups are primarily used as a
visualization aid in web interfaces. visualization aid in web interfaces.
@ -1000,7 +1000,7 @@ This can be done for service and user groups the same way:
email = "ops@example.com" email = "ops@example.com"
} }
### <a id="group-assign-intro"></a> Group Membership Assign ### Group Membership Assign <a id="group-assign-intro"></a>
Instead of manually assigning each object to a group you can also assign objects Instead of manually assigning each object to a group you can also assign objects
to a group based on their attributes: to a group based on their attributes:
@ -1021,7 +1021,7 @@ or with the `test_server` attribute set to `true` are **not** added to this grou
Details on the `assign where` syntax can be found in the Details on the `assign where` syntax can be found in the
[Language Reference](17-language-reference.md#apply). [Language Reference](17-language-reference.md#apply).
## <a id="alert-notifications"></a> Notifications ## Notifications <a id="alert-notifications"></a>
Notifications for service and host problems are an integral part of your Notifications for service and host problems are an integral part of your
monitoring setup. monitoring setup.
@ -1064,7 +1064,7 @@ You should choose which information you (and your notified users) are interested
case of emergency, and also which information does not provide any value to you and case of emergency, and also which information does not provide any value to you and
your environment. your environment.
An example notification command is explained [here](3-monitoring-basics.md#notification-commands). An example notification command is explained [here](03-monitoring-basics.md#notification-commands).
You can add all shared attributes to a `Notification` template which is inherited You can add all shared attributes to a `Notification` template which is inherited
to the defined notifications. That way you'll save duplicated attributes in each to the defined notifications. That way you'll save duplicated attributes in each
@ -1103,7 +1103,7 @@ send notifications to all group members.
**Note**: Only users who have been notified of a problem before (`Warning`, `Critical`, `Unknown` **Note**: Only users who have been notified of a problem before (`Warning`, `Critical`, `Unknown`
states for services, `Down` for hosts) will receive `Recovery` notifications. states for services, `Down` for hosts) will receive `Recovery` notifications.
### <a id="notification-escalations"></a> Notification Escalations ### Notification Escalations <a id="notification-escalations"></a>
When a problem notification is sent and a problem still exists at the time of re-notification When a problem notification is sent and a problem still exists at the time of re-notification
you may want to escalate the problem to the next support level. A different approach you may want to escalate the problem to the next support level. A different approach
@ -1130,7 +1130,7 @@ notifications between start and end time.
vars.mobile = "+1 555 424642" vars.mobile = "+1 555 424642"
} }
Define an additional [NotificationCommand](3-monitoring-basics.md#notification-commands) for SMS notifications. Define an additional [NotificationCommand](03-monitoring-basics.md#notification-commands) for SMS notifications.
> **Note** > **Note**
> >
@ -1198,7 +1198,7 @@ notified, but only for one hour (`2h` as `end` key for the `times` dictionary).
assign where service.name == "ping4" assign where service.name == "ping4"
} }
### <a id="notification-delay"></a> Notification Delay ### Notification Delay <a id="notification-delay"></a>
Sometimes the problem in question should not be announced when the notification is due Sometimes the problem in question should not be announced when the notification is due
(the object reaching the `HARD` state), but after a certain period. In Icinga 2 (the object reaching the `HARD` state), but after a certain period. In Icinga 2
@ -1220,7 +1220,7 @@ specify a relatively low notification `interval` to get notified soon enough aga
assign where service.name == "ping4" assign where service.name == "ping4"
} }
### <a id="disable-renotification"></a> Disable Re-notifications ### Disable Re-notifications <a id="disable-renotification"></a>
If you prefer to be notified only once, you can disable re-notifications by setting the If you prefer to be notified only once, you can disable re-notifications by setting the
`interval` attribute to `0`. `interval` attribute to `0`.
@ -1236,7 +1236,7 @@ If you prefer to be notified only once, you can disable re-notifications by sett
assign where service.name == "ping4" assign where service.name == "ping4"
} }
### <a id="notification-filters-state-type"></a> Notification Filters by State and Type ### Notification Filters by State and Type <a id="notification-filters-state-type"></a>
If there are no notification state and type filter attributes defined at the `Notification` If there are no notification state and type filter attributes defined at the `Notification`
or `User` object, Icinga 2 assumes that all states and types are being notified. or `User` object, Icinga 2 assumes that all states and types are being notified.
@ -1255,19 +1255,19 @@ into type and state to allow more fine granular filtering for example on downtim
You can filter for acknowledgements and custom notifications too. You can filter for acknowledgements and custom notifications too.
## <a id="commands"></a> Commands ## Commands <a id="commands"></a>
Icinga 2 uses three different command object types to specify how Icinga 2 uses three different command object types to specify how
checks should be performed, notifications should be sent, and checks should be performed, notifications should be sent, and
events should be handled. events should be handled.
### <a id="check-commands"></a> Check Commands ### Check Commands <a id="check-commands"></a>
[CheckCommand](9-object-types.md#objecttype-checkcommand) objects define the command line how [CheckCommand](09-object-types.md#objecttype-checkcommand) objects define the command line how
a check is called. a check is called.
[CheckCommand](9-object-types.md#objecttype-checkcommand) objects are referenced by [CheckCommand](09-object-types.md#objecttype-checkcommand) objects are referenced by
[Host](9-object-types.md#objecttype-host) and [Service](9-object-types.md#objecttype-service) objects [Host](09-object-types.md#objecttype-host) and [Service](09-object-types.md#objecttype-service) objects
using the `check_command` attribute. using the `check_command` attribute.
> **Note** > **Note**
@ -1275,10 +1275,10 @@ using the `check_command` attribute.
> Make sure that the [checker](11-cli-commands.md#enable-features) feature is enabled in order to > Make sure that the [checker](11-cli-commands.md#enable-features) feature is enabled in order to
> execute checks. > execute checks.
#### <a id="command-plugin-integration"></a> Integrate the Plugin with a CheckCommand Definition #### Integrate the Plugin with a CheckCommand Definition <a id="command-plugin-integration"></a>
Unless you have done so already, download your check plugin and put it Unless you have done so already, download your check plugin and put it
into the [PluginDir](4-configuring-icinga-2.md#constants-conf) directory. The following example uses the into the [PluginDir](04-configuring-icinga-2.md#constants-conf) directory. The following example uses the
`check_mysql` plugin contained in the Monitoring Plugins package. `check_mysql` plugin contained in the Monitoring Plugins package.
The plugin path and all command arguments are made a list of The plugin path and all command arguments are made a list of
@ -1298,13 +1298,13 @@ partition defined (`-p`) it will check all local partitions.
[-u user] [-p password] [-S] [-l] [-a cert] [-k key] [-u user] [-p password] [-S] [-l] [-a cert] [-k key]
[-C ca-cert] [-D ca-dir] [-L ciphers] [-f optfile] [-g group] [-C ca-cert] [-D ca-dir] [-L ciphers] [-f optfile] [-g group]
Next step is to understand how [command parameters](3-monitoring-basics.md#command-passing-parameters) Next step is to understand how [command parameters](03-monitoring-basics.md#command-passing-parameters)
are being passed from a host or service object, and add a [CheckCommand](9-object-types.md#objecttype-checkcommand) are being passed from a host or service object, and add a [CheckCommand](09-object-types.md#objecttype-checkcommand)
definition based on these required parameters and/or default values. definition based on these required parameters and/or default values.
Please continue reading in the [plugins section](5-service-monitoring.md#service-monitoring-plugins) for additional integration examples. Please continue reading in the [plugins section](05-service-monitoring.md#service-monitoring-plugins) for additional integration examples.
#### <a id="command-passing-parameters"></a> Passing Check Command Parameters from Host or Service #### Passing Check Command Parameters from Host or Service <a id="command-passing-parameters"></a>
Check command parameters are defined as custom attributes which can be accessed as runtime macros Check command parameters are defined as custom attributes which can be accessed as runtime macros
by the executed check command. by the executed check command.
@ -1313,13 +1313,13 @@ The check command parameters for ITL provided plugin check command definitions a
[here](10-icinga-template-library.md#plugin-check-commands), for example [here](10-icinga-template-library.md#plugin-check-commands), for example
[disk](10-icinga-template-library.md#plugin-check-command-disk). [disk](10-icinga-template-library.md#plugin-check-command-disk).
In order to practice passing command parameters you should [integrate your own plugin](3-monitoring-basics.md#command-plugin-integration). 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](2-getting-started.md#setting-up-check-plugins). The following example will use `check_mysql` provided by the [Monitoring Plugins installation](02-getting-started.md#setting-up-check-plugins).
Define the default check command custom attributes, for example `mysql_user` and `mysql_password` Define the default check command custom attributes, for example `mysql_user` and `mysql_password`
(freely definable naming schema) and optional their default threshold values. You can (freely definable naming schema) and optional their default threshold values. You can
then use these custom attributes as runtime macros for [command arguments](3-monitoring-basics.md#command-arguments) then use these custom attributes as runtime macros for [command arguments](03-monitoring-basics.md#command-arguments)
on the command line. on the command line.
> **Tip** > **Tip**
@ -1373,7 +1373,7 @@ The check command definition also sets `mysql_host` to the `$address$` default v
this command parameter if for example your MySQL host is not running on the same server's ip address. this command parameter if for example your MySQL host is not running on the same server's ip address.
Make sure pass all required command parameters, such as `mysql_user`, `mysql_password` and `mysql_database`. Make sure pass all required command parameters, such as `mysql_user`, `mysql_password` and `mysql_database`.
`MysqlUsername` and `MysqlPassword` are specified as [global constants](4-configuring-icinga-2.md#constants-conf) `MysqlUsername` and `MysqlPassword` are specified as [global constants](04-configuring-icinga-2.md#constants-conf)
in this example. in this example.
# vim /etc/icinga2/conf.d/services.conf # vim /etc/icinga2/conf.d/services.conf
@ -1394,10 +1394,10 @@ in this example.
} }
Take a different example: The example host configuration in [hosts.conf](4-configuring-icinga-2.md#hosts-conf) Take a different example: The example host configuration in [hosts.conf](04-configuring-icinga-2.md#hosts-conf)
also applies an `ssh` service check. Your host's ssh port is not the default `22`, but set to `2022`. also applies an `ssh` service check. Your host's ssh port is not the default `22`, but set to `2022`.
You can pass the command parameter as custom attribute `ssh_port` directly inside the service apply rule You can pass the command parameter as custom attribute `ssh_port` directly inside the service apply rule
inside [services.conf](4-configuring-icinga-2.md#services-conf): inside [services.conf](04-configuring-icinga-2.md#services-conf):
apply Service "ssh" { apply Service "ssh" {
import "generic-service" import "generic-service"
@ -1409,17 +1409,17 @@ inside [services.conf](4-configuring-icinga-2.md#services-conf):
} }
If you prefer this being configured at the host instead of the service, modify the host configuration If you prefer this being configured at the host instead of the service, modify the host configuration
object instead. The runtime macro resolving order is described [here](3-monitoring-basics.md#macro-evaluation-order). object instead. The runtime macro resolving order is described [here](03-monitoring-basics.md#macro-evaluation-order).
object Host NodeName { object Host NodeName {
... ...
vars.ssh_port = 2022 vars.ssh_port = 2022
} }
#### <a id="command-passing-parameters-apply-for"></a> Passing Check Command Parameters Using Apply For #### Passing Check Command Parameters Using Apply For <a id="command-passing-parameters-apply-for"></a>
The host `localhost` with the generated services from the `basic-partitions` dictionary (see The host `localhost` with the generated services from the `basic-partitions` dictionary (see
[apply for](3-monitoring-basics.md#using-apply-for) for details) checks a basic set of disk partitions [apply for](03-monitoring-basics.md#using-apply-for) for details) checks a basic set of disk partitions
with modified custom attributes (warning thresholds at `10%`, critical thresholds at `5%` with modified custom attributes (warning thresholds at `10%`, critical thresholds at `5%`
free disk space). free disk space).
@ -1448,10 +1448,10 @@ string values for passing multiple partitions to the `check_disk` check plugin.
More details on using arrays in custom attributes can be found in More details on using arrays in custom attributes can be found in
[this chapter](3-monitoring-basics.md#custom-attributes). [this chapter](03-monitoring-basics.md#custom-attributes).
#### <a id="command-arguments"></a> Command Arguments #### Command Arguments <a id="command-arguments"></a>
By defining a check command line using the `command` attribute Icinga 2 By defining a check command line using the `command` attribute Icinga 2
will resolve all macros in the static string or array. Sometimes it is will resolve all macros in the static string or array. Sometimes it is
@ -1509,10 +1509,10 @@ That way you can use the `check_http` command definition for both, with and
without SSL enabled checks saving you duplicated command definitions. without SSL enabled checks saving you duplicated command definitions.
Details on all available options can be found in the Details on all available options can be found in the
[CheckCommand object definition](9-object-types.md#objecttype-checkcommand). [CheckCommand object definition](09-object-types.md#objecttype-checkcommand).
#### <a id="command-environment-variables"></a> Environment Variables #### Environment Variables <a id="command-environment-variables"></a>
The `env` command object attribute specifies a list of environment variables with values calculated The `env` command object attribute specifies a list of environment variables with values calculated
from either runtime macros or custom attributes which should be exported as environment variables from either runtime macros or custom attributes which should be exported as environment variables
@ -1542,13 +1542,13 @@ when passing credentials to database checks:
### <a id="notification-commands"></a> Notification Commands ### Notification Commands <a id="notification-commands"></a>
[NotificationCommand](9-object-types.md#objecttype-notificationcommand) [NotificationCommand](09-object-types.md#objecttype-notificationcommand)
objects define how notifications are delivered to external interfaces objects define how notifications are delivered to external interfaces
(email, XMPP, IRC, Twitter, etc.). (email, XMPP, IRC, Twitter, etc.).
[NotificationCommand](9-object-types.md#objecttype-notificationcommand) [NotificationCommand](09-object-types.md#objecttype-notificationcommand)
objects are referenced by [Notification](9-object-types.md#objecttype-notification) objects are referenced by [Notification](09-object-types.md#objecttype-notification)
objects using the `command` attribute. objects using the `command` attribute.
> **Note** > **Note**
@ -1581,13 +1581,13 @@ defaults can always be overwritten locally.
> This example requires the `mail` binary installed on the Icinga 2 > This example requires the `mail` binary installed on the Icinga 2
> master. > master.
#### <a id="mail-host-notification"></a> mail-host-notification #### mail-host-notification <a id="mail-host-notification"></a>
The `mail-host-notification` NotificationCommand object uses the The `mail-host-notification` NotificationCommand object uses the
example notification script located in `/etc/icinga2/scripts/mail-host-notification.sh`. example notification script located in `/etc/icinga2/scripts/mail-host-notification.sh`.
Here is a quick overview of the arguments that can be used. See also [host runtime Here is a quick overview of the arguments that can be used. See also [host runtime
macros](3-monitoring-basics.md#-host-runtime-macros) for further macros](03-monitoring-basics.md#-host-runtime-macros) for further
information. information.
Name | Description Name | Description
@ -1607,13 +1607,13 @@ information.
`notification_icingaweb2url` | **Optional.** Define URL to your Icinga Web 2 (e.g. `"https://www.example.com/icingaweb2"`) `notification_icingaweb2url` | **Optional.** Define URL to your Icinga Web 2 (e.g. `"https://www.example.com/icingaweb2"`)
`notification_logtosyslog` | **Optional.** Set `true` to log notification events to syslog; useful for debugging. Defaults to `false`. `notification_logtosyslog` | **Optional.** Set `true` to log notification events to syslog; useful for debugging. Defaults to `false`.
#### <a id="mail-service-notification"></a> mail-service-notification #### mail-service-notification <a id="mail-service-notification"></a>
The `mail-service-notification` NotificationCommand object uses the The `mail-service-notification` NotificationCommand object uses the
example notification script located in `/etc/icinga2/scripts/mail-service-notification.sh`. example notification script located in `/etc/icinga2/scripts/mail-service-notification.sh`.
Here is a quick overview of the arguments that can be used. See also [service runtime Here is a quick overview of the arguments that can be used. See also [service runtime
macros](3-monitoring-basics.md#-service-runtime-macros) for further macros](03-monitoring-basics.md#-service-runtime-macros) for further
information. information.
Name | Description Name | Description
@ -1635,17 +1635,17 @@ information.
`notification_icingaweb2url` | **Optional.** Define URL to your Icinga Web 2 (e.g. `"https://www.example.com/icingaweb2"`) `notification_icingaweb2url` | **Optional.** Define URL to your Icinga Web 2 (e.g. `"https://www.example.com/icingaweb2"`)
`notification_logtosyslog` | **Optional.** Set `true` to log notification events to syslog; useful for debugging. Defaults to `false`. `notification_logtosyslog` | **Optional.** Set `true` to log notification events to syslog; useful for debugging. Defaults to `false`.
### <a id="event-commands"></a> Event Commands ### Event Commands <a id="event-commands"></a>
Unlike notifications, event commands for hosts/services are called on every Unlike notifications, event commands for hosts/services are called on every
check execution if one of these conditions matches: check execution if one of these conditions matches:
* The host/service is in a [soft state](3-monitoring-basics.md#hard-soft-states) * The host/service is in a [soft state](03-monitoring-basics.md#hard-soft-states)
* The host/service state changes into a [hard state](3-monitoring-basics.md#hard-soft-states) * The host/service state changes into a [hard state](03-monitoring-basics.md#hard-soft-states)
* The host/service state recovers from a [soft or hard state](3-monitoring-basics.md#hard-soft-states) to [OK](3-monitoring-basics.md#service-states)/[Up](3-monitoring-basics.md#host-states) * The host/service state recovers from a [soft or hard state](03-monitoring-basics.md#hard-soft-states) to [OK](03-monitoring-basics.md#service-states)/[Up](03-monitoring-basics.md#host-states)
[EventCommand](9-object-types.md#objecttype-eventcommand) objects are referenced by [EventCommand](09-object-types.md#objecttype-eventcommand) objects are referenced by
[Host](9-object-types.md#objecttype-host) and [Service](9-object-types.md#objecttype-service) objects [Host](09-object-types.md#objecttype-host) and [Service](09-object-types.md#objecttype-service) objects
with the `event_command` attribute. with the `event_command` attribute.
Therefore the `EventCommand` object should define a command line Therefore the `EventCommand` object should define a command line
@ -1654,7 +1654,7 @@ available through runtime variables. Runtime macros such as `$service.state_type
and `$service.state$` will be processed by Icinga 2 and help with fine-granular and `$service.state$` will be processed by Icinga 2 and help with fine-granular
triggered events triggered events
If the host/service is located on a client as [command endpoint](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint) If the host/service is located on a client as [command endpoint](06-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint)
the event command will be executed on the client itself (similar to the check the event command will be executed on the client itself (similar to the check
command). command).
@ -1664,12 +1664,12 @@ responding and therefore requires a restart. You can also use event handlers
to forward more details on state changes and events than the typical notification to forward more details on state changes and events than the typical notification
alerts provide. alerts provide.
#### <a id="event-command-send-information-from-master"></a> Use Event Commands to Send Information from the Master #### Use Event Commands to Send Information from the Master <a id="event-command-send-information-from-master"></a>
This example sends a web request from the master node to an external tool This example sends a web request from the master node to an external tool
for every event triggered on a `businessprocess` service. for every event triggered on a `businessprocess` service.
Define an [EventCommand](9-object-types.md#objecttype-eventcommand) Define an [EventCommand](09-object-types.md#objecttype-eventcommand)
object `send_to_businesstool` which sends state changes to the external tool. object `send_to_businesstool` which sends state changes to the external tool.
object EventCommand "send_to_businesstool" { object EventCommand "send_to_businesstool" {
@ -1728,7 +1728,7 @@ Expected Result:
businessprocess businessprocess CRITICAL SOFT 1 businessprocess businessprocess CRITICAL SOFT 1
#### <a id="event-command-restart-service-daemon-command-endpoint-linux"></a> Use Event Commands to Restart Service Daemon via Command Endpoint on Linux #### Use Event Commands to Restart Service Daemon via Command Endpoint on Linux <a id="event-command-restart-service-daemon-command-endpoint-linux"></a>
This example triggers a restart of the `httpd` service on the local system This example triggers a restart of the `httpd` service on the local system
when the `procs` service check executed via Command Endpoint fails. It only when the `procs` service check executed via Command Endpoint fails. It only
@ -1747,8 +1747,8 @@ Example on CentOS 7:
Note: Distributions might use a different name. On Debian/Ubuntu the service is called `apache2`. Note: Distributions might use a different name. On Debian/Ubuntu the service is called `apache2`.
Define an [EventCommand](9-object-types.md#objecttype-eventcommand) object `restart_service` Define an [EventCommand](09-object-types.md#objecttype-eventcommand) object `restart_service`
which allows to trigger local service restarts. Put it into a [global zone](6-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync) which allows to trigger local service restarts. Put it into a [global zone](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync)
to sync its configuration to all clients. to sync its configuration to all clients.
[root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/global-templates/eventcommands.conf [root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/global-templates/eventcommands.conf
@ -1833,7 +1833,7 @@ executed command line.
[root@icinga2-client1.localdomain /]# tail -f /var/log/icinga2/debug.log | grep restart_service [root@icinga2-client1.localdomain /]# tail -f /var/log/icinga2/debug.log | grep restart_service
#### <a id="event-command-restart-service-daemon-command-endpoint-windows"></a> Use Event Commands to Restart Service Daemon via Command Endpoint on Windows #### Use Event Commands to Restart Service Daemon via Command Endpoint on Windows <a id="event-command-restart-service-daemon-command-endpoint-windows"></a>
This example triggers a restart of the `httpd` service on the remote system This example triggers a restart of the `httpd` service on the remote system
when the `service-windows` service check executed via Command Endpoint fails. when the `service-windows` service check executed via Command Endpoint fails.
@ -1845,8 +1845,8 @@ Requirements:
* Icinga 2 as client on the remote node * Icinga 2 as client on the remote node
* Icinga 2 service with permissions to execute Powershell scripts (which is the default) * Icinga 2 service with permissions to execute Powershell scripts (which is the default)
Define an [EventCommand](9-object-types.md#objecttype-eventcommand) object `restart_service-windows` Define an [EventCommand](09-object-types.md#objecttype-eventcommand) object `restart_service-windows`
which allows to trigger local service restarts. Put it into a [global zone](6-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync) which allows to trigger local service restarts. Put it into a [global zone](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync)
to sync its configuration to all clients. to sync its configuration to all clients.
[root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/global-templates/eventcommands.conf [root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/global-templates/eventcommands.conf
@ -1922,7 +1922,7 @@ You can enable the [debug log](15-troubleshooting.md#troubleshooting-enable-debu
executed command line in `C:\ProgramData\icinga2\var\log\icinga2\debug.log`. executed command line in `C:\ProgramData\icinga2\var\log\icinga2\debug.log`.
#### <a id="event-command-restart-service-daemon-ssh"></a> Use Event Commands to Restart Service Daemon via SSH #### Use Event Commands to Restart Service Daemon via SSH <a id="event-command-restart-service-daemon-ssh"></a>
This example triggers a restart of the `httpd` daemon This example triggers a restart of the `httpd` daemon
via SSH when the `http` service check fails. via SSH when the `http` service check fails.
@ -1941,7 +1941,7 @@ Example on Debian:
# visudo # visudo
icinga ALL=(ALL) NOPASSWD: /etc/init.d/apache2 restart icinga ALL=(ALL) NOPASSWD: /etc/init.d/apache2 restart
Define a generic [EventCommand](9-object-types.md#objecttype-eventcommand) object `event_by_ssh` Define a generic [EventCommand](09-object-types.md#objecttype-eventcommand) object `event_by_ssh`
which can be used for all event commands triggered using SSH: which can be used for all event commands triggered using SSH:
[root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/master/local_eventcommands.conf [root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/master/local_eventcommands.conf
@ -2017,9 +2017,9 @@ executed command line.
[root@icinga2-client1.localdomain /]# tail -f /var/log/icinga2/debug.log | grep by_ssh [root@icinga2-client1.localdomain /]# tail -f /var/log/icinga2/debug.log | grep by_ssh
## <a id="dependencies"></a> Dependencies ## Dependencies <a id="dependencies"></a>
Icinga 2 uses host and service [Dependency](9-object-types.md#objecttype-dependency) objects Icinga 2 uses host and service [Dependency](09-object-types.md#objecttype-dependency) objects
for determining their network reachability. for determining their network reachability.
A service can depend on a host, and vice versa. A service has an implicit A service can depend on a host, and vice versa. A service has an implicit
@ -2030,8 +2030,8 @@ account but all parents are inherited.
The `parent_host_name` and `parent_service_name` attributes are mandatory for The `parent_host_name` and `parent_service_name` attributes are mandatory for
service dependencies, `parent_host_name` is required for host dependencies. service dependencies, `parent_host_name` is required for host dependencies.
[Apply rules](3-monitoring-basics.md#using-apply) will allow you to [Apply rules](03-monitoring-basics.md#using-apply) will allow you to
[determine these attributes](3-monitoring-basics.md#dependencies-apply-custom-attributes) in a more [determine these attributes](03-monitoring-basics.md#dependencies-apply-custom-attributes) in a more
dynamic fashion if required. dynamic fashion if required.
parent_host_name = "core-router" parent_host_name = "core-router"
@ -2059,7 +2059,7 @@ dependency will fail and render all child objects (hosts or services) unreachabl
You can determine the child's reachability by querying the `is_reachable` attribute You can determine the child's reachability by querying the `is_reachable` attribute
in for example [DB IDO](23-appendix.md#schema-db-ido-extensions). in for example [DB IDO](23-appendix.md#schema-db-ido-extensions).
### <a id="dependencies-implicit-host-service"></a> Implicit Dependencies for Services on Host ### Implicit Dependencies for Services on Host <a id="dependencies-implicit-host-service"></a>
Icinga 2 automatically adds an implicit dependency for services on their host. That way Icinga 2 automatically adds an implicit dependency for services on their host. That way
service notifications are suppressed when a host is `DOWN` or `UNREACHABLE`. This dependency service notifications are suppressed when a host is `DOWN` or `UNREACHABLE`. This dependency
@ -2075,7 +2075,7 @@ and disabling the checks. `assign where true` matches on all `Service` objects.
assign where true assign where true
} }
### <a id="dependencies-network-reachability"></a> Dependencies for Network Reachability ### Dependencies for Network Reachability <a id="dependencies-network-reachability"></a>
A common scenario is the Icinga 2 server behind a router. Checking internet A common scenario is the Icinga 2 server behind a router. Checking internet
access by pinging the Google DNS server `google-dns` is a common method, but access by pinging the Google DNS server `google-dns` is a common method, but
@ -2121,9 +2121,9 @@ be suppressed. This is achieved by setting the `disable_checks` attribute to `tr
assign where host.name != "dsl-router" assign where host.name != "dsl-router"
} }
### <a id="dependencies-apply-custom-attributes"></a> Apply Dependencies based on Custom Attributes ### Apply Dependencies based on Custom Attributes <a id="dependencies-apply-custom-attributes"></a>
You can use [apply rules](3-monitoring-basics.md#using-apply) to set parent or You can use [apply rules](03-monitoring-basics.md#using-apply) to set parent or
child attributes, e.g. `parent_host_name` to other objects' child attributes, e.g. `parent_host_name` to other objects'
attributes. attributes.
@ -2192,7 +2192,7 @@ will detect their reachability immediately when executing checks.
> apply rules, but not in object definitions. > apply rules, but not in object definitions.
### <a id="dependencies-agent-checks"></a> Dependencies for Agent Checks ### Dependencies for Agent Checks <a id="dependencies-agent-checks"></a>
Another classic example are agent based checks. You would define a health check Another classic example are agent based checks. You would define a health check
for the agent daemon responding to your requests, and make all other services for the agent daemon responding to your requests, and make all other services

180
doc/4-configuring-icinga-2.md → doc/04-configuring-icinga-2.md
View File

@ -1,4 +1,4 @@
# <a id="configuring-icinga2-first-steps"></a> Configuring Icinga 2: First Steps # Configuring Icinga 2: First Steps <a id="configuring-icinga2-first-steps"></a>
This chapter provides an introduction into best practices with your Icinga 2 configuration. This chapter provides an introduction into best practices with your Icinga 2 configuration.
The configuration files which are automatically created when installing the Icinga 2 packages The configuration files which are automatically created when installing the Icinga 2 packages
@ -7,7 +7,7 @@ are a good way to start with Icinga 2.
The [Language Reference](17-language-reference.md#language-reference) chapter explains details The [Language Reference](17-language-reference.md#language-reference) chapter explains details
on value types (string, number, dictionaries, etc.) and the general configuration syntax. on value types (string, number, dictionaries, etc.) and the general configuration syntax.
## <a id="configuration-best-practice"></a> Configuration Best Practice ## Configuration Best Practice <a id="configuration-best-practice"></a>
If you are ready to configure additional hosts, services, notifications, If you are ready to configure additional hosts, services, notifications,
dependencies, etc., you should think about the requirements first and then dependencies, etc., you should think about the requirements first and then
@ -27,7 +27,7 @@ Find the best strategy for your own configuration and ask yourself the following
* Only a small set of users receives notifications and escalations for all hosts/services? * Only a small set of users receives notifications and escalations for all hosts/services?
If you can at least answer one of these questions with yes, look for the If you can at least answer one of these questions with yes, look for the
[apply rules](3-monitoring-basics.md#using-apply) logic instead of defining objects on a per [apply rules](03-monitoring-basics.md#using-apply) logic instead of defining objects on a per
host and service basis. host and service basis.
* You are required to define specific configuration for each host/service? * You are required to define specific configuration for each host/service?
@ -36,7 +36,7 @@ host and service basis.
Then you should look for the object specific configuration setting `host_name` etc. accordingly. Then you should look for the object specific configuration setting `host_name` etc. accordingly.
You decide on the "best" layout for configuration files and directories. Ensure that You decide on the "best" layout for configuration files and directories. Ensure that
the [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) configuration file includes them. the [icinga2.conf](04-configuring-icinga-2.md#icinga2-conf) configuration file includes them.
Consider these ideas: Consider these ideas:
@ -52,24 +52,24 @@ In either way of choosing the right strategy you should additionally check the f
You can later use them for applying assign/ignore rules, or export them into external interfaces. You can later use them for applying assign/ignore rules, or export them into external interfaces.
* Put hosts into hostgroups, services into servicegroups and use these attributes for your apply rules. * Put hosts into hostgroups, services into servicegroups and use these attributes for your apply rules.
* Use templates to store generic attributes for your objects and apply rules making your configuration more readable. * Use templates to store generic attributes for your objects and apply rules making your configuration more readable.
Details can be found in the [using templates](3-monitoring-basics.md#object-inheritance-using-templates) chapter. Details can be found in the [using templates](03-monitoring-basics.md#object-inheritance-using-templates) chapter.
* Apply rules may overlap. Keep a central place (for example, [services.conf](4-configuring-icinga-2.md#services-conf) or [notifications.conf](4-configuring-icinga-2.md#notifications-conf)) storing * Apply rules may overlap. Keep a central place (for example, [services.conf](04-configuring-icinga-2.md#services-conf) or [notifications.conf](04-configuring-icinga-2.md#notifications-conf)) storing
the configuration instead of defining apply rules deep in your configuration tree. the configuration instead of defining apply rules deep in your configuration tree.
* Every plugin used as check, notification or event command requires a `Command` definition. * Every plugin used as check, notification or event command requires a `Command` definition.
Further details can be looked up in the [check commands](3-monitoring-basics.md#check-commands) chapter. Further details can be looked up in the [check commands](03-monitoring-basics.md#check-commands) chapter.
If you are planning to use a distributed monitoring setup with master, satellite and client installations If you are planning to use a distributed monitoring setup with master, satellite and client installations
take the configuration location into account too. Everything configured on the master, synced to all other take the configuration location into account too. Everything configured on the master, synced to all other
nodes? Or any specific local configuration (e.g. health checks)? nodes? Or any specific local configuration (e.g. health checks)?
There is a detailed chapter on [distributed monitoring scenarios](6-distributed-monitoring.md#distributed-monitoring-scenarios). There is a detailed chapter on [distributed monitoring scenarios](06-distributed-monitoring.md#distributed-monitoring-scenarios).
Please ensure to have read the [introduction](6-distributed-monitoring.md#distributed-monitoring) at first glance. Please ensure to have read the [introduction](06-distributed-monitoring.md#distributed-monitoring) at first glance.
If you happen to have further questions, do not hesitate to join the If you happen to have further questions, do not hesitate to join the
[community support channels](https://www.icinga.com/community/get-involved/) [community support channels](https://www.icinga.com/community/get-involved/)
and ask community members for their experience and best practices. and ask community members for their experience and best practices.
## <a id="your-configuration"></a> Your Configuration ## Your Configuration <a id="your-configuration"></a>
If you prefer to organize your own local object tree, you can also remove If you prefer to organize your own local object tree, you can also remove
`include_recursive "conf.d"` from your icinga2.conf file. `include_recursive "conf.d"` from your icinga2.conf file.
@ -86,12 +86,12 @@ in your icinga2.conf file.
This approach is used by the [Icinga 2 Puppet module](https://github.com/Icinga/puppet-icinga2). This approach is used by the [Icinga 2 Puppet module](https://github.com/Icinga/puppet-icinga2).
If you plan to setup a distributed setup with HA clusters and clients, please refer to [this chapter](#6-distributed-monitoring.md#distributed-monitoring-top-down) If you plan to setup a distributed setup with HA clusters and clients, please refer to [this chapter](#06-distributed-monitoring.md#distributed-monitoring-top-down)
for examples with `zones.d` as configuration directory. for examples with `zones.d` as configuration directory.
## <a id="configuring-icinga2-overview"></a> Configuration Overview ## Configuration Overview <a id="configuring-icinga2-overview"></a>
### <a id="icinga2-conf"></a> icinga2.conf ### icinga2.conf <a id="icinga2-conf"></a>
An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`. An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`.
@ -122,7 +122,7 @@ The `include` directive can be used to include other files.
include "zones.conf" include "zones.conf"
The [Icinga Template Library](10-icinga-template-library.md#icinga-template-library) provides a set of common templates The [Icinga Template Library](10-icinga-template-library.md#icinga-template-library) provides a set of common templates
and [CheckCommand](3-monitoring-basics.md#check-commands) definitions. and [CheckCommand](03-monitoring-basics.md#check-commands) definitions.
/** /**
* The Icinga Template Library (ITL) provides a number of useful templates * The Icinga Template Library (ITL) provides a number of useful templates
@ -167,10 +167,10 @@ the features which have been enabled with `icinga2 feature enable`. See
This `include_recursive` directive is used for discovery of services on remote clients This `include_recursive` directive is used for discovery of services on remote clients
and their generated configuration described in and their generated configuration described in
[this chapter](6-distributed-monitoring.md#distributed-monitoring-bottom-up). [this chapter](06-distributed-monitoring.md#distributed-monitoring-bottom-up).
**Note**: This has been DEPRECATED in Icinga 2 v2.6 and is **not** required for **Note**: This has been DEPRECATED in Icinga 2 v2.6 and is **not** required for
satellites and clients using the [top down approach](#6-distributed-monitoring.md#distributed-monitoring-top-down). satellites and clients using the [top down approach](#06-distributed-monitoring.md#distributed-monitoring-top-down).
You can safely disable/remove it. You can safely disable/remove it.
@ -181,16 +181,16 @@ You can safely disable/remove it.
*/ */
include_recursive "conf.d" include_recursive "conf.d"
You can put your own configuration files in the [conf.d](4-configuring-icinga-2.md#conf-d) directory. This You can put your own configuration files in the [conf.d](04-configuring-icinga-2.md#conf-d) directory. This
directive makes sure that all of your own configuration files are included. directive makes sure that all of your own configuration files are included.
### <a id="constants-conf"></a> constants.conf ### constants.conf <a id="constants-conf"></a>
The `constants.conf` configuration file can be used to define global constants. The `constants.conf` configuration file can be used to define global constants.
By default, you need to make sure to set these 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](2-getting-started.md#setting-up-check-plugins) are installed. * The `PluginDir` constant must be set to the path where the [Monitoring Project plugins](02-getting-started.md#setting-up-check-plugins) are installed.
This constant is used by a number of This constant is used by a number of
[built-in check command definitions](10-icinga-template-library.md#plugin-check-commands). [built-in check command definitions](10-icinga-template-library.md#plugin-check-commands).
* The `NodeName` constant defines your local node name. Should be set to FQDN which is the default * The `NodeName` constant defines your local node name. Should be set to FQDN which is the default
@ -221,58 +221,58 @@ Example:
The `ZoneName` and `TicketSalt` constants are required for remote client The `ZoneName` and `TicketSalt` constants are required for remote client
and distributed setups only. and distributed setups only.
### <a id="zones-conf"></a> zones.conf ### zones.conf <a id="zones-conf"></a>
This file can be used to specify the required [Zone](9-object-types.md#objecttype-zone) This file can be used to specify the required [Zone](09-object-types.md#objecttype-zone)
and [Endpoint](9-object-types.md#objecttype-endpoint) configuration object for and [Endpoint](09-object-types.md#objecttype-endpoint) configuration object for
[distributed monitoring](6-distributed-monitoring.md#distributed-monitoring). [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring).
By default the `NodeName` and `ZoneName` [constants](4-configuring-icinga-2.md#constants-conf) will be used. By default the `NodeName` and `ZoneName` [constants](04-configuring-icinga-2.md#constants-conf) will be used.
It also contains several [global zones](6-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync) It also contains several [global zones](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync)
for distributed monitoring environments. for distributed monitoring environments.
Please ensure to modify this configuration with real names i.e. use the FQDN Please ensure to modify this configuration with real names i.e. use the FQDN
mentioned in [this chapter](6-distributed-monitoring.md#distributed-monitoring-conventions) mentioned in [this chapter](06-distributed-monitoring.md#distributed-monitoring-conventions)
for your `Zone` and `Endpoint` object names. for your `Zone` and `Endpoint` object names.
### <a id="conf-d"></a> The conf.d Directory ### The conf.d Directory <a id="conf-d"></a>
This directory contains **example configuration** which should help you get started This directory contains **example configuration** which should help you get started
with monitoring the local host and its services. It is included in the with monitoring the local host and its services. It is included in the
[icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) configuration file by default. [icinga2.conf](04-configuring-icinga-2.md#icinga2-conf) configuration file by default.
It can be used as reference example for your own configuration strategy. It can be used as reference example for your own configuration strategy.
Just keep in mind to include the main directories in the Just keep in mind to include the main directories in the
[icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) file. [icinga2.conf](04-configuring-icinga-2.md#icinga2-conf) file.
> **Note** > **Note**
> >
> You can remove the include directive in [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) > You can remove the include directive in [icinga2.conf](04-configuring-icinga-2.md#icinga2-conf)
> if you prefer your own way of deploying Icinga 2 configuration. > if you prefer your own way of deploying Icinga 2 configuration.
Further details on configuration best practice and how to build your Further details on configuration best practice and how to build your
own strategy is described in [this chapter](4-configuring-icinga-2.md#configuration-best-practice). own strategy is described in [this chapter](04-configuring-icinga-2.md#configuration-best-practice).
Available configuration files which are installed by default: Available configuration files which are installed by default:
* [hosts.conf](4-configuring-icinga-2.md#hosts-conf) * [hosts.conf](04-configuring-icinga-2.md#hosts-conf)
* [services.conf](4-configuring-icinga-2.md#services-conf) * [services.conf](04-configuring-icinga-2.md#services-conf)
* [users.conf](4-configuring-icinga-2.md#users-conf) * [users.conf](04-configuring-icinga-2.md#users-conf)
* [notifications.conf](4-configuring-icinga-2.md#notifications-conf) * [notifications.conf](04-configuring-icinga-2.md#notifications-conf)
* [commands.conf](4-configuring-icinga-2.md#commands-conf) * [commands.conf](04-configuring-icinga-2.md#commands-conf)
* [groups.conf](4-configuring-icinga-2.md#groups-conf) * [groups.conf](04-configuring-icinga-2.md#groups-conf)
* [templates.conf](4-configuring-icinga-2.md#templates-conf) * [templates.conf](04-configuring-icinga-2.md#templates-conf)
* [downtimes.conf](4-configuring-icinga-2.md#downtimes-conf) * [downtimes.conf](04-configuring-icinga-2.md#downtimes-conf)
* [timeperiods.conf](4-configuring-icinga-2.md#timeperiods-conf) * [timeperiods.conf](04-configuring-icinga-2.md#timeperiods-conf)
* [satellite.conf](4-configuring-icinga-2.md#satellite-conf) * [satellite.conf](04-configuring-icinga-2.md#satellite-conf)
* [api-users.conf](4-configuring-icinga-2.md#api-users-conf) * [api-users.conf](04-configuring-icinga-2.md#api-users-conf)
* [app.conf](4-configuring-icinga-2.md#app-conf) * [app.conf](04-configuring-icinga-2.md#app-conf)
#### <a id="hosts-conf"></a> hosts.conf #### hosts.conf <a id="hosts-conf"></a>
The `hosts.conf` file contains an example host based on your The `hosts.conf` file contains an example host based on your
`NodeName` setting in [constants.conf](4-configuring-icinga-2.md#constants-conf). You `NodeName` setting in [constants.conf](04-configuring-icinga-2.md#constants-conf). You
can use global constants for your object names instead of string can use global constants for your object names instead of string
values. values.
@ -285,20 +285,20 @@ for check and notification commands. Most of the [Plugin Check Commands](10-icin
in the Icinga Template Library require an `address` attribute. in the Icinga Template Library require an `address` attribute.
The custom attribute `os` is evaluated by the `linux-servers` group in The custom attribute `os` is evaluated by the `linux-servers` group in
[groups.conf](4-configuring-icinga-2.md#groups-conf) making the local host a member. [groups.conf](04-configuring-icinga-2.md#groups-conf) making the local host a member.
The example host will show you how to The example host will show you how to
* define http vhost attributes for the `http` service apply rule defined * define http vhost attributes for the `http` service apply rule defined
in [services.conf](4-configuring-icinga-2.md#services-conf). in [services.conf](04-configuring-icinga-2.md#services-conf).
* define disks (all, specific `/`) and their attributes for the `disk` * define disks (all, specific `/`) and their attributes for the `disk`
service apply rule defined in [services.conf](4-configuring-icinga-2.md#services-conf). service apply rule defined in [services.conf](04-configuring-icinga-2.md#services-conf).
* define notification types (`mail`) and set the groups attribute. This * define notification types (`mail`) and set the groups attribute. This
will be used by notification apply rules in [notifications.conf](4-configuring-icinga-2.md#notifications-conf). will be used by notification apply rules in [notifications.conf](04-configuring-icinga-2.md#notifications-conf).
If you've installed [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2), you can If you've installed [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2), you can
uncomment the http vhost attributes and reload Icinga 2. The apply uncomment the http vhost attributes and reload Icinga 2. The apply
rules in [services.conf](4-configuring-icinga-2.md#services-conf) will automatically rules in [services.conf](04-configuring-icinga-2.md#services-conf) will automatically
generate a new service checking the `/icingaweb2` URI using the `http` generate a new service checking the `/icingaweb2` URI using the `http`
check. check.
@ -355,15 +355,15 @@ check.
} }
This is only the host object definition. Now we'll need to make sure that this This is only the host object definition. Now we'll need to make sure that this
host and your additional hosts are getting [services](4-configuring-icinga-2.md#services-conf) applied. host and your additional hosts are getting [services](04-configuring-icinga-2.md#services-conf) applied.
> **Tip** > **Tip**
> >
> If you don't understand all the attributes and how to use [apply rules](17-language-reference.md#apply), > If you don't understand all the attributes and how to use [apply rules](17-language-reference.md#apply),
> don't worry -- the [monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter will explain > don't worry -- the [monitoring basics](03-monitoring-basics.md#monitoring-basics) chapter will explain
> that in detail. > that in detail.
#### <a id="services-conf"></a> services.conf #### services.conf <a id="services-conf"></a>
These service [apply rules](17-language-reference.md#apply) will show you how to monitor These service [apply rules](17-language-reference.md#apply) will show you how to monitor
the local host, but also allow you to re-use or modify them for the local host, but also allow you to re-use or modify them for
@ -409,7 +409,7 @@ attributes.
The custom attribe `backup_downtime` is defined to a specific timerange string. The custom attribe `backup_downtime` is defined to a specific timerange string.
This variable value will be used for applying a `ScheduledDowntime` object to This variable value will be used for applying a `ScheduledDowntime` object to
these services in [downtimes.conf](4-configuring-icinga-2.md#downtimes-conf). these services in [downtimes.conf](04-configuring-icinga-2.md#downtimes-conf).
In this example the `assign where` condition is a boolean expression which is In this example the `assign where` condition is a boolean expression which is
evaluated for all objects of type `Host` and a new service with name "load" evaluated for all objects of type `Host` and a new service with name "load"
@ -440,10 +440,10 @@ rules. While one `apply` rule for `ssh` will only create a service for matching
hosts, you can go one step further: Generate apply rules based on array items hosts, you can go one step further: Generate apply rules based on array items
or dictionary key-value pairs. or dictionary key-value pairs.
The idea is simple: Your host in [hosts.conf](4-configuring-icinga-2.md#hosts-conf) defines the The idea is simple: Your host in [hosts.conf](04-configuring-icinga-2.md#hosts-conf) defines the
`disks` dictionary as custom attribute in `vars`. `disks` dictionary as custom attribute in `vars`.
Remember the example from [hosts.conf](4-configuring-icinga-2.md#hosts-conf): Remember the example from [hosts.conf](04-configuring-icinga-2.md#hosts-conf):
... ...
/* Define disks and attributes for service apply rules in `services.conf`. */ /* Define disks and attributes for service apply rules in `services.conf`. */
@ -462,7 +462,7 @@ parameter `disk_partition` to the check command.
You'll recognize that the naming is important -- that's the very same name You'll recognize that the naming is important -- that's the very same name
as it is passed from a service to a check command argument. Read about services as it is passed from a service to a check command argument. Read about services
and passing check commands in [this chapter](3-monitoring-basics.md#command-passing-parameters). and passing check commands in [this chapter](03-monitoring-basics.md#command-passing-parameters).
Using `apply Service for` omits the service name, it will take the key stored in Using `apply Service for` omits the service name, it will take the key stored in
the `disk` variable in `key => config` as new service object name. the `disk` variable in `key => config` as new service object name.
@ -494,21 +494,21 @@ A similar example is used for the `http` services. That way you can make your
host the information provider for all apply rules. Define them once, and only host the information provider for all apply rules. Define them once, and only
manage your hosts. manage your hosts.
Look into [notifications.conf](4-configuring-icinga-2.md#notifications-conf) how this technique is used Look into [notifications.conf](04-configuring-icinga-2.md#notifications-conf) how this technique is used
for applying notifications to hosts and services using their type and user for applying notifications to hosts and services using their type and user
attributes. attributes.
Don't forget to install the [check plugins](2-getting-started.md#setting-up-check-plugins) required by Don't forget to install the [check plugins](02-getting-started.md#setting-up-check-plugins) required by
the hosts and services and their check commands. the hosts and services and their check commands.
Further details on the monitoring configuration can be found in the Further details on the monitoring configuration can be found in the
[monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter. [monitoring basics](03-monitoring-basics.md#monitoring-basics) chapter.
#### <a id="users-conf"></a> users.conf #### users.conf <a id="users-conf"></a>
Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is used in Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is used in
[hosts.conf](4-configuring-icinga-2.md#hosts-conf) for defining a custom host attribute later used in [hosts.conf](04-configuring-icinga-2.md#hosts-conf) for defining a custom host attribute later used in
[notifications.conf](4-configuring-icinga-2.md#notifications-conf) for notification apply rules. [notifications.conf](04-configuring-icinga-2.md#notifications-conf) for notification apply rules.
object User "icingaadmin" { object User "icingaadmin" {
import "generic-user" import "generic-user"
@ -524,7 +524,7 @@ Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is u
} }
#### <a id="notifications-conf"></a> notifications.conf #### notifications.conf <a id="notifications-conf"></a>
Notifications for check alerts are an integral part or your Notifications for check alerts are an integral part or your
Icinga 2 monitoring stack. Icinga 2 monitoring stack.
@ -533,15 +533,15 @@ The examples in this file define two notification apply rules for hosts and serv
Both `apply` rules match on the same condition: They are only applied if the Both `apply` rules match on the same condition: They are only applied if the
nested dictionary attribute `notification.mail` is set. nested dictionary attribute `notification.mail` is set.
Please note that the `to` keyword is important in [notification apply rules](3-monitoring-basics.md#using-apply-notifications) Please note that the `to` keyword is important in [notification apply rules](03-monitoring-basics.md#using-apply-notifications)
defining whether these notifications are applies to hosts or services. defining whether these notifications are applies to hosts or services.
The `import` keyword imports the specific mail templates defined in [templates.conf](4-configuring-icinga-2.md#templates-conf). The `import` keyword imports the specific mail templates defined in [templates.conf](04-configuring-icinga-2.md#templates-conf).
The `interval` attribute is not explicitly set -- it [defaults to 30 minutes](9-object-types.md#objecttype-notification). The `interval` attribute is not explicitly set -- it [defaults to 30 minutes](09-object-types.md#objecttype-notification).
By setting the `user_groups` to the value provided by the By setting the `user_groups` to the value provided by the
respective [host.vars.notification.mail](4-configuring-icinga-2.md#hosts-conf) attribute we'll respective [host.vars.notification.mail](04-configuring-icinga-2.md#hosts-conf) attribute we'll
implicitely use the `icingaadmins` UserGroup defined in [users.conf](4-configuring-icinga-2.md#users-conf). implicitely use the `icingaadmins` UserGroup defined in [users.conf](04-configuring-icinga-2.md#users-conf).
apply Notification "mail-icingaadmin" to Host { apply Notification "mail-icingaadmin" to Host {
import "mail-host-notification" import "mail-host-notification"
@ -562,24 +562,24 @@ implicitely use the `icingaadmins` UserGroup defined in [users.conf](4-configuri
} }
More details on defining notifications and their additional attributes such as More details on defining notifications and their additional attributes such as
filters can be read in [this chapter](3-monitoring-basics.md#alert-notifications). filters can be read in [this chapter](03-monitoring-basics.md#alert-notifications).
#### <a id="commands-conf"></a> commands.conf #### commands.conf <a id="commands-conf"></a>
This is the place where your own command configuration can be defined. By default This is the place where your own command configuration can be defined. By default
only the notification commands used by the notification templates defined in [templates.conf](4-configuring-icinga-2.md#templates-conf). only the notification commands used by the notification templates defined in [templates.conf](04-configuring-icinga-2.md#templates-conf).
You can freely customize these notification commands, and adapt them for your needs. You can freely customize these notification commands, and adapt them for your needs.
Read more on that topic [here](3-monitoring-basics.md#notification-commands). Read more on that topic [here](03-monitoring-basics.md#notification-commands).
#### <a id="groups-conf"></a> groups.conf #### groups.conf <a id="groups-conf"></a>
The example host defined in [hosts.conf](hosts-conf) already has the The example host defined in [hosts.conf](hosts-conf) already has the
custom attribute `os` set to `Linux` and is therefore automatically custom attribute `os` set to `Linux` and is therefore automatically
a member of the host group `linux-servers`. a member of the host group `linux-servers`.
This is done by using the [group assign](17-language-reference.md#group-assign) expressions similar This is done by using the [group assign](17-language-reference.md#group-assign) expressions similar
to previously seen [apply rules](3-monitoring-basics.md#using-apply). to previously seen [apply rules](03-monitoring-basics.md#using-apply).
object HostGroup "linux-servers" { object HostGroup "linux-servers" {
display_name = "Linux Servers" display_name = "Linux Servers"
@ -616,7 +616,7 @@ and the attribute string to match with.
} }
#### <a id="templates-conf"></a> templates.conf #### templates.conf <a id="templates-conf"></a>
Most of the example configuration objects use generic global templates by Most of the example configuration objects use generic global templates by
default: default:
@ -661,15 +661,15 @@ The `hostalive` check command is part of the
period = "24x7" period = "24x7"
} }
More details on `Notification` object attributes can be found [here](9-object-types.md#objecttype-notification). More details on `Notification` object attributes can be found [here](09-object-types.md#objecttype-notification).
#### <a id="downtimes-conf"></a> downtimes.conf #### downtimes.conf <a id="downtimes-conf"></a>
The `load` service apply rule defined in [services.conf](4-configuring-icinga-2.md#services-conf) defines The `load` service apply rule defined in [services.conf](04-configuring-icinga-2.md#services-conf) defines
the `backup_downtime` custom attribute. the `backup_downtime` custom attribute.
The [ScheduledDowntime](9-object-types.md#objecttype-scheduleddowntime) apply rule uses this attribute The [ScheduledDowntime](09-object-types.md#objecttype-scheduleddowntime) apply rule uses this attribute
to define the default value for the time ranges required for recurring downtime slots. to define the default value for the time ranges required for recurring downtime slots.
apply ScheduledDowntime "backup-downtime" to Service { apply ScheduledDowntime "backup-downtime" to Service {
@ -690,32 +690,32 @@ to define the default value for the time ranges required for recurring downtime
} }
#### <a id="timeperiods-conf"></a> timeperiods.conf #### timeperiods.conf <a id="timeperiods-conf"></a>
This file contains the default timeperiod definitions for `24x7`, `9to5` This file contains the default timeperiod definitions for `24x7`, `9to5`
and `never`. TimePeriod objects are referenced by `*period` and `never`. TimePeriod objects are referenced by `*period`
objects such as hosts, services or notifications. objects such as hosts, services or notifications.
#### <a id="satellite-conf"></a> satellite.conf #### satellite.conf <a id="satellite-conf"></a>
Includes default templates and dependencies for Includes default templates and dependencies for
[monitoring remote clients](6-distributed-monitoring.md#distributed-monitoring) [monitoring remote clients](06-distributed-monitoring.md#distributed-monitoring)
using service discovery and using service discovery and
[config generation](6-distributed-monitoring.md#distributed-monitoring-bottom-up) [config generation](06-distributed-monitoring.md#distributed-monitoring-bottom-up)
on the master. Can be ignored/removed on setups not using this feature. on the master. Can be ignored/removed on setups not using this feature.
Further details on the monitoring configuration can be found in the Further details on the monitoring configuration can be found in the
[monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter. [monitoring basics](03-monitoring-basics.md#monitoring-basics) chapter.
#### <a id="api-users-conf"></a> api-users.conf #### api-users.conf <a id="api-users-conf"></a>
Provides the default [ApiUser](9-object-types.md#objecttype-apiuser) object Provides the default [ApiUser](09-object-types.md#objecttype-apiuser) object
named "root" for the [API authentication](12-icinga2-api.md#icinga2-api-authentication). named "root" for the [API authentication](12-icinga2-api.md#icinga2-api-authentication).
#### <a id="app-conf"></a> app.conf #### app.conf <a id="app-conf"></a>
Provides the default [IcingaApplication](9-object-types.md#objecttype-icingaapplication) Provides the default [IcingaApplication](09-object-types.md#objecttype-icingaapplication)
object named "app" for additional settings such as disabling notifications object named "app" for additional settings such as disabling notifications
globally, etc. globally, etc.

64
doc/5-service-monitoring.md → doc/05-service-monitoring.md
View File

@ -1,18 +1,18 @@
# <a id="service-monitoring"></a> Service Monitoring # Service Monitoring <a id="service-monitoring"></a>
The power of Icinga 2 lies in its modularity. There are thousands of The power of Icinga 2 lies in its modularity. There are thousands of
community plugins available next to the standard plugins provided by community plugins available next to the standard plugins provided by
the [Monitoring Plugins project](https://www.monitoring-plugins.org). the [Monitoring Plugins project](https://www.monitoring-plugins.org).
## <a id="service-monitoring-requirements"></a> Requirements ## Requirements <a id="service-monitoring-requirements"></a>
### <a id="service-monitoring-plugins"></a> Plugins ### Plugins <a id="service-monitoring-plugins"></a>
All existing Nagios or Icinga 1.x plugins work with Icinga 2. Community All existing Nagios or Icinga 1.x plugins work with Icinga 2. Community
plugins can be found for example on [Icinga Exchange](https://exchange.icinga.com). plugins can be found for example on [Icinga Exchange](https://exchange.icinga.com).
The recommended way of setting up these plugins is to copy them to a common directory The recommended way of setting up these plugins is to copy them to a common directory
and create a new global constant, e.g. `CustomPluginDir` in your [constants.conf](4-configuring-icinga-2.md#constants-conf) and create a new global constant, e.g. `CustomPluginDir` in your [constants.conf](04-configuring-icinga-2.md#constants-conf)
configuration file: configuration file:
# cp check_snmp_int.pl /opt/monitoring/plugins # cp check_snmp_int.pl /opt/monitoring/plugins
@ -42,11 +42,11 @@ the plugin it might be easier to create a symbolic link to make sure it doesn't
Sometimes there are plugins which do not exactly fit your requirements. Sometimes there are plugins which do not exactly fit your requirements.
In that case you can modify an existing plugin or just write your own. In that case you can modify an existing plugin or just write your own.
### <a id="service-monitoring-plugin-checkcommand"></a> CheckCommand Definition ### CheckCommand Definition <a id="service-monitoring-plugin-checkcommand"></a>
Each plugin requires a [CheckCommand](9-object-types.md#objecttype-checkcommand) object in your Each plugin requires a [CheckCommand](09-object-types.md#objecttype-checkcommand) object in your
configuration which can be used in the [Service](9-object-types.md#objecttype-service) or configuration which can be used in the [Service](09-object-types.md#objecttype-service) or
[Host](9-object-types.md#objecttype-host) object definition. [Host](09-object-types.md#objecttype-host) object definition.
Please check if the Icinga 2 package already provides an Please check if the Icinga 2 package already provides an
[existing CheckCommand definition](10-icinga-template-library.md#plugin-check-commands). [existing CheckCommand definition](10-icinga-template-library.md#plugin-check-commands).
@ -55,12 +55,12 @@ into your host and service objects.
Please make sure to follow these conventions when adding a new command object definition: Please make sure to follow these conventions when adding a new command object definition:
* Use [command arguments](3-monitoring-basics.md#command-arguments) whenever possible. The `command` attribute * Use [command arguments](03-monitoring-basics.md#command-arguments) whenever possible. The `command` attribute
must be an array in `[ ... ]` for shell escaping. must be an array in `[ ... ]` for shell escaping.
* Define a unique `prefix` for the command's specific arguments. That way you can safely * Define a unique `prefix` for the command's specific arguments. That way you can safely
set them on host/service level and you'll always know which command they control. set them on host/service level and you'll always know which command they control.
* Use command argument default values, e.g. for thresholds. * Use command argument default values, e.g. for thresholds.
* Use [advanced conditions](9-object-types.md#objecttype-checkcommand) like `set_if` definitions. * Use [advanced conditions](09-object-types.md#objecttype-checkcommand) like `set_if` definitions.
This is an example for a custom `my-snmp-int` check command: This is an example for a custom `my-snmp-int` check command:
@ -90,16 +90,16 @@ This is an example for a custom `my-snmp-int` check command:
For further information on your monitoring configuration read the For further information on your monitoring configuration read the
[Monitoring Basics](3-monitoring-basics.md#monitoring-basics) chapter. [Monitoring Basics](03-monitoring-basics.md#monitoring-basics) chapter.
If you have created your own `CheckCommand` definition, please kindly If you have created your own `CheckCommand` definition, please kindly
[send it upstream](https://www.icinga.com/community/get-involved/). [send it upstream](https://www.icinga.com/community/get-involved/).
### <a id="service-monitoring-plugin-api"></a> Plugin API ### Plugin API <a id="service-monitoring-plugin-api"></a>
Currently Icinga 2 supports the native plugin API specification from the Monitoring Plugins project. It is defined in the [Monitoring Plugins Development Guidelines](https://www.monitoring-plugins.org/doc/guidelines.html). Currently Icinga 2 supports the native plugin API specification from the Monitoring Plugins project. It is defined in the [Monitoring Plugins Development Guidelines](https://www.monitoring-plugins.org/doc/guidelines.html).
### <a id="service-monitoring-plugin-new"></a> Create a new Plugin ### Create a new Plugin <a id="service-monitoring-plugin-new"></a>
Sometimes an existing plugin does not satisfy your requirements. You Sometimes an existing plugin does not satisfy your requirements. You
can either kindly contact the original author about plans to add changes can either kindly contact the original author about plans to add changes
@ -122,7 +122,7 @@ Common best practices when creating a new plugin are for example:
* Add parameters with key-value pairs to your plugin. They should allow long names (e.g. `--host localhost`) and also short parameters (e.g. `-H localhost`) * Add parameters with key-value pairs to your plugin. They should allow long names (e.g. `--host localhost`) and also short parameters (e.g. `-H localhost`)
* `-h|--help` should print the version and all details about parameters and runtime invocation. * `-h|--help` should print the version and all details about parameters and runtime invocation.
* Add a verbose/debug output functionality for detailed on-demand logging. * Add a verbose/debug output functionality for detailed on-demand logging.
* Respect the exit codes required by the [Plugin API](5-service-monitoring.md#service-monitoring-plugin-api). * Respect the exit codes required by the [Plugin API](05-service-monitoring.md#service-monitoring-plugin-api).
* Always add performance data to your plugin output * Always add performance data to your plugin output
Example skeleton: Example skeleton:
@ -162,13 +162,13 @@ with plugin execution and output formatting too, for example
Once you've finished your plugin please upload/sync it to [Icinga Exchange](https://exchange.icinga.com/new). Once you've finished your plugin please upload/sync it to [Icinga Exchange](https://exchange.icinga.com/new).
Thanks in advance! Thanks in advance!
## <a id="service-monitoring-overview"></a> Service Monitoring Overview ## Service Monitoring Overview <a id="service-monitoring-overview"></a>
The following examples should help you to start implementing your own ideas. The following examples should help you to start implementing your own ideas.
There is a variety of plugins available. This collection is not complete -- There is a variety of plugins available. This collection is not complete --
if you have any updates, please send a documentation patch upstream. if you have any updates, please send a documentation patch upstream.
### <a id="service-monitoring-general"></a> General Monitoring ### General Monitoring <a id="service-monitoring-general"></a>
If the remote service is available (via a network protocol and port), If the remote service is available (via a network protocol and port),
and if a check plugin is also available, you don't necessarily need a local client. and if a check plugin is also available, you don't necessarily need a local client.
@ -179,7 +179,7 @@ Instead, choose a plugin and configure its parameters and thresholds. The follow
* [tcp](10-icinga-template-library.md#plugin-check-command-tcp), [udp](10-icinga-template-library.md#plugin-check-command-udp), [ssl](10-icinga-template-library.md#plugin-check-command-ssl) * [tcp](10-icinga-template-library.md#plugin-check-command-tcp), [udp](10-icinga-template-library.md#plugin-check-command-udp), [ssl](10-icinga-template-library.md#plugin-check-command-ssl)
* [ntp_time](10-icinga-template-library.md#plugin-check-command-ntp-time) * [ntp_time](10-icinga-template-library.md#plugin-check-command-ntp-time)
### <a id="service-monitoring-linux"></a> Linux Monitoring ### Linux Monitoring <a id="service-monitoring-linux"></a>
* [disk](10-icinga-template-library.md#plugin-check-command-disk) * [disk](10-icinga-template-library.md#plugin-check-command-disk)
* [mem](10-icinga-template-library.md#plugin-contrib-command-mem), [swap](10-icinga-template-library.md#plugin-check-command-swap) * [mem](10-icinga-template-library.md#plugin-contrib-command-mem), [swap](10-icinga-template-library.md#plugin-check-command-swap)
@ -190,14 +190,14 @@ Instead, choose a plugin and configure its parameters and thresholds. The follow
* [ssh](10-icinga-template-library.md#plugin-check-command-ssh) * [ssh](10-icinga-template-library.md#plugin-check-command-ssh)
* performance: [iostat](10-icinga-template-library.md#plugin-contrib-command-iostat), [check_sar_perf](https://github.com/dnsmichi/icinga-plugins/blob/master/scripts/check_sar_perf.py) * performance: [iostat](10-icinga-template-library.md#plugin-contrib-command-iostat), [check_sar_perf](https://github.com/dnsmichi/icinga-plugins/blob/master/scripts/check_sar_perf.py)
### <a id="service-monitoring-windows"></a> Windows Monitoring ### Windows Monitoring <a id="service-monitoring-windows"></a>
* [check_wmi_plus](http://www.edcint.co.nz/checkwmiplus/) * [check_wmi_plus](http://www.edcint.co.nz/checkwmiplus/)
* [NSClient++](https://www.nsclient.org) (in combination with the Icinga 2 client and either [check_nscp_api](10-icinga-template-library.md#nscp-check-api) or [nscp-local](10-icinga-template-library.md#nscp-plugin-check-commands) check commands) * [NSClient++](https://www.nsclient.org) (in combination with the Icinga 2 client and either [check_nscp_api](10-icinga-template-library.md#nscp-check-api) or [nscp-local](10-icinga-template-library.md#nscp-plugin-check-commands) check commands)
* [Icinga 2 Windows Plugins](10-icinga-template-library.md#windows-plugins) (disk, load, memory, network, performance counters, ping, procs, service, swap, updates, uptime, users * [Icinga 2 Windows Plugins](10-icinga-template-library.md#windows-plugins) (disk, load, memory, network, performance counters, ping, procs, service, swap, updates, uptime, users
* vbs and Powershell scripts * vbs and Powershell scripts
### <a id="service-monitoring-database"></a> Database Monitoring ### Database Monitoring <a id="service-monitoring-database"></a>
* MySQL/MariaDB: [mysql_health](10-icinga-template-library.md#plugin-contrib-command-mysql_health), [mysql](10-icinga-template-library.md#plugin-check-command-mysql), [mysql_query](10-icinga-template-library.md#plugin-check-command-mysql-query) * MySQL/MariaDB: [mysql_health](10-icinga-template-library.md#plugin-contrib-command-mysql_health), [mysql](10-icinga-template-library.md#plugin-check-command-mysql), [mysql_query](10-icinga-template-library.md#plugin-check-command-mysql-query)
* PostgreSQL: [postgres](10-icinga-template-library.md#plugin-contrib-command-postgres) * PostgreSQL: [postgres](10-icinga-template-library.md#plugin-contrib-command-postgres)
@ -208,19 +208,19 @@ Instead, choose a plugin and configure its parameters and thresholds. The follow
* Elasticsearch: [elasticsearch](10-icinga-template-library.md#plugin-contrib-command-elasticsearch) * Elasticsearch: [elasticsearch](10-icinga-template-library.md#plugin-contrib-command-elasticsearch)
* Redis: [redis](10-icinga-template-library.md#plugin-contrib-command-redis) * Redis: [redis](10-icinga-template-library.md#plugin-contrib-command-redis)
### <a id="service-monitoring-snmp"></a> SNMP Monitoring ### SNMP Monitoring <a id="service-monitoring-snmp"></a>
* [Manubulon plugins](10-icinga-template-library.md#snmp-manubulon-plugin-check-commands) (interface, storage, load, memory, process) * [Manubulon plugins](10-icinga-template-library.md#snmp-manubulon-plugin-check-commands) (interface, storage, load, memory, process)
* [snmp](10-icinga-template-library.md#plugin-check-command-snmp), [snmpv3](10-icinga-template-library.md#plugin-check-command-snmpv3) * [snmp](10-icinga-template-library.md#plugin-check-command-snmp), [snmpv3](10-icinga-template-library.md#plugin-check-command-snmpv3)
### <a id="service-monitoring-network"></a> Network Monitoring ### Network Monitoring <a id="service-monitoring-network"></a>
* [nwc_health](10-icinga-template-library.md#plugin-contrib-command-nwc_health) * [nwc_health](10-icinga-template-library.md#plugin-contrib-command-nwc_health)
* [interfaces](10-icinga-template-library.md#plugin-contrib-command-interfaces) * [interfaces](10-icinga-template-library.md#plugin-contrib-command-interfaces)
* [interfacetable](10-icinga-template-library.md#plugin-contrib-command-interfacetable) * [interfacetable](10-icinga-template-library.md#plugin-contrib-command-interfacetable)
* [iftraffic](10-icinga-template-library.md#plugin-contrib-command-iftraffic), [iftraffic64](10-icinga-template-library.md#plugin-contrib-command-iftraffic64) * [iftraffic](10-icinga-template-library.md#plugin-contrib-command-iftraffic), [iftraffic64](10-icinga-template-library.md#plugin-contrib-command-iftraffic64)
### <a id="service-monitoring-web"></a> Web Monitoring ### Web Monitoring <a id="service-monitoring-web"></a>
* [http](10-icinga-template-library.md#plugin-check-command-http) * [http](10-icinga-template-library.md#plugin-check-command-http)
* [ftp](10-icinga-template-library.md#plugin-check-command-ftp) * [ftp](10-icinga-template-library.md#plugin-check-command-ftp)
@ -231,29 +231,29 @@ Instead, choose a plugin and configure its parameters and thresholds. The follow
* [kdc](10-icinga-template-library.md#plugin-contrib-command-kdc) * [kdc](10-icinga-template-library.md#plugin-contrib-command-kdc)
* [rbl](10-icinga-template-library.md#plugin-contrib-command-rbl) * [rbl](10-icinga-template-library.md#plugin-contrib-command-rbl)
### <a id="service-monitoring-java"></a> Java Monitoring ### Java Monitoring <a id="service-monitoring-java"></a>
* [jmx4perl](10-icinga-template-library.md#plugin-contrib-command-jmx4perl) * [jmx4perl](10-icinga-template-library.md#plugin-contrib-command-jmx4perl)
### <a id="service-monitoring-dns"></a> DNS Monitoring ### DNS Monitoring <a id="service-monitoring-dns"></a>
* [dns](10-icinga-template-library.md#plugin-check-command-dns) * [dns](10-icinga-template-library.md#plugin-check-command-dns)
* [dig](10-icinga-template-library.md#plugin-check-command-dig) * [dig](10-icinga-template-library.md#plugin-check-command-dig)
* [dhcp](10-icinga-template-library.md#plugin-check-command-dhcp) * [dhcp](10-icinga-template-library.md#plugin-check-command-dhcp)
### <a id="service-monitoring-backup"></a> Backup Monitoring ### Backup Monitoring <a id="service-monitoring-backup"></a>
* [check_bareos](https://github.com/widhalmt/check_bareos) * [check_bareos](https://github.com/widhalmt/check_bareos)
### <a id="service-monitoring-log"></a> Log Monitoring ### Log Monitoring <a id="service-monitoring-log"></a>
* [check_logfiles](https://labs.consol.de/nagios/check_logfiles/) * [check_logfiles](https://labs.consol.de/nagios/check_logfiles/)
* [check_logstash](https://github.com/widhalmt/check_logstash) * [check_logstash](https://github.com/widhalmt/check_logstash)
* [check_graylog2_stream](https://github.com/Graylog2/check-graylog2-stream) * [check_graylog2_stream](https://github.com/Graylog2/check-graylog2-stream)
### <a id="service-monitoring-virtualization"></a> Virtualization Monitoring ### Virtualization Monitoring <a id="service-monitoring-virtualization"></a>
### <a id="service-monitoring-virtualization-vmware"></a> VMware Monitoring ### VMware Monitoring <a id="service-monitoring-virtualization-vmware"></a>
* [esxi_hardware](10-icinga-template-library.md#plugin-contrib-command-esxi-hardware) * [esxi_hardware](10-icinga-template-library.md#plugin-contrib-command-esxi-hardware)
* [VMware](10-icinga-template-library.md#plugin-contrib-vmware) * [VMware](10-icinga-template-library.md#plugin-contrib-vmware)
@ -261,23 +261,23 @@ Instead, choose a plugin and configure its parameters and thresholds. The follow
**Tip**: If you are encountering timeouts using the VMware Perl SDK, **Tip**: If you are encountering timeouts using the VMware Perl SDK,
check [this blog entry](https://www.claudiokuenzler.com/blog/650/slow-vmware-perl-sdk-soap-request-error-libwww-version). check [this blog entry](https://www.claudiokuenzler.com/blog/650/slow-vmware-perl-sdk-soap-request-error-libwww-version).
### <a id="service-monitoring-sap"></a> SAP Monitoring ### SAP Monitoring <a id="service-monitoring-sap"></a>
* [check_sap_health](https://labs.consol.de/nagios/check_sap_health/index.html) * [check_sap_health](https://labs.consol.de/nagios/check_sap_health/index.html)
* [SAP CCMS](https://sourceforge.net/projects/nagios-sap-ccms/) * [SAP CCMS](https://sourceforge.net/projects/nagios-sap-ccms/)
### <a id="service-monitoring-mail"></a> Mail Monitoring ### Mail Monitoring <a id="service-monitoring-mail"></a>
* [smtp](10-icinga-template-library.md#plugin-check-command-smtp), [ssmtp](10-icinga-template-library.md#plugin-check-command-ssmtp) * [smtp](10-icinga-template-library.md#plugin-check-command-smtp), [ssmtp](10-icinga-template-library.md#plugin-check-command-ssmtp)
* [imap](10-icinga-template-library.md#plugin-check-command-imap), [simap](10-icinga-template-library.md#plugin-check-command-simap) * [imap](10-icinga-template-library.md#plugin-check-command-imap), [simap](10-icinga-template-library.md#plugin-check-command-simap)
* [pop](10-icinga-template-library.md#plugin-check-command-pop), [spop](10-icinga-template-library.md#plugin-check-command-spop) * [pop](10-icinga-template-library.md#plugin-check-command-pop), [spop](10-icinga-template-library.md#plugin-check-command-spop)
* [mailq](10-icinga-template-library.md#plugin-check-command-mailq) * [mailq](10-icinga-template-library.md#plugin-check-command-mailq)
### <a id="service-monitoring-hardware"></a> Hardware Monitoring ### Hardware Monitoring <a id="service-monitoring-hardware"></a>
* [hpasm](10-icinga-template-library.md#plugin-contrib-command-hpasm) * [hpasm](10-icinga-template-library.md#plugin-contrib-command-hpasm)
* [ipmi-sensor](10-icinga-template-library.md#plugin-contrib-command-ipmi-sensor) * [ipmi-sensor](10-icinga-template-library.md#plugin-contrib-command-ipmi-sensor)
### <a id="service-monitoring-metrics"></a> Metrics Monitoring ### Metrics Monitoring <a id="service-monitoring-metrics"></a>
* [graphite](10-icinga-template-library.md#plugin-contrib-command-graphite) * [graphite](10-icinga-template-library.md#plugin-contrib-command-graphite)

284
doc/6-distributed-monitoring.md → doc/06-distributed-monitoring.md
View File

@ -1,10 +1,10 @@
# <a id="distributed-monitoring"></a> Distributed Monitoring with Master, Satellites, and Clients # Distributed Monitoring with Master, Satellites, and Clients <a id="distributed-monitoring"></a>
This chapter will guide you through the setup of a distributed monitoring This chapter will guide you through the setup of a distributed monitoring
environment, including high-availability clustering and setup details environment, including high-availability clustering and setup details
for the Icinga 2 client. for the Icinga 2 client.
## <a id="distributed-monitoring-roles"></a> Roles: Master, Satellites, and Clients ## Roles: Master, Satellites, and Clients <a id="distributed-monitoring-roles"></a>
Icinga 2 nodes can be given names for easier understanding: Icinga 2 nodes can be given names for easier understanding:
@ -36,16 +36,16 @@ In case you are planning a huge cluster setup with multiple levels and
lots of clients, read on -- we'll deal with these cases later on. lots of clients, read on -- we'll deal with these cases later on.
The installation on each system is the same: You need to install the The installation on each system is the same: You need to install the
[Icinga 2 package](2-getting-started.md#setting-up-icinga2) and the required [plugins](2-getting-started.md#setting-up-check-plugins). [Icinga 2 package](02-getting-started.md#setting-up-icinga2) and the required [plugins](02-getting-started.md#setting-up-check-plugins).
The required configuration steps are mostly happening The required configuration steps are mostly happening
on the command line. You can also [automate the setup](6-distributed-monitoring.md#distributed-monitoring-automation). on the command line. You can also [automate the setup](06-distributed-monitoring.md#distributed-monitoring-automation).
The first thing you need learn about a distributed setup is the hierarchy of the single components. The first thing you need learn about a distributed setup is the hierarchy of the single components.
## <a id="distributed-monitoring-zones"></a> Zones ## Zones <a id="distributed-monitoring-zones"></a>
The Icinga 2 hierarchy consists of so-called [zone](9-object-types.md#objecttype-zone) objects. The Icinga 2 hierarchy consists of so-called [zone](09-object-types.md#objecttype-zone) objects.
Zones depend on a parent-child relationship in order to trust each other. Zones depend on a parent-child relationship in order to trust each other.
![Icinga 2 Distributed Zones](images/distributed-monitoring/icinga2_distributed_zones.png) ![Icinga 2 Distributed Zones](images/distributed-monitoring/icinga2_distributed_zones.png)
@ -70,14 +70,14 @@ There are certain limitations for child zones, e.g. their members are not allowe
to send configuration commands to the parent zone members. Vice versa, the to send configuration commands to the parent zone members. Vice versa, the
trust hierarchy allows for example the `master` zone to send trust hierarchy allows for example the `master` zone to send
configuration files to the `satellite` zone. Read more about this configuration files to the `satellite` zone. Read more about this
in the [security section](6-distributed-monitoring.md#distributed-monitoring-security). in the [security section](06-distributed-monitoring.md#distributed-monitoring-security).
`client` nodes also have their own unique zone. By convention you `client` nodes also have their own unique zone. By convention you
can use the FQDN for the zone name. can use the FQDN for the zone name.
## <a id="distributed-monitoring-endpoints"></a> Endpoints ## Endpoints <a id="distributed-monitoring-endpoints"></a>
Nodes which are a member of a zone are so-called [Endpoint](9-object-types.md#objecttype-endpoint) objects. Nodes which are a member of a zone are so-called [Endpoint](09-object-types.md#objecttype-endpoint) objects.
![Icinga 2 Distributed Endpoints](images/distributed-monitoring/icinga2_distributed_endpoints.png) ![Icinga 2 Distributed Endpoints](images/distributed-monitoring/icinga2_distributed_endpoints.png)
@ -110,13 +110,13 @@ The zone membership is defined inside the `Zone` object definition using
the `endpoints` attribute with an array of `Endpoint` names. the `endpoints` attribute with an array of `Endpoint` names.
If you want to check the availability (e.g. ping checks) of the node If you want to check the availability (e.g. ping checks) of the node
you still need a [Host](9-object-types.md#objecttype-host) object. you still need a [Host](09-object-types.md#objecttype-host) object.
## <a id="distributed-monitoring-apilistener"></a> ApiListener ## ApiListener <a id="distributed-monitoring-apilistener"></a>
In case you are using the CLI commands later, you don't have to write In case you are using the CLI commands later, you don't have to write
this configuration from scratch in a text editor. this configuration from scratch in a text editor.
The [ApiListener](9-object-types.md#objecttype-apilistener) The [ApiListener](09-object-types.md#objecttype-apilistener)
object is used to load the SSL certificates and specify restrictions, e.g. object is used to load the SSL certificates and specify restrictions, e.g.
for accepting configuration commands. for accepting configuration commands.
@ -131,7 +131,7 @@ In order to use the `api` feature you need to enable it and restart Icinga 2.
icinga2 feature enable api icinga2 feature enable api
## <a id="distributed-monitoring-conventions"></a> Conventions ## Conventions <a id="distributed-monitoring-conventions"></a>
By convention all nodes should be configured using their FQDN. By convention all nodes should be configured using their FQDN.
@ -146,7 +146,7 @@ Setting this up on the command line will help you to minimize the effort.
Just keep in mind that you need to use the FQDN for endpoints and for Just keep in mind that you need to use the FQDN for endpoints and for
common names when asked. common names when asked.
## <a id="distributed-monitoring-security"></a> Security ## Security <a id="distributed-monitoring-security"></a>
While there are certain mechanisms to ensure a secure communication between all While there are certain mechanisms to ensure a secure communication between all
nodes (firewalls, policies, software hardening, etc.), Icinga 2 also provides nodes (firewalls, policies, software hardening, etc.), Icinga 2 also provides
@ -158,20 +158,20 @@ help you create those certificates.
* Child zones are not allowed to push configuration updates to parent zones. * Child zones are not allowed to push configuration updates to parent zones.
* Zones cannot interfere with other zones and influence each other. Each checkable host or service object is assigned to **one zone** only. * Zones cannot interfere with other zones and influence each other. Each checkable host or service object is assigned to **one zone** only.
* All nodes in a zone trust each other. * All nodes in a zone trust each other.
* [Config sync](6-distributed-monitoring.md#distributed-monitoring-top-down-config-sync) and [remote command endpoint execution](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint) is disabled by default. * [Config sync](06-distributed-monitoring.md#distributed-monitoring-top-down-config-sync) and [remote command endpoint execution](06-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint) is disabled by default.
The underlying protocol uses JSON-RPC event notifications exchanged by nodes. The underlying protocol uses JSON-RPC event notifications exchanged by nodes.
The connection is secured by TLS. The message protocol uses an internal API, The connection is secured by TLS. The message protocol uses an internal API,
and as such message types and names may change internally and are not documented. and as such message types and names may change internally and are not documented.
## <a id="distributed-monitoring-setup-master"></a> Master Setup ## Master Setup <a id="distributed-monitoring-setup-master"></a>
This section explains how to install a central single master node using 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 the `node wizard` command. If you prefer to do an automated installation, please
refer to the [automated setup](6-distributed-monitoring.md#distributed-monitoring-automation) section. refer to the [automated setup](06-distributed-monitoring.md#distributed-monitoring-automation) section.
Install the [Icinga 2 package](2-getting-started.md#setting-up-icinga2) and setup Install the [Icinga 2 package](02-getting-started.md#setting-up-icinga2) and setup
the required [plugins](2-getting-started.md#setting-up-check-plugins) if you haven't done the required [plugins](02-getting-started.md#setting-up-check-plugins) if you haven't done
so already. so already.
**Note**: Windows is not supported for a master node setup. **Note**: Windows is not supported for a master node setup.
@ -236,24 +236,24 @@ Here is an example of a master setup for the `icinga2-master1.localdomain` node
[root@icinga2-master1.localdomain /]# systemctl restart icinga2 [root@icinga2-master1.localdomain /]# systemctl restart icinga2
As you can see, the CA public and private key are stored in the `/var/lib/icinga2/ca` directory. As you can see, the CA public and private key are stored in the `/var/lib/icinga2/ca` directory.
Keep this path secure and include it in your [backups](2-getting-started.md#install-backup). Keep this path secure and include it in your [backups](02-getting-started.md#install-backup).
In case you lose the CA private key you have to generate a new CA for signing new client In case you lose the CA private key you have to generate a new CA for signing new client
certificate requests. You then have to also re-create new signed certificates for all certificate requests. You then have to also re-create new signed certificates for all
existing nodes. existing nodes.
Once the master setup is complete, you can also use this node as primary [CSR auto-signing](6-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing) Once the master setup is complete, you can also use this node as primary [CSR auto-signing](06-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing)
master. The following section will explain how to use the CLI commands in order to fetch their master. The following section will explain how to use the CLI commands in order to fetch their
signed certificate from this master node. signed certificate from this master node.
## <a id="distributed-monitoring-setup-satellite-client"></a> Client/Satellite Setup ## Client/Satellite Setup <a id="distributed-monitoring-setup-satellite-client"></a>
This section describes the setup of a satellite and/or client connected to an This section describes the setup of a satellite and/or client connected to an
existing master node setup. If you haven't done so already, please [run the master setup](6-distributed-monitoring.md#distributed-monitoring-setup-master). existing master node setup. If you haven't done so already, please [run the master setup](06-distributed-monitoring.md#distributed-monitoring-setup-master).
Icinga 2 on the master node must be running and accepting connections on port `5665`. Icinga 2 on the master node must be running and accepting connections on port `5665`.
### <a id="distributed-monitoring-setup-csr-auto-signing"></a> CSR Auto-Signing ### CSR Auto-Signing <a id="distributed-monitoring-setup-csr-auto-signing"></a>
The `node wizard` command will set up a satellite/client using CSR auto-signing. This The `node wizard` command will set up a satellite/client using CSR auto-signing. This
involves that the setup wizard sends a certificate signing request (CSR) to the involves that the setup wizard sends a certificate signing request (CSR) to the
@ -261,7 +261,7 @@ master node.
There is a security mechanism in place which requires the client to send in a valid There is a security mechanism in place which requires the client to send in a valid
ticket for CSR auto-signing. ticket for CSR auto-signing.
This ticket must be generated beforehand. The `ticket_salt` attribute for the [ApiListener](9-object-types.md#objecttype-apilistener) This ticket must be generated beforehand. The `ticket_salt` attribute for the [ApiListener](09-object-types.md#objecttype-apilistener)
must be configured in order to make this work. must be configured in order to make this work.
There are two possible ways to retrieve the ticket: There are two possible ways to retrieve the ticket:
@ -301,14 +301,14 @@ Store that ticket number for the satellite/client setup below.
**Note**: Never expose the ticket salt and/or ApiUser credentials to your client nodes. **Note**: Never expose the ticket salt and/or ApiUser credentials to your client nodes.
Example: Retrieve the ticket on the Puppet master node and send the compiled catalog Example: Retrieve the ticket on the Puppet master node and send the compiled catalog
to the authorized Puppet agent node which will invoke the to the authorized Puppet agent node which will invoke the
[automated setup steps](6-distributed-monitoring.md#distributed-monitoring-automation-cli-node-setup). [automated setup steps](06-distributed-monitoring.md#distributed-monitoring-automation-cli-node-setup).
### <a id="distributed-monitoring-setup-client-linux"></a> Client/Satellite Linux Setup ### Client/Satellite Linux Setup <a id="distributed-monitoring-setup-client-linux"></a>
Please ensure that you've run all the steps mentioned in the [client/satellite section](6-distributed-monitoring.md#distributed-monitoring-setup-satellite-client). Please ensure that you've run all the steps mentioned in the [client/satellite section](06-distributed-monitoring.md#distributed-monitoring-setup-satellite-client).
Install the [Icinga 2 package](2-getting-started.md#setting-up-icinga2) and setup Install the [Icinga 2 package](02-getting-started.md#setting-up-icinga2) and setup
the required [plugins](2-getting-started.md#setting-up-check-plugins) if you haven't done the required [plugins](02-getting-started.md#setting-up-check-plugins) if you haven't done
so already. so already.
The next step is to run the `node wizard` CLI command. Prior to that The next step is to run the `node wizard` CLI command. Prior to that
@ -324,11 +324,11 @@ ensure to collect the required information:
Add more master endpoints | **Optional.** If you have multiple master nodes configured, add them here. Add more master endpoints | **Optional.** If you have multiple master nodes configured, add them here.
Master connection for CSR auto-signing | **Required.** The master node's IP address or FQDN and port where the client should request a certificate from. Defaults to the master endpoint host. Master connection for CSR auto-signing | **Required.** The master node's IP address or FQDN and port where the client should request a certificate from. Defaults to the master endpoint host.
Certificate information | **Required.** Verify that the connecting host really is the requested master node. Certificate information | **Required.** Verify that the connecting host really is the requested master node.
Request ticket | **Required.** Paste the previously generated [ticket number](6-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing). Request ticket | **Required.** Paste the previously generated [ticket number](06-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing).
API bind host | **Optional.** Allows to specify the address the ApiListener is bound to. For advanced usage only. API bind host | **Optional.** Allows to specify the address the ApiListener is bound to. For advanced usage only.
API bind port | **Optional.** Allows to specify the port the ApiListener is bound to. For advanced usage only (requires changing the default port 5665 everywhere). API bind port | **Optional.** Allows to specify the port the ApiListener is bound to. For advanced usage only (requires changing the default port 5665 everywhere).
Accept config | **Optional.** Whether this node accepts configuration sync from the master node (required for [config sync mode](6-distributed-monitoring.md#distributed-monitoring-top-down-config-sync)). For [security reasons](6-distributed-monitoring.md#distributed-monitoring-security) this defaults to `n`. Accept config | **Optional.** Whether this node accepts configuration sync from the master node (required for [config sync mode](06-distributed-monitoring.md#distributed-monitoring-top-down-config-sync)). For [security reasons](06-distributed-monitoring.md#distributed-monitoring-security) this defaults to `n`.
Accept commands | **Optional.** Whether this node accepts command execution messages from the master node (required for [command endpoint mode](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint)). For [security reasons](6-distributed-monitoring.md#distributed-monitoring-security) this defaults to `n`. Accept commands | **Optional.** Whether this node accepts command execution messages from the master node (required for [command endpoint mode](06-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint)). For [security reasons](06-distributed-monitoring.md#distributed-monitoring-security) this defaults to `n`.
The setup wizard will ensure that the following steps are taken: The setup wizard will ensure that the following steps are taken:
@ -410,9 +410,9 @@ is configured to accept configuration and commands from the master:
As you can see, the certificate files are stored in the `/etc/icinga2/pki` directory. As you can see, the certificate files are stored in the `/etc/icinga2/pki` directory.
Now that you've successfully installed a satellite/client, please proceed to Now that you've successfully installed a satellite/client, please proceed to
the [configuration modes](6-distributed-monitoring.md#distributed-monitoring-configuration-modes). the [configuration modes](06-distributed-monitoring.md#distributed-monitoring-configuration-modes).
### <a id="distributed-monitoring-setup-client-windows"></a> Client/Satellite Windows Setup ### Client/Satellite Windows Setup <a id="distributed-monitoring-setup-client-windows"></a>
Download the MSI-Installer package from [https://packages.icinga.com/windows/](https://packages.icinga.com/windows/). Download the MSI-Installer package from [https://packages.icinga.com/windows/](https://packages.icinga.com/windows/).
@ -423,12 +423,12 @@ Requirements:
The installer package includes the [NSClient++](https://www.nsclient.org/) package The installer package includes the [NSClient++](https://www.nsclient.org/) package
so that Icinga 2 can use its built-in plugins. You can find more details in so that Icinga 2 can use its built-in plugins. You can find more details in
[this chapter](6-distributed-monitoring.md#distributed-monitoring-windows-nscp). [this chapter](06-distributed-monitoring.md#distributed-monitoring-windows-nscp).
The Windows package also installs native [monitoring plugin binaries](6-distributed-monitoring.md#distributed-monitoring-windows-plugins) The Windows package also installs native [monitoring plugin binaries](06-distributed-monitoring.md#distributed-monitoring-windows-plugins)
to get you started more easily. to get you started more easily.
#### <a id="distributed-monitoring-setup-client-windows-start"></a> Windows Client Setup Start #### Windows Client Setup Start <a id="distributed-monitoring-setup-client-windows-start"></a>
Run the MSI-Installer package and follow the instructions shown in the screenshots. Run the MSI-Installer package and follow the instructions shown in the screenshots.
@ -447,7 +447,7 @@ You'll need the following configuration details:
Parameter | Description Parameter | Description
--------------------|-------------------- --------------------|--------------------
Common name (CN) | **Required.** By convention this should be the host's FQDN. Defaults to the FQDN. Common name (CN) | **Required.** By convention this should be the host's FQDN. Defaults to the FQDN.
Request ticket | **Required.** Paste the previously generated [ticket number](6-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing). Request ticket | **Required.** Paste the previously generated [ticket number](06-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing).
Fill in the required information and click `Add` to add a new master connection. Fill in the required information and click `Add` to add a new master connection.
@ -467,9 +467,9 @@ Optionally, you can enable the following settings:
Parameter | Description Parameter | Description
--------------------|-------------------- --------------------|--------------------
Accept config | **Optional.** Whether this node accepts configuration sync from the master node (required for [config sync mode](6-distributed-monitoring.md#distributed-monitoring-top-down-config-sync)). For [security reasons](6-distributed-monitoring.md#distributed-monitoring-security) this is disabled by default. Accept config | **Optional.** Whether this node accepts configuration sync from the master node (required for [config sync mode](06-distributed-monitoring.md#distributed-monitoring-top-down-config-sync)). For [security reasons](06-distributed-monitoring.md#distributed-monitoring-security) this is disabled by default.
Accept commands | **Optional.** Whether this node accepts command execution messages from the master node (required for [command endpoint mode](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint)). For [security reasons](6-distributed-monitoring.md#distributed-monitoring-security) this is disabled by default. Accept commands | **Optional.** Whether this node accepts command execution messages from the master node (required for [command endpoint mode](06-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint)). For [security reasons](06-distributed-monitoring.md#distributed-monitoring-security) this is disabled by default.
Install NSClient++ | **Optional.** The Windows installer bundles the NSClient++ installer for additional [plugin checks](6-distributed-monitoring.md#distributed-monitoring-windows-nscp). Install NSClient++ | **Optional.** The Windows installer bundles the NSClient++ installer for additional [plugin checks](06-distributed-monitoring.md#distributed-monitoring-windows-nscp).
![Icinga 2 Windows Setup](images/distributed-monitoring/icinga2_windows_setup_wizard_03.png) ![Icinga 2 Windows Setup](images/distributed-monitoring/icinga2_windows_setup_wizard_03.png)
@ -477,7 +477,7 @@ The next step allows you to verify the CA presented by the master.
![Icinga 2 Windows Setup](images/distributed-monitoring/icinga2_windows_setup_wizard_04.png) ![Icinga 2 Windows Setup](images/distributed-monitoring/icinga2_windows_setup_wizard_04.png)
#### <a id="distributed-monitoring-setup-client-windows-nsclient"></a> Bundled NSClient++ Setup #### Bundled NSClient++ Setup <a id="distributed-monitoring-setup-client-windows-nsclient"></a>
If you have chosen to install/update the NSClient++ package, the Icinga 2 setup wizard will ask If you have chosen to install/update the NSClient++ package, the Icinga 2 setup wizard will ask
you to do so. you to do so.
@ -514,7 +514,7 @@ configuration file.
The NSClient++ REST API can be used to query metrics. Future Icinga 2 versions will add The NSClient++ REST API can be used to query metrics. Future Icinga 2 versions will add
more integrations. Additional details can be found in this [blog post](https://www.icinga.com/2016/09/16/nsclient-0-5-0-rest-api-and-icinga-2-integration/). more integrations. Additional details can be found in this [blog post](https://www.icinga.com/2016/09/16/nsclient-0-5-0-rest-api-and-icinga-2-integration/).
#### <a id="distributed-monitoring-setup-client-windows-finish"></a> Finish Windows Client Setup #### Finish Windows Client Setup <a id="distributed-monitoring-setup-client-windows-finish"></a>
Finish the setup wizard. Finish the setup wizard.
@ -531,10 +531,10 @@ If you click `Examine Config` in the setup wizard, it will open a new Explorer w
The configuration files can be modified with your favorite editor. The configuration files can be modified with your favorite editor.
In order to use the [top down](6-distributed-monitoring.md#distributed-monitoring-top-down) client In order to use the [top down](06-distributed-monitoring.md#distributed-monitoring-top-down) client
configuration prepare the following steps. configuration prepare the following steps.
Add a [global zone](6-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync) Add a [global zone](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync)
for syncing check commands later. Navigate to `C:\ProgramData\icinga2\etc\icinga2` and open for syncing check commands later. Navigate to `C:\ProgramData\icinga2\etc\icinga2` and open
the `zones.conf` file in your preferred editor. Add the following lines if not existing already: the `zones.conf` file in your preferred editor. Add the following lines if not existing already:
@ -569,27 +569,27 @@ and restart the `icinga2` service. Alternatively, you can use the `net {start,st
![Icinga 2 Windows Service Start/Stop](images/distributed-monitoring/icinga2_windows_cmd_admin_net_start_stop.png) ![Icinga 2 Windows Service Start/Stop](images/distributed-monitoring/icinga2_windows_cmd_admin_net_start_stop.png)
Now that you've successfully installed a satellite/client, please proceed to Now that you've successfully installed a satellite/client, please proceed to
the [detailed configuration modes](6-distributed-monitoring.md#distributed-monitoring-configuration-modes). the [detailed configuration modes](06-distributed-monitoring.md#distributed-monitoring-configuration-modes).
## <a id="distributed-monitoring-configuration-modes"></a> Configuration Modes ## Configuration Modes <a id="distributed-monitoring-configuration-modes"></a>
There are different ways to ensure that the Icinga 2 cluster nodes execute There are different ways to ensure that the Icinga 2 cluster nodes execute
checks, send notifications, etc. checks, send notifications, etc.
Two different modes are available for synchronizing the host/service object's configuration between nodes and for executing checks: Two different modes are available for synchronizing the host/service object's configuration between nodes and for executing checks:
The preferred mode is the [top down](6-distributed-monitoring.md#distributed-monitoring-top-down) approach. The preferred mode is the [top down](06-distributed-monitoring.md#distributed-monitoring-top-down) approach.
This mode sends the configuration and commands from the master to the child zones. This mode sends the configuration and commands from the master to the child zones.
The [bottom up](6-distributed-monitoring.md#distributed-monitoring-bottom-up) has been **deprecated in v2.6 and will be removed in future releases**. The [bottom up](06-distributed-monitoring.md#distributed-monitoring-bottom-up) has been **deprecated in v2.6 and will be removed in future releases**.
This mode leaves the configuration files on the child nodes and requires an import on the parent nodes. This mode leaves the configuration files on the child nodes and requires an import on the parent nodes.
**Note**: Check results are always sent from the child nodes to the parent nodes. **Note**: Check results are always sent from the child nodes to the parent nodes.
This happens automatically and is ensured by the cluster protocol. This happens automatically and is ensured by the cluster protocol.
### <a id="distributed-monitoring-top-down"></a> Top Down ### Top Down <a id="distributed-monitoring-top-down"></a>
According to feedback that we've received from the community, this is the most commonly used mode. According to feedback that we've received from the community, this is the most commonly used mode.
@ -601,7 +601,7 @@ There are two different behaviors with check execution:
Again, technically it does not matter whether this is a `client` or a `satellite` Again, technically it does not matter whether this is a `client` or a `satellite`
which is receiving configuration or command execution events. which is receiving configuration or command execution events.
### <a id="distributed-monitoring-top-down-command-endpoint"></a> Top Down Command Endpoint ### Top Down Command Endpoint <a id="distributed-monitoring-top-down-command-endpoint"></a>
This mode will force the Icinga 2 node to execute commands remotely on a specified endpoint. This mode will force the Icinga 2 node to execute commands remotely on a specified endpoint.
The host/service object configuration is located on the master/satellite and the client only The host/service object configuration is located on the master/satellite and the client only
@ -613,14 +613,14 @@ Advantages:
* No local checks need to be defined on the child node (client). * No local checks need to be defined on the child node (client).
* Light-weight remote check execution (asynchronous events). * Light-weight remote check execution (asynchronous events).
* No [replay log](6-distributed-monitoring.md#distributed-monitoring-advanced-hints-command-endpoint-log-duration) is necessary for the child node. * No [replay log](06-distributed-monitoring.md#distributed-monitoring-advanced-hints-command-endpoint-log-duration) is necessary for the child node.
* Pin checks to specific endpoints (if the child zone consists of 2 endpoints). * Pin checks to specific endpoints (if the child zone consists of 2 endpoints).
Disadvantages: Disadvantages:
* If the child node is not connected, no more checks are executed. * If the child node is not connected, no more checks are executed.
* Requires additional configuration attribute specified in host/service objects. * Requires additional configuration attribute specified in host/service objects.
* Requires local `CheckCommand` object configuration. Best practice is to use a [global config zone](6-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync). * Requires local `CheckCommand` object configuration. Best practice is to use a [global config zone](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync).
To make sure that all nodes involved will accept configuration and/or To make sure that all nodes involved will accept configuration and/or
commands, you need to configure the `Zone` and `Endpoint` hierarchy commands, you need to configure the `Zone` and `Endpoint` hierarchy
@ -662,7 +662,7 @@ The `master` zone is a parent of the `icinga2-client1.localdomain` zone:
parent = "master" //establish zone hierarchy parent = "master" //establish zone hierarchy
} }
In addition, add a [global zone](6-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync) In addition, add a [global zone](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync)
for syncing check commands later: for syncing check commands later:
[root@icinga2-client1.localdomain /]# vim /etc/icinga2/zones.conf [root@icinga2-client1.localdomain /]# vim /etc/icinga2/zones.conf
@ -772,11 +772,11 @@ The following steps will happen:
As you can see, no interaction from your side is required on the client itself, and it's not necessary to reload the Icinga 2 service on the client. As you can see, no interaction from your side is required on the client itself, and it's not necessary to reload the Icinga 2 service on the client.
You have learned the basics about command endpoint checks. Proceed with You have learned the basics about command endpoint checks. Proceed with
the [scenarios](6-distributed-monitoring.md#distributed-monitoring-scenarios) the [scenarios](06-distributed-monitoring.md#distributed-monitoring-scenarios)
section where you can find detailed information on extending the setup. section where you can find detailed information on extending the setup.
### <a id="distributed-monitoring-top-down-config-sync"></a> Top Down Config Sync ### Top Down Config Sync <a id="distributed-monitoring-top-down-config-sync"></a>
This mode syncs the object configuration files within specified zones. This mode syncs the object configuration files within specified zones.
It comes in handy if you want to configure everything on the master node It comes in handy if you want to configure everything on the master node
@ -862,7 +862,7 @@ Example on CentOS 7:
[root@icinga2-master1.localdomain /]# systemctl restart icinga2 [root@icinga2-master1.localdomain /]# systemctl restart icinga2
**Tip**: Best practice is to use a [global zone](6-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync) **Tip**: Best practice is to use a [global zone](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync)
for common configuration items (check commands, templates, groups, etc.). for common configuration items (check commands, templates, groups, etc.).
Once the clients have connected successfully, it's time for the next step: **execute Once the clients have connected successfully, it's time for the next step: **execute
@ -929,16 +929,16 @@ Multiple nodes with configuration files in the `zones.d` directory are
**not supported**. **not supported**.
Now that you've learned the basics about the configuration sync, proceed with Now that you've learned the basics about the configuration sync, proceed with
the [scenarios](6-distributed-monitoring.md#distributed-monitoring-scenarios) the [scenarios](06-distributed-monitoring.md#distributed-monitoring-scenarios)
section where you can find detailed information on extending the setup. section where you can find detailed information on extending the setup.
### <a id="distributed-monitoring-bottom-up"></a> Bottom Up Import ### Bottom Up Import <a id="distributed-monitoring-bottom-up"></a>
> **Warning** > **Warning**
> >
> This mode has been deprecated in v2.6. You are strongly advised to > This mode has been deprecated in v2.6. You are strongly advised to
> migrate your existing configuration files to the [top down mode](6-distributed-monitoring.md#distributed-monitoring-top-down). > migrate your existing configuration files to the [top down mode](06-distributed-monitoring.md#distributed-monitoring-top-down).
> >
> Make sure to follow the release announcements on the [Icinga website](https://www.icinga.com). > Make sure to follow the release announcements on the [Icinga website](https://www.icinga.com).
@ -996,7 +996,7 @@ If you have accidentally added specific hosts or services, you can safely purge
them from this directory and restart Icinga 2. them from this directory and restart Icinga 2.
The generated host object uses the `cluster-zone` check command as The generated host object uses the `cluster-zone` check command as
[health check](6-distributed-monitoring.md#distributed-monitoring-health-checks). [health check](06-distributed-monitoring.md#distributed-monitoring-health-checks).
**Tip**: In case you want to blacklist or whitelist certain hosts and/or services **Tip**: In case you want to blacklist or whitelist certain hosts and/or services
on the master, use the `icinga2 node {black,white}list` on the master, use the `icinga2 node {black,white}list`
@ -1027,10 +1027,10 @@ and fix it. This will help with additional notification apply rules
or group memberships required for Icinga Web 2 and addons. or group memberships required for Icinga Web 2 and addons.
#### <a id="distributed-monitoring-bottom-up-migration-top-down"></a> Bottom Up Migration to Top Down #### Bottom Up Migration to Top Down <a id="distributed-monitoring-bottom-up-migration-top-down"></a>
The bottom up mode has been deprecated and you should be prepared to migrate The bottom up mode has been deprecated and you should be prepared to migrate
your clients to the existing [top down mode](6-distributed-monitoring.md#distributed-monitoring-top-down). your clients to the existing [top down mode](06-distributed-monitoring.md#distributed-monitoring-top-down).
The bottom up mode generates configuration files on the master node underneath The bottom up mode generates configuration files on the master node underneath
the `/etc/icinga2/repository.d` directory. This is achieved by running the the `/etc/icinga2/repository.d` directory. This is achieved by running the
@ -1046,7 +1046,7 @@ directory and generates the `repository.d` configuration files. In addition to
that blacklist and whitelist settings are evaluated. that blacklist and whitelist settings are evaluated.
Those CLI commands also hide the fact that each client needs its own `Zone` Those CLI commands also hide the fact that each client needs its own `Zone`
and `Endpoint` object as described [here](6-distributed-monitoring.md#distributed-monitoring-roles). and `Endpoint` object as described [here](06-distributed-monitoring.md#distributed-monitoring-roles).
If you are certain that the master node has an up-to-date `repository.d` If you are certain that the master node has an up-to-date `repository.d`
ensure that all your clients **do not include conf.d in their icinga2.conf** ensure that all your clients **do not include conf.d in their icinga2.conf**
@ -1054,7 +1054,7 @@ configuration file.
**Steps on each client**: **Steps on each client**:
Add a [global zone](6-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync) Add a [global zone](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync)
for syncing check commands later: for syncing check commands later:
[root@icinga2-client3.localdomain /]# vim /etc/icinga2/zones.conf [root@icinga2-client3.localdomain /]# vim /etc/icinga2/zones.conf
@ -1099,7 +1099,7 @@ Example on CentOS 7:
**Steps on the configuration master node**: **Steps on the configuration master node**:
The migration strategy will guide you to use the client(s) as The migration strategy will guide you to use the client(s) as
[top down command endpoint](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint). [top down command endpoint](06-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint).
The `repository.d` directory is organised as a tree of object type directories. The `repository.d` directory is organised as a tree of object type directories.
@ -1162,7 +1162,7 @@ client connection check `cluster-zone`, you need to add the `cluster_zone` custo
In addition to that add a new custom attribute called `client_endpoint` which stores In addition to that add a new custom attribute called `client_endpoint` which stores
the command endpoint information. In case you need to learn more details please refer to the command endpoint information. In case you need to learn more details please refer to
the [top down command endpoint](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint) the [top down command endpoint](06-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint)
chapter. chapter.
[root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/master/icinga2-client3.localdomain.conf [root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/master/icinga2-client3.localdomain.conf
@ -1181,7 +1181,7 @@ Extract the service objects from the configuration files in the
and add them into the `/etc/icinga2/zones.d/master/icinga2-client3.localdomain.conf` and add them into the `/etc/icinga2/zones.d/master/icinga2-client3.localdomain.conf`
file. file.
Best practice is to use a generic [service apply rule](3-monitoring-basics.md#using-apply) Best practice is to use a generic [service apply rule](03-monitoring-basics.md#using-apply)
for each service. Identify common services on your hosts and modify the apply rules for for each service. Identify common services on your hosts and modify the apply rules for
your own needs. your own needs.
@ -1255,7 +1255,7 @@ adopt and merge them accordingly.
If you are eager to start fresh instead you might take a look into the If you are eager to start fresh instead you might take a look into the
[Icinga Director](https://github.com/icinga/icingaweb2-module-director). [Icinga Director](https://github.com/icinga/icingaweb2-module-director).
## <a id="distributed-monitoring-scenarios"></a> Scenarios ## Scenarios <a id="distributed-monitoring-scenarios"></a>
The following examples should give you an idea on how to build your own The following examples should give you an idea on how to build your own
distributed monitoring environment. We've seen them all in production distributed monitoring environment. We've seen them all in production
@ -1266,7 +1266,7 @@ and [partner support](https://www.icinga.com/services/support/) channels:
* HA master with clients as command endpoint. * HA master with clients as command endpoint.
* Three level cluster with config HA masters, satellites receiving config sync, and clients checked using command endpoint. * Three level cluster with config HA masters, satellites receiving config sync, and clients checked using command endpoint.
### <a id="distributed-monitoring-master-clients"></a> Master with Clients ### Master with Clients <a id="distributed-monitoring-master-clients"></a>
![Icinga 2 Distributed Master with Clients](images/distributed-monitoring/icinga2_distributed_scenarios_master_clients.png) ![Icinga 2 Distributed Master with Clients](images/distributed-monitoring/icinga2_distributed_scenarios_master_clients.png)
@ -1275,8 +1275,8 @@ and [partner support](https://www.icinga.com/services/support/) channels:
Setup requirements: Setup requirements:
* Set up `icinga2-master1.localdomain` as [master](6-distributed-monitoring.md#distributed-monitoring-setup-master). * Set up `icinga2-master1.localdomain` as [master](06-distributed-monitoring.md#distributed-monitoring-setup-master).
* Set up `icinga2-client1.localdomain` and `icinga2-client2.localdomain` as [client](6-distributed-monitoring.md#distributed-monitoring-setup-satellite-client). * Set up `icinga2-client1.localdomain` and `icinga2-client2.localdomain` as [client](06-distributed-monitoring.md#distributed-monitoring-setup-satellite-client).
Edit the `zones.conf` configuration file on the master: Edit the `zones.conf` configuration file on the master:
@ -1320,7 +1320,7 @@ is that they know about the parent zone and their endpoint members (and optional
If you specify the `host` attribute in the `icinga2-master1.localdomain` endpoint object, If you specify the `host` attribute in the `icinga2-master1.localdomain` endpoint object,
the client will actively try to connect to the master node. Since we've specified the client the client will actively try to connect to the master node. Since we've specified the client
endpoint's attribute on the master node already, we don't want the clients to connect to the endpoint's attribute on the master node already, we don't want the clients to connect to the
master. **Choose one [connection direction](6-distributed-monitoring.md#distributed-monitoring-advanced-hints-connection-direction).** master. **Choose one [connection direction](06-distributed-monitoring.md#distributed-monitoring-advanced-hints-connection-direction).**
[root@icinga2-client1.localdomain /]# vim /etc/icinga2/zones.conf [root@icinga2-client1.localdomain /]# vim /etc/icinga2/zones.conf
@ -1422,11 +1422,11 @@ Validate the configuration and restart Icinga 2 on the master node `icinga2-mast
Open Icinga Web 2 and check the two newly created client hosts with two new services Open Icinga Web 2 and check the two newly created client hosts with two new services
-- one executed locally (`ping4`) and one using command endpoint (`disk`). -- one executed locally (`ping4`) and one using command endpoint (`disk`).
### <a id="distributed-monitoring-scenarios-ha-master-clients"></a> High-Availability Master with Clients ### High-Availability Master with Clients <a id="distributed-monitoring-scenarios-ha-master-clients"></a>
![Icinga 2 Distributed High Availability Master with Clients](images/distributed-monitoring/icinga2_distributed_scenarios_ha_master_clients.png) ![Icinga 2 Distributed High Availability Master with Clients](images/distributed-monitoring/icinga2_distributed_scenarios_ha_master_clients.png)
This scenario is similar to the one in the [previous section](6-distributed-monitoring.md#distributed-monitoring-master-clients). The only difference is that we will now set up two master nodes in a high-availablity setup. This scenario is similar to the one in the [previous section](06-distributed-monitoring.md#distributed-monitoring-master-clients). The only difference is that we will now set up two master nodes in a high-availablity setup.
These nodes must be configured as zone and endpoints objects. These nodes must be configured as zone and endpoints objects.
The setup uses the capabilities of the Icinga 2 cluster. All zone members The setup uses the capabilities of the Icinga 2 cluster. All zone members
@ -1443,15 +1443,15 @@ Overview:
Setup requirements: Setup requirements:
* Set up `icinga2-master1.localdomain` as [master](6-distributed-monitoring.md#distributed-monitoring-setup-master). * Set up `icinga2-master1.localdomain` as [master](06-distributed-monitoring.md#distributed-monitoring-setup-master).
* Set up `icinga2-master2.localdomain` as [client](6-distributed-monitoring.md#distributed-monitoring-setup-satellite-client) (we will modify the generated configuration). * Set up `icinga2-master2.localdomain` as [client](06-distributed-monitoring.md#distributed-monitoring-setup-satellite-client) (we will modify the generated configuration).
* Set up `icinga2-client1.localdomain` and `icinga2-client2.localdomain` as [clients](6-distributed-monitoring.md#distributed-monitoring-setup-satellite-client) (when asked for adding multiple masters, set to `y` and add the secondary master `icinga2-master2.localdomain`). * Set up `icinga2-client1.localdomain` and `icinga2-client2.localdomain` as [clients](06-distributed-monitoring.md#distributed-monitoring-setup-satellite-client) (when asked for adding multiple masters, set to `y` and add the secondary master `icinga2-master2.localdomain`).
In case you don't want to use the CLI commands, you can also manually create and sync the In case you don't want to use the CLI commands, you can also manually create and sync the
required SSL certificates. We will modify and discuss all the details of the automatically generated configuration here. required SSL certificates. We will modify and discuss all the details of the automatically generated configuration here.
Since there are now two nodes in the same zone, we must consider the Since there are now two nodes in the same zone, we must consider the
[high-availability features](6-distributed-monitoring.md#distributed-monitoring-high-availability-features). [high-availability features](06-distributed-monitoring.md#distributed-monitoring-high-availability-features).
* Checks and notifiations are balanced between the two master nodes. That's fine, but it requires check plugins and notification scripts to exist on both nodes. * Checks and notifiations are balanced between the two master nodes. That's fine, but it requires check plugins and notification scripts to exist on both nodes.
* The IDO feature will only be active on one node by default. Since all events are replicated between both nodes, it is easier to just have one central database. * The IDO feature will only be active on one node by default. Since all events are replicated between both nodes, it is easier to just have one central database.
@ -1510,7 +1510,7 @@ is that they know about the parent zone and their endpoint members (and optional
If you specify the `host` attribute in the `icinga2-master1.localdomain` and `icinga2-master2.localdomain` If you specify the `host` attribute in the `icinga2-master1.localdomain` and `icinga2-master2.localdomain`
endpoint objects, the client will actively try to connect to the master node. Since we've specified the client endpoint objects, the client will actively try to connect to the master node. Since we've specified the client
endpoint's attribute on the master node already, we don't want the clients to connect to the endpoint's attribute on the master node already, we don't want the clients to connect to the
master nodes. **Choose one [connection direction](6-distributed-monitoring.md#distributed-monitoring-advanced-hints-connection-direction).** master nodes. **Choose one [connection direction](06-distributed-monitoring.md#distributed-monitoring-advanced-hints-connection-direction).**
[root@icinga2-client1.localdomain /]# vim /etc/icinga2/zones.conf [root@icinga2-client1.localdomain /]# vim /etc/icinga2/zones.conf
@ -1574,7 +1574,7 @@ config sync mode here.
Create a new configuration directory on the master node `icinga2-master1.localdomain`. Create a new configuration directory on the master node `icinga2-master1.localdomain`.
**Note**: The secondary master node `icinga2-master2.localdomain` receives the **Note**: The secondary master node `icinga2-master2.localdomain` receives the
configuration using the [config sync mode](6-distributed-monitoring.md#distributed-monitoring-top-down-config-sync). configuration using the [config sync mode](06-distributed-monitoring.md#distributed-monitoring-top-down-config-sync).
[root@icinga2-master1.localdomain /]# mkdir -p /etc/icinga2/zones.d/master [root@icinga2-master1.localdomain /]# mkdir -p /etc/icinga2/zones.d/master
@ -1622,11 +1622,11 @@ Validate the configuration and restart Icinga 2 on the master node `icinga2-mast
Open Icinga Web 2 and check the two newly created client hosts with two new services Open Icinga Web 2 and check the two newly created client hosts with two new services
-- one executed locally (`ping4`) and one using command endpoint (`disk`). -- one executed locally (`ping4`) and one using command endpoint (`disk`).
**Tip**: It's a good idea to add [health checks](6-distributed-monitoring.md#distributed-monitoring-health-checks) **Tip**: It's a good idea to add [health checks](06-distributed-monitoring.md#distributed-monitoring-health-checks)
to make sure that your cluster notifies you in case of failure. to make sure that your cluster notifies you in case of failure.
### <a id="distributed-monitoring-scenarios-master-satellite-client"></a> Three Levels with Master, Satellites, and Clients ### Three Levels with Master, Satellites, and Clients <a id="distributed-monitoring-scenarios-master-satellite-client"></a>
![Icinga 2 Distributed Master and Satellites with Clients](images/distributed-monitoring/icinga2_distributed_scenarios_master_satellite_client.png) ![Icinga 2 Distributed Master and Satellites with Clients](images/distributed-monitoring/icinga2_distributed_scenarios_master_satellite_client.png)
@ -1646,9 +1646,9 @@ Overview:
Setup requirements: Setup requirements:
* Set up `icinga2-master1.localdomain` as [master](6-distributed-monitoring.md#distributed-monitoring-setup-master). * Set up `icinga2-master1.localdomain` as [master](06-distributed-monitoring.md#distributed-monitoring-setup-master).
* Set up `icinga2-master2.localdomain`, `icinga2-satellite1.localdomain` and `icinga2-satellite2.localdomain` as [clients](6-distributed-monitoring.md#distributed-monitoring-setup-satellite-client) (we will modify the generated configuration). * Set up `icinga2-master2.localdomain`, `icinga2-satellite1.localdomain` and `icinga2-satellite2.localdomain` as [clients](06-distributed-monitoring.md#distributed-monitoring-setup-satellite-client) (we will modify the generated configuration).
* Set up `icinga2-client1.localdomain` and `icinga2-client2.localdomain` as [clients](6-distributed-monitoring.md#distributed-monitoring-setup-satellite-client). * Set up `icinga2-client1.localdomain` and `icinga2-client2.localdomain` as [clients](06-distributed-monitoring.md#distributed-monitoring-setup-satellite-client).
When being asked for the master endpoint providing CSR auto-signing capabilities, When being asked for the master endpoint providing CSR auto-signing capabilities,
please add the master node which holds the CA and has the `ApiListener` feature configured and enabled. please add the master node which holds the CA and has the `ApiListener` feature configured and enabled.
@ -1683,7 +1683,7 @@ Specify the master node `icinga2-master2.localdomain` with the CA private key an
Port [5665]: Port [5665]:
In case you cannot connect to the master node from your clients, you'll manually need In case you cannot connect to the master node from your clients, you'll manually need
to [generate the SSL certificates](6-distributed-monitoring.md#distributed-monitoring-advanced-hints-certificates) to [generate the SSL certificates](06-distributed-monitoring.md#distributed-monitoring-advanced-hints-certificates)
and modify the configuration accordingly. and modify the configuration accordingly.
We'll discuss the details of the required configuration below. We'll discuss the details of the required configuration below.
@ -1691,7 +1691,7 @@ We'll discuss the details of the required configuration below.
The zone hierarchy can look like this. We'll define only the directly connected zones here. The zone hierarchy can look like this. We'll define only the directly connected zones here.
You can safely deploy this configuration onto all master and satellite zone You can safely deploy this configuration onto all master and satellite zone
members. You should keep in mind to control the endpoint [connection direction](6-distributed-monitoring.md#distributed-monitoring-advanced-hints-connection-direction) members. You should keep in mind to control the endpoint [connection direction](06-distributed-monitoring.md#distributed-monitoring-advanced-hints-connection-direction)
using the `host` attribute. using the `host` attribute.
[root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.conf [root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.conf
@ -1730,7 +1730,7 @@ using the `host` attribute.
Repeat the configuration step for `icinga2-master2.localdomain`, `icinga2-satellite1.localdomain` Repeat the configuration step for `icinga2-master2.localdomain`, `icinga2-satellite1.localdomain`
and `icinga2-satellite2.localdomain`. and `icinga2-satellite2.localdomain`.
Since we want to use [top down command endpoint](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint) checks, Since we want to use [top down command endpoint](06-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint) checks,
we must configure the client endpoint and zone objects. we must configure the client endpoint and zone objects.
In order to minimize the effort, we'll sync the client zone and endpoint configuration to the In order to minimize the effort, we'll sync the client zone and endpoint configuration to the
satellites where the connection information is needed as well. satellites where the connection information is needed as well.
@ -1768,7 +1768,7 @@ is that they know about the parent zone (the satellite) and their endpoint membe
If you specify the `host` attribute in the `icinga2-satellite1.localdomain` and `icinga2-satellite2.localdomain` If you specify the `host` attribute in the `icinga2-satellite1.localdomain` and `icinga2-satellite2.localdomain`
endpoint objects, the client node will actively try to connect to the satellite node. Since we've specified the client endpoint objects, the client node will actively try to connect to the satellite node. Since we've specified the client
endpoint's attribute on the satellite node already, we don't want the client node to connect to the endpoint's attribute on the satellite node already, we don't want the client node to connect to the
satellite nodes. **Choose one [connection direction](6-distributed-monitoring.md#distributed-monitoring-advanced-hints-connection-direction).** satellite nodes. **Choose one [connection direction](06-distributed-monitoring.md#distributed-monitoring-advanced-hints-connection-direction).**
Example for `icinga2-client1.localdomain`: Example for `icinga2-client1.localdomain`:
@ -1894,15 +1894,15 @@ Validate the configuration and restart Icinga 2 on the master node `icinga2-mast
Open Icinga Web 2 and check the two newly created client hosts with two new services Open Icinga Web 2 and check the two newly created client hosts with two new services
-- one executed locally (`ping4`) and one using command endpoint (`disk`). -- one executed locally (`ping4`) and one using command endpoint (`disk`).
**Tip**: It's a good idea to add [health checks](6-distributed-monitoring.md#distributed-monitoring-health-checks) **Tip**: It's a good idea to add [health checks](06-distributed-monitoring.md#distributed-monitoring-health-checks)
to make sure that your cluster notifies you in case of failure. to make sure that your cluster notifies you in case of failure.
## <a id="distributed-monitoring-best-practice"></a> Best Practice ## Best Practice <a id="distributed-monitoring-best-practice"></a>
We've put together a collection of configuration examples from community feedback. We've put together a collection of configuration examples from community feedback.
If you like to share your tips and tricks with us, please join the [community channels](https://www.icinga.com/community/get-involved/)! If you like to share your tips and tricks with us, please join the [community channels](https://www.icinga.com/community/get-involved/)!
### <a id="distributed-monitoring-global-zone-config-sync"></a> Global Zone for Config Sync ### Global Zone for Config Sync <a id="distributed-monitoring-global-zone-config-sync"></a>
Global zones can be used to sync generic configuration objects Global zones can be used to sync generic configuration objects
to all nodes depending on them. Common examples are: to all nodes depending on them. Common examples are:
@ -1959,7 +1959,7 @@ Example:
[root@icinga2-master1.localdomain /]# cd /etc/icinga2/conf.d [root@icinga2-master1.localdomain /]# cd /etc/icinga2/conf.d
[root@icinga2-master1.localdomain /etc/icinga2/conf.d]# cp {commands,downtimes,groups,notifications,templates,timeperiods,users}.conf /etc/icinga2/zones.d/global-templates [root@icinga2-master1.localdomain /etc/icinga2/conf.d]# cp {commands,downtimes,groups,notifications,templates,timeperiods,users}.conf /etc/icinga2/zones.d/global-templates
### <a id="distributed-monitoring-health-checks"></a> Health Checks ### Health Checks <a id="distributed-monitoring-health-checks"></a>
In case of network failures or other problems, your monitoring might In case of network failures or other problems, your monitoring might
either have late check results or just send out mass alarms for unknown either have late check results or just send out mass alarms for unknown
@ -1990,7 +1990,7 @@ connected zones are working properly:
} }
The `cluster-zone` check will test whether the configured target zone is currently The `cluster-zone` check will test whether the configured target zone is currently
connected or not. This example adds a health check for the [ha master with clients scenario](6-distributed-monitoring.md#distributed-monitoring-scenarios-ha-master-clients). connected or not. This example adds a health check for the [ha master with clients scenario](06-distributed-monitoring.md#distributed-monitoring-scenarios-ha-master-clients).
[root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/master/services.conf [root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/master/services.conf
@ -2035,7 +2035,7 @@ add a dependency which prevents notifications for all other failing services:
ignore where service.name == "child-health" ignore where service.name == "child-health"
} }
### <a id="distributed-monitoring-pin-checks-zone"></a> Pin Checks in a Zone ### Pin Checks in a Zone <a id="distributed-monitoring-pin-checks-zone"></a>
In case you want to pin specific checks to their endpoints in a given zone you'll need to use In case you want to pin specific checks to their endpoints in a given zone you'll need to use
the `command_endpoint` attribute. This is reasonable if you want to the `command_endpoint` attribute. This is reasonable if you want to
@ -2064,7 +2064,7 @@ the service object is only created for host objects inside the `master`
zone. In addition to that the [match](18-library-reference.md#global-functions-match) zone. In addition to that the [match](18-library-reference.md#global-functions-match)
function ensures to only create services for the master nodes. function ensures to only create services for the master nodes.
### <a id="distributed-monitoring-windows-firewall"></a> Windows Firewall ### Windows Firewall <a id="distributed-monitoring-windows-firewall"></a>
By default ICMP requests are disabled in the Windows firewall. You can By default ICMP requests are disabled in the Windows firewall. You can
change that by [adding a new rule](https://support.microsoft.com/en-us/kb/947709). change that by [adding a new rule](https://support.microsoft.com/en-us/kb/947709).
@ -2077,7 +2077,7 @@ you'll also need to ensure that port `5665` is enabled.
C:\WINDOWS\system32>netsh advfirewall firewall add rule name="Open port 5665 (Icinga 2)" dir=in action=allow protocol=TCP localport=5665 C:\WINDOWS\system32>netsh advfirewall firewall add rule name="Open port 5665 (Icinga 2)" dir=in action=allow protocol=TCP localport=5665
### <a id="distributed-monitoring-windows-plugins"></a> Windows Client and Plugins ### Windows Client and Plugins <a id="distributed-monitoring-windows-plugins"></a>
The Icinga 2 package on Windows already provides several plugins. The Icinga 2 package on Windows already provides several plugins.
Detailed [documentation](10-icinga-template-library.md#windows-plugins) is available for all check command definitions. Detailed [documentation](10-icinga-template-library.md#windows-plugins) is available for all check command definitions.
@ -2088,7 +2088,7 @@ Add the following `include` statement on all your nodes (master, satellite, clie
include <windows-plugins> include <windows-plugins>
Based on the [master with clients](6-distributed-monitoring.md#distributed-monitoring-master-clients) Based on the [master with clients](06-distributed-monitoring.md#distributed-monitoring-master-clients)
scenario we'll now add a local disk check. scenario we'll now add a local disk check.
First, add the client node as host object: First, add the client node as host object:
@ -2128,30 +2128,30 @@ Open Icinga Web 2 and check your newly added Windows disk check :)
![Icinga 2 Client Windows](images/distributed-monitoring/icinga2_distributed_windows_client_disk_icingaweb2.png) ![Icinga 2 Client Windows](images/distributed-monitoring/icinga2_distributed_windows_client_disk_icingaweb2.png)
If you want to add your own plugins please check [this chapter](5-service-monitoring.md#service-monitoring-requirements) If you want to add your own plugins please check [this chapter](05-service-monitoring.md#service-monitoring-requirements)
for the requirements. for the requirements.
### <a id="distributed-monitoring-windows-nscp"></a> Windows Client and NSClient++ ### Windows Client and NSClient++ <a id="distributed-monitoring-windows-nscp"></a>
There are two methods available for querying NSClient++: There are two methods available for querying NSClient++:
* Query the [HTTP API](6-distributed-monitoring.md#distributed-monitoring-windows-nscp-check-api) locally or remotely (requires a running NSClient++ service) * Query the [HTTP API](06-distributed-monitoring.md#distributed-monitoring-windows-nscp-check-api) locally or remotely (requires a running NSClient++ service)
* Run a [local CLI check](6-distributed-monitoring.md#distributed-monitoring-windows-nscp-check-local) (does not require NSClient++ as a service) * Run a [local CLI check](06-distributed-monitoring.md#distributed-monitoring-windows-nscp-check-local) (does not require NSClient++ as a service)
Both methods have their advantages and disadvantages. One thing to Both methods have their advantages and disadvantages. One thing to
note: If you rely on performance counter delta calculations such as note: If you rely on performance counter delta calculations such as
CPU utilization, please use the HTTP API instead of the CLI sample call. CPU utilization, please use the HTTP API instead of the CLI sample call.
#### <a id="distributed-monitoring-windows-nscp-check-api"></a> NSCLient++ with check_nscp_api #### NSCLient++ with check_nscp_api <a id="distributed-monitoring-windows-nscp-check-api"></a>
The [Windows setup](6-distributed-monitoring.md#distributed-monitoring-setup-client-windows) already allows The [Windows setup](06-distributed-monitoring.md#distributed-monitoring-setup-client-windows) already allows
you to install the NSClient++ package. In addition to the Windows plugins you can you to install the NSClient++ package. In addition to the Windows plugins you can
use the [nscp_api command](10-icinga-template-library.md#nscp-check-api) provided by the Icinga Template Library (ITL). use the [nscp_api command](10-icinga-template-library.md#nscp-check-api) provided by the Icinga Template Library (ITL).
The initial setup for the NSClient++ API and the required arguments The initial setup for the NSClient++ API and the required arguments
is the described in the ITL chapter for the [nscp_api](10-icinga-template-library.md#nscp-check-api) CheckCommand. is the described in the ITL chapter for the [nscp_api](10-icinga-template-library.md#nscp-check-api) CheckCommand.
Based on the [master with clients](6-distributed-monitoring.md#distributed-monitoring-master-clients) Based on the [master with clients](06-distributed-monitoring.md#distributed-monitoring-master-clients)
scenario we'll now add a local nscp check which queries the NSClient++ API to check the free disk space. scenario we'll now add a local nscp check which queries the NSClient++ API to check the free disk space.
Define a host object called `icinga2-client2.localdomain` on the master. Add the `nscp_api_password` Define a host object called `icinga2-client2.localdomain` on the master. Add the `nscp_api_password`
@ -2169,7 +2169,7 @@ custom attribute and specify the drives to check.
vars.drives = [ "C:", "D:" ] vars.drives = [ "C:", "D:" ]
} }
The service checks are generated using an [apply for](3-monitoring-basics.md#using-apply-for) The service checks are generated using an [apply for](03-monitoring-basics.md#using-apply-for)
rule based on `host.vars.drives`: rule based on `host.vars.drives`:
[root@icinga2-master1.localdomain /etc/icinga2/zones.d/master]# vim services.conf [root@icinga2-master1.localdomain /etc/icinga2/zones.d/master]# vim services.conf
@ -2210,9 +2210,9 @@ which defaults to `host.address`.
You can verify the check execution by looking at the `Check Source` attribute You can verify the check execution by looking at the `Check Source` attribute
in Icinga Web 2 or the REST API. in Icinga Web 2 or the REST API.
#### <a id="distributed-monitoring-windows-nscp-check-local"></a> NSCLient++ with nscp-local #### NSCLient++ with nscp-local <a id="distributed-monitoring-windows-nscp-check-local"></a>
The [Windows setup](6-distributed-monitoring.md#distributed-monitoring-setup-client-windows) already allows The [Windows setup](06-distributed-monitoring.md#distributed-monitoring-setup-client-windows) already allows
you to install the NSClient++ package. In addition to the Windows plugins you can you to install the NSClient++ package. In addition to the Windows plugins you can
use the [nscp-local commands](10-icinga-template-library.md#nscp-plugin-check-commands) use the [nscp-local commands](10-icinga-template-library.md#nscp-plugin-check-commands)
provided by the Icinga Template Library (ITL). provided by the Icinga Template Library (ITL).
@ -2228,7 +2228,7 @@ Add the following `include` statement on all your nodes (master, satellite, clie
The CheckCommand definitions will automatically determine the installed path The CheckCommand definitions will automatically determine the installed path
to the `nscp.exe` binary. to the `nscp.exe` binary.
Based on the [master with clients](6-distributed-monitoring.md#distributed-monitoring-master-clients) Based on the [master with clients](06-distributed-monitoring.md#distributed-monitoring-master-clients)
scenario we'll now add a local nscp check querying a given performance counter. scenario we'll now add a local nscp check querying a given performance counter.
First, add the client node as host object: First, add the client node as host object:
@ -2271,22 +2271,22 @@ Open Icinga Web 2 and check your newly added Windows NSClient++ check :)
![Icinga 2 Distributed Monitoring Windows Client with NSClient++ nscp-local](images/distributed-monitoring/icinga2_distributed_windows_nscp_counter_icingaweb2.png) ![Icinga 2 Distributed Monitoring Windows Client with NSClient++ nscp-local](images/distributed-monitoring/icinga2_distributed_windows_nscp_counter_icingaweb2.png)
## <a id="distributed-monitoring-advanced-hints"></a> Advanced Hints ## Advanced Hints <a id="distributed-monitoring-advanced-hints"></a>
You can find additional hints in this section if you prefer to go your own route You can find additional hints in this section if you prefer to go your own route
with automating setups (setup, certificates, configuration). with automating setups (setup, certificates, configuration).
### <a id="distributed-monitoring-high-availability-features"></a> High-Availability for Icinga 2 Features ### High-Availability for Icinga 2 Features <a id="distributed-monitoring-high-availability-features"></a>
All nodes in the same zone require that you enable the same features for high-availability (HA). All nodes in the same zone require that you enable the same features for high-availability (HA).
By default, the following features provide advanced HA functionality: By default, the following features provide advanced HA functionality:
* [Checks](6-distributed-monitoring.md#distributed-monitoring-high-availability-checks) (load balanced, automated failover). * [Checks](06-distributed-monitoring.md#distributed-monitoring-high-availability-checks) (load balanced, automated failover).
* [Notifications](6-distributed-monitoring.md#distributed-monitoring-high-availability-notifications) (load balanced, automated failover). * [Notifications](06-distributed-monitoring.md#distributed-monitoring-high-availability-notifications) (load balanced, automated failover).
* [DB IDO](6-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido) (Run-Once, automated failover). * [DB IDO](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido) (Run-Once, automated failover).
#### <a id="distributed-monitoring-high-availability-checks"></a> High-Availability with Checks #### High-Availability with Checks <a id="distributed-monitoring-high-availability-checks"></a>
All instances within the same zone (e.g. the `master` zone as HA cluster) must All instances within the same zone (e.g. the `master` zone as HA cluster) must
have the `checker` feature enabled. have the `checker` feature enabled.
@ -2298,7 +2298,7 @@ Example:
All nodes in the same zone load-balance the check execution. If one instance shuts down, All nodes in the same zone load-balance the check execution. If one instance shuts down,
the other nodes will automatically take over the remaining checks. the other nodes will automatically take over the remaining checks.
#### <a id="distributed-monitoring-high-availability-notifications"></a> High-Availability with Notifications #### High-Availability with Notifications <a id="distributed-monitoring-high-availability-notifications"></a>
All instances within the same zone (e.g. the `master` zone as HA cluster) must All instances within the same zone (e.g. the `master` zone as HA cluster) must
have the `notification` feature enabled. have the `notification` feature enabled.
@ -2311,9 +2311,9 @@ Notifications are load-balanced amongst all nodes in a zone. By default this fun
is enabled. is enabled.
If your nodes should send out notifications independently from any other nodes (this will cause If your nodes should send out notifications independently from any other nodes (this will cause
duplicated notifications if not properly handled!), you can set `enable_ha = false` duplicated notifications if not properly handled!), you can set `enable_ha = false`
in the [NotificationComponent](9-object-types.md#objecttype-notificationcomponent) feature. in the [NotificationComponent](09-object-types.md#objecttype-notificationcomponent) feature.
#### <a id="distributed-monitoring-high-availability-db-ido"></a> High-Availability with DB IDO #### High-Availability with DB IDO <a id="distributed-monitoring-high-availability-db-ido"></a>
All instances within the same zone (e.g. the `master` zone as HA cluster) must All instances within the same zone (e.g. the `master` zone as HA cluster) must
have the DB IDO feature enabled. have the DB IDO feature enabled.
@ -2327,8 +2327,8 @@ the active IDO database connection at runtime. The node with the active DB IDO c
not necessarily the zone master. not necessarily the zone master.
**Note**: The DB IDO HA feature can be disabled by setting the `enable_ha` attribute to `false` **Note**: The DB IDO HA feature can be disabled by setting the `enable_ha` attribute to `false`
for the [IdoMysqlConnection](9-object-types.md#objecttype-idomysqlconnection) or for the [IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection) or
[IdoPgsqlConnection](9-object-types.md#objecttype-idopgsqlconnection) object on **all** nodes in the [IdoPgsqlConnection](09-object-types.md#objecttype-idopgsqlconnection) object on **all** nodes in the
**same** zone. **same** zone.
All endpoints will enable the DB IDO feature and connect to the configured All endpoints will enable the DB IDO feature and connect to the configured
@ -2351,9 +2351,9 @@ This is useful when the cluster connection between endpoints breaks, and prevent
data duplication in split-brain-scenarios. The failover timeout can be set for the data duplication in split-brain-scenarios. The failover timeout can be set for the
`failover_timeout` attribute, but not lower than 60 seconds. `failover_timeout` attribute, but not lower than 60 seconds.
### <a id="distributed-monitoring-advanced-hints-connection-direction"></a> Endpoint Connection Direction ### Endpoint Connection Direction <a id="distributed-monitoring-advanced-hints-connection-direction"></a>
Nodes will attempt to connect to another node when its local [Endpoint](9-object-types.md#objecttype-endpoint) object Nodes will attempt to connect to another node when its local [Endpoint](09-object-types.md#objecttype-endpoint) object
configuration specifies a valid `host` attribute (FQDN or IP address). configuration specifies a valid `host` attribute (FQDN or IP address).
Example for the master node `icinga2-master1.localdomain` actively connecting Example for the master node `icinga2-master1.localdomain` actively connecting
@ -2388,17 +2388,17 @@ and close the second connection if established.
or vice versa. or vice versa.
### <a id="distributed-monitoring-advanced-hints-command-endpoint-log-duration"></a> Disable Log Duration for Command Endpoints ### Disable Log Duration for Command Endpoints <a id="distributed-monitoring-advanced-hints-command-endpoint-log-duration"></a>
The replay log is a built-in mechanism to ensure that nodes in a distributed setup The replay log is a built-in mechanism to ensure that nodes in a distributed setup
keep the same history (check results, notifications, etc.) when nodes are temporarily keep the same history (check results, notifications, etc.) when nodes are temporarily
disconnected and then reconnect. disconnected and then reconnect.
This functionality is not needed when a master/satellite node is sending check This functionality is not needed when a master/satellite node is sending check
execution events to a client which is purely configured for [command endpoint](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint) execution events to a client which is purely configured for [command endpoint](06-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint)
checks only. checks only.
The [Endpoint](9-object-types.md#objecttype-endpoint) object attribute `log_duration` can The [Endpoint](09-object-types.md#objecttype-endpoint) object attribute `log_duration` can
be lower or set to 0 to fully disable any log replay updates when the be lower or set to 0 to fully disable any log replay updates when the
client is not connected. client is not connected.
@ -2434,7 +2434,7 @@ Configuration on the client `icinga2-client1.localdomain`:
log_duration = 0 log_duration = 0
} }
### <a id="distributed-monitoring-advanced-hints-csr-autosigning-ha-satellites"></a> CSR auto-signing with HA and multiple Level Cluster ### CSR auto-signing with HA and multiple Level Cluster <a id="distributed-monitoring-advanced-hints-csr-autosigning-ha-satellites"></a>
If you are using two masters in a High-Availability setup it can be necessary If you are using two masters in a High-Availability setup it can be necessary
to allow both to sign requested certificates. Ensure to safely sync the following to allow both to sign requested certificates. Ensure to safely sync the following
@ -2443,14 +2443,14 @@ details in private:
* `TicketSalt` constant in `constants.conf`. * `TicketSalt` constant in `constants.conf`.
* `var/lib/icinga2/ca` directory. * `var/lib/icinga2/ca` directory.
This also helps if you are using a [three level cluster](6-distributed-monitoring.md#distributed-monitoring-scenarios-master-satellite-client) This also helps if you are using a [three level cluster](06-distributed-monitoring.md#distributed-monitoring-scenarios-master-satellite-client)
and your client nodes are not able to reach the CSR auto-signing master node(s). and your client nodes are not able to reach the CSR auto-signing master node(s).
Make sure that the directory permissions for `/var/lib/icinga2/ca` are secure Make sure that the directory permissions for `/var/lib/icinga2/ca` are secure
(not world readable). (not world readable).
**Do not expose these private keys to anywhere else. This is a matter of security.** **Do not expose these private keys to anywhere else. This is a matter of security.**
### <a id="distributed-monitoring-advanced-hints-certificates"></a> Manual Certificate Creation ### Manual Certificate Creation <a id="distributed-monitoring-advanced-hints-certificates"></a>
Choose the host which should store the certificate authority (one of the master nodes). Choose the host which should store the certificate authority (one of the master nodes).
@ -2500,22 +2500,22 @@ Example for creating multiple certificates at once:
information/pki: Writing certificate to file 'icinga2-satellite1.localdomain.crt'. information/pki: Writing certificate to file 'icinga2-satellite1.localdomain.crt'.
## <a id="distributed-monitoring-automation"></a> Automation ## Automation <a id="distributed-monitoring-automation"></a>
These hints should get you started with your own automation tools (Puppet, Ansible, Chef, Salt, etc.) These hints should get you started with your own automation tools (Puppet, Ansible, Chef, Salt, etc.)
or custom scripts for automated setup. or custom scripts for automated setup.
These are collected best practices from various community channels. These are collected best practices from various community channels.
* [Silent Windows setup](6-distributed-monitoring.md#distributed-monitoring-automation-windows-silent) * [Silent Windows setup](06-distributed-monitoring.md#distributed-monitoring-automation-windows-silent)
* [Node Setup CLI command](6-distributed-monitoring.md#distributed-monitoring-automation-cli-node-setup) with parameters * [Node Setup CLI command](06-distributed-monitoring.md#distributed-monitoring-automation-cli-node-setup) with parameters
If you prefer an alternate method, we still recommend leaving all the Icinga 2 features intact (e.g. `icinga2 feature enable api`). If you prefer an alternate method, we still recommend leaving all the Icinga 2 features intact (e.g. `icinga2 feature enable api`).
You should also use well known and documented default configuration file locations (e.g. `zones.conf`). You should also use well known and documented default configuration file locations (e.g. `zones.conf`).
This will tremendously help when someone is trying to help in the [community channels](https://www.icinga.com/community/get-involved/). This will tremendously help when someone is trying to help in the [community channels](https://www.icinga.com/community/get-involved/).
### <a id="distributed-monitoring-automation-windows-silent"></a> Silent Windows Setup ### Silent Windows Setup <a id="distributed-monitoring-automation-windows-silent"></a>
If you want to install the client silently/unattended, use the `/qn` modifier. The If you want to install the client silently/unattended, use the `/qn` modifier. The
installation should not trigger a restart, but if you want to be completly sure, you can use the `/norestart` modifier. installation should not trigger a restart, but if you want to be completly sure, you can use the `/norestart` modifier.
@ -2524,7 +2524,7 @@ installation should not trigger a restart, but if you want to be completly sure,
Once the setup is completed you can use the `node setup` cli command too. Once the setup is completed you can use the `node setup` cli command too.
### <a id="distributed-monitoring-automation-cli-node-setup"></a> Node Setup using CLI Parameters ### Node Setup using CLI Parameters <a id="distributed-monitoring-automation-cli-node-setup"></a>
Instead of using the `node wizard` CLI command, there is an alternative `node setup` Instead of using the `node wizard` CLI command, there is an alternative `node setup`
command available which has some prerequisites. command available which has some prerequisites.
@ -2532,7 +2532,7 @@ command available which has some prerequisites.
**Note**: The CLI command can be used on Linux/Unix and Windows operating systems. **Note**: The CLI command can be used on Linux/Unix and Windows operating systems.
The graphical Windows setup wizard actively uses these CLI commands. The graphical Windows setup wizard actively uses these CLI commands.
#### <a id="distributed-monitoring-automation-cli-node-setup-master"></a> Node Setup on the Master Node #### Node Setup on the Master Node <a id="distributed-monitoring-automation-cli-node-setup-master"></a>
In case you want to setup a master node you must add the `--master` parameter In case you want to setup a master node you must add the `--master` parameter
to the `node setup` CLI command. In addition to that the `--cn` can optionally to the `node setup` CLI command. In addition to that the `--cn` can optionally
@ -2553,7 +2553,7 @@ host/port you can specify it like this:
--listen 192.68.56.101,5665 --listen 192.68.56.101,5665
#### <a id="distributed-monitoring-automation-cli-node-setup-satellite-client"></a> Node Setup with Satellites/Clients #### Node Setup with Satellites/Clients <a id="distributed-monitoring-automation-cli-node-setup-satellite-client"></a>
Make sure that the `/etc/icinga2/pki` exists and is owned by the `icinga` Make sure that the `/etc/icinga2/pki` exists and is owned by the `icinga`
user (or the user Icinga 2 is running as). user (or the user Icinga 2 is running as).
@ -2602,13 +2602,13 @@ Pass the following details to the `node setup` CLI command:
Parameter | Description Parameter | Description
--------------------|-------------------- --------------------|--------------------
Common name (CN) | **Optional.** Specified with the `--cn` parameter. By convention this should be the host's FQDN. Common name (CN) | **Optional.** Specified with the `--cn` parameter. By convention this should be the host's FQDN.
Request ticket | **Required.** Add the previously generated [ticket number](6-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing). Request ticket | **Required.** Add the previously generated [ticket number](06-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing).
Trusted master certicate | **Required.** Add the previously fetched trusted master certificate (this step means that you've verified its origin). Trusted master certicate | **Required.** Add the previously fetched trusted master certificate (this step means that you've verified its origin).
Master endpoint | **Required.** Specify the master's endpoint name. Master endpoint | **Required.** Specify the master's endpoint name.
Client zone name | **Required.** Specify the client's zone name. Client zone name | **Required.** Specify the client's zone name.
Master host | **Required.** FQDN or IP address of the master host. Master host | **Required.** FQDN or IP address of the master host.
Accept config | **Optional.** Whether this node accepts configuration sync from the master node (required for [config sync mode](6-distributed-monitoring.md#distributed-monitoring-top-down-config-sync)). Accept config | **Optional.** Whether this node accepts configuration sync from the master node (required for [config sync mode](06-distributed-monitoring.md#distributed-monitoring-top-down-config-sync)).
Accept commands | **Optional.** Whether this node accepts command execution messages from the master node (required for [command endpoint mode](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint)). Accept commands | **Optional.** Whether this node accepts command execution messages from the master node (required for [command endpoint mode](06-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint)).
Example: Example:
@ -2641,12 +2641,12 @@ Add an additional global zone. Please note the `>>` append mode.
Note: Packages >= 2.7 provide this configuration by default. Note: Packages >= 2.7 provide this configuration by default.
If this client node is configured as [remote command endpoint execution](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint) If this client node is configured as [remote command endpoint execution](06-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint)
you can safely disable the `checker` feature. The `node setup` CLI command already disabled the `notification` feature. you can safely disable the `checker` feature. The `node setup` CLI command already disabled the `notification` feature.
[root@icinga2-client1.localdomain /]# icinga2 feature disable checker [root@icinga2-client1.localdomain /]# icinga2 feature disable checker
Disable "conf.d" inclusion if this is a [top down](6-distributed-monitoring.md#distributed-monitoring-top-down) Disable "conf.d" inclusion if this is a [top down](06-distributed-monitoring.md#distributed-monitoring-top-down)
configured client. configured client.
[root@icinga2-client1.localdomain /]# sed -i 's/include_recursive "conf.d"/\/\/include_recursive "conf.d"/g' /etc/icinga2/icinga2.conf [root@icinga2-client1.localdomain /]# sed -i 's/include_recursive "conf.d"/\/\/include_recursive "conf.d"/g' /etc/icinga2/icinga2.conf

28
doc/7-agent-based-monitoring.md → doc/07-agent-based-monitoring.md
View File

@ -1,14 +1,14 @@
# <a id="agent-based-checks-addon"></a> Additional Agent-based Checks # Additional Agent-based Checks <a id="agent-based-checks-addon"></a>
If the remote services are not directly accessible through the network, a If the remote services are not directly accessible through the network, a
local agent installation exposing the results to check queries can local agent installation exposing the results to check queries can
become handy. become handy.
## <a id="agent-based-checks-snmp"></a> SNMP ## SNMP <a id="agent-based-checks-snmp"></a>
The SNMP daemon runs on the remote system and answers SNMP queries by plugin The SNMP daemon runs on the remote system and answers SNMP queries by plugin
binaries. The [Monitoring Plugins package](2-getting-started.md#setting-up-check-plugins) ships binaries. The [Monitoring Plugins package](02-getting-started.md#setting-up-check-plugins) ships
the `check_snmp` plugin binary, but there are plenty of [existing plugins](5-service-monitoring.md#service-monitoring-plugins) 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. for specific use cases already around, for example monitoring Cisco routers.
The following example uses the [SNMP ITL](10-icinga-template-library.md#plugin-check-command-snmp) `CheckCommand` and just The following example uses the [SNMP ITL](10-icinga-template-library.md#plugin-check-command-snmp) `CheckCommand` and just
@ -31,11 +31,11 @@ If no `snmp_miblist` is specified, the plugin will default to `ALL`. As the numb
on the system increases so will the load generated by this plugin if no `MIB` is specified. on the system increases so will the load generated by this plugin if no `MIB` is specified.
As such, it is recommended to always specify at least one `MIB`. As such, it is recommended to always specify at least one `MIB`.
## <a id="agent-based-checks-ssh"></a> SSH ## SSH <a id="agent-based-checks-ssh"></a>
Calling a plugin using the SSH protocol to execute a plugin on the remote server fetching Calling a plugin using the SSH protocol to execute a plugin on the remote server fetching
its return code and output. The `by_ssh` command object is part of the built-in templates and its return code and output. The `by_ssh` command object is part of the built-in templates and
requires the `check_by_ssh` check plugin which is available in the [Monitoring Plugins package](2-getting-started.md#setting-up-check-plugins). requires the `check_by_ssh` check plugin which is available in the [Monitoring Plugins package](02-getting-started.md#setting-up-check-plugins).
object CheckCommand "by_ssh_swap" { object CheckCommand "by_ssh_swap" {
import "by_ssh" import "by_ssh"
@ -55,7 +55,7 @@ requires the `check_by_ssh` check plugin which is available in the [Monitoring P
vars.by_ssh_logname = "icinga" vars.by_ssh_logname = "icinga"
} }
## <a id="agent-based-checks-nsclient"></a> NSClient++ ## NSClient++ <a id="agent-based-checks-nsclient"></a>
[NSClient++](https://nsclient.org/) works on both Windows and Linux platforms and is well [NSClient++](https://nsclient.org/) works on both Windows and Linux platforms and is well
known for its magnificent Windows support. There are alternatives like the WMI interface, known for its magnificent Windows support. There are alternatives like the WMI interface,
@ -82,7 +82,7 @@ Example:
For details on the `NSClient++` configuration please refer to the [official documentation](https://docs.nsclient.org/). For details on the `NSClient++` configuration please refer to the [official documentation](https://docs.nsclient.org/).
## <a id="agent-based-checks-nsca-ng"></a> NSCA-NG ## NSCA-NG <a id="agent-based-checks-nsca-ng"></a>
[NSCA-ng](http://www.nsca-ng.org) provides a client-server pair that allows the [NSCA-ng](http://www.nsca-ng.org) provides a client-server pair that allows the
remote sender to push check results into the Icinga 2 `ExternalCommandListener` remote sender to push check results into the Icinga 2 `ExternalCommandListener`
@ -93,7 +93,7 @@ feature.
> This addon works in a similar fashion like the Icinga 1.x distributed model. If you > This addon works in a similar fashion like the Icinga 1.x distributed model. If you
> are looking for a real distributed architecture with Icinga 2, scroll down. > are looking for a real distributed architecture with Icinga 2, scroll down.
## <a id="agent-based-checks-nrpe"></a> NRPE ## NRPE <a id="agent-based-checks-nrpe"></a>
[NRPE](https://docs.icinga.com/latest/en/nrpe.html) runs as daemon on the remote client including [NRPE](https://docs.icinga.com/latest/en/nrpe.html) runs as daemon on the remote client including
the required plugins and command definitions. the required plugins and command definitions.
@ -105,7 +105,7 @@ remote client.
> The NRPE protocol is considered insecure and has multiple flaws in its > The NRPE protocol is considered insecure and has multiple flaws in its
> design. Upstream is not willing to fix these issues. > design. Upstream is not willing to fix these issues.
> >
> In order to stay safe, please use the native [Icinga 2 client](6-distributed-monitoring.md#distributed-monitoring) > In order to stay safe, please use the native [Icinga 2 client](06-distributed-monitoring.md#distributed-monitoring)
> instead. > instead.
The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe` The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe`
@ -171,11 +171,11 @@ executed by the NRPE daemon looks similar to that:
/usr/local/icinga/libexec/check_disk -w 20% -c 10% -p / /usr/local/icinga/libexec/check_disk -w 20% -c 10% -p /
You can pass arguments in a similar manner to [NSClient++](7-agent-based-monitoring.md#agent-based-checks-nsclient) You can pass arguments in a similar manner to [NSClient++](07-agent-based-monitoring.md#agent-based-checks-nsclient)
when using its NRPE supported check method. when using its NRPE supported check method.
## <a id="agent-based-checks-snmp-traps"></a> Passive Check Results and SNMP Traps ## Passive Check Results and SNMP Traps <a id="agent-based-checks-snmp-traps"></a>
SNMP Traps can be received and filtered by using [SNMPTT](http://snmptt.sourceforge.net/) SNMP Traps can be received and filtered by using [SNMPTT](http://snmptt.sourceforge.net/)
and specific trap handlers passing the check results to Icinga 2. and specific trap handlers passing the check results to Icinga 2.
@ -184,7 +184,7 @@ Following the SNMPTT [Format](http://snmptt.sourceforge.net/docs/snmptt.shtml#SN
documentation and the Icinga external command syntax found [here](23-appendix.md#external-commands-list-detail) documentation and the Icinga external command syntax found [here](23-appendix.md#external-commands-list-detail)
we can create generic services that can accommodate any number of hosts for a given scenario. we can create generic services that can accommodate any number of hosts for a given scenario.
### <a id="simple-traps"></a> Simple SNMP Traps ### Simple SNMP Traps <a id="simple-traps"></a>
A simple example might be monitoring host reboots indicated by an SNMP agent reset. A simple example might be monitoring host reboots indicated by an SNMP agent reset.
Building the event to auto reset after dispatching a notification is important. Building the event to auto reset after dispatching a notification is important.
@ -310,7 +310,7 @@ Finally create the `Service` and assign it:
assign where (host.vars.os == "Linux" || host.vars.os == "Windows") assign where (host.vars.os == "Linux" || host.vars.os == "Windows")
} }
### <a id="complex-traps"></a> Complex SNMP Traps ### Complex SNMP Traps <a id="complex-traps"></a>
A more complex example might be passing dynamic data from a traps varbind list A more complex example might be passing dynamic data from a traps varbind list
for a backup scenario where the backup software dispatches status updates. By for a backup scenario where the backup software dispatches status updates. By

92
doc/8-advanced-topics.md → doc/08-advanced-topics.md
View File

@ -1,9 +1,9 @@
# <a id="advanced-topics"></a> Advanced Topics # Advanced Topics <a id="advanced-topics"></a>
This chapter covers a number of advanced topics. If you're new to Icinga, you This chapter covers a number of advanced topics. If you're new to Icinga, you
can safely skip over things you're not interested in. can safely skip over things you're not interested in.
## <a id="downtimes"></a> Downtimes ## Downtimes <a id="downtimes"></a>
Downtimes can be scheduled for planned server maintenance or Downtimes can be scheduled for planned server maintenance or
any other targeted service outage you are aware of in advance. any other targeted service outage you are aware of in advance.
@ -24,7 +24,7 @@ If the downtime was scheduled after the problem changed to a critical hard
state triggering a problem notification, and the service recovers during state triggering a problem notification, and the service recovers during
the downtime window, the recovery notification won't be suppressed. the downtime window, the recovery notification won't be suppressed.
### <a id="fixed-flexible-downtimes"></a> Fixed and Flexible Downtimes ### Fixed and Flexible Downtimes <a id="fixed-flexible-downtimes"></a>
A `fixed` downtime will be activated at the defined start time, and A `fixed` downtime will be activated at the defined start time, and
removed at the end time. During this time window the service state removed at the end time. During this time window the service state
@ -51,14 +51,14 @@ For that reason, you may want to schedule a downtime between 07:30 and
its trigger time until the duration is over. After that, the downtime its trigger time until the duration is over. After that, the downtime
is removed (may happen before or after the actual end time!). is removed (may happen before or after the actual end time!).
### <a id="scheduling-downtime"></a> Scheduling a downtime ### Scheduling a downtime <a id="scheduling-downtime"></a>
You can schedule a downtime either by using the Icinga 2 API action You can schedule a downtime either by using the Icinga 2 API action
[schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) or [schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) or
by sending an [external command](14-features.md#external-commands). by sending an [external command](14-features.md#external-commands).
#### <a id="fixed-downtime"></a> Fixed Downtime #### Fixed Downtime <a id="fixed-downtime"></a>
If the host/service changes into a NOT-OK state between the start and If the host/service changes into a NOT-OK state between the start and
end time window, the downtime will be marked as `in effect` and end time window, the downtime will be marked as `in effect` and
@ -70,7 +70,7 @@ start | end
trigger time trigger time
``` ```
#### <a id="flexible-downtime"></a> Flexible Downtime #### Flexible Downtime <a id="flexible-downtime"></a>
A flexible downtime defines a time window where the downtime may be A flexible downtime defines a time window where the downtime may be
triggered from a host/service NOT-OK state change. It will then last triggered from a host/service NOT-OK state change. It will then last
@ -87,7 +87,7 @@ start | end actual end time
``` ```
### <a id="triggered-downtimes"></a> Triggered Downtimes ### Triggered Downtimes <a id="triggered-downtimes"></a>
This is optional when scheduling a downtime. If there is already a downtime This is optional when scheduling a downtime. If there is already a downtime
scheduled for a future maintenance, the current downtime can be triggered by scheduled for a future maintenance, the current downtime can be triggered by
@ -95,9 +95,9 @@ that downtime. This renders useful if you have scheduled a host downtime and
are now scheduling a child host's downtime getting triggered by the parent are now scheduling a child host's downtime getting triggered by the parent
downtime on `NOT-OK` state change. downtime on `NOT-OK` state change.
### <a id="recurring-downtimes"></a> Recurring Downtimes ### Recurring Downtimes <a id="recurring-downtimes"></a>
[ScheduledDowntime objects](9-object-types.md#objecttype-scheduleddowntime) can be used to set up [ScheduledDowntime objects](09-object-types.md#objecttype-scheduleddowntime) can be used to set up
recurring downtimes for services. recurring downtimes for services.
Example: Example:
@ -120,7 +120,7 @@ Example:
} }
## <a id="comments-intro"></a> Comments ## Comments <a id="comments-intro"></a>
Comments can be added at runtime and are persistent over restarts. You can Comments can be added at runtime and are persistent over restarts. You can
add useful information for others on repeating incidents (for example add useful information for others on repeating incidents (for example
@ -131,14 +131,14 @@ You can add a comment either by using the Icinga 2 API action
[add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) or [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) or
by sending an [external command](14-features.md#external-commands). by sending an [external command](14-features.md#external-commands).
## <a id="acknowledgements"></a> Acknowledgements ## Acknowledgements <a id="acknowledgements"></a>
If a problem persists and notifications have been sent, you can If a problem persists and notifications have been sent, you can
acknowledge the problem. That way other users will get acknowledge the problem. That way other users will get
a notification that you're aware of the issue and probably are a notification that you're aware of the issue and probably are
already working on a fix. already working on a fix.
Note: Acknowledgements also add a new [comment](8-advanced-topics.md#comments-intro) Note: Acknowledgements also add a new [comment](08-advanced-topics.md#comments-intro)
which contains the author and text fields. which contains the author and text fields.
You can send an acknowledgement either by using the Icinga 2 API action You can send an acknowledgement either by using the Icinga 2 API action
@ -146,7 +146,7 @@ You can send an acknowledgement either by using the Icinga 2 API action
by sending an [external command](14-features.md#external-commands). by sending an [external command](14-features.md#external-commands).
### <a id="sticky-acknowledgements"></a> Sticky Acknowledgements ### Sticky Acknowledgements <a id="sticky-acknowledgements"></a>
The acknowledgement is removed if a state change occurs or if the host/service The acknowledgement is removed if a state change occurs or if the host/service
recovers (OK/Up state). recovers (OK/Up state).
@ -161,7 +161,7 @@ If you prefer to keep the acknowledgement until the problem is resolved (`OK`
recovery) you need to enable the `sticky` parameter. recovery) you need to enable the `sticky` parameter.
### <a id="expiring-acknowledgements"></a> Expiring Acknowledgements ### Expiring Acknowledgements <a id="expiring-acknowledgements"></a>
Once a problem is acknowledged it may disappear from your `handled problems` Once a problem is acknowledged it may disappear from your `handled problems`
dashboard and no-one ever looks at it again since it will suppress dashboard and no-one ever looks at it again since it will suppress
@ -175,9 +175,9 @@ Icinga 2 will clear the acknowledgement when expired and start to
re-notify, if the problem persists. re-notify, if the problem persists.
## <a id="timeperiods"></a> Time Periods ## Time Periods <a id="timeperiods"></a>
[Time Periods](9-object-types.md#objecttype-timeperiod) define [Time Periods](09-object-types.md#objecttype-timeperiod) define
time ranges in Icinga where event actions are triggered, for time ranges in Icinga where event actions are triggered, for
example whether a service check is executed or not within example whether a service check is executed or not within
the `check_period` attribute. Or a notification should be sent to the `check_period` attribute. Or a notification should be sent to
@ -282,14 +282,14 @@ to assign time periods to `Notification` and `Dependency` objects:
period = "workhours" period = "workhours"
} }
### <a id="timeperiods-includes-excludes"></a> Time Periods Inclusion and Exclusion ### Time Periods Inclusion and Exclusion <a id="timeperiods-includes-excludes"></a>
Sometimes it is necessary to exclude certain time ranges from Sometimes it is necessary to exclude certain time ranges from
your default time period definitions, for example, if you don't your default time period definitions, for example, if you don't
want to send out any notification during the holiday season, want to send out any notification during the holiday season,
or if you only want to allow small time windows for executed checks. or if you only want to allow small time windows for executed checks.
The [TimePeriod object](9-object-types.md#objecttype-timeperiod) The [TimePeriod object](09-object-types.md#objecttype-timeperiod)
provides the `includes` and `excludes` attributes to solve this issue. provides the `includes` and `excludes` attributes to solve this issue.
`prefer_includes` defines whether included or excluded time periods are `prefer_includes` defines whether included or excluded time periods are
preferred. preferred.
@ -343,7 +343,7 @@ and adds the excluded time period names as an array.
} }
} }
## <a id="check-result-freshness"></a> Check Result Freshness ## Check Result Freshness <a id="check-result-freshness"></a>
In Icinga 2 active check freshness is enabled by default. It is determined by the In Icinga 2 active check freshness is enabled by default. It is determined by the
`check_interval` attribute and no incoming check results in that period of time. `check_interval` attribute and no incoming check results in that period of time.
@ -358,7 +358,7 @@ If the freshness checks are invalid, a new check is executed defined by the
`check_command` attribute. `check_command` attribute.
## <a id="check-flapping"></a> Check Flapping ## Check Flapping <a id="check-flapping"></a>
Icinga 2 supports optional detection of hosts and services that are "flapping". Icinga 2 supports optional detection of hosts and services that are "flapping".
@ -369,12 +369,12 @@ or real network problems.
Flapping detection can be enabled or disabled using the `enable_flapping` attribute. Flapping detection can be enabled or disabled using the `enable_flapping` attribute.
The `flapping_threshold` attributes allows to specify the percentage of state changes The `flapping_threshold` attributes allows to specify the percentage of state changes
when a [host](9-object-types.md#objecttype-host) or [service](objecttype-service) is considered to flap. when a [host](09-object-types.md#objecttype-host) or [service](objecttype-service) is considered to flap.
Note: There are known issues with flapping detection. Please refrain from enabling Note: There are known issues with flapping detection. Please refrain from enabling
flapping until [#4982](https://github.com/Icinga/icinga2/issues/4982) is fixed. flapping until [#4982](https://github.com/Icinga/icinga2/issues/4982) is fixed.
## <a id="volatile-services"></a> Volatile Services ## Volatile Services <a id="volatile-services"></a>
By default all services remain in a non-volatile state. When a problem By default all services remain in a non-volatile state. When a problem
occurs, the `SOFT` state applies and once `max_check_attempts` attribute occurs, the `SOFT` state applies and once `max_check_attempts` attribute
@ -387,7 +387,7 @@ state type if the service stays in a `NOT-OK` state. That way each
service recheck will automatically trigger a notification unless the service recheck will automatically trigger a notification unless the
service is acknowledged or in a scheduled downtime. service is acknowledged or in a scheduled downtime.
## <a id="monitoring-icinga"></a> Monitoring Icinga 2 ## Monitoring Icinga 2 <a id="monitoring-icinga"></a>
Why should you do that? Icinga and its components run like any other Why should you do that? Icinga and its components run like any other
service application on your server. There are predictable issues service application on your server. There are predictable issues
@ -417,7 +417,7 @@ System | Logs | Forward them to [Elastic Stack](14-features.md#elastic-stack
System | NTP | [ntp_time](10-icinga-template-library.md#plugin-check-command-ntp-time) System | NTP | [ntp_time](10-icinga-template-library.md#plugin-check-command-ntp-time)
System | Updates | [apt](10-icinga-template-library.md#plugin-check-command-apt), [yum](10-icinga-template-library.md#plugin-contrib-command-yum) System | Updates | [apt](10-icinga-template-library.md#plugin-check-command-apt), [yum](10-icinga-template-library.md#plugin-contrib-command-yum)
Icinga | Status & Stats | [icinga](10-icinga-template-library.md#itl-icinga) (more below) Icinga | Status & Stats | [icinga](10-icinga-template-library.md#itl-icinga) (more below)
Icinga | Cluster & Clients | [health checks](6-distributed-monitoring.md#distributed-monitoring-health-checks) Icinga | Cluster & Clients | [health checks](06-distributed-monitoring.md#distributed-monitoring-health-checks)
Database | MySQL | [mysql_health](10-icinga-template-library.md#plugin-contrib-command-mysql_health) Database | MySQL | [mysql_health](10-icinga-template-library.md#plugin-contrib-command-mysql_health)
Database | PostgreSQL | [postgres](10-icinga-template-library.md#plugin-contrib-command-postgres) Database | PostgreSQL | [postgres](10-icinga-template-library.md#plugin-contrib-command-postgres)
Database | Housekeeping | Check the database size and growth and analyse metrics to examine trends. Database | Housekeeping | Check the database size and growth and analyse metrics to examine trends.
@ -438,7 +438,7 @@ Metrics | Graylog | [Graylog integration](14-features.md#graylog-integration)
The [icinga](10-icinga-template-library.md#itl-icinga) CheckCommand provides metrics for the runtime stats of The [icinga](10-icinga-template-library.md#itl-icinga) CheckCommand provides metrics for the runtime stats of
Icinga 2. You can forward them to your preferred graphing solution. Icinga 2. You can forward them to your preferred graphing solution.
If you require more metrics you can also query the [REST API](12-icinga2-api.md#icinga2-api) and write If you require more metrics you can also query the [REST API](12-icinga2-api.md#icinga2-api) and write
your own custom check plugin. Or you keep using the built-in [object accessor functions](8-advanced-topics.md#access-object-attributes-at-runtime) your own custom check plugin. Or you keep using the built-in [object accessor functions](08-advanced-topics.md#access-object-attributes-at-runtime)
to calculate stats in-memory. to calculate stats in-memory.
There is a built-in [ido](10-icinga-template-library.md#itl-icinga-ido) check available for DB IDO MySQL/PostgreSQL There is a built-in [ido](10-icinga-template-library.md#itl-icinga-ido) check available for DB IDO MySQL/PostgreSQL
@ -457,17 +457,17 @@ apply Service "ido-mysql" {
More specific database queries can be found in the [DB IDO](14-features.md#db-ido) chapter. More specific database queries can be found in the [DB IDO](14-features.md#db-ido) chapter.
Distributed setups should include specific [health checks](6-distributed-monitoring.md#distributed-monitoring-health-checks). Distributed setups should include specific [health checks](06-distributed-monitoring.md#distributed-monitoring-health-checks).
You might also want to add additional checks for SSL certificate expiration. You might also want to add additional checks for SSL certificate expiration.
## <a id="advanced-configuration-hints"></a> Advanced Configuration Hints ## Advanced Configuration Hints <a id="advanced-configuration-hints"></a>
### <a id="advanced-use-of-apply-rules"></a> Advanced Use of Apply Rules ### Advanced Use of Apply Rules <a id="advanced-use-of-apply-rules"></a>
[Apply rules](3-monitoring-basics.md#using-apply) can be used to create a rule set which is [Apply rules](03-monitoring-basics.md#using-apply) can be used to create a rule set which is
entirely based on host objects and their attributes. entirely based on host objects and their attributes.
In addition to that [apply for and custom attribute override](3-monitoring-basics.md#using-apply-for) In addition to that [apply for and custom attribute override](03-monitoring-basics.md#using-apply-for)
extend the possibilities. extend the possibilities.
The following example defines a dictionary on the host object which contains The following example defines a dictionary on the host object which contains
@ -546,13 +546,13 @@ service checks in this example.
In addition to defining check parameters this way, you can also enrich the `display_name` In addition to defining check parameters this way, you can also enrich the `display_name`
attribute with more details. This will be shown in in Icinga Web 2 for example. attribute with more details. This will be shown in in Icinga Web 2 for example.
### <a id="use-functions-object-config"></a> Use Functions in Object Configuration ### Use Functions in Object Configuration <a id="use-functions-object-config"></a>
There is a limited scope where functions can be used as object attributes such as: There is a limited scope where functions can be used as object attributes such as:
* As value for [Custom Attributes](3-monitoring-basics.md#custom-attributes-functions) * As value for [Custom Attributes](03-monitoring-basics.md#custom-attributes-functions)
* Returning boolean expressions for [set_if](8-advanced-topics.md#use-functions-command-arguments-setif) inside command arguments * Returning boolean expressions for [set_if](08-advanced-topics.md#use-functions-command-arguments-setif) inside command arguments
* Returning a [command](8-advanced-topics.md#use-functions-command-attribute) array inside command objects * Returning a [command](08-advanced-topics.md#use-functions-command-attribute) array inside command objects
The other way around you can create objects dynamically using your own global functions. The other way around you can create objects dynamically using your own global functions.
@ -560,7 +560,7 @@ The other way around you can create objects dynamically using your own global fu
> >
> Functions called inside command objects share the same global scope as runtime macros. > Functions called inside command objects share the same global scope as runtime macros.
> Therefore you can access host custom attributes like `host.vars.os`, or any other > Therefore you can access host custom attributes like `host.vars.os`, or any other
> object attribute from inside the function definition used for [set_if](8-advanced-topics.md#use-functions-command-arguments-setif) or [command](8-advanced-topics.md#use-functions-command-attribute). > object attribute from inside the function definition used for [set_if](08-advanced-topics.md#use-functions-command-arguments-setif) or [command](08-advanced-topics.md#use-functions-command-attribute).
Tips when implementing functions: Tips when implementing functions:
@ -569,10 +569,10 @@ inside the `icinga2.log` file depending in your log severity
* Use the `icinga2 console` to test basic functionality (e.g. iterating over a dictionary) * Use the `icinga2 console` to test basic functionality (e.g. iterating over a dictionary)
* Build them step-by-step. You can always refactor your code later on. * Build them step-by-step. You can always refactor your code later on.
#### <a id="use-functions-command-arguments-setif"></a> Use Functions in Command Arguments set_if #### Use Functions in Command Arguments set_if <a id="use-functions-command-arguments-setif"></a>
The `set_if` attribute inside the command arguments definition in the The `set_if` attribute inside the command arguments definition in the
[CheckCommand object definition](9-object-types.md#objecttype-checkcommand) is primarily used to [CheckCommand object definition](09-object-types.md#objecttype-checkcommand) is primarily used to
evaluate whether the command parameter should be set or not. evaluate whether the command parameter should be set or not.
By default you can evaluate runtime macros for their existence. If the result is not an empty By default you can evaluate runtime macros for their existence. If the result is not an empty
@ -648,10 +648,10 @@ The more programmatic approach for `set_if` could look like this:
} }
#### <a id="use-functions-command-attribute"></a> Use Functions as Command Attribute #### Use Functions as Command Attribute <a id="use-functions-command-attribute"></a>
This comes in handy for [NotificationCommands](9-object-types.md#objecttype-notificationcommand) This comes in handy for [NotificationCommands](09-object-types.md#objecttype-notificationcommand)
or [EventCommands](9-object-types.md#objecttype-eventcommand) which does not require or [EventCommands](09-object-types.md#objecttype-eventcommand) which does not require
a returned checkresult including state/output. a returned checkresult including state/output.
The following example was taken from the community support channels. The requirement was to The following example was taken from the community support channels. The requirement was to
@ -702,7 +702,7 @@ You can omit the `log()` calls, they only help debugging.
} }
} }
#### <a id="custom-functions-as-attribute"></a> Use Custom Functions as Attribute #### Use Custom Functions as Attribute <a id="custom-functions-as-attribute"></a>
To use custom functions as attributes, the function must be defined in a To use custom functions as attributes, the function must be defined in a
slightly unexpected way. The following example shows how to assign values slightly unexpected way. The following example shows how to assign values
@ -729,14 +729,14 @@ as value for `ping_wrta`, all other hosts use 100.
assign where true assign where true
} }
#### <a id="use-functions-assign-where"></a> Use Functions in Assign Where Expressions #### Use Functions in Assign Where Expressions <a id="use-functions-assign-where"></a>
If a simple expression for matching a name or checking if an item If a simple expression for matching a name or checking if an item
exists in an array or dictionary does not fit, you should consider exists in an array or dictionary does not fit, you should consider
writing your own global [functions](17-language-reference.md#functions). writing your own global [functions](17-language-reference.md#functions).
You can call them inside `assign where` and `ignore where` expressions You can call them inside `assign where` and `ignore where` expressions
for [apply rules](3-monitoring-basics.md#using-apply-expressions) or for [apply rules](03-monitoring-basics.md#using-apply-expressions) or
[group assignments](3-monitoring-basics.md#group-assign-intro) just like [group assignments](03-monitoring-basics.md#group-assign-intro) just like
any other global functions for example [match](18-library-reference.md#global-functions-match). any other global functions for example [match](18-library-reference.md#global-functions-match).
The following example requires the host `myprinter` being added The following example requires the host `myprinter` being added
@ -818,13 +818,13 @@ with the `vars_app` dictionary.
assign where check_app_type(host, "ABAP") assign where check_app_type(host, "ABAP")
} }
### <a id="access-object-attributes-at-runtime"></a> Access Object Attributes at Runtime ### Access Object Attributes at Runtime <a id="access-object-attributes-at-runtime"></a>
The [Object Accessor Functions](18-library-reference.md#object-accessor-functions) The [Object Accessor Functions](18-library-reference.md#object-accessor-functions)
can be used to retrieve references to other objects by name. can be used to retrieve references to other objects by name.
This allows you to access configuration and runtime object attributes. A detailed This allows you to access configuration and runtime object attributes. A detailed
list can be found [here](9-object-types.md#object-types). list can be found [here](09-object-types.md#object-types).
Simple cluster example for accessing two host object states and calculating a virtual Simple cluster example for accessing two host object states and calculating a virtual
cluster state and output: cluster state and output:

132
doc/9-object-types.md → doc/09-object-types.md
View File

@ -1,4 +1,4 @@
# <a id="object-types"></a> Config Object Types # Config Object Types <a id="object-types"></a>
This chapter provides an overview of all available config object types which can be This chapter provides an overview of all available config object types which can be
instantiated using the `object` keyword. instantiated using the `object` keyword.
@ -16,18 +16,18 @@ the [Icinga 2 API](12-icinga2-api.md#icinga2-api-config-objects).
type | Object type. type | Object type.
original_attributes | Original values of object attributes modified at runtime. original_attributes | Original values of object attributes modified at runtime.
active | Object is active (e.g. a service being checked). active | Object is active (e.g. a service being checked).
paused | Object has been paused at runtime (e.g. [IdoMysqlConnection](9-object-types.md#objecttype-idomysqlconnection). Defaults to `false`. paused | Object has been paused at runtime (e.g. [IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection). Defaults to `false`.
templates | Templates imported on object compilation. templates | Templates imported on object compilation.
package | [Configuration package name](12-icinga2-api.md#icinga2-api-config-management) this object belongs to. Local configuration is set to `_etc`, runtime created objects use `_api`. package | [Configuration package name](12-icinga2-api.md#icinga2-api-config-management) this object belongs to. Local configuration is set to `_etc`, runtime created objects use `_api`.
## <a id="objecttype-apilistener"></a> ApiListener ## ApiListener <a id="objecttype-apilistener"></a>
ApiListener objects are used for distributed monitoring setups ApiListener objects are used for distributed monitoring setups
and API usage specifying the certificate files used for ssl and API usage specifying the certificate files used for ssl
authorization and additional restrictions. authorization and additional restrictions.
The `NodeName` constant must be defined in [constants.conf](4-configuring-icinga-2.md#constants-conf). The `NodeName` constant must be defined in [constants.conf](04-configuring-icinga-2.md#constants-conf).
Example: Example:
@ -53,7 +53,7 @@ Configuration Attributes:
cipher\_list |**Optional.** Cipher list that is allowed. cipher\_list |**Optional.** Cipher list that is allowed.
tls\_protocolmin |**Optional.** Minimum TLS protocol version. Must be one of `TLSv1`, `TLSv1.1` or `TLSv1.2`. Defaults to `TLSv1`. tls\_protocolmin |**Optional.** Minimum TLS protocol version. Must be one of `TLSv1`, `TLSv1.1` or `TLSv1.2`. Defaults to `TLSv1`.
## <a id="objecttype-apiuser"></a> ApiUser ## ApiUser <a id="objecttype-apiuser"></a>
ApiUser objects are used for authentication against the Icinga 2 API. ApiUser objects are used for authentication against the Icinga 2 API.
@ -76,7 +76,7 @@ Configuration Attributes:
Available permissions are described in the [API permissions](12-icinga2-api.md#icinga2-api-permissions) Available permissions are described in the [API permissions](12-icinga2-api.md#icinga2-api-permissions)
chapter. chapter.
## <a id="objecttype-checkcommand"></a> CheckCommand ## CheckCommand <a id="objecttype-checkcommand"></a>
A check command definition. Additional default command custom attributes can be A check command definition. Additional default command custom attributes can be
defined here. defined here.
@ -132,7 +132,7 @@ Configuration Attributes:
arguments |**Optional.** A dictionary of command arguments. arguments |**Optional.** A dictionary of command arguments.
### <a id="objecttype-checkcommand-arguments"></a> CheckCommand Arguments ### CheckCommand Arguments <a id="objecttype-checkcommand-arguments"></a>
Command arguments can be defined as key-value-pairs in the `arguments` Command arguments can be defined as key-value-pairs in the `arguments`
dictionary. If the argument requires additional configuration, for example dictionary. If the argument requires additional configuration, for example
@ -191,7 +191,7 @@ Argument array `repeat_key = false`:
`'key' 'value[0]' 'value[1]' 'value[2]'` `'key' 'value[0]' 'value[1]' 'value[2]'`
## <a id="objecttype-checkcomponent"></a> CheckerComponent ## CheckerComponent <a id="objecttype-checkcomponent"></a>
The checker component is responsible for scheduling active checks. The checker component is responsible for scheduling active checks.
@ -209,7 +209,7 @@ Configuration Attributes:
--------------------|---------------- --------------------|----------------
concurrent\_checks |**Optional.** The maximum number of concurrent checks. Defaults to 512. concurrent\_checks |**Optional.** The maximum number of concurrent checks. Defaults to 512.
## <a id="objecttype-checkresultreader"></a> CheckResultReader ## CheckResultReader <a id="objecttype-checkresultreader"></a>
Reads Icinga 1.x check results from a directory. This functionality is provided Reads Icinga 1.x check results from a directory. This functionality is provided
to help existing Icinga 1.x users and might be useful for certain cluster to help existing Icinga 1.x users and might be useful for certain cluster
@ -229,7 +229,7 @@ Configuration Attributes:
----------------|---------------- ----------------|----------------
spool\_dir |**Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/". spool\_dir |**Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/".
## <a id="objecttype-comment"></a> Comment ## Comment <a id="objecttype-comment"></a>
Comments created at runtime are represented as objects. Comments created at runtime are represented as objects.
@ -254,7 +254,7 @@ Configuration Attributes:
expire_time | **Optional.** The comment's expire time as unix timestamp. expire_time | **Optional.** The comment's expire time as unix timestamp.
persistent | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed. persistent | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed.
## <a id="objecttype-compatlogger"></a> CompatLogger ## CompatLogger <a id="objecttype-compatlogger"></a>
Writes log files in a format that's compatible with Icinga 1.x. Writes log files in a format that's compatible with Icinga 1.x.
@ -276,7 +276,7 @@ Configuration Attributes:
## <a id="objecttype-dependency"></a> Dependency ## Dependency <a id="objecttype-dependency"></a>
Dependency objects are used to specify dependencies between hosts and services. Dependencies Dependency objects are used to specify dependencies between hosts and services. Dependencies
can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
@ -288,7 +288,7 @@ relations.
> to just create a `Dependency` template and use the `apply` keyword to assign the > to just create a `Dependency` template and use the `apply` keyword to assign the
> dependency to a number of hosts or services. Use the `to` keyword to set the specific target > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
> type for `Host` or `Service`. > type for `Host` or `Service`.
> Check the [dependencies](3-monitoring-basics.md#dependencies) chapter for detailed examples. > Check the [dependencies](03-monitoring-basics.md#dependencies) chapter for detailed examples.
Service-to-Service Example: Service-to-Service Example:
@ -339,7 +339,7 @@ Available state filters:
Up Up
Down Down
When using [apply rules](3-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be When using [apply rules](03-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be
automatically determined by Icinga 2. automatically determined by Icinga 2.
Service-to-Host Dependency Example: Service-to-Host Dependency Example:
@ -372,7 +372,7 @@ Dependency objects have composite names, i.e. their names are based on the `chil
name you specified. This means you can define more than one object with the same (short) name as long as one of the `child_host_name` and name you specified. This means you can define more than one object with the same (short) name as long as one of the `child_host_name` and
`child_service_name` attributes has a different value. `child_service_name` attributes has a different value.
## <a id="objecttype-downtime"></a> Downtime ## Downtime <a id="objecttype-downtime"></a>
Downtimes created at runtime are represented as objects. Downtimes created at runtime are represented as objects.
@ -396,7 +396,7 @@ Configuration Attributes:
end_time | **Required.** The end time as unix timestamp. end_time | **Required.** The end time as unix timestamp.
duration | **Required.** The duration as number. duration | **Required.** The duration as number.
entry_time | **Optional.** The unix timestamp when this downtime was added. entry_time | **Optional.** The unix timestamp when this downtime was added.
fixed | **Optional.** Whether the downtime is fixed (true) or flexible (false). Defaults to flexible. Details in the [advanced topics chapter](8-advanced-topics.md#fixed-flexible-downtimes). fixed | **Optional.** Whether the downtime is fixed (true) or flexible (false). Defaults to flexible. Details in the [advanced topics chapter](08-advanced-topics.md#fixed-flexible-downtimes).
triggers | **Optional.** List of downtimes which should be triggered by this downtime. triggers | **Optional.** List of downtimes which should be triggered by this downtime.
Runtime Attributes: Runtime Attributes:
@ -408,7 +408,7 @@ Runtime Attributes:
## <a id="objecttype-endpoint"></a> Endpoint ## Endpoint <a id="objecttype-endpoint"></a>
Endpoint objects are used to specify connection information for remote Endpoint objects are used to specify connection information for remote
Icinga 2 instances. Icinga 2 instances.
@ -439,7 +439,7 @@ Configuration Attributes:
Endpoint objects cannot currently be created with the API. Endpoint objects cannot currently be created with the API.
## <a id="objecttype-eventcommand"></a> EventCommand ## EventCommand <a id="objecttype-eventcommand"></a>
An event command definition. An event command definition.
@ -465,11 +465,11 @@ Configuration Attributes:
timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds. timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
arguments |**Optional.** A dictionary of command arguments. arguments |**Optional.** A dictionary of command arguments.
Command arguments can be used the same way as for [CheckCommand objects](9-object-types.md#objecttype-checkcommand-arguments). Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
More advanced examples for event command usage can be found [here](3-monitoring-basics.md#event-commands). More advanced examples for event command usage can be found [here](03-monitoring-basics.md#event-commands).
## <a id="objecttype-externalcommandlistener"></a> ExternalCommandListener ## ExternalCommandListener <a id="objecttype-externalcommandlistener"></a>
Implements the Icinga 1.x command pipe which can be used to send commands to Icinga. Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
@ -489,7 +489,7 @@ Configuration Attributes:
## <a id="objecttype-filelogger"></a> FileLogger ## FileLogger <a id="objecttype-filelogger"></a>
Specifies Icinga 2 logging to a file. Specifies Icinga 2 logging to a file.
@ -508,7 +508,7 @@ Configuration Attributes:
severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information". severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
## <a id="objecttype-gelfwriter"></a> GelfWriter ## GelfWriter <a id="objecttype-gelfwriter"></a>
Writes event log entries to a defined GELF receiver host (Graylog2, Logstash). Writes event log entries to a defined GELF receiver host (Graylog2, Logstash).
@ -531,7 +531,7 @@ Configuration Attributes:
enable_send_perfdata |**Optional.** Enable performance data for 'CHECK RESULT' events. enable_send_perfdata |**Optional.** Enable performance data for 'CHECK RESULT' events.
## <a id="objecttype-graphitewriter"></a> GraphiteWriter ## GraphiteWriter <a id="objecttype-graphitewriter"></a>
Writes check result metrics and performance data to a defined Writes check result metrics and performance data to a defined
Graphite Carbon host. Graphite Carbon host.
@ -561,7 +561,7 @@ Additional usage examples can be found [here](14-features.md#graphite-carbon-cac
## <a id="objecttype-host"></a> Host ## Host <a id="objecttype-host"></a>
A host. A host.
@ -644,7 +644,7 @@ Runtime Attributes:
## <a id="objecttype-hostgroup"></a> HostGroup ## HostGroup <a id="objecttype-hostgroup"></a>
A group of hosts. A group of hosts.
@ -665,7 +665,7 @@ Configuration Attributes:
display_name |**Optional.** A short description of the host group. display_name |**Optional.** A short description of the host group.
groups |**Optional.** An array of nested group names. groups |**Optional.** An array of nested group names.
## <a id="objecttype-icingaapplication"></a> IcingaApplication ## IcingaApplication <a id="objecttype-icingaapplication"></a>
The IcingaApplication object is required to start Icinga 2. The IcingaApplication object is required to start Icinga 2.
The object name must be `app`. If the object configuration The object name must be `app`. If the object configuration
@ -690,7 +690,7 @@ Configuration Attributes:
enable_perfdata |**Optional.** Whether performance data processing is globally enabled. Defaults to true. enable_perfdata |**Optional.** Whether performance data processing is globally enabled. Defaults to true.
vars |**Optional.** A dictionary containing custom attributes that are available globally. vars |**Optional.** A dictionary containing custom attributes that are available globally.
## <a id="objecttype-idomysqlconnection"></a> IdoMySqlConnection ## IdoMySqlConnection <a id="objecttype-idomysqlconnection"></a>
IDO database adapter for MySQL. IDO database adapter for MySQL.
@ -730,8 +730,8 @@ Configuration Attributes:
table\_prefix |**Optional.** MySQL database table prefix. Defaults to "icinga\_". table\_prefix |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default". instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
instance\_description|**Optional.** Description for the Icinga 2 instance. instance\_description|**Optional.** Description for the Icinga 2 instance.
enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](6-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to "true". enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to "true".
failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](6-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 60s. Defaults to "60s". failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
cleanup |**Optional.** Dictionary with items for historical table cleanup. cleanup |**Optional.** Dictionary with items for historical table cleanup.
categories |**Optional.** Array of information types that should be written to the database. categories |**Optional.** Array of information types that should be written to the database.
@ -780,7 +780,7 @@ by Icinga Web 2 in the table above.
In addition to the category flags listed above the `DbCatEverything` In addition to the category flags listed above the `DbCatEverything`
flag may be used as a shortcut for listing all flags. flag may be used as a shortcut for listing all flags.
## <a id="objecttype-idopgsqlconnection"></a> IdoPgSqlConnection ## IdoPgSqlConnection <a id="objecttype-idopgsqlconnection"></a>
IDO database adapter for PostgreSQL. IDO database adapter for PostgreSQL.
@ -813,8 +813,8 @@ Configuration Attributes:
table\_prefix |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_". table\_prefix |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_".
instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default". instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
instance\_description|**Optional.** Description for the Icinga 2 instance. instance\_description|**Optional.** Description for the Icinga 2 instance.
enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](6-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to "true". enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Defaults to "true".
failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](6-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 60s. Defaults to "60s". failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
cleanup |**Optional.** Dictionary with items for historical table cleanup. cleanup |**Optional.** Dictionary with items for historical table cleanup.
categories |**Optional.** Array of information types that should be written to the database. categories |**Optional.** Array of information types that should be written to the database.
@ -863,7 +863,7 @@ by Icinga Web 2 in the table above.
In addition to the category flags listed above the `DbCatEverything` In addition to the category flags listed above the `DbCatEverything`
flag may be used as a shortcut for listing all flags. flag may be used as a shortcut for listing all flags.
## <a id="objecttype-influxdbwriter"></a> InfluxdbWriter ## InfluxdbWriter <a id="objecttype-influxdbwriter"></a>
Writes check result metrics and performance data to a defined InfluxDB host. Writes check result metrics and performance data to a defined InfluxDB host.
@ -932,7 +932,7 @@ Note: If `flush_threshold` is set too low, this will always force the feature to
to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
or similar. or similar.
### <a id="objecttype-influxdbwriter-instance-tags"></a> Instance Tagging ### Instance Tagging <a id="objecttype-influxdbwriter-instance-tags"></a>
Consider the following service check: Consider the following service check:
@ -971,10 +971,10 @@ is associated with the service:
... ...
} }
## <a id="objecttype-livestatuslistener"></a> LiveStatusListener ## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
Livestatus API interface available as TCP or UNIX socket. Historical table queries Livestatus API interface available as TCP or UNIX socket. Historical table queries
require the [CompatLogger](9-object-types.md#objecttype-compatlogger) feature enabled require the [CompatLogger](09-object-types.md#objecttype-compatlogger) feature enabled
pointing to the log files using the `compat_log_path` configuration attribute. pointing to the log files using the `compat_log_path` configuration attribute.
Example: Example:
@ -1007,7 +1007,7 @@ Configuration Attributes:
> UNIX sockets are not supported on Windows. > UNIX sockets are not supported on Windows.
## <a id="objecttype-notification"></a> Notification ## Notification <a id="objecttype-notification"></a>
Notification objects are used to specify how users should be notified in case Notification objects are used to specify how users should be notified in case
of host and service state changes and other events. of host and service state changes and other events.
@ -1018,7 +1018,7 @@ of host and service state changes and other events.
> usually easier to just create a `Notification` template and use the `apply` keyword > usually easier to just create a `Notification` template and use the `apply` keyword
> to assign the notification to a number of hosts or services. Use the `to` keyword > to assign the notification to a number of hosts or services. Use the `to` keyword
> to set the specific target type for `Host` or `Service`. > to set the specific target type for `Host` or `Service`.
> Check the [notifications](3-monitoring-basics.md#alert-notifications) chapter for detailed examples. > Check the [notifications](03-monitoring-basics.md#alert-notifications) chapter for detailed examples.
Example: Example:
@ -1044,7 +1044,7 @@ Configuration Attributes:
user_groups | **Optional.** A list of user group names who should be notified. 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. 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. 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. If set to 0, [re-notifications](3-monitoring-basics.md#disable-renotification) are disabled. interval | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, [re-notifications](03-monitoring-basics.md#disable-renotification) are disabled.
period | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default. period | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
zone |**Optional.** The zone this object is a member of. zone |**Optional.** The zone this object is a member of.
types | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched. types | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
@ -1084,7 +1084,7 @@ Runtime Attributes:
last\_problem\_notification | Number | When the last notification was sent for a problem (as a UNIX timestamp). last\_problem\_notification | Number | When the last notification was sent for a problem (as a UNIX timestamp).
## <a id="objecttype-notificationcommand"></a> NotificationCommand ## NotificationCommand <a id="objecttype-notificationcommand"></a>
A notification command definition. A notification command definition.
@ -1178,11 +1178,11 @@ Configuration Attributes:
timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds. timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
arguments |**Optional.** A dictionary of command arguments. arguments |**Optional.** A dictionary of command arguments.
Command arguments can be used the same way as for [CheckCommand objects](9-object-types.md#objecttype-checkcommand-arguments). Command arguments can be used the same way as for [CheckCommand objects](09-object-types.md#objecttype-checkcommand-arguments).
More details on specific attributes can be found in [this chapter](3-monitoring-basics.md#notification-commands). More details on specific attributes can be found in [this chapter](03-monitoring-basics.md#notification-commands).
## <a id="objecttype-notificationcomponent"></a> NotificationComponent ## NotificationComponent <a id="objecttype-notificationcomponent"></a>
The notification component is responsible for sending notifications. There are no configurable options. The notification component is responsible for sending notifications. There are no configurable options.
@ -1196,9 +1196,9 @@ Configuration Attributes:
Name |Description Name |Description
----------------|---------------- ----------------|----------------
enable\_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](6-distributed-monitoring.md#distributed-monitoring-high-availability-notifications). Disabling this currently only affects reminder notifications. Defaults to "true". enable\_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](06-distributed-monitoring.md#distributed-monitoring-high-availability-notifications). Disabling this currently only affects reminder notifications. Defaults to "true".
## <a id="objecttype-opentsdbwriter"></a> OpenTsdbWriter ## OpenTsdbWriter <a id="objecttype-opentsdbwriter"></a>
Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net). Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net).
@ -1219,7 +1219,7 @@ Configuration Attributes:
port |**Optional.** OpenTSDB port. Defaults to 4242. port |**Optional.** OpenTSDB port. Defaults to 4242.
## <a id="objecttype-perfdatawriter"></a> PerfdataWriter ## PerfdataWriter <a id="objecttype-perfdatawriter"></a>
Writes check result performance data to a defined path using macro Writes check result performance data to a defined path using macro
pattern consisting of custom attributes and runtime macros. pattern consisting of custom attributes and runtime macros.
@ -1255,7 +1255,7 @@ When rotating the performance data file the current UNIX timestamp is appended t
in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename. in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
## <a id="objecttype-scheduleddowntime"></a> ScheduledDowntime ## ScheduledDowntime <a id="objecttype-scheduleddowntime"></a>
ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services. ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
@ -1265,7 +1265,7 @@ ScheduledDowntime objects can be used to set up recurring downtimes for hosts/se
> to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
> scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
> type for `Host` or `Service`. > type for `Host` or `Service`.
> Check the [recurring downtimes](8-advanced-topics.md#recurring-downtimes) example for details. > Check the [recurring downtimes](08-advanced-topics.md#recurring-downtimes) example for details.
Example: Example:
@ -1303,7 +1303,7 @@ with the same (short) name as long as one of the `host_name` and
`service_name` attributes has a different value. `service_name` attributes has a different value.
## <a id="objecttype-service"></a> Service ## Service <a id="objecttype-service"></a>
Service objects describe network services and how they should be checked Service objects describe network services and how they should be checked
by Icinga 2. by Icinga 2.
@ -1313,7 +1313,7 @@ by Icinga 2.
> Rather than creating a `Service` object for a specific host it is usually easier > Rather than creating a `Service` object for a specific host it is usually easier
> to just create a `Service` template and use the `apply` keyword to assign the > to just create a `Service` template and use the `apply` keyword to assign the
> service to a number of hosts. > service to a number of hosts.
> Check the [apply](3-monitoring-basics.md#using-apply) chapter for details. > Check the [apply](03-monitoring-basics.md#using-apply) chapter for details.
Example: Example:
@ -1399,7 +1399,7 @@ Runtime Attributes:
last_state_unknown | Number | When the last UNKNOWN state occurred (as a UNIX timestamp). last_state_unknown | Number | When the last UNKNOWN state occurred (as a UNIX timestamp).
## <a id="objecttype-servicegroup"></a> ServiceGroup ## ServiceGroup <a id="objecttype-servicegroup"></a>
A group of services. A group of services.
@ -1421,7 +1421,7 @@ Configuration Attributes:
groups |**Optional.** An array of nested group names. groups |**Optional.** An array of nested group names.
## <a id="objecttype-statusdatawriter"></a> StatusDataWriter ## StatusDataWriter <a id="objecttype-statusdatawriter"></a>
Periodically writes status data files which are used by the Classic UI and other third-party tools. Periodically writes status data files which are used by the Classic UI and other third-party tools.
@ -1444,7 +1444,7 @@ Configuration Attributes:
update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds. update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
## <a id="objecttype-sysloglogger"></a> SyslogLogger ## SyslogLogger <a id="objecttype-sysloglogger"></a>
Specifies Icinga 2 logging to syslog. Specifies Icinga 2 logging to syslog.
@ -1461,7 +1461,7 @@ Configuration Attributes:
severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning". severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning".
## <a id="objecttype-timeperiod"></a> TimePeriod ## TimePeriod <a id="objecttype-timeperiod"></a>
Time periods can be used to specify when hosts/services should be checked or to limit Time periods can be used to specify when hosts/services should be checked or to limit
when notifications should be sent out. when notifications should be sent out.
@ -1505,7 +1505,7 @@ Examples:
} }
Additional examples can be found [here](8-advanced-topics.md#timeperiods). Additional examples can be found [here](08-advanced-topics.md#timeperiods).
Configuration Attributes: Configuration Attributes:
@ -1528,7 +1528,7 @@ Runtime Attributes:
is\_inside | Boolean | Whether we're currently inside this timeperiod. is\_inside | Boolean | Whether we're currently inside this timeperiod.
## <a id="objecttype-user"></a> User ## User <a id="objecttype-user"></a>
A user. A user.
@ -1589,7 +1589,7 @@ Runtime Attributes:
--------------------------|---------------|----------------- --------------------------|---------------|-----------------
last\_notification | Number | When the last notification was sent for this user (as a UNIX timestamp). last\_notification | Number | When the last notification was sent for this user (as a UNIX timestamp).
## <a id="objecttype-usergroup"></a> UserGroup ## UserGroup <a id="objecttype-usergroup"></a>
A user group. A user group.
@ -1611,7 +1611,7 @@ Configuration Attributes:
groups |**Optional.** An array of nested group names. groups |**Optional.** An array of nested group names.
## <a id="objecttype-zone"></a> Zone ## Zone <a id="objecttype-zone"></a>
Zone objects are used to specify which Icinga 2 instances are located in a zone. Zone objects are used to specify which Icinga 2 instances are located in a zone.
@ -1637,17 +1637,17 @@ Configuration Attributes:
Zone objects cannot currently be created with the API. Zone objects cannot currently be created with the API.
# <a id="value-types"></a> Value Types # Value Types <a id="value-types"></a>
In addition to [configuration objects](9-object-types.md#object-types) Icinga 2 also uses a few other types to represent its internal state. The following types are exposed via the [API](12-icinga2-api.md#icinga2-api). In addition to [configuration objects](09-object-types.md#object-types) Icinga 2 also uses a few other types to represent its internal state. The following types are exposed via the [API](12-icinga2-api.md#icinga2-api).
## <a id="value-types-checkresult"></a> CheckResult ## CheckResult <a id="value-types-checkresult"></a>
Name | Type | Description Name | Type | Description
--------------------------|---------------|----------------- --------------------------|---------------|-----------------
exit_status | Number | The exit status returned by the check execution. exit_status | Number | The exit status returned by the check execution.
output | String | The check output. output | String | The check output.
performance_data | Array | Array of [performance data values](9-object-types.md#value-types-perfdatavalue). performance_data | Array | Array of [performance data values](09-object-types.md#value-types-perfdatavalue).
check_source | String | Name of the node executing the check. check_source | String | Name of the node executing the check.
state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN). state | Number | The current state (0 = OK, 1 = WARNING, 2 = CRITICAL, 3 = UNKNOWN).
command | Value | Array of command with shell-escaped arguments or command line string. command | Value | Array of command with shell-escaped arguments or command line string.
@ -1659,16 +1659,16 @@ In addition to [configuration objects](9-object-types.md#object-types) Icinga 2
vars_before | Dictionary | Internal attribute used for calculations. vars_before | Dictionary | Internal attribute used for calculations.
vars_after | Dictionary | Internal attribute used for calculations. vars_after | Dictionary | Internal attribute used for calculations.
## <a id="value-types-perfdatavalue"></a> PerfdataValue ## PerfdataValue <a id="value-types-perfdatavalue"></a>
Icinga 2 parses performance data strings returned by check plugins and makes the information available to external interfaces (e.g. [GraphiteWriter](9-object-types.md#objecttype-graphitewriter) or the [Icinga 2 API](12-icinga2-api.md#icinga2-api)). Icinga 2 parses performance data strings returned by check plugins and makes the information available to external interfaces (e.g. [GraphiteWriter](09-object-types.md#objecttype-graphitewriter) or the [Icinga 2 API](12-icinga2-api.md#icinga2-api)).
Name | Type | Description Name | Type | Description
--------------------------|---------------|----------------- --------------------------|---------------|-----------------
label | String | Performance data label. label | String | Performance data label.
value | Number | Normalized performance data value without unit. value | Number | Normalized performance data value without unit.
counter | Boolean | Enabled if the original value contains `c` as unit. Defaults to `false`. counter | Boolean | Enabled if the original value contains `c` as unit. Defaults to `false`.
unit | String | Unit of measurement (`seconds`, `bytes`. `percent`) according to the [plugin API](5-service-monitoring.md#service-monitoring-plugin-api). unit | String | Unit of measurement (`seconds`, `bytes`. `percent`) according to the [plugin API](05-service-monitoring.md#service-monitoring-plugin-api).
crit | Value | Critical threshold value. crit | Value | Critical threshold value.
warn | Value | Warning threshold value. warn | Value | Warning threshold value.
min | Value | Minimum value returned by the check. min | Value | Minimum value returned by the check.

680
doc/10-icinga-template-library.md
View File

File diff suppressed because it is too large Load Diff

38
doc/11-cli-commands.md
View File

@ -1,4 +1,4 @@
# <a id="cli-commands"></a> Icinga 2 CLI Commands # Icinga 2 CLI Commands <a id="cli-commands"></a>
Icinga 2 comes with a number of CLI commands which support bash autocompletion. Icinga 2 comes with a number of CLI commands which support bash autocompletion.
@ -80,7 +80,7 @@ options.
Icinga home page: <https://www.icinga.com/> Icinga home page: <https://www.icinga.com/>
## <a id="cli-commands-autocompletion"></a> Icinga 2 CLI Bash Autocompletion ## Icinga 2 CLI Bash Autocompletion <a id="cli-commands-autocompletion"></a>
Bash Auto-Completion (pressing `<TAB>`) is provided only for the corresponding context. Bash Auto-Completion (pressing `<TAB>`) is provided only for the corresponding context.
@ -111,7 +111,7 @@ into your current session and test it:
# source /etc/bash-completion.d/icinga2 # source /etc/bash-completion.d/icinga2
## <a id="cli-commands-global-options"></a> Icinga 2 CLI Global Options ## Icinga 2 CLI Global Options <a id="cli-commands-global-options"></a>
### Application Type ### Application Type
@ -129,7 +129,7 @@ Note: This is not needed by the average Icinga user, only developers.
[Global constants](17-language-reference.md#constants) can be set using the `--define` command-line option. [Global constants](17-language-reference.md#constants) can be set using the `--define` command-line option.
### <a id="config-include-path"></a> Config Include Path ### Config Include Path <a id="config-include-path"></a>
When including files you can specify that the include search path should be When including files you can specify that the include search path should be
checked. You can do this by putting your configuration file name in angle checked. You can do this by putting your configuration file name in angle
@ -145,7 +145,7 @@ Using the `--include` command-line option additional search directories can be
added. added.
## <a id="cli-command-console"></a> CLI command: Console ## CLI command: Console <a id="cli-command-console"></a>
The CLI command `console` can be used to debug and evaluate Icinga 2 config expressions, The CLI command `console` can be used to debug and evaluate Icinga 2 config expressions,
e.g. to test [functions](17-language-reference.md#functions) in your local sandbox. e.g. to test [functions](17-language-reference.md#functions) in your local sandbox.
@ -253,7 +253,7 @@ Here's an example that retrieves the command that was used by Icinga to check th
"3000,80%" "3000,80%"
] ]
## <a id="cli-command-daemon"></a> CLI command: Daemon ## CLI command: Daemon <a id="cli-command-daemon"></a>
The CLI command `daemon` provides the functionality to start/stop Icinga 2. The CLI command `daemon` provides the functionality to start/stop Icinga 2.
Furthermore it allows to run the [configuration validation](11-cli-commands.md#config-validation). Furthermore it allows to run the [configuration validation](11-cli-commands.md#config-validation).
@ -307,7 +307,7 @@ The `--validate` option can be used to check if configuration files
contain errors. If any errors are found, the exit status is 1, otherwise 0 contain errors. If any errors are found, the exit status is 1, otherwise 0
is returned. More details in the [configuration validation](11-cli-commands.md#config-validation) chapter. is returned. More details in the [configuration validation](11-cli-commands.md#config-validation) chapter.
## <a id="cli-command-feature"></a> CLI command: Feature ## CLI command: Feature <a id="cli-command-feature"></a>
The `feature enable` and `feature disable` commands can be used to enable and disable features: The `feature enable` and `feature disable` commands can be used to enable and disable features:
@ -326,7 +326,7 @@ The `feature list` command shows which features are currently enabled:
Enabled features: api checker command graphite ido-mysql mainlog notification Enabled features: api checker command graphite ido-mysql mainlog notification
## <a id="cli-command-node"></a> CLI command: Node ## CLI command: Node <a id="cli-command-node"></a>
> **Warning** > **Warning**
> >
@ -337,7 +337,7 @@ The `feature list` command shows which features are currently enabled:
> Make sure to follow the release announcements on the [Icinga website](https://www.icinga.com). > Make sure to follow the release announcements on the [Icinga website](https://www.icinga.com).
Provides the functionality to install and manage master and client Provides the functionality to install and manage master and client
nodes in a [distributed monitoring](6-distributed-monitoring.md#distributed-monitoring) scenario. nodes in a [distributed monitoring](06-distributed-monitoring.md#distributed-monitoring) scenario.
# icinga2 node --help # icinga2 node --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0) icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0)
@ -379,7 +379,7 @@ nodes in a [distributed monitoring](6-distributed-monitoring.md#distributed-moni
## <a id="cli-command-object"></a> CLI command: Object ## CLI command: Object <a id="cli-command-object"></a>
The `object` CLI command can be used to list all configuration objects and their The `object` CLI command can be used to list all configuration objects and their
attributes. The command also shows where each of the attributes was modified and as such attributes. The command also shows where each of the attributes was modified and as such
@ -419,7 +419,7 @@ More information can be found in the [troubleshooting](15-troubleshooting.md#lis
Report bugs at <https://github.com/Icinga/icinga2> Report bugs at <https://github.com/Icinga/icinga2>
Icinga home page: <https://www.icinga.com/> Icinga home page: <https://www.icinga.com/>
## <a id="cli-command-pki"></a> CLI command: Pki ## CLI command: Pki <a id="cli-command-pki"></a>
Provides the CLI commands to Provides the CLI commands to
@ -431,7 +431,7 @@ Provides the CLI commands to
* generate a new ticket for the client setup * generate a new ticket for the client setup
This functionality is used by the [node setup/wizard](11-cli-commands.md#cli-command-node) CLI commands. This functionality is used by the [node setup/wizard](11-cli-commands.md#cli-command-node) CLI commands.
You will need them in the [distributed monitoring chapter](6-distributed-monitoring.md#distributed-monitoring). You will need them in the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring).
# icinga2 pki --help # icinga2 pki --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0) icinga2 - The Icinga 2 network monitoring daemon (version: v2.6.0)
@ -464,7 +464,7 @@ You will need them in the [distributed monitoring chapter](6-distributed-monitor
Report bugs at <https://github.com/Icinga/icinga2> Report bugs at <https://github.com/Icinga/icinga2>
Icinga home page: <https://www.icinga.com/> Icinga home page: <https://www.icinga.com/>
## <a id="cli-command-repository"></a> CLI command: Repository ## CLI command: Repository <a id="cli-command-repository"></a>
> **Warning** > **Warning**
> >
@ -476,7 +476,7 @@ You will need them in the [distributed monitoring chapter](6-distributed-monitor
This command is experimental and not finished as public CLI command. Parts of its functionality This command is experimental and not finished as public CLI command. Parts of its functionality
are used in the [node update-config](11-cli-commands.md#cli-command-node) cli command. are used in the [node update-config](11-cli-commands.md#cli-command-node) cli command.
## <a id="cli-command-troubleshoot"></a> CLI command: Troubleshoot ## CLI command: Troubleshoot <a id="cli-command-troubleshoot"></a>
Collects basic information like version, paths, log files and crash reports for troubleshooting Collects basic information like version, paths, log files and crash reports for troubleshooting
purposes and prints them to a file or the console. See [troubleshooting](15-troubleshooting.md#troubleshooting-information-required). purposes and prints them to a file or the console. See [troubleshooting](15-troubleshooting.md#troubleshooting-information-required).
@ -518,7 +518,7 @@ This is only a tool to collect information to help others help you, it will not
Report bugs at <https://github.com/Icinga/icinga2> Report bugs at <https://github.com/Icinga/icinga2>
Icinga home page: <https://www.icinga.com/> Icinga home page: <https://www.icinga.com/>
## <a id="cli-command-variable"></a> CLI command: Variable ## CLI command: Variable <a id="cli-command-variable"></a>
Lists all configured variables (constants) in a similar fashion like [object list](11-cli-commands.md#cli-command-object). Lists all configured variables (constants) in a similar fashion like [object list](11-cli-commands.md#cli-command-object).
@ -549,7 +549,7 @@ Lists all configured variables (constants) in a similar fashion like [object lis
Report bugs at <https://github.com/Icinga/icinga2> Report bugs at <https://github.com/Icinga/icinga2>
Icinga home page: <https://www.icinga.com/> Icinga home page: <https://www.icinga.com/>
## <a id="enable-features"></a> Enabling/Disabling Features ## Enabling/Disabling Features <a id="enable-features"></a>
Icinga 2 provides configuration files for some commonly used features. These Icinga 2 provides configuration files for some commonly used features. These
are installed in the `/etc/icinga2/features-available` directory and can be are installed in the `/etc/icinga2/features-available` directory and can be
@ -585,7 +585,7 @@ after enabling or disabling features.
## <a id="config-validation"></a> Configuration Validation ## Configuration Validation <a id="config-validation"></a>
Once you've edited the configuration files make sure to tell Icinga 2 to validate Once you've edited the configuration files make sure to tell Icinga 2 to validate
the configuration changes. Icinga 2 will log any configuration error including the configuration changes. Icinga 2 will log any configuration error including
@ -603,7 +603,7 @@ Validate the configuration with the init script option `checkconfig`:
# /etc/init.d/icinga2 checkconfig # /etc/init.d/icinga2 checkconfig
**Note**: Using [systemd](2-getting-started.md#systemd-service) you need to manually validate the configuration using **Note**: Using [systemd](02-getting-started.md#systemd-service) you need to manually validate the configuration using
the CLI command below. the CLI command below.
# icinga2 daemon -C # icinga2 daemon -C
@ -656,7 +656,7 @@ Example filtered by `Service` objects with the name `ping*`:
## <a id="config-change-reload"></a> Reload on Configuration Changes ## Reload on Configuration Changes <a id="config-change-reload"></a>
Every time you have changed your configuration you should first tell Icinga 2 Every time you have changed your configuration you should first tell Icinga 2
to [validate](11-cli-commands.md#config-validation). If there are no validation errors, you can to [validate](11-cli-commands.md#config-validation). If there are no validation errors, you can

156
doc/12-icinga2-api.md
View File

@ -1,6 +1,6 @@
# <a id="icinga2-api"></a> Icinga 2 API # Icinga 2 API <a id="icinga2-api"></a>
## <a id="icinga2-api-setup"></a> Setting up the API ## Setting up the API <a id="icinga2-api-setup"></a>
You can run the CLI command `icinga2 api setup` to enable the You can run the CLI command `icinga2 api setup` to enable the
`api` [feature](11-cli-commands.md#enable-features) and set up `api` [feature](11-cli-commands.md#enable-features) and set up
@ -21,7 +21,7 @@ If you prefer to set up the API manually, you will have to perform the following
The next chapter provides a quick overview of how you can use the API. The next chapter provides a quick overview of how you can use the API.
## <a id="icinga2-api-introduction"></a> Introduction ## Introduction <a id="icinga2-api-introduction"></a>
The Icinga 2 API allows you to manage configuration objects The Icinga 2 API allows you to manage configuration objects
and resources in a simple, programmatic way using HTTP requests. and resources in a simple, programmatic way using HTTP requests.
@ -35,7 +35,7 @@ make calls to
* [manage configuration packages](12-icinga2-api.md#icinga2-api-config-management) * [manage configuration packages](12-icinga2-api.md#icinga2-api-config-management)
* evaluate [script expressions](12-icinga2-api.md#icinga2-api-console) * evaluate [script expressions](12-icinga2-api.md#icinga2-api-console)
### <a id="icinga2-api-requests"></a> Requests ### Requests <a id="icinga2-api-requests"></a>
Any tool capable of making HTTP requests can communicate with Any tool capable of making HTTP requests can communicate with
the API, for example [curl](https://curl.haxx.se/). the API, for example [curl](https://curl.haxx.se/).
@ -45,7 +45,7 @@ traffic remains encrypted.
By default the Icinga 2 API listens on port `5665` which is shared with By default the Icinga 2 API listens on port `5665` which is shared with
the cluster stack. The port can be changed by setting the `bind_port` attribute the cluster stack. The port can be changed by setting the `bind_port` attribute
for the [ApiListener](9-object-types.md#objecttype-apilistener) for the [ApiListener](09-object-types.md#objecttype-apilistener)
object in the `/etc/icinga2/features-available/api.conf` object in the `/etc/icinga2/features-available/api.conf`
configuration file. configuration file.
@ -64,7 +64,7 @@ All requests apart from `GET` require that the following `Accept` header is set:
Each URL is prefixed with the API version (currently "/v1"). Each URL is prefixed with the API version (currently "/v1").
### <a id="icinga2-api-responses"></a> Responses ### Responses <a id="icinga2-api-responses"></a>
Successful requests will send back a response body containing a `results` Successful requests will send back a response body containing a `results`
list. Depending on the number of affected objects in your request, the list. Depending on the number of affected objects in your request, the
@ -92,7 +92,7 @@ prefers `python -m json.tool` as Python is available nearly everywhere.
> should gracefully handle fields it is not familiar with, for example by > should gracefully handle fields it is not familiar with, for example by
> ignoring them. > ignoring them.
### <a id="icinga2-api-http-statuses"></a> HTTP Statuses ### HTTP Statuses <a id="icinga2-api-http-statuses"></a>
The API will return standard [HTTP statuses](https://www.ietf.org/rfc/rfc2616.txt) The API will return standard [HTTP statuses](https://www.ietf.org/rfc/rfc2616.txt)
including error codes. including error codes.
@ -111,14 +111,14 @@ was malformed.
A status in the range of 500 generally means that there was a server-side problem A status in the range of 500 generally means that there was a server-side problem
and Icinga 2 is unable to process your request. and Icinga 2 is unable to process your request.
### <a id="icinga2-api-authentication"></a> Authentication ### Authentication <a id="icinga2-api-authentication"></a>
There are two different ways for authenticating against the Icinga 2 API: There are two different ways for authenticating against the Icinga 2 API:
* username and password using HTTP basic auth * username and password using HTTP basic auth
* X.509 certificate * X.509 certificate
In order to configure a new API user you'll need to add a new [ApiUser](9-object-types.md#objecttype-apiuser) In order to configure a new API user you'll need to add a new [ApiUser](09-object-types.md#objecttype-apiuser)
configuration object. In this example `root` will be the basic auth username configuration object. In this example `root` will be the basic auth username
and the `password` attribute contains the basic auth password. and the `password` attribute contains the basic auth password.
@ -130,7 +130,7 @@ and the `password` attribute contains the basic auth password.
Alternatively you can use X.509 client certificates by specifying the `client_cn` Alternatively you can use X.509 client certificates by specifying the `client_cn`
the API should trust. The X.509 certificate has to be signed by the CA certificate the API should trust. The X.509 certificate has to be signed by the CA certificate
that is configured in the [ApiListener](9-object-types.md#objecttype-apilistener) object. that is configured in the [ApiListener](09-object-types.md#objecttype-apilistener) object.
# vim /etc/icinga2/conf.d/api-users.conf # vim /etc/icinga2/conf.d/api-users.conf
@ -162,7 +162,7 @@ specify the trusted CA certificate using the curl parameter`--cacert`:
Read the next chapter on [API permissions](12-icinga2-api.md#icinga2-api-permissions) Read the next chapter on [API permissions](12-icinga2-api.md#icinga2-api-permissions)
in order to configure authorization settings for your newly created API user. in order to configure authorization settings for your newly created API user.
### <a id="icinga2-api-permissions"></a> Permissions ### Permissions <a id="icinga2-api-permissions"></a>
By default an API user does not have any permissions to perform By default an API user does not have any permissions to perform
actions on the URL endpoints. actions on the URL endpoints.
@ -221,7 +221,7 @@ Available permissions for specific URL endpoints:
The required actions or types can be replaced by using a wildcard match ("\*"). The required actions or types can be replaced by using a wildcard match ("\*").
### <a id="icinga2-api-parameters"></a> Parameters ### Parameters <a id="icinga2-api-parameters"></a>
Depending on the request method there are two ways of Depending on the request method there are two ways of
passing parameters to the request: passing parameters to the request:
@ -243,7 +243,7 @@ Here are the exact same query parameters as a JSON object:
The [match function](18-library-reference.md#global-functions-match) is available as global function The [match function](18-library-reference.md#global-functions-match) is available as global function
in Icinga 2. in Icinga 2.
### <a id="icinga2-api-requests-method-override"></a> Request Method Override ### Request Method Override <a id="icinga2-api-requests-method-override"></a>
`GET` requests do not allow you to send a request body. In case you cannot pass everything as URL `GET` requests do not allow you to send a request body. In case you cannot pass everything as URL
parameters (e.g. complex filters or JSON-encoded dictionaries) you can use the `X-HTTP-Method-Override` parameters (e.g. complex filters or JSON-encoded dictionaries) you can use the `X-HTTP-Method-Override`
@ -257,9 +257,9 @@ Delete an existing object by sending a `POST` request with `X-HTTP-Method-Overri
$ curl -k -s -u 'root:icinga' -H 'Accept: application/json' -X POST -H 'X-HTTP-Method-Override: DELETE' 'https://localhost:5665/v1/objects/hosts/example.localdomain' $ curl -k -s -u 'root:icinga' -H 'Accept: application/json' -X POST -H 'X-HTTP-Method-Override: DELETE' 'https://localhost:5665/v1/objects/hosts/example.localdomain'
### <a id="icinga2-api-filters"></a> Filters ### Filters <a id="icinga2-api-filters"></a>
#### <a id="icinga2-api-simple-filters"></a> Simple Filters #### Simple Filters <a id="icinga2-api-simple-filters"></a>
By default actions and queries operate on all objects unless further restricted by the user. For By default actions and queries operate on all objects unless further restricted by the user. For
example, the following query returns all `Host` objects: example, the following query returns all `Host` objects:
@ -287,12 +287,12 @@ full name has to be used:
The full name of an object can be obtained by looking at the `__name` attribute. The full name of an object can be obtained by looking at the `__name` attribute.
#### <a id="icinga2-api-advanced-filters"></a> Advanced Filters #### Advanced Filters <a id="icinga2-api-advanced-filters"></a>
Most of the information provided in this chapter applies to both permission filters (as used when Most of the information provided in this chapter applies to both permission filters (as used when
configuring `ApiUser` objects) and filters specified in queries. configuring `ApiUser` objects) and filters specified in queries.
Advanced filters allow users to filter objects using lambda expressions. The syntax for these filters is the same like for [apply rule expressions](3-monitoring-basics.md#using-apply-expressions). Advanced filters allow users to filter objects using lambda expressions. The syntax for these filters is the same like for [apply rule expressions](03-monitoring-basics.md#using-apply-expressions).
> **Note** > **Note**
> >
@ -351,7 +351,7 @@ the HTTP specification does not allow message bodies for GET requests.
The `filters_vars` attribute can only be used inside the request body, but not as The `filters_vars` attribute can only be used inside the request body, but not as
a URL parameter because there is no way to specify a dictionary in a URL. a URL parameter because there is no way to specify a dictionary in a URL.
## <a id="icinga2-api-config-objects"></a> Config Objects ## Config Objects <a id="icinga2-api-config-objects"></a>
Provides methods to manage configuration objects: Provides methods to manage configuration objects:
@ -360,7 +360,7 @@ Provides methods to manage configuration objects:
* [modifying objects](12-icinga2-api.md#icinga2-api-config-objects-modify) * [modifying objects](12-icinga2-api.md#icinga2-api-config-objects-modify)
* [deleting objects](12-icinga2-api.md#icinga2-api-config-objects-delete) * [deleting objects](12-icinga2-api.md#icinga2-api-config-objects-delete)
### <a id="icinga2-api-config-objects-cluster-sync"></a> API Objects and Cluster Config Sync ### API Objects and Cluster Config Sync <a id="icinga2-api-config-objects-cluster-sync"></a>
Newly created or updated objects can be synced throughout your Newly created or updated objects can be synced throughout your
Icinga 2 cluster. Set the `zone` attribute to the zone this object Icinga 2 cluster. Set the `zone` attribute to the zone this object
@ -372,14 +372,14 @@ Objects without a zone attribute are only synced in the same zone the Icinga ins
> >
> Cluster nodes must accept configuration for creating, modifying > Cluster nodes must accept configuration for creating, modifying
> and deleting objects. Ensure that `accept_config` is set to `true` > and deleting objects. Ensure that `accept_config` is set to `true`
> in the [ApiListener](9-object-types.md#objecttype-apilistener) object > in the [ApiListener](09-object-types.md#objecttype-apilistener) object
> on each node. > on each node.
If you add a new cluster instance, or reconnect an instance which has been offline If you add a new cluster instance, or reconnect an instance which has been offline
for a while, Icinga 2 takes care of the initial object sync for all objects for a while, Icinga 2 takes care of the initial object sync for all objects
created by the API. created by the API.
### <a id="icinga2-api-config-objects-query"></a> Querying Objects ### Querying Objects <a id="icinga2-api-config-objects-query"></a>
You can request information about configuration objects by sending You can request information about configuration objects by sending
a `GET` query to the `/v1/objects/<type>` URL endpoint. `<type` has a `GET` query to the `/v1/objects/<type>` URL endpoint. `<type` has
@ -389,7 +389,7 @@ in:
$ curl -k -s -u root:icinga 'https://localhost:5665/v1/objects/hosts' $ curl -k -s -u root:icinga 'https://localhost:5665/v1/objects/hosts'
A list of all available configuration types is available in the A list of all available configuration types is available in the
[object types](9-object-types.md#object-types) chapter. [object types](09-object-types.md#object-types) chapter.
The following URL parameters are available: The following URL parameters are available:
@ -425,7 +425,7 @@ You can limit the output to specific attributes using the `attrs` URL parameter:
] ]
} }
#### <a id="icinga2-api-config-objects-query-result"></a> Object Queries Result #### Object Queries Result <a id="icinga2-api-config-objects-query-result"></a>
Each response entry in the results array contains the following attributes: Each response entry in the results array contains the following attributes:
@ -437,7 +437,7 @@ Each response entry in the results array contains the following attributes:
joins | dictionary | [Joined object types](12-icinga2-api.md#icinga2-api-config-objects-query-joins) as key, attributes as nested dictionary. Disabled by default. joins | dictionary | [Joined object types](12-icinga2-api.md#icinga2-api-config-objects-query-joins) as key, attributes as nested dictionary. Disabled by default.
meta | dictionary | Contains `used_by` object references. Disabled by default, enable it using `?meta=used_by` as URL parameter. meta | dictionary | Contains `used_by` object references. Disabled by default, enable it using `?meta=used_by` as URL parameter.
#### <a id="icinga2-api-config-objects-query-joins"></a> Object Query Joins #### Object Query Joins <a id="icinga2-api-config-objects-query-joins"></a>
Icinga 2 knows about object relations. For example it can optionally return Icinga 2 knows about object relations. For example it can optionally return
information about the host when querying service objects. information about the host when querying service objects.
@ -514,7 +514,7 @@ via a join:
] ]
} }
In case you want to fetch all [comments](9-object-types.md#objecttype-comment) In case you want to fetch all [comments](09-object-types.md#objecttype-comment)
for hosts and services, you can use the following query URL (similar example for hosts and services, you can use the following query URL (similar example
for downtimes): for downtimes):
@ -577,7 +577,7 @@ method:
] ]
} }
### <a id="icinga2-api-config-objects-create"></a> Creating Config Objects ### Creating Config Objects <a id="icinga2-api-config-objects-create"></a>
New objects must be created by sending a PUT request. The following New objects must be created by sending a PUT request. The following
parameters need to be passed inside the JSON body: parameters need to be passed inside the JSON body:
@ -585,7 +585,7 @@ parameters need to be passed inside the JSON body:
Parameters | Type | Description Parameters | Type | Description
-----------|--------------|-------------------------- -----------|--------------|--------------------------
templates | string array | **Optional.** Import existing configuration templates for this object type. Note: These templates must either be statically configured or provided in [config packages](12-icinga2-api.md#icinga2-api-config-management)- templates | string array | **Optional.** Import existing configuration templates for this object type. Note: These templates must either be statically configured or provided in [config packages](12-icinga2-api.md#icinga2-api-config-management)-
attrs | dictionary | **Required.** Set specific object attributes for this [object type](9-object-types.md#object-types). attrs | dictionary | **Required.** Set specific object attributes for this [object type](09-object-types.md#object-types).
The object name must be specified as part of the URL path. For objects with composite names (e.g. services) The object name must be specified as part of the URL path. For objects with composite names (e.g. services)
the full name (e.g. `example.localdomain!http`) must be specified. the full name (e.g. `example.localdomain!http`) must be specified.
@ -639,21 +639,21 @@ Example for a new CheckCommand object:
-d '{ "templates": [ "plugin-check-command" ], "attrs": { "command": [ "/usr/local/sbin/check_http" ], "arguments": { "-I": "$mytest_iparam$" } } }' -d '{ "templates": [ "plugin-check-command" ], "attrs": { "command": [ "/usr/local/sbin/check_http" ], "arguments": { "-I": "$mytest_iparam$" } } }'
### <a id="icinga2-api-config-objects-modify"></a> Modifying Objects ### Modifying Objects <a id="icinga2-api-config-objects-modify"></a>
Existing objects must be modified by sending a `POST` request. The following Existing objects must be modified by sending a `POST` request. The following
parameters need to be passed inside the JSON body: parameters need to be passed inside the JSON body:
Parameters | Type | Description Parameters | Type | Description
-----------|------------|--------------------------- -----------|------------|---------------------------
attrs | dictionary | **Required.** Set specific object attributes for this [object type](9-object-types.md#object-types). attrs | dictionary | **Required.** Set specific object attributes for this [object type](09-object-types.md#object-types).
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) should be provided. In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) should be provided.
> **Note**: > **Note**:
> >
> Modified attributes do not trigger a re-evaluation of existing > Modified attributes do not trigger a re-evaluation of existing
> static [apply rules](3-monitoring-basics.md#using-apply) and [group assignments](3-monitoring-basics.md#group-assign-intro). > static [apply rules](03-monitoring-basics.md#using-apply) and [group assignments](03-monitoring-basics.md#group-assign-intro).
> Delete and re-create the objects if you require such changes. > Delete and re-create the objects if you require such changes.
> >
> Furthermore you cannot modify templates which have already been resolved > Furthermore you cannot modify templates which have already been resolved
@ -682,7 +682,7 @@ The following example updates the `address` attribute and the custom attribute `
} }
### <a id="icinga2-api-config-objects-delete"></a> Deleting Objects ### Deleting Objects <a id="icinga2-api-config-objects-delete"></a>
You can delete objects created using the API by sending a `DELETE` You can delete objects created using the API by sending a `DELETE`
request. request.
@ -707,7 +707,7 @@ Example for deleting the host object `example.localdomain`:
] ]
} }
## <a id="icinga2-api-config-templates"></a> Config Templates ## Config Templates <a id="icinga2-api-config-templates"></a>
Provides methods to manage configuration templates: Provides methods to manage configuration templates:
@ -715,7 +715,7 @@ Provides methods to manage configuration templates:
Creation, modification and deletion of templates at runtime is not supported. Creation, modification and deletion of templates at runtime is not supported.
### <a id="icinga2-api-config-templates-query"></a> Querying Templates ### Querying Templates <a id="icinga2-api-config-templates-query"></a>
You can request information about configuration templates by sending You can request information about configuration templates by sending
a `GET` query to the `/v1/templates/<type>` URL endpoint. `<type` has a `GET` query to the `/v1/templates/<type>` URL endpoint. `<type` has
@ -725,7 +725,7 @@ in:
$ curl -k -s -u root:icinga 'https://localhost:5665/v1/templates/hosts' $ curl -k -s -u root:icinga 'https://localhost:5665/v1/templates/hosts'
A list of all available configuration types is available in the A list of all available configuration types is available in the
[object types](9-object-types.md#object-types) chapter. [object types](09-object-types.md#object-types) chapter.
A [filter](12-icinga2-api.md#icinga2-api-filters) may be provided for this query type. The A [filter](12-icinga2-api.md#icinga2-api-filters) may be provided for this query type. The
template object can be accessed in the filter using the `tmpl` variable. In this template object can be accessed in the filter using the `tmpl` variable. In this
@ -744,13 +744,13 @@ URL path when querying a single object:
The result set contains the type, name as well as the location of the template. The result set contains the type, name as well as the location of the template.
## <a id="icinga2-api-variables"></a> Variables ## Variables <a id="icinga2-api-variables"></a>
Provides methods to manage global variables: Provides methods to manage global variables:
* [querying variables](12-icinga2-api.md#icinga2-api-variables-query) * [querying variables](12-icinga2-api.md#icinga2-api-variables-query)
### <a id="icinga2-api-variables-query"></a> Querying Variables ### Querying Variables <a id="icinga2-api-variables-query"></a>
You can request information about global variables by sending You can request information about global variables by sending
a `GET` query to the `/v1/variables/` URL endpoint: a `GET` query to the `/v1/variables/` URL endpoint:
@ -772,7 +772,7 @@ URL path when querying a single variable:
The result set contains the type, name and value of the global variable. The result set contains the type, name and value of the global variable.
## <a id="icinga2-api-actions"></a> Actions ## Actions <a id="icinga2-api-actions"></a>
There are several actions available for Icinga 2 provided by the `/v1/actions` There are several actions available for Icinga 2 provided by the `/v1/actions`
URL endpoint. You can run actions by sending a `POST` request. URL endpoint. You can run actions by sending a `POST` request.
@ -792,7 +792,7 @@ called `app`.
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/objects/icingaapplications/app' -d '{ "attrs": { "enable_notifications": false } }' $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/objects/icingaapplications/app' -d '{ "attrs": { "enable_notifications": false } }'
### <a id="icinga2-api-actions-process-check-result"></a> process-check-result ### process-check-result <a id="icinga2-api-actions-process-check-result"></a>
Process a check result for a host or a service. Process a check result for a host or a service.
@ -829,7 +829,7 @@ Example for using the `Host` type and filter by the host name:
You can avoid URL encoding of white spaces in object names by using the `filter` attribute in the request body. You can avoid URL encoding of white spaces in object names by using the `filter` attribute in the request body.
### <a id="icinga2-api-actions-reschedule-check"></a> reschedule-check ### reschedule-check <a id="icinga2-api-actions-reschedule-check"></a>
Reschedule a check for hosts and services. The check can be forced if required. Reschedule a check for hosts and services. The check can be forced if required.
@ -859,7 +859,7 @@ allowed for the service (`force_check=true`).
} }
### <a id="icinga2-api-actions-send-custom-notification"></a> send-custom-notification ### send-custom-notification <a id="icinga2-api-actions-send-custom-notification"></a>
Send a custom notification for hosts and services. This notification Send a custom notification for hosts and services. This notification
type can be forced being sent to all users. type can be forced being sent to all users.
@ -892,7 +892,7 @@ host owners:
} }
} }
### <a id="icinga2-api-actions-delay-notification"></a> delay-notification ### delay-notification <a id="icinga2-api-actions-delay-notification"></a>
Delay notifications for a host or a service. Delay notifications for a host or a service.
Note that this will only have an effect if the service stays in the same problem Note that this will only have an effect if the service stays in the same problem
@ -924,7 +924,7 @@ Example:
} }
} }
### <a id="icinga2-api-actions-acknowledge-problem"></a> acknowledge-problem ### acknowledge-problem <a id="icinga2-api-actions-acknowledge-problem"></a>
Allows you to acknowledge the current problem for hosts or services. By Allows you to acknowledge the current problem for hosts or services. By
acknowledging the current problem, future notifications (for the same state if `sticky` is set to `false`) acknowledging the current problem, future notifications (for the same state if `sticky` is set to `false`)
@ -962,7 +962,7 @@ a notification for them:
} }
### <a id="icinga2-api-actions-remove-acknowledgement"></a> remove-acknowledgement ### remove-acknowledgement <a id="icinga2-api-actions-remove-acknowledgement"></a>
Removes the acknowledgements for services or hosts. Once the acknowledgement has Removes the acknowledgements for services or hosts. Once the acknowledgement has
been removed notifications will be sent out again. been removed notifications will be sent out again.
@ -987,7 +987,7 @@ The example removes all service acknowledgements:
} }
} }
### <a id="icinga2-api-actions-add-comment"></a> add-comment ### add-comment <a id="icinga2-api-actions-add-comment"></a>
Adds a `comment` from an `author` to services or hosts. Adds a `comment` from an `author` to services or hosts.
@ -1020,7 +1020,7 @@ The following example adds a comment for all `ping4` services:
] ]
} }
### <a id="icinga2-api-actions-remove-comment"></a> remove-comment ### remove-comment <a id="icinga2-api-actions-remove-comment"></a>
Remove the comment using its `name` attribute , returns `OK` if the Remove the comment using its `name` attribute , returns `OK` if the
comment did not exist. comment did not exist.
@ -1060,7 +1060,7 @@ Example for removing all service comments using a service name filter for `ping4
} }
### <a id="icinga2-api-actions-schedule-downtime"></a> schedule-downtime ### schedule-downtime <a id="icinga2-api-actions-schedule-downtime"></a>
Schedule a downtime for hosts and services. Schedule a downtime for hosts and services.
@ -1072,9 +1072,9 @@ Send a `POST` request to the URL endpoint `/v1/actions/schedule-downtime`.
comment | string | **Required.** Comment text. comment | string | **Required.** Comment text.
start\_time | timestamp | **Required.** Timestamp marking the beginning of the downtime. start\_time | timestamp | **Required.** Timestamp marking the beginning of the downtime.
end\_time | timestamp | **Required.** Timestamp marking the end of the downtime. end\_time | timestamp | **Required.** Timestamp marking the end of the downtime.
fixed | boolean | **Optional.** Defaults to `true`. If true, the downtime is `fixed` otherwise `flexible`. See [downtimes](8-advanced-topics.md#downtimes) for more information. fixed | boolean | **Optional.** Defaults to `true`. If true, the downtime is `fixed` otherwise `flexible`. See [downtimes](08-advanced-topics.md#downtimes) for more information.
duration | integer | **Required for flexible downtimes.** Duration of the downtime in seconds if `fixed` is set to false. duration | integer | **Required for flexible downtimes.** Duration of the downtime in seconds if `fixed` is set to false.
trigger\_name | string | **Optional.** Sets the trigger for a triggered downtime. See [downtimes](8-advanced-topics.md#downtimes) for more information on triggered downtimes. trigger\_name | string | **Optional.** Sets the trigger for a triggered downtime. See [downtimes](08-advanced-topics.md#downtimes) for more information on triggered downtimes.
child\_options | integer | **Optional.** Schedule child downtimes. `0` does not do anything, `1` schedules child downtimes triggered by this downtime, `2` schedules non-triggered downtimes. Defaults to `0`. child\_options | integer | **Optional.** Schedule child downtimes. `0` does not do anything, `1` schedules child downtimes triggered by this downtime, `2` schedules non-triggered downtimes. Defaults to `0`.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`. In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
@ -1099,7 +1099,7 @@ Example:
] ]
} }
### <a id="icinga2-api-actions-remove-downtime"></a> remove-downtime ### remove-downtime <a id="icinga2-api-actions-remove-downtime"></a>
Remove the downtime using its `name` attribute , returns `OK` if the Remove the downtime using its `name` attribute , returns `OK` if the
downtime did not exist. downtime did not exist.
@ -1156,7 +1156,7 @@ filter variables explained in the [advanced filters](12-icinga2-api.md#icinga2-a
] ]
} }
### <a id="icinga2-api-actions-shutdown-process"></a> shutdown-process ### shutdown-process <a id="icinga2-api-actions-shutdown-process"></a>
Shuts down Icinga2. May or may not return. Shuts down Icinga2. May or may not return.
@ -1177,7 +1177,7 @@ Example:
] ]
} }
### <a id="icinga2-api-actions-restart-process"></a> restart-process ### restart-process <a id="icinga2-api-actions-restart-process"></a>
Restarts Icinga2. May or may not return. Restarts Icinga2. May or may not return.
@ -1198,9 +1198,9 @@ Example:
] ]
} }
### <a id="icinga2-api-actions-generate-ticket"></a> generate-ticket ### generate-ticket <a id="icinga2-api-actions-generate-ticket"></a>
Generates a PKI ticket for [CSR auto-signing](6-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing). Generates a PKI ticket for [CSR auto-signing](06-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing).
This can be used in combination with satellite/client setups requesting this ticket number. This can be used in combination with satellite/client setups requesting this ticket number.
Send a `POST` request to the URL endpoint `/v1/actions/generate-ticket`. Send a `POST` request to the URL endpoint `/v1/actions/generate-ticket`.
@ -1224,7 +1224,7 @@ Example:
} }
## <a id="icinga2-api-event-streams"></a> Event Streams ## Event Streams <a id="icinga2-api-event-streams"></a>
You can subscribe to event streams by sending a `POST` request to the URL endpoint `/v1/events`. You can subscribe to event streams by sending a `POST` request to the URL endpoint `/v1/events`.
The following parameters need to be specified (either as URL parameters or in a JSON-encoded message body): The following parameters need to be specified (either as URL parameters or in a JSON-encoded message body):
@ -1235,7 +1235,7 @@ The following parameters need to be specified (either as URL parameters or in a
queue | string | **Required.** Unique queue name. Multiple HTTP clients can use the same queue as long as they use the same event types and filter. queue | string | **Required.** Unique queue name. Multiple HTTP clients can use the same queue as long as they use the same event types and filter.
filter | string | **Optional.** Filter for specific event attributes using [filter expressions](12-icinga2-api.md#icinga2-api-filters). filter | string | **Optional.** Filter for specific event attributes using [filter expressions](12-icinga2-api.md#icinga2-api-filters).
### <a id="icinga2-api-event-streams-types"></a> Event Stream Types ### Event Stream Types <a id="icinga2-api-event-streams-types"></a>
The following event stream types are available: The following event stream types are available:
@ -1261,7 +1261,7 @@ Example for all downtime events:
&types=DowntimeAdded&types=DowntimeRemoved&types=DowntimeTriggered &types=DowntimeAdded&types=DowntimeRemoved&types=DowntimeTriggered
### <a id="icinga2-api-event-streams-filter"></a> Event Stream Filter ### Event Stream Filter <a id="icinga2-api-event-streams-filter"></a>
Event streams can be filtered by attributes using the prefix `event.`. Event streams can be filtered by attributes using the prefix `event.`.
@ -1275,7 +1275,7 @@ the string pattern "random\*":
&types=CheckResult&filter=match%28%22random*%22,event.service%29 &types=CheckResult&filter=match%28%22random*%22,event.service%29
### <a id="icinga2-api-event-streams-response"></a> Event Stream Response ### Event Stream Response <a id="icinga2-api-event-streams-response"></a>
The event stream response is separated with new lines. The HTTP client The event stream response is separated with new lines. The HTTP client
must support long-polling and HTTP/1.1. HTTP/1.0 is not supported. must support long-polling and HTTP/1.1. HTTP/1.0 is not supported.
@ -1289,7 +1289,7 @@ Example:
{"check_result":{ ... },"host":"example.localdomain","service":"ping4","timestamp":1445421329.7226390839,"type":"CheckResult"} {"check_result":{ ... },"host":"example.localdomain","service":"ping4","timestamp":1445421329.7226390839,"type":"CheckResult"}
## <a id="icinga2-api-status"></a> Status and Statistics ## Status and Statistics <a id="icinga2-api-status"></a>
Send a `GET` request to the URL endpoint `/v1/status` to retrieve status information and statistics for Icinga 2. Send a `GET` request to the URL endpoint `/v1/status` to retrieve status information and statistics for Icinga 2.
@ -1341,7 +1341,7 @@ You can limit the output by specifying a status type in the URL, e.g. `IcingaApp
} }
## <a id="icinga2-api-config-management"></a> Configuration Management ## Configuration Management <a id="icinga2-api-config-management"></a>
The main idea behind configuration management is to allow external applications The main idea behind configuration management is to allow external applications
creating configuration packages and stages based on configuration files and creating configuration packages and stages based on configuration files and
@ -1352,7 +1352,7 @@ validate the configuration asynchronously and populate a status log which
can be fetched in a separated request. can be fetched in a separated request.
### <a id="icinga2-api-config-management-create-package"></a> Creating a Config Package ### Creating a Config Package <a id="icinga2-api-config-management-create-package"></a>
Send a `POST` request to a new config package called `example-cmdb` in this example. This Send a `POST` request to a new config package called `example-cmdb` in this example. This
will create a new empty configuration package. will create a new empty configuration package.
@ -1371,7 +1371,7 @@ will create a new empty configuration package.
Package names starting with an underscore are reserved for internal packages and must not be used. Package names starting with an underscore are reserved for internal packages and must not be used.
### <a id="icinga2-api-config-management-create-config-stage"></a> Uploading configuration for a Config Package ### Uploading configuration for a Config Package <a id="icinga2-api-config-management-create-config-stage"></a>
Configuration files in packages are managed in stages. Configuration files in packages are managed in stages.
Stages provide a way to maintain multiple configuration versions for a package. Stages provide a way to maintain multiple configuration versions for a package.
@ -1386,7 +1386,7 @@ The file path requires one of these two directories inside its path:
Directory | Description Directory | Description
------------|------------------------------------ ------------|------------------------------------
conf.d | Local configuration directory. conf.d | Local configuration directory.
zones.d | Configuration directory for cluster zones, each zone must be put into its own zone directory underneath. Supports the [cluster config sync](6-distributed-monitoring.md#distributed-monitoring-top-down-config-sync). zones.d | Configuration directory for cluster zones, each zone must be put into its own zone directory underneath. Supports the [cluster config sync](06-distributed-monitoring.md#distributed-monitoring-top-down-config-sync).
Example for a local configuration in the `conf.d` directory: Example for a local configuration in the `conf.d` directory:
@ -1438,7 +1438,7 @@ You can [fetch these files](12-icinga2-api.md#icinga2-api-config-management-fetc
in order to verify that the new configuration was deployed successfully. in order to verify that the new configuration was deployed successfully.
### <a id="icinga2-api-config-management-list-config-packages"></a> List Configuration Packages and their Stages ### List Configuration Packages and their Stages <a id="icinga2-api-config-management-list-config-packages"></a>
A list of packages and their stages can be retrieved by sending a `GET` request to the URL endpoint `/v1/config/packages`. A list of packages and their stages can be retrieved by sending a `GET` request to the URL endpoint `/v1/config/packages`.
@ -1459,7 +1459,7 @@ have an active stage.
} }
### <a id="icinga2-api-config-management-list-config-package-stage-files"></a> List Configuration Packages and their Stages ### List Configuration Packages and their Stages <a id="icinga2-api-config-management-list-config-package-stage-files"></a>
In order to retrieve a list of files for a stage you can send a `GET` request to In order to retrieve a list of files for a stage you can send a `GET` request to
the URL endpoint `/v1/config/stages`. You need to include the URL endpoint `/v1/config/stages`. You need to include
@ -1492,7 +1492,7 @@ the package name (`example-cmdb`) and stage name (`example.localdomain-144162583
] ]
} }
### <a id="icinga2-api-config-management-fetch-config-package-stage-files"></a> Fetch Configuration Package Stage Files ### Fetch Configuration Package Stage Files <a id="icinga2-api-config-management-fetch-config-package-stage-files"></a>
Send a `GET` request to the URL endpoint `/v1/config/files` and add Send a `GET` request to the URL endpoint `/v1/config/files` and add
the package name, the stage name and the relative path to the file to the URL path. the package name, the stage name and the relative path to the file to the URL path.
@ -1510,7 +1510,7 @@ The following example fetches the configuration file `conf.d/test.conf`:
You can fetch a [list of existing files](12-icinga2-api.md#icinga2-api-config-management-list-config-package-stage-files) You can fetch a [list of existing files](12-icinga2-api.md#icinga2-api-config-management-list-config-package-stage-files)
in a configuration stage and then specifically request their content. in a configuration stage and then specifically request their content.
### <a id="icinga2-api-config-management-config-package-stage-errors"></a> Configuration Package Stage Errors ### Configuration Package Stage Errors <a id="icinga2-api-config-management-config-package-stage-errors"></a>
Now that we don't have an active stage for `example-cmdb` yet seen [here](12-icinga2-api.md#icinga2-api-config-management-list-config-packages), Now that we don't have an active stage for `example-cmdb` yet seen [here](12-icinga2-api.md#icinga2-api-config-management-list-config-packages),
there must have been an error. there must have been an error.
@ -1536,7 +1536,7 @@ The output is similar to the manual [configuration validation](11-cli-commands.m
> The returned output is plain-text instead of JSON-encoded. > The returned output is plain-text instead of JSON-encoded.
### <a id="icinga2-api-config-management-delete-config-stage"></a> Deleting Configuration Package Stage ### Deleting Configuration Package Stage <a id="icinga2-api-config-management-delete-config-stage"></a>
You can send a `DELETE` request to the URL endpoint `/v1/config/stages` You can send a `DELETE` request to the URL endpoint `/v1/config/stages`
in order to purge a configuration stage. You must include the package and in order to purge a configuration stage. You must include the package and
@ -1557,7 +1557,7 @@ in the `example-cmdb` configuration package:
} }
### <a id="icinga2-api-config-management-delete-config-package"></a> Deleting Configuration Package ### Deleting Configuration Package <a id="icinga2-api-config-management-delete-config-package"></a>
In order to completely purge a configuration package and its stages In order to completely purge a configuration package and its stages
you can send a `DELETE` request to the URL endpoint `/v1/config/packages` you can send a `DELETE` request to the URL endpoint `/v1/config/packages`
@ -1578,7 +1578,7 @@ This example entirely deletes the configuration package `example-cmdb`:
} }
## <a id="icinga2-api-types"></a> Types ## Types <a id="icinga2-api-types"></a>
You can retrieve the configuration object types by sending a `GET` request to URL You can retrieve the configuration object types by sending a `GET` request to URL
endpoint `/v1/types`. endpoint `/v1/types`.
@ -1628,7 +1628,7 @@ In order to view a specific configuration object type specify its name inside th
} }
## <a id="icinga2-api-console"></a> Console ## Console <a id="icinga2-api-console"></a>
You can inspect variables and execute other expressions by sending a `POST` request to the URL endpoint `/v1/console/execute-script`. You can inspect variables and execute other expressions by sending a `POST` request to the URL endpoint `/v1/console/execute-script`.
In order to receive auto-completion suggestions, send a `POST` request to the URL endpoint `/v1/console/auto-complete-script`. In order to receive auto-completion suggestions, send a `POST` request to the URL endpoint `/v1/console/auto-complete-script`.
@ -1696,7 +1696,7 @@ similar fashion when pressing TAB inside the [console CLI command](11-cli-comman
} }
## <a id="icinga2-api-clients"></a> API Clients ## API Clients <a id="icinga2-api-clients"></a>
There are a couple of existing clients which can be used with the Icinga 2 API: There are a couple of existing clients which can be used with the Icinga 2 API:
@ -1713,7 +1713,7 @@ Demo cases:
Additional [programmatic examples](12-icinga2-api.md#icinga2-api-clients-programmatic-examples) Additional [programmatic examples](12-icinga2-api.md#icinga2-api-clients-programmatic-examples)
will help you getting started using the Icinga 2 API in your environment. will help you getting started using the Icinga 2 API in your environment.
### <a id="icinga2-api-clients-icinga-studio"></a> Icinga Studio ### Icinga Studio <a id="icinga2-api-clients-icinga-studio"></a>
Icinga Studio is a graphical application to query configuration objects provided by the API. Icinga Studio is a graphical application to query configuration objects provided by the API.
@ -1730,13 +1730,13 @@ packages.
The Windows installer already includes Icinga Studio. On Debian and Ubuntu the package The Windows installer already includes Icinga Studio. On Debian and Ubuntu the package
`icinga2-studio` can be used to install Icinga Studio. `icinga2-studio` can be used to install Icinga Studio.
### <a id="icinga2-api-clients-cli-console"></a> Icinga 2 Console ### Icinga 2 Console <a id="icinga2-api-clients-cli-console"></a>
By default the [console CLI command](11-cli-commands.md#cli-command-console) evaluates By default the [console CLI command](11-cli-commands.md#cli-command-console) evaluates
expressions in a local interpreter, i.e. independently from your Icinga 2 daemon. expressions in a local interpreter, i.e. independently from your Icinga 2 daemon.
Add the `--connect` parameter to debug and evaluate expressions via the API. Add the `--connect` parameter to debug and evaluate expressions via the API.
### <a id="icinga2-api-clients-programmatic-examples"></a> API Clients Programmatic Examples ### API Clients Programmatic Examples <a id="icinga2-api-clients-programmatic-examples"></a>
The programmatic examples use HTTP basic authentication and SSL certificate The programmatic examples use HTTP basic authentication and SSL certificate
verification. The CA file is expected in `pki/icinga2-ca.crt` verification. The CA file is expected in `pki/icinga2-ca.crt`
@ -1750,7 +1750,7 @@ and `joins` are therefore specified as array.
The `filter` attribute [matches](18-library-reference.md#global-functions-match) The `filter` attribute [matches](18-library-reference.md#global-functions-match)
on all services with `ping` in their name. on all services with `ping` in their name.
#### <a id="icinga2-api-clients-programmatic-examples-python"></a> Example API Client in Python #### Example API Client in Python <a id="icinga2-api-clients-programmatic-examples-python"></a>
The following example uses **Python** and the `requests` and `json` module: The following example uses **Python** and the `requests` and `json` module:
@ -1794,7 +1794,7 @@ The following example uses **Python** and the `requests` and `json` module:
$ python icinga2-api-example.py $ python icinga2-api-example.py
#### <a id="icinga2-api-clients-programmatic-examples-ruby"></a> Example API Client in Ruby #### Example API Client in Ruby <a id="icinga2-api-clients-programmatic-examples-ruby"></a>
The following example uses **Ruby** and the `rest_client` gem: The following example uses **Ruby** and the `rest_client` gem:
@ -1843,7 +1843,7 @@ The following example uses **Ruby** and the `rest_client` gem:
A more detailed example can be found in the [Dashing demo](https://github.com/Icinga/dashing-icinga2). A more detailed example can be found in the [Dashing demo](https://github.com/Icinga/dashing-icinga2).
#### <a id="icinga2-api-clients-programmatic-examples-php"></a> Example API Client in PHP #### Example API Client in PHP <a id="icinga2-api-clients-programmatic-examples-php"></a>
The following example uses **PHP** and its `curl` library: The following example uses **PHP** and its `curl` library:
@ -1894,7 +1894,7 @@ The following example uses **PHP** and its `curl` library:
$ php icinga2-api-example.php $ php icinga2-api-example.php
#### <a id="icinga2-api-clients-programmatic-examples-perl"></a> Example API Client in Perl #### Example API Client in Perl <a id="icinga2-api-clients-programmatic-examples-perl"></a>
The following example uses **Perl** and the `Rest::Client` module: The following example uses **Perl** and the `Rest::Client` module:

32
doc/13-addons.md
View File

@ -1,8 +1,8 @@
# <a id="addons"></a> Icinga 2 Addons # Icinga 2 Addons <a id="addons"></a>
## <a id="addons-graphing"></a> Graphing ## Graphing <a id="addons-graphing"></a>
### <a id="addons-graphing-pnp"></a> PNP ### PNP <a id="addons-graphing-pnp"></a>
[PNP](https://www.pnp4nagios.org) is a graphing addon. [PNP](https://www.pnp4nagios.org) is a graphing addon.
@ -33,7 +33,7 @@ More information on [action_url as attribute](13-addons.md#addons-graphing-pnp-a
and [graph template names](13-addons.md#addons-graphing-pnp-custom-templates). and [graph template names](13-addons.md#addons-graphing-pnp-custom-templates).
### <a id="addons-graphing-graphite"></a> Graphite ### Graphite <a id="addons-graphing-graphite"></a>
[Graphite](https://graphite.readthedocs.org/en/latest/) is a time-series database [Graphite](https://graphite.readthedocs.org/en/latest/) is a time-series database
storing collected metrics and making them available through restful apis storing collected metrics and making them available through restful apis
@ -54,7 +54,7 @@ There are Graphite addons available for collecting the performance data files to
A popular alternative frontend for Graphite is for example [Grafana](https://grafana.org). A popular alternative frontend for Graphite is for example [Grafana](https://grafana.org).
### <a id="addons-graphing-influxdb"></a> InfluxDB ### InfluxDB <a id="addons-graphing-influxdb"></a>
[InfluxDB](https://influxdb.com) is a time series, metrics, and analytics database. [InfluxDB](https://influxdb.com) is a time series, metrics, and analytics database.
It’s written in Go and has no external dependencies. It’s written in Go and has no external dependencies.
@ -66,14 +66,14 @@ for sending real-time metrics from Icinga 2 to InfluxDB.
A popular frontend for InfluxDB is for example [Grafana](https://grafana.org). A popular frontend for InfluxDB is for example [Grafana](https://grafana.org).
## <a id="addons-visualization"></a> Visualization ## Visualization <a id="addons-visualization"></a>
### <a id="addons-visualization-reporting"></a> Icinga Reporting ### Icinga Reporting <a id="addons-visualization-reporting"></a>
By enabling the [DB IDO](14-features.md#db-ido) feature you can use the By enabling the [DB IDO](14-features.md#db-ido) feature you can use the
[Icinga Reporting package](https://docs.icinga.com/latest/en/reporting.html). [Icinga Reporting package](https://docs.icinga.com/latest/en/reporting.html).
### <a id="addons-visualization-nagvis"></a> NagVis ### NagVis <a id="addons-visualization-nagvis"></a>
By using either [Livestatus](14-features.md#setting-up-livestatus) or By using either [Livestatus](14-features.md#setting-up-livestatus) or
[DB IDO](14-features.md#db-ido) as a backend you can create your own network maps [DB IDO](14-features.md#db-ido) as a backend you can create your own network maps
@ -87,12 +87,12 @@ The configuration in nagvis.ini.php should look like this for Livestatus for exa
If you are planning an integration into Icinga Web 2, look at [this module](https://github.com/Icinga/icingaweb2-module-nagvis). If you are planning an integration into Icinga Web 2, look at [this module](https://github.com/Icinga/icingaweb2-module-nagvis).
### <a id="addons-visualization-thruk"></a> Thruk ### Thruk <a id="addons-visualization-thruk"></a>
[Thruk](https://www.thruk.org) is an alternative web interface which can be used with Icinga 2 [Thruk](https://www.thruk.org) is an alternative web interface which can be used with Icinga 2
and the [Livestatus](14-features.md#setting-up-livestatus) feature. and the [Livestatus](14-features.md#setting-up-livestatus) feature.
## <a id="log-monitoring"></a> Log Monitoring ## Log Monitoring <a id="log-monitoring"></a>
Using [Logstash](https://www.elastic.co/guide/en/logstash/current/introduction.html) or Using [Logstash](https://www.elastic.co/guide/en/logstash/current/introduction.html) or
[Graylog](https://www.graylog.org) in your infrastructure and correlate events with your monitoring [Graylog](https://www.graylog.org) in your infrastructure and correlate events with your monitoring
@ -104,11 +104,11 @@ is even simpler these days.
More details can be found in [this blog post](https://www.icinga.com/2014/12/02/team-icinga-at-osmc-2014/). More details can be found in [this blog post](https://www.icinga.com/2014/12/02/team-icinga-at-osmc-2014/).
## <a id="notification-scripts-interfaces"></a> Notification Scripts and Interfaces ## Notification Scripts and Interfaces <a id="notification-scripts-interfaces"></a>
There's a variety of resources available, for example different notification scripts such as: There's a variety of resources available, for example different notification scripts such as:
* E-Mail ([examples](3-monitoring-basics.md#alert-notifications) provided) * E-Mail ([examples](03-monitoring-basics.md#alert-notifications) provided)
* SMS * SMS
* Pager (XMPP, etc.) * Pager (XMPP, etc.)
* Twitter * Twitter
@ -124,7 +124,7 @@ Additionally external services can be [integrated with Icinga 2](https://www.ici
More information can be found on the [Icinga Website](https://www.icinga.com/). More information can be found on the [Icinga Website](https://www.icinga.com/).
## <a id="configuration-tools"></a> Configuration Management Tools ## Configuration Management Tools <a id="configuration-tools"></a>
If you require your favourite configuration tool to export the Icinga 2 configuration, please get in If you require your favourite configuration tool to export the Icinga 2 configuration, please get in
touch with their developers. The Icinga project does not provide a configuration web interface touch with their developers. The Icinga project does not provide a configuration web interface
@ -139,9 +139,9 @@ These tools are currently in development and require feedback and tests:
* [Puppet Module](https://github.com/Icinga/puppet-icinga2) * [Puppet Module](https://github.com/Icinga/puppet-icinga2)
* [Chef Cookbook](https://github.com/Icinga/chef-icinga2) * [Chef Cookbook](https://github.com/Icinga/chef-icinga2)
## <a id="addon-integration-hints"></a> More Addon Integration Hints ## More Addon Integration Hints <a id="addon-integration-hints"></a>
### <a id="addons-graphing-pnp-action-url"></a> PNP Action Url ### PNP Action Url <a id="addons-graphing-pnp-action-url"></a>
They work in a similar fashion for Icinga 2 and are used for 1.x web interfaces (Icinga Web 2 doesn't require They work in a similar fashion for Icinga 2 and are used for 1.x web interfaces (Icinga Web 2 doesn't require
the action url attribute in its own module). the action url attribute in its own module).
@ -154,7 +154,7 @@ the action url attribute in its own module).
action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$" action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$"
} }
### <a id="addons-graphing-pnp-custom-templates"></a> PNP Custom Templates with Icinga 2 ### PNP Custom Templates with Icinga 2 <a id="addons-graphing-pnp-custom-templates"></a>
PNP automatically determines the graph template from the check command name (or the argument's name). PNP automatically determines the graph template from the check command name (or the argument's name).
This behavior changed in Icinga 2 compared to Icinga 1.x. Though there are certain possibilities to This behavior changed in Icinga 2 compared to Icinga 1.x. Though there are certain possibilities to

84
doc/14-features.md
View File

@ -1,6 +1,6 @@
# <a id="icinga2-features"></a> Icinga 2 Features # Icinga 2 Features <a id="icinga2-features"></a>
## <a id="logging"></a> Logging ## Logging <a id="logging"></a>
Icinga 2 supports three different types of logging: Icinga 2 supports three different types of logging:
@ -25,18 +25,18 @@ Packages will install a configuration file for logrotate on supported
platforms. This configuration ensures that the `icinga2.log`, `error.log` and platforms. This configuration ensures that the `icinga2.log`, `error.log` and
`debug.log` files are rotated on a daily basis. `debug.log` files are rotated on a daily basis.
## <a id="db-ido"></a> DB IDO ## DB IDO <a id="db-ido"></a>
The IDO (Icinga Data Output) modules for Icinga 2 take care of exporting all The IDO (Icinga Data Output) modules for Icinga 2 take care of exporting all
configuration and status information into a database. The IDO database is used configuration and status information into a database. The IDO database is used
by Icinga Web 2. by Icinga Web 2.
Details on the installation can be found in the [Configuring DB IDO](2-getting-started.md#configuring-db-ido-mysql) Details on the installation can be found in the [Configuring DB IDO](02-getting-started.md#configuring-db-ido-mysql)
chapter. Details on the configuration can be found in the chapter. Details on the configuration can be found in the
[IdoMysqlConnection](9-object-types.md#objecttype-idomysqlconnection) and [IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection) and
[IdoPgsqlConnection](9-object-types.md#objecttype-idopgsqlconnection) [IdoPgsqlConnection](09-object-types.md#objecttype-idopgsqlconnection)
object configuration documentation. object configuration documentation.
The DB IDO feature supports [High Availability](6-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido) in The DB IDO feature supports [High Availability](06-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido) in
the Icinga 2 cluster. the Icinga 2 cluster.
The following example query checks the health of the current Icinga 2 instance The following example query checks the health of the current Icinga 2 instance
@ -47,7 +47,7 @@ the query returns an empty result.
> **Tip** > **Tip**
> >
> Use [check plugins](5-service-monitoring.md#service-monitoring-plugins) to monitor the backend. > Use [check plugins](05-service-monitoring.md#service-monitoring-plugins) to monitor the backend.
Replace the `default` string with your instance name if different. Replace the `default` string with your instance name if different.
@ -81,7 +81,7 @@ Example for PostgreSQL:
A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](23-appendix.md#schema-db-ido). A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](23-appendix.md#schema-db-ido).
## <a id="external-commands"></a> External Commands ## External Commands <a id="external-commands"></a>
Icinga 2 provides an external command pipe for processing commands Icinga 2 provides an external command pipe for processing commands
triggering specific actions (for example rescheduling a service check triggering specific actions (for example rescheduling a service check
@ -111,7 +111,7 @@ A list of currently supported external commands can be found [here](23-appendix.
Detailed information on the commands and their required parameters can be found Detailed information on the commands and their required parameters can be found
on the [Icinga 1.x documentation](https://docs.icinga.com/latest/en/extcommands2.html). on the [Icinga 1.x documentation](https://docs.icinga.com/latest/en/extcommands2.html).
## <a id="performance-data"></a> Performance Data ## Performance Data <a id="performance-data"></a>
When a host or service check is executed plugins should provide so-called When a host or service check is executed plugins should provide so-called
`performance data`. Next to that additional check performance data `performance data`. Next to that additional check performance data
@ -125,12 +125,12 @@ reporting and trending.
Well-known addons processing Icinga performance data are [PNP4Nagios](13-addons.md#addons-graphing-pnp), Well-known addons processing Icinga performance data are [PNP4Nagios](13-addons.md#addons-graphing-pnp),
[Graphite](13-addons.md#addons-graphing-graphite) or [OpenTSDB](14-features.md#opentsdb-writer). [Graphite](13-addons.md#addons-graphing-graphite) or [OpenTSDB](14-features.md#opentsdb-writer).
### <a id="writing-performance-data-files"></a> Writing Performance Data Files ### Writing Performance Data Files <a id="writing-performance-data-files"></a>
PNP4Nagios and Graphios use performance data collector daemons to fetch PNP4Nagios and Graphios use performance data collector daemons to fetch
the current performance files for their backend updates. the current performance files for their backend updates.
Therefore the Icinga 2 [PerfdataWriter](9-object-types.md#objecttype-perfdatawriter) Therefore the Icinga 2 [PerfdataWriter](09-object-types.md#objecttype-perfdatawriter)
feature allows you to define the output template format for host and services helped feature allows you to define the output template format for host and services helped
with Icinga 2 runtime vars. with Icinga 2 runtime vars.
@ -148,7 +148,7 @@ the `/var/spool/icinga2/perfdata/` directory as `host-perfdata.<timestamp>` and
External collectors need to parse the rotated performance data files and then External collectors need to parse the rotated performance data files and then
remove the processed files. remove the processed files.
### <a id="graphite-carbon-cache-writer"></a> Graphite Carbon Cache Writer ### Graphite Carbon Cache Writer <a id="graphite-carbon-cache-writer"></a>
While there are some [Graphite](13-addons.md#addons-graphing-graphite) While there are some [Graphite](13-addons.md#addons-graphing-graphite)
collector scripts and daemons like Graphios available for Icinga 1.x it's more collector scripts and daemons like Graphios available for Icinga 1.x it's more
@ -160,16 +160,16 @@ You can enable the feature using
# icinga2 feature enable graphite # icinga2 feature enable graphite
By default the [GraphiteWriter](9-object-types.md#objecttype-graphitewriter) feature By default the [GraphiteWriter](09-object-types.md#objecttype-graphitewriter) feature
expects the Graphite Carbon Cache to listen at `127.0.0.1` on TCP port `2003`. expects the Graphite Carbon Cache to listen at `127.0.0.1` on TCP port `2003`.
#### <a id="graphite-carbon-cache-writer-schema"></a> Current Graphite Schema #### Current Graphite Schema <a id="graphite-carbon-cache-writer-schema"></a>
The current naming schema is defined as follows. The official Icinga Web 2 Graphite The current naming schema is defined as follows. The official Icinga Web 2 Graphite
module will use that schema too. module will use that schema too.
The default prefix for hosts and services is configured using The default prefix for hosts and services is configured using
[runtime macros](3-monitoring-basics.md#runtime-macros)like this: [runtime macros](03-monitoring-basics.md#runtime-macros)like this:
icinga2.$host.name$.host.$host.check_command$ icinga2.$host.name$.host.$host.check_command$
icinga2.$host.name$.services.$service.name$.$service.check_command$ icinga2.$host.name$.services.$service.name$.$service.check_command$
@ -249,7 +249,7 @@ Cache.
pattern = ^icinga2\. pattern = ^icinga2\.
retentions = 1m:2d,5m:10d,30m:90d,360m:4y retentions = 1m:2d,5m:10d,30m:90d,360m:4y
#### <a id="graphite-carbon-cache-writer-schema-legacy"></a> Graphite Schema < 2.4 #### Graphite Schema < 2.4 <a id="graphite-carbon-cache-writer-schema-legacy"></a>
> **Note** > **Note**
> >
@ -274,9 +274,9 @@ The old legacy naming schema is
You can customize the metric prefix name by using the `host_name_template` and You can customize the metric prefix name by using the `host_name_template` and
`service_name_template` configuration attributes. `service_name_template` configuration attributes.
The example below uses [runtime macros](3-monitoring-basics.md#runtime-macros) and a The example below uses [runtime macros](03-monitoring-basics.md#runtime-macros) and a
[global constant](17-language-reference.md#constants) named `GraphiteEnv`. The constant name [global constant](17-language-reference.md#constants) named `GraphiteEnv`. The constant name
is freely definable and should be put in the [constants.conf](4-configuring-icinga-2.md#constants-conf) file. is freely definable and should be put in the [constants.conf](04-configuring-icinga-2.md#constants-conf) file.
const GraphiteEnv = "icinga.env1" const GraphiteEnv = "icinga.env1"
@ -322,7 +322,7 @@ Cache. Please make sure that the order is correct because the first match wins.
pattern = ^icinga\. pattern = ^icinga\.
retentions = 1m:2d,5m:10d,30m:90d,360m:4y retentions = 1m:2d,5m:10d,30m:90d,360m:4y
### <a id="influxdb-writer"></a> InfluxDB Writer ### InfluxDB Writer <a id="influxdb-writer"></a>
Once there are new metrics available, Icinga 2 will directly write them to the Once there are new metrics available, Icinga 2 will directly write them to the
defined InfluxDB HTTP API. defined InfluxDB HTTP API.
@ -331,14 +331,14 @@ You can enable the feature using
# icinga2 feature enable influxdb # icinga2 feature enable influxdb
By default the [InfluxdbWriter](9-object-types.md#objecttype-influxdbwriter) feature By default the [InfluxdbWriter](09-object-types.md#objecttype-influxdbwriter) feature
expects the InfluxDB daemon to listen at `127.0.0.1` on port `8086`. expects the InfluxDB daemon to listen at `127.0.0.1` on port `8086`.
More configuration details can be found [here](9-object-types.md#objecttype-influxdbwriter). More configuration details can be found [here](09-object-types.md#objecttype-influxdbwriter).
### <a id="graylog-integration"></a> Graylog Integration ### Graylog Integration <a id="graylog-integration"></a>
#### <a id="gelfwriter"></a> GELF Writer #### GELF Writer <a id="gelfwriter"></a>
The `Graylog Extended Log Format` (short: [GELF](http://docs.graylog.org/en/latest/pages/gelf.html)) The `Graylog Extended Log Format` (short: [GELF](http://docs.graylog.org/en/latest/pages/gelf.html))
can be used to send application logs directly to a TCP socket. can be used to send application logs directly to a TCP socket.
@ -360,7 +360,7 @@ Currently these events are processed:
* State changes * State changes
* Notifications * Notifications
### <a id="elastic-stack-integration"></a> Elastic Stack Integration ### Elastic Stack Integration <a id="elastic-stack-integration"></a>
[Icingabeat](https://github.com/icinga/icingabeat) is an Elastic Beat that fetches data [Icingabeat](https://github.com/icinga/icingabeat) is an Elastic Beat that fetches data
from the Icinga 2 API and sends it either directly to Elasticsearch or Logstash. from the Icinga 2 API and sends it either directly to Elasticsearch or Logstash.
@ -369,7 +369,7 @@ More integrations in development:
* [Logstash output](https://github.com/Icinga/logstash-output-icinga) for the Icinga 2 API. * [Logstash output](https://github.com/Icinga/logstash-output-icinga) for the Icinga 2 API.
* [Logstash Grok Pattern](https://github.com/Icinga/logstash-grok-pattern) for Icinga 2 logs. * [Logstash Grok Pattern](https://github.com/Icinga/logstash-grok-pattern) for Icinga 2 logs.
### <a id="opentsdb-writer"></a> OpenTSDB Writer ### OpenTSDB Writer <a id="opentsdb-writer"></a>
While there are some OpenTSDB collector scripts and daemons like tcollector available for While there are some OpenTSDB collector scripts and daemons like tcollector available for
Icinga 1.x it's more reasonable to directly process the check and plugin performance Icinga 1.x it's more reasonable to directly process the check and plugin performance
@ -434,7 +434,7 @@ with the following tags
> in your opentsdb.conf configuration file. > in your opentsdb.conf configuration file.
## <a id="setting-up-livestatus"></a> Livestatus ## Livestatus <a id="setting-up-livestatus"></a>
The [MK Livestatus](https://mathias-kettner.de/checkmk_livestatus.html) project The [MK Livestatus](https://mathias-kettner.de/checkmk_livestatus.html) project
implements a query protocol that lets users query their Icinga instance for implements a query protocol that lets users query their Icinga instance for
@ -443,7 +443,7 @@ status information. It can also be used to send commands.
> **Tip** > **Tip**
> >
> Only install the Livestatus feature if your web interface or addon requires > Only install the Livestatus feature if your web interface or addon requires
> you to do so (for example, [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2)). > you to do so (for example, [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2)).
> Icinga Classic UI 1.x and Icinga Web 1.x do not use Livestatus as backend. > Icinga Classic UI 1.x and Icinga Web 1.x do not use Livestatus as backend.
The Livestatus component that is distributed as part of Icinga 2 is a The Livestatus component that is distributed as part of Icinga 2 is a
@ -487,17 +487,17 @@ are expected to be in `/var/log/icinga2/compat`. A different path can be set usi
# icinga2 feature enable compatlog # icinga2 feature enable compatlog
### <a id="livestatus-sockets"></a> Livestatus Sockets ### Livestatus Sockets <a id="livestatus-sockets"></a>
Other to the Icinga 1.x Addon, Icinga 2 supports two socket types Other to the Icinga 1.x Addon, Icinga 2 supports two socket types
* Unix socket (default) * Unix socket (default)
* TCP socket * TCP socket
Details on the configuration can be found in the [LivestatusListener](9-object-types.md#objecttype-livestatuslistener) Details on the configuration can be found in the [LivestatusListener](09-object-types.md#objecttype-livestatuslistener)
object configuration. object configuration.
### <a id="livestatus-get-queries"></a> Livestatus GET Queries ### Livestatus GET Queries <a id="livestatus-get-queries"></a>
> **Note** > **Note**
> >
@ -525,14 +525,14 @@ Example using the tcp socket listening on port `6558`:
(cat servicegroups; sleep 1) | netcat 127.0.0.1 6558 (cat servicegroups; sleep 1) | netcat 127.0.0.1 6558
### <a id="livestatus-command-queries"></a> Livestatus COMMAND Queries ### Livestatus COMMAND Queries <a id="livestatus-command-queries"></a>
A list of available external commands and their parameters can be found [here](23-appendix.md#external-commands-list-detail) A list of available external commands and their parameters can be found [here](23-appendix.md#external-commands-list-detail)
$ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558 $ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558
### <a id="livestatus-filters"></a> Livestatus Filters ### Livestatus Filters <a id="livestatus-filters"></a>
and, or, negate and, or, negate
@ -548,7 +548,7 @@ and, or, negate
>= | | Greater than or equal >= | | Greater than or equal
### <a id="livestatus-stats"></a> Livestatus Stats ### Livestatus Stats <a id="livestatus-stats"></a>
Schema: "Stats: aggregatefunction aggregateattribute" Schema: "Stats: aggregatefunction aggregateattribute"
@ -580,7 +580,7 @@ Example:
OutputFormat: json OutputFormat: json
ResponseHeader: fixed16 ResponseHeader: fixed16
### <a id="livestatus-output"></a> Livestatus Output ### Livestatus Output <a id="livestatus-output"></a>
* CSV * CSV
@ -596,7 +596,7 @@ Separators can be set using ASCII codes like:
Default separators. Default separators.
### <a id="livestatus-error-codes"></a> Livestatus Error Codes ### Livestatus Error Codes <a id="livestatus-error-codes"></a>
Code | Description Code | Description
----------|-------------- ----------|--------------
@ -604,7 +604,7 @@ Default separators.
404 | Table does not exist 404 | Table does not exist
452 | Exception on query 452 | Exception on query
### <a id="livestatus-tables"></a> Livestatus Tables ### Livestatus Tables <a id="livestatus-tables"></a>
Table | Join |Description Table | Join |Description
--------------|-----------|---------------------------- --------------|-----------|----------------------------
@ -620,8 +620,8 @@ Default separators.
downtimes | services | status attributes downtimes | services | status attributes
timeperiods | &nbsp; | name and is inside flag timeperiods | &nbsp; | name and is inside flag
endpoints | &nbsp; | config and status attributes endpoints | &nbsp; | config and status attributes
log | services, hosts, contacts, commands | parses [compatlog](9-object-types.md#objecttype-compatlogger) and shows log attributes log | services, hosts, contacts, commands | parses [compatlog](09-object-types.md#objecttype-compatlogger) and shows log attributes
statehist | hosts, services | parses [compatlog](9-object-types.md#objecttype-compatlogger) and aggregates state change attributes statehist | hosts, services | parses [compatlog](09-object-types.md#objecttype-compatlogger) and aggregates state change attributes
hostsbygroup | hostgroups | host attributes grouped by hostgroup and its attributes hostsbygroup | hostgroups | host attributes grouped by hostgroup and its attributes
servicesbygroup | servicegroups | service attributes grouped by servicegroup and its attributes servicesbygroup | servicegroups | service attributes grouped by servicegroup and its attributes
servicesbyhostgroup | hostgroups | service attributes grouped by hostgroup and its attributes servicesbyhostgroup | hostgroups | service attributes grouped by hostgroup and its attributes
@ -631,7 +631,7 @@ The `commands` table is populated with `CheckCommand`, `EventCommand` and `Notif
A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](23-appendix.md#schema-livestatus). A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](23-appendix.md#schema-livestatus).
## <a id="status-data"></a> Status Data Files ## Status Data Files <a id="status-data"></a>
Icinga 1.x writes object configuration data and status data in a cyclic Icinga 1.x writes object configuration data and status data in a cyclic
interval to its `objects.cache` and `status.dat` files. Icinga 2 provides interval to its `objects.cache` and `status.dat` files. Icinga 2 provides
@ -648,7 +648,7 @@ Icinga 1.x Classic UI requires this data set as part of its backend.
> you can safely disable this feature. > you can safely disable this feature.
## <a id="compat-logging"></a> Compat Log Files ## Compat Log Files <a id="compat-logging"></a>
The Icinga 1.x log format is considered being the `Compat Log` The Icinga 1.x log format is considered being the `Compat Log`
in Icinga 2 provided with the `CompatLogger` object. in Icinga 2 provided with the `CompatLogger` object.
@ -695,7 +695,7 @@ existing log parsers.
[1382115731] SERVICE ALERT: localhost;ping6;CRITICAL;SOFT;2;critical test [1382115731] SERVICE ALERT: localhost;ping6;CRITICAL;SOFT;2;critical test
## <a id="check-result-files"></a> Check Result Files ## Check Result Files <a id="check-result-files"></a>
Icinga 1.x writes its check result files to a temporary spool directory Icinga 1.x writes its check result files to a temporary spool directory
where they are processed in a regular interval. where they are processed in a regular interval.

110
doc/15-troubleshooting.md
View File

@ -1,6 +1,6 @@
# <a id="troubleshooting"></a> Icinga 2 Troubleshooting # Icinga 2 Troubleshooting <a id="troubleshooting"></a>
## <a id="troubleshooting-information-required"></a> Required Information ## Required Information <a id="troubleshooting-information-required"></a>
Please ensure to provide any detail which may help reproduce and understand your issue. Please ensure to provide any detail which may help reproduce and understand your issue.
Whether you ask on the community channels or you create an issue at [GitHub](https://github.com/Icinga), make sure Whether you ask on the community channels or you create an issue at [GitHub](https://github.com/Icinga), make sure
@ -22,8 +22,8 @@ findings and details please.
* [Icinga Web 2 modules](https://www.icinga.com/products/icinga-web-2-modules/) e.g. the Icinga Director (optional) * [Icinga Web 2 modules](https://www.icinga.com/products/icinga-web-2-modules/) e.g. the Icinga Director (optional)
* Configuration insights: * Configuration insights:
* Provide complete configuration snippets explaining your problem in detail * Provide complete configuration snippets explaining your problem in detail
* Your [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) file * Your [icinga2.conf](04-configuring-icinga-2.md#icinga2-conf) file
* If you run multiple Icinga 2 instances, the [zones.conf](4-configuring-icinga-2.md#zones-conf) file (or `icinga2 object list --type Endpoint` and `icinga2 object list --type Zone`) from all affected nodes. * If you run multiple Icinga 2 instances, the [zones.conf](04-configuring-icinga-2.md#zones-conf) file (or `icinga2 object list --type Endpoint` and `icinga2 object list --type Zone`) from all affected nodes.
* Logs * Logs
* Relevant output from your main and [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) in `/var/log/icinga2`. Please add step-by-step explanations with timestamps if required. * Relevant output from your main and [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) in `/var/log/icinga2`. Please add step-by-step explanations with timestamps if required.
* The newest Icinga 2 crash log if relevant, located in `/var/log/icinga2/crash` * The newest Icinga 2 crash log if relevant, located in `/var/log/icinga2/crash`
@ -31,7 +31,7 @@ findings and details please.
* If the check command failed, what's the output of your manual plugin tests? * If the check command failed, what's the output of your manual plugin tests?
* In case of [debugging](20-development.md#development) Icinga 2, the full back traces and outputs * In case of [debugging](20-development.md#development) Icinga 2, the full back traces and outputs
## <a id="troubleshooting-analyze-environment"></a> Analyze your Environment ## Analyze your Environment <a id="troubleshooting-analyze-environment"></a>
There are many components involved on a server running Icinga 2. When you There are many components involved on a server running Icinga 2. When you
analyze a problem, keep in mind that basic system administration knowledge analyze a problem, keep in mind that basic system administration knowledge
@ -39,7 +39,7 @@ is also key to identify bottlenecks and issues.
> **Tip** > **Tip**
> >
> [Monitor Icinga 2](8-advanced-topics.md#monitoring-icinga) and use the hints for further analysis. > [Monitor Icinga 2](08-advanced-topics.md#monitoring-icinga) and use the hints for further analysis.
* Analyze the system's performance and dentify bottlenecks and issues. * Analyze the system's performance and dentify bottlenecks and issues.
* Collect details about all applications (e.g. Icinga 2, MySQL, Apache, Graphite, Elastic, etc.). * Collect details about all applications (e.g. Icinga 2, MySQL, Apache, Graphite, Elastic, etc.).
@ -48,7 +48,7 @@ is also key to identify bottlenecks and issues.
Install tools which help you to do so. Opinions differ, let us know if you have any additions here! Install tools which help you to do so. Opinions differ, let us know if you have any additions here!
### <a id="troubleshooting-analyze-environment-linux"></a> Analyse your Linux/Unix Environment ### Analyse your Linux/Unix Environment <a id="troubleshooting-analyze-environment-linux"></a>
[htop](https://hisham.hm/htop/) is a better replacement for `top` and helps to analyze processes [htop](https://hisham.hm/htop/) is a better replacement for `top` and helps to analyze processes
interactively. interactively.
@ -99,7 +99,7 @@ sar -b //I/O
If you are missing checks and metrics found in your analysis, add them to your monitoring! If you are missing checks and metrics found in your analysis, add them to your monitoring!
### <a id="troubleshooting-analyze-environment-windows"></a> Analyze your Windows Environment ### Analyze your Windows Environment <a id="troubleshooting-analyze-environment-windows"></a>
A good tip for Windows are the tools found inside the [Sysinternals Suite](https://technet.microsoft.com/en-us/sysinternals/bb842062.aspx). A good tip for Windows are the tools found inside the [Sysinternals Suite](https://technet.microsoft.com/en-us/sysinternals/bb842062.aspx).
@ -107,9 +107,9 @@ You can also start `perfmon` and analyze specific performance counters.
Keep notes which could be important for your monitoring, and add service Keep notes which could be important for your monitoring, and add service
checks later on. checks later on.
## <a id="troubleshooting-enable-debug-output"></a> Enable Debug Output ## Enable Debug Output <a id="troubleshooting-enable-debug-output"></a>
### <a id="troubleshooting-enable-debug-output-linux"></a> Enable Debug Output on Linux/Unix ### Enable Debug Output on Linux/Unix <a id="troubleshooting-enable-debug-output-linux"></a>
Enable the `debuglog` feature: Enable the `debuglog` feature:
@ -123,10 +123,10 @@ log severity as an additional parameter argument to `-x`.
# /usr/sbin/icinga2 daemon -x notice # /usr/sbin/icinga2 daemon -x notice
The [log severity](9-object-types.md#objecttype-filelogger) can be one of `critical`, `warning`, `information`, `notice` The [log severity](09-object-types.md#objecttype-filelogger) can be one of `critical`, `warning`, `information`, `notice`
and `debug`. and `debug`.
### <a id="troubleshooting-enable-debug-output-windows"></a> Enable Debug Output on Windows ### Enable Debug Output on Windows <a id="troubleshooting-enable-debug-output-windows"></a>
Open a command prompt with administrative privileges and enable the debug log feature. Open a command prompt with administrative privileges and enable the debug log feature.
@ -138,7 +138,7 @@ Restart the Icinga 2 service and open the newly created `debug.log` file.
C:> net stop icinga2 C:> net stop icinga2
C:> net start icinga2 C:> net start icinga2
## <a id="list-configuration-objects"></a> List Configuration Objects ## List Configuration Objects <a id="list-configuration-objects"></a>
The `icinga2 object list` CLI command can be used to list all configuration objects and their The `icinga2 object list` CLI command can be used to list all configuration objects and their
attributes. The tool also shows where each of the attributes was modified. attributes. The tool also shows where each of the attributes was modified.
@ -210,7 +210,7 @@ are not immediately updated. Furthermore there is a known issue with
You need to restart Icinga 2 in order to update the `icinga2.debug` cache file. You need to restart Icinga 2 in order to update the `icinga2.debug` cache file.
## <a id="check-command-definitions"></a> Where are the check command definitions? ## Where are the check command definitions? <a id="check-command-definitions"></a>
Icinga 2 features a number of built-in [check command definitions](10-icinga-template-library.md#plugin-check-commands) which are Icinga 2 features a number of built-in [check command definitions](10-icinga-template-library.md#plugin-check-commands) which are
included with included with
@ -218,16 +218,16 @@ included with
include <itl> include <itl>
include <plugins> include <plugins>
in the [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) configuration file. These files are not considered configuration files and will be overridden in the [icinga2.conf](04-configuring-icinga-2.md#icinga2-conf) configuration file. These files are not considered configuration files and will be overridden
on upgrade, so please send modifications as proposed patches upstream. The default include path is set to on upgrade, so please send modifications as proposed patches upstream. The default include path is set to
`LocalStateDir + "/share/icinga2/includes"`. `LocalStateDir + "/share/icinga2/includes"`.
You should add your own command definitions to a new file in `conf.d/` called `commands.conf` You should add your own command definitions to a new file in `conf.d/` called `commands.conf`
or similar. or similar.
## <a id="troubleshooting-checks"></a> Checks ## Checks <a id="troubleshooting-checks"></a>
### <a id="checks-executed-command"></a> Executed Command for Checks ### Executed Command for Checks <a id="checks-executed-command"></a>
* Use the Icinga 2 API to [query](12-icinga2-api.md#icinga2-api-config-objects-query) host/service objects * Use the Icinga 2 API to [query](12-icinga2-api.md#icinga2-api-config-objects-query) host/service objects
for their check result containing the executed shell command. for their check result containing the executed shell command.
@ -287,7 +287,7 @@ Example for searching the debug log:
# tail -f /var/log/icinga2/debug.log | grep "notice/Process" # tail -f /var/log/icinga2/debug.log | grep "notice/Process"
### <a id="checks-not-executed"></a> Checks are not executed ### Checks are not executed <a id="checks-not-executed"></a>
* Check the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) to see if the check command gets executed. * Check the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) to see if the check command gets executed.
* Verify that failed depedencies do not prevent command execution. * Verify that failed depedencies do not prevent command execution.
@ -307,7 +307,7 @@ Fetch all check result events matching the `event.service` name `random`:
$ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/events?queue=debugchecks&types=CheckResult&filter=match%28%22random*%22,event.service%29' $ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/events?queue=debugchecks&types=CheckResult&filter=match%28%22random*%22,event.service%29'
### <a id="check-fork-errors"></a> Check Fork Errors ### Check Fork Errors <a id="check-fork-errors"></a>
We've learned that newer kernel versions introduce a [fork limit for cgroups](https://lwn.net/Articles/663873/) We've learned that newer kernel versions introduce a [fork limit for cgroups](https://lwn.net/Articles/663873/)
which is enabled in SLES 12 SP2+ for example. The default value which is enabled in SLES 12 SP2+ for example. The default value
@ -335,7 +335,7 @@ or set it to `infinity`:
Please note that this setting is available since Systemd version 226. Please note that this setting is available since Systemd version 226.
### <a id="late-check-results"></a> Late Check Results ### Late Check Results <a id="late-check-results"></a>
[Icinga Web 2](https://www.icinga.com/products/icinga-web-2/) provides [Icinga Web 2](https://www.icinga.com/products/icinga-web-2/) provides
a dashboard overview for `overdue checks`. a dashboard overview for `overdue checks`.
@ -379,7 +379,7 @@ and repeat the commands.
More details about the Icinga 2 DSL and its possibilities can be More details about the Icinga 2 DSL and its possibilities can be
found in the [language](17-language-reference.md#language-reference) and [library](18-library-reference.md#library-reference) reference chapters. found in the [language](17-language-reference.md#language-reference) and [library](18-library-reference.md#library-reference) reference chapters.
### <a id="late-check-results-distributed"></a> Late Check Results in Distributed Environments ### Late Check Results in Distributed Environments <a id="late-check-results-distributed"></a>
When it comes to a distributed HA setup, each node is responsible for a load-balanced amount of checks. When it comes to a distributed HA setup, each node is responsible for a load-balanced amount of checks.
Host and Service objects provide the attribute `paused`. If this is set to `false`, the current node Host and Service objects provide the attribute `paused`. If this is set to `false`, the current node
@ -397,7 +397,7 @@ found a bug in the cluster.
If you are running a cluster setup where the master/satellite executes checks on the client via If you are running a cluster setup where the master/satellite executes checks on the client via
[top down command endpoint](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint) mode, [top down command endpoint](06-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint) mode,
you might want to know which zones are affected. you might want to know which zones are affected.
This analysis assumes that clients which are not connected, have the string `connected` in their This analysis assumes that clients which are not connected, have the string `connected` in their
@ -414,7 +414,7 @@ service check result output and their state is `UNKNOWN`.
The result set shows the configured zones and their affected hosts in a unique list. The output also just prints the numbers The result set shows the configured zones and their affected hosts in a unique list. The output also just prints the numbers
but you can adjust this by omitting the `len()` call inside the for loop. but you can adjust this by omitting the `len()` call inside the for loop.
## <a id="notifications-not-sent"></a> Notifications are not sent ## Notifications are not sent <a id="notifications-not-sent"></a>
* Check the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) to see if a notification is triggered. * Check the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) to see if a notification is triggered.
* If yes, verify that all conditions are satisfied. * If yes, verify that all conditions are satisfied.
@ -426,14 +426,14 @@ to any question or issue posted to the community channels.
Verify the following configuration: Verify the following configuration:
* Is the host/service `enable_notifications` attribute set, and if so, to which value? * Is the host/service `enable_notifications` attribute set, and if so, to which value?
* Do the [notification](9-object-types.md#objecttype-notification) attributes `states`, `types`, `period` match the notification conditions? * Do the [notification](09-object-types.md#objecttype-notification) attributes `states`, `types`, `period` match the notification conditions?
* Do the [user](9-object-types.md#objecttype-user) attributes `states`, `types`, `period` match the notification conditions? * Do the [user](09-object-types.md#objecttype-user) attributes `states`, `types`, `period` match the notification conditions?
* Are there any notification `begin` and `end` times configured? * Are there any notification `begin` and `end` times configured?
* Make sure the [notification](11-cli-commands.md#enable-features) feature is enabled. * Make sure the [notification](11-cli-commands.md#enable-features) feature is enabled.
* Does the referenced NotificationCommand work when executed as Icinga user on the shell? * Does the referenced NotificationCommand work when executed as Icinga user on the shell?
If notifications are to be sent via mail, make sure that the mail program specified inside the If notifications are to be sent via mail, make sure that the mail program specified inside the
[NotificationCommand object](9-object-types.md#objecttype-notificationcommand) exists. [NotificationCommand object](09-object-types.md#objecttype-notificationcommand) exists.
The name and location depends on the distribution so the preconfigured setting might have to be The name and location depends on the distribution so the preconfigured setting might have to be
changed on your system. changed on your system.
@ -448,14 +448,14 @@ You can use the Icinga 2 API [event streams](12-icinga2-api.md#icinga2-api-event
$ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/events?queue=debugnotifications&types=Notification' $ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/events?queue=debugnotifications&types=Notification'
## <a id="feature-not-working"></a> Feature is not working ## Feature is not working <a id="feature-not-working"></a>
* Make sure that the feature configuration is enabled by symlinking from `features-available/` * Make sure that the feature configuration is enabled by symlinking from `features-available/`
to `features-enabled` and that the latter is included in [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf). to `features-enabled` and that the latter is included in [icinga2.conf](04-configuring-icinga-2.md#icinga2-conf).
* Are the feature attributes set correctly according to the documentation? * Are the feature attributes set correctly according to the documentation?
* Any errors on the logs? * Any errors on the logs?
Look up the [object type](9-object-types.md#object-types) for the required feature and verify it is enabled: Look up the [object type](09-object-types.md#object-types) for the required feature and verify it is enabled:
# icinga2 object list --type <feature object type> # icinga2 object list --type <feature object type>
@ -463,18 +463,18 @@ Example for the `graphite` feature:
# icinga2 object list --type GraphiteWriter # icinga2 object list --type GraphiteWriter
## <a id="configuration-ignored"></a> Configuration is ignored ## Configuration is ignored <a id="configuration-ignored"></a>
* Make sure that the line(s) are not [commented out](17-language-reference.md#comments) (starting with `//` or `#`, or * Make sure that the line(s) are not [commented out](17-language-reference.md#comments) (starting with `//` or `#`, or
encapsulated by `/* ... */`). encapsulated by `/* ... */`).
* Is the configuration file included in [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf)? * Is the configuration file included in [icinga2.conf](04-configuring-icinga-2.md#icinga2-conf)?
Run the [configuration validation](11-cli-commands.md#config-validation) and add `notice` as log severity. Run the [configuration validation](11-cli-commands.md#config-validation) and add `notice` as log severity.
Search for the file which should be included i.e. using the `grep` CLI command. Search for the file which should be included i.e. using the `grep` CLI command.
# icinga2 daemon -C -x notice | grep command # icinga2 daemon -C -x notice | grep command
## <a id="configuration-attribute-inheritance"></a> Configuration attributes are inherited from ## Configuration attributes are inherited from <a id="configuration-attribute-inheritance"></a>
Icinga 2 allows you to import templates using the [import](17-language-reference.md#template-imports) keyword. If these templates Icinga 2 allows you to import templates using the [import](17-language-reference.md#template-imports) keyword. If these templates
contain additional attributes, your objects will automatically inherit them. You can override contain additional attributes, your objects will automatically inherit them. You can override
@ -482,10 +482,10 @@ or modify these attributes in the current object.
The [object list](15-troubleshooting.md#list-configuration-objects) CLI command allows you to verify the attribute origin. The [object list](15-troubleshooting.md#list-configuration-objects) CLI command allows you to verify the attribute origin.
## <a id="configuration-value-dollar-sign"></a> Configuration Value with Single Dollar Sign ## Configuration Value with Single Dollar Sign <a id="configuration-value-dollar-sign"></a>
In case your configuration validation fails with a missing closing dollar sign error message, you In case your configuration validation fails with a missing closing dollar sign error message, you
did not properly escape the single dollar sign preventing its usage as [runtime macro](3-monitoring-basics.md#runtime-macros). did not properly escape the single dollar sign preventing its usage as [runtime macro](03-monitoring-basics.md#runtime-macros).
critical/config: Error: Validation failed for Object 'ping4' (Type: 'Service') at /etc/icinga2/zones.d/global-templates/windows.conf:24: Closing $ not found in macro format string 'top-syntax=${list}'. critical/config: Error: Validation failed for Object 'ping4' (Type: 'Service') at /etc/icinga2/zones.d/global-templates/windows.conf:24: Closing $ not found in macro format string 'top-syntax=${list}'.
@ -493,11 +493,11 @@ Correct the custom attribute value to
"top-syntax=$${list}" "top-syntax=$${list}"
## <a id="troubleshooting-cluster"></a> Cluster and Clients Troubleshooting ## Cluster and Clients Troubleshooting <a id="troubleshooting-cluster"></a>
This applies to any Icinga 2 node in a [distributed monitoring setup](6-distributed-monitoring.md#distributed-monitoring-scenarios). This applies to any Icinga 2 node in a [distributed monitoring setup](06-distributed-monitoring.md#distributed-monitoring-scenarios).
You should configure the [cluster health checks](6-distributed-monitoring.md#distributed-monitoring-health-checks) if you haven't You should configure the [cluster health checks](06-distributed-monitoring.md#distributed-monitoring-health-checks) if you haven't
done so already. done so already.
> **Note** > **Note**
@ -505,7 +505,7 @@ done so already.
> Some problems just exist due to wrong file permissions or applied packet filters. Make > Some problems just exist due to wrong file permissions or applied packet filters. Make
> sure to check these in the first place. > sure to check these in the first place.
### <a id="troubleshooting-cluster-connection-errors"></a> Cluster Troubleshooting Connection Errors ### Cluster Troubleshooting Connection Errors <a id="troubleshooting-cluster-connection-errors"></a>
General connection errors could be one of the following problems: General connection errors could be one of the following problems:
@ -522,7 +522,7 @@ works (default port is `5665`).
# nmap yourclusternode.localdomain # nmap yourclusternode.localdomain
### <a id="troubleshooting-cluster-ssl-errors"></a> Cluster Troubleshooting SSL Errors ### Cluster Troubleshooting SSL Errors <a id="troubleshooting-cluster-ssl-errors"></a>
If the cluster communication fails with SSL error messages, make sure to check If the cluster communication fails with SSL error messages, make sure to check
the following the following
@ -565,7 +565,7 @@ Try to manually connect from `icinga2-node2.localdomain` to the master node `ici
If the connection attempt fails or your CA does not match, [verify the master and client certificates](15-troubleshooting.md#troubleshooting-cluster-ssl-certificate-verification). If the connection attempt fails or your CA does not match, [verify the master and client certificates](15-troubleshooting.md#troubleshooting-cluster-ssl-certificate-verification).
#### <a id="troubleshooting-cluster-unauthenticated-clients"></a> Cluster Troubleshooting Unauthenticated Clients #### Cluster Troubleshooting Unauthenticated Clients <a id="troubleshooting-cluster-unauthenticated-clients"></a>
Unauthenticated nodes are able to connect. This is required for client setups. Unauthenticated nodes are able to connect. This is required for client setups.
@ -579,7 +579,7 @@ Client as command execution bridge:
If these messages do not go away, make sure to [verify the master and client certificates](15-troubleshooting.md#troubleshooting-cluster-ssl-certificate-verification). If these messages do not go away, make sure to [verify the master and client certificates](15-troubleshooting.md#troubleshooting-cluster-ssl-certificate-verification).
#### <a id="troubleshooting-cluster-ssl-certificate-verification"></a> Cluster Troubleshooting SSL Certificate Verification #### Cluster Troubleshooting SSL Certificate Verification <a id="troubleshooting-cluster-ssl-certificate-verification"></a>
Make sure to verify the client's certificate and its received `ca.crt` in `/etc/icinga2/pki` and ensure that Make sure to verify the client's certificate and its received `ca.crt` in `/etc/icinga2/pki` and ensure that
both instances are signed by the **same CA**. both instances are signed by the **same CA**.
@ -597,7 +597,7 @@ Fetch the `ca.crt` file from the client node and compare it to your master's `ca
On SLES11 you'll need to use the `openssl1` command instead of `openssl`. On SLES11 you'll need to use the `openssl1` command instead of `openssl`.
### <a id="troubleshooting-cluster-message-errors"></a> Cluster Troubleshooting Message Errors ### Cluster Troubleshooting Message Errors <a id="troubleshooting-cluster-message-errors"></a>
At some point, when the network connection is broken or gone, the Icinga 2 instances At some point, when the network connection is broken or gone, the Icinga 2 instances
will be disconnected. If the connection can't be re-established between endpoints in the same HA zone, will be disconnected. If the connection can't be re-established between endpoints in the same HA zone,
@ -606,16 +606,16 @@ they remain in a Split-Brain-mode and history may differ.
Although the Icinga 2 cluster protocol stores historical events in a [replay log](15-troubleshooting.md#troubleshooting-cluster-replay-log) Although the Icinga 2 cluster protocol stores historical events in a [replay log](15-troubleshooting.md#troubleshooting-cluster-replay-log)
for later synchronisation, you should make sure to check why the network connection failed. for later synchronisation, you should make sure to check why the network connection failed.
### <a id="troubleshooting-cluster-command-endpoint-errors"></a> Cluster Troubleshooting Command Endpoint Errors ### Cluster Troubleshooting Command Endpoint Errors <a id="troubleshooting-cluster-command-endpoint-errors"></a>
Command endpoints can be used [for clients](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint) Command endpoints can be used [for clients](06-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint)
as well as inside an [High-Availability cluster](6-distributed-monitoring.md#distributed-monitoring-scenarios). as well as inside an [High-Availability cluster](06-distributed-monitoring.md#distributed-monitoring-scenarios).
There is no cli command for manually executing the check, but you can verify There is no cli command for manually executing the check, but you can verify
the following (e.g. by invoking a forced check from the web interface): the following (e.g. by invoking a forced check from the web interface):
* `/var/log/icinga2/icinga2.log` contains connection and execution errors. * `/var/log/icinga2/icinga2.log` contains connection and execution errors.
* The ApiListener is not enabled to [accept commands](6-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint). * The ApiListener is not enabled to [accept commands](06-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint).
* `CheckCommand` definition not found on the remote client. * `CheckCommand` definition not found on the remote client.
* Referenced check plugin not found on the remote client. * Referenced check plugin not found on the remote client.
* Runtime warnings and errors, e.g. unresolved runtime macros or configuration problems. * Runtime warnings and errors, e.g. unresolved runtime macros or configuration problems.
@ -631,7 +631,7 @@ Fetch all check result events matching the `event.service` name `remote-client`:
### <a id="troubleshooting-cluster-config-sync"></a> Cluster Troubleshooting Config Sync ### Cluster Troubleshooting Config Sync <a id="troubleshooting-cluster-config-sync"></a>
If the cluster zones do not sync their configuration, make sure to check the following: If the cluster zones do not sync their configuration, make sure to check the following:
@ -639,24 +639,24 @@ If the cluster zones do not sync their configuration, make sure to check the fol
** The master syncs the configuration to `/var/lib/icinga2/api/zones/` during startup and only syncs valid configuration to the other nodes. ** The master syncs the configuration to `/var/lib/icinga2/api/zones/` during startup and only syncs valid configuration to the other nodes.
** The other nodes receive the configuration into `/var/lib/icinga2/api/zones/`. ** The other nodes receive the configuration into `/var/lib/icinga2/api/zones/`.
* The `icinga2.log` log file in `/var/log/icinga2` will indicate whether this ApiListener * The `icinga2.log` log file in `/var/log/icinga2` will indicate whether this ApiListener
[accepts config](6-distributed-monitoring.md#distributed-monitoring-top-down-config-sync), or not. [accepts config](06-distributed-monitoring.md#distributed-monitoring-top-down-config-sync), or not.
Verify the object's [version](9-object-types.md#object-types) attribute on all nodes to Verify the object's [version](09-object-types.md#object-types) attribute on all nodes to
check whether the config update and reload was succesful or not. check whether the config update and reload was succesful or not.
### <a id="troubleshooting-cluster-check-results"></a> Cluster Troubleshooting Overdue Check Results ### Cluster Troubleshooting Overdue Check Results <a id="troubleshooting-cluster-check-results"></a>
If your master does not receive check results (or any other events) from the child zones If your master does not receive check results (or any other events) from the child zones
(satellite, clients, etc.), make sure to check whether the client sending in events (satellite, clients, etc.), make sure to check whether the client sending in events
is allowed to do so. is allowed to do so.
The [distributed monitoring conventions](6-distributed-monitoring.md#distributed-monitoring-conventions) The [distributed monitoring conventions](06-distributed-monitoring.md#distributed-monitoring-conventions)
apply. So, if there's a mismatch between your client node's endpoint name and its provided apply. So, if there's a mismatch between your client node's endpoint name and its provided
certificate's CN, the master will deny all events. certificate's CN, the master will deny all events.
> **Tip** > **Tip**
> >
> [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2) provides a dashboard view > [Icinga Web 2](02-getting-started.md#setting-up-icingaweb2) provides a dashboard view
> for overdue check results. > for overdue check results.
Enable the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) on the master Enable the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) on the master
@ -674,7 +674,7 @@ in on the master:
Discarding 'check result' message from 'icinga2b': Unauthorized access. Discarding 'check result' message from 'icinga2b': Unauthorized access.
### <a id="troubleshooting-cluster-replay-log"></a> Cluster Troubleshooting Replay Log ### Cluster Troubleshooting Replay Log <a id="troubleshooting-cluster-replay-log"></a>
If your `/var/lib/icinga2/api/log` directory grows, it generally means that your cluster If your `/var/lib/icinga2/api/log` directory grows, it generally means that your cluster
cannot replay the log on connection loss and re-establishment. A master node for example cannot replay the log on connection loss and re-establishment. A master node for example
@ -682,7 +682,7 @@ will store all events for not connected endpoints in the same and child zones.
Check the following: Check the following:
* All clients are connected? (e.g. [cluster health check](6-distributed-monitoring.md#distributed-monitoring-health-checks)). * All clients are connected? (e.g. [cluster health check](06-distributed-monitoring.md#distributed-monitoring-health-checks)).
* Check your [connection](15-troubleshooting.md#troubleshooting-cluster-connection-errors) in general. * Check your [connection](15-troubleshooting.md#troubleshooting-cluster-connection-errors) in general.
* Does the log replay work, e.g. are all events processed and the directory gets cleared up over time? * Does the log replay work, e.g. are all events processed and the directory gets cleared up over time?
* Decrease the `log_duration` attribute value for that specific [endpoint](9-object-types.md#objecttype-endpoint). * Decrease the `log_duration` attribute value for that specific [endpoint](09-object-types.md#objecttype-endpoint).

6
doc/16-upgrading-icinga-2.md
View File

@ -1,9 +1,9 @@
# <a id="upgrading-icinga-2"></a> Upgrading Icinga 2 # Upgrading Icinga 2 <a id="upgrading-icinga-2"></a>
Upgrading Icinga 2 is usually quite straightforward. Ordinarily the only manual steps involved Upgrading Icinga 2 is usually quite straightforward. Ordinarily the only manual steps involved
are scheme updates for the IDO database. are scheme updates for the IDO database.
## <a id="upgrading-mysql-db"></a> Upgrading the MySQL database ## Upgrading the MySQL database <a id="upgrading-mysql-db"></a>
If you're upgrading an existing Icinga 2 instance, you should check the If you're upgrading an existing Icinga 2 instance, you should check the
`/usr/share/icinga2-ido-mysql/schema/upgrade` directory for an incremental schema upgrade file. `/usr/share/icinga2-ido-mysql/schema/upgrade` directory for an incremental schema upgrade file.
@ -29,7 +29,7 @@ the *upgrade* directory:
There are two new upgrade files called `2.1.0.sql`, `2.2.0.sql` and `2.3.0.sql` There are two new upgrade files called `2.1.0.sql`, `2.2.0.sql` and `2.3.0.sql`
which must be applied incrementally to your IDO database. which must be applied incrementally to your IDO database.
## <a id="upgrading-postgresql-db"></a> Upgrading the PostgreSQL database ## Upgrading the PostgreSQL database <a id="upgrading-postgresql-db"></a>
If you're updating an existing Icinga 2 instance, you should check the If you're updating an existing Icinga 2 instance, you should check the
`/usr/share/icinga2-ido-pgsql/schema/upgrade` directory for an incremental schema upgrade file. `/usr/share/icinga2-ido-pgsql/schema/upgrade` directory for an incremental schema upgrade file.

102
doc/17-language-reference.md
View File

@ -1,6 +1,6 @@
# <a id="language-reference"></a> Language Reference # Language Reference <a id="language-reference"></a>
## <a id="object-definition"></a> Object Definition ## Object Definition <a id="object-definition"></a>
Icinga 2 features an object-based configuration format. You can define new Icinga 2 features an object-based configuration format. You can define new
objects using the `object` keyword: objects using the `object` keyword:
@ -43,11 +43,11 @@ Attribute | Description
name | The name of the object. This attribute can be modified in the object definition to override the name specified with the `object` directive. name | The name of the object. This attribute can be modified in the object definition to override the name specified with the `object` directive.
type | The type of the object. type | The type of the object.
## <a id="expressions"></a> Expressions ## Expressions <a id="expressions"></a>
The following expressions can be used on the right-hand side of assignments. The following expressions can be used on the right-hand side of assignments.
### <a id="numeric-literals"></a> Numeric Literals ### Numeric Literals <a id="numeric-literals"></a>
A floating-point number. A floating-point number.
@ -55,7 +55,7 @@ Example:
27.3 27.3
### <a id="duration-literals"></a> Duration Literals ### Duration Literals <a id="duration-literals"></a>
Similar to floating-point numbers except for the fact that they support Similar to floating-point numbers except for the fact that they support
suffixes to help with specifying time durations. suffixes to help with specifying time durations.
@ -70,7 +70,7 @@ h (hours) and d (days).
Duration literals are converted to seconds by the config parser and Duration literals are converted to seconds by the config parser and
are treated like numeric literals. are treated like numeric literals.
### <a id="string-literals"></a> String Literals ### String Literals <a id="string-literals"></a>
A string. A string.
@ -78,7 +78,7 @@ Example:
"Hello World!" "Hello World!"
#### <a id="string-literals-escape-sequences"></a> String Literals Escape Sequences #### String Literals Escape Sequences <a id="string-literals-escape-sequences"></a>
Certain characters need to be escaped. The following escape sequences Certain characters need to be escaped. The following escape sequences
are supported: are supported:
@ -97,7 +97,7 @@ In addition to these pre-defined escape sequences you can specify
arbitrary ASCII characters using the backslash character (\\) followed arbitrary ASCII characters using the backslash character (\\) followed
by an ASCII character in octal encoding. by an ASCII character in octal encoding.
### <a id="multiline-string-literals"></a> Multi-line String Literals ### Multi-line String Literals <a id="multiline-string-literals"></a>
Strings spanning multiple lines can be specified by enclosing them in Strings spanning multiple lines can be specified by enclosing them in
{{{ and }}}. {{{ and }}}.
@ -112,15 +112,15 @@ Example:
Unlike in ordinary strings special characters do not have to be escaped Unlike in ordinary strings special characters do not have to be escaped
in multi-line string literals. in multi-line string literals.
### <a id="boolean-literals"></a> Boolean Literals ### Boolean Literals <a id="boolean-literals"></a>
The keywords `true` and `false` are used to denote truth values. The keywords `true` and `false` are used to denote truth values.
### <a id="null-value"></a> Null Value ### Null Value <a id="null-value"></a>
The `null` keyword can be used to specify an empty value. The `null` keyword can be used to specify an empty value.
### <a id="dictionary"></a> Dictionary ### Dictionary <a id="dictionary"></a>
An unordered list of key-value pairs. Keys must be unique and are An unordered list of key-value pairs. Keys must be unique and are
compared in a case-sensitive manner. compared in a case-sensitive manner.
@ -140,7 +140,7 @@ with certain characters (e.g. digits). If you want to use a dictionary
key that is not a valid identifier, you can enclose the key in double key that is not a valid identifier, you can enclose the key in double
quotes. quotes.
### <a id="array"></a> Array ### Array <a id="array"></a>
An ordered list of values. An ordered list of values.
@ -154,7 +154,7 @@ Example:
An array may simultaneously contain values of different types, such as An array may simultaneously contain values of different types, such as
strings and numbers. strings and numbers.
### <a id="expression-operators"></a> Operators ### Operators <a id="expression-operators"></a>
The following operators are supported in expressions. The operators are by descending precedence. The following operators are supported in expressions. The operators are by descending precedence.
@ -191,7 +191,7 @@ in | 7 | "foo" in [ "foo", "bar" ] (true) | Element
= | 12 | a = 3 | Assignment = | 12 | a = 3 | Assignment
=> | 15 | x => x * x (function with arg x) | Lambda, for loop => | 15 | x => x * x (function with arg x) | Lambda, for loop
### <a id="function-calls"></a> Function Calls ### Function Calls <a id="function-calls"></a>
Functions can be called using the `()` operator: Functions can be called using the `()` operator:
@ -203,13 +203,13 @@ Functions can be called using the `()` operator:
A list of available functions is available in the [Library Reference](18-library-reference.md#library-reference) chapter. A list of available functions is available in the [Library Reference](18-library-reference.md#library-reference) chapter.
## <a id="dictionary-operators"></a> Assignments ## Assignments <a id="dictionary-operators"></a>
In addition to the `=` operator shown above a number of other operators In addition to the `=` operator shown above a number of other operators
to manipulate attributes are supported. Here's a list of all to manipulate attributes are supported. Here's a list of all
available operators: available operators:
### <a id="operator-assignment"></a> Operator = ### Operator = <a id="operator-assignment"></a>
Sets an attribute to the specified value. Sets an attribute to the specified value.
@ -222,7 +222,7 @@ Example:
In this example `a` has the value `7` after both instructions are executed. In this example `a` has the value `7` after both instructions are executed.
### <a id="operator-additive-assignment"></a> Operator += ### Operator += <a id="operator-additive-assignment"></a>
The += operator is a shortcut. The following expression: The += operator is a shortcut. The following expression:
@ -238,7 +238,7 @@ is equivalent to:
a = a + [ "world" ] a = a + [ "world" ]
} }
### <a id="operator-substractive-assignment"></a> Operator -= ### Operator -= <a id="operator-substractive-assignment"></a>
The -= operator is a shortcut. The following expression: The -= operator is a shortcut. The following expression:
@ -254,7 +254,7 @@ is equivalent to:
a = a - 5 a = a - 5
} }
### <a id="operator-multiply-assignment"></a> Operator \*= ### Operator \*= <a id="operator-multiply-assignment"></a>
The *= operator is a shortcut. The following expression: The *= operator is a shortcut. The following expression:
@ -270,7 +270,7 @@ is equivalent to:
a = a * 5 a = a * 5
} }
### <a id="operator-dividing-assignment"></a> Operator /= ### Operator /= <a id="operator-dividing-assignment"></a>
The /= operator is a shortcut. The following expression: The /= operator is a shortcut. The following expression:
@ -286,7 +286,7 @@ is equivalent to:
a = a / 5 a = a / 5
} }
## <a id="indexer"></a> Indexer ## Indexer <a id="indexer"></a>
The indexer syntax provides a convenient way to set dictionary elements. The indexer syntax provides a convenient way to set dictionary elements.
@ -312,7 +312,7 @@ This is equivalent to writing:
If the `hello` attribute does not already have a value, it is automatically initialized to an empty dictionary. If the `hello` attribute does not already have a value, it is automatically initialized to an empty dictionary.
## <a id="template-imports"></a> Template Imports ## Template Imports <a id="template-imports"></a>
Objects can import attributes from other objects. Objects can import attributes from other objects.
@ -359,7 +359,7 @@ object definition is evaluated.
If there are multiple default templates the order in which they are imported If there are multiple default templates the order in which they are imported
is unspecified. is unspecified.
## <a id="constants"></a> Constants ## Constants <a id="constants"></a>
Global constants can be set using the `const` keyword: Global constants can be set using the `const` keyword:
@ -368,7 +368,7 @@ Global constants can be set using the `const` keyword:
Once defined a constant can be accessed from any file. Constants cannot be changed Once defined a constant can be accessed from any file. Constants cannot be changed
once they are set. once they are set.
### <a id="icinga-constants"></a> Icinga 2 Specific Constants ### Icinga 2 Specific Constants <a id="icinga-constants"></a>
Icinga 2 provides a number of special global constants. Some of them can be overridden using the `--define` command line parameter: Icinga 2 provides a number of special global constants. Some of them can be overridden using the `--define` command line parameter:
@ -406,7 +406,7 @@ RLimitFiles |**Read-write.** Defines the resource limit for RLIMIT_NOFIL
RLimitProcesses |**Read-write.** Defines the resource limit for RLIMIT_NPROC that should be set at start-up. Value cannot be set lower than the default `16 * 1024`. 0 disables the setting. Used in the `init.conf` configuration file. RLimitProcesses |**Read-write.** Defines the resource limit for RLIMIT_NPROC that should be set at start-up. Value cannot be set lower than the default `16 * 1024`. 0 disables the setting. Used in the `init.conf` configuration file.
RLimitStack |**Read-write.** Defines the resource limit for RLIMIT_STACK that should be set at start-up. Value cannot be set lower than the default `256 * 1024`. 0 disables the setting. Used in the `init.conf` configuration file. RLimitStack |**Read-write.** Defines the resource limit for RLIMIT_STACK that should be set at start-up. Value cannot be set lower than the default `256 * 1024`. 0 disables the setting. Used in the `init.conf` configuration file.
## <a id="apply"></a> Apply ## Apply <a id="apply"></a>
The `apply` keyword can be used to create new objects which are associated with The `apply` keyword can be used to create new objects which are associated with
another group of objects. another group of objects.
@ -444,10 +444,10 @@ Any valid config attribute can be accessed using the `host` and `service`
variables. For example, `host.address` would return the value of the host's variables. For example, `host.address` would return the value of the host's
"address" attribute -- or null if that attribute isn't set. "address" attribute -- or null if that attribute isn't set.
More usage examples are documented in the [monitoring basics](3-monitoring-basics.md#using-apply-expressions) More usage examples are documented in the [monitoring basics](03-monitoring-basics.md#using-apply-expressions)
chapter. chapter.
## <a id="apply-for"></a> Apply For ## Apply For <a id="apply-for"></a>
[Apply](17-language-reference.md#apply) rules can be extended with the [Apply](17-language-reference.md#apply) rules can be extended with the
[for loop](17-language-reference.md#for-loops) keyword. [for loop](17-language-reference.md#for-loops) keyword.
@ -477,10 +477,10 @@ and afterwards the `assign where` and `ignore where` conditions are evaluated.
It is not necessary to check attributes referenced in the `for loop` expression It is not necessary to check attributes referenced in the `for loop` expression
for their existance using an additional `assign where` condition. for their existance using an additional `assign where` condition.
More usage examples are documented in the [monitoring basics](3-monitoring-basics.md#using-apply-for) More usage examples are documented in the [monitoring basics](03-monitoring-basics.md#using-apply-for)
chapter. chapter.
## <a id="group-assign"></a> Group Assign ## Group Assign <a id="group-assign"></a>
Group objects can be assigned to specific member objects using the `assign where` Group objects can be assigned to specific member objects using the `assign where`
and `ignore where` conditions. and `ignore where` conditions.
@ -504,7 +504,7 @@ ServiceGroup | host, service
UserGroup | user UserGroup | user
## <a id="boolean-values"></a> Boolean Values ## Boolean Values <a id="boolean-values"></a>
The `assign where`, `ignore where`, `if` and `while` statements, the `!` operator as The `assign where`, `ignore where`, `if` and `while` statements, the `!` operator as
well as the `bool()` function convert their arguments to a boolean value based on the well as the `bool()` function convert their arguments to a boolean value based on the
@ -525,7 +525,7 @@ Non-empty dictionary | { key = "value" } | true
For a list of supported expression operators for `assign where` and `ignore where` For a list of supported expression operators for `assign where` and `ignore where`
statements, see [expression operators](17-language-reference.md#expression-operators). statements, see [expression operators](17-language-reference.md#expression-operators).
## <a id="comments"></a> Comments ## Comments <a id="comments"></a>
The Icinga 2 configuration format supports C/C++-style and shell-style comments. The Icinga 2 configuration format supports C/C++-style and shell-style comments.
@ -539,7 +539,7 @@ Example:
retry_interval = 15 # yet another comment retry_interval = 15 # yet another comment
} }
## <a id="includes"></a> Includes ## Includes <a id="includes"></a>
Other configuration files can be included using the `include` directive. Other configuration files can be included using the `include` directive.
Paths must be relative to the configuration file that contains the Paths must be relative to the configuration file that contains the
@ -565,7 +565,7 @@ paths. Additional include search paths can be added using
Wildcards are not permitted when using angle brackets. Wildcards are not permitted when using angle brackets.
## <a id="recursive-includes"></a> Recursive Includes ## Recursive Includes <a id="recursive-includes"></a>
The `include_recursive` directive can be used to recursively include all The `include_recursive` directive can be used to recursively include all
files in a directory which match a certain pattern. files in a directory which match a certain pattern.
@ -581,7 +581,7 @@ recursively included.
The file names need to match the pattern given in the second parameter. The file names need to match the pattern given in the second parameter.
When no pattern is specified the default pattern "*.conf" is used. When no pattern is specified the default pattern "*.conf" is used.
## <a id="zone-includes"></a> Zone Includes ## Zone Includes <a id="zone-includes"></a>
The `include_zones` recursively includes all subdirectories for the The `include_zones` recursively includes all subdirectories for the
given path. given path.
@ -604,7 +604,7 @@ The second parameter specifies the directory which contains the subdirectories.
The file names need to match the pattern given in the third parameter. The file names need to match the pattern given in the third parameter.
When no pattern is specified the default pattern "*.conf" is used. When no pattern is specified the default pattern "*.conf" is used.
## <a id="library"></a> Library directive ## Library directive <a id="library"></a>
The `library` directive can be used to manually load additional The `library` directive can be used to manually load additional
libraries. Libraries can be used to provide additional object types and libraries. Libraries can be used to provide additional object types and
@ -614,7 +614,7 @@ Example:
library "snmphelper" library "snmphelper"
## <a id="functions"></a> Functions ## Functions <a id="functions"></a>
Functions can be defined using the `function` keyword. Functions can be defined using the `function` keyword.
@ -650,7 +650,7 @@ resulting function object can be used like any other value:
fn() /* Returns 3 */ fn() /* Returns 3 */
## <a id="lambdas"></a> Lambda Expressions ## Lambda Expressions <a id="lambdas"></a>
Functions can also be declared using the alternative lambda syntax. Functions can also be declared using the alternative lambda syntax.
@ -671,7 +671,7 @@ For lambdas which take exactly one argument the braces around the arguments can
f = x => x * x f = x => x * x
## <a id="nullary-lambdas"></a> Abbreviated Lambda Syntax ## Abbreviated Lambda Syntax <a id="nullary-lambdas"></a>
Lambdas which take no arguments can also be written using the abbreviated lambda syntax. Lambdas which take no arguments can also be written using the abbreviated lambda syntax.
@ -681,7 +681,7 @@ Example:
This creates a new function which returns the value 3. This creates a new function which returns the value 3.
## <a id="variable-scopes"></a> Variable Scopes ## Variable Scopes <a id="variable-scopes"></a>
When setting a variable Icinga checks the following scopes in this order whether the variable When setting a variable Icinga checks the following scopes in this order whether the variable
already exists there: already exists there:
@ -745,7 +745,7 @@ a function is set to whichever object was used to invoke the function. Here's an
We're using `hm.init` to invoke the function which causes the value of `hm` to become the `this` We're using `hm.init` to invoke the function which causes the value of `hm` to become the `this`
scope for this function call. scope for this function call.
## <a id="closures"></a> Closures ## Closures <a id="closures"></a>
By default `function`s, `object`s and `apply` rules do not have access to variables declared By default `function`s, `object`s and `apply` rules do not have access to variables declared
outside of their scope (except for global variables). outside of their scope (except for global variables).
@ -769,7 +769,7 @@ Alternatively a different value for the inner variable can be specified:
} }
} }
## <a id="conditional-statements"></a> Conditional Statements ## Conditional Statements <a id="conditional-statements"></a>
Sometimes it can be desirable to only evaluate statements when certain conditions are met. The if/else Sometimes it can be desirable to only evaluate statements when certain conditions are met. The if/else
construct can be used to accomplish this. construct can be used to accomplish this.
@ -801,7 +801,7 @@ This example prints the log message "Taking the 'true' branch" and the `a` varia
The value of an if/else construct is null if the condition evaluates to false and no else branch is given. The value of an if/else construct is null if the condition evaluates to false and no else branch is given.
## <a id="while-loops"></a> While Loops ## While Loops <a id="while-loops"></a>
The `while` statement checks a condition and executes the loop body when the condition evaluates to `true`. The `while` statement checks a condition and executes the loop body when the condition evaluates to `true`.
This is repeated until the condition is no longer true. This is repeated until the condition is no longer true.
@ -819,7 +819,7 @@ The `continue` and `break` keywords can be used to control how the loop is execu
skips over the remaining expressions for the loop body and begins the next loop evaluation. The `break` keyword skips over the remaining expressions for the loop body and begins the next loop evaluation. The `break` keyword
breaks out of the loop. breaks out of the loop.
## <a id="for-loops"></a> For Loops ## For Loops <a id="for-loops"></a>
The `for` statement can be used to iterate over arrays and dictionaries. The `for` statement can be used to iterate over arrays and dictionaries.
@ -846,7 +846,7 @@ The `continue` and `break` keywords can be used to control how the loop is execu
skips over the remaining expressions for the loop body and begins the next loop evaluation. The `break` keyword skips over the remaining expressions for the loop body and begins the next loop evaluation. The `break` keyword
breaks out of the loop. breaks out of the loop.
## <a id="constructor"></a> Constructors ## Constructors <a id="constructor"></a>
In order to create a new value of a specific type constructor calls may be used. In order to create a new value of a specific type constructor calls may be used.
@ -862,7 +862,7 @@ Example:
var s = String(3) /* Sets s to "3". */ var s = String(3) /* Sets s to "3". */
## <a id="throw"></a> Throwing Exceptions ## Throwing Exceptions <a id="throw"></a>
Built-in commands may throw exceptions to signal errors such as invalid arguments. User scripts can throw exceptions Built-in commands may throw exceptions to signal errors such as invalid arguments. User scripts can throw exceptions
using the `throw` keyword. using the `throw` keyword.
@ -871,7 +871,7 @@ Example:
throw "An error occurred." throw "An error occurred."
## <a id="try-except"></a> Handling Exceptions ## Handling Exceptions <a id="try-except"></a>
Exceptions can be handled using the `try` and `except` keywords. When an exception occurs while executing code in the Exceptions can be handled using the `try` and `except` keywords. When an exception occurs while executing code in the
`try` clause no further statements in the `try` clause are evaluated and the `except` clause is executed instead. `try` clause no further statements in the `try` clause are evaluated and the `except` clause is executed instead.
@ -886,13 +886,13 @@ Example:
log("An error occurred in the try clause.") log("An error occurred in the try clause.")
} }
## <a id="breakpoints"></a> Breakpoints ## Breakpoints <a id="breakpoints"></a>
The `debugger` keyword can be used to insert a breakpoint. It may be used at any place where an assignment would also be a valid expression. The `debugger` keyword can be used to insert a breakpoint. It may be used at any place where an assignment would also be a valid expression.
By default breakpoints have no effect unless Icinga is started with the `--script-debugger` command-line option. When the script debugger is enabled Icinga stops execution of the script when it encounters a breakpoint and spawns a console which lets the user inspect the current state of the execution environment. By default breakpoints have no effect unless Icinga is started with the `--script-debugger` command-line option. When the script debugger is enabled Icinga stops execution of the script when it encounters a breakpoint and spawns a console which lets the user inspect the current state of the execution environment.
## <a id="types"></a> Types ## Types <a id="types"></a>
All values have a static type. The `typeof` function can be used to determine the type of a value: All values have a static type. The `typeof` function can be used to determine the type of a value:
@ -909,7 +909,7 @@ Array | [ "a", "b" ] | An array.
Dictionary | { a = 3 } | A dictionary. Dictionary | { a = 3 } | A dictionary.
Depending on which libraries are loaded additional types may become available. The `icinga` Depending on which libraries are loaded additional types may become available. The `icinga`
library implements a whole bunch of other [object types](9-object-types.md#object-types), library implements a whole bunch of other [object types](09-object-types.md#object-types),
e.g. Host, Service, CheckCommand, etc. e.g. Host, Service, CheckCommand, etc.
Each type has an associated type object which describes the type's semantics. These Each type has an associated type object which describes the type's semantics. These
@ -927,7 +927,7 @@ supports:
Additional documentation on type methods is available in the Additional documentation on type methods is available in the
[library reference](18-library-reference.md#library-reference). [library reference](18-library-reference.md#library-reference).
## <a id="location-information"></a> Location Information ## Location Information <a id="location-information"></a>
The location of the currently executing script can be obtained using the The location of the currently executing script can be obtained using the
`current_filename` and `current_line` keywords. `current_filename` and `current_line` keywords.
@ -936,7 +936,7 @@ Example:
log("Hello from '" + current_filename + "' in line " + current_line) log("Hello from '" + current_filename + "' in line " + current_line)
## <a id="reserved-keywords"></a> Reserved Keywords ## Reserved Keywords <a id="reserved-keywords"></a>
These keywords are reserved and must not be used as constants or custom attributes. These keywords are reserved and must not be used as constants or custom attributes.

258
doc/18-library-reference.md
View File

@ -1,8 +1,8 @@
# <a id="library-reference"></a> Library Reference # Library Reference <a id="library-reference"></a>
## <a id="global-functions"></a> Global functions ## Global functions <a id="global-functions"></a>
These functions are globally available in [assign/ignore where expressions](3-monitoring-basics.md#using-apply-expressions), These functions are globally available in [assign/ignore where expressions](03-monitoring-basics.md#using-apply-expressions),
[functions](17-language-reference.md#functions), [API filters](12-icinga2-api.md#icinga2-api-filters) [functions](17-language-reference.md#functions), [API filters](12-icinga2-api.md#icinga2-api-filters)
and the [Icinga 2 debug console](11-cli-commands.md#cli-command-console). and the [Icinga 2 debug console](11-cli-commands.md#cli-command-console).
@ -10,7 +10,7 @@ You can use the [Icinga 2 debug console](11-cli-commands.md#cli-command-console)
as a sandbox to test these functions before implementing as a sandbox to test these functions before implementing
them in your scenarios. them in your scenarios.
### <a id="global-functions-regex"></a> regex ### regex <a id="global-functions-regex"></a>
Signature: Signature:
@ -33,7 +33,7 @@ Example:
<3> => regex("^Linux$", host.vars.os_type) <3> => regex("^Linux$", host.vars.os_type)
false false
### <a id="global-functions-match"></a> match ### match <a id="global-functions-match"></a>
Signature: Signature:
@ -56,7 +56,7 @@ Example:
<4> => match("NUE-*-DEV-*", host.display_name) <4> => match("NUE-*-DEV-*", host.display_name)
false false
### <a id="global-functions-cidr_match"></a> cidr_match ### cidr_match <a id="global-functions-cidr_match"></a>
Signature: Signature:
@ -80,7 +80,7 @@ Example:
<3> => cidr_match("192.168.56.0/26", host.address) <3> => cidr_match("192.168.56.0/26", host.address)
false false
### <a id="global-functions-range"></a> range ### range <a id="global-functions-range"></a>
Signature: Signature:
@ -109,7 +109,7 @@ Example:
<3> => range(2,10,2) <3> => range(2,10,2)
[ 2.000000, 4.000000, 6.000000, 8.000000 ] [ 2.000000, 4.000000, 6.000000, 8.000000 ]
### <a id="global-functions-len"></a> len ### len <a id="global-functions-len"></a>
Signature: Signature:
@ -142,7 +142,7 @@ Example:
10.000000 10.000000
### <a id="global-functions-union"></a> union ### union <a id="global-functions-union"></a>
Signature: Signature:
@ -161,7 +161,7 @@ Example:
<3> => union(dev_notification_groups, host_notification_groups) <3> => union(dev_notification_groups, host_notification_groups)
[ "devs", "noc", "slack" ] [ "devs", "noc", "slack" ]
### <a id="global-functions-intersection"></a> intersection ### intersection <a id="global-functions-intersection"></a>
Signature: Signature:
@ -181,7 +181,7 @@ Example:
<3> => intersection(dev_notification_groups, host_notification_groups) <3> => intersection(dev_notification_groups, host_notification_groups)
[ "slack" ] [ "slack" ]
### <a id="global-functions-keys"></a> keys ### keys <a id="global-functions-keys"></a>
Signature: Signature:
@ -203,7 +203,7 @@ Example:
<3> => host.vars.disks.keys() <3> => host.vars.disks.keys()
[ "/", "/var" ] [ "/", "/var" ]
### <a id="global-functions-string"></a> string ### string <a id="global-functions-string"></a>
Signature: Signature:
@ -237,7 +237,7 @@ Example:
<6> => DateTime(2016, 11, 25).to_string() <6> => DateTime(2016, 11, 25).to_string()
"2016-11-25 00:00:00 +0100" "2016-11-25 00:00:00 +0100"
### <a id="global-functions-number"></a> number ### number <a id="global-functions-number"></a>
Signature: Signature:
@ -254,7 +254,7 @@ Example:
<2> => number("78") <2> => number("78")
78.000000 78.000000
### <a id="global-functions-bool"></a> bool ### bool <a id="global-functions-bool"></a>
Signature: Signature:
@ -271,7 +271,7 @@ Example:
<2> => bool(0) <2> => bool(0)
false false
### <a id="global-functions-random"></a> random ### random <a id="global-functions-random"></a>
Signature: Signature:
@ -286,7 +286,7 @@ Returns a random value between 0 and RAND\_MAX (as defined in stdlib.h).
<2> => random() <2> => random()
108402530.000000 108402530.000000
### <a id="global-functions-log"></a> log ### log <a id="global-functions-log"></a>
Signature: Signature:
@ -316,7 +316,7 @@ Example:
critical/Console: ["devs","slack"] critical/Console: ["devs","slack"]
null null
### <a id="global-functions-typeof"></a> typeof ### typeof <a id="global-functions-typeof"></a>
Signature: Signature:
@ -339,7 +339,7 @@ Example:
<5> => typeof({ a = 2, b = 3 }) == Dictionary <5> => typeof({ a = 2, b = 3 }) == Dictionary
true true
### <a id="global-functions-get_time"></a> get_time ### get_time <a id="global-functions-get_time"></a>
Signature: Signature:
@ -356,7 +356,7 @@ Example:
<2> => get_time() <2> => get_time()
1480072140.401207 1480072140.401207
### <a id="global-functions-parse_performance_data"></a> parse_performance_data ### parse_performance_data <a id="global-functions-parse_performance_data"></a>
Signature: Signature:
@ -383,7 +383,7 @@ Example:
warn = null warn = null
} }
### <a id="global-functions-dirname"></a> dirname ### dirname <a id="global-functions-dirname"></a>
Signature: Signature:
@ -400,7 +400,7 @@ Example:
<2> => dirname(path) <2> => dirname(path)
"/etc/icinga2/scripts" "/etc/icinga2/scripts"
### <a id="global-functions-basename"></a> basename ### basename <a id="global-functions-basename"></a>
Signature: Signature:
@ -417,7 +417,7 @@ Example:
<2> => basename(path) <2> => basename(path)
"xmpp-notification.pl" "xmpp-notification.pl"
### <a id="global-functions-escape_shell_arg"></a> escape_shell_arg ### escape_shell_arg <a id="global-functions-escape_shell_arg"></a>
Signature: Signature:
@ -432,7 +432,7 @@ Example:
<1> => escape_shell_arg("'$host.name$' '$service.name$'") <1> => escape_shell_arg("'$host.name$' '$service.name$'")
"''\\''$host.name$'\\'' '\\''$service.name$'\\'''" "''\\''$host.name$'\\'' '\\''$service.name$'\\'''"
### <a id="global-functions-escape_shell_cmd"></a> escape_shell_cmd ### escape_shell_cmd <a id="global-functions-escape_shell_cmd"></a>
Signature: Signature:
@ -447,7 +447,7 @@ Example:
<1> => escape_shell_cmd("/bin/echo 'shell test' $ENV") <1> => escape_shell_cmd("/bin/echo 'shell test' $ENV")
"/bin/echo 'shell test' \\$ENV" "/bin/echo 'shell test' \\$ENV"
### <a id="global-functions-escape_create_process_arg"></a> escape_create_process_arg ### escape_create_process_arg <a id="global-functions-escape_create_process_arg"></a>
Signature: Signature:
@ -455,7 +455,7 @@ Signature:
Escapes a string for use as an argument for CreateProcess(). Windows only. Escapes a string for use as an argument for CreateProcess(). Windows only.
### <a id="global-functions-sleep"></a> sleep ### sleep <a id="global-functions-sleep"></a>
Signature: Signature:
@ -463,11 +463,11 @@ Signature:
Sleeps for the specified amount of time (in seconds). Sleeps for the specified amount of time (in seconds).
## <a id="object-accessor-functions"></a> Object Accessor Functions ## Object Accessor Functions <a id="object-accessor-functions"></a>
These functions can be used to retrieve a reference to another object by name. These functions can be used to retrieve a reference to another object by name.
### <a id="objref-get_check_command"></a> get_check_command ### get_check_command <a id="objref-get_check_command"></a>
Signature: Signature:
@ -475,7 +475,7 @@ Signature:
Returns the CheckCommand object with the specified name, or `null` if no such CheckCommand object exists. Returns the CheckCommand object with the specified name, or `null` if no such CheckCommand object exists.
### <a id="objref-get_event_command"></a> get_event_command ### get_event_command <a id="objref-get_event_command"></a>
Signature: Signature:
@ -483,7 +483,7 @@ Signature:
Returns the EventCommand object with the specified name, or `null` if no such EventCommand object exists. Returns the EventCommand object with the specified name, or `null` if no such EventCommand object exists.
### <a id="objref-get_notification_command"></a> get_notification_command ### get_notification_command <a id="objref-get_notification_command"></a>
Signature: Signature:
@ -491,7 +491,7 @@ Signature:
Returns the NotificationCommand object with the specified name, or `null` if no such NotificationCommand object exists. Returns the NotificationCommand object with the specified name, or `null` if no such NotificationCommand object exists.
### <a id="objref-get_host"></a> get_host ### get_host <a id="objref-get_host"></a>
Signature: Signature:
@ -500,7 +500,7 @@ Signature:
Returns the Host object with the specified name, or `null` if no such Host object exists. Returns the Host object with the specified name, or `null` if no such Host object exists.
### <a id="objref-get_service"></a> get_service ### get_service <a id="objref-get_service"></a>
Signature: Signature:
@ -509,7 +509,7 @@ Signature:
Returns the Service object with the specified name, or `null` if no such Service object exists. Returns the Service object with the specified name, or `null` if no such Service object exists.
### <a id="objref-get_user"></a> get_user ### get_user <a id="objref-get_user"></a>
Signature: Signature:
@ -517,7 +517,7 @@ Signature:
Returns the User object with the specified name, or `null` if no such User object exists. Returns the User object with the specified name, or `null` if no such User object exists.
### <a id="objref-get_host_group"></a> get_host_group ### get_host_group <a id="objref-get_host_group"></a>
Signature: Signature:
@ -526,7 +526,7 @@ Signature:
Returns the HostGroup object with the specified name, or `null` if no such HostGroup object exists. Returns the HostGroup object with the specified name, or `null` if no such HostGroup object exists.
### <a id="objref-get_service_group"></a> get_service_group ### get_service_group <a id="objref-get_service_group"></a>
Signature: Signature:
@ -534,7 +534,7 @@ Signature:
Returns the ServiceGroup object with the specified name, or `null` if no such ServiceGroup object exists. Returns the ServiceGroup object with the specified name, or `null` if no such ServiceGroup object exists.
### <a id="objref-get_user_group"></a> get_user_group ### get_user_group <a id="objref-get_user_group"></a>
Signature: Signature:
@ -543,7 +543,7 @@ Signature:
Returns the UserGroup object with the specified name, or `null` if no such UserGroup object exists. Returns the UserGroup object with the specified name, or `null` if no such UserGroup object exists.
### <a id="objref-get_time_period"></a> get_time_period ### get_time_period <a id="objref-get_time_period"></a>
Signature: Signature:
@ -552,7 +552,7 @@ Signature:
Returns the TimePeriod object with the specified name, or `null` if no such TimePeriod object exists. Returns the TimePeriod object with the specified name, or `null` if no such TimePeriod object exists.
### <a id="objref-get_object"></a> get_object ### get_object <a id="objref-get_object"></a>
Signature: Signature:
@ -562,7 +562,7 @@ Returns the object with the specified type and name, or `null` if no such object
to a type object. to a type object.
### <a id="objref-get_objects"></a> get_objects ### get_objects <a id="objref-get_objects"></a>
Signature: Signature:
@ -572,40 +572,40 @@ Returns an array of objects whose type matches the specified type. `type` must r
to a type object. to a type object.
## <a id="math-object"></a> Math object ## Math object <a id="math-object"></a>
The global `Math` object can be used to access a number of mathematical constants The global `Math` object can be used to access a number of mathematical constants
and functions. and functions.
### <a id="math-e"></a> Math.E ### Math.E <a id="math-e"></a>
Euler's constant. Euler's constant.
### <a id="math-ln2"></a> Math.LN2 ### Math.LN2 <a id="math-ln2"></a>
Natural logarithm of 2. Natural logarithm of 2.
### <a id="math-ln10"></a> Math.LN10 ### Math.LN10 <a id="math-ln10"></a>
Natural logarithm of 10. Natural logarithm of 10.
### <a id="math-log2e"></a> Math.LOG2E ### Math.LOG2E <a id="math-log2e"></a>
Base 2 logarithm of E. Base 2 logarithm of E.
### <a id="math-pi"></a> Math.PI ### Math.PI <a id="math-pi"></a>
The mathematical constant Pi. The mathematical constant Pi.
### <a id="math-sqrt1_2"></a> Math.SQRT1_2 ### Math.SQRT1_2 <a id="math-sqrt1_2"></a>
Square root of 1/2. Square root of 1/2.
### <a id="math-sqrt2"></a> Math.SQRT2 ### Math.SQRT2 <a id="math-sqrt2"></a>
Square root of 2. Square root of 2.
### <a id="math-abs"></a> Math.abs ### Math.abs <a id="math-abs"></a>
Signature: Signature:
@ -613,7 +613,7 @@ Signature:
Returns the absolute value of `x`. Returns the absolute value of `x`.
### <a id="math-acos"></a> Math.acos ### Math.acos <a id="math-acos"></a>
Signature: Signature:
@ -621,7 +621,7 @@ Signature:
Returns the arccosine of `x`. Returns the arccosine of `x`.
### <a id="math-asin"></a> Math.asin ### Math.asin <a id="math-asin"></a>
Signature: Signature:
@ -629,7 +629,7 @@ Signature:
Returns the arcsine of `x`. Returns the arcsine of `x`.
### <a id="math-atan"></a> Math.atan ### Math.atan <a id="math-atan"></a>
Signature: Signature:
@ -637,7 +637,7 @@ Signature:
Returns the arctangent of `x`. Returns the arctangent of `x`.
### <a id="math-atan2"></a> Math.atan2 ### Math.atan2 <a id="math-atan2"></a>
Signature: Signature:
@ -645,7 +645,7 @@ Signature:
Returns the arctangent of the quotient of `y` and `x`. Returns the arctangent of the quotient of `y` and `x`.
### <a id="math-ceil"></a> Math.ceil ### Math.ceil <a id="math-ceil"></a>
Signature: Signature:
@ -653,7 +653,7 @@ Signature:
Returns the smallest integer value not less than `x`. Returns the smallest integer value not less than `x`.
### <a id="math-cos"></a> Math.cos ### Math.cos <a id="math-cos"></a>
Signature: Signature:
@ -661,7 +661,7 @@ Signature:
Returns the cosine of `x`. Returns the cosine of `x`.
### <a id="math-exp"></a> Math.exp ### Math.exp <a id="math-exp"></a>
Signature: Signature:
@ -669,7 +669,7 @@ Signature:
Returns E raised to the `x`th power. Returns E raised to the `x`th power.
### <a id="math-floor"></a> Math.floor ### Math.floor <a id="math-floor"></a>
Signature: Signature:
@ -677,7 +677,7 @@ Signature:
Returns the largest integer value not greater than `x`. Returns the largest integer value not greater than `x`.
### <a id="math-isinf"></a> Math.isinf ### Math.isinf <a id="math-isinf"></a>
Signature: Signature:
@ -685,7 +685,7 @@ Signature:
Returns whether `x` is infinite. Returns whether `x` is infinite.
### <a id="math-isnan"></a> Math.isnan ### Math.isnan <a id="math-isnan"></a>
Signature: Signature:
@ -693,7 +693,7 @@ Signature:
Returns whether `x` is NaN (not-a-number). Returns whether `x` is NaN (not-a-number).
### <a id="math-log"></a> Math.log ### Math.log <a id="math-log"></a>
Signature: Signature:
@ -701,7 +701,7 @@ Signature:
Returns the natural logarithm of `x`. Returns the natural logarithm of `x`.
### <a id="math-max"></a> Math.max ### Math.max <a id="math-max"></a>
Signature: Signature:
@ -710,7 +710,7 @@ Signature:
Returns the largest argument. A variable number of arguments can be specified. Returns the largest argument. A variable number of arguments can be specified.
If no arguments are given, -Infinity is returned. If no arguments are given, -Infinity is returned.
### <a id="math-min"></a> Math.min ### Math.min <a id="math-min"></a>
Signature: Signature:
@ -719,7 +719,7 @@ Signature:
Returns the smallest argument. A variable number of arguments can be specified. Returns the smallest argument. A variable number of arguments can be specified.
If no arguments are given, +Infinity is returned. If no arguments are given, +Infinity is returned.
### <a id="math-pow"></a> Math.pow ### Math.pow <a id="math-pow"></a>
Signature: Signature:
@ -727,7 +727,7 @@ Signature:
Returns `x` raised to the `y`th power. Returns `x` raised to the `y`th power.
### <a id="math-random"></a> Math.random ### Math.random <a id="math-random"></a>
Signature: Signature:
@ -735,7 +735,7 @@ Signature:
Returns a pseudo-random number between 0 and 1. Returns a pseudo-random number between 0 and 1.
### <a id="math-round"></a> Math.round ### Math.round <a id="math-round"></a>
Signature: Signature:
@ -743,7 +743,7 @@ Signature:
Returns `x` rounded to the nearest integer value. Returns `x` rounded to the nearest integer value.
### <a id="math-sign"></a> Math.sign ### Math.sign <a id="math-sign"></a>
Signature: Signature:
@ -752,7 +752,7 @@ Signature:
Returns -1 if `x` is negative, 1 if `x` is positive Returns -1 if `x` is negative, 1 if `x` is positive
and 0 if `x` is 0. and 0 if `x` is 0.
### <a id="math-sin"></a> Math.sin ### Math.sin <a id="math-sin"></a>
Signature: Signature:
@ -760,7 +760,7 @@ Signature:
Returns the sine of `x`. Returns the sine of `x`.
### <a id="math-sqrt"></a> Math.sqrt ### Math.sqrt <a id="math-sqrt"></a>
Signature: Signature:
@ -768,7 +768,7 @@ Signature:
Returns the square root of `x`. Returns the square root of `x`.
### <a id="math-tan"></a> Math.tan ### Math.tan <a id="math-tan"></a>
Signature: Signature:
@ -776,11 +776,11 @@ Signature:
Returns the tangent of `x`. Returns the tangent of `x`.
## <a id="json-object"></a> Json object ## Json object <a id="json-object"></a>
The global `Json` object can be used to encode and decode JSON. The global `Json` object can be used to encode and decode JSON.
### <a id="json-encode"></a> Json.encode ### Json.encode <a id="json-encode"></a>
Signature: Signature:
@ -788,7 +788,7 @@ Signature:
Encodes an arbitrary value into JSON. Encodes an arbitrary value into JSON.
### <a id="json-decode"></a> Json.decode ### Json.decode <a id="json-decode"></a>
Signature: Signature:
@ -796,9 +796,9 @@ Signature:
Decodes a JSON string. Decodes a JSON string.
## <a id="number-type"></a> Number type ## Number type <a id="number-type"></a>
### <a id="number-to_string"></a> Number#to_string ### Number#to_string <a id="number-to_string"></a>
Signature: Signature:
@ -811,9 +811,9 @@ Example:
var example = 7 var example = 7
example.to_string() /* Returns "7" */ example.to_string() /* Returns "7" */
## <a id="boolean-type"></a> Boolean type ## Boolean type <a id="boolean-type"></a>
### <a id="boolean-to_string"></a> Boolean#to_string ### Boolean#to_string <a id="boolean-to_string"></a>
Signature: Signature:
@ -826,9 +826,9 @@ Example:
var example = true var example = true
example.to_string() /* Returns "true" */ example.to_string() /* Returns "true" */
## <a id="string-type"></a> String type ## String type <a id="string-type"></a>
### <a id="string-find"></a> String#find ### String#find <a id="string-find"></a>
Signature: Signature:
@ -842,7 +842,7 @@ Example:
"Hello World".find("World") /* Returns 6 */ "Hello World".find("World") /* Returns 6 */
### <a id="string-contains"></a> String#contains ### String#contains <a id="string-contains"></a>
Signature: Signature:
@ -856,7 +856,7 @@ Example:
"Hello World".contains("World") /* Returns true */ "Hello World".contains("World") /* Returns true */
### <a id="string-len"></a> String#len ### String#len <a id="string-len"></a>
Signature Signature
@ -869,7 +869,7 @@ Example:
"Hello World".len() /* Returns 11 */ "Hello World".len() /* Returns 11 */
### <a id="string-lower"></a> String#lower ### String#lower <a id="string-lower"></a>
Signature: Signature:
@ -881,7 +881,7 @@ Example:
"Hello World".lower() /* Returns "hello world" */ "Hello World".lower() /* Returns "hello world" */
### <a id="string-upper"></a> String#upper ### String#upper <a id="string-upper"></a>
Signature: Signature:
@ -893,7 +893,7 @@ Example:
"Hello World".upper() /* Returns "HELLO WORLD" */ "Hello World".upper() /* Returns "HELLO WORLD" */
### <a id="string-replace"></a> String#replace ### String#replace <a id="string-replace"></a>
Signature: Signature:
@ -902,7 +902,7 @@ Signature:
Returns a copy of the string with all occurences of the string specified in `search` replaced Returns a copy of the string with all occurences of the string specified in `search` replaced
with the string specified in `replacement`. with the string specified in `replacement`.
### <a id="string-split"></a> String#split ### String#split <a id="string-split"></a>
Signature: Signature:
@ -915,7 +915,7 @@ Example:
"x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */ "x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */
### <a id="string-substr"></a> String#substr ### String#substr <a id="string-substr"></a>
Signature: Signature:
@ -928,7 +928,7 @@ Example:
"Hello World".substr(6) /* Returns "World" */ "Hello World".substr(6) /* Returns "World" */
### <a id="string-to_string"></a> String#to_string ### String#to_string <a id="string-to_string"></a>
Signature: Signature:
@ -936,7 +936,7 @@ Signature:
Returns a copy of the string. Returns a copy of the string.
### <a id="string-reverse"></a> String#reverse ### String#reverse <a id="string-reverse"></a>
Signature: Signature:
@ -944,7 +944,7 @@ Signature:
Returns a copy of the string in reverse order. Returns a copy of the string in reverse order.
### <a id="string-trim"></a> String#trim ### String#trim <a id="string-trim"></a>
Signature: Signature:
@ -952,11 +952,11 @@ Signature:
Removes trailing whitespaces and returns the string. Removes trailing whitespaces and returns the string.
## <a id="object-type"></a> Object type ## Object type <a id="object-type"></a>
This is the base type for all types in the Icinga application. This is the base type for all types in the Icinga application.
### <a id="object-clone"></a> Object#clone ### Object#clone <a id="object-clone"></a>
Signature: Signature:
@ -966,7 +966,7 @@ Returns a copy of the object. Note that for object elements which are
reference values (e.g. objects such as arrays or dictionaries) the entire reference values (e.g. objects such as arrays or dictionaries) the entire
object is recursively copied. object is recursively copied.
### <a id="object-to-string"></a> Object#to_string ### Object#to_string <a id="object-to-string"></a>
Signature: Signature:
@ -980,7 +980,7 @@ Example:
[ 3, true ].to_string() /* Returns "[ 3.000000, true ]" */ [ 3, true ].to_string() /* Returns "[ 3.000000, true ]" */
### <a id="object-type-field"></a> Object#type ### Object#type <a id="object-type-field"></a>
Signature: Signature:
@ -992,7 +992,7 @@ Example:
get_host("localhost").type /* Returns "Host" */ get_host("localhost").type /* Returns "Host" */
## <a id="type-type"></a> Type type ## Type type <a id="type-type"></a>
Inherits methods from the [Object type](18-library-reference.md#object-type). Inherits methods from the [Object type](18-library-reference.md#object-type).
@ -1000,7 +1000,7 @@ The `Type` type provides information about the underlying type of an object or s
All types are registered as global variables. For example, in order to obtain a reference to the `String` type the global variable `String` can be used. All types are registered as global variables. For example, in order to obtain a reference to the `String` type the global variable `String` can be used.
### <a id="type-base"></a> Type#base ### Type#base <a id="type-base"></a>
Signature: Signature:
@ -1012,7 +1012,7 @@ Example:
Dictionary.base == Object /* Returns true, because the Dictionary type inherits directly from the Object type. */ Dictionary.base == Object /* Returns true, because the Dictionary type inherits directly from the Object type. */
### <a id="type-name"></a> Type#name ### Type#name <a id="type-name"></a>
Signature: Signature:
@ -1020,7 +1020,7 @@ Signature:
Returns the name of the type. Returns the name of the type.
### <a id="type-prototype"></a> Type#prototype ### Type#prototype <a id="type-prototype"></a>
Signature: Signature:
@ -1034,11 +1034,11 @@ Example:
3.to_string() /* Even though '3' does not have a to_string property the Number type's prototype object does. */ 3.to_string() /* Even though '3' does not have a to_string property the Number type's prototype object does. */
## <a id="array-type"></a> Array type ## Array type <a id="array-type"></a>
Inherits methods from the [Object type](18-library-reference.md#object-type). Inherits methods from the [Object type](18-library-reference.md#object-type).
### <a id="array-add"></a> Array#add ### Array#add <a id="array-add"></a>
Signature: Signature:
@ -1046,7 +1046,7 @@ Signature:
Adds a new value after the last element in the array. Adds a new value after the last element in the array.
### <a id="array-clear"></a> Array#clear ### Array#clear <a id="array-clear"></a>
Signature: Signature:
@ -1054,14 +1054,14 @@ Signature:
Removes all elements from the array. Removes all elements from the array.
### <a id="array-shallow-clone"></a> Array#shallow_clone ### Array#shallow_clone <a id="array-shallow-clone"></a>
function shallow_clone(); function shallow_clone();
Returns a copy of the array. Note that for elements which are reference values (e.g. objects such Returns a copy of the array. Note that for elements which are reference values (e.g. objects such
as arrays and dictionaries) only the references are copied. as arrays and dictionaries) only the references are copied.
### <a id="array-contains"></a> Array#contains ### Array#contains <a id="array-contains"></a>
Signature: Signature:
@ -1069,7 +1069,7 @@ Signature:
Returns true if the array contains the specified value, false otherwise. Returns true if the array contains the specified value, false otherwise.
### <a id="array-len"></a> Array#len ### Array#len <a id="array-len"></a>
Signature: Signature:
@ -1077,7 +1077,7 @@ Signature:
Returns the number of elements contained in the array. Returns the number of elements contained in the array.
### <a id="array-remove"></a> Array#remove ### Array#remove <a id="array-remove"></a>
Signature: Signature:
@ -1085,7 +1085,7 @@ Signature:
Removes the element at the specified zero-based index. Removes the element at the specified zero-based index.
### <a id="array-set"></a> Array#set ### Array#set <a id="array-set"></a>
Signature: Signature:
@ -1094,7 +1094,7 @@ Signature:
Sets the element at the zero-based index to the specified value. The `index` must refer to an element Sets the element at the zero-based index to the specified value. The `index` must refer to an element
which already exists in the array. which already exists in the array.
### <a id="array-get"></a> Array#get ### Array#get <a id="array-get"></a>
Signature: Signature:
@ -1102,7 +1102,7 @@ Signature:
Retrieves the element at the specified zero-based index. Retrieves the element at the specified zero-based index.
### <a id="array-sort"></a> Array#sort ### Array#sort <a id="array-sort"></a>
Signature: Signature:
@ -1112,7 +1112,7 @@ Returns a copy of the array where all items are sorted. The items are
compared using the `<` (less-than) operator. A custom comparator function compared using the `<` (less-than) operator. A custom comparator function
can be specified with the `less_cmp` argument. can be specified with the `less_cmp` argument.
### <a id="array-join"></a> Array#join ### Array#join <a id="array-join"></a>
Signature: Signature:
@ -1120,7 +1120,7 @@ Signature:
Joins all elements of the array using the specified separator. Joins all elements of the array using the specified separator.
### <a id="array-reverse"></a> Array#reverse ### Array#reverse <a id="array-reverse"></a>
Signature: Signature:
@ -1128,7 +1128,7 @@ Signature:
Returns a new array with all elements of the current array in reverse order. Returns a new array with all elements of the current array in reverse order.
### <a id="array-map"></a> Array#map ### Array#map <a id="array-map"></a>
Signature: Signature:
@ -1137,7 +1137,7 @@ Signature:
Calls `func(element)` for each of the elements in the array and returns Calls `func(element)` for each of the elements in the array and returns
a new array containing the return values of these function calls. a new array containing the return values of these function calls.
### <a id="array-reduce"></a> Array#reduce ### Array#reduce <a id="array-reduce"></a>
Signature: Signature:
@ -1147,7 +1147,7 @@ Reduces the elements of the array into a single value by calling the provided
function `func` as `func(a, b)` repeatedly where `a` and `b` are elements of the array function `func` as `func(a, b)` repeatedly where `a` and `b` are elements of the array
or results from previous function calls. or results from previous function calls.
### <a id="array-filter"></a> Array#filter ### Array#filter <a id="array-filter"></a>
Signature: Signature:
@ -1156,7 +1156,7 @@ Signature:
Returns a copy of the array containing only the elements for which `func(element)` Returns a copy of the array containing only the elements for which `func(element)`
is true. is true.
### <a id="array-any"></a> Array#any ### Array#any <a id="array-any"></a>
Signature: Signature:
@ -1165,7 +1165,7 @@ Signature:
Returns true if the array contains at least one element for which `func(element)` Returns true if the array contains at least one element for which `func(element)`
is true, false otherwise. is true, false otherwise.
### <a id="array-all"></a> Array#all ### Array#all <a id="array-all"></a>
Signature: Signature:
@ -1174,7 +1174,7 @@ Signature:
Returns true if the array contains only elements for which `func(element)` Returns true if the array contains only elements for which `func(element)`
is true, false otherwise. is true, false otherwise.
### <a id="array-unique"></a> Array#unique ### Array#unique <a id="array-unique"></a>
Signature: Signature:
@ -1183,11 +1183,11 @@ Signature:
Returns a copy of the array with all duplicate elements removed. The original order Returns a copy of the array with all duplicate elements removed. The original order
of the array is not preserved. of the array is not preserved.
## <a id="dictionary-type"></a> Dictionary type ## Dictionary type <a id="dictionary-type"></a>
Inherits methods from the [Object type](18-library-reference.md#object-type). Inherits methods from the [Object type](18-library-reference.md#object-type).
### <a id="dictionary-shallow-clone"></a> Dictionary#shallow_clone ### Dictionary#shallow_clone <a id="dictionary-shallow-clone"></a>
Signature: Signature:
@ -1196,7 +1196,7 @@ Signature:
Returns a copy of the dictionary. Note that for elements which are reference values (e.g. objects such Returns a copy of the dictionary. Note that for elements which are reference values (e.g. objects such
as arrays and dictionaries) only the references are copied. as arrays and dictionaries) only the references are copied.
### <a id="dictionary-contains"></a> Dictionary#contains ### Dictionary#contains <a id="dictionary-contains"></a>
Signature: Signature:
@ -1204,7 +1204,7 @@ Signature:
Returns true if a dictionary item with the specified `key` exists, false otherwise. Returns true if a dictionary item with the specified `key` exists, false otherwise.
### <a id="dictionary-len"></a> Dictionary#len ### Dictionary#len <a id="dictionary-len"></a>
Signature: Signature:
@ -1212,7 +1212,7 @@ Signature:
Returns the number of items contained in the dictionary. Returns the number of items contained in the dictionary.
### <a id="dictionary-remove"></a> Dictionary#remove ### Dictionary#remove <a id="dictionary-remove"></a>
Signature: Signature:
@ -1221,7 +1221,7 @@ Signature:
Removes the item with the specified `key`. Trying to remove an item which does not exist Removes the item with the specified `key`. Trying to remove an item which does not exist
is a no-op. is a no-op.
### <a id="dictionary-set"></a> Dictionary#set ### Dictionary#set <a id="dictionary-set"></a>
Signature: Signature:
@ -1229,7 +1229,7 @@ Signature:
Creates or updates an item with the specified `key` and `value`. Creates or updates an item with the specified `key` and `value`.
### <a id="dictionary-get"></a> Dictionary#get ### Dictionary#get <a id="dictionary-get"></a>
Signature: Signature:
@ -1238,7 +1238,7 @@ Signature:
Retrieves the value for the specified `key`. Returns `null` if they `key` does not exist Retrieves the value for the specified `key`. Returns `null` if they `key` does not exist
in the dictionary. in the dictionary.
### <a id="dictionary-keys"></a> Dictionary#keys ### Dictionary#keys <a id="dictionary-keys"></a>
Signature: Signature:
@ -1246,7 +1246,7 @@ Signature:
Returns a list of keys for all items that are currently in the dictionary. Returns a list of keys for all items that are currently in the dictionary.
### <a id="dictionary-values"></a> Dictionary#values ### Dictionary#values <a id="dictionary-values"></a>
Signature: Signature:
@ -1254,11 +1254,11 @@ Signature:
Returns a list of values for all items that are currently in the dictionary. Returns a list of values for all items that are currently in the dictionary.
## <a id="scriptfunction-type"></a> Function type ## Function type <a id="scriptfunction-type"></a>
Inherits methods from the [Object type](18-library-reference.md#object-type). Inherits methods from the [Object type](18-library-reference.md#object-type).
### <a id="scriptfunction-call"></a> Function#call ### Function#call <a id="scriptfunction-call"></a>
Signature: Signature:
@ -1277,7 +1277,7 @@ Example:
set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */ set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */
### <a id="scriptfunction-callv"></a> Function#callv ### Function#callv <a id="scriptfunction-callv"></a>
Signature: Signature:
@ -1298,11 +1298,11 @@ Example:
set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */ set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */
## <a id="datetime-type"></a> DateTime type ## DateTime type <a id="datetime-type"></a>
Inherits methods from the [Object type](18-library-reference.md#object-type). Inherits methods from the [Object type](18-library-reference.md#object-type).
### <a id="datetime-ctor"></a> DateTime constructor ### DateTime constructor <a id="datetime-ctor"></a>
Signature: Signature:
@ -1319,7 +1319,7 @@ Example:
var d1 = DateTime() /* current time */ var d1 = DateTime() /* current time */
var d2 = DateTime(2016, 5, 21) /* midnight April 21st, 2016 (local time) */ var d2 = DateTime(2016, 5, 21) /* midnight April 21st, 2016 (local time) */
### <a id="datetime-arithmetic"></a> DateTime arithmetic ### DateTime arithmetic <a id="datetime-arithmetic"></a>
Subtracting two DateTime objects yields the interval between them, in seconds. Subtracting two DateTime objects yields the interval between them, in seconds.
@ -1339,7 +1339,7 @@ Example:
var dt = DateTime() + 24 * 60 60 /* Current time plus 24 hours */ var dt = DateTime() + 24 * 60 60 /* Current time plus 24 hours */
### <a id="datetime-format"></a> DateTime#format ### DateTime#format <a id="datetime-format"></a>
Signature: Signature:
@ -1352,7 +1352,7 @@ Example:
var s = DateTime(2016, 4, 21).format("%A") /* Sets s to "Thursday". */ var s = DateTime(2016, 4, 21).format("%A") /* Sets s to "Thursday". */
### <a id="datetime-tostring"></a> DateTime#to_string ### DateTime#to_string <a id="datetime-tostring"></a>
Signature: Signature:

8
doc/19-script-debugger.md
View File

@ -1,4 +1,4 @@
# <a id="script-debugger"></a> Script Debugger # Script Debugger <a id="script-debugger"></a>
You can run the Icinga 2 daemon with the `-X` (`--script-debugger`) You can run the Icinga 2 daemon with the `-X` (`--script-debugger`)
parameter to enable the script debugger: parameter to enable the script debugger:
@ -14,9 +14,9 @@ Here is a list of common errors which can be diagnosed with the script debugger:
* Configuration errors (apply) * Configuration errors (apply)
* Errors in user-defined functions * Errors in user-defined functions
## <a id="script-debugger-config-errors"></a> Debugging Configuration Errors ## Debugging Configuration Errors <a id="script-debugger-config-errors"></a>
The following example illustrates the problem of a service [apply rule](3-monitoring-basics.md#using-apply-for) The following example illustrates the problem of a service [apply rule](03-monitoring-basics.md#using-apply-for)
which expects a dictionary value for `config`, but the host custom attribute only which expects a dictionary value for `config`, but the host custom attribute only
provides a string value: provides a string value:
@ -76,7 +76,7 @@ you can inspect attributes of the service object:
Additionally you can view the service object attributes by printing the value of `this`. Additionally you can view the service object attributes by printing the value of `this`.
## <a id="script-debugger-breakpoints"></a> Using Breakpoints ## Using Breakpoints <a id="script-debugger-breakpoints"></a>
In order to halt execution in a script you can use the `debugger` keyword: In order to halt execution in a script you can use the `debugger` keyword:

26
doc/20-development.md
View File

@ -1,4 +1,4 @@
# <a id="development"></a> Develop Icinga 2 # Develop Icinga 2 <a id="development"></a>
This chapter provides hints on Icinga 2 development This chapter provides hints on Icinga 2 development
especially for debugging purposes. especially for debugging purposes.
@ -8,7 +8,7 @@ especially for debugging purposes.
> If you are planning to build your own development environment, > If you are planning to build your own development environment,
> please consult the `INSTALL.md` file from the source tree. > please consult the `INSTALL.md` file from the source tree.
## <a id="debug-requirements"></a> Debug Requirements ## Debug Requirements <a id="debug-requirements"></a>
Make sure that the debug symbols are available for Icinga 2. Make sure that the debug symbols are available for Icinga 2.
The Icinga 2 packages provide a debug package which must be The Icinga 2 packages provide a debug package which must be
@ -34,7 +34,7 @@ If you're building your own binaries, you should use the `-DCMAKE_BUILD_TYPE=Deb
build flag for debug builds. build flag for debug builds.
## <a id="development-debug-gdb"></a> GDB ## GDB <a id="development-debug-gdb"></a>
Install gdb: Install gdb:
@ -114,7 +114,7 @@ the duplicate import in your `~/.gdbinit` file.
RuntimeError: pretty-printer already registered: libstdc++-v6 RuntimeError: pretty-printer already registered: libstdc++-v6
### <a id="development-debug-gdb-run"></a> GDB Run ### GDB Run <a id="development-debug-gdb-run"></a>
Call GDB with the binary (`/usr/sbin/icinga2` is a wrapper script calling Call GDB with the binary (`/usr/sbin/icinga2` is a wrapper script calling
`/usr/lib64/icinga2/sbin/icinga2` since 2.4) and all arguments and run it in foreground. `/usr/lib64/icinga2/sbin/icinga2` since 2.4) and all arguments and run it in foreground.
@ -142,7 +142,7 @@ Continue after breakpoint.
(gdb) c (gdb) c
### <a id="development-debug-gdb-coredump"></a> GDB Core Dump ### GDB Core Dump <a id="development-debug-gdb-coredump"></a>
Either attach to the running process using `gdb -p PID` or start Either attach to the running process using `gdb -p PID` or start
a new gdb run. a new gdb run.
@ -150,7 +150,7 @@ a new gdb run.
(gdb) r (gdb) r
(gdb) generate-core-file (gdb) generate-core-file
### <a id="development-debug-gdb-backtrace"></a> GDB Backtrace ### GDB Backtrace <a id="development-debug-gdb-backtrace"></a>
If Icinga 2 aborted its operation abnormally, generate a backtrace. If Icinga 2 aborted its operation abnormally, generate a backtrace.
@ -166,14 +166,14 @@ running Icinga 2.
If you create a [bug report](https://www.icinga.com/community/get-involved/), If you create a [bug report](https://www.icinga.com/community/get-involved/),
make sure to attach as much detail as possible. make sure to attach as much detail as possible.
### <a id="development-debug-gdb-backtrace-running"></a> GDB Backtrace from Running Process ### GDB Backtrace from Running Process <a id="development-debug-gdb-backtrace-running"></a>
If Icinga 2 is still running, generate a full backtrace from the running If Icinga 2 is still running, generate a full backtrace from the running
process and store it into a new file (e.g. for debugging dead locks): process and store it into a new file (e.g. for debugging dead locks):
# gdb -p $(pidof icinga2) -batch -ex "thread apply all bt full" -ex "detach" -ex "q" > gdb_bt.log # gdb -p $(pidof icinga2) -batch -ex "thread apply all bt full" -ex "detach" -ex "q" > gdb_bt.log
### <a id="development-debug-gdb-backtrace-stepping"></a> GDB Backtrace Stepping ### GDB Backtrace Stepping <a id="development-debug-gdb-backtrace-stepping"></a>
Identifying the problem may require stepping into the backtrace, analysing Identifying the problem may require stepping into the backtrace, analysing
the current scope, attributes, and possible unmet requirements. `p` prints the current scope, attributes, and possible unmet requirements. `p` prints
@ -185,7 +185,7 @@ the value of the selected variable or function call result.
(gdb) p checkable.px->m_Name (gdb) p checkable.px->m_Name
### <a id="development-debug-gdb-breakpoint"></a> GDB Breakpoints ### GDB Breakpoints <a id="development-debug-gdb-breakpoint"></a>
To set a breakpoint to a specific function call, or file specific line. To set a breakpoint to a specific function call, or file specific line.
@ -239,13 +239,13 @@ Breakpoint Example:
m_Data = "/etc/icinga2/conf.d/timeperiods.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/users.conf"}} m_Data = "/etc/icinga2/conf.d/timeperiods.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/users.conf"}}
## <a id="development-debug-core-dump"></a> Core Dump ## Core Dump <a id="development-debug-core-dump"></a>
When the Icinga 2 daemon crashes with a `SIGSEGV` signal When the Icinga 2 daemon crashes with a `SIGSEGV` signal
a core dump file should be written. This will help a core dump file should be written. This will help
developers to analyze and fix the problem. developers to analyze and fix the problem.
### <a id="development-debug-core-dump-limit"></a> Core Dump File Size Limit ### Core Dump File Size Limit <a id="development-debug-core-dump-limit"></a>
This requires setting the core dump file size to `unlimited`. This requires setting the core dump file size to `unlimited`.
@ -276,7 +276,7 @@ Verify that the Icinga 2 process core file size limit is set to `unlimited`.
Max core file size unlimited unlimited bytes Max core file size unlimited unlimited bytes
### <a id="development-debug-core-dump-format"></a> Core Dump Kernel Format ### Core Dump Kernel Format <a id="development-debug-core-dump-format"></a>
The Icinga 2 daemon runs with the SUID bit set. Therefore you need The Icinga 2 daemon runs with the SUID bit set. Therefore you need
to explicitly enable core dumps for SUID on Linux. to explicitly enable core dumps for SUID on Linux.
@ -295,7 +295,7 @@ MacOS:
chmod 777 /cores chmod 777 /cores
### <a id="development-debug-core-dump-analysis"></a> Core Dump Analysis ### Core Dump Analysis <a id="development-debug-core-dump-analysis"></a>
Once Icinga 2 crashes again a new coredump file will be written. Please Once Icinga 2 crashes again a new coredump file will be written. Please
attach this file to your bug report in addition to the general details. attach this file to your bug report in addition to the general details.

30
doc/21-selinux.md
View File

@ -1,6 +1,6 @@
# <a id="selinux"></a> SELinux # SELinux <a id="selinux"></a>
## <a id="selinux-introduction"></a> Introduction ## Introduction <a id="selinux-introduction"></a>
SELinux is a mandatory access control (MAC) system on Linux which adds a fine-grained permission system for access to all system resources such as files, devices, networks and inter-process communication. 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.
@ -8,11 +8,11 @@ The most important questions are answered briefly in the [FAQ of the SELinux Pro
This documentation will use a format similar to the SELinux User's and Administrator's Guide. This documentation will use a format similar to the SELinux User's and Administrator's Guide.
### <a id="selinux-policy"></a> Policy ### Policy <a id="selinux-policy"></a>
Icinga 2 provides its own SELinux policy. Development target is a policy package for Red Hat Enterprise Linux 7 and derivatives running the targeted policy which confines Icinga 2 with all features and all checks executed. All other distributions will require some tweaks. Icinga 2 provides its own SELinux policy. Development target is a policy package for Red Hat Enterprise Linux 7 and derivatives running the targeted policy which confines Icinga 2 with all features and all checks executed. All other distributions will require some tweaks.
### <a id="selinux-policy-installation"></a> Installation ### Installation <a id="selinux-policy-installation"></a>
There are two ways of installing the SELinux Policy for Icinga 2 on Enterprise Linux 7. The preferred way is to install the package. The other option involves installing the SELinux policy manually which might be necessary if you need some fixes which haven't made their way into a release yet. There are two ways of installing the SELinux Policy for Icinga 2 on Enterprise Linux 7. The preferred way is to install the package. The other option involves installing the SELinux policy manually which might be necessary if you need some fixes which haven't made their way into a release yet.
@ -31,7 +31,7 @@ If the system runs in enforcing mode and you encounter problems you can set Icin
You can change the configured mode by editing `/etc/selinux/config` and the current mode by executing `setenforce 0`. You can change the configured mode by editing `/etc/selinux/config` and the current mode by executing `setenforce 0`.
#### <a id="selinux-policy-installation-package"></a> Package installation #### Package installation <a id="selinux-policy-installation-package"></a>
Simply add the `icinga2-selinux` package to your installation. Simply add the `icinga2-selinux` package to your installation.
@ -43,7 +43,7 @@ Ensure that the `icinga2` process is running in its own `icinga2_t` domain after
# ps -eZ | grep icinga2 # ps -eZ | grep icinga2
system_u:system_r:icinga2_t:s0 2825 ? 00:00:00 icinga2 system_u:system_r:icinga2_t:s0 2825 ? 00:00:00 icinga2
#### <a id="selinux-policy-installation-manual"></a> Manual installation #### Manual installation <a id="selinux-policy-installation-manual"></a>
This section describes the installation to support development and testing. It assumes that Icinga 2 is already installed from packages and running on the system. This section describes the installation to support development and testing. It assumes that Icinga 2 is already installed from packages and running on the system.
@ -68,7 +68,7 @@ After that restart Icinga 2 and verify it running in its own domain `icinga2_t`.
# ps -eZ | grep icinga2 # ps -eZ | grep icinga2
system_u:system_r:icinga2_t:s0 2825 ? 00:00:00 icinga2 system_u:system_r:icinga2_t:s0 2825 ? 00:00:00 icinga2
### <a id="selinux-policy-general"></a> General ### General <a id="selinux-policy-general"></a>
When the SELinux policy package for Icinga 2 is installed, the Icinga 2 daemon (icinga2) runs in its own domain `icinga2_t` and is separated from other confined services. When the SELinux policy package for Icinga 2 is installed, the Icinga 2 daemon (icinga2) runs in its own domain `icinga2_t` and is separated from other confined services.
@ -76,7 +76,7 @@ Files have to be labeled correctly in order for Icinga 2 to be able to access th
Additionally the Apache web server is allowed to connect to Icinga 2's command pipe in order to allow web interfaces to send commands to icinga2. This will perhaps change later on while investigating Icinga Web 2 for SELinux! Additionally the Apache web server is allowed to connect to Icinga 2's command pipe in order to allow web interfaces to send commands to icinga2. This will perhaps change later on while investigating Icinga Web 2 for SELinux!
### <a id="selinux-policy-types"></a> Types ### Types <a id="selinux-policy-types"></a>
The command pipe is labeled `icinga2_command_t` and other services can request access to it by using the interface `icinga2_send_commands`. The command pipe is labeled `icinga2_command_t` and other services can request access to it by using the interface `icinga2_send_commands`.
@ -98,7 +98,7 @@ If one of those plugin domains causes problems you can set it to permissive by e
The policy provides a role `icinga2adm_r` for confining an user which enables an administrative user managing only Icinga 2 on the system. This user will also execute the plugins in their domain instead of the users one, so you can verify their execution with the same restrictions like they have when executed by icinga2. The policy provides a role `icinga2adm_r` for confining an user which enables an administrative user managing only Icinga 2 on the system. This user will also execute the plugins in their domain instead of the users one, so you can verify their execution with the same restrictions like they have when executed by icinga2.
### <a id="selinux-policy-booleans"></a> Booleans ### Booleans <a id="selinux-policy-booleans"></a>
SELinux is based on the least level of access required for a service to run. Using booleans you can grant more access in a defined way. The Icinga 2 policy package provides the following booleans. SELinux is based on the least level of access required for a service to run. Using booleans you can grant more access in a defined way. The Icinga 2 policy package provides the following booleans.
@ -114,15 +114,15 @@ Having this boolean enabled allows httpd to write to the command pipe of icinga2
Having this boolean enabled allows httpd to connect to the API of icinga2 (Ports labeled icinga2_port_t). This is enabled by default, if not needed you can disable it for more security. Having this boolean enabled allows httpd to connect to the API of icinga2 (Ports labeled icinga2_port_t). This is enabled by default, if not needed you can disable it for more security.
### <a id="selinux-policy-examples"></a> Configuration Examples ### Configuration Examples <a id="selinux-policy-examples"></a>
#### <a id="selinux-policy-examples-permissive"></a> Run the icinga2 service permissive #### Run the icinga2 service permissive <a id="selinux-policy-examples-permissive"></a>
If problems occur while running the system in enforcing mode and those problems are only caused by the policy of the icinga2 domain, you can set this domain to permissive instead of the complete system. This can be done by executing `semanage permissive -a icinga2_t`. If problems occur while running the system in enforcing mode and those problems are only caused by the policy of the icinga2 domain, you can set this domain to permissive instead of the complete system. This can be done by executing `semanage permissive -a icinga2_t`.
Make sure to report the bugs in the policy afterwards. Make sure to report the bugs in the policy afterwards.
#### <a id="selinux-policy-examples-plugin"></a> Confining a plugin #### Confining a plugin <a id="selinux-policy-examples-plugin"></a>
Download and install a plugin, for example check_mysql_health. Download and install a plugin, for example check_mysql_health.
@ -146,7 +146,7 @@ In this case the plugin is monitoring a service, so it should be labeled `nagios
The plugin still runs fine but if someone changes the script to do weird stuff it will fail to do so. The plugin still runs fine but if someone changes the script to do weird stuff it will fail to do so.
#### <a id="selinux-policy-examples-connectall"></a> Allow icinga to connect to all ports. #### Allow icinga to connect to all ports. <a id="selinux-policy-examples-connectall"></a>
You are running graphite on a different port than `2003` and want `icinga2` to connect to it. You are running graphite on a different port than `2003` and want `icinga2` to connect to it.
@ -174,7 +174,7 @@ Before you restart the icinga2 service allow it to connect to all ports by enabl
If you restart the daemon now it will successfully connect to graphite. If you restart the daemon now it will successfully connect to graphite.
#### <a id="selinux-policy-examples-user"></a> Confining a user #### Confining a user <a id="selinux-policy-examples-user"></a>
If you want to have an administrative account capable of only managing icinga2 and not the complete system, you can restrict the privileges by confining If you want to have an administrative account capable of only managing icinga2 and not the complete system, you can restrict the privileges by confining
this user. This is completly optional! this user. This is completly optional!
@ -225,7 +225,7 @@ Now try the commands again without providing the role and type and they will wor
$ sudo systemctl reload httpd.service $ sudo systemctl reload httpd.service
Failed to issue method call: Access denied Failed to issue method call: Access denied
## <a id="selinux-bugreports"></a> Bugreports ## Bugreports <a id="selinux-bugreports"></a>
If you experience any problems while running in enforcing mode try to reproduce it in permissive mode. If the problem persists it is not related to SELinux because in permissive mode SELinux will not deny anything. If you experience any problems while running in enforcing mode try to reproduce it in permissive mode. If the problem persists it is not related to SELinux because in permissive mode SELinux will not deny anything.

158
doc/22-migrating-from-icinga-1x.md
View File

@ -1,12 +1,12 @@
# <a id="migration"></a> Migration from Icinga 1.x # Migration from Icinga 1.x <a id="migration"></a>
## <a id="configuration-migration"></a> Configuration Migration ## Configuration Migration <a id="configuration-migration"></a>
The Icinga 2 configuration format introduces plenty of behavioural changes. In The Icinga 2 configuration format introduces plenty of behavioural changes. In
order to ease migration from Icinga 1.x, this section provides hints and tips order to ease migration from Icinga 1.x, this section provides hints and tips
on your migration requirements. on your migration requirements.
### <a id="manual-config-migration"></a> Manual Config Migration ### Manual Config Migration <a id="manual-config-migration"></a>
For a long-term migration of your configuration you should consider re-creating For a long-term migration of your configuration you should consider re-creating
your configuration based on the proposed Icinga 2 configuration paradigm. your configuration based on the proposed Icinga 2 configuration paradigm.
@ -14,7 +14,7 @@ your configuration based on the proposed Icinga 2 configuration paradigm.
Please read the [next chapter](22-migrating-from-icinga-1x.md#differences-1x-2) to find out more about the differences Please read the [next chapter](22-migrating-from-icinga-1x.md#differences-1x-2) to find out more about the differences
between 1.x and 2. between 1.x and 2.
### <a id="manual-config-migration-hints"></a> Manual Config Migration Hints ### Manual Config Migration Hints <a id="manual-config-migration-hints"></a>
These hints should provide you with enough details for manually migrating your configuration, These hints should provide you with enough details for manually migrating your configuration,
or to adapt your configuration export tool to dump Icinga 2 configuration instead of or to adapt your configuration export tool to dump Icinga 2 configuration instead of
@ -26,7 +26,7 @@ let us know!
If you require in-depth explanations, please check the [next chapter](22-migrating-from-icinga-1x.md#differences-1x-2). If you require in-depth explanations, please check the [next chapter](22-migrating-from-icinga-1x.md#differences-1x-2).
#### <a id="manual-config-migration-hints-Intervals"></a> Manual Config Migration Hints for Intervals #### Manual Config Migration Hints for Intervals <a id="manual-config-migration-hints-Intervals"></a>
By default all intervals without any duration literal are interpreted as seconds. Therefore By default all intervals without any duration literal are interpreted as seconds. Therefore
all existing Icinga 1.x `*_interval` attributes require an additional `m` duration literal. all existing Icinga 1.x `*_interval` attributes require an additional `m` duration literal.
@ -52,10 +52,10 @@ Icinga 2:
retry_interval = 1m retry_interval = 1m
} }
#### <a id="manual-config-migration-hints-services"></a> Manual Config Migration Hints for Services #### Manual Config Migration Hints for Services <a id="manual-config-migration-hints-services"></a>
If you have used the `host_name` attribute in Icinga 1.x with one or more host names this service If you have used the `host_name` attribute in Icinga 1.x with one or more host names this service
belongs to, you can migrate this to the [apply rules](3-monitoring-basics.md#using-apply) syntax. belongs to, you can migrate this to the [apply rules](03-monitoring-basics.md#using-apply) syntax.
Icinga 1.x: Icinga 1.x:
@ -85,7 +85,7 @@ like the following example:
use generic-service use generic-service
} }
Using Icinga 2 you can migrate this to the [apply rules](3-monitoring-basics.md#using-apply) syntax: Using Icinga 2 you can migrate this to the [apply rules](03-monitoring-basics.md#using-apply) syntax:
apply Service "servicewithhostgroups" { apply Service "servicewithhostgroups" {
import "generic-service" import "generic-service"
@ -95,7 +95,7 @@ Using Icinga 2 you can migrate this to the [apply rules](3-monitoring-basics.md#
assign where "hostgroup3" in host.groups assign where "hostgroup3" in host.groups
} }
#### <a id="manual-config-migration-hints-group-members"></a> Manual Config Migration Hints for Group Members #### Manual Config Migration Hints for Group Members <a id="manual-config-migration-hints-group-members"></a>
The Icinga 1.x hostgroup `hg1` has two members `host1` and `host2`. The hostgroup `hg2` has `host3` as The Icinga 1.x hostgroup `hg1` has two members `host1` and `host2`. The hostgroup `hg2` has `host3` as
a member and includes all members of the `hg1` hostgroup. a member and includes all members of the `hg1` hostgroup.
@ -133,7 +133,7 @@ These assign rules can be applied for all groups: `HostGroup`, `ServiceGroup` an
#### <a id="manual-config-migration-hints-check-command-arguments"></a> Manual Config Migration Hints for Check Command Arguments #### Manual Config Migration Hints for Check Command Arguments <a id="manual-config-migration-hints-check-command-arguments"></a>
Host and service check command arguments are separated by a `!` in Icinga 1.x. Their order is important and they Host and service check command arguments are separated by a `!` in Icinga 1.x. Their order is important and they
are referenced as `$ARGn$` where `n` is the argument counter. are referenced as `$ARGn$` where `n` is the argument counter.
@ -183,7 +183,7 @@ While you could manually migrate this like (please note the new generic command
vars.ping_cpl = 60 vars.ping_cpl = 60
} }
#### <a id="manual-config-migration-hints-runtime-macros"></a> Manual Config Migration Hints for Runtime Macros #### Manual Config Migration Hints for Runtime Macros <a id="manual-config-migration-hints-runtime-macros"></a>
Runtime macros have been renamed. A detailed comparison table can be found [here](22-migrating-from-icinga-1x.md#differences-1x-2-runtime-macros). Runtime macros have been renamed. A detailed comparison table can be found [here](22-migrating-from-icinga-1x.md#differences-1x-2-runtime-macros).
@ -204,7 +204,7 @@ In Icinga 2 you'd just use the following macro to access all `address` attribute
$address$ $address$
#### <a id="manual-config-migration-hints-runtime-custom-attributes"></a> Manual Config Migration Hints for Runtime Custom Attributes #### Manual Config Migration Hints for Runtime Custom Attributes <a id="manual-config-migration-hints-runtime-custom-attributes"></a>
Custom variables from Icinga 1.x are available as Icinga 2 custom attributes. Custom variables from Icinga 1.x are available as Icinga 2 custom attributes.
@ -254,7 +254,7 @@ while the service check command resolves its value to the service attribute attr
> >
> Custom attributes in Icinga 2 are case-sensitive. `vars.CVTEST` is not the same as `vars.CvTest`. > Custom attributes in Icinga 2 are case-sensitive. `vars.CVTEST` is not the same as `vars.CvTest`.
#### <a id="manual-config-migration-hints-contacts-users"></a> Manual Config Migration Hints for Contacts (Users) #### Manual Config Migration Hints for Contacts (Users) <a id="manual-config-migration-hints-contacts-users"></a>
Contacts in Icinga 1.x act as users in Icinga 2, but do not have any notification commands specified. Contacts in Icinga 1.x act as users in Icinga 2, but do not have any notification commands specified.
This migration part is explained in the [next chapter](22-migrating-from-icinga-1x.md#manual-config-migration-hints-notifications). This migration part is explained in the [next chapter](22-migrating-from-icinga-1x.md#manual-config-migration-hints-notifications).
@ -280,7 +280,7 @@ renamed to `display_name`.
This user can be put into usergroups (former contactgroups) or referenced in newly migration notification This user can be put into usergroups (former contactgroups) or referenced in newly migration notification
objects. objects.
#### <a id="manual-config-migration-hints-notifications"></a> Manual Config Migration Hints for Notifications #### Manual Config Migration Hints for Notifications <a id="manual-config-migration-hints-notifications"></a>
If you are migrating a host or service notification, you'll need to extract the following information from If you are migrating a host or service notification, you'll need to extract the following information from
your existing Icinga 1.x configuration objects your existing Icinga 1.x configuration objects
@ -297,7 +297,7 @@ generic strategy
* which contacts (users) are notified by mail? * which contacts (users) are notified by mail?
* do the notification filters, periods, intervals still apply for them? (do a cleanup during migration) * do the notification filters, periods, intervals still apply for them? (do a cleanup during migration)
* assign users and groups to these notifications * assign users and groups to these notifications
* Redesign the notifications into generic [apply rules](3-monitoring-basics.md#using-apply-notifications) * Redesign the notifications into generic [apply rules](03-monitoring-basics.md#using-apply-notifications)
The ugly workaround solution could look like this: The ugly workaround solution could look like this:
@ -339,7 +339,7 @@ examples, try [LConf](https://www.netways.org).
#### <a id="manual-config-migration-hints-notification-filters"></a> Manual Config Migration Hints for Notification Filters #### Manual Config Migration Hints for Notification Filters <a id="manual-config-migration-hints-notification-filters"></a>
Icinga 1.x defines all notification filters in an attribute called `notification_options`. Using Icinga 2 you will Icinga 1.x defines all notification filters in an attribute called `notification_options`. Using Icinga 2 you will
have to split these values into the `states` and `types` attributes. have to split these values into the `states` and `types` attributes.
@ -364,7 +364,7 @@ have to split these values into the `states` and `types` attributes.
#### <a id="manual-config-migration-hints-escalations"></a> Manual Config Migration Hints for Escalations #### Manual Config Migration Hints for Escalations <a id="manual-config-migration-hints-escalations"></a>
Escalations in Icinga 1.x are a bit tricky. By default service escalations can be applied to hosts and Escalations in Icinga 1.x are a bit tricky. By default service escalations can be applied to hosts and
hostgroups and require a defined service object. hostgroups and require a defined service object.
@ -455,9 +455,9 @@ just this service belonging to hosts in the matched hostgroup.
#### <a id="manual-config-migration-hints-dependencies"></a> Manual Config Migration Hints for Dependencies #### Manual Config Migration Hints for Dependencies <a id="manual-config-migration-hints-dependencies"></a>
There are some dependency examples already in the [basics chapter](3-monitoring-basics.md#dependencies). Dependencies in There are some dependency examples already in the [basics chapter](03-monitoring-basics.md#dependencies). Dependencies in
Icinga 1.x can be confusing in terms of which host/service is the parent and which host/service acts Icinga 1.x can be confusing in terms of which host/service is the parent and which host/service acts
as the child. as the child.
@ -560,7 +560,7 @@ Host dependencies are explained in the [next chapter](22-migrating-from-icinga-1
#### <a id="manual-config-migration-hints-host-parents"></a> Manual Config Migration Hints for Host Parents #### Manual Config Migration Hints for Host Parents <a id="manual-config-migration-hints-host-parents"></a>
Host parents from Icinga 1.x are migrated into `Host-to-Host` dependencies in Icinga 2. Host parents from Icinga 1.x are migrated into `Host-to-Host` dependencies in Icinga 2.
@ -681,24 +681,24 @@ Another way to express the same configuration would be something like:
This example allows finer grained host-to-host dependency, as well as multiple dependency support. This example allows finer grained host-to-host dependency, as well as multiple dependency support.
#### <a id="manual-config-migration-hints-distributed-setup"></a> Manual Config Migration Hints for Distributed Setups #### Manual Config Migration Hints for Distributed Setups <a id="manual-config-migration-hints-distributed-setup"></a>
* Icinga 2 does not use active/passive instances calling OSCP commands and requiring the NSCA * Icinga 2 does not use active/passive instances calling OSCP commands and requiring the NSCA
daemon for passing check results between instances. daemon for passing check results between instances.
* Icinga 2 does not support any 1.x NEB addons for check load distribution * Icinga 2 does not support any 1.x NEB addons for check load distribution
* If your current setup consists of instances distributing the check load, you should consider * If your current setup consists of instances distributing the check load, you should consider
building a [load distribution](6-distributed-monitoring.md#distributed-monitoring-scenarios) setup with Icinga 2. building a [load distribution](06-distributed-monitoring.md#distributed-monitoring-scenarios) setup with Icinga 2.
* If your current setup includes active/passive clustering with external tools like Pacemaker/DRBD, * If your current setup includes active/passive clustering with external tools like Pacemaker/DRBD,
consider the [High Availability](6-distributed-monitoring.md#distributed-monitoring-scenarios) setup. consider the [High Availability](06-distributed-monitoring.md#distributed-monitoring-scenarios) setup.
* If you have build your own custom configuration deployment and check result collecting mechanism, * If you have build your own custom configuration deployment and check result collecting mechanism,
you should re-design your setup and re-evaluate your requirements, and how they may be fulfilled you should re-design your setup and re-evaluate your requirements, and how they may be fulfilled
using the Icinga 2 cluster capabilities. using the Icinga 2 cluster capabilities.
## <a id="differences-1x-2"></a> Differences between Icinga 1.x and 2 ## Differences between Icinga 1.x and 2 <a id="differences-1x-2"></a>
### <a id="differences-1x-2-configuration-format"></a> Configuration Format ### Configuration Format <a id="differences-1x-2-configuration-format"></a>
Icinga 1.x supports two configuration formats: key-value-based settings in the Icinga 1.x supports two configuration formats: key-value-based settings in the
`icinga.cfg` configuration file and object-based in included files (`cfg_dir`, `icinga.cfg` configuration file and object-based in included files (`cfg_dir`,
@ -726,7 +726,7 @@ icinga2.conf:
enable_notifications = false enable_notifications = false
} }
#### <a id="differences-1x-2-sample-configuration-itl"></a> Sample Configuration and ITL #### Sample Configuration and ITL <a id="differences-1x-2-sample-configuration-itl"></a>
While Icinga 1.x ships sample configuration and templates spread in various While Icinga 1.x ships sample configuration and templates spread in various
object files, Icinga 2 moves all templates into the Icinga Template Library (ITL) object files, Icinga 2 moves all templates into the Icinga Template Library (ITL)
@ -746,18 +746,18 @@ included in `icinga2.conf` by default.
> **Note** > **Note**
> >
> Add your own custom templates in the `conf.d/` directory as well, e.g. inside > Add your own custom templates in the `conf.d/` directory as well, e.g. inside
> the [templates.conf](4-configuring-icinga-2.md#templates-conf) file. > the [templates.conf](04-configuring-icinga-2.md#templates-conf) file.
### <a id="differences-1x-2-main-config"></a> Main Config File ### Main Config File <a id="differences-1x-2-main-config"></a>
In Icinga 1.x there are many global configuration settings available in `icinga.cfg`. In Icinga 1.x there are many global configuration settings available in `icinga.cfg`.
Icinga 2 only uses a small set of [global constants](17-language-reference.md#constants) allowing Icinga 2 only uses a small set of [global constants](17-language-reference.md#constants) allowing
you to specify certain different setting such as the `NodeName` in a cluster scenario. you to specify certain different setting such as the `NodeName` in a cluster scenario.
Aside from that, the [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) should take care of including Aside from that, the [icinga2.conf](04-configuring-icinga-2.md#icinga2-conf) should take care of including
global constants, enabled [features](11-cli-commands.md#enable-features) and the object configuration. global constants, enabled [features](11-cli-commands.md#enable-features) and the object configuration.
### <a id="differences-1x-2-include-files-dirs"></a> Include Files and Directories ### Include Files and Directories <a id="differences-1x-2-include-files-dirs"></a>
In Icinga 1.x the `icinga.cfg` file contains `cfg_file` and `cfg_dir` In Icinga 1.x the `icinga.cfg` file contains `cfg_file` and `cfg_dir`
directives. The `cfg_dir` directive recursively includes all files with a `.cfg` directives. The `cfg_dir` directive recursively includes all files with a `.cfg`
@ -787,7 +787,7 @@ command configuration.
By convention the `.conf` suffix is used for Icinga 2 configuration files. By convention the `.conf` suffix is used for Icinga 2 configuration files.
### <a id="differences-1x-2-resource-file-global-macros"></a> Resource File and Global Macros ### Resource File and Global Macros <a id="differences-1x-2-resource-file-global-macros"></a>
Global macros such as for the plugin directory, usernames and passwords can be Global macros such as for the plugin directory, usernames and passwords can be
set in the `resource.cfg` configuration file in Icinga 1.x. By convention the set in the `resource.cfg` configuration file in Icinga 1.x. By convention the
@ -807,7 +807,7 @@ set in the `constants.conf` configuration file:
[Global macros](17-language-reference.md#constants) can only be defined once. Trying to modify a [Global macros](17-language-reference.md#constants) can only be defined once. Trying to modify a
global constant will result in an error. global constant will result in an error.
### <a id="differences-1x-2-configuration-comments"></a> Configuration Comments ### Configuration Comments <a id="differences-1x-2-configuration-comments"></a>
In Icinga 1.x comments are made using a leading hash (`#`) or a semi-colon (`;`) In Icinga 1.x comments are made using a leading hash (`#`) or a semi-colon (`;`)
for inline comments. for inline comments.
@ -816,7 +816,7 @@ In Icinga 2 comments can either be encapsulated by `/*` and `*/` (allowing for
multi-line comments) or starting with two slashes (`//`). A leading hash (`#`) multi-line comments) or starting with two slashes (`//`). A leading hash (`#`)
could also be used. could also be used.
### <a id="differences-1x-2-object-names"></a> Object Names ### Object Names <a id="differences-1x-2-object-names"></a>
Object names must not contain an exclamation mark (`!`). Use the `display_name` attribute Object names must not contain an exclamation mark (`!`). Use the `display_name` attribute
to specify user-friendly names which should be shown in UIs (supported by to specify user-friendly names which should be shown in UIs (supported by
@ -834,7 +834,7 @@ services) like in Icinga 1.x but directly after their type definition.
host_name = "localhost" host_name = "localhost"
} }
### <a id="differences-1x-2-templates"></a> Templates ### Templates <a id="differences-1x-2-templates"></a>
In Icinga 1.x templates are identified using the `register 0` setting. Icinga 2 In Icinga 1.x templates are identified using the `register 0` setting. Icinga 2
uses the `template` identifier: uses the `template` identifier:
@ -857,7 +857,7 @@ Icinga 2 uses the keyword `import` with template names in double quotes.
The last template overrides previously set values. The last template overrides previously set values.
### <a id="differences-1x-2-object-attributes"></a> Object attributes ### Object attributes <a id="differences-1x-2-object-attributes"></a>
Icinga 1.x separates attribute and value pairs with whitespaces/tabs. Icinga 2 Icinga 1.x separates attribute and value pairs with whitespaces/tabs. Icinga 2
requires an equal sign (=) between them. requires an equal sign (=) between them.
@ -878,7 +878,7 @@ must be escaped by a backslash (e.g. in command line).
If an attribute identifier starts with a number, it must be enclosed If an attribute identifier starts with a number, it must be enclosed
in double quotes as well. in double quotes as well.
#### <a id="differences-1x-2-alias-display-name"></a> Alias vs. Display Name #### Alias vs. Display Name <a id="differences-1x-2-alias-display-name"></a>
In Icinga 1.x a host can have an `alias` and a `display_name` attribute used In Icinga 1.x a host can have an `alias` and a `display_name` attribute used
for a more descriptive name. A service only can have a `display_name` attribute. for a more descriptive name. A service only can have a `display_name` attribute.
@ -886,7 +886,7 @@ The `alias` is used for group, timeperiod, etc. objects too.
Icinga 2 only supports the `display_name` attribute which is also taken into Icinga 2 only supports the `display_name` attribute which is also taken into
account by Icinga web interfaces. account by Icinga web interfaces.
### <a id="differences-1x-2-custom-attributes"></a> Custom Attributes ### Custom Attributes <a id="differences-1x-2-custom-attributes"></a>
Icinga 2 allows you to define custom attributes in the `vars` dictionary. Icinga 2 allows you to define custom attributes in the `vars` dictionary.
The `notes`, `notes_url`, `action_url`, `icon_image`, `icon_image_alt` The `notes`, `notes_url`, `action_url`, `icon_image`, `icon_image_alt`
@ -894,7 +894,7 @@ attributes for host and service objects are still available in Icinga 2.
`2d_coords` and `statusmap_image` are not supported in Icinga 2. `2d_coords` and `statusmap_image` are not supported in Icinga 2.
#### <a id="differences-1x-2-custom-variables"></a> Custom Variables #### Custom Variables <a id="differences-1x-2-custom-variables"></a>
Icinga 1.x custom variable attributes must be prefixed using an underscore (`_`). Icinga 1.x custom variable attributes must be prefixed using an underscore (`_`).
In Icinga 2 these attributes must be added to the `vars` dictionary as custom attributes. In Icinga 2 these attributes must be added to the `vars` dictionary as custom attributes.
@ -902,32 +902,32 @@ In Icinga 2 these attributes must be added to the `vars` dictionary as custom at
vars.dn = "cn=icinga2-dev-host,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org" vars.dn = "cn=icinga2-dev-host,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org"
vars.cv = "my custom cmdb description" vars.cv = "my custom cmdb description"
These custom attributes are also used as [command parameters](3-monitoring-basics.md#command-passing-parameters). These custom attributes are also used as [command parameters](03-monitoring-basics.md#command-passing-parameters).
While Icinga 1.x only supports numbers and strings as custom attribute values, While Icinga 1.x only supports numbers and strings as custom attribute values,
Icinga 2 extends that to arrays and (nested) dictionaries. For more details Icinga 2 extends that to arrays and (nested) dictionaries. For more details
look [here](3-monitoring-basics.md#custom-attributes). look [here](03-monitoring-basics.md#custom-attributes).
### <a id="differences-1x-2-host-service-relation"></a> Host Service Relation ### Host Service Relation <a id="differences-1x-2-host-service-relation"></a>
In Icinga 1.x a service object is associated with a host by defining the In Icinga 1.x a service object is associated with a host by defining the
`host_name` attribute in the service definition. Alternate methods refer `host_name` attribute in the service definition. Alternate methods refer
to `hostgroup_name` or behaviour changing regular expression. to `hostgroup_name` or behaviour changing regular expression.
The preferred way of associating hosts with services in Icinga 2 is by The preferred way of associating hosts with services in Icinga 2 is by
using the [apply](3-monitoring-basics.md#using-apply) keyword. using the [apply](03-monitoring-basics.md#using-apply) keyword.
Direct object relations between a service and a host still allow you to use Direct object relations between a service and a host still allow you to use
the `host_name` [Service](9-object-types.md#objecttype-service) object attribute. the `host_name` [Service](09-object-types.md#objecttype-service) object attribute.
### <a id="differences-1x-2-users"></a> Users ### Users <a id="differences-1x-2-users"></a>
Contacts have been renamed to users (same for groups). A contact does not Contacts have been renamed to users (same for groups). A contact does not
only provide (custom) attributes and notification commands used for notifications, only provide (custom) attributes and notification commands used for notifications,
but is also used for authorization checks in Icinga 1.x. but is also used for authorization checks in Icinga 1.x.
Icinga 2 changes that behavior and makes the user an attribute provider only. Icinga 2 changes that behavior and makes the user an attribute provider only.
These attributes can be accessed using [runtime macros](3-monitoring-basics.md#runtime-macros) These attributes can be accessed using [runtime macros](03-monitoring-basics.md#runtime-macros)
inside notification command definitions. inside notification command definitions.
In Icinga 2 notification commands are not directly associated with users. In Icinga 2 notification commands are not directly associated with users.
@ -939,12 +939,12 @@ provide the contact and contactgroups attributes for services for compatibility
reasons. These values are calculated from all services, their notifications, reasons. These values are calculated from all services, their notifications,
and their users. and their users.
### <a id="differences-1x-2-macros"></a> Macros ### Macros <a id="differences-1x-2-macros"></a>
Various object attributes and runtime variables can be accessed as macros in Various object attributes and runtime variables can be accessed as macros in
commands in Icinga 1.x -- Icinga 2 supports all required [custom attributes](3-monitoring-basics.md#custom-attributes). commands in Icinga 1.x -- Icinga 2 supports all required [custom attributes](03-monitoring-basics.md#custom-attributes).
#### <a id="differences-1x-2-command-arguments"></a> Command Arguments #### Command Arguments <a id="differences-1x-2-command-arguments"></a>
If you have previously used Icinga 1.x, you may already be familiar with If you have previously used Icinga 1.x, you may already be familiar with
user and argument definitions (e.g., `USER1` or `ARG1`). Unlike in Icinga 1.x user and argument definitions (e.g., `USER1` or `ARG1`). Unlike in Icinga 1.x
@ -961,15 +961,15 @@ Please check the migration hints for a detailed
> >
> The Classic UI feature named `Command Expander` does not work with Icinga 2. > The Classic UI feature named `Command Expander` does not work with Icinga 2.
#### <a id="differences-1x-2-environment-macros"></a> Environment Macros #### Environment Macros <a id="differences-1x-2-environment-macros"></a>
The global configuration setting `enable_environment_macros` does not exist in The global configuration setting `enable_environment_macros` does not exist in
Icinga 2. Icinga 2.
Macros exported into the [environment](3-monitoring-basics.md#command-environment-variables) Macros exported into the [environment](03-monitoring-basics.md#command-environment-variables)
can be set using the `env` attribute in command objects. can be set using the `env` attribute in command objects.
#### <a id="differences-1x-2-runtime-macros"></a> Runtime Macros #### Runtime Macros <a id="differences-1x-2-runtime-macros"></a>
Icinga 2 requires an object specific namespace when accessing configuration Icinga 2 requires an object specific namespace when accessing configuration
and stateful runtime macros. Custom attributes can be accessed directly. and stateful runtime macros. Custom attributes can be accessed directly.
@ -1104,7 +1104,7 @@ Changes to global statistic macros:
### <a id="differences-1x-2-external-commands"></a> External Commands ### External Commands <a id="differences-1x-2-external-commands"></a>
`CHANGE_CUSTOM_CONTACT_VAR` was renamed to `CHANGE_CUSTOM_USER_VAR`. `CHANGE_CUSTOM_CONTACT_VAR` was renamed to `CHANGE_CUSTOM_USER_VAR`.
@ -1152,16 +1152,16 @@ The following external commands are not supported:
STOP_OBSESSING_OVER_SVC STOP_OBSESSING_OVER_SVC
STOP_OBSESSING_OVER_SVC_CHECKS STOP_OBSESSING_OVER_SVC_CHECKS
### <a id="differences-1x-2-async-event-execution"></a> Asynchronous Event Execution ### Asynchronous Event Execution <a id="differences-1x-2-async-event-execution"></a>
Unlike Icinga 1.x, Icinga 2 does not block when it's waiting for a command Unlike Icinga 1.x, Icinga 2 does not block when it's waiting for a command
being executed -- whether if it's a check, a notification, an event being executed -- whether if it's a check, a notification, an event
handler, a performance data writing update, etc. That way you'll handler, a performance data writing update, etc. That way you'll
recognize low to zero (check) latencies with Icinga 2. recognize low to zero (check) latencies with Icinga 2.
### <a id="differences-1x-2-checks"></a> Checks ### Checks <a id="differences-1x-2-checks"></a>
#### <a id="differences-1x-2-check-output"></a> Check Output #### Check Output <a id="differences-1x-2-check-output"></a>
Icinga 2 does not make a difference between `output` (first line) and Icinga 2 does not make a difference between `output` (first line) and
`long_output` (remaining lines) like in Icinga 1.x. Performance Data is `long_output` (remaining lines) like in Icinga 1.x. Performance Data is
@ -1174,18 +1174,18 @@ The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types
split the raw output into `output` (first line) and `long_output` (remaining split the raw output into `output` (first line) and `long_output` (remaining
lines) for compatibility reasons. lines) for compatibility reasons.
#### <a id="differences-1x-2-initial-state"></a> Initial State #### Initial State <a id="differences-1x-2-initial-state"></a>
Icinga 1.x uses the `max_service_check_spread` setting to specify a timerange Icinga 1.x uses the `max_service_check_spread` setting to specify a timerange
where the initial state checks must have happened. Icinga 2 will use the where the initial state checks must have happened. Icinga 2 will use the
`retry_interval` setting instead and `check_interval` divided by 5 if `retry_interval` setting instead and `check_interval` divided by 5 if
`retry_interval` is not defined. `retry_interval` is not defined.
### <a id="differences-1x-2-comments"></a> Comments ### Comments <a id="differences-1x-2-comments"></a>
Icinga 2 doesn't support non-persistent comments. Icinga 2 doesn't support non-persistent comments.
### <a id="differences-1x-2-commands"></a> Commands ### Commands <a id="differences-1x-2-commands"></a>
Unlike in Icinga 1.x there are three different command types in Icinga 2: Unlike in Icinga 1.x there are three different command types in Icinga 2:
`CheckCommand`, `NotificationCommand`, and `EventCommand`. `CheckCommand`, `NotificationCommand`, and `EventCommand`.
@ -1198,29 +1198,29 @@ In Icinga 2 these command types are separated and will generate an error on
configuration validation if used in the wrong context. configuration validation if used in the wrong context.
While Icinga 2 still supports the complete command line in command objects, it's While Icinga 2 still supports the complete command line in command objects, it's
recommended to use [command arguments](3-monitoring-basics.md#command-arguments) recommended to use [command arguments](03-monitoring-basics.md#command-arguments)
with optional and conditional command line parameters instead. with optional and conditional command line parameters instead.
It's also possible to define default argument values for the command itself It's also possible to define default argument values for the command itself
which can be overridden by the host or service then. which can be overridden by the host or service then.
#### <a id="differences-1x-2-commands-timeouts"></a> Command Timeouts #### Command Timeouts <a id="differences-1x-2-commands-timeouts"></a>
In Icinga 1.x there were two global options defining a host and service check In Icinga 1.x there were two global options defining a host and service check
timeout. This was essentially bad when there only was a couple of check plugins timeout. This was essentially bad when there only was a couple of check plugins
requiring some command timeouts to be extended. requiring some command timeouts to be extended.
Icinga 2 allows you to specify the command timeout directly on the command. So, Icinga 2 allows you to specify the command timeout directly on the command. So,
if your VMVware check plugin takes 15 minutes, [increase the timeout](9-object-types.md#objecttype-checkcommand) if your VMVware check plugin takes 15 minutes, [increase the timeout](09-object-types.md#objecttype-checkcommand)
accordingly. accordingly.
### <a id="differences-1x-2-groups"></a> Groups ### Groups <a id="differences-1x-2-groups"></a>
In Icinga 2 hosts, services, and users are added to groups using the `groups` In Icinga 2 hosts, services, and users are added to groups using the `groups`
attribute in the object. The old way of listing all group members in the group's attribute in the object. The old way of listing all group members in the group's
`members` attribute is available through `assign where` and `ignore where` `members` attribute is available through `assign where` and `ignore where`
expressions by using [group assign](3-monitoring-basics.md#group-assign-intro). expressions by using [group assign](03-monitoring-basics.md#group-assign-intro).
object Host "web-dev" { object Host "web-dev" {
import "generic-host" import "generic-host"
@ -1231,9 +1231,9 @@ expressions by using [group assign](3-monitoring-basics.md#group-assign-intro).
assign where match("*-dev", host.name) assign where match("*-dev", host.name)
} }
#### <a id="differences-1x-2-service-hostgroup-host"></a> Add Service to Hostgroup where Host is Member #### Add Service to Hostgroup where Host is Member <a id="differences-1x-2-service-hostgroup-host"></a>
In order to associate a service with all hosts in a host group the [apply](3-monitoring-basics.md#using-apply) In order to associate a service with all hosts in a host group the [apply](03-monitoring-basics.md#using-apply)
keyword can be used: keyword can be used:
apply Service "ping4" { apply Service "ping4" {
@ -1244,7 +1244,7 @@ keyword can be used:
assign where "dev-hosts" in host.groups assign where "dev-hosts" in host.groups
} }
### <a id="differences-1x-2-notifications"></a> Notifications ### Notifications <a id="differences-1x-2-notifications"></a>
Notifications are a new object type in Icinga 2. Imagine the following Notifications are a new object type in Icinga 2. Imagine the following
notification configuration problem in Icinga 1.x: notification configuration problem in Icinga 1.x:
@ -1289,7 +1289,7 @@ In Icinga 2 it will look like this:
Service -> Notification -> NotificationCommand Service -> Notification -> NotificationCommand
-> User, UserGroup -> User, UserGroup
#### <a id="differences-1x-2-escalations"></a> Escalations #### Escalations <a id="differences-1x-2-escalations"></a>
Escalations in Icinga 1.x require a separated object matching on existing Escalations in Icinga 1.x require a separated object matching on existing
objects. Escalations happen between a defined start and end time which is objects. Escalations happen between a defined start and end time which is
@ -1313,7 +1313,7 @@ happens.
That's not necessary with Icinga 2 only requiring an additional notification That's not necessary with Icinga 2 only requiring an additional notification
object for the escalation itself. object for the escalation itself.
#### <a id="differences-1x-2-notification-options"></a> Notification Options #### Notification Options <a id="differences-1x-2-notification-options"></a>
Unlike Icinga 1.x with the 'notification_options' attribute with comma-separated Unlike Icinga 1.x with the 'notification_options' attribute with comma-separated
state and type filters, Icinga 2 uses two configuration attributes for that. state and type filters, Icinga 2 uses two configuration attributes for that.
@ -1327,7 +1327,7 @@ All state and type filter use long names OR'd with a pipe together
Icinga 2 adds more fine-grained type filters for acknowledgements, downtime, Icinga 2 adds more fine-grained type filters for acknowledgements, downtime,
and flapping type (start, end, ...). and flapping type (start, end, ...).
### <a id="differences-1x-2-dependencies-parents"></a> Dependencies and Parents ### Dependencies and Parents <a id="differences-1x-2-dependencies-parents"></a>
In Icinga 1.x it's possible to define host parents to determine network reachability In Icinga 1.x it's possible to define host parents to determine network reachability
and keep a host's state unreachable rather than down. and keep a host's state unreachable rather than down.
@ -1343,7 +1343,7 @@ The former `host_name` and `dependent_host_name` have been renamed to `parent_ho
and `child_host_name` (same for the service attribute). When using apply rules the and `child_host_name` (same for the service attribute). When using apply rules the
child attributes may be omitted. child attributes may be omitted.
For detailed examples on how to use the dependencies please check the [dependencies](3-monitoring-basics.md#dependencies) For detailed examples on how to use the dependencies please check the [dependencies](03-monitoring-basics.md#dependencies)
chapter. chapter.
Dependencies can be applied to hosts or services using the [apply rules](17-language-reference.md#apply). Dependencies can be applied to hosts or services using the [apply rules](17-language-reference.md#apply).
@ -1352,7 +1352,7 @@ The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types
support the Icinga 1.x schema with dependencies and parent attributes for support the Icinga 1.x schema with dependencies and parent attributes for
compatibility reasons. compatibility reasons.
### <a id="differences-1x-2-flapping"></a> Flapping ### Flapping <a id="differences-1x-2-flapping"></a>
The Icinga 1.x flapping detection uses the last 21 states of a service. This The Icinga 1.x flapping detection uses the last 21 states of a service. This
value is hardcoded and cannot be changed. The algorithm on determining a flapping state value is hardcoded and cannot be changed. The algorithm on determining a flapping state
@ -1366,7 +1366,7 @@ The algorithm used in Icinga 2 does not store the past states but calculates the
threshold from a single value based on counters and half-life values. Icinga 2 compares threshold from a single value based on counters and half-life values. Icinga 2 compares
the value with a single flapping threshold configuration attribute. the value with a single flapping threshold configuration attribute.
### <a id="differences-1x-2-check-result-freshness"></a> Check Result Freshness ### Check Result Freshness <a id="differences-1x-2-check-result-freshness"></a>
Freshness of check results must be enabled explicitly in Icinga 1.x. The attribute Freshness of check results must be enabled explicitly in Icinga 1.x. The attribute
`freshness_threshold` defines the threshold in seconds. Once the threshold is triggered, an `freshness_threshold` defines the threshold in seconds. Once the threshold is triggered, an
@ -1379,7 +1379,7 @@ freshness is calculated from the `check_interval` attribute if set. There is no
`freshness_threshold` attribute in Icinga 2. If the freshness checks are invalid, a new `freshness_threshold` attribute in Icinga 2. If the freshness checks are invalid, a new
service check is forced. service check is forced.
### <a id="differences-1x-2-real-reload"></a> Real Reload ### Real Reload <a id="differences-1x-2-real-reload"></a>
In Nagios / Icinga 1.x a daemon reload does the following: In Nagios / Icinga 1.x a daemon reload does the following:
@ -1397,7 +1397,7 @@ execution during config validation:
* parent process continues with old configuration objects and the event scheduling * parent process continues with old configuration objects and the event scheduling
(doing checks, replicating cluster events, triggering alert notifications, etc.) (doing checks, replicating cluster events, triggering alert notifications, etc.)
* validation NOT ok: child process terminates, parent process continues with old configuration state * validation NOT ok: child process terminates, parent process continues with old configuration state
(this is **essential** for the [cluster config synchronisation](6-distributed-monitoring.md#distributed-monitoring-top-down-config-sync)) (this is **essential** for the [cluster config synchronisation](06-distributed-monitoring.md#distributed-monitoring-top-down-config-sync))
* validation ok: child process signals parent process to terminate and save its current state * validation ok: child process signals parent process to terminate and save its current state
(all events until now) into the icinga2 state file (all events until now) into the icinga2 state file
* parent process shuts down writing icinga2.state file * parent process shuts down writing icinga2.state file
@ -1411,14 +1411,14 @@ The configuration validation itself runs in parallel allowing fast verification
That way your monitoring does not stop during a configuration reload. That way your monitoring does not stop during a configuration reload.
### <a id="differences-1x-2-state-retention"></a> State Retention ### State Retention <a id="differences-1x-2-state-retention"></a>
Icinga 1.x uses the `retention.dat` file to save its state in order to be able Icinga 1.x uses the `retention.dat` file to save its state in order to be able
to reload it after a restart. In Icinga 2 this file is called `icinga2.state`. to reload it after a restart. In Icinga 2 this file is called `icinga2.state`.
The format is **not** compatible with Icinga 1.x. The format is **not** compatible with Icinga 1.x.
### <a id="differences-1x-2-logging"></a> Logging ### Logging <a id="differences-1x-2-logging"></a>
Icinga 1.x supports syslog facilities and writes its own `icinga.log` log file Icinga 1.x supports syslog facilities and writes its own `icinga.log` log file
and archives. These logs are used in Icinga 1.x Classic UI to generate and archives. These logs are used in Icinga 1.x Classic UI to generate
@ -1432,7 +1432,7 @@ FileLogger, StreamLogger. Each of them has their own severity and target configu
The Icinga 2 daemon log does not log any alerts but is considered an application log only. The Icinga 2 daemon log does not log any alerts but is considered an application log only.
### <a id="differences-1x-2-broker-modules-features"></a> Broker Modules and Features ### Broker Modules and Features <a id="differences-1x-2-broker-modules-features"></a>
Icinga 1.x broker modules are incompatible with Icinga 2. Icinga 1.x broker modules are incompatible with Icinga 2.
@ -1444,7 +1444,7 @@ popular broker modules was implemented for Icinga 2:
* Cluster (allows for high availability and load balancing) * Cluster (allows for high availability and load balancing)
### <a id="differences-1x-2-distributed-monitoring"></a> Distributed Monitoring ### Distributed Monitoring <a id="differences-1x-2-distributed-monitoring"></a>
Icinga 1.x uses the native "obsess over host/service" method which requires the NSCA addon Icinga 1.x uses the native "obsess over host/service" method which requires the NSCA addon
passing the slave's check results passively onto the master's external command pipe. passing the slave's check results passively onto the master's external command pipe.
@ -1454,7 +1454,7 @@ not synced between the master and slave nodes. There are addons available solvin
and configuration distribution problems Icinga 1.x distributed monitoring currently suffers from. and configuration distribution problems Icinga 1.x distributed monitoring currently suffers from.
Icinga 2 implements a new built-in Icinga 2 implements a new built-in
[distributed monitoring architecture](6-distributed-monitoring.md#distributed-monitoring-scenarios), [distributed monitoring architecture](06-distributed-monitoring.md#distributed-monitoring-scenarios),
including config and check distribution, IPv4/IPv6 support, SSL certificates and zone support for DMZ. including config and check distribution, IPv4/IPv6 support, SSL certificates and zone support for DMZ.
High Availability and load balancing are also part of the Icinga 2 Cluster feature, next to local replay High Availability and load balancing are also part of the Icinga 2 Cluster feature, next to local replay
logs on connection loss ensuring that the event history is kept in sync. logs on connection loss ensuring that the event history is kept in sync.

48
doc/23-appendix.md
View File

@ -1,6 +1,6 @@
# <a id="appendix"></a> Appendix # Appendix <a id="appendix"></a>
## <a id="external-commands-list-detail"></a> External Commands List ## External Commands List <a id="external-commands-list-detail"></a>
Additional details can be found in the [Icinga 1.x Documentation](https://docs.icinga.com/latest/en/extcommands2.html) Additional details can be found in the [Icinga 1.x Documentation](https://docs.icinga.com/latest/en/extcommands2.html)
@ -125,7 +125,7 @@ Additional details can be found in the [Icinga 1.x Documentation](https://docs.i
DISABLE_SERVICEGROUP_SVC_NOTIFICATIONS | ;&lt;servicegroup_name&gt; (1) | - DISABLE_SERVICEGROUP_SVC_NOTIFICATIONS | ;&lt;servicegroup_name&gt; (1) | -
## <a id="schemas"></a> Schemas ## Schemas <a id="schemas"></a>
By convention `CheckCommand`, `EventCommand`, and `NotificationCommand` objects By convention `CheckCommand`, `EventCommand`, and `NotificationCommand` objects
are exported using a prefix. This is mandatory for unique objects in the are exported using a prefix. This is mandatory for unique objects in the
@ -137,7 +137,7 @@ CheckCommand | check_
EventCommand | event_ EventCommand | event_
NotificationCommand | notification_ NotificationCommand | notification_
### <a id="schema-status-files"></a> Status Files ### Status Files <a id="schema-status-files"></a>
Status files used by Icinga 1.x Classic UI: `status.dat`, `objects.cache`. Status files used by Icinga 1.x Classic UI: `status.dat`, `objects.cache`.
@ -149,12 +149,12 @@ Icinga 2 specific extensions:
* 2.2 adds custom attributes with arrays and dictionaries. They are dumped as JSON encoded string and `_is_json` * 2.2 adds custom attributes with arrays and dictionaries. They are dumped as JSON encoded string and `_is_json`
is set as additional custom variable in `objects.cache`. is set as additional custom variable in `objects.cache`.
### <a id="schema-db-ido"></a> DB IDO Schema ### DB IDO Schema <a id="schema-db-ido"></a>
There is a detailed documentation for the Icinga IDOUtils 1.x There is a detailed documentation for the Icinga IDOUtils 1.x
database schema available on [https://docs.icinga.com/latest/en/db_model.html] database schema available on [https://docs.icinga.com/latest/en/db_model.html]
#### <a id="schema-db-ido-extensions"></a> DB IDO Schema Extensions #### DB IDO Schema Extensions <a id="schema-db-ido-extensions"></a>
Icinga 2 specific extensions are shown below: Icinga 2 specific extensions are shown below:
@ -207,9 +207,9 @@ New columns:
Additional command custom variables populated from 'vars' dictionary. Additional command custom variables populated from 'vars' dictionary.
Additional global custom variables populated from 'Vars' constant (object_id is NULL). Additional global custom variables populated from 'Vars' constant (object_id is NULL).
### <a id="schema-livestatus"></a> Livestatus Schema ### Livestatus Schema <a id="schema-livestatus"></a>
#### <a id="schema-livestatus-extensions"></a> Livestatus Schema Extensions #### Livestatus Schema Extensions <a id="schema-livestatus-extensions"></a>
Icinga 2 specific extensions are shown below: Icinga 2 specific extensions are shown below:
@ -259,7 +259,7 @@ New columns:
Command custom variables reflect the local 'vars' dictionary. Command custom variables reflect the local 'vars' dictionary.
Status custom variables reflect the global 'Vars' constant. Status custom variables reflect the global 'Vars' constant.
#### <a id="schema-livestatus-hosts-table-attributes"></a> Livestatus Hosts Table Attributes #### Livestatus Hosts Table Attributes <a id="schema-livestatus-hosts-table-attributes"></a>
Key | Type | Note Key | Type | Note
----------------------|-----------|------------------------- ----------------------|-----------|-------------------------
@ -364,7 +364,7 @@ Not supported: `initial_state`, `pending_flex_downtime`, `check_flapping_recover
`is_executing`, `check_options`, `obsess_over_host`, `first_notification_delay`, `x_3d`, `y_3d`, `z_3d`, `is_executing`, `check_options`, `obsess_over_host`, `first_notification_delay`, `x_3d`, `y_3d`, `z_3d`,
`x_2d`, `y_2d`, `filename`, `pnpgraph_present`. `x_2d`, `y_2d`, `filename`, `pnpgraph_present`.
#### <a id="schema-livestatus-hostgroups-table-attributes"></a> Livestatus Hostgroups Table Attributes #### Livestatus Hostgroups Table Attributes <a id="schema-livestatus-hostgroups-table-attributes"></a>
Key | Type | Note Key | Type | Note
----------------------|-----------|------------------------- ----------------------|-----------|-------------------------
@ -394,7 +394,7 @@ Not supported: `initial_state`, `pending_flex_downtime`, `check_flapping_recover
num_services_hard_crit | int | . num_services_hard_crit | int | .
num_services_hard_unknown | int | . num_services_hard_unknown | int | .
#### <a id="schema-livestatus-services-table-attributes"></a> Livestatus Services Table Attributes #### Livestatus Services Table Attributes <a id="schema-livestatus-services-table-attributes"></a>
Key | Type | Note Key | Type | Note
----------------------|-----------|------------------------- ----------------------|-----------|-------------------------
@ -481,7 +481,7 @@ Not supported: `initial_state`, `pending_flex_downtime`, `check_flapping_recover
Not supported: `initial_state`, `is_executing`, `check_options`, `obsess_over_service`, `first_notification_delay`, Not supported: `initial_state`, `is_executing`, `check_options`, `obsess_over_service`, `first_notification_delay`,
`pnpgraph_present`. `pnpgraph_present`.
#### <a id="schema-livestatus-servicegroups-table-attributes"></a> Livestatus Servicegroups Table Attributes #### Livestatus Servicegroups Table Attributes <a id="schema-livestatus-servicegroups-table-attributes"></a>
Key | Type | Note Key | Type | Note
----------------------|-----------|------------------------- ----------------------|-----------|-------------------------
@ -504,7 +504,7 @@ Not supported: `initial_state`, `is_executing`, `check_options`, `obsess_over_se
num_services_hard_crit | int | . num_services_hard_crit | int | .
num_services_hard_unknown | int | . num_services_hard_unknown | int | .
#### <a id="schema-livestatus-contacts-table-attributes"></a> Livestatus Contacts Table Attributes #### Livestatus Contacts Table Attributes <a id="schema-livestatus-contacts-table-attributes"></a>
Key | Type | Note Key | Type | Note
----------------------|-----------|------------------------- ----------------------|-----------|-------------------------
@ -527,7 +527,7 @@ Not supported: `initial_state`, `is_executing`, `check_options`, `obsess_over_se
Not supported: `can_submit_commands`. Not supported: `can_submit_commands`.
#### <a id="schema-livestatus-contactgroups-table-attributes"></a> Livestatus Contactgroups Table Attributes #### Livestatus Contactgroups Table Attributes <a id="schema-livestatus-contactgroups-table-attributes"></a>
Key | Type | Note Key | Type | Note
----------------------|-----------|------------------------- ----------------------|-----------|-------------------------
@ -536,7 +536,7 @@ Not supported: `can_submit_commands`.
members | array | . members | array | .
#### <a id="schema-livestatus-commands-table-attributes"></a> Livestatus Commands Table Attributes #### Livestatus Commands Table Attributes <a id="schema-livestatus-commands-table-attributes"></a>
Key | Type | Note Key | Type | Note
----------------------|-----------|------------------------- ----------------------|-----------|-------------------------
@ -544,7 +544,7 @@ Not supported: `can_submit_commands`.
line | string | . line | string | .
#### <a id="schema-livestatus-status-table-attributes"></a> Livestatus Status Table Attributes #### Livestatus Status Table Attributes <a id="schema-livestatus-status-table-attributes"></a>
Key | Type | Note Key | Type | Note
----------------------|-----------|------------------------- ----------------------|-----------|-------------------------
@ -583,7 +583,7 @@ Not supported: `neb_callbacks`, `neb_callbacks_rate`, `requests`, `requests_rate
`cached_log_messages`, `livestatus_queued_connections`, `livestatus_threads`. `cached_log_messages`, `livestatus_queued_connections`, `livestatus_threads`.
#### <a id="schema-livestatus-comments-table-attributes"></a> Livestatus Comments Table Attributes #### Livestatus Comments Table Attributes <a id="schema-livestatus-comments-table-attributes"></a>
Key | Type | Note Key | Type | Note
----------------------|-----------|------------------------- ----------------------|-----------|-------------------------
@ -602,7 +602,7 @@ Not supported: `neb_callbacks`, `neb_callbacks_rate`, `requests`, `requests_rate
host_ | join | Prefix for attributes from implicit join with hosts table. host_ | join | Prefix for attributes from implicit join with hosts table.
#### <a id="schema-livestatus-downtimes-table-attributes"></a> Livestatus Downtimes Table Attributes #### Livestatus Downtimes Table Attributes <a id="schema-livestatus-downtimes-table-attributes"></a>
Key | Type | Note Key | Type | Note
----------------------|-----------|------------------------- ----------------------|-----------|-------------------------
@ -623,7 +623,7 @@ Not supported: `neb_callbacks`, `neb_callbacks_rate`, `requests`, `requests_rate
host_ | join | Prefix for attributes from implicit join with hosts table. host_ | join | Prefix for attributes from implicit join with hosts table.
#### <a id="schema-livestatus-timeperiod-table-attributes"></a> Livestatus Timeperiod Table Attributes #### Livestatus Timeperiod Table Attributes <a id="schema-livestatus-timeperiod-table-attributes"></a>
Key | Type | Note Key | Type | Note
----------------------|-----------|------------------------- ----------------------|-----------|-------------------------
@ -631,7 +631,7 @@ Not supported: `neb_callbacks`, `neb_callbacks_rate`, `requests`, `requests_rate
alias | string | `display_name` attribute. alias | string | `display_name` attribute.
in | int | Current time is in timeperiod or not. in | int | Current time is in timeperiod or not.
#### <a id="schema-livestatus-log-table-attributes"></a> Livestatus Log Table Attributes #### Livestatus Log Table Attributes <a id="schema-livestatus-log-table-attributes"></a>
Key | Type | Note Key | Type | Note
----------------------|-----------|------------------------- ----------------------|-----------|-------------------------
@ -655,7 +655,7 @@ Not supported: `neb_callbacks`, `neb_callbacks_rate`, `requests`, `requests_rate
current_contact_ | join | Prefix for attributes from implicit join with contacts table. current_contact_ | join | Prefix for attributes from implicit join with contacts table.
current_command_ | join | Prefix for attributes from implicit join with commands table. current_command_ | join | Prefix for attributes from implicit join with commands table.
#### <a id="schema-livestatus-statehist-table-attributes"></a> Livestatus Statehist Table Attributes #### Livestatus Statehist Table Attributes <a id="schema-livestatus-statehist-table-attributes"></a>
Key | Type | Note Key | Type | Note
----------------------|-----------|------------------------- ----------------------|-----------|-------------------------
@ -690,17 +690,17 @@ Not supported: `neb_callbacks`, `neb_callbacks_rate`, `requests`, `requests_rate
Not supported: `debug_info`. Not supported: `debug_info`.
#### <a id="schema-livestatus-hostsbygroup-table-attributes"></a> Livestatus Hostsbygroup Table Attributes #### Livestatus Hostsbygroup Table Attributes <a id="schema-livestatus-hostsbygroup-table-attributes"></a>
All [hosts](23-appendix.md#schema-livestatus-hosts-table-attributes) table attributes grouped with All [hosts](23-appendix.md#schema-livestatus-hosts-table-attributes) table attributes grouped with
the [hostgroups](23-appendix.md#schema-livestatus-hostgroups-table-attributes) table prefixed with `hostgroup_`. the [hostgroups](23-appendix.md#schema-livestatus-hostgroups-table-attributes) table prefixed with `hostgroup_`.
#### <a id="schema-livestatus-servicesbygroup-table-attributes"></a> Livestatus Servicesbygroup Table Attributes #### Livestatus Servicesbygroup Table Attributes <a id="schema-livestatus-servicesbygroup-table-attributes"></a>
All [services](23-appendix.md#schema-livestatus-services-table-attributes) table attributes grouped with All [services](23-appendix.md#schema-livestatus-services-table-attributes) table attributes grouped with
the [servicegroups](23-appendix.md#schema-livestatus-servicegroups-table-attributes) table prefixed with `servicegroup_`. the [servicegroups](23-appendix.md#schema-livestatus-servicegroups-table-attributes) table prefixed with `servicegroup_`.
#### <a id="schema-livestatus-servicesbyhostgroup-table-attributes"></a> Livestatus Servicesbyhostgroup Table Attributes #### Livestatus Servicesbyhostgroup Table Attributes <a id="schema-livestatus-servicesbyhostgroup-table-attributes"></a>
All [services](23-appendix.md#schema-livestatus-services-table-attributes) table attributes grouped with All [services](23-appendix.md#schema-livestatus-services-table-attributes) table attributes grouped with
the [hostgroups](23-appendix.md#schema-livestatus-hostgroups-table-attributes) table prefixed with `hostgroup_`. the [hostgroups](23-appendix.md#schema-livestatus-hostgroups-table-attributes) table prefixed with `hostgroup_`.