From 10c3c52ed3ce6125a1c47ff6dc32d41cac6760fa Mon Sep 17 00:00:00 2001 From: Michael Friedrich Date: Sun, 4 May 2014 11:25:12 +0200 Subject: [PATCH] Documentation: Apply new structure. Fixes #6115 --- doc/2-getting-started.md | 826 ++++++++++ doc/2.0-getting-started.md | 5 - doc/2.1-setting-up-icinga-2.md | 206 --- doc/2.2-setting-up-check-plugins.md | 67 - doc/2.3-setting-up-ido.md | 200 --- doc/2.4-setting-up-livestatus.md | 46 - doc/2.5-setting-up-icinga2-uis.md | 116 -- doc/2.6-config-tools.md | 11 - doc/2.7-running-icinga-2.md | 115 -- ...ect-types.md => 3-configuring-icinga-2.md} | 568 ++++++- doc/3-monitoring-basics.md | 4 - doc/3.01-hosts-and-services.md | 74 - doc/3.02-commands.md | 173 --- doc/3.03-custom-attributes-runtime-macros.md | 228 --- doc/3.04-notifications.md | 229 --- doc/3.05-using-templates.md | 32 - doc/3.06-groups.md | 55 - doc/3.07-time-periods.md | 77 - doc/3.08-external-commands.md | 40 - doc/3.09-event-handlers.md | 14 - doc/3.10-logging.md | 20 - doc/3.11-performance-data.md | 54 - doc/3.12-status-data.md | 15 - doc/3.13-compat-logging.md | 46 - doc/3.14-check-result-files.md | 18 - doc/3.15-monitoring-remote-clients.md | 182 --- doc/4-configuring-icinga-2.md | 1 - doc/4-monitoring-basics.md | 1326 +++++++++++++++++ doc/4.1-configuration-syntax.md | 564 ------- doc/4.2-global-variables.md | 22 - doc/5-icinga-template-library.md | 263 ---- ...er.md => 5-monitoring-remote-instances.md} | 223 ++- ...6.11-plugin-api.md => 6-addons-plugins.md} | 2 + doc/6-advanced-topics.md | 1 - doc/6.01-downtimes.md | 85 -- doc/6.02-comments.md | 10 - doc/6.03-acknowledgements.md | 23 - doc/6.05-domains.md | 36 - doc/6.06-dependencies.md | 43 - doc/6.07-check-result-freshness.md | 13 - doc/6.08-check-flapping.md | 8 - doc/6.09-volatile-services.md | 12 - doc/6.10-modified-attributes.md | 8 - doc/6.12-schemas.md | 191 --- doc/6.13-external-commands-list,md | 151 -- doc/7-migrating-from-icinga-1x.md | 32 - ...ween-icinga-1x-and-2.md => 7-migration.md} | 144 +- doc/8-appendix.md | 632 ++++++++ doc/9-vagrant-demo-vm.md | 46 - 49 files changed, 3660 insertions(+), 3597 deletions(-) create mode 100644 doc/2-getting-started.md delete mode 100644 doc/2.0-getting-started.md delete mode 100644 doc/2.1-setting-up-icinga-2.md delete mode 100644 doc/2.2-setting-up-check-plugins.md delete mode 100644 doc/2.3-setting-up-ido.md delete mode 100644 doc/2.4-setting-up-livestatus.md delete mode 100644 doc/2.5-setting-up-icinga2-uis.md delete mode 100644 doc/2.6-config-tools.md delete mode 100644 doc/2.7-running-icinga-2.md rename doc/{4.3-object-types.md => 3-configuring-icinga-2.md} (67%) delete mode 100644 doc/3-monitoring-basics.md delete mode 100644 doc/3.01-hosts-and-services.md delete mode 100644 doc/3.02-commands.md delete mode 100644 doc/3.03-custom-attributes-runtime-macros.md delete mode 100644 doc/3.04-notifications.md delete mode 100644 doc/3.05-using-templates.md delete mode 100644 doc/3.06-groups.md delete mode 100644 doc/3.07-time-periods.md delete mode 100644 doc/3.08-external-commands.md delete mode 100644 doc/3.09-event-handlers.md delete mode 100644 doc/3.10-logging.md delete mode 100644 doc/3.11-performance-data.md delete mode 100644 doc/3.12-status-data.md delete mode 100644 doc/3.13-compat-logging.md delete mode 100644 doc/3.14-check-result-files.md delete mode 100644 doc/3.15-monitoring-remote-clients.md delete mode 100644 doc/4-configuring-icinga-2.md create mode 100644 doc/4-monitoring-basics.md delete mode 100644 doc/4.1-configuration-syntax.md delete mode 100644 doc/4.2-global-variables.md delete mode 100644 doc/5-icinga-template-library.md rename doc/{6.04-cluster.md => 5-monitoring-remote-instances.md} (69%) rename doc/{6.11-plugin-api.md => 6-addons-plugins.md} (83%) delete mode 100644 doc/6-advanced-topics.md delete mode 100644 doc/6.01-downtimes.md delete mode 100644 doc/6.02-comments.md delete mode 100644 doc/6.03-acknowledgements.md delete mode 100644 doc/6.05-domains.md delete mode 100644 doc/6.06-dependencies.md delete mode 100644 doc/6.07-check-result-freshness.md delete mode 100644 doc/6.08-check-flapping.md delete mode 100644 doc/6.09-volatile-services.md delete mode 100644 doc/6.10-modified-attributes.md delete mode 100644 doc/6.12-schemas.md delete mode 100644 doc/6.13-external-commands-list,md delete mode 100644 doc/7-migrating-from-icinga-1x.md rename doc/{8-differences-between-icinga-1x-and-2.md => 7-migration.md} (82%) create mode 100644 doc/8-appendix.md delete mode 100644 doc/9-vagrant-demo-vm.md diff --git a/doc/2-getting-started.md b/doc/2-getting-started.md new file mode 100644 index 000000000..f7aabb6f4 --- /dev/null +++ b/doc/2-getting-started.md @@ -0,0 +1,826 @@ +# 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. + +## 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. + + +### 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. + +### 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 + + /** + * 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. + +### 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" + +### 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. + + +## 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. + +### 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. + + +## 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. + +### Configuring IDO MySQL + +#### 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`. + +#### 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. + +#### 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 + + +### 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`. + +#### 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. + +#### 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 + + +## 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 + + +## 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. + +### 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. + +#### 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 + +### 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. + +#### 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 + + + + /var/run/icinga2/cmd/icinga.cmd + + + + # 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 + + +### 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. + + +### 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). + + +## 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). + + +## Running Icinga 2 + +### 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. + +### 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 + Icinga home page: + +#### 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 + +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. + +### 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 + 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. + + +## 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. + +## 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 + + +## 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 \ No newline at end of file diff --git a/doc/2.0-getting-started.md b/doc/2.0-getting-started.md deleted file mode 100644 index 6e4d17535..000000000 --- a/doc/2.0-getting-started.md +++ /dev/null @@ -1,5 +0,0 @@ -# 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. diff --git a/doc/2.1-setting-up-icinga-2.md b/doc/2.1-setting-up-icinga-2.md deleted file mode 100644 index 0922c429b..000000000 --- a/doc/2.1-setting-up-icinga-2.md +++ /dev/null @@ -1,206 +0,0 @@ -## 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. - -### 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. - -### 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 - - /** - * 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. - -### 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" - -### 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. diff --git a/doc/2.2-setting-up-check-plugins.md b/doc/2.2-setting-up-check-plugins.md deleted file mode 100644 index 492d254c7..000000000 --- a/doc/2.2-setting-up-check-plugins.md +++ /dev/null @@ -1,67 +0,0 @@ -## 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. - -### 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. diff --git a/doc/2.3-setting-up-ido.md b/doc/2.3-setting-up-ido.md deleted file mode 100644 index 751cc3eb1..000000000 --- a/doc/2.3-setting-up-ido.md +++ /dev/null @@ -1,200 +0,0 @@ -## 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. - -### Configuring IDO MySQL - -#### 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`. - -#### 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. - -#### 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 - - -### 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`. - -#### 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. - -#### 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 diff --git a/doc/2.4-setting-up-livestatus.md b/doc/2.4-setting-up-livestatus.md deleted file mode 100644 index 0f754d2ee..000000000 --- a/doc/2.4-setting-up-livestatus.md +++ /dev/null @@ -1,46 +0,0 @@ -## 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 diff --git a/doc/2.5-setting-up-icinga2-uis.md b/doc/2.5-setting-up-icinga2-uis.md deleted file mode 100644 index 27b9ecc86..000000000 --- a/doc/2.5-setting-up-icinga2-uis.md +++ /dev/null @@ -1,116 +0,0 @@ -## 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. - -### 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. - -#### 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 - -### 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. - -#### 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 - - - - /var/run/icinga2/cmd/icinga.cmd - - - - # 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 - -### 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. - -### 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). diff --git a/doc/2.6-config-tools.md b/doc/2.6-config-tools.md deleted file mode 100644 index 5d7f1d3b2..000000000 --- a/doc/2.6-config-tools.md +++ /dev/null @@ -1,11 +0,0 @@ -## 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). diff --git a/doc/2.7-running-icinga-2.md b/doc/2.7-running-icinga-2.md deleted file mode 100644 index 5432b1f31..000000000 --- a/doc/2.7-running-icinga-2.md +++ /dev/null @@ -1,115 +0,0 @@ -## Running Icinga 2 - -### 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. - -### 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 - Icinga home page: - -#### 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 - -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. - -### 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 - 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. - diff --git a/doc/4.3-object-types.md b/doc/3-configuring-icinga-2.md similarity index 67% rename from doc/4.3-object-types.md rename to doc/3-configuring-icinga-2.md index a418075e0..69a9f5ea8 100644 --- a/doc/4.3-object-types.md +++ b/doc/3-configuring-icinga-2.md @@ -1,3 +1,537 @@ +# Configuring Icinga 2 + + +## Configuration Syntax + +### 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. + +#### Numeric Literals + +A floating-point number. + +Example: + + -27.3 + +#### 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. + +#### 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. + +#### 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. + +#### Boolean Literals + +The keywords `true` and `false` are equivalent to 1 and 0 respectively. + +#### Null Value + +The `null` keyword can be used to specify an empty value. + +#### 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. + +#### 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. + +#### Operators + +The following operators are supported in expressions: + +Operator | Examples (Result) | Description +---------|-----------------------------------------------|-------------------------------- +! | !"Hello" (false), !false (true) | Logical 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. + +### 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: + +#### 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. + +#### Operator += + +The += operator is a shortcut. The following expression: + + { + a = [ "hello" ] + a += [ "world" ] + } + +is equivalent to: + + { + a = [ "hello" ] + a = a + [ "world" ] + } + +#### Operator -= + +The -= operator is a shortcut. The following expression: + + { + a = 10 + a -= 5 + } + +is equivalent to: + + { + a = 10 + a = a - 5 + } + +#### Operator \*= + +The *= operator is a shortcut. The following expression: + + { + a = 60 + a *= 5 + } + +is equivalent to: + + { + a = 60 + a = a * 5 + } + +#### Operator /= + +The /= operator is a shortcut. The following expression: + + { + a = 300 + a /= 5 + } + +is equivalent to: + + { + a = 300 + a = a / 5 + } + +### 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" + } + } + +### 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. + +### 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. + +### 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. + +### 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 + + +### 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 + +### 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 + } + +### 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 + +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. + +### 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. + +### 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" + + + +## 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. + + ## Object Types ### 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: ### 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 diff --git a/doc/3-monitoring-basics.md b/doc/3-monitoring-basics.md deleted file mode 100644 index e20ac16b4..000000000 --- a/doc/3-monitoring-basics.md +++ /dev/null @@ -1,4 +0,0 @@ -# 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. diff --git a/doc/3.01-hosts-and-services.md b/doc/3.01-hosts-and-services.md deleted file mode 100644 index 8766cf0d2..000000000 --- a/doc/3.01-hosts-and-services.md +++ /dev/null @@ -1,74 +0,0 @@ -## 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. - -### Host States - -Hosts can be in any of the following states: - - Name | Description - ------------|-------------- - UP | The host is available. - DOWN | The host is unavailable. - -### 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. - -### 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. diff --git a/doc/3.02-commands.md b/doc/3.02-commands.md deleted file mode 100644 index 00866508f..000000000 --- a/doc/3.02-commands.md +++ /dev/null @@ -1,173 +0,0 @@ -## 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. - -### Environment Variables for Commands - -Please check [Runtime Custom Attributes as Environment Variables](#runtime-custom-attribute-env-vars). - -### 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 - } - - -### 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 <