tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update documentation. 

Refs #5877
This commit is contained in:
Gunnar Beutner 2014-03-31 13:27:39 +02:00
parent 036fd3303f
commit fdd5fbc217
10 changed files with 51 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
doc/2.1-setting-up-icinga-2.md
View File

@ -114,19 +114,17 @@ the features which have been enabled with `icinga2-enable-feature`. See
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.
### <a id="macros-conf"></a> macros.conf
### <a id="constants-conf"></a> constants.conf
The `conf.d/macros.conf` file can be used to define global macros:
The `constants.conf` constants file can be used to define global constants:
/**
* Global macros
* This file defines global constants which can be used in
* the other configuration files. At a minimum the
* PluginDir constant should be defined.
*/
const IcingaMacros = {
plugindir = "/usr/local/icinga/libexec"
}
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.
const PluginDir = "/usr/lib/nagios/plugins"
### <a id="localhost-conf"></a> localhost.conf

17
doc/2.2-setting-up-check-plugins.md
View File

@ -25,7 +25,7 @@ FreeBSD | nagios-plugins | /usr/local/libexec/nagios
OS X (MacPorts) | nagios-plugins | /opt/local/libexec
Depending on which directory your plugins are installed into you may need to
update the `plugindir` macro in your Icinga 2 configuration. This macro is used
update the global `PluginDir` constant in your Icinga 2 configuration. This macro is used
by the service templates contained in the Icinga Template Library to determine
where to find the plugin binaries.
@ -41,20 +41,21 @@ list of popular community sites which host check plugins:
* [Icinga Wiki](https://wiki.icinga.org)
The recommended way of setting up these plugins is to copy them to a common directory
and creating an extra global macro, e.g. `customplugindir` in your `macros.conf`
and creating an extra global constant, e.g. `CustomPluginDir` in your `constants.conf`
configuration file:
# cp check_snmp_int.pl /opt/plugins
# chmod +x /opt/plugins/check_snmp_int.pl
# cat /etc/icinga2/conf/macros.conf
# cat /etc/icinga2/constants.conf
/**
* Global macros
* This file defines global constants which can be used in
* the other configuration files. At a minimum the
* PluginDir constant should be defined.
*/
const IcingaMacros = {
plugindir = "/usr/lib/nagios/plugins",
customplugindir = "/opt/monitoring"
}
const PluginDir = "/usr/lib/nagios/plugins"
const CustomPluginDir = "/opt/monitoring"
Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
by trying to run it on the console using whichever user Icinga 2 is running as:

12
doc/3.02-commands.md
View File

@ -6,10 +6,10 @@ events should be handled.
> **Note**
>
> Define the `$plugindir$` macro in your global `IcingaMacros` variable
> (located in `/etc/icinga2/conf.d/macros.conf` by default) and use
> Define the global `PluginDir` constant (located in
> `/etc/icinga2/conf.d/macros.conf` by default) and use
> it in all your command object definitions.
> Put your plugins and scripts into the directory defined by the `$plugindir$` macro
> Put your plugins and scripts into the directory defined by the `PluginDir` constant
> and make sure they are executable by the Icinga 2 user.
### <a id="environment-macros"></a> Environment Macros
@ -38,7 +38,7 @@ to define all macros in the `export_macros` attribute as list.
> to support native plugin based check methods.
Unless you have done so already, download your check plugin and put it
into the `$plugindir$` directory. The following example uses the
into the `PluginDir` directory. The following example uses the
`check_disk` plugin shipped with the Nagios Plugins package.
The plugin path and all command arguments are made a list of
@ -63,7 +63,7 @@ then use these macros on the command line.
import "plugin-check-command",
command = [
"$plugindir$/check_disk",
PluginDir + "/check_disk",
"-w", "$wfree$%",
"-c", "$cfree$%"
],
@ -191,7 +191,7 @@ information in the check output (`-o`).
import "plugin-event-command",
command = [
"$plugindir$/process_check_result",
PluginDir + "/process_check_result",
"-H",
"$HOSTNAME$",
"-S",

40
doc/3.03-macros.md
View File

@ -25,7 +25,7 @@ Here is an example of a command definition which uses user-defined macros:
import "plugin-check-command",
command = [
"$plugindir$/check_ping",
PluginDir + "/check_ping",
"-4",
"-H", "$address$",
"-w", "$wrta$,$wpl$%",
@ -53,7 +53,7 @@ Here is an example of a command definition which uses user-defined 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 using
Macro names must be enclosed in two `$` signs, e.g. `$address$`. When using
the `$` sign as single character, you need to escape it with an additional dollar
sign (`$$`).
@ -96,46 +96,12 @@ emitted to the Icinga 2 log.
> 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.
#### Custom Variables as Runtime Macros
Custom variables are made available as macros using an underscore and the object type
in uppercase characters as additional prefix. For example `_HOST`name "_HOST<name>"
where <name> is the name of the custom variable.
#### Runtime Macro Evaluation Order in Cluster Mode
These macros are evaluated and calculated upon command execution on each node. If a
cluster node defines additional macros overriding the default tuples, the calculated
macro values will be different and affect only the node executing the command.
Node 1:
const IcingaMacros = {
plugindir = "/usr/lib/icinga/plugins"
}
Node 2:
const IcingaMacros = {
plugindir = "/usr/lib/monitoring/plugins"
}
CheckCommand definition:
object CheckCommand "whatever" {
import "plugin-check-command",
command = "$plugindir$/check_whatever"
}
On Node 1, this will be evaluated into `/usr/lib/icinga/plugins/check_whatever`.
On Node 2, Icinga 2 will attempt to execute `/usr/lib/icinga/monitoring/check_whatever`
instead.
### <a id="host-runtime-macros"></a> Host Runtime Macros
The following host macros are available in all commands that are executed for
@ -251,7 +217,7 @@ when passing credentials to database checks:
object CheckCommand "mysql-health" {
import "plugin-check-command",
command = "$plugindir$/check_mysql -H $address$ -d $db$",
command = PluginDir + "/check_mysql -H $address$ -d $db$",
/* default macro values */
macros = {
"MYSQLUSER" = "icinga_check",

2
doc/3.04-notifications.md
View File

@ -176,7 +176,7 @@ Define an additional `NotificationCommand` for sms notifications.
> or local hardware with a sim card active.
object NotificationCommand "sms-notification" {
command = "$plugindir$/send_sms_notification $mobile$ ..."
command = PluginDir + "/send_sms_notification $mobile$ ..."
}
The two new notification escalations are added onto the host `localhost`

6
doc/3.15-monitoring-remote-clients.md
View File

@ -43,7 +43,7 @@ its return code and output. `check_by_ssh` is available in the [Monitoring Plugi
object CheckCommand "check_by_ssh_swap" {
import "plugin-check-command",
command = [ "$plugindir$/check_by_ssh",
command = [ PluginDir + "/check_by_ssh",
"-l", "remoteuser",
"-H", "$address$",
"-C", "\"/usr/local/icinga/libexec/check_swap -w $warn$ -c $crit$\""
@ -78,7 +78,7 @@ Example:
object CheckCommand "check_nrpe" {
import "plugin-check-command",
command = [ "$plugindir$/check_nrpe",
command = [ PluginDir + "/check_nrpe",
"-H", "$address$",
"-c", "$remote_nrpe_command$",
],
@ -114,7 +114,7 @@ Example:
object CheckCommand "check_nscp" {
import "plugin-check-command",
command = [ "$plugindir$/check_nt",
command = [ PluginDir + "/check_nt",
"-H", "$address$",
"-p", "$port$",
"-v", "$remote_nscp_command$",

11
doc/4.3-object-types.md
View File

@ -419,7 +419,12 @@ Example:
object CheckCommand "check_snmp" {
import "plugin-check-command",
command = "$plugindir$/check_snmp -H $address$ -C $community$ -o $oid$",
command = [
PluginDir + "/check_snmp",
"-H", "$address$",
"-C", "$community$",
"-o", "$oid$"
],
macros = {
address = "127.0.0.1",
@ -447,7 +452,9 @@ Example:
object NotificationCommand "mail-service-notification" {
import "plugin-notification-command",
command = [ IcingaSysconfDir + "/icinga2/scripts/mail-notification.sh" ],
command = [
IcingaSysconfDir + "/icinga2/scripts/mail-notification.sh"
],
export_macros = [
"NOTIFICATIONTYPE",

23
doc/5-icinga-template-library.md
View File

@ -10,6 +10,9 @@ file:
include <itl/itl.conf>
The ITL assumes that there's a global constant named `PluginDir` which contains
the path of the plugins from the Monitoring Plugins project.
## <a id="itl-check-commands"></a> Check Commands
### <a id="itl-ping4"></a> ping4
@ -20,7 +23,6 @@ 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.
@ -37,7 +39,6 @@ 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.
@ -54,7 +55,6 @@ 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.".
@ -66,7 +66,6 @@ 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 3.
text | **Optional.** Plugin output. Defaults to "No Passive Check Result Received.".
@ -78,7 +77,6 @@ Macros:
Name | Description
----------------|--------------
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
port | **Required.** The port that should be checked.
@ -90,7 +88,6 @@ Macros:
Name | Description
----------------|--------------
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
port | **Required.** The port that should be checked.
@ -102,7 +99,6 @@ Macros:
Name | Description
----------------|--------------
plugindir | **Required.** The directory containing this plugin.
vhost | **Required.** The name of the virtual host that should be checked.
### <a id="itl-http-ip"></a> http_ip
@ -113,7 +109,6 @@ Macros:
Name | Description
----------------|--------------
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
### <a id="itl-https-vhost"></a> https_vhost
@ -124,7 +119,6 @@ Macros:
Name | Description
----------------|--------------
plugindir | **Required.** The directory containing this plugin.
vhost | **Required.** The name of the virtual host that should be checked.
### <a id="itl-https-ip"></a> https_ip
@ -135,7 +129,6 @@ Macros:
Name | Description
----------------|--------------
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
### <a id="itl-smtp"></a> smtp
@ -146,7 +139,6 @@ Macros:
Name | Description
----------------|--------------
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
### <a id="itl-ssmtp"></a> ssmtp
@ -157,7 +149,6 @@ 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.
@ -169,7 +160,6 @@ Macros:
Name | Description
----------------|--------------
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
### <a id="itl-ssh"></a> ssh
@ -180,7 +170,6 @@ Macros:
Name | Description
----------------|--------------
plugindir | **Required.** The directory containing this plugin.
address | **Required.** The host's address.
### <a id="itl-disk"></a> disk
@ -191,7 +180,6 @@ 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.
@ -203,7 +191,6 @@ 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 critical threshold. Defaults to 50.
@ -215,7 +202,6 @@ 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 critical threshold. Defaults to 400.
@ -227,7 +213,6 @@ 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.
@ -243,7 +228,6 @@ 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".
@ -256,7 +240,6 @@ 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".

19
doc/8-differences-between-icinga-1x-and-2.md
View File

@ -76,15 +76,16 @@ Global macros such as for the plugin directory, usernames and passwords can be
set in the `resource.cfg` configuration file in Icinga 1.x. By convention the
`USER1` macro is used to define the directory for the plugins.
Icinga 2 uses a global `IcingaMacros` constant variable which is set in the
`conf.d/macros.conf` file:
Icinga 2 uses global constants instead. In the default config these are
set in the `constants.conf` configuration file:
/**
* Global macros
*/
set IcingaMacros = {
plugindir = "/usr/lib/nagios/plugins"
}
* This file defines global constants which can be used in
* the other configuration files. At a minimum the
* PluginDir constant should be defined.
*/
const PluginDir = "/usr/lib/nagios/plugins"
> **Note**
>
@ -280,7 +281,7 @@ are separated from the command name using an exclamation mark (`!`).
With the freely definable macros in Icinga 2 it looks like this:
object CheckCommand "ping4" {
command = "$plugindir$/check_ping -H $HOSTADDRESS$ -w $wrta$,$wpl%$ -c $crta$,$cpl%$",
command = PluginDir + "/check_ping -H $HOSTADDRESS$ -w $wrta$,$wpl%$ -c $crta$,$cpl%$",
}
object Service "PING" {
@ -295,7 +296,7 @@ With the freely definable macros in Icinga 2 it looks like this:
> **Note**
>
> Tip: The above example uses the global $plugindir$ macro instead of the Icinga 1.x
> Tip: The above example uses the global `PluginDir` constant instead of the Icinga 1.x
> $USER1$ macro. It also replaces the Icinga 1.x notation with $ARGn$ with freely
> definable macros.

2
icinga2.spec
View File

@ -265,7 +265,7 @@ install -D -m 0644 etc/icinga/icinga-classic-apache.conf %{buildroot}%{apachecon
# fix plugin path on x64
%if "%{_vendor}" != "suse"
sed -i 's@plugindir = .*@plugindir = "%{_libdir}/nagios/plugins"@' %{buildroot}/%{_sysconfdir}/%{name}/conf.d/macros.conf
sed -i 's@PluginDir = .*@PluginDir = "%{_libdir}/nagios/plugins"@' %{buildroot}/%{_sysconfdir}/%{name}/constants.conf
%endif
# remove features-enabled symlinks