diff --git a/doc/1-about.md b/doc/1-about.md index 9a5f33f1d..6ec2abac0 100644 --- a/doc/1-about.md +++ b/doc/1-about.md @@ -1,25 +1,26 @@ -# About Icinga 2 +# About Icinga 2 -## What is Icinga 2? +## What is Icinga 2? Icinga 2 is an enterprise-grade open source monitoring system which keeps watch over networks and any conceivable network resource, notifies the user of errors and recoveries and generates performance data for reporting. Scalable and extensible, Icinga 2 can monitor complex, large environments across dispersed locations. -## Licensing +## Licensing Icinga 2 and the Icinga 2 documentation are licensed under the terms of the GNU General Public License Version 2, you will find a copy of this license in the LICENSE file included in the package. -## Support +## Support Support for Icinga 2 is available in a number of ways. Please have a look at the support overview page at [https://support.icinga.org]. +## What's new -## What's New in Version 0.0.6 +### What's New in Version 0.0.6 * Scheduled Downtimes as configuration object (also known as "Recurring Downtimes"). * Log command arguments @@ -32,7 +33,7 @@ the support overview page at [https://support.icinga.org]. * Improve performance with fetching data for status.dat/objects.cache, DB IDO and Livestatus * Livestatus History Table performance improvements -### Changes +#### Changes * Generated object names (host with services array) use an exclamation mark instead of a colon as seperator. State file objects with downtimes, comments, etc are invalid (unknown) for that reason. @@ -40,7 +41,7 @@ reason. * ITL constants are now embedded in libicinga * Removed the ConsoleLogger object and keep the default console log enabled until we daemonize -## What's New in Version 0.0.5 +### What's New in Version 0.0.5 * Cluster: Implement support for CRLs * Implement modified attributes @@ -54,7 +55,7 @@ reason. * Lots of bugfixes and performance improvements * Package fixes (Note: GPG key of packages.icinga.org has been updated) -## What's New in Version 0.0.4 +### What's New in Version 0.0.4 * IDO: PostgreSQL support * IDO: implemented options to filter which kind of events are written to the database @@ -63,7 +64,7 @@ reason. * Replaced autotools-based build system with cmake * Lots of bug fixes and performance improvements -## What's New in Version 0.0.3 +### What's New in Version 0.0.3 * `StatusDataWriter` and `ExternalCommandListener` (former `Compat`) and `CompatLogger` (former CompatLog) for status.dat/objects.cache/icinga2.cmd/icinga.log for Icinga 1.x Classic UI support diff --git a/doc/2.0-getting-started.md b/doc/2.0-getting-started.md index e23d91a05..6e4d17535 100644 --- a/doc/2.0-getting-started.md +++ b/doc/2.0-getting-started.md @@ -1,5 +1,5 @@ -# Getting Started +# Getting Started This tutorial is a step-by-step introduction to installing Icinga 2 and -the standalone version of the Icinga 1.x classic web interface. It assumes -that you are familiar with the system you're installing Icinga 2 on. +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 index 4fa3390d1..e4436af3e 100644 --- a/doc/2.1-setting-up-icinga-2.md +++ b/doc/2.1-setting-up-icinga-2.md @@ -1,4 +1,4 @@ -## Setting up Icinga 2 +## 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 @@ -44,7 +44,7 @@ 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 +### Installation Paths By default Icinga 2 uses the following files and directories: @@ -62,7 +62,7 @@ By default Icinga 2 uses the following files and directories: /var/lib/icinga2 | The Icinga 2 state file. /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature. -### icinga2.conf +### icinga2.conf An example configuration file is installed for you in `/etc/icinga2/icinga2.conf`. @@ -107,7 +107,7 @@ the features which have been enabled with `icinga2-enable-feature`. See 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. -### macros.conf +### macros.conf The `conf.d/macros.conf` file can be used to define global macros: @@ -121,7 +121,7 @@ The `conf.d/macros.conf` file can be used to define global macros: Icinga 2 lets you define free-form macros. The IcingaMacros variable can be used to define global macros which are available in all command definitions. -### localhost.conf +### localhost.conf The `conf.d/localhost.conf` file contains our first host definition: diff --git a/doc/2.2-setting-up-check-plugins.md b/doc/2.2-setting-up-check-plugins.md index 4e453ed73..e969cb735 100644 --- a/doc/2.2-setting-up-check-plugins.md +++ b/doc/2.2-setting-up-check-plugins.md @@ -1,4 +1,4 @@ -## Setting up Check Plugins +## 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/) (former @@ -28,7 +28,7 @@ update the `plugindir` macro 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 Additonal Plugins +### Integrate Additonal Plugins You may require a custom check plugin not provided by the official Nagios plugins. All existing Nagios or Icinga 1.x plugins found on public community websites diff --git a/doc/2.3-setting-up-ido.md b/doc/2.3-setting-up-ido.md index 2b0e4ad00..467cb1712 100644 --- a/doc/2.3-setting-up-ido.md +++ b/doc/2.3-setting-up-ido.md @@ -1,4 +1,4 @@ -## Configuring IDO +## Configuring IDO The IDO (Icinga Data Output) modules for Icinga 2 takes care of exporting all configuration and status information into a database. The IDO database is used @@ -10,11 +10,13 @@ both MySQL and PostgreSQL is implemented. > **Note** > > Icinga 2 uses the Icinga 1.x IDOUtils database schema starting with version -> `1.11.0`. +> `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. -### Configuring IDO MySQL +### Configuring IDO MySQL -#### Setting up the MySQL database +#### 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 @@ -49,7 +51,7 @@ following command: > On SuSE-based distributions the schema files are installed in > `/usr/share/doc/packages/icinga2-ido-mysql/schema`. -#### Upgrading the MySQL database +#### Upgrading the MySQL database If the database has been installed and requires an upgrade, verify the current schema version first: @@ -73,7 +75,7 @@ Apply all database schema upgrade files incrementially. > 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 +#### 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 @@ -90,7 +92,7 @@ After enabling the ido-mysql feature you have to restart Icinga 2: # /etc/init.d/icinga2 restart -### Configuring IDO PostgreSQL +### Configuring IDO PostgreSQL #### Setting up the PostgreSQL database @@ -146,7 +148,7 @@ using the following command: > `/usr/share/doc/packages/icinga2-ido-pgsql/schema`. -#### Upgrading the PostgreSQL database +#### Upgrading the PostgreSQL database If the database has been installed and requires an upgrade, verify the current schema version first: @@ -171,7 +173,7 @@ Apply all database schema upgrade files incrementially. > on startup and generate an error message if not satisfied. -#### Installing the IDO PostgreSQL module +#### 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 diff --git a/doc/2.4-setting-up-livestatus.md b/doc/2.4-setting-up-livestatus.md index 0cdff2dcc..11ada6cf3 100644 --- a/doc/2.4-setting-up-livestatus.md +++ b/doc/2.4-setting-up-livestatus.md @@ -1,4 +1,4 @@ -## Setting up Livestatus +## 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 diff --git a/doc/2.5-setting-up-icinga2-uis.md b/doc/2.5-setting-up-icinga2-uis.md index 2ab00c4ec..3132bb9fe 100644 --- a/doc/2.5-setting-up-icinga2-uis.md +++ b/doc/2.5-setting-up-icinga2-uis.md @@ -1,6 +1,4 @@ - - -## Setting up Icinga 2 User Interfaces +## Setting up Icinga 2 User Interfaces Icinga 2 is compatible to Icinga 1.x user interfaces by providing additional features required as backends. @@ -9,14 +7,20 @@ 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. -### Setting up Icinga Classic UI +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 through intelligent compatibility layers +for dumping the host dependencies as parents. +Special restrictions are noted specifically in the sections below. + +### 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 +#### Installing Icinga Classic UI The Icinga package repository has both Debian and RPM packages. You can install the Classic UI using the following packages: @@ -39,14 +43,21 @@ UI installation URL: Debian | [http://localhost/icinga2-classicui](http://localhost/icinga2-classicui) | asked during installation all others | [http://localhost/icinga](http://localhost/icinga) | icingaadmin/icingaadmin +> **Note** +> +> Due to compatibility restrictions, not all features available in Icinga 1.x +> Classic UI will be available with Icinga 2. The different handling of +> [commands](#differences-1x-2-commands) and [macros](#differences-1x-2-macros) +> renders the command expander invalid for example. -### Setting up Icinga Web + +### 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 +#### Installing Icinga Web The Icinga package repository has both Debian and RPM packages. You can install the Classic UI using the following packages: @@ -95,7 +106,7 @@ Verify that your Icinga 1.x Web works by browsing to your Web installation URL: -### Setting up Icinga Web 2 +### 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 @@ -107,7 +118,7 @@ further instructions. > yourself you should consider testing it using the available Vagrant > demo boxes. -### Additional visualization +### Additional visualization There are many addons in the wild which are using Icinga 1.x backends and are well integrated into user interfaces. diff --git a/doc/2.6-running-icinga.md b/doc/2.6-running-icinga-2.md similarity index 98% rename from doc/2.6-running-icinga.md rename to doc/2.6-running-icinga-2.md index 697babb56..bcbbdfa1c 100644 --- a/doc/2.6-running-icinga.md +++ b/doc/2.6-running-icinga-2.md @@ -1,6 +1,6 @@ -## Running Icinga +## Running Icinga 2 -### Init Script +### Init Script Icinga 2's init script is installed in `/etc/init.d/icinga2` by default: diff --git a/doc/3-monitoring-basics.md b/doc/3-monitoring-basics.md index c4d851fef..e20ac16b4 100644 --- a/doc/3-monitoring-basics.md +++ b/doc/3-monitoring-basics.md @@ -1,4 +1,4 @@ -# Monitoring Basics +# Monitoring Basics This part of the Icinga 2 documentation provides an overview of all the basic monitoring concepts you need to know to run Icinga 2. diff --git a/doc/3.01-hosts-and-services.md b/doc/3.01-hosts-and-services.md index 7e7754081..c1950d630 100644 --- a/doc/3.01-hosts-and-services.md +++ b/doc/3.01-hosts-and-services.md @@ -1,4 +1,4 @@ -## Hosts and Services +## 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: @@ -44,7 +44,7 @@ It also specifies that the host should inherit its availability state from the The `address` macro is used by check commands to determine which network address is associated with the host object. -### Host States +### Host States Hosts inherit their state from the host check service that is specified using the `check` attribute. @@ -57,7 +57,7 @@ Hosts can be in any of the following states: DOWN | The host is unavailable. UNREACHABLE | At least one of the host's dependencies (e.g. its upstream router) is unavailable causing the host to be unreachable. -### Service States +### Service States Services can be in any of the following states: @@ -68,7 +68,7 @@ Services can be in any of the following states: CRITICAL | The service is in a critical state. UNKNOWN | The check could not determine the service's state. -### Hard and Soft States +### Hard and Soft States When detecting a problem with a service Icinga re-checks the service a number of times (based on the `max_check_attempts` and `retry_interval` settings) before sending diff --git a/doc/3.02-commands.md b/doc/3.02-commands.md index d90e35e4b..d0edad39f 100644 --- a/doc/3.02-commands.md +++ b/doc/3.02-commands.md @@ -1,4 +1,4 @@ -## Commands +## Commands Icinga 2 uses three different command object types to specify how checks should be performed, notifications should be sent and @@ -12,7 +12,7 @@ events should be handled. > Put your plugins and scripts into the directory defined by the `$plugindir$` macro > and make sure they are executable by the Icinga 2 user. -### Environment Macros +### Environment Macros If your plugins require environment macros instead of command arguments you have to define all macros in the `export_macros` attribute as list. @@ -28,7 +28,7 @@ to define all macros in the `export_macros` attribute as list. > Use templates to define global `export_macros` attributes for the three > command types and let each command object inherit the attribute. -### Check Commands +### Check Commands `CheckCommand` objects define the command line how a check is called. @@ -95,7 +95,7 @@ space). } -### Notification Commands +### Notification Commands `NotificationCommand` objects define how notifications are delivered to external interfaces (E-Mail, XMPP, IRC, Twitter, etc). @@ -163,7 +163,7 @@ as environment variables and can be used in the notification script: > shell script in the `/etc/icinga2/scripts` directory and have the > NotificationCommand object refer to that. -### Event Commands +### Event Commands Unlike notifications event commands are called on every service state change if defined. Therefore the `EventCommand` object should define a command line diff --git a/doc/3.04-notifications.md b/doc/3.04-notifications.md index 0a453d983..01f81d730 100644 --- a/doc/3.04-notifications.md +++ b/doc/3.04-notifications.md @@ -1,4 +1,4 @@ -## Notifications +## Notifications Notifications on alerts are an integral part of your Icinga 2 monitoring application. There are many ways of getting a notification to the actual receiver - Email, XMPP, @@ -130,7 +130,7 @@ Notifications can be defined in `Service` templates inherited to the objects. > attribute with a list of user groups to the `Notification` object. Icinga 2 will > resolve all group members and send notifications to all of them. -### Notification Escalations +### 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 @@ -233,7 +233,7 @@ notified, but only for one hour (`2h` as `end` key for the `times` dictionary). > resolve all group members and send notifications and notification escalations to > all of them. -### First Notification Delay +### 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` @@ -259,7 +259,7 @@ end time for this notification. > > In Icinga 1.x the attribute is called `first_notification_delay`. -### Notification Filters by State and Type +### Notification Filters by State and Type If there are no notification state and type filter attributes defined at the `Notification` or `User` object Icinga 2 assumes that all states and types are being notified. diff --git a/doc/3.05-using-templates.md b/doc/3.05-using-templates.md index 0ba9bbed4..0cb0a403a 100644 --- a/doc/3.05-using-templates.md +++ b/doc/3.05-using-templates.md @@ -1,4 +1,4 @@ -## Using Templates +## Using Templates Templates may be used to apply a set of similar settings to more than one object. diff --git a/doc/3.06-groups.md b/doc/3.06-groups.md index 89634728b..4e53e3389 100644 --- a/doc/3.06-groups.md +++ b/doc/3.06-groups.md @@ -1,4 +1,4 @@ -## Groups +## Groups Groups are used for combining hosts, services and users into accessible configuration attributes and views in external (web) diff --git a/doc/3.07-time-periods.md b/doc/3.07-time-periods.md index afcef40ae..2ba56d154 100644 --- a/doc/3.07-time-periods.md +++ b/doc/3.07-time-periods.md @@ -1,4 +1,4 @@ -## Time Periods +## Time Periods Time Periods define time ranges in Icinga where event actions are triggered, for example if a service check is executed or not within diff --git a/doc/3.08-external-commands.md b/doc/3.08-external-commands.md index 6f560290f..d25fb4a06 100644 --- a/doc/3.08-external-commands.md +++ b/doc/3.08-external-commands.md @@ -1,4 +1,4 @@ -## External Commands +## External Commands Icinga 2 provides an external command pipe for processing commands triggering specific actions (for example rescheduling a service check @@ -31,9 +31,7 @@ a forced service check: # usermod -G -a icingacmd www-data - - -### External Command List +### External Command List A list of currently supported external commands can be found on the [Icinga Wiki](https://wiki.icinga.org/display/icinga2/External+Commands). diff --git a/doc/3.09-event-handlers.md b/doc/3.09-event-handlers.md index 9d92eb923..3a7dbcce2 100644 --- a/doc/3.09-event-handlers.md +++ b/doc/3.09-event-handlers.md @@ -1,4 +1,4 @@ -## Event Handlers +## Event Handlers Event handlers are defined as `EventCommand` objects in Icinga 2. diff --git a/doc/3.10-logging.md b/doc/3.10-logging.md index 051f671ea..37bb826a3 100644 --- a/doc/3.10-logging.md +++ b/doc/3.10-logging.md @@ -1,4 +1,4 @@ -## Logging +## Logging Icinga 2 supports three different types of logging: diff --git a/doc/3.11-performance-data.md b/doc/3.11-performance-data.md index ab0d1eff4..7fb58a951 100644 --- a/doc/3.11-performance-data.md +++ b/doc/3.11-performance-data.md @@ -1,4 +1,4 @@ -## Performance Data +## Performance Data When a service check is executed plugins should provide so-called `performance data`. Next to that additional check performance data @@ -16,7 +16,7 @@ inGraph and Graphite. > As there are no real host checks in Icinga 2, there is no performance > data generated for hosts. -### Writing Performance Data Files +### Writing Performance Data Files PNP4Nagios and inGraph use performance data collector daemons to fetch the current performance files for their backend updates. @@ -44,7 +44,7 @@ remove the processed files. > and critical thresholds. -### Graphite Carbon Cache Writer +### Graphite Carbon Cache Writer While there are some Graphite collector scripts for Icinga 1.x available it's more reasonable to directly process the check and plugin performance in memory diff --git a/doc/3.12-status-data.md b/doc/3.12-status-data.md index 3b93c2ea4..5942b765a 100644 --- a/doc/3.12-status-data.md +++ b/doc/3.12-status-data.md @@ -1,4 +1,4 @@ -## Status Data +## 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 diff --git a/doc/3.13-compat-logging.md b/doc/3.13-compat-logging.md index 0b18ed31c..a0da1ad82 100644 --- a/doc/3.13-compat-logging.md +++ b/doc/3.13-compat-logging.md @@ -1,11 +1,13 @@ -## Compat Logging +## 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 informal representation in external web interfaces parsing the logs, but also to generate -sla reports and trends in Icinga 1.x Classic UI. +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 diff --git a/doc/3.14-check-result-files.md b/doc/3.14-check-result-files.md index f09d76864..4226c3768 100644 --- a/doc/3.14-check-result-files.md +++ b/doc/3.14-check-result-files.md @@ -1,4 +1,4 @@ -## Check Result Files +## 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. diff --git a/doc/4-configuring-icinga.md b/doc/4-configuring-icinga-2.md similarity index 100% rename from doc/4-configuring-icinga.md rename to doc/4-configuring-icinga-2.md diff --git a/doc/4.3-object-types.md b/doc/4.3-object-types.md index 584959e83..b684a0cff 100644 --- a/doc/4.3-object-types.md +++ b/doc/4.3-object-types.md @@ -1,4 +1,4 @@ -## Object Types +## Object Types ### Host diff --git a/doc/4.4-configuration-tools.md b/doc/4.4-configuration-tools.md new file mode 100644 index 000000000..d1254a2f4 --- /dev/null +++ b/doc/4.4-configuration-tools.md @@ -0,0 +1,11 @@ +## 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 favorite 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/5-icinga-template-library.md b/doc/5-icinga-template-library.md index 3835f586c..b31432d6d 100644 --- a/doc/5-icinga-template-library.md +++ b/doc/5-icinga-template-library.md @@ -1,6 +1,6 @@ -# Icinga Template Library +# Icinga Template Library -## Overview +## Overview The Icinga Template Library (ITL) implements standard templates and object definitions for commonly used services. @@ -10,9 +10,9 @@ file: include -## Check Commands +## Check Commands -### ping4 +### ping4 Check command object for the `check_ping` plugin. @@ -29,7 +29,7 @@ cpl | **Optional.** The packet loss critical threshold in %. Default packets | **Optional.** The number of packets to send. Defaults to 5. timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout). -### ping6 +### ping6 Check command object for the `check_ping` plugin. @@ -46,7 +46,7 @@ cpl | **Optional.** The packet loss critical threshold in %. Default packets | **Optional.** The number of packets to send. Defaults to 5. timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout). -### dummy +### dummy Check command object for the `check_dummy` plugin. @@ -58,7 +58,7 @@ plugindir | **Required.** The directory containing this plugin. state | **Optional.** The state. Can be one of 0 (ok), 1 (warning), 2 (critical) and 3 (unknown). Defaults to 0. text | **Optional.** Plugin output. Defaults to "Check was successful.". -### passive +### passive Specialised check command object for passive checks executing the `check_dummy` plugin with appropriate default values. @@ -70,7 +70,7 @@ plugindir | **Required.** The directory containing this plugin. state | **Optional.** The state. Can be one of 0 (ok), 1 (warning), 2 (critical) and 3 (unknown). Defaults to 3. text | **Optional.** Plugin output. Defaults to "No Passive Check Result Received.". -### tcp +### tcp Check command object for the `check_tcp` plugin. @@ -82,7 +82,7 @@ plugindir | **Required.** The directory containing this plugin. address | **Required.** The host's address. port | **Required.** The port that should be checked. -### udp +### udp Check command object for the `check_udp` plugin. @@ -94,7 +94,7 @@ plugindir | **Required.** The directory containing this plugin. address | **Required.** The host's address. port | **Required.** The port that should be checked. -### http_vhost +### http_vhost Check command object for the `check_http` plugin. @@ -105,7 +105,7 @@ Name | Description plugindir | **Required.** The directory containing this plugin. vhost | **Required.** The name of the virtual host that should be checked. -### http_ip +### http_ip Check command object for the `check_http` plugin. @@ -116,7 +116,7 @@ Name | Description plugindir | **Required.** The directory containing this plugin. address | **Required.** The host's address. -### https_vhost +### https_vhost Check command object for the `check_http` plugin. @@ -127,7 +127,7 @@ Name | Description plugindir | **Required.** The directory containing this plugin. vhost | **Required.** The name of the virtual host that should be checked. -### https_ip +### https_ip Check command object for the `check_http` plugin. @@ -138,7 +138,7 @@ Name | Description plugindir | **Required.** The directory containing this plugin. address | **Required.** The host's address. -### smtp +### smtp Check command object for the `check_smtp` plugin. @@ -149,7 +149,7 @@ Name | Description plugindir | **Required.** The directory containing this plugin. address | **Required.** The host's address. -### ssmtp +### ssmtp Check command object for the `check_ssmtp` plugin. @@ -161,7 +161,7 @@ plugindir | **Required.** The directory containing this plugin. address | **Required.** The host's address. port | **Optional.** The port that should be checked. Defaults to 465. -### ntp_time +### ntp_time Check command object for the `check_ntp_time` plugin. @@ -172,7 +172,7 @@ Name | Description plugindir | **Required.** The directory containing this plugin. address | **Required.** The host's address. -### ssh +### ssh Check command object for the `check_ssh` plugin. @@ -183,7 +183,7 @@ Name | Description plugindir | **Required.** The directory containing this plugin. address | **Required.** The host's address. -### disk +### disk Check command object for the `check_disk` plugin. @@ -195,7 +195,7 @@ plugindir | **Required.** The directory containing this plugin. wfree | **Optional.** The free space warning threshold in %. Defaults to 20. cfree | **Optional.** The free space critical threshold in %. Defaults to 10. -### users +### users Check command object for the `check_disk` plugin. @@ -207,7 +207,7 @@ plugindir | **Required.** The directory containing this plugin. wgreater | **Optional.** The user count warning threshold. Defaults to 20. cgreater | **Optional.** The user count warning threshold. Defaults to 50. -### processes +### processes Check command object for the `check_processes` plugin. @@ -219,7 +219,7 @@ plugindir | **Required.** The directory containing this plugin. wgreater | **Optional.** The process count warning threshold. Defaults to 250. cgreater | **Optional.** The process count warning threshold. Defaults to 400. -### load +### load Check command object for the `check_load` plugin. @@ -235,7 +235,7 @@ cload1 | **Optional.** The 1-minute critical threshold. Defaults to 10. cload5 | **Optional.** The 5-minute critical threshold. Defaults to 6. cload15 | **Optional.** The 15-minute critical threshold. Defaults to 4. -### snmp +### snmp Check command object for the `check_snmp` plugin. @@ -248,7 +248,7 @@ address | **Required.** The host's address. oid | **Required.** The SNMP OID. community | **Optional.** The SNMP community. Defaults to "public". -### snmp-uptime +### snmp-uptime Check command object for the `check_snmp` plugin. @@ -261,7 +261,7 @@ address | **Required.** The host's address. oid | **Optional.** The SNMP OID. Defaults to "1.3.6.1.2.1.1.3.0". community | **Optional.** The SNMP community. Defaults to "public". -### icinga +### icinga Check command for the built-in `icinga` check. This check returns performance data for the current Icinga instance. diff --git a/doc/6-advanced-topics.md b/doc/6-advanced-topics.md index 0e1d73ffa..c1768b38a 100644 --- a/doc/6-advanced-topics.md +++ b/doc/6-advanced-topics.md @@ -1,6 +1,6 @@ -# Advanced Topics +# Advanced Topics -## Downtimes +## Downtimes Downtimes can be scheduled for planned server maintenance or any other targetted service outage you are aware of in advance. @@ -18,7 +18,7 @@ tools calculating the SLAs based on the state and downtime history. > will be more than `1`. This is useful when you want to extend > your maintenance window taking longer than expected. -### Fixed and Flexible Downtimes +### Fixed and Flexible Downtimes A `fixed` downtime will be activated at the defined start time, and removed at the end time. During this time window the service state @@ -46,7 +46,7 @@ For that reason, you may want to schedule a downtime between 07:30 and its trigger time until the duration is over. After that, the downtime is removed (may happen before or after the actual end time!). -### Scheduling a downtime +### Scheduling a downtime 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` @@ -60,7 +60,7 @@ independent from that time span. > > Modern web interfaces treat services in a downtime as `handled`. -### Triggered Downtimes +### Triggered Downtimes This is optional when scheduling a downtime. If there is already a downtime scheduled for a future maintenance, the current downtime can be triggered by @@ -68,7 +68,43 @@ 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. -## Comments +### Recurring Downtimes + +[ScheduledDowntime objects](#objecttype-scheduleddowntime) can be used to set up +recurring downtimes for services. + +Example: + + template ScheduledDowntime "backup-downtime" { + 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" + } + } + + object Host "localhost" inherits "generic-host" { + ... + services["load"] = { + templates = [ "generic-service" ], + + check_command = "load", + + scheduled_downtimes["backup"] = { + templates = [ "backup-downtime" ] + } + }, + } + + +## Comments Comments can be added at runtime and are persistent over restarts. You can add useful information for others on repeating incidents (for example @@ -79,7 +115,7 @@ Adding and deleting comment actions are possible through the external command pi provided with the `ExternalCommandListener` configuration. The caller must pass the comment id in case of manipulating an existing comment. -## Acknowledgements +## 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. @@ -94,7 +130,7 @@ to all notified users. > > Modern web interfaces treat acknowledged problems as `handled`. -### Expiring Acknowledgements +### Expiring Acknowledgements Once a problem is acknowledged it may disappear from your `handled problems` dashboard and no-one ever looks at it again since it will suppress @@ -107,7 +143,7 @@ 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. -## Cluster +## Cluster 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 @@ -115,7 +151,7 @@ features using components. In case of a cluster setup you have to add the cluster feature to all nodes. Before you start configuring the diffent nodes it's necessary to setup the underlying communication layer based on SSL. -### Certificate Authority and Certificates +### Certificate Authority and Certificates Icinga 2 comes with two scripts helping you to create CA and node certificates for you Icinga 2 Cluster. @@ -138,14 +174,14 @@ Please create a certificate and a key file for every node in the Icinga 2 Cluster and save the CA key in case you want to set up certificates for additional nodes at a later date. -### Enable the Cluster Configuration +### Enable the Cluster Configuration Until the cluster-component is moved into an independent feature you have to enable the required libraries in the icinga2.conf configuration file: library "cluster" -### Configure the ClusterListener Object +### Configure the ClusterListener Object The ClusterListener needs to be configured on every node in the cluster with the following settings: @@ -191,7 +227,7 @@ a three node cluster consisting of and `node-3` is only reachable from `node-2`, you have to consider this in your peer configuration -### Configure Cluster Endpoints +### Configure Cluster Endpoints In addition to the configured port and hostname every endpoint can have specific abilities to send configuration files to other nodes and limit the hosts allowed @@ -227,7 +263,7 @@ instance you will have to add the following include directive to your include (IcingaLocalStateDir + "/lib/icinga2/cluster/config/*/*") -### Initial Sync +### Initial Cluster Sync In order to make sure that all of your cluster nodes have the same state you will have to pick one of the nodes as your initial "master" and copy its state file @@ -237,7 +273,7 @@ You can find the state file in `/var/lib/icinga2/icinga2.state`. Before copying the state file you should make sure that all your cluster nodes are properly shut down. -### Assign Services to Cluster Nodes +### Assign Services to Cluster Nodes By default all services are distributed among the cluster nodes with the `Checker` feature enabled. @@ -260,7 +296,7 @@ attribute. Required Endpoints must be defined as array. > defining the authorities. -## Dependencies +## Dependencies Icinga 2 uses host and service dependencies as attribute directly on the host or service object or template. A service can depend on a host, and vice versa. A @@ -302,7 +338,7 @@ router's firewall. host_dependencies = [ "dsl-router" ] } -## Check Result Freshness +## Check Result Freshness In Icinga 2 active check freshness is enabled by default. It is determined by the `check_interval` attribute and no incoming check results in that period of time. @@ -316,7 +352,7 @@ Passive check freshness is calculated from the `check_interval` attribute if set If the freshness checks are invalid, a new check is executed defined by the `check_command` attribute. -## Check Flapping +## 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 @@ -328,7 +364,7 @@ configuration attribute named `flapping_threshold`. > Flapping must be explicitely enabled seting the `Service` object attribute > `enable_flapping = 1`. -## Volatile Services +## Volatile Services By default all services remain in a non-volatile state. When a problem occurs, the `SOFT` state applies and once `max_check_attempts` attribute @@ -341,7 +377,7 @@ state type if the service stays in a `NOT-OK` state. That way each service recheck will automatically trigger a notification unless the service is acknowledged or in a scheduled downtime. -## Modified Attributes +## Modified Attributes Icinga 2 allows you to modify defined object attributes at runtime different to the local configuration object attributes. These modified attributes are @@ -351,13 +387,13 @@ modified attributes in its state file and restores them on restart. Modified Attributes can be reset using external commands. -## Plugin API +## Plugin API Currently the native plugin api inherited from the `Monitoring Plugins` (former `Nagios Plugins`) project is available. Future specifications will be documented here. -### Monitoring Plugin API +### Monitoring Plugin API The `Monitoring Plugin API` (former `Nagios Plugin API`) is defined in the [Monitoring Plugins Development Guidelines](https://www.monitoring-plugins.org/doc/guidelines.html). diff --git a/doc/7-migrating-from-icinga-1x.md b/doc/7-migrating-from-icinga-1x.md index a83749d02..4b031a23a 100644 --- a/doc/7-migrating-from-icinga-1x.md +++ b/doc/7-migrating-from-icinga-1x.md @@ -1,12 +1,12 @@ -# Migrating from Icinga 1.x +# Migrating from Icinga 1.x -## Configuration Migration +## Configuration Migration The Icinga 2 configuration format introduces plenty of behavioral changes. In order to ease migration from Icinga 1.x, Icinga 2 ships its own config migration script. -### Configuration Migration Script +### 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. @@ -29,10 +29,9 @@ possible. # mkdir /etc/icinga2/conf.d/migrate # /usr/bin/icinga2-migrate-config -c /etc/icinga/icinga.cfg -o /etc/icinga2/conf.d/migrate - -### Manual Config Migration +### 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 to get an idea about the differences between 1.x and 2. +Please read the [next chapter](#differences-1x-2) to get an idea about the differences between 1.x and 2. \ No newline at end of file diff --git a/doc/8-differences-between-icinga-1x-and-2.md b/doc/8-differences-between-icinga-1x-and-2.md index a04241abb..32fed6480 100644 --- a/doc/8-differences-between-icinga-1x-and-2.md +++ b/doc/8-differences-between-icinga-1x-and-2.md @@ -1,6 +1,6 @@ # Differences between Icinga 1.x and 2 -## Configuration Format +## Configuration Format Icinga 1.x supports two configuration formats: key-value-based settings in the `icinga.cfg` configuration file and object-based in included files (`cfg_dir`, @@ -22,7 +22,7 @@ if it's the main configuration file, or any included file. enable_notifications = 0, } -### Sample Configuration and ITL +### Sample Configuration and ITL While Icinga 1.x ships sample configuration and templates spread in various object files Icinga 2 moves all templates into the Icinga Template Library (ITL) @@ -35,7 +35,7 @@ The ITL will be updated on every release and should not be edited by the user. > Sample configuration files are located in the `conf.d/` directory which is > included in `icinga2.conf` by default. -### Include Files and Directories +### Include Files and Directories In Icinga 1.x the `icinga.cfg` file contains `cfg_file` and `cfg_dir` directives. The `cfg_dir` directive recursively includes all files with a `.cfg` @@ -58,7 +58,7 @@ suffix does not matter as long as it matches the (wildcard) include expression. > > By convention the `.conf` suffix is used for Icinga 2 configuration files. -## Resource File and Global Macros +## Resource File and Global Macros Global macros such as for the plugin directory, usernames and passwords can be set in the `resource.cfg` configuration file in Icinga 1.x. By convention the @@ -75,7 +75,7 @@ Icinga 2 uses a global `IcingaMacros` variable which is set in the } -## Comments +## Comments In Icinga 1.x comments are made using a leading hash (`#`) or a semi-colon (`;`) for inline comments. @@ -83,9 +83,9 @@ for inline comments. In Icinga 2 comments can either be encapsulated by `/*` and `*/` (allowing for multi-line comments) or starting with two slashes (`//`). -## Object names +## Object names -Object names must not contain a colon (`:`). Use the `display_name` attribute +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 Icinga 1.x Classic UI and Web). @@ -99,7 +99,7 @@ services) like in Icinga 1.x but directly after their type definition. object Service "localhost-ping4" { } -## Templates +## Templates In Icinga 1.x templates are identified using the `register 0` setting. Icinga 2 uses the `template` identifier: @@ -118,7 +118,7 @@ comma-separated list with template names in double quotes. object Service "testservice" inherits "tmpl1", "tmpl2", "tmpl3" { } -## Object attributes +## Object attributes Icinga 1.x separates attribute and value with whitespaces/tabs. Icinga 2 requires an equal sign (=) between them. @@ -144,7 +144,7 @@ with double quotes as well. Unlike in Icinga 1.x all attributes within the current object must be terminated with a comma (,). -### Alias vs. Display Name +### Alias vs. Display Name In Icinga 1.x a host can have an `alias` and a `display_name` attribute used for a more descriptive name. A service only can have a `display_name` attribute. @@ -152,9 +152,9 @@ 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. -## Custom Attributes +## Custom Attributes -### Action Url, Notes Url, Notes +### Action Url, Notes Url, Notes Icinga 1.x objects support configuration attributes not required as runtime values but for external ressources such as Icinga 1.x Classic UI or Web. @@ -177,7 +177,7 @@ or `Service` objects: External interfaces will recognize and display these attributes accordingly. -### Custom Variables +### Custom Variables Icinga 1.x custom variable attributes must be prefixed using an underscore (`_`). In Icinga 2 these attributes must be added to the `custom`dictionary. @@ -189,11 +189,11 @@ In Icinga 2 these attributes must be added to the `custom`dictionary. > **Note** > -> If you are planning to access custom variables as runtime macros you should -> add them to the macros dictionary instead! +> If you are planning to access custom variables as runtime macros you may access +> them with `_HOST`name as known from Icinga 1.x -## Host Service Relation +## Host Service Relation In Icinga 1.x a service object is associated with a host by defining the `host_name` attribute in the service definition. Alternate methods refer @@ -207,7 +207,7 @@ inline service definitions can reference service templates. Linking a service to a host is still possible with the 'host' attribute in a service object in Icinga 2. -## Users +## Users Contacts have been renamed to Users (same for groups). A user does not only provide attributes and macros used for notifications, but is also @@ -221,7 +221,7 @@ provide the contact and contactgroups attributes for services for compatibility reasons. These values are calculated from all services, their notifications, and their users. -## Macros +## Macros Various object attributes and runtime variables can be accessed as macros in commands in Icinga 1.x - Icinga 2 supports all required [macros](#macros). @@ -241,7 +241,7 @@ commands in Icinga 1.x - Icinga 2 supports all required [macros](#macros). CONTACTPAGER | USERPAGER -### Command Macros +### Command Macros If you have previously used Icinga 1.x you may already be familiar with user and argument macros (e.g., `USER1` or `ARG1`). Unlike in Icinga 1.x macros @@ -285,7 +285,7 @@ With the freely definable macros in Icinga 2 it looks like this: > $USER1$ macro. It also replaces the Icinga 1.x notation with $ARGn$ with freely > definable macros. -### Environment Macros +### Environment Macros The global configuration setting `enable_environment_macros` does not exist in Icinga 2. @@ -293,15 +293,15 @@ Icinga 2. Macros exported into the environment must be set using the `export_macros` attribute in command objects. -## Checks +## Checks -### Host Check +### Host Check Unlike in Icinga 1.x hosts are not checkable objects in Icinga 2. Instead hosts inherit their state from the service that is specified using the `check` attribute. -### Check Output +### Check Output Icinga 2 does not make a difference between `output` (first line) and `long_output` (remaining lines) like in Icinga 1.x. Performance Data is @@ -311,20 +311,20 @@ The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types split the raw output into `output` (first line) and `long_output` (remaining lines) for compatibility reasons. -### Initial State +### Initial State Icinga 1.x uses the `max_service_check_spread` setting to specify a timerange where the initial state checks must have happened. Icinga 2 will use the `retry_interval` setting instead and `check_interval` divided by 5 if `retry_interval` is not defined. -### Performance Data +### Performance Data There is no host performance data generated in Icinga 2 because there are no real host checks. Therefore the PerfDataWriter will only write service performance data files. -## Commands +## Commands Unlike in Icinga 1.x there are 3 different command types in Icinga 2: `CheckCommand`, `NotificationCommand` and EventCommand`. @@ -343,7 +343,7 @@ as array to the `command_line` attribute i.e. for better readability. It's also possible to define default macros for the command itself which can be overridden by a service macro. -## Groups +## Groups In Icinga 2 hosts, services and users are added to groups using the `groups` attribute in the object. The old way of listing all group members in the group's @@ -365,7 +365,7 @@ Host groups in Icinga 2 cannot be used to associate services with all members of that group. The example above shows how to use templates to accomplish the same effect. -## Notifications +## Notifications Notifications are a new object type in Icinga 2. Imagine the following notification configuration problem in Icinga 1.x: @@ -415,7 +415,7 @@ In Icinga 2 it will look like this: Service -> Notification -> NotificationCommand -> User, UserGroup -### Escalations +### Escalations Escalations in Icinga 1.x require a separated object matching on existing objects. Escalations happen between a defined start and end time which is @@ -439,7 +439,7 @@ happens. That's not necessary with Icinga 2 only requiring an additional notification object for the escalation itself. -### Notification Options +### Notification Options Unlike Icinga 1.x with the 'notification_options' attribute with comma-separated state and type filters, Icinga 2 uses two configuration attributes for that. @@ -463,7 +463,7 @@ and flapping type (start, end, ...). > Notification state and type filters are only valid configuration attributes for > `Notification` and `User` objects. -## Dependencies and Parents +## Dependencies and Parents In Icinga 1.x it's possible to define host parents to determine network reachability and keep a host's state unreachable rather than down. @@ -481,7 +481,7 @@ The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types support the Icinga 1.x schema with dependencies and parent attributes for compatibility reasons. -## Flapping +## Flapping The Icinga 1.x flapping detection uses the last 21 states of a service. This value is hardcoded and cannot be changed. The algorithm on determining a flapping state @@ -495,7 +495,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. -## Check Result Freshness +## 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 @@ -508,14 +508,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. -## State Retention +## State Retention Icinga 1.x uses the `retention.dat` file to save its state in order to be able to reload it after a restart. In Icinga 2 this file is called `icinga2.state`. The format objects are stored in is not compatible with Icinga 1.x. -## Logging +## Logging Icinga 1.x supports syslog facilities and writes its own `icinga.log` log file and archives. These logs are used in Icinga 1.x Classic UI to generate @@ -527,7 +527,7 @@ The native Icinga 2 logging facilities are split into three configuration object FileLogger, StreamLogger. Each of them got their own severity and target configuration. -## Broker Modules and Features +## Broker Modules and Features Icinga 1.x broker modules are incompatible with Icinga 2. @@ -543,7 +543,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. -## Distributed Monitoring +## 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. diff --git a/doc/9-vagrant-demo-vm.md b/doc/9-vagrant-demo-vm.md index 757c6f6d0..808f50d06 100644 --- a/doc/9-vagrant-demo-vm.md +++ b/doc/9-vagrant-demo-vm.md @@ -31,3 +31,7 @@ An instance of icinga-web is installed at [http://localhost:8080/icinga-web](htt The username is `root` and the password is `password`. SSH login is available using `vagrant ssh`. + +## Vagrant on Windows + +TODO