Update documentation.

This commit is contained in:
Gunnar Beutner 2013-10-02 09:50:26 +02:00
parent ddfe45031b
commit 115aea29a0
20 changed files with 236 additions and 241 deletions

25
INSTALL
View File

@ -43,19 +43,22 @@ User Requirements
-----------------
By default Icinga will run as user 'icinga' and group 'icinga'. Additionally the
ExternalCommandListener and LivestatusListener require a dedicated command group
'icingacmd'. You can choose your own user/group names and pass them to configure
later.
external command pipe and livestatus features require a dedicated command group
'icingacmd'. You can choose your own user/group names and pass them to the
configure script using the --with-icinga-user, --with-icinga-group,
--with-icingacmd-user and --with-icingacmd-group options.
# groupadd icinga
# groupadd icingacmd
# useradd -c "icinga" -s /sbin/nologin -G icingacmd -g icinga
Add the webserver user to the icingacmd group for granting write permissions.
Change 'www-data' to your distribution specific webserver user.
Add the web server user to the icingacmd group in order to grant it write
permissions to the external command pipe and livestatus socket:
# usermod -a -G icingacmd www-data
Make sure to replace "www-data" with the name of the user your web server
is running as.
Building Icinga 2
-----------------
@ -71,9 +74,6 @@ The configure script supports all the usual parameters one comes to expect
from autoconf. In particular you may want to use --prefix to specify an
alternative installation prefix.
Use --with-icinga[cmd]-{user,group}= to set the run and command user/group
for Icinga 2.
Note: The Git repository does not contain any auto-generated Autotools files,
i.e. there is no 'configure' script. In this case you will need to regenerate
the 'configure' script by running 'autogen.sh'. However, as an end-user you
@ -86,15 +86,16 @@ Running Icinga 2
Icinga 2 comes with a single binary that takes care of loading all the relevant
components (e.g. for check execution, notifications, etc.):
$ /tmp/i2/bin/icinga
$ icinga2
[2012/09/14 10:36:12] information/icinga: Icinga application loader (version:
2.0, git branch master, commit 8e4bdf38 + changes)
[2012/09/14 10:36:12] information/base: Syntax: ./bin/icinga -c <config-file> ...
[2012/09/14 10:36:12] information/base: Syntax: icinga2 -c <config-file> ...
Icinga 2 reads a single configuration file which is used to specify all
configuration settings (global settings, hosts, services, etc.). The
configuration format is explained in detail in the docs/icinga2-config.txt
file.
By default "make install" installs example configuration files to /etc/icinga2
unless you have specified a different prefix or sysconfdir.
By default "make install" installs example configuration files in
/usr/local/etc/icinga2 unless you have specified a different prefix or
sysconfdir.

View File

@ -1,7 +1,5 @@
# Getting Started
## Installation
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.

View File

@ -1,9 +1,8 @@
### Setting up Icinga 2
## Setting up Icinga 2
In order to get started with Icinga 2 you will have to install it. The
preferred way of doing this is to use the official Debian or RPM
package repositories depending on which Linux distribution you are
running.
First of all you will have to install Icinga 2. The preferred way of doing this
is to use the official Debian or RPM package repositories depending on which
operating system and distribution you are running.
Distribution |Repository URL
------------------------|---------------------------
@ -15,31 +14,38 @@ Packages for distributions other than the ones listed above may also be
available. Please check http://packages.icinga.org/ to see if packages
are available for your favorite distribution.
Icinga 2 is split up into several packages:
You can install Icinga 2 by using your distribution's package manager
to install the *icinga2* package. Some parts of Icinga 2's functionality
are available as separate packages.
are available as separate packages:
Name | Description
------------------------|--------------------------------
icinga2-ido-mysql | IDO provider module for MySQL
icinga2-python | Python scripting support for Icinga 2
In case you're running a distribution for which Icinga 2 packages are
not yet available you will have to use the release tarball which you
can download from the [Icinga website](https://www.icinga.org/). The
release tarballs contain an *INSTALL* file with further instructions.
#### Installation Paths
### Installation Paths
By default Icinga 2 uses the following files and directories:
Path |Description
Path | Description
------------------------------------|------------------------------------
/etc/icinga2 |Contains Icinga 2 configuration files.
/etc/init.d/icinga2 |The Icinga 2 init script.
/usr/share/doc/icinga2 |Documentation files that come with Icinga 2.
/usr/share/icinga2/itl |The Icinga Template Library.
/var/run/icinga2 |PID file.
/var/run/icinga2/cmd |Command pipe and livestatus socket.
/var/cache/icinga2 |Performance data files and status.dat/objects.cache.
/var/lib/icinga2 |The Icinga 2 state file.
/etc/icinga2 | Contains Icinga 2 configuration files.
/etc/init.d/icinga2 | The Icinga 2 init script.
/usr/share/doc/icinga2 | Documentation files that come with Icinga 2.
/usr/share/icinga2/itl | The Icinga Template Library.
/var/run/icinga2 | PID file.
/var/run/icinga2/cmd | Command pipe and livestatus socket.
/var/cache/icinga2 | Performance data files and status.dat/objects.cache.
/var/lib/icinga2 | The Icinga 2 state file.
#### icinga2.conf
### icinga2.conf
An example configuration file is installed for you in */etc/icinga2/icinga2.conf*.
@ -85,7 +91,7 @@ the features which have been enabled with *i2enfeature*. See
You can put your own configuration files in the *conf.d* directory. This
directive makes sure that all of your own configuration files are included.
#### macros.conf
### macros.conf
The *conf.d/macros.conf* file can be used to define global macros:
@ -99,7 +105,7 @@ The *conf.d/macros.conf* file can be used to define global macros:
Icinga 2 lets you define free-form macros. The IcingaMacros variable can be used
to define global macros which are available in all command definitions.
#### localhost.conf
### localhost.conf
The *conf.d/localhost.conf* file contains our first host definition:

View File

@ -1,4 +1,4 @@
### Setting up Icinga Classic UI
## 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
@ -12,7 +12,7 @@ You should be able to find the *status.dat* and *objects.cache* files in
*/var/cache/icinga2*. The log files can be found in */var/log/icinga2/compat*.
The command pipe can be found in */var/run/icinga2*.
#### Installing Icinga Classic UI
### Installing Icinga Classic UI
You can install Icinga 1.x Classic UI in standalone mode using the
following commands:
@ -30,7 +30,7 @@ following commands:
> found on the Icinga Wiki here:
> [https://wiki.icinga.org/display/howtos/Setting+up+Icinga+Classic+UI+Standalone](https://wiki.icinga.org/display/howtos/Setting+up+Icinga+Classic+UI+Standalone)
#### Configuring Icinga 2
### Configuring Icinga 2
By default Icinga 2 does not write *status.dat* and *objects.cache* files which are used
by the Classic UI. The command pipe is also not enabled by default.
@ -44,7 +44,7 @@ After enabling these features you will need to restart Icinga 2:
# /etc/init.d/icinga2 restart
#### Configuring the Classic UI
### Configuring the Classic UI
After installing the Classic UI you will need to update the following
settings in your *cgi.cfg* configuration file in the *STANDALONE (ICINGA 2)
@ -71,9 +71,9 @@ OPTIONS* section:
> might be different.
In order for commands to work you will need to add your web server user to
the *icinga-cmd* group:
the *icingacmd* group:
# usermod -a -G icinga-cmd www-data
# usermod -a -G icingacmd www-data
> **Note**
>

View File

@ -1,4 +1,4 @@
### Setting up Check Plugins
## Setting up Check Plugins
On its own Icinga 2 does not know how to check external services. The
[Nagios Plugins Project](https://www.nagios-plugins.org/) provides an extensive

View File

@ -1,4 +1,4 @@
### Configuring IDO
## Configuring IDO
The IDO (Icinga Data Output) modules for Icinga 2 takes care of exporting all
configuration and status information into a database. The IDO database is used
@ -7,7 +7,7 @@ by a number of projects including Icinga Web.
There is a separate module for each database backend. At present only support
for MySQL is implemented.
#### Setting up the database
### Setting up the database
First of all you have to create a database for Icinga 2:
@ -34,7 +34,7 @@ following command:
# mysql -u root -p icinga < /path/to/icinga-src/components/db_ido_mysql/schema/mysql.sql
#### Installing the IDO module
### Installing the IDO module
Once you've set up your database you have to install the *icinga2-ido-mysql*
package using your distribution's package manager.

View File

@ -1,4 +1,4 @@
### Setting up Livestatus
## Setting up Livestatus
The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project
implements a query protocol that lets users query their Icinga instance for
@ -19,9 +19,9 @@ After that you will have to restart Icinga 2:
By default the Livestatus socket is available in */var/run/icinga2/cmd/livestatus*.
In order for queries and commands to work you will need to add your query user
(e.g. your web server) to the *icinga-cmd* group:
(e.g. your web server) to the *icingacmd* group:
# usermod -a -G icinga-cmd www-data
# usermod -a -G icingacmd www-data
> **Note**
>

View File

@ -7,35 +7,14 @@ 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}
#### start
The *start* action starts the Icinga 2 daemon.
#### stop
The *stop* action stops the Icinga 2 daemon.
#### restart
The *restart* action is a shortcut for running the *stop* action followed by
*start*.
#### reload
The *reload* action sends the HUP signal to Icinga 2 which causes it to restart.
Unlike the *restart* action *reload* does not wait until Icinga 2 has restarted.
#### checkconfig
The *checkconfig* action checks if the */etc/icinga2/icinga2.conf* configuration
file contains any errors.
#### status
The *status* action checks if Icinga 2 is running:
$ /etc/init.d/icinga2 status
Icinga 2 status: Running
Command | Description
--------------------|------------------------
start | The *start* action starts the Icinga 2 daemon.
stop | The *stop* action stops the Icinga 2 daemon.
restart | The *restart* action is a shortcut for running the *stop* action followed by *start*.
reload | The *reload* action sends the HUP signal to Icinga 2 which causes it to restart. Unlike the *restart* action *reload* does not wait until Icinga 2 has restarted.
checkconfig | The *checkconfig* action checks if the */etc/icinga2/icinga2.conf* configuration file contains any errors.
status | The *status* action checks if Icinga 2 is running.
### <a id="cmdline"></a> Command-line Options

View File

@ -0,0 +1,4 @@
# 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.

View File

@ -0,0 +1,84 @@
## Hosts and Services
Icinga 2 can be used to monitor the availability of hosts and services. Services
can be virtually anything which can be checked in some way:
* Network services (HTTP, SMTP, SNMP, SSH, etc.)
* Printers
* Switches / Routers
* Temperature Sensors
* Other local or network-accessible services
Host objects provide a mechanism to group together services that are running
on the same physical device.
Here is an example of a host object which defines two child services:
object Host "my-server1" {
services["ping4"] = {
check_command = "ping4"
},
services["http"] = {
check_command = "http_ip"
},
check = "ping4",
macros["address"] = "10.0.0.1"
}
The example host *my-server1* creates two services which belong to this host:
*ping4* and *http*.
It also specifies that the host should inherit its availability state from the
*ping4* service.
> **Note**
>
> In Icinga 1.x hosts had their own check command, check interval and
> notification settings. Instead, in Icinga 2 hosts inherit their state
> from one of its child services. No checks are performed for the host
> itself.
The *address* macro is used by check commands to determine which network
address is associated with the host object.
### Host States
Hosts inherit their state from the host check service that is specified using
the *check* attribute.
Hosts can be in any of the following states:
Name | Description
------------|--------------
UP | The host is available.
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
Services can be in any of the following states:
Name | Description
------------|--------------
OK | The service is working properly.
WARNING | The service is experiencing some problems but is still considered to be in working condition.
CRITICAL | The service is in a critical state.
UNKNOWN | The check could not determine the service's state.
### Hard and Soft States
When detecting a problem with a service Icinga re-checks the service a number of
times (based on the *max_check_attempts* and *retry_interval* settings) before sending
notifications. This ensures that no unnecessary notifications are sent for
transient failures. During this time the service is in a *SOFT* state.
After all re-checks have been executed and the service is still in a non-OK
state the service switches to a *HARD* state and notifications are sent.
Name | Description
------------|--------------
HARD | The host/service's state hasn't recently changed.
SOFT | The host/service has recently changed state and is being re-checked.

View File

@ -0,0 +1,3 @@
## Check Commands
TODO

View File

@ -1,98 +1,4 @@
## 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.
### Hosts and Services
Icinga 2 can be used to monitor the availability of hosts and services. Services
can be virtually anything which can be checked in some way:
* Network services (HTTP, SMTP, SNMP, SSH, etc.)
* Printers
* Switches / Routers
* Temperature Sensors
* Other local or network-accessible services
Host objects provide a mechanism to group together services that are running
on the same physical device.
Here is an example of a host object which defines two child services:
object Host "my-server1" {
services["ping4"] = {
check_command = "ping4"
},
services["http"] = {
check_command = "http_ip"
},
check = "ping4",
macros["address"] = "10.0.0.1"
}
The example host *my-server1* creates two services which belong to this host:
*ping4* and *http*.
It also specifies that the host should inherit its availability state from the
*ping4* service.
> **Note**
>
> In Icinga 1.x hosts had their own check command, check interval and
> notification settings. Instead, in Icinga 2 hosts inherit their state
> from one of its child services. No checks are performed for the host
> itself.
The *address* macro is used by check commands to determine which network
address is associated with the host object.
#### Host States
Hosts inherit their state from the host check service that is specified using
the *check* attribute.
Hosts can be in any of the following states:
Name | Description
------------|--------------
UP | The host is available.
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
Services can be in any of the following states:
Name | Description
------------|--------------
OK | The service is working properly.
WARNING | The service is experiencing some problems but is still considered to be in working condition.
CRITICAL | The service is in a critical state.
UNKNOWN | The check could not determine the service's state.
#### Hard and Soft States
When detecting a problem with a service Icinga re-checks the service a number of
times (based on the *max_check_attempts* and *retry_interval* settings) before sending
notifications. This ensures that no unnecessary notifications are sent for
transient failures. During this time the service is in a *SOFT* state.
After all re-checks have been executed and the service is still in a non-OK
state the service switches to a *HARD* state and notifications are sent.
Name | Description
------------|--------------
HARD | The host/service's state hasn't recently changed.
SOFT | The host/service has recently changed state and is being re-checked.
### Check Commands
TODO
### Macros
## Macros
Macros may be used in command definitions to dynamically change how the command
is executed.
@ -171,7 +77,7 @@ The *plugindir* macro should be set to the path of your check plugins. The
*/etc/icinga2/conf.d/macros.conf* file is usually used to define global macros
including this one.
#### Host Macros
### Host Macros
The following host macros are available in all commands that are executed for
hosts or services:
@ -197,7 +103,7 @@ hosts or services:
HOSTADDRESS | This is an alias for the *address* macro. If the *address* macro is not defined the host object's name is used instead.
HOSTADDRESS6 | This is an alias for the *address6* macro. If the *address* macro is not defined the host object's name is used instead.
#### Service Macros
### Service Macros
The following service macros are available in all commands that are executed for
services:
@ -222,7 +128,7 @@ services:
SERVICEPERFDATA | The last check's performance data.
LASTSERVICECHECK | The timestamp when the last check was executed.
#### User Macros
### User Macros
The following service macros are available in all commands that are executed for
users:
@ -234,7 +140,7 @@ users:
CONTACTEMAIL | This is an alias for the *email* macro.
CONTACTPAGER | This is an alias for the *pager* macro.
#### Global Macros
### Global Macros
The following macros are available in all commands:
@ -245,48 +151,3 @@ The following macros are available in all commands:
SHORTDATETIME | Current date and time.
DATE | Current date.
TIME | Current time including timezone information.
### Using Templates
Templates may be used to apply a set of similar settings to more than one
object.
For example, rather than manually creating a *ping* service object for each of
your hosts you can use templates to avoid having to copy & paste parts of your
config:
template Host "linux-server" {
services["ping"] = {
check_command = "ping4"
},
check = "ping4"
}
object Host "my-server1" inherits "linux-server" {
macros["address"] = "10.0.0.1"
}
object Host "my-server2" inherits "linux-server" {
macros["address"] = "10.0.0.2"
}
In this example both *my-server1* and *my-server2* each get their own ping
service check.
Objects as well as templates themselves can inherit from an arbitrary number of
templates. Attributes inherited from a template can be overridden in the
object if necessary.
### Groups
TODO
### Host/Service Dependencies
TODO
### Notifications
TODO

View File

@ -0,0 +1,47 @@
## Using Templates
Templates may be used to apply a set of similar settings to more than one
object.
For example, rather than manually creating a *ping* service object for each of
your hosts you can use templates to avoid having to copy & paste parts of your
config:
template Host "linux-server" {
services["ping"] = {
check_command = "ping4"
},
check = "ping4"
}
object Host "my-server1" inherits "linux-server" {
macros["address"] = "10.0.0.1"
}
object Host "my-server2" inherits "linux-server" {
macros["address"] = "10.0.0.2"
}
In this example both *my-server1* and *my-server2* each get their own ping
service check.
Objects as well as templates themselves can inherit from an arbitrary number of
templates. Attributes inherited from a template can be overridden in the
object if necessary.
Templates can also be used in service and notification definitions using the
*templates* attribute:
template Service "weekend-service" {
check_interval = 0.5m,
check_period = "weekend"
}
object Host "my-server1" {
services["backup"] {
check_command = "backup-check",
templates = [ "weekend-service" ]
}
}

12
doc/3.5-groups.md Normal file
View File

@ -0,0 +1,12 @@
## Groups
TODO
## Host/Service Dependencies
TODO
## Notifications
TODO

View File

@ -1,6 +1,6 @@
## Icinga Template Library
# Icinga Template Library
### Overview
## Overview
The Icinga Template Library (ITL) implements standard templates and object
definitions for commonly used services.
@ -10,9 +10,9 @@ file:
include <itl/itl.conf>
### Check Commands
## Check Commands
#### ping4
### ping4
Check command object for the *check_ping* plugin.
@ -29,7 +29,7 @@ cpl | **Optional.** The packet loss critical threshold in %. Default
packets | **Optional.** The number of packets to send. Defaults to 5.
timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
#### ping6
### ping6
Check command object for the *check_ping* plugin.
@ -46,7 +46,7 @@ cpl | **Optional.** The packet loss critical threshold in %. Default
packets | **Optional.** The number of packets to send. Defaults to 5.
timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
#### dummy
### dummy
Check command object for the *check_dummy* plugin.
@ -58,7 +58,7 @@ plugindir | **Required.** The directory containing this plugin.
state | **Optional.** The state. Can be one of 0 (ok), 1 (warning), 2 (critical) and 3 (unknown). Defaults to 0.
text | **Optional.** Plugin output. Defaults to "Check was successful.".
#### tcp
### tcp
Check command object for the *check_tcp* plugin.
@ -70,7 +70,7 @@ plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
port | **Required.** The port that should be checked.
#### udp
### udp
Check command object for the *check_udp* plugin.
@ -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.
#### http_vhost
### http_vhost
Check command object for the *check_http* plugin.
@ -93,7 +93,7 @@ Name | Description
plugindir | **Required.** The directory containing this plugin.
vhost | **Required.** The name of the virtual host that should be checked.
#### http_ip
### http_ip
Check command object for the *check_http* plugin.
@ -104,7 +104,7 @@ Name | Description
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
#### https_vhost
### https_vhost
Check command object for the *check_http* plugin.
@ -115,7 +115,7 @@ Name | Description
plugindir | **Required.** The directory containing this plugin.
vhost | **Required.** The name of the virtual host that should be checked.
#### https_ip
### https_ip
Check command object for the *check_http* plugin.
@ -126,7 +126,7 @@ Name | Description
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
#### smtp
### smtp
Check command object for the *check_smtp* plugin.
@ -137,7 +137,7 @@ Name | Description
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
#### ssmtp
### ssmtp
Check command object for the *check_ssmtp* plugin.
@ -149,7 +149,7 @@ plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
port | **Optional.** The port that should be checked. Defaults to 465.
#### ntp_time
### ntp_time
Check command object for the *check_ntp_time* plugin.
@ -160,7 +160,7 @@ Name | Description
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
#### ssh
### ssh
Check command object for the *check_ssh* plugin.
@ -171,7 +171,7 @@ Name | Description
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
#### disk
### disk
Check command object for the *check_disk* plugin.
@ -183,7 +183,7 @@ plugindir | **Required.** The directory containing this plugin.
wfree | **Optional.** The free space warning threshold in %. Defaults to 20.
cfree | **Optional.** The free space critical threshold in %. Defaults to 10.
#### users
### users
Check command object for the *check_disk* plugin.
@ -195,7 +195,7 @@ plugindir | **Required.** The directory containing this plugin.
wgreater | **Optional.** The user count warning threshold. Defaults to 20.
cgreater | **Optional.** The user count warning threshold. Defaults to 50.
#### processes
### processes
Check command object for the *check_processes* plugin.
@ -207,7 +207,7 @@ plugindir | **Required.** The directory containing this plugin.
wgreater | **Optional.** The process count warning threshold. Defaults to 250.
cgreater | **Optional.** The process count warning threshold. Defaults to 400.
#### load
### load
Check command object for the *check_load* plugin.
@ -223,7 +223,7 @@ cload1 | **Optional.** The 1-minute critical threshold. Defaults to 10.
cload5 | **Optional.** The 5-minute critical threshold. Defaults to 6.
cload15 | **Optional.** The 15-minute critical threshold. Defaults to 4.
#### snmp
### snmp
Check command object for the *check_snmp* plugin.
@ -236,7 +236,7 @@ address | **Required.** The host's address.
oid | **Required.** The SNMP OID.
community | **Optional.** The SNMP community. Defaults to "public".
#### snmp-uptime
### snmp-uptime
Check command object for the *check_snmp* plugin.