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

Update documentation

This commit is contained in:
Gunnar Beutner 2015-01-25 16:07:43 +01:00
parent 7bbb1ee7bf
commit 775ed474d7
7 changed files with 89 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/10-alternative-frontends.md
View File

@ -62,7 +62,7 @@ Therefore you need to setup the [DB IDO feature](2-getting-started.md#configurin
### <a id="installing-icinga-web"></a> Installing Icinga Web 1.x
The Icinga package repository has both Debian and RPM packages. You can install
Icinga Web using the following packages (RPMs ship an additional configuration package):
Icinga Web using the following packages:
Distribution | Packages
--------------|-------------------------------------------------------
@ -76,7 +76,6 @@ Details can be found in the package `README` files, for example [README.RHEL](ht
The Icinga Web RPM packages install the schema files into
`/usr/share/doc/icinga-web-*/schema` (`*` means package version).
The Icinga Web dist tarball ships the schema files in `etc/schema`.
On SuSE-based distributions the schema files are installed in
`/usr/share/doc/packages/icinga-web/schema`.

4
doc/12-troubleshooting.md
View File

@ -91,13 +91,13 @@ You can also filter by name and type:
## <a id="check-command-definitions"></a> Where are the check command definitions?
Icinga 2 ships additional [plugin check command definitions](6-icinga-template-library.md#plugin-check-commands) which are
Icinga 2 features a number of built-in [check command definitions](6-icinga-template-library.md#plugin-check-commands) which are
included using
include <itl>
include <plugins>
in the [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) configuration file. These configurations will be overridden
in the [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf) configuration file. These files are not considered configuration files and will be overridden
on upgrade, so please send modifications as proposed patches upstream. The default include path is set to
`LocalStateDir + "/share/icinga2/includes"`.

109
doc/2-getting-started.md
View File

@ -45,12 +45,13 @@ Ubuntu (PPA):
RHEL/CentOS:
# rpm --import http://packages.icinga.org/icinga.key
# wget http://packages.icinga.org/epel/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
# curl -o /etc/yum.repos.d/ICINGA-release.repo http://packages.icinga.org/epel/ICINGA-release.repo
# yum makecache
Fedora:
# wget http://packages.icinga.org/fedora/ICINGA-release.repo -O /etc/yum.repos.d/ICINGA-release.repo
# rpm --import http://packages.icinga.org/icinga.key
# curl -o /etc/yum.repos.d/ICINGA-release.repo http://packages.icinga.org/fedora/ICINGA-release.repo
# yum makecache
SLES:
@ -96,13 +97,6 @@ RHEL/CentOS 7 and Fedora use [systemd](2-getting-started.md#systemd-service):
# systemctl enable icinga2
# systemctl start icinga2
Some parts of Icinga 2's functionality are available as separate packages:
Name | Description
------------------------|--------------------------------
icinga2-ido-mysql | [DB IDO](2-getting-started.md#configuring-db-ido) provider module for MySQL
icinga2-ido-pgsql | [DB IDO](2-getting-started.md#configuring-db-ido) provider module for PostgreSQL
### <a id="installation-enabled-features"></a> Enabled Features during Installation
The default installation will enable three features required for a basic
@ -214,7 +208,7 @@ SUSE:
RHEL based distributions do not automatically set a secure root password. Do that **now**:
# /usr/bin/mysql_secure_installation
# mysql_secure_installation
#### <a id="installing-database-mysql-modules"></a> Installing the IDO modules for MySQL
@ -236,9 +230,9 @@ SUSE:
> **Note**
>
> Upstream Debian packages provide a database configuration wizard by default.
> You can skip the automated setup and install/upgrade the database manually
> if you prefer that.
> The Debian/Ubuntu packages provide a database configuration wizard by
> default. You can skip the automated setup and install/upgrade the
> database manually if you prefer that.
#### <a id="setting-up-mysql-db"></a> Setting up the MySQL database
@ -248,7 +242,6 @@ Set up a MySQL database for Icinga 2:
mysql> CREATE DATABASE icinga;
GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga';
quit
After creating the database you can import the Icinga 2 IDO schema using the
following command:
@ -259,10 +252,11 @@ following command:
#### <a id="enabling-ido-mysql"></a> Enabling the IDO MySQL module
The package provides a new configuration file that is installed in
`/etc/icinga2/features-available/ido-mysql.conf`. You will need to update the
database credentials in this file.
All available attributes are listed in the
[IdoMysqlConnection object](5-object-types.md#objecttype-idomysqlconnection) configuration details.
`/etc/icinga2/features-available/ido-mysql.conf`. You will need to
update the database credentials in this file.
All available attributes are explained in the
[IdoMysqlConnection object](5-object-types.md#objecttype-idomysqlconnection) chapter.
You can enable the `ido-mysql` feature configuration file using `icinga2 feature enable`:
@ -373,10 +367,11 @@ using the following command:
#### <a id="enabling-ido-postgresql"></a> Enabling the IDO PostgreSQL module
The package provides a new configuration file that is installed in
`/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update the
database credentials in this file.
All available attributes are listed in the
[IdoPgsqlConnection object](5-object-types.md#objecttype-idopgsqlconnection) configuration details.
`/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update
the database credentials in this file.
All available attributes are explained in the
[IdoPgsqlConnection object](5-object-types.md#objecttype-idopgsqlconnection) chapter.
You can enable the `ido-pgsql` feature configuration file using `icinga2 feature enable`:
@ -427,10 +422,9 @@ The webserver's user is different between distributions so you might have to cha
Change "www-data" to the user you're using to run queries.
> **Note**
>
> Packages will do that automatically. Verify that by running `id <your-webserver-user>` and skip this
> step.
You can verify that the user has been successfully added to the `icingacmd` group using the `id` command:
id <your-webserver-user>
## <a id="running-icinga2"></a> Running Icinga 2
@ -441,6 +435,8 @@ Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
# /etc/init.d/icinga2
Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
The init script supports the following actions:
Command | Description
--------------------|------------------------
start | The `start` action starts the Icinga 2 daemon.
@ -451,15 +447,15 @@ Icinga 2's init script is installed in `/etc/init.d/icinga2` by default:
status | The `status` action checks if Icinga 2 is running.
By default the Icinga 2 daemon is running as `icinga` user and group
using the init script. Using Debian packages the user and group are set to `nagios`
for historical reasons.
using the init script. Using Debian packages the user and group are set to
`nagios` for historical reasons.
### <a id="systemd-service"></a> systemd Service
Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The Icinga 2
packages automatically install the necessary systemd unit files.
Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The
Icinga 2 packages automatically install the necessary systemd unit files.
The Icinga 2 systemd service can be (re)started, reloaded, stopped and also queried for its current status.
The Icinga 2 systemd service can be (re-)started, reloaded, stopped and also queried for its current status.
# systemctl status icinga2
icinga2.service - Icinga host/service/network monitoring system
@ -491,19 +487,22 @@ The `systemctl` command supports the following actions:
status | The `status` action checks if Icinga 2 is running.
enable | The `enable` action enables the service being started at system boot time (similar to `chkconfig`)
If you're stuck with configuration errors, you can manually invoke the [configuration validation](7-cli-commands.md#config-validation).
Examples:
# systemctl enable icinga2
# systemctl restart icinga2
Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details.
If you're stuck with configuration errors, you can manually invoke the [configuration validation](7-cli-commands.md#config-validation).
## <a id="setting-up-the-user-interface"></a> Setting up the User Interface
Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces. This chapter explains how
to set up Icinga Web 2. The [Alternative Frontends](10-alternative-frontends.md#alternative-frontends) chapter can be used as a
starting point for installing some of the other web interfaces which are also available.
Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces.
This chapter explains how to set up Icinga Web 2. The
[Alternative Frontends](10-alternative-frontends.md#alternative-frontends)
chapter can be used as a starting point for installing some of the other web
interfaces which are also available.
#### <a id="icinga2-user-interface-webserver"></a> Webserver
@ -512,17 +511,22 @@ Debian/Ubuntu:
# apt-get install apache2
RHEL/CentOS/Fedora:
RHEL/CentOS 6:
# yum install httpd
# chkconfig httpd on && service httpd start
## RHEL7
# systemctl enable httpd && systemctl start httpd
# chkconfig httpd on
# service httpd start
RHEL/CentOS 7/Fedora:
# systemctl enable httpd
# systemctl start httpd
SUSE:
# zypper install apache2
# chkconfig on && service apache2 start
# chkconfig on
# service apache2 start
#### <a id="icinga2-user-interface-firewall-rules"></a> Firewall Rules
@ -538,30 +542,19 @@ RHEL/CentOS 7 specific:
### <a id="setting-up-icingaweb2"></a> Setting up Icinga Web 2
Icinga Web 2 supports `DB IDO` or `Livestatus` as backends.
Icinga Web 2 currently requires `DB IDO` as a backend. You need to install and configure the [DB IDO backend](2-getting-started.md#configuring-db-ido) if you
haven't already done so.
Using DB IDO as backend, you need to install and configure the
[DB IDO backend](2-getting-started.md#configuring-db-ido).
In order to use commands in Web 2 you will also need to [set up the external command pipe](2-getting-started.md#setting-up-external-command-pipe).
In order to use commands in Web 2 you need to [set up the external command pipe](2-getting-started.md#setting-up-external-command-pipe).
[Icinga Web 2](https://github.com/Icinga/icingaweb2) features a
web-based setup wizard which will guide you through the setup process.
[Icinga Web 2](https://github.com/Icinga/icingaweb2) ships its own
web-based setup wizard which will guide you through the entire setup process.
Generate the Webserver configuration and a setup token using its local cli
and proceed with the web setup when accessing `/icingaweb2` after reloading
your webserver configuration.
Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/installation.md)
shipped with `Icinga Web 2` for further instructions on how to install
`Icinga Web 2` and to configure backends, resources and instances manually.
Check the [Icinga website](https://www.icinga.org) for release announcements
and packages.
Please consult the [installation documentation](https://github.com/Icinga/icingaweb2/blob/master/doc/installation.md) for further instructions on how to install `Icinga Web 2`.
### <a id="install-addons"></a> Addons
A number of additional features are available in the form of plugins. A list of popular
A number of additional features are available in the form of addons. A list of popular
addons is available in the [Addons and Plugins](9-addons-plugins.md#addons-plugins) chapter.

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

@ -307,7 +307,7 @@ The notification is ignored for services whose host name ends with `*internal`
#### <a id="using-apply-services"></a> Apply Services to Hosts
The sample configuration already ships a detailed example in [hosts.conf](4-configuring-icinga-2.md#hosts-conf)
The sample configuration already includes a detailed example in [hosts.conf](4-configuring-icinga-2.md#hosts-conf)
and [services.conf](4-configuring-icinga-2.md#services-conf) for this use case.
The example for `ssh` applies a service object to all hosts with the `address`
@ -350,7 +350,7 @@ Detailed examples can be found in the [dependencies](3-monitoring-basics.md#depe
#### <a id="using-apply-scheduledowntimes"></a> Apply Recurring Downtimes to Hosts and Services
The sample confituration ships an example in [downtimes.conf](4-configuring-icinga-2.md#downtimes-conf).
The sample confituration includes an example in [downtimes.conf](4-configuring-icinga-2.md#downtimes-conf).
Detailed examples can be found in the [recurring downtimes](3-monitoring-basics.md#recurring-downtimes) chapter.
@ -362,7 +362,7 @@ apply rules objects based on set (array or dictionary). That way you'll save qui
of a lot of duplicated apply rules by combining them into one generic generating
the object name with or without a prefix.
The sample configuration already ships a detailed example in [hosts.conf](4-configuring-icinga-2.md#hosts-conf)
The sample configuration already includes a detailed example in [hosts.conf](4-configuring-icinga-2.md#hosts-conf)
and [services.conf](4-configuring-icinga-2.md#services-conf) for this use case.
Imagine a different example: You are monitoring your switch (hosts) with many
@ -619,7 +619,7 @@ to the defined notifications. That way you'll save duplicated attributes in each
period = "24x7"
}
The time period `24x7` is shipped as example configuration with Icinga 2.
The time period `24x7` is included as example configuration with Icinga 2.
Use the `apply` keyword to create `Notification` objects for your services:
@ -905,7 +905,7 @@ using the `check_command` attribute.
Unless you have done so already, download your check plugin and put it
into the [PluginDir](4-configuring-icinga-2.md#constants-conf) directory. The following example uses the
`check_disk` plugin shipped with the Monitoring Plugins package.
`check_disk` plugin contained in the Monitoring Plugins package.
The plugin path and all command arguments are made a list of
double-quoted string arguments for proper shell escaping.
@ -2494,7 +2494,7 @@ skipping the external command pipe.
Several clustered/distributed environments and check-aggregation addons
use that method. In order to support step-by-step migration of these
environments, Icinga 2 ships the `CheckResultReader` object.
environments, Icinga 2 supports the `CheckResultReader` object.
There is no feature configuration available, but it must be defined
on-demand in your Icinga 2 objects configuration.

38
doc/4-configuring-icinga-2.md
View File

@ -79,21 +79,15 @@ and their generated configuration described in
You can put your own configuration files in the [conf.d](4-configuring-icinga-2.md#conf-d) directory. This
directive makes sure that all of your own configuration files are included.
> **Tip**
>
> The example configuration is shipped in this directory too. You can either
> remove it entirely, or adapt the existing configuration structure with your
> own object configuration.
## <a id="constants-conf"></a> constants.conf
The `constants.conf` configuration file can be used to define global constants.
By default, you need to make sure to set these constants:
* The `PluginDir` constant must be pointed to your [check plugins](2-getting-started.md#setting-up-check-plugins) path.
This constant is required by the shipped
[plugin check command configuration](6-icinga-template-library.md#plugin-check-commands).
* The `PluginDir` constant must be set to the path where the [Monitoring Project plugins](2-getting-started.md#setting-up-check-plugins) are installed.
This constant is used by a number of
[built-in check command definitions](6-icinga-template-library.md#plugin-check-commands).
* The `NodeName` constant defines your local node name. Should be set to FQDN which is the default
if not set. This constant is required for local host configuration, monitoring remote clients and
cluster setup.
@ -139,7 +133,7 @@ way of deploying Icinga 2 configuration.
Further details on configuration best practice and how to build your
own strategy is described in [this chapter](3-monitoring-basics.md#configuration-best-practice).
Available configuration files shipped by default:
Available configuration files which are installed by default:
* [hosts.conf](4-configuring-icinga-2.md#hosts-conf)
* [services.conf](4-configuring-icinga-2.md#services-conf)
@ -265,7 +259,7 @@ Service(s) | Applied on host(s)
`http`, optional: `Icinga Web 2` | All hosts with custom attribute `http_vhosts` defined as dictionary
`disk`, `disk /` | All hosts with custom attribute `disks` defined as dictionary
The Debian packages also ship an additional `apt` service check applied to the local host.
The Debian packages also include an additional `apt` service check applied to the local host.
The command object `icinga` for the embedded health check is provided by the
[Icinga Template Library (ITL)](6-icinga-template-library.md#icinga-template-library) while `http_ip`, `ssh`, `load`, `processes`,
@ -415,7 +409,7 @@ Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is u
Notifications for check alerts are an integral part or your
Icinga 2 monitoring stack.
The shipped example defines two notification apply rules for hosts and services.
The examples in this file define two notification apply rules for hosts and services.
Both `apply` rules match on the same condition: They are only applied if the
nested dictionary attribute `notification.mail` is set.
@ -453,12 +447,6 @@ filters can be read in [this chapter](3-monitoring-basics.md#notifications).
This is the place where your own command configuration can be defined. By default
only the notification commands used by the notification templates defined in [templates.conf](4-configuring-icinga-2.md#templates-conf).
> **Tip**
>
> Icinga 2 ships the most common command definitions already in the
> [Plugin Check Commands](6-icinga-template-library.md#plugin-check-commands) definitions. More details on
> that topic in the [troubleshooting section](12-troubleshooting.md#check-command-definitions).
You can freely customize these notification commands, and adapt them for your needs.
Read more on that topic [here](3-monitoring-basics.md#notification-commands).
@ -508,12 +496,8 @@ and the attribute string to match with.
### <a id="templates-conf"></a> templates.conf
All shipped example configuration objects use generic global templates by
default. Be it setting a default `check_command` attribute in the `generic-host`
templates for your hosts defined in [hosts.conf](4-configuring-icinga-2.md#hosts-conf), or defining
the default `states` and `types` filters for notification apply rules defined in
[notifications.conf](4-configuring-icinga-2.md#notifications-conf).
Most of the example configuration objects use generic global templates by
default:
template Host "generic-host" {
max_check_attempts = 5
@ -529,7 +513,7 @@ the default `states` and `types` filters for notification apply rules defined in
retry_interval = 30s
}
The `hostalive` check command is shipped with Icinga 2 in the
The `hostalive` check command is part of the
[Plugin Check Commands](6-icinga-template-library.md#plugin-check-commands).
@ -586,14 +570,14 @@ to define the default value for the time ranges required for recurring downtime
### <a id="timeperiods-conf"></a> timeperiods.conf
This file ships the default timeperiod definitions for `24x7`, `9to5`
This file contains the default timeperiod definitions for `24x7`, `9to5`
and `never`. Timeperiod objects are referenced by `*period`
objects such as hosts, services or notifications.
### <a id="satellite-conf"></a> satellite.conf
Ships default templates and dependencies for [monitoring remote clients](8-monitoring-remote-systems.md#icinga2-remote-client-monitoring)
Includes default templates and dependencies for [monitoring remote clients](8-monitoring-remote-systems.md#icinga2-remote-client-monitoring)
using service discovery and [config generation](8-monitoring-remote-systems.md#icinga2-remote-monitoring-master-discovery-generate-config)
on the master. Can be ignored/removed on setups not using this features.

14
doc/7-cli-commands.md
View File

@ -1,6 +1,6 @@
## <a id="cli-commands"></a> Icinga 2 CLI Commands
Icinga 2 ships its own integrated CLI commands supporting bash-autocompletion.
Icinga 2 comes with a number of CLI commands which support bash autocompletion.
These CLI commands will allow you to use certain functionality
provided by and around the Icinga 2 daemon.
@ -12,7 +12,6 @@ Run `icinga2` without any arguments to get a list of all available global
options.
# icinga2
icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
Usage:
@ -181,9 +180,7 @@ is returned. More details in the [configuration validation](7-cli-commands.md#co
### <a id="cli-command-feature"></a> CLI command: Feature
The CLI commands for `enable` and `disable` feature support bash auto-completion
and will only suggest features for the corresponding context. Like disabling a
feature will only bring up all enabled features.
The `feature enable` and `feature disable` commands can be used to enable and disable features:
# icinga2 feature disable <tab>
checker --color --define --help --include --library --log-level mainlog notification --version
@ -192,6 +189,13 @@ feature will only bring up all enabled features.
api command debuglog graphite icingastatus ido-pgsql --library --log-level statusdata --version
--color compatlog --define --help ido-mysql --include livestatus perfdata syslog
The `feature list` command shows which features are currently enabled:
# icinga2 feature list
Disabled features: agent command compatlog debuglog gelf graphite icingastatus notification perfdata statusdata syslog
Enabled features: api checker livestatus mainlog
### <a id="cli-command-node"></a> CLI command: Node
Provides the functionality to install and manage master and client

11
doc/9-addons-plugins.md
View File

@ -123,15 +123,12 @@ Example for a custom `my-snmp-int` check command:
vars.snmp_crit = "0,600"
}
You can find an existing `CheckCommand` definition for the `check_snmp_int.pl` plugin
shipped with the optional [Manubulon Plugin Check Command](6-icinga-template-library.md#snmp-manubulon-plugin-check-commands)
definitions already.
Icinga 2 has built-in check command definitions for the [Manubulon Plugin Checks](6-icinga-template-library.md#snmp-manubulon-plugin-check-commands).
For further information on your monitoring configuration read the
[monitoring basics](3-monitoring-basics.md#monitoring-basics).
You can find plugins (additional to the ones at [Monitoring Plugins](https://www.monitoring-plugins.org)) over at
[Icinga Exchange](https://exchange.icinga.org)
[Monitoring Basics](3-monitoring-basics.md#monitoring-basics) chapter.
You can find additional plugins at the [Icinga Exchange](https://exchange.icinga.org)
More details on the plugins can also be found on the Icinga Wiki at https://wiki.icinga.org