mirror of
https://github.com/Icinga/icinga2.git
synced 2025-07-24 06:05:01 +02:00
Update documentation.
This commit is contained in:
parent
ddfe45031b
commit
115aea29a0
25
INSTALL
25
INSTALL
@ -43,19 +43,22 @@ User Requirements
|
|||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
By default Icinga will run as user 'icinga' and group 'icinga'. Additionally the
|
By default Icinga will run as user 'icinga' and group 'icinga'. Additionally the
|
||||||
ExternalCommandListener and LivestatusListener require a dedicated command group
|
external command pipe and livestatus features require a dedicated command group
|
||||||
'icingacmd'. You can choose your own user/group names and pass them to configure
|
'icingacmd'. You can choose your own user/group names and pass them to the
|
||||||
later.
|
configure script using the --with-icinga-user, --with-icinga-group,
|
||||||
|
--with-icingacmd-user and --with-icingacmd-group options.
|
||||||
|
|
||||||
# groupadd icinga
|
# groupadd icinga
|
||||||
# groupadd icingacmd
|
# groupadd icingacmd
|
||||||
# useradd -c "icinga" -s /sbin/nologin -G icingacmd -g icinga
|
# useradd -c "icinga" -s /sbin/nologin -G icingacmd -g icinga
|
||||||
|
|
||||||
Add the webserver user to the icingacmd group for granting write permissions.
|
Add the web server user to the icingacmd group in order to grant it write
|
||||||
Change 'www-data' to your distribution specific webserver user.
|
permissions to the external command pipe and livestatus socket:
|
||||||
|
|
||||||
# usermod -a -G icingacmd www-data
|
# 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
|
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
|
from autoconf. In particular you may want to use --prefix to specify an
|
||||||
alternative installation prefix.
|
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,
|
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
|
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
|
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
|
Icinga 2 comes with a single binary that takes care of loading all the relevant
|
||||||
components (e.g. for check execution, notifications, etc.):
|
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:
|
[2012/09/14 10:36:12] information/icinga: Icinga application loader (version:
|
||||||
2.0, git branch master, commit 8e4bdf38 + changes)
|
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
|
Icinga 2 reads a single configuration file which is used to specify all
|
||||||
configuration settings (global settings, hosts, services, etc.). The
|
configuration settings (global settings, hosts, services, etc.). The
|
||||||
configuration format is explained in detail in the docs/icinga2-config.txt
|
configuration format is explained in detail in the docs/icinga2-config.txt
|
||||||
file.
|
file.
|
||||||
|
|
||||||
By default "make install" installs example configuration files to /etc/icinga2
|
By default "make install" installs example configuration files in
|
||||||
unless you have specified a different prefix or sysconfdir.
|
/usr/local/etc/icinga2 unless you have specified a different prefix or
|
||||||
|
sysconfdir.
|
||||||
|
@ -1,7 +1,5 @@
|
|||||||
# Getting Started
|
# Getting Started
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
This tutorial is a step-by-step introduction to installing Icinga 2 and
|
This tutorial is a step-by-step introduction to installing Icinga 2 and
|
||||||
the standalone version of the Icinga 1.x classic web interface. It assumes
|
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.
|
that you are familiar with the system you're installing Icinga 2 on.
|
||||||
|
@ -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
|
First of all you will have to install Icinga 2. The preferred way of doing this
|
||||||
preferred way of doing this is to use the official Debian or RPM
|
is to use the official Debian or RPM package repositories depending on which
|
||||||
package repositories depending on which Linux distribution you are
|
operating system and distribution you are running.
|
||||||
running.
|
|
||||||
|
|
||||||
Distribution |Repository URL
|
Distribution |Repository URL
|
||||||
------------------------|---------------------------
|
------------------------|---------------------------
|
||||||
@ -15,16 +14,23 @@ Packages for distributions other than the ones listed above may also be
|
|||||||
available. Please check http://packages.icinga.org/ to see if packages
|
available. Please check http://packages.icinga.org/ to see if packages
|
||||||
are available for your favorite distribution.
|
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
|
You can install Icinga 2 by using your distribution's package manager
|
||||||
to install the *icinga2* package. Some parts of Icinga 2's functionality
|
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
|
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
|
not yet available you will have to use the release tarball which you
|
||||||
can download from the [Icinga website](https://www.icinga.org/). The
|
can download from the [Icinga website](https://www.icinga.org/). The
|
||||||
release tarballs contain an *INSTALL* file with further instructions.
|
release tarballs contain an *INSTALL* file with further instructions.
|
||||||
|
|
||||||
#### Installation Paths
|
### Installation Paths
|
||||||
|
|
||||||
By default Icinga 2 uses the following files and directories:
|
By default Icinga 2 uses the following files and directories:
|
||||||
|
|
||||||
@ -39,7 +45,7 @@ By default Icinga 2 uses the following files and directories:
|
|||||||
/var/cache/icinga2 | Performance data files and status.dat/objects.cache.
|
/var/cache/icinga2 | Performance data files and status.dat/objects.cache.
|
||||||
/var/lib/icinga2 | The Icinga 2 state file.
|
/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*.
|
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
|
You can put your own configuration files in the *conf.d* directory. This
|
||||||
directive makes sure that all of your own configuration files are included.
|
directive makes sure that all of your own configuration files are included.
|
||||||
|
|
||||||
#### macros.conf
|
### macros.conf
|
||||||
|
|
||||||
The *conf.d/macros.conf* file can be used to define global macros:
|
The *conf.d/macros.conf* file can be used to define global macros:
|
||||||
|
|
||||||
@ -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
|
Icinga 2 lets you define free-form macros. The IcingaMacros variable can be used
|
||||||
to define global macros which are available in all command definitions.
|
to define global macros which are available in all command definitions.
|
||||||
|
|
||||||
#### localhost.conf
|
### localhost.conf
|
||||||
|
|
||||||
The *conf.d/localhost.conf* file contains our first host definition:
|
The *conf.d/localhost.conf* file contains our first host definition:
|
||||||
|
|
@ -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
|
Icinga 2 can write *status.dat* and *objects.cache* files in the format that
|
||||||
is supported by the Icinga 1.x Classic UI. External commands (a.k.a. the
|
is supported by the Icinga 1.x Classic UI. External commands (a.k.a. the
|
||||||
@ -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*.
|
*/var/cache/icinga2*. The log files can be found in */var/log/icinga2/compat*.
|
||||||
The command pipe can be found in */var/run/icinga2*.
|
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
|
You can install Icinga 1.x Classic UI in standalone mode using the
|
||||||
following commands:
|
following commands:
|
||||||
@ -30,7 +30,7 @@ following commands:
|
|||||||
> found on the Icinga Wiki here:
|
> 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)
|
> [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 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.
|
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
|
# /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
|
After installing the Classic UI you will need to update the following
|
||||||
settings in your *cgi.cfg* configuration file in the *STANDALONE (ICINGA 2)
|
settings in your *cgi.cfg* configuration file in the *STANDALONE (ICINGA 2)
|
||||||
@ -71,9 +71,9 @@ OPTIONS* section:
|
|||||||
> might be different.
|
> might be different.
|
||||||
|
|
||||||
In order for commands to work you will need to add your web server user to
|
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**
|
> **Note**
|
||||||
>
|
>
|
@ -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
|
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
|
[Nagios Plugins Project](https://www.nagios-plugins.org/) provides an extensive
|
@ -1,4 +1,4 @@
|
|||||||
### Configuring IDO
|
## Configuring IDO
|
||||||
|
|
||||||
The IDO (Icinga Data Output) modules for Icinga 2 takes care of exporting all
|
The IDO (Icinga Data Output) modules for Icinga 2 takes care of exporting all
|
||||||
configuration and status information into a database. The IDO database is used
|
configuration and status information into a database. The IDO database is used
|
||||||
@ -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
|
There is a separate module for each database backend. At present only support
|
||||||
for MySQL is implemented.
|
for MySQL is implemented.
|
||||||
|
|
||||||
#### Setting up the database
|
### Setting up the database
|
||||||
|
|
||||||
First of all you have to create a database for Icinga 2:
|
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
|
# 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*
|
Once you've set up your database you have to install the *icinga2-ido-mysql*
|
||||||
package using your distribution's package manager.
|
package using your distribution's package manager.
|
@ -1,4 +1,4 @@
|
|||||||
### Setting up Livestatus
|
## Setting up Livestatus
|
||||||
|
|
||||||
The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project
|
The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project
|
||||||
implements a query protocol that lets users query their Icinga instance for
|
implements a query protocol that lets users query their Icinga instance for
|
||||||
@ -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*.
|
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
|
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**
|
> **Note**
|
||||||
>
|
>
|
@ -7,35 +7,14 @@ Icinga 2's init script is installed in */etc/init.d/icinga2* by default:
|
|||||||
# /etc/init.d/icinga2
|
# /etc/init.d/icinga2
|
||||||
Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
|
Usage: /etc/init.d/icinga2 {start|stop|restart|reload|checkconfig|status}
|
||||||
|
|
||||||
#### start
|
Command | Description
|
||||||
|
--------------------|------------------------
|
||||||
The *start* action starts the Icinga 2 daemon.
|
start | The *start* action starts the Icinga 2 daemon.
|
||||||
|
stop | The *stop* action stops the Icinga 2 daemon.
|
||||||
#### stop
|
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.
|
||||||
The *stop* action stops the Icinga 2 daemon.
|
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.
|
||||||
#### 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
|
|
||||||
|
|
||||||
### <a id="cmdline"></a> Command-line Options
|
### <a id="cmdline"></a> Command-line Options
|
||||||
|
|
4
doc/3-monitoring-basics.md
Normal file
4
doc/3-monitoring-basics.md
Normal 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.
|
84
doc/3.1-hosts-and-services.md
Normal file
84
doc/3.1-hosts-and-services.md
Normal 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.
|
3
doc/3.2-check-commands.md
Normal file
3
doc/3.2-check-commands.md
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
## Check Commands
|
||||||
|
|
||||||
|
TODO
|
@ -1,98 +1,4 @@
|
|||||||
## Monitoring Basics
|
## Macros
|
||||||
|
|
||||||
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 may be used in command definitions to dynamically change how the command
|
Macros may be used in command definitions to dynamically change how the command
|
||||||
is executed.
|
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
|
*/etc/icinga2/conf.d/macros.conf* file is usually used to define global macros
|
||||||
including this one.
|
including this one.
|
||||||
|
|
||||||
#### Host Macros
|
### Host Macros
|
||||||
|
|
||||||
The following host macros are available in all commands that are executed for
|
The following host macros are available in all commands that are executed for
|
||||||
hosts or services:
|
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.
|
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.
|
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
|
The following service macros are available in all commands that are executed for
|
||||||
services:
|
services:
|
||||||
@ -222,7 +128,7 @@ services:
|
|||||||
SERVICEPERFDATA | The last check's performance data.
|
SERVICEPERFDATA | The last check's performance data.
|
||||||
LASTSERVICECHECK | The timestamp when the last check was executed.
|
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
|
The following service macros are available in all commands that are executed for
|
||||||
users:
|
users:
|
||||||
@ -234,7 +140,7 @@ users:
|
|||||||
CONTACTEMAIL | This is an alias for the *email* macro.
|
CONTACTEMAIL | This is an alias for the *email* macro.
|
||||||
CONTACTPAGER | This is an alias for the *pager* macro.
|
CONTACTPAGER | This is an alias for the *pager* macro.
|
||||||
|
|
||||||
#### Global Macros
|
### Global Macros
|
||||||
|
|
||||||
The following macros are available in all commands:
|
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.
|
SHORTDATETIME | Current date and time.
|
||||||
DATE | Current date.
|
DATE | Current date.
|
||||||
TIME | Current time including timezone information.
|
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
|
|
||||||
|
|
47
doc/3.4-using-templates.md
Normal file
47
doc/3.4-using-templates.md
Normal 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
12
doc/3.5-groups.md
Normal file
@ -0,0 +1,12 @@
|
|||||||
|
## Groups
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
||||||
|
## Host/Service Dependencies
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
||||||
|
## Notifications
|
||||||
|
|
||||||
|
TODO
|
||||||
|
|
@ -1,6 +1,6 @@
|
|||||||
## Icinga Template Library
|
# Icinga Template Library
|
||||||
|
|
||||||
### Overview
|
## Overview
|
||||||
|
|
||||||
The Icinga Template Library (ITL) implements standard templates and object
|
The Icinga Template Library (ITL) implements standard templates and object
|
||||||
definitions for commonly used services.
|
definitions for commonly used services.
|
||||||
@ -10,9 +10,9 @@ file:
|
|||||||
|
|
||||||
include <itl/itl.conf>
|
include <itl/itl.conf>
|
||||||
|
|
||||||
### Check Commands
|
## Check Commands
|
||||||
|
|
||||||
#### ping4
|
### ping4
|
||||||
|
|
||||||
Check command object for the *check_ping* plugin.
|
Check command object for the *check_ping* plugin.
|
||||||
|
|
||||||
@ -29,7 +29,7 @@ cpl | **Optional.** The packet loss critical threshold in %. Default
|
|||||||
packets | **Optional.** The number of packets to send. Defaults to 5.
|
packets | **Optional.** The number of packets to send. Defaults to 5.
|
||||||
timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
|
timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
|
||||||
|
|
||||||
#### ping6
|
### ping6
|
||||||
|
|
||||||
Check command object for the *check_ping* plugin.
|
Check command object for the *check_ping* plugin.
|
||||||
|
|
||||||
@ -46,7 +46,7 @@ cpl | **Optional.** The packet loss critical threshold in %. Default
|
|||||||
packets | **Optional.** The number of packets to send. Defaults to 5.
|
packets | **Optional.** The number of packets to send. Defaults to 5.
|
||||||
timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
|
timeout | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
|
||||||
|
|
||||||
#### dummy
|
### dummy
|
||||||
|
|
||||||
Check command object for the *check_dummy* plugin.
|
Check command object for the *check_dummy* plugin.
|
||||||
|
|
||||||
@ -58,7 +58,7 @@ plugindir | **Required.** The directory containing this plugin.
|
|||||||
state | **Optional.** The state. Can be one of 0 (ok), 1 (warning), 2 (critical) and 3 (unknown). Defaults to 0.
|
state | **Optional.** The state. Can be one of 0 (ok), 1 (warning), 2 (critical) and 3 (unknown). Defaults to 0.
|
||||||
text | **Optional.** Plugin output. Defaults to "Check was successful.".
|
text | **Optional.** Plugin output. Defaults to "Check was successful.".
|
||||||
|
|
||||||
#### tcp
|
### tcp
|
||||||
|
|
||||||
Check command object for the *check_tcp* plugin.
|
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.
|
address | **Required.** The host's address.
|
||||||
port | **Required.** The port that should be checked.
|
port | **Required.** The port that should be checked.
|
||||||
|
|
||||||
#### udp
|
### udp
|
||||||
|
|
||||||
Check command object for the *check_udp* plugin.
|
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.
|
address | **Required.** The host's address.
|
||||||
port | **Required.** The port that should be checked.
|
port | **Required.** The port that should be checked.
|
||||||
|
|
||||||
#### http_vhost
|
### http_vhost
|
||||||
|
|
||||||
Check command object for the *check_http* plugin.
|
Check command object for the *check_http* plugin.
|
||||||
|
|
||||||
@ -93,7 +93,7 @@ Name | Description
|
|||||||
plugindir | **Required.** The directory containing this plugin.
|
plugindir | **Required.** The directory containing this plugin.
|
||||||
vhost | **Required.** The name of the virtual host that should be checked.
|
vhost | **Required.** The name of the virtual host that should be checked.
|
||||||
|
|
||||||
#### http_ip
|
### http_ip
|
||||||
|
|
||||||
Check command object for the *check_http* plugin.
|
Check command object for the *check_http* plugin.
|
||||||
|
|
||||||
@ -104,7 +104,7 @@ Name | Description
|
|||||||
plugindir | **Required.** The directory containing this plugin.
|
plugindir | **Required.** The directory containing this plugin.
|
||||||
address | **Required.** The host's address.
|
address | **Required.** The host's address.
|
||||||
|
|
||||||
#### https_vhost
|
### https_vhost
|
||||||
|
|
||||||
Check command object for the *check_http* plugin.
|
Check command object for the *check_http* plugin.
|
||||||
|
|
||||||
@ -115,7 +115,7 @@ Name | Description
|
|||||||
plugindir | **Required.** The directory containing this plugin.
|
plugindir | **Required.** The directory containing this plugin.
|
||||||
vhost | **Required.** The name of the virtual host that should be checked.
|
vhost | **Required.** The name of the virtual host that should be checked.
|
||||||
|
|
||||||
#### https_ip
|
### https_ip
|
||||||
|
|
||||||
Check command object for the *check_http* plugin.
|
Check command object for the *check_http* plugin.
|
||||||
|
|
||||||
@ -126,7 +126,7 @@ Name | Description
|
|||||||
plugindir | **Required.** The directory containing this plugin.
|
plugindir | **Required.** The directory containing this plugin.
|
||||||
address | **Required.** The host's address.
|
address | **Required.** The host's address.
|
||||||
|
|
||||||
#### smtp
|
### smtp
|
||||||
|
|
||||||
Check command object for the *check_smtp* plugin.
|
Check command object for the *check_smtp* plugin.
|
||||||
|
|
||||||
@ -137,7 +137,7 @@ Name | Description
|
|||||||
plugindir | **Required.** The directory containing this plugin.
|
plugindir | **Required.** The directory containing this plugin.
|
||||||
address | **Required.** The host's address.
|
address | **Required.** The host's address.
|
||||||
|
|
||||||
#### ssmtp
|
### ssmtp
|
||||||
|
|
||||||
Check command object for the *check_ssmtp* plugin.
|
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.
|
address | **Required.** The host's address.
|
||||||
port | **Optional.** The port that should be checked. Defaults to 465.
|
port | **Optional.** The port that should be checked. Defaults to 465.
|
||||||
|
|
||||||
#### ntp_time
|
### ntp_time
|
||||||
|
|
||||||
Check command object for the *check_ntp_time* plugin.
|
Check command object for the *check_ntp_time* plugin.
|
||||||
|
|
||||||
@ -160,7 +160,7 @@ Name | Description
|
|||||||
plugindir | **Required.** The directory containing this plugin.
|
plugindir | **Required.** The directory containing this plugin.
|
||||||
address | **Required.** The host's address.
|
address | **Required.** The host's address.
|
||||||
|
|
||||||
#### ssh
|
### ssh
|
||||||
|
|
||||||
Check command object for the *check_ssh* plugin.
|
Check command object for the *check_ssh* plugin.
|
||||||
|
|
||||||
@ -171,7 +171,7 @@ Name | Description
|
|||||||
plugindir | **Required.** The directory containing this plugin.
|
plugindir | **Required.** The directory containing this plugin.
|
||||||
address | **Required.** The host's address.
|
address | **Required.** The host's address.
|
||||||
|
|
||||||
#### disk
|
### disk
|
||||||
|
|
||||||
Check command object for the *check_disk* plugin.
|
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.
|
wfree | **Optional.** The free space warning threshold in %. Defaults to 20.
|
||||||
cfree | **Optional.** The free space critical threshold in %. Defaults to 10.
|
cfree | **Optional.** The free space critical threshold in %. Defaults to 10.
|
||||||
|
|
||||||
#### users
|
### users
|
||||||
|
|
||||||
Check command object for the *check_disk* plugin.
|
Check command object for the *check_disk* plugin.
|
||||||
|
|
||||||
@ -195,7 +195,7 @@ plugindir | **Required.** The directory containing this plugin.
|
|||||||
wgreater | **Optional.** The user count warning threshold. Defaults to 20.
|
wgreater | **Optional.** The user count warning threshold. Defaults to 20.
|
||||||
cgreater | **Optional.** The user count warning threshold. Defaults to 50.
|
cgreater | **Optional.** The user count warning threshold. Defaults to 50.
|
||||||
|
|
||||||
#### processes
|
### processes
|
||||||
|
|
||||||
Check command object for the *check_processes* plugin.
|
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.
|
wgreater | **Optional.** The process count warning threshold. Defaults to 250.
|
||||||
cgreater | **Optional.** The process count warning threshold. Defaults to 400.
|
cgreater | **Optional.** The process count warning threshold. Defaults to 400.
|
||||||
|
|
||||||
#### load
|
### load
|
||||||
|
|
||||||
Check command object for the *check_load* plugin.
|
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.
|
cload5 | **Optional.** The 5-minute critical threshold. Defaults to 6.
|
||||||
cload15 | **Optional.** The 15-minute critical threshold. Defaults to 4.
|
cload15 | **Optional.** The 15-minute critical threshold. Defaults to 4.
|
||||||
|
|
||||||
#### snmp
|
### snmp
|
||||||
|
|
||||||
Check command object for the *check_snmp* plugin.
|
Check command object for the *check_snmp* plugin.
|
||||||
|
|
||||||
@ -236,7 +236,7 @@ address | **Required.** The host's address.
|
|||||||
oid | **Required.** The SNMP OID.
|
oid | **Required.** The SNMP OID.
|
||||||
community | **Optional.** The SNMP community. Defaults to "public".
|
community | **Optional.** The SNMP community. Defaults to "public".
|
||||||
|
|
||||||
#### snmp-uptime
|
### snmp-uptime
|
||||||
|
|
||||||
Check command object for the *check_snmp* plugin.
|
Check command object for the *check_snmp* plugin.
|
||||||
|
|
Loading…
x
Reference in New Issue
Block a user