tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Documentation: Add unique section ids. 

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
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
## <a id="licensing"></a> 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
## <a id="support"></a> 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].
## <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").
* 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

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
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.

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
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
### <a id="installation-paths"></a> 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
### <a id="icinga2-conf"></a> 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
### <a id="macros-conf"></a> 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
### <a id="localhost-conf"></a> localhost.conf
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
[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
### <a id="integrate-additional-plugins"></a> 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

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
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
### <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
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
#### <a id="upgrading-mysql-db"></a> Upgrading the MySQL database
If the database has been installed and requires an upgrade, verify the current
schema version first:
@ -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
#### <a id="installing-ido-mysql"></a> Installing the IDO MySQL module
The package provides a new configuration file that is installed in
`/etc/icinga2/features-available/ido-mysql.conf`. You will need to update the
@ -90,7 +92,7 @@ After enabling the ido-mysql feature you have to restart Icinga 2:
# /etc/init.d/icinga2 restart
### Configuring IDO PostgreSQL
### <a id="configuring-ido-postgresql"></a> 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
#### <a id="upgrading-postgresql-db"></a> Upgrading the PostgreSQL database
If the database has been installed and requires an upgrade, verify the current
schema version first:
@ -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
#### <a id="installing-ido-postgresql"></a> Installing the IDO PostgreSQL module
The package provides a new configuration file that is installed in
`/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update the

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
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 @@
## Setting up Icinga 2 User Interfaces
## <a id="setting-up-icinga2-user-interfaces"></a> Setting up Icinga 2 User Interfaces
Icinga 2 is compatible to Icinga 1.x user interfaces by providing additional
features required as backends.
@ -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.
### <a id="setting-up-icinga-classic-ui"></a> Setting up Icinga Classic UI
Icinga 2 can write `status.dat` and `objects.cache` files in the format that
is supported by the Icinga 1.x Classic UI. External commands (a.k.a. the
"command pipe") are also supported. It also supports writing Icinga 1.x
log files which are required for the reporting functionality in the Classic UI.
#### 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 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
### <a id="setting-up-icinga-web"></a> Setting up Icinga Web
Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which
is an explicit requirement to run `Icinga Web` next to the external command pipe.
Therefore you need to setup the DB IDO feature remarked in the previous sections.
#### 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 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.
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
### <a id="additional-visualization"></a> Additional visualization
There are many addons in the wild which are using Icinga 1.x backends and
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:

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
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
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
### <a id="host-states"></a> 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
### <a id="service-states"></a> 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
### <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
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
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
### <a id="environment-macros"></a> 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
### <a id="check-commands"></a> Check Commands
`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
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
### <a id="event-commands"></a> Event Commands
Unlike notifications event commands are called on every service state change
if defined. Therefore the `EventCommand` object should define a command line

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.
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
### <a id="notification-escalations"></a> Notification Escalations
When a problem notification is sent and a problem still exists after re-notification
you may want to escalate the problem to the next support level. A different approach
@ -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
### <a id="first-notification-delay"></a> First Notification Delay
Sometimes the problem in question should not be notified when the first notification
happens, but a defined time duration afterwards. In Icinga 2 you can use the `times`
@ -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
### <a id="notification-filters-state-type"></a> Notification Filters by State and Type
If there are no notification state and type filter attributes defined at the `Notification`
or `User` object Icinga 2 assumes that all states and types are being notified.

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
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
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
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
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
### <a id="external-command-list"></a> 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).

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.

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:

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
`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
### <a id="writing-performance-data-files"></a> 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
### <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
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
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`
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

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
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

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
definitions for commonly used services.
@ -10,9 +10,9 @@ file:
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.
@ -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
### <a id="itl-ping6"></a> 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
### <a id="itl-dummy"></a> 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
### <a id="itl-passive"></a> 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
### <a id="itl-tcp"></a> 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
### <a id="itl-udp"></a> 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
### <a id="itl-http-vhost"></a> 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
### <a id="itl-http-ip"></a> 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
### <a id="itl-https-vhost"></a> 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
### <a id="itl-https-ip"></a> 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
### <a id="itl-smtp"></a> 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
### <a id="itl-ssmtp"></a> 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
### <a id="itl-ntp-time"></a> 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
### <a id="itl-ssh"></a> 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
### <a id="itl-disk"></a> 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
### <a id="itl-users"></a> 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
### <a id="itl-processes"></a> 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
### <a id="itl-load"></a> 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
### <a id="itl-snmp"></a> 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
### <a id="itl-snmp-uptime"></a> 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
### <a id="itl-icinga"></a> icinga
Check command for the built-in `icinga` check. This check returns performance
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
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
### <a id="fixed-flexible-downtimes"></a> Fixed and Flexible Downtimes
A `fixed` downtime will be activated at the defined start time, and
removed at the end time. During this time window the service state
@ -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
### <a id="scheduling-downtime"></a> Scheduling a downtime
This can either happen through a web interface (Icinga 1.x Classic UI or Web)
or by using the external command pipe provided by the `ExternalCommandListener`
@ -60,7 +60,7 @@ independent from that time span.
>
> 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
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
### <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
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
## <a id="acknowledgements"></a> Acknowledgements
If a problem is alerted and notified you may signal the other notification
receipients that you are aware of the problem and will handle it.
@ -94,7 +130,7 @@ to all notified users.
>
> 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`
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
## <a id="cluster"></a> 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
### <a id="certificate-authority-certificates"></a> 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
### <a id="enable-cluster-configuration"></a> 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
### <a id="configure-clusterlistener-object"></a> 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
### <a id="configure-cluster-endpoints"></a> 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
### <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
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
### <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`
feature enabled.
@ -260,7 +296,7 @@ attribute. Required Endpoints must be defined as array.
> defining the authorities.
## Dependencies
## <a id="dependencies"></a> 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
## <a id="check-result-freshness"></a> Check Result Freshness
In Icinga 2 active check freshness is enabled by default. It is determined by the
`check_interval` attribute and no incoming check results in that period of time.
@ -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
## <a id="check-flapping"></a> Check Flapping
The flapping algorithm used in Icinga 2 does not store the past states but
calculcates the flapping threshold from a single value based on counters and
@ -328,7 +364,7 @@ configuration attribute named `flapping_threshold`.
> Flapping must be explicitely enabled seting the `Service` object attribute
> `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
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
## <a id="modified-attributes"></a> Modified Attributes
Icinga 2 allows you to modify defined object attributes at runtime different to
the local configuration object attributes. These modified attributes are
@ -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
## <a id="plugin-api"></a> 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
### <a id="monitoring-plugin-api"></a> 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).

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
order to ease migration from Icinga 1.x,
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
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
### <a id="manual-config-migration"></a> Manual Config Migration
For a long-term migration of your configuration you should consider re-creating
your configuration based on the Icinga 2 proposed way of doing configuration right.
Please read the next chapter 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
## 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.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
### <a id="differences-1x-2-sample-configuration-itl"></a> Sample Configuration and ITL
While Icinga 1.x ships sample configuration and templates spread in various
object files Icinga 2 moves all templates into the Icinga Template Library (ITL)
@ -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
### <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`
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
## <a id="differences-1x-2-resource-file-global-macros"></a> Resource File and Global Macros
Global macros such as for the plugin directory, usernames and passwords can be
set in the `resource.cfg` configuration file in Icinga 1.x. By convention the
@ -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 (`;`)
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
## <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
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
## <a id="differences-1x-2-templates"></a> Templates
In Icinga 1.x templates are identified using the `register 0` setting. Icinga 2
uses the `template` identifier:
@ -118,7 +118,7 @@ comma-separated list with template names in double quotes.
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
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
### <a id="differences-1x-2-alias-display-name"></a> Alias vs. Display Name
In Icinga 1.x a host can have an `alias` and a `display_name` attribute used
for a more descriptive name. A service only can have a `display_name` attribute.
@ -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
## <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
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
### <a id="differences-1x-2-custom-variables"></a> Custom Variables
Icinga 1.x custom variable attributes must be prefixed using an underscore (`_`).
In Icinga 2 these attributes must be added to the `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
## <a id="differences-1x-2-host-service-relation"></a> Host Service Relation
In Icinga 1.x a service object is associated with a host by defining the
`host_name` attribute in the service definition. Alternate methods refer
@ -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
## <a id="differences-1x-2-users"></a> Users
Contacts have been renamed to Users (same for groups). A user does not
only provide attributes and 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
## <a id="differences-1x-2-macros"></a> Macros
Various object attributes and runtime variables can be accessed as macros in
commands in Icinga 1.x - Icinga 2 supports all required [macros](#macros).
@ -241,7 +241,7 @@ commands in Icinga 1.x - Icinga 2 supports all required [macros](#macros).
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
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
### <a id="differences-1x-2-environment-macros"></a> 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
## <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
inherit their state from the service that is specified using the `check`
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
`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
### <a id="differences-1x-2-initial-state"></a> Initial State
Icinga 1.x uses the `max_service_check_spread` setting to specify a timerange
where the initial state checks must have happened. Icinga 2 will use the
`retry_interval` setting instead and `check_interval` divided by 5 if
`retry_interval` is not defined.
### 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
real host checks. Therefore the PerfDataWriter will only write service
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:
`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
## <a id="differences-1x-2-groups"></a> Groups
In Icinga 2 hosts, services and users are added to groups using the `groups`
attribute in the object. The old way of listing all group members in the group's
@ -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
## <a id="differences-1x-2-notifications"></a> Notifications
Notifications are a new object type in Icinga 2. Imagine the following
notification configuration problem in Icinga 1.x:
@ -415,7 +415,7 @@ In Icinga 2 it will look like this:
Service -> Notification -> NotificationCommand
-> User, UserGroup
### Escalations
### <a id="differences-1x-2-escalations"></a> Escalations
Escalations in Icinga 1.x require a separated object matching on existing
objects. Escalations happen between a defined start and end time which is
@ -439,7 +439,7 @@ happens.
That's not necessary with Icinga 2 only requiring an additional notification
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
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
## <a id="differences-1x-2-dependencies-parents"></a> Dependencies and Parents
In Icinga 1.x it's possible to define host parents to determine network reachability
and keep a host's state unreachable rather than down.
@ -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
## <a id="differences-1x-2-flapping"></a> Flapping
The Icinga 1.x flapping detection uses the last 21 states of a service. This
value is hardcoded and cannot be changed. The algorithm on determining a flapping state
@ -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
## <a id="differences-1x-2-check-result-freshness"></a> Check Result Freshness
Freshness of check results must be explicitely enabled in Icinga 1.x. The attribute
`freshness_treshold` defines the threshold in seconds. Once the threshold is triggered, an
@ -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
## <a id="differences-1x-2-state-retention"></a> State Retention
Icinga 1.x uses the `retention.dat` file to save its state in order to be able
to reload it after a restart. In Icinga 2 this file is called `icinga2.state`.
The format objects are stored in is not compatible with Icinga 1.x.
## Logging
## <a id="differences-1x-2-logging"></a> Logging
Icinga 1.x supports syslog facilities and writes its own `icinga.log` log file
and archives. These logs are used in Icinga 1.x Classic UI to generate
@ -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
## <a id="differences-1x-2-broker-modules-features"></a> 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
## <a id="differences-1x-2-distributed-monitoring"></a> Distributed Monitoring
Icinga 1.x uses the native "obsess over host/service" method which requires the NSCA addon
passing the slave's checkresults passively onto the master's external command pipe.

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