Update documentation.

This commit is contained in:
Gunnar Beutner 2013-10-01 12:59:02 +02:00
parent 1eb209e4f0
commit 5a6b7ffb78
7 changed files with 360 additions and 51 deletions

View File

@ -15,6 +15,10 @@ 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.
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.
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

View File

@ -30,6 +30,20 @@ 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
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.
You can use i2enfeature to enable these features:
# i2enfeature statusdat
# i2enfeature command
After enabling these features you will need to restart Icinga 2:
# /etc/init.d/icinga2 restart
#### Configuring the Classic UI
After installing the Classic UI you will need to update the following

View File

@ -1,14 +1,15 @@
### Configuring IDO
The IDO (Icinga Data Output) modules for Icinga 2 takes care of exporting all
configuration and status information into a database.
configuration and status information into a database. The IDO database is used
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
First of all you will need to create a database for Icinga 2:
First of all you have to create a database for Icinga 2:
# mysql -u root -p
@ -29,14 +30,13 @@ First of all you will need to create a database for Icinga 2:
mysql> quit
After creating the database you can import the Icinga 2 IDO schema using the
following commands:
following command:
# cd /path/to/icinga-src/components/db_ido_mysql/schema
# mysql -u root -p icinga < mysql.sql
# mysql -u root -p icinga < /path/to/icinga-src/components/db_ido_mysql/schema/mysql.sql
#### Installing the IDO module
Once you've set up your database you will need 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.
The package provides a new configuration file that is installed in
@ -49,6 +49,6 @@ You can enable the ido-mysql feature configuration file using *i2enfeature*:
Module 'ido-mysql' was enabled.
Make sure to restart Icinga 2 for these changes to take effect.
After enabling the ido-mysql feature you will need to restart Icinga 2:
After enabling the ido-mysql feature you have to restart Icinga 2:
# /etc/init.d/icinga2 restart
# /etc/init.d/icinga2 restart

View File

@ -1,12 +1,85 @@
## Monitoring Basics
### Hosts
This part of the Icinga 2 documentation provides an overview of all the basic
monitoring concepts you need to know to run Icinga 2.
TODO
### Hosts and Services
### 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:
TODO
* 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
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
Name | Description
------------|--------------
OK | The service is fully available.
WARNING | The service is experiencing some problems but is still considered available.
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
@ -14,25 +87,187 @@ TODO
### Macros
TODO
Macros may be used in command definitions to dynamically change how the command
is executed.
## Using Templates
Here is an example of a command definition which uses user-defined macros:
object CheckCommand "my-ping" inherits "plugin-check-command" {
command = [
"$plugindir$/check_ping",
"-4",
"-H", "$address$",
"-w", "$wrta$,$wpl$%",
"-c", "$crta$,$cpl$%",
"-p", "$packets$",
"-t", "$timeout$"
],
macros = {
wrta = 100,
wpl = 5,
crta = 200,
cpl = 15,
packets = 5,
timeout = 0
}
}
> **Note**
>
> If you have previously used Icinga 1.x you may already be familiar with
> user and argument macros (e.g., USER1 or ARG1). Unlike in Icinga 1.x macros
> may have arbitrary names and arguments are no longer specified in the
> check_command setting.
Macro names must be enclosed in two *$* signs, e.g. *$plugindir$*. When
executing the command Icinga 2 checks the following objects in this
order to look up macros:
1. User object (only for notifications)
2. Service object
3. Host object
4. Command object
5. Global macros in the IcingaMacros variable
This execution order allows you to define default values for macros in your
command objects. The *my-ping* command shown above uses this to set default
values for some of the latency thresholds and timeouts.
When using the *my-ping* command you can overwrite all or some of the macros
in the service definition like this:
object Host "my-server1" {
services["ping"] = {
check_command = "my-ping",
macros["packets"] = 10 // Overwrites the default value of 5 given in the command
},
macros["address"] = "10.0.0.1"
}
If a macro isn't defined anywhere an empty value is used and a warning is
emitted to the Icinga 2 log.
> **Note**
>
> Macros in capital letters (e.g. HOSTNAME) are reserved for use by Icinga 2
> and should not be overwritten by users.
By convention every host should have an *address* macro. Hosts
which have an IPv6 address should also have an *address6* macro.
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
The following host macros are available in all commands that are executed for
hosts or services:
Name | Description
-----------------------|--------------
HOSTNAME |The name of the host object.
HOSTDISPLAYNAME |The value of the display_name attribute.
HOSTALIAS |This is an alias for the *HOSTDISPLAYNAME* macro.
HOSTSTATE |The host's current state. Can be one of UNREACHABLE, UP and DOWN.
HOSTSTATEID |The host's current state. Can be one of 0 (up), 1 (down) and 2 (unreachable).
HOSTSTATETYPE |The host's current state type. Can be one of SOFT and HARD.
HOSTATTEMPT |The current check attempt number.
MAXHOSTATTEMPT |The maximum number of checks which are executed before changing to a hard state.
LASTHOSTSTATE |The host's previous state. Can be one of UNREACHABLE, UP and DOWN.
LASTHOSTSTATEID |The host's previous state. Can be one of 0 (up), 1 (down) and 2 (unreachable).
LASTHOSTSTATETYPE |The host's previous state type. Can be one of SOFT and HARD.
HOSTLATENCY |The host's check latency.
HOSTEXECUTIONTIME |The host's check execution time.
HOSTOUTPUT |The last check's output.
HOSTPERFDATA |The last check's performance data.
LASTHOSTCHECK |The timestamp when the last check was executed.
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
The following service macros are available in all commands that are executed for
services:
Name | Description
-----------------------|--------------
SERVICEDESC |The short name of the service object.
SERVICEDISPLAYNAME |The value of the display_name attribute.
SERVICECHECKCOMMAND |This is an alias for the *SERVICEDISPLAYNAME* macro.
SERVICESTATE |The service's current state. Can be one of OK, WARNING, CRITICAL, UNCHECKABLE and UNKNOWN.
SERVICESTATEID |The service's current state. Can be one of 0 (ok), 1 (warning), 2 (critical), 3 (unknown) and 4 (uncheckable).
SERVICESTATETYPE |The service's current state type. Can be one of SOFT and HARD.
SERVICEATTEMPT |The current check attempt number.
MAXSERVICEATTEMPT |The maximum number of checks which are executed before changing to a hard state.
LASTSERVICESTATE |The service's previous state. Can be one of OK, WARNING, CRITICAL, UNCHECKABLE and UNKNOWN.
LASTSERVICESTATEID |The service's previous state. Can be one of 0 (ok), 1 (warning), 2 (critical), 3 (unknown) and 4 (uncheckable).
LASTSERVICESTATETYPE |The service's previous state type. Can be one of SOFT and HARD.
LASTSERVICESTATECHANGE |The last state change's timestamp.
SERVICELATENCY |The service's check latency.
SERVICEEXECUTIONTIME |The service's check execution time.
SERVICEOUTPUT |The last check's output.
SERVICEPERFDATA |The last check's performance data.
LASTSERVICECHECK |The timestamp when the last check was executed.
#### User Macros
The following service macros are available in all commands that are executed for
users:
Name | Description
-----------------------|---------------
CONTACTNAME | The name of the user object.
CONTACTALIAS | The value of the display_name attribute.
CONTACTEMAIL | This is an alias for the *email* macro.
CONTACTPAGER | This is an alias for the *pager* macro.
### 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 overwritten in the
object if necessary.
### Groups
TODO
## Groups
### Host/Service Dependencies
TODO
## Host/Service Dependencies
TODO
## Time Periods
TODO
## Notifications
### Notifications
TODO

View File

@ -106,15 +106,15 @@ Attributes:
display_name |**Optional.** A short description of the service.
macros |**Optional.**
check\_command |**Required.** The name of the check command.
max\_check\_attempts|TODO
max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
check\_period |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
check\_interval |**Optional.** The check interval (in seconds).
retry\_interval |**Optional.** The retry interval (in seconds). This is used when the service is in a soft state. Defaults to 1/5th of the check interval if not specified.
check\_interval |**Optional.** The check interval (in seconds). This interval is used for checks when the service is in a *HARD* state. Defaults to 5 minutes.
retry\_interval |**Optional.** The retry interval (in seconds). This interval is used for checks when the service is in a *SOFT* state. Defaults to 1/5th of the check interval if not specified.
event\_command |**Optional.** The name of an event command that should be executed every time the service's state changes.
flapping\_threshold|TODO
volatile |TODO
host\_dependencies|TODO
service\_dependencies|TODO
host_dependencies|**Optional.** A list of host names which this host depends on. These dependencies are used to determine whether the host is unreachable.
service_dependencies|**Optional.** A list of services which this host depends on. Each array element must be a dictionary containing the keys "host" and "service". These dependencies are used to determine whether the host is unreachable.
groups |**Optional.** The service groups this service belongs to.
notifications |TODO
@ -397,10 +397,11 @@ Example:
database = "icinga",
table_prefix = "icinga_",
instance_name = "icinga2",
instance_description = "icinga2 dev instance"
instance_description = "icinga2 dev instance",
cleanup = {
downtimehistory_age = 48h,
logentries_age = 31d,
logentries_age = 31d,
}
}
@ -420,22 +421,23 @@ Attributes:
Cleanup Items:
Name | Description
----------------|----------------
acknowledgement_age |**Optional.** Max age for acknowledgement table rows (entry_time)
commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time)
contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time)
contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time)
downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time)
eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time)
externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time)
flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time)
hostchecks_age |**Optional.** Max age for hostchecks table rows (start_time)
logentries_age |**Optional.** Max age for logentries table rows (logentry_time)
notifications_age |**Optional.** Max age for notifications table rows (start_time)
processevents_age |**Optional.** Max age for processevents table rows (event_time)
statehistory_age |**Optional.** Max age for statehistory table rows (state_time)
servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time)
systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time)
acknowledgement_age |**Optional.** Max age for acknowledgement table rows (entry_time). Defaults to 0 (never).
commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
hostchecks_age |**Optional.** Max age for hostchecks table rows (start_time). Defaults to 0 (never).
logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
### LiveStatusListener
@ -529,21 +531,27 @@ Attributes:
### CheckResultReader
TODO
Reads Icinga 1.x check results from a directory. This functionality is provided
to help existing Icinga 1.x users and might be useful for certain cluster
scenarios.
Example:
TODO
library "compat"
object CheckResultReader "reader" {
spool_dir = "/data/check-results"
}
Attributes:
Name |Description
----------------|----------------
spool\_dir |TODO
spool\_dir |**Optional.** The directory which contains the check result files. Defaults to IcingaLocalStateDir + "/lib/icinga2/spool/checkresults/".
### CheckerComponent
TODO
The checker component is responsible for scheduling active checks. There are no configurable options.
Example:
@ -553,7 +561,7 @@ Example:
### NotificationComponent
TODO
The notification component is responsible for sending notifications. There are no configurable options.
Example:

View File

@ -0,0 +1,46 @@
## Icinga Template Library
TODO
### Overview
### Check Commands
#### ping4
#### ping6
#### dummy
#### tcp
#### udp
#### http_vhost
#### http_ip
#### https_vhost
#### https_ip
#### smtp
#### ssmtp
#### ntp_time
#### ssh
#### disk
#### users
#### processes
#### load
#### snmp
#### snmp-uptime

View File

@ -1,5 +1,7 @@
# Advanced Topics
## Time Periods
## External Commands
TODO