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 information.
+release tarballs contain an *INSTALL* file with further instructions.
#### Installation Paths
> Depending on how you installed Icinga 2 some of those paths and options
> might be different.
-In order for commands to work you will need to grant the web server
-write permissions for the command pipe:
+In order for commands to work you will need to add your web server user to
+the *icinga-cmd* group:
- # chgrp www-data /var/run/icinga2/cmd/icinga2.cmd
+ # usermod -a -G icinga-cmd www-data
> **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
UI installation URL, e.g.
--- /dev/null
+### 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.
\ No newline at end of file
#### 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.
#### Service States
+Services can be in any of the following states:
+
Name | Description
------------|--------------
- OK | The service is fully available.
- WARNING | The service is experiencing some problems but is still considered available.
+ 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.
> 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
+executing commands Icinga 2 checks the following objects in this
order to look up macros:
1. User object (only for notifications)
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
+When using the *my-ping* command you can override 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["packets"] = 10 // Overrides the default value of 5 given in the command
},
macros["address"] = "10.0.0.1"
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.
+ 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
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.
+ 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
- -----------------------|---------------
+ 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.
+#### 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
Templates may be used to apply a set of similar settings to more than one
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
+templates. Attributes inherited from a template can be overridden in the
object if necessary.
### Groups
groups = [ "all-hosts" ],
- check = "ping",
-
host_dependencies = [ "router" ],
service_dependencies = [
vhost = "test1.example.org",
port = 81
}
- }
+ },
+
+ check = "ping"
}
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.
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.
- macros |TODO
+ macros |**Optional.** A dictionary containing macros that are specific to this host.
### HostGroup
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).
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.
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.
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
+ 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
### 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:
- TODO
+ object Notification "localhost-ping-notification" {
+ host = "localhost",
+ service = "ping4",
+
+ notification_command = "mail-notification",
+
+ users = [ "user1", "user2" ]
+ }
Attributes:
----------------|----------------
host |**Required.** The name of the host 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.
user_groups |**Optional.** A list of user group names who should be notified.
times |TODO
Name |Description
----------------|----------------
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
enable_notifications|TODO
notification_period|TODO
Name |Description
----------------|----------------
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
### ConsoleLogger
Name |Description
----------------|----------------
- methods |TODO
- command |TODO
- export_macros |TODO
- escape_macros |TODO
- macros |TODO
- timeout |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 |**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 |**Optional.** A list of macros which should be exported as environment variables prior to executing the command.
+ escape_macros |**Optional.** A list of macros which should be shell-escaped in the command.
+ macros |**Optional.** A dictionary containing macros that are specific to this command.
+ timeout |**Optional.** The command timeout in seconds. Defaults to 5 minutes.
### NotificationCommand
Name |Description
----------------|----------------
- methods |TODO
- command |TODO
- export_macros |TODO
- escape_macros |TODO
- macros |TODO
- timeout |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 |**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 |**Optional.** A list of macros which should be exported as environment variables prior to executing the command.
+ escape_macros |**Optional.** A list of macros which should be shell-escaped in the command.
+ macros |**Optional.** A dictionary containing macros that are specific to this command.
+ timeout |**Optional.** The command timeout in seconds. Defaults to 5 minutes.
### EventCommand
Name |Description
----------------|----------------
- methods |TODO
- command |TODO
- export_macros |TODO
- escape_macros |TODO
- macros |TODO
- timeout |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 |**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 |**Optional.** A list of macros which should be exported as environment variables prior to executing the command.
+ escape_macros |**Optional.** A list of macros which should be shell-escaped in the command.
+ macros |**Optional.** A dictionary containing macros that are specific to this command.
+ timeout |**Optional.** The command timeout in seconds. Defaults to 5 minutes.
### PerfdataWriter
Name |Description
----------------|----------------
- perfdata\_path |**Optional.** Path to the service perfdata 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.
+ perfdata\_path |**Optional.** Path to the service performance data file. Defaults to IcingaLocalStateDir + "/cache/icinga2/perfdata/perfdata".
+ 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.
> **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.
### IdoMySqlConnection
## Icinga Template Library
-TODO
-
### 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
#### 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
+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
+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
+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
+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
+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
+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
+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
+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
+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
+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
+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
+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
+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
+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
+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
+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
+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
+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".
object CheckCommand "disk" inherits "plugin-check-command" {
command = [
"$plugindir$/check_disk",
- "-w", "$wfree$",
- "-c", "$cfree$"
+ "-w", "$wfree$%",
+ "-c", "$cfree$%"
],
macros += {
- wfree = "20%",
- cfree = "10%",
+ wfree = 20,
+ cfree = 10",
}
}
projects / icinga2 / commitdiff