-# <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
your network resources, notifies users of outages, and generates performance
Scalable and extensible, Icinga 2 can monitor large, complex environments across
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
General Public License Version 2, you will find a copy of this license in the
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
[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/).
-## <a id="contribute"></a> Contribute
+## Contribute <a id="contribute"></a>
There are many ways to contribute to Icinga -- whether it be sending patches,
testing, reporting bugs, or reviewing and updating the documentation. Every
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).
Read more about development builds in the [INSTALL.md](https://github.com/Icinga/icinga2/blob/master/INSTALL.md)
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
* 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 [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 [4954](https://github.com/Icinga/icinga2/issues/4954) (Documentation): Add an example for /v1/actions/process-check-result which uses filter/type
#### 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 [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
-# <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)
-and [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2).
+This tutorial is a step-by-step introduction to installing [Icinga 2](02-getting-started.md#setting-up-icinga2)
+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.
-## <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
is to use the official package repositories depending on which operating system
Packages for distributions other than the ones listed above may also be
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.
Below is a list with examples for the various distributions.
# 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
as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL).
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).
-#### <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
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
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
to install the `icinga2` package.
# 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
Icinga 2 installation:
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:
/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.
-## <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
[Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
an extensive set of plugins which can be used with Icinga 2 to check whether
services are working properly.
-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.
For your convenience here is a list of package names for some of the more
# pkg install monitoring-plugins
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
to determine where to find the plugin binaries.
> **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.
-## <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:
using the init script. Using Debian packages the user and group are set to
`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
Icinga 2 packages automatically install the necessary systemd unit files.
# 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.
The RHEL and SUSE package `icinga2-common` installs these files into `/usr/share/doc/icinga2-common-[x.x.x]/syntax`
On Debian systems the `icinga2-common` package provides only the Nano configuration file (`/usr/share/nano/icinga2.nanorc`);
to obtain the Vim configuration, please install the extra package `vim-icinga2`. The files are located in `/usr/share/vim/addons`.
-### <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.
-### <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.
-## <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.
This chapter explains how to set up Icinga Web 2.
The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of
exporting all configuration and status information into a database. The IDO
database is used by a number of projects including
-[Icinga Web 2](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.
There is a separate module for each database backend. At present support for
both MySQL and PostgreSQL is implemented.
-Please choose whether to install [MySQL](2-getting-started.md#configuring-db-ido-mysql) or
-[PostgreSQL](2-getting-started.md#configuring-db-ido-postgresql).
+Please choose whether to install [MySQL](02-getting-started.md#configuring-db-ido-mysql) or
+[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:
# service mysql-server restart
# 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
distribution's package manager.
> default. You can skip the automated setup and install/upgrade the
> database manually if you prefer that.
-#### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
+#### Setting up the MySQL database <a id="setting-up-mysql-db"></a>
Set up a MySQL database for Icinga 2:
# 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
`/etc/icinga2/features-available/ido-mysql.conf`. You will need to
update the database credentials in this file.
All available attributes are explained in the
-[IdoMysqlConnection object](9-object-types.md#objecttype-idomysqlconnection)
+[IdoMysqlConnection object](09-object-types.md#objecttype-idomysqlconnection)
chapter.
You can enable the `ido-mysql` feature configuration file using
# 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:
# sysrc postgresql_enable=yes
# 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
distribution's package manager.
-#### <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
`/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update
the database credentials in this file.
All available attributes are explained in the
-[IdoPgsqlConnection object](9-object-types.md#objecttype-idopgsqlconnection)
+[IdoPgsqlConnection object](09-object-types.md#objecttype-idopgsqlconnection)
chapter.
You can enable the `ido-pgsql` feature configuration file using
# 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:
# service php-fpm 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:
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)
to send actions (reschedule check, etc.) and query object details.
# 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)
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)
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
popular addons is available in the
[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:
-# <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
monitoring concepts you need to know to run Icinga 2.
using Windows, you will need to change the services accordingly. See the [ITL reference](10-icinga-template-library.md#windows-plugins)
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
and services can be virtually anything which can be checked in some way:
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:
UP | The host is available.
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:
CRITICAL | The service is in a critical 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
times (based on the `max_check_attempts` and `retry_interval` settings) before sending
HARD | The host/service's state hasn't recently changed.
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.
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
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:
* [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)
-* [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.
The special case here is that whenever Icinga 2 needs the value for such a custom attribute it runs
}
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
are used in command definitions to figure out which IP address a check should be
> 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
up macros and their respective values:
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
hosts or services:
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.
-### <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
services:
service.last_check | The timestamp when the last check was executed.
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:
-----------------------|--------------
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
users:
user.name | The name of the user object.
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
-----------------------|--------------
notification.author | The author of the notification comment 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:
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),
-[Notification](9-object-types.md#objecttype-notification), [Dependency](9-object-types.md#objecttype-dependency),
-[ScheduledDowntime](9-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)
+Several object types require an object relation, e.g. [Service](09-object-types.md#objecttype-service),
+[Notification](09-object-types.md#objecttype-notification), [Dependency](09-object-types.md#objecttype-dependency),
+[ScheduledDowntime](09-object-types.md#objecttype-scheduleddowntime) objects.
+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.
object Service "ping4" {
}
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**.
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:
* Define the best match.
- * A set of unique [custom attributes](3-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?
+ * A set of unique [custom attributes](03-monitoring-basics.md#custom-attributes) for these hosts/services?
+ * 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?
- * [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.)
More specific object type requirements are described in these chapters:
-* [Apply services to hosts](3-monitoring-basics.md#using-apply-services)
-* [Apply notifications to hosts and services](3-monitoring-basics.md#using-apply-notifications)
-* [Apply dependencies to hosts and services](3-monitoring-basics.md#using-apply-dependencies)
-* [Apply scheduled downtimes to hosts and services](3-monitoring-basics.md#using-apply-scheduledowntimes)
+* [Apply services to hosts](03-monitoring-basics.md#using-apply-services)
+* [Apply notifications to hosts and services](03-monitoring-basics.md#using-apply-notifications)
+* [Apply dependencies to hosts and services](03-monitoring-basics.md#using-apply-dependencies)
+* [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
objects in that scope (host and/or service objects).
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
("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
-dictionaries](3-monitoring-basics.md#using-apply-for) provided by
-[custom atttributes](3-monitoring-basics.md#custom-attributes) or groups.
+dictionaries](03-monitoring-basics.md#using-apply-for) provided by
+[custom atttributes](03-monitoring-basics.md#custom-attributes) or groups.
> **Tip**
>
> 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
expression must evaluate into the boolean `true` value. An empty string
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 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):
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)
-and [services.conf](4-configuring-icinga-2.md#services-conf) for this use case.
+The sample configuration already includes a detailed example in [hosts.conf](04-configuring-icinga-2.md#hosts-conf)
+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`
attribute being defined and the custom attribute `os` set to the string `Linux` in `vars`.
}
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
manner:
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
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)
-and [services.conf](4-configuring-icinga-2.md#services-conf) for this use case.
+The sample configuration already includes a detailed example in [hosts.conf](04-configuring-icinga-2.md#hosts-conf)
+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
types. This could look like the following example:
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)
with many interfaces (services). The following requirements/problems apply:
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"
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.
object Host "cisco-catalyst-6509-34" {
This example makes use of the [check_iftraffic](https://exchange.icinga.com/exchange/iftraffic) plugin.
The `CheckCommand` definition can be found in the
[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**
* 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
can reference existing host and/or service object attributes as
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
visualization aid in web interfaces.
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
to a group based on their attributes:
Details on the `assign where` syntax can be found in the
[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
monitoring setup.
case of emergency, and also which information does not provide any value to you and
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
to the defined notifications. That way you'll save duplicated attributes in each
**Note**: Only users who have been notified of a problem before (`Warning`, `Critical`, `Unknown`
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
you may want to escalate the problem to the next support level. A different approach
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**
>
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
(the object reaching the `HARD` state), but after a certain period. In Icinga 2
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
`interval` attribute to `0`.
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`
or `User` object, Icinga 2 assumes that all states and types are being notified.
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
checks should be performed, notifications should be sent, and
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.
-[CheckCommand](9-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
+[CheckCommand](09-object-types.md#objecttype-checkcommand) objects are referenced by
+[Host](09-object-types.md#objecttype-host) and [Service](09-object-types.md#objecttype-service) objects
using the `check_command` attribute.
> **Note**
> Make sure that the [checker](11-cli-commands.md#enable-features) feature is enabled in order to
> 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
-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.
The plugin path and all command arguments are made a list of
[-u user] [-p password] [-S] [-l] [-a cert] [-k key]
[-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)
-are being passed from a host or service object, and add a [CheckCommand](9-object-types.md#objecttype-checkcommand)
+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](09-object-types.md#objecttype-checkcommand)
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
by the executed check command.
[here](10-icinga-template-library.md#plugin-check-commands), for example
[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`
(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.
> **Tip**
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`.
-`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.
# vim /etc/icinga2/conf.d/services.conf
}
-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`.
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" {
import "generic-service"
}
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 {
...
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
-[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%`
free disk space).
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
will resolve all macros in the static string or array. Sometimes it is
without SSL enabled checks saving you duplicated command definitions.
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
from either runtime macros or custom attributes which should be exported as environment variables
-### <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
(email, XMPP, IRC, Twitter, etc.).
-[NotificationCommand](9-object-types.md#objecttype-notificationcommand)
-objects are referenced by [Notification](9-object-types.md#objecttype-notification)
+[NotificationCommand](09-object-types.md#objecttype-notificationcommand)
+objects are referenced by [Notification](09-object-types.md#objecttype-notification)
objects using the `command` attribute.
> **Note**
> This example requires the `mail` binary installed on the Icinga 2
> 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
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
-macros](3-monitoring-basics.md#-host-runtime-macros) for further
+macros](03-monitoring-basics.md#-host-runtime-macros) for further
information.
Name | Description
`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`.
-#### <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
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
-macros](3-monitoring-basics.md#-service-runtime-macros) for further
+macros](03-monitoring-basics.md#-service-runtime-macros) for further
information.
Name | Description
`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`.
-### <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
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 state changes into a [hard state](3-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 is in a [soft state](03-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](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
-[Host](9-object-types.md#objecttype-host) and [Service](9-object-types.md#objecttype-service) objects
+[EventCommand](09-object-types.md#objecttype-eventcommand) objects are referenced by
+[Host](09-object-types.md#objecttype-host) and [Service](09-object-types.md#objecttype-service) objects
with the `event_command` attribute.
Therefore the `EventCommand` object should define a command line
and `$service.state$` will be processed by Icinga 2 and help with fine-granular
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
command).
to forward more details on state changes and events than the typical notification
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
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 EventCommand "send_to_businesstool" {
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
when the `procs` service check executed via Command Endpoint fails. It only
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`
-which allows to trigger local service restarts. Put it into a [global zone](6-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync)
+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](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync)
to sync its configuration to all clients.
[root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/global-templates/eventcommands.conf
[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
when the `service-windows` service check executed via Command Endpoint fails.
* Icinga 2 as client on the remote node
* 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`
-which allows to trigger local service restarts. Put it into a [global zone](6-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync)
+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](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync)
to sync its configuration to all clients.
[root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/global-templates/eventcommands.conf
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
via SSH when the `http` service check fails.
# visudo
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:
[root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/master/local_eventcommands.conf
[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.
A service can depend on a host, and vice versa. A service has an implicit
The `parent_host_name` and `parent_service_name` attributes are mandatory for
service dependencies, `parent_host_name` is required for host dependencies.
-[Apply rules](3-monitoring-basics.md#using-apply) will allow you to
-[determine these attributes](3-monitoring-basics.md#dependencies-apply-custom-attributes) in a more
+[Apply rules](03-monitoring-basics.md#using-apply) will allow you to
+[determine these attributes](03-monitoring-basics.md#dependencies-apply-custom-attributes) in a more
dynamic fashion if required.
parent_host_name = "core-router"
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).
-### <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
service notifications are suppressed when a host is `DOWN` or `UNREACHABLE`. This dependency
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
access by pinging the Google DNS server `google-dns` is a common method, but
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'
attributes.
> 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
for the agent daemon responding to your requests, and make all other services
-# <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.
The configuration files which are automatically created when installing the Icinga 2 packages
The [Language Reference](17-language-reference.md#language-reference) chapter explains details
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,
dependencies, etc., you should think about the requirements first and then
* 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
-[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.
* You are required to define specific configuration for each host/service?
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
-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:
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.
* 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.
-* 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
+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](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.
* 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
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)?
-There is a detailed chapter on [distributed monitoring scenarios](6-distributed-monitoring.md#distributed-monitoring-scenarios).
-Please ensure to have read the [introduction](6-distributed-monitoring.md#distributed-monitoring) at first glance.
+There is a detailed chapter on [distributed monitoring scenarios](06-distributed-monitoring.md#distributed-monitoring-scenarios).
+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
[community support channels](https://www.icinga.com/community/get-involved/)
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
`include_recursive "conf.d"` from your icinga2.conf file.
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.
-## <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`.
include "zones.conf"
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
This `include_recursive` directive is used for discovery of services on remote clients
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
-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.
*/
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.
-### <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.
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
[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 `ZoneName` and `TicketSalt` constants are required for remote client
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)
-and [Endpoint](9-object-types.md#objecttype-endpoint) configuration object for
-[distributed monitoring](6-distributed-monitoring.md#distributed-monitoring).
+This file can be used to specify the required [Zone](09-object-types.md#objecttype-zone)
+and [Endpoint](09-object-types.md#objecttype-endpoint) configuration object for
+[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.
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.
-### <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
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.
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**
>
-> 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.
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:
-* [hosts.conf](4-configuring-icinga-2.md#hosts-conf)
-* [services.conf](4-configuring-icinga-2.md#services-conf)
-* [users.conf](4-configuring-icinga-2.md#users-conf)
-* [notifications.conf](4-configuring-icinga-2.md#notifications-conf)
-* [commands.conf](4-configuring-icinga-2.md#commands-conf)
-* [groups.conf](4-configuring-icinga-2.md#groups-conf)
-* [templates.conf](4-configuring-icinga-2.md#templates-conf)
-* [downtimes.conf](4-configuring-icinga-2.md#downtimes-conf)
-* [timeperiods.conf](4-configuring-icinga-2.md#timeperiods-conf)
-* [satellite.conf](4-configuring-icinga-2.md#satellite-conf)
-* [api-users.conf](4-configuring-icinga-2.md#api-users-conf)
-* [app.conf](4-configuring-icinga-2.md#app-conf)
-
-#### <a id="hosts-conf"></a> hosts.conf
+* [hosts.conf](04-configuring-icinga-2.md#hosts-conf)
+* [services.conf](04-configuring-icinga-2.md#services-conf)
+* [users.conf](04-configuring-icinga-2.md#users-conf)
+* [notifications.conf](04-configuring-icinga-2.md#notifications-conf)
+* [commands.conf](04-configuring-icinga-2.md#commands-conf)
+* [groups.conf](04-configuring-icinga-2.md#groups-conf)
+* [templates.conf](04-configuring-icinga-2.md#templates-conf)
+* [downtimes.conf](04-configuring-icinga-2.md#downtimes-conf)
+* [timeperiods.conf](04-configuring-icinga-2.md#timeperiods-conf)
+* [satellite.conf](04-configuring-icinga-2.md#satellite-conf)
+* [api-users.conf](04-configuring-icinga-2.md#api-users-conf)
+* [app.conf](04-configuring-icinga-2.md#app-conf)
+
+#### hosts.conf <a id="hosts-conf"></a>
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
values.
in the Icinga Template Library require an `address` attribute.
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
* 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`
-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
-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
-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`
check.
}
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**
>
> 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.
-#### <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
the local host, but also allow you to re-use or modify them for
The custom attribe `backup_downtime` is defined to a specific timerange string.
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
evaluated for all objects of type `Host` and a new service with name "load"
hosts, you can go one step further: Generate apply rules based on array items
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`.
-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`. */
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
-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
the `disk` variable in `key => config` as new service object name.
host the information provider for all apply rules. Define them once, and only
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
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.
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
-[hosts.conf](4-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.
+[hosts.conf](04-configuring-icinga-2.md#hosts-conf) for defining a custom host attribute later used in
+[notifications.conf](04-configuring-icinga-2.md#notifications-conf) for notification apply rules.
object User "icingaadmin" {
import "generic-user"
}
-#### <a id="notifications-conf"></a> notifications.conf
+#### notifications.conf <a id="notifications-conf"></a>
Notifications for check alerts are an integral part or your
Icinga 2 monitoring stack.
Both `apply` rules match on the same condition: They are only applied if the
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.
-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
-respective [host.vars.notification.mail](4-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).
+respective [host.vars.notification.mail](04-configuring-icinga-2.md#hosts-conf) attribute we'll
+implicitely use the `icingaadmins` UserGroup defined in [users.conf](04-configuring-icinga-2.md#users-conf).
apply Notification "mail-icingaadmin" to Host {
import "mail-host-notification"
}
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
-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.
-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
custom attribute `os` set to `Linux` and is therefore automatically
a member of the host group `linux-servers`.
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" {
display_name = "Linux Servers"
}
-#### <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
default:
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 [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.
apply ScheduledDowntime "backup-downtime" to Service {
}
-#### <a id="timeperiods-conf"></a> timeperiods.conf
+#### timeperiods.conf <a id="timeperiods-conf"></a>
This file contains the default timeperiod definitions for `24x7`, `9to5`
and `never`. TimePeriod objects are referenced by `*period`
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
-[monitoring remote clients](6-distributed-monitoring.md#distributed-monitoring)
+[monitoring remote clients](06-distributed-monitoring.md#distributed-monitoring)
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.
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).
-#### <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
globally, etc.
-# <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
community plugins available next to the standard plugins provided by
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
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
-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:
# cp check_snmp_int.pl /opt/monitoring/plugins
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.
-### <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
-configuration which can be used in the [Service](9-object-types.md#objecttype-service) or
-[Host](9-object-types.md#objecttype-host) object definition.
+Each plugin requires a [CheckCommand](09-object-types.md#objecttype-checkcommand) object in your
+configuration which can be used in the [Service](09-object-types.md#objecttype-service) or
+[Host](09-object-types.md#objecttype-host) object definition.
Please check if the Icinga 2 package already provides an
[existing CheckCommand definition](10-icinga-template-library.md#plugin-check-commands).
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.
* 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.
* 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:
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
[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).
-### <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
can either kindly contact the original author about plans to add changes
* 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.
* 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
Example skeleton:
Once you've finished your plugin please upload/sync it to [Icinga Exchange](https://exchange.icinga.com/new).
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.
There is a variety of plugins available. This collection is not complete --
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),
and if a check plugin is also available, you don't necessarily need a local client.
* [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)
-### <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)
* [mem](10-icinga-template-library.md#plugin-contrib-command-mem), [swap](10-icinga-template-library.md#plugin-check-command-swap)
* [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)
-### <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/)
* [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
* 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)
* PostgreSQL: [postgres](10-icinga-template-library.md#plugin-contrib-command-postgres)
* Elasticsearch: [elasticsearch](10-icinga-template-library.md#plugin-contrib-command-elasticsearch)
* 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)
* [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)
* [interfaces](10-icinga-template-library.md#plugin-contrib-command-interfaces)
* [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)
-### <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)
* [ftp](10-icinga-template-library.md#plugin-check-command-ftp)
* [kdc](10-icinga-template-library.md#plugin-contrib-command-kdc)
* [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)
-### <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)
* [dig](10-icinga-template-library.md#plugin-check-command-dig)
* [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)
-### <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_logstash](https://github.com/widhalmt/check_logstash)
* [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)
* [VMware](10-icinga-template-library.md#plugin-contrib-vmware)
**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).
-### <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)
* [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)
* [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)
* [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)
* [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)
-# <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
environment, including high-availability clustering and setup details
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:
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
-[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
-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.
-## <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.
to send configuration commands to the parent zone members. Vice versa, the
trust hierarchy allows for example the `master` zone to send
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
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.
the `endpoints` attribute with an array of `Endpoint` names.
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
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.
for accepting configuration commands.
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.
Just keep in mind that you need to use the FQDN for endpoints and for
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
nodes (firewalls, policies, software hardening, etc.), Icinga 2 also provides
* 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.
* 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 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.
-## <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
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
-the required [plugins](2-getting-started.md#setting-up-check-plugins) if you haven't done
+Install the [Icinga 2 package](02-getting-started.md#setting-up-icinga2) and setup
+the required [plugins](02-getting-started.md#setting-up-check-plugins) if you haven't done
so already.
**Note**: Windows is not supported for a master node setup.
[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.
-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
certificate requests. You then have to also re-create new signed certificates for all
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
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
-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`.
-### <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
involves that the setup wizard sends a certificate signing request (CSR) to the
There is a security mechanism in place which requires the client to send in a valid
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.
There are two possible ways to retrieve the ticket:
**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
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
-the required [plugins](2-getting-started.md#setting-up-check-plugins) if you haven't done
+Install the [Icinga 2 package](02-getting-started.md#setting-up-icinga2) and setup
+the required [plugins](02-getting-started.md#setting-up-check-plugins) if you haven't done
so already.
The next step is to run the `node wizard` CLI command. Prior to that
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.
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 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 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 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](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:
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
-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/).
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
-[this chapter](6-distributed-monitoring.md#distributed-monitoring-windows-nscp).
-The Windows package also installs native [monitoring plugin binaries](6-distributed-monitoring.md#distributed-monitoring-windows-plugins)
+[this chapter](06-distributed-monitoring.md#distributed-monitoring-windows-nscp).
+The Windows package also installs native [monitoring plugin binaries](06-distributed-monitoring.md#distributed-monitoring-windows-plugins)
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.
Parameter | Description
--------------------|--------------------
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.
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 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.
- Install NSClient++ | **Optional.** The Windows installer bundles the NSClient++ installer for additional [plugin checks](6-distributed-monitoring.md#distributed-monitoring-windows-nscp).
+ 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](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](06-distributed-monitoring.md#distributed-monitoring-windows-nscp).
-#### <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
you to do so.
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/).
-#### <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.
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.
-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
the `zones.conf` file in your preferred editor. Add the following lines if not existing already:
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
checks, send notifications, etc.
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.
-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.
**Note**: Check results are always sent from the child nodes to the parent nodes.
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.
Again, technically it does not matter whether this is a `client` or a `satellite`
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.
The host/service object configuration is located on the master/satellite and the client only
* No local checks need to be defined on the child node (client).
* 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).
Disadvantages:
* If the child node is not connected, no more checks are executed.
* 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
commands, you need to configure the `Zone` and `Endpoint` 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:
[root@icinga2-client1.localdomain /]# vim /etc/icinga2/zones.conf
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
-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.
-### <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.
It comes in handy if you want to configure everything on the master node
[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.).
Once the clients have connected successfully, it's time for the next step: **execute
**not supported**.
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.
-### <a id="distributed-monitoring-bottom-up"></a> Bottom Up Import
+### Bottom Up Import <a id="distributed-monitoring-bottom-up"></a>
> **Warning**
>
> 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).
them from this directory and restart Icinga 2.
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
on the master, use the `icinga2 node {black,white}list`
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
-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 `/etc/icinga2/repository.d` directory. This is achieved by running the
that blacklist and whitelist settings are evaluated.
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`
ensure that all your clients **do not include conf.d in their icinga2.conf**
**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:
[root@icinga2-client3.localdomain /]# vim /etc/icinga2/zones.conf
**Steps on the configuration master node**:
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.
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 [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.
[root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/master/icinga2-client3.localdomain.conf
and add them into the `/etc/icinga2/zones.d/master/icinga2-client3.localdomain.conf`
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
your own needs.
If you are eager to start fresh instead you might take a look into the
[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
distributed monitoring environment. We've seen them all in production
* HA master with clients as 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>
Setup requirements:
-* Set up `icinga2-master1.localdomain` as [master](6-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-master1.localdomain` as [master](06-distributed-monitoring.md#distributed-monitoring-setup-master).
+* 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:
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
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
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`).
-### <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>
-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.
The setup uses the capabilities of the Icinga 2 cluster. All zone members
Setup requirements:
-* Set up `icinga2-master1.localdomain` as [master](6-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-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-master1.localdomain` as [master](06-distributed-monitoring.md#distributed-monitoring-setup-master).
+* 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](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
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
-[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.
* 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.
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'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
Create a new configuration directory on the master node `icinga2-master1.localdomain`.
**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
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`).
-**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.
-### <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>
Setup requirements:
-* Set up `icinga2-master1.localdomain` as [master](6-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-client1.localdomain` and `icinga2-client2.localdomain` as [clients](6-distributed-monitoring.md#distributed-monitoring-setup-satellite-client).
+* 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](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](06-distributed-monitoring.md#distributed-monitoring-setup-satellite-client).
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.
Port [5665]:
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.
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.
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.
[root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.conf
Repeat the configuration step for `icinga2-master2.localdomain`, `icinga2-satellite1.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.
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.
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'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`:
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`).
-**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.
-## <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.
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
to all nodes depending on them. Common examples are:
[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
-### <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
either have late check results or just send out mass alarms for unknown
}
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
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
the `command_endpoint` attribute. This is reasonable if you want to
zone. In addition to that the [match](18-library-reference.md#global-functions-match)
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
change that by [adding a new rule](https://support.microsoft.com/en-us/kb/947709).
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.
Detailed [documentation](10-icinga-template-library.md#windows-plugins) is available for all check command definitions.
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.
First, add the client node as host object:
-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.
-### <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++:
-* Query the [HTTP API](6-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)
+* 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](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
note: If you rely on performance counter delta calculations such as
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
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
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.
Define a host object called `icinga2-client2.localdomain` on the master. Add the `nscp_api_password`
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`:
[root@icinga2-master1.localdomain /etc/icinga2/zones.d/master]# vim services.conf
You can verify the check execution by looking at the `Check Source` attribute
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
use the [nscp-local commands](10-icinga-template-library.md#nscp-plugin-check-commands)
provided by the Icinga Template Library (ITL).
The CheckCommand definitions will automatically determine the installed path
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.
First, add the client node as host object:
-## <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
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).
By default, the following features provide advanced HA functionality:
-* [Checks](6-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).
-* [DB IDO](6-distributed-monitoring.md#distributed-monitoring-high-availability-db-ido) (Run-Once, automated failover).
+* [Checks](06-distributed-monitoring.md#distributed-monitoring-high-availability-checks) (load balanced, automated failover).
+* [Notifications](06-distributed-monitoring.md#distributed-monitoring-high-availability-notifications) (load balanced, 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
have the `checker` feature enabled.
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.
-#### <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
have the `notification` feature enabled.
is enabled.
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`
-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
have the DB IDO feature enabled.
not necessarily the zone master.
**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
-[IdoPgsqlConnection](9-object-types.md#objecttype-idopgsqlconnection) object on **all** nodes in the
+for the [IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection) or
+[IdoPgsqlConnection](09-object-types.md#objecttype-idopgsqlconnection) object on **all** nodes in the
**same** zone.
All endpoints will enable the DB IDO feature and connect to the configured
data duplication in split-brain-scenarios. The failover timeout can be set for the
`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).
Example for the master node `icinga2-master1.localdomain` actively connecting
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
keep the same history (check results, notifications, etc.) when nodes are temporarily
disconnected and then reconnect.
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.
-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
client is not connected.
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
to allow both to sign requested certificates. Ensure to safely sync the following
* `TicketSalt` constant in `constants.conf`.
* `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).
Make sure that the directory permissions for `/var/lib/icinga2/ca` are secure
(not world readable).
**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).
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.)
or custom scripts for automated setup.
These are collected best practices from various community channels.
-* [Silent Windows setup](6-distributed-monitoring.md#distributed-monitoring-automation-windows-silent)
-* [Node Setup CLI command](6-distributed-monitoring.md#distributed-monitoring-automation-cli-node-setup) with parameters
+* [Silent Windows setup](06-distributed-monitoring.md#distributed-monitoring-automation-windows-silent)
+* [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`).
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/).
-### <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
installation should not trigger a restart, but if you want to be completly sure, you can use the `/norestart` modifier.
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`
command available which has some prerequisites.
**Note**: The CLI command can be used on Linux/Unix and Windows operating systems.
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
to the `node setup` CLI command. In addition to that the `--cn` can optionally
--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`
user (or the user Icinga 2 is running as).
Parameter | Description
--------------------|--------------------
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).
Master endpoint | **Required.** Specify the master's endpoint name.
Client zone name | **Required.** Specify the client's zone name.
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 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 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](06-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint)).
Example:
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.
[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.
[root@icinga2-client1.localdomain /]# sed -i 's/include_recursive "conf.d"/\/\/include_recursive "conf.d"/g' /etc/icinga2/icinga2.conf
-# <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
local agent installation exposing the results to check queries can
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
-binaries. The [Monitoring Plugins package](2-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)
+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](05-service-monitoring.md#service-monitoring-plugins)
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
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`.
-## <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
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" {
import "by_ssh"
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
known for its magnificent Windows support. There are alternatives like the WMI interface,
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
remote sender to push check results into the Icinga 2 `ExternalCommandListener`
> 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.
-## <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
the required plugins and command definitions.
> The NRPE protocol is considered insecure and has multiple flaws in its
> 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.
The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe`
/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.
-## <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/)
and specific trap handlers passing the check results to Icinga 2.
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.
-### <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.
Building the event to auto reset after dispatching a notification is important.
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
for a backup scenario where the backup software dispatches status updates. By
-# <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
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
any other targeted service outage you are aware of in advance.
state triggering a problem notification, and the service recovers during
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
removed at the end time. During this time window the service state
its trigger time until the duration is over. After that, the downtime
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
[schedule-downtime](12-icinga2-api.md#icinga2-api-actions-schedule-downtime) or
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
end time window, the downtime will be marked as `in effect` and
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
triggered from a host/service NOT-OK state change. It will then last
```
-### <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
scheduled for a future maintenance, the current downtime can be triggered by
are now scheduling a child host's downtime getting triggered by the parent
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.
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
add useful information for others on repeating incidents (for example
[add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) or
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
acknowledge the problem. That way other users will get
a notification that you're aware of the issue and probably are
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.
You can send an acknowledgement either by using the Icinga 2 API action
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
recovers (OK/Up state).
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`
dashboard and no-one ever looks at it again since it will suppress
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
example whether a service check is executed or not within
the `check_period` attribute. Or a notification should be sent to
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
your default time period definitions, for example, if you don't
want to send out any notification during the holiday season,
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.
`prefer_includes` defines whether included or excluded time periods are
preferred.
}
}
-## <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
`check_interval` attribute and no incoming check results in that period of time.
`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".
Flapping detection can be enabled or disabled using the `enable_flapping` attribute.
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
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
occurs, the `SOFT` state applies and once `max_check_attempts` attribute
service recheck will automatically trigger a notification unless the
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
service application on your server. There are predictable issues
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)
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 | 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.
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.
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.
There is a built-in [ido](10-icinga-template-library.md#itl-icinga-ido) check available for DB IDO MySQL/PostgreSQL
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.
-## <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.
-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.
The following example defines a dictionary on the host object which contains
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.
-### <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:
-* As value for [Custom Attributes](3-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 a [command](8-advanced-topics.md#use-functions-command-attribute) array inside command objects
+* As value for [Custom Attributes](03-monitoring-basics.md#custom-attributes-functions)
+* Returning boolean expressions for [set_if](08-advanced-topics.md#use-functions-command-arguments-setif) inside command arguments
+* 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.
>
> 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
-> 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:
* 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.
-#### <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
-[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.
By default you can evaluate runtime macros for their existence. If the result is not an empty
}
-#### <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)
-or [EventCommands](9-object-types.md#objecttype-eventcommand) which does not require
+This comes in handy for [NotificationCommands](09-object-types.md#objecttype-notificationcommand)
+or [EventCommands](09-object-types.md#objecttype-eventcommand) which does not require
a returned checkresult including state/output.
The following example was taken from the community support channels. The requirement was to
}
}
-#### <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
slightly unexpected way. The following example shows how to assign values
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
exists in an array or dictionary does not fit, you should consider
writing your own global [functions](17-language-reference.md#functions).
You can call them inside `assign where` and `ignore where` expressions
-for [apply rules](3-monitoring-basics.md#using-apply-expressions) or
-[group assignments](3-monitoring-basics.md#group-assign-intro) just like
+for [apply rules](03-monitoring-basics.md#using-apply-expressions) or
+[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).
The following example requires the host `myprinter` being added
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)
can be used to retrieve references to other objects by name.
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
cluster state and output:
-# <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
instantiated using the `object` keyword.
type | Object type.
original_attributes | Original values of object attributes modified at runtime.
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.
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
and API usage specifying the certificate files used for ssl
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:
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`.
-## <a id="objecttype-apiuser"></a> ApiUser
+## ApiUser <a id="objecttype-apiuser"></a>
ApiUser objects are used for authentication against the Icinga 2 API.
Available permissions are described in the [API permissions](12-icinga2-api.md#icinga2-api-permissions)
chapter.
-## <a id="objecttype-checkcommand"></a> CheckCommand
+## CheckCommand <a id="objecttype-checkcommand"></a>
A check command definition. Additional default command custom attributes can be
defined here.
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`
dictionary. If the argument requires additional configuration, for example
`'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.
--------------------|----------------
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
to help existing Icinga 1.x users and might be useful for certain cluster
----------------|----------------
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.
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.
-## <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.
-## <a id="objecttype-dependency"></a> Dependency
+## Dependency <a id="objecttype-dependency"></a>
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
> 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
> 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:
Up
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.
Service-to-Host Dependency Example:
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.
-## <a id="objecttype-downtime"></a> Downtime
+## Downtime <a id="objecttype-downtime"></a>
Downtimes created at runtime are represented as objects.
end_time | **Required.** The end time as unix timestamp.
duration | **Required.** The duration as number.
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.
Runtime Attributes:
-## <a id="objecttype-endpoint"></a> Endpoint
+## Endpoint <a id="objecttype-endpoint"></a>
Endpoint objects are used to specify connection information for remote
Icinga 2 instances.
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.
timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
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.
-## <a id="objecttype-filelogger"></a> FileLogger
+## FileLogger <a id="objecttype-filelogger"></a>
Specifies Icinga 2 logging to a file.
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).
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
Graphite Carbon host.
-## <a id="objecttype-host"></a> Host
+## Host <a id="objecttype-host"></a>
A host.
-## <a id="objecttype-hostgroup"></a> HostGroup
+## HostGroup <a id="objecttype-hostgroup"></a>
A group of hosts.
display_name |**Optional.** A short description of the host group.
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 object name must be `app`. If the object configuration
enable_perfdata |**Optional.** Whether performance data processing is globally enabled. Defaults to true.
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.
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\_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".
- 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".
+ 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](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.
categories |**Optional.** Array of information types that should be written to the database.
In addition to the category flags listed above the `DbCatEverything`
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.
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\_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".
- 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".
+ 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](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.
categories |**Optional.** Array of information types that should be written to the database.
In addition to the category flags listed above the `DbCatEverything`
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.
to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second
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:
...
}
-## <a id="objecttype-livestatuslistener"></a> LiveStatusListener
+## LiveStatusListener <a id="objecttype-livestatuslistener"></a>
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.
Example:
> 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
of host and service state changes and other events.
> 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 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:
user_groups | **Optional.** A list of user group names who should be notified.
times | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
command | **Required.** The name of the notification command which should be executed when the notification is triggered.
- interval | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. 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.
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.
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.
timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
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.
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).
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
pattern consisting of custom attributes and runtime macros.
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.
> 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
> 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:
`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
by Icinga 2.
> 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
> 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:
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.
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.
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.
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
when notifications should be sent out.
}
-Additional examples can be found [here](8-advanced-topics.md#timeperiods).
+Additional examples can be found [here](08-advanced-topics.md#timeperiods).
Configuration Attributes:
is\_inside | Boolean | Whether we're currently inside this timeperiod.
-## <a id="objecttype-user"></a> User
+## User <a id="objecttype-user"></a>
A user.
--------------------------|---------------|-----------------
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.
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 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
--------------------------|---------------|-----------------
exit_status |Â Number | The exit status returned by the check execution.
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.
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.
vars_before | 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
--------------------------|---------------|-----------------
label |Â String | Performance data label.
value | Number | Normalized performance data value without unit.
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.
warn | Value | Warning threshold value.
min | Value | Minimum value returned by the check.
-# <a id="icinga-template-library"></a> Icinga Template Library
+# Icinga Template Library <a id="icinga-template-library"></a>
The Icinga Template Library (ITL) implements standard templates and object
definitions for commonly used services.
include <itl>
-## <a id="itl-generic-templates"></a> Generic Templates
+## Generic Templates <a id="itl-generic-templates"></a>
These templates are imported by the provided example configuration.
> These templates are built into the binaries. By convention
> all command and timeperiod objects should import these templates.
-### <a id="itl-plugin-check-command"></a> plugin-check-command
+### plugin-check-command <a id="itl-plugin-check-command"></a>
Command template for check plugins executed by Icinga 2.
The `plugin-check-command` command does not support any vars.
-By default this template is automatically imported into all [CheckCommand](9-object-types.md#objecttype-checkcommand) definitions.
+By default this template is automatically imported into all [CheckCommand](09-object-types.md#objecttype-checkcommand) definitions.
-### <a id="itl-plugin-notification-command"></a> plugin-notification-command
+### plugin-notification-command <a id="itl-plugin-notification-command"></a>
Command template for notification scripts executed by Icinga 2.
The `plugin-notification-command` command does not support any vars.
-By default this template is automatically imported into all [NotificationCommand](9-object-types.md#objecttype-notificationcommand) definitions.
+By default this template is automatically imported into all [NotificationCommand](09-object-types.md#objecttype-notificationcommand) definitions.
-### <a id="itl-plugin-event-command"></a> plugin-event-command
+### plugin-event-command <a id="itl-plugin-event-command"></a>
Command template for event handler scripts executed by Icinga 2.
The `plugin-event-command` command does not support any vars.
-By default this template is automatically imported into all [EventCommand](9-object-types.md#objecttype-eventcommand) definitions.
+By default this template is automatically imported into all [EventCommand](09-object-types.md#objecttype-eventcommand) definitions.
-### <a id="itl-legacy-timeperiod"></a> legacy-timeperiod
+### legacy-timeperiod <a id="itl-legacy-timeperiod"></a>
-Timeperiod template for [Timeperiod objects](9-object-types.md#objecttype-timeperiod).
+Timeperiod template for [Timeperiod objects](09-object-types.md#objecttype-timeperiod).
The `legacy-timeperiod` timeperiod does not support any vars.
-By default this template is automatically imported into all [TimePeriod](9-object-types.md#objecttype-timeperiod) definitions.
+By default this template is automatically imported into all [TimePeriod](09-object-types.md#objecttype-timeperiod) definitions.
-## <a id="itl-check-commands"></a> Check Commands
+## Check Commands <a id="itl-check-commands"></a>
These check commands are embedded into Icinga 2 and do not require any external
plugin scripts.
-### <a id="itl-icinga"></a> icinga
+### icinga <a id="itl-icinga"></a>
Check command for the built-in `icinga` check. This check returns performance
data for the current Icinga instance.
The `icinga` check command does not support any vars.
-### <a id="itl-icinga-cluster"></a> cluster
+### cluster <a id="itl-icinga-cluster"></a>
Check command for the built-in `cluster` check. This check returns performance
data for the current Icinga instance and connected endpoints.
The `cluster` check command does not support any vars.
-### <a id="itl-icinga-cluster-zone"></a> cluster-zone
+### cluster-zone <a id="itl-icinga-cluster-zone"></a>
Check command for the built-in `cluster-zone` check.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------|---------------
cluster_lag_warning | **Optional.** Warning threshold for log lag in seconds. Applies if the log lag is greater than the threshold.
cluster_lag_critical | **Optional.** Critical threshold for log lag in seconds. Applies if the log lag is greater than the threshold.
-### <a id="itl-icinga-ido"></a> ido
+### ido <a id="itl-icinga-ido"></a>
Check command for the built-in `ido` check.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
-------------|---------------
ido_type | **Required.** The type of the IDO connection object. Can be either "IdoMysqlConnection" or "IdoPgsqlConnection".
ido_name | **Required.** The name of the IDO connection object.
-### <a id="itl-random"></a> random
+### random <a id="itl-random"></a>
Check command for the built-in `random` check. This check returns random states
and adds the check source to the check output.
For test and demo purposes only. The `random` check command does not support
any vars.
-### <a id="itl-exception"></a> exception
+### exception <a id="itl-exception"></a>
Check command for the built-in `exception` check. This check throws an exception.
For test and demo purposes only. The `exception` check command does not support
any vars.
-# <a id="plugin-check-commands"></a> Plugin Check Commands
+# Plugin Check Commands <a id="plugin-check-commands"></a>
-## <a id="plugin-check-commands-monitoring-plugins"></a> Plugin Check Commands for Monitoring Plugins
+## Plugin Check Commands for Monitoring Plugins <a id="plugin-check-commands-monitoring-plugins"></a>
The Plugin Check Commands provides example configuration for plugin check commands
provided by the [Monitoring Plugins](https://www.monitoring-plugins.org) project.
definitions please kindly send a patch upstream. This should include an update
for the ITL CheckCommand itself and this documentation section.
-### <a id="plugin-check-command-apt"></a> apt
+### apt <a id="plugin-check-command-apt"></a>
The plugin [apt](https://www.monitoring-plugins.org/doc/index.html) checks for software updates on systems that use
package management systems based on the apt-get(8) command found in Debian based systems.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
apt_only_critical | **Optional.** Only warn about critical upgrades.
-### <a id="plugin-check-command-breeze"></a> breeze
+### breeze <a id="plugin-check-command-breeze"></a>
The [check_breeze](https://www.monitoring-plugins.org/doc/man/check_breeze.html) plugin reports the signal
strength of a Breezecom wireless equipment.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
-----------------|---------------------------------
breeze_critical | **Required.** Percentage strength below which a WARNING status will result. Defaults to 20.
-### <a id="plugin-check-command-by-ssh"></a> by_ssh
+### by_ssh <a id="plugin-check-command-by-ssh"></a>
The [check_by_ssh](https://www.monitoring-plugins.org/doc/man/check_by_ssh.html) plugin uses SSH to execute
commands on a remote host.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
by_ssh_ipv6 | **Optional.** Use IPv6 connection. Defaults to false.
-### <a id="plugin-check-command-clamd"></a> clamd
+### clamd <a id="plugin-check-command-clamd"></a>
The [check_clamd](https://www.monitoring-plugins.org/doc/man/check_clamd.html) plugin tests CLAMD
connections with the specified host (or unix socket).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
-------------------|--------------
clamd_ipv6 | **Optional.** Use IPv6 connection. Defaults to false.
-### <a id="plugin-check-command-dhcp"></a> dhcp
+### dhcp <a id="plugin-check-command-dhcp"></a>
The [check_dhcp](https://www.monitoring-plugins.org/doc/man/check_dhcp.html) plugin
tests the availability of DHCP servers on a network.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
dhcp_unicast | **Optional.** Whether to use unicast requests. Defaults to false.
-### <a id="plugin-check-command-dig"></a> dig
+### dig <a id="plugin-check-command-dig"></a>
The [check_dig](https://www.monitoring-plugins.org/doc/man/check_dig.html) plugin
test the DNS service on the specified host using dig.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------|--------------
dig_ipv6 | **Optional.** Force dig to only use IPv6 query transport. Defaults to false.
-### <a id="plugin-check-command-disk"></a> disk
+### disk <a id="plugin-check-command-disk"></a>
The [check_disk](https://www.monitoring-plugins.org/doc/man/check_disk.html) plugin
checks the amount of used disk space on a mounted file system and generates an alert
if free space is less than one of the threshold values.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
--------------------|------------------------
disk\_units | **Optional.** Choose bytes, kB, MB, GB, TB (default: MB).
disk\_exclude\_type | **Optional.** Ignore all filesystems of indicated type. Multiple regular expression strings must be defined as array. Defaults to "none", "tmpfs", "sysfs", "proc", "devtmpfs", "devfs", "mtmfs", "tracefs", "cgroup", "fuse.gvfsd-fuse", "fuse.gvfs-fuse-daemon", "fdescfs".
-### <a id="plugin-check-command-disk-smb"></a> disk_smb
+### disk_smb <a id="plugin-check-command-disk-smb"></a>
The [check_disk_smb](https://www.monitoring-plugins.org/doc/man/check_disk_smb.html) plugin
uses the `smbclient` binary to check SMB shares.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|------------------------
disk_smb_cused | **Optional.** The used space critical threshold. Defaults to "95%". If the percent sign is omitted, use optional disk units.
disk_smb_port | **Optional.** Connection port, e.g. `139` or `445`. Defaults to `smbclient` default if omitted.
-### <a id="plugin-check-command-dns"></a> dns
+### dns <a id="plugin-check-command-dns"></a>
The [check_dns](https://www.monitoring-plugins.org/doc/man/check_dns.html) plugin
uses the nslookup program to obtain the IP address for the given host/domain query.
An optional DNS server to use may be specified. If no DNS server is specified, the
default server(s) specified in `/etc/resolv.conf` will be used.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------|--------------
dns_timeout | **Optional.** Seconds before connection times out. Defaults to 10.
-### <a id="plugin-check-command-dummy"></a> dummy
+### dummy <a id="plugin-check-command-dummy"></a>
The [check_dummy](https://www.monitoring-plugins.org/doc/man/check_dummy.html) plugin
will simply return the state corresponding to the numeric value of the `dummy_state`
argument with optional text.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
dummy_text | **Optional.** Plugin output. Defaults to "Check was successful.".
-### <a id="plugin-check-command-file-age"></a> file_age
+### file_age <a id="plugin-check-command-file-age"></a>
The [check_file_age](https://www.monitoring-plugins.org/doc/man/check_file_age.html) plugin
checks a file's size and modification time to make sure it's not empty and that it's sufficiently recent.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
-----------------------|--------------------------------------------------------------------------------------------------------
file_age_ignoremissing | **Optional.** Return OK if the file does not exist. Defaults to false.
-### <a id="plugin-check-command-flexlm"></a> flexlm
+### flexlm <a id="plugin-check-command-flexlm"></a>
The [check_flexlm](https://www.monitoring-plugins.org/doc/man/check_flexlm.html) plugin
checks available flexlm license managers. Requires the `lmstat` command.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
-------------------|----------------------------------------------------------
flexlm_timeout | **Optional.** Plugin time out in seconds. Defaults to 15.
-### <a id="plugin-check-command-fping4"></a> fping4
+### fping4 <a id="plugin-check-command-fping4"></a>
The [check_fping](https://www.monitoring-plugins.org/doc/man/check_fping.html) plugin
uses the `fping` command to ping the specified host for a fast check. Note that it is
This CheckCommand expects an IPv4 address.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
fping_source_interface | **Optional.** The source interface name.
-### <a id="plugin-check-command-fping6"></a> fping6
+### fping6 <a id="plugin-check-command-fping6"></a>
The [check_fping](https://www.monitoring-plugins.org/doc/man/check_fping.html) plugin
will use the `fping` command to ping the specified host for a fast check. Note that it is
This CheckCommand expects an IPv6 address.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
fping_source_interface | **Optional.** The source interface name.
-### <a id="plugin-check-command-ftp"></a> ftp
+### ftp <a id="plugin-check-command-ftp"></a>
The [check_ftp](https://www.monitoring-plugins.org/doc/man/check_ftp.html) plugin
tests FTP connections with the specified host (or unix socket).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
-------------------|--------------
ftp_ipv6 | **Optional.** Use IPv6 connection. Defaults to false.
-### <a id="plugin-check-command-game"></a> game
+### game <a id="plugin-check-command-game"></a>
The [check_game](https://www.monitoring-plugins.org/doc/man/check_game.html) plugin
tests game server connections with the specified host.
If you don't have the package installed, you will need to [download](http://www.activesw.com/people/steve/qstat.html)
or install the package `quakestat` before you can use this plugin.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
-------------------|-------------------
game_hostname | **Optional.** Name of the host running the game.
-### <a id="plugin-check-command-hostalive"></a> hostalive
+### hostalive <a id="plugin-check-command-hostalive"></a>
Check command object for the [check_ping](https://www.monitoring-plugins.org/doc/man/check_ping.html)
plugin with host check default values. This variant uses the host's `address` attribute
if available and falls back to using the `address6` attribute if the `address` attribute is not set.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
ping_timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
-### <a id="plugin-check-command-hostalive4"></a> hostalive4
+### hostalive4 <a id="plugin-check-command-hostalive4"></a>
Check command object for the [check_ping](https://www.monitoring-plugins.org/doc/man/check_ping.html)
plugin with host check default values. This variant uses the host's `address` attribute.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
ping_timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
-### <a id="plugin-check-command-hostalive6"></a> hostalive6
+### hostalive6 <a id="plugin-check-command-hostalive6"></a>
Check command object for the [check_ping](https://www.monitoring-plugins.org/doc/man/check_ping.html)
plugin with host check default values. This variant uses the host's `address6` attribute.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
ping_timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
-### <a id="plugin-check-command-hpjd"></a> hpjd
+### hpjd <a id="plugin-check-command-hpjd"></a>
The [check_hpjd](https://www.monitoring-plugins.org/doc/man/check_hpjd.html) plugin
tests the state of an HP printer with a JetDirect card. Net-snmp must be installed
on the computer running the plugin.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
hpjd_community | **Optional.** The SNMP community. Defaults to "public".
-### <a id="plugin-check-command-http"></a> http
+### http <a id="plugin-check-command-http"></a>
The [check_http](https://www.monitoring-plugins.org/doc/man/check_http.html) plugin
tests the HTTP service on the specified host. It can test normal (http) and secure
(https) servers, follow redirects, search for strings and regular expressions,
check connection times, and report on certificate expiration times.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------------------|---------------------------------
http_verbose | **Optional.** Show details for command-line debugging. Defaults to false.
-### <a id="plugin-check-command-icmp"></a> icmp
+### icmp <a id="plugin-check-command-icmp"></a>
The [check_icmp](https://www.monitoring-plugins.org/doc/man/check_icmp.html) plugin
check_icmp allows for checking multiple hosts at once compared to `check_ping`.
parses its output while check_icmp talks ICMP itself. check_icmp must be installed
setuid root.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
icmp_ttl | **Optional.** The TTL on outgoing packets.
-### <a id="plugin-check-command-imap"></a> imap
+### imap <a id="plugin-check-command-imap"></a>
The [check_imap](https://www.monitoring-plugins.org/doc/man/check_imap.html) plugin
tests IMAP connections with the specified host (or unix socket).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------------|--------------
imap_ipv6 | **Optional.** Use IPv6 connection. Defaults to false.
-### <a id="plugin-check-command-ldap"></a> ldap
+### ldap <a id="plugin-check-command-ldap"></a>
The [check_ldap](https://www.monitoring-plugins.org/doc/man/check_ldap.html) plugin
can be used to check LDAP servers.
The plugin can also be used for monitoring ldaps connections instead of the deprecated `check_ldaps`.
This can be ensured by enabling `ldap_starttls` or `ldap_ssl`.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
ldap_timeout | **Optional.** Seconds before connection times out (default: 10).
ldap_verbose | **Optional.** Show details for command-line debugging (disabled by default)
-### <a id="plugin-check-command-load"></a> load
+### load <a id="plugin-check-command-load"></a>
The [check_load](https://www.monitoring-plugins.org/doc/man/check_load.html) plugin
tests the current system load average.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
load_cload15 | **Optional.** The 15-minute critical threshold. Defaults to 4.
load_percpu | **Optional.** Divide the load averages by the number of CPUs (when possible). Defaults to false.
-### <a id="plugin-check-command-mailq"></a> mailq
+### mailq <a id="plugin-check-command-mailq"></a>
The [check_mailq](https://www.monitoring-plugins.org/doc/man/check_mailq.html) plugin
checks the number of messages in the mail queue (supports multiple sendmail queues, qmail).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
mailq_servertype | **Optional.** [ sendmail \| qmail \| postfix \| exim \| nullmailer ] (default = autodetect).
mailq_sudo | **Optional.** Use sudo to execute the mailq command.
-### <a id="plugin-check-command-mysql"></a> mysql
+### mysql <a id="plugin-check-command-mysql"></a>
The [check_mysql](https://www.monitoring-plugins.org/doc/man/check_mysql.html) plugin
tests connections to a MySQL server.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|---------------------------------------------------------------
mysql_ciphers | **Optional.** List of valid SSL ciphers.
-### <a id="plugin-check-command-mysql-query"></a> mysql_query
+### mysql_query <a id="plugin-check-command-mysql-query"></a>
The [check_mysql_query](https://www.monitoring-plugins.org/doc/man/check_mysql_query.html) plugin
checks a query result against threshold levels.
**Note**: You must specify `mysql_query_password` with an empty string to force an empty password,
overriding any my.cnf settings.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|---------------------------------------------------------------
mysql_query_critical | **Optional.** Exit with CRITICAL status if query is outside of the range.
-### <a id="plugin-check-command-negate"></a> negate
+### negate <a id="plugin-check-command-negate"></a>
The [negate](https://www.monitoring-plugins.org/doc/man/negate.html) plugin
negates the status of a plugin (returns OK for CRITICAL and vice-versa).
Additional switches can be used to control which state becomes what.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|---------------------------------------------------------------
negate_command | **Required.** Command to be negated.
negate_arguments | **Optional.** Arguments for the negated command.
-### <a id="plugin-check-command-nrpe"></a> nrpe
+### nrpe <a id="plugin-check-command-nrpe"></a>
The `check_nrpe` plugin can be used to query an [NRPE](https://docs.icinga.com/latest/en/nrpe.html)
server or [NSClient++](https://www.nsclient.org). **Note**: This plugin
is considered insecure/deprecated.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
nrpe_version_2 | **Optional.** Use this if you want to connect using NRPE v2 protocol. Defaults to false.
-### <a id="plugin-check-command-nscp"></a> nscp
+### nscp <a id="plugin-check-command-nscp"></a>
The [check_nt](https://www.monitoring-plugins.org/doc/man/check_nt.html) plugin
collects data from the [NSClient++](https://www.nsclient.org) service.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
nscp_showall | **Optional.** Use with SERVICESTATE to see working services or PROCSTATE for running processes. Defaults to false.
-### <a id="plugin-check-command-ntp-time"></a> ntp_time
+### ntp_time <a id="plugin-check-command-ntp-time"></a>
The [check_ntp_time](https://www.monitoring-plugins.org/doc/man/check_ntp_time.html) plugin
checks the clock offset between the local host and a remote NTP server.
**Note**: If you want to monitor an NTP server, please use `ntp_peer`.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
ntp_ipv6 | **Optional.** Use IPv6 connection. Defaults to false.
-### <a id="plugin-check-command-ntp-peer"></a> ntp_peer
+### ntp_peer <a id="plugin-check-command-ntp-peer"></a>
The [check_ntp_peer](https://www.monitoring-plugins.org/doc/man/check_ntp_peer.html) plugin
checks the health of an NTP server. It supports checking the offset with the sync peer, the
jitter and stratum. This plugin will not check the clock offset between the local host and NTP
server; please use `ntp_time` for that purpose.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
ntp_ipv6 | **Optional.** Use IPv6 connection. Defaults to false.
-### <a id="plugin-check-command-passive"></a> passive
+### passive <a id="plugin-check-command-passive"></a>
Specialised check command object for passive checks executing the `check_dummy` plugin with appropriate default values.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
dummy_state | **Optional.** The state. Can be one of 0 (ok), 1 (warning), 2 (critical) and 3 (unknown). Defaults to 3.
dummy_text | **Optional.** Plugin output. Defaults to "No Passive Check Result Received.".
-### <a id="plugin-check-command-pgsql"></a> pgsql
+### pgsql <a id="plugin-check-command-pgsql"></a>
The [check_pgsql](https://www.monitoring-plugins.org/doc/man/check_pgsql.html) plugin
tests a PostgreSQL DBMS to determine whether it is active and accepting queries.
connecting to the server. The result from the query has to be numeric in order
to compare it against the query thresholds if set.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|---------------------------------------------------------------
pgsql_query_warning | **Optional.** SQL query value to result in warning status (double).
pgsql_query_critical | **Optional.** SQL query value to result in critical status (double).
-### <a id="plugin-check-command-ping"></a> ping
+### ping <a id="plugin-check-command-ping"></a>
The [check_ping](https://www.monitoring-plugins.org/doc/man/check_ping.html) plugin
uses the ping command to probe the specified host for packet loss (percentage) and
This command uses the host's `address` attribute if available and falls back to using
the `address6` attribute if the `address` attribute is not set.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
ping_timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
-### <a id="plugin-check-command-ping4"></a> ping4
+### ping4 <a id="plugin-check-command-ping4"></a>
The [check_ping](https://www.monitoring-plugins.org/doc/man/check_ping.html) plugin
uses the ping command to probe the specified host for packet loss (percentage) and
This command uses the host's `address` attribute if not explicitely specified using
the `ping_address` attribute.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
ping_packets | **Optional.** The number of packets to send. Defaults to 5.
ping_timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
-### <a id="plugin-check-command-ping6"></a> ping6
+### ping6 <a id="plugin-check-command-ping6"></a>
The [check_ping](https://www.monitoring-plugins.org/doc/man/check_ping.html) plugin
uses the ping command to probe the specified host for packet loss (percentage) and
This command uses the host's `address6` attribute if not explicitely specified using
the `ping_address` attribute.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
ping_timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
-### <a id="plugin-check-command-pop"></a> pop
+### pop <a id="plugin-check-command-pop"></a>
The [check_pop](https://www.monitoring-plugins.org/doc/man/check_pop.html) plugin
tests POP connections with the specified host (or unix socket).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------|--------------
pop_ipv6 | **Optional.** Use IPv6 connection. Defaults to false.
-### <a id="plugin-check-command-processes"></a> procs
+### procs <a id="plugin-check-command-processes"></a>
The [check_procs](https://www.monitoring-plugins.org/doc/man/check_procs.html) plugin
checks all processes and generates WARNING or CRITICAL states if the specified
metric is outside the required threshold ranges. The metric defaults to number
of processes. Search filters can be applied to limit the processes to check.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------|--------------
procs_nokthreads | **Optional.** Only scan for non kernel threads. Defaults to false.
-### <a id="plugin-check-command-radius"></a> radius
+### radius <a id="plugin-check-command-radius"></a>
The [check_radius](https://www.monitoring-plugins.org/doc/man/check_radius.html) plugin
checks a RADIUS server to see if it is accepting connections. The server to test
password used does not allow access to sensitive system resources.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
-------------------|--------------
radius_timeout | **Optional.** The number of seconds before connection times out (default: 10).
-### <a id="plugin-check-command-simap"></a> simap
+### simap <a id="plugin-check-command-simap"></a>
The [check_simap](https://www.monitoring-plugins.org/doc/man/check_simap.html) plugin
tests SIMAP connections with the specified host (or unix socket).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
-----------------------|--------------
simap_ipv4 | **Optional.** Use IPv4 connection. Defaults to false.
simap_ipv6 | **Optional.** Use IPv6 connection. Defaults to false.
-### <a id="plugin-check-command-smart"></a> smart
+### smart <a id="plugin-check-command-smart"></a>
The [check_ide_smart](https://www.monitoring-plugins.org/doc/man/check_ide_smart.html) plugin
checks a local hard drive with the (Linux specific) SMART interface. Requires installation of `smartctl`.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
smart_device | **Required.** The name of a local hard drive to monitor.
-### <a id="plugin-check-command-smtp"></a> smtp
+### smtp <a id="plugin-check-command-smtp"></a>
The [check_smtp](https://www.monitoring-plugins.org/doc/man/check_smtp.html) plugin
will attempt to open an SMTP connection with the host.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------------|--------------
smtp_ipv6 | **Optional.** Use IPv6 connection. Defaults to false.
-### <a id="plugin-check-command-snmp"></a> snmp
+### snmp <a id="plugin-check-command-snmp"></a>
The [check_snmp](https://www.monitoring-plugins.org/doc/man/check_snmp.html) plugin
checks the status of remote machines and obtains system information via SNMP.
**Note**: This plugin uses the `snmpget` command included with the NET-SNMP package.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
--------------------|--------------
snmp_getnext | **Optional.** Boolean. Use SNMP GETNEXT. Defaults to false.
snmp_timeout | **Optional.** The command timeout in seconds. Defaults to 10 seconds.
-### <a id="plugin-check-command-snmpv3"></a> snmpv3
+### snmpv3 <a id="plugin-check-command-snmpv3"></a>
Check command object for the [check_snmp](https://www.monitoring-plugins.org/doc/man/check_snmp.html)
plugin, using SNMPv3 authentication and encryption options.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------|--------------
snmpv3_rate | **Optional.** Boolean. Enable rate calculation.
snmpv3_timeout | **Optional.** The command timeout in seconds. Defaults to 10 seconds.
-### <a id="plugin-check-command-snmp-uptime"></a> snmp-uptime
+### snmp-uptime <a id="plugin-check-command-snmp-uptime"></a>
Check command object for the [check_snmp](https://www.monitoring-plugins.org/doc/man/check_snmp.html)
plugin, using the uptime OID by default.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
snmp_community | **Optional.** The SNMP community. Defaults to "public".
-### <a id="plugin-check-command-spop"></a> spop
+### spop <a id="plugin-check-command-spop"></a>
The [check_spop](https://www.monitoring-plugins.org/doc/man/check_spop.html) plugin
tests SPOP connections with the specified host (or unix socket).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------------|--------------
spop_ipv6 | **Optional.** Use IPv6 connection. Defaults to false.
-### <a id="plugin-check-command-ssh"></a> ssh
+### ssh <a id="plugin-check-command-ssh"></a>
The [check_ssh](https://www.monitoring-plugins.org/doc/man/check_ssh.html) plugin
connects to an SSH server at a specified host and port.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
ssh_ipv6 | **Optional.** Use IPv6 connection. Defaults to false.
-### <a id="plugin-check-command-ssl"></a> ssl
+### ssl <a id="plugin-check-command-ssl"></a>
Check command object for the [check_tcp](https://www.monitoring-plugins.org/doc/man/check_tcp.html) plugin,
using ssl-related options.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------------|--------------
ssl_sni | **Optional.** The `server_name` that is send to select the SSL certificate to check. Important if SNI is used. Defaults to "$ssl_address$".
-### <a id="plugin-check-command-ssmtp"></a> ssmtp
+### ssmtp <a id="plugin-check-command-ssmtp"></a>
The [check_ssmtp](https://www.monitoring-plugins.org/doc/man/check_ssmtp.html) plugin
tests SSMTP connections with the specified host (or unix socket).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
-----------------------|--------------
ssmtp_ipv6 | **Optional.** Use IPv6 connection. Defaults to false.
-### <a id="plugin-check-command-swap"></a> swap
+### swap <a id="plugin-check-command-swap"></a>
The [check_swap](https://www.monitoring-plugins.org/doc/man/check_swap.html) plugin
checks the swap space on a local machine.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
swap_noswap | **Optional.** Resulting state when there is no swap regardless of thresholds. Possible values are "ok", "warning", "critical", "unknown". Defaults to "critical".
-### <a id="plugin-check-command-tcp"></a> tcp
+### tcp <a id="plugin-check-command-tcp"></a>
The [check_tcp](https://www.monitoring-plugins.org/doc/man/check_tcp.html) plugin
tests TCP connections with the specified host (or unix socket).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
tcp_ipv6 | **Optional.** Use IPv6 connection. Defaults to false.
-### <a id="plugin-check-command-udp"></a> udp
+### udp <a id="plugin-check-command-udp"></a>
The [check_udp](https://www.monitoring-plugins.org/doc/man/check_udp.html) plugin
tests UDP connections with the specified host (or unix socket).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
udp_ipv6 | **Optional.** Use IPv6 connection. Defaults to false.
-### <a id="plugin-check-command-ups"></a> ups
+### ups <a id="plugin-check-command-ups"></a>
The [check_ups](https://www.monitoring-plugins.org/doc/man/check_ups.html) plugin
tests the UPS service on the specified host. [Network UPS Tools](http://www.networkupstools.org)
must be running for this plugin to work.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
ups_timeout | **Optional.** The number of seconds before the connection times out. Defaults to 10.
-### <a id="plugin-check-command-users"></a> users
+### users <a id="plugin-check-command-users"></a>
The [check_users](https://www.monitoring-plugins.org/doc/man/check_users.html) plugin
checks the number of users currently logged in on the local system and generates an
error if the number exceeds the thresholds specified.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
users_wgreater | **Optional.** The user count warning threshold. Defaults to 20.
users_cgreater | **Optional.** The user count critical threshold. Defaults to 50.
-## <a id="windows-plugins"></a> Windows Plugins for Icinga 2
+## Windows Plugins for Icinga 2 <a id="windows-plugins"></a>
To allow a basic monitoring of Windows clients Icinga 2 comes with a set of Windows only plugins. While trying to mirror the functionalities of their linux cousins from the monitoring-plugins package, the differences between Windows and Linux are too big to be able use the same CheckCommands for both systems.
One of the differences between the Windows plugins and their linux counterparts is that they consistently do not require thresholds to run, functioning like dummies without.
-### <a id="windows-plugins-thresholds"></a> Threshold syntax
+### Threshold syntax <a id="windows-plugins-thresholds"></a>
So not specified differently the thresholds for the plugins all follow the same pattern
"![10-40]" | Same as above, but the result is inverted.
-### <a id="windows-plugins-disk-windows"></a> disk-windows
+### disk-windows <a id="windows-plugins-disk-windows"></a>
Check command object for the `check_disk.exe` plugin.
Aggregates the free disk space of all volumes and mount points it can find, or the ones defined in `disk_win_path`. Ignores removable storage like fash drives and discs (CD, DVD etc.).
disk\_win\_unit | **Optional**. Use this unit to display disk space, thresholds are interpreted in this unit. Defaults to "mb", possible values are: b, kb, mb, gb and tb.
disk\_win\_exclude | **Optional**. Exclude these drives from check.
-### <a id="windows-plugins-load-windows"></a> load-windows
+### load-windows <a id="windows-plugins-load-windows"></a>
Check command object for the `check_load.exe` plugin.
This plugin collects the inverse of the performance counter `\Processor(_Total)\% Idle Time` two times, with a wait time of one second between the collection. To change this wait time use [`perfmon-windows`](10-icinga-template-library.md#windows-plugins-load-windows).
load\_win\_crit | **Optional**. The critical threshold.
-### <a id="windows-plugins-memory-windows"></a> memory-windows
+### memory-windows <a id="windows-plugins-memory-windows"></a>
Check command object for the `check_memory.exe` plugin.
The memory collection is instant and free memory is used for threshold computation.
memory\_win\_unit | **Optional**. The unit to display the received value in, thresholds are interpreted in this unit. Defaults to "mb" (megabye), possible values are: b, kb, mb, gb and tb.
-### <a id="windows-plugins-network-windows"></a> network-windows
+### network-windows <a id="windows-plugins-network-windows"></a>
Check command object for the `check_network.exe` plugin.
Collects the total Bytes inbount and outbound for all interfaces in one second, to itemise interfaces or use a different collection interval use [`perfmon-windows`](10-icinga-template-library.md#windows-plugins-load-windows).
network\_no\_isatap | **Optional**. Do not print ISATAP interfaces.
-### <a id="windows-plugins-perfmon-windows"></a> perfmon-windows
+### perfmon-windows <a id="windows-plugins-perfmon-windows"></a>
Check command object for the `check_perfmon.exe` plugin.
This plugins allows to collect data from a Performance Counter. After the first data collection a second one is done after `perfmon_win_wait` milliseconds. When you know `perfmon_win_counter` only requires one set of data to provide valid data you can set `perfmon_win_wait` to `0`.
perfmon\_win\_syntax | **Optional**. Use this in the performance output instead of `perfmon\_win\_counter`. Exists for graphice compatibility reasons.
-### <a id="windows-plugins-ping-windows"></a> ping-windows
+### ping-windows <a id="windows-plugins-ping-windows"></a>
Check command object for the `check_ping.exe` plugin.
ping-windows should automaticly detect whether `ping_win_address` is an IPv4 or IPv6 address. If not, use ping4-windows and ping6-windows. Also note that check\_ping.exe waits at least `ping_win_timeout` milliseconds between the pings.
ping\_win\_timeout | **Optional**. The timeout in milliseconds. Default: 1000
-### <a id="windows-plugins-procs-windows"></a> procs-windows
+### procs-windows <a id="windows-plugins-procs-windows"></a>
Check command object for `check_procs.exe` plugin.
When useing `procs_win_user` this plugins needs adminstratice privileges to access the processes of other users, to just enumerate them no additional privileges are required.
procs\_win\_user | **Optional**. Count this useres processes.
-### <a id="windows-plugins-service-windows"></a> service-windows
+### service-windows <a id="windows-plugins-service-windows"></a>
Check command object for `check_service.exe` plugin.
This checks thresholds work different since the binary decision whether a service is running or not does not allow for three states. As a default `check_service.exe` will return CRITICAL when `service_win_service` is not running, the `service_win_warn` flag changes this to WARNING.
service\_win\_service | **Required**. The critical threshold.
-### <a id="windows-plugins-swap-windows"></a> swap-windows
+### swap-windows <a id="windows-plugins-swap-windows"></a>
Check command object for `check_swap.exe` plugin.
The data collection is instant.
swap\_win\_unit | **Optional**. The unit to display the received value in, thresholds are interpreted in this unit. Defaults to "mb" (megabyte).
-### <a id="windows-plugins-update-windows"></a> update-windows
+### update-windows <a id="windows-plugins-update-windows"></a>
Check command object for `check_update.exe` plugin.
Querying Microsoft for Windows updates can take multiple seconds to minutes. An update is treated as important when it has the WSUS flag for SecurityUpdates or CriticalUpdates.
> If run without the optional parameters, the plugin will output critical if any important updates are available.
-### <a id="windows-plugins-uptime-windows"></a> uptime-windows
+### uptime-windows <a id="windows-plugins-uptime-windows"></a>
Check command opject for `check_uptime.exe` plugin.
Uses GetTickCount64 to get the uptime, so boot time is not included.
uptime\_win\_unit | **Optional**. The unit to display the received value in, thresholds are interpreted in this unit. Defaults to "s"(seconds), possible values are ms (milliseconds), s, m (minutes), h (hours).
-### <a id="windows-plugins-users-windows"></a> users-windows
+### users-windows <a id="windows-plugins-users-windows"></a>
Check command object for `check_users.exe` plugin.
users\_win\_crit | **Optional**. The critical threshold.
-## <a id="nscp-plugin-check-commands"></a> Plugin Check Commands for NSClient++
+## Plugin Check Commands for NSClient++ <a id="nscp-plugin-check-commands"></a>
There are two methods available for querying NSClient++:
note: If you rely on performance counter delta calculations such as
CPU utilization, please use the HTTP API instead of the CLI sample call.
-### <a id="nscp-check-api"></a> nscp_api
+### nscp_api <a id="nscp-check-api"></a>
`check_nscp_api` is part of the Icinga 2 plugins. This plugin is available for
both, Windows and Linux/Unix.
```
-### <a id="nscp-check-local"></a> nscp-local
+### nscp-local <a id="nscp-check-local"></a>
Icinga 2 can use the `nscp client` command to run arbitrary NSClient++ checks locally on the client.
You can enable these check commands by adding the following the include directive in your
-[icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) configuration file:
+[icinga2.conf](04-configuring-icinga-2.md#icinga2-conf) configuration file:
include <nscp>
You can also optionally specify an alternative installation directory for NSClient++ by adding
-the NscpPath constant in your [constants.conf](4-configuring-icinga-2.md#constants-conf) configuration
+the NscpPath constant in your [constants.conf](04-configuring-icinga-2.md#constants-conf) configuration
file:
const NscpPath = "C:\\Program Files (x86)\\NSClient++"
The check command object for NSClient++ is available as `nscp-local`.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------
nscp_arguments | **Optional.** An array of query arguments.
nscp_showall | **Optional.** Shows more details in plugin output, default to false.
-### <a id="nscp-check-local-cpu"></a> nscp-local-cpu
+### nscp-local-cpu <a id="nscp-check-local-cpu"></a>
Check command object for the `check_cpu` NSClient++ plugin.
nscp_cpu_arguments | **Optional.** Additional arguments.
nscp_cpu_showall | **Optional.** Shows more details in plugin output, default to false.
-### <a id="nscp-check-local-memory"></a> nscp-local-memory
+### nscp-local-memory <a id="nscp-check-local-memory"></a>
Check command object for the `check_memory` NSClient++ plugin.
nscp_memory_arguments | **Optional.** Additional arguments.
nscp_memory_showall | **Optional.** Shows more details in plugin output, default to false.
-### <a id="nscp-check-local-os-version"></a> nscp-local-os-version
+### nscp-local-os-version <a id="nscp-check-local-os-version"></a>
Check command object for the `check_os_version` NSClient++ plugin.
This command has the same custom attributes like the `nscp-local` check command.
-### <a id="nscp-check-local-pagefile"></a> nscp-local-pagefile
+### nscp-local-pagefile <a id="nscp-check-local-pagefile"></a>
Check command object for the `check_pagefile` NSClient++ plugin.
This command has the same custom attributes like the `nscp-local` check command.
-### <a id="nscp-check-local-process"></a> nscp-local-process
+### nscp-local-process <a id="nscp-check-local-process"></a>
Check command object for the `check_process` NSClient++ plugin.
This command has the same custom attributes like the `nscp-local` check command.
-### <a id="nscp-check-local-service"></a> nscp-local-service
+### nscp-local-service <a id="nscp-check-local-service"></a>
Check command object for the `check_service` NSClient++ plugin.
nscp_service_arguments | **Optional.** Additional arguments.
nscp_service_showall | **Optional.** Shows more details in plugin output, default to true.
-### <a id="nscp-check-local-uptime"></a> nscp-local-uptime
+### nscp-local-uptime <a id="nscp-check-local-uptime"></a>
Check command object for the `check_uptime` NSClient++ plugin.
This command has the same custom attributes like the `nscp-local` check command.
-### <a id="nscp-check-local-version"></a> nscp-local-version
+### nscp-local-version <a id="nscp-check-local-version"></a>
Check command object for the `check_version` NSClient++ plugin.
This command has the same custom attributes like the `nscp-local` check command.
In addition to that the default value for `nscp_modules` is set to `[ "CheckHelpers" ]`.
-### <a id="nscp-check-local-disk"></a> nscp-local-disk
+### nscp-local-disk <a id="nscp-check-local-disk"></a>
Check command object for the `check_drivesize` NSClient++ plugin.
nscp_disk_showall | **Optional.** Shows more details in plugin output, default to true.
nscp_modules | **Optional.** An array of NSClient++ modules to load. Defaults to `[ "CheckDisk" ]`.
-### <a id="nscp-check-local-counter"></a> nscp-local-counter
+### nscp-local-counter <a id="nscp-check-local-counter"></a>
Check command object for the `check_pdh` NSClient++ plugin.
-## <a id="snmp-manubulon-plugin-check-commands"></a> Plugin Check Commands for Manubulon SNMP
+## Plugin Check Commands for Manubulon SNMP <a id="snmp-manubulon-plugin-check-commands"></a>
The `SNMP Manubulon Plugin Check Commands` provide configuration for plugin check
commands provided by the [SNMP Manubulon project](http://nagios.manubulon.com/index_snmp.html).
is set to the path where the Manubublon SNMP plugins are installed.
You can enable these plugin check commands by adding the following the include directive in your
-[icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) configuration file:
+[icinga2.conf](04-configuring-icinga-2.md#icinga2-conf) configuration file:
include <manubulon>
Cisco CSS | Yes | ?? | Yes | Yes | No | ?? | check_snmp_css.pl
-### <a id="plugin-check-command-snmp-load"></a> snmp-load
+### snmp-load <a id="plugin-check-command-snmp-load"></a>
Check command object for the [check_snmp_load.pl](http://nagios.manubulon.com/snmp_load.html) plugin.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
snmp_perf | **Optional.** Enable perfdata values. Defaults to true.
snmp_timeout | **Optional.** The command timeout in seconds. Defaults to 5 seconds.
-### <a id="plugin-check-command-snmp-memory"></a> snmp-memory
+### snmp-memory <a id="plugin-check-command-snmp-memory"></a>
Check command object for the [check_snmp_mem.pl](http://nagios.manubulon.com/snmp_mem.html) plugin.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
snmp_perf | **Optional.** Enable perfdata values. Defaults to true.
snmp_timeout | **Optional.** The command timeout in seconds. Defaults to 5 seconds.
-### <a id="plugin-check-command-snmp-storage"></a> snmp-storage
+### snmp-storage <a id="plugin-check-command-snmp-storage"></a>
Check command object for the [check_snmp_storage.pl](http://nagios.manubulon.com/snmp_storage.html) plugin.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
snmp_perf | **Optional.** Enable perfdata values. Defaults to true.
snmp_timeout | **Optional.** The command timeout in seconds. Defaults to 5 seconds.
-### <a id="plugin-check-command-snmp-interface"></a> snmp-interface
+### snmp-interface <a id="plugin-check-command-snmp-interface"></a>
Check command object for the [check_snmp_int.pl](http://nagios.manubulon.com/snmp_int.html) plugin.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------------------|--------------
snmp_perf | **Optional.** Enable perfdata values. Defaults to true.
snmp_timeout | **Optional.** The command timeout in seconds. Defaults to 5 seconds.
-### <a id="plugin-check-command-snmp-process"></a> snmp-process
+### snmp-process <a id="plugin-check-command-snmp-process"></a>
Check command object for the [check_snmp_process.pl](http://nagios.manubulon.com/snmp_process.html) plugin.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------------|--------------
snmp_process_cpu_threshold | **Optional.** Defines the warning and critical thresholds in % when snmp_process_cpu_usage set to true. If more than one CPU, value can be > 100% : 100%=1 CPU. Example "15,50". Defaults to "0,0".
-## <a id="plugin-contrib"></a> Contributed Plugin Check Commands
+## Contributed Plugin Check Commands <a id="plugin-contrib"></a>
The contributed Plugin Check Commands provides various additional command definitions
contributed by community members.
These check commands assume that the global constant named `PluginContribDir`
is set to the path where the user installs custom plugins and can be enabled by
-uncommenting the corresponding line in [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf):
+uncommenting the corresponding line in [icinga2.conf](04-configuring-icinga-2.md#icinga2-conf):
```
vim /etc/icinga2/icinga2.conf
This is enabled by default since Icinga 2 2.5.0.
-### <a id="plugin-contrib-databases"></a> Databases
+### Databases <a id="plugin-contrib-databases"></a>
This category contains plugins for various database servers.
-#### <a id="plugin-contrib-command-db2_health"></a> db2_health
+#### db2_health <a id="plugin-contrib-command-db2_health"></a>
The [check_db2_health](https://labs.consol.de/nagios/check_db2_health/) plugin
uses the `DBD::DB2` Perl library to monitor a [DB2](https://www.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/)
The Git repository is located on [GitHub](https://github.com/lausser/check_db2_health).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------------------|------------------------------------------------------------------------------------------------------------------------------
db2_health_env_db2_home | **Required.** Specifies the location of the db2 client libraries as environment variable `DB2_HOME`. Defaults to "/opt/ibm/db2/V10.5".
db2_health_env_db2_version | **Optional.** Specifies the DB2 version as environment variable `DB2_VERSION`.
-#### <a id="plugin-contrib-command-mssql_health"></a> mssql_health
+#### mssql_health <a id="plugin-contrib-command-mssql_health"></a>
The [check_mssql_health](https://labs.consol.de/nagios/check_mssql_health/index.html) plugin
uses the `DBD::Sybase` Perl library based on [FreeTDS](http://www.freetds.org/) to monitor a
The Git repository is located on [GitHub](https://github.com/lausser/check_mssql_health).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------------------|------------------------------------------------------------------------------------------------------------------------------
mssql_health_lookback | **Optional.** The amount of time you want to look back when calculating average rates.
mssql_health_report | **Optional.** Report can be used to output only the bad news. Possible values are "short", "long", "html". Defaults to `short`.
-#### <a id="plugin-contrib-command-mysql_health"></a> mysql_health
+#### mysql_health <a id="plugin-contrib-command-mysql_health"></a>
The [check_mysql_health](https://labs.consol.de/nagios/check_mysql_health/index.html) plugin
uses the `DBD::MySQL` Perl library to monitor a
The Git repository is located on [GitHub](https://github.com/lausser/check_mysql_health).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------------------|------------------------------------------------------------------------------------------------------------------------------
mysql_health_isvalidtime | **Optional.** Signals the plugin to return OK if now is not a valid check time."
mysql_health_timeout | **Optional.** Plugin timeout. Defaults to 60s.
-#### <a id="plugin-contrib-command-oracle_health"></a> oracle_health
+#### oracle_health <a id="plugin-contrib-command-oracle_health"></a>
The [check_oracle_health](https://labs.consol.de/nagios/check_oracle_health/index.html) plugin
uses the `DBD::Oracle` Perl library to monitor an [Oracle](https://www.oracle.com/database/) database.
The Git repository is located on [GitHub](https://github.com/lausser/check_oracle_health).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------------------|------------------------------------------------------------------------------------------------------------------------------
ORACLE_HOME | **Required.** Specifies the location of the oracle instant client libraries. Defaults to "/usr/lib/oracle/11.2/client64/lib". Can be overridden by setting "oracle_home".
TNS_ADMIN | **Required.** Specifies the location of the tnsnames.ora including the database connection strings. Defaults to "/etc/icinga2/plugin-configs". Can be overridden by setting "oracle_tns_admin".
-#### <a id="plugin-contrib-command-postgres"></a> postgres
+#### postgres <a id="plugin-contrib-command-postgres"></a>
The [check_postgres](https://bucardo.org/wiki/Check_postgres) plugin
uses the `psql` binary to monitor a [PostgreSQL](https://www.postgresql.org/about/) database.
The Git repository is located on [GitHub](https://github.com/bucardo/check_postgres).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------------------|------------------------------------------------------------------------------------------------------------------------------
postgres_reverse | **Optional.** If "postgres_reverse" is set, warning and critical values are reversed for "custom_query" action.
postgres_tempdir | **Optional.** Specify directory for temporary files. The default directory is dependent on the OS. More details [here](https://perldoc.perl.org/File/Spec.html).
-#### <a id="plugin-contrib-command-mongodb"></a> mongodb
+#### mongodb <a id="plugin-contrib-command-mongodb"></a>
The [check_mongodb.py](https://github.com/mzupan/nagios-plugin-mongodb) plugin
uses the `pymongo` Python library to monitor a [MongoDB](https://docs.mongodb.com/manual/) instance.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------------------|------------------------------------------------------------------------------------------------------------------------------
mongodb_collection | **Optional.** Specify the collection to check
mongodb_sampletime | **Optional.** Time used to sample number of pages faults
-#### <a id="plugin-contrib-command-elasticsearch"></a> elasticsearch
+#### elasticsearch <a id="plugin-contrib-command-elasticsearch"></a>
The [check_elasticsearch](https://github.com/anchor/nagios-plugin-elasticsearch) plugin
uses the HTTP API to monitor an [Elasticsearch](https://www.elastic.co/products/elasticsearch) node.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
-----------------------------|-------------------------------------------------------------------------------------------------------
elasticsearch_prefix | **Optional.** Optional prefix (e.g. 'es') for the ElasticSearch API. Defaults to ''.
elasticsearch_yellowcritical | **Optional.** Instead of issuing a 'warning' for a yellow cluster state, issue a 'critical' alert. Defaults to false.
-#### <a id="plugin-contrib-command-redis"></a> redis
+#### redis <a id="plugin-contrib-command-redis"></a>
The [check_redis.pl](https://github.com/willixix/naglio-plugins/blob/master/check_redis.pl) plugin
uses the `Redis` Perl library to monitor a [Redis](https://redis.io/) instance. The plugin can
measure response time, hitrate, memory utilization, check replication synchronization, etc. It is
also possible to test data in a specified key and calculate averages or summaries on ranges.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
-------------------------|--------------------------------------------------------------------------------------------------------------
redis_replication_delay | **Optional.** Allows to set threshold on replication delay info.
-### <a id="plugin-contrib-hardware"></a> Hardware
+### Hardware <a id="plugin-contrib-hardware"></a>
This category includes all plugin check commands for various hardware checks.
-#### <a id="plugin-contrib-command-hpasm"></a> hpasm
+#### hpasm <a id="plugin-contrib-command-hpasm"></a>
The [check_hpasm](https://labs.consol.de/de/nagios/check_hpasm/index.html) plugin
monitors the hardware health of HP Proliant Servers, provided that the `hpasm`
For compatibility reasons this attribute uses `true` as default value, and ensures that
specifying the `hpasm_hostname` always enables remote checks.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
--------------------------------|-----------------------------------------------------------------------
hpasm_eval-nics | **Optional.** Check network interfaces (and groups). Try it and report me whyt you think about it. I need to build up some know how on this subject. If you get an error and think, it is not justified for your configuration, please tell me about it. (alwasy send the output of "snmpwalk -On .... 1.3.6.1.4.1.232" and a description how you setup your nics and why it is correct opposed to the plugins error message.
hpasm_remote | **Optional.** Run remote SNMP checks if enabled. Otherwise checks are executed locally using the `hpasmcli` binary. Defaults to `true`.
-#### <a id="plugin-contrib-command-adaptec-raid"></a> adaptec-raid
+#### adaptec-raid <a id="plugin-contrib-command-adaptec-raid"></a>
The [check_adaptec_raid](https://github.com/thomas-krenn/check_adaptec_raid) plugin
uses the `arcconf` binary to monitor Adaptec RAID controllers.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
--------------------------------|-----------------------------------------------------------------------
adaptec_controller_number | **Required.** Controller number to monitor.
arcconf_path | **Required.** Path to the `arcconf` binary, e.g. "/sbin/arcconf".
-#### <a id="plugin-contrib-command-lsi-raid"></a> lsi-raid
+#### lsi-raid <a id="plugin-contrib-command-lsi-raid"></a>
The [check_lsi_raid](https://github.com/thomas-krenn/check_lsi_raid) plugin
uses the `storcli` binary to monitor MegaRAID RAID controllers.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
--------------------------------|-----------------------------------------------------------------------
lsi_controller_number | **Required.** Controller number to monitor.
storcli_path | **Required.** Path to the `storcli` binary, e.g. "/usr/sbin/storcli".
-#### <a id="plugin-contrib-command-smart-attributes"></a> smart-attributes
+#### smart-attributes <a id="plugin-contrib-command-smart-attributes"></a>
The [check_smart_attributes](https://github.com/thomas-krenn/check_smart_attributes) plugin
uses the `smartctl` binary to monitor SMART values of SSDs and HDDs.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
--------------------------------|-----------------------------------------------------------------------
smart_attributes_device | **Required.** Device name (e.g. /dev/sda) to monitor.
-### <a id="plugin-contrib-icingacli"></a> IcingaCLI
+### IcingaCLI <a id="plugin-contrib-icingacli"></a>
This category includes all plugins using the icingacli provided by Icinga Web 2.
-#### <a id="plugin-contrib-icingacli-businessprocess"></a> Business Process
+#### Business Process <a id="plugin-contrib-icingacli-businessprocess"></a>
This subcommand is provided by the [business process module](https://exchange.icinga.com/icinga/Business+Process)
and executed as `icingacli businessprocess` CLI command.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------------------------|-----------------------------------------------------------------------------------------
icingacli_businessprocess_statetype | **Optional.** Define which state type to look at, `soft` or `hard`. Overrides the default value inside the businessprocess module, if configured.
-### <a id="plugin-contrib-ipmi"></a> IPMI Devices
+### IPMI Devices <a id="plugin-contrib-ipmi"></a>
This category includes all plugins for IPMI devices.
-#### <a id="plugin-contrib-command-ipmi-sensor"></a> ipmi-sensor
+#### ipmi-sensor <a id="plugin-contrib-command-ipmi-sensor"></a>
The [check_ipmi_sensor](https://github.com/thomas-krenn/check_ipmi_sensor_v3) plugin
uses the `ipmimonitoring` binary to monitor sensor data for IPMI devices. Please
read the [documentation](https://www.thomas-krenn.com/en/wiki/IPMI_Sensor_Monitoring_Plugin)
for installation and configuration details.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------------------|-----------------------------------------------------------------------------------------------------
ipmi_verbose | **Optional.** Be Verbose multi line output, also with additional details for warnings.
ipmi_debug | **Optional.** Be Verbose debugging output, followed by normal multi line output.
-#### <a id="plugin-contrib-command-ipmi-alive"></a> ipmi-alive
+#### ipmi-alive <a id="plugin-contrib-command-ipmi-alive"></a>
The `ipmi-alive` check commands allows you to create a ping check for the IPMI Interface.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------------------|-----------------------------------------------------------------------------------------------------
ping_timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
-### <a id="plugins-contrib-log-management"></a> Log Management
+### Log Management <a id="plugins-contrib-log-management"></a>
This category includes all plugins for log management, for example [Logstash](https://www.elastic.co/products/logstash).
-#### <a id="plugins-contrib-command-logstash"></a> logstash
+#### logstash <a id="plugins-contrib-command-logstash"></a>
The [logstash](https://github.com/widhalmt/check_logstash) plugin connects to
the Node API of Logstash. This plugin requires at least Logstash version 5.0.x.
logstash_cpu_crit | **Optional.** Critical threshold for cpu usage in percent.
-### <a id="plugin-contrib-metrics"></a> Metrics
+### Metrics <a id="plugin-contrib-metrics"></a>
This category includes all plugins for metric-based checks.
-#### <a id="plugin-contrib-command-graphite"></a> graphite
+#### graphite <a id="plugin-contrib-command-graphite"></a>
The [check_graphite](https://github.com/obfuscurity/nagios-scripts) plugin
uses the `rest-client` Ruby library to monitor a [Graphite](https://graphiteapp.org) instance.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------------------|-----------------------------------------------------------------------------------------------------
graphite_zero_on_error | **Optional.** Return 0 on a graphite 500 error.
graphite_link_graph |Â **Optional.** Add a link in the plugin output, showing a 24h graph for this metric in graphite.
-### <a id="plugin-contrib-network-components"></a> Network Components
+### Network Components <a id="plugin-contrib-network-components"></a>
This category includes all plugins for various network components like routers, switches and firewalls.
-#### <a id="plugin-contrib-command-interfacetable"></a> interfacetable
+#### interfacetable <a id="plugin-contrib-command-interfacetable"></a>
The [check_interfacetable_v3t](http://www.tontonitch.com/tiki/tiki-index.php?page=Nagios+plugins+-+interfacetable_v3t) plugin
generates a html page containing information about the monitored node and all of its interfaces.
The Git repository is located on [GitHub](https://github.com/Tontonitch/interfacetable_v3t).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------------------|-----------------------------------------------------------------------------------------------------
interfacetable_tablesplit | **Optional.** Generate multiple interface tables, one per interface type. Defaults to false.
interfacetable_notype | **Optional.** Remove the interface type for each interface. Defaults to false.
-#### <a id="plugin-contrib-command-iftraffic"></a> iftraffic
+#### iftraffic <a id="plugin-contrib-command-iftraffic"></a>
The [check_iftraffic](https://exchange.icinga.com/exchange/iftraffic) plugin
checks the utilization of a given interface name using the SNMP protocol.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|---------------------------------------------------------
iftraffic_crit | **Optional.** Percent of bandwidth usage necessary to result in critical status (defaults to `98`).
iftraffic_max_counter | **Optional.** Maximum counter value of net devices in kilo/mega/giga/bytes.
-#### <a id="plugin-contrib-command-iftraffic64"></a> iftraffic64
+#### iftraffic64 <a id="plugin-contrib-command-iftraffic64"></a>
The [check_iftraffic64](https://exchange.icinga.com/exchange/iftraffic64) plugin
checks the utilization of a given interface name using the SNMP protocol.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|---------------------------------------------------------
iftraffic64_crit | **Optional.** Percent of bandwidth usage necessary to result in critical status (defaults to `98`).
iftraffic64_max_counter | **Optional.** Maximum counter value of net devices in kilo/mega/giga/bytes.
-#### <a id="plugin-contrib-command-interfaces"></a> interfaces
+#### interfaces <a id="plugin-contrib-command-interfaces"></a>
The [check_interfaces](https://git.netways.org/plugins/check_interfaces) plugin
uses SNMP to monitor network interfaces and their utilization.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
--------------------------|---------------------------------------------------------
interfaces_sleep | **Optional.** Sleep between every SNMP query (in ms).
interfaces_names | **Optional.** If set to true, use ifName instead of ifDescr.
-#### <a id="plugin-contrib-command-nwc_health"></a> nwc_health
+#### nwc_health <a id="plugin-contrib-command-nwc_health"></a>
The [check_nwc_health](https://labs.consol.de/de/nagios/check_nwc_health/index.html) plugin
uses SNMP to monitor network components. The plugin is able to generate interface statistics,
Juniper IVE, Pulse-Gateway MAG4610, Cisco IronPort AsyncOS, Foundry, etc. A complete list can be
found in the plugin [documentation](https://labs.consol.de/nagios/check_nwc_health/index.html).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
--------------------------------|---------------------------------------------------------
nwc_health_multiline | **Optional.** Multiline output
-### <a id="plugin-contrib-operating-system"></a> Operating System
+### Operating System <a id="plugin-contrib-operating-system"></a>
This category contains plugins which receive details about your operating system
or the guest system.
-#### <a id="plugin-contrib-command-mem"></a> mem
+#### mem <a id="plugin-contrib-command-mem"></a>
The [check_mem.pl](https://github.com/justintime/nagios-plugins) plugin checks the
memory usage on linux and unix hosts. It is able to count cache memory as free when
compared to thresholds. More details can be found on [this blog entry]((http://sysadminsjourney.com/content/2009/06/04/new-and-improved-checkmempl-nagios-plugin).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
-------------|-----------------------------------------------------------------------------------------------------------------------
mem_warning | **Required.** Specify the warning threshold as number interpreted as percent.
mem_critical | **Required.** Specify the critical threshold as number interpreted as percent.
-#### <a id="plugin-contrib-command-running_kernel"></a> running_kernel
+#### running_kernel <a id="plugin-contrib-command-running_kernel"></a>
The [check_running_kernel](https://packages.debian.org/stretch/nagios-plugins-contrib) plugin
is provided by the `nagios-plugin-contrib` package on Debian/Ubuntu.
---------------------------|-------------
running\_kernel\_use\_sudo | Whether to run the plugin with `sudo`. Defaults to false except on Ubuntu where it defaults to true.
-#### <a id="plugin-contrib-command-iostats"></a> iostats
+#### iostats <a id="plugin-contrib-command-iostats"></a>
The [check_iostats](https://github.com/dnsmichi/icinga-plugins/blob/master/scripts/check_iostats) plugin
uses the `iostat` binary to monitor I/O on a Linux host. The default thresholds are rather high
so you can use a grapher for baselining before setting your own.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------|-----------------------------------------------------------------------------------------------------------------------
iostats\_critical\_write | **Required.** Critical threshold for KB/s writes (default: 25000)
iostats\_critical\_wait | **Required.** Critical threshold for % iowait (default: 80)
-#### <a id="plugin-contrib-command-iostat"></a> iostat
+#### iostat <a id="plugin-contrib-command-iostat"></a>
The [check_iostat](https://github.com/dnsmichi/icinga-plugins/blob/master/scripts/check_iostat) plugin
uses the `iostat` binary to monitor disk I/O on a Linux host. The default thresholds are rather high
so you can use a grapher for baselining before setting your own.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------|-----------------------------------------------------------------------------------------------------------------------
iostat\_cread | **Required.** Critical threshold for KB/s reads (default: 200)
iostat\_cwrite | **Required.** Critical threshold for KB/s writes (default: 200)
-#### <a id="plugin-contrib-command-yum"></a> yum
+#### yum <a id="plugin-contrib-command-yum"></a>
The [check_yum](https://github.com/calestyo/check_yum) plugin checks the YUM package
management system for package updates.
The plugin requires the `yum-plugin-security` package to differentiate between security and normal updates.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
yum_installroot | **Optional.** Specifies another installation root directory (for example a chroot).
yum_timeout | **Optional.** Set a timeout in seconds after which the plugin will exit (defaults to 55 seconds).
-### <a id="plugins-contrib-storage"></a> Storage
+### Storage <a id="plugins-contrib-storage"></a>
This category includes all plugins for various storage and object storage technologies.
-#### <a id="plugins-contrib-command-glusterfs"></a> glusterfs
+#### glusterfs <a id="plugins-contrib-command-glusterfs"></a>
The [glusterfs](https://www.unixadm.org/software/nagios-stuff/checks/check_glusterfs) plugin
is used to check the GlusterFS storage health on the server.
The plugin requires `sudo` permissions.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
---------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
glusterfs_inode_critical | **Optional.** Return a critical error if inode usage is above *DISKCRIT*. Defaults to 95 (percent).
-### <a id="plugin-contrib-virtualization"></a> Virtualization
+### Virtualization <a id="plugin-contrib-virtualization"></a>
This category includes all plugins for various virtualization technologies.
-#### <a id="plugin-contrib-command-esxi-hardware"></a> esxi_hardware
+#### esxi_hardware <a id="plugin-contrib-command-esxi-hardware"></a>
The [check_esxi_hardware.py](https://www.claudiokuenzler.com/nagios-plugins/check_esxi_hardware.php) plugin
uses the [pywbem](https://pywbem.github.io/pywbem/) Python library to monitor the hardware of ESXi servers
through the [VMWare API](https://www.vmware.com/support/pubs/sdk_pubs.html) and CIM service.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
esxi_hardware_notemp | **Optional.** Do not collect temperature performance data, when **esxi_hardware_perfdata** is set to true. Defaults to false.
esxi_hardware_nofan | **Optional.** Do not collect fan performance data, when **esxi_hardware_perfdata** is set to true. Defaults to false.
-#### <a id="plugin-contrib-vmware"></a> VMware
+#### VMware <a id="plugin-contrib-vmware"></a>
Check commands for the [check_vmware_esx](https://github.com/BaldMansMojo/check_vmware_esx) plugin.
Check command object for the `check_vmware_esx` plugin. Shows all datastore volumes info.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Shows all runtime info for the datacenter/Vcenter.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. List of vmware machines and their power state. BEWARE!! In larger environments systems can cause trouble displaying the informations needed due to the mass of data. Use **vmware_alertonly** to avoid this.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. List of VMware ESX hosts and their power state.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. List of VMware clusters and their states.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. All issues for the host.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Overall object status (gray/green/red/yellow).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Vmware Tools status.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Simple check to verify a successfull connection to VMware SOAP API.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Displays uptime of the VMware host.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. CPU usage in percentage.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Percentage of time that the virtual machine was ready, but could not get scheduled to run on the physical CPU. CPU ready time is dependent on the number of virtual machines on the host and their CPU loads. High or growing ready time can be a hint CPU bottlenecks.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. CPU time spent in wait state. The wait total includes time spent the CPU idle, CPU swap wait, and CPU I/O wait states. High or growing wait time can be a hint I/O bottlenecks.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Actively used CPU of the host, as a percentage of the total available CPU. Active CPU is approximately equal to the ratio of the used CPU to the available CPU.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. All mem info(except overall and no thresholds).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Average mem usage in percentage.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Amount of machine memory used on the host. Consumed memory includes Includes memory used by the Service Console, the VMkernel vSphere services, plus the total consumed metrics for all running virtual machines in MB.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Amount of memory that is used by swap. Sum of memory swapped of all powered on VMs and vSphere services on the host in MB. In case of an error all VMs with their swap used will be displayed.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Additional mem used by VM Server in MB.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. The sum of all vmmemctl values in MB for all powered-on virtual machines, plus vSphere services on the host. If the balloon target value is greater than the balloon value, the VMkernel inflates the balloon, causing more virtual machine memory to be reclaimed. If the balloon target value is less than the balloon value, the VMkernel deflates the balloon, which allows the virtual machine to consume additional memory if needed (used by VM memory control driver). In case of an error all VMs with their vmmemctl values will be displayed.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Shows net info.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Overall network usage in KBps(Kilobytes per Second).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Data receive in KBps(Kilobytes per Second).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Data send in KBps(Kilobytes per Second).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Check all active NICs.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Shows all datastore volumes info.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Shows all disk io info. Without subselect no thresholds can be given. All I/O values are aggregated from historical intervals over the past 24 hours with a 5 minute sample rate.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Number of aborted SCSI commands.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Number of SCSI bus resets.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Average number of kilobytes read from the disk each second.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Average amount of time (ms) to process a SCSI read command issued from the Guest OS to the virtual machine.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Average number of kilobytes written to disk each second.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Average amount of time (ms) taken to process a SCSI write command issued by the Guest OS to the virtual machine.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Aggregated disk I/O rate. For hosts, this metric includes the rates for all virtual machines running on the host.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Average amount of time (ms) spent by VMkernel processing each SCSI command.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Average amount of time (ms) to complete a SCSI command from the physical device.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Average amount of time (ms) spent in the VMkernel queue.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Average amount of time (ms) taken during the collection interval to process a SCSI command issued by the guest OS to the virtual machine. The sum of kernelWriteLatency and deviceWriteLatency.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. List vm's with attached host mounted media like cd,dvd or floppy drives. This is important for monitoring because a virtual machine with a mount cd or dvd drive can not be moved to another host.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Shows host service info.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Shows runtime info: VMs, overall status, connection state, health, storagehealth, temperature and sensor are represented as one value and without thresholds.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Shows connection state.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. List of VMware machines and their status.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Overall object status (gray/green/red/yellow).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Checks cpu/storage/memory/sensor status.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. List all available sensors(use for listing purpose only).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. This is to avoid a double alarm if you use **vmware-esx-soap-host-runtime-health** and **vmware-esx-soap-host-runtime-storagehealth**.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Local storage status check.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Lists all temperature sensors.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Lists all configuration issues for the host.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Shows Host storage info.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. List host bus adapters.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. List SCSI logical units. The listing will include: LUN, canonical name of the disc, all of displayed name which is not part of the canonical name and status.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. List multipaths and the associated paths.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Shows all CPU usage info.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Percentage of time that the virtual machine was ready, but could not get scheduled to run on the physical CPU.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. CPU time spent in wait state. The wait total includes time spent the CPU idle, CPU swap wait, and CPU I/O wait states. High or growing wait time can be a hint I/O bottlenecks.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Amount of actively used virtual CPU, as a percentage of total available CPU. This is the host's view of the CPU usage, not the guest operating system view. It is the average CPU utilization over all available virtual CPUs in the virtual machine.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Shows all memory info, except overall.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Average mem usage in percentage of configured virtual machine "physical" memory.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Amount of guest physical memory in MB consumed by the virtual machine for guest memory. Consumed memory does not include overhead memory. It includes shared memory and memory that might be reserved, but not actually used. Use this metric for charge-back purposes.<br>
**vm consumed memory = memory granted -- memory saved**
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Amount of guest physical memory that is currently reclaimed from the virtual machine through ballooning. This is the amount of guest physical memory that has been allocated and pinned by the balloon driver.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Shows net info.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Overall network usage in KBps(Kilobytes per Second).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Receive in KBps(Kilobytes per Second).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Send in KBps(Kilobytes per Second).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. SShows all disk io info. Without subselect no thresholds can be given. All I/O values are aggregated from historical intervals over the past 24 hours with a 5 minute sample rate.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Average number of kilobytes read from the disk each second.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Average number of kilobytes written to disk each second.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Aggregated disk I/O rate.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Shows virtual machine runtime info.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Shows the connection state.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Shows virtual machine power state: poweredOn, poweredOff or suspended.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Overall object status (gray/green/red/yellow).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Console connections to virtual machine.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Guest OS status. Needs VMware Tools installed and running.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. Guest OS status. VMware tools status.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
Check command object for the `check_vmware_esx` plugin. All issues for the virtual machine.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
vmware_multiline | **Optional.** Multiline output in overview. This mean technically that a multiline output uses a HTML **\<br\>** for the GUI. No value defined as default.
-### <a id="plugin-contrib-web"></a> Web
+### Web <a id="plugin-contrib-web"></a>
This category includes all plugins for web-based checks.
-#### <a id="plugin-contrib-command-apache_status"></a> apache_status
+#### apache_status <a id="plugin-contrib-command-apache_status"></a>
The [check_apache_status.pl](https://github.com/lbetz/check_apache_status) plugin
uses the [/server-status](https://httpd.apache.org/docs/current/mod/mod_status.html)
HTTP endpoint to monitor status metrics for the Apache webserver.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|----------------------------------------------------------------------------------
apache_status_critical | **Optional.** Critical threshold (number of open slots, busy workers and idle workers that will cause a CRITICAL) like ':10,25,:20'.
-### <a id="plugin-check-command-ssl_cert"></a> cert
+### cert <a id="plugin-check-command-ssl_cert"></a>
The [check_ssl_cert](https://github.com/matteocorti/check_ssl_cert) plugin
uses the openssl binary (and optional curl) to check a X.509 certificate.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
--------------------------|--------------
ssl_cert_ignore_ocsp | **Optional.** Do not check revocation with OCSP.
-#### <a id="plugin-contrib-command-jmx4perl"></a> jmx4perl
+#### jmx4perl <a id="plugin-contrib-command-jmx4perl"></a>
The [check_jmx4perl](http://search.cpan.org/~roland/jmx4perl/scripts/check_jmx4perl) plugin
uses the HTTP API exposed by the [Jolokia](https://jolokia.org)
part of the `JMX::Jmx4Perl` Perl module which includes detailed
[documentation](http://search.cpan.org/~roland/jmx4perl/scripts/check_jmx4perl).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------
jmx4perl_check | **Optional.** Name of a check configuration as defined in the configuration file, use array if you need arguments.
-#### <a id="plugin-contrib-command-kdc"></a> kdc
+#### kdc <a id="plugin-contrib-command-kdc"></a>
The [check_kdc](https://exchange.nagios.org/directory/Plugins/Security/check_kdc/details) plugin
uses the Kerberos `kinit` binary to monitor Kerberos 5 KDC by acquiring a ticket.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------------------------------------------------------------------
kdc_keytab | **Required** Keytab file containing principal's key.
-#### <a id="plugin-contrib-command-nginx_status"></a> nginx_status
+#### nginx_status <a id="plugin-contrib-command-nginx_status"></a>
The [check_nginx_status.pl](https://github.com/regilero/check_nginx_status) plugin
uses the [/nginx_status](https://nginx.org/en/docs/http/ngx_http_stub_status_module.html)
HTTP endpoint which provides metrics for monitoring Nginx.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
--------------------------------|----------------------------------------------------------------------------------
nginx_status_critical | **Optional.** Critical threshold (number of active connections, ReqPerSec or ConnPerSec that will cause a CRITICAL) like '20000,200,300'.
-#### <a id="plugin-contrib-command-rbl"></a> rbl
+#### rbl <a id="plugin-contrib-command-rbl"></a>
The [check_rbl](https://github.com/matteocorti/check_rbl) plugin
uses the `Net::DNS` Perl library to check whether your SMTP server
is blacklisted.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
----------------|--------------------------------------------------------------------------
tbl_timeout | **Optional** Seconds before plugin times out (default: 15).
-#### <a id="plugin-contrib-command-squid"></a> squid
+#### squid <a id="plugin-contrib-command-squid"></a>
The [check_squid](https://exchange.icinga.com/exchange/check_squid) plugin
uses the `squidclient` binary to monitor a [Squid proxy](http://www.squid-cache.org).
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|----------------------------------------------------------------------------------
squid_timeout | **Optional.** Seconds before plugin times out (default: 15).
-#### <a id="plugin-contrib-command-webinject"></a> webinject
+#### webinject <a id="plugin-contrib-command-webinject"></a>
The [check_webinject](https://labs.consol.de/de/nagios/check_webinject/index.html) plugin
uses [WebInject](http://www.webinject.org/manual.html) to test web applications
and collect/report your results. WebInject offers real-time results
display and may also be used for monitoring system response times.
-Custom attributes passed as [command parameters](3-monitoring-basics.md#command-passing-parameters):
+Custom attributes passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
Name | Description
------------------------|--------------
-# <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 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.
# 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
[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
checked. You can do this by putting your configuration file name in angle
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,
e.g. to test [functions](17-language-reference.md#functions) in your local sandbox.
"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.
Furthermore it allows to run the [configuration validation](11-cli-commands.md#config-validation).
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.
-## <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:
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**
>
> 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
-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 - The Icinga 2 network monitoring daemon (version: v2.6.0)
-## <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
attributes. The command also shows where each of the attributes was modified and as such
Report bugs at <https://github.com/Icinga/icinga2>
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
* 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.
-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 - The Icinga 2 network monitoring daemon (version: v2.6.0)
Report bugs at <https://github.com/Icinga/icinga2>
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**
>
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.
-## <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
purposes and prints them to a file or the console. See [troubleshooting](15-troubleshooting.md#troubleshooting-information-required).
Report bugs at <https://github.com/Icinga/icinga2>
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).
Report bugs at <https://github.com/Icinga/icinga2>
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
are installed in the `/etc/icinga2/features-available` directory and can be
-## <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
the configuration changes. Icinga 2 will log any configuration error including
# /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.
# icinga2 daemon -C
-## <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
to [validate](11-cli-commands.md#config-validation). If there are no validation errors, you can
-# <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
`api` [feature](11-cli-commands.md#enable-features) and set up
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
and resources in a simple, programmatic way using HTTP requests.
* [manage configuration packages](12-icinga2-api.md#icinga2-api-config-management)
* 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
the API, for example [curl](https://curl.haxx.se/).
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
-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`
configuration file.
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`
list. Depending on the number of affected objects in your request, the
> should gracefully handle fields it is not familiar with, for example by
> 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)
including error codes.
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.
-### <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:
* username and password using HTTP basic auth
* 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
and the `password` attribute contains the basic auth password.
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
-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
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.
-### <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
actions on the URL endpoints.
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
passing parameters to the request:
The [match function](18-library-reference.md#global-functions-match) is available as global function
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
parameters (e.g. complex filters or JSON-encoded dictionaries) you can use the `X-HTTP-Method-Override`
$ 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
example, the following query returns all `Host` objects:
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
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**
>
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 id="icinga2-api-config-objects"></a> Config Objects
+## Config Objects <a id="icinga2-api-config-objects"></a>
Provides methods to manage configuration objects:
* [modifying objects](12-icinga2-api.md#icinga2-api-config-objects-modify)
* [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
Icinga 2 cluster. Set the `zone` attribute to the zone this object
>
> Cluster nodes must accept configuration for creating, modifying
> 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.
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
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
a `GET` query to the `/v1/objects/<type>` URL endpoint. `<type` has
$ curl -k -s -u root:icinga 'https://localhost:5665/v1/objects/hosts'
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:
]
}
-#### <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:
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.
-#### <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
information about the host when querying service objects.
]
}
-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 downtimes):
]
}
-### <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
parameters need to be passed inside the JSON body:
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)-
- 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 full name (e.g. `example.localdomain!http`) must be specified.
-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
parameters need to be passed inside the JSON body:
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.
> **Note**:
>
> 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.
>
> Furthermore you cannot modify templates which have already been resolved
}
-### <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`
request.
]
}
-## <a id="icinga2-api-config-templates"></a> Config Templates
+## Config Templates <a id="icinga2-api-config-templates"></a>
Provides methods to manage configuration templates:
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
a `GET` query to the `/v1/templates/<type>` URL endpoint. `<type` has
$ curl -k -s -u root:icinga 'https://localhost:5665/v1/templates/hosts'
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
template object can be accessed in the filter using the `tmpl` variable. In this
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:
* [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
a `GET` query to the `/v1/variables/` URL endpoint:
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`
URL endpoint. You can run actions by sending a `POST` request.
$ 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.
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.
}
-### <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
type can be forced being sent to all users.
}
}
-### <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.
Note that this will only have an effect if the service stays in the same problem
}
}
-### <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
acknowledging the current problem, future notifications (for the same state if `sticky` is set to `false`)
}
-### <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
been removed notifications will be sent out again.
}
}
-### <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.
]
}
-### <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
comment did not exist.
}
-### <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.
comment | string | **Required.** Comment text.
start\_time | timestamp | **Required.** Timestamp marking the beginning 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.
- 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`.
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`.
]
}
-### <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
downtime did not exist.
]
}
-### <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.
]
}
-### <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.
]
}
-### <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.
Send a `POST` request to the URL endpoint `/v1/actions/generate-ticket`.
}
-## <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`.
The following parameters need to be specified (either as URL parameters or in a JSON-encoded message body):
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).
-### <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:
&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.`.
&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
must support long-polling and HTTP/1.1. HTTP/1.0 is not supported.
{"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.
}
-## <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
creating configuration packages and stages based on configuration files and
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
will create a new empty configuration package.
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.
Stages provide a way to maintain multiple configuration versions for a package.
Directory | Description
------------|------------------------------------
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:
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 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
the URL endpoint `/v1/config/stages`. You need to include
]
}
-### <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
the package name, the stage name and the relative path to the file to the URL path.
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.
-### <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),
there must have been an error.
> 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`
in order to purge a configuration stage. You must include the package and
}
-### <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
you can send a `DELETE` request to the URL endpoint `/v1/config/packages`
}
-## <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
endpoint `/v1/types`.
}
-## <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`.
In order to receive auto-completion suggestions, send a `POST` request to the URL endpoint `/v1/console/auto-complete-script`.
}
-## <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:
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.
-### <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.
The Windows installer already includes Icinga Studio. On Debian and Ubuntu the package
`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
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.
-### <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
verification. The CA file is expected in `pki/icinga2-ca.crt`
The `filter` attribute [matches](18-library-reference.md#global-functions-match)
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:
$ 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:
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:
$ 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:
-# <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.
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
storing collected metrics and making them available through restful apis
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.
It’s written in Go and has no external dependencies.
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
[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
[DB IDO](14-features.md#db-ido) as a backend you can create your own network maps
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
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
[Graylog](https://www.graylog.org) in your infrastructure and correlate events with your monitoring
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:
-* E-Mail ([examples](3-monitoring-basics.md#alert-notifications) provided)
+* E-Mail ([examples](03-monitoring-basics.md#alert-notifications) provided)
* SMS
* Pager (XMPP, etc.)
* Twitter
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
touch with their developers. The Icinga project does not provide a configuration web interface
* [Puppet Module](https://github.com/Icinga/puppet-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
the action url attribute in its own module).
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).
This behavior changed in Icinga 2 compared to Icinga 1.x. Though there are certain possibilities to
-# <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:
platforms. This configuration ensures that the `icinga2.log`, `error.log` and
`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
configuration and status information into a database. The IDO database is used
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
-[IdoMysqlConnection](9-object-types.md#objecttype-idomysqlconnection) and
-[IdoPgsqlConnection](9-object-types.md#objecttype-idopgsqlconnection)
+[IdoMysqlConnection](09-object-types.md#objecttype-idomysqlconnection) and
+[IdoPgsqlConnection](09-object-types.md#objecttype-idopgsqlconnection)
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 following example query checks the health of the current Icinga 2 instance
> **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.
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
triggering specific actions (for example rescheduling a service check
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).
-## <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
`performance data`. Next to that additional check performance data
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).
-### <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
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
with Icinga 2 runtime vars.
External collectors need to parse the rotated performance data files and then
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)
collector scripts and daemons like Graphios available for Icinga 1.x it's more
# 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`.
-#### <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
module will use that schema too.
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$.services.$service.name$.$service.check_command$
pattern = ^icinga2\.
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**
>
You can customize the metric prefix name by using the `host_name_template` and
`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
-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"
pattern = ^icinga\.
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
defined InfluxDB HTTP API.
# 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`.
-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))
can be used to send application logs directly to a TCP socket.
* State changes
* 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
from the Icinga 2 API and sends it either directly to Elasticsearch or Logstash.
* [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.
-### <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
Icinga 1.x it's more reasonable to directly process the check and plugin performance
> 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
implements a query protocol that lets users query their Icinga instance for
> **Tip**
>
> 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.
The Livestatus component that is distributed as part of Icinga 2 is a
# 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
* Unix socket (default)
* 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.
-### <a id="livestatus-get-queries"></a> Livestatus GET Queries
+### Livestatus GET Queries <a id="livestatus-get-queries"></a>
> **Note**
>
(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)
$ 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
>= | | Greater than or equal
-### <a id="livestatus-stats"></a> Livestatus Stats
+### Livestatus Stats <a id="livestatus-stats"></a>
Schema: "Stats: aggregatefunction aggregateattribute"
OutputFormat: json
ResponseHeader: fixed16
-### <a id="livestatus-output"></a> Livestatus Output
+### Livestatus Output <a id="livestatus-output"></a>
* CSV
Default separators.
-### <a id="livestatus-error-codes"></a> Livestatus Error Codes
+### Livestatus Error Codes <a id="livestatus-error-codes"></a>
Code | Description
----------|--------------
404 | Table does not exist
452 | Exception on query
-### <a id="livestatus-tables"></a> Livestatus Tables
+### Livestatus Tables <a id="livestatus-tables"></a>
Table | Join |Description
--------------|-----------|----------------------------
downtimes | services | status attributes
timeperiods | | name and is inside flag
endpoints | | config and status attributes
- log | services, hosts, contacts, commands | parses [compatlog](9-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
+ log | services, hosts, contacts, commands | parses [compatlog](09-object-types.md#objecttype-compatlogger) and shows log 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
servicesbygroup | servicegroups | service attributes grouped by servicegroup and its attributes
servicesbyhostgroup | hostgroups | service attributes grouped by hostgroup and its attributes
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
interval to its `objects.cache` and `status.dat` files. Icinga 2 provides
> 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`
in Icinga 2 provided with the `CompatLogger` object.
[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
where they are processed in a regular interval.
-# <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.
Whether you ask on the community channels or you create an issue at [GitHub](https://github.com/Icinga), make sure
* [Icinga Web 2 modules](https://www.icinga.com/products/icinga-web-2-modules/) e.g. the Icinga Director (optional)
* Configuration insights:
* Provide complete configuration snippets explaining your problem in detail
- * Your [icinga2.conf](4-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.
+ * Your [icinga2.conf](04-configuring-icinga-2.md#icinga2-conf) file
+ * 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
* 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`
* 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
-## <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
analyze a problem, keep in mind that basic system administration knowledge
> **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.
* Collect details about all applications (e.g. Icinga 2, MySQL, Apache, Graphite, Elastic, etc.).
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
interactively.
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).
Keep notes which could be important for your monitoring, and add service
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:
# /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`.
-### <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.
C:> net stop 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
attributes. The tool also shows where each of the attributes was modified.
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
included with
include <itl>
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
`LocalStateDir + "/share/icinga2/includes"`.
You should add your own command definitions to a new file in `conf.d/` called `commands.conf`
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
for their check result containing the executed shell command.
# 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.
* Verify that failed depedencies do not prevent command execution.
$ 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/)
which is enabled in SLES 12 SP2+ for example. The default value
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
a dashboard overview for `overdue checks`.
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.
-### <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.
Host and Service objects provide the attribute `paused`. If this is set to `false`, the current node
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.
This analysis assumes that clients which are not connected, have the string `connected` in their
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.
-## <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.
* If yes, verify that all conditions are satisfied.
Verify the following configuration:
* 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 [user](9-object-types.md#objecttype-user) 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](09-object-types.md#objecttype-user) attributes `states`, `types`, `period` match the notification conditions?
* Are there any notification `begin` and `end` times configured?
* 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?
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
changed on your system.
$ 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/`
-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?
* 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 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
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.
Search for the file which should be included i.e. using the `grep` CLI 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
contain additional attributes, your objects will automatically inherit them. You can override
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
-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}'.
"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.
> **Note**
> Some problems just exist due to wrong file permissions or applied packet filters. Make
> 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:
# 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
the following
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.
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
both instances are signed by the **same CA**.
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
will be disconnected. If the connection can't be re-established between endpoints in the same HA zone,
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.
-### <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)
-as well as inside an [High-Availability cluster](6-distributed-monitoring.md#distributed-monitoring-scenarios).
+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](06-distributed-monitoring.md#distributed-monitoring-scenarios).
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):
* `/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.
* Referenced check plugin not found on the remote client.
* Runtime warnings and errors, e.g. unresolved runtime macros or configuration problems.
-### <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:
** 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 `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.
-### <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
(satellite, clients, etc.), make sure to check whether the client sending in events
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
certificate's CN, the master will deny all events.
> **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.
Enable the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) on the master
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
cannot replay the log on connection loss and re-establishment. A master node for example
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.
* 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).
-# <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
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
`/usr/share/icinga2-ido-mysql/schema/upgrade` directory for an incremental schema upgrade file.
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.
-## <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
`/usr/share/icinga2-ido-pgsql/schema/upgrade` directory for an incremental schema upgrade file.
-# <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
objects using the `object` keyword:
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.
-## <a id="expressions"></a> Expressions
+## Expressions <a id="expressions"></a>
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.
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
suffixes to help with specifying time durations.
Duration literals are converted to seconds by the config parser and
are treated like numeric literals.
-### <a id="string-literals"></a> String Literals
+### String Literals <a id="string-literals"></a>
A string.
"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
are supported:
arbitrary ASCII characters using the backslash character (\\) followed
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
{{{ and }}}.
Unlike in ordinary strings special characters do not have to be escaped
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.
-### <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.
-### <a id="dictionary"></a> Dictionary
+### Dictionary <a id="dictionary"></a>
An unordered list of key-value pairs. Keys must be unique and are
compared in a case-sensitive manner.
key that is not a valid identifier, you can enclose the key in double
quotes.
-### <a id="array"></a> Array
+### Array <a id="array"></a>
An ordered list of values.
An array may simultaneously contain values of different types, such as
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.
= | 12 | a = 3 | Assignment
=> | 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:
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
to manipulate attributes are supported. Here's a list of all
available operators:
-### <a id="operator-assignment"></a> Operator =
+### Operator = <a id="operator-assignment"></a>
Sets an attribute to the specified value.
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:
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:
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:
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:
a = a / 5
}
-## <a id="indexer"></a> Indexer
+## Indexer <a id="indexer"></a>
The indexer syntax provides a convenient way to set dictionary elements.
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.
If there are multiple default templates the order in which they are imported
is unspecified.
-## <a id="constants"></a> Constants
+## Constants <a id="constants"></a>
Global constants can be set using the `const` keyword:
Once defined a constant can be accessed from any file. Constants cannot be changed
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:
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.
-## <a id="apply"></a> Apply
+## Apply <a id="apply"></a>
The `apply` keyword can be used to create new objects which are associated with
another group of objects.
variables. For example, `host.address` would return the value of the host's
"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.
-## <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
[for loop](17-language-reference.md#for-loops) keyword.
It is not necessary to check attributes referenced in the `for loop` expression
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.
-## <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`
and `ignore where` conditions.
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
well as the `bool()` function convert their arguments to a boolean value based on the
For a list of supported expression operators for `assign where` and `ignore where`
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.
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.
Paths must be relative to the configuration file that contains the
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
files in a directory which match a certain pattern.
The file names need to match the pattern given in the second parameter.
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
given path.
The file names need to match the pattern given in the third parameter.
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
libraries. Libraries can be used to provide additional object types and
library "snmphelper"
-## <a id="functions"></a> Functions
+## Functions <a id="functions"></a>
Functions can be defined using the `function` keyword.
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.
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.
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
already exists there:
We're using `hm.init` to invoke the function which causes the value of `hm` to become the `this`
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
outside of their scope (except for global variables).
}
}
-## <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
construct can be used to accomplish this.
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`.
This is repeated until the condition is no longer true.
skips over the remaining expressions for the loop body and begins the next loop evaluation. The `break` keyword
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.
skips over the remaining expressions for the loop body and begins the next loop evaluation. The `break` keyword
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.
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
using the `throw` keyword.
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
`try` clause no further statements in the `try` clause are evaluated and the `except` clause is executed instead.
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.
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:
Dictionary | { a = 3 } | A dictionary.
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.
Each type has an associated type object which describes the type's semantics. These
Additional documentation on type methods is available in the
[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
`current_filename` and `current_line` keywords.
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.
-# <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)
and the [Icinga 2 debug console](11-cli-commands.md#cli-command-console).
as a sandbox to test these functions before implementing
them in your scenarios.
-### <a id="global-functions-regex"></a> regex
+### regex <a id="global-functions-regex"></a>
Signature:
<3> => regex("^Linux$", host.vars.os_type)
false
-### <a id="global-functions-match"></a> match
+### match <a id="global-functions-match"></a>
Signature:
<4> => match("NUE-*-DEV-*", host.display_name)
false
-### <a id="global-functions-cidr_match"></a> cidr_match
+### cidr_match <a id="global-functions-cidr_match"></a>
Signature:
<3> => cidr_match("192.168.56.0/26", host.address)
false
-### <a id="global-functions-range"></a> range
+### range <a id="global-functions-range"></a>
Signature:
<3> => range(2,10,2)
[ 2.000000, 4.000000, 6.000000, 8.000000 ]
-### <a id="global-functions-len"></a> len
+### len <a id="global-functions-len"></a>
Signature:
10.000000
-### <a id="global-functions-union"></a> union
+### union <a id="global-functions-union"></a>
Signature:
<3> => union(dev_notification_groups, host_notification_groups)
[ "devs", "noc", "slack" ]
-### <a id="global-functions-intersection"></a> intersection
+### intersection <a id="global-functions-intersection"></a>
Signature:
<3> => intersection(dev_notification_groups, host_notification_groups)
[ "slack" ]
-### <a id="global-functions-keys"></a> keys
+### keys <a id="global-functions-keys"></a>
Signature:
<3> => host.vars.disks.keys()
[ "/", "/var" ]
-### <a id="global-functions-string"></a> string
+### string <a id="global-functions-string"></a>
Signature:
<6> => DateTime(2016, 11, 25).to_string()
"2016-11-25 00:00:00 +0100"
-### <a id="global-functions-number"></a> number
+### number <a id="global-functions-number"></a>
Signature:
<2> => number("78")
78.000000
-### <a id="global-functions-bool"></a> bool
+### bool <a id="global-functions-bool"></a>
Signature:
<2> => bool(0)
false
-### <a id="global-functions-random"></a> random
+### random <a id="global-functions-random"></a>
Signature:
<2> => random()
108402530.000000
-### <a id="global-functions-log"></a> log
+### log <a id="global-functions-log"></a>
Signature:
critical/Console: ["devs","slack"]
null
-### <a id="global-functions-typeof"></a> typeof
+### typeof <a id="global-functions-typeof"></a>
Signature:
<5> => typeof({ a = 2, b = 3 }) == Dictionary
true
-### <a id="global-functions-get_time"></a> get_time
+### get_time <a id="global-functions-get_time"></a>
Signature:
<2> => get_time()
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:
warn = null
}
-### <a id="global-functions-dirname"></a> dirname
+### dirname <a id="global-functions-dirname"></a>
Signature:
<2> => dirname(path)
"/etc/icinga2/scripts"
-### <a id="global-functions-basename"></a> basename
+### basename <a id="global-functions-basename"></a>
Signature:
<2> => basename(path)
"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:
<1> => escape_shell_arg("'$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:
<1> => escape_shell_cmd("/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:
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:
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.
-### <a id="objref-get_check_command"></a> get_check_command
+### get_check_command <a id="objref-get_check_command"></a>
Signature:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
to a type object.
-### <a id="objref-get_objects"></a> get_objects
+### get_objects <a id="objref-get_objects"></a>
Signature:
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
and functions.
-### <a id="math-e"></a> Math.E
+### Math.E <a id="math-e"></a>
Euler's constant.
-### <a id="math-ln2"></a> Math.LN2
+### Math.LN2 <a id="math-ln2"></a>
Natural logarithm of 2.
-### <a id="math-ln10"></a> Math.LN10
+### Math.LN10 <a id="math-ln10"></a>
Natural logarithm of 10.
-### <a id="math-log2e"></a> Math.LOG2E
+### Math.LOG2E <a id="math-log2e"></a>
Base 2 logarithm of E.
-### <a id="math-pi"></a> Math.PI
+### Math.PI <a id="math-pi"></a>
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.
-### <a id="math-sqrt2"></a> Math.SQRT2
+### Math.SQRT2 <a id="math-sqrt2"></a>
Square root of 2.
-### <a id="math-abs"></a> Math.abs
+### Math.abs <a id="math-abs"></a>
Signature:
Returns the absolute value of `x`.
-### <a id="math-acos"></a> Math.acos
+### Math.acos <a id="math-acos"></a>
Signature:
Returns the arccosine of `x`.
-### <a id="math-asin"></a> Math.asin
+### Math.asin <a id="math-asin"></a>
Signature:
Returns the arcsine of `x`.
-### <a id="math-atan"></a> Math.atan
+### Math.atan <a id="math-atan"></a>
Signature:
Returns the arctangent of `x`.
-### <a id="math-atan2"></a> Math.atan2
+### Math.atan2 <a id="math-atan2"></a>
Signature:
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:
Returns the smallest integer value not less than `x`.
-### <a id="math-cos"></a> Math.cos
+### Math.cos <a id="math-cos"></a>
Signature:
Returns the cosine of `x`.
-### <a id="math-exp"></a> Math.exp
+### Math.exp <a id="math-exp"></a>
Signature:
Returns E raised to the `x`th power.
-### <a id="math-floor"></a> Math.floor
+### Math.floor <a id="math-floor"></a>
Signature:
Returns the largest integer value not greater than `x`.
-### <a id="math-isinf"></a> Math.isinf
+### Math.isinf <a id="math-isinf"></a>
Signature:
Returns whether `x` is infinite.
-### <a id="math-isnan"></a> Math.isnan
+### Math.isnan <a id="math-isnan"></a>
Signature:
Returns whether `x` is NaN (not-a-number).
-### <a id="math-log"></a> Math.log
+### Math.log <a id="math-log"></a>
Signature:
Returns the natural logarithm of `x`.
-### <a id="math-max"></a> Math.max
+### Math.max <a id="math-max"></a>
Signature:
Returns the largest argument. A variable number of arguments can be specified.
If no arguments are given, -Infinity is returned.
-### <a id="math-min"></a> Math.min
+### Math.min <a id="math-min"></a>
Signature:
Returns the smallest argument. A variable number of arguments can be specified.
If no arguments are given, +Infinity is returned.
-### <a id="math-pow"></a> Math.pow
+### Math.pow <a id="math-pow"></a>
Signature:
Returns `x` raised to the `y`th power.
-### <a id="math-random"></a> Math.random
+### Math.random <a id="math-random"></a>
Signature:
Returns a pseudo-random number between 0 and 1.
-### <a id="math-round"></a> Math.round
+### Math.round <a id="math-round"></a>
Signature:
Returns `x` rounded to the nearest integer value.
-### <a id="math-sign"></a> Math.sign
+### Math.sign <a id="math-sign"></a>
Signature:
Returns -1 if `x` is negative, 1 if `x` is positive
and 0 if `x` is 0.
-### <a id="math-sin"></a> Math.sin
+### Math.sin <a id="math-sin"></a>
Signature:
Returns the sine of `x`.
-### <a id="math-sqrt"></a> Math.sqrt
+### Math.sqrt <a id="math-sqrt"></a>
Signature:
Returns the square root of `x`.
-### <a id="math-tan"></a> Math.tan
+### Math.tan <a id="math-tan"></a>
Signature:
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.
-### <a id="json-encode"></a> Json.encode
+### Json.encode <a id="json-encode"></a>
Signature:
Encodes an arbitrary value into JSON.
-### <a id="json-decode"></a> Json.decode
+### Json.decode <a id="json-decode"></a>
Signature:
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:
var example = 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:
var example = 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:
"Hello World".find("World") /* Returns 6 */
-### <a id="string-contains"></a> String#contains
+### String#contains <a id="string-contains"></a>
Signature:
"Hello World".contains("World") /* Returns true */
-### <a id="string-len"></a> String#len
+### String#len <a id="string-len"></a>
Signature
"Hello World".len() /* Returns 11 */
-### <a id="string-lower"></a> String#lower
+### String#lower <a id="string-lower"></a>
Signature:
"Hello World".lower() /* Returns "hello world" */
-### <a id="string-upper"></a> String#upper
+### String#upper <a id="string-upper"></a>
Signature:
"Hello World".upper() /* Returns "HELLO WORLD" */
-### <a id="string-replace"></a> String#replace
+### String#replace <a id="string-replace"></a>
Signature:
Returns a copy of the string with all occurences of the string specified in `search` replaced
with the string specified in `replacement`.
-### <a id="string-split"></a> String#split
+### String#split <a id="string-split"></a>
Signature:
"x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */
-### <a id="string-substr"></a> String#substr
+### String#substr <a id="string-substr"></a>
Signature:
"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:
Returns a copy of the string.
-### <a id="string-reverse"></a> String#reverse
+### String#reverse <a id="string-reverse"></a>
Signature:
Returns a copy of the string in reverse order.
-### <a id="string-trim"></a> String#trim
+### String#trim <a id="string-trim"></a>
Signature:
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.
-### <a id="object-clone"></a> Object#clone
+### Object#clone <a id="object-clone"></a>
Signature:
reference values (e.g. objects such as arrays or dictionaries) the entire
object is recursively copied.
-### <a id="object-to-string"></a> Object#to_string
+### Object#to_string <a id="object-to-string"></a>
Signature:
[ 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:
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).
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:
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:
Returns the name of the type.
-### <a id="type-prototype"></a> Type#prototype
+### Type#prototype <a id="type-prototype"></a>
Signature:
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).
-### <a id="array-add"></a> Array#add
+### Array#add <a id="array-add"></a>
Signature:
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:
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();
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.
-### <a id="array-contains"></a> Array#contains
+### Array#contains <a id="array-contains"></a>
Signature:
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:
Returns the number of elements contained in the array.
-### <a id="array-remove"></a> Array#remove
+### Array#remove <a id="array-remove"></a>
Signature:
Removes the element at the specified zero-based index.
-### <a id="array-set"></a> Array#set
+### Array#set <a id="array-set"></a>
Signature:
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.
-### <a id="array-get"></a> Array#get
+### Array#get <a id="array-get"></a>
Signature:
Retrieves the element at the specified zero-based index.
-### <a id="array-sort"></a> Array#sort
+### Array#sort <a id="array-sort"></a>
Signature:
compared using the `<` (less-than) operator. A custom comparator function
can be specified with the `less_cmp` argument.
-### <a id="array-join"></a> Array#join
+### Array#join <a id="array-join"></a>
Signature:
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:
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:
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 id="array-reduce"></a> Array#reduce
+### Array#reduce <a id="array-reduce"></a>
Signature:
function `func` as `func(a, b)` repeatedly where `a` and `b` are elements of the array
or results from previous function calls.
-### <a id="array-filter"></a> Array#filter
+### Array#filter <a id="array-filter"></a>
Signature:
Returns a copy of the array containing only the elements for which `func(element)`
is true.
-### <a id="array-any"></a> Array#any
+### Array#any <a id="array-any"></a>
Signature:
Returns true if the array contains at least one element for which `func(element)`
is true, false otherwise.
-### <a id="array-all"></a> Array#all
+### Array#all <a id="array-all"></a>
Signature:
Returns true if the array contains only elements for which `func(element)`
is true, false otherwise.
-### <a id="array-unique"></a> Array#unique
+### Array#unique <a id="array-unique"></a>
Signature:
Returns a copy of the array with all duplicate elements removed. The original order
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).
-### <a id="dictionary-shallow-clone"></a> Dictionary#shallow_clone
+### Dictionary#shallow_clone <a id="dictionary-shallow-clone"></a>
Signature:
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.
-### <a id="dictionary-contains"></a> Dictionary#contains
+### Dictionary#contains <a id="dictionary-contains"></a>
Signature:
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:
Returns the number of items contained in the dictionary.
-### <a id="dictionary-remove"></a> Dictionary#remove
+### Dictionary#remove <a id="dictionary-remove"></a>
Signature:
Removes the item with the specified `key`. Trying to remove an item which does not exist
is a no-op.
-### <a id="dictionary-set"></a> Dictionary#set
+### Dictionary#set <a id="dictionary-set"></a>
Signature:
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:
Retrieves the value for the specified `key`. Returns `null` if they `key` does not exist
in the dictionary.
-### <a id="dictionary-keys"></a> Dictionary#keys
+### Dictionary#keys <a id="dictionary-keys"></a>
Signature:
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:
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).
-### <a id="scriptfunction-call"></a> Function#call
+### Function#call <a id="scriptfunction-call"></a>
Signature:
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:
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).
-### <a id="datetime-ctor"></a> DateTime constructor
+### DateTime constructor <a id="datetime-ctor"></a>
Signature:
var d1 = DateTime() /* current 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.
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:
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:
-# <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`)
parameter to enable the script debugger:
* Configuration errors (apply)
* 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
provides a string value:
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:
-# <a id="development"></a> Develop Icinga 2
+# Develop Icinga 2 <a id="development"></a>
This chapter provides hints on Icinga 2 development
especially for debugging purposes.
> If you are planning to build your own development environment,
> 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.
The Icinga 2 packages provide a debug package which must be
build flag for debug builds.
-## <a id="development-debug-gdb"></a> GDB
+## GDB <a id="development-debug-gdb"></a>
Install gdb:
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
`/usr/lib64/icinga2/sbin/icinga2` since 2.4) and all arguments and run it in foreground.
(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
a new gdb run.
(gdb) r
(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 you create a [bug report](https://www.icinga.com/community/get-involved/),
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
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
-### <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
the current scope, attributes, and possible unmet requirements. `p` prints
(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.
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
a core dump file should be written. This will help
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`.
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
to explicitly enable core dumps for SUID on Linux.
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
attach this file to your bug report in addition to the general details.
-# <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.
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.
-### <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.
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.
# ps -eZ | grep 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.
# ps -eZ | grep 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.
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 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.
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`.
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.
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.
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
this user. This is completly optional!
$ sudo systemctl reload httpd.service
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.
-# <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
order to ease migration from Icinga 1.x, this section provides hints and tips
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
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
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,
or to adapt your configuration export tool to dump Icinga 2 configuration instead of
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
all existing Icinga 1.x `*_interval` attributes require an additional `m` duration literal.
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
-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:
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" {
import "generic-service"
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
a member and includes all members of the `hg1` hostgroup.
-#### <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
are referenced as `$ARGn$` where `n` is the argument counter.
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).
$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 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.
This migration part is explained in the [next chapter](22-migrating-from-icinga-1x.md#manual-config-migration-hints-notifications).
This user can be put into usergroups (former contactgroups) or referenced in newly migration notification
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
your existing Icinga 1.x configuration objects
* which contacts (users) are notified by mail?
* do the notification filters, periods, intervals still apply for them? (do a cleanup during migration)
* 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:
-#### <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
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
hostgroups and require a defined service object.
-#### <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
as the child.
-#### <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.
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
daemon for passing check results between instances.
* 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
-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,
-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,
you should re-design your setup and re-evaluate your requirements, and how they may be fulfilled
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.cfg` configuration file and object-based in included files (`cfg_dir`,
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
object files, Icinga 2 moves all templates into the Icinga Template Library (ITL)
> **Note**
>
> 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`.
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.
-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.
-### <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`
directives. The `cfg_dir` directive recursively includes all files with a `.cfg`
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
set in the `resource.cfg` configuration file in Icinga 1.x. By convention the
[Global macros](17-language-reference.md#constants) can only be defined once. Trying to modify a
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 (`;`)
for inline comments.
multi-line comments) or starting with two slashes (`//`). A leading hash (`#`)
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
to specify user-friendly names which should be shown in UIs (supported by
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
uses the `template` identifier:
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
requires an equal sign (=) between them.
If an attribute identifier starts with a number, it must be enclosed
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
for a more descriptive name. A service only can have a `display_name` attribute.
Icinga 2 only supports the `display_name` attribute which is also taken into
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.
The `notes`, `notes_url`, `action_url`, `icon_image`, `icon_image_alt`
`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 (`_`).
In Icinga 2 these attributes must be added to the `vars` dictionary as custom attributes.
vars.dn = "cn=icinga2-dev-host,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org"
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,
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
`host_name` attribute in the service definition. Alternate methods refer
to `hostgroup_name` or behaviour changing regular expression.
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
-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
only provide (custom) attributes and notification commands used for notifications,
but is also used for authorization checks in Icinga 1.x.
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.
In Icinga 2 notification commands are not directly associated with users.
reasons. These values are calculated from all services, their notifications,
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
-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
user and argument definitions (e.g., `USER1` or `ARG1`). Unlike in Icinga 1.x
>
> 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
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.
-#### <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
and stateful runtime macros. Custom attributes can be accessed directly.
-### <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`.
STOP_OBSESSING_OVER_SVC
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
being executed -- whether if it's a check, a notification, an event
handler, a performance data writing update, etc. That way you'll
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
`long_output` (remaining lines) like in Icinga 1.x. Performance Data is
split the raw output into `output` (first line) and `long_output` (remaining
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
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` 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.
-### <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:
`CheckCommand`, `NotificationCommand`, and `EventCommand`.
configuration validation if used in the wrong context.
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.
It's also possible to define default argument values for the command itself
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
timeout. This was essentially bad when there only was a couple of check plugins
requiring some command timeouts to be extended.
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.
-### <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`
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`
-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" {
import "generic-host"
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:
apply Service "ping4" {
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
notification configuration problem in Icinga 1.x:
Service -> Notification -> NotificationCommand
-> 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
objects. Escalations happen between a defined start and end time which is
That's not necessary with Icinga 2 only requiring an additional notification
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
state and type filters, Icinga 2 uses two configuration attributes for that.
Icinga 2 adds more fine-grained type filters for acknowledgements, downtime,
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
and keep a host's state unreachable rather than down.
and `child_host_name` (same for the service attribute). When using apply rules the
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.
Dependencies can be applied to hosts or services using the [apply rules](17-language-reference.md#apply).
support the Icinga 1.x schema with dependencies and parent attributes for
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
value is hardcoded and cannot be changed. The algorithm on determining a flapping state
threshold from a single value based on counters and half-life values. Icinga 2 compares
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_threshold` defines the threshold in seconds. Once the threshold is triggered, an
`freshness_threshold` attribute in Icinga 2. If the freshness checks are invalid, a new
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:
* parent process continues with old configuration objects and the event scheduling
(doing checks, replicating cluster events, triggering alert notifications, etc.)
* 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
(all events until now) into the icinga2 state file
* parent process shuts down writing icinga2.state file
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
to reload it after a restart. In Icinga 2 this file is called `icinga2.state`.
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
and archives. These logs are used in Icinga 1.x Classic UI to generate
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.
* 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
passing the slave's check results passively onto the master's external command pipe.
and configuration distribution problems Icinga 1.x distributed monitoring currently suffers from.
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.
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.
-# <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)
DISABLE_SERVICEGROUP_SVC_NOTIFICATIONS | ;<servicegroup_name> (1) | -
-## <a id="schemas"></a> Schemas
+## Schemas <a id="schemas"></a>
By convention `CheckCommand`, `EventCommand`, and `NotificationCommand` objects
are exported using a prefix. This is mandatory for unique objects in the
EventCommand | event_
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`.
* 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`.
-### <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
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:
Additional command custom variables populated from 'vars' dictionary.
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:
Command custom variables reflect the local 'vars' dictionary.
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
----------------------|-----------|-------------------------
`is_executing`, `check_options`, `obsess_over_host`, `first_notification_delay`, `x_3d`, `y_3d`, `z_3d`,
`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
----------------------|-----------|-------------------------
num_services_hard_crit | 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
----------------------|-----------|-------------------------
Not supported: `initial_state`, `is_executing`, `check_options`, `obsess_over_service`, `first_notification_delay`,
`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
----------------------|-----------|-------------------------
num_services_hard_crit | 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
----------------------|-----------|-------------------------
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
----------------------|-----------|-------------------------
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
----------------------|-----------|-------------------------
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
----------------------|-----------|-------------------------
`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
----------------------|-----------|-------------------------
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
----------------------|-----------|-------------------------
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
----------------------|-----------|-------------------------
alias | string | `display_name` attribute.
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
----------------------|-----------|-------------------------
current_contact_ | join | Prefix for attributes from implicit join with contacts 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
----------------------|-----------|-------------------------
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
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
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
the [hostgroups](23-appendix.md#schema-livestatus-hostgroups-table-attributes) table prefixed with `hostgroup_`.
projects / icinga2 / commitdiff