diff --git a/doc/1-about.md b/doc/01-about.md similarity index 98% rename from doc/1-about.md rename to doc/01-about.md index 006cd69b3..b595d0bf1 100644 --- a/doc/1-about.md +++ b/doc/01-about.md @@ -1,6 +1,6 @@ -# About Icinga 2 +# About Icinga 2 -## What is Icinga 2? +## What is Icinga 2? Icinga 2 is an open source monitoring system which checks the availability of your network resources, notifies users of outages, and generates performance @@ -9,19 +9,19 @@ data for reporting. Scalable and extensible, Icinga 2 can monitor large, complex environments across multiple locations. -## Licensing +## Licensing 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. -## Support +## Support 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/). -## Contribute +## Contribute There are many ways to contribute to Icinga -- whether it be sending patches, testing, reporting bugs, or reviewing and updating the documentation. Every @@ -29,7 +29,7 @@ contribution is appreciated! Please continue reading in the [Contributing chapter](https://github.com/Icinga/icinga2/blob/master/CONTRIBUTING.md). -### Icinga 2 Development +### Icinga 2 Development The Git repository is located on [GitHub](https://github.com/Icinga/icinga2). @@ -37,7 +37,7 @@ Icinga 2 is written in C++ and can be built on Linux/Unix and Windows. Read more about development builds in the [INSTALL.md](https://github.com/Icinga/icinga2/blob/master/INSTALL.md) file. -## What's New +## What's New ### What's New in Version 2.6.3 @@ -56,7 +56,7 @@ documentation. * Feature [5029](https://github.com/Icinga/icinga2/issues/5029) (Documentation): Advanced topics: Wrong acknowledgement notification filter * Feature [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 @@ -87,7 +87,7 @@ reflect our recent move to GitHub. #### 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 diff --git a/doc/2-getting-started.md b/doc/02-getting-started.md similarity index 89% rename from doc/2-getting-started.md rename to doc/02-getting-started.md index f62f5c52f..9395220c5 100644 --- a/doc/2-getting-started.md +++ b/doc/02-getting-started.md @@ -1,10 +1,10 @@ -# Getting Started +# Getting Started -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. -## Setting up Icinga 2 +## Setting up Icinga 2 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 @@ -26,7 +26,7 @@ and distribution you are running. Packages for distributions other than the ones listed above may also be available. Please contact your distribution packagers. -### Package Repositories +### Package Repositories You need to add the Icinga repository to your package management configuration. Below is a list with examples for the various distributions. @@ -75,7 +75,7 @@ openSUSE: # zypper ref -#### RHEL/CentOS EPEL Repository +#### RHEL/CentOS EPEL Repository The packages for RHEL/CentOS depend on other packages which are distributed as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL). @@ -87,17 +87,17 @@ CentOS 7/6: If you are using RHEL you need enable the `optional` repository and then install the [EPEL rpm package](https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F). -#### SLES Security Repository +#### SLES Security Repository 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/). -#### SLES 12 SDK +#### SLES 12 SDK 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. -### Installing Icinga 2 +### Installing Icinga 2 You can install Icinga 2 by using your distribution's package manager to install the `icinga2` package. @@ -126,7 +126,7 @@ FreeBSD: # pkg install icinga2 -### Enabled Features during Installation +### Enabled Features during Installation The default installation will enable three features required for a basic Icinga 2 installation: @@ -144,7 +144,7 @@ enabled and disabled. Enabled features: checker mainlog notification -### Installation Paths +### Installation Paths By default Icinga 2 uses the following files and directories: @@ -183,14 +183,14 @@ By default Icinga 2 uses the following files and directories: /var/lib/icinga2 | Icinga 2 state file, cluster log, local CA and configuration files (cluster, api). /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature. -## Setting up Check Plugins +## Setting up Check Plugins Without plugins Icinga 2 does not know how to check external services. The [Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides an extensive set of plugins which can be used with Icinga 2 to check whether services are working properly. -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 @@ -237,18 +237,18 @@ FreeBSD: # 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. -## Running Icinga 2 +## Running Icinga 2 -### Init Script +### Init Script Icinga 2's init script is installed in `/etc/init.d/icinga2` (`/usr/local/etc/rc.d/icinga2` on FreeBSD) by default: @@ -270,7 +270,7 @@ By default the Icinga 2 daemon is running as `icinga` user and group using the init script. Using Debian packages the user and group are set to `nagios` for historical reasons. -### systemd Service +### systemd Service Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The Icinga 2 packages automatically install the necessary systemd unit files. @@ -326,7 +326,7 @@ On FreeBSD you need to enable icinga2 in your rc.conf # service icinga2 restart -## Configuration Syntax Highlighting +## Configuration Syntax Highlighting 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` @@ -334,7 +334,7 @@ The RHEL and SUSE package `icinga2-common` installs these files into `/usr/share On Debian systems the `icinga2-common` package provides only the Nano configuration file (`/usr/share/nano/icinga2.nanorc`); to obtain the Vim configuration, please install the extra package `vim-icinga2`. The files are located in `/usr/share/vim/addons`. -### Configuration Syntax Highlighting using Vim +### Configuration Syntax Highlighting using Vim Install the package `vim-icinga2` with your distribution's package manager. @@ -365,7 +365,7 @@ Test it: ![Vim with syntax highlighting](images/getting-started/vim-syntax.png "Vim with Icinga 2 syntax highlighting") -### Configuration Syntax Highlighting using Nano +### Configuration Syntax Highlighting using Nano Install the package `nano-icinga2` with your distribution's package manager. @@ -398,7 +398,7 @@ Test it: ![Nano with syntax highlighting](images/getting-started/nano-syntax.png "Nano with Icinga 2 syntax highlighting") -## Setting up Icinga Web 2 +## Setting up Icinga Web 2 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. @@ -406,18 +406,18 @@ This chapter explains how to set up Icinga Web 2. The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of 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). -### Configuring DB IDO MySQL +### Configuring DB IDO MySQL -#### Installing MySQL database server +#### Installing MySQL database server Debian/Ubuntu: @@ -451,7 +451,7 @@ FreeBSD: # service mysql-server restart # mysql_secure_installation -#### Installing the IDO modules for MySQL +#### Installing the IDO modules for MySQL The next step is to install the `icinga2-ido-mysql` package using your distribution's package manager. @@ -479,7 +479,7 @@ and located at /usr/local/share/icinga2-ido-mysql/schema/mysql.sql > default. You can skip the automated setup and install/upgrade the > database manually if you prefer that. -#### Setting up the MySQL database +#### Setting up the MySQL database Set up a MySQL database for Icinga 2: @@ -497,14 +497,14 @@ following command: # mysql -u root -p icinga < /usr/share/icinga2-ido-mysql/schema/mysql.sql -#### Enabling the IDO MySQL module +#### Enabling the IDO MySQL module The package provides a new configuration file that is installed in `/etc/icinga2/features-available/ido-mysql.conf`. You will need to update the database credentials in this file. All available attributes are 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 @@ -529,11 +529,11 @@ FreeBSD: # 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). -### Configuring DB IDO PostgreSQL +### Configuring DB IDO PostgreSQL -#### Installing PostgreSQL database server +#### Installing PostgreSQL database server Debian/Ubuntu: @@ -564,7 +564,7 @@ FreeBSD: # sysrc postgresql_enable=yes # service postgresql start -#### Installing the IDO modules for PostgreSQL +#### Installing the IDO modules for PostgreSQL The next step is to install the `icinga2-ido-pgsql` package using your distribution's package manager. @@ -635,14 +635,14 @@ schema using the following command: ![importing the Icinga 2 IDO schema](images/getting-started/postgr-import-ido.png "Importing the Icinga 2 IDO schema on Debian Jessie") -#### Enabling the IDO PostgreSQL module +#### Enabling the IDO PostgreSQL module The package provides a new configuration file that is installed in `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update the database credentials in this file. All available attributes are 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 @@ -666,9 +666,9 @@ FreeBSD: # 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). -### Webserver +### Webserver Debian/Ubuntu: @@ -704,7 +704,7 @@ FreeBSD (nginx, but you could also use the apache24 package): # service php-fpm start # service nginx start -### Firewall Rules +### Firewall Rules Example: @@ -720,7 +720,7 @@ FreeBSD: Please consult the [FreeBSD Handbook](https://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/firewalls.html) how to configure one of FreeBSD's firewalls. -### Setting Up Icinga 2 REST API +### Setting Up Icinga 2 REST API 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. @@ -756,7 +756,7 @@ FreeBSD: # service icinga2 restart -### Installing Icinga Web 2 +### Installing Icinga Web 2 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. @@ -764,13 +764,13 @@ for further instructions on how to install Icinga Web 2. The Icinga 2 API can be defined as [command transport](https://github.com/Icinga/icingaweb2/blob/master/modules/monitoring/doc/commandtransports.md) in Icinga Web 2 >= 2.4. -## Addons +## Addons 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. -## Backup +## Backup Ensure to include the following in your backups: diff --git a/doc/3-monitoring-basics.md b/doc/03-monitoring-basics.md similarity index 89% rename from doc/3-monitoring-basics.md rename to doc/03-monitoring-basics.md index f432e4d43..ad84f17d7 100644 --- a/doc/3-monitoring-basics.md +++ b/doc/03-monitoring-basics.md @@ -1,4 +1,4 @@ -# Monitoring Basics +# Monitoring Basics This part of the Icinga 2 documentation provides an overview of all the basic monitoring concepts you need to know to run Icinga 2. @@ -6,7 +6,7 @@ Keep in mind these examples are made with a Linux server. If you are using Windows, you will need to change the services accordingly. See the [ITL reference](10-icinga-template-library.md#windows-plugins) for further information. -## Hosts and Services +## Hosts and Services 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: @@ -48,7 +48,7 @@ address is associated with the host object. Details on troubleshooting check problems can be found [here](15-troubleshooting.md#troubleshooting). -### Host States +### Host States Hosts can be in any of the following states: @@ -57,7 +57,7 @@ Hosts can be in any of the following states: UP | The host is available. DOWN | The host is unavailable. -### Service States +### Service States Services can be in any of the following states: @@ -68,7 +68,7 @@ Services can be in any of the following states: CRITICAL | The service is in a critical state. UNKNOWN | The check could not determine the service's state. -### Hard and Soft States +### Hard and Soft States 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 @@ -83,7 +83,7 @@ state the host/service switches to a `HARD` state and notifications are sent. HARD | The host/service's state hasn't recently changed. SOFT | The host/service has recently changed state and is being re-checked. -### Host and Service Checks +### Host and Service Checks Hosts and services determine their state by running checks in a regular interval. @@ -101,7 +101,7 @@ available. In addition to these commands the next few chapters will explain in detail how to set up your own check commands. -## Templates +## Templates Templates may be used to apply a set of identical attributes to more than one object: @@ -142,7 +142,7 @@ and objects share the same namespace, i.e. you can't define a template that has the same name like an object. -## Custom Attributes +## Custom Attributes In addition to built-in attributes you can define your own attributes: @@ -154,9 +154,9 @@ Valid values for custom attributes include: * [Strings](17-language-reference.md#string-literals), [numbers](17-language-reference.md#numeric-literals) and [booleans](17-language-reference.md#boolean-literals) * [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) -### Functions as Custom Attributes +### Functions as Custom Attributes Icinga 2 lets you specify [functions](17-language-reference.md#functions) for custom attributes. The special case here is that whenever Icinga 2 needs the value for such a custom attribute it runs @@ -218,9 +218,9 @@ command and arguments that should be executed via SSH: } Acessing object attributes at runtime inside these functions is described in the -[advanced topics](8-advanced-topics.md#access-object-attributes-at-runtime) chapter. +[advanced topics](08-advanced-topics.md#access-object-attributes-at-runtime) chapter. -## Runtime Macros +## Runtime Macros 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 @@ -264,7 +264,7 @@ exact rules for this are explained in the next section. > additional dollar character (`$$`). -### Evaluation Order +### Evaluation Order When executing commands Icinga 2 checks the following objects in this order to look up macros and their respective values: @@ -301,7 +301,7 @@ returns an empty value if the service does not have such a custom attribute no m whether another object such as the host has this attribute. -### Host Runtime Macros +### Host Runtime Macros The following host custom attributes are available in all commands that are executed for hosts or services: @@ -333,7 +333,7 @@ hosts or services: host.num_services_unknown | Number of services associated with the host which are in an `UNKNOWN` state. host.num_services_critical | Number of services associated with the host which are in a `CRITICAL` state. -### Service Runtime Macros +### Service Runtime Macros The following service macros are available in all commands that are executed for services: @@ -361,7 +361,7 @@ services: service.last_check | The timestamp when the last check was executed. service.check_source | The monitoring instance that performed the last check. -### Command Runtime Macros +### Command Runtime Macros The following custom attributes are available in all commands: @@ -369,7 +369,7 @@ The following custom attributes are available in all commands: -----------------------|-------------- command.name | The name of the command object. -### User Runtime Macros +### User Runtime Macros The following custom attributes are available in all commands that are executed for users: @@ -379,7 +379,7 @@ users: user.name | The name of the user object. user.display_name | The value of the display_name attribute. -### Notification Runtime Macros +### Notification Runtime Macros Name | Description -----------------------|-------------- @@ -387,7 +387,7 @@ users: notification.author | The author of the notification comment if existing. notification.comment | The comment of the notification if existing. -### Global Runtime Macros +### Global Runtime Macros The following macros are available in all executed commands: @@ -422,12 +422,12 @@ The following macros provide global statistics: icinga.num_hosts_acknowledged | Current number of acknowledged host problems. -## Apply Rules +## Apply Rules -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" { @@ -436,7 +436,7 @@ attribute and reference an existing host attribute. } This isn't comfortable when managing a huge set of configuration objects which could -[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**. @@ -449,36 +449,36 @@ instead of 1000 service objects. Apply rules will automatically generate them fo 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** > @@ -487,7 +487,7 @@ dictionaries](3-monitoring-basics.md#using-apply-for) provided by > after successful [configuration validation](11-cli-commands.md#config-validation). -### Apply Rules Expressions +### Apply Rules Expressions You can use simple or advanced combinations of apply rule expressions. Each expression must evaluate into the boolean `true` value. An empty string @@ -504,7 +504,7 @@ You can combine multiple expressions for matching only a subset of objects. In s you want to be able to add more than one assign/ignore where expression which matches a specific condition. To achieve this you can use the logical `and` and `or` operators. -#### Apply Rules Expressions Examples +#### Apply Rules Expressions Examples Assign a service to a specific host in a host group [array](18-library-reference.md#array-type) using the [in operator](17-language-reference.md#expression-operators): @@ -561,12 +561,12 @@ The notification is ignored for services whose host name ends with `*internal` ignore where match("*internal", host.name) || (service.vars.priority < 2 && host.vars.is_clustered == true) } -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). -### Apply Services to Hosts +### Apply Services to Hosts -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`. @@ -580,9 +580,9 @@ attribute being defined and the custom attribute `os` set to the string `Linux` } Other detailed examples are used in their respective chapters, for example -[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). -### Apply Notifications to Hosts and Services +### Apply Notifications to Hosts and Services Notifications are applied to specific targets (`Host` or `Service`) and work in a similar manner: @@ -647,25 +647,25 @@ The corresponding host object could look like this: vars.notification_type = "sms" } -### Apply Dependencies to Hosts and Services +### Apply Dependencies to Hosts and Services -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. -### Apply Recurring Downtimes to Hosts and Services +### Apply Recurring Downtimes to Hosts and Services -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. -### Using Apply For Rules +### Using Apply For Rules -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: @@ -710,7 +710,7 @@ That way you'll save duplicated apply rules by combining them into one generic `apply for` rule generating the object name with or without a prefix. -#### Apply For and Custom Attribute Override +#### Apply For and Custom Attribute Override Imagine a different more advanced example: You are monitoring your network device (host) with many interfaces (services). The following requirements/problems apply: @@ -722,12 +722,12 @@ 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" { @@ -840,7 +840,7 @@ The other way around you can override specific custom attributes inherited from This example makes use of the [check_iftraffic](https://exchange.icinga.com/exchange/iftraffic) plugin. 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** @@ -904,7 +904,7 @@ inherited custom attributes: * vlan = "mgmt" -### Use Object Attributes in Apply Rules +### Use Object Attributes in Apply Rules Since apply rules are evaluated after the generic objects, you can reference existing host and/or service object attributes as @@ -946,7 +946,7 @@ values for any object attribute specified in that apply rule. action_url = "http://snmp.checker.company.com/" + host.name + "/" + vars.customer_id } -## Groups +## Groups A group is a collection of similar objects. Groups are primarily used as a visualization aid in web interfaces. @@ -1000,7 +1000,7 @@ This can be done for service and user groups the same way: email = "ops@example.com" } -### Group Membership Assign +### Group Membership Assign Instead of manually assigning each object to a group you can also assign objects to a group based on their attributes: @@ -1021,7 +1021,7 @@ or with the `test_server` attribute set to `true` are **not** added to this grou Details on the `assign where` syntax can be found in the [Language Reference](17-language-reference.md#apply). -## Notifications +## Notifications Notifications for service and host problems are an integral part of your monitoring setup. @@ -1064,7 +1064,7 @@ You should choose which information you (and your notified users) are interested case of emergency, and also which information does not provide any value to you and 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 @@ -1103,7 +1103,7 @@ send notifications to all group members. **Note**: Only users who have been notified of a problem before (`Warning`, `Critical`, `Unknown` states for services, `Down` for hosts) will receive `Recovery` notifications. -### Notification Escalations +### Notification Escalations 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 @@ -1130,7 +1130,7 @@ notifications between start and end time. 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** > @@ -1198,7 +1198,7 @@ notified, but only for one hour (`2h` as `end` key for the `times` dictionary). assign where service.name == "ping4" } -### Notification Delay +### Notification Delay 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 @@ -1220,7 +1220,7 @@ specify a relatively low notification `interval` to get notified soon enough aga assign where service.name == "ping4" } -### Disable Re-notifications +### Disable Re-notifications If you prefer to be notified only once, you can disable re-notifications by setting the `interval` attribute to `0`. @@ -1236,7 +1236,7 @@ If you prefer to be notified only once, you can disable re-notifications by sett assign where service.name == "ping4" } -### Notification Filters by State and Type +### Notification Filters by State and Type 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. @@ -1255,19 +1255,19 @@ into type and state to allow more fine granular filtering for example on downtim You can filter for acknowledgements and custom notifications too. -## Commands +## Commands Icinga 2 uses three different command object types to specify how checks should be performed, notifications should be sent, and events should be handled. -### Check Commands +### Check Commands -[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** @@ -1275,10 +1275,10 @@ using the `check_command` attribute. > Make sure that the [checker](11-cli-commands.md#enable-features) feature is enabled in order to > execute checks. -#### Integrate the Plugin with a CheckCommand Definition +#### Integrate the Plugin with a CheckCommand Definition 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 @@ -1298,13 +1298,13 @@ partition defined (`-p`) it will check all local partitions. [-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. -#### Passing Check Command Parameters from Host or Service +#### Passing Check Command Parameters from Host or Service Check command parameters are defined as custom attributes which can be accessed as runtime macros by the executed check command. @@ -1313,13 +1313,13 @@ The check command parameters for ITL provided plugin check command definitions a [here](10-icinga-template-library.md#plugin-check-commands), for example [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** @@ -1373,7 +1373,7 @@ The check command definition also sets `mysql_host` to the `$address$` default v this command parameter if for example your MySQL host is not running on the same server's ip address. 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 @@ -1394,10 +1394,10 @@ in this example. } -Take a different example: The example host configuration in [hosts.conf](4-configuring-icinga-2.md#hosts-conf) +Take a different example: The example host configuration in [hosts.conf](04-configuring-icinga-2.md#hosts-conf) also applies an `ssh` service check. Your host's ssh port is not the default `22`, but set to `2022`. 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" @@ -1409,17 +1409,17 @@ inside [services.conf](4-configuring-icinga-2.md#services-conf): } If you prefer this being configured at the host instead of the service, modify the host configuration -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 } -#### Passing Check Command Parameters Using Apply For +#### Passing Check Command Parameters Using Apply For 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). @@ -1448,10 +1448,10 @@ string values for passing multiple partitions to the `check_disk` check plugin. More details on using arrays in custom attributes can be found in -[this chapter](3-monitoring-basics.md#custom-attributes). +[this chapter](03-monitoring-basics.md#custom-attributes). -#### Command Arguments +#### Command Arguments 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 @@ -1509,10 +1509,10 @@ That way you can use the `check_http` command definition for both, with and without SSL enabled checks saving you duplicated command definitions. 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). -#### Environment Variables +#### Environment Variables 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 @@ -1542,13 +1542,13 @@ when passing credentials to database checks: -### Notification Commands +### Notification Commands -[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** @@ -1581,13 +1581,13 @@ defaults can always be overwritten locally. > This example requires the `mail` binary installed on the Icinga 2 > master. -#### mail-host-notification +#### mail-host-notification 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 @@ -1607,13 +1607,13 @@ information. `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`. -#### mail-service-notification +#### mail-service-notification 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 @@ -1635,17 +1635,17 @@ information. `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`. -### Event Commands +### Event Commands 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 @@ -1654,7 +1654,7 @@ available through runtime variables. Runtime macros such as `$service.state_type and `$service.state$` will be processed by Icinga 2 and help with fine-granular 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). @@ -1664,12 +1664,12 @@ responding and therefore requires a restart. You can also use event handlers to forward more details on state changes and events than the typical notification alerts provide. -#### Use Event Commands to Send Information from the Master +#### Use Event Commands to Send Information from the Master 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" { @@ -1728,7 +1728,7 @@ Expected Result: businessprocess businessprocess CRITICAL SOFT 1 -#### Use Event Commands to Restart Service Daemon via Command Endpoint on Linux +#### Use Event Commands to Restart Service Daemon via Command Endpoint on Linux 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 @@ -1747,8 +1747,8 @@ Example on CentOS 7: 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 @@ -1833,7 +1833,7 @@ executed command line. [root@icinga2-client1.localdomain /]# tail -f /var/log/icinga2/debug.log | grep restart_service -#### Use Event Commands to Restart Service Daemon via Command Endpoint on Windows +#### Use Event Commands to Restart Service Daemon via Command Endpoint on Windows This example triggers a restart of the `httpd` service on the remote system when the `service-windows` service check executed via Command Endpoint fails. @@ -1845,8 +1845,8 @@ Requirements: * Icinga 2 as client on the remote node * Icinga 2 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 @@ -1922,7 +1922,7 @@ You can enable the [debug log](15-troubleshooting.md#troubleshooting-enable-debu executed command line in `C:\ProgramData\icinga2\var\log\icinga2\debug.log`. -#### Use Event Commands to Restart Service Daemon via SSH +#### Use Event Commands to Restart Service Daemon via SSH This example triggers a restart of the `httpd` daemon via SSH when the `http` service check fails. @@ -1941,7 +1941,7 @@ Example on Debian: # 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 @@ -2017,9 +2017,9 @@ executed command line. [root@icinga2-client1.localdomain /]# tail -f /var/log/icinga2/debug.log | grep by_ssh -## Dependencies +## Dependencies -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 @@ -2030,8 +2030,8 @@ account but all parents are inherited. 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" @@ -2059,7 +2059,7 @@ dependency will fail and render all child objects (hosts or services) unreachabl You can determine the child's reachability by querying the `is_reachable` attribute in for example [DB IDO](23-appendix.md#schema-db-ido-extensions). -### Implicit Dependencies for Services on Host +### Implicit Dependencies for Services on Host 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 @@ -2075,7 +2075,7 @@ and disabling the checks. `assign where true` matches on all `Service` objects. assign where true } -### Dependencies for Network Reachability +### Dependencies for Network Reachability 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 @@ -2121,9 +2121,9 @@ be suppressed. This is achieved by setting the `disable_checks` attribute to `tr assign where host.name != "dsl-router" } -### Apply Dependencies based on Custom Attributes +### Apply Dependencies based on Custom Attributes -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. @@ -2192,7 +2192,7 @@ will detect their reachability immediately when executing checks. > apply rules, but not in object definitions. -### Dependencies for Agent Checks +### Dependencies for Agent Checks 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 diff --git a/doc/4-configuring-icinga-2.md b/doc/04-configuring-icinga-2.md similarity index 77% rename from doc/4-configuring-icinga-2.md rename to doc/04-configuring-icinga-2.md index 069275c8f..e0e367f55 100644 --- a/doc/4-configuring-icinga-2.md +++ b/doc/04-configuring-icinga-2.md @@ -1,4 +1,4 @@ -# Configuring Icinga 2: First Steps +# Configuring Icinga 2: First Steps 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 @@ -7,7 +7,7 @@ are a good way to start with Icinga 2. The [Language Reference](17-language-reference.md#language-reference) chapter explains details on value types (string, number, dictionaries, etc.) and the general configuration syntax. -## Configuration Best Practice +## Configuration Best Practice If you are ready to configure additional hosts, services, notifications, dependencies, etc., you should think about the requirements first and then @@ -27,7 +27,7 @@ Find the best strategy for your own configuration and ask yourself the following * Only a small set of users receives notifications and escalations for all hosts/services? 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? @@ -36,7 +36,7 @@ host and service basis. 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: @@ -52,24 +52,24 @@ In either way of choosing the right strategy you should additionally check the f You can later use them for applying assign/ignore rules, or export them into external interfaces. * 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. -## Your Configuration +## Your Configuration If you prefer to organize your own local object tree, you can also remove `include_recursive "conf.d"` from your icinga2.conf file. @@ -86,12 +86,12 @@ in your icinga2.conf file. This approach is used by the [Icinga 2 Puppet module](https://github.com/Icinga/puppet-icinga2). -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. -## Configuration Overview +## Configuration Overview -### icinga2.conf +### icinga2.conf An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`. @@ -122,7 +122,7 @@ The `include` directive can be used to include other files. include "zones.conf" 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 @@ -167,10 +167,10 @@ the features which have been enabled with `icinga2 feature enable`. See This `include_recursive` directive is used for discovery of services on remote clients 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. @@ -181,16 +181,16 @@ 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. -### constants.conf +### constants.conf 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 @@ -221,58 +221,58 @@ Example: The `ZoneName` and `TicketSalt` constants are required for remote client and distributed setups only. -### zones.conf +### zones.conf -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. -### The conf.d Directory +### The conf.d Directory 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) +* [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 +#### hosts.conf 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. @@ -285,20 +285,20 @@ for check and notification commands. Most of the [Plugin Check Commands](10-icin in the Icinga Template Library require an `address` attribute. 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. @@ -355,15 +355,15 @@ 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. -#### services.conf +#### services.conf 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 @@ -409,7 +409,7 @@ attributes. 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" @@ -440,10 +440,10 @@ rules. While one `apply` rule for `ssh` will only create a service for matching hosts, you can go one step further: Generate apply rules based on array items 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`. */ @@ -462,7 +462,7 @@ parameter `disk_partition` to the check command. You'll recognize that the naming is important -- that's the very same name 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. @@ -494,21 +494,21 @@ A similar example is used for the `http` services. That way you can make your host the information provider for all apply rules. Define them once, and only 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. -#### users.conf +#### users.conf 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" @@ -524,7 +524,7 @@ Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is u } -#### notifications.conf +#### notifications.conf Notifications for check alerts are an integral part or your Icinga 2 monitoring stack. @@ -533,15 +533,15 @@ The examples in this file define two notification apply rules for hosts and serv Both `apply` rules match on the same condition: They are only applied if the 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" @@ -562,24 +562,24 @@ implicitely use the `icingaadmins` UserGroup defined in [users.conf](4-configuri } More details on defining notifications and their additional attributes such as -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). -#### commands.conf +#### commands.conf 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). -#### groups.conf +#### groups.conf 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" @@ -616,7 +616,7 @@ and the attribute string to match with. } -#### templates.conf +#### templates.conf Most of the example configuration objects use generic global templates by default: @@ -661,15 +661,15 @@ The `hostalive` check command is part of the 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). -#### downtimes.conf +#### downtimes.conf -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 { @@ -690,32 +690,32 @@ to define the default value for the time ranges required for recurring downtime } -#### timeperiods.conf +#### timeperiods.conf 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. -#### satellite.conf +#### satellite.conf 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. -#### api-users.conf +#### api-users.conf -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). -#### app.conf +#### app.conf -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. diff --git a/doc/5-service-monitoring.md b/doc/05-service-monitoring.md similarity index 84% rename from doc/5-service-monitoring.md rename to doc/05-service-monitoring.md index 1ca6f89b2..3fd2cc6af 100644 --- a/doc/5-service-monitoring.md +++ b/doc/05-service-monitoring.md @@ -1,18 +1,18 @@ -# Service Monitoring +# Service Monitoring 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). -## Requirements +## Requirements -### Plugins +### Plugins 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 @@ -42,11 +42,11 @@ the plugin it might be easier to create a symbolic link to make sure it doesn't Sometimes there are plugins which do not exactly fit your requirements. In that case you can modify an existing plugin or just write your own. -### CheckCommand Definition +### CheckCommand Definition -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). @@ -55,12 +55,12 @@ into your host and service objects. 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: @@ -90,16 +90,16 @@ This is an example for a custom `my-snmp-int` check command: For further information on your monitoring configuration read the -[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/). -### Plugin API +### Plugin API 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). -### Create a new Plugin +### Create a new Plugin Sometimes an existing plugin does not satisfy your requirements. You can either kindly contact the original author about plans to add changes @@ -122,7 +122,7 @@ Common best practices when creating a new plugin are for example: * Add parameters with key-value pairs to your plugin. They should allow long names (e.g. `--host localhost`) and also short parameters (e.g. `-H localhost`) * `-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: @@ -162,13 +162,13 @@ with plugin execution and output formatting too, for example Once you've finished your plugin please upload/sync it to [Icinga Exchange](https://exchange.icinga.com/new). Thanks in advance! -## Service Monitoring Overview +## Service Monitoring Overview 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. -### General Monitoring +### General Monitoring 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. @@ -179,7 +179,7 @@ Instead, choose a plugin and configure its parameters and thresholds. The follow * [tcp](10-icinga-template-library.md#plugin-check-command-tcp), [udp](10-icinga-template-library.md#plugin-check-command-udp), [ssl](10-icinga-template-library.md#plugin-check-command-ssl) * [ntp_time](10-icinga-template-library.md#plugin-check-command-ntp-time) -### Linux Monitoring +### Linux Monitoring * [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) @@ -190,14 +190,14 @@ Instead, choose a plugin and configure its parameters and thresholds. The follow * [ssh](10-icinga-template-library.md#plugin-check-command-ssh) * 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) -### Windows Monitoring +### Windows Monitoring * [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 -### Database Monitoring +### Database Monitoring * 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) @@ -208,19 +208,19 @@ Instead, choose a plugin and configure its parameters and thresholds. The follow * Elasticsearch: [elasticsearch](10-icinga-template-library.md#plugin-contrib-command-elasticsearch) * Redis: [redis](10-icinga-template-library.md#plugin-contrib-command-redis) -### SNMP Monitoring +### SNMP Monitoring * [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) -### Network Monitoring +### Network Monitoring * [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) -### Web Monitoring +### Web Monitoring * [http](10-icinga-template-library.md#plugin-check-command-http) * [ftp](10-icinga-template-library.md#plugin-check-command-ftp) @@ -231,29 +231,29 @@ Instead, choose a plugin and configure its parameters and thresholds. The follow * [kdc](10-icinga-template-library.md#plugin-contrib-command-kdc) * [rbl](10-icinga-template-library.md#plugin-contrib-command-rbl) -### Java Monitoring +### Java Monitoring * [jmx4perl](10-icinga-template-library.md#plugin-contrib-command-jmx4perl) -### DNS Monitoring +### DNS Monitoring * [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) -### Backup Monitoring +### Backup Monitoring * [check_bareos](https://github.com/widhalmt/check_bareos) -### Log Monitoring +### Log Monitoring * [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) -### Virtualization Monitoring +### Virtualization Monitoring -### VMware Monitoring +### VMware Monitoring * [esxi_hardware](10-icinga-template-library.md#plugin-contrib-command-esxi-hardware) * [VMware](10-icinga-template-library.md#plugin-contrib-vmware) @@ -261,23 +261,23 @@ Instead, choose a plugin and configure its parameters and thresholds. The follow **Tip**: If you are encountering timeouts using the VMware Perl SDK, check [this blog entry](https://www.claudiokuenzler.com/blog/650/slow-vmware-perl-sdk-soap-request-error-libwww-version). -### SAP Monitoring +### SAP Monitoring * [check_sap_health](https://labs.consol.de/nagios/check_sap_health/index.html) * [SAP CCMS](https://sourceforge.net/projects/nagios-sap-ccms/) -### Mail Monitoring +### Mail Monitoring * [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) -### Hardware Monitoring +### Hardware Monitoring * [hpasm](10-icinga-template-library.md#plugin-contrib-command-hpasm) * [ipmi-sensor](10-icinga-template-library.md#plugin-contrib-command-ipmi-sensor) -### Metrics Monitoring +### Metrics Monitoring * [graphite](10-icinga-template-library.md#plugin-contrib-command-graphite) diff --git a/doc/6-distributed-monitoring.md b/doc/06-distributed-monitoring.md similarity index 87% rename from doc/6-distributed-monitoring.md rename to doc/06-distributed-monitoring.md index a758d8aca..c181f405c 100644 --- a/doc/6-distributed-monitoring.md +++ b/doc/06-distributed-monitoring.md @@ -1,10 +1,10 @@ -# Distributed Monitoring with Master, Satellites, and Clients +# Distributed Monitoring with Master, Satellites, and Clients 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. -## Roles: Master, Satellites, and Clients +## Roles: Master, Satellites, and Clients Icinga 2 nodes can be given names for easier understanding: @@ -36,16 +36,16 @@ In case you are planning a huge cluster setup with multiple levels and lots of clients, read on -- we'll deal with these cases later on. 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. -## Zones +## Zones -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. ![Icinga 2 Distributed Zones](images/distributed-monitoring/icinga2_distributed_zones.png) @@ -70,14 +70,14 @@ There are certain limitations for child zones, e.g. their members are not allowe to send configuration commands to the parent zone members. Vice versa, the 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. -## Endpoints +## Endpoints -Nodes which are a member of a zone are so-called [Endpoint](9-object-types.md#objecttype-endpoint) objects. +Nodes which are a member of a zone are so-called [Endpoint](09-object-types.md#objecttype-endpoint) objects. ![Icinga 2 Distributed Endpoints](images/distributed-monitoring/icinga2_distributed_endpoints.png) @@ -110,13 +110,13 @@ The zone membership is defined inside the `Zone` object definition using 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. -## ApiListener +## ApiListener 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. @@ -131,7 +131,7 @@ In order to use the `api` feature you need to enable it and restart Icinga 2. icinga2 feature enable api -## Conventions +## Conventions By convention all nodes should be configured using their FQDN. @@ -146,7 +146,7 @@ Setting this up on the command line will help you to minimize the effort. Just keep in mind that you need to use the FQDN for endpoints and for common names when asked. -## Security +## Security While there are certain mechanisms to ensure a secure communication between all nodes (firewalls, policies, software hardening, etc.), Icinga 2 also provides @@ -158,20 +158,20 @@ help you create those certificates. * Child zones are not allowed to push configuration updates to parent zones. * 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. -## Master Setup +## Master Setup 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. @@ -236,24 +236,24 @@ Here is an example of a master setup for the `icinga2-master1.localdomain` node [root@icinga2-master1.localdomain /]# systemctl restart icinga2 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. -## Client/Satellite Setup +## Client/Satellite Setup 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`. -### CSR Auto-Signing +### CSR Auto-Signing 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 @@ -261,7 +261,7 @@ master node. 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: @@ -301,14 +301,14 @@ Store that ticket number for the satellite/client setup below. **Note**: Never expose the ticket salt and/or ApiUser credentials to your client nodes. 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). -### Client/Satellite Linux Setup +### Client/Satellite Linux Setup -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 @@ -324,11 +324,11 @@ ensure to collect the required information: Add more master endpoints | **Optional.** If you have multiple master nodes configured, add them here. 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: @@ -410,9 +410,9 @@ is configured to accept configuration and commands from the master: As you can see, the certificate files are stored in the `/etc/icinga2/pki` directory. 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). -### Client/Satellite Windows Setup +### Client/Satellite Windows Setup Download the MSI-Installer package from [https://packages.icinga.com/windows/](https://packages.icinga.com/windows/). @@ -423,12 +423,12 @@ Requirements: The installer package includes the [NSClient++](https://www.nsclient.org/) package 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. -#### Windows Client Setup Start +#### Windows Client Setup Start Run the MSI-Installer package and follow the instructions shown in the screenshots. @@ -447,7 +447,7 @@ You'll need the following configuration details: Parameter | Description --------------------|-------------------- 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. @@ -467,9 +467,9 @@ Optionally, you can enable the following settings: 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). ![Icinga 2 Windows Setup](images/distributed-monitoring/icinga2_windows_setup_wizard_03.png) @@ -477,7 +477,7 @@ The next step allows you to verify the CA presented by the master. ![Icinga 2 Windows Setup](images/distributed-monitoring/icinga2_windows_setup_wizard_04.png) -#### Bundled NSClient++ Setup +#### Bundled NSClient++ Setup If you have chosen to install/update the NSClient++ package, the Icinga 2 setup wizard will ask you to do so. @@ -514,7 +514,7 @@ configuration file. The NSClient++ REST API can be used to query metrics. Future Icinga 2 versions will add 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/). -#### Finish Windows Client Setup +#### Finish Windows Client Setup Finish the setup wizard. @@ -531,10 +531,10 @@ If you click `Examine Config` in the setup wizard, it will open a new Explorer w The configuration files can be modified with your favorite editor. -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: @@ -569,27 +569,27 @@ and restart the `icinga2` service. Alternatively, you can use the `net {start,st ![Icinga 2 Windows Service Start/Stop](images/distributed-monitoring/icinga2_windows_cmd_admin_net_start_stop.png) 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). -## Configuration Modes +## Configuration Modes 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. -### Top Down +### Top Down According to feedback that we've received from the community, this is the most commonly used mode. @@ -601,7 +601,7 @@ There are two different behaviors with check execution: Again, technically it does not matter whether this is a `client` or a `satellite` which is receiving configuration or command execution events. -### Top Down Command Endpoint +### Top Down Command Endpoint This mode will force the Icinga 2 node to execute commands remotely on a specified endpoint. The host/service object configuration is located on the master/satellite and the client only @@ -613,14 +613,14 @@ Advantages: * 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 @@ -662,7 +662,7 @@ The `master` zone is a parent of the `icinga2-client1.localdomain` zone: 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 @@ -772,11 +772,11 @@ The following steps will happen: As you can see, no interaction from your side is required on the client itself, and it's not necessary to reload the Icinga 2 service on the client. 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. -### Top Down Config Sync +### Top Down Config Sync This mode syncs the object configuration files within specified zones. It comes in handy if you want to configure everything on the master node @@ -862,7 +862,7 @@ Example on CentOS 7: [root@icinga2-master1.localdomain /]# systemctl restart icinga2 -**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 @@ -929,16 +929,16 @@ Multiple nodes with configuration files in the `zones.d` directory are **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. -### Bottom Up Import +### Bottom Up Import > **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). @@ -996,7 +996,7 @@ If you have accidentally added specific hosts or services, you can safely purge them from this directory and restart Icinga 2. 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` @@ -1027,10 +1027,10 @@ and fix it. This will help with additional notification apply rules or group memberships required for Icinga Web 2 and addons. -#### Bottom Up Migration to Top Down +#### Bottom Up Migration to Top Down 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 @@ -1046,7 +1046,7 @@ directory and generates the `repository.d` configuration files. In addition to 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** @@ -1054,7 +1054,7 @@ configuration file. **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 @@ -1099,7 +1099,7 @@ Example on CentOS 7: **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. @@ -1162,7 +1162,7 @@ client connection check `cluster-zone`, you need to add the `cluster_zone` custo In addition to that add a new custom attribute called `client_endpoint` which stores 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 @@ -1181,7 +1181,7 @@ Extract the service objects from the configuration files in the and add them into the `/etc/icinga2/zones.d/master/icinga2-client3.localdomain.conf` 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. @@ -1255,7 +1255,7 @@ adopt and merge them accordingly. If you are eager to start fresh instead you might take a look into the [Icinga Director](https://github.com/icinga/icingaweb2-module-director). -## Scenarios +## Scenarios The following examples should give you an idea on how to build your own distributed monitoring environment. We've seen them all in production @@ -1266,7 +1266,7 @@ and [partner support](https://www.icinga.com/services/support/) channels: * HA master with clients as command endpoint. * Three level cluster with config HA masters, satellites receiving config sync, and clients checked using command endpoint. -### Master with Clients +### Master with Clients ![Icinga 2 Distributed Master with Clients](images/distributed-monitoring/icinga2_distributed_scenarios_master_clients.png) @@ -1275,8 +1275,8 @@ and [partner support](https://www.icinga.com/services/support/) channels: Setup requirements: -* 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: @@ -1320,7 +1320,7 @@ is that they know about the parent zone and their endpoint members (and optional If you specify the `host` attribute in the `icinga2-master1.localdomain` endpoint object, 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 @@ -1422,11 +1422,11 @@ Validate the configuration and restart Icinga 2 on the master node `icinga2-mast Open Icinga Web 2 and check the two newly created client hosts with two new services -- one executed locally (`ping4`) and one using command endpoint (`disk`). -### High-Availability Master with Clients +### High-Availability Master with Clients ![Icinga 2 Distributed High Availability Master with Clients](images/distributed-monitoring/icinga2_distributed_scenarios_ha_master_clients.png) -This scenario is similar to the one in the [previous section](6-distributed-monitoring.md#distributed-monitoring-master-clients). The only difference is that we will now set up two master nodes in a high-availablity setup. +This scenario is similar to the one in the [previous section](06-distributed-monitoring.md#distributed-monitoring-master-clients). The only difference is that we will now set up two master nodes in a high-availablity setup. These nodes must be configured as zone and endpoints objects. The setup uses the capabilities of the Icinga 2 cluster. All zone members @@ -1443,15 +1443,15 @@ Overview: 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. @@ -1510,7 +1510,7 @@ is that they know about the parent zone and their endpoint members (and optional If you specify the `host` attribute in the `icinga2-master1.localdomain` and `icinga2-master2.localdomain` 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 @@ -1574,7 +1574,7 @@ config sync mode here. 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 @@ -1622,11 +1622,11 @@ Validate the configuration and restart Icinga 2 on the master node `icinga2-mast Open Icinga Web 2 and check the two newly created client hosts with two new services -- 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. -### Three Levels with Master, Satellites, and Clients +### Three Levels with Master, Satellites, and Clients ![Icinga 2 Distributed Master and Satellites with Clients](images/distributed-monitoring/icinga2_distributed_scenarios_master_satellite_client.png) @@ -1646,9 +1646,9 @@ Overview: Setup requirements: -* 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. @@ -1683,7 +1683,7 @@ Specify the master node `icinga2-master2.localdomain` with the CA private key an 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. @@ -1691,7 +1691,7 @@ We'll discuss the details of the required configuration below. The zone hierarchy can look like this. We'll define only the directly connected zones here. 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 @@ -1730,7 +1730,7 @@ using the `host` attribute. 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. @@ -1768,7 +1768,7 @@ is that they know about the parent zone (the satellite) and their endpoint membe If you specify the `host` attribute in the `icinga2-satellite1.localdomain` and `icinga2-satellite2.localdomain` 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`: @@ -1894,15 +1894,15 @@ Validate the configuration and restart Icinga 2 on the master node `icinga2-mast Open Icinga Web 2 and check the two newly created client hosts with two new services -- 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. -## Best Practice +## Best Practice 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/)! -### Global Zone for Config Sync +### Global Zone for Config Sync Global zones can be used to sync generic configuration objects to all nodes depending on them. Common examples are: @@ -1959,7 +1959,7 @@ Example: [root@icinga2-master1.localdomain /]# cd /etc/icinga2/conf.d [root@icinga2-master1.localdomain /etc/icinga2/conf.d]# cp {commands,downtimes,groups,notifications,templates,timeperiods,users}.conf /etc/icinga2/zones.d/global-templates -### Health Checks +### Health Checks In case of network failures or other problems, your monitoring might either have late check results or just send out mass alarms for unknown @@ -1990,7 +1990,7 @@ connected zones are working properly: } The `cluster-zone` check will test whether the configured target zone is currently -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 @@ -2035,7 +2035,7 @@ add a dependency which prevents notifications for all other failing services: ignore where service.name == "child-health" } -### Pin Checks in a Zone +### Pin Checks in a Zone 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 @@ -2064,7 +2064,7 @@ the service object is only created for host objects inside the `master` zone. In addition to that the [match](18-library-reference.md#global-functions-match) function ensures to only create services for the master nodes. -### Windows Firewall +### Windows Firewall 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). @@ -2077,7 +2077,7 @@ you'll also need to ensure that port `5665` is enabled. C:\WINDOWS\system32>netsh advfirewall firewall add rule name="Open port 5665 (Icinga 2)" dir=in action=allow protocol=TCP localport=5665 -### Windows Client and Plugins +### Windows Client and Plugins The Icinga 2 package on Windows already provides several plugins. Detailed [documentation](10-icinga-template-library.md#windows-plugins) is available for all check command definitions. @@ -2088,7 +2088,7 @@ Add the following `include` statement on all your nodes (master, satellite, clie include -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: @@ -2128,30 +2128,30 @@ Open Icinga Web 2 and check your newly added Windows disk check :) ![Icinga 2 Client Windows](images/distributed-monitoring/icinga2_distributed_windows_client_disk_icingaweb2.png) -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. -### Windows Client and NSClient++ +### Windows Client and NSClient++ There are two methods available for querying NSClient++: -* Query the [HTTP API](6-distributed-monitoring.md#distributed-monitoring-windows-nscp-check-api) locally or remotely (requires a running NSClient++ service) -* 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. -#### NSCLient++ with check_nscp_api +#### NSCLient++ with check_nscp_api -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` @@ -2169,7 +2169,7 @@ custom attribute and specify the drives to check. 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 @@ -2210,9 +2210,9 @@ which defaults to `host.address`. You can verify the check execution by looking at the `Check Source` attribute in Icinga Web 2 or the REST API. -#### NSCLient++ with nscp-local +#### NSCLient++ with nscp-local -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). @@ -2228,7 +2228,7 @@ Add the following `include` statement on all your nodes (master, satellite, clie The CheckCommand definitions will automatically determine the installed path 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: @@ -2271,22 +2271,22 @@ Open Icinga Web 2 and check your newly added Windows NSClient++ check :) ![Icinga 2 Distributed Monitoring Windows Client with NSClient++ nscp-local](images/distributed-monitoring/icinga2_distributed_windows_nscp_counter_icingaweb2.png) -## Advanced Hints +## Advanced Hints You can find additional hints in this section if you prefer to go your own route with automating setups (setup, certificates, configuration). -### High-Availability for Icinga 2 Features +### High-Availability for Icinga 2 Features 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). -#### High-Availability with Checks +#### High-Availability with Checks All instances within the same zone (e.g. the `master` zone as HA cluster) must have the `checker` feature enabled. @@ -2298,7 +2298,7 @@ Example: All nodes in the same zone load-balance the check execution. If one instance shuts down, the other nodes will automatically take over the remaining checks. -#### High-Availability with Notifications +#### High-Availability with Notifications All instances within the same zone (e.g. the `master` zone as HA cluster) must have the `notification` feature enabled. @@ -2311,9 +2311,9 @@ Notifications are load-balanced amongst all nodes in a zone. By default this fun is enabled. 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. -#### High-Availability with DB IDO +#### High-Availability with DB IDO All instances within the same zone (e.g. the `master` zone as HA cluster) must have the DB IDO feature enabled. @@ -2327,8 +2327,8 @@ the active IDO database connection at runtime. The node with the active DB IDO c not necessarily the zone master. **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 @@ -2351,9 +2351,9 @@ This is useful when the cluster connection between endpoints breaks, and prevent data duplication in split-brain-scenarios. The failover timeout can be set for the `failover_timeout` attribute, but not lower than 60 seconds. -### Endpoint Connection Direction +### Endpoint Connection Direction -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 @@ -2388,17 +2388,17 @@ and close the second connection if established. or vice versa. -### Disable Log Duration for Command Endpoints +### Disable Log Duration for Command Endpoints 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. @@ -2434,7 +2434,7 @@ Configuration on the client `icinga2-client1.localdomain`: log_duration = 0 } -### CSR auto-signing with HA and multiple Level Cluster +### CSR auto-signing with HA and multiple Level Cluster 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 @@ -2443,14 +2443,14 @@ details in private: * `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.** -### Manual Certificate Creation +### Manual Certificate Creation Choose the host which should store the certificate authority (one of the master nodes). @@ -2500,22 +2500,22 @@ Example for creating multiple certificates at once: information/pki: Writing certificate to file 'icinga2-satellite1.localdomain.crt'. -## Automation +## Automation 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/). -### Silent Windows Setup +### Silent Windows Setup 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. @@ -2524,7 +2524,7 @@ installation should not trigger a restart, but if you want to be completly sure, Once the setup is completed you can use the `node setup` cli command too. -### Node Setup using CLI Parameters +### Node Setup using CLI Parameters Instead of using the `node wizard` CLI command, there is an alternative `node setup` command available which has some prerequisites. @@ -2532,7 +2532,7 @@ command available which has some prerequisites. **Note**: The CLI command can be used on Linux/Unix and Windows operating systems. The graphical Windows setup wizard actively uses these CLI commands. -#### Node Setup on the Master Node +#### Node Setup on the Master Node 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 @@ -2553,7 +2553,7 @@ host/port you can specify it like this: --listen 192.68.56.101,5665 -#### Node Setup with Satellites/Clients +#### Node Setup with Satellites/Clients Make sure that the `/etc/icinga2/pki` exists and is owned by the `icinga` user (or the user Icinga 2 is running as). @@ -2602,13 +2602,13 @@ Pass the following details to the `node setup` CLI command: Parameter | Description --------------------|-------------------- 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: @@ -2641,12 +2641,12 @@ Add an additional global zone. Please note the `>>` append mode. 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 diff --git a/doc/7-agent-based-monitoring.md b/doc/07-agent-based-monitoring.md similarity index 92% rename from doc/7-agent-based-monitoring.md rename to doc/07-agent-based-monitoring.md index 6027bc8d3..a79feba47 100644 --- a/doc/7-agent-based-monitoring.md +++ b/doc/07-agent-based-monitoring.md @@ -1,14 +1,14 @@ -# Additional Agent-based Checks +# Additional Agent-based Checks If the remote services are not directly accessible through the network, a local agent installation exposing the results to check queries can become handy. -## SNMP +## SNMP 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 @@ -31,11 +31,11 @@ If no `snmp_miblist` is specified, the plugin will default to `ALL`. As the numb on the system increases so will the load generated by this plugin if no `MIB` is specified. As such, it is recommended to always specify at least one `MIB`. -## SSH +## SSH 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" @@ -55,7 +55,7 @@ requires the `check_by_ssh` check plugin which is available in the [Monitoring P vars.by_ssh_logname = "icinga" } -## NSClient++ +## NSClient++ [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, @@ -82,7 +82,7 @@ Example: For details on the `NSClient++` configuration please refer to the [official documentation](https://docs.nsclient.org/). -## NSCA-NG +## NSCA-NG [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` @@ -93,7 +93,7 @@ feature. > 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. -## NRPE +## NRPE [NRPE](https://docs.icinga.com/latest/en/nrpe.html) runs as daemon on the remote client including the required plugins and command definitions. @@ -105,7 +105,7 @@ remote client. > 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` @@ -171,11 +171,11 @@ executed by the NRPE daemon looks similar to that: /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. -## Passive Check Results and SNMP Traps +## Passive Check Results and SNMP Traps 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. @@ -184,7 +184,7 @@ Following the SNMPTT [Format](http://snmptt.sourceforge.net/docs/snmptt.shtml#SN documentation and the Icinga external command syntax found [here](23-appendix.md#external-commands-list-detail) we can create generic services that can accommodate any number of hosts for a given scenario. -### Simple SNMP Traps +### Simple SNMP Traps 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. @@ -310,7 +310,7 @@ Finally create the `Service` and assign it: assign where (host.vars.os == "Linux" || host.vars.os == "Windows") } -### Complex SNMP Traps +### Complex SNMP Traps 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 diff --git a/doc/8-advanced-topics.md b/doc/08-advanced-topics.md similarity index 90% rename from doc/8-advanced-topics.md rename to doc/08-advanced-topics.md index fbd9f89eb..3d559d91e 100644 --- a/doc/8-advanced-topics.md +++ b/doc/08-advanced-topics.md @@ -1,9 +1,9 @@ -# Advanced Topics +# Advanced Topics 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. -## Downtimes +## Downtimes Downtimes can be scheduled for planned server maintenance or any other targeted service outage you are aware of in advance. @@ -24,7 +24,7 @@ If the downtime was scheduled after the problem changed to a critical hard state triggering a problem notification, and the service recovers during the downtime window, the recovery notification won't be suppressed. -### Fixed and Flexible Downtimes +### Fixed and Flexible Downtimes A `fixed` downtime will be activated at the defined start time, and removed at the end time. During this time window the service state @@ -51,14 +51,14 @@ For that reason, you may want to schedule a downtime between 07:30 and its trigger time until the duration is over. After that, the downtime is removed (may happen before or after the actual end time!). -### Scheduling a downtime +### Scheduling a downtime 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). -#### Fixed Downtime +#### Fixed Downtime 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 @@ -70,7 +70,7 @@ start | end trigger time ``` -#### Flexible Downtime +#### Flexible Downtime 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 @@ -87,7 +87,7 @@ start | end actual end time ``` -### Triggered Downtimes +### Triggered Downtimes 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 @@ -95,9 +95,9 @@ that downtime. This renders useful if you have scheduled a host downtime and are now scheduling a child host's downtime getting triggered by the parent downtime on `NOT-OK` state change. -### Recurring Downtimes +### Recurring Downtimes -[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: @@ -120,7 +120,7 @@ Example: } -## Comments +## Comments Comments can be added at runtime and are persistent over restarts. You can add useful information for others on repeating incidents (for example @@ -131,14 +131,14 @@ You can add a comment either by using the Icinga 2 API action [add-comment](12-icinga2-api.md#icinga2-api-actions-add-comment) or by sending an [external command](14-features.md#external-commands). -## Acknowledgements +## Acknowledgements 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 @@ -146,7 +146,7 @@ You can send an acknowledgement either by using the Icinga 2 API action by sending an [external command](14-features.md#external-commands). -### Sticky Acknowledgements +### Sticky Acknowledgements The acknowledgement is removed if a state change occurs or if the host/service recovers (OK/Up state). @@ -161,7 +161,7 @@ If you prefer to keep the acknowledgement until the problem is resolved (`OK` recovery) you need to enable the `sticky` parameter. -### Expiring Acknowledgements +### Expiring Acknowledgements 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 @@ -175,9 +175,9 @@ Icinga 2 will clear the acknowledgement when expired and start to re-notify, if the problem persists. -## Time Periods +## Time Periods -[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 @@ -282,14 +282,14 @@ to assign time periods to `Notification` and `Dependency` objects: period = "workhours" } -### Time Periods Inclusion and Exclusion +### Time Periods Inclusion and Exclusion 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. @@ -343,7 +343,7 @@ and adds the excluded time period names as an array. } } -## Check Result Freshness +## Check Result Freshness 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. @@ -358,7 +358,7 @@ If the freshness checks are invalid, a new check is executed defined by the `check_command` attribute. -## Check Flapping +## Check Flapping Icinga 2 supports optional detection of hosts and services that are "flapping". @@ -369,12 +369,12 @@ or real network problems. Flapping detection can be enabled or disabled using the `enable_flapping` attribute. 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. -## Volatile Services +## Volatile Services By default all services remain in a non-volatile state. When a problem occurs, the `SOFT` state applies and once `max_check_attempts` attribute @@ -387,7 +387,7 @@ state type if the service stays in a `NOT-OK` state. That way each service recheck will automatically trigger a notification unless the service is acknowledged or in a scheduled downtime. -## Monitoring Icinga 2 +## Monitoring Icinga 2 Why should you do that? Icinga and its components run like any other service application on your server. There are predictable issues @@ -417,7 +417,7 @@ System | Logs | Forward them to [Elastic Stack](14-features.md#elastic-stack System | NTP | [ntp_time](10-icinga-template-library.md#plugin-check-command-ntp-time) System | 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. @@ -438,7 +438,7 @@ Metrics | Graylog | [Graylog integration](14-features.md#graylog-integration) The [icinga](10-icinga-template-library.md#itl-icinga) CheckCommand provides metrics for the runtime stats of 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 @@ -457,17 +457,17 @@ apply Service "ido-mysql" { More specific database queries can be found in the [DB IDO](14-features.md#db-ido) chapter. -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. -## Advanced Configuration Hints +## Advanced Configuration Hints -### Advanced Use of Apply Rules +### Advanced Use of Apply Rules -[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 @@ -546,13 +546,13 @@ service checks in this example. 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. -### Use Functions in Object Configuration +### Use Functions in Object Configuration 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. @@ -560,7 +560,7 @@ The other way around you can create objects dynamically using your own global fu > > Functions called inside command objects share the same global scope as runtime macros. > 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: @@ -569,10 +569,10 @@ inside the `icinga2.log` file depending in your log severity * Use the `icinga2 console` to test basic functionality (e.g. iterating over a dictionary) * Build them step-by-step. You can always refactor your code later on. -#### Use Functions in Command Arguments set_if +#### Use Functions in Command Arguments set_if 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 @@ -648,10 +648,10 @@ The more programmatic approach for `set_if` could look like this: } -#### Use Functions as Command Attribute +#### Use Functions as Command Attribute -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 @@ -702,7 +702,7 @@ You can omit the `log()` calls, they only help debugging. } } -#### Use Custom Functions as Attribute +#### Use Custom Functions as Attribute To use custom functions as attributes, the function must be defined in a slightly unexpected way. The following example shows how to assign values @@ -729,14 +729,14 @@ as value for `ping_wrta`, all other hosts use 100. assign where true } -#### Use Functions in Assign Where Expressions +#### Use Functions in Assign Where Expressions 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 @@ -818,13 +818,13 @@ with the `vars_app` dictionary. assign where check_app_type(host, "ABAP") } -### Access Object Attributes at Runtime +### Access Object Attributes at Runtime 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: diff --git a/doc/9-object-types.md b/doc/09-object-types.md similarity index 93% rename from doc/9-object-types.md rename to doc/09-object-types.md index 0f4559d55..78b59192c 100644 --- a/doc/9-object-types.md +++ b/doc/09-object-types.md @@ -1,4 +1,4 @@ -# Config Object Types +# Config Object Types This chapter provides an overview of all available config object types which can be instantiated using the `object` keyword. @@ -16,18 +16,18 @@ the [Icinga 2 API](12-icinga2-api.md#icinga2-api-config-objects). 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`. -## ApiListener +## ApiListener 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: @@ -53,7 +53,7 @@ Configuration Attributes: 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`. -## ApiUser +## ApiUser ApiUser objects are used for authentication against the Icinga 2 API. @@ -76,7 +76,7 @@ Configuration Attributes: Available permissions are described in the [API permissions](12-icinga2-api.md#icinga2-api-permissions) chapter. -## CheckCommand +## CheckCommand A check command definition. Additional default command custom attributes can be defined here. @@ -132,7 +132,7 @@ Configuration Attributes: arguments |**Optional.** A dictionary of command arguments. -### CheckCommand Arguments +### CheckCommand Arguments Command arguments can be defined as key-value-pairs in the `arguments` dictionary. If the argument requires additional configuration, for example @@ -191,7 +191,7 @@ Argument array `repeat_key = false`: `'key' 'value[0]' 'value[1]' 'value[2]'` -## CheckerComponent +## CheckerComponent The checker component is responsible for scheduling active checks. @@ -209,7 +209,7 @@ Configuration Attributes: --------------------|---------------- concurrent\_checks |**Optional.** The maximum number of concurrent checks. Defaults to 512. -## CheckResultReader +## CheckResultReader 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 @@ -229,7 +229,7 @@ Configuration Attributes: ----------------|---------------- spool\_dir |**Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/". -## Comment +## Comment Comments created at runtime are represented as objects. @@ -254,7 +254,7 @@ Configuration Attributes: expire_time | **Optional.** The comment's expire time as unix timestamp. persistent | **Optional.** Only evaluated for `entry_type` Acknowledgement. `true` does not remove the comment when the acknowledgement is removed. -## CompatLogger +## CompatLogger Writes log files in a format that's compatible with Icinga 1.x. @@ -276,7 +276,7 @@ Configuration Attributes: -## Dependency +## Dependency 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 @@ -288,7 +288,7 @@ relations. > 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: @@ -339,7 +339,7 @@ Available state filters: 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: @@ -372,7 +372,7 @@ Dependency objects have composite names, i.e. their names are based on the `chil name you specified. This means you can define more than one object with the same (short) name as long as one of the `child_host_name` and `child_service_name` attributes has a different value. -## Downtime +## Downtime Downtimes created at runtime are represented as objects. @@ -396,7 +396,7 @@ Configuration Attributes: 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: @@ -408,7 +408,7 @@ Runtime Attributes: -## Endpoint +## Endpoint Endpoint objects are used to specify connection information for remote Icinga 2 instances. @@ -439,7 +439,7 @@ Configuration Attributes: Endpoint objects cannot currently be created with the API. -## EventCommand +## EventCommand An event command definition. @@ -465,11 +465,11 @@ Configuration Attributes: 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). -## ExternalCommandListener +## ExternalCommandListener Implements the Icinga 1.x command pipe which can be used to send commands to Icinga. @@ -489,7 +489,7 @@ Configuration Attributes: -## FileLogger +## FileLogger Specifies Icinga 2 logging to a file. @@ -508,7 +508,7 @@ Configuration Attributes: severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information". -## GelfWriter +## GelfWriter Writes event log entries to a defined GELF receiver host (Graylog2, Logstash). @@ -531,7 +531,7 @@ Configuration Attributes: enable_send_perfdata |**Optional.** Enable performance data for 'CHECK RESULT' events. -## GraphiteWriter +## GraphiteWriter Writes check result metrics and performance data to a defined Graphite Carbon host. @@ -561,7 +561,7 @@ Additional usage examples can be found [here](14-features.md#graphite-carbon-cac -## Host +## Host A host. @@ -644,7 +644,7 @@ Runtime Attributes: -## HostGroup +## HostGroup A group of hosts. @@ -665,7 +665,7 @@ Configuration Attributes: display_name |**Optional.** A short description of the host group. groups |**Optional.** An array of nested group names. -## IcingaApplication +## IcingaApplication The IcingaApplication object is required to start Icinga 2. The object name must be `app`. If the object configuration @@ -690,7 +690,7 @@ Configuration Attributes: enable_perfdata |**Optional.** Whether performance data processing is globally enabled. Defaults to true. vars |**Optional.** A dictionary containing custom attributes that are available globally. -## IdoMySqlConnection +## IdoMySqlConnection IDO database adapter for MySQL. @@ -730,8 +730,8 @@ Configuration Attributes: 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. @@ -780,7 +780,7 @@ by Icinga Web 2 in the table above. In addition to the category flags listed above the `DbCatEverything` flag may be used as a shortcut for listing all flags. -## IdoPgSqlConnection +## IdoPgSqlConnection IDO database adapter for PostgreSQL. @@ -813,8 +813,8 @@ Configuration Attributes: 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. @@ -863,7 +863,7 @@ by Icinga Web 2 in the table above. In addition to the category flags listed above the `DbCatEverything` flag may be used as a shortcut for listing all flags. -## InfluxdbWriter +## InfluxdbWriter Writes check result metrics and performance data to a defined InfluxDB host. @@ -932,7 +932,7 @@ Note: If `flush_threshold` is set too low, this will always force the feature to to InfluxDB. Experiment with the setting, if you are processing more than 1024 metrics per second or similar. -### Instance Tagging +### Instance Tagging Consider the following service check: @@ -971,10 +971,10 @@ is associated with the service: ... } -## LiveStatusListener +## LiveStatusListener 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: @@ -1007,7 +1007,7 @@ Configuration Attributes: > UNIX sockets are not supported on Windows. -## Notification +## Notification Notification objects are used to specify how users should be notified in case of host and service state changes and other events. @@ -1018,7 +1018,7 @@ of host and service state changes and other events. > usually easier to just create a `Notification` template and use the `apply` keyword > 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: @@ -1044,7 +1044,7 @@ Configuration Attributes: 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. @@ -1084,7 +1084,7 @@ Runtime Attributes: last\_problem\_notification | Number | When the last notification was sent for a problem (as a UNIX timestamp). -## NotificationCommand +## NotificationCommand A notification command definition. @@ -1178,11 +1178,11 @@ Configuration Attributes: 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). -## NotificationComponent +## NotificationComponent The notification component is responsible for sending notifications. There are no configurable options. @@ -1196,9 +1196,9 @@ Configuration Attributes: 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". -## OpenTsdbWriter +## OpenTsdbWriter Writes check result metrics and performance data to [OpenTSDB](http://opentsdb.net). @@ -1219,7 +1219,7 @@ Configuration Attributes: port |**Optional.** OpenTSDB port. Defaults to 4242. -## PerfdataWriter +## PerfdataWriter Writes check result performance data to a defined path using macro pattern consisting of custom attributes and runtime macros. @@ -1255,7 +1255,7 @@ When rotating the performance data file the current UNIX timestamp is appended t in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename. -## ScheduledDowntime +## ScheduledDowntime ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services. @@ -1265,7 +1265,7 @@ ScheduledDowntime objects can be used to set up recurring downtimes for hosts/se > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the > 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: @@ -1303,7 +1303,7 @@ with the same (short) name as long as one of the `host_name` and `service_name` attributes has a different value. -## Service +## Service Service objects describe network services and how they should be checked by Icinga 2. @@ -1313,7 +1313,7 @@ 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: @@ -1399,7 +1399,7 @@ Runtime Attributes: last_state_unknown | Number | When the last UNKNOWN state occurred (as a UNIX timestamp). -## ServiceGroup +## ServiceGroup A group of services. @@ -1421,7 +1421,7 @@ Configuration Attributes: groups |**Optional.** An array of nested group names. -## StatusDataWriter +## StatusDataWriter Periodically writes status data files which are used by the Classic UI and other third-party tools. @@ -1444,7 +1444,7 @@ Configuration Attributes: update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds. -## SyslogLogger +## SyslogLogger Specifies Icinga 2 logging to syslog. @@ -1461,7 +1461,7 @@ Configuration Attributes: severity |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "warning". -## TimePeriod +## TimePeriod Time periods can be used to specify when hosts/services should be checked or to limit when notifications should be sent out. @@ -1505,7 +1505,7 @@ Examples: } -Additional examples can be found [here](8-advanced-topics.md#timeperiods). +Additional examples can be found [here](08-advanced-topics.md#timeperiods). Configuration Attributes: @@ -1528,7 +1528,7 @@ Runtime Attributes: is\_inside | Boolean | Whether we're currently inside this timeperiod. -## User +## User A user. @@ -1589,7 +1589,7 @@ Runtime Attributes: --------------------------|---------------|----------------- last\_notification | Number | When the last notification was sent for this user (as a UNIX timestamp). -## UserGroup +## UserGroup A user group. @@ -1611,7 +1611,7 @@ Configuration Attributes: groups |**Optional.** An array of nested group names. -## Zone +## Zone Zone objects are used to specify which Icinga 2 instances are located in a zone. @@ -1637,17 +1637,17 @@ Configuration Attributes: Zone objects cannot currently be created with the API. -# Value Types +# Value Types -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). -## CheckResult +## CheckResult 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. @@ -1659,16 +1659,16 @@ In addition to [configuration objects](9-object-types.md#object-types) Icinga 2 vars_before | Dictionary | Internal attribute used for calculations. vars_after | Dictionary | Internal attribute used for calculations. -## PerfdataValue +## PerfdataValue -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. diff --git a/doc/10-icinga-template-library.md b/doc/10-icinga-template-library.md index 5722e1d9e..fc32a34b3 100644 --- a/doc/10-icinga-template-library.md +++ b/doc/10-icinga-template-library.md @@ -1,4 +1,4 @@ -# Icinga Template Library +# Icinga Template Library The Icinga Template Library (ITL) implements standard templates and object definitions for commonly used services. @@ -7,7 +7,7 @@ By default the ITL is included in the `icinga2.conf` configuration file: include -## Generic Templates +## Generic Templates These templates are imported by the provided example configuration. @@ -16,62 +16,62 @@ 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. -### plugin-check-command +### plugin-check-command 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. -### plugin-notification-command +### plugin-notification-command 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. -### plugin-event-command +### plugin-event-command 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. -### legacy-timeperiod +### legacy-timeperiod -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. -## Check Commands +## Check Commands These check commands are embedded into Icinga 2 and do not require any external plugin scripts. -### icinga +### icinga 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. -### cluster +### cluster 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. -### cluster-zone +### cluster-zone 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 ---------------------|--------------- @@ -79,18 +79,18 @@ cluster_zone | **Required.** The zone name. 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. -### ido +### ido 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. -### random +### random Check command for the built-in `random` check. This check returns random states and adds the check source to the check output. @@ -98,16 +98,16 @@ and adds the check source to the check output. For test and demo purposes only. The `random` check command does not support any vars. -### exception +### exception 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. -# Plugin Check Commands +# Plugin Check Commands -## Plugin Check Commands for Monitoring Plugins +## Plugin Check Commands for Monitoring Plugins The Plugin Check Commands provides example configuration for plugin check commands provided by the [Monitoring Plugins](https://www.monitoring-plugins.org) project. @@ -124,12 +124,12 @@ which contains the path of the plugins from the Monitoring Plugins project. definitions please kindly send a patch upstream. This should include an update for the ITL CheckCommand itself and this documentation section. -### apt +### apt 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 ------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- @@ -143,12 +143,12 @@ apt_timeout | **Optional.** Seconds before plugin times out (default apt_only_critical | **Optional.** Only warn about critical upgrades. -### breeze +### breeze 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 -----------------|--------------------------------- @@ -158,12 +158,12 @@ breeze_warning | **Required.** Percentage strength below which a WARNING statu breeze_critical | **Required.** Percentage strength below which a WARNING status will result. Defaults to 20. -### by_ssh +### by_ssh 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 ----------------|-------------- @@ -182,12 +182,12 @@ by_ssh_ipv4 | **Optional.** Use IPv4 connection. Defaults to false. by_ssh_ipv6 | **Optional.** Use IPv6 connection. Defaults to false. -### clamd +### clamd 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 -------------------|-------------- @@ -213,12 +213,12 @@ clamd_ipv4 | **Optional.** Use IPv4 connection. Defaults to false. clamd_ipv6 | **Optional.** Use IPv6 connection. Defaults to false. -### dhcp +### dhcp 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 ----------------|-------------- @@ -230,12 +230,12 @@ dhcp_mac | **Optional.** The MAC address to use in the DHCP request. dhcp_unicast | **Optional.** Whether to use unicast requests. Defaults to false. -### dig +### dig 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 ---------------------|-------------- @@ -253,13 +253,13 @@ dig_ipv4 | **Optional.** Force dig to only use IPv4 query transport. dig_ipv6 | **Optional.** Force dig to only use IPv6 query transport. Defaults to false. -### disk +### disk 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 --------------------|------------------------ @@ -290,12 +290,12 @@ disk\_timeout | **Optional.** Seconds before connection times out (d 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". -### disk_smb +### disk_smb 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 ------------------------|------------------------ @@ -309,14 +309,14 @@ disk_smb_wused | **Optional.** The used space warning threshold. Defaults 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. -### dns +### dns 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 ---------------------|-------------- @@ -331,13 +331,13 @@ dns_ctime | **Optional.** Return critical if elapsed time exceeds val dns_timeout | **Optional.** Seconds before connection times out. Defaults to 10. -### dummy +### dummy 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 ----------------|-------------- @@ -345,12 +345,12 @@ dummy_state | **Optional.** The state. Can be one of 0 (ok), 1 (warning), 2 dummy_text | **Optional.** Plugin output. Defaults to "Check was successful.". -### file_age +### file_age 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 -----------------------|-------------------------------------------------------------------------------------------------------- @@ -362,12 +362,12 @@ file_age_critical_size | **Optional.** File must be at least this many bytes lon file_age_ignoremissing | **Optional.** Return OK if the file does not exist. Defaults to false. -### flexlm +### flexlm 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 -------------------|---------------------------------------------------------- @@ -375,7 +375,7 @@ flexlm_licensefile | **Required.** Name of license file (usually license.dat). flexlm_timeout | **Optional.** Plugin time out in seconds. Defaults to 15. -### fping4 +### fping4 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 @@ -383,7 +383,7 @@ necessary to set the suid flag on fping. 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 ----------------|-------------- @@ -400,7 +400,7 @@ fping_source_ip | **Optional.** The name or ip address of the source ip. fping_source_interface | **Optional.** The source interface name. -### fping6 +### fping6 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 @@ -408,7 +408,7 @@ necessary to set the suid flag on fping. 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 ----------------|-------------- @@ -425,12 +425,12 @@ fping_source_ip | **Optional.** The name or ip address of the source ip. fping_source_interface | **Optional.** The source interface name. -### ftp +### ftp 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 -------------------|-------------- @@ -456,7 +456,7 @@ ftp_ipv4 | **Optional.** Use IPv4 connection. Defaults to false. ftp_ipv6 | **Optional.** Use IPv6 connection. Defaults to false. -### game +### game The [check_game](https://www.monitoring-plugins.org/doc/man/check_game.html) plugin tests game server connections with the specified host. @@ -464,7 +464,7 @@ This plugin uses the 'qstat' command, the popular game server status query tool. 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 -------------------|------------------- @@ -479,13 +479,13 @@ game_gametime | **Optional.** Field number in raw qstat output that contain game_hostname | **Optional.** Name of the host running the game. -### hostalive +### hostalive 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 ----------------|-------------- @@ -498,12 +498,12 @@ 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). -### hostalive4 +### hostalive4 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 ----------------|-------------- @@ -516,12 +516,12 @@ 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). -### hostalive6 +### hostalive6 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 ----------------|-------------- @@ -534,13 +534,13 @@ 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). -### hpjd +### hpjd 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 ----------------|-------------- @@ -549,14 +549,14 @@ hpjd_port | **Optional.** The host's SNMP port. Defaults to 161. hpjd_community | **Optional.** The SNMP community. Defaults to "public". -### http +### http 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 ---------------------------------|--------------------------------- @@ -607,7 +607,7 @@ http_link | **Optional.** Wrap output in HTML link. Defau http_verbose | **Optional.** Show details for command-line debugging. Defaults to false. -### icmp +### icmp 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`. @@ -615,7 +615,7 @@ The main difference is that check_ping executes the system's ping(1) command and 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 ----------------|-------------- @@ -634,12 +634,12 @@ icmp_timeout | **Optional.** The plugin timeout in seconds. Defaults to 10 (s icmp_ttl | **Optional.** The TTL on outgoing packets. -### imap +### imap 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 ----------------------|-------------- @@ -664,7 +664,7 @@ imap_ipv4 | **Optional.** Use IPv4 connection. Defaults to false. imap_ipv6 | **Optional.** Use IPv6 connection. Defaults to false. -### ldap +### ldap The [check_ldap](https://www.monitoring-plugins.org/doc/man/check_ldap.html) plugin can be used to check LDAP servers. @@ -672,7 +672,7 @@ 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 ------------------------|-------------- @@ -693,12 +693,12 @@ ldap_critical_entries | **Optional.** Number of found entries to result in criti ldap_timeout | **Optional.** Seconds before connection times out (default: 10). ldap_verbose | **Optional.** Show details for command-line debugging (disabled by default) -### load +### load 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 ----------------|-------------- @@ -710,12 +710,12 @@ load_cload5 | **Optional.** The 5-minute critical threshold. Defaults to 6. 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. -### mailq +### mailq 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 ------------------------|-------------- @@ -727,12 +727,12 @@ mailq_timeout | **Optional.** Plugin timeout in seconds (default = 15). mailq_servertype | **Optional.** [ sendmail \| qmail \| postfix \| exim \| nullmailer ] (default = autodetect). mailq_sudo | **Optional.** Use sudo to execute the mailq command. -### mysql +### mysql 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 ------------------------|--------------------------------------------------------------- @@ -756,7 +756,7 @@ mysql_cadir | **Optional.** Path to CA directory. mysql_ciphers | **Optional.** List of valid SSL ciphers. -### mysql_query +### mysql_query The [check_mysql_query](https://www.monitoring-plugins.org/doc/man/check_mysql_query.html) plugin checks a query result against threshold levels. @@ -765,7 +765,7 @@ The result from the query should be numeric. For extra security, create a user w **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 ------------------------|--------------------------------------------------------------- @@ -781,13 +781,13 @@ mysql_query_warning | **Optional.** Exit with WARNING status if query is out mysql_query_critical | **Optional.** Exit with CRITICAL status if query is outside of the range. -### negate +### negate 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 ------------------------|--------------------------------------------------------------- @@ -800,13 +800,13 @@ negate_substitute | **Optional.** Substitute output text as well. Will only subs negate_command | **Required.** Command to be negated. negate_arguments | **Optional.** Arguments for the negated command. -### nrpe +### nrpe 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 ----------------|-------------- @@ -822,12 +822,12 @@ nrpe_ipv6 | **Optional.** Use IPv6 connection. Defaults to false. nrpe_version_2 | **Optional.** Use this if you want to connect using NRPE v2 protocol. Defaults to false. -### nscp +### nscp 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 ----------------|-------------- @@ -842,14 +842,14 @@ nscp_timeout | **Optional.** The query timeout in seconds. nscp_showall | **Optional.** Use with SERVICESTATE to see working services or PROCSTATE for running processes. Defaults to false. -### ntp_time +### ntp_time 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 ----------------|-------------- @@ -864,14 +864,14 @@ ntp_ipv4 | **Optional.** Use IPv4 connection. Defaults to false. ntp_ipv6 | **Optional.** Use IPv6 connection. Defaults to false. -### ntp_peer +### ntp_peer 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 ----------------|-------------- @@ -890,18 +890,18 @@ ntp_ipv4 | **Optional.** Use IPv4 connection. Defaults to false. ntp_ipv6 | **Optional.** Use IPv6 connection. Defaults to false. -### passive +### passive 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.". -### pgsql +### pgsql 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. @@ -909,7 +909,7 @@ If a query is specified using the `pgsql_query` attribute, it will be executed a 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 ------------------------|--------------------------------------------------------------- @@ -926,7 +926,7 @@ pgsql_query | **Optional.** SQL query to run. Only first column in first row wi 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). -### ping +### ping 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 @@ -935,7 +935,7 @@ round trip average (milliseconds). 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 ----------------|-------------- @@ -948,7 +948,7 @@ 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). -### ping4 +### ping4 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 @@ -957,7 +957,7 @@ round trip average (milliseconds). 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 ----------------|-------------- @@ -969,7 +969,7 @@ ping_cpl | **Optional.** The packet loss critical threshold in %. Default 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). -### ping6 +### ping6 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 @@ -978,7 +978,7 @@ round trip average (milliseconds). 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 ----------------|-------------- @@ -991,12 +991,12 @@ 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). -### pop +### pop 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 ---------------------|-------------- @@ -1021,14 +1021,14 @@ pop_ipv4 | **Optional.** Use IPv4 connection. Defaults to false. pop_ipv6 | **Optional.** Use IPv6 connection. Defaults to false. -### procs +### procs 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 ---------------------|-------------- @@ -1049,7 +1049,7 @@ procs_command | **Optional.** Only scan for exact matches of COMMAND (wit procs_nokthreads | **Optional.** Only scan for non kernel threads. Defaults to false. -### radius +### radius 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 @@ -1062,7 +1062,7 @@ typically be executed at regular predictable intervals. Please be sure that the 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 -------------------|-------------- @@ -1078,12 +1078,12 @@ radius_retries | **Optional.** The number of times to retry a failed connect radius_timeout | **Optional.** The number of seconds before connection times out (default: 10). -### simap +### simap 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 -----------------------|-------------- @@ -1107,24 +1107,24 @@ simap_timeout | **Optional.** Seconds before connection times out (defa simap_ipv4 | **Optional.** Use IPv4 connection. Defaults to false. simap_ipv6 | **Optional.** Use IPv6 connection. Defaults to false. -### smart +### smart 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. -### smtp +### smtp 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 ----------------------|-------------- @@ -1148,14 +1148,14 @@ smtp_ipv4 | **Optional.** Use IPv4 connection. Defaults to false. smtp_ipv6 | **Optional.** Use IPv6 connection. Defaults to false. -### snmp +### snmp 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 --------------------|-------------- @@ -1179,12 +1179,12 @@ snmp_rate | **Optional.** Boolean. Enable rate calculation. snmp_getnext | **Optional.** Boolean. Use SNMP GETNEXT. Defaults to false. snmp_timeout | **Optional.** The command timeout in seconds. Defaults to 10 seconds. -### snmpv3 +### snmpv3 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 ---------------------|-------------- @@ -1209,12 +1209,12 @@ snmpv3_rate_multiplier | **Optional.** Converts rate per second. For example, se snmpv3_rate | **Optional.** Boolean. Enable rate calculation. snmpv3_timeout | **Optional.** The command timeout in seconds. Defaults to 10 seconds. -### snmp-uptime +### snmp-uptime 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 ----------------|-------------- @@ -1223,12 +1223,12 @@ snmp_oid | **Optional.** The SNMP OID. Defaults to "1.3.6.1.2.1.1.3.0". snmp_community | **Optional.** The SNMP community. Defaults to "public". -### spop +### spop 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 ----------------------|-------------- @@ -1253,12 +1253,12 @@ spop_ipv4 | **Optional.** Use IPv4 connection. Defaults to false. spop_ipv6 | **Optional.** Use IPv6 connection. Defaults to false. -### ssh +### ssh 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 ----------------|-------------- @@ -1269,12 +1269,12 @@ ssh_ipv4 | **Optional.** Use IPv4 connection. Defaults to false. ssh_ipv6 | **Optional.** Use IPv6 connection. Defaults to false. -### ssl +### ssl 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 ------------------------------|-------------- @@ -1286,12 +1286,12 @@ ssl_cert_valid_days_critical | **Optional.** Critical threshold for days before 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$". -### ssmtp +### ssmtp 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 -----------------------|-------------- @@ -1316,12 +1316,12 @@ ssmtp_ipv4 | **Optional.** Use IPv4 connection. Defaults to false. ssmtp_ipv6 | **Optional.** Use IPv6 connection. Defaults to false. -### swap +### swap 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 ----------------|-------------- @@ -1332,12 +1332,12 @@ swap_allswaps | **Optional.** Conduct comparisons for all swap partitions, one swap_noswap | **Optional.** Resulting state when there is no swap regardless of thresholds. Possible values are "ok", "warning", "critical", "unknown". Defaults to "critical". -### tcp +### tcp 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 ----------------|-------------- @@ -1363,12 +1363,12 @@ tcp_ipv4 | **Optional.** Use IPv4 connection. Defaults to false. tcp_ipv6 | **Optional.** Use IPv6 connection. Defaults to false. -### udp +### udp 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 ----------------|-------------- @@ -1381,13 +1381,13 @@ udp_ipv4 | **Optional.** Use IPv4 connection. Defaults to false. udp_ipv6 | **Optional.** Use IPv6 connection. Defaults to false. -### ups +### ups 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 ----------------|-------------- @@ -1401,20 +1401,20 @@ ups_celsius | **Optional.** Display the temperature in degrees Celsius inste ups_timeout | **Optional.** The number of seconds before the connection times out. Defaults to 10. -### users +### users 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. -## Windows Plugins for Icinga 2 +## Windows Plugins for Icinga 2 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. @@ -1425,7 +1425,7 @@ A check-commands-windows.conf comes with Icinga 2, it asumes that the Windows Pl 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. -### Threshold syntax +### Threshold syntax So not specified differently the thresholds for the plugins all follow the same pattern @@ -1437,7 +1437,7 @@ Threshold | Meaning "![10-40]" | Same as above, but the result is inverted. -### disk-windows +### disk-windows 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.). @@ -1458,7 +1458,7 @@ disk\_win\_path | **Optional**. Check only these paths, default checks all. 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. -### load-windows +### load-windows 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). @@ -1471,7 +1471,7 @@ load\_win\_warn | **Optional**. The warning threshold. load\_win\_crit | **Optional**. The critical threshold. -### memory-windows +### memory-windows Check command object for the `check_memory.exe` plugin. The memory collection is instant and free memory is used for threshold computation. @@ -1491,7 +1491,7 @@ memory\_win\_crit | **Optional**. The critical threshold. 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. -### network-windows +### network-windows 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). @@ -1505,7 +1505,7 @@ network\_win\_crit | **Optional**. The critical threshold. network\_no\_isatap | **Optional**. Do not print ISATAP interfaces. -### perfmon-windows +### perfmon-windows 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`. @@ -1524,7 +1524,7 @@ perfmon\_win\_type | **Optional**. Format in which to expect perfomance value perfmon\_win\_syntax | **Optional**. Use this in the performance output instead of `perfmon\_win\_counter`. Exists for graphice compatibility reasons. -### ping-windows +### ping-windows 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. @@ -1540,7 +1540,7 @@ ping\_win\_packets | **Optional**. Number of packages to send. Default: 5. ping\_win\_timeout | **Optional**. The timeout in milliseconds. Default: 1000 -### procs-windows +### procs-windows 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. @@ -1554,7 +1554,7 @@ procs\_win\_crit | **Optional**. The critical threshold. procs\_win\_user | **Optional**. Count this useres processes. -### service-windows +### service-windows 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. @@ -1567,7 +1567,7 @@ service\_win\_warn | **Optional**. Warn when service is not running. service\_win\_service | **Required**. The critical threshold. -### swap-windows +### swap-windows Check command object for `check_swap.exe` plugin. The data collection is instant. @@ -1581,7 +1581,7 @@ swap\_win\_crit | **Optional**. The critical threshold. swap\_win\_unit | **Optional**. The unit to display the received value in, thresholds are interpreted in this unit. Defaults to "mb" (megabyte). -### update-windows +### update-windows 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. @@ -1610,7 +1610,7 @@ Thresholds will always be "1". > If run without the optional parameters, the plugin will output critical if any important updates are available. -### uptime-windows +### uptime-windows Check command opject for `check_uptime.exe` plugin. Uses GetTickCount64 to get the uptime, so boot time is not included. @@ -1624,7 +1624,7 @@ uptime\_win\_crit | **Optional**. The critical threshold. 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). -### users-windows +### users-windows Check command object for `check_users.exe` plugin. @@ -1636,7 +1636,7 @@ users\_win\_warn | **Optional**. The warning threshold. users\_win\_crit | **Optional**. The critical threshold. -## Plugin Check Commands for NSClient++ +## Plugin Check Commands for NSClient++ There are two methods available for querying NSClient++: @@ -1647,7 +1647,7 @@ 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. -### nscp_api +### nscp_api `check_nscp_api` is part of the Icinga 2 plugins. This plugin is available for both, Windows and Linux/Unix. @@ -1690,17 +1690,17 @@ check_cpu CRITICAL: critical(5m: 48%, 1m: 36%), 5s: 0% | 'total 5m'=48%;40;30 't ``` -### nscp-local +### nscp-local 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 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++" @@ -1712,7 +1712,7 @@ Note that it is not necessary to run NSClient++ as a Windows service for these c 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 ----------------|-------------- @@ -1724,7 +1724,7 @@ nscp_query | **Required.** The NSClient++ query. Try `nscp client -q x` for nscp_arguments | **Optional.** An array of query arguments. nscp_showall | **Optional.** Shows more details in plugin output, default to false. -### nscp-local-cpu +### nscp-local-cpu Check command object for the `check_cpu` NSClient++ plugin. @@ -1736,7 +1736,7 @@ nscp_cpu_critical | **Optional.** Threshold for CRITICAL state in percent, def nscp_cpu_arguments | **Optional.** Additional arguments. nscp_cpu_showall | **Optional.** Shows more details in plugin output, default to false. -### nscp-local-memory +### nscp-local-memory Check command object for the `check_memory` NSClient++ plugin. @@ -1750,25 +1750,25 @@ nscp_memory_critical | **Optional.** Threshold for CRITICAL state in percent or nscp_memory_arguments | **Optional.** Additional arguments. nscp_memory_showall | **Optional.** Shows more details in plugin output, default to false. -### nscp-local-os-version +### nscp-local-os-version Check command object for the `check_os_version` NSClient++ plugin. This command has the same custom attributes like the `nscp-local` check command. -### nscp-local-pagefile +### nscp-local-pagefile Check command object for the `check_pagefile` NSClient++ plugin. This command has the same custom attributes like the `nscp-local` check command. -### nscp-local-process +### nscp-local-process Check command object for the `check_process` NSClient++ plugin. This command has the same custom attributes like the `nscp-local` check command. -### nscp-local-service +### nscp-local-service Check command object for the `check_service` NSClient++ plugin. @@ -1785,20 +1785,20 @@ nscp_service_ctype | **Optional.** Dedicate type for nscp_service_critical, nscp_service_arguments | **Optional.** Additional arguments. nscp_service_showall | **Optional.** Shows more details in plugin output, default to true. -### nscp-local-uptime +### nscp-local-uptime Check command object for the `check_uptime` NSClient++ plugin. This command has the same custom attributes like the `nscp-local` check command. -### nscp-local-version +### nscp-local-version 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" ]`. -### nscp-local-disk +### nscp-local-disk Check command object for the `check_drivesize` NSClient++ plugin. @@ -1812,7 +1812,7 @@ nscp_disk_arguments | **Optional.** Additional arguments. 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" ]`. -### nscp-local-counter +### nscp-local-counter Check command object for the `check_pdh` NSClient++ plugin. @@ -1827,7 +1827,7 @@ nscp_counter_perfsyntax | **Optional.** Apply performance data label, e.g. `Tota -## Plugin Check Commands for Manubulon SNMP +## Plugin Check Commands for Manubulon SNMP 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). @@ -1839,7 +1839,7 @@ The SNMP manubulon plugin check commands assume that the global constant named ` 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 @@ -1871,11 +1871,11 @@ You can enable these plugin check commands by adding the following the include d Cisco CSS | Yes | ?? | Yes | Yes | No | ?? | check_snmp_css.pl -### snmp-load +### snmp-load 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 @@ -1898,11 +1898,11 @@ snmp_load_type | **Optional.** Load type. Defaults to "stand". Check al snmp_perf | **Optional.** Enable perfdata values. Defaults to true. snmp_timeout | **Optional.** The command timeout in seconds. Defaults to 5 seconds. -### snmp-memory +### snmp-memory 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 ------------------------|-------------- @@ -1925,11 +1925,11 @@ snmp_is_hp | **Optional.** Change OIDs for HP/Procurve switches. De snmp_perf | **Optional.** Enable perfdata values. Defaults to true. snmp_timeout | **Optional.** The command timeout in seconds. Defaults to 5 seconds. -### snmp-storage +### snmp-storage 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 ------------------------|-------------- @@ -1951,11 +1951,11 @@ snmp_storage_name | **Optional.** Storage name. Default to regex "^/$$". M snmp_perf | **Optional.** Enable perfdata values. Defaults to true. snmp_timeout | **Optional.** The command timeout in seconds. Defaults to 5 seconds. -### snmp-interface +### snmp-interface 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 ----------------------------|-------------- @@ -1991,11 +1991,11 @@ snmp_interface_ifalias | **Optional.** Switch from IF-MIB::ifDescr to IF-MI snmp_perf | **Optional.** Enable perfdata values. Defaults to true. snmp_timeout | **Optional.** The command timeout in seconds. Defaults to 5 seconds. -### snmp-process +### snmp-process 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 ---------------------------|-------------- @@ -2023,14 +2023,14 @@ snmp_process_cpu_usage | **Optional.** Define to check CPU usage for the pro 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". -## Contributed Plugin Check Commands +## Contributed Plugin Check Commands 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 @@ -2040,11 +2040,11 @@ include This is enabled by default since Icinga 2 2.5.0. -### Databases +### Databases This category contains plugins for various database servers. -#### db2_health +#### db2_health 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/) @@ -2052,7 +2052,7 @@ database. 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 ---------------------------------|------------------------------------------------------------------------------------------------------------------------------ @@ -2075,7 +2075,7 @@ db2_health_report | **Optional.** Report can be used to output only 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`. -#### mssql_health +#### mssql_health 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 @@ -2083,7 +2083,7 @@ uses the `DBD::Sybase` Perl library based on [FreeTDS](http://www.freetds.org/) 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 ---------------------------------|------------------------------------------------------------------------------------------------------------------------------ @@ -2108,7 +2108,7 @@ mssql_health_nooffline | **Optional.** Set this to true to ignore offl 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`. -#### mysql_health +#### mysql_health The [check_mysql_health](https://labs.consol.de/nagios/check_mysql_health/index.html) plugin uses the `DBD::MySQL` Perl library to monitor a @@ -2116,7 +2116,7 @@ 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 ---------------------------------|------------------------------------------------------------------------------------------------------------------------------ @@ -2157,14 +2157,14 @@ mysql_health_statefilesdir | **Optional.** An alternate directory where th 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. -#### oracle_health +#### oracle_health 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 ---------------------------------|------------------------------------------------------------------------------------------------------------------------------ @@ -2192,14 +2192,14 @@ 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". -#### postgres +#### postgres 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 ---------------------------------|------------------------------------------------------------------------------------------------------------------------------ @@ -2224,12 +2224,12 @@ postgres_valtype | **Optional.** Value type of query result for "custom_quer 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). -#### mongodb +#### mongodb 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 ---------------------------------|------------------------------------------------------------------------------------------------------------------------------ @@ -2252,12 +2252,12 @@ mongodb_querytype | **Optional.** The query type to check [query\ mongodb_collection | **Optional.** Specify the collection to check mongodb_sampletime | **Optional.** Time used to sample number of pages faults -#### elasticsearch +#### elasticsearch 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 -----------------------------|------------------------------------------------------------------------------------------------------- @@ -2268,14 +2268,14 @@ elasticsearch_port | **Optional.** TCP port to probe. The ElasticSear 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. -#### redis +#### redis 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 -------------------------|-------------------------------------------------------------------------------------------------------------- @@ -2301,11 +2301,11 @@ redis_total_memory | **Optional.** Amount of memory on a system for memory redis_replication_delay | **Optional.** Allows to set threshold on replication delay info. -### Hardware +### Hardware This category includes all plugin check commands for various hardware checks. -#### hpasm +#### hpasm 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` @@ -2323,7 +2323,7 @@ The `hpasm_remote` attribute enables the plugin to execute remote SNMP queries i 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 --------------------------------|----------------------------------------------------------------------- @@ -2346,36 +2346,36 @@ hpasm_servertype | **Optional.** The type of the server: proliant (default) or 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`. -#### adaptec-raid +#### adaptec-raid 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". -#### lsi-raid +#### lsi-raid 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". -#### smart-attributes +#### smart-attributes 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 --------------------------------|----------------------------------------------------------------------- @@ -2383,16 +2383,16 @@ smart_attributes_config_path | **Required.** Path to the smart attributes con smart_attributes_device | **Required.** Device name (e.g. /dev/sda) to monitor. -### IcingaCLI +### IcingaCLI This category includes all plugins using the icingacli provided by Icinga Web 2. -#### Business Process +#### Business Process 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 ------------------------------------------|----------------------------------------------------------------------------------------- @@ -2402,18 +2402,18 @@ icingacli_businessprocess_details | **Optional.** Get details for root c icingacli_businessprocess_statetype | **Optional.** Define which state type to look at, `soft` or `hard`. Overrides the default value inside the businessprocess module, if configured. -### IPMI Devices +### IPMI Devices This category includes all plugins for IPMI devices. -#### ipmi-sensor +#### ipmi-sensor 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 ---------------------------------|----------------------------------------------------------------------------------------------------- @@ -2436,11 +2436,11 @@ ipmi_no_sel_checking | **Optional.** Turn off system event log check 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. -#### ipmi-alive +#### ipmi-alive 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 ---------------------------------|----------------------------------------------------------------------------------------------------- @@ -2453,11 +2453,11 @@ ping_packets | **Optional.** The number of packets to send. ping_timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout). -### Log Management +### Log Management This category includes all plugins for log management, for example [Logstash](https://www.elastic.co/products/logstash). -#### logstash +#### logstash 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. @@ -2479,16 +2479,16 @@ logstash_cpu_warn | **Optional.** Warning threshold for cpu usage in pe logstash_cpu_crit | **Optional.** Critical threshold for cpu usage in percent. -### Metrics +### Metrics This category includes all plugins for metric-based checks. -#### graphite +#### graphite 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 ------------------------------------|----------------------------------------------------------------------------------------------------- @@ -2504,18 +2504,18 @@ graphite_message | **Optional.** Text message to output (defa 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. -### Network Components +### Network Components This category includes all plugins for various network components like routers, switches and firewalls. -#### interfacetable +#### interfacetable 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 ------------------------------------|----------------------------------------------------------------------------------------------------- @@ -2581,12 +2581,12 @@ interfacetable_defaulttablesorting | **Optional.** Default table sorting can be 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. -#### iftraffic +#### iftraffic 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 ------------------------|--------------------------------------------------------- @@ -2599,12 +2599,12 @@ iftraffic_warn | **Optional.** Percent of bandwidth usage necessary to result i 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. -#### iftraffic64 +#### iftraffic64 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 ------------------------|--------------------------------------------------------- @@ -2617,12 +2617,12 @@ iftraffic64_warn | **Optional.** Percent of bandwidth usage necessary to 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. -#### interfaces +#### interfaces 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 --------------------------|--------------------------------------------------------- @@ -2650,7 +2650,7 @@ interfaces_timeout | **Optional.** Sets the SNMP timeout (in ms). interfaces_sleep | **Optional.** Sleep between every SNMP query (in ms). interfaces_names | **Optional.** If set to true, use ifName instead of ifDescr. -#### nwc_health +#### nwc_health 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, @@ -2664,7 +2664,7 @@ Brocade ICX6610-24-HPOE, Cisco UC Telefonzeugs, FOUNDRY-SN-AGENT-MIB, FRITZ!BOX 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 --------------------------------|--------------------------------------------------------- @@ -2711,18 +2711,18 @@ nwc_health_offline | **Optional.** The maximum number of seconds since the last nwc_health_multiline | **Optional.** Multiline output -### Operating System +### Operating System This category contains plugins which receive details about your operating system or the guest system. -#### mem +#### mem 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 -------------|----------------------------------------------------------------------------------------------------------------------- @@ -2732,7 +2732,7 @@ mem_cache | **Optional.** If set to true, plugin will count cache as free mem mem_warning | **Required.** Specify the warning threshold as number interpreted as percent. mem_critical | **Required.** Specify the critical threshold as number interpreted as percent. -#### running_kernel +#### running_kernel The [check_running_kernel](https://packages.debian.org/stretch/nagios-plugins-contrib) plugin is provided by the `nagios-plugin-contrib` package on Debian/Ubuntu. @@ -2743,13 +2743,13 @@ Name | Description ---------------------------|------------- running\_kernel\_use\_sudo | Whether to run the plugin with `sudo`. Defaults to false except on Ubuntu where it defaults to true. -#### iostats +#### iostats 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 ---------------|----------------------------------------------------------------------------------------------------------------------- @@ -2763,13 +2763,13 @@ iostats\_critical\_read | **Required.** Critical threshold for KB/s reads (defa iostats\_critical\_write | **Required.** Critical threshold for KB/s writes (default: 25000) iostats\_critical\_wait | **Required.** Critical threshold for % iowait (default: 80) -#### iostat +#### iostat 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 ---------------|----------------------------------------------------------------------------------------------------------------------- @@ -2781,13 +2781,13 @@ iostat\_ctps | **Required.** Critical threshold for tps (default: 200) iostat\_cread | **Required.** Critical threshold for KB/s reads (default: 200) iostat\_cwrite | **Required.** Critical threshold for KB/s writes (default: 200) -#### yum +#### yum 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 ------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- @@ -2801,17 +2801,17 @@ yum_disablerepo | **Optional.** Explicitly disables a reposity when call 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). -### Storage +### Storage This category includes all plugins for various storage and object storage technologies. -#### glusterfs +#### glusterfs 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 ---------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ @@ -2824,17 +2824,17 @@ glusterfs_inode_warning | **Optional.** Warn if inode usage is above *DISKWAR glusterfs_inode_critical | **Optional.** Return a critical error if inode usage is above *DISKCRIT*. Defaults to 95 (percent). -### Virtualization +### Virtualization This category includes all plugins for various virtualization technologies. -#### esxi_hardware +#### esxi_hardware 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 ------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ @@ -2852,7 +2852,7 @@ esxi_hardware_nocurrent | **Optional.** Do not collect current performance data, 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. -#### VMware +#### VMware Check commands for the [check_vmware_esx](https://github.com/BaldMansMojo/check_vmware_esx) plugin. @@ -2860,7 +2860,7 @@ Check commands for the [check_vmware_esx](https://github.com/BaldMansMojo/check_ 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 ------------------------|-------------- @@ -2893,7 +2893,7 @@ vmware_crit | **Optional.** The critical threshold for volumes. Defa 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 ------------------------|-------------- @@ -2916,7 +2916,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -2944,7 +2944,7 @@ vmware_multiline | **Optional.** Multiline output in overview. This mean 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 ------------------------|-------------- @@ -2972,7 +2972,7 @@ vmware_multiline | **Optional.** Multiline output in overview. This mean 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 ------------------------|-------------- @@ -3000,7 +3000,7 @@ vmware_multiline | **Optional.** Multiline output in overview. This mean 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 ------------------------|-------------- @@ -3027,7 +3027,7 @@ vmware_multiline | **Optional.** Multiline output in overview. This mean 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 ------------------------|-------------- @@ -3050,7 +3050,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -3080,7 +3080,7 @@ vmware_openvmtools | **Optional** Prevent CRITICAL state for installed and runni 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 ------------------------|-------------- @@ -3103,7 +3103,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -3126,7 +3126,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -3151,7 +3151,7 @@ vmware_crit | **Optional.** The critical threshold in percent. Defau 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 ------------------------|-------------- @@ -3174,7 +3174,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -3197,7 +3197,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -3222,7 +3222,7 @@ vmware_crit | **Optional.** The critical threshold in percent. Defau 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 ------------------------|-------------- @@ -3245,7 +3245,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -3270,7 +3270,7 @@ vmware_crit | **Optional.** The critical threshold in percent. Defau 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 ------------------------|-------------- @@ -3295,7 +3295,7 @@ vmware_crit | **Optional.** The critical threshold in percent. No va 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 ------------------------|-------------- @@ -3321,7 +3321,7 @@ vmware_multiline | **Optional.** Multiline output in overview. This mean 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 ------------------------|-------------- @@ -3346,7 +3346,7 @@ vmware_crit | **Optional.** The critical threshold in percent. No va 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 ------------------------|-------------- @@ -3372,7 +3372,7 @@ vmware_multiline | **Optional.** Multiline output in overview. This mean 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 ------------------------|-------------- @@ -3397,7 +3397,7 @@ vmware_isregexp | **Optional.** Treat blacklist expression as regexp. 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 ------------------------|-------------- @@ -3422,7 +3422,7 @@ vmware_crit | **Optional.** The critical threshold in KBps(Kilobytes 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 ------------------------|-------------- @@ -3447,7 +3447,7 @@ vmware_crit | **Optional.** The critical threshold in KBps(Kilobytes 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 ------------------------|-------------- @@ -3472,7 +3472,7 @@ vmware_crit | **Optional.** The critical threshold in KBps(Kilobytes 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 ------------------------|-------------- @@ -3497,7 +3497,7 @@ vmware_isregexp | **Optional.** Treat blacklist expression as regexp. 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 ------------------------|-------------- @@ -3530,7 +3530,7 @@ vmware_spaceleft | **Optional.** This has to be used in conjunction with 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 ------------------------|-------------- @@ -3553,7 +3553,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -3578,7 +3578,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -3603,7 +3603,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -3628,7 +3628,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -3653,7 +3653,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -3678,7 +3678,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -3703,7 +3703,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -3728,7 +3728,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -3753,7 +3753,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -3778,7 +3778,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -3803,7 +3803,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -3828,7 +3828,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -3855,7 +3855,7 @@ vmware_multiline | **Optional.** Multiline output in overview. This mean 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 ------------------------|-------------- @@ -3882,7 +3882,7 @@ vmware_multiline | **Optional.** Multiline output in overview. This mean 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 ------------------------|-------------- @@ -3905,7 +3905,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -3928,7 +3928,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -3955,7 +3955,7 @@ vmware_multiline | **Optional.** Multiline output in overview. This mean 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 ------------------------|-------------- @@ -3978,7 +3978,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -4004,7 +4004,7 @@ vmware_isregexp | **Optional.** Treat blacklist and whitelist expression 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 ------------------------|-------------- @@ -4030,7 +4030,7 @@ vmware_isregexp | **Optional.** Treat blacklist and whitelist expression 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 ------------------------|-------------- @@ -4056,7 +4056,7 @@ vmware_isregexp | **Optional.** Treat blacklist and whitelist expression 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 ------------------------|-------------- @@ -4083,7 +4083,7 @@ vmware_multiline | **Optional.** Multiline output in overview. This mean 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 ------------------------|-------------- @@ -4110,7 +4110,7 @@ vmware_multiline | **Optional.** Multiline output in overview. This mean 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 ------------------------|-------------- @@ -4137,7 +4137,7 @@ vmware_multiline | **Optional.** Multiline output in overview. This mean 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 ------------------------|-------------- @@ -4163,7 +4163,7 @@ vmware_isregexp | **Optional.** Treat blacklist and whitelist expression 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 ------------------------|-------------- @@ -4190,7 +4190,7 @@ vmware_multiline | **Optional.** Multiline output in overview. This mean 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 ------------------------|-------------- @@ -4217,7 +4217,7 @@ vmware_multiline | **Optional.** Multiline output in overview. This mean 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 ------------------------|-------------- @@ -4246,7 +4246,7 @@ vmware_standbyok | **Optional.** For storage systems where a standby mult 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 ------------------------|-------------- @@ -4271,7 +4271,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -4297,7 +4297,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -4323,7 +4323,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -4349,7 +4349,7 @@ vmware_crit | **Optional.** Critical threshold in percent. Defaults 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 ------------------------|-------------- @@ -4373,7 +4373,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -4400,7 +4400,7 @@ vmware_crit | **Optional.** Critical threshold in percent. Defaults 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.
**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 ------------------------|-------------- @@ -4426,7 +4426,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -4453,7 +4453,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -4477,7 +4477,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -4503,7 +4503,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -4529,7 +4529,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -4555,7 +4555,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -4579,7 +4579,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -4605,7 +4605,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -4631,7 +4631,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -4657,7 +4657,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -4681,7 +4681,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -4705,7 +4705,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -4729,7 +4729,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -4753,7 +4753,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -4779,7 +4779,7 @@ vmware_crit | **Optional.** The critical threshold. No value defined 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 ------------------------|-------------- @@ -4802,7 +4802,7 @@ vmware_authfile | **Optional.** Use auth file instead username/password 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 ------------------------|-------------- @@ -4827,7 +4827,7 @@ vmware_openvmtools | **Optional** Prevent CRITICAL state for installed and runni 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 ------------------------|-------------- @@ -4848,17 +4848,17 @@ vmware_authfile | **Optional.** Use auth file instead username/password vmware_multiline | **Optional.** Multiline output in overview. This mean technically that a multiline output uses a HTML **\** for the GUI. No value defined as default. -### Web +### Web This category includes all plugins for web-based checks. -#### apache_status +#### apache_status 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 ------------------------|---------------------------------------------------------------------------------- @@ -4871,12 +4871,12 @@ apache_status_warning | **Optional.** Warning threshold (number of open slots, b apache_status_critical | **Optional.** Critical threshold (number of open slots, busy workers and idle workers that will cause a CRITICAL) like ':10,25,:20'. -### cert +### cert 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 --------------------------|-------------- @@ -4910,7 +4910,7 @@ ssl_cert_ignore_expiration | **Optional.** Ignore expiration date. ssl_cert_ignore_ocsp | **Optional.** Do not check revocation with OCSP. -#### jmx4perl +#### jmx4perl The [check_jmx4perl](http://search.cpan.org/~roland/jmx4perl/scripts/check_jmx4perl) plugin uses the HTTP API exposed by the [Jolokia](https://jolokia.org) @@ -4918,7 +4918,7 @@ web application and queries Java message beans on an application server. It is 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 -----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------- @@ -4958,12 +4958,12 @@ jmx4perl_server | **Optional.** Symbolic name of server url to use, jmx4perl_check | **Optional.** Name of a check configuration as defined in the configuration file, use array if you need arguments. -#### kdc +#### kdc 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 ----------------|-------------------------------------------------------------------------- @@ -4973,13 +4973,13 @@ kdc_principal | **Required** Principal name to authenticate as (including realm) kdc_keytab | **Required** Keytab file containing principal's key. -#### nginx_status +#### nginx_status 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 --------------------------------|---------------------------------------------------------------------------------- @@ -4998,13 +4998,13 @@ nginx_status_warn | **Optional.** Warning threshold (number of active connectio nginx_status_critical | **Optional.** Critical threshold (number of active connections, ReqPerSec or ConnPerSec that will cause a CRITICAL) like '20000,200,300'. -#### rbl +#### rbl 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 ----------------|-------------------------------------------------------------------------- @@ -5015,12 +5015,12 @@ rbl_critical | **Optional** Number of blacklisting servers for a critical. tbl_timeout | **Optional** Seconds before plugin times out (default: 15). -#### squid +#### squid 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 ------------------------|---------------------------------------------------------------------------------- @@ -5035,7 +5035,7 @@ squid_client | **Optional.** Path of squidclient (default: /usr/bin/squidclient squid_timeout | **Optional.** Seconds before plugin times out (default: 15). -#### webinject +#### webinject 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 @@ -5047,7 +5047,7 @@ acceptance, and regression tests. A test harness allows you to run many test cas 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 ------------------------|-------------- diff --git a/doc/11-cli-commands.md b/doc/11-cli-commands.md index efb39ca55..f1cf09d75 100644 --- a/doc/11-cli-commands.md +++ b/doc/11-cli-commands.md @@ -1,4 +1,4 @@ -# Icinga 2 CLI Commands +# Icinga 2 CLI Commands Icinga 2 comes with a number of CLI commands which support bash autocompletion. @@ -80,7 +80,7 @@ options. Icinga home page: -## Icinga 2 CLI Bash Autocompletion +## Icinga 2 CLI Bash Autocompletion Bash Auto-Completion (pressing ``) is provided only for the corresponding context. @@ -111,7 +111,7 @@ into your current session and test it: # source /etc/bash-completion.d/icinga2 -## Icinga 2 CLI Global Options +## Icinga 2 CLI Global Options ### Application Type @@ -129,7 +129,7 @@ Note: This is not needed by the average Icinga user, only developers. [Global constants](17-language-reference.md#constants) can be set using the `--define` command-line option. -### Config Include Path +### Config Include Path 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 @@ -145,7 +145,7 @@ Using the `--include` command-line option additional search directories can be added. -## CLI command: Console +## CLI command: Console 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. @@ -253,7 +253,7 @@ Here's an example that retrieves the command that was used by Icinga to check th "3000,80%" ] -## CLI command: Daemon +## CLI command: Daemon 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). @@ -307,7 +307,7 @@ The `--validate` option can be used to check if configuration files contain errors. If any errors are found, the exit status is 1, otherwise 0 is returned. More details in the [configuration validation](11-cli-commands.md#config-validation) chapter. -## CLI command: Feature +## CLI command: Feature The `feature enable` and `feature disable` commands can be used to enable and disable features: @@ -326,7 +326,7 @@ The `feature list` command shows which features are currently enabled: Enabled features: api checker command graphite ido-mysql mainlog notification -## CLI command: Node +## CLI command: Node > **Warning** > @@ -337,7 +337,7 @@ The `feature list` command shows which features are currently enabled: > Make sure to follow the release announcements on the [Icinga website](https://www.icinga.com). 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) @@ -379,7 +379,7 @@ nodes in a [distributed monitoring](6-distributed-monitoring.md#distributed-moni -## CLI command: Object +## CLI command: Object 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 @@ -419,7 +419,7 @@ More information can be found in the [troubleshooting](15-troubleshooting.md#lis Report bugs at Icinga home page: -## CLI command: Pki +## CLI command: Pki Provides the CLI commands to @@ -431,7 +431,7 @@ 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) @@ -464,7 +464,7 @@ You will need them in the [distributed monitoring chapter](6-distributed-monitor Report bugs at Icinga home page: -## CLI command: Repository +## CLI command: Repository > **Warning** > @@ -476,7 +476,7 @@ You will need them in the [distributed monitoring chapter](6-distributed-monitor This command is experimental and not finished as public CLI command. Parts of its functionality are used in the [node update-config](11-cli-commands.md#cli-command-node) cli command. -## CLI command: Troubleshoot +## CLI command: Troubleshoot 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). @@ -518,7 +518,7 @@ This is only a tool to collect information to help others help you, it will not Report bugs at Icinga home page: -## CLI command: Variable +## CLI command: Variable Lists all configured variables (constants) in a similar fashion like [object list](11-cli-commands.md#cli-command-object). @@ -549,7 +549,7 @@ Lists all configured variables (constants) in a similar fashion like [object lis Report bugs at Icinga home page: -## Enabling/Disabling Features +## Enabling/Disabling Features Icinga 2 provides configuration files for some commonly used features. These are installed in the `/etc/icinga2/features-available` directory and can be @@ -585,7 +585,7 @@ after enabling or disabling features. -## Configuration Validation +## Configuration Validation 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 @@ -603,7 +603,7 @@ Validate the configuration with the init script option `checkconfig`: # /etc/init.d/icinga2 checkconfig -**Note**: Using [systemd](2-getting-started.md#systemd-service) you need to manually validate the configuration using +**Note**: Using [systemd](02-getting-started.md#systemd-service) you need to manually validate the configuration using the CLI command below. # icinga2 daemon -C @@ -656,7 +656,7 @@ Example filtered by `Service` objects with the name `ping*`: -## Reload on Configuration Changes +## Reload on Configuration Changes 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 diff --git a/doc/12-icinga2-api.md b/doc/12-icinga2-api.md index fa9ffb8f2..41fbf88fc 100644 --- a/doc/12-icinga2-api.md +++ b/doc/12-icinga2-api.md @@ -1,6 +1,6 @@ -# Icinga 2 API +# Icinga 2 API -## Setting up the API +## Setting up the API You can run the CLI command `icinga2 api setup` to enable the `api` [feature](11-cli-commands.md#enable-features) and set up @@ -21,7 +21,7 @@ If you prefer to set up the API manually, you will have to perform the following The next chapter provides a quick overview of how you can use the API. -## Introduction +## Introduction The Icinga 2 API allows you to manage configuration objects and resources in a simple, programmatic way using HTTP requests. @@ -35,7 +35,7 @@ make calls to * [manage configuration packages](12-icinga2-api.md#icinga2-api-config-management) * evaluate [script expressions](12-icinga2-api.md#icinga2-api-console) -### Requests +### Requests Any tool capable of making HTTP requests can communicate with the API, for example [curl](https://curl.haxx.se/). @@ -45,7 +45,7 @@ traffic remains encrypted. By default the Icinga 2 API listens on port `5665` which is shared with 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. @@ -64,7 +64,7 @@ All requests apart from `GET` require that the following `Accept` header is set: Each URL is prefixed with the API version (currently "/v1"). -### Responses +### Responses Successful requests will send back a response body containing a `results` list. Depending on the number of affected objects in your request, the @@ -92,7 +92,7 @@ prefers `python -m json.tool` as Python is available nearly everywhere. > should gracefully handle fields it is not familiar with, for example by > ignoring them. -### HTTP Statuses +### HTTP Statuses The API will return standard [HTTP statuses](https://www.ietf.org/rfc/rfc2616.txt) including error codes. @@ -111,14 +111,14 @@ was malformed. A status in the range of 500 generally means that there was a server-side problem and Icinga 2 is unable to process your request. -### Authentication +### Authentication 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. @@ -130,7 +130,7 @@ and the `password` attribute contains the basic auth password. Alternatively you can use X.509 client certificates by specifying the `client_cn` 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 @@ -162,7 +162,7 @@ specify the trusted CA certificate using the curl parameter`--cacert`: Read the next chapter on [API permissions](12-icinga2-api.md#icinga2-api-permissions) in order to configure authorization settings for your newly created API user. -### Permissions +### Permissions By default an API user does not have any permissions to perform actions on the URL endpoints. @@ -221,7 +221,7 @@ Available permissions for specific URL endpoints: The required actions or types can be replaced by using a wildcard match ("\*"). -### Parameters +### Parameters Depending on the request method there are two ways of passing parameters to the request: @@ -243,7 +243,7 @@ Here are the exact same query parameters as a JSON object: The [match function](18-library-reference.md#global-functions-match) is available as global function in Icinga 2. -### Request Method Override +### Request Method Override `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` @@ -257,9 +257,9 @@ Delete an existing object by sending a `POST` request with `X-HTTP-Method-Overri $ curl -k -s -u 'root:icinga' -H 'Accept: application/json' -X POST -H 'X-HTTP-Method-Override: DELETE' 'https://localhost:5665/v1/objects/hosts/example.localdomain' -### Filters +### Filters -#### Simple Filters +#### Simple Filters By default actions and queries operate on all objects unless further restricted by the user. For example, the following query returns all `Host` objects: @@ -287,12 +287,12 @@ full name has to be used: The full name of an object can be obtained by looking at the `__name` attribute. -#### Advanced Filters +#### Advanced Filters 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** > @@ -351,7 +351,7 @@ the HTTP specification does not allow message bodies for GET requests. The `filters_vars` attribute can only be used inside the request body, but not as a URL parameter because there is no way to specify a dictionary in a URL. -## Config Objects +## Config Objects Provides methods to manage configuration objects: @@ -360,7 +360,7 @@ Provides methods to manage configuration objects: * [modifying objects](12-icinga2-api.md#icinga2-api-config-objects-modify) * [deleting objects](12-icinga2-api.md#icinga2-api-config-objects-delete) -### API Objects and Cluster Config Sync +### API Objects and Cluster Config Sync Newly created or updated objects can be synced throughout your Icinga 2 cluster. Set the `zone` attribute to the zone this object @@ -372,14 +372,14 @@ Objects without a zone attribute are only synced in the same zone the Icinga ins > > Cluster nodes must accept configuration for creating, modifying > 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. -### Querying Objects +### Querying Objects You can request information about configuration objects by sending a `GET` query to the `/v1/objects/` URL endpoint. ` Object Queries Result +#### Object Queries Result Each response entry in the results array contains the following attributes: @@ -437,7 +437,7 @@ Each response entry in the results array contains the following attributes: joins | dictionary | [Joined object types](12-icinga2-api.md#icinga2-api-config-objects-query-joins) as key, attributes as nested dictionary. Disabled by default. meta | dictionary | Contains `used_by` object references. Disabled by default, enable it using `?meta=used_by` as URL parameter. -#### Object Query Joins +#### Object Query Joins Icinga 2 knows about object relations. For example it can optionally return information about the host when querying service objects. @@ -514,7 +514,7 @@ via a join: ] } -In case you want to fetch all [comments](9-object-types.md#objecttype-comment) +In case you want to fetch all [comments](09-object-types.md#objecttype-comment) for hosts and services, you can use the following query URL (similar example for downtimes): @@ -577,7 +577,7 @@ method: ] } -### Creating Config Objects +### Creating Config Objects New objects must be created by sending a PUT request. The following parameters need to be passed inside the JSON body: @@ -585,7 +585,7 @@ parameters need to be passed inside the JSON body: Parameters | Type | Description -----------|--------------|-------------------------- 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. @@ -639,21 +639,21 @@ Example for a new CheckCommand object: -d '{ "templates": [ "plugin-check-command" ], "attrs": { "command": [ "/usr/local/sbin/check_http" ], "arguments": { "-I": "$mytest_iparam$" } } }' -### Modifying Objects +### Modifying Objects 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 @@ -682,7 +682,7 @@ The following example updates the `address` attribute and the custom attribute ` } -### Deleting Objects +### Deleting Objects You can delete objects created using the API by sending a `DELETE` request. @@ -707,7 +707,7 @@ Example for deleting the host object `example.localdomain`: ] } -## Config Templates +## Config Templates Provides methods to manage configuration templates: @@ -715,7 +715,7 @@ Provides methods to manage configuration templates: Creation, modification and deletion of templates at runtime is not supported. -### Querying Templates +### Querying Templates You can request information about configuration templates by sending a `GET` query to the `/v1/templates/` URL endpoint. ` Variables +## Variables Provides methods to manage global variables: * [querying variables](12-icinga2-api.md#icinga2-api-variables-query) -### Querying Variables +### Querying Variables You can request information about global variables by sending a `GET` query to the `/v1/variables/` URL endpoint: @@ -772,7 +772,7 @@ URL path when querying a single variable: The result set contains the type, name and value of the global variable. -## Actions +## Actions There are several actions available for Icinga 2 provided by the `/v1/actions` URL endpoint. You can run actions by sending a `POST` request. @@ -792,7 +792,7 @@ called `app`. $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/objects/icingaapplications/app' -d '{ "attrs": { "enable_notifications": false } }' -### process-check-result +### process-check-result Process a check result for a host or a service. @@ -829,7 +829,7 @@ Example for using the `Host` type and filter by the host name: You can avoid URL encoding of white spaces in object names by using the `filter` attribute in the request body. -### reschedule-check +### reschedule-check Reschedule a check for hosts and services. The check can be forced if required. @@ -859,7 +859,7 @@ allowed for the service (`force_check=true`). } -### send-custom-notification +### send-custom-notification Send a custom notification for hosts and services. This notification type can be forced being sent to all users. @@ -892,7 +892,7 @@ host owners: } } -### delay-notification +### delay-notification Delay notifications for a host or a service. Note that this will only have an effect if the service stays in the same problem @@ -924,7 +924,7 @@ Example: } } -### acknowledge-problem +### acknowledge-problem 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`) @@ -962,7 +962,7 @@ a notification for them: } -### remove-acknowledgement +### remove-acknowledgement Removes the acknowledgements for services or hosts. Once the acknowledgement has been removed notifications will be sent out again. @@ -987,7 +987,7 @@ The example removes all service acknowledgements: } } -### add-comment +### add-comment Adds a `comment` from an `author` to services or hosts. @@ -1020,7 +1020,7 @@ The following example adds a comment for all `ping4` services: ] } -### remove-comment +### remove-comment Remove the comment using its `name` attribute , returns `OK` if the comment did not exist. @@ -1060,7 +1060,7 @@ Example for removing all service comments using a service name filter for `ping4 } -### schedule-downtime +### schedule-downtime Schedule a downtime for hosts and services. @@ -1072,9 +1072,9 @@ Send a `POST` request to the URL endpoint `/v1/actions/schedule-downtime`. comment | string | **Required.** Comment text. 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`. @@ -1099,7 +1099,7 @@ Example: ] } -### remove-downtime +### remove-downtime Remove the downtime using its `name` attribute , returns `OK` if the downtime did not exist. @@ -1156,7 +1156,7 @@ filter variables explained in the [advanced filters](12-icinga2-api.md#icinga2-a ] } -### shutdown-process +### shutdown-process Shuts down Icinga2. May or may not return. @@ -1177,7 +1177,7 @@ Example: ] } -### restart-process +### restart-process Restarts Icinga2. May or may not return. @@ -1198,9 +1198,9 @@ Example: ] } -### generate-ticket +### generate-ticket -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`. @@ -1224,7 +1224,7 @@ Example: } -## Event Streams +## Event Streams 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): @@ -1235,7 +1235,7 @@ The following parameters need to be specified (either as URL parameters or in a queue | string | **Required.** Unique queue name. Multiple HTTP clients can use the same queue as long as they use the same event types and filter. filter | string | **Optional.** Filter for specific event attributes using [filter expressions](12-icinga2-api.md#icinga2-api-filters). -### Event Stream Types +### Event Stream Types The following event stream types are available: @@ -1261,7 +1261,7 @@ Example for all downtime events: &types=DowntimeAdded&types=DowntimeRemoved&types=DowntimeTriggered -### Event Stream Filter +### Event Stream Filter Event streams can be filtered by attributes using the prefix `event.`. @@ -1275,7 +1275,7 @@ the string pattern "random\*": &types=CheckResult&filter=match%28%22random*%22,event.service%29 -### Event Stream Response +### Event Stream Response 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. @@ -1289,7 +1289,7 @@ Example: {"check_result":{ ... },"host":"example.localdomain","service":"ping4","timestamp":1445421329.7226390839,"type":"CheckResult"} -## Status and Statistics +## Status and Statistics Send a `GET` request to the URL endpoint `/v1/status` to retrieve status information and statistics for Icinga 2. @@ -1341,7 +1341,7 @@ You can limit the output by specifying a status type in the URL, e.g. `IcingaApp } -## Configuration Management +## Configuration Management The main idea behind configuration management is to allow external applications creating configuration packages and stages based on configuration files and @@ -1352,7 +1352,7 @@ validate the configuration asynchronously and populate a status log which can be fetched in a separated request. -### Creating a Config Package +### Creating a Config Package Send a `POST` request to a new config package called `example-cmdb` in this example. This will create a new empty configuration package. @@ -1371,7 +1371,7 @@ will create a new empty configuration package. Package names starting with an underscore are reserved for internal packages and must not be used. -### Uploading configuration for a Config Package +### Uploading configuration for a Config Package Configuration files in packages are managed in stages. Stages provide a way to maintain multiple configuration versions for a package. @@ -1386,7 +1386,7 @@ The file path requires one of these two directories inside its path: Directory | Description ------------|------------------------------------ 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: @@ -1438,7 +1438,7 @@ You can [fetch these files](12-icinga2-api.md#icinga2-api-config-management-fetc in order to verify that the new configuration was deployed successfully. -### List Configuration Packages and their Stages +### List Configuration Packages and their Stages A list of packages and their stages can be retrieved by sending a `GET` request to the URL endpoint `/v1/config/packages`. @@ -1459,7 +1459,7 @@ have an active stage. } -### List Configuration Packages and their Stages +### List Configuration Packages and their Stages 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 @@ -1492,7 +1492,7 @@ the package name (`example-cmdb`) and stage name (`example.localdomain-144162583 ] } -### Fetch Configuration Package Stage Files +### Fetch Configuration Package Stage Files 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. @@ -1510,7 +1510,7 @@ The following example fetches the configuration file `conf.d/test.conf`: You can fetch a [list of existing files](12-icinga2-api.md#icinga2-api-config-management-list-config-package-stage-files) in a configuration stage and then specifically request their content. -### Configuration Package Stage Errors +### Configuration Package Stage Errors 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. @@ -1536,7 +1536,7 @@ The output is similar to the manual [configuration validation](11-cli-commands.m > The returned output is plain-text instead of JSON-encoded. -### Deleting Configuration Package Stage +### Deleting Configuration Package Stage 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 @@ -1557,7 +1557,7 @@ in the `example-cmdb` configuration package: } -### Deleting Configuration Package +### Deleting Configuration Package In order to completely purge a configuration package and its stages you can send a `DELETE` request to the URL endpoint `/v1/config/packages` @@ -1578,7 +1578,7 @@ This example entirely deletes the configuration package `example-cmdb`: } -## Types +## Types You can retrieve the configuration object types by sending a `GET` request to URL endpoint `/v1/types`. @@ -1628,7 +1628,7 @@ In order to view a specific configuration object type specify its name inside th } -## Console +## Console 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`. @@ -1696,7 +1696,7 @@ similar fashion when pressing TAB inside the [console CLI command](11-cli-comman } -## API Clients +## API Clients There are a couple of existing clients which can be used with the Icinga 2 API: @@ -1713,7 +1713,7 @@ Demo cases: Additional [programmatic examples](12-icinga2-api.md#icinga2-api-clients-programmatic-examples) will help you getting started using the Icinga 2 API in your environment. -### Icinga Studio +### Icinga Studio Icinga Studio is a graphical application to query configuration objects provided by the API. @@ -1730,13 +1730,13 @@ packages. The Windows installer already includes Icinga Studio. On Debian and Ubuntu the package `icinga2-studio` can be used to install Icinga Studio. -### Icinga 2 Console +### Icinga 2 Console 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. -### API Clients Programmatic Examples +### API Clients Programmatic Examples The programmatic examples use HTTP basic authentication and SSL certificate verification. The CA file is expected in `pki/icinga2-ca.crt` @@ -1750,7 +1750,7 @@ and `joins` are therefore specified as array. The `filter` attribute [matches](18-library-reference.md#global-functions-match) on all services with `ping` in their name. -#### Example API Client in Python +#### Example API Client in Python The following example uses **Python** and the `requests` and `json` module: @@ -1794,7 +1794,7 @@ The following example uses **Python** and the `requests` and `json` module: $ python icinga2-api-example.py -#### Example API Client in Ruby +#### Example API Client in Ruby The following example uses **Ruby** and the `rest_client` gem: @@ -1843,7 +1843,7 @@ The following example uses **Ruby** and the `rest_client` gem: A more detailed example can be found in the [Dashing demo](https://github.com/Icinga/dashing-icinga2). -#### Example API Client in PHP +#### Example API Client in PHP The following example uses **PHP** and its `curl` library: @@ -1894,7 +1894,7 @@ The following example uses **PHP** and its `curl` library: $ php icinga2-api-example.php -#### Example API Client in Perl +#### Example API Client in Perl The following example uses **Perl** and the `Rest::Client` module: diff --git a/doc/13-addons.md b/doc/13-addons.md index 42ec0658b..1d26de747 100644 --- a/doc/13-addons.md +++ b/doc/13-addons.md @@ -1,8 +1,8 @@ -# Icinga 2 Addons +# Icinga 2 Addons -## Graphing +## Graphing -### PNP +### PNP [PNP](https://www.pnp4nagios.org) is a graphing addon. @@ -33,7 +33,7 @@ More information on [action_url as attribute](13-addons.md#addons-graphing-pnp-a and [graph template names](13-addons.md#addons-graphing-pnp-custom-templates). -### Graphite +### Graphite [Graphite](https://graphite.readthedocs.org/en/latest/) is a time-series database storing collected metrics and making them available through restful apis @@ -54,7 +54,7 @@ There are Graphite addons available for collecting the performance data files to A popular alternative frontend for Graphite is for example [Grafana](https://grafana.org). -### InfluxDB +### InfluxDB [InfluxDB](https://influxdb.com) is a time series, metrics, and analytics database. It’s written in Go and has no external dependencies. @@ -66,14 +66,14 @@ for sending real-time metrics from Icinga 2 to InfluxDB. A popular frontend for InfluxDB is for example [Grafana](https://grafana.org). -## Visualization +## Visualization -### Icinga Reporting +### Icinga Reporting 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). -### NagVis +### NagVis 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 @@ -87,12 +87,12 @@ The configuration in nagvis.ini.php should look like this for Livestatus for exa If you are planning an integration into Icinga Web 2, look at [this module](https://github.com/Icinga/icingaweb2-module-nagvis). -### Thruk +### Thruk [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. -## Log Monitoring +## Log Monitoring 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 @@ -104,11 +104,11 @@ is even simpler these days. More details can be found in [this blog post](https://www.icinga.com/2014/12/02/team-icinga-at-osmc-2014/). -## Notification Scripts and Interfaces +## Notification Scripts and Interfaces 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 @@ -124,7 +124,7 @@ Additionally external services can be [integrated with Icinga 2](https://www.ici More information can be found on the [Icinga Website](https://www.icinga.com/). -## Configuration Management Tools +## Configuration Management Tools 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 @@ -139,9 +139,9 @@ These tools are currently in development and require feedback and tests: * [Puppet Module](https://github.com/Icinga/puppet-icinga2) * [Chef Cookbook](https://github.com/Icinga/chef-icinga2) -## More Addon Integration Hints +## More Addon Integration Hints -### PNP Action Url +### PNP Action Url 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). @@ -154,7 +154,7 @@ the action url attribute in its own module). action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$" } -### PNP Custom Templates with Icinga 2 +### PNP Custom Templates with Icinga 2 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 diff --git a/doc/14-features.md b/doc/14-features.md index 80cedcc8b..f99f7a757 100644 --- a/doc/14-features.md +++ b/doc/14-features.md @@ -1,6 +1,6 @@ -# Icinga 2 Features +# Icinga 2 Features -## Logging +## Logging Icinga 2 supports three different types of logging: @@ -25,18 +25,18 @@ Packages will install a configuration file for logrotate on supported platforms. This configuration ensures that the `icinga2.log`, `error.log` and `debug.log` files are rotated on a daily basis. -## DB IDO +## DB IDO 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 @@ -47,7 +47,7 @@ the query returns an empty result. > **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. @@ -81,7 +81,7 @@ Example for PostgreSQL: A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](23-appendix.md#schema-db-ido). -## External Commands +## External Commands Icinga 2 provides an external command pipe for processing commands triggering specific actions (for example rescheduling a service check @@ -111,7 +111,7 @@ A list of currently supported external commands can be found [here](23-appendix. Detailed information on the commands and their required parameters can be found on the [Icinga 1.x documentation](https://docs.icinga.com/latest/en/extcommands2.html). -## Performance Data +## Performance Data When a host or service check is executed plugins should provide so-called `performance data`. Next to that additional check performance data @@ -125,12 +125,12 @@ reporting and trending. Well-known addons processing Icinga performance data are [PNP4Nagios](13-addons.md#addons-graphing-pnp), [Graphite](13-addons.md#addons-graphing-graphite) or [OpenTSDB](14-features.md#opentsdb-writer). -### Writing Performance Data Files +### Writing Performance Data Files 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. @@ -148,7 +148,7 @@ the `/var/spool/icinga2/perfdata/` directory as `host-perfdata.` and External collectors need to parse the rotated performance data files and then remove the processed files. -### Graphite Carbon Cache Writer +### Graphite Carbon Cache Writer 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 @@ -160,16 +160,16 @@ You can enable the feature using # 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`. -#### Current Graphite Schema +#### Current Graphite Schema 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$ @@ -249,7 +249,7 @@ Cache. pattern = ^icinga2\. retentions = 1m:2d,5m:10d,30m:90d,360m:4y -#### Graphite Schema < 2.4 +#### Graphite Schema < 2.4 > **Note** > @@ -274,9 +274,9 @@ The old legacy naming schema is You can customize the metric prefix name by using the `host_name_template` and `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" @@ -322,7 +322,7 @@ Cache. Please make sure that the order is correct because the first match wins. pattern = ^icinga\. retentions = 1m:2d,5m:10d,30m:90d,360m:4y -### InfluxDB Writer +### InfluxDB Writer Once there are new metrics available, Icinga 2 will directly write them to the defined InfluxDB HTTP API. @@ -331,14 +331,14 @@ You can enable the feature using # 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). -### Graylog Integration +### Graylog Integration -#### GELF Writer +#### GELF Writer 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. @@ -360,7 +360,7 @@ Currently these events are processed: * State changes * Notifications -### Elastic Stack Integration +### Elastic Stack Integration [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. @@ -369,7 +369,7 @@ More integrations in development: * [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. -### OpenTSDB Writer +### OpenTSDB Writer 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 @@ -434,7 +434,7 @@ with the following tags > in your opentsdb.conf configuration file. -## Livestatus +## Livestatus The [MK Livestatus](https://mathias-kettner.de/checkmk_livestatus.html) project implements a query protocol that lets users query their Icinga instance for @@ -443,7 +443,7 @@ status information. It can also be used to send commands. > **Tip** > > 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 @@ -487,17 +487,17 @@ are expected to be in `/var/log/icinga2/compat`. A different path can be set usi # icinga2 feature enable compatlog -### Livestatus Sockets +### Livestatus Sockets 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. -### Livestatus GET Queries +### Livestatus GET Queries > **Note** > @@ -525,14 +525,14 @@ Example using the tcp socket listening on port `6558`: (cat servicegroups; sleep 1) | netcat 127.0.0.1 6558 -### Livestatus COMMAND Queries +### Livestatus COMMAND Queries A list of available external commands and their parameters can be found [here](23-appendix.md#external-commands-list-detail) $ echo -e 'COMMAND ' | netcat 127.0.0.1 6558 -### Livestatus Filters +### Livestatus Filters and, or, negate @@ -548,7 +548,7 @@ and, or, negate >= | | Greater than or equal -### Livestatus Stats +### Livestatus Stats Schema: "Stats: aggregatefunction aggregateattribute" @@ -580,7 +580,7 @@ Example: OutputFormat: json ResponseHeader: fixed16 -### Livestatus Output +### Livestatus Output * CSV @@ -596,7 +596,7 @@ Separators can be set using ASCII codes like: Default separators. -### Livestatus Error Codes +### Livestatus Error Codes Code | Description ----------|-------------- @@ -604,7 +604,7 @@ Default separators. 404 | Table does not exist 452 | Exception on query -### Livestatus Tables +### Livestatus Tables Table | Join |Description --------------|-----------|---------------------------- @@ -620,8 +620,8 @@ Default separators. 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 @@ -631,7 +631,7 @@ The `commands` table is populated with `CheckCommand`, `EventCommand` and `Notif A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](23-appendix.md#schema-livestatus). -## Status Data Files +## Status Data Files 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 @@ -648,7 +648,7 @@ Icinga 1.x Classic UI requires this data set as part of its backend. > you can safely disable this feature. -## Compat Log Files +## Compat Log Files The Icinga 1.x log format is considered being the `Compat Log` in Icinga 2 provided with the `CompatLogger` object. @@ -695,7 +695,7 @@ existing log parsers. [1382115731] SERVICE ALERT: localhost;ping6;CRITICAL;SOFT;2;critical test -## Check Result Files +## Check Result Files Icinga 1.x writes its check result files to a temporary spool directory where they are processed in a regular interval. diff --git a/doc/15-troubleshooting.md b/doc/15-troubleshooting.md index 2437e6e7e..884d355d1 100644 --- a/doc/15-troubleshooting.md +++ b/doc/15-troubleshooting.md @@ -1,6 +1,6 @@ -# Icinga 2 Troubleshooting +# Icinga 2 Troubleshooting -## Required Information +## Required Information 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 @@ -22,8 +22,8 @@ findings and details please. * [Icinga Web 2 modules](https://www.icinga.com/products/icinga-web-2-modules/) e.g. the Icinga Director (optional) * 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` @@ -31,7 +31,7 @@ findings and details please. * 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 -## Analyze your Environment +## Analyze your Environment There are many components involved on a server running Icinga 2. When you analyze a problem, keep in mind that basic system administration knowledge @@ -39,7 +39,7 @@ is also key to identify bottlenecks and issues. > **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.). @@ -48,7 +48,7 @@ is also key to identify bottlenecks and issues. Install tools which help you to do so. Opinions differ, let us know if you have any additions here! -### Analyse your Linux/Unix Environment +### Analyse your Linux/Unix Environment [htop](https://hisham.hm/htop/) is a better replacement for `top` and helps to analyze processes interactively. @@ -99,7 +99,7 @@ sar -b //I/O If you are missing checks and metrics found in your analysis, add them to your monitoring! -### Analyze your Windows Environment +### Analyze your Windows Environment A good tip for Windows are the tools found inside the [Sysinternals Suite](https://technet.microsoft.com/en-us/sysinternals/bb842062.aspx). @@ -107,9 +107,9 @@ You can also start `perfmon` and analyze specific performance counters. Keep notes which could be important for your monitoring, and add service checks later on. -## Enable Debug Output +## Enable Debug Output -### Enable Debug Output on Linux/Unix +### Enable Debug Output on Linux/Unix Enable the `debuglog` feature: @@ -123,10 +123,10 @@ log severity as an additional parameter argument to `-x`. # /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`. -### Enable Debug Output on Windows +### Enable Debug Output on Windows Open a command prompt with administrative privileges and enable the debug log feature. @@ -138,7 +138,7 @@ Restart the Icinga 2 service and open the newly created `debug.log` file. C:> net stop icinga2 C:> net start icinga2 -## List Configuration Objects +## List Configuration Objects 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. @@ -210,7 +210,7 @@ are not immediately updated. Furthermore there is a known issue with You need to restart Icinga 2 in order to update the `icinga2.debug` cache file. -## Where are the check command definitions? +## Where are the check command definitions? Icinga 2 features a number of built-in [check command definitions](10-icinga-template-library.md#plugin-check-commands) which are included with @@ -218,16 +218,16 @@ included with include include -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. -## Checks +## Checks -### Executed Command for Checks +### Executed Command for Checks * 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. @@ -287,7 +287,7 @@ Example for searching the debug log: # tail -f /var/log/icinga2/debug.log | grep "notice/Process" -### Checks are not executed +### Checks are not executed * Check the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) to see if the check command gets executed. * Verify that failed depedencies do not prevent command execution. @@ -307,7 +307,7 @@ Fetch all check result events matching the `event.service` name `random`: $ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/events?queue=debugchecks&types=CheckResult&filter=match%28%22random*%22,event.service%29' -### Check Fork Errors +### Check Fork Errors 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 @@ -335,7 +335,7 @@ or set it to `infinity`: Please note that this setting is available since Systemd version 226. -### Late Check Results +### Late Check Results [Icinga Web 2](https://www.icinga.com/products/icinga-web-2/) provides a dashboard overview for `overdue checks`. @@ -379,7 +379,7 @@ and repeat the commands. More details about the Icinga 2 DSL and its possibilities can be found in the [language](17-language-reference.md#language-reference) and [library](18-library-reference.md#library-reference) reference chapters. -### Late Check Results in Distributed Environments +### Late Check Results in Distributed Environments 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 @@ -397,7 +397,7 @@ found a bug in the cluster. If you are running a cluster setup where the master/satellite executes checks on the client via -[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 @@ -414,7 +414,7 @@ service check result output and their state is `UNKNOWN`. The result set shows the configured zones and their affected hosts in a unique list. The output also just prints the numbers but you can adjust this by omitting the `len()` call inside the for loop. -## Notifications are not sent +## Notifications are not sent * 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. @@ -426,14 +426,14 @@ to any question or issue posted to the community channels. 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. @@ -448,14 +448,14 @@ You can use the Icinga 2 API [event streams](12-icinga2-api.md#icinga2-api-event $ curl -k -s -u root:icinga -X POST 'https://localhost:5665/v1/events?queue=debugnotifications&types=Notification' -## Feature is not working +## Feature is not working * 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 @@ -463,18 +463,18 @@ Example for the `graphite` feature: # icinga2 object list --type GraphiteWriter -## Configuration is ignored +## Configuration is ignored * 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 -## Configuration attributes are inherited from +## Configuration attributes are inherited from 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 @@ -482,10 +482,10 @@ or modify these attributes in the current object. The [object list](15-troubleshooting.md#list-configuration-objects) CLI command allows you to verify the attribute origin. -## Configuration Value with Single Dollar Sign +## Configuration Value with Single Dollar Sign 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}'. @@ -493,11 +493,11 @@ Correct the custom attribute value to "top-syntax=$${list}" -## Cluster and Clients Troubleshooting +## Cluster and Clients Troubleshooting -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** @@ -505,7 +505,7 @@ done so already. > Some problems just exist due to wrong file permissions or applied packet filters. Make > sure to check these in the first place. -### Cluster Troubleshooting Connection Errors +### Cluster Troubleshooting Connection Errors General connection errors could be one of the following problems: @@ -522,7 +522,7 @@ works (default port is `5665`). # nmap yourclusternode.localdomain -### Cluster Troubleshooting SSL Errors +### Cluster Troubleshooting SSL Errors If the cluster communication fails with SSL error messages, make sure to check the following @@ -565,7 +565,7 @@ Try to manually connect from `icinga2-node2.localdomain` to the master node `ici If the connection attempt fails or your CA does not match, [verify the master and client certificates](15-troubleshooting.md#troubleshooting-cluster-ssl-certificate-verification). -#### Cluster Troubleshooting Unauthenticated Clients +#### Cluster Troubleshooting Unauthenticated Clients Unauthenticated nodes are able to connect. This is required for client setups. @@ -579,7 +579,7 @@ Client as command execution bridge: If these messages do not go away, make sure to [verify the master and client certificates](15-troubleshooting.md#troubleshooting-cluster-ssl-certificate-verification). -#### Cluster Troubleshooting SSL Certificate Verification +#### Cluster Troubleshooting SSL Certificate Verification 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**. @@ -597,7 +597,7 @@ Fetch the `ca.crt` file from the client node and compare it to your master's `ca On SLES11 you'll need to use the `openssl1` command instead of `openssl`. -### Cluster Troubleshooting Message Errors +### Cluster Troubleshooting Message Errors 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, @@ -606,16 +606,16 @@ they remain in a Split-Brain-mode and history may differ. Although the Icinga 2 cluster protocol stores historical events in a [replay log](15-troubleshooting.md#troubleshooting-cluster-replay-log) for later synchronisation, you should make sure to check why the network connection failed. -### Cluster Troubleshooting Command Endpoint Errors +### Cluster Troubleshooting Command Endpoint Errors -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. @@ -631,7 +631,7 @@ Fetch all check result events matching the `event.service` name `remote-client`: -### Cluster Troubleshooting Config Sync +### Cluster Troubleshooting Config Sync If the cluster zones do not sync their configuration, make sure to check the following: @@ -639,24 +639,24 @@ If the cluster zones do not sync their configuration, make sure to check the fol ** The master syncs the configuration to `/var/lib/icinga2/api/zones/` during startup and only syncs valid configuration to the other nodes. ** The 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. -### Cluster Troubleshooting Overdue Check Results +### Cluster Troubleshooting Overdue Check Results 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 @@ -674,7 +674,7 @@ in on the master: Discarding 'check result' message from 'icinga2b': Unauthorized access. -### Cluster Troubleshooting Replay Log +### Cluster Troubleshooting Replay Log 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 @@ -682,7 +682,7 @@ will store all events for not connected endpoints in the same and child zones. 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). diff --git a/doc/16-upgrading-icinga-2.md b/doc/16-upgrading-icinga-2.md index e3f8a506b..bc7732acb 100644 --- a/doc/16-upgrading-icinga-2.md +++ b/doc/16-upgrading-icinga-2.md @@ -1,9 +1,9 @@ -# Upgrading Icinga 2 +# Upgrading Icinga 2 Upgrading Icinga 2 is usually quite straightforward. Ordinarily the only manual steps involved are scheme updates for the IDO database. -## Upgrading the MySQL database +## Upgrading the MySQL database 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. @@ -29,7 +29,7 @@ the *upgrade* directory: There are two new upgrade files called `2.1.0.sql`, `2.2.0.sql` and `2.3.0.sql` which must be applied incrementally to your IDO database. -## Upgrading the PostgreSQL database +## Upgrading the PostgreSQL database 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. diff --git a/doc/17-language-reference.md b/doc/17-language-reference.md index 989d9ae48..4f7cee061 100644 --- a/doc/17-language-reference.md +++ b/doc/17-language-reference.md @@ -1,6 +1,6 @@ -# Language Reference +# Language Reference -## Object Definition +## Object Definition Icinga 2 features an object-based configuration format. You can define new objects using the `object` keyword: @@ -43,11 +43,11 @@ Attribute | Description name | The name of the object. This attribute can be modified in the object definition to override the name specified with the `object` directive. type | The type of the object. -## Expressions +## Expressions The following expressions can be used on the right-hand side of assignments. -### Numeric Literals +### Numeric Literals A floating-point number. @@ -55,7 +55,7 @@ Example: 27.3 -### Duration Literals +### Duration Literals Similar to floating-point numbers except for the fact that they support suffixes to help with specifying time durations. @@ -70,7 +70,7 @@ h (hours) and d (days). Duration literals are converted to seconds by the config parser and are treated like numeric literals. -### String Literals +### String Literals A string. @@ -78,7 +78,7 @@ Example: "Hello World!" -#### String Literals Escape Sequences +#### String Literals Escape Sequences Certain characters need to be escaped. The following escape sequences are supported: @@ -97,7 +97,7 @@ In addition to these pre-defined escape sequences you can specify arbitrary ASCII characters using the backslash character (\\) followed by an ASCII character in octal encoding. -### Multi-line String Literals +### Multi-line String Literals Strings spanning multiple lines can be specified by enclosing them in {{{ and }}}. @@ -112,15 +112,15 @@ Example: Unlike in ordinary strings special characters do not have to be escaped in multi-line string literals. -### Boolean Literals +### Boolean Literals The keywords `true` and `false` are used to denote truth values. -### Null Value +### Null Value The `null` keyword can be used to specify an empty value. -### Dictionary +### Dictionary An unordered list of key-value pairs. Keys must be unique and are compared in a case-sensitive manner. @@ -140,7 +140,7 @@ with certain characters (e.g. digits). If you want to use a dictionary key that is not a valid identifier, you can enclose the key in double quotes. -### Array +### Array An ordered list of values. @@ -154,7 +154,7 @@ Example: An array may simultaneously contain values of different types, such as strings and numbers. -### Operators +### Operators The following operators are supported in expressions. The operators are by descending precedence. @@ -191,7 +191,7 @@ in | 7 | "foo" in [ "foo", "bar" ] (true) | Element = | 12 | a = 3 | Assignment => | 15 | x => x * x (function with arg x) | Lambda, for loop -### Function Calls +### Function Calls Functions can be called using the `()` operator: @@ -203,13 +203,13 @@ Functions can be called using the `()` operator: A list of available functions is available in the [Library Reference](18-library-reference.md#library-reference) chapter. -## Assignments +## Assignments 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: -### Operator = +### Operator = Sets an attribute to the specified value. @@ -222,7 +222,7 @@ Example: In this example `a` has the value `7` after both instructions are executed. -### Operator += +### Operator += The += operator is a shortcut. The following expression: @@ -238,7 +238,7 @@ is equivalent to: a = a + [ "world" ] } -### Operator -= +### Operator -= The -= operator is a shortcut. The following expression: @@ -254,7 +254,7 @@ is equivalent to: a = a - 5 } -### Operator \*= +### Operator \*= The *= operator is a shortcut. The following expression: @@ -270,7 +270,7 @@ is equivalent to: a = a * 5 } -### Operator /= +### Operator /= The /= operator is a shortcut. The following expression: @@ -286,7 +286,7 @@ is equivalent to: a = a / 5 } -## Indexer +## Indexer The indexer syntax provides a convenient way to set dictionary elements. @@ -312,7 +312,7 @@ This is equivalent to writing: If the `hello` attribute does not already have a value, it is automatically initialized to an empty dictionary. -## Template Imports +## Template Imports Objects can import attributes from other objects. @@ -359,7 +359,7 @@ object definition is evaluated. If there are multiple default templates the order in which they are imported is unspecified. -## Constants +## Constants Global constants can be set using the `const` keyword: @@ -368,7 +368,7 @@ Global constants can be set using the `const` keyword: Once defined a constant can be accessed from any file. Constants cannot be changed once they are set. -### Icinga 2 Specific Constants +### Icinga 2 Specific Constants Icinga 2 provides a number of special global constants. Some of them can be overridden using the `--define` command line parameter: @@ -406,7 +406,7 @@ RLimitFiles |**Read-write.** Defines the resource limit for RLIMIT_NOFIL RLimitProcesses |**Read-write.** Defines the resource limit for RLIMIT_NPROC that should be set at start-up. Value cannot be set lower than the default `16 * 1024`. 0 disables the setting. Used in the `init.conf` configuration file. 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. -## Apply +## Apply The `apply` keyword can be used to create new objects which are associated with another group of objects. @@ -444,10 +444,10 @@ Any valid config attribute can be accessed using the `host` and `service` variables. For example, `host.address` would return the value of the host's "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. -## Apply For +## Apply For [Apply](17-language-reference.md#apply) rules can be extended with the [for loop](17-language-reference.md#for-loops) keyword. @@ -477,10 +477,10 @@ and afterwards the `assign where` and `ignore where` conditions are evaluated. It is not necessary to check attributes referenced in the `for loop` expression 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. -## Group Assign +## Group Assign Group objects can be assigned to specific member objects using the `assign where` and `ignore where` conditions. @@ -504,7 +504,7 @@ ServiceGroup | host, service UserGroup | user -## Boolean Values +## Boolean Values 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 @@ -525,7 +525,7 @@ Non-empty dictionary | { key = "value" } | true For a list of supported expression operators for `assign where` and `ignore where` statements, see [expression operators](17-language-reference.md#expression-operators). -## Comments +## Comments The Icinga 2 configuration format supports C/C++-style and shell-style comments. @@ -539,7 +539,7 @@ Example: retry_interval = 15 # yet another comment } -## Includes +## Includes Other configuration files can be included using the `include` directive. Paths must be relative to the configuration file that contains the @@ -565,7 +565,7 @@ paths. Additional include search paths can be added using Wildcards are not permitted when using angle brackets. -## Recursive Includes +## Recursive Includes The `include_recursive` directive can be used to recursively include all files in a directory which match a certain pattern. @@ -581,7 +581,7 @@ recursively included. The file names need to match the pattern given in the second parameter. When no pattern is specified the default pattern "*.conf" is used. -## Zone Includes +## Zone Includes The `include_zones` recursively includes all subdirectories for the given path. @@ -604,7 +604,7 @@ The second parameter specifies the directory which contains the subdirectories. The file names need to match the pattern given in the third parameter. When no pattern is specified the default pattern "*.conf" is used. -## Library directive +## Library directive The `library` directive can be used to manually load additional libraries. Libraries can be used to provide additional object types and @@ -614,7 +614,7 @@ Example: library "snmphelper" -## Functions +## Functions Functions can be defined using the `function` keyword. @@ -650,7 +650,7 @@ resulting function object can be used like any other value: fn() /* Returns 3 */ -## Lambda Expressions +## Lambda Expressions Functions can also be declared using the alternative lambda syntax. @@ -671,7 +671,7 @@ For lambdas which take exactly one argument the braces around the arguments can f = x => x * x -## Abbreviated Lambda Syntax +## Abbreviated Lambda Syntax Lambdas which take no arguments can also be written using the abbreviated lambda syntax. @@ -681,7 +681,7 @@ Example: This creates a new function which returns the value 3. -## Variable Scopes +## Variable Scopes When setting a variable Icinga checks the following scopes in this order whether the variable already exists there: @@ -745,7 +745,7 @@ a function is set to whichever object was used to invoke the function. Here's an We're using `hm.init` to invoke the function which causes the value of `hm` to become the `this` scope for this function call. -## Closures +## Closures By default `function`s, `object`s and `apply` rules do not have access to variables declared outside of their scope (except for global variables). @@ -769,7 +769,7 @@ Alternatively a different value for the inner variable can be specified: } } -## Conditional Statements +## Conditional Statements Sometimes it can be desirable to only evaluate statements when certain conditions are met. The if/else construct can be used to accomplish this. @@ -801,7 +801,7 @@ This example prints the log message "Taking the 'true' branch" and the `a` varia The value of an if/else construct is null if the condition evaluates to false and no else branch is given. -## While Loops +## While Loops 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. @@ -819,7 +819,7 @@ The `continue` and `break` keywords can be used to control how the loop is execu skips over the remaining expressions for the loop body and begins the next loop evaluation. The `break` keyword breaks out of the loop. -## For Loops +## For Loops The `for` statement can be used to iterate over arrays and dictionaries. @@ -846,7 +846,7 @@ The `continue` and `break` keywords can be used to control how the loop is execu skips over the remaining expressions for the loop body and begins the next loop evaluation. The `break` keyword breaks out of the loop. -## Constructors +## Constructors In order to create a new value of a specific type constructor calls may be used. @@ -862,7 +862,7 @@ Example: var s = String(3) /* Sets s to "3". */ -## Throwing Exceptions +## Throwing Exceptions Built-in commands may throw exceptions to signal errors such as invalid arguments. User scripts can throw exceptions using the `throw` keyword. @@ -871,7 +871,7 @@ Example: throw "An error occurred." -## Handling Exceptions +## Handling Exceptions 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. @@ -886,13 +886,13 @@ Example: log("An error occurred in the try clause.") } -## Breakpoints +## Breakpoints 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. -## Types +## Types All values have a static type. The `typeof` function can be used to determine the type of a value: @@ -909,7 +909,7 @@ Array | [ "a", "b" ] | An array. Dictionary | { a = 3 } | A dictionary. 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 @@ -927,7 +927,7 @@ supports: Additional documentation on type methods is available in the [library reference](18-library-reference.md#library-reference). -## Location Information +## Location Information The location of the currently executing script can be obtained using the `current_filename` and `current_line` keywords. @@ -936,7 +936,7 @@ Example: log("Hello from '" + current_filename + "' in line " + current_line) -## Reserved Keywords +## Reserved Keywords These keywords are reserved and must not be used as constants or custom attributes. diff --git a/doc/18-library-reference.md b/doc/18-library-reference.md index 9a545cfaa..5d79d00e4 100644 --- a/doc/18-library-reference.md +++ b/doc/18-library-reference.md @@ -1,8 +1,8 @@ -# Library Reference +# Library Reference -## Global functions +## Global functions -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). @@ -10,7 +10,7 @@ You can use the [Icinga 2 debug console](11-cli-commands.md#cli-command-console) as a sandbox to test these functions before implementing them in your scenarios. -### regex +### regex Signature: @@ -33,7 +33,7 @@ Example: <3> => regex("^Linux$", host.vars.os_type) false -### match +### match Signature: @@ -56,7 +56,7 @@ Example: <4> => match("NUE-*-DEV-*", host.display_name) false -### cidr_match +### cidr_match Signature: @@ -80,7 +80,7 @@ Example: <3> => cidr_match("192.168.56.0/26", host.address) false -### range +### range Signature: @@ -109,7 +109,7 @@ Example: <3> => range(2,10,2) [ 2.000000, 4.000000, 6.000000, 8.000000 ] -### len +### len Signature: @@ -142,7 +142,7 @@ Example: 10.000000 -### union +### union Signature: @@ -161,7 +161,7 @@ Example: <3> => union(dev_notification_groups, host_notification_groups) [ "devs", "noc", "slack" ] -### intersection +### intersection Signature: @@ -181,7 +181,7 @@ Example: <3> => intersection(dev_notification_groups, host_notification_groups) [ "slack" ] -### keys +### keys Signature: @@ -203,7 +203,7 @@ Example: <3> => host.vars.disks.keys() [ "/", "/var" ] -### string +### string Signature: @@ -237,7 +237,7 @@ Example: <6> => DateTime(2016, 11, 25).to_string() "2016-11-25 00:00:00 +0100" -### number +### number Signature: @@ -254,7 +254,7 @@ Example: <2> => number("78") 78.000000 -### bool +### bool Signature: @@ -271,7 +271,7 @@ Example: <2> => bool(0) false -### random +### random Signature: @@ -286,7 +286,7 @@ Returns a random value between 0 and RAND\_MAX (as defined in stdlib.h). <2> => random() 108402530.000000 -### log +### log Signature: @@ -316,7 +316,7 @@ Example: critical/Console: ["devs","slack"] null -### typeof +### typeof Signature: @@ -339,7 +339,7 @@ Example: <5> => typeof({ a = 2, b = 3 }) == Dictionary true -### get_time +### get_time Signature: @@ -356,7 +356,7 @@ Example: <2> => get_time() 1480072140.401207 -### parse_performance_data +### parse_performance_data Signature: @@ -383,7 +383,7 @@ Example: warn = null } -### dirname +### dirname Signature: @@ -400,7 +400,7 @@ Example: <2> => dirname(path) "/etc/icinga2/scripts" -### basename +### basename Signature: @@ -417,7 +417,7 @@ Example: <2> => basename(path) "xmpp-notification.pl" -### escape_shell_arg +### escape_shell_arg Signature: @@ -432,7 +432,7 @@ Example: <1> => escape_shell_arg("'$host.name$' '$service.name$'") "''\\''$host.name$'\\'' '\\''$service.name$'\\'''" -### escape_shell_cmd +### escape_shell_cmd Signature: @@ -447,7 +447,7 @@ Example: <1> => escape_shell_cmd("/bin/echo 'shell test' $ENV") "/bin/echo 'shell test' \\$ENV" -### escape_create_process_arg +### escape_create_process_arg Signature: @@ -455,7 +455,7 @@ Signature: Escapes a string for use as an argument for CreateProcess(). Windows only. -### sleep +### sleep Signature: @@ -463,11 +463,11 @@ Signature: Sleeps for the specified amount of time (in seconds). -## Object Accessor Functions +## Object Accessor Functions These functions can be used to retrieve a reference to another object by name. -### get_check_command +### get_check_command Signature: @@ -475,7 +475,7 @@ Signature: Returns the CheckCommand object with the specified name, or `null` if no such CheckCommand object exists. -### get_event_command +### get_event_command Signature: @@ -483,7 +483,7 @@ Signature: Returns the EventCommand object with the specified name, or `null` if no such EventCommand object exists. -### get_notification_command +### get_notification_command Signature: @@ -491,7 +491,7 @@ Signature: Returns the NotificationCommand object with the specified name, or `null` if no such NotificationCommand object exists. -### get_host +### get_host Signature: @@ -500,7 +500,7 @@ Signature: Returns the Host object with the specified name, or `null` if no such Host object exists. -### get_service +### get_service Signature: @@ -509,7 +509,7 @@ Signature: Returns the Service object with the specified name, or `null` if no such Service object exists. -### get_user +### get_user Signature: @@ -517,7 +517,7 @@ Signature: Returns the User object with the specified name, or `null` if no such User object exists. -### get_host_group +### get_host_group Signature: @@ -526,7 +526,7 @@ Signature: Returns the HostGroup object with the specified name, or `null` if no such HostGroup object exists. -### get_service_group +### get_service_group Signature: @@ -534,7 +534,7 @@ Signature: Returns the ServiceGroup object with the specified name, or `null` if no such ServiceGroup object exists. -### get_user_group +### get_user_group Signature: @@ -543,7 +543,7 @@ Signature: Returns the UserGroup object with the specified name, or `null` if no such UserGroup object exists. -### get_time_period +### get_time_period Signature: @@ -552,7 +552,7 @@ Signature: Returns the TimePeriod object with the specified name, or `null` if no such TimePeriod object exists. -### get_object +### get_object Signature: @@ -562,7 +562,7 @@ Returns the object with the specified type and name, or `null` if no such object to a type object. -### get_objects +### get_objects Signature: @@ -572,40 +572,40 @@ Returns an array of objects whose type matches the specified type. `type` must r to a type object. -## Math object +## Math object The global `Math` object can be used to access a number of mathematical constants and functions. -### Math.E +### Math.E Euler's constant. -### Math.LN2 +### Math.LN2 Natural logarithm of 2. -### Math.LN10 +### Math.LN10 Natural logarithm of 10. -### Math.LOG2E +### Math.LOG2E Base 2 logarithm of E. -### Math.PI +### Math.PI The mathematical constant Pi. -### Math.SQRT1_2 +### Math.SQRT1_2 Square root of 1/2. -### Math.SQRT2 +### Math.SQRT2 Square root of 2. -### Math.abs +### Math.abs Signature: @@ -613,7 +613,7 @@ Signature: Returns the absolute value of `x`. -### Math.acos +### Math.acos Signature: @@ -621,7 +621,7 @@ Signature: Returns the arccosine of `x`. -### Math.asin +### Math.asin Signature: @@ -629,7 +629,7 @@ Signature: Returns the arcsine of `x`. -### Math.atan +### Math.atan Signature: @@ -637,7 +637,7 @@ Signature: Returns the arctangent of `x`. -### Math.atan2 +### Math.atan2 Signature: @@ -645,7 +645,7 @@ Signature: Returns the arctangent of the quotient of `y` and `x`. -### Math.ceil +### Math.ceil Signature: @@ -653,7 +653,7 @@ Signature: Returns the smallest integer value not less than `x`. -### Math.cos +### Math.cos Signature: @@ -661,7 +661,7 @@ Signature: Returns the cosine of `x`. -### Math.exp +### Math.exp Signature: @@ -669,7 +669,7 @@ Signature: Returns E raised to the `x`th power. -### Math.floor +### Math.floor Signature: @@ -677,7 +677,7 @@ Signature: Returns the largest integer value not greater than `x`. -### Math.isinf +### Math.isinf Signature: @@ -685,7 +685,7 @@ Signature: Returns whether `x` is infinite. -### Math.isnan +### Math.isnan Signature: @@ -693,7 +693,7 @@ Signature: Returns whether `x` is NaN (not-a-number). -### Math.log +### Math.log Signature: @@ -701,7 +701,7 @@ Signature: Returns the natural logarithm of `x`. -### Math.max +### Math.max Signature: @@ -710,7 +710,7 @@ Signature: Returns the largest argument. A variable number of arguments can be specified. If no arguments are given, -Infinity is returned. -### Math.min +### Math.min Signature: @@ -719,7 +719,7 @@ Signature: Returns the smallest argument. A variable number of arguments can be specified. If no arguments are given, +Infinity is returned. -### Math.pow +### Math.pow Signature: @@ -727,7 +727,7 @@ Signature: Returns `x` raised to the `y`th power. -### Math.random +### Math.random Signature: @@ -735,7 +735,7 @@ Signature: Returns a pseudo-random number between 0 and 1. -### Math.round +### Math.round Signature: @@ -743,7 +743,7 @@ Signature: Returns `x` rounded to the nearest integer value. -### Math.sign +### Math.sign Signature: @@ -752,7 +752,7 @@ Signature: Returns -1 if `x` is negative, 1 if `x` is positive and 0 if `x` is 0. -### Math.sin +### Math.sin Signature: @@ -760,7 +760,7 @@ Signature: Returns the sine of `x`. -### Math.sqrt +### Math.sqrt Signature: @@ -768,7 +768,7 @@ Signature: Returns the square root of `x`. -### Math.tan +### Math.tan Signature: @@ -776,11 +776,11 @@ Signature: Returns the tangent of `x`. -## Json object +## Json object The global `Json` object can be used to encode and decode JSON. -### Json.encode +### Json.encode Signature: @@ -788,7 +788,7 @@ Signature: Encodes an arbitrary value into JSON. -### Json.decode +### Json.decode Signature: @@ -796,9 +796,9 @@ Signature: Decodes a JSON string. -## Number type +## Number type -### Number#to_string +### Number#to_string Signature: @@ -811,9 +811,9 @@ Example: var example = 7 example.to_string() /* Returns "7" */ -## Boolean type +## Boolean type -### Boolean#to_string +### Boolean#to_string Signature: @@ -826,9 +826,9 @@ Example: var example = true example.to_string() /* Returns "true" */ -## String type +## String type -### String#find +### String#find Signature: @@ -842,7 +842,7 @@ Example: "Hello World".find("World") /* Returns 6 */ -### String#contains +### String#contains Signature: @@ -856,7 +856,7 @@ Example: "Hello World".contains("World") /* Returns true */ -### String#len +### String#len Signature @@ -869,7 +869,7 @@ Example: "Hello World".len() /* Returns 11 */ -### String#lower +### String#lower Signature: @@ -881,7 +881,7 @@ Example: "Hello World".lower() /* Returns "hello world" */ -### String#upper +### String#upper Signature: @@ -893,7 +893,7 @@ Example: "Hello World".upper() /* Returns "HELLO WORLD" */ -### String#replace +### String#replace Signature: @@ -902,7 +902,7 @@ Signature: Returns a copy of the string with all occurences of the string specified in `search` replaced with the string specified in `replacement`. -### String#split +### String#split Signature: @@ -915,7 +915,7 @@ Example: "x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */ -### String#substr +### String#substr Signature: @@ -928,7 +928,7 @@ Example: "Hello World".substr(6) /* Returns "World" */ -### String#to_string +### String#to_string Signature: @@ -936,7 +936,7 @@ Signature: Returns a copy of the string. -### String#reverse +### String#reverse Signature: @@ -944,7 +944,7 @@ Signature: Returns a copy of the string in reverse order. -### String#trim +### String#trim Signature: @@ -952,11 +952,11 @@ Signature: Removes trailing whitespaces and returns the string. -## Object type +## Object type This is the base type for all types in the Icinga application. -### Object#clone +### Object#clone Signature: @@ -966,7 +966,7 @@ Returns a copy of the object. Note that for object elements which are reference values (e.g. objects such as arrays or dictionaries) the entire object is recursively copied. -### Object#to_string +### Object#to_string Signature: @@ -980,7 +980,7 @@ Example: [ 3, true ].to_string() /* Returns "[ 3.000000, true ]" */ -### Object#type +### Object#type Signature: @@ -992,7 +992,7 @@ Example: get_host("localhost").type /* Returns "Host" */ -## Type type +## Type type Inherits methods from the [Object type](18-library-reference.md#object-type). @@ -1000,7 +1000,7 @@ The `Type` type provides information about the underlying type of an object or s All types are registered as global variables. For example, in order to obtain a reference to the `String` type the global variable `String` can be used. -### Type#base +### Type#base Signature: @@ -1012,7 +1012,7 @@ Example: Dictionary.base == Object /* Returns true, because the Dictionary type inherits directly from the Object type. */ -### Type#name +### Type#name Signature: @@ -1020,7 +1020,7 @@ Signature: Returns the name of the type. -### Type#prototype +### Type#prototype Signature: @@ -1034,11 +1034,11 @@ Example: 3.to_string() /* Even though '3' does not have a to_string property the Number type's prototype object does. */ -## Array type +## Array type Inherits methods from the [Object type](18-library-reference.md#object-type). -### Array#add +### Array#add Signature: @@ -1046,7 +1046,7 @@ Signature: Adds a new value after the last element in the array. -### Array#clear +### Array#clear Signature: @@ -1054,14 +1054,14 @@ Signature: Removes all elements from the array. -### Array#shallow_clone +### Array#shallow_clone 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. -### Array#contains +### Array#contains Signature: @@ -1069,7 +1069,7 @@ Signature: Returns true if the array contains the specified value, false otherwise. -### Array#len +### Array#len Signature: @@ -1077,7 +1077,7 @@ Signature: Returns the number of elements contained in the array. -### Array#remove +### Array#remove Signature: @@ -1085,7 +1085,7 @@ Signature: Removes the element at the specified zero-based index. -### Array#set +### Array#set Signature: @@ -1094,7 +1094,7 @@ Signature: Sets the element at the zero-based index to the specified value. The `index` must refer to an element which already exists in the array. -### Array#get +### Array#get Signature: @@ -1102,7 +1102,7 @@ Signature: Retrieves the element at the specified zero-based index. -### Array#sort +### Array#sort Signature: @@ -1112,7 +1112,7 @@ Returns a copy of the array where all items are sorted. The items are compared using the `<` (less-than) operator. A custom comparator function can be specified with the `less_cmp` argument. -### Array#join +### Array#join Signature: @@ -1120,7 +1120,7 @@ Signature: Joins all elements of the array using the specified separator. -### Array#reverse +### Array#reverse Signature: @@ -1128,7 +1128,7 @@ Signature: Returns a new array with all elements of the current array in reverse order. -### Array#map +### Array#map Signature: @@ -1137,7 +1137,7 @@ 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. -### Array#reduce +### Array#reduce Signature: @@ -1147,7 +1147,7 @@ Reduces the elements of the array into a single value by calling the provided function `func` as `func(a, b)` repeatedly where `a` and `b` are elements of the array or results from previous function calls. -### Array#filter +### Array#filter Signature: @@ -1156,7 +1156,7 @@ Signature: Returns a copy of the array containing only the elements for which `func(element)` is true. -### Array#any +### Array#any Signature: @@ -1165,7 +1165,7 @@ Signature: Returns true if the array contains at least one element for which `func(element)` is true, false otherwise. -### Array#all +### Array#all Signature: @@ -1174,7 +1174,7 @@ Signature: Returns true if the array contains only elements for which `func(element)` is true, false otherwise. -### Array#unique +### Array#unique Signature: @@ -1183,11 +1183,11 @@ Signature: Returns a copy of the array with all duplicate elements removed. The original order of the array is not preserved. -## Dictionary type +## Dictionary type Inherits methods from the [Object type](18-library-reference.md#object-type). -### Dictionary#shallow_clone +### Dictionary#shallow_clone Signature: @@ -1196,7 +1196,7 @@ 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. -### Dictionary#contains +### Dictionary#contains Signature: @@ -1204,7 +1204,7 @@ Signature: Returns true if a dictionary item with the specified `key` exists, false otherwise. -### Dictionary#len +### Dictionary#len Signature: @@ -1212,7 +1212,7 @@ Signature: Returns the number of items contained in the dictionary. -### Dictionary#remove +### Dictionary#remove Signature: @@ -1221,7 +1221,7 @@ Signature: Removes the item with the specified `key`. Trying to remove an item which does not exist is a no-op. -### Dictionary#set +### Dictionary#set Signature: @@ -1229,7 +1229,7 @@ Signature: Creates or updates an item with the specified `key` and `value`. -### Dictionary#get +### Dictionary#get Signature: @@ -1238,7 +1238,7 @@ Signature: Retrieves the value for the specified `key`. Returns `null` if they `key` does not exist in the dictionary. -### Dictionary#keys +### Dictionary#keys Signature: @@ -1246,7 +1246,7 @@ Signature: Returns a list of keys for all items that are currently in the dictionary. -### Dictionary#values +### Dictionary#values Signature: @@ -1254,11 +1254,11 @@ Signature: Returns a list of values for all items that are currently in the dictionary. -## Function type +## Function type Inherits methods from the [Object type](18-library-reference.md#object-type). -### Function#call +### Function#call Signature: @@ -1277,7 +1277,7 @@ Example: set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */ -### Function#callv +### Function#callv Signature: @@ -1298,11 +1298,11 @@ Example: set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */ -## DateTime type +## DateTime type Inherits methods from the [Object type](18-library-reference.md#object-type). -### DateTime constructor +### DateTime constructor Signature: @@ -1319,7 +1319,7 @@ Example: var d1 = DateTime() /* current time */ var d2 = DateTime(2016, 5, 21) /* midnight April 21st, 2016 (local time) */ -### DateTime arithmetic +### DateTime arithmetic Subtracting two DateTime objects yields the interval between them, in seconds. @@ -1339,7 +1339,7 @@ Example: var dt = DateTime() + 24 * 60 60 /* Current time plus 24 hours */ -### DateTime#format +### DateTime#format Signature: @@ -1352,7 +1352,7 @@ Example: var s = DateTime(2016, 4, 21).format("%A") /* Sets s to "Thursday". */ -### DateTime#to_string +### DateTime#to_string Signature: diff --git a/doc/19-script-debugger.md b/doc/19-script-debugger.md index f852436f8..b212b9a60 100644 --- a/doc/19-script-debugger.md +++ b/doc/19-script-debugger.md @@ -1,4 +1,4 @@ -# Script Debugger +# Script Debugger You can run the Icinga 2 daemon with the `-X` (`--script-debugger`) parameter to enable the script debugger: @@ -14,9 +14,9 @@ Here is a list of common errors which can be diagnosed with the script debugger: * Configuration errors (apply) * Errors in user-defined functions -## Debugging Configuration Errors +## Debugging Configuration Errors -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: @@ -76,7 +76,7 @@ you can inspect attributes of the service object: Additionally you can view the service object attributes by printing the value of `this`. -## Using Breakpoints +## Using Breakpoints In order to halt execution in a script you can use the `debugger` keyword: diff --git a/doc/20-development.md b/doc/20-development.md index c761f8fbd..cc591e506 100644 --- a/doc/20-development.md +++ b/doc/20-development.md @@ -1,4 +1,4 @@ -# Develop Icinga 2 +# Develop Icinga 2 This chapter provides hints on Icinga 2 development especially for debugging purposes. @@ -8,7 +8,7 @@ especially for debugging purposes. > If you are planning to build your own development environment, > please consult the `INSTALL.md` file from the source tree. -## Debug Requirements +## Debug Requirements Make sure that the debug symbols are available for Icinga 2. The Icinga 2 packages provide a debug package which must be @@ -34,7 +34,7 @@ If you're building your own binaries, you should use the `-DCMAKE_BUILD_TYPE=Deb build flag for debug builds. -## GDB +## GDB Install gdb: @@ -114,7 +114,7 @@ the duplicate import in your `~/.gdbinit` file. RuntimeError: pretty-printer already registered: libstdc++-v6 -### GDB Run +### GDB Run 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. @@ -142,7 +142,7 @@ Continue after breakpoint. (gdb) c -### GDB Core Dump +### GDB Core Dump Either attach to the running process using `gdb -p PID` or start a new gdb run. @@ -150,7 +150,7 @@ a new gdb run. (gdb) r (gdb) generate-core-file -### GDB Backtrace +### GDB Backtrace If Icinga 2 aborted its operation abnormally, generate a backtrace. @@ -166,14 +166,14 @@ running Icinga 2. If you create a [bug report](https://www.icinga.com/community/get-involved/), make sure to attach as much detail as possible. -### GDB Backtrace from Running Process +### GDB Backtrace from Running Process 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 -### GDB Backtrace Stepping +### GDB Backtrace Stepping Identifying the problem may require stepping into the backtrace, analysing the current scope, attributes, and possible unmet requirements. `p` prints @@ -185,7 +185,7 @@ the value of the selected variable or function call result. (gdb) p checkable.px->m_Name -### GDB Breakpoints +### GDB Breakpoints To set a breakpoint to a specific function call, or file specific line. @@ -239,13 +239,13 @@ Breakpoint Example: m_Data = "/etc/icinga2/conf.d/timeperiods.conf"}, {static NPos = 18446744073709551615, m_Data = "/etc/icinga2/conf.d/users.conf"}} -## Core Dump +## Core Dump 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. -### Core Dump File Size Limit +### Core Dump File Size Limit This requires setting the core dump file size to `unlimited`. @@ -276,7 +276,7 @@ Verify that the Icinga 2 process core file size limit is set to `unlimited`. Max core file size unlimited unlimited bytes -### Core Dump Kernel Format +### Core Dump Kernel Format The Icinga 2 daemon runs with the SUID bit set. Therefore you need to explicitly enable core dumps for SUID on Linux. @@ -295,7 +295,7 @@ MacOS: chmod 777 /cores -### Core Dump Analysis +### Core Dump Analysis 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. diff --git a/doc/21-selinux.md b/doc/21-selinux.md index dc017f17d..e1ceedb39 100644 --- a/doc/21-selinux.md +++ b/doc/21-selinux.md @@ -1,6 +1,6 @@ -# SELinux +# SELinux -## Introduction +## Introduction SELinux is a mandatory access control (MAC) system on Linux which adds a fine-grained permission system for access to all system resources such as files, devices, networks and inter-process communication. @@ -8,11 +8,11 @@ The most important questions are answered briefly in the [FAQ of the SELinux Pro This documentation will use a format similar to the SELinux User's and Administrator's Guide. -### Policy +### Policy 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. -### Installation +### Installation There are two ways of installing the SELinux Policy for Icinga 2 on Enterprise Linux 7. The preferred way is to install the package. The other option involves installing the SELinux policy manually which might be necessary if you need some fixes which haven't made their way into a release yet. @@ -31,7 +31,7 @@ If the system runs in enforcing mode and you encounter problems you can set Icin You can change the configured mode by editing `/etc/selinux/config` and the current mode by executing `setenforce 0`. -#### Package installation +#### Package installation Simply add the `icinga2-selinux` package to your installation. @@ -43,7 +43,7 @@ Ensure that the `icinga2` process is running in its own `icinga2_t` domain after # ps -eZ | grep icinga2 system_u:system_r:icinga2_t:s0 2825 ? 00:00:00 icinga2 -#### Manual installation +#### Manual installation This section describes the installation to support development and testing. It assumes that Icinga 2 is already installed from packages and running on the system. @@ -68,7 +68,7 @@ After that restart Icinga 2 and verify it running in its own domain `icinga2_t`. # ps -eZ | grep icinga2 system_u:system_r:icinga2_t:s0 2825 ? 00:00:00 icinga2 -### General +### General When the SELinux policy package for Icinga 2 is installed, the Icinga 2 daemon (icinga2) runs in its own domain `icinga2_t` and is separated from other confined services. @@ -76,7 +76,7 @@ Files have to be labeled correctly in order for Icinga 2 to be able to access th Additionally the Apache web server is allowed to connect to Icinga 2's command pipe in order to allow web interfaces to send commands to icinga2. This will perhaps change later on while investigating Icinga Web 2 for SELinux! -### Types +### Types The command pipe is labeled `icinga2_command_t` and other services can request access to it by using the interface `icinga2_send_commands`. @@ -98,7 +98,7 @@ If one of those plugin domains causes problems you can set it to permissive by e The policy provides a role `icinga2adm_r` for confining an user which enables an administrative user managing only Icinga 2 on the system. This user will also execute the plugins in their domain instead of the users one, so you can verify their execution with the same restrictions like they have when executed by icinga2. -### Booleans +### Booleans SELinux is based on the least level of access required for a service to run. Using booleans you can grant more access in a defined way. The Icinga 2 policy package provides the following booleans. @@ -114,15 +114,15 @@ Having this boolean enabled allows httpd to write to the command pipe of icinga2 Having this boolean enabled allows httpd to connect to the API of icinga2 (Ports labeled icinga2_port_t). This is enabled by default, if not needed you can disable it for more security. -### Configuration Examples +### Configuration Examples -#### Run the icinga2 service permissive +#### Run the icinga2 service permissive 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. -#### Confining a plugin +#### Confining a plugin Download and install a plugin, for example check_mysql_health. @@ -146,7 +146,7 @@ In this case the plugin is monitoring a service, so it should be labeled `nagios The plugin still runs fine but if someone changes the script to do weird stuff it will fail to do so. -#### Allow icinga to connect to all ports. +#### Allow icinga to connect to all ports. You are running graphite on a different port than `2003` and want `icinga2` to connect to it. @@ -174,7 +174,7 @@ Before you restart the icinga2 service allow it to connect to all ports by enabl If you restart the daemon now it will successfully connect to graphite. -#### Confining a user +#### Confining a user 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! @@ -225,7 +225,7 @@ Now try the commands again without providing the role and type and they will wor $ sudo systemctl reload httpd.service Failed to issue method call: Access denied -## Bugreports +## Bugreports 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. diff --git a/doc/22-migrating-from-icinga-1x.md b/doc/22-migrating-from-icinga-1x.md index dadf5492d..831841e95 100644 --- a/doc/22-migrating-from-icinga-1x.md +++ b/doc/22-migrating-from-icinga-1x.md @@ -1,12 +1,12 @@ -# Migration from Icinga 1.x +# Migration from Icinga 1.x -## Configuration Migration +## Configuration Migration 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. -### Manual Config Migration +### Manual Config Migration For a long-term migration of your configuration you should consider re-creating your configuration based on the proposed Icinga 2 configuration paradigm. @@ -14,7 +14,7 @@ your configuration based on the proposed Icinga 2 configuration paradigm. Please read the [next chapter](22-migrating-from-icinga-1x.md#differences-1x-2) to find out more about the differences between 1.x and 2. -### Manual Config Migration Hints +### Manual Config Migration Hints 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 @@ -26,7 +26,7 @@ let us know! If you require in-depth explanations, please check the [next chapter](22-migrating-from-icinga-1x.md#differences-1x-2). -#### Manual Config Migration Hints for Intervals +#### Manual Config Migration Hints for Intervals 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. @@ -52,10 +52,10 @@ Icinga 2: retry_interval = 1m } -#### Manual Config Migration Hints for Services +#### Manual Config Migration Hints for Services 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: @@ -85,7 +85,7 @@ like the following example: 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" @@ -95,7 +95,7 @@ Using Icinga 2 you can migrate this to the [apply rules](3-monitoring-basics.md# assign where "hostgroup3" in host.groups } -#### Manual Config Migration Hints for Group Members +#### Manual Config Migration Hints for Group Members 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. @@ -133,7 +133,7 @@ These assign rules can be applied for all groups: `HostGroup`, `ServiceGroup` an -#### Manual Config Migration Hints for Check Command Arguments +#### Manual Config Migration Hints for Check Command Arguments 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. @@ -183,7 +183,7 @@ While you could manually migrate this like (please note the new generic command vars.ping_cpl = 60 } -#### Manual Config Migration Hints for Runtime Macros +#### Manual Config Migration Hints for Runtime Macros Runtime macros have been renamed. A detailed comparison table can be found [here](22-migrating-from-icinga-1x.md#differences-1x-2-runtime-macros). @@ -204,7 +204,7 @@ In Icinga 2 you'd just use the following macro to access all `address` attribute $address$ -#### Manual Config Migration Hints for Runtime Custom Attributes +#### Manual Config Migration Hints for Runtime Custom Attributes Custom variables from Icinga 1.x are available as Icinga 2 custom attributes. @@ -254,7 +254,7 @@ while the service check command resolves its value to the service attribute attr > > Custom attributes in Icinga 2 are case-sensitive. `vars.CVTEST` is not the same as `vars.CvTest`. -#### Manual Config Migration Hints for Contacts (Users) +#### Manual Config Migration Hints for Contacts (Users) 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). @@ -280,7 +280,7 @@ renamed to `display_name`. This user can be put into usergroups (former contactgroups) or referenced in newly migration notification objects. -#### Manual Config Migration Hints for Notifications +#### Manual Config Migration Hints for Notifications 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 @@ -297,7 +297,7 @@ generic strategy * 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: @@ -339,7 +339,7 @@ examples, try [LConf](https://www.netways.org). -#### Manual Config Migration Hints for Notification Filters +#### Manual Config Migration Hints for Notification Filters 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. @@ -364,7 +364,7 @@ have to split these values into the `states` and `types` attributes. -#### Manual Config Migration Hints for Escalations +#### Manual Config Migration Hints for Escalations 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. @@ -455,9 +455,9 @@ just this service belonging to hosts in the matched hostgroup. -#### Manual Config Migration Hints for Dependencies +#### Manual Config Migration Hints for Dependencies -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. @@ -560,7 +560,7 @@ Host dependencies are explained in the [next chapter](22-migrating-from-icinga-1 -#### Manual Config Migration Hints for Host Parents +#### Manual Config Migration Hints for Host Parents Host parents from Icinga 1.x are migrated into `Host-to-Host` dependencies in Icinga 2. @@ -681,24 +681,24 @@ Another way to express the same configuration would be something like: This example allows finer grained host-to-host dependency, as well as multiple dependency support. -#### Manual Config Migration Hints for Distributed Setups +#### Manual Config Migration Hints for Distributed Setups * 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. -## Differences between Icinga 1.x and 2 +## Differences between Icinga 1.x and 2 -### Configuration Format +### Configuration Format 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`, @@ -726,7 +726,7 @@ icinga2.conf: enable_notifications = false } -#### Sample Configuration and ITL +#### Sample Configuration and ITL 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) @@ -746,18 +746,18 @@ included in `icinga2.conf` by default. > **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. -### Main Config File +### Main Config File 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. -### Include Files and Directories +### Include Files and Directories 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` @@ -787,7 +787,7 @@ command configuration. By convention the `.conf` suffix is used for Icinga 2 configuration files. -### Resource File and Global Macros +### Resource File and Global Macros 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 @@ -807,7 +807,7 @@ set in the `constants.conf` configuration file: [Global macros](17-language-reference.md#constants) can only be defined once. Trying to modify a global constant will result in an error. -### Configuration Comments +### Configuration Comments In Icinga 1.x comments are made using a leading hash (`#`) or a semi-colon (`;`) for inline comments. @@ -816,7 +816,7 @@ In Icinga 2 comments can either be encapsulated by `/*` and `*/` (allowing for multi-line comments) or starting with two slashes (`//`). A leading hash (`#`) could also be used. -### Object Names +### Object Names 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 @@ -834,7 +834,7 @@ services) like in Icinga 1.x but directly after their type definition. host_name = "localhost" } -### Templates +### Templates In Icinga 1.x templates are identified using the `register 0` setting. Icinga 2 uses the `template` identifier: @@ -857,7 +857,7 @@ Icinga 2 uses the keyword `import` with template names in double quotes. The last template overrides previously set values. -### Object attributes +### Object attributes Icinga 1.x separates attribute and value pairs with whitespaces/tabs. Icinga 2 requires an equal sign (=) between them. @@ -878,7 +878,7 @@ must be escaped by a backslash (e.g. in command line). If an attribute identifier starts with a number, it must be enclosed in double quotes as well. -#### Alias vs. Display Name +#### Alias vs. Display Name 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. @@ -886,7 +886,7 @@ The `alias` is used for group, timeperiod, etc. objects too. Icinga 2 only supports the `display_name` attribute which is also taken into account by Icinga web interfaces. -### Custom Attributes +### Custom Attributes Icinga 2 allows you to define custom attributes in the `vars` dictionary. The `notes`, `notes_url`, `action_url`, `icon_image`, `icon_image_alt` @@ -894,7 +894,7 @@ attributes for host and service objects are still available in Icinga 2. `2d_coords` and `statusmap_image` are not supported in Icinga 2. -#### Custom Variables +#### Custom Variables 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. @@ -902,32 +902,32 @@ In Icinga 2 these attributes must be added to the `vars` dictionary as custom at vars.dn = "cn=icinga2-dev-host,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org" vars.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). -### Host Service Relation +### Host Service Relation 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. -### Users +### Users 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. @@ -939,12 +939,12 @@ provide the contact and contactgroups attributes for services for compatibility reasons. These values are calculated from all services, their notifications, and their users. -### Macros +### Macros 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). -#### Command Arguments +#### Command Arguments 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 @@ -961,15 +961,15 @@ Please check the migration hints for a detailed > > The Classic UI feature named `Command Expander` does not work with Icinga 2. -#### Environment Macros +#### Environment Macros 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. -#### Runtime Macros +#### Runtime Macros Icinga 2 requires an object specific namespace when accessing configuration and stateful runtime macros. Custom attributes can be accessed directly. @@ -1104,7 +1104,7 @@ Changes to global statistic macros: -### External Commands +### External Commands `CHANGE_CUSTOM_CONTACT_VAR` was renamed to `CHANGE_CUSTOM_USER_VAR`. @@ -1152,16 +1152,16 @@ The following external commands are not supported: STOP_OBSESSING_OVER_SVC STOP_OBSESSING_OVER_SVC_CHECKS -### Asynchronous Event Execution +### Asynchronous Event Execution 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. -### Checks +### Checks -#### Check Output +#### Check Output Icinga 2 does not make a difference between `output` (first line) and `long_output` (remaining lines) like in Icinga 1.x. Performance Data is @@ -1174,18 +1174,18 @@ The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types split the raw output into `output` (first line) and `long_output` (remaining lines) for compatibility reasons. -#### Initial State +#### Initial State 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. -### Comments +### Comments Icinga 2 doesn't support non-persistent comments. -### Commands +### Commands Unlike in Icinga 1.x there are three different command types in Icinga 2: `CheckCommand`, `NotificationCommand`, and `EventCommand`. @@ -1198,29 +1198,29 @@ In Icinga 2 these command types are separated and will generate an error on configuration validation if used in the wrong context. 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. -#### Command Timeouts +#### Command Timeouts 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. -### Groups +### Groups In Icinga 2 hosts, services, and users are added to groups using the `groups` attribute in the object. The old way of listing all group members in the group's `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" @@ -1231,9 +1231,9 @@ expressions by using [group assign](3-monitoring-basics.md#group-assign-intro). assign where match("*-dev", host.name) } -#### Add Service to Hostgroup where Host is Member +#### Add Service to Hostgroup where Host is Member -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" { @@ -1244,7 +1244,7 @@ keyword can be used: assign where "dev-hosts" in host.groups } -### Notifications +### Notifications Notifications are a new object type in Icinga 2. Imagine the following notification configuration problem in Icinga 1.x: @@ -1289,7 +1289,7 @@ In Icinga 2 it will look like this: Service -> Notification -> NotificationCommand -> User, UserGroup -#### Escalations +#### Escalations Escalations in Icinga 1.x require a separated object matching on existing objects. Escalations happen between a defined start and end time which is @@ -1313,7 +1313,7 @@ happens. That's not necessary with Icinga 2 only requiring an additional notification object for the escalation itself. -#### Notification Options +#### Notification Options Unlike Icinga 1.x with the 'notification_options' attribute with comma-separated state and type filters, Icinga 2 uses two configuration attributes for that. @@ -1327,7 +1327,7 @@ All state and type filter use long names OR'd with a pipe together Icinga 2 adds more fine-grained type filters for acknowledgements, downtime, and flapping type (start, end, ...). -### Dependencies and Parents +### Dependencies and Parents 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. @@ -1343,7 +1343,7 @@ The former `host_name` and `dependent_host_name` have been renamed to `parent_ho and `child_host_name` (same for the service attribute). When using apply rules the 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). @@ -1352,7 +1352,7 @@ The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types support the Icinga 1.x schema with dependencies and parent attributes for compatibility reasons. -### Flapping +### Flapping 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 @@ -1366,7 +1366,7 @@ The algorithm used in Icinga 2 does not store the past states but calculates the threshold from a single value based on counters and half-life values. Icinga 2 compares the value with a single flapping threshold configuration attribute. -### Check Result Freshness +### Check Result Freshness 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 @@ -1379,7 +1379,7 @@ freshness is calculated from the `check_interval` attribute if set. There is no `freshness_threshold` attribute in Icinga 2. If the freshness checks are invalid, a new service check is forced. -### Real Reload +### Real Reload In Nagios / Icinga 1.x a daemon reload does the following: @@ -1397,7 +1397,7 @@ execution during config validation: * parent process continues with old configuration objects and the event scheduling (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 @@ -1411,14 +1411,14 @@ The configuration validation itself runs in parallel allowing fast verification That way your monitoring does not stop during a configuration reload. -### State Retention +### State Retention 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. -### Logging +### Logging 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 @@ -1432,7 +1432,7 @@ FileLogger, StreamLogger. Each of them has their own severity and target configu The Icinga 2 daemon log does not log any alerts but is considered an application log only. -### Broker Modules and Features +### Broker Modules and Features Icinga 1.x broker modules are incompatible with Icinga 2. @@ -1444,7 +1444,7 @@ popular broker modules was implemented for Icinga 2: * Cluster (allows for high availability and load balancing) -### Distributed Monitoring +### Distributed Monitoring 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. @@ -1454,7 +1454,7 @@ not synced between the master and slave nodes. There are addons available solvin and configuration distribution problems Icinga 1.x distributed monitoring currently suffers from. 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. diff --git a/doc/23-appendix.md b/doc/23-appendix.md index 568c71c16..3453ee993 100644 --- a/doc/23-appendix.md +++ b/doc/23-appendix.md @@ -1,6 +1,6 @@ -# Appendix +# Appendix -## External Commands List +## External Commands List Additional details can be found in the [Icinga 1.x Documentation](https://docs.icinga.com/latest/en/extcommands2.html) @@ -125,7 +125,7 @@ Additional details can be found in the [Icinga 1.x Documentation](https://docs.i DISABLE_SERVICEGROUP_SVC_NOTIFICATIONS | ;<servicegroup_name> (1) | - -## Schemas +## Schemas By convention `CheckCommand`, `EventCommand`, and `NotificationCommand` objects are exported using a prefix. This is mandatory for unique objects in the @@ -137,7 +137,7 @@ CheckCommand | check_ EventCommand | event_ NotificationCommand | notification_ -### Status Files +### Status Files Status files used by Icinga 1.x Classic UI: `status.dat`, `objects.cache`. @@ -149,12 +149,12 @@ Icinga 2 specific extensions: * 2.2 adds custom attributes with arrays and dictionaries. They are dumped as JSON encoded string and `_is_json` is set as additional custom variable in `objects.cache`. -### DB IDO Schema +### DB IDO Schema There is a detailed documentation for the Icinga IDOUtils 1.x database schema available on [https://docs.icinga.com/latest/en/db_model.html] -#### DB IDO Schema Extensions +#### DB IDO Schema Extensions Icinga 2 specific extensions are shown below: @@ -207,9 +207,9 @@ New columns: Additional command custom variables populated from 'vars' dictionary. Additional global custom variables populated from 'Vars' constant (object_id is NULL). -### Livestatus Schema +### Livestatus Schema -#### Livestatus Schema Extensions +#### Livestatus Schema Extensions Icinga 2 specific extensions are shown below: @@ -259,7 +259,7 @@ New columns: Command custom variables reflect the local 'vars' dictionary. Status custom variables reflect the global 'Vars' constant. -#### Livestatus Hosts Table Attributes +#### Livestatus Hosts Table Attributes Key | Type | Note ----------------------|-----------|------------------------- @@ -364,7 +364,7 @@ Not supported: `initial_state`, `pending_flex_downtime`, `check_flapping_recover `is_executing`, `check_options`, `obsess_over_host`, `first_notification_delay`, `x_3d`, `y_3d`, `z_3d`, `x_2d`, `y_2d`, `filename`, `pnpgraph_present`. -#### Livestatus Hostgroups Table Attributes +#### Livestatus Hostgroups Table Attributes Key | Type | Note ----------------------|-----------|------------------------- @@ -394,7 +394,7 @@ Not supported: `initial_state`, `pending_flex_downtime`, `check_flapping_recover num_services_hard_crit | int | . num_services_hard_unknown | int | . -#### Livestatus Services Table Attributes +#### Livestatus Services Table Attributes Key | Type | Note ----------------------|-----------|------------------------- @@ -481,7 +481,7 @@ Not supported: `initial_state`, `pending_flex_downtime`, `check_flapping_recover Not supported: `initial_state`, `is_executing`, `check_options`, `obsess_over_service`, `first_notification_delay`, `pnpgraph_present`. -#### Livestatus Servicegroups Table Attributes +#### Livestatus Servicegroups Table Attributes Key | Type | Note ----------------------|-----------|------------------------- @@ -504,7 +504,7 @@ Not supported: `initial_state`, `is_executing`, `check_options`, `obsess_over_se num_services_hard_crit | int | . num_services_hard_unknown | int | . -#### Livestatus Contacts Table Attributes +#### Livestatus Contacts Table Attributes Key | Type | Note ----------------------|-----------|------------------------- @@ -527,7 +527,7 @@ Not supported: `initial_state`, `is_executing`, `check_options`, `obsess_over_se Not supported: `can_submit_commands`. -#### Livestatus Contactgroups Table Attributes +#### Livestatus Contactgroups Table Attributes Key | Type | Note ----------------------|-----------|------------------------- @@ -536,7 +536,7 @@ Not supported: `can_submit_commands`. members | array | . -#### Livestatus Commands Table Attributes +#### Livestatus Commands Table Attributes Key | Type | Note ----------------------|-----------|------------------------- @@ -544,7 +544,7 @@ Not supported: `can_submit_commands`. line | string | . -#### Livestatus Status Table Attributes +#### Livestatus Status Table Attributes Key | Type | Note ----------------------|-----------|------------------------- @@ -583,7 +583,7 @@ Not supported: `neb_callbacks`, `neb_callbacks_rate`, `requests`, `requests_rate `cached_log_messages`, `livestatus_queued_connections`, `livestatus_threads`. -#### Livestatus Comments Table Attributes +#### Livestatus Comments Table Attributes Key | Type | Note ----------------------|-----------|------------------------- @@ -602,7 +602,7 @@ Not supported: `neb_callbacks`, `neb_callbacks_rate`, `requests`, `requests_rate host_ | join | Prefix for attributes from implicit join with hosts table. -#### Livestatus Downtimes Table Attributes +#### Livestatus Downtimes Table Attributes Key | Type | Note ----------------------|-----------|------------------------- @@ -623,7 +623,7 @@ Not supported: `neb_callbacks`, `neb_callbacks_rate`, `requests`, `requests_rate host_ | join | Prefix for attributes from implicit join with hosts table. -#### Livestatus Timeperiod Table Attributes +#### Livestatus Timeperiod Table Attributes Key | Type | Note ----------------------|-----------|------------------------- @@ -631,7 +631,7 @@ Not supported: `neb_callbacks`, `neb_callbacks_rate`, `requests`, `requests_rate alias | string | `display_name` attribute. in | int | Current time is in timeperiod or not. -#### Livestatus Log Table Attributes +#### Livestatus Log Table Attributes Key | Type | Note ----------------------|-----------|------------------------- @@ -655,7 +655,7 @@ Not supported: `neb_callbacks`, `neb_callbacks_rate`, `requests`, `requests_rate current_contact_ | join | Prefix for attributes from implicit join with contacts table. current_command_ | join | Prefix for attributes from implicit join with commands table. -#### Livestatus Statehist Table Attributes +#### Livestatus Statehist Table Attributes Key | Type | Note ----------------------|-----------|------------------------- @@ -690,17 +690,17 @@ Not supported: `neb_callbacks`, `neb_callbacks_rate`, `requests`, `requests_rate Not supported: `debug_info`. -#### Livestatus Hostsbygroup Table Attributes +#### Livestatus Hostsbygroup Table Attributes 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_`. -#### Livestatus Servicesbygroup Table Attributes +#### Livestatus Servicesbygroup Table Attributes 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_`. -#### Livestatus Servicesbyhostgroup Table Attributes +#### Livestatus Servicesbyhostgroup Table Attributes 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_`.