tyler.durden/icinga2
1
0
Fork 0
mirror of https://github.com/Icinga/icinga2.git synced 2025-07-27 07:34:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

Documentation: Add unique section ids.

Browse Source 
Fixes #5586
This commit is contained in:
Michael Friedrich 2014-02-05 15:53:22 +01:00
parent e6d405b4a4
commit 7342706eb8
30 changed files with 224 additions and 160 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
doc/1-about.md
View File

@ -1,25 +1,26 @@
# About Icinga 2 # <a id="about-icinga2"></a> About Icinga 2
## What is Icinga 2? ## <a id="what-is-icinga2"></a> What is Icinga 2?
Icinga 2 is an enterprise-grade open source monitoring system which keeps watch over networks 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 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 performance data for reporting. Scalable and extensible, Icinga 2 can monitor complex, large
environments across dispersed locations. environments across dispersed locations.
## Licensing ## <a id="licensing"></a> Licensing
Icinga 2 and the Icinga 2 documentation are licensed under the terms of the GNU 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 General Public License Version 2, you will find a copy of this license in the
LICENSE file included in the package. LICENSE file included in the package.
## Support ## <a id="support"></a> Support
Support for Icinga 2 is available in a number of ways. Please have a look at 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]. the support overview page at [https://support.icinga.org].
## <a id="whats-new"></a> 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"). * Scheduled Downtimes as configuration object (also known as "Recurring Downtimes").
* Log command arguments * 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 * Improve performance with fetching data for status.dat/objects.cache, DB IDO and Livestatus
* Livestatus History Table performance improvements * Livestatus History Table performance improvements
### Changes #### Changes
* Generated object names (host with services array) use an exclamation mark instead of a colon * 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 as seperator. State file objects with downtimes, comments, etc are invalid (unknown) for that
reason. reason.
@ -40,7 +41,7 @@ reason.
* ITL constants are now embedded in libicinga * ITL constants are now embedded in libicinga
* Removed the ConsoleLogger object and keep the default console log enabled until we daemonize * 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 * Cluster: Implement support for CRLs
* Implement modified attributes * Implement modified attributes
@ -54,7 +55,7 @@ reason.
* Lots of bugfixes and performance improvements * Lots of bugfixes and performance improvements
* Package fixes (Note: GPG key of packages.icinga.org has been updated) * 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: PostgreSQL support
* IDO: implemented options to filter which kind of events are written to the database * 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 * Replaced autotools-based build system with cmake
* Lots of bug fixes and performance improvements * 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` * `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 (former CompatLog) for status.dat/objects.cache/icinga2.cmd/icinga.log for Icinga 1.x Classic UI support

6
doc/2.0-getting-started.md
View File

@ -1,5 +1,5 @@
# Getting Started # <a id="getting-started"></a> Getting Started
This tutorial is a step-by-step introduction to installing Icinga 2 and 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 available Icinga web interfaces. It assumes that you are familiar with
that you are familiar with the system you're installing Icinga 2 on. the system you're installing Icinga 2 on.

10
doc/2.1-setting-up-icinga-2.md
View File

@ -1,4 +1,4 @@
## Setting up Icinga 2 ## <a id="setting-up-icinga2"></a> Setting up Icinga 2
First of all you will have to install Icinga 2. The preferred way of doing this 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 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 can download from the [Icinga website](https://www.icinga.org/). The
release tarballs contain an `INSTALL` file with further instructions. release tarballs contain an `INSTALL` file with further instructions.
### Installation Paths ### <a id="installation-paths"></a> Installation Paths
By default Icinga 2 uses the following files and directories: 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/lib/icinga2 | The Icinga 2 state file.
/var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature. /var/log/icinga2 | Log file location and compat/ directory for the CompatLogger feature.
### icinga2.conf ### <a id="icinga2-conf"></a> icinga2.conf
An example configuration file is installed for you in `/etc/icinga2/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 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. directive makes sure that all of your own configuration files are included.
### macros.conf ### <a id="macros-conf"></a> macros.conf
The `conf.d/macros.conf` file can be used to define global macros: 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 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. to define global macros which are available in all command definitions.
### localhost.conf ### <a id="localhost-conf"></a> localhost.conf
The `conf.d/localhost.conf` file contains our first host definition: The `conf.d/localhost.conf` file contains our first host definition:

4
doc/2.2-setting-up-check-plugins.md
View File

@ -1,4 +1,4 @@
## Setting up Check Plugins ## <a id="setting-up-check-plugins"></a> Setting up Check Plugins
On its own Icinga 2 does not know how to check external services. The On its own Icinga 2 does not know how to check external services. The
[Monitoring Plugins Project](https://www.monitoring-plugins.org/) (former [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 by the service templates contained in the Icinga Template Library to determine
where to find the plugin binaries. where to find the plugin binaries.
### Integrate Additonal Plugins ### <a id="integrate-additional-plugins"></a> Integrate Additonal Plugins
You may require a custom check plugin not provided by the official Nagios 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 All existing Nagios or Icinga 1.x plugins found on public community websites

20
doc/2.3-setting-up-ido.md
View File

@ -1,4 +1,4 @@
## Configuring IDO ## <a id="configuring-ido"></a> Configuring IDO
The IDO (Icinga Data Output) modules for Icinga 2 takes care of exporting all 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 configuration and status information into a database. The IDO database is used
@ -10,11 +10,13 @@ both MySQL and PostgreSQL is implemented.
> **Note** > **Note**
> >
> Icinga 2 uses the Icinga 1.x IDOUtils database schema starting with version > 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 ### <a id="configuring-ido-mysql"></a> Configuring IDO MySQL
#### Setting up the MySQL database #### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
First of all you have to install the `icinga2-ido-mysql` package using your 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 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 > On SuSE-based distributions the schema files are installed in
> `/usr/share/doc/packages/icinga2-ido-mysql/schema`. > `/usr/share/doc/packages/icinga2-ido-mysql/schema`.
#### Upgrading the MySQL database #### <a id="upgrading-mysql-db"></a> Upgrading the MySQL database
If the database has been installed and requires an upgrade, verify the current If the database has been installed and requires an upgrade, verify the current
schema version first: 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 > The Icinga 2 IDO module will check for the required database schema version
> on startup and generate an error message if not satisfied. > on startup and generate an error message if not satisfied.
#### Installing the IDO MySQL module #### <a id="installing-ido-mysql"></a> Installing the IDO MySQL module
The package provides a new configuration file that is installed in The package provides a new configuration file that is installed in
`/etc/icinga2/features-available/ido-mysql.conf`. You will need to update the `/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 # /etc/init.d/icinga2 restart
### Configuring IDO PostgreSQL ### <a id="configuring-ido-postgresql"></a> Configuring IDO PostgreSQL
#### Setting up the PostgreSQL database #### Setting up the PostgreSQL database
@ -146,7 +148,7 @@ using the following command:
> `/usr/share/doc/packages/icinga2-ido-pgsql/schema`. > `/usr/share/doc/packages/icinga2-ido-pgsql/schema`.
#### Upgrading the PostgreSQL database #### <a id="upgrading-postgresql-db"></a> Upgrading the PostgreSQL database
If the database has been installed and requires an upgrade, verify the current If the database has been installed and requires an upgrade, verify the current
schema version first: schema version first:
@ -171,7 +173,7 @@ Apply all database schema upgrade files incrementially.
> on startup and generate an error message if not satisfied. > on startup and generate an error message if not satisfied.
#### Installing the IDO PostgreSQL module #### <a id="installing-ido-postgresql"></a> Installing the IDO PostgreSQL module
The package provides a new configuration file that is installed in The package provides a new configuration file that is installed in
`/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update the `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update the

2
doc/2.4-setting-up-livestatus.md
View File

@ -1,4 +1,4 @@
## Setting up Livestatus ## <a id=setting-up-livestatus""></a> Setting up Livestatus
The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project
implements a query protocol that lets users query their Icinga instance for implements a query protocol that lets users query their Icinga instance for

29
doc/2.5-setting-up-icinga2-uis.md
View File

@ -1,6 +1,4 @@
## <a id="setting-up-icinga2-user-interfaces"></a> 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 Icinga 2 is compatible to Icinga 1.x user interfaces by providing additional
features required as backends. 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` exclusive interface) can be used for the newly created `Icinga Web 2`
user interface. 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.
### <a id="setting-up-icinga-classic-ui"></a> Setting up Icinga Classic UI
Icinga 2 can write `status.dat` and `objects.cache` files in the format that 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 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 "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. log files which are required for the reporting functionality in the Classic UI.
#### Installing Icinga Classic UI #### <a id="installing-icinga-classic-ui"></a> Installing Icinga Classic UI
The Icinga package repository has both Debian and RPM packages. You can install The Icinga package repository has both Debian and RPM packages. You can install
the Classic UI using the following packages: 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 Debian | [http://localhost/icinga2-classicui](http://localhost/icinga2-classicui) | asked during installation
all others | [http://localhost/icinga](http://localhost/icinga) | icingaadmin/icingaadmin 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
### <a id="setting-up-icinga-web"></a> Setting up Icinga Web
Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which 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. 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. Therefore you need to setup the DB IDO feature remarked in the previous sections.
#### Installing Icinga Web #### <a id="installing-icinga-web"></a> Installing Icinga Web
The Icinga package repository has both Debian and RPM packages. You can install The Icinga package repository has both Debian and RPM packages. You can install
the Classic UI using the following packages: 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 ### <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
Icinga Web 2 currently supports `status.dat`, `DB IDO` or `Livestatus` as backends. Icinga Web 2 currently supports `status.dat`, `DB IDO` or `Livestatus` as backends.
Please consult the INSTALL documentation shipped with `Icinga Web 2` for 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 > yourself you should consider testing it using the available Vagrant
> demo boxes. > demo boxes.
### Additional visualization ### <a id="additional-visualization"></a> Additional visualization
There are many addons in the wild which are using Icinga 1.x backends and There are many addons in the wild which are using Icinga 1.x backends and
are well integrated into user interfaces. are well integrated into user interfaces.

4
doc/2.6-running-icinga.md → doc/2.6-running-icinga-2.md
View File

@ -1,6 +1,6 @@
## Running Icinga ## <a id="running-icinga2"></a> Running Icinga 2
### Init Script ### <a id="init-script"></a> Init Script
Icinga 2's init script is installed in `/etc/init.d/icinga2` by default: Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:

2
doc/3-monitoring-basics.md
View File

@ -1,4 +1,4 @@
# Monitoring Basics # <a id="monitoring-basics"></a> Monitoring Basics
This part of the Icinga 2 documentation provides an overview of all the basic This part of the Icinga 2 documentation provides an overview of all the basic
monitoring concepts you need to know to run Icinga 2. monitoring concepts you need to know to run Icinga 2.

8
doc/3.01-hosts-and-services.md
View File

@ -1,4 +1,4 @@
## Hosts and Services ## <a id="hosts-services"></a> Hosts and Services
Icinga 2 can be used to monitor the availability of hosts and services. 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: 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 The `address` macro is used by check commands to determine which network
address is associated with the host object. address is associated with the host object.
### Host States ### <a id="host-states"></a> Host States
Hosts inherit their state from the host check service that is specified using Hosts inherit their state from the host check service that is specified using
the `check` attribute. the `check` attribute.
@ -57,7 +57,7 @@ Hosts can be in any of the following states:
DOWN | The host is unavailable. 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. UNREACHABLE | At least one of the host's dependencies (e.g. its upstream router) is unavailable causing the host to be unreachable.
### Service States ### <a id="service-states"></a> Service States
Services can be in any of the following 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. CRITICAL | The service is in a critical state.
UNKNOWN | The check could not determine the service's state. UNKNOWN | The check could not determine the service's state.
### Hard and Soft States ### <a id="hard-soft-states"></a> Hard and Soft States
When detecting a problem with a service Icinga re-checks the service a number of 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 times (based on the `max_check_attempts` and `retry_interval` settings) before sending

10
doc/3.02-commands.md
View File

@ -1,4 +1,4 @@
## Commands ## <a id="commands"></a> Commands
Icinga 2 uses three different command object types to specify how Icinga 2 uses three different command object types to specify how
checks should be performed, notifications should be sent and 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 > Put your plugins and scripts into the directory defined by the `$plugindir$` macro
> and make sure they are executable by the Icinga 2 user. > and make sure they are executable by the Icinga 2 user.
### Environment Macros ### <a id="environment-macros"></a> Environment Macros
If your plugins require environment macros instead of command arguments you have If your plugins require environment macros instead of command arguments you have
to define all macros in the `export_macros` attribute as list. 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 > Use templates to define global `export_macros` attributes for the three
> command types and let each command object inherit the attribute. > command types and let each command object inherit the attribute.
### Check Commands ### <a id="check-commands"></a> Check Commands
`CheckCommand` objects define the command line how a check is called. `CheckCommand` objects define the command line how a check is called.
@ -95,7 +95,7 @@ space).
} }
### Notification Commands ### <a id="notification-commands"></a> Notification Commands
`NotificationCommand` objects define how notifications are delivered to external `NotificationCommand` objects define how notifications are delivered to external
interfaces (E-Mail, XMPP, IRC, Twitter, etc). 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 > shell script in the `/etc/icinga2/scripts` directory and have the
> NotificationCommand object refer to that. > NotificationCommand object refer to that.
### Event Commands ### <a id="event-commands"></a> Event Commands
Unlike notifications event commands are called on every service state change Unlike notifications event commands are called on every service state change
if defined. Therefore the `EventCommand` object should define a command line if defined. Therefore the `EventCommand` object should define a command line

8
doc/3.04-notifications.md
View File

@ -1,4 +1,4 @@
## Notifications ## <a id="notifications"></a> Notifications
Notifications on alerts are an integral part of your Icinga 2 monitoring application. 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, 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 > 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. > resolve all group members and send notifications to all of them.
### Notification Escalations ### <a id="notification-escalations"></a> Notification Escalations
When a problem notification is sent and a problem still exists after re-notification 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 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 > resolve all group members and send notifications and notification escalations to
> all of them. > all of them.
### First Notification Delay ### <a id="first-notification-delay"></a> First Notification Delay
Sometimes the problem in question should not be notified when the first notification 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` 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`. > In Icinga 1.x the attribute is called `first_notification_delay`.
### Notification Filters by State and Type ### <a id="notification-filters-state-type"></a> Notification Filters by State and Type
If there are no notification state and type filter attributes defined at the `Notification` 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. or `User` object Icinga 2 assumes that all states and types are being notified.

2
doc/3.05-using-templates.md
View File

@ -1,4 +1,4 @@
## Using Templates ## <a id="using-templates"></a> Using Templates
Templates may be used to apply a set of similar settings to more than one Templates may be used to apply a set of similar settings to more than one
object. object.

2
doc/3.06-groups.md
View File

@ -1,4 +1,4 @@
## Groups ## <a id="groups"></a> Groups
Groups are used for combining hosts, services and users into Groups are used for combining hosts, services and users into
accessible configuration attributes and views in external (web) accessible configuration attributes and views in external (web)

2
doc/3.07-time-periods.md
View File

@ -1,4 +1,4 @@
## Time Periods ## <a id="timeperiods"></a> Time Periods
Time Periods define time ranges in Icinga where event actions are Time Periods define time ranges in Icinga where event actions are
triggered, for example if a service check is executed or not within triggered, for example if a service check is executed or not within

6
doc/3.08-external-commands.md
View File

@ -1,4 +1,4 @@
## External Commands ## <a id="external-commands"></a> External Commands
Icinga 2 provides an external command pipe for processing commands Icinga 2 provides an external command pipe for processing commands
triggering specific actions (for example rescheduling a service check triggering specific actions (for example rescheduling a service check
@ -31,9 +31,7 @@ a forced service check:
# usermod -G -a icingacmd www-data # usermod -G -a icingacmd www-data
### <a id="external-command-list"></a> External Command List
### External Command List
A list of currently supported external commands can be found on the A list of currently supported external commands can be found on the
[Icinga Wiki](https://wiki.icinga.org/display/icinga2/External+Commands). [Icinga Wiki](https://wiki.icinga.org/display/icinga2/External+Commands).

2
doc/3.09-event-handlers.md
View File

@ -1,4 +1,4 @@
## Event Handlers ## <a id="event-handlers"></a> Event Handlers
Event handlers are defined as `EventCommand` objects in Icinga 2. Event handlers are defined as `EventCommand` objects in Icinga 2.

2
doc/3.10-logging.md
View File

@ -1,4 +1,4 @@
## Logging ## <a id="logging"></a> Logging
Icinga 2 supports three different types of logging: Icinga 2 supports three different types of logging:

6
doc/3.11-performance-data.md
View File

@ -1,4 +1,4 @@
## Performance Data ## <a id="performance-data"></a> Performance Data
When a service check is executed plugins should provide so-called When a service check is executed plugins should provide so-called
`performance data`. Next to that additional check performance data `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 > As there are no real host checks in Icinga 2, there is no performance
> data generated for hosts. > data generated for hosts.
### Writing Performance Data Files ### <a id="writing-performance-data-files"></a> Writing Performance Data Files
PNP4Nagios and inGraph use performance data collector daemons to fetch PNP4Nagios and inGraph use performance data collector daemons to fetch
the current performance files for their backend updates. the current performance files for their backend updates.
@ -44,7 +44,7 @@ remove the processed files.
> and critical thresholds. > and critical thresholds.
### Graphite Carbon Cache Writer ### <a id="graphite-carbon-cache-writer"></a> Graphite Carbon Cache Writer
While there are some Graphite collector scripts for Icinga 1.x available it's 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 more reasonable to directly process the check and plugin performance in memory

2
doc/3.12-status-data.md
View File

@ -1,4 +1,4 @@
## Status Data ## <a id="status-data"></a> Status Data
Icinga 1.x writes object configuration data and status data in a cyclic 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 interval to its `objects.cache` and `status.dat` files. Icinga 2 provides

6
doc/3.13-compat-logging.md
View File

@ -1,11 +1,13 @@
## Compat Logging ## <a id="compat-logging"></a> Compat Logging
The Icinga 1.x log format is considered being the `Compat Log` The Icinga 1.x log format is considered being the `Compat Log`
in Icinga 2 provided with the `CompatLogger` object. in Icinga 2 provided with the `CompatLogger` object.
These logs are not only used for informal representation in These logs are not only used for informal representation in
external web interfaces parsing the logs, but also to generate 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 The `CompatLogger` object can be enabled with

2
doc/3.14-check-result-files.md
View File

@ -1,4 +1,4 @@
## Check Result Files ## <a id="check-result-files"></a> Check Result Files
Icinga 1.x writes its check result files into a temporary spool directory 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. where it reads these check result files in a regular interval from.

0
doc/4-configuring-icinga.md → doc/4-configuring-icinga-2.md
View File

2
doc/4.3-object-types.md
View File

@ -1,4 +1,4 @@
## Object Types ## <a id="object-types"></a> Object Types
### <a id="objecttype-host"></a> Host ### <a id="objecttype-host"></a> Host

11
doc/4.4-configuration-tools.md Normal file
View File

@ -0,0 +1,11 @@
## <a id="configuration-tools"></a> Configuration Tools
Well known configuration tools for Icinga 1.x such as [LConf](http://www.netways.de/en/de/produkte/icinga/addons/lconf/),
[NConf](http://www.nconf.org/) or [NagiosQL](http://www.nagiosql.org/)
store their configuration in a custom format in their backends (LDAP or RDBMS).
Currently only LConf 1.4.x supports Icinga 2 configuration export. If you require
your 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) :-)

48
doc/5-icinga-template-library.md
View File

@ -1,6 +1,6 @@
# Icinga Template Library # <a id="icinga-template-library"></a> Icinga Template Library
## Overview ## <a id="itl-overview"></a> Overview
The Icinga Template Library (ITL) implements standard templates and object The Icinga Template Library (ITL) implements standard templates and object
definitions for commonly used services. definitions for commonly used services.
@ -10,9 +10,9 @@ file:
include <itl/itl.conf> include <itl/itl.conf>
## Check Commands ## <a id="itl-check-commands"></a> Check Commands
### ping4 ### <a id="itl-ping4"></a> ping4
Check command object for the `check_ping` plugin. 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. packets | **Optional.** The number of packets to send. Defaults to 5.
timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout). timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
### ping6 ### <a id="itl-ping6"></a> ping6
Check command object for the `check_ping` plugin. 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. packets | **Optional.** The number of packets to send. Defaults to 5.
timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout). timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
### dummy ### <a id="itl-dummy"></a> dummy
Check command object for the `check_dummy` plugin. 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. 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.". text | **Optional.** Plugin output. Defaults to "Check was successful.".
### passive ### <a id="itl-passive"></a> passive
Specialised check command object for passive checks executing the `check_dummy` plugin with appropriate default values. 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. 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.". text | **Optional.** Plugin output. Defaults to "No Passive Check Result Received.".
### tcp ### <a id="itl-tcp"></a> tcp
Check command object for the `check_tcp` plugin. 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. address | **Required.** The host's address.
port | **Required.** The port that should be checked. port | **Required.** The port that should be checked.
### udp ### <a id="itl-udp"></a> udp
Check command object for the `check_udp` plugin. 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. address | **Required.** The host's address.
port | **Required.** The port that should be checked. port | **Required.** The port that should be checked.
### http_vhost ### <a id="itl-http-vhost"></a> http_vhost
Check command object for the `check_http` plugin. Check command object for the `check_http` plugin.
@ -105,7 +105,7 @@ Name | Description
plugindir | **Required.** The directory containing this plugin. plugindir | **Required.** The directory containing this plugin.
vhost | **Required.** The name of the virtual host that should be checked. vhost | **Required.** The name of the virtual host that should be checked.
### http_ip ### <a id="itl-http-ip"></a> http_ip
Check command object for the `check_http` plugin. Check command object for the `check_http` plugin.
@ -116,7 +116,7 @@ Name | Description
plugindir | **Required.** The directory containing this plugin. plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address. address | **Required.** The host's address.
### https_vhost ### <a id="itl-https-vhost"></a> https_vhost
Check command object for the `check_http` plugin. Check command object for the `check_http` plugin.
@ -127,7 +127,7 @@ Name | Description
plugindir | **Required.** The directory containing this plugin. plugindir | **Required.** The directory containing this plugin.
vhost | **Required.** The name of the virtual host that should be checked. vhost | **Required.** The name of the virtual host that should be checked.
### https_ip ### <a id="itl-https-ip"></a> https_ip
Check command object for the `check_http` plugin. Check command object for the `check_http` plugin.
@ -138,7 +138,7 @@ Name | Description
plugindir | **Required.** The directory containing this plugin. plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address. address | **Required.** The host's address.
### smtp ### <a id="itl-smtp"></a> smtp
Check command object for the `check_smtp` plugin. Check command object for the `check_smtp` plugin.
@ -149,7 +149,7 @@ Name | Description
plugindir | **Required.** The directory containing this plugin. plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address. address | **Required.** The host's address.
### ssmtp ### <a id="itl-ssmtp"></a> ssmtp
Check command object for the `check_ssmtp` plugin. 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. address | **Required.** The host's address.
port | **Optional.** The port that should be checked. Defaults to 465. port | **Optional.** The port that should be checked. Defaults to 465.
### ntp_time ### <a id="itl-ntp-time"></a> ntp_time
Check command object for the `check_ntp_time` plugin. Check command object for the `check_ntp_time` plugin.
@ -172,7 +172,7 @@ Name | Description
plugindir | **Required.** The directory containing this plugin. plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address. address | **Required.** The host's address.
### ssh ### <a id="itl-ssh"></a> ssh
Check command object for the `check_ssh` plugin. Check command object for the `check_ssh` plugin.
@ -183,7 +183,7 @@ Name | Description
plugindir | **Required.** The directory containing this plugin. plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address. address | **Required.** The host's address.
### disk ### <a id="itl-disk"></a> disk
Check command object for the `check_disk` plugin. 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. wfree | **Optional.** The free space warning threshold in %. Defaults to 20.
cfree | **Optional.** The free space critical threshold in %. Defaults to 10. cfree | **Optional.** The free space critical threshold in %. Defaults to 10.
### users ### <a id="itl-users"></a> users
Check command object for the `check_disk` plugin. 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. wgreater | **Optional.** The user count warning threshold. Defaults to 20.
cgreater | **Optional.** The user count warning threshold. Defaults to 50. cgreater | **Optional.** The user count warning threshold. Defaults to 50.
### processes ### <a id="itl-processes"></a> processes
Check command object for the `check_processes` plugin. 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. wgreater | **Optional.** The process count warning threshold. Defaults to 250.
cgreater | **Optional.** The process count warning threshold. Defaults to 400. cgreater | **Optional.** The process count warning threshold. Defaults to 400.
### load ### <a id="itl-load"></a> load
Check command object for the `check_load` plugin. 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. cload5 | **Optional.** The 5-minute critical threshold. Defaults to 6.
cload15 | **Optional.** The 15-minute critical threshold. Defaults to 4. cload15 | **Optional.** The 15-minute critical threshold. Defaults to 4.
### snmp ### <a id="itl-snmp"></a> snmp
Check command object for the `check_snmp` plugin. Check command object for the `check_snmp` plugin.
@ -248,7 +248,7 @@ address | **Required.** The host's address.
oid | **Required.** The SNMP OID. oid | **Required.** The SNMP OID.
community | **Optional.** The SNMP community. Defaults to "public". community | **Optional.** The SNMP community. Defaults to "public".
### snmp-uptime ### <a id="itl-snmp-uptime"></a> snmp-uptime
Check command object for the `check_snmp` plugin. 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". oid | **Optional.** The SNMP OID. Defaults to "1.3.6.1.2.1.1.3.0".
community | **Optional.** The SNMP community. Defaults to "public". community | **Optional.** The SNMP community. Defaults to "public".
### icinga ### <a id="itl-icinga"></a> icinga
Check command for the built-in `icinga` check. This check returns performance Check command for the built-in `icinga` check. This check returns performance
data for the current Icinga instance. data for the current Icinga instance.

80
doc/6-advanced-topics.md
View File

@ -1,6 +1,6 @@
# Advanced Topics # <a id="advanced-topics"></a> Advanced Topics
## Downtimes ## <a id="downtimes"></a> Downtimes
Downtimes can be scheduled for planned server maintenance or Downtimes can be scheduled for planned server maintenance or
any other targetted service outage you are aware of in advance. 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 > will be more than `1`. This is useful when you want to extend
> your maintenance window taking longer than expected. > your maintenance window taking longer than expected.
### Fixed and Flexible Downtimes ### <a id="fixed-flexible-downtimes"></a> Fixed and Flexible Downtimes
A `fixed` downtime will be activated at the defined start time, and A `fixed` downtime will be activated at the defined start time, and
removed at the end time. During this time window the service state 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 its trigger time until the duration is over. After that, the downtime
is removed (may happen before or after the actual end time!). is removed (may happen before or after the actual end time!).
### Scheduling a downtime ### <a id="scheduling-downtime"></a> Scheduling a downtime
This can either happen through a web interface (Icinga 1.x Classic UI or Web) 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` 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`. > Modern web interfaces treat services in a downtime as `handled`.
### Triggered Downtimes ### <a id="triggered-downtimes"></a> Triggered Downtimes
This is optional when scheduling a downtime. If there is already a downtime 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 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 are now scheduling a child host's downtime getting triggered by the parent
downtime on NOT-OK state change. downtime on NOT-OK state change.
## Comments ### <a id="recurring-downtimes"></a> 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" ]
}
},
}
## <a id="comments"></a> Comments
Comments can be added at runtime and are persistent over restarts. You can Comments can be added at runtime and are persistent over restarts. You can
add useful information for others on repeating incidents (for example 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 provided with the `ExternalCommandListener` configuration. The caller must
pass the comment id in case of manipulating an existing comment. pass the comment id in case of manipulating an existing comment.
## Acknowledgements ## <a id="acknowledgements"></a> Acknowledgements
If a problem is alerted and notified you may signal the other notification 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. 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`. > Modern web interfaces treat acknowledged problems as `handled`.
### Expiring Acknowledgements ### <a id="expiring-acknowledgements"></a> Expiring Acknowledgements
Once a problem is acknowledged it may disappear from your `handled problems` 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 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 Icinga 2 will clear the acknowledgement when expired and start to
re-notify if the problem persists. re-notify if the problem persists.
## Cluster ## <a id="cluster"></a> Cluster
An Icinga 2 cluster consists of two or more nodes and can reside on multiple 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 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 cluster feature to all nodes. Before you start configuring the diffent nodes
it's necessary to setup the underlying communication layer based on SSL. it's necessary to setup the underlying communication layer based on SSL.
### Certificate Authority and Certificates ### <a id="certificate-authority-certificates"></a> Certificate Authority and Certificates
Icinga 2 comes with two scripts helping you to create CA and node certificates Icinga 2 comes with two scripts helping you to create CA and node certificates
for you Icinga 2 Cluster. 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 Cluster and save the CA key in case you want to set up certificates for
additional nodes at a later date. additional nodes at a later date.
### Enable the Cluster Configuration ### <a id="enable-cluster-configuration"></a> Enable the Cluster Configuration
Until the cluster-component is moved into an independent feature you have to Until the cluster-component is moved into an independent feature you have to
enable the required libraries in the icinga2.conf configuration file: enable the required libraries in the icinga2.conf configuration file:
library "cluster" library "cluster"
### Configure the ClusterListener Object ### <a id="configure-clusterlistener-object"></a> Configure the ClusterListener Object
The ClusterListener needs to be configured on every node in the cluster with the The ClusterListener needs to be configured on every node in the cluster with the
following settings: 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 and `node-3` is only reachable from `node-2`, you have to consider this in your
peer configuration peer configuration
### Configure Cluster Endpoints ### <a id="configure-cluster-endpoints"></a> Configure Cluster Endpoints
In addition to the configured port and hostname every endpoint can have specific 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 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/*/*") include (IcingaLocalStateDir + "/lib/icinga2/cluster/config/*/*")
### Initial Sync ### <a id="initial-cluster-sync"></a> Initial Cluster Sync
In order to make sure that all of your cluster nodes have the same state you will 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 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 the state file you should make sure that all your cluster nodes are properly shut
down. down.
### Assign Services to Cluster Nodes ### <a id="assign-services-to-cluster-nodes"></a> Assign Services to Cluster Nodes
By default all services are distributed among the cluster nodes with the `Checker` By default all services are distributed among the cluster nodes with the `Checker`
feature enabled. feature enabled.
@ -260,7 +296,7 @@ attribute. Required Endpoints must be defined as array.
> defining the authorities. > defining the authorities.
## Dependencies ## <a id="dependencies"></a> Dependencies
Icinga 2 uses host and service dependencies as attribute directly on the host or 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 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" ] host_dependencies = [ "dsl-router" ]
} }
## Check Result Freshness ## <a id="check-result-freshness"></a> Check Result Freshness
In Icinga 2 active check freshness is enabled by default. It is determined by the In Icinga 2 active check freshness is enabled by default. It is determined by the
`check_interval` attribute and no incoming check results in that period of time. `check_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 If the freshness checks are invalid, a new check is executed defined by the
`check_command` attribute. `check_command` attribute.
## Check Flapping ## <a id="check-flapping"></a> Check Flapping
The flapping algorithm used in Icinga 2 does not store the past states but 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 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 > Flapping must be explicitely enabled seting the `Service` object attribute
> `enable_flapping = 1`. > `enable_flapping = 1`.
## Volatile Services ## <a id="volatile-services"></a> Volatile Services
By default all services remain in a non-volatile state. When a problem By default all services remain in a non-volatile state. When a problem
occurs, the `SOFT` state applies and once `max_check_attempts` attribute 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 recheck will automatically trigger a notification unless the
service is acknowledged or in a scheduled downtime. service is acknowledged or in a scheduled downtime.
## Modified Attributes ## <a id="modified-attributes"></a> Modified Attributes
Icinga 2 allows you to modify defined object attributes at runtime different to Icinga 2 allows you to modify defined object attributes at runtime different to
the local configuration object attributes. These modified attributes are 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. Modified Attributes can be reset using external commands.
## Plugin API ## <a id="plugin-api"></a> Plugin API
Currently the native plugin api inherited from the `Monitoring Plugins` (former Currently the native plugin api inherited from the `Monitoring Plugins` (former
`Nagios Plugins`) project is available. `Nagios Plugins`) project is available.
Future specifications will be documented here. Future specifications will be documented here.
### Monitoring Plugin API ### <a id="monitoring-plugin-api"></a> Monitoring Plugin API
The `Monitoring Plugin API` (former `Nagios Plugin API`) is defined in the The `Monitoring Plugin API` (former `Nagios Plugin API`) is defined in the
[Monitoring Plugins Development Guidelines](https://www.monitoring-plugins.org/doc/guidelines.html). [Monitoring Plugins Development Guidelines](https://www.monitoring-plugins.org/doc/guidelines.html).

11
doc/7-migrating-from-icinga-1x.md
View File

@ -1,12 +1,12 @@
# Migrating from Icinga 1.x # <a id="migrating-from-icinga-1x"></a> Migrating from Icinga 1.x
## Configuration Migration ## <a id="configuration-migration"></a> Configuration Migration
The Icinga 2 configuration format introduces plenty of behavioral changes. In The Icinga 2 configuration format introduces plenty of behavioral changes. In
order to ease migration from Icinga 1.x, order to ease migration from Icinga 1.x,
Icinga 2 ships its own config migration script. Icinga 2 ships its own config migration script.
### Configuration Migration Script ### <a id="configuration-migration-script"></a> Configuration Migration Script
Due to the complexity of the Icinga 1.x configuration format the migration Due to the complexity of the Icinga 1.x configuration format the migration
script might not currently work for all use cases. script might not currently work for all use cases.
@ -29,10 +29,9 @@ possible.
# mkdir /etc/icinga2/conf.d/migrate # mkdir /etc/icinga2/conf.d/migrate
# /usr/bin/icinga2-migrate-config -c /etc/icinga/icinga.cfg -o /etc/icinga2/conf.d/migrate # /usr/bin/icinga2-migrate-config -c /etc/icinga/icinga.cfg -o /etc/icinga2/conf.d/migrate
### <a id="manual-config-migration"></a> Manual Config Migration
### Manual Config Migration
For a long-term migration of your configuration you should consider re-creating 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. 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.

74
doc/8-differences-between-icinga-1x-and-2.md
View File

@ -1,6 +1,6 @@
# <a id="differences-1x-2"></a> Differences between Icinga 1.x and 2 # <a id="differences-1x-2"></a> Differences between Icinga 1.x and 2
## Configuration Format ## <a id="differences-1x-2-configuration-format"></a> Configuration Format
Icinga 1.x supports two configuration formats: key-value-based settings in the 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`, `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, enable_notifications = 0,
} }
### Sample Configuration and ITL ### <a id="differences-1x-2-sample-configuration-itl"></a> Sample Configuration and ITL
While Icinga 1.x ships sample configuration and templates spread in various 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) 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 > Sample configuration files are located in the `conf.d/` directory which is
> included in `icinga2.conf` by default. > included in `icinga2.conf` by default.
### Include Files and Directories ### <a id="differences-1x-2-include-files-dirs"></a> Include Files and Directories
In Icinga 1.x the `icinga.cfg` file contains `cfg_file` and `cfg_dir` 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` 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. > By convention the `.conf` suffix is used for Icinga 2 configuration files.
## Resource File and Global Macros ## <a id="differences-1x-2-resource-file-global-macros"></a> Resource File and Global Macros
Global macros such as for the plugin directory, usernames and passwords can be 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 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 ## <a id="differences-1x-2-comments"></a> Comments
In Icinga 1.x comments are made using a leading hash (`#`) or a semi-colon (`;`) In Icinga 1.x comments are made using a leading hash (`#`) or a semi-colon (`;`)
for inline comments. for inline comments.
@ -83,9 +83,9 @@ for inline comments.
In Icinga 2 comments can either be encapsulated by `/*` and `*/` (allowing for In Icinga 2 comments can either be encapsulated by `/*` and `*/` (allowing for
multi-line comments) or starting with two slashes (`//`). multi-line comments) or starting with two slashes (`//`).
## Object names ## <a id="differences-1x-2-object-names"></a> 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 to specify user-friendly names which should be shown in UIs (supported by
Icinga 1.x Classic UI and Web). 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" { } object Service "localhost-ping4" { }
## Templates ## <a id="differences-1x-2-templates"></a> Templates
In Icinga 1.x templates are identified using the `register 0` setting. Icinga 2 In Icinga 1.x templates are identified using the `register 0` setting. Icinga 2
uses the `template` identifier: 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 Service "testservice" inherits "tmpl1", "tmpl2", "tmpl3" {
} }
## Object attributes ## <a id="differences-1x-2-object-attributes"></a> Object attributes
Icinga 1.x separates attribute and value with whitespaces/tabs. Icinga 2 Icinga 1.x separates attribute and value with whitespaces/tabs. Icinga 2
requires an equal sign (=) between them. 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 Unlike in Icinga 1.x all attributes within the current object must be
terminated with a comma (,). terminated with a comma (,).
### Alias vs. Display Name ### <a id="differences-1x-2-alias-display-name"></a> Alias vs. Display Name
In Icinga 1.x a host can have an `alias` and a `display_name` attribute used 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. 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 Icinga 2 only supports the `display_name` attribute which is also taken into
account by Icinga 1.x Classic UI and Web. account by Icinga 1.x Classic UI and Web.
## Custom Attributes ## <a id="differences-1x-2-custom-attributes"></a> Custom Attributes
### Action Url, Notes Url, Notes ### <a id="differences-1x-2-action-url-notes-url-notes"></a> Action Url, Notes Url, Notes
Icinga 1.x objects support configuration attributes not required as runtime 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. 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. External interfaces will recognize and display these attributes accordingly.
### Custom Variables ### <a id="differences-1x-2-custom-variables"></a> Custom Variables
Icinga 1.x custom variable attributes must be prefixed using an underscore (`_`). Icinga 1.x custom variable attributes must be prefixed using an underscore (`_`).
In Icinga 2 these attributes must be added to the `custom`dictionary. 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** > **Note**
> >
> If you are planning to access custom variables as runtime macros you should > If you are planning to access custom variables as runtime macros you may access
> add them to the macros dictionary instead! > them with `_HOST`name as known from Icinga 1.x
## Host Service Relation ## <a id="differences-1x-2-host-service-relation"></a> Host Service Relation
In Icinga 1.x a service object is associated with a host by defining the 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 `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 Linking a service to a host is still possible with the 'host' attribute in
a service object in Icinga 2. a service object in Icinga 2.
## Users ## <a id="differences-1x-2-users"></a> Users
Contacts have been renamed to Users (same for groups). A user does not Contacts have been renamed to Users (same for groups). A user does not
only provide attributes and macros used for notifications, but is also 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, reasons. These values are calculated from all services, their notifications,
and their users. and their users.
## Macros ## <a id="differences-1x-2-macros"></a> Macros
Various object attributes and runtime variables can be accessed as macros in Various object attributes and runtime variables can be accessed as macros in
commands in Icinga 1.x - Icinga 2 supports all required [macros](#macros). 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 CONTACTPAGER | USERPAGER
### Command Macros ### <a id="differences-1x-2-command-macros"></a> Command Macros
If you have previously used Icinga 1.x you may already be familiar with 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 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 > $USER1$ macro. It also replaces the Icinga 1.x notation with $ARGn$ with freely
> definable macros. > definable macros.
### Environment Macros ### <a id="differences-1x-2-environment-macros"></a> Environment Macros
The global configuration setting `enable_environment_macros` does not exist in The global configuration setting `enable_environment_macros` does not exist in
Icinga 2. Icinga 2.
@ -293,15 +293,15 @@ Icinga 2.
Macros exported into the environment must be set using the `export_macros` Macros exported into the environment must be set using the `export_macros`
attribute in command objects. attribute in command objects.
## Checks ## <a id="differences-1x-2-checks"></a> Checks
### Host Check ### <a id="differences-1x-2-host-check"></a> Host Check
Unlike in Icinga 1.x hosts are not checkable objects in Icinga 2. Instead hosts 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` inherit their state from the service that is specified using the `check`
attribute. attribute.
### Check Output ### <a id="differences-1x-2-check-output"></a> Check Output
Icinga 2 does not make a difference between `output` (first line) and Icinga 2 does not make a difference between `output` (first line) and
`long_output` (remaining lines) like in Icinga 1.x. Performance Data is `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 split the raw output into `output` (first line) and `long_output` (remaining
lines) for compatibility reasons. lines) for compatibility reasons.
### Initial State ### <a id="differences-1x-2-initial-state"></a> Initial State
Icinga 1.x uses the `max_service_check_spread` setting to specify a timerange 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 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` setting instead and `check_interval` divided by 5 if
`retry_interval` is not defined. `retry_interval` is not defined.
### Performance Data ### <a id="differences-1x-2-performance-data"></a> Performance Data
There is no host performance data generated in Icinga 2 because there are no There is no host performance data generated in Icinga 2 because there are no
real host checks. Therefore the PerfDataWriter will only write service real host checks. Therefore the PerfDataWriter will only write service
performance data files. performance data files.
## Commands ## <a id="differences-1x-2-commands"></a> Commands
Unlike in Icinga 1.x there are 3 different command types in Icinga 2: Unlike in Icinga 1.x there are 3 different command types in Icinga 2:
`CheckCommand`, `NotificationCommand` and EventCommand`. `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 It's also possible to define default macros for the command itself which can be
overridden by a service macro. overridden by a service macro.
## Groups ## <a id="differences-1x-2-groups"></a> Groups
In Icinga 2 hosts, services and users are added to groups using the `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 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 of that group. The example above shows how to use templates to accomplish
the same effect. the same effect.
## Notifications ## <a id="differences-1x-2-notifications"></a> Notifications
Notifications are a new object type in Icinga 2. Imagine the following Notifications are a new object type in Icinga 2. Imagine the following
notification configuration problem in Icinga 1.x: notification configuration problem in Icinga 1.x:
@ -415,7 +415,7 @@ In Icinga 2 it will look like this:
Service -> Notification -> NotificationCommand Service -> Notification -> NotificationCommand
-> User, UserGroup -> User, UserGroup
### Escalations ### <a id="differences-1x-2-escalations"></a> Escalations
Escalations in Icinga 1.x require a separated object matching on existing Escalations in Icinga 1.x require a separated object matching on existing
objects. Escalations happen between a defined start and end time which is 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 That's not necessary with Icinga 2 only requiring an additional notification
object for the escalation itself. object for the escalation itself.
### Notification Options ### <a id="differences-1x-2-notification-options"></a> Notification Options
Unlike Icinga 1.x with the 'notification_options' attribute with comma-separated Unlike Icinga 1.x with the 'notification_options' attribute with comma-separated
state and type filters, Icinga 2 uses two configuration attributes for that. 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 state and type filters are only valid configuration attributes for
> `Notification` and `User` objects. > `Notification` and `User` objects.
## Dependencies and Parents ## <a id="differences-1x-2-dependencies-parents"></a> Dependencies and Parents
In Icinga 1.x it's possible to define host parents to determine network reachability In Icinga 1.x it's possible to define host parents to determine network reachability
and keep a host's state unreachable rather than down. and 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 support the Icinga 1.x schema with dependencies and parent attributes for
compatibility reasons. compatibility reasons.
## Flapping ## <a id="differences-1x-2-flapping"></a> Flapping
The Icinga 1.x flapping detection uses the last 21 states of a service. This 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 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 threshold from a single value based on counters and half-life values. Icinga 2 compares
the value with a single flapping threshold configuration attribute. the value with a single flapping threshold configuration attribute.
## Check Result Freshness ## <a id="differences-1x-2-check-result-freshness"></a> Check Result Freshness
Freshness of check results must be explicitely enabled in Icinga 1.x. The attribute Freshness 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 `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 `freshness_threshold` attribute in Icinga 2. If the freshness checks are invalid, a new
service check is forced. service check is forced.
## State Retention ## <a id="differences-1x-2-state-retention"></a> State Retention
Icinga 1.x uses the `retention.dat` file to save its state in order to be able 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`. 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. The format objects are stored in is not compatible with Icinga 1.x.
## Logging ## <a id="differences-1x-2-logging"></a> Logging
Icinga 1.x supports syslog facilities and writes its own `icinga.log` log file 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 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. FileLogger, StreamLogger. Each of them got their own severity and target configuration.
## Broker Modules and Features ## <a id="differences-1x-2-broker-modules-features"></a> Broker Modules and Features
Icinga 1.x broker modules are incompatible with Icinga 2. 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. objects work in Icinga 2 it is possible to set up multiple IDO database instances.
## Distributed Monitoring ## <a id="differences-1x-2-distributed-monitoring"></a> Distributed Monitoring
Icinga 1.x uses the native "obsess over host/service" method which requires the NSCA addon 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. passing the slave's checkresults passively onto the master's external command pipe.

4
doc/9-vagrant-demo-vm.md
View File

@ -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`. The username is `root` and the password is `password`.
SSH login is available using `vagrant ssh`. SSH login is available using `vagrant ssh`.
## <a id="vagrant-windows"></a> Vagrant on Windows
TODO