-----------------
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
-----------------
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
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.
# 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.
-### 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
------------------------|---------------------------
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*.
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:
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:
-### 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
*/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:
> 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.
# /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)
> 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**
>
-### 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
-### 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
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:
# 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.
-### 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
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**
>
# /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
--- /dev/null
+# 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.
--- /dev/null
+## 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.
--- /dev/null
+## Check Commands
+
+TODO
-## 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.
*/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:
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:
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:
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:
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
-
--- /dev/null
+## 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" ]
+ }
+ }
--- /dev/null
+## Groups
+
+TODO
+
+## Host/Service Dependencies
+
+TODO
+
+## Notifications
+
+TODO
+
-## Icinga Template Library
+# Icinga Template Library
-### Overview
+## Overview
The Icinga Template Library (ITL) implements standard templates and object
definitions for commonly used services.
include <itl/itl.conf>
-### Check Commands
+## Check Commands
-#### ping4
+### ping4
Check command object for the *check_ping* plugin.
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.
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.
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.
address | **Required.** The host's address.
port | **Required.** The port that should be checked.
-#### udp
+### udp
Check command object for the *check_udp* 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.
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.
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.
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.
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
-#### smtp
+### smtp
Check command object for the *check_smtp* plugin.
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
-#### ssmtp
+### ssmtp
Check command object for the *check_ssmtp* 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.
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
-#### ssh
+### ssh
Check command object for the *check_ssh* plugin.
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
-#### disk
+### disk
Check command object for the *check_disk* 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.
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.
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.
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.
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.
projects / icinga2 / commitdiff