tyler.durden/icinga2
1
0
Fork 0
mirror of https://github.com/Icinga/icinga2.git synced 2025-07-30 00:54:30 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation.

Browse Source
This commit is contained in:
Gunnar Beutner 2013-10-01 15:33:34 +02:00
parent 599fcec1b0
commit de8522f500
7 changed files with 351 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/2.1.1-setting-up-icinga-2.md
View File

@ -22,7 +22,7 @@ are available as separate packages.
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 information. release tarballs contain an *INSTALL* file with further instructions.
#### Installation Paths #### Installation Paths

8
doc/2.1.2-setting-up-icinga-classic-ui.md
View File

@ -70,14 +70,14 @@ OPTIONS* section:
> Depending on how you installed Icinga 2 some of those paths and options > Depending on how you installed Icinga 2 some of those paths and options
> might be different. > might be different.
In order for commands to work you will need to grant the web server In order for commands to work you will need to add your web server user to
write permissions for the command pipe: the *icinga-cmd* group:
# chgrp www-data /var/run/icinga2/cmd/icinga2.cmd # usermod -a -G icinga-cmd www-data
> **Note** > **Note**
> >
> Change "www-data" to the group the Apache HTTP daemon is running as. > Change "www-data" to the user name your web server is running as.
Verify that your Icinga 1.x Classic UI works by browsing to your Classic Verify that your Icinga 1.x Classic UI works by browsing to your Classic
UI installation URL, e.g. UI installation URL, e.g.

28
doc/2.1.5-setting-up-livestatus.md Normal file
View File

@ -0,0 +1,28 @@
### 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
status information. It can also be used to send commands.
The Livestatus component that is distributed as part of Icinga 2 is a
re-implementation of the Livestatus protocol which is compatible with MK
Livestatus.
You can enable Livestatus using i2enfeature:
# i2enfeature livestatus
After that you will have to restart Icinga 2:
# /etc/init.d/icinga2 restart
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:
# usermod -a -G icinga-cmd www-data
> **Note**
>
> Change "www-data" to the user you're using to run queries.

33
doc/2.3-monitoring-basics.md
View File

@ -51,6 +51,11 @@ address is associated with the host object.
#### Host States #### 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 Name | Description
------------|-------------- ------------|--------------
UP | The host is available. UP | The host is available.
@ -59,10 +64,12 @@ address is associated with the host object.
#### Service States #### Service States
Services can be in any of the following states:
Name | Description Name | Description
------------|-------------- ------------|--------------
OK | The service is fully available. OK | The service is working properly.
WARNING | The service is experiencing some problems but is still considered available. WARNING | The service is experiencing some problems but is still considered to be in working condition.
CRITICAL | The service is in a critical state. CRITICAL | The service is in a critical state.
UNKNOWN | The check could not determine the service's state. UNKNOWN | The check could not determine the service's state.
@ -123,7 +130,7 @@ Here is an example of a command definition which uses user-defined macros:
> check_command setting. > check_command setting.
Macro names must be enclosed in two *$* signs, e.g. *$plugindir$*. When Macro names must be enclosed in two *$* signs, e.g. *$plugindir$*. When
executing the command Icinga 2 checks the following objects in this executing commands Icinga 2 checks the following objects in this
order to look up macros: order to look up macros:
1. User object (only for notifications) 1. User object (only for notifications)
@ -136,14 +143,14 @@ 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 command objects. The *my-ping* command shown above uses this to set default
values for some of the latency thresholds and timeouts. values for some of the latency thresholds and timeouts.
When using the *my-ping* command you can overwrite all or some of the macros When using the *my-ping* command you can override all or some of the macros
in the service definition like this: in the service definition like this:
object Host "my-server1" { object Host "my-server1" {
services["ping"] = { services["ping"] = {
check_command = "my-ping", check_command = "my-ping",
macros["packets"] = 10 // Overwrites the default value of 5 given in the command macros["packets"] = 10 // Overrides the default value of 5 given in the command
}, },
macros["address"] = "10.0.0.1" macros["address"] = "10.0.0.1"
@ -221,12 +228,24 @@ The following service macros are available in all commands that are executed for
users: users:
Name | Description Name | Description
-----------------------|--------------- -----------------------|--------------
CONTACTNAME | The name of the user object. CONTACTNAME | The name of the user object.
CONTACTALIAS | The value of the display_name attribute. CONTACTALIAS | The value of the display_name attribute.
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
The following macros are available in all commands:
Name | Description
-----------------------|--------------
TIMET | Current UNIX timestamp.
LONGDATETIME | Current date and time including timezone information.
SHORTDATETIME | Current date and time.
DATE | Current date.
TIME | Current time including timezone information.
### Using Templates ### Using Templates
Templates may be used to apply a set of similar settings to more than one Templates may be used to apply a set of similar settings to more than one
@ -256,7 +275,7 @@ In this example both *my-server1* and *my-server2* each get their own ping
service check. service check.
Objects as well as templates themselves can inherit from an arbitrary number of Objects as well as templates themselves can inherit from an arbitrary number of
templates. Attributes inherited from a template can be overwritten in the templates. Attributes inherited from a template can be overridden in the
object if necessary. object if necessary.
### Groups ### Groups

78
doc/3.3-object-types.md
View File

@ -15,8 +15,6 @@ Example:
groups = [ "all-hosts" ], groups = [ "all-hosts" ],
check = "ping",
host_dependencies = [ "router" ], host_dependencies = [ "router" ],
service_dependencies = [ service_dependencies = [
@ -34,7 +32,9 @@ Example:
vhost = "test1.example.org", vhost = "test1.example.org",
port = 81 port = 81
} }
} },
check = "ping"
} }
Attributes: Attributes:
@ -47,7 +47,7 @@ Attributes:
host_dependencies|**Optional.** A list of host names which this host depends on. These dependencies are used to determine whether the host is unreachable. 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. 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.
services |**Optional.** Inline definition of services. Each dictionary item specifies a service.<br /><br />The *templates* attribute can be used to specify an array of templates that should be inherited by the service.<br /><br />The new service's name is "hostname:service" - where "service" is the dictionary key in the services dictionary.<br /><br />The dictionary key is used as the service's short name. services |**Optional.** Inline definition of services. Each dictionary item specifies a service.<br /><br />The *templates* attribute can be used to specify an array of templates that should be inherited by the service.<br /><br />The new service's name is "hostname:service" - where "service" is the dictionary key in the services dictionary.<br /><br />The dictionary key is used as the service's short name.
macros |TODO macros |**Optional.** A dictionary containing macros that are specific to this host.
### HostGroup ### HostGroup
@ -104,7 +104,7 @@ Attributes:
host |**Required.** The host this service belongs to. There must be a *Host* object with that name. host |**Required.** The host this service belongs to. There must be a *Host* object with that name.
short_name |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x). short_name |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
display_name |**Optional.** A short description of the service. display_name |**Optional.** A short description of the service.
macros |**Optional.** macros |**Optional.** A dictionary containing macros that are specific to this host.
check\_command |**Required.** The name of the check command. check\_command |**Required.** The name of the check command.
max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3. 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\_period |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
@ -116,7 +116,7 @@ Attributes:
host_dependencies|**Optional.** A list of host names which this host depends on. These dependencies are used to determine whether the host is unreachable. 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. 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. groups |**Optional.** The service groups this service belongs to.
notifications |TODO notifications |**Optional.** Inline definition of notifications. Each dictionary item specifies a notification.<br /><br />The *templates* attribute can be used to specify an array of templates that should be inherited by the notification object.<br /><br />The new notification object's name is "hostname:service:notification" - where "notification" is the dictionary key in the notifications dictionary.
### ServiceGroup ### ServiceGroup
@ -136,11 +136,25 @@ Attributes:
### Notification ### Notification
TODO Notification objects are used to specify how users should be notified in case
of service state changes and other events.
> **Best Practice**
>
> Rather than creating a *Notification* object for a specific service it is usually easier
> to just create a *Notification* template and using the *notifications* attribute in the *Service*
> object to associate these templates with a service.
Example: Example:
TODO object Notification "localhost-ping-notification" {
host = "localhost",
service = "ping4",
notification_command = "mail-notification",
users = [ "user1", "user2" ]
}
Attributes: Attributes:
@ -148,7 +162,7 @@ Attributes:
----------------|---------------- ----------------|----------------
host |**Required.** The name of the host this notification belongs to. host |**Required.** The name of the host this notification belongs to.
service |**Required.** The short name of the service this notification belongs to. service |**Required.** The short name of the service this notification belongs to.
macros |TODO macros |**Optional.** A dictionary containing macros that are specific to this notification object.
users |**Optional.** A list of user names who should be notified. users |**Optional.** A list of user names who should be notified.
user_groups |**Optional.** A list of user group names who should be notified. user_groups |**Optional.** A list of user group names who should be notified.
times |TODO times |TODO
@ -171,7 +185,7 @@ Attributes:
Name |Description Name |Description
----------------|---------------- ----------------|----------------
display_name |**Optional.** A short description of the user. display_name |**Optional.** A short description of the user.
macros |TODO macros |**Optional.** A dictionary containing macros that are specific to this user.
groups |TODO groups |TODO
enable_notifications|TODO enable_notifications|TODO
notification_period|TODO notification_period|TODO
@ -208,7 +222,7 @@ Attributes:
Name |Description Name |Description
----------------|---------------- ----------------|----------------
display_name |**Optional.** A short description of the time period. display_name |**Optional.** A short description of the time period.
methods |TODO methods |**Required.** The "update" script method takes care of updating the internal representation of the time period. In virtually all cases you should just inherit from the "legacy-timeperiod" template to take care of this setting.
ranges |TODO ranges |TODO
### ConsoleLogger ### ConsoleLogger
@ -281,12 +295,12 @@ Attributes:
Name |Description Name |Description
----------------|---------------- ----------------|----------------
methods |TODO methods |**Required.** The "execute" script method takes care of executing the check. In virtually all cases you should just inherit from the "plugin-check-command" template to take care of this setting.
command |TODO command |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
export_macros |TODO export_macros |**Optional.** A list of macros which should be exported as environment variables prior to executing the command.
escape_macros |TODO escape_macros |**Optional.** A list of macros which should be shell-escaped in the command.
macros |TODO macros |**Optional.** A dictionary containing macros that are specific to this command.
timeout |TODO timeout |**Optional.** The command timeout in seconds. Defaults to 5 minutes.
### NotificationCommand ### NotificationCommand
@ -320,12 +334,12 @@ Attributes:
Name |Description Name |Description
----------------|---------------- ----------------|----------------
methods |TODO methods |**Required.** The "execute" script method takes care of executing the notification. In virtually all cases you should just inherit from the "plugin-notification-command" template to take care of this setting.
command |TODO command |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
export_macros |TODO export_macros |**Optional.** A list of macros which should be exported as environment variables prior to executing the command.
escape_macros |TODO escape_macros |**Optional.** A list of macros which should be shell-escaped in the command.
macros |TODO macros |**Optional.** A dictionary containing macros that are specific to this command.
timeout |TODO timeout |**Optional.** The command timeout in seconds. Defaults to 5 minutes.
### EventCommand ### EventCommand
@ -346,12 +360,12 @@ Attributes:
Name |Description Name |Description
----------------|---------------- ----------------|----------------
methods |TODO methods |**Required.** The "execute" script method takes care of executing the event handler. In virtually all cases you should just inherit from the "plugin-event-command" template to take care of this setting.
command |TODO command |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
export_macros |TODO export_macros |**Optional.** A list of macros which should be exported as environment variables prior to executing the command.
escape_macros |TODO escape_macros |**Optional.** A list of macros which should be shell-escaped in the command.
macros |TODO macros |**Optional.** A dictionary containing macros that are specific to this command.
timeout |TODO timeout |**Optional.** The command timeout in seconds. Defaults to 5 minutes.
### PerfdataWriter ### PerfdataWriter
@ -372,13 +386,13 @@ Attributes:
Name |Description Name |Description
----------------|---------------- ----------------|----------------
perfdata\_path |**Optional.** Path to the service perfdata file. Defaults to IcingaLocalStateDir + "/cache/icinga2/perfdata/perfdata". perfdata\_path |**Optional.** Path to the service performance data file. Defaults to IcingaLocalStateDir + "/cache/icinga2/perfdata/perfdata".
format\_template|**Optional.** Format template for the perfdata file. Defaults to a template that's suitable for use with PNP4Nagios. format\_template|**Optional.** Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
rotation\_interval|**Optional.** Rotation interval for the file specified in *perfdata\_path*. Defaults to 30 seconds. rotation\_interval|**Optional.** Rotation interval for the file specified in *perfdata\_path*. Defaults to 30 seconds.
> **Note** > **Note**
> >
> When rotating the perfdata file the current UNIX timestamp is appended to the path specified > When rotating the performance data file the current UNIX timestamp is appended to the path specified
> in *perfdata\_path* to generate a unique filename. > in *perfdata\_path* to generate a unique filename.
### IdoMySqlConnection ### IdoMySqlConnection

208
doc/4-icinga-template-library.md
View File

@ -1,46 +1,250 @@
## Icinga Template Library ## Icinga Template Library
TODO
### Overview ### Overview
The Icinga Template Library (ITL) implements standard templates and object
definitions for commonly used services.
You can include the ITL by using the *include* directive in your configuration
file:
include <itl/itl.conf>
### Check Commands ### Check Commands
#### ping4 #### ping4
Check command object for the *check_ping* plugin.
Macros:
Name | Description
----------------|--------------
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
wrta | **Optional.** The RTA warning threshold in milliseconds. Defaults to 100.
wpl | **Optional.** The packet loss warning threshold in %. Defaults to 5.
crta | **Optional.** The RTA critical threshold in milliseconds. Defaults to 200.
cpl | **Optional.** The packet loss critical threshold in %. Defaults to 15.
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.
Macros:
Name | Description
----------------|--------------
plugindir | **Required.** The directory containing this plugin.
address6 | **Required.** The host's IPv6 address.
wrta | **Optional.** The RTA warning threshold in milliseconds. Defaults to 100.
wpl | **Optional.** The packet loss warning threshold in %. Defaults to 5.
crta | **Optional.** The RTA critical threshold in milliseconds. Defaults to 200.
cpl | **Optional.** The packet loss critical threshold in %. Defaults to 15.
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.
Macros:
Name | Description
----------------|--------------
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.
Macros:
Name | Description
----------------|--------------
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.
Macros:
Name | Description
----------------|--------------
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.
Macros:
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.
Macros:
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.
Macros:
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.
Macros:
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.
Macros:
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.
Macros:
Name | Description
----------------|--------------
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.
Macros:
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.
Macros:
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.
Macros:
Name | Description
----------------|--------------
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.
Macros:
Name | Description
----------------|--------------
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.
Macros:
Name | Description
----------------|--------------
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.
Macros:
Name | Description
----------------|--------------
plugindir | **Required.** The directory containing this plugin.
wload1 | **Optional.** The 1-minute warning threshold. Defaults to 5.
wload5 | **Optional.** The 5-minute warning threshold. Defaults to 4.
wload15 | **Optional.** The 15-minute warning threshold. Defaults to 3.
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.
Macros:
Name | Description
----------------|--------------
plugindir | **Required.** The directory containing this plugin.
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.
Macros:
Name | Description
----------------|--------------
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
oid | **Optional.** The SNMP OID. Defaults to "1.3.6.1.2.1.1.3.0".
community | **Optional.** The SNMP community. Defaults to "public".

8
itl/command-common.conf
View File

@ -156,13 +156,13 @@ object CheckCommand "ssh" inherits "plugin-check-command" {
object CheckCommand "disk" inherits "plugin-check-command" { object CheckCommand "disk" inherits "plugin-check-command" {
command = [ command = [
"$plugindir$/check_disk", "$plugindir$/check_disk",
"-w", "$wfree$", "-w", "$wfree$%",
"-c", "$cfree$" "-c", "$cfree$%"
], ],
macros += { macros += {
wfree = "20%", wfree = 20,
cfree = "10%", cfree = 10",
} }
} }