mirror of https://github.com/Icinga/icinga2.git
Michael Friedrich
parent
ddfccf3188
commit
10c3c52ed3
|
|
@ -0,0 +1,826 @@
|
|||
# <a id="getting-started"></a> Getting Started
|
||||
|
||||
This tutorial is a step-by-step introduction to installing Icinga 2 and
|
||||
available Icinga web interfaces. It assumes that you are familiar with
|
||||
the system you're installing Icinga 2 on.
|
||||
|
||||
## <a id="setting-up-icinga2"></a> Setting up Icinga 2
|
||||
|
||||
First of all you will have to install Icinga 2. The preferred way of doing this
|
||||
is to use the official Debian or RPM package repositories depending on which
|
||||
operating system and distribution you are running.
|
||||
|
||||
Distribution | Repository URL
|
||||
------------------------|---------------------------
|
||||
Debian | http://packages.icinga.org/debian/
|
||||
Ubuntu | http://packages.icinga.org/ubuntu/
|
||||
RHEL/CentOS | http://packages.icinga.org/epel/
|
||||
OpenSUSE | http://packages.icinga.org/openSUSE/
|
||||
SLES | http://packages.icinga.org/SUSE/
|
||||
|
||||
Packages for distributions other than the ones listed above may also be
|
||||
available. Please check http://packages.icinga.org/ to see if packages
|
||||
are available for your favourite distribution.
|
||||
|
||||
The packages for RHEL/CentOS 5 depend on other packages which are distributed
|
||||
as part of the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please
|
||||
make sure to enable this repository.
|
||||
|
||||
You can install Icinga 2 by using your distribution's package manager
|
||||
to install the `icinga2` package.
|
||||
|
||||
On RHEL/CentOS and SLES you will need to use `chkconfig` to enable the
|
||||
`icinga2` service. You can manually start Icinga 2 using `/etc/init.d/icinga2 start`.
|
||||
|
||||
Some parts of Icinga 2's functionality are available as separate packages:
|
||||
|
||||
Name | Description
|
||||
------------------------|--------------------------------
|
||||
icinga2-ido-mysql | IDO provider module for MySQL
|
||||
icinga2-ido-pgsql | IDO provider module for PostgreSQL
|
||||
|
||||
In case you're running a distribution for which Icinga 2 packages are
|
||||
not yet available you will have to use the release tarball which you
|
||||
can download from the [Icinga website](https://www.icinga.org/). The
|
||||
release tarballs contain an `INSTALL` file with further instructions.
|
||||
|
||||
|
||||
### <a id="installation-paths"></a> Installation Paths
|
||||
|
||||
By default Icinga 2 uses the following files and directories:
|
||||
|
||||
Path | Description
|
||||
------------------------------------|------------------------------------
|
||||
/etc/icinga2 | Contains Icinga 2 configuration files.
|
||||
/etc/init.d/icinga2 | The Icinga 2 init script.
|
||||
/usr/bin/icinga2-* | Migration and certificate build scripts.
|
||||
/usr/sbin/icinga2* | The Icinga 2 binary and feature enable/disable scripts.
|
||||
/usr/share/doc/icinga2 | Documentation files that come with Icinga 2.
|
||||
/usr/share/icinga2/itl | The Icinga Template Library.
|
||||
/var/run/icinga2 | PID file.
|
||||
/var/run/icinga2/cmd | Command pipe and Livestatus socket.
|
||||
/var/cache/icinga2 | status.dat/objects.cache.
|
||||
/var/spool/icinga2 | Used for performance data spool files.
|
||||
/var/lib/icinga2 | Icinga 2 state file, cluster feature replay log and configuration files.
|
||||
/var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
|
||||
|
||||
### <a id="icinga2-conf"></a> icinga2.conf
|
||||
|
||||
An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`.
|
||||
|
||||
Here's a brief description of the example configuration:
|
||||
|
||||
/**
|
||||
* Icinga 2 configuration file
|
||||
* - this is where you define settings for the Icinga application including
|
||||
* which hosts/services to check.
|
||||
*
|
||||
* For an overview of all available configuration options please refer
|
||||
* to the documentation that is distributed as part of Icinga 2.
|
||||
*/
|
||||
|
||||
Icinga 2 supports [C/C++-style comments](#comments).
|
||||
|
||||
/**
|
||||
* The constants.conf defines global constants.
|
||||
*/
|
||||
include "constants.conf"
|
||||
|
||||
The `include` directive can be used to include other files.
|
||||
|
||||
/**
|
||||
* The Icinga Template Library (ITL) provides a number of useful templates
|
||||
* and command definitions.
|
||||
*/
|
||||
include <itl/itl.conf>
|
||||
|
||||
/**
|
||||
* The features-available directory contains a number of configuration
|
||||
* files for features which can be enabled and disabled using the
|
||||
* icinga2-enable-feature / icinga2-disable-feature tools. These two tools work by creating
|
||||
* and removing symbolic links in the features-enabled directory.
|
||||
*/
|
||||
include "features-enabled/*.conf"
|
||||
|
||||
This `include` directive takes care of including the configuration files for all
|
||||
the features which have been enabled with `icinga2-enable-feature`. See
|
||||
[Enabling/Disabling Features](#features) for more details.
|
||||
|
||||
/**
|
||||
* Although in theory you could define all your objects in this file
|
||||
* the preferred way is to create separate directories and files in the conf.d
|
||||
* directory. Each of these files must have the file extension ".conf".
|
||||
*/
|
||||
include_recursive "conf.d"
|
||||
|
||||
You can put your own configuration files in the `conf.d` directory. This
|
||||
directive makes sure that all of your own configuration files are included.
|
||||
|
||||
### <a id="constants-conf"></a> constants.conf
|
||||
|
||||
The `constants.conf` configuration file can be used to define global constants:
|
||||
|
||||
/**
|
||||
* This file defines global constants which can be used in
|
||||
* the other configuration files. At a minimum the
|
||||
* PluginDir constant should be defined.
|
||||
*/
|
||||
|
||||
const PluginDir = "/usr/lib/nagios/plugins"
|
||||
|
||||
### <a id="localhost-conf"></a> localhost.conf
|
||||
|
||||
The `conf.d/localhost.conf` file contains our first host definition:
|
||||
|
||||
/**
|
||||
* A host definition. You can create your own configuration files
|
||||
* in the conf.d directory (e.g. one per host). By default all *.conf
|
||||
* files in this directory are included.
|
||||
*/
|
||||
object Host "localhost" {
|
||||
import "linux-server"
|
||||
|
||||
address = "127.0.0.1"
|
||||
address6 = "::1"
|
||||
}
|
||||
|
||||
This defines the host `localhost`. The `import` keyword is used to import
|
||||
the `linux-server` template which takes care of setting up the host check
|
||||
as well as adding the host to the `linux-servers` host group.
|
||||
|
||||
The `vars` attribute can be used to define custom attributes which are available
|
||||
for check and notification commands. Most of the templates in the Icinga
|
||||
Template Library require an `address` custom attribute.
|
||||
|
||||
object Service "icinga" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "icinga"
|
||||
}
|
||||
|
||||
object Service "http" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "http_ip"
|
||||
}
|
||||
|
||||
object Service "ssh" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "ssh"
|
||||
}
|
||||
|
||||
object Service "load" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "load"
|
||||
}
|
||||
|
||||
object ScheduledDowntime "backup-downtime" {
|
||||
import "backup-downtime"
|
||||
|
||||
host_name = "localhost"
|
||||
service_name = "load"
|
||||
}
|
||||
|
||||
object Service "processes" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "processes"
|
||||
}
|
||||
|
||||
object Service "users" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "users"
|
||||
}
|
||||
|
||||
object Service "disk" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "disk"
|
||||
}
|
||||
|
||||
The command objects `icinga`, `http_ip`, `ssh`, `load`, `processes`, `users`
|
||||
and `disk` are all provided by the Icinga Template Library (ITL) which
|
||||
we enabled earlier by including the `itl/itl.conf` configuration file.
|
||||
|
||||
> **Best Practice**
|
||||
>
|
||||
> Instead of defining each service object and assigning it to a host object
|
||||
> using the `host_name` attribute rather use the [apply rules](#apply)
|
||||
> simplifying your configuration.
|
||||
|
||||
|
||||
## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
|
||||
|
||||
On its own Icinga 2 does not know how to check external services. The
|
||||
[Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
|
||||
an extensive set of plugins which can be used with Icinga 2 to check whether
|
||||
services are working properly.
|
||||
|
||||
The recommended way of installing these standard plugins is to use your
|
||||
distribution's package manager.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The `Nagios Plugins` project was renamed to `Monitoring Plugins`
|
||||
> in January 2014. At the time of this writing the packages are still
|
||||
> using the old name.
|
||||
|
||||
For your convenience here is a list of package names for some of the more
|
||||
popular operating systems/distributions:
|
||||
|
||||
OS/Distribution | Package Name | Installation Path
|
||||
-----------------------|--------------------|---------------------------
|
||||
RHEL/CentOS (EPEL) | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
|
||||
Debian | nagios-plugins | /usr/lib/nagios/plugins
|
||||
FreeBSD | nagios-plugins | /usr/local/libexec/nagios
|
||||
OS X (MacPorts) | nagios-plugins | /opt/local/libexec
|
||||
|
||||
Depending on which directory your plugins are installed into you may need to
|
||||
update the global `PluginDir` constant in your Icinga 2 configuration. This macro is used
|
||||
by the service templates contained in the Icinga Template Library to determine
|
||||
where to find the plugin binaries.
|
||||
|
||||
### <a id="integrate-additional-plugins"></a> Integrate Additional Plugins
|
||||
|
||||
For some services you may need additional check plugins which are not provided
|
||||
by the official Monitoring Plugins project.
|
||||
|
||||
All existing Nagios or Icinga 1.x plugins should work with Icinga 2. Here's a
|
||||
list of popular community sites which host check plugins:
|
||||
|
||||
* [MonitoringExchange](https://www.monitoringexchange.org)
|
||||
* [Icinga Wiki](https://wiki.icinga.org)
|
||||
|
||||
The recommended way of setting up these plugins is to copy them to a common directory
|
||||
and create an extra global constant, e.g. `CustomPluginDir` in your `constants.conf`
|
||||
configuration file:
|
||||
|
||||
# cp check_snmp_int.pl /opt/plugins
|
||||
# chmod +x /opt/plugins/check_snmp_int.pl
|
||||
|
||||
# cat /etc/icinga2/constants.conf
|
||||
/**
|
||||
* This file defines global constants which can be used in
|
||||
* the other configuration files. At a minimum the
|
||||
* PluginDir constant should be defined.
|
||||
*/
|
||||
|
||||
const PluginDir = "/usr/lib/nagios/plugins"
|
||||
const CustomPluginDir = "/opt/monitoring"
|
||||
|
||||
Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
|
||||
by trying to run it on the console using whichever user Icinga 2 is running as:
|
||||
|
||||
# su - icinga -s /bin/bash
|
||||
$ /opt/plugins/check_snmp_int.pl --help
|
||||
|
||||
Additional libraries may be required for some plugins. Please consult the plugin
|
||||
documentation and/or README for installation instructions.
|
||||
|
||||
|
||||
## <a id="configuring-ido"></a> Configuring 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 a number of projects including Icinga Web.
|
||||
|
||||
There is a separate module for each database back-end. At present support for
|
||||
both MySQL and PostgreSQL is implemented.
|
||||
|
||||
Icinga 2 uses the Icinga 1.x IDOUtils database schema starting with version
|
||||
`1.11.0`. Icinga 2 may require additional features not yet released with
|
||||
Icinga 1.x and therefore require manual upgrade steps during pre-final
|
||||
milestone releases.
|
||||
|
||||
> **Tip**
|
||||
>
|
||||
> Only install the IDO feature if your web interface or reporting tool requires
|
||||
> you to do so (for example, [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2)).
|
||||
> [Icinga Classic UI](#setting-up-icinga-classic-ui) does not use IDO as backend.
|
||||
|
||||
### <a id="configuring-ido-mysql"></a> Configuring IDO MySQL
|
||||
|
||||
#### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
|
||||
|
||||
First of all you have to install the `icinga2-ido-mysql` package using your
|
||||
distribution's package manager. Once you have done that you can proceed with
|
||||
setting up a MySQL database for Icinga 2:
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The Debian packages can optionally create and maintain the database for you
|
||||
> using Debian's `dbconfig` framework. This is the recommended way of setting up
|
||||
> the database.
|
||||
|
||||
# mysql -u root -p
|
||||
|
||||
mysql> CREATE DATABASE icinga;
|
||||
|
||||
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
|
||||
|
||||
mysql> quit
|
||||
|
||||
|
||||
After creating the database you can import the Icinga 2 IDO schema using the
|
||||
following command:
|
||||
|
||||
# mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/mysql.sql
|
||||
|
||||
The Icinga 2 RPM packages install the schema files into
|
||||
`/usr/share/doc/icinga2-ido-mysql-*/schema` (`*` means package version).
|
||||
|
||||
On SuSE-based distributions the schema files are installed in
|
||||
`/usr/share/doc/packages/icinga2-ido-mysql/schema`.
|
||||
|
||||
The Debian/Ubuntu packages put the schema files into
|
||||
`/usr/share/icinga2-ido-mysql/schema`.
|
||||
|
||||
#### <a id="upgrading-mysql-db"></a> Upgrading the MySQL database
|
||||
|
||||
Check the `schema/upgrade` directory for an incremental schema upgrade file.
|
||||
If there isn't an upgrade file available there's nothing to do.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> During pre release status (0.x.y releases) small snippets called for example
|
||||
> `0.0.10.sql` will ship the required schema updates.
|
||||
|
||||
Apply all database schema upgrade files incrementially.
|
||||
|
||||
# mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/upgrade/0.0.10.sql
|
||||
|
||||
The Icinga 2 IDO module will check for the required database schema version on startup
|
||||
and generate an error message if not satisfied.
|
||||
|
||||
#### <a id="installing-ido-mysql"></a> Installing 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.
|
||||
|
||||
You can enable the `ido-mysql` feature configuration file using `icinga2-enable-feature`:
|
||||
|
||||
# icinga2-enable-feature ido-mysql
|
||||
Module 'ido-mysql' was enabled.
|
||||
Make sure to restart Icinga 2 for these changes to take effect.
|
||||
|
||||
After enabling the ido-mysql feature you have to restart Icinga 2:
|
||||
|
||||
# /etc/init.d/icinga2 restart
|
||||
|
||||
|
||||
### <a id="configuring-ido-postgresql"></a> Configuring IDO PostgreSQL
|
||||
|
||||
#### Setting up the PostgreSQL database
|
||||
|
||||
First of all you have to install the `icinga2-ido-pgsql` package using your
|
||||
distribution's package manager. Once you have done that you can proceed with
|
||||
setting up a PostgreSQL database for Icinga 2:
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The Debian packages can optionally create and maintain the database for you
|
||||
> using Debian's `dbconfig` framework. This is the recommended way of setting up
|
||||
> the database.
|
||||
|
||||
# cd /tmp
|
||||
# sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
|
||||
# sudo -u postgres createdb -O icinga -E UTF8 icinga
|
||||
# sudo -u postgres createlang plpgsql icinga
|
||||
|
||||
Locate your pg_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
|
||||
RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
|
||||
authentication method and restart the postgresql server.
|
||||
|
||||
# vim /var/lib/pgsql/data/pg_hba.conf
|
||||
|
||||
# icinga
|
||||
local icinga icinga md5
|
||||
host icinga icinga 127.0.0.1/32 md5
|
||||
host icinga icinga ::1/128 md5
|
||||
|
||||
# "local" is for Unix domain socket connections only
|
||||
local all all ident
|
||||
# IPv4 local connections:
|
||||
host all all 127.0.0.1/32 ident
|
||||
# IPv6 local connections:
|
||||
host all all ::1/128 ident
|
||||
|
||||
# /etc/init.d/postgresql restart
|
||||
|
||||
|
||||
After creating the database and permissions you can import the Icinga 2 IDO schema
|
||||
using the following command:
|
||||
|
||||
# export PGPASSWORD=icinga
|
||||
# psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/pgsql.sql
|
||||
|
||||
The Icinga 2 RPM packages install the schema files into
|
||||
`/usr/share/doc/icinga2-ido-pgsql-*/schema` (`*` means package version).
|
||||
|
||||
On SuSE-based distributions the schema files are installed in
|
||||
`/usr/share/doc/packages/icinga2-ido-pgsql/schema`.
|
||||
|
||||
The Debian/Ubuntu packages put the schema files into
|
||||
`/usr/share/icinga2-ido-pgsql/schema`.
|
||||
|
||||
#### <a id="upgrading-postgresql-db"></a> Upgrading the PostgreSQL database
|
||||
|
||||
Check the `schema/upgrade` directory for an incremental schema upgrade file.
|
||||
If there isn't an upgrade file available there's nothing to do.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> During pre release status (0.x.y releases) small snippets called for example
|
||||
> `0.0.10.sql` will ship the required schema updates.
|
||||
|
||||
Apply all database schema upgrade files incrementially.
|
||||
|
||||
# export PGPASSWORD=icinga
|
||||
# psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/upgrade/0.0.10.sql
|
||||
|
||||
The Icinga 2 IDO module will check for the required database schema version on startup
|
||||
and generate an error message if not satisfied.
|
||||
|
||||
#### <a id="installing-ido-postgresql"></a> Installing 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.
|
||||
|
||||
You can enable the `ido-pgsql` feature configuration file using `icinga2-enable-feature`:
|
||||
|
||||
# icinga2-enable-feature ido-pgsql
|
||||
Module 'ido-pgsql' was enabled.
|
||||
Make sure to restart Icinga 2 for these changes to take effect.
|
||||
|
||||
After enabling the ido-pgsql feature you have to restart Icinga 2:
|
||||
|
||||
# /etc/init.d/icinga2 restart
|
||||
|
||||
|
||||
## <a id="setting-up-livestatus"></a> Setting up Livestatus
|
||||
|
||||
The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project
|
||||
implements a query protocol that lets users query their Icinga instance for
|
||||
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](#setting-up-icingaweb2)).
|
||||
> [Icinga Classic UI](#setting-up-icinga-classic-ui) and [Icinga Web](#setting-up-icinga-web)
|
||||
> do not use Livestatus as backend.
|
||||
|
||||
The Livestatus component that is distributed as part of Icinga 2 is a
|
||||
re-implementation of the Livestatus protocol which is compatible with MK
|
||||
Livestatus.
|
||||
|
||||
Details on the available tables and attributes with Icinga 2 can be found
|
||||
in the [Livestatus Schema](#schema-livestatus) section.
|
||||
|
||||
You can enable Livestatus using icinga2-enable-feature:
|
||||
|
||||
# icinga2-enable-feature livestatus
|
||||
|
||||
After that you will have to restart Icinga 2:
|
||||
|
||||
# /etc/init.d/icinga2 restart
|
||||
|
||||
By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`.
|
||||
|
||||
In order for queries and commands to work you will need to add your query user
|
||||
(e.g. your web server) to the `icingacmd` group:
|
||||
|
||||
# usermod -a -G icingacmd www-data
|
||||
|
||||
The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
|
||||
`nagios` if you're using Debian.
|
||||
|
||||
Change "www-data" to the user you're using to run queries.
|
||||
|
||||
In order to use the historical tables provided by the livestatus feature (for example, the
|
||||
`log` table) you need to have the `CompatLogger` feature enabled. By default these logs
|
||||
are expected in `/var/log/icinga2/compat`. A different path can be set using the `compat_log_path`
|
||||
configuration attribute.
|
||||
|
||||
# icinga2-enable-feature compatlog
|
||||
|
||||
|
||||
## <a id="setting-up-icinga2-user-interfaces"></a> Setting up Icinga 2 User Interfaces
|
||||
|
||||
Icinga 2 is compatible to Icinga 1.x user interfaces by providing additional
|
||||
features required as backends.
|
||||
|
||||
Furthermore these interfaces (and somewhere in the future an Icinga 2
|
||||
exclusive interface) can be used for the newly created `Icinga Web 2`
|
||||
user interface.
|
||||
|
||||
Some interface features will only work in a limited manner due to
|
||||
[compatibility reasons](#differences-1x-2), other features like the
|
||||
statusmap parents are available dumping the host dependencies as parents.
|
||||
Special restrictions are noted specifically in the sections below.
|
||||
|
||||
> **Tip**
|
||||
>
|
||||
> Choose your preferred interface. There's no need to install [Classic UI](#setting-up-icinga-classic-ui)
|
||||
> if you prefer [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2) for example.
|
||||
|
||||
### <a id="setting-up-icinga-classic-ui"></a> Setting up Icinga Classic UI
|
||||
|
||||
Icinga 2 can write `status.dat` and `objects.cache` files in the format that
|
||||
is supported by the Icinga 1.x Classic UI. External commands (a.k.a. the
|
||||
"command pipe") are also supported. It also supports writing Icinga 1.x
|
||||
log files which are required for the reporting functionality in the Classic UI.
|
||||
|
||||
#### <a id="installing-icinga-classic-ui"></a> Installing Icinga Classic UI
|
||||
|
||||
The Icinga package repository has both Debian and RPM packages. You can install
|
||||
the Classic UI using the following packages:
|
||||
|
||||
Distribution | Packages
|
||||
--------------|---------------------
|
||||
Debian | icinga2-classicui
|
||||
all others | icinga2-classicui-config icinga-gui
|
||||
|
||||
The Debian packages require additional packages which are provided by the
|
||||
[Debian Monitoring Project](http://www.debmon.org) repository.
|
||||
|
||||
On all distributions other than Debian you may have to restart both your web
|
||||
server as well as Icinga 2 after installing the Classic UI package.
|
||||
|
||||
Verify that your Icinga 1.x Classic UI works by browsing to your Classic
|
||||
UI installation URL:
|
||||
|
||||
Distribution | URL | Default Login
|
||||
--------------|--------------------------------------------------------------------------|--------------------------
|
||||
Debian | [http://localhost/icinga2-classicui](http://localhost/icinga2-classicui) | asked during installation
|
||||
all others | [http://localhost/icinga](http://localhost/icinga) | icingaadmin/icingaadmin
|
||||
|
||||
### <a id="setting-up-icinga-web"></a> Setting up Icinga Web
|
||||
|
||||
Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which
|
||||
is an explicit requirement to run `Icinga Web` next to the external command pipe.
|
||||
Therefore you need to setup the [DB IDO feature](#configuring-ido) remarked in the previous sections.
|
||||
|
||||
#### <a id="installing-icinga-web"></a> Installing Icinga Web
|
||||
|
||||
The Icinga package repository has both Debian and RPM packages. You can install
|
||||
the Classic UI using the following packages:
|
||||
|
||||
Distribution | Packages
|
||||
--------------|-------------------------------------
|
||||
RHEL/SUSE | icinga-web icinga-web-{mysql,pgsql}
|
||||
Debian | icinga-web
|
||||
|
||||
Additionally you need to setup the `icinga_web` database.
|
||||
|
||||
The Icinga Web RPM packages install the schema files into
|
||||
`/usr/share/doc/icinga-web-*/schema` (`*` means package version).
|
||||
The Icinga Web dist tarball ships the schema files in `etc/schema`.
|
||||
|
||||
On SuSE-based distributions the schema files are installed in
|
||||
`/usr/share/doc/packages/icinga-web/schema`.
|
||||
|
||||
Icinga Web requires the IDO feature as database backend using MySQL or PostgreSQL.
|
||||
Enable that feature, e.g. for MySQL.
|
||||
|
||||
# icinga2-enable-feature ido-mysql
|
||||
|
||||
If you've changed your default credentials you may either create a read-only user
|
||||
or use the credentials defined in the IDO feature for Icinga Web backend configuration.
|
||||
Edit `databases.xml` accordingly and clear the cache afterwards. Further details can be
|
||||
found in the [Icinga Web documentation](http://docs.icinga.org/latest/en/icinga-web-config.html).
|
||||
|
||||
# vim /etc/icinga-web/conf.d/databases.xml
|
||||
|
||||
# icinga-web-clearcache
|
||||
|
||||
Additionally you need to enable the `command` feature:
|
||||
|
||||
# icinga2-enable-feature command
|
||||
|
||||
Then edit the Icinga Web configuration for sending commands in `/etc/icinga-web/conf.d/access.xml`
|
||||
(RHEL) or `/etc/icinga-web/access.xml` (SUSE) setting the command pipe path
|
||||
to the default used in Icinga 2. Make sure to clear the cache afterwards.
|
||||
|
||||
# vim /etc/icinga-web/conf.d/access.xml
|
||||
|
||||
<write>
|
||||
<files>
|
||||
<resource name="icinga_pipe">/var/run/icinga2/cmd/icinga.cmd</resource>
|
||||
</files>
|
||||
</write>
|
||||
|
||||
# icinga-web-clearcache
|
||||
|
||||
Verify that your Icinga 1.x Web works by browsing to your Web installation URL:
|
||||
|
||||
Distribution | URL | Default Login
|
||||
--------------|-------------------------------------------------------------|--------------------------
|
||||
Debian | [http://localhost/icinga-web](http://localhost/icinga-web) | asked during installation
|
||||
all others | [http://localhost/icinga-web](http://localhost/icinga-web) | root/password
|
||||
|
||||
|
||||
### <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
|
||||
|
||||
Icinga Web 2 currently supports `status.dat`, `DB IDO`, or `Livestatus` as backends.
|
||||
Please consult the INSTALL documentation shipped with `Icinga Web 2` for
|
||||
further instructions.
|
||||
|
||||
Icinga Web 2 is still under development. Rather than installing it
|
||||
yourself you should consider testing it using the available Vagrant
|
||||
demo VM.
|
||||
|
||||
|
||||
### <a id="additional-visualization"></a> Additional visualization
|
||||
|
||||
There are many visualization addons which can be used with Icinga 2.
|
||||
|
||||
Some of the more popular ones are PNP, inGraph (graphing performance data),
|
||||
Graphite, and NagVis (network maps).
|
||||
|
||||
|
||||
## <a id="configuration-tools"></a> Configuration Tools
|
||||
|
||||
Well known configuration tools for Icinga 1.x such as [LConf](http://www.netways.de/en/de/produkte/icinga/addons/lconf/),
|
||||
[NConf](http://www.nconf.org/) or [NagiosQL](http://www.nagiosql.org/)
|
||||
store their configuration in a custom format in their backends (LDAP or RDBMS).
|
||||
Currently only LConf 1.4.x supports Icinga 2 configuration export. If you require
|
||||
your favourite configuration tool to export Icinga 2 configuration, please get in
|
||||
touch with their developers.
|
||||
|
||||
If you're looking for puppet manifests, chef cookbooks, ansible recipes, etc - we're happy
|
||||
to integrate them upstream, so please get in touch at [https://support.icinga.org](https://support.icinga.org).
|
||||
|
||||
|
||||
## <a id="running-icinga2"></a> Running Icinga 2
|
||||
|
||||
### <a id="init-script"></a> Init Script
|
||||
|
||||
Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
|
||||
|
||||
# /etc/init.d/icinga2
|
||||
Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
|
||||
|
||||
Command | Description
|
||||
--------------------|------------------------
|
||||
start | The `start` action starts the Icinga 2 daemon.
|
||||
stop | The `stop` action stops the Icinga 2 daemon.
|
||||
restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
|
||||
reload | The `reload` action sends the `HUP` signal to Icinga 2 which causes it to restart. Unlike the `restart` action `reload` does not wait until Icinga 2 has restarted.
|
||||
checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
|
||||
status | The `status` action checks if Icinga 2 is running.
|
||||
|
||||
By default the Icinga 2 daemon is running as `icinga` user and group
|
||||
using the init script. Using Debian packages the user and group are set to `nagios`
|
||||
for historical reasons.
|
||||
|
||||
### <a id="cmdline"></a> Command-line Options
|
||||
|
||||
$ icinga2 --help
|
||||
icinga2 - The Icinga 2 network monitoring daemon.
|
||||
|
||||
Supported options:
|
||||
--help show this help message
|
||||
-V [ --version ] show version information
|
||||
-l [ --library ] arg load a library
|
||||
-I [ --include ] arg add include search directory
|
||||
-D [ --define] args define a constant
|
||||
-c [ --config ] arg parse a configuration file
|
||||
-C [ --validate ] exit after validating the configuration
|
||||
-x [ --debug ] enable debugging
|
||||
-d [ --daemonize ] detach from the controlling terminal
|
||||
-e [ --errorlog ] arg log fatal errors to the specified log file (only works
|
||||
in combination with --daemonize)
|
||||
-u [ --user ] arg user to run Icinga as
|
||||
-g [ --group ] arg group to run Icinga as
|
||||
|
||||
Report bugs at <https://dev.icinga.org/>
|
||||
Icinga home page: <http://www.icinga.org/>
|
||||
|
||||
#### Libraries
|
||||
|
||||
Instead of loading libraries using the [`library` config directive](#library)
|
||||
you can also use the `--library` command-line option.
|
||||
|
||||
#### Constants
|
||||
|
||||
[Global constants](#global-constants) can be set using the `--define` command-line option.
|
||||
|
||||
#### 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
|
||||
brackets like this:
|
||||
|
||||
include <test.conf>
|
||||
|
||||
This would cause Icinga 2 to search its include path for the configuration file
|
||||
`test.conf`. By default the installation path for the Icinga Template Library
|
||||
is the only search directory.
|
||||
|
||||
Using the `--include` command-line option additional search directories can be
|
||||
added.
|
||||
|
||||
#### Config Files
|
||||
|
||||
Using the `--config` option you can specify one or more configuration files.
|
||||
Config files are processed in the order they're specified on the command-line.
|
||||
|
||||
#### Config Validation
|
||||
|
||||
The `--validate` option can be used to check if your configuration files
|
||||
contain errors. If any errors are found the exit status is 1, otherwise 0
|
||||
is returned.
|
||||
|
||||
### <a id="features"></a> 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
|
||||
enabled and disabled using the `icinga2-enable-feature` and `icinga2-disable-feature` tools,
|
||||
respectively.
|
||||
|
||||
The `icinga2-enable-feature` tool creates symlinks in the `/etc/icinga2/features-enabled`
|
||||
directory which is included by default in the example configuration file.
|
||||
|
||||
You can view a list of available feature configuration files:
|
||||
|
||||
# icinga2-enable-feature
|
||||
Syntax: icinga2-enable-feature <feature>
|
||||
Enables the specified feature.
|
||||
|
||||
Available features: statusdata
|
||||
|
||||
Using the `icinga2-enable-feature` command you can enable features:
|
||||
|
||||
# icinga2-enable-feature statusdata
|
||||
Module 'statusdata' was enabled.
|
||||
Make sure to restart Icinga 2 for these changes to take effect.
|
||||
|
||||
You can disable features using the `icinga2-disable-feature` command:
|
||||
|
||||
# icinga2-disable-feature statusdata
|
||||
Module 'statusdata' was disabled.
|
||||
Make sure to restart Icinga 2 for these changes to take effect.
|
||||
|
||||
The `icinga2-enable-feature` and `icinga2-disable-feature` commands do not
|
||||
restart Icinga 2. You will need to restart Icinga 2 using the init script
|
||||
after enabling or disabling features.
|
||||
|
||||
|
||||
## <a id="vagrant"></a> Vagrant Demo VM
|
||||
|
||||
The Icinga 2 Git repository contains support for [Vagrant](http://docs.vagrantup.com/v2/)
|
||||
with VirtualBox. Please note that Vagrant version `1.0.x` is not supported. At least
|
||||
version `1.2.x` is required.
|
||||
|
||||
In order to build the Vagrant VM first you will have to check out
|
||||
the Git repository:
|
||||
|
||||
$ git clone git://git.icinga.org/icinga2.git
|
||||
|
||||
Once you have checked out the Git repository you can build the VM using the
|
||||
following command:
|
||||
|
||||
$ vagrant up
|
||||
|
||||
The Vagrant VM is based on CentOS 6.x and uses the official Icinga 2 RPM
|
||||
packages from `packages.icinga.org`. The check plugins are installed from
|
||||
EPEL providing RPMs with sources from the Monitoring Plugins project.
|
||||
|
||||
## <a id="vagrant-demo-guis"></a> Demo GUIs
|
||||
|
||||
In addition to installing Icinga 2 the Vagrant puppet modules also install the
|
||||
Icinga 1.x Classic UI and Icinga Web.
|
||||
|
||||
GUI | Url | Credentials
|
||||
----------------|----------------------------------------------------------------------|------------------------
|
||||
Classic UI | [http://localhost:8080/icinga](http://localhost:8080/icinga) | icingaadmin / icingaadmin
|
||||
Icinga Web | [http://localhost:8080/icinga-web](http://localhost:8080/icinga-web) | root / password
|
||||
|
||||
|
||||
## <a id="vagrant-ssh"></a> SSH Access
|
||||
|
||||
You can access the Vagrant VM using SSH:
|
||||
|
||||
$ vagrant ssh
|
||||
|
||||
Alternatively you can use your favorite SSH client:
|
||||
|
||||
Name | Value
|
||||
----------------|----------------
|
||||
Host | 127.0.0.1
|
||||
Port | 2222
|
||||
Username | vagrant
|
||||
Password | vagrant
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
# <a id="getting-started"></a> Getting Started
|
||||
|
||||
This tutorial is a step-by-step introduction to installing Icinga 2 and
|
||||
available Icinga web interfaces. It assumes that you are familiar with
|
||||
the system you're installing Icinga 2 on.
|
||||
|
|
@ -1,206 +0,0 @@
|
|||
## <a id="setting-up-icinga2"></a> Setting up Icinga 2
|
||||
|
||||
First of all you will have to install Icinga 2. The preferred way of doing this
|
||||
is to use the official Debian or RPM package repositories depending on which
|
||||
operating system and distribution you are running.
|
||||
|
||||
Distribution | Repository URL
|
||||
------------------------|---------------------------
|
||||
Debian | http://packages.icinga.org/debian/
|
||||
Ubuntu | http://packages.icinga.org/ubuntu/
|
||||
RHEL/CentOS | http://packages.icinga.org/epel/
|
||||
OpenSUSE | http://packages.icinga.org/openSUSE/
|
||||
SLES | http://packages.icinga.org/SUSE/
|
||||
|
||||
Packages for distributions other than the ones listed above may also be
|
||||
available. Please check http://packages.icinga.org/ to see if packages
|
||||
are available for your favourite distribution.
|
||||
|
||||
The packages for RHEL/CentOS 5 depend on other packages which are distributed
|
||||
as part of the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please
|
||||
make sure to enable this repository.
|
||||
|
||||
You can install Icinga 2 by using your distribution's package manager
|
||||
to install the `icinga2` package.
|
||||
|
||||
On RHEL/CentOS and SLES you will need to use `chkconfig` to enable the
|
||||
`icinga2` service. You can manually start Icinga 2 using `/etc/init.d/icinga2 start`.
|
||||
|
||||
Some parts of Icinga 2's functionality are available as separate packages:
|
||||
|
||||
Name | Description
|
||||
------------------------|--------------------------------
|
||||
icinga2-ido-mysql | IDO provider module for MySQL
|
||||
icinga2-ido-pgsql | IDO provider module for PostgreSQL
|
||||
|
||||
In case you're running a distribution for which Icinga 2 packages are
|
||||
not yet available you will have to use the release tarball which you
|
||||
can download from the [Icinga website](https://www.icinga.org/). The
|
||||
release tarballs contain an `INSTALL` file with further instructions.
|
||||
|
||||
### <a id="installation-paths"></a> Installation Paths
|
||||
|
||||
By default Icinga 2 uses the following files and directories:
|
||||
|
||||
Path | Description
|
||||
------------------------------------|------------------------------------
|
||||
/etc/icinga2 | Contains Icinga 2 configuration files.
|
||||
/etc/init.d/icinga2 | The Icinga 2 init script.
|
||||
/usr/bin/icinga2-* | Migration and certificate build scripts.
|
||||
/usr/sbin/icinga2* | The Icinga 2 binary and feature enable/disable scripts.
|
||||
/usr/share/doc/icinga2 | Documentation files that come with Icinga 2.
|
||||
/usr/share/icinga2/itl | The Icinga Template Library.
|
||||
/var/run/icinga2 | PID file.
|
||||
/var/run/icinga2/cmd | Command pipe and Livestatus socket.
|
||||
/var/cache/icinga2 | status.dat/objects.cache.
|
||||
/var/spool/icinga2 | Used for performance data spool files.
|
||||
/var/lib/icinga2 | Icinga 2 state file, cluster feature replay log and configuration files.
|
||||
/var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
|
||||
|
||||
### <a id="icinga2-conf"></a> icinga2.conf
|
||||
|
||||
An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`.
|
||||
|
||||
Here's a brief description of the example configuration:
|
||||
|
||||
/**
|
||||
* Icinga 2 configuration file
|
||||
* - this is where you define settings for the Icinga application including
|
||||
* which hosts/services to check.
|
||||
*
|
||||
* For an overview of all available configuration options please refer
|
||||
* to the documentation that is distributed as part of Icinga 2.
|
||||
*/
|
||||
|
||||
Icinga 2 supports [C/C++-style comments](#comments).
|
||||
|
||||
/**
|
||||
* The constants.conf defines global constants.
|
||||
*/
|
||||
include "constants.conf"
|
||||
|
||||
The `include` directive can be used to include other files.
|
||||
|
||||
/**
|
||||
* The Icinga Template Library (ITL) provides a number of useful templates
|
||||
* and command definitions.
|
||||
*/
|
||||
include <itl/itl.conf>
|
||||
|
||||
/**
|
||||
* The features-available directory contains a number of configuration
|
||||
* files for features which can be enabled and disabled using the
|
||||
* icinga2-enable-feature / icinga2-disable-feature tools. These two tools work by creating
|
||||
* and removing symbolic links in the features-enabled directory.
|
||||
*/
|
||||
include "features-enabled/*.conf"
|
||||
|
||||
This `include` directive takes care of including the configuration files for all
|
||||
the features which have been enabled with `icinga2-enable-feature`. See
|
||||
[Enabling/Disabling Features](#features) for more details.
|
||||
|
||||
/**
|
||||
* Although in theory you could define all your objects in this file
|
||||
* the preferred way is to create separate directories and files in the conf.d
|
||||
* directory. Each of these files must have the file extension ".conf".
|
||||
*/
|
||||
include_recursive "conf.d"
|
||||
|
||||
You can put your own configuration files in the `conf.d` directory. This
|
||||
directive makes sure that all of your own configuration files are included.
|
||||
|
||||
### <a id="constants-conf"></a> constants.conf
|
||||
|
||||
The `constants.conf` configuration file can be used to define global constants:
|
||||
|
||||
/**
|
||||
* This file defines global constants which can be used in
|
||||
* the other configuration files. At a minimum the
|
||||
* PluginDir constant should be defined.
|
||||
*/
|
||||
|
||||
const PluginDir = "/usr/lib/nagios/plugins"
|
||||
|
||||
### <a id="localhost-conf"></a> localhost.conf
|
||||
|
||||
The `conf.d/localhost.conf` file contains our first host definition:
|
||||
|
||||
/**
|
||||
* A host definition. You can create your own configuration files
|
||||
* in the conf.d directory (e.g. one per host). By default all *.conf
|
||||
* files in this directory are included.
|
||||
*/
|
||||
object Host "localhost" {
|
||||
import "linux-server"
|
||||
|
||||
address = "127.0.0.1"
|
||||
address6 = "::1"
|
||||
}
|
||||
|
||||
This defines the host `localhost`. The `import` keyword is used to import
|
||||
the `linux-server` template which takes care of setting up the host check
|
||||
as well as adding the host to the `linux-servers` host group.
|
||||
|
||||
The `vars` attribute can be used to define custom attributes which are available
|
||||
for check and notification commands. Most of the templates in the Icinga
|
||||
Template Library require an `address` custom attribute.
|
||||
|
||||
object Service "icinga" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "icinga"
|
||||
}
|
||||
|
||||
object Service "http" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "http_ip"
|
||||
}
|
||||
|
||||
object Service "ssh" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "ssh"
|
||||
}
|
||||
|
||||
object Service "load" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "load"
|
||||
}
|
||||
|
||||
object ScheduledDowntime "backup-downtime" {
|
||||
import "backup-downtime"
|
||||
|
||||
host_name = "localhost"
|
||||
service_name = "load"
|
||||
}
|
||||
|
||||
object Service "processes" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "processes"
|
||||
}
|
||||
|
||||
object Service "users" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "users"
|
||||
}
|
||||
|
||||
object Service "disk" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "disk"
|
||||
}
|
||||
|
||||
The command objects `icinga`, `http_ip`, `ssh`, `load`, `processes`, `users`
|
||||
and `disk` are all provided by the Icinga Template Library (ITL) which
|
||||
we enabled earlier by including the `itl/itl.conf` configuration file.
|
||||
|
|
@ -1,67 +0,0 @@
|
|||
## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
|
||||
|
||||
On its own Icinga 2 does not know how to check external services. The
|
||||
[Monitoring Plugins Project](https://www.monitoring-plugins.org/) provides
|
||||
an extensive set of plugins which can be used with Icinga 2 to check whether
|
||||
services are working properly.
|
||||
|
||||
The recommended way of installing these standard plugins is to use your
|
||||
distribution's package manager.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The `Nagios Plugins` project was renamed to `Monitoring Plugins`
|
||||
> in January 2014. At the time of this writing the packages are still
|
||||
> using the old name.
|
||||
|
||||
For your convenience here is a list of package names for some of the more
|
||||
popular operating systems/distributions:
|
||||
|
||||
OS/Distribution | Package Name | Installation Path
|
||||
-----------------------|--------------------|---------------------------
|
||||
RHEL/CentOS (EPEL) | nagios-plugins-all | /usr/lib/nagios/plugins or /usr/lib64/nagios/plugins
|
||||
Debian | nagios-plugins | /usr/lib/nagios/plugins
|
||||
FreeBSD | nagios-plugins | /usr/local/libexec/nagios
|
||||
OS X (MacPorts) | nagios-plugins | /opt/local/libexec
|
||||
|
||||
Depending on which directory your plugins are installed into you may need to
|
||||
update the global `PluginDir` constant in your Icinga 2 configuration. This macro is used
|
||||
by the service templates contained in the Icinga Template Library to determine
|
||||
where to find the plugin binaries.
|
||||
|
||||
### <a id="integrate-additional-plugins"></a> Integrate Additional Plugins
|
||||
|
||||
For some services you may need additional check plugins which are not provided
|
||||
by the official Monitoring Plugins project.
|
||||
|
||||
All existing Nagios or Icinga 1.x plugins should work with Icinga 2. Here's a
|
||||
list of popular community sites which host check plugins:
|
||||
|
||||
* [MonitoringExchange](https://www.monitoringexchange.org)
|
||||
* [Icinga Wiki](https://wiki.icinga.org)
|
||||
|
||||
The recommended way of setting up these plugins is to copy them to a common directory
|
||||
and create an extra global constant, e.g. `CustomPluginDir` in your `constants.conf`
|
||||
configuration file:
|
||||
|
||||
# cp check_snmp_int.pl /opt/plugins
|
||||
# chmod +x /opt/plugins/check_snmp_int.pl
|
||||
|
||||
# cat /etc/icinga2/constants.conf
|
||||
/**
|
||||
* This file defines global constants which can be used in
|
||||
* the other configuration files. At a minimum the
|
||||
* PluginDir constant should be defined.
|
||||
*/
|
||||
|
||||
const PluginDir = "/usr/lib/nagios/plugins"
|
||||
const CustomPluginDir = "/opt/monitoring"
|
||||
|
||||
Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
|
||||
by trying to run it on the console using whichever user Icinga 2 is running as:
|
||||
|
||||
# su - icinga -s /bin/bash
|
||||
$ /opt/plugins/check_snmp_int.pl --help
|
||||
|
||||
Additional libraries may be required for some plugins. Please consult the plugin
|
||||
documentation and/or README for installation instructions.
|
||||
|
|
@ -1,200 +0,0 @@
|
|||
## <a id="configuring-ido"></a> Configuring 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 a number of projects including Icinga Web.
|
||||
|
||||
There is a separate module for each database back-end. At present support for
|
||||
both MySQL and PostgreSQL is implemented.
|
||||
|
||||
Icinga 2 uses the Icinga 1.x IDOUtils database schema starting with version
|
||||
`1.11.0`. Icinga 2 may require additional features not yet released with
|
||||
Icinga 1.x and therefore require manual upgrade steps during pre-final
|
||||
milestone releases.
|
||||
|
||||
> **Tip**
|
||||
>
|
||||
> Only install the IDO feature if your web interface or reporting tool requires
|
||||
> you to do so (for example, [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2)).
|
||||
> [Icinga Classic UI](#setting-up-icinga-classic-ui) does not use IDO as backend.
|
||||
|
||||
### <a id="configuring-ido-mysql"></a> Configuring IDO MySQL
|
||||
|
||||
#### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
|
||||
|
||||
First of all you have to install the `icinga2-ido-mysql` package using your
|
||||
distribution's package manager. Once you have done that you can proceed with
|
||||
setting up a MySQL database for Icinga 2:
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The Debian packages can optionally create and maintain the database for you
|
||||
> using Debian's `dbconfig` framework. This is the recommended way of setting up
|
||||
> the database.
|
||||
|
||||
# mysql -u root -p
|
||||
|
||||
mysql> CREATE DATABASE icinga;
|
||||
|
||||
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
|
||||
|
||||
mysql> quit
|
||||
|
||||
|
||||
After creating the database you can import the Icinga 2 IDO schema using the
|
||||
following command:
|
||||
|
||||
# mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/mysql.sql
|
||||
|
||||
The Icinga 2 RPM packages install the schema files into
|
||||
`/usr/share/doc/icinga2-ido-mysql-*/schema` (`*` means package version).
|
||||
|
||||
On SuSE-based distributions the schema files are installed in
|
||||
`/usr/share/doc/packages/icinga2-ido-mysql/schema`.
|
||||
|
||||
The Debian/Ubuntu packages put the schema files into
|
||||
`/usr/share/icinga2-ido-mysql/schema`.
|
||||
|
||||
#### <a id="upgrading-mysql-db"></a> Upgrading the MySQL database
|
||||
|
||||
If the database has been installed and requires an upgrade, verify the current
|
||||
schema version first:
|
||||
|
||||
# mysql -u root -p icinga -e 'SELECT version FROM icinga_dbversion;'
|
||||
+---------+
|
||||
| version |
|
||||
+---------+
|
||||
| 1.11.0 |
|
||||
+---------+
|
||||
|
||||
Check the `schema/upgrade` directory for an incremental schema upgrade file, e.g.
|
||||
if your database schema version is `1.11.0` look for `mysql-upgrade-1.12.0.sql`
|
||||
and newer. If there isn't an upgrade file available there's nothing to do.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> During pre release status (0.x.y releases) small snippets called for example
|
||||
> `0.0.8.sql` will ship the required schema updates.
|
||||
|
||||
Apply all database schema upgrade files incrementially.
|
||||
|
||||
# mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/upgrade/mysql-upgrade-1.12.0.sql
|
||||
|
||||
The Icinga 2 IDO module will check for the required database schema version on startup
|
||||
and generate an error message if not satisfied.
|
||||
|
||||
#### <a id="installing-ido-mysql"></a> Installing 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.
|
||||
|
||||
You can enable the `ido-mysql` feature configuration file using `icinga2-enable-feature`:
|
||||
|
||||
# icinga2-enable-feature ido-mysql
|
||||
Module 'ido-mysql' was enabled.
|
||||
Make sure to restart Icinga 2 for these changes to take effect.
|
||||
|
||||
After enabling the ido-mysql feature you have to restart Icinga 2:
|
||||
|
||||
# /etc/init.d/icinga2 restart
|
||||
|
||||
|
||||
### <a id="configuring-ido-postgresql"></a> Configuring IDO PostgreSQL
|
||||
|
||||
#### Setting up the PostgreSQL database
|
||||
|
||||
First of all you have to install the `icinga2-ido-pgsql` package using your
|
||||
distribution's package manager. Once you have done that you can proceed with
|
||||
setting up a PostgreSQL database for Icinga 2:
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The Debian packages can optionally create and maintain the database for you
|
||||
> using Debian's `dbconfig` framework. This is the recommended way of setting up
|
||||
> the database.
|
||||
|
||||
# cd /tmp
|
||||
# sudo -u postgres psql -c "CREATE ROLE icinga WITH LOGIN PASSWORD 'icinga'";
|
||||
# sudo -u postgres createdb -O icinga -E UTF8 icinga
|
||||
# sudo -u postgres createlang plpgsql icinga
|
||||
|
||||
Locate your pg_hba.conf (Debian: `/etc/postgresql/*/main/pg_hba.conf`,
|
||||
RHEL/SUSE: `/var/lib/pgsql/data/pg_hba.conf`), add the icinga user with md5
|
||||
authentication method and restart the postgresql server.
|
||||
|
||||
# vim /var/lib/pgsql/data/pg_hba.conf
|
||||
|
||||
# icinga
|
||||
local icinga icinga md5
|
||||
host icinga icinga 127.0.0.1/32 md5
|
||||
host icinga icinga ::1/128 md5
|
||||
|
||||
# "local" is for Unix domain socket connections only
|
||||
local all all ident
|
||||
# IPv4 local connections:
|
||||
host all all 127.0.0.1/32 ident
|
||||
# IPv6 local connections:
|
||||
host all all ::1/128 ident
|
||||
|
||||
# /etc/init.d/postgresql restart
|
||||
|
||||
|
||||
After creating the database and permissions you can import the Icinga 2 IDO schema
|
||||
using the following command:
|
||||
|
||||
# export PGPASSWORD=icinga
|
||||
# psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/pgsql.sql
|
||||
|
||||
The Icinga 2 RPM packages install the schema files into
|
||||
`/usr/share/doc/icinga2-ido-pgsql-*/schema` (`*` means package version).
|
||||
|
||||
On SuSE-based distributions the schema files are installed in
|
||||
`/usr/share/doc/packages/icinga2-ido-pgsql/schema`.
|
||||
|
||||
The Debian/Ubuntu packages put the schema files into
|
||||
`/usr/share/icinga2-ido-pgsql/schema`.
|
||||
|
||||
#### <a id="upgrading-postgresql-db"></a> Upgrading the PostgreSQL database
|
||||
|
||||
If the database has been installed and requires an upgrade, verify the current
|
||||
schema version first:
|
||||
|
||||
# export PGPASSWORD=icinga
|
||||
# psql -U icinga -d icinga -c "SELECT version FROM icinga_dbversion;"
|
||||
version
|
||||
\---------
|
||||
1.11.0
|
||||
|
||||
Check the `schema/upgrade` directory for an incremental schema upgrade file, e.g.
|
||||
if your database schema version is `1.11.0` look for `pgsql-upgrade-1.12.0.sql`
|
||||
and newer. If there isn't an upgrade file available there's nothing to do.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> During pre release status (0.x.y releases) small snippets called for example
|
||||
> `0.0.8.sql` will ship the required schema updates.
|
||||
|
||||
Apply all database schema upgrade files incrementially.
|
||||
|
||||
# export PGPASSWORD=icinga
|
||||
# psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/upgrade/pgsql-upgrade-1.12.0.sql
|
||||
|
||||
The Icinga 2 IDO module will check for the required database schema version on startup
|
||||
and generate an error message if not satisfied.
|
||||
|
||||
#### <a id="installing-ido-postgresql"></a> Installing 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.
|
||||
|
||||
You can enable the `ido-pgsql` feature configuration file using `icinga2-enable-feature`:
|
||||
|
||||
# icinga2-enable-feature ido-pgsql
|
||||
Module 'ido-pgsql' was enabled.
|
||||
Make sure to restart Icinga 2 for these changes to take effect.
|
||||
|
||||
After enabling the ido-pgsql feature you have to restart Icinga 2:
|
||||
|
||||
# /etc/init.d/icinga2 restart
|
||||
|
|
@ -1,46 +0,0 @@
|
|||
## <a id="setting-up-livestatus"></a> Setting up Livestatus
|
||||
|
||||
The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project
|
||||
implements a query protocol that lets users query their Icinga instance for
|
||||
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](#setting-up-icingaweb2)).
|
||||
> [Icinga Classic UI](#setting-up-icinga-classic-ui) and [Icinga Web](#setting-up-icinga-web)
|
||||
> do not use Livestatus as backend.
|
||||
|
||||
The Livestatus component that is distributed as part of Icinga 2 is a
|
||||
re-implementation of the Livestatus protocol which is compatible with MK
|
||||
Livestatus.
|
||||
|
||||
Details on the available tables and attributes with Icinga 2 can be found
|
||||
in the [Livestatus Schema](#schema-livestatus) section.
|
||||
|
||||
You can enable Livestatus using icinga2-enable-feature:
|
||||
|
||||
# icinga2-enable-feature livestatus
|
||||
|
||||
After that you will have to restart Icinga 2:
|
||||
|
||||
# /etc/init.d/icinga2 restart
|
||||
|
||||
By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`.
|
||||
|
||||
In order for queries and commands to work you will need to add your query user
|
||||
(e.g. your web server) to the `icingacmd` group:
|
||||
|
||||
# usermod -a -G icingacmd www-data
|
||||
|
||||
The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
|
||||
`nagios` if you're using Debian.
|
||||
|
||||
Change "www-data" to the user you're using to run queries.
|
||||
|
||||
In order to use the historical tables provided by the livestatus feature (for example, the
|
||||
`log` table) you need to have the `CompatLogger` feature enabled. By default these logs
|
||||
are expected in `/var/log/icinga2/compat`. A different path can be set using the `compat_log_path`
|
||||
configuration attribute.
|
||||
|
||||
# icinga2-enable-feature compatlog
|
||||
|
|
@ -1,116 +0,0 @@
|
|||
## <a id="setting-up-icinga2-user-interfaces"></a> Setting up Icinga 2 User Interfaces
|
||||
|
||||
Icinga 2 is compatible to Icinga 1.x user interfaces by providing additional
|
||||
features required as backends.
|
||||
|
||||
Furthermore these interfaces (and somewhere in the future an Icinga 2
|
||||
exclusive interface) can be used for the newly created `Icinga Web 2`
|
||||
user interface.
|
||||
|
||||
Some interface features will only work in a limited manner due to
|
||||
[compatibility reasons](#differences-1x-2), other features like the
|
||||
statusmap parents are available dumping the host dependencies as parents.
|
||||
Special restrictions are noted specifically in the sections below.
|
||||
|
||||
> **Tip**
|
||||
>
|
||||
> Choose your preferred interface. There's no need to install [Classic UI](#setting-up-icinga-classic-ui)
|
||||
> if you prefer [Icinga Web](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2) for example.
|
||||
|
||||
### <a id="setting-up-icinga-classic-ui"></a> Setting up Icinga Classic UI
|
||||
|
||||
Icinga 2 can write `status.dat` and `objects.cache` files in the format that
|
||||
is supported by the Icinga 1.x Classic UI. External commands (a.k.a. the
|
||||
"command pipe") are also supported. It also supports writing Icinga 1.x
|
||||
log files which are required for the reporting functionality in the Classic UI.
|
||||
|
||||
#### <a id="installing-icinga-classic-ui"></a> Installing Icinga Classic UI
|
||||
|
||||
The Icinga package repository has both Debian and RPM packages. You can install
|
||||
the Classic UI using the following packages:
|
||||
|
||||
Distribution | Packages
|
||||
--------------|---------------------
|
||||
Debian | icinga2-classicui
|
||||
all others | icinga2-classicui-config icinga-gui
|
||||
|
||||
The Debian packages require additional packages which are provided by the
|
||||
[Debian Monitoring Project](http://www.debmon.org) repository.
|
||||
|
||||
On all distributions other than Debian you may have to restart both your web
|
||||
server as well as Icinga 2 after installing the Classic UI package.
|
||||
|
||||
Verify that your Icinga 1.x Classic UI works by browsing to your Classic
|
||||
UI installation URL:
|
||||
|
||||
Distribution | URL | Default Login
|
||||
--------------|--------------------------------------------------------------------------|--------------------------
|
||||
Debian | [http://localhost/icinga2-classicui](http://localhost/icinga2-classicui) | asked during installation
|
||||
all others | [http://localhost/icinga](http://localhost/icinga) | icingaadmin/icingaadmin
|
||||
|
||||
### <a id="setting-up-icinga-web"></a> Setting up Icinga Web
|
||||
|
||||
Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which
|
||||
is an explicit requirement to run `Icinga Web` next to the external command pipe.
|
||||
Therefore you need to setup the DB IDO feature remarked in the previous sections.
|
||||
|
||||
#### <a id="installing-icinga-web"></a> Installing Icinga Web
|
||||
|
||||
The Icinga package repository has both Debian and RPM packages. You can install
|
||||
the Classic UI using the following packages:
|
||||
|
||||
Distribution | Packages
|
||||
--------------|-------------------------------------
|
||||
RHEL/SUSE | icinga-web icinga-web-{mysql,pgsql}
|
||||
Debian | icinga-web
|
||||
|
||||
Additionally you need to setup the `icinga_web` database.
|
||||
|
||||
The Icinga Web RPM packages install the schema files into
|
||||
`/usr/share/doc/icinga-web-*/schema` (`*` means package version).
|
||||
The Icinga Web dist tarball ships the schema files in `etc/schema`.
|
||||
|
||||
On SuSE-based distributions the schema files are installed in
|
||||
`/usr/share/doc/packages/icinga-web/schema`.
|
||||
|
||||
Additionally you need to enable the `command` feature:
|
||||
|
||||
# icinga2-enable-feature command
|
||||
|
||||
Then edit the Icinga Web configuration for sending commands in `/etc/icinga-web/conf.d/access.xml`
|
||||
(RHEL) or `/etc/icinga-web/access.xml` (SUSE) setting the command pipe path
|
||||
to the default used in Icinga 2. Make sure to clear the cache afterwards.
|
||||
|
||||
# vim /etc/icinga-web/conf.d/access.xml
|
||||
|
||||
<write>
|
||||
<files>
|
||||
<resource name="icinga_pipe">/var/run/icinga2/cmd/icinga.cmd</resource>
|
||||
</files>
|
||||
</write>
|
||||
|
||||
# icinga-web-clearcache
|
||||
|
||||
Verify that your Icinga 1.x Web works by browsing to your Web installation URL:
|
||||
|
||||
Distribution | URL | Default Login
|
||||
--------------|-------------------------------------------------------------|--------------------------
|
||||
Debian | [http://localhost/icinga-web](http://localhost/icinga-web) | asked during installation
|
||||
all others | [http://localhost/icinga-web](http://localhost/icinga-web) | root/password
|
||||
|
||||
### <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
|
||||
|
||||
Icinga Web 2 currently supports `status.dat`, `DB IDO`, or `Livestatus` as backends.
|
||||
Please consult the INSTALL documentation shipped with `Icinga Web 2` for
|
||||
further instructions.
|
||||
|
||||
Icinga Web 2 is still under development. Rather than installing it
|
||||
yourself you should consider testing it using the available Vagrant
|
||||
demo VM.
|
||||
|
||||
### <a id="additional-visualization"></a> Additional visualization
|
||||
|
||||
There are many visualization addons which can be used with Icinga 2.
|
||||
|
||||
Some of the more popular ones are PNP, inGraph (graphing performance data),
|
||||
Graphite, and NagVis (network maps).
|
||||
|
|
@ -1,11 +0,0 @@
|
|||
## <a id="configuration-tools"></a> Configuration Tools
|
||||
|
||||
Well known configuration tools for Icinga 1.x such as [LConf](http://www.netways.de/en/de/produkte/icinga/addons/lconf/),
|
||||
[NConf](http://www.nconf.org/) or [NagiosQL](http://www.nagiosql.org/)
|
||||
store their configuration in a custom format in their backends (LDAP or RDBMS).
|
||||
Currently only LConf 1.4.x supports Icinga 2 configuration export. If you require
|
||||
your favourite configuration tool to export Icinga 2 configuration, please get in
|
||||
touch with their developers.
|
||||
|
||||
If you're looking for puppet manifests, chef cookbooks, ansible recipes, etc - we're happy
|
||||
to integrate them upstream, so please get in touch using [https://support.icinga.org](https://support.icinga.org).
|
||||
|
|
@ -1,115 +0,0 @@
|
|||
## <a id="running-icinga2"></a> Running Icinga 2
|
||||
|
||||
### <a id="init-script"></a> Init Script
|
||||
|
||||
Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
|
||||
|
||||
# /etc/init.d/icinga2
|
||||
Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
|
||||
|
||||
Command | Description
|
||||
--------------------|------------------------
|
||||
start | The `start` action starts the Icinga 2 daemon.
|
||||
stop | The `stop` action stops the Icinga 2 daemon.
|
||||
restart | The `restart` action is a shortcut for running the `stop` action followed by `start`.
|
||||
reload | The `reload` action sends the `HUP` signal to Icinga 2 which causes it to restart. Unlike the `restart` action `reload` does not wait until Icinga 2 has restarted.
|
||||
checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
|
||||
status | The `status` action checks if Icinga 2 is running.
|
||||
|
||||
By default the Icinga 2 daemon is running as `icinga` user and group
|
||||
using the init script. Using Debian packages the user and group are set to `nagios`
|
||||
for historical reasons.
|
||||
|
||||
### <a id="cmdline"></a> Command-line Options
|
||||
|
||||
$ icinga2 --help
|
||||
icinga2 - The Icinga 2 network monitoring daemon.
|
||||
|
||||
Supported options:
|
||||
--help show this help message
|
||||
-V [ --version ] show version information
|
||||
-l [ --library ] arg load a library
|
||||
-I [ --include ] arg add include search directory
|
||||
-D [ --define] args define a constant
|
||||
-c [ --config ] arg parse a configuration file
|
||||
-C [ --validate ] exit after validating the configuration
|
||||
-Z [ --no-validate ] skip validating the configuration
|
||||
-x [ --debug ] enable debugging
|
||||
-d [ --daemonize ] detach from the controlling terminal
|
||||
-e [ --errorlog ] arg log fatal errors to the specified log file (only works
|
||||
in combination with --daemonize)
|
||||
-u [ --user ] arg user to run Icinga as
|
||||
-g [ --group ] arg group to run Icinga as
|
||||
|
||||
Report bugs at <https://dev.icinga.org/>
|
||||
Icinga home page: <http://www.icinga.org/>
|
||||
|
||||
#### Libraries
|
||||
|
||||
Instead of loading libraries using the [`library` config directive](#library)
|
||||
you can also use the `--library` command-line option.
|
||||
|
||||
#### Constants
|
||||
|
||||
[Global constants](#global-constants) can be set using the `--define` command-line option.
|
||||
|
||||
#### 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
|
||||
brackets like this:
|
||||
|
||||
include <test.conf>
|
||||
|
||||
This would cause Icinga 2 to search its include path for the configuration file
|
||||
`test.conf`. By default the installation path for the Icinga Template Library
|
||||
is the only search directory.
|
||||
|
||||
Using the `--include` command-line option additional search directories can be
|
||||
added.
|
||||
|
||||
#### Config Files
|
||||
|
||||
Using the `--config` option you can specify one or more configuration files.
|
||||
Config files are processed in the order they're specified on the command-line.
|
||||
|
||||
#### Config Validation
|
||||
|
||||
The `--validate` option can be used to check if your configuration files
|
||||
contain errors. If any errors are found the exit status is 1, otherwise 0
|
||||
is returned.
|
||||
|
||||
### <a id="features"></a> 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
|
||||
enabled and disabled using the `icinga2-enable-feature` and `icinga2-disable-feature` tools,
|
||||
respectively.
|
||||
|
||||
The `icinga2-enable-feature` tool creates symlinks in the `/etc/icinga2/features-enabled`
|
||||
directory which is included by default in the example configuration file.
|
||||
|
||||
You can view a list of available feature configuration files:
|
||||
|
||||
# icinga2-enable-feature
|
||||
Syntax: icinga2-enable-feature <feature>
|
||||
Enables the specified feature.
|
||||
|
||||
Available features: statusdata
|
||||
|
||||
Using the `icinga2-enable-feature` command you can enable features:
|
||||
|
||||
# icinga2-enable-feature statusdata
|
||||
Module 'statusdata' was enabled.
|
||||
Make sure to restart Icinga 2 for these changes to take effect.
|
||||
|
||||
You can disable features using the `icinga2-disable-feature` command:
|
||||
|
||||
# icinga2-disable-feature statusdata
|
||||
Module 'statusdata' was disabled.
|
||||
Make sure to restart Icinga 2 for these changes to take effect.
|
||||
|
||||
The `icinga2-enable-feature` and `icinga2-disable-feature` commands do not
|
||||
restart Icinga 2. You will need to restart Icinga 2 using the init script
|
||||
after enabling or disabling features.
|
||||
|
||||
|
|
@ -1,3 +1,537 @@
|
|||
# <a id="configuring-icinga2"></a> Configuring Icinga 2
|
||||
|
||||
|
||||
## <a id="configuration-syntax"></a> Configuration Syntax
|
||||
|
||||
### <a id="object-definition"></a> Object Definition
|
||||
|
||||
Icinga 2 features an object-based configuration format. You can define new
|
||||
objects using the `object` keyword:
|
||||
|
||||
object Host "host1.example.org" {
|
||||
display_name = "host1"
|
||||
|
||||
address = "192.168.0.1"
|
||||
address6 = "::1"
|
||||
}
|
||||
|
||||
In general you need to write each statement on a new line. Expressions started
|
||||
with `{`, `(` and `[` extend until the matching closing character and can be broken
|
||||
up into multiple lines.
|
||||
|
||||
Alternatively you can write multiple statements in a single line by separating
|
||||
them with a semicolon:
|
||||
|
||||
object Host "host1.example.org" {
|
||||
display_name = "host1"
|
||||
|
||||
address = "192.168.0.1"; address6 = "::1"
|
||||
}
|
||||
|
||||
Each object is uniquely identified by its type (`Host`) and name
|
||||
(`host1.example.org`). Some types have composite names, e.g. the
|
||||
`Service` type which uses the `host_name` attribute and the name
|
||||
you specified to generate its object name.
|
||||
|
||||
Exclamation marks (!) are not permitted in object names.
|
||||
|
||||
Objects can contain a comma-separated list of property
|
||||
declarations. Instead of commas semicolons may also be used.
|
||||
The following data types are available for property values:
|
||||
|
||||
### Expressions
|
||||
|
||||
The following expressions can be used in the right-hand side of dictionary
|
||||
values.
|
||||
|
||||
#### <a id="numeric-literals"></a> Numeric Literals
|
||||
|
||||
A floating-point number.
|
||||
|
||||
Example:
|
||||
|
||||
-27.3
|
||||
|
||||
#### <a id="duration-literals"></a> Duration Literals
|
||||
|
||||
Similar to floating-point numbers except for the fact that they support
|
||||
suffixes to help with specifying time durations.
|
||||
|
||||
Example:
|
||||
|
||||
2.5m
|
||||
|
||||
Supported suffixes include ms (milliseconds), s (seconds), m (minutes),
|
||||
h (hours) and d (days).
|
||||
|
||||
Duration literals are converted to seconds by the config parser and
|
||||
are treated like numeric literals.
|
||||
|
||||
#### <a id="string-literals"></a> String Literals
|
||||
|
||||
A string.
|
||||
|
||||
Example:
|
||||
|
||||
"Hello World!"
|
||||
|
||||
Certain characters need to be escaped. The following escape sequences
|
||||
are supported:
|
||||
|
||||
Character | Escape sequence
|
||||
--------------------------|------------------------------------
|
||||
" | \\"
|
||||
\\ | \\\\
|
||||
<TAB> | \\t
|
||||
<CARRIAGE-RETURN> | \\r
|
||||
<LINE-FEED> | \\n
|
||||
<BEL> | \\b
|
||||
<FORM-FEED> | \\f
|
||||
|
||||
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.
|
||||
|
||||
#### <a id="multiline-string-literals"></a> Multi-line String Literals
|
||||
|
||||
Strings spanning multiple lines can be specified by enclosing them in
|
||||
{{{ and }}}.
|
||||
|
||||
Example.
|
||||
|
||||
{{{This
|
||||
is
|
||||
a multi-line
|
||||
string.}}}
|
||||
|
||||
Unlike in ordinary strings special characters do not have to be escaped
|
||||
in multi-line string literals.
|
||||
|
||||
#### <a id="boolean-literals"></a> Boolean Literals
|
||||
|
||||
The keywords `true` and `false` are equivalent to 1 and 0 respectively.
|
||||
|
||||
#### <a id="null-value"></a> Null Value
|
||||
|
||||
The `null` keyword can be used to specify an empty value.
|
||||
|
||||
#### <a id="dictionary"></a> Dictionary
|
||||
|
||||
An unordered list of key-value pairs. Keys must be unique and are
|
||||
compared in a case-insensitive manner.
|
||||
|
||||
Individual key-value pairs must be separated from each other with a
|
||||
comma. The comma after the last key-value pair is optional.
|
||||
|
||||
Example:
|
||||
|
||||
{
|
||||
address = "192.168.0.1"
|
||||
port = 443
|
||||
}
|
||||
|
||||
Identifiers may not contain certain characters (e.g. space) or start
|
||||
with certain characters (e.g. digits). If you want to use a dictionary
|
||||
key that is not a valid identifier you can put the key in double
|
||||
quotes.
|
||||
|
||||
Setting a dictionary key to null causes the key and its value to be
|
||||
removed from the dictionary.
|
||||
|
||||
#### <a id="array"></a> Array
|
||||
|
||||
An ordered list of values.
|
||||
|
||||
Individual array elements must be separated from each other with a
|
||||
comma. The comma after the last element is optional.
|
||||
|
||||
Example:
|
||||
|
||||
[ "hello", 42 ]
|
||||
|
||||
An array may simultaneously contain values of different types, such as
|
||||
strings and numbers.
|
||||
|
||||
#### <a id="expression-operators"></a> Operators
|
||||
|
||||
The following operators are supported in expressions:
|
||||
|
||||
Operator | Examples (Result) | Description
|
||||
---------|-----------------------------------------------|--------------------------------
|
||||
! | !"Hello" (false), !false (true) | Log<!-- ignore BLACKLIST -->ical negation of the operand
|
||||
~ | ~true (false) | Bitwise negation of the operand
|
||||
+ | 1 + 3 (4), "hello " + "world" ("hello world") | Adds two numbers; concatenates strings
|
||||
- | 3 - 1 (2) | Subtracts two numbers
|
||||
* | 5m * 10 (3000) | Multiplies two numbers
|
||||
/ | 5m / 5 (60) | Divides two numbers
|
||||
& | 7 & 3 (3) | Binary AND
|
||||
| | 2 | 3 (3) | Binary OR
|
||||
< | 3 < 5 (true) | Less than
|
||||
> | 3 > 5 (false) | Greater than
|
||||
<= | 3 <= 3 (true) | Less than or equal
|
||||
>= | 3 >= 3 (true) | Greater than or equal
|
||||
<< | 4 << 8 (1024) | Left shift
|
||||
>> | 1024 >> 4 (64) | Right shift
|
||||
== | "hello" == "hello" (true), 3 == 5 (false) | Equal to
|
||||
!= | "hello" != "world" (true), 3 != 3 (false) | Not equal to
|
||||
in | "foo" in [ "foo", "bar" ] (true) | Element contained in array
|
||||
!in | "foo" !in [ "bar", "baz" ] (true) | Element not contained in array
|
||||
() | (3 + 3) * 5 | Groups sub-expressions
|
||||
|
||||
Constants may be used in expressions:
|
||||
|
||||
const MyCheckInterval = 10m
|
||||
|
||||
...
|
||||
|
||||
{
|
||||
check_interval = MyCheckInterval / 2.5
|
||||
}
|
||||
|
||||
#### Function Calls
|
||||
|
||||
Functions can be called using the `()` operator:
|
||||
|
||||
const MyGroups = [ "test1", "test" ]
|
||||
|
||||
{
|
||||
check_interval = len(MyGroups) * 1m
|
||||
}
|
||||
|
||||
Function | Description
|
||||
--------------------------------|-----------------------
|
||||
regex(pattern, text) | Returns true if the regex pattern matches the text, false otherwise.
|
||||
match(pattern, text) | Returns true if the wildcard pattern matches the text, false otherwise.
|
||||
len(value) | Returns the length of the value, i.e. the number of elements for an array or dictionary, or the length of the string in bytes.
|
||||
union(array, array, ...) | Returns an array containing all unique elements from the specified arrays.
|
||||
intersection(array, array, ...) | Returns an array containing all unique elements which are common to all specified arrays.
|
||||
string(value) | Converts the value to a string.
|
||||
number(value) | Converts the value to a number.
|
||||
bool(value) | Converts to value to a bool.
|
||||
log(value) | Writes a message to the log. Non-string values are converted to a JSON string.
|
||||
log(severity, facility, value) | Writes a message to the log. `severity` can be one of `LogDebug`, `LogInformation`, `LogWarning` and `LogCritical`. Non-string values are converted to a JSON string.
|
||||
exit(integer) | Terminates the application.
|
||||
|
||||
### <a id="operators"></a> Dictionary Operators
|
||||
|
||||
In addition to the `=` operator shown above a number of other operators
|
||||
to manipulate dictionary elements are supported. Here's a list of all
|
||||
available operators:
|
||||
|
||||
#### <a id="operator-assignment"></a> Operator =
|
||||
|
||||
Sets a dictionary element to the specified value.
|
||||
|
||||
Example:
|
||||
|
||||
{
|
||||
a = 5,
|
||||
a = 7
|
||||
}
|
||||
|
||||
In this example a has the value 7 after both instructions are executed.
|
||||
|
||||
#### <a id="operator-additive-assignment"></a> Operator +=
|
||||
|
||||
The += operator is a shortcut. The following expression:
|
||||
|
||||
{
|
||||
a = [ "hello" ]
|
||||
a += [ "world" ]
|
||||
}
|
||||
|
||||
is equivalent to:
|
||||
|
||||
{
|
||||
a = [ "hello" ]
|
||||
a = a + [ "world" ]
|
||||
}
|
||||
|
||||
#### <a id="operator-substractive-assignment"></a> Operator -=
|
||||
|
||||
The -= operator is a shortcut. The following expression:
|
||||
|
||||
{
|
||||
a = 10
|
||||
a -= 5
|
||||
}
|
||||
|
||||
is equivalent to:
|
||||
|
||||
{
|
||||
a = 10
|
||||
a = a - 5
|
||||
}
|
||||
|
||||
#### <a id="operator-multiply-assignment"></a> Operator \*=
|
||||
|
||||
The *= operator is a shortcut. The following expression:
|
||||
|
||||
{
|
||||
a = 60
|
||||
a *= 5
|
||||
}
|
||||
|
||||
is equivalent to:
|
||||
|
||||
{
|
||||
a = 60
|
||||
a = a * 5
|
||||
}
|
||||
|
||||
#### <a id="operator-dividing-assignment"></a> Operator /=
|
||||
|
||||
The /= operator is a shortcut. The following expression:
|
||||
|
||||
{
|
||||
a = 300
|
||||
a /= 5
|
||||
}
|
||||
|
||||
is equivalent to:
|
||||
|
||||
{
|
||||
a = 300
|
||||
a = a / 5
|
||||
}
|
||||
|
||||
### <a id="indexer"></a> Indexer
|
||||
|
||||
The indexer syntax provides a convenient way to set dictionary elements.
|
||||
|
||||
Example:
|
||||
|
||||
{
|
||||
hello.key = "world"
|
||||
}
|
||||
|
||||
Example (alternative syntax):
|
||||
|
||||
{
|
||||
hello["key"] = "world"
|
||||
}
|
||||
|
||||
This is equivalent to writing:
|
||||
|
||||
{
|
||||
hello += {
|
||||
key = "world"
|
||||
}
|
||||
}
|
||||
|
||||
### <a id="template-imports"></a> Template Imports
|
||||
|
||||
Objects can import attributes from other objects.
|
||||
|
||||
Example:
|
||||
|
||||
template Host "default-host" {
|
||||
vars.color = "red"
|
||||
}
|
||||
|
||||
template Host "test-host" {
|
||||
import "default-host"
|
||||
|
||||
vars.color = "blue"
|
||||
}
|
||||
|
||||
object Host "localhost" {
|
||||
import "test-host"
|
||||
|
||||
address = "127.0.0.1"
|
||||
address6 = "::1"
|
||||
}
|
||||
|
||||
The `default-host` and `test-host` objects are marked as templates
|
||||
using the `template` keyword. Unlike ordinary objects templates are not
|
||||
instantiated at run-time. Parent objects do not necessarily have to be
|
||||
templates, however in general they are.
|
||||
|
||||
The `vars` dictionary for the `localhost` object contains all three
|
||||
custom attributes and the custom attribute `color` has the value `"blue"`.
|
||||
|
||||
Parent objects are resolved in the order they're specified using the
|
||||
`import` keyword.
|
||||
|
||||
### <a id="constants"></a> Constants
|
||||
|
||||
Global constants can be set using the `const` keyword:
|
||||
|
||||
const VarName = "some value"
|
||||
|
||||
Once defined a constant can be access from any file. Constants cannot be changed
|
||||
once they are set.
|
||||
|
||||
### <a id="apply"></a> Apply
|
||||
|
||||
The `apply` keyword can be used to create new objects which are associated with
|
||||
another group of objects.
|
||||
|
||||
apply Service "ping" to Host {
|
||||
import "generic-service"
|
||||
|
||||
check_command = "ping4"
|
||||
|
||||
assign where host.name == "localhost"
|
||||
}
|
||||
|
||||
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 "ping"
|
||||
is created for each matching host.
|
||||
|
||||
The `to` keyword and the target type may be omitted if there is only target
|
||||
type, e.g. for the `Service` type.
|
||||
|
||||
Depending on the object type used in the `apply` expression additional local
|
||||
variables may be available for use in the `where` condition:
|
||||
|
||||
Source Type | Target Type | Variables
|
||||
------------------|-------------|--------------
|
||||
Service | Host | host
|
||||
Dependency | Host | host
|
||||
Dependency | Service | host, service
|
||||
Notification | Host | host
|
||||
Notification | Service | host, service
|
||||
ScheduledDowntime | Host | host
|
||||
ScheduledDowntime | Service | host, service
|
||||
|
||||
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.
|
||||
|
||||
### <a id="group-assign"></a> Group Assign
|
||||
|
||||
Group objects can be assigned to specific member objects using the `assign where`
|
||||
and `ignore where` conditions.
|
||||
|
||||
object HostGroup "linux-servers" {
|
||||
display_name = "Linux Servers"
|
||||
|
||||
assign where host.vars.os == "Linux"
|
||||
}
|
||||
|
||||
In this example the `assign where` condition is a boolean expression which is evaluated
|
||||
for all objects of the type `Host`. Each matching host is added as member to the host group
|
||||
with the name "linux-servers". Membership exclusion can be controlled using the `ignore where`
|
||||
condition.
|
||||
|
||||
Source Type | Variables
|
||||
------------------|--------------
|
||||
HostGroup | host
|
||||
ServiceGroup | host, service
|
||||
UserGroup | user
|
||||
|
||||
|
||||
### <a id="boolean-values"></a> Boolean Values
|
||||
|
||||
The `assign where` and `ignore where` statements, the `!`, `&&` and `||`
|
||||
operators as well as the `bool()` function convert their arguments to a
|
||||
boolean value based on the following rules:
|
||||
|
||||
Description | Example Value | Boolean Value
|
||||
---------------------|-------------------|--------------
|
||||
Empty value | null | false
|
||||
Zero | 0 | false
|
||||
Non-zero integer | -23945 | true
|
||||
Empty string | "" | false
|
||||
Non-empty string | "Hello" | true
|
||||
Empty array | [] | false
|
||||
Non-empty array | [ "Hello" ] | true
|
||||
Empty dictionary | {} | false
|
||||
Non-empty dictionary | { key = "value" } | true
|
||||
|
||||
### <a id="comments"></a> Comments
|
||||
|
||||
The Icinga 2 configuration format supports C/C++-style and shell-style comments.
|
||||
|
||||
Example:
|
||||
|
||||
/*
|
||||
This is a comment.
|
||||
*/
|
||||
object Host "localhost" {
|
||||
check_interval = 30 // this is also a comment.
|
||||
retry_interval = 15 # yet another comment
|
||||
}
|
||||
|
||||
### <a id="includes"></a> Includes
|
||||
|
||||
Other configuration files can be included using the `include` directive.
|
||||
Paths must be relative to the configuration file that contains the
|
||||
`include` directive.
|
||||
|
||||
Example:
|
||||
|
||||
include "some/other/file.conf"
|
||||
include "conf.d/*.conf"
|
||||
|
||||
Wildcard includes are not recursive.
|
||||
|
||||
Icinga also supports include search paths similar to how they work in a
|
||||
C/C++ compiler:
|
||||
|
||||
include <itl/itl.conf>
|
||||
|
||||
Note the use of angle brackets instead of double quotes. This causes the
|
||||
config compiler to search the include search paths for the specified
|
||||
file. By default $PREFIX/share/icinga2 is included in the list of search
|
||||
paths. Additional include search paths can be added using
|
||||
[command-line options](#cmdline).
|
||||
|
||||
Wildcards are not permitted when using angle brackets.
|
||||
|
||||
### <a id="recursive-includes"></a> Recursive Includes
|
||||
|
||||
The `include_recursive` directive can be used to recursively include all
|
||||
files in a directory which match a certain pattern.
|
||||
|
||||
Example:
|
||||
|
||||
include_recursive "conf.d", "*.conf"
|
||||
include_recursive "templates"
|
||||
|
||||
The first parameter specifies the directory from which files should be
|
||||
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.
|
||||
|
||||
### <a id="library"></a> Library directive
|
||||
|
||||
The `library` directive can be used to manually load additional
|
||||
libraries. Libraries can be used to provide additional object types and
|
||||
functions.
|
||||
|
||||
Example:
|
||||
|
||||
library "snmphelper"
|
||||
|
||||
|
||||
|
||||
## <a id="global-constants"></a> Global Constants
|
||||
|
||||
Icinga 2 provides a number of special global constants. Some of them can be overriden using the `--define` command line parameter:
|
||||
|
||||
Variable |Description
|
||||
--------------------|-------------------
|
||||
PrefixDir |**Read-only.** Contains the installation prefix that was specified with cmake -DCMAKE_INSTALL_PREFIX. Defaults to "/usr/local".
|
||||
SysconfDir |**Read-only.** Contains the path of the sysconf directory. Defaults to PrefixDir + "/etc".
|
||||
LocalStateDir |**Read-only.** Contains the path of the local state directory. Defaults to PrefixDir + "/var".
|
||||
PkgDataDir |**Read-only.** Contains the path of the package data directory. Defaults to PrefixDir + "/share/icinga2".
|
||||
StatePath |**Read-write.** Contains the path of the Icinga 2 state file. Defaults to LocalStateDir + "/lib/icinga2/icinga2.state".
|
||||
PidPath |**Read-write.** Contains the path of the Icinga 2 PID file. Defaults to LocalStateDir + "/run/icinga2/icinga2.pid".
|
||||
Vars |**Read-write.** Contains a dictionary with global custom attributes. Not set by default.
|
||||
NodeName |**Read-write.** Contains the cluster node name. Set to the local hostname by default.
|
||||
ApplicationType |**Read-write.** Contains the name of the Application type. Defaults to "icinga/IcingaApplication".
|
||||
EnableNotifications |**Read-write.** Whether notifications are globally enabled. Defaults to true.
|
||||
EnableEventHandlers |**Read-write.** Whether event handlers are globally enabled. Defaults to true.
|
||||
EnableFlapping |**Read-write.** Whether flap detection is globally enabled. Defaults to true.
|
||||
EnableHostChecks |**Read-write.** Whether active host checks are globally enabled. Defaults to true.
|
||||
EnableServiceChecks |**Read-write.** Whether active service checks are globally enabled. Defaults to true.
|
||||
EnablePerfdata |**Read-write.** Whether performance data processing is globally enabled. Defaults to true.
|
||||
UseVfork |**Read-write.** Whether to use vfork(). Only available on *NIX. Defaults to true.
|
||||
|
||||
|
||||
## <a id="object-types"></a> Object Types
|
||||
|
||||
### <a id="objecttype-host"></a> Host
|
||||
|
|
@ -105,9 +639,29 @@ Attributes:
|
|||
host_name |**Required.** The host this service belongs to. There must be a `Host` object with that name.
|
||||
name |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
|
||||
groups |**Optional.** The service groups this service belongs to.
|
||||
vars |**Optional.** A dictionary containing custom attributes that are specific to this service.
|
||||
check\_command |**Required.** The name of the check command.
|
||||
max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
|
||||
check\_period |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
|
||||
check\_interval |**Optional.** The check interval (in seconds). This interval is used for checks when the service is in a `HARD` state. Defaults to 5 minutes.
|
||||
retry\_interval |**Optional.** The retry interval (in seconds). This interval is used for checks when the service is in a `SOFT` state. Defaults to 1 minute.
|
||||
enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
|
||||
enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
|
||||
enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
|
||||
enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
|
||||
enable\_flap\_detection|**Optional.** Whether flap detection is enabled. Defaults to true.
|
||||
enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
|
||||
event\_command |**Optional.** The name of an event command that should be executed every time the service's state changes.
|
||||
flapping\_threshold|**Optional.** The flapping threshold in percent when a service is considered to be flapping.
|
||||
volatile |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
|
||||
authorities |**Optional.** A list of Endpoints on which this service check will be executed in a cluster scenario.
|
||||
domains |**Optional.** A list of Domains for this service object in a cluster scenario.
|
||||
notes |**Optional.** Notes for the service.
|
||||
notes_url |**Optional.** Url for notes for the service (for example, in notification commands).
|
||||
action_url |**Optional.** Url for actions for the service (for example, an external graphing tool).
|
||||
icon_image |**Optional.** Icon image for the service. Required for external interfaces only.
|
||||
icon_image_alt |**Optional.** Icon image description for the service. Required for external interface only.
|
||||
|
||||
In addition to these attributes you can also use any of the attributes except the `address` and `address6` which are also valid
|
||||
for `Host` objects.
|
||||
|
||||
Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
|
||||
you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
|
||||
|
|
@ -524,7 +1078,7 @@ Attributes:
|
|||
### <a id="objecttype-perfdatawriter"></a> PerfdataWriter
|
||||
|
||||
Writes check result performance data to a defined path using macro
|
||||
pattern.
|
||||
pattern consisting of custom attributes and runtime macros.
|
||||
|
||||
Example:
|
||||
|
||||
|
|
@ -912,12 +1466,12 @@ Example:
|
|||
|
||||
object ClusterListener "cluster" {
|
||||
ca_path = "/etc/icinga2/ca/ca.crt"
|
||||
cert_path = "/etc/icinga2/ca/icinga-node-1.crt"
|
||||
key_path = "/etc/icinga2/ca/icinga-node-1.key"
|
||||
cert_path = "/etc/icinga2/ca/icinga2a.crt"
|
||||
key_path = "/etc/icinga2/ca/icinga2a.key"
|
||||
|
||||
bind_port = 8888
|
||||
|
||||
peers = [ "icinga-node-2" ]
|
||||
peers = [ "icinga2b" ]
|
||||
}
|
||||
|
||||
Attributes:
|
||||
|
|
@ -941,7 +1495,7 @@ Example:
|
|||
|
||||
library "cluster"
|
||||
|
||||
object Endpoint "icinga-c2" {
|
||||
object Endpoint "icinga2b" {
|
||||
host = "192.168.5.46"
|
||||
port = 7777
|
||||
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
# <a id="monitoring-basics"></a> 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.
|
||||
|
|
@ -1,74 +0,0 @@
|
|||
## <a id="hosts-services"></a> Hosts and Services
|
||||
|
||||
Icinga 2 can be used to monitor the availability of hosts and services. Services
|
||||
can be virtually anything which can be checked in some way:
|
||||
|
||||
* Network services (HTTP, SMTP, SNMP, SSH, etc.)
|
||||
* Printers
|
||||
* Switches / Routers
|
||||
* Temperature Sensors
|
||||
* Other local or network-accessible services
|
||||
|
||||
Host objects provide a mechanism to group services that are running
|
||||
on the same physical device.
|
||||
|
||||
Here is an example of a host object which defines two child services:
|
||||
|
||||
object Host "my-server1" {
|
||||
address = "10.0.0.1"
|
||||
check_command = "hostalive"
|
||||
}
|
||||
|
||||
object Service "ping4" {
|
||||
host_name = "localhost"
|
||||
check_command = "ping4"
|
||||
}
|
||||
|
||||
object Service "http" {
|
||||
host_name = "localhost"
|
||||
check_command = "http_ip"
|
||||
}
|
||||
|
||||
The example creates two services `ping4` and `http` which belong to the
|
||||
host `my-server1`.
|
||||
|
||||
It also specifies that the host should perform its own check using the `hostalive`
|
||||
check command.
|
||||
|
||||
The `address` custom attribute is used by check commands to determine which network
|
||||
address is associated with the host object.
|
||||
|
||||
### <a id="host-states"></a> Host States
|
||||
|
||||
Hosts can be in any of the following states:
|
||||
|
||||
Name | Description
|
||||
------------|--------------
|
||||
UP | The host is available.
|
||||
DOWN | The host is unavailable.
|
||||
|
||||
### <a id="service-states"></a> Service States
|
||||
|
||||
Services can be in any of the following states:
|
||||
|
||||
Name | Description
|
||||
------------|--------------
|
||||
OK | The service is working properly.
|
||||
WARNING | The service is experiencing some problems but is still considered to be in working condition.
|
||||
CRITICAL | The service is in a critical state.
|
||||
UNKNOWN | The check could not determine the service's state.
|
||||
|
||||
### <a id="hard-soft-states"></a> Hard and Soft States
|
||||
|
||||
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
|
||||
notifications. This ensures that no unnecessary notifications are sent for
|
||||
transient failures. During this time the object is in a `SOFT` state.
|
||||
|
||||
After all re-checks have been executed and the object is still in a non-OK
|
||||
state the host/service switches to a `HARD` state and notifications are sent.
|
||||
|
||||
Name | Description
|
||||
------------|--------------
|
||||
HARD | The host/service's state hasn't recently changed.
|
||||
SOFT | The host/service has recently changed state and is being re-checked.
|
||||
|
|
@ -1,173 +0,0 @@
|
|||
## <a id="commands"></a> 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.
|
||||
|
||||
### <a id="command-environment-variables"></a> Environment Variables for Commands
|
||||
|
||||
Please check [Runtime Custom Attributes as Environment Variables](#runtime-custom-attribute-env-vars).
|
||||
|
||||
### <a id="check-commands"></a> Check Commands
|
||||
|
||||
`CheckCommand` objects define the command line how a check is called.
|
||||
|
||||
`CheckCommand` objects require the ITL template `plugin-check-command`
|
||||
to support native plugin based check methods.
|
||||
|
||||
Unless you have done so already, download your check plugin and put it
|
||||
into the `PluginDir` directory. The following example uses the
|
||||
`check_disk` plugin shipped with the Nagios Plugins package.
|
||||
|
||||
The plugin path and all command arguments are made a list of
|
||||
double-quoted string arguments for proper shell escaping.
|
||||
|
||||
Call the `check_disk` plugin with the `--help` parameter to see
|
||||
all available options. Our example defines warning (`-w`) and
|
||||
critical (`-c`) thresholds for the disk usage. Without any
|
||||
partition defined (`-p`) it will check all local partitions.
|
||||
|
||||
Define the default check command custom attribute `wfree` and `cfree` freely
|
||||
definable naming schema) and their default threshold values. You can
|
||||
then use these custom attributes as runtime macros on the command line.
|
||||
|
||||
The default custom attributes can be overridden by the custom attributes
|
||||
defined in the service using the check command `disk`. The custom attributes
|
||||
can also be inherited from a parent template using additive inheritance (`+=`).
|
||||
|
||||
object CheckCommand "disk" {
|
||||
import "plugin-check-command"
|
||||
|
||||
command = [
|
||||
PluginDir + "/check_disk",
|
||||
"-w", "$wfree$%",
|
||||
"-c", "$cfree$%"
|
||||
],
|
||||
|
||||
vars.wfree = 20
|
||||
vars.cfree = 10
|
||||
}
|
||||
|
||||
The host `localhost` with the service `disk` checks all disks with modified
|
||||
custom attributes (warning thresholds at `10%`, critical thresholds at `5%`
|
||||
free disk space).
|
||||
|
||||
object Host "localhost" {
|
||||
import "generic-host"
|
||||
|
||||
address = "127.0.0.1"
|
||||
address6 = "::1"
|
||||
}
|
||||
|
||||
object Service "disk" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "disk"
|
||||
|
||||
vars.wfree = 10
|
||||
vars.cfree = 5
|
||||
}
|
||||
|
||||
|
||||
### <a id="notification-commands"></a> Notification Commands
|
||||
|
||||
`NotificationCommand` objects define how notifications are delivered to external
|
||||
interfaces (E-Mail, XMPP, IRC, Twitter, etc).
|
||||
|
||||
`NotificationCommand` objects require the ITL template `plugin-notification-command`
|
||||
to support native plugin-based notifications.
|
||||
|
||||
Below is an example using runtime macros from Icinga 2 (such as `$service.output$` for
|
||||
the current check output) sending an email to the user(s) associated with the
|
||||
notification itself (`$user.email$`).
|
||||
|
||||
If you want to specify default values for some of the custom attribute definitions,
|
||||
you can add a `vars` dictionary as shown for the `CheckCommand` object.
|
||||
|
||||
TODO
|
||||
|
||||
object NotificationCommand "mail-service-notification" {
|
||||
import "plugin-notification-command"
|
||||
|
||||
command = [ SysconfDir + "/icinga2/scripts/mail-notification.sh" ]
|
||||
|
||||
env = {
|
||||
"NOTIFICATIONTYPE" = "$notification.type$"
|
||||
"SERVICEDESC" = "$service.name$"
|
||||
"HOSTALIAS" = "$host.display_name$",
|
||||
"HOSTADDRESS" = "$address$",
|
||||
"SERVICESTATE" = "$service.state$",
|
||||
"LONGDATETIME" = "$icinga.long_date_time$",
|
||||
"SERVICEOUTPUT" = "$service.output$",
|
||||
"NOTIFICATIONAUTHORNAME" = "$notification.author$",
|
||||
"NOTIFICATIONCOMMENT" = "$notification.comment$",
|
||||
"HOSTDISPLAYNAME" = "$host.display_name$",
|
||||
"SERVICEDISPLAYNAME" = "$service.display_name$",
|
||||
"USEREMAIL" = "$user.email$"
|
||||
}
|
||||
}
|
||||
|
||||
The command attribute in the `mail-service-notification` command refers to the following
|
||||
shell script. The macros specified in the `env` array are exported
|
||||
as environment variables and can be used in the notification script:
|
||||
|
||||
#!/usr/bin/env bash
|
||||
template=$(cat <<TEMPLATE
|
||||
***** Icinga *****
|
||||
|
||||
Notification Type: $NOTIFICATIONTYPE
|
||||
|
||||
Service: $SERVICEDESC
|
||||
Host: $HOSTALIAS
|
||||
Address: $HOSTADDRESS
|
||||
State: $SERVICESTATE
|
||||
|
||||
Date/Time: $LONGDATETIME
|
||||
|
||||
Additional Info: $SERVICEOUTPUT
|
||||
|
||||
Comment: [$NOTIFICATIONAUTHORNAME] $NOTIFICATIONCOMMENT
|
||||
TEMPLATE
|
||||
)
|
||||
|
||||
/usr/bin/printf "%b" $template | mail -s "$NOTIFICATIONTYPE - $HOSTDISPLAYNAME - $SERVICEDISPLAYNAME is $SERVICESTATE" $USEREMAIL
|
||||
|
||||
While it's possible to specify the entire notification command right
|
||||
in the NotificationCommand object it is generally advisable to create a
|
||||
shell script in the `/etc/icinga2/scripts` directory and have the
|
||||
NotificationCommand object refer to that.
|
||||
|
||||
### <a id="event-commands"></a> Event Commands
|
||||
|
||||
Unlike notifications event commands are called on every service state change
|
||||
if defined. Therefore the `EventCommand` object should define a command line
|
||||
evaluating the current service state and other service runtime attributes
|
||||
available through runtime vars. Runtime macros such as `$SERVICESTATETYPE$`
|
||||
and `$SERVICESTATE$` will be processed by Icinga 2 helping on fine-granular
|
||||
events being triggered.
|
||||
|
||||
Common use case scenarios are a failing HTTP check requiring an immediate
|
||||
restart via event command, or if an application is locked and requires
|
||||
a restart upon detection.
|
||||
|
||||
`EventCommand` objects require the ITL template `plugin-event-command`
|
||||
to support native plugin based checks.
|
||||
|
||||
When the event command is triggered on a service state change, it will
|
||||
send a check result using the `process_check_result` script forcibly
|
||||
changing the service state back to `OK` (`-r 0`) providing some debug
|
||||
information in the check output (`-o`).
|
||||
|
||||
object EventCommand "plugin-event-process-check-result" {
|
||||
import "plugin-event-command"
|
||||
|
||||
command = [
|
||||
PluginDir + "/process_check_result",
|
||||
"-H", "$host.name$",
|
||||
"-S", "$service.name$",
|
||||
"-c", LocalStateDir + "/run/icinga2/cmd/icinga2.cmd",
|
||||
"-r", "0",
|
||||
"-o", "Event Handler triggered in state '$service.state$' with output '$service.output$'."
|
||||
]
|
||||
}
|
||||
|
|
@ -1,228 +0,0 @@
|
|||
## <a id="custom-attributes"></a> Custom Attributes
|
||||
|
||||
### <a id="runtime-custom-attributes"></a> Using Custom Attributes at Runtime
|
||||
|
||||
Custom attributes may be used in command definitions to dynamically change how the command
|
||||
is executed.
|
||||
|
||||
Additionally there are Icinga 2 features such as the `PerfDataWriter` type
|
||||
which use custom attributes to format their output.
|
||||
|
||||
> **Tip**
|
||||
>
|
||||
> Custom attributes are identified by the 'vars' dictionary attribute as short name.
|
||||
> Accessing the different attribute keys is possible using the '.' accessor.
|
||||
|
||||
Custom attributes in command definitions or performance data templates are evaluated at
|
||||
runtime when executing a command. These custom attributes cannot be used elsewhere
|
||||
(e.g. in other configuration attributes).
|
||||
|
||||
Here is an example of a command definition which uses user-defined custom attributes:
|
||||
|
||||
object CheckCommand "my-ping" {
|
||||
import "plugin-check-command"
|
||||
|
||||
command = [
|
||||
PluginDir + "/check_ping",
|
||||
"-4",
|
||||
"-H", "$address$",
|
||||
"-w", "$wrta$,$wpl$%",
|
||||
"-c", "$crta$,$cpl$%",
|
||||
"-p", "$packets$",
|
||||
"-t", "$timeout$"
|
||||
]
|
||||
|
||||
vars.wrta = 100
|
||||
vars.wpl = 5
|
||||
vars.crta = 200
|
||||
vars.cpl = 15
|
||||
vars.packets = 5
|
||||
vars.timeout = 0
|
||||
}
|
||||
|
||||
Custom attribute names used at runtime must be enclosed in two `$` signs, e.g.
|
||||
`$address$`. When using the `$` sign as single character, you need to escape
|
||||
it with an additional dollar sign (`$$`).
|
||||
|
||||
### <a id="runtime-custom-attributes-evaluation-order"></a> Runtime Custom Attributes Evaluation Order
|
||||
|
||||
When executing commands Icinga 2 checks the following objects in this order to look
|
||||
up custom attributes and their respective values:
|
||||
|
||||
1. User object (only for notifications)
|
||||
2. Service object
|
||||
3. Host object
|
||||
4. Command object
|
||||
5. Global custom attributes in the Vars constant
|
||||
|
||||
This execution order allows you to define default values for custom attributes
|
||||
in your command objects. The `my-ping` command shown above uses this to set
|
||||
default values for some of the latency thresholds and timeouts.
|
||||
|
||||
When using the `my-ping` command you can override all or some of the custom
|
||||
attributes in the service definition like this:
|
||||
|
||||
object Service "ping" {
|
||||
host_name = "localhost"
|
||||
check_command = "my-ping"
|
||||
|
||||
vars.packets = 10 // Overrides the default value of 5 given in the command
|
||||
}
|
||||
|
||||
If a custom attribute isn't defined anywhere an empty value is used and a warning is
|
||||
emitted to the Icinga 2 log.
|
||||
|
||||
> **Best Practice**
|
||||
>
|
||||
> By convention every host should have an `address` attribute. Hosts
|
||||
> which have an IPv6 address should also have an `address6` attribute.
|
||||
|
||||
### <a id="runtime-custom-attribute-env-vars"></a> Runtime Custom Attributes as Environment Variables
|
||||
|
||||
TODO
|
||||
|
||||
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
|
||||
prior to executing the command.
|
||||
|
||||
This is useful for example for hiding sensitive information on the command line output
|
||||
when passing credentials to database checks:
|
||||
|
||||
object CheckCommand "mysql-health" {
|
||||
import "plugin-check-command",
|
||||
|
||||
command = PluginDir + "/check_mysql -H $address$ -d $db$",
|
||||
|
||||
/* default custom attribute values */
|
||||
vars = {
|
||||
mysql_user = "icinga_check",
|
||||
mysql_pass = "password"
|
||||
},
|
||||
|
||||
env = {
|
||||
MYSQLUSER = "$mysql_user$",
|
||||
MYSQLPASS = "$mysql_pass$"
|
||||
}
|
||||
}
|
||||
|
||||
## <a id="runtime-macros"></a> Runtime Macros
|
||||
|
||||
Next to custom attributes there are additional runtime macros made available by Icinga 2.
|
||||
These runtime macros reflect the current object state and may change over time while
|
||||
custom attributes are configured statically (but can be modified at runtime using
|
||||
external commands).
|
||||
|
||||
### <a id="host-runtime-macros"></a> Host Runtime Macros
|
||||
|
||||
The following host custom attributes are available in all commands that are executed for
|
||||
hosts or services:
|
||||
|
||||
Name | Description
|
||||
-----------------------------|--------------
|
||||
host.name | The name of the host object.
|
||||
host.display_name | The value of the `display_name` attribute.
|
||||
host.state | The host's current state. Can be one of `UNREACHABLE`, `UP` and `DOWN`.
|
||||
host.state_id | The host's current state. Can be one of `0` (up), `1` (down) and `2` (unreachable).
|
||||
host.state_type | The host's current state type. Can be one of `SOFT` and `HARD`.
|
||||
host.check_attempt | The current check attempt number.
|
||||
host.max_check_attempts | The maximum number of checks which are executed before changing to a hard state.
|
||||
host.last_state | The host's previous state. Can be one of `UNREACHABLE`, `UP` and `DOWN`.
|
||||
host.last_state_id | The host's previous state. Can be one of `0` (up), `1` (down) and `2` (unreachable).
|
||||
host.last_state_type | The host's previous state type. Can be one of `SOFT` and `HARD`.
|
||||
host.last_state_change | The last state change's timestamp.
|
||||
host.duration_sec | The time since the last state change.
|
||||
host.latency | The host's check latency.
|
||||
host.execution_time | The host's check execution time.
|
||||
host.output | The last check's output.
|
||||
host.perfdata | The last check's performance data.
|
||||
host.last_check | The timestamp when the last check was executed.
|
||||
host.total_services | Number of services associated with the host.
|
||||
host.total_services_ok | Number of services associated with the host which are in an `OK` state.
|
||||
host.total_services_warning | Number of services associated with the host which are in a `WARNING` state.
|
||||
host.total_services_unknown | Number of services associated with the host which are in an `UNKNOWN` state.
|
||||
host.total_services_critical | Number of services associated with the host which are in a `CRITICAL` state.
|
||||
|
||||
### <a id="service-runtime-macros"></a> Service Runtime Macros
|
||||
|
||||
The following service macros are available in all commands that are executed for
|
||||
services:
|
||||
|
||||
Name | Description
|
||||
---------------------------|--------------
|
||||
service.name | The short name of the service object.
|
||||
service.display_name | The value of the `display_name` attribute.
|
||||
service.check_command | The short name of the command along with any arguments to be used for the check.
|
||||
service.state | The service's current state. Can be one of `OK`, `WARNING`, `CRITICAL` and `UNKNOWN`.
|
||||
service.state_id | The service's current state. Can be one of `0` (ok), `1` (warning), `2` (critical) and `3` (unknown).
|
||||
service.state_type | The service's current state type. Can be one of `SOFT` and `HARD`.
|
||||
service.check_attempt | The current check attempt number.
|
||||
service.max_check_attempts | The maximum number of checks which are executed before changing to a hard state.
|
||||
service.last_state | The service's previous state. Can be one of `OK`, `WARNING`, `CRITICAL` and `UNKNOWN`.
|
||||
service.last_state_id | The service's previous state. Can be one of `0` (ok), `1` (warning), `2` (critical) and `3` (unknown).
|
||||
service.last_state_type | The service's previous state type. Can be one of `SOFT` and `HARD`.
|
||||
service.last_state_change | The last state change's timestamp.
|
||||
service.duration_sec | The time since the last state change.
|
||||
service.latency | The service's check latency.
|
||||
service.execution_time | The service's check execution time.
|
||||
service.output | The last check's output.
|
||||
service.perfdata | The last check's performance data.
|
||||
service.last_check | The timestamp when the last check was executed.
|
||||
|
||||
### <a id="command-runtime-macros"></a> Command Runtime Macros
|
||||
|
||||
The following custom attributes are available in all commands:
|
||||
|
||||
Name | Description
|
||||
-----------------------|--------------
|
||||
command.name | The name of the command object.
|
||||
|
||||
### <a id="user-runtime-macros"></a> User Runtime Macros
|
||||
|
||||
The following custom attributes are available in all commands that are executed for
|
||||
users:
|
||||
|
||||
Name | Description
|
||||
-----------------------|--------------
|
||||
user.name | The name of the user object.
|
||||
user.display_name | The value of the display_name attribute.
|
||||
|
||||
### <a id="notification-runtime-macros"></a> Notification Runtime Macros
|
||||
|
||||
Name | Description
|
||||
-----------------------|--------------
|
||||
notification.type | The type of the notification.
|
||||
notification.author | The author of the notification comment, if existing.
|
||||
notification.comment | The comment of the notification, if existing.
|
||||
|
||||
### <a id="global-runtime-macros"></a> Global Runtime Macros
|
||||
|
||||
The following macros are available in all executed commands:
|
||||
|
||||
Name | Description
|
||||
-----------------------|--------------
|
||||
icinga.timet | Current UNIX timestamp.
|
||||
icinga.long_date_time | Current date and time including timezone information. Example: `2014-01-03 11:23:08 +0000`
|
||||
icinga.short_date_time | Current date and time. Example: `2014-01-03 11:23:08`
|
||||
icinga.date | Current date. Example: `2014-01-03`
|
||||
icinga.time | Current time including timezone information. Example: `11:23:08 +0000`
|
||||
icinga.uptime | Current uptime of the Icinga 2 process.
|
||||
|
||||
The following macros provide global statistics:
|
||||
|
||||
Name | Description
|
||||
----------------------------------|--------------
|
||||
icinga.num_services_ok | Current number of services in state 'OK'.
|
||||
icinga.num_services_warning | Current number of services in state 'Warning'.
|
||||
icinga.num_services_critical | Current number of services in state 'Critical'.
|
||||
icinga.num_services_unknown | Current number of services in state 'Unknown'.
|
||||
icinga.num_services_pending | Current number of pending services.
|
||||
icinga.num_services_unreachable | Current number of unreachable services.
|
||||
icinga.num_services_flapping | Current number of flapping services.
|
||||
icinga.num_services_in_downtime | Current number of services in downtime.
|
||||
icinga.num_services_acknowledged | Current number of acknowledged service problems.
|
||||
icinga.num_hosts_up | Current number of hosts in state 'Up'.
|
||||
icinga.num_hosts_down | Current number of hosts in state 'Down'.
|
||||
icinga.num_hosts_unreachable | Current number of unreachable hosts.
|
||||
icinga.num_hosts_flapping | Current number of flapping hosts.
|
||||
icinga.num_hosts_in_downtime | Current number of hosts in downtime.
|
||||
icinga.num_hosts_acknowledged | Current number of acknowledged host problems.
|
||||
|
|
@ -1,229 +0,0 @@
|
|||
## <a id="notifications"></a> Notifications
|
||||
|
||||
Notifications for service and host problems are an integral part of your
|
||||
monitoring setup.
|
||||
|
||||
There are many ways of sending notifications, e.g. by e-mail, XMPP,
|
||||
IRC, Twitter, etc. On its own Icinga 2 does not know how to send notifications.
|
||||
Instead it relies on external mechanisms such as shell scripts to notify users.
|
||||
|
||||
A notification specification requires one or more users (and/or user groups)
|
||||
who will be notified in case of problems. These users must have all custom
|
||||
attributes defined which will be used in the `NotificationCommand` on execution.
|
||||
|
||||
TODO
|
||||
|
||||
The user `icingaadmin` in the example below will get notified only on `WARNING` and
|
||||
`CRITICAL` states and `problem` and `recovery` notification types.
|
||||
|
||||
object User "icingaadmin" {
|
||||
display_name = "Icinga 2 Admin"
|
||||
enable_notifications = true
|
||||
states = [ OK, Warning, Critical ]
|
||||
types = [ Problem, Recovery ]
|
||||
email = "icinga@localhost"
|
||||
}
|
||||
|
||||
If you don't set the `states` and `types`
|
||||
configuration attributes for the `User` object, notifications for all states and types
|
||||
will be sent.
|
||||
|
||||
You should choose which information you (and your notified users) are interested in
|
||||
case of emergency, and also which information does not provide any value to you and
|
||||
your environment.
|
||||
|
||||
There are various custom attributes available at runtime execution of the
|
||||
`NotificationCommand`. The example below may or may not fit your needs.
|
||||
|
||||
object NotificationCommand "mail-service-notification" {
|
||||
import "plugin-notification-command"
|
||||
|
||||
command = [ SysconfDir + "/icinga2/scripts/mail-notification.sh" ]
|
||||
|
||||
env = {
|
||||
"NOTIFICATIONTYPE" = "$notification.type$"
|
||||
"SERVICEDESC" = "$service.name$"
|
||||
"HOSTALIAS" = "$host.display_name$",
|
||||
"HOSTADDRESS" = "$address$",
|
||||
"SERVICESTATE" = "$service.state$",
|
||||
"LONGDATETIME" = "$icinga.long_date_time$",
|
||||
"SERVICEOUTPUT" = "$service.output$",
|
||||
"NOTIFICATIONAUTHORNAME" = "$notification.author$",
|
||||
"NOTIFICATIONCOMMENT" = "$notification.comment$",
|
||||
"HOSTDISPLAYNAME" = "$host.display_name$",
|
||||
"SERVICEDISPLAYNAME" = "$service.display_name$",
|
||||
"USEREMAIL" = "$user.email$"
|
||||
}
|
||||
}
|
||||
|
||||
The command attribute in the `mail-service-notification` command refers to the
|
||||
shell script installed into `/etc/icinga2/scripts/mail-notification.sh`.
|
||||
The macros specified in the `env` dictionary are exported as environment
|
||||
variables and can be used in the notification script.
|
||||
|
||||
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
|
||||
`Notification` object. Attributes can be overridden locally.
|
||||
|
||||
TODO
|
||||
|
||||
template Notification "generic-notification" {
|
||||
interval = 15m
|
||||
|
||||
command = "mail-service-notification"
|
||||
|
||||
states = [ Warning, Critical, Unknown ]
|
||||
types = [ Problem, Acknowledgement, Recovery, Custom, FlappingStart,
|
||||
FlappingEnd, DowntimeStart,DowntimeEnd, DowntimeRemoved ]
|
||||
|
||||
period = "24x7"
|
||||
}
|
||||
|
||||
The time period `24x7` is shipped as example configuration with Icinga 2.
|
||||
|
||||
Use the `apply` keyword to create `Notification` objects for your services:
|
||||
|
||||
apply Notification "mail" to Service {
|
||||
import "generic-notification"
|
||||
|
||||
command = "mail-notification"
|
||||
users = [ "icingaadmin" ]
|
||||
|
||||
assign where service.name == "mysql"
|
||||
}
|
||||
|
||||
Instead of assigning users to notifications, you can also add the `user_groups`
|
||||
attribute with a list of user groups to the `Notification` object. Icinga 2 will
|
||||
send notifications to all group members.
|
||||
|
||||
### <a id="notification-escalations"></a> Notification Escalations
|
||||
|
||||
When a problem notification is sent and a problem still exists after re-notification
|
||||
you may want to escalate the problem to the next support level. A different approach
|
||||
is to configure the default notification by email, and escalate the problem via sms
|
||||
if not already solved.
|
||||
|
||||
You can define notification start and end times as additional configuration
|
||||
attributes making the `Notification` object a so-called `notification escalation`.
|
||||
Using templates you can share the basic notification attributes such as users or the
|
||||
`interval` (and override them for the escalation then).
|
||||
|
||||
Using the example from above, you can define additional users being escalated for sms
|
||||
notifications between start and end time.
|
||||
|
||||
object User "icinga-oncall-2nd-level" {
|
||||
display_name = "Icinga 2nd Level"
|
||||
|
||||
vars.mobile = "+1 555 424642"
|
||||
}
|
||||
|
||||
object User "icinga-oncall-1st-level" {
|
||||
display_name = "Icinga 1st Level"
|
||||
|
||||
vars.mobile = "+1 555 424642"
|
||||
}
|
||||
|
||||
Define an additional `NotificationCommand` for SMS notifications.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The example is not complete as there are many different SMS providers.
|
||||
> Please note that sending SMS notifications will require an SMS provider
|
||||
> or local hardware with a SIM card active.
|
||||
|
||||
object NotificationCommand "sms-notification" {
|
||||
command = [
|
||||
PluginDir + "/send_sms_notification",
|
||||
"$mobile$",
|
||||
"..."
|
||||
}
|
||||
|
||||
The two new notification escalations are added onto the host `localhost`
|
||||
and its service `ping4` using the `generic-notification` template.
|
||||
The user `icinga-oncall-2nd-level` will get notified by SMS (`sms-notification`
|
||||
command) after `30m` until `1h`.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The `interval` was set to 15m in the `generic-notification`
|
||||
> template example. Lower that value in your escalations by using a secondary
|
||||
> template or overriding the attribute directly in the `notifications` array
|
||||
> position for `escalation-sms-2nd-level`.
|
||||
|
||||
If the problem does not get resolved or acknowledged preventing further notifications
|
||||
the `escalation-sms-1st-level` user will be escalated `1h` after the initial problem was
|
||||
notified, but only for one hour (`2h` as `end` key for the `times` dictionary).
|
||||
|
||||
apply Notification "mail" to Service {
|
||||
import "generic-notification"
|
||||
|
||||
command = "mail-notification"
|
||||
users = [ "icingaadmin" ]
|
||||
|
||||
assign where service.name == "ping4"
|
||||
}
|
||||
|
||||
apply Notification "escalation-sms-2nd-level" to Service {
|
||||
import "generic-notification"
|
||||
|
||||
command = "sms-notification"
|
||||
users = [ "icinga-oncall-2nd-level" ]
|
||||
|
||||
times = {
|
||||
begin = 30m
|
||||
end = 1h
|
||||
}
|
||||
|
||||
assign where service.name == "ping4"
|
||||
}
|
||||
|
||||
apply Notification "escalation-sms-1st-level" to Service {
|
||||
import "generic-notification"
|
||||
|
||||
command = "sms-notification"
|
||||
users = [ "icinga-oncall-1st-level" ]
|
||||
|
||||
times = {
|
||||
begin = 1h
|
||||
end = 2h
|
||||
}
|
||||
|
||||
assign where service.name == "ping4"
|
||||
}
|
||||
|
||||
### <a id="first-notification-delay"></a> First Notification Delay
|
||||
|
||||
Sometimes the problem in question should not be notified when the first notification
|
||||
happens, but a defined time duration afterwards. In Icinga 2 you can use the `times`
|
||||
dictionary and set `begin = 15m` as key and value if you want to suppress notifications
|
||||
in the first 15 minutes. Leave out the `end` key - if not set, Icinga 2 will not check against any
|
||||
end time for this notification.
|
||||
|
||||
apply Notification "mail" to Service {
|
||||
import "generic-notification"
|
||||
|
||||
command = "mail-notification"
|
||||
users = [ "icingaadmin" ]
|
||||
|
||||
times.begin = 15m // delay first notification
|
||||
|
||||
assign where service.name == "ping4"
|
||||
}
|
||||
|
||||
### <a id="notification-filters-state-type"></a> 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.
|
||||
|
||||
Available state and type filters for notifications are:
|
||||
|
||||
template Notification "generic-notification" {
|
||||
|
||||
states = [ Warning, Critical, Unknown ]
|
||||
types = [ Problem, Acknowledgement, Recovery, Custom, FlappingStart,
|
||||
FlappingEnd, DowntimeStart, DowntimeEnd, DowntimeRemoved ]
|
||||
}
|
||||
|
||||
If you are familiar with Icinga 1.x `notification_options` please note that they have been split
|
||||
into type and state, and allow more fine granular filtering for example on downtimes and flapping.
|
||||
You can filter for acknowledgements and custom notifications too.
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
## <a id="using-templates"></a> Using Templates
|
||||
|
||||
Templates may be used to apply a set of identical attributes to more than one
|
||||
object:
|
||||
|
||||
template Service "generic-service" {
|
||||
max_check_attempts = 3
|
||||
check_interval = 5m
|
||||
retry_interval = 1m
|
||||
enable_perfdata = true
|
||||
}
|
||||
|
||||
object Service "ping4" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "ping4"
|
||||
}
|
||||
|
||||
object Service "ping6" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "localhost"
|
||||
check_command = "ping6"
|
||||
}
|
||||
|
||||
In this example the `ping4` and `ping6` services inherit properties from the
|
||||
template `generic-service`.
|
||||
|
||||
Objects as well as templates themselves can import an arbitrary number of
|
||||
templates. Attributes inherited from a template can be overridden in the
|
||||
object if necessary.
|
||||
|
|
@ -1,55 +0,0 @@
|
|||
## <a id="groups"></a> Groups
|
||||
|
||||
Groups are used for combining hosts, services, and users into
|
||||
accessible configuration attributes and views in external (web)
|
||||
interfaces.
|
||||
|
||||
Group membership is defined at the respective object itself. If
|
||||
you have a hostgroup name `windows` for example, and want to assign
|
||||
specific hosts to this group for later viewing the group on your
|
||||
alert dashboard, first create the hostgroup:
|
||||
|
||||
object HostGroup "windows" {
|
||||
display_name = "Windows Servers"
|
||||
}
|
||||
|
||||
Then add your hosts to this hostgroup
|
||||
|
||||
template Host "windows-server" {
|
||||
groups += [ "windows" ]
|
||||
}
|
||||
|
||||
object Host "mssql-srv1" {
|
||||
import "windows-server"
|
||||
|
||||
vars.mssql_port = 1433
|
||||
}
|
||||
|
||||
object Host "mssql-srv2" {
|
||||
import "windows-server"
|
||||
|
||||
vars.mssql_port = 1433
|
||||
}
|
||||
|
||||
This can be done for service and user groups the same way. Additionally
|
||||
the user groups are associated as attributes in `Notification` objects.
|
||||
|
||||
object UserGroup "windows-mssql-admins" {
|
||||
display_name = "Windows MSSQL Admins"
|
||||
}
|
||||
|
||||
template User "generic-windows-mssql-users" {
|
||||
groups += [ "windows-mssql-admins" ]
|
||||
}
|
||||
|
||||
object User "win-mssql-noc" {
|
||||
import "generic-windows-mssql-users"
|
||||
|
||||
vars.email = "noc@example.com"
|
||||
}
|
||||
|
||||
object User "win-mssql-ops" {
|
||||
import "generic-windows-mssql-users"
|
||||
|
||||
vars.email = "ops@example.com"
|
||||
}
|
||||
|
|
@ -1,77 +0,0 @@
|
|||
## <a id="timeperiods"></a> Time Periods
|
||||
|
||||
Time Periods 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
|
||||
users or not, filtered by the `period` and `notification_period`
|
||||
configuration attributes for `Notification` and `User` objects.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> If you are familar with Icinga 1.x - these time period definitions
|
||||
> are called `legacy timeperiods` in Icinga 2.
|
||||
>
|
||||
> An Icinga 2 legacy timeperiod requires the `ITL` provided template
|
||||
>`legacy-timeperiod`.
|
||||
|
||||
The `TimePeriod` attribute `ranges` may contain multiple directives,
|
||||
including weekdays, days of the month, and calendar dates.
|
||||
These types may overlap/override other types in your ranges dictionary.
|
||||
|
||||
The descending order of precedence is as follows:
|
||||
|
||||
* Calendar date (2008-01-01)
|
||||
* Specific month date (January 1st)
|
||||
* Generic month date (Day 15)
|
||||
* Offset weekday of specific month (2nd Tuesday in December)
|
||||
* Offset weekday (3rd Monday)
|
||||
* Normal weekday (Tuesday)
|
||||
|
||||
If you don't set any `check_period` or `notification_period` attribute
|
||||
on your configuration objects Icinga 2 assumes `24x7` as time period
|
||||
as shown below.
|
||||
|
||||
object TimePeriod "24x7" {
|
||||
import "legacy-timeperiod"
|
||||
|
||||
display_name = "Icinga 2 24x7 TimePeriod"
|
||||
ranges = {
|
||||
"monday" = "00:00-24:00"
|
||||
"tuesday" = "00:00-24:00"
|
||||
"wednesday" = "00:00-24:00"
|
||||
"thursday" = "00:00-24:00"
|
||||
"friday" = "00:00-24:00"
|
||||
"saturday" = "00:00-24:00"
|
||||
"sunday" = "00:00-24:00"
|
||||
}
|
||||
}
|
||||
|
||||
If your operation staff should only be notified during workhours
|
||||
create a new timeperiod named `workhours` defining a work day from
|
||||
09:00 to 17:00.
|
||||
|
||||
object TimePeriod "workhours" {
|
||||
import "legacy-timeperiod"
|
||||
|
||||
display_name = "Icinga 2 8x5 TimePeriod"
|
||||
ranges = {
|
||||
"monday" = "09:00-17:00"
|
||||
"tuesday" = "09:00-17:00"
|
||||
"wednesday" = "09:00-17:00"
|
||||
"thursday" = "09:00-17:00"
|
||||
"friday" = "09:00-17:00"
|
||||
}
|
||||
}
|
||||
|
||||
Use the `period` attribute to assign time periods to
|
||||
`Notification` objects:
|
||||
|
||||
object Notification "mail" {
|
||||
import "generic-notification"
|
||||
|
||||
host_name = "localhost"
|
||||
|
||||
command = "mail-notification"
|
||||
users = [ "icingaadmin" ]
|
||||
period = "workhours"
|
||||
}
|
||||
|
|
@ -1,40 +0,0 @@
|
|||
## <a id="external-commands"></a> External Commands
|
||||
|
||||
Icinga 2 provides an external command pipe for processing commands
|
||||
triggering specific actions (for example rescheduling a service check
|
||||
through the web interface).
|
||||
|
||||
In order to enable the `ExternalCommandListener` configuration use the
|
||||
following command and restart Icinga 2 afterwards:
|
||||
|
||||
# icinga2-enable-feature command
|
||||
|
||||
Icinga 2 creates the command pipe file as `/var/run/icinga2/cmd/icinga2.cmd`
|
||||
using the default configuration.
|
||||
|
||||
Web interfaces and other Icinga addons are able to send commands to
|
||||
Icinga 2 through the external command pipe, for example for rescheduling
|
||||
a forced service check:
|
||||
|
||||
# /bin/echo "[`date +%s`] SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;`date +%s`" >> /var/run/icinga2/cmd/icinga2.cmd
|
||||
|
||||
# tail -f /var/log/messages
|
||||
|
||||
Oct 17 15:01:25 icinga-server icinga2: Executing external command: [1382014885] SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;1382014885
|
||||
Oct 17 15:01:25 icinga-server icinga2: Rescheduling next check for service 'ping4'
|
||||
|
||||
By default the command pipe file is owned by the group `icingacmd` with read/write
|
||||
permissions. Add your webserver's user to the group `icingacmd` to
|
||||
enable sending commands to Icinga 2 through your web interface:
|
||||
|
||||
# usermod -G -a icingacmd www-data
|
||||
|
||||
Debian packages use `nagios` as the default user and group name. Therefore change `icingacmd` to
|
||||
`nagios`.
|
||||
|
||||
### <a id="external-command-list"></a> External Command List
|
||||
|
||||
A list of currently supported external commands can be found [here](#external-commands-list-detail)
|
||||
|
||||
Detailed information on the commands and their required parameters can be found
|
||||
on the [Icinga 1.x documentation](http://docs.icinga.org/latest/en/extcommands2.html).
|
||||
|
|
@ -1,14 +0,0 @@
|
|||
## <a id="event-handlers"></a> Event Handlers
|
||||
|
||||
Event handlers are defined as `EventCommand` objects in Icinga 2.
|
||||
|
||||
Unlike notifications event commands are called on every host/service execution
|
||||
if defined. Therefore the `EventCommand` object should define a command line
|
||||
evaluating the current service state and other service runtime attributes
|
||||
available through runtime macros. Runtime macros such as `$SERVICESTATETYPE$`
|
||||
and `$SERVICESTATE$` will be processed by Icinga 2 helping on fine-granular
|
||||
events being triggered.
|
||||
|
||||
Common use case scenarios are a failing HTTP check requiring an immediate
|
||||
restart via event command, or if an application is locked and requires
|
||||
a restart upon detection.
|
||||
|
|
@ -1,20 +0,0 @@
|
|||
## <a id="logging"></a> Logging
|
||||
|
||||
Icinga 2 supports three different types of logging:
|
||||
|
||||
* File logging
|
||||
* Syslog (on *NIX-based operating systems)
|
||||
* Console logging (`STDOUT` on tty)
|
||||
|
||||
You can enable additional loggers using the `icinga2-enable-feature`
|
||||
and `icinga2-disable-feature` commands to configure loggers:
|
||||
|
||||
Feature | Description
|
||||
---------|------------
|
||||
debuglog | Debug log (path: `/var/log/icinga2/debug.log`, severity: `debug` or higher)
|
||||
mainlog | Main log (path: `/var/log/icinga2/icinga2.log`, severity: `information` or higher)
|
||||
syslog | Syslog (severity: `warning` or higher)
|
||||
|
||||
By default file the `mainlog` feature is enabled. When running Icinga 2
|
||||
on a terminal log messages with severity `information` or higher are
|
||||
written to the console.
|
||||
|
|
@ -1,54 +0,0 @@
|
|||
## <a id="performance-data"></a> Performance Data
|
||||
|
||||
When a host and service check is executed plugins should provide so-called
|
||||
`performance data`. Next to that additional check performance data
|
||||
can be fetched using Icinga 2 runtime macros such as the check latency
|
||||
or the current service state (or additional custom attributes).
|
||||
|
||||
The performance data may be passed to external applications which
|
||||
then generate nice graphs for historical reporting and trending.
|
||||
|
||||
Well-known addons processing Icinga performance data are PNP4Nagios,
|
||||
inGraph and Graphite.
|
||||
|
||||
### <a id="writing-performance-data-files"></a> Writing Performance Data Files
|
||||
|
||||
PNP4Nagios, inGraph and Graphios use performance data collector daemons to fetch
|
||||
the current performance files for their backend updates.
|
||||
|
||||
Therefore the Icinga 2 `PerfdataWriter` object allows you to define
|
||||
the output template format for host and services backed with Icinga 2
|
||||
runtime vars.
|
||||
|
||||
host_format_template = "DATATYPE::HOSTPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tHOSTPERFDATA::$host.perfdata$\tHOSTCHECKCOMMAND::$host.checkcommand$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.statetype$"
|
||||
service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.description$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.checkcommand$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.statetype$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.statetype$"
|
||||
|
||||
The default templates are already provided with the Icinga 2 feature configuration
|
||||
which can be enabled using
|
||||
|
||||
# icinga2-enable-feature perfdata
|
||||
|
||||
By default all performance data files are rotated in a 15 seconds interval into
|
||||
the `/var/spool/icinga2/perfdata/` directory as `host-perfdata.<timestamp>` and
|
||||
`service-perfdata.<timestamp>`.
|
||||
External collectors need to parse the rotated performance data files and then
|
||||
remove the processed files.
|
||||
|
||||
### <a id="graphite-carbon-cache-writer"></a> Graphite Carbon Cache Writer
|
||||
|
||||
While there are some Graphite collector scripts and daemons like Graphios available for
|
||||
Icinga 1.x it's more reasonable to directly process the check and plugin performance
|
||||
in memory in Icinga 2. Once there are new metrics available, Icinga 2 will directly
|
||||
write them to the defined Graphite Carbon daemon tcp socket.
|
||||
|
||||
You can enable the feature using
|
||||
|
||||
# icinga2-enable-feature graphite
|
||||
|
||||
By default the `GraphiteWriter` object expects the Graphite Carbon Cache to listen at
|
||||
`127.0.0.1` on port `2003`.
|
||||
|
||||
The current naming schema is
|
||||
|
||||
icinga.<hostname>.<metricname>
|
||||
icinga.<hostname>.<servicename>.<metricname>
|
||||
|
|
@ -1,15 +0,0 @@
|
|||
## <a id="status-data"></a> Status Data
|
||||
|
||||
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
|
||||
the `StatusDataWriter` object which dumps all configuration objects and
|
||||
status updates in a regular interval.
|
||||
|
||||
# icinga2-enable-feature statusdata
|
||||
|
||||
Icinga 1.x Classic UI requires this data set as part of its backend.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> If you are not using any web interface or addon which uses these files
|
||||
> you can safely disable this feature.
|
||||
|
|
@ -1,46 +0,0 @@
|
|||
## <a id="compat-logging"></a> Compat Logging
|
||||
|
||||
The Icinga 1.x log format is considered being the `Compat Log`
|
||||
in Icinga 2 provided with the `CompatLogger` object.
|
||||
|
||||
These logs are not only used for informational representation in
|
||||
external web interfaces parsing the logs, but also to generate
|
||||
SLA reports and trends in Icinga 1.x Classic UI. Futhermore the
|
||||
`Livestatus` feature uses these logs for answering queries to
|
||||
historical tables.
|
||||
|
||||
The `CompatLogger` object can be enabled with
|
||||
|
||||
# icinga2-enable-feature compatlog
|
||||
|
||||
By default, the Icinga 1.x log file called `icinga.log` is located
|
||||
in `/var/log/icinga2/compat`. Rotated log files are moved into
|
||||
`var/log/icinga2/compat/archives`.
|
||||
|
||||
The format cannot be changed without breaking compatibility to
|
||||
existing log parsers.
|
||||
|
||||
# tail -f /var/log/icinga2/compat/icinga.log
|
||||
|
||||
[1382115688] LOG ROTATION: HOURLY
|
||||
[1382115688] LOG VERSION: 2.0
|
||||
[1382115688] HOST STATE: CURRENT;localhost;UP;HARD;1;
|
||||
[1382115688] SERVICE STATE: CURRENT;localhost;disk;WARNING;HARD;1;
|
||||
[1382115688] SERVICE STATE: CURRENT;localhost;http;OK;HARD;1;
|
||||
[1382115688] SERVICE STATE: CURRENT;localhost;load;OK;HARD;1;
|
||||
[1382115688] SERVICE STATE: CURRENT;localhost;ping4;OK;HARD;1;
|
||||
[1382115688] SERVICE STATE: CURRENT;localhost;ping6;OK;HARD;1;
|
||||
[1382115688] SERVICE STATE: CURRENT;localhost;processes;WARNING;HARD;1;
|
||||
[1382115688] SERVICE STATE: CURRENT;localhost;ssh;OK;HARD;1;
|
||||
[1382115688] SERVICE STATE: CURRENT;localhost;users;OK;HARD;1;
|
||||
[1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;disk;1382115705
|
||||
[1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;http;1382115705
|
||||
[1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;load;1382115705
|
||||
[1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;1382115705
|
||||
[1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;ping6;1382115705
|
||||
[1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;processes;1382115705
|
||||
[1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;ssh;1382115705
|
||||
[1382115706] EXTERNAL COMMAND: SCHEDULE_FORCED_SVC_CHECK;localhost;users;1382115705
|
||||
[1382115731] EXTERNAL COMMAND: PROCESS_SERVICE_CHECK_RESULT;localhost;ping6;2;critical test|
|
||||
[1382115731] SERVICE ALERT: localhost;ping6;CRITICAL;SOFT;2;critical test
|
||||
|
||||
|
|
@ -1,18 +0,0 @@
|
|||
## <a id="check-result-files"></a> Check Result Files
|
||||
|
||||
Icinga 1.x writes its check result files into a temporary spool directory
|
||||
where it reads these check result files in a regular interval from.
|
||||
While this is extremly inefficient in performance regards it has been
|
||||
rendered useful for passing passive check results directly into Icinga 1.x
|
||||
skipping the external command pipe.
|
||||
|
||||
Several clustered/distributed environments and check-aggregation addons
|
||||
use that method. In order to support step-by-step migration of these
|
||||
environments, Icinga 2 ships the `CheckResultReader` object.
|
||||
|
||||
There is no feature configuration available, but it must be defined
|
||||
on-demand in your Icinga 2 objects configuration.
|
||||
|
||||
object CheckResultReader "reader" {
|
||||
spool_dir = "/data/check-results"
|
||||
}
|
||||
|
|
@ -1,182 +0,0 @@
|
|||
## <a id="monitoring-remote-clients"></a> Monitoring Remote Clients
|
||||
|
||||
### Agent-less Checks
|
||||
|
||||
If the remote service is available using a network protocol and port,
|
||||
and a [check plugin](#setting-up-check-plugins) is available, you don't
|
||||
necessarily need a local client installed. Rather choose a plugin and
|
||||
configure all parameters and thresholds. The [Icinga 2 Template Library](#itl)
|
||||
already ships various examples.
|
||||
|
||||
### 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
|
||||
|
||||
The SNMP daemon runs on the remote system and answers SNMP queries by plugin
|
||||
binaries. The [Monitoring Plugins package](#setting-up-check-plugins) ships
|
||||
the `check_snmp` plugin binary, but there are plenty of [existing plugins](#integrate-additional-plugins)
|
||||
for specific use cases already around, for example monitoring Cisco routers.
|
||||
|
||||
The following example uses the [SNMP ITL](#itl-snmp) `CheckCommand` and just
|
||||
overrides the `oid` custom attribute. A service is created for all hosts which
|
||||
have the `community` custom attribute.
|
||||
|
||||
apply Service "uptime" {
|
||||
import "generic-service"
|
||||
|
||||
check_command = "snmp"
|
||||
vars.oid = "1.3.6.1.2.1.1.3.0"
|
||||
|
||||
assign where host.vars.community
|
||||
}
|
||||
|
||||
#### SSH
|
||||
|
||||
Calling a plugin using the SSH protocol to execute a plugin on the remote server fetching
|
||||
its return code and output. `check_by_ssh` is available in the [Monitoring Plugins package](#setting-up-check-plugins).
|
||||
|
||||
object CheckCommand "check_by_ssh_swap" {
|
||||
import "plugin-check-command"
|
||||
|
||||
command = [ PluginDir + "/check_by_ssh",
|
||||
"-l", "remoteuser",
|
||||
"-H", "$address$",
|
||||
"-C", "\"/usr/local/icinga/libexec/check_swap -w $warn$ -c $crit$\""
|
||||
]
|
||||
}
|
||||
|
||||
object Service "swap" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "remote-ssh-host"
|
||||
|
||||
check_command = "check_by_ssh_swap"
|
||||
vars = {
|
||||
"warn" = "50%"
|
||||
"crit" = "75%"
|
||||
}
|
||||
}
|
||||
|
||||
#### NRPE
|
||||
|
||||
[NRPE](http://docs.icinga.org/latest/en/nrpe.html) runs as daemon on the remote client including
|
||||
the required plugins and command definitions.
|
||||
Icinga 2 calls the `check_nrpe` plugin binary in order to query the configured command on the
|
||||
remote client.
|
||||
|
||||
The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe`
|
||||
can be embedded into the Icinga 2 `CheckCommand` configuration syntax.
|
||||
|
||||
Example:
|
||||
|
||||
object CheckCommand "check_nrpe" {
|
||||
import "plugin-check-command"
|
||||
|
||||
command = [
|
||||
PluginDir + "/check_nrpe",
|
||||
"-H", "$address$",
|
||||
"-c", "$remote_nrpe_command$",
|
||||
]
|
||||
}
|
||||
|
||||
object Service "users" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "remote-nrpe-host"
|
||||
|
||||
check_command = "check_nrpe"
|
||||
vars.remote_nrpe_command = "check_users"
|
||||
}
|
||||
|
||||
nrpe.cfg:
|
||||
|
||||
command[check_users]=/usr/local/icinga/libexec/check_users -w 5 -c 10
|
||||
|
||||
#### NSClient++
|
||||
|
||||
[NSClient++](http://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,
|
||||
but using `NSClient++` will allow you to run local scripts similar to check plugins fetching
|
||||
the required output and performance counters.
|
||||
|
||||
The NSClient++ agent uses its own configuration format while `check_nt`
|
||||
can be embedded into the Icinga 2 `CheckCommand` configuration syntax.
|
||||
|
||||
Example:
|
||||
|
||||
object CheckCommand "check_nscp" {
|
||||
import "plugin-check-command"
|
||||
|
||||
command = [
|
||||
PluginDir + "/check_nt",
|
||||
"-H", "$address$",
|
||||
"-p", "$port$",
|
||||
"-v", "$remote_nscp_command$",
|
||||
"-l", "$partition$",
|
||||
"-w", "$warn$",
|
||||
"-c", "$crit$",
|
||||
"-s", "$pass$"
|
||||
]
|
||||
|
||||
vars = {
|
||||
"port" = "12489"
|
||||
"pass" = "supersecret"
|
||||
}
|
||||
}
|
||||
|
||||
object Service "users" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "remote-windows-host"
|
||||
|
||||
check_command = "check_nscp"
|
||||
|
||||
vars += {
|
||||
remote_nscp_command = "USEDDISKSPACE"
|
||||
partition = "c"
|
||||
warn = "70"
|
||||
crit = "80"
|
||||
}
|
||||
}
|
||||
|
||||
For details on the `NSClient++` configuration please refer to the [official documentation](http://www.nsclient.org/nscp/wiki/doc/configuration/0.4.x).
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The format of the `NSClient++` configuration file has changed from 0.3.x to 0.4!
|
||||
|
||||
#### Icinga 2 Agent
|
||||
|
||||
A dedicated Icinga 2 agent supporting all platforms and using the native
|
||||
Icinga 2 communication protocol supported with SSL certificates, IPv4/IPv6
|
||||
support, etc. is on the [development roadmap](https://dev.icinga.org/projects/i2?jump=issues).
|
||||
Meanwhile remote checkers in a [Cluster](#cluster) setup could act as
|
||||
immediate replacement, but without any local configuration - or pushing
|
||||
their standalone configuration back to the master node including their check
|
||||
result messages.
|
||||
|
||||
### Passive Check Results and SNMP Traps
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The host and service object configuration must be available on the Icinga 2
|
||||
> server in order to process passive check results.
|
||||
|
||||
#### 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`
|
||||
feature.
|
||||
|
||||
The [Icinga 2 Vagrant Demo VM](#vagrant) ships a demo integration and further samples.
|
||||
|
||||
#### 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.
|
||||
|
||||
|
||||
|
|
@ -1 +0,0 @@
|
|||
# <a id="configuring-icinga2"></a> Configuring Icinga 2
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -1,564 +0,0 @@
|
|||
## <a id="configuration-syntax"></a> Configuration Syntax
|
||||
|
||||
### <a id="object-definition"></a> Object Definition
|
||||
|
||||
Icinga 2 features an object-based configuration format. You can define new
|
||||
objects using the `object` keyword:
|
||||
|
||||
object Host "host1.example.org" {
|
||||
display_name = "host1"
|
||||
|
||||
address = "192.168.0.1"
|
||||
address6 = "::1"
|
||||
}
|
||||
|
||||
In general you need to write each statement on a new line. Expressions started
|
||||
with `{`, `(` and `[` extend until the matching closing character and can be broken
|
||||
up into multiple lines.
|
||||
|
||||
Alternatively you can write multiple statements in a single line by separating
|
||||
them with a semicolon:
|
||||
|
||||
object Host "host1.example.org" {
|
||||
display_name = "host1"
|
||||
|
||||
address = "192.168.0.1"; address6 = "::1"
|
||||
}
|
||||
|
||||
Each object is uniquely identified by its type (`Host`) and name
|
||||
(`host1.example.org`). Some types have composite names, e.g. the
|
||||
`Service` type which uses the `host_name` attribute and the name
|
||||
you specified to generate its object name.
|
||||
|
||||
Exclamation marks (!) are not permitted in object names.
|
||||
|
||||
Objects can contain a comma-separated list of property
|
||||
declarations. Instead of commas semicolons may also be used.
|
||||
The following data types are available for property values:
|
||||
|
||||
### Expressions
|
||||
|
||||
The following expressions can be used in the right-hand side of dictionary
|
||||
values.
|
||||
|
||||
#### <a id="numeric-literals"></a> Numeric Literals
|
||||
|
||||
A floating-point number.
|
||||
|
||||
Example:
|
||||
|
||||
-27.3
|
||||
|
||||
#### <a id="duration-literals"></a> Duration Literals
|
||||
|
||||
Similar to floating-point numbers except for the fact that they support
|
||||
suffixes to help with specifying time durations.
|
||||
|
||||
Example:
|
||||
|
||||
2.5m
|
||||
|
||||
Supported suffixes include ms (milliseconds), s (seconds), m (minutes),
|
||||
h (hours) and d (days).
|
||||
|
||||
Duration literals are converted to seconds by the config parser and
|
||||
are treated like numeric literals.
|
||||
|
||||
#### <a id="string-literals"></a> String Literals
|
||||
|
||||
A string.
|
||||
|
||||
Example:
|
||||
|
||||
"Hello World!"
|
||||
|
||||
Certain characters need to be escaped. The following escape sequences
|
||||
are supported:
|
||||
|
||||
Character | Escape sequence
|
||||
--------------------------|------------------------------------
|
||||
" | \\"
|
||||
\\ | \\\\
|
||||
<TAB> | \\t
|
||||
<CARRIAGE-RETURN> | \\r
|
||||
<LINE-FEED> | \\n
|
||||
<BEL> | \\b
|
||||
<FORM-FEED> | \\f
|
||||
|
||||
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.
|
||||
|
||||
#### <a id="multiline-string-literals"></a> Multi-line String Literals
|
||||
|
||||
Strings spanning multiple lines can be specified by enclosing them in
|
||||
{{{ and }}}.
|
||||
|
||||
Example.
|
||||
|
||||
{{{This
|
||||
is
|
||||
a multi-line
|
||||
string.}}}
|
||||
|
||||
Unlike in ordinary strings special characters do not have to be escaped
|
||||
in multi-line string literals.
|
||||
|
||||
#### <a id="boolean-literals"></a> Boolean Literals
|
||||
|
||||
The keywords `true` and `false` are equivalent to 1 and 0 respectively.
|
||||
|
||||
#### <a id="null-value"></a> Null Value
|
||||
|
||||
The `null` keyword can be used to specify an empty value.
|
||||
|
||||
#### <a id="dictionary"></a> Dictionary
|
||||
|
||||
An unordered list of key-value pairs. Keys must be unique and are
|
||||
compared in a case-insensitive manner.
|
||||
|
||||
Individual key-value pairs must be separated from each other with a
|
||||
comma. The comma after the last key-value pair is optional.
|
||||
|
||||
Example:
|
||||
|
||||
{
|
||||
address = "192.168.0.1"
|
||||
port = 443
|
||||
}
|
||||
|
||||
Identifiers may not contain certain characters (e.g. space) or start
|
||||
with certain characters (e.g. digits). If you want to use a dictionary
|
||||
key that is not a valid identifier you can put the key in double
|
||||
quotes.
|
||||
|
||||
Setting a dictionary key to null causes the key and its value to be
|
||||
removed from the dictionary.
|
||||
|
||||
#### <a id="array"></a> Array
|
||||
|
||||
An ordered list of values.
|
||||
|
||||
Individual array elements must be separated from each other with a
|
||||
comma. The comma after the last element is optional.
|
||||
|
||||
Example:
|
||||
|
||||
[ "hello", 42 ]
|
||||
|
||||
An array may simultaneously contain values of different types, such as
|
||||
strings and numbers.
|
||||
|
||||
#### <a id="expression-operators"></a> Operators
|
||||
|
||||
The following operators are supported in expressions:
|
||||
|
||||
Operator | Examples (Result) | Description
|
||||
---------|-----------------------------------------------|--------------------------------
|
||||
! | !"Hello" (false), !false (true) | Log<!-- ignore BLACKLIST -->ical negation of the operand
|
||||
~ | ~true (false) | Bitwise negation of the operand
|
||||
+ | 1 + 3 (4), "hello " + "world" ("hello world") | Adds two numbers; concatenates strings
|
||||
- | 3 - 1 (2) | Subtracts two numbers
|
||||
* | 5m * 10 (3000) | Multiplies two numbers
|
||||
/ | 5m / 5 (60) | Divides two numbers
|
||||
& | 7 & 3 (3) | Binary AND
|
||||
| | 2 | 3 (3) | Binary OR
|
||||
< | 3 < 5 (true) | Less than
|
||||
> | 3 > 5 (false) | Greater than
|
||||
<= | 3 <= 3 (true) | Less than or equal
|
||||
>= | 3 >= 3 (true) | Greater than or equal
|
||||
<< | 4 << 8 (1024) | Left shift
|
||||
>> | 1024 >> 4 (64) | Right shift
|
||||
== | "hello" == "hello" (true), 3 == 5 (false) | Equal to
|
||||
!= | "hello" != "world" (true), 3 != 3 (false) | Not equal to
|
||||
in | "foo" in [ "foo", "bar" ] (true) | Element contained in array
|
||||
!in | "foo" !in [ "bar", "baz" ] (true) | Element not contained in array
|
||||
() | (3 + 3) * 5 | Groups sub-expressions
|
||||
|
||||
Constants may be used in expressions:
|
||||
|
||||
const MyCheckInterval = 10m
|
||||
|
||||
...
|
||||
|
||||
{
|
||||
check_interval = MyCheckInterval / 2.5
|
||||
}
|
||||
|
||||
#### Function Calls
|
||||
|
||||
Functions can be called using the `()` operator:
|
||||
|
||||
const MyGroups = [ "test1", "test" ]
|
||||
|
||||
{
|
||||
check_interval = len(MyGroups) * 1m
|
||||
}
|
||||
|
||||
Function | Description
|
||||
--------------------------------|-----------------------
|
||||
regex(pattern, text) | Returns true if the regex pattern matches the text, false otherwise.
|
||||
match(pattern, text) | Returns true if the wildcard pattern matches the text, false otherwise.
|
||||
len(value) | Returns the length of the value, i.e. the number of elements for an array or dictionary, or the length of the string in bytes.
|
||||
union(array, array, ...) | Returns an array containing all unique elements from the specified arrays.
|
||||
intersection(array, array, ...) | Returns an array containing all unique elements which are common to all specified arrays.
|
||||
string(value) | Converts the value to a string.
|
||||
number(value) | Converts the value to a number.
|
||||
bool(value) | Converts to value to a bool.
|
||||
log(value) | Writes a message to the log. Non-string values are converted to a JSON string.
|
||||
log(severity, facility, value) | Writes a message to the log. `severity` can be one of `LogDebug`, `LogInformation`, `LogWarning` and `LogCritical`. Non-string values are converted to a JSON string.
|
||||
exit(integer) | Terminates the application.
|
||||
|
||||
### <a id="operators"></a> Dictionary Operators
|
||||
|
||||
In addition to the `=` operator shown above a number of other operators
|
||||
to manipulate dictionary elements are supported. Here's a list of all
|
||||
available operators:
|
||||
|
||||
#### <a id="operator-assignment"></a> Operator =
|
||||
|
||||
Sets a dictionary element to the specified value.
|
||||
|
||||
Example:
|
||||
|
||||
{
|
||||
a = 5,
|
||||
a = 7
|
||||
}
|
||||
|
||||
In this example a has the value 7 after both instructions are executed.
|
||||
|
||||
#### <a id="operator-additive-assignment"></a> Operator +=
|
||||
|
||||
The += operator is a shortcut. The following expression:
|
||||
|
||||
{
|
||||
a = [ "hello" ]
|
||||
a += [ "world" ]
|
||||
}
|
||||
|
||||
is equivalent to:
|
||||
|
||||
{
|
||||
a = [ "hello" ]
|
||||
a = a + [ "world" ]
|
||||
}
|
||||
|
||||
#### <a id="operator-substractive-assignment"></a> Operator -=
|
||||
|
||||
The -= operator is a shortcut. The following expression:
|
||||
|
||||
{
|
||||
a = 10
|
||||
a -= 5
|
||||
}
|
||||
|
||||
is equivalent to:
|
||||
|
||||
{
|
||||
a = 10
|
||||
a = a - 5
|
||||
}
|
||||
|
||||
#### <a id="operator-multiply-assignment"></a> Operator \*=
|
||||
|
||||
The *= operator is a shortcut. The following expression:
|
||||
|
||||
{
|
||||
a = 60
|
||||
a *= 5
|
||||
}
|
||||
|
||||
is equivalent to:
|
||||
|
||||
{
|
||||
a = 60
|
||||
a = a * 5
|
||||
}
|
||||
|
||||
#### <a id="operator-dividing-assignment"></a> Operator /=
|
||||
|
||||
The /= operator is a shortcut. The following expression:
|
||||
|
||||
{
|
||||
a = 300
|
||||
a /= 5
|
||||
}
|
||||
|
||||
is equivalent to:
|
||||
|
||||
{
|
||||
a = 300
|
||||
a = a / 5
|
||||
}
|
||||
|
||||
### <a id="indexer"></a> Indexer
|
||||
|
||||
The indexer syntax provides a convenient way to set dictionary elements.
|
||||
|
||||
Example:
|
||||
|
||||
{
|
||||
hello.key = "world"
|
||||
}
|
||||
|
||||
Example (alternative syntax):
|
||||
|
||||
{
|
||||
hello["key"] = "world"
|
||||
}
|
||||
|
||||
This is equivalent to writing:
|
||||
|
||||
{
|
||||
hello += {
|
||||
key = "world"
|
||||
}
|
||||
}
|
||||
|
||||
### <a id="template-imports"></a> Template Imports
|
||||
|
||||
Objects can import attributes from other objects.
|
||||
|
||||
Example:
|
||||
|
||||
template Host "default-host" {
|
||||
vars.color = "red"
|
||||
}
|
||||
|
||||
template Host "test-host" {
|
||||
import "default-host"
|
||||
|
||||
vars.color = "blue"
|
||||
}
|
||||
|
||||
object Host "localhost" {
|
||||
import "test-host"
|
||||
|
||||
address = "127.0.0.1"
|
||||
address6 = "::1"
|
||||
}
|
||||
|
||||
The `default-host` and `test-host` objects are marked as templates
|
||||
using the `template` keyword. Unlike ordinary objects templates are not
|
||||
instantiated at run-time. Parent objects do not necessarily have to be
|
||||
templates, however in general they are.
|
||||
|
||||
The `vars` dictionary for the `localhost` object contains all three
|
||||
custom attributes and the custom attribute `color` has the value `"blue"`.
|
||||
|
||||
Parent objects are resolved in the order they're specified using the
|
||||
`import` keyword.
|
||||
|
||||
### <a id="constants"></a> Constants
|
||||
|
||||
Global constants can be set using the `const` keyword:
|
||||
|
||||
const VarName = "some value"
|
||||
|
||||
Once defined a constant can be access from any file. Constants cannot be changed
|
||||
once they are set.
|
||||
|
||||
### <a id="apply"></a> Apply
|
||||
|
||||
The `apply` keyword can be used to create new objects which are associated with
|
||||
another group of objects.
|
||||
|
||||
apply Service "ping" to Host {
|
||||
import "generic-service"
|
||||
|
||||
check_command = "ping4"
|
||||
|
||||
assign where host.name == "localhost"
|
||||
}
|
||||
|
||||
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 "ping"
|
||||
is created for each matching host.
|
||||
|
||||
The `to` keyword and the target type may be omitted if there is only target
|
||||
type, e.g. for the `Service` type.
|
||||
|
||||
Depending on the object type used in the `apply` expression additional local
|
||||
variables may be available for use in the `where` condition:
|
||||
|
||||
Source Type | Target Type | Variables
|
||||
------------------|-------------|--------------
|
||||
Service | Host | host
|
||||
Dependency | Host | host
|
||||
Dependency | Service | host, service
|
||||
Notification | Host | host
|
||||
Notification | Service | host, service
|
||||
ScheduledDowntime | Host | host
|
||||
ScheduledDowntime | Service | host, service
|
||||
|
||||
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.
|
||||
|
||||
### <a id="group-assign"></a> Group Assign
|
||||
|
||||
Group objects can be assigned to specific member objects using the `assign where`
|
||||
and `ignore where` conditions.
|
||||
|
||||
object HostGroup "linux-servers" {
|
||||
display_name = "Linux Servers"
|
||||
|
||||
assign where host.vars.os == "linux"
|
||||
}
|
||||
|
||||
In this example the `assign where` condition is a boolean expression which is evaluated
|
||||
for all objects of the type `Host`. Each matching host is added as member to the host group
|
||||
with the name "linux-servers". Membership exclusion can be controlled using the `ignore where`
|
||||
condition.
|
||||
|
||||
Source Type | Variables
|
||||
------------------|--------------
|
||||
HostGroup | host
|
||||
ServiceGroup | host, service
|
||||
UserGroup | user
|
||||
|
||||
|
||||
### <a id="boolean-values"></a> Boolean Values
|
||||
|
||||
The `assign where` and `ignore where` statements, the `!`, `&&` and `||`
|
||||
operators as well as the `bool()` function convert their arguments to a
|
||||
boolean value based on the following rules:
|
||||
|
||||
Description | Example Value | Boolean Value
|
||||
---------------------|-------------------|--------------
|
||||
Empty value | null | false
|
||||
Zero | 0 | false
|
||||
Non-zero integer | -23945 | true
|
||||
Empty string | "" | false
|
||||
Non-empty string | "Hello" | true
|
||||
Empty array | [] | false
|
||||
Non-empty array | [ "Hello" ] | true
|
||||
Empty dictionary | {} | false
|
||||
Non-empty dictionary | { key = "value" } | true
|
||||
|
||||
### <a id="comments"></a> Comments
|
||||
|
||||
The Icinga 2 configuration format supports C/C++-style and shell-style comments.
|
||||
|
||||
Example:
|
||||
|
||||
/*
|
||||
This is a comment.
|
||||
*/
|
||||
object Host "localhost" {
|
||||
check_interval = 30 // this is also a comment.
|
||||
retry_interval = 15 # yet another comment
|
||||
}
|
||||
|
||||
### <a id="includes"></a> Includes
|
||||
|
||||
Other configuration files can be included using the `include` directive.
|
||||
Paths must be relative to the configuration file that contains the
|
||||
`include` directive.
|
||||
|
||||
Example:
|
||||
|
||||
include "some/other/file.conf"
|
||||
include "conf.d/*.conf"
|
||||
|
||||
Wildcard includes are not recursive.
|
||||
|
||||
Icinga also supports include search paths similar to how they work in a
|
||||
C/C++ compiler:
|
||||
|
||||
include <itl/itl.conf>
|
||||
|
||||
Note the use of angle brackets instead of double quotes. This causes the
|
||||
config compiler to search the include search paths for the specified
|
||||
file. By default $PREFIX/share/icinga2 is included in the list of search
|
||||
paths. Additional include search paths can be added using
|
||||
[command-line options](#cmdline).
|
||||
|
||||
Wildcards are not permitted when using angle brackets.
|
||||
|
||||
### <a id="recursive-includes"></a> Recursive Includes
|
||||
|
||||
The `include_recursive` directive can be used to recursively include all
|
||||
files in a directory which match a certain pattern.
|
||||
|
||||
Example:
|
||||
|
||||
include_recursive "conf.d", "*.conf"
|
||||
include_recursive "templates"
|
||||
|
||||
The first parameter specifies the directory from which files should be
|
||||
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.
|
||||
|
||||
### <a id="library"></a> Library directive
|
||||
|
||||
The `library` directive can be used to manually load additional
|
||||
libraries. Libraries can be used to provide additional object types and
|
||||
functions.
|
||||
|
||||
Example:
|
||||
|
||||
library "snmphelper"
|
||||
|
||||
<!--
|
||||
|
||||
### <a id="type-definition"></a> Type Definition
|
||||
|
||||
By default Icinga has no way of semantically verifying its configuration
|
||||
objects. This is where type definitions come in. Using type definitions
|
||||
you can specify which attributes are allowed in an object definition.
|
||||
|
||||
Example:
|
||||
|
||||
%type Pizza {
|
||||
%require "radius",
|
||||
%attribute %number "radius",
|
||||
|
||||
%attribute %dictionary "ingredients" {
|
||||
%validator "ValidateIngredients",
|
||||
|
||||
%attribute %string "*",
|
||||
|
||||
%attribute %dictionary "*" {
|
||||
%attribute %number "quantity",
|
||||
%attribute %string "name"
|
||||
}
|
||||
},
|
||||
|
||||
%attribute any "custom::*"
|
||||
}
|
||||
|
||||
The Pizza definition provides the following validation rules:
|
||||
|
||||
- Pizza objects must contain an attribute `radius` which has to be a
|
||||
number.
|
||||
|
||||
- Pizza objects may contain an attribute `ingredients` which has to be
|
||||
a dictionary.
|
||||
|
||||
- Elements in the ingredients dictionary can be either a string or a
|
||||
dictionary.
|
||||
|
||||
- If they're a dictionary they may contain attributes `quantity` (of
|
||||
type number) and `name` (of type string).
|
||||
|
||||
- The s
|
||||
- cript function `ValidateIngredients` is run to perform further
|
||||
validation of the ingredients dictionary.
|
||||
|
||||
- Pizza objects may contain attribute matching the pattern
|
||||
`custom::*` of any type.
|
||||
|
||||
Valid types for type rules include:
|
||||
|
||||
* %any
|
||||
* %number
|
||||
* %string
|
||||
* %scalar (an alias for string)
|
||||
* %dictionary
|
||||
* %array
|
||||
|
||||
-->
|
||||
|
|
@ -1,22 +0,0 @@
|
|||
## <a id="global-constants"></a> Global Constants
|
||||
|
||||
Icinga 2 provides a number of special global constants. Some of them can be overriden using the `--define` command line parameter:
|
||||
|
||||
Variable |Description
|
||||
--------------------|-------------------
|
||||
PrefixDir |**Read-only.** Contains the installation prefix that was specified with cmake -DCMAKE_INSTALL_PREFIX. Defaults to "/usr/local".
|
||||
SysconfDir |**Read-only.** Contains the path of the sysconf directory. Defaults to PrefixDir + "/etc".
|
||||
LocalStateDir |**Read-only.** Contains the path of the local state directory. Defaults to PrefixDir + "/var".
|
||||
PkgDataDir |**Read-only.** Contains the path of the package data directory. Defaults to PrefixDir + "/share/icinga2".
|
||||
StatePath |**Read-write.** Contains the path of the Icinga 2 state file. Defaults to LocalStateDir + "/lib/icinga2/icinga2.state".
|
||||
PidPath |**Read-write.** Contains the path of the Icinga 2 PID file. Defaults to LocalStateDir + "/run/icinga2/icinga2.pid".
|
||||
Vars |**Read-write.** Contains a dictionary with global custom attributes. Not set by default.
|
||||
NodeName |**Read-write.** Contains the cluster node name. Set to the local hostname by default.
|
||||
ApplicationType |**Read-write.** Contains the name of the Application type. Defaults to "icinga/IcingaApplication".
|
||||
EnableNotifications |**Read-write.** Whether notifications are globally enabled. Defaults to true.
|
||||
EnableEventHandlers |**Read-write.** Whether event handlers are globally enabled. Defaults to true.
|
||||
EnableFlapping |**Read-write.** Whether flap detection is globally enabled. Defaults to true.
|
||||
EnableHostChecks |**Read-write.** Whether active host checks are globally enabled. Defaults to true.
|
||||
EnableServiceChecks |**Read-write.** Whether active service checks are globally enabled. Defaults to true.
|
||||
EnablePerfdata |**Read-write.** Whether performance data processing is globally enabled. Defaults to true.
|
||||
UseVfork |**Read-write.** Whether to use vfork(). Only available on *NIX. Defaults to true.
|
||||
|
|
@ -1,263 +0,0 @@
|
|||
# <a id="icinga-template-library"></a> Icinga Template Library
|
||||
|
||||
## <a id="itl-overview"></a> Overview
|
||||
|
||||
The Icinga Template Library (ITL) implements standard templates and object
|
||||
definitions for commonly used services.
|
||||
|
||||
You can include the ITL by using the `include` directive in your configuration
|
||||
file:
|
||||
|
||||
include <itl/itl.conf>
|
||||
|
||||
The ITL assumes that there's a global constant named `PluginDir` which contains
|
||||
the path of the plugins from the Monitoring Plugins project.
|
||||
|
||||
## <a id="itl-check-commands"></a> Check Commands
|
||||
|
||||
### <a id="itl-ping4"></a> ping4
|
||||
|
||||
Check command object for the `check_ping` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
ping_address | **Optional.** The host's IPv4 address. Defaults to "$address$".
|
||||
ping_wrta | **Optional.** The RTA warning threshold in milliseconds. Defaults to 100.
|
||||
ping_wpl | **Optional.** The packet loss warning threshold in %. Defaults to 5.
|
||||
ping_crta | **Optional.** The RTA critical threshold in milliseconds. Defaults to 200.
|
||||
ping_cpl | **Optional.** The packet loss critical threshold in %. Defaults to 15.
|
||||
ping_packets | **Optional.** The number of packets to send. Defaults to 5.
|
||||
ping_timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
|
||||
|
||||
### <a id="itl-ping6"></a> ping6
|
||||
|
||||
Check command object for the `check_ping` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
ping_address | **Optional.** The host's IPv6 address. Defaults to "$address6$".
|
||||
ping_wrta | **Optional.** The RTA warning threshold in milliseconds. Defaults to 100.
|
||||
ping_wpl | **Optional.** The packet loss warning threshold in %. Defaults to 5.
|
||||
ping_crta | **Optional.** The RTA critical threshold in milliseconds. Defaults to 200.
|
||||
ping_cpl | **Optional.** The packet loss critical threshold in %. Defaults to 15.
|
||||
ping_packets | **Optional.** The number of packets to send. Defaults to 5.
|
||||
ping_timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
|
||||
|
||||
### <a id="itl-hostalive"></a> hostalive
|
||||
|
||||
Check command object for the `check_ping` plugin with host check default values.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
ping_address | **Optional.** The host's IPv4 address. Defaults to "$address$".
|
||||
ping_wrta | **Optional.** The RTA warning threshold in milliseconds. Defaults to 3000.
|
||||
ping_wpl | **Optional.** The packet loss warning threshold in %. Defaults to 80.
|
||||
ping_crta | **Optional.** The RTA critical threshold in milliseconds. Defaults to 5000.
|
||||
ping_cpl | **Optional.** The packet loss critical threshold in %. Defaults to 100.
|
||||
ping_packets | **Optional.** The number of packets to send. Defaults to 5.
|
||||
ping_timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
|
||||
|
||||
### <a id="itl-dummy"></a> dummy
|
||||
|
||||
Check command object for the `check_dummy` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
dummy_state | **Optional.** The state. Can be one of 0 (ok), 1 (warning), 2 (critical) and 3 (unknown). Defaults to 0.
|
||||
dummy_text | **Optional.** Plugin output. Defaults to "Check was successful.".
|
||||
|
||||
### <a id="itl-passive"></a> passive
|
||||
|
||||
Specialised check command object for passive checks executing the `check_dummy` plugin with appropriate default values.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
dummy_state | **Optional.** The state. Can be one of 0 (ok), 1 (warning), 2 (critical) and 3 (unknown). Defaults to 3.
|
||||
dummy_text | **Optional.** Plugin output. Defaults to "No Passive Check Result Received.".
|
||||
|
||||
### <a id="itl-tcp"></a> tcp
|
||||
|
||||
Check command object for the `check_tcp` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
tcp_address | **Optional.** The host's address. Defaults to "$address$".
|
||||
tcp_port | **Required.** The port that should be checked.
|
||||
|
||||
### <a id="itl-udp"></a> udp
|
||||
|
||||
Check command object for the `check_udp` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
udp_address | **Optional.** The host's address. Defaults to "$address$".
|
||||
udp_port | **Required.** The port that should be checked.
|
||||
|
||||
### <a id="itl-http-ip"></a> http
|
||||
|
||||
Check command object for the `check_http` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
-------------------|--------------
|
||||
http_address | **Optional.** The host's address. Defaults to "$address".
|
||||
http_vhost | **Optional.** The virtual host that should be sent in the "Host" header.
|
||||
http_uri | **Optional.** The request URI.
|
||||
http_port | **Optional.** The TCP port. Defaults to 80 when not using SSL, 443 otherwise.
|
||||
http_ssl | **Optional.** Whether to use SSL. Defaults to false.
|
||||
http_warn_time | **Optional.** The warning threshold.
|
||||
http_critical_time | **Optional.** The critical threshold.
|
||||
|
||||
### <a id="itl-smtp"></a> smtp
|
||||
|
||||
Check command object for the `check_smtp` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
---------------------|--------------
|
||||
smtp_address | **Optional.** The host's address. Defaults to "$address$".
|
||||
|
||||
### <a id="itl-ssmtp"></a> ssmtp
|
||||
|
||||
Check command object for the `check_ssmtp` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
ssmtp_address | **Required.** The host's address. Defaults to "$address$".
|
||||
ssmtp_port | **Optional.** The port that should be checked. Defaults to 465.
|
||||
|
||||
### <a id="itl-ntp-time"></a> ntp_time
|
||||
|
||||
Check command object for the `check_ntp_time` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
ntp_address | **Optional.** The host's address. Defaults to "$address$".
|
||||
|
||||
### <a id="itl-ssh"></a> ssh
|
||||
|
||||
Check command object for the `check_ssh` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
ssh_address | **Optional.** The host's address. Defaults to "$address$".
|
||||
ssh_port | **Optional.** The port that should be checked. Defaults to 22.
|
||||
|
||||
### <a id="itl-disk"></a> disk
|
||||
|
||||
Check command object for the `check_disk` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
disk_wfree | **Optional.** The free space warning threshold in %. Defaults to 20.
|
||||
disk_cfree | **Optional.** The free space critical threshold in %. Defaults to 10.
|
||||
|
||||
### <a id="itl-users"></a> users
|
||||
|
||||
Check command object for the `check_disk` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
users_wgreater | **Optional.** The user count warning threshold. Defaults to 20.
|
||||
users_cgreater | **Optional.** The user count critical threshold. Defaults to 50.
|
||||
|
||||
### <a id="itl-processes"></a> procs
|
||||
|
||||
Check command object for the `check_procs` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
procs_wgreater | **Optional.** The process count warning threshold. Defaults to 250.
|
||||
procs_cgreater | **Optional.** The process count critical threshold. Defaults to 400.
|
||||
|
||||
### <a id="itl-swap"></a> swap
|
||||
|
||||
Check command object for the `check_swap` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
swap_wfree | **Optional.** The free swap space warning threshold in %. Defaults to 50.
|
||||
swap_cfree | **Optional.** The free swap space critical threshold in %. Defaults to 25.
|
||||
|
||||
### <a id="itl-load"></a> load
|
||||
|
||||
Check command object for the `check_load` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
load_wload1 | **Optional.** The 1-minute warning threshold. Defaults to 5.
|
||||
load_wload5 | **Optional.** The 5-minute warning threshold. Defaults to 4.
|
||||
load_wload15 | **Optional.** The 15-minute warning threshold. Defaults to 3.
|
||||
load_cload1 | **Optional.** The 1-minute critical threshold. Defaults to 10.
|
||||
load_cload5 | **Optional.** The 5-minute critical threshold. Defaults to 6.
|
||||
load_cload15 | **Optional.** The 15-minute critical threshold. Defaults to 4.
|
||||
|
||||
### <a id="itl-snmp"></a> snmp
|
||||
|
||||
Check command object for the `check_snmp` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
snmp_address | **Optional.** The host's address. Defaults to "$address$".
|
||||
snmp_oid | **Required.** The SNMP OID.
|
||||
snmp_community | **Optional.** The SNMP community. Defaults to "public".
|
||||
|
||||
### <a id="itl-snmp-uptime"></a> snmp-uptime
|
||||
|
||||
Check command object for the `check_snmp` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
snmp_address | **Optional.** The host's address. Defaults to "$address$".
|
||||
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".
|
||||
|
||||
### <a id="itl-apt"></a> apt
|
||||
|
||||
Check command for the `check_apt` plugin.
|
||||
|
||||
The `apt` check command does not support any vars.
|
||||
|
||||
### <a id="itl-icinga"></a> 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.
|
||||
|
||||
|
|
@ -1,4 +1,185 @@
|
|||
## <a id="cluster"></a> Cluster
|
||||
# <a id="monitoring-remote-instances"></a> Monitoring Remote Instances
|
||||
|
||||
## <a id="agent-less-checks"></a> Agent-less Checks
|
||||
|
||||
If the remote service is available using a network protocol and port,
|
||||
and a [check plugin](#setting-up-check-plugins) is available, you don't
|
||||
necessarily need a local client installed. Rather choose a plugin and
|
||||
configure all parameters and thresholds. The [Icinga 2 Template Library](#itl)
|
||||
already ships various examples.
|
||||
|
||||
## <a id="agent-based-checks"></a> 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.
|
||||
|
||||
### <a id="agent-based-checks-snmp"></a> SNMP
|
||||
|
||||
The SNMP daemon runs on the remote system and answers SNMP queries by plugin
|
||||
binaries. The [Monitoring Plugins package](#setting-up-check-plugins) ships
|
||||
the `check_snmp` plugin binary, but there are plenty of [existing plugins](#integrate-additional-plugins)
|
||||
for specific use cases already around, for example monitoring Cisco routers.
|
||||
|
||||
The following example uses the [SNMP ITL](#itl-snmp) `CheckCommand` and just
|
||||
overrides the `oid` custom attribute. A service is created for all hosts which
|
||||
have the `community` custom attribute.
|
||||
|
||||
apply Service "uptime" {
|
||||
import "generic-service"
|
||||
|
||||
check_command = "snmp"
|
||||
vars.oid = "1.3.6.1.2.1.1.3.0"
|
||||
|
||||
assign where host.vars.community
|
||||
}
|
||||
|
||||
### <a id="agent-based-checks-ssh"></a> SSH
|
||||
|
||||
Calling a plugin using the SSH protocol to execute a plugin on the remote server fetching
|
||||
its return code and output. `check_by_ssh` is available in the [Monitoring Plugins package](#setting-up-check-plugins).
|
||||
|
||||
object CheckCommand "check_by_ssh_swap" {
|
||||
import "plugin-check-command"
|
||||
|
||||
command = [ PluginDir + "/check_by_ssh",
|
||||
"-l", "remoteuser",
|
||||
"-H", "$address$",
|
||||
"-C", "\"/usr/local/icinga/libexec/check_swap -w $warn$ -c $crit$\""
|
||||
]
|
||||
}
|
||||
|
||||
object Service "swap" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "remote-ssh-host"
|
||||
|
||||
check_command = "check_by_ssh_swap"
|
||||
vars = {
|
||||
"warn" = "50%"
|
||||
"crit" = "75%"
|
||||
}
|
||||
}
|
||||
|
||||
### <a id="agent-based-checks-nrpe"></a> NRPE
|
||||
|
||||
[NRPE](http://docs.icinga.org/latest/en/nrpe.html) runs as daemon on the remote client including
|
||||
the required plugins and command definitions.
|
||||
Icinga 2 calls the `check_nrpe` plugin binary in order to query the configured command on the
|
||||
remote client.
|
||||
|
||||
The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe`
|
||||
can be embedded into the Icinga 2 `CheckCommand` configuration syntax.
|
||||
|
||||
Example:
|
||||
|
||||
object CheckCommand "check_nrpe" {
|
||||
import "plugin-check-command"
|
||||
|
||||
command = [
|
||||
PluginDir + "/check_nrpe",
|
||||
"-H", "$address$",
|
||||
"-c", "$remote_nrpe_command$",
|
||||
]
|
||||
}
|
||||
|
||||
object Service "users" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "remote-nrpe-host"
|
||||
|
||||
check_command = "check_nrpe"
|
||||
vars.remote_nrpe_command = "check_users"
|
||||
}
|
||||
|
||||
nrpe.cfg:
|
||||
|
||||
command[check_users]=/usr/local/icinga/libexec/check_users -w 5 -c 10
|
||||
|
||||
### <a id="agent-based-checks-nsclient"></a> NSClient++
|
||||
|
||||
[NSClient++](http://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,
|
||||
but using `NSClient++` will allow you to run local scripts similar to check plugins fetching
|
||||
the required output and performance counters.
|
||||
|
||||
The NSClient++ agent uses its own configuration format while `check_nt`
|
||||
can be embedded into the Icinga 2 `CheckCommand` configuration syntax.
|
||||
|
||||
Example:
|
||||
|
||||
object CheckCommand "check_nscp" {
|
||||
import "plugin-check-command"
|
||||
|
||||
command = [
|
||||
PluginDir + "/check_nt",
|
||||
"-H", "$address$",
|
||||
"-p", "$port$",
|
||||
"-v", "$remote_nscp_command$",
|
||||
"-l", "$partition$",
|
||||
"-w", "$warn$",
|
||||
"-c", "$crit$",
|
||||
"-s", "$pass$"
|
||||
]
|
||||
|
||||
vars = {
|
||||
"port" = "12489"
|
||||
"pass" = "supersecret"
|
||||
}
|
||||
}
|
||||
|
||||
object Service "users" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "remote-windows-host"
|
||||
|
||||
check_command = "check_nscp"
|
||||
|
||||
vars += {
|
||||
remote_nscp_command = "USEDDISKSPACE"
|
||||
partition = "c"
|
||||
warn = "70"
|
||||
crit = "80"
|
||||
}
|
||||
}
|
||||
|
||||
For details on the `NSClient++` configuration please refer to the [official documentation](http://www.nsclient.org/nscp/wiki/doc/configuration/0.4.x).
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The format of the `NSClient++` configuration file has changed from 0.3.x to 0.4!
|
||||
|
||||
### <a id="agent-based-checks-icinga2-agent"></a> Icinga 2 Agent
|
||||
|
||||
A dedicated Icinga 2 agent supporting all platforms and using the native
|
||||
Icinga 2 communication protocol supported with SSL certificates, IPv4/IPv6
|
||||
support, etc. is on the [development roadmap](https://dev.icinga.org/projects/i2?jump=issues).
|
||||
Meanwhile remote checkers in a [Cluster](#cluster) setup could act as
|
||||
immediate replacement, but without any local configuration - or pushing
|
||||
their standalone configuration back to the master node including their check
|
||||
result messages.
|
||||
|
||||
### <a id="agent-based-checks-snmp-traps"></a> 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.
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> The host and service object configuration must be available on the Icinga 2
|
||||
> server in order to process passive check results.
|
||||
|
||||
### <a id="agent-based-checks-nsca-ng"></a> 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`
|
||||
feature.
|
||||
|
||||
The [Icinga 2 Vagrant Demo VM](#vagrant) ships a demo integration and further samples.
|
||||
|
||||
|
||||
|
||||
## <a id="distributed-monitoring"></a> Distributed Monitoring
|
||||
|
||||
An Icinga 2 cluster consists of two or more nodes and can reside on multiple
|
||||
architectures. The base concept of Icinga 2 is the possibility to add additional
|
||||
|
|
@ -480,3 +661,43 @@ department instances. Furthermore the central NOC is able to see what's going on
|
|||
|
||||
The instances in the departments will serve a local interface, and allow the administrators
|
||||
to reschedule checks or acknowledge problems for their services.
|
||||
|
||||
|
||||
|
||||
### <a id="domains"></a> Domains
|
||||
|
||||
A [Service](#objecttype-service) object can be restricted using the `domains` attribute
|
||||
array specifying endpoint privileges.
|
||||
A Domain object specifices the ACLs applied for each [Endpoint](#objecttype-endpoint).
|
||||
|
||||
The following example assigns the domain `dmz-db` to the service `dmz-oracledb`. Endpoint
|
||||
`icinga-node-dmz-1` does not allow any object modification (no commands, check results) and only
|
||||
relays local messages to the remote node(s). The endpoint `icinga-node-dmz-2` processes all
|
||||
messages read and write (accept check results, commands and also relay messages to remote
|
||||
nodes).
|
||||
|
||||
That way the service `dmz-oracledb` on endpoint `icinga-node-dmz-1` will not be modified
|
||||
by any cluster event message, and could be checked by the local authority too presenting
|
||||
a different state history. `icinga-node-dmz-2` still receives all cluster message updates
|
||||
from the `icinga-node-dmz-1` endpoint.
|
||||
|
||||
object Host "dmz-host1" {
|
||||
import "generic-host"
|
||||
}
|
||||
|
||||
object Service "dmz-oracledb" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "dmz-host1"
|
||||
|
||||
domains = [ "dmz-db" ]
|
||||
authorities = [ "icinga-node-dmz-1", "icinga-node-dmz-2"]
|
||||
}
|
||||
|
||||
object Domain "dmz-db" {
|
||||
acl = {
|
||||
"icinga-node-dmz-1" = DomainPrivReadOnly
|
||||
"icinga-node-dmz-2" = DomainPrivReadWrite
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -1,3 +1,5 @@
|
|||
# <a id="addons-plugins"></a> Icinga Addons and Plugins
|
||||
|
||||
## <a id="plugin-api"></a> Plugin API
|
||||
|
||||
Currently Icinga 2 supports the native plugin API specification from the `Monitoring Plugins`
|
||||
|
|
@ -1 +0,0 @@
|
|||
# <a id="advanced-topics"></a> Advanced Topics
|
||||
|
|
@ -1,85 +0,0 @@
|
|||
## <a id="downtimes"></a> Downtimes
|
||||
|
||||
Downtimes can be scheduled for planned server maintenance or
|
||||
any other targetted service outage you are aware of in advance.
|
||||
|
||||
Downtimes will suppress any notifications, and may trigger other
|
||||
downtimes too. If the downtime was set by accident, or the duration
|
||||
exceeds the maintenance, you can manually cancel the downtime.
|
||||
Planned downtimes will also be taken into account for SLA reporting
|
||||
tools calculating the SLAs based on the state and downtime history.
|
||||
|
||||
Downtimes may overlap with their start and end times. If there
|
||||
are multiple downtimes triggered for one object, the overall downtime depth
|
||||
will be more than `1`. This is useful when you want to extend
|
||||
your maintenance window taking longer than expected.
|
||||
|
||||
### <a id="fixed-flexible-downtimes"></a> 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
|
||||
will change to `NOT-OK` and then actually trigger the downtime.
|
||||
Notifications are suppressed and the downtime depth is incremented.
|
||||
|
||||
Common scenarios are a planned distribution upgrade on your linux
|
||||
servers, or database updates in your warehouse. The customer knows
|
||||
about a fixed downtime window between 23:00 and 24:00. After 24:00
|
||||
all problems should be alerted again. Solution is simple -
|
||||
schedule a `fixed` downtime starting at 23:00 and ending at 24:00.
|
||||
|
||||
Unlike a `fixed` downtime, a `flexible` downtime end does not necessarily
|
||||
happen at the provided end time. Instead the downtime will be triggered
|
||||
by the state change in the time span defined by start and end time, but
|
||||
then last a defined duration in minutes.
|
||||
|
||||
Imagine the following scenario: Your service is frequently polled
|
||||
by users trying to grab free deleted domains for immediate registration.
|
||||
Between 07:30 and 08:00 the impact will hit for 15 minutes and generate
|
||||
a network outage visible to the monitoring. The service is still alive,
|
||||
but answering too slow to Icinga 2 service checks.
|
||||
For that reason, you may want to schedule a downtime between 07:30 and
|
||||
08:00 with a duration of 15 minutes. The downtime will then last from
|
||||
its trigger time until the duration is over. After that, the downtime
|
||||
is removed (may happen before or after the actual end time!).
|
||||
|
||||
### <a id="scheduling-downtime"></a> Scheduling a downtime
|
||||
|
||||
This can either happen through a web interface (Icinga 1.x Classic UI or Web)
|
||||
or by using the external command pipe provided by the `ExternalCommandListener`
|
||||
configuration.
|
||||
|
||||
Fixed downtimes require a start and end time (a duration will be ignored).
|
||||
Flexible downtimes need a start and end time for the time span, and a duration
|
||||
independent from that time span.
|
||||
|
||||
### <a id="triggered-downtimes"></a> 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
|
||||
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.
|
||||
|
||||
### <a id="recurring-downtimes"></a> Recurring Downtimes
|
||||
|
||||
[ScheduledDowntime objects](#objecttype-scheduleddowntime) can be used to set up
|
||||
recurring downtimes for services.
|
||||
|
||||
Example:
|
||||
|
||||
apply ScheduledDowntime "backup-downtime" to Service {
|
||||
author = "icingaadmin"
|
||||
comment = "Scheduled downtime for backup"
|
||||
|
||||
ranges = {
|
||||
monday = "02:00-03:00"
|
||||
tuesday = "02:00-03:00"
|
||||
wednesday = "02:00-03:00"
|
||||
thursday = "02:00-03:00"
|
||||
friday = "02:00-03:00"
|
||||
saturday = "02:00-03:00"
|
||||
sunday = "02:00-03:00"
|
||||
}
|
||||
|
||||
assign where "backup" in service.groups
|
||||
}
|
||||
|
|
@ -1,10 +0,0 @@
|
|||
## <a id="comments"></a> Comments
|
||||
|
||||
Comments can be added at runtime and are persistent over restarts. You can
|
||||
add useful information for others on repeating incidents (for example
|
||||
"last time syslog at 100% cpu on 17.10.2013 due to stale nfs mount") which
|
||||
is primarly accessible using web interfaces.
|
||||
|
||||
Adding and deleting comment actions are possible through the external command pipe
|
||||
provided with the `ExternalCommandListener` configuration. The caller must
|
||||
pass the comment id in case of manipulating an existing comment.
|
||||
|
|
@ -1,23 +0,0 @@
|
|||
## <a id="acknowledgements"></a> Acknowledgements
|
||||
|
||||
If a problem is alerted and notified you may signal the other notification
|
||||
receipients that you are aware of the problem and will handle it.
|
||||
|
||||
By sending an acknowledgement to Icinga 2 (using the external command pipe
|
||||
provided with `ExternalCommandListener` configuration) all future notifications
|
||||
are suppressed, a new comment is added with the provided description and
|
||||
a notification with the type `NotificationFilterAcknowledgement` is sent
|
||||
to all notified users.
|
||||
|
||||
### <a id="expiring-acknowledgements"></a> 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
|
||||
notifications too.
|
||||
|
||||
This `fire-and-forget` action is quite common. If you're sure that a
|
||||
current problem should be resolved in the future at a defined time,
|
||||
you can define an expiration time when acknowledging the problem.
|
||||
|
||||
Icinga 2 will clear the acknowledgement when expired and start to
|
||||
re-notify if the problem persists.
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
## <a id="domains"></a> Domains
|
||||
|
||||
A [Service](#objecttype-service) object can be restricted using the `domains` attribute
|
||||
array specifying endpoint privileges.
|
||||
A Domain object specifices the ACLs applied for each [Endpoint](#objecttype-endpoint).
|
||||
|
||||
The following example assigns the domain `dmz-db` to the service `dmz-oracledb`. Endpoint
|
||||
`icinga-node-dmz-1` does not allow any object modification (no commands, check results) and only
|
||||
relays local messages to the remote node(s). The endpoint `icinga-node-dmz-2` processes all
|
||||
messages read and write (accept check results, commands and also relay messages to remote
|
||||
nodes).
|
||||
|
||||
That way the service `dmz-oracledb` on endpoint `icinga-node-dmz-1` will not be modified
|
||||
by any cluster event message, and could be checked by the local authority too presenting
|
||||
a different state history. `icinga-node-dmz-2` still receives all cluster message updates
|
||||
from the `icinga-node-dmz-1` endpoint.
|
||||
|
||||
object Host "dmz-host1" {
|
||||
import "generic-host"
|
||||
}
|
||||
|
||||
object Service "dmz-oracledb" {
|
||||
import "generic-service"
|
||||
|
||||
host_name = "dmz-host1"
|
||||
|
||||
domains = [ "dmz-db" ]
|
||||
authorities = [ "icinga-node-dmz-1", "icinga-node-dmz-2"]
|
||||
}
|
||||
|
||||
object Domain "dmz-db" {
|
||||
acl = {
|
||||
"icinga-node-dmz-1" = DomainPrivReadOnly
|
||||
"icinga-node-dmz-2" = DomainPrivReadWrite
|
||||
}
|
||||
}
|
||||
|
|
@ -1,43 +0,0 @@
|
|||
## <a id="dependencies"></a> Dependencies
|
||||
|
||||
Icinga 2 uses host and service [Dependency](#objecttype-dependency) objects either directly
|
||||
defined or as inline definition as `dependencies` dictionary. The `parent_host_name` and `parent_service_name`
|
||||
attributes are mandatory.
|
||||
|
||||
A service can depend on a host, and vice versa. A service has an implicit dependency (parent)
|
||||
to its host. A host to host dependency acts implicit as host parent relation.
|
||||
When dependencies are calculated, not only the immediate parent is taken into
|
||||
account but all parents are inherited.
|
||||
|
||||
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
|
||||
will fail in case the `dsl-router` host is down. Therefore the example below
|
||||
defines a host dependency which acts implicit as parent relation too.
|
||||
|
||||
Furthermore the host may be reachable but ping probes are dropped by the
|
||||
router's firewall. In case the `dsl-router``ping4` service check fails, all
|
||||
further checks for the `ping4` service on host `google-dns` service should
|
||||
be suppressed. This is achieved by setting the `disable_checks` attribute to `true`.
|
||||
|
||||
object Host "dsl-router" {
|
||||
address = "192.168.1.1"
|
||||
}
|
||||
|
||||
object Host "google-dns" {
|
||||
address = "8.8.8.8"
|
||||
}
|
||||
|
||||
apply Service "ping4" {
|
||||
import "generic-service"
|
||||
|
||||
check_command = "ping4"
|
||||
|
||||
assign where host.address
|
||||
}
|
||||
|
||||
apply Dependency "internet" to Service {
|
||||
parent_host_name = "dsl-router"
|
||||
disable_checks = true
|
||||
|
||||
assign where host.name != "dsl-router"
|
||||
}
|
||||
|
|
@ -1,13 +0,0 @@
|
|||
## <a id="check-result-freshness"></a> 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.
|
||||
|
||||
threshold = last check execution time + check interval
|
||||
|
||||
Passive check freshness is calculated from the `check_interval` attribute if set.
|
||||
|
||||
threshold = last check result time + check interval
|
||||
|
||||
If the freshness checks are invalid, a new check is executed defined by the
|
||||
`check_command` attribute.
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
## <a id="check-flapping"></a> Check Flapping
|
||||
|
||||
The flapping algorithm used in Icinga 2 does not store the past states but
|
||||
calculcates the flapping threshold from a single value based on counters and
|
||||
half-life values. Icinga 2 compares the value with a single flapping threshold
|
||||
configuration attribute named `flapping_threshold`.
|
||||
|
||||
Flapping detection can be enabled or disabled using the `enable_flapping` attribute.
|
||||
|
|
@ -1,12 +0,0 @@
|
|||
## <a id="volatile-services"></a> 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
|
||||
is reached with the check counter, a `HARD` state transition happens.
|
||||
Notifications are only triggered by `HARD` state changes and are then
|
||||
re-sent defined by the `interval` attribute.
|
||||
|
||||
It may be reasonable to have a volatile service which stays in a `HARD`
|
||||
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.
|
||||
|
|
@ -1,8 +0,0 @@
|
|||
## <a id="modified-attributes"></a> Modified Attributes
|
||||
|
||||
Icinga 2 allows you to modify defined object attributes at runtime different to
|
||||
the local configuration object attributes. These modified attributes are
|
||||
stored as bit-shifted-value and made available in backends. Icinga 2 stores
|
||||
modified attributes in its state file and restores them on restart.
|
||||
|
||||
Modified Attributes can be reset using external commands.
|
||||
|
|
@ -1,191 +0,0 @@
|
|||
## <a id="schemas"></a> Schemas
|
||||
|
||||
### <a id="schema-db-ido"></a> DB IDO
|
||||
|
||||
There is a detailed documentation for the Icinga IDOUtils 1.x
|
||||
database schema available on [http://docs.icinga.org/latest/en/db_model.html]
|
||||
|
||||
#### <a id="schema-db-ido-extensions"></a> DB IDO Schema Extensions
|
||||
|
||||
Icinga 2 specific extensions are shown below:
|
||||
|
||||
New tables: `endpoints`, `endpointstatus`
|
||||
|
||||
Table | Column | Type | Default | Description
|
||||
--------------------|--------------------|----------|---------|-------------
|
||||
endpoints | endpoint_object_id | bigint | NULL | FK: objects table
|
||||
endpoints | identity | TEXT | NULL | endpoint name
|
||||
endpoints | node | TEXT | NULL | local node name
|
||||
|
||||
Table | Column | Type | Default | Description
|
||||
--------------------|--------------------|----------|---------|-------------
|
||||
endpointstatus | endpoint_object_id | bigint | NULL | FK: objects table
|
||||
endpointstatus | identity | TEXT | NULL | endpoint name
|
||||
endpointstatus | node | TEXT | NULL | local node name
|
||||
endpointstatus | is_connected | smallint | 0 | update on endpoint connect/disconnect
|
||||
|
||||
New columns:
|
||||
|
||||
Table | Column | Type | Default | Description
|
||||
--------------------|-------------------------|----------|---------|-------------
|
||||
all status/history | endpoint_object_id | bigint | NULL | FK: objects table
|
||||
servicestatus | check_source | TEXT | NULL | node name where check was executed
|
||||
hoststatus | check_source | TEXT | NULL | node name where check was executed
|
||||
statehistory | check_source | TEXT | NULL | node name where check was executed
|
||||
logentries | object_id | bigint | NULL | FK: objects table (service associated with column)
|
||||
|
||||
Additional command custom variables populated from 'vars' dictionary.
|
||||
Additional global custom variables populated from 'Vars' constant (object_id is NULL).
|
||||
|
||||
|
||||
### <a id="schema-livestatus"></a> Livestatus
|
||||
|
||||
|
||||
#### <a id="schema-livestatus-tables"></a> Livestatus Tables
|
||||
|
||||
Table | Join |Description
|
||||
--------------|-----------|----------------------------
|
||||
hosts | | host config and status attributes, services counter
|
||||
hostgroups | | hostgroup config, status attributes and host/service counters
|
||||
services | hosts | service config and status attributes
|
||||
servicegroups | | servicegroup config, status attributes and service counters
|
||||
contacts | | contact config and status attributes
|
||||
contactgroups | | contact config, members
|
||||
commands | | command name and line
|
||||
status | | programstatus, config and stats
|
||||
comments | services | status attributes
|
||||
downtimes | services | status attributes
|
||||
timeperiods | | name and is inside flag
|
||||
endpoints | | config and status attributes
|
||||
log | services, hosts, contacts, commands | parses [compatlog](#objecttype-compatlogger) and shows log attributes
|
||||
statehist | hosts, services | parses [compatlog](#objecttype-compatlogger) and aggregates state change attributes
|
||||
|
||||
The `commands` table is populated with `CheckCommand`, `EventCommand` and `NotificationCommand` objects.
|
||||
|
||||
|
||||
#### <a id="schema-livestatus-table-attributes"></a> Livestatus Table Attributes
|
||||
|
||||
A detailed list which table attributes are supported can be found here: [https://wiki.icinga.org/display/icinga2/Livestatus#Livestatus-Attributes]
|
||||
|
||||
|
||||
#### <a id="schema-livestatus-get-queries"></a> Livestatus GET Queries
|
||||
|
||||
$ echo -e 'GET services' | netcat 127.0.0.1 6558
|
||||
|
||||
$ cat servicegroups <<EOF
|
||||
GET servicegroups
|
||||
|
||||
EOF
|
||||
|
||||
(cat servicegroups; sleep 1) | netcat 127.0.0.1 6558
|
||||
|
||||
#### <a id="schema-livestatus-command-queries"></a> Livestatus COMMAND Queries
|
||||
|
||||
A list of available external commands and their parameters can be found [here](#external-commands-list-detail)
|
||||
|
||||
$ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558
|
||||
|
||||
|
||||
#### <a id="schema-livestatus-filters"></a> Livestatus Filters
|
||||
|
||||
and, or, negate
|
||||
|
||||
Operator | Negate | Description
|
||||
----------|------------------------
|
||||
= | != | Euqality
|
||||
~ | !~ | Regex match
|
||||
=~ | !=~ | Euqality ignoring case
|
||||
~~ | !~~ | Regex ignoring case
|
||||
> | | Less than
|
||||
< | | Greater than
|
||||
>= | | Less than or equal
|
||||
<= | | Greater than or equal
|
||||
|
||||
|
||||
#### <a id="schema-livestatus-stats"></a> Livestatus Stats
|
||||
|
||||
Schema: "Stats: aggregatefunction aggregateattribute"
|
||||
|
||||
Aggregate Function | Description
|
||||
-------------------|--------------
|
||||
sum |
|
||||
min |
|
||||
max |
|
||||
avg | sum / count
|
||||
std | standard deviation
|
||||
suminv | sum (1 / value)
|
||||
avginv | suminv / count
|
||||
count | ordinary default for any stats query if not aggregate function defined
|
||||
|
||||
Example:
|
||||
|
||||
GET hosts
|
||||
Filter: has_been_checked = 1
|
||||
Filter: check_type = 0
|
||||
Stats: sum execution_time
|
||||
Stats: sum latency
|
||||
Stats: sum percent_state_change
|
||||
Stats: min execution_time
|
||||
Stats: min latency
|
||||
Stats: min percent_state_change
|
||||
Stats: max execution_time
|
||||
Stats: max latency
|
||||
Stats: max percent_state_change
|
||||
OutputFormat: json
|
||||
ResponseHeader: fixed16
|
||||
|
||||
#### <a id="schema-livestatus-output"></a> Livestatus Output
|
||||
|
||||
* CSV
|
||||
|
||||
CSV Output uses two levels of array seperators: The members array separator
|
||||
is a comma (1st level) while extra info and host|service relation separator
|
||||
is a pipe (2nd level).
|
||||
|
||||
Seperators can be set using ASCII codes like:
|
||||
|
||||
Separators: 10 59 44 124
|
||||
|
||||
* JSON
|
||||
|
||||
Default separators.
|
||||
|
||||
#### <a id="schema-livestatus-error-codes"></a> Livestatus Error Codes
|
||||
|
||||
Code | Description
|
||||
----------|--------------
|
||||
200 | OK
|
||||
404 | Table does not exist
|
||||
452 | Exception on query
|
||||
|
||||
#### <a id="schema-livestatus-extensions"></a> Livestatus Schema Extensions
|
||||
|
||||
Icinga 2 specific extensions are shown below:
|
||||
|
||||
New table: `endpoints`
|
||||
|
||||
Table | Column
|
||||
----------|--------------
|
||||
endpoints | name
|
||||
endpoints | identity
|
||||
endpoints | node
|
||||
endpoints | is_connected
|
||||
|
||||
New columns:
|
||||
|
||||
Table | Column
|
||||
----------|--------------
|
||||
services | check_source
|
||||
downtimes | triggers
|
||||
downtimes | trigger_time
|
||||
commands | custom_variable_names
|
||||
commands | custom_variable_values
|
||||
commands | custom_variables
|
||||
commands | modified_attributes
|
||||
commands | modified_attributes_list
|
||||
status | custom_variable_names
|
||||
status | custom_variable_values
|
||||
status | custom_variables
|
||||
|
||||
Command custom variables reflect the local 'vars' dictionary.
|
||||
Status custom variables reflect the global 'Vars' constant.
|
||||
|
|
@ -1,151 +0,0 @@
|
|||
## <a id="external-commands-list-detail"></a> External Commands List
|
||||
|
||||
Additional details can be found in the [Icinga 1.x Documentation](http://docs.icinga.org/latest/en/extcommands2.html)
|
||||
|
||||
Command name | Parameters | Description
|
||||
------------------------------------------|-----------------------------------|--------------------------
|
||||
PROCESS_HOST_CHECK_RESULT | ;<host_name>;<status_code>;<plugin_output> (3) |
|
||||
PROCESS_SERVICE_CHECK_RESULT | ;<host_name>;<service_name>;<return_code>;<plugin_output> (4) |
|
||||
SCHEDULE_HOST_CHECK | ;<host_name>;<check_time> (2) |
|
||||
SCHEDULE_FORCED_HOST_CHECK | ;<host_name>;<check_time> (2) |
|
||||
SCHEDULE_SVC_CHECK | ;<host_name>;<service_name>;<check_time> (3) |
|
||||
SCHEDULE_FORCED_SVC_CHECK | ;<host_name>;<service_name>;<check_time> (3) |
|
||||
ENABLE_HOST_CHECK | ;<host_name> (1) |
|
||||
DISABLE_HOST_CHECK | ;<host_name> (1) |
|
||||
ENABLE_SVC_CHECK | ;<host_name>;<service_name> (2) |
|
||||
DISABLE_SVC_CHECK | ;<host_name>;<service_name> (2) |
|
||||
SHUTDOWN_PROCESS | (0) |
|
||||
RESTART_PROCESS | (0) |
|
||||
SCHEDULE_FORCED_HOST_SVC_CHECKS | ;<host_name>;<check_time> (2) |
|
||||
SCHEDULE_HOST_SVC_CHECKS | ;<host_name>;<check_time> (2) |
|
||||
ENABLE_HOST_SVC_CHECKS | ;<host_name> (1) |
|
||||
DISABLE_HOST_SVC_CHECKS | ;<host_name> (1) |
|
||||
ACKNOWLEDGE_SVC_PROBLEM | ;<host_name>;<service_name>;<sticky>;<notify>;<persistent>;<author>;<comment> (7) | Note: Icinga 2 treats all comments as persistent.
|
||||
ACKNOWLEDGE_SVC_PROBLEM_EXPIRE | ;<host_name>;<service_name>;<sticky>;<notify>;<persistent>;<timestamp>;<author>;<comment> (8) | Note: Icinga 2 treats all comments as persistent.
|
||||
REMOVE_SVC_ACKNOWLEDGEMENT | ;<host_name>;<service_name> (2) |
|
||||
ACKNOWLEDGE_HOST_PROBLEM | ;<host_name>;<sticky>;<notify>;<persistent>;<author>;<comment> (6) | Note: Icinga 2 treats all comments as persistent.
|
||||
ACKNOWLEDGE_HOST_PROBLEM_EXPIRE | ;<host_name>;<sticky>;<notify>;<persistent>;<timestamp>;<author>;<comment> (7) | Note: Icinga 2 treats all comments as persistent.
|
||||
REMOVE_HOST_ACKNOWLEDGEMENT | ;<host_name> (1) |
|
||||
DISABLE_HOST_FLAP_DETECTION | ;<host_name> (1) |
|
||||
ENABLE_HOST_FLAP_DETECTION | ;<host_name> (1) |
|
||||
DISABLE_SVC_FLAP_DETECTION | ;<host_name>;<service_name> (2) |
|
||||
ENABLE_SVC_FLAP_DETECTION | ;<host_name>;<service_name> (2) |
|
||||
ENABLE_HOSTGROUP_SVC_CHECKS | ;<hostgroup_name> (1) |
|
||||
DISABLE_HOSTGROUP_SVC_CHECKS | ;<hostgroup_name> (1) |
|
||||
ENABLE_SERVICEGROUP_SVC_CHECKS | ;<servicegroup_name> (1) |
|
||||
DISABLE_SERVICEGROUP_SVC_CHECKS | ;<servicegroup_name> (1) |
|
||||
ENABLE_PASSIVE_HOST_CHECKS | ;<host_name> (1) |
|
||||
DISABLE_PASSIVE_HOST_CHECKS | ;<host_name> (1) |
|
||||
ENABLE_PASSIVE_SVC_CHECKS | ;<host_name>;<service_name> (2) |
|
||||
DISABLE_PASSIVE_SVC_CHECKS | ;<host_name>;<service_name> (2) |
|
||||
ENABLE_SERVICEGROUP_PASSIVE_SVC_CHECKS | ;<servicegroup_name> (1) |
|
||||
DISABLE_SERVICEGROUP_PASSIVE_SVC_CHECKS | ;<servicegroup_name> (1) |
|
||||
ENABLE_HOSTGROUP_PASSIVE_SVC_CHECKS | ;<hostgroup_name> (1) |
|
||||
DISABLE_HOSTGROUP_PASSIVE_SVC_CHECKS | ;<hostgroup_name> (1) |
|
||||
PROCESS_FILE | ;<file_name>;<delete> (2) |
|
||||
SCHEDULE_SVC_DOWNTIME | ;<host_name>;<service_name>;<start_time>;<end_time>;<fixed>;<trigger_id>;<duration>;<author>;<comment> (9) |
|
||||
DEL_SVC_DOWNTIME | ;<downtime_id> (1) |
|
||||
SCHEDULE_HOST_DOWNTIME | ;<host_name>;<start_time>;<end_time>;<fixed>;<trigger_id>;<duration>;<author>;<comment> (8) |
|
||||
DEL_HOST_DOWNTIME | ;<downtime_id> (1) |
|
||||
SCHEDULE_HOST_SVC_DOWNTIME | ;<host_name>;<start_time>;<end_time>;<fixed>;<trigger_id>;<duration>;<author>;<comment> (8) |
|
||||
SCHEDULE_HOSTGROUP_HOST_DOWNTIME | ;<hostgroup_name>;<start_time>;<end_time>;<fixed>;<trigger_id>;<duration>;<author>;<comment> (8) |
|
||||
SCHEDULE_HOSTGROUP_SVC_DOWNTIME | ;<hostgroup_name>;<start_time>;<end_time>;<fixed>;<trigger_id>;<duration>;<author>;<comment> (8) |
|
||||
SCHEDULE_SERVICEGROUP_HOST_DOWNTIME | ;<servicegroup_name>;<start_time>;<end_time>;<fixed>;<trigger_id>;<duration>;<author>;<comment> (8) |
|
||||
SCHEDULE_SERVICEGROUP_SVC_DOWNTIME | ;<servicegroup_name>;<start_time>;<end_time>;<fixed>;<trigger_id>;<duration>;<author>;<comment> (8) |
|
||||
ADD_HOST_COMMENT | ;<host_name>;<persistent>;<author>;<comment> (4) | Note: Icinga 2 treats all comments as persistent.
|
||||
DEL_HOST_COMMENT | ;<comment_id> (1) |
|
||||
ADD_SVC_COMMENT | ;<host_name>;<service_name>;<persistent>;<author>;<comment> (5) | Note: Icinga 2 treats all comments as persistent.
|
||||
DEL_SVC_COMMENT | ;<comment_id> (1) |
|
||||
DEL_ALL_HOST_COMMENTS | ;<host_name> (1) |
|
||||
DEL_ALL_SVC_COMMENTS | ;<host_name>;<service_name> (2) |
|
||||
SEND_CUSTOM_HOST_NOTIFICATION | ;<host_name>;<options>;<author>;<comment> (4) |
|
||||
SEND_CUSTOM_SVC_NOTIFICATION | ;<host_name>;<service_name>;<options>;<author>;<comment> (5) |
|
||||
DELAY_HOST_NOTIFICATION | ;<host_name>;<notification_time> (2) |
|
||||
DELAY_SVC_NOTIFICATION | ;<host_name>;<service_name>;<notification_time> (3) |
|
||||
ENABLE_HOST_NOTIFICATIONS | ;<host_name> (1) |
|
||||
DISABLE_HOST_NOTIFICATIONS | ;<host_name> (1) |
|
||||
ENABLE_SVC_NOTIFICATIONS | ;<host_name>;<service_name> (2) |
|
||||
DISABLE_SVC_NOTIFICATIONS | ;<host_name>;<service_name> (2) |
|
||||
DISABLE_HOSTGROUP_HOST_CHECKS | ;<hostgroup_name> (1) |
|
||||
DISABLE_HOSTGROUP_PASSIVE_HOST_CHECKS | ;<hostgroup_name> (1) |
|
||||
DISABLE_SERVICEGROUP_HOST_CHECKS | ;<servicegroup_name> (1) |
|
||||
DISABLE_SERVICEGROUP_PASSIVE_HOST_CHECKS | ;<servicegroup_name> (1) |
|
||||
ENABLE_HOSTGROUP_HOST_CHECKS | ;<hostgroup_name> (1) |
|
||||
ENABLE_HOSTGROUP_PASSIVE_HOST_CHECKS | ;<hostgroup_name> (1) |
|
||||
ENABLE_SERVICEGROUP_HOST_CHECKS | ;<servicegroup_name> (1) |
|
||||
ENABLE_SERVICEGROUP_PASSIVE_HOST_CHECKS | ;<servicegroup_name> (1) |
|
||||
ENABLE_NOTIFICATIONS | (0) |
|
||||
DISABLE_NOTIFICATIONS | (0) |
|
||||
ENABLE_FLAP_DETECTION | (0) |
|
||||
DISABLE_FLAP_DETECTION | (0) |
|
||||
ENABLE_EVENT_HANDLERS | (0) |
|
||||
DISABLE_EVENT_HANDLERS | (0) |
|
||||
ENABLE_PERFORMANCE_DATA | (0) |
|
||||
DISABLE_PERFORMANCE_DATA | (0) |
|
||||
START_EXECUTING_HOST_CHECKS | (0) |
|
||||
STOP_EXECUTING_HOST_CHECKS | (0) |
|
||||
START_EXECUTING_SVC_CHECKS | (0) |
|
||||
STOP_EXECUTING_SVC_CHECKS | (0) |
|
||||
CHANGE_SVC_MODATTR | ;<host_name>;<service_name>;<value> (3) |
|
||||
CHANGE_HOST_MODATTR | ;<host_name>;<value> (2) |
|
||||
CHANGE_USER_MODATTR | ;<user_name>;<value> (2) |
|
||||
CHANGE_CHECKCOMMAND_MODATTR | ;<checkcommand_name>;<value> (2) |
|
||||
CHANGE_EVENTCOMMAND_MODATTR | ;<eventcommand_name>;<value> (2) |
|
||||
CHANGE_NOTIFICATIONCOMMAND_MODATTR | ;<notificationcommand_name>;<value> (2) |
|
||||
CHANGE_NORMAL_SVC_CHECK_INTERVAL | ;<host_name>;<service_name>;<check_interval> (3) |
|
||||
CHANGE_NORMAL_HOST_CHECK_INTERVAL | ;<host_name>;<check_interval> (2) |
|
||||
CHANGE_RETRY_SVC_CHECK_INTERVAL | ;<host_name>;<service_name>;<check_interval> (3) |
|
||||
CHANGE_RETRY_HOST_CHECK_INTERVAL | ;<host_name>;<check_interval> (2) |
|
||||
ENABLE_HOST_EVENT_HANDLER | ;<host_name> (1) |
|
||||
DISABLE_HOST_EVENT_HANDLER | ;<host_name> (1) |
|
||||
ENABLE_SVC_EVENT_HANDLER | ;<host_name>;<service_name> (2) |
|
||||
DISABLE_SVC_EVENT_HANDLER | ;<host_name>;<service_name> (2) |
|
||||
CHANGE_HOST_EVENT_HANDLER | ;<host_name>;<event_command_name> (2) |
|
||||
CHANGE_SVC_EVENT_HANDLER | ;<host_name>;<service_name>;<event_command_name> (3) |
|
||||
CHANGE_HOST_CHECK_COMMAND | ;<host_name>;<check_command_name> (2) |
|
||||
CHANGE_SVC_CHECK_COMMAND | ;<host_name>;<service_name>;<check_command_name> (3) |
|
||||
CHANGE_MAX_HOST_CHECK_ATTEMPTS | ;<host_name>;<check_attempts> (2) |
|
||||
CHANGE_MAX_SVC_CHECK_ATTEMPTS | ;<host_name>;<service_name>;<check_attempts> (3) |
|
||||
CHANGE_HOST_CHECK_TIMEPERIOD | ;<host_name>;<timeperiod_name> (2) |
|
||||
CHANGE_SVC_CHECK_TIMEPERIOD | ;<host_name>;<service_name>;<timeperiod_name> |
|
||||
CHANGE_CUSTOM_HOST_VAR | ;<host_name>;<var_name>;<var_value> (3) |
|
||||
CHANGE_CUSTOM_SVC_VAR | ;<host_name>;<service_name>;<var_name>;<var_value> (4) |
|
||||
CHANGE_CUSTOM_USER_VAR | ;<user_name>;<var_name>;<var_value> (3) |
|
||||
CHANGE_CUSTOM_CHECKCOMMAND_VAR | ;<check_command_name>;<var_name>;<var_value> (3) |
|
||||
CHANGE_CUSTOM_EVENTCOMMAND_VAR | ;<event_command_name>;<var_name>;<var_value> (3) |
|
||||
CHANGE_CUSTOM_NOTIFICATIONCOMMAND_VAR | ;<notification_command_name>;<var_name>;<var_value> (3) |
|
||||
ENABLE_HOSTGROUP_HOST_NOTIFICATIONS | ;<hostgroup_name> (1) |
|
||||
ENABLE_HOSTGROUP_SVC_NOTIFICATIONS | ;<hostgroup_name> (1) |
|
||||
DISABLE_HOSTGROUP_HOST_NOTIFICATIONS | ;<hostgroup_name> (1) |
|
||||
DISABLE_HOSTGROUP_SVC_NOTIFICATIONS | ;<hostgroup_name> (1) |
|
||||
ENABLE_SERVICEGROUP_HOST_NOTIFICATIONS | ;<servicegroup_name> (1) |
|
||||
DISABLE_SERVICEGROUP_HOST_NOTIFICATIONS | ;<servicegroup_name> (1) |
|
||||
ENABLE_SERVICEGROUP_SVC_NOTIFICATIONS | ;<servicegroup_name> (1) |
|
||||
DISABLE_SERVICEGROUP_SVC_NOTIFICATIONS | ;<servicegroup_name> (1) |
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
# <a id="migrating-from-icinga-1x"></a> Migrating from Icinga 1.x
|
||||
|
||||
## <a id="configuration-migration"></a> Configuration Migration
|
||||
|
||||
The Icinga 2 configuration format introduces plenty of behavioural changes. In
|
||||
order to ease migration from Icinga 1.x,
|
||||
Icinga 2 ships its own config migration script.
|
||||
|
||||
### <a id="configuration-migration-script"></a> Configuration Migration Script
|
||||
|
||||
Due to the complexity of the Icinga 1.x configuration format the migration
|
||||
script might not currently work for all use cases.
|
||||
|
||||
The config migration script provides support for basic Icinga 1.x
|
||||
configuration format migration to native Icinga 2 configuration syntax.
|
||||
|
||||
The migration script tries to preserve your existing template structure and
|
||||
adds new templates where appropriate. However, the original file structure is
|
||||
not preserved.
|
||||
|
||||
The migration script uses templates from the Icinga Template Library where
|
||||
possible.
|
||||
|
||||
# mkdir /etc/icinga2/conf.d/migrate
|
||||
# /usr/bin/icinga2-migrate-config -c /etc/icinga/icinga.cfg -o /etc/icinga2/conf.d/migrate
|
||||
|
||||
### <a id="manual-config-migration"></a> Manual Config Migration
|
||||
|
||||
For a long-term migration of your configuration you should consider re-creating
|
||||
your configuration based on the Icinga 2 proposed way of doing configuration right.
|
||||
|
||||
Please read the [next chapter](#differences-1x-2) to get an idea about the differences between 1.x and 2.
|
||||
|
|
@ -1,6 +1,42 @@
|
|||
# <a id="differences-1x-2"></a> Differences between Icinga 1.x and 2
|
||||
# <a id="migration"></a> Migration from Icinga 1.x
|
||||
|
||||
## <a id="differences-1x-2-configuration-format"></a> Configuration Format
|
||||
## <a id="configuration-migration"></a> Configuration Migration
|
||||
|
||||
The Icinga 2 configuration format introduces plenty of behavioural changes. In
|
||||
order to ease migration from Icinga 1.x,
|
||||
Icinga 2 ships its own config migration script.
|
||||
|
||||
### <a id="configuration-migration-script"></a> Configuration Migration Script
|
||||
|
||||
TODO
|
||||
|
||||
Due to the complexity of the Icinga 1.x configuration format the migration
|
||||
script might not currently work for all use cases.
|
||||
|
||||
The config migration script provides support for basic Icinga 1.x
|
||||
configuration format migration to native Icinga 2 configuration syntax.
|
||||
|
||||
The migration script tries to preserve your existing template structure and
|
||||
adds new templates where appropriate. However, the original file structure is
|
||||
not preserved.
|
||||
|
||||
The migration script uses templates from the Icinga Template Library where
|
||||
possible.
|
||||
|
||||
# mkdir /etc/icinga2/conf.d/migrate
|
||||
# /usr/bin/icinga2-migrate-config -c /etc/icinga/icinga.cfg -o /etc/icinga2/conf.d/migrate
|
||||
|
||||
### <a id="manual-config-migration"></a> Manual Config Migration
|
||||
|
||||
For a long-term migration of your configuration you should consider re-creating
|
||||
your configuration based on the Icinga 2 proposed way of doing configuration right.
|
||||
|
||||
Please read the [next chapter](#differences-1x-2) to get an idea about the differences between 1.x and 2.
|
||||
|
||||
|
||||
## <a id="differences-1x-2"></a> Differences between Icinga 1.x and 2
|
||||
|
||||
### <a id="differences-1x-2-configuration-format"></a> 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`,
|
||||
|
|
@ -22,7 +58,7 @@ if it's the main configuration file, or any included file.
|
|||
enable_notifications = 0
|
||||
}
|
||||
|
||||
### <a id="differences-1x-2-sample-configuration-itl"></a> Sample Configuration and ITL
|
||||
#### <a id="differences-1x-2-sample-configuration-itl"></a> 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)
|
||||
|
|
@ -66,7 +102,7 @@ as it matches the (wildcard) include expression.
|
|||
|
||||
By convention the `.conf` suffix is used for Icinga 2 configuration files.
|
||||
|
||||
## <a id="differences-1x-2-resource-file-global-macros"></a> Resource File and Global Macros
|
||||
### <a id="differences-1x-2-resource-file-global-macros"></a> 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
|
||||
|
|
@ -86,7 +122,7 @@ set in the `constants.conf` configuration file:
|
|||
[Global macros](#global-constants) can only be defined once. Trying to modify a
|
||||
global constant will result in an error.
|
||||
|
||||
## <a id="differences-1x-2-configuration-comments"></a> Configuration Comments
|
||||
### <a id="differences-1x-2-configuration-comments"></a> Configuration Comments
|
||||
|
||||
In Icinga 1.x comments are made using a leading hash (`#`) or a semi-colon (`;`)
|
||||
for inline comments.
|
||||
|
|
@ -94,7 +130,7 @@ for inline comments.
|
|||
In Icinga 2 comments can either be encapsulated by `/*` and `*/` (allowing for
|
||||
multi-line comments) or starting with two slashes (`//`).
|
||||
|
||||
## <a id="differences-1x-2-object-names"></a> Object names
|
||||
### <a id="differences-1x-2-object-names"></a> Object names
|
||||
|
||||
Object names must not contain a colon (`!`). Use the `display_name` attribute
|
||||
to specify user-friendly names which should be shown in UIs (supported by
|
||||
|
|
@ -112,7 +148,7 @@ services) like in Icinga 1.x but directly after their type definition.
|
|||
host_name = "localhost"
|
||||
}
|
||||
|
||||
## <a id="differences-1x-2-templates"></a> Templates
|
||||
### <a id="differences-1x-2-templates"></a> Templates
|
||||
|
||||
In Icinga 1.x templates are identified using the `register 0` setting. Icinga 2
|
||||
uses the `template` identifier:
|
||||
|
|
@ -133,7 +169,7 @@ Icinga 2 uses the keyword `import` with template names in double quotes.
|
|||
import "tmpl3"
|
||||
}
|
||||
|
||||
## <a id="differences-1x-2-object-attributes"></a> Object attributes
|
||||
### <a id="differences-1x-2-object-attributes"></a> Object attributes
|
||||
|
||||
Icinga 1.x separates attribute and value with whitespaces/tabs. Icinga 2
|
||||
requires an equal sign (=) between them.
|
||||
|
|
@ -154,7 +190,7 @@ must be escaped with a backslash (e.g. in command line).
|
|||
If an attribute identifier starts with a number, it must be encapsulated
|
||||
with double quotes as well.
|
||||
|
||||
### <a id="differences-1x-2-alias-display-name"></a> Alias vs. Display Name
|
||||
#### <a id="differences-1x-2-alias-display-name"></a> 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.
|
||||
|
|
@ -162,7 +198,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 1.x Classic UI and Web.
|
||||
|
||||
## <a id="differences-1x-2-custom-attributes"></a> Custom Attributes
|
||||
### <a id="differences-1x-2-custom-attributes"></a> 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`
|
||||
|
|
@ -170,7 +206,7 @@ attributes for host and service objects are still available in Icinga 2.
|
|||
|
||||
`2d_coords` and `statusmap_image` are not supported in Icinga 2.
|
||||
|
||||
### <a id="differences-1x-2-custom-variables"></a> Custom Variables
|
||||
#### <a id="differences-1x-2-custom-variables"></a> 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.
|
||||
|
|
@ -178,17 +214,16 @@ 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"
|
||||
|
||||
## <a id="differences-1x-2-host-service-relation"></a> Host Service Relation
|
||||
### <a id="differences-1x-2-host-service-relation"></a> 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 behavior changing regular expression. It's not possible
|
||||
to define a service definition within a host definition.
|
||||
to `hostgroup_name` or behavior changing regular expression.
|
||||
|
||||
The preferred way of associating hosts with services in Icinga 2 is by
|
||||
using the `apply` keyword.
|
||||
|
||||
## <a id="differences-1x-2-users"></a> Users
|
||||
### <a id="differences-1x-2-users"></a> Users
|
||||
|
||||
Contacts have been renamed to Users (same for groups). A user does not
|
||||
only provide attributes and custom attributes used for notifications, but is also
|
||||
|
|
@ -202,12 +237,12 @@ provide the contact and contactgroups attributes for services for compatibility
|
|||
reasons. These values are calculated from all services, their notifications,
|
||||
and their users.
|
||||
|
||||
## <a id="differences-1x-2-macros"></a> Macros
|
||||
### <a id="differences-1x-2-macros"></a> 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](#custom-attributes).
|
||||
|
||||
### <a id="differences-1x-2-command-arguments"></a> Command Arguments
|
||||
#### <a id="differences-1x-2-command-arguments"></a> 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
|
||||
|
|
@ -243,7 +278,7 @@ With the freely definable custom attributes in Icinga 2 it looks like this:
|
|||
vars.cpl = 60
|
||||
}
|
||||
|
||||
### <a id="differences-1x-2-environment-macros"></a> Environment Macros
|
||||
#### <a id="differences-1x-2-environment-macros"></a> Environment Macros
|
||||
|
||||
The global configuration setting `enable_environment_macros` does not exist in
|
||||
Icinga 2.
|
||||
|
|
@ -251,7 +286,7 @@ Icinga 2.
|
|||
Macros exported into the environment must be set using the `env`
|
||||
attribute in command objects.
|
||||
|
||||
### <a id="differences-1x-2-runtime-macros"></a> Runtime Macros
|
||||
#### <a id="differences-1x-2-runtime-macros"></a> Runtime Macros
|
||||
|
||||
Icinga 2 requires an object specific namespace when accessing configuration
|
||||
and stateful runtime macros. Custom attributes can be access directly.
|
||||
|
|
@ -326,7 +361,7 @@ Changes to global runtime macros:
|
|||
TIME | icinga.time
|
||||
|
||||
|
||||
## <a id="differences-1x-2-external-commands"></a> External Commands
|
||||
### <a id="differences-1x-2-external-commands"></a> External Commands
|
||||
|
||||
`CHANGE_CUSTOM_CONTACT_VAR` was renamed to `CHANGE_CUSTOM_USER_VAR`.
|
||||
`CHANGE_CONTACT_MODATTR` was renamed to `CHANGE_USER_MODATTR`.
|
||||
|
|
@ -378,9 +413,9 @@ The following external commands are not supported:
|
|||
STOP_OBSESSING_OVER_SVC
|
||||
STOP_OBSESSING_OVER_SVC_CHECKS
|
||||
|
||||
## <a id="differences-1x-2-checks"></a> Checks
|
||||
### <a id="differences-1x-2-checks"></a> Checks
|
||||
|
||||
### <a id="differences-1x-2-check-output"></a> Check Output
|
||||
#### <a id="differences-1x-2-check-output"></a> 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
|
||||
|
|
@ -390,18 +425,18 @@ The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types
|
|||
split the raw output into `output` (first line) and `long_output` (remaining
|
||||
lines) for compatibility reasons.
|
||||
|
||||
### <a id="differences-1x-2-initial-state"></a> Initial State
|
||||
#### <a id="differences-1x-2-initial-state"></a> 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.
|
||||
|
||||
## <a id="differences-1x-2-comments"></a> Comments
|
||||
### <a id="differences-1x-2-comments"></a> Comments
|
||||
|
||||
Icinga 2 doesn't support non-persistent comments.
|
||||
|
||||
## <a id="differences-1x-2-commands"></a> Commands
|
||||
### <a id="differences-1x-2-commands"></a> Commands
|
||||
|
||||
Unlike in Icinga 1.x there are 3 different command types in Icinga 2:
|
||||
`CheckCommand`, `NotificationCommand` and EventCommand`.
|
||||
|
|
@ -420,34 +455,36 @@ as array to the `command_line` attribute i.e. for better readability.
|
|||
It's also possible to define default custom attributes for the command itself which can be
|
||||
overridden by a service macro.
|
||||
|
||||
## <a id="differences-1x-2-groups"></a> Groups
|
||||
### <a id="differences-1x-2-groups"></a> 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 not supported.
|
||||
|
||||
The preferred way of assigning objects to groups is by using a template:
|
||||
|
||||
template Host "dev-host" {
|
||||
groups += [ "dev-hosts" ]
|
||||
}
|
||||
`members` attribute is available through `assign where` and `ignore where`
|
||||
conditions.
|
||||
|
||||
object Host "web-dev" {
|
||||
import "dev-host"
|
||||
import "generic-host"
|
||||
}
|
||||
|
||||
object HostGroup "dev-hosts" {
|
||||
display_name = "Dev Hosts"
|
||||
assign where match("*-dev", host.name)
|
||||
}
|
||||
|
||||
#### <a id="differences-1x-2-service-hostgroup-host"></a> Add Service to Hostgroup where Host is member
|
||||
|
||||
In order to associate a service with all hosts in a host group the `apply`
|
||||
keyword can be used:
|
||||
|
||||
apply Service "ping" {
|
||||
apply Service "ping4" {
|
||||
import "generic-service"
|
||||
|
||||
check_command = "ping4"
|
||||
|
||||
assign where "group" in host.groups
|
||||
assign where "dev-hosts" in host.groups
|
||||
}
|
||||
|
||||
## <a id="differences-1x-2-notifications"></a> Notifications
|
||||
### <a id="differences-1x-2-notifications"></a> Notifications
|
||||
|
||||
Notifications are a new object type in Icinga 2. Imagine the following
|
||||
notification configuration problem in Icinga 1.x:
|
||||
|
|
@ -492,7 +529,7 @@ In Icinga 2 it will look like this:
|
|||
Service -> Notification -> NotificationCommand
|
||||
-> User, UserGroup
|
||||
|
||||
### <a id="differences-1x-2-escalations"></a> Escalations
|
||||
#### <a id="differences-1x-2-escalations"></a> 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
|
||||
|
|
@ -516,9 +553,7 @@ happens.
|
|||
That's not necessary with Icinga 2 only requiring an additional notification
|
||||
object for the escalation itself.
|
||||
|
||||
### <a id="differences-1x-2-notification-options"></a> Notification Options
|
||||
|
||||
TODO
|
||||
#### <a id="differences-1x-2-notification-options"></a> 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.
|
||||
|
|
@ -532,7 +567,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, ...).
|
||||
|
||||
## <a id="differences-1x-2-dependencies-parents"></a> Dependencies and Parents
|
||||
### <a id="differences-1x-2-dependencies-parents"></a> 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.
|
||||
|
|
@ -541,16 +576,16 @@ notifications. A host must not depend on a service, and vice versa. All dependen
|
|||
are configured as separate objects and cannot be set directly on the host or service
|
||||
object.
|
||||
|
||||
Icinga 2 adds host and service dependencies as attribute directly onto the host or
|
||||
service object or template. A service can now depend on a host, and vice versa. A
|
||||
service has an implicit dependeny (parent) to its host. A host to host dependency acts
|
||||
implicit as host parent relation.
|
||||
A service can now depend on a host, and vice versa. A service has an implicit dependeny
|
||||
(parent) to its host. A host to host dependency acts implicit as host parent relation.
|
||||
|
||||
Dependencies can be applied to hosts or services using the [apply rules](#apply).
|
||||
|
||||
The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types
|
||||
support the Icinga 1.x schema with dependencies and parent attributes for
|
||||
compatibility reasons.
|
||||
|
||||
## <a id="differences-1x-2-flapping"></a> Flapping
|
||||
### <a id="differences-1x-2-flapping"></a> 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
|
||||
|
|
@ -564,7 +599,7 @@ The algorithm used in Icinga 2 does not store the past states but calculcates th
|
|||
threshold from a single value based on counters and half-life values. Icinga 2 compares
|
||||
the value with a single flapping threshold configuration attribute.
|
||||
|
||||
## <a id="differences-1x-2-check-result-freshness"></a> Check Result Freshness
|
||||
### <a id="differences-1x-2-check-result-freshness"></a> Check Result Freshness
|
||||
|
||||
Freshness of check results must be explicitely enabled in Icinga 1.x. The attribute
|
||||
`freshness_treshold` defines the threshold in seconds. Once the threshold is triggered, an
|
||||
|
|
@ -577,14 +612,14 @@ 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.
|
||||
|
||||
## <a id="differences-1x-2-state-retention"></a> State Retention
|
||||
### <a id="differences-1x-2-state-retention"></a> 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 objects are stored in is not compatible with Icinga 1.x.
|
||||
|
||||
## <a id="differences-1x-2-logging"></a> Logging
|
||||
### <a id="differences-1x-2-logging"></a> 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
|
||||
|
|
@ -592,11 +627,13 @@ historical reports.
|
|||
|
||||
Icinga 2 compat library provides the CompatLogger object which writes the icinga.log and archive
|
||||
in Icinga 1.x format in order to stay compatible with Classic UI and other addons.
|
||||
|
||||
The native Icinga 2 logging facilities are split into three configuration objects: SyslogLogger,
|
||||
FileLogger, StreamLogger. Each of them got their own severity and target configuration.
|
||||
|
||||
The Icinga 2 daemon log does not log any alerts but is considered an application log only.
|
||||
|
||||
## <a id="differences-1x-2-broker-modules-features"></a> Broker Modules and Features
|
||||
### <a id="differences-1x-2-broker-modules-features"></a> Broker Modules and Features
|
||||
|
||||
Icinga 1.x broker modules are incompatible with Icinga 2.
|
||||
|
||||
|
|
@ -612,7 +649,7 @@ to have one Icinga instance write to multiple IDO databases. Due to the way
|
|||
objects work in Icinga 2 it is possible to set up multiple IDO database instances.
|
||||
|
||||
|
||||
## <a id="differences-1x-2-distributed-monitoring"></a> Distributed Monitoring
|
||||
### <a id="differences-1x-2-distributed-monitoring"></a> Distributed Monitoring
|
||||
|
||||
Icinga 1.x uses the native "obsess over host/service" method which requires the NSCA addon
|
||||
passing the slave's checkresults passively onto the master's external command pipe.
|
||||
|
|
@ -623,5 +660,6 @@ and configuration distribution problems Icinga 1.x distributed monitoring curren
|
|||
|
||||
Icinga 2 implements a new built-in distributed monitoring architecture, including config and check
|
||||
distribution, IPv4/IPv6 support, SSL certificates and domain support for DMZ. High Availability
|
||||
and load balancing are also part of the Icinga 2 [Cluster](#cluster) setup.
|
||||
and load balancing are also part of the Icinga 2 Cluster setup.
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,632 @@
|
|||
# <a id="appendix"></a> Appendix
|
||||
|
||||
## <a id="icinga-template-library"></a> Icinga Template Library
|
||||
|
||||
### <a id="itl-overview"></a> Overview
|
||||
|
||||
The Icinga Template Library (ITL) implements standard templates and object
|
||||
definitions for commonly used services.
|
||||
|
||||
You can include the ITL by using the `include` directive in your configuration
|
||||
file:
|
||||
|
||||
include <itl/itl.conf>
|
||||
|
||||
The ITL assumes that there's a global constant named `PluginDir` which contains
|
||||
the path of the plugins from the Monitoring Plugins project.
|
||||
|
||||
### <a id="itl-check-commands"></a> Check Commands
|
||||
|
||||
#### <a id="itl-ping4"></a> ping4
|
||||
|
||||
Check command object for the `check_ping` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
ping_address | **Optional.** The host's IPv4 address. Defaults to "$address$".
|
||||
ping_wrta | **Optional.** The RTA warning threshold in milliseconds. Defaults to 100.
|
||||
ping_wpl | **Optional.** The packet loss warning threshold in %. Defaults to 5.
|
||||
ping_crta | **Optional.** The RTA critical threshold in milliseconds. Defaults to 200.
|
||||
ping_cpl | **Optional.** The packet loss critical threshold in %. Defaults to 15.
|
||||
ping_packets | **Optional.** The number of packets to send. Defaults to 5.
|
||||
ping_timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
|
||||
|
||||
#### <a id="itl-ping6"></a> ping6
|
||||
|
||||
Check command object for the `check_ping` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
ping_address | **Optional.** The host's IPv6 address. Defaults to "$address6$".
|
||||
ping_wrta | **Optional.** The RTA warning threshold in milliseconds. Defaults to 100.
|
||||
ping_wpl | **Optional.** The packet loss warning threshold in %. Defaults to 5.
|
||||
ping_crta | **Optional.** The RTA critical threshold in milliseconds. Defaults to 200.
|
||||
ping_cpl | **Optional.** The packet loss critical threshold in %. Defaults to 15.
|
||||
ping_packets | **Optional.** The number of packets to send. Defaults to 5.
|
||||
ping_timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
|
||||
|
||||
#### <a id="itl-hostalive"></a> hostalive
|
||||
|
||||
Check command object for the `check_ping` plugin with host check default values.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
ping_address | **Optional.** The host's IPv4 address. Defaults to "$address$".
|
||||
ping_wrta | **Optional.** The RTA warning threshold in milliseconds. Defaults to 3000.
|
||||
ping_wpl | **Optional.** The packet loss warning threshold in %. Defaults to 80.
|
||||
ping_crta | **Optional.** The RTA critical threshold in milliseconds. Defaults to 5000.
|
||||
ping_cpl | **Optional.** The packet loss critical threshold in %. Defaults to 100.
|
||||
ping_packets | **Optional.** The number of packets to send. Defaults to 5.
|
||||
ping_timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
|
||||
|
||||
#### <a id="itl-dummy"></a> dummy
|
||||
|
||||
Check command object for the `check_dummy` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
dummy_state | **Optional.** The state. Can be one of 0 (ok), 1 (warning), 2 (critical) and 3 (unknown). Defaults to 0.
|
||||
dummy_text | **Optional.** Plugin output. Defaults to "Check was successful.".
|
||||
|
||||
#### <a id="itl-passive"></a> passive
|
||||
|
||||
Specialised check command object for passive checks executing the `check_dummy` plugin with appropriate default values.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
dummy_state | **Optional.** The state. Can be one of 0 (ok), 1 (warning), 2 (critical) and 3 (unknown). Defaults to 3.
|
||||
dummy_text | **Optional.** Plugin output. Defaults to "No Passive Check Result Received.".
|
||||
|
||||
#### <a id="itl-tcp"></a> tcp
|
||||
|
||||
Check command object for the `check_tcp` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
tcp_address | **Optional.** The host's address. Defaults to "$address$".
|
||||
tcp_port | **Required.** The port that should be checked.
|
||||
|
||||
#### <a id="itl-udp"></a> udp
|
||||
|
||||
Check command object for the `check_udp` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
udp_address | **Optional.** The host's address. Defaults to "$address$".
|
||||
udp_port | **Required.** The port that should be checked.
|
||||
|
||||
#### <a id="itl-http-ip"></a> http
|
||||
|
||||
Check command object for the `check_http` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
-------------------|--------------
|
||||
http_address | **Optional.** The host's address. Defaults to "$address".
|
||||
http_vhost | **Optional.** The virtual host that should be sent in the "Host" header.
|
||||
http_uri | **Optional.** The request URI.
|
||||
http_port | **Optional.** The TCP port. Defaults to 80 when not using SSL, 443 otherwise.
|
||||
http_ssl | **Optional.** Whether to use SSL. Defaults to false.
|
||||
http_warn_time | **Optional.** The warning threshold.
|
||||
http_critical_time | **Optional.** The critical threshold.
|
||||
|
||||
#### <a id="itl-smtp"></a> smtp
|
||||
|
||||
Check command object for the `check_smtp` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
---------------------|--------------
|
||||
smtp_address | **Optional.** The host's address. Defaults to "$address$".
|
||||
|
||||
#### <a id="itl-ssmtp"></a> ssmtp
|
||||
|
||||
Check command object for the `check_ssmtp` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
ssmtp_address | **Required.** The host's address. Defaults to "$address$".
|
||||
ssmtp_port | **Optional.** The port that should be checked. Defaults to 465.
|
||||
|
||||
#### <a id="itl-ntp-time"></a> ntp_time
|
||||
|
||||
Check command object for the `check_ntp_time` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
ntp_address | **Optional.** The host's address. Defaults to "$address$".
|
||||
|
||||
#### <a id="itl-ssh"></a> ssh
|
||||
|
||||
Check command object for the `check_ssh` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
ssh_address | **Optional.** The host's address. Defaults to "$address$".
|
||||
ssh_port | **Optional.** The port that should be checked. Defaults to 22.
|
||||
|
||||
### <a id="itl-disk"></a> disk
|
||||
|
||||
Check command object for the `check_disk` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
disk_wfree | **Optional.** The free space warning threshold in %. Defaults to 20.
|
||||
disk_cfree | **Optional.** The free space critical threshold in %. Defaults to 10.
|
||||
|
||||
#### <a id="itl-users"></a> users
|
||||
|
||||
Check command object for the `check_disk` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
users_wgreater | **Optional.** The user count warning threshold. Defaults to 20.
|
||||
users_cgreater | **Optional.** The user count critical threshold. Defaults to 50.
|
||||
|
||||
#### <a id="itl-processes"></a> procs
|
||||
|
||||
Check command object for the `check_procs` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
procs_wgreater | **Optional.** The process count warning threshold. Defaults to 250.
|
||||
procs_cgreater | **Optional.** The process count critical threshold. Defaults to 400.
|
||||
|
||||
#### <a id="itl-swap"></a> swap
|
||||
|
||||
Check command object for the `check_swap` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
swap_wfree | **Optional.** The free swap space warning threshold in %. Defaults to 50.
|
||||
swap_cfree | **Optional.** The free swap space critical threshold in %. Defaults to 25.
|
||||
|
||||
#### <a id="itl-load"></a> load
|
||||
|
||||
Check command object for the `check_load` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
load_wload1 | **Optional.** The 1-minute warning threshold. Defaults to 5.
|
||||
load_wload5 | **Optional.** The 5-minute warning threshold. Defaults to 4.
|
||||
load_wload15 | **Optional.** The 15-minute warning threshold. Defaults to 3.
|
||||
load_cload1 | **Optional.** The 1-minute critical threshold. Defaults to 10.
|
||||
load_cload5 | **Optional.** The 5-minute critical threshold. Defaults to 6.
|
||||
load_cload15 | **Optional.** The 15-minute critical threshold. Defaults to 4.
|
||||
|
||||
### <a id="itl-snmp"></a> snmp
|
||||
|
||||
Check command object for the `check_snmp` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
snmp_address | **Optional.** The host's address. Defaults to "$address$".
|
||||
snmp_oid | **Required.** The SNMP OID.
|
||||
snmp_community | **Optional.** The SNMP community. Defaults to "public".
|
||||
|
||||
#### <a id="itl-snmp-uptime"></a> snmp-uptime
|
||||
|
||||
Check command object for the `check_snmp` plugin.
|
||||
|
||||
Custom Attributes:
|
||||
|
||||
Name | Description
|
||||
----------------|--------------
|
||||
snmp_address | **Optional.** The host's address. Defaults to "$address$".
|
||||
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".
|
||||
|
||||
#### <a id="itl-apt"></a> apt
|
||||
|
||||
Check command for the `check_apt` plugin.
|
||||
|
||||
The `apt` check command does not support any vars.
|
||||
|
||||
#### <a id="itl-icinga"></a> 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.
|
||||
|
||||
|
||||
#### <a id="itl-plugin-check-command"></a> plugin-check-command
|
||||
|
||||
Check command template for plugins executed by Icinga 2.
|
||||
|
||||
The `plugin-check-command` check command does not support any vars.
|
||||
|
||||
#### <a id="itl-plugin-notification-command"></a> plugin-check-command
|
||||
|
||||
Check command template for notification scripts executed by Icinga 2.
|
||||
|
||||
The `plugin-notification-command` check command does not support any vars.
|
||||
|
||||
#### <a id="itl-plugin-event-command"></a> plugin-check-command
|
||||
|
||||
Check command template for event handler scripts executed by Icinga 2.
|
||||
|
||||
The `plugin-event-command` check command does not support any vars.
|
||||
|
||||
|
||||
|
||||
## <a id="schemas"></a> Schemas
|
||||
|
||||
### <a id="schema-db-ido"></a> DB IDO
|
||||
|
||||
There is a detailed documentation for the Icinga IDOUtils 1.x
|
||||
database schema available on [http://docs.icinga.org/latest/en/db_model.html]
|
||||
|
||||
#### <a id="schema-db-ido-extensions"></a> DB IDO Schema Extensions
|
||||
|
||||
Icinga 2 specific extensions are shown below:
|
||||
|
||||
New tables: `endpoints`, `endpointstatus`
|
||||
|
||||
Table | Column | Type | Default | Description
|
||||
--------------------|--------------------|----------|---------|-------------
|
||||
endpoints | endpoint_object_id | bigint | NULL | FK: objects table
|
||||
endpoints | identity | TEXT | NULL | endpoint name
|
||||
endpoints | node | TEXT | NULL | local node name
|
||||
|
||||
Table | Column | Type | Default | Description
|
||||
--------------------|--------------------|----------|---------|-------------
|
||||
endpointstatus | endpoint_object_id | bigint | NULL | FK: objects table
|
||||
endpointstatus | identity | TEXT | NULL | endpoint name
|
||||
endpointstatus | node | TEXT | NULL | local node name
|
||||
endpointstatus | is_connected | smallint | 0 | update on endpoint connect/disconnect
|
||||
|
||||
New columns:
|
||||
|
||||
Table | Column | Type | Default | Description
|
||||
--------------------|-------------------------|----------|---------|-------------
|
||||
all status/history | endpoint_object_id | bigint | NULL | FK: objects table
|
||||
servicestatus | check_source | TEXT | NULL | node name where check was executed
|
||||
hoststatus | check_source | TEXT | NULL | node name where check was executed
|
||||
statehistory | check_source | TEXT | NULL | node name where check was executed
|
||||
logentries | object_id | bigint | NULL | FK: objects table (service associated with column)
|
||||
|
||||
Additional command custom variables populated from 'vars' dictionary.
|
||||
Additional global custom variables populated from 'Vars' constant (object_id is NULL).
|
||||
|
||||
|
||||
### <a id="schema-livestatus"></a> Livestatus
|
||||
|
||||
|
||||
#### <a id="schema-livestatus-tables"></a> Livestatus Tables
|
||||
|
||||
Table | Join |Description
|
||||
--------------|-----------|----------------------------
|
||||
hosts | | host config and status attributes, services counter
|
||||
hostgroups | | hostgroup config, status attributes and host/service counters
|
||||
services | hosts | service config and status attributes
|
||||
servicegroups | | servicegroup config, status attributes and service counters
|
||||
contacts | | contact config and status attributes
|
||||
contactgroups | | contact config, members
|
||||
commands | | command name and line
|
||||
status | | programstatus, config and stats
|
||||
comments | services | status attributes
|
||||
downtimes | services | status attributes
|
||||
timeperiods | | name and is inside flag
|
||||
endpoints | | config and status attributes
|
||||
log | services, hosts, contacts, commands | parses [compatlog](#objecttype-compatlogger) and shows log attributes
|
||||
statehist | hosts, services | parses [compatlog](#objecttype-compatlogger) and aggregates state change attributes
|
||||
|
||||
The `commands` table is populated with `CheckCommand`, `EventCommand` and `NotificationCommand` objects.
|
||||
|
||||
|
||||
#### <a id="schema-livestatus-table-attributes"></a> Livestatus Table Attributes
|
||||
|
||||
A detailed list which table attributes are supported can be found here: [https://wiki.icinga.org/display/icinga2/Livestatus#Livestatus-Attributes]
|
||||
|
||||
|
||||
#### <a id="schema-livestatus-get-queries"></a> Livestatus GET Queries
|
||||
|
||||
$ echo -e 'GET services' | netcat 127.0.0.1 6558
|
||||
|
||||
$ cat servicegroups <<EOF
|
||||
GET servicegroups
|
||||
|
||||
EOF
|
||||
|
||||
(cat servicegroups; sleep 1) | netcat 127.0.0.1 6558
|
||||
|
||||
#### <a id="schema-livestatus-command-queries"></a> Livestatus COMMAND Queries
|
||||
|
||||
A list of available external commands and their parameters can be found [here](#external-commands-list-detail)
|
||||
|
||||
$ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558
|
||||
|
||||
|
||||
#### <a id="schema-livestatus-filters"></a> Livestatus Filters
|
||||
|
||||
and, or, negate
|
||||
|
||||
Operator | Negate | Description
|
||||
----------|------------------------
|
||||
= | != | Euqality
|
||||
~ | !~ | Regex match
|
||||
=~ | !=~ | Euqality ignoring case
|
||||
~~ | !~~ | Regex ignoring case
|
||||
> | | Less than
|
||||
< | | Greater than
|
||||
>= | | Less than or equal
|
||||
<= | | Greater than or equal
|
||||
|
||||
|
||||
#### <a id="schema-livestatus-stats"></a> Livestatus Stats
|
||||
|
||||
Schema: "Stats: aggregatefunction aggregateattribute"
|
||||
|
||||
Aggregate Function | Description
|
||||
-------------------|--------------
|
||||
sum |
|
||||
min |
|
||||
max |
|
||||
avg | sum / count
|
||||
std | standard deviation
|
||||
suminv | sum (1 / value)
|
||||
avginv | suminv / count
|
||||
count | ordinary default for any stats query if not aggregate function defined
|
||||
|
||||
Example:
|
||||
|
||||
GET hosts
|
||||
Filter: has_been_checked = 1
|
||||
Filter: check_type = 0
|
||||
Stats: sum execution_time
|
||||
Stats: sum latency
|
||||
Stats: sum percent_state_change
|
||||
Stats: min execution_time
|
||||
Stats: min latency
|
||||
Stats: min percent_state_change
|
||||
Stats: max execution_time
|
||||
Stats: max latency
|
||||
Stats: max percent_state_change
|
||||
OutputFormat: json
|
||||
ResponseHeader: fixed16
|
||||
|
||||
#### <a id="schema-livestatus-output"></a> Livestatus Output
|
||||
|
||||
* CSV
|
||||
|
||||
CSV Output uses two levels of array seperators: The members array separator
|
||||
is a comma (1st level) while extra info and host|service relation separator
|
||||
is a pipe (2nd level).
|
||||
|
||||
Seperators can be set using ASCII codes like:
|
||||
|
||||
Separators: 10 59 44 124
|
||||
|
||||
* JSON
|
||||
|
||||
Default separators.
|
||||
|
||||
#### <a id="schema-livestatus-error-codes"></a> Livestatus Error Codes
|
||||
|
||||
Code | Description
|
||||
----------|--------------
|
||||
200 | OK
|
||||
404 | Table does not exist
|
||||
452 | Exception on query
|
||||
|
||||
#### <a id="schema-livestatus-extensions"></a> Livestatus Schema Extensions
|
||||
|
||||
Icinga 2 specific extensions are shown below:
|
||||
|
||||
New table: `endpoints`
|
||||
|
||||
Table | Column
|
||||
----------|--------------
|
||||
endpoints | name
|
||||
endpoints | identity
|
||||
endpoints | node
|
||||
endpoints | is_connected
|
||||
|
||||
New columns:
|
||||
|
||||
Table | Column
|
||||
----------|--------------
|
||||
services | check_source
|
||||
downtimes | triggers
|
||||
downtimes | trigger_time
|
||||
commands | custom_variable_names
|
||||
commands | custom_variable_values
|
||||
commands | custom_variables
|
||||
commands | modified_attributes
|
||||
commands | modified_attributes_list
|
||||
status | custom_variable_names
|
||||
status | custom_variable_values
|
||||
status | custom_variables
|
||||
|
||||
Command custom variables reflect the local 'vars' dictionary.
|
||||
Status custom variables reflect the global 'Vars' constant.
|
||||
|
||||
|
||||
## <a id="external-commands-list-detail"></a> External Commands List
|
||||
|
||||
Additional details can be found in the [Icinga 1.x Documentation](http://docs.icinga.org/latest/en/extcommands2.html)
|
||||
|
||||
Command name | Parameters | Description
|
||||
------------------------------------------|-----------------------------------|--------------------------
|
||||
PROCESS_HOST_CHECK_RESULT | ;<host_name>;<status_code>;<plugin_output> (3) |
|
||||
PROCESS_SERVICE_CHECK_RESULT | ;<host_name>;<service_name>;<return_code>;<plugin_output> (4) |
|
||||
SCHEDULE_HOST_CHECK | ;<host_name>;<check_time> (2) |
|
||||
SCHEDULE_FORCED_HOST_CHECK | ;<host_name>;<check_time> (2) |
|
||||
SCHEDULE_SVC_CHECK | ;<host_name>;<service_name>;<check_time> (3) |
|
||||
SCHEDULE_FORCED_SVC_CHECK | ;<host_name>;<service_name>;<check_time> (3) |
|
||||
ENABLE_HOST_CHECK | ;<host_name> (1) |
|
||||
DISABLE_HOST_CHECK | ;<host_name> (1) |
|
||||
ENABLE_SVC_CHECK | ;<host_name>;<service_name> (2) |
|
||||
DISABLE_SVC_CHECK | ;<host_name>;<service_name> (2) |
|
||||
SHUTDOWN_PROCESS | (0) |
|
||||
RESTART_PROCESS | (0) |
|
||||
SCHEDULE_FORCED_HOST_SVC_CHECKS | ;<host_name>;<check_time> (2) |
|
||||
SCHEDULE_HOST_SVC_CHECKS | ;<host_name>;<check_time> (2) |
|
||||
ENABLE_HOST_SVC_CHECKS | ;<host_name> (1) |
|
||||
DISABLE_HOST_SVC_CHECKS | ;<host_name> (1) |
|
||||
ACKNOWLEDGE_SVC_PROBLEM | ;<host_name>;<service_name>;<sticky>;<notify>;<persistent>;<author>;<comment> (7) | Note: Icinga 2 treats all comments as persistent.
|
||||
ACKNOWLEDGE_SVC_PROBLEM_EXPIRE | ;<host_name>;<service_name>;<sticky>;<notify>;<persistent>;<timestamp>;<author>;<comment> (8) | Note: Icinga 2 treats all comments as persistent.
|
||||
REMOVE_SVC_ACKNOWLEDGEMENT | ;<host_name>;<service_name> (2) |
|
||||
ACKNOWLEDGE_HOST_PROBLEM | ;<host_name>;<sticky>;<notify>;<persistent>;<author>;<comment> (6) | Note: Icinga 2 treats all comments as persistent.
|
||||
ACKNOWLEDGE_HOST_PROBLEM_EXPIRE | ;<host_name>;<sticky>;<notify>;<persistent>;<timestamp>;<author>;<comment> (7) | Note: Icinga 2 treats all comments as persistent.
|
||||
REMOVE_HOST_ACKNOWLEDGEMENT | ;<host_name> (1) |
|
||||
DISABLE_HOST_FLAP_DETECTION | ;<host_name> (1) |
|
||||
ENABLE_HOST_FLAP_DETECTION | ;<host_name> (1) |
|
||||
DISABLE_SVC_FLAP_DETECTION | ;<host_name>;<service_name> (2) |
|
||||
ENABLE_SVC_FLAP_DETECTION | ;<host_name>;<service_name> (2) |
|
||||
ENABLE_HOSTGROUP_SVC_CHECKS | ;<hostgroup_name> (1) |
|
||||
DISABLE_HOSTGROUP_SVC_CHECKS | ;<hostgroup_name> (1) |
|
||||
ENABLE_SERVICEGROUP_SVC_CHECKS | ;<servicegroup_name> (1) |
|
||||
DISABLE_SERVICEGROUP_SVC_CHECKS | ;<servicegroup_name> (1) |
|
||||
ENABLE_PASSIVE_HOST_CHECKS | ;<host_name> (1) |
|
||||
DISABLE_PASSIVE_HOST_CHECKS | ;<host_name> (1) |
|
||||
ENABLE_PASSIVE_SVC_CHECKS | ;<host_name>;<service_name> (2) |
|
||||
DISABLE_PASSIVE_SVC_CHECKS | ;<host_name>;<service_name> (2) |
|
||||
ENABLE_SERVICEGROUP_PASSIVE_SVC_CHECKS | ;<servicegroup_name> (1) |
|
||||
DISABLE_SERVICEGROUP_PASSIVE_SVC_CHECKS | ;<servicegroup_name> (1) |
|
||||
ENABLE_HOSTGROUP_PASSIVE_SVC_CHECKS | ;<hostgroup_name> (1) |
|
||||
DISABLE_HOSTGROUP_PASSIVE_SVC_CHECKS | ;<hostgroup_name> (1) |
|
||||
PROCESS_FILE | ;<file_name>;<delete> (2) |
|
||||
SCHEDULE_SVC_DOWNTIME | ;<host_name>;<service_name>;<start_time>;<end_time>;<fixed>;<trigger_id>;<duration>;<author>;<comment> (9) |
|
||||
DEL_SVC_DOWNTIME | ;<downtime_id> (1) |
|
||||
SCHEDULE_HOST_DOWNTIME | ;<host_name>;<start_time>;<end_time>;<fixed>;<trigger_id>;<duration>;<author>;<comment> (8) |
|
||||
DEL_HOST_DOWNTIME | ;<downtime_id> (1) |
|
||||
SCHEDULE_HOST_SVC_DOWNTIME | ;<host_name>;<start_time>;<end_time>;<fixed>;<trigger_id>;<duration>;<author>;<comment> (8) |
|
||||
SCHEDULE_HOSTGROUP_HOST_DOWNTIME | ;<hostgroup_name>;<start_time>;<end_time>;<fixed>;<trigger_id>;<duration>;<author>;<comment> (8) |
|
||||
SCHEDULE_HOSTGROUP_SVC_DOWNTIME | ;<hostgroup_name>;<start_time>;<end_time>;<fixed>;<trigger_id>;<duration>;<author>;<comment> (8) |
|
||||
SCHEDULE_SERVICEGROUP_HOST_DOWNTIME | ;<servicegroup_name>;<start_time>;<end_time>;<fixed>;<trigger_id>;<duration>;<author>;<comment> (8) |
|
||||
SCHEDULE_SERVICEGROUP_SVC_DOWNTIME | ;<servicegroup_name>;<start_time>;<end_time>;<fixed>;<trigger_id>;<duration>;<author>;<comment> (8) |
|
||||
ADD_HOST_COMMENT | ;<host_name>;<persistent>;<author>;<comment> (4) | Note: Icinga 2 treats all comments as persistent.
|
||||
DEL_HOST_COMMENT | ;<comment_id> (1) |
|
||||
ADD_SVC_COMMENT | ;<host_name>;<service_name>;<persistent>;<author>;<comment> (5) | Note: Icinga 2 treats all comments as persistent.
|
||||
DEL_SVC_COMMENT | ;<comment_id> (1) |
|
||||
DEL_ALL_HOST_COMMENTS | ;<host_name> (1) |
|
||||
DEL_ALL_SVC_COMMENTS | ;<host_name>;<service_name> (2) |
|
||||
SEND_CUSTOM_HOST_NOTIFICATION | ;<host_name>;<options>;<author>;<comment> (4) |
|
||||
SEND_CUSTOM_SVC_NOTIFICATION | ;<host_name>;<service_name>;<options>;<author>;<comment> (5) |
|
||||
DELAY_HOST_NOTIFICATION | ;<host_name>;<notification_time> (2) |
|
||||
DELAY_SVC_NOTIFICATION | ;<host_name>;<service_name>;<notification_time> (3) |
|
||||
ENABLE_HOST_NOTIFICATIONS | ;<host_name> (1) |
|
||||
DISABLE_HOST_NOTIFICATIONS | ;<host_name> (1) |
|
||||
ENABLE_SVC_NOTIFICATIONS | ;<host_name>;<service_name> (2) |
|
||||
DISABLE_SVC_NOTIFICATIONS | ;<host_name>;<service_name> (2) |
|
||||
DISABLE_HOSTGROUP_HOST_CHECKS | ;<hostgroup_name> (1) |
|
||||
DISABLE_HOSTGROUP_PASSIVE_HOST_CHECKS | ;<hostgroup_name> (1) |
|
||||
DISABLE_SERVICEGROUP_HOST_CHECKS | ;<servicegroup_name> (1) |
|
||||
DISABLE_SERVICEGROUP_PASSIVE_HOST_CHECKS | ;<servicegroup_name> (1) |
|
||||
ENABLE_HOSTGROUP_HOST_CHECKS | ;<hostgroup_name> (1) |
|
||||
ENABLE_HOSTGROUP_PASSIVE_HOST_CHECKS | ;<hostgroup_name> (1) |
|
||||
ENABLE_SERVICEGROUP_HOST_CHECKS | ;<servicegroup_name> (1) |
|
||||
ENABLE_SERVICEGROUP_PASSIVE_HOST_CHECKS | ;<servicegroup_name> (1) |
|
||||
ENABLE_NOTIFICATIONS | (0) |
|
||||
DISABLE_NOTIFICATIONS | (0) |
|
||||
ENABLE_FLAP_DETECTION | (0) |
|
||||
DISABLE_FLAP_DETECTION | (0) |
|
||||
ENABLE_EVENT_HANDLERS | (0) |
|
||||
DISABLE_EVENT_HANDLERS | (0) |
|
||||
ENABLE_PERFORMANCE_DATA | (0) |
|
||||
DISABLE_PERFORMANCE_DATA | (0) |
|
||||
START_EXECUTING_HOST_CHECKS | (0) |
|
||||
STOP_EXECUTING_HOST_CHECKS | (0) |
|
||||
START_EXECUTING_SVC_CHECKS | (0) |
|
||||
STOP_EXECUTING_SVC_CHECKS | (0) |
|
||||
CHANGE_SVC_MODATTR | ;<host_name>;<service_name>;<value> (3) |
|
||||
CHANGE_HOST_MODATTR | ;<host_name>;<value> (2) |
|
||||
CHANGE_USER_MODATTR | ;<user_name>;<value> (2) |
|
||||
CHANGE_CHECKCOMMAND_MODATTR | ;<checkcommand_name>;<value> (2) |
|
||||
CHANGE_EVENTCOMMAND_MODATTR | ;<eventcommand_name>;<value> (2) |
|
||||
CHANGE_NOTIFICATIONCOMMAND_MODATTR | ;<notificationcommand_name>;<value> (2) |
|
||||
CHANGE_NORMAL_SVC_CHECK_INTERVAL | ;<host_name>;<service_name>;<check_interval> (3) |
|
||||
CHANGE_NORMAL_HOST_CHECK_INTERVAL | ;<host_name>;<check_interval> (2) |
|
||||
CHANGE_RETRY_SVC_CHECK_INTERVAL | ;<host_name>;<service_name>;<check_interval> (3) |
|
||||
CHANGE_RETRY_HOST_CHECK_INTERVAL | ;<host_name>;<check_interval> (2) |
|
||||
ENABLE_HOST_EVENT_HANDLER | ;<host_name> (1) |
|
||||
DISABLE_HOST_EVENT_HANDLER | ;<host_name> (1) |
|
||||
ENABLE_SVC_EVENT_HANDLER | ;<host_name>;<service_name> (2) |
|
||||
DISABLE_SVC_EVENT_HANDLER | ;<host_name>;<service_name> (2) |
|
||||
CHANGE_HOST_EVENT_HANDLER | ;<host_name>;<event_command_name> (2) |
|
||||
CHANGE_SVC_EVENT_HANDLER | ;<host_name>;<service_name>;<event_command_name> (3) |
|
||||
CHANGE_HOST_CHECK_COMMAND | ;<host_name>;<check_command_name> (2) |
|
||||
CHANGE_SVC_CHECK_COMMAND | ;<host_name>;<service_name>;<check_command_name> (3) |
|
||||
CHANGE_MAX_HOST_CHECK_ATTEMPTS | ;<host_name>;<check_attempts> (2) |
|
||||
CHANGE_MAX_SVC_CHECK_ATTEMPTS | ;<host_name>;<service_name>;<check_attempts> (3) |
|
||||
CHANGE_HOST_CHECK_TIMEPERIOD | ;<host_name>;<timeperiod_name> (2) |
|
||||
CHANGE_SVC_CHECK_TIMEPERIOD | ;<host_name>;<service_name>;<timeperiod_name> |
|
||||
CHANGE_CUSTOM_HOST_VAR | ;<host_name>;<var_name>;<var_value> (3) |
|
||||
CHANGE_CUSTOM_SVC_VAR | ;<host_name>;<service_name>;<var_name>;<var_value> (4) |
|
||||
CHANGE_CUSTOM_USER_VAR | ;<user_name>;<var_name>;<var_value> (3) |
|
||||
CHANGE_CUSTOM_CHECKCOMMAND_VAR | ;<check_command_name>;<var_name>;<var_value> (3) |
|
||||
CHANGE_CUSTOM_EVENTCOMMAND_VAR | ;<event_command_name>;<var_name>;<var_value> (3) |
|
||||
CHANGE_CUSTOM_NOTIFICATIONCOMMAND_VAR | ;<notification_command_name>;<var_name>;<var_value> (3) |
|
||||
ENABLE_HOSTGROUP_HOST_NOTIFICATIONS | ;<hostgroup_name> (1) |
|
||||
ENABLE_HOSTGROUP_SVC_NOTIFICATIONS | ;<hostgroup_name> (1) |
|
||||
DISABLE_HOSTGROUP_HOST_NOTIFICATIONS | ;<hostgroup_name> (1) |
|
||||
DISABLE_HOSTGROUP_SVC_NOTIFICATIONS | ;<hostgroup_name> (1) |
|
||||
ENABLE_SERVICEGROUP_HOST_NOTIFICATIONS | ;<servicegroup_name> (1) |
|
||||
DISABLE_SERVICEGROUP_HOST_NOTIFICATIONS | ;<servicegroup_name> (1) |
|
||||
ENABLE_SERVICEGROUP_SVC_NOTIFICATIONS | ;<servicegroup_name> (1) |
|
||||
DISABLE_SERVICEGROUP_SVC_NOTIFICATIONS | ;<servicegroup_name> (1) |
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,46 +0,0 @@
|
|||
# <a id="vagrant"></a> Vagrant Demo VM
|
||||
|
||||
The Icinga 2 Git repository contains support for [Vagrant](http://docs.vagrantup.com/v2/)
|
||||
with VirtualBox. Please note that Vagrant version `1.0.x` is not supported. At least
|
||||
version `1.2.x` is required.
|
||||
|
||||
In order to build the Vagrant VM first you will have to check out
|
||||
the Git repository:
|
||||
|
||||
$ git clone git://git.icinga.org/icinga2.git
|
||||
|
||||
Once you have checked out the Git repository you can build the VM using the
|
||||
following command:
|
||||
|
||||
$ vagrant up
|
||||
|
||||
The Vagrant VM is based on CentOS 6.4 and uses the official Icinga 2 RPM
|
||||
packages from `packages.icinga.org`. The check plugins are installed from
|
||||
EPEL providing RPMs with sources from the Monitoring Plugins project.
|
||||
|
||||
## <a id="vagrant-demo-guis"></a> Demo GUIs
|
||||
|
||||
In addition to installing Icinga 2 the Vagrant puppet modules also install the
|
||||
Icinga 1.x Classic UI and Icinga Web.
|
||||
|
||||
GUI | Url | Credentials
|
||||
----------------|----------------------------------------------------------------------|------------------------
|
||||
Classic UI | [http://localhost:8080/icinga](http://localhost:8080/icinga) | icingaadmin / icingaadmin
|
||||
Icinga Web | [http://localhost:8080/icinga-web](http://localhost:8080/icinga-web) | root / password
|
||||
|
||||
|
||||
## <a id="vagrant-windows"></a> SSH Access
|
||||
|
||||
You can access the Vagrant VM using SSH:
|
||||
|
||||
$ vagrant ssh
|
||||
|
||||
Alternatively you can use your favorite SSH client:
|
||||
|
||||
Name | Value
|
||||
----------------|----------------
|
||||
Host | 127.0.0.1
|
||||
Port | 2222
|
||||
Username | vagrant
|
||||
Password | vagrant
|
||||
|
||||
Loading…
Reference in New Issue