Documentation: Update command definitions to use argument conditions.

Fixes #6364
This commit is contained in:
Michael Friedrich 2014-06-11 14:05:47 +02:00
parent 9c40164e6c
commit b4248123f7
4 changed files with 90 additions and 54 deletions

View File

@ -101,7 +101,7 @@ Sample configuration for common plugins is shipped with Icinga 2 as part of the
* Revamped Commands
One command to rule them all - supporting optional and conditional [command arguments](#commands-arguments).
One command to rule them all - supporting optional and conditional [command arguments](#command-arguments).
[Environment variables](#command-environment-variables) exported on-demand populated with
runtime evaluated macros.
Three types of commands used for different actions: checks, notifications and events.

View File

@ -654,26 +654,30 @@ which can be accessed as runtime macros by the executed check command.
Define the default check command custom attribute `disk_wfree` and `disk_cfree`
(freely definable naming schema) and their default threshold values. You can
then use these custom attributes as runtime macros on the command line.
then use these custom attributes as runtime macros for [command arguments](#command-arguments)
on the command line.
The default custom attributes can be overridden by the custom attributes
defined in the service using the check command `disk`. The custom attributes
defined in the service using the check command `my-disk`. The custom attributes
can also be inherited from a parent template using additive inheritance (`+=`).
object CheckCommand "disk" {
object CheckCommand "my-disk" {
import "plugin-check-command"
command = [
PluginDir + "/check_disk",
"-w", "$disk_wfree$%",
"-c", "$disk_cfree$%"
],
command = PluginDir + "/check_disk"
arguments = {
"-w" = "$disk_wfree$%"
"-c" = "$disk_cfree$%"
}
vars.disk_wfree = 20
vars.disk_cfree = 10
}
The host `localhost` with the service `disk` checks all disks with modified
The host `localhost` with the service `my-disk` checks all disks with modified
custom attributes (warning thresholds at `10%`, critical thresholds at `5%`
free disk space).
@ -684,17 +688,17 @@ free disk space).
address6 = "::1"
}
object Service "disk" {
object Service "my-disk" {
import "generic-service"
host_name = "localhost"
check_command = "disk"
check_command = "my-disk"
vars.disk_wfree = 10
vars.disk_cfree = 5
}
#### <a id="commands-arguments"></a> Command Arguments
#### <a id="command-arguments"></a> Command Arguments
By defining a check command line using the `command` attribute Icinga 2
will resolve all macros in the static string or array. Sometimes it is
@ -796,11 +800,11 @@ the service is applied to. If not set, the check command `my-ssh` will omit the
The `my-host1` will get the `my-ssh` service checking on the default port:
[2014-05-26 21:52:23 +0200] <Q #0x7f8bdd5f4a48 W #0x7f8bdd5f4b88> notice/base: Running command '/usr/lib/nagios/plugins/check_ssh', '129.168.1.50': PID 27281
[2014-05-26 21:52:23 +0200] notice/Process: Running command '/usr/lib/nagios/plugins/check_ssh', '129.168.1.50': PID 27281
The `my-host2` will inherit the `custom_ssh_port` variable to the service and execute a different command:
[2014-05-26 21:51:32 +0200] <Q #0x7f8bdd5f4708 W #0x7f8bdd5f4848> notice/base: Running command '/usr/lib/nagios/plugins/check_ssh', '-p', '2222', '129.168.2.50': PID 26956
[2014-05-26 21:51:32 +0200] notice/Process: Running command '/usr/lib/nagios/plugins/check_ssh', '-p', '2222', '129.168.2.50': PID 26956
### <a id="notification-commands"></a> Notification Commands
@ -869,6 +873,11 @@ as environment variables and can be used in the notification script:
/usr/bin/printf "%b" $template | mail -s "$NOTIFICATIONTYPE - $HOSTDISPLAYNAME - $SERVICEDISPLAYNAME is $SERVICESTATE" $USEREMAIL
> **Note**
>
> This example is for `exim` only. Requires changes for `sendmail` and
> other MTAs.
While it's possible to specify the entire notification command right
in the NotificationCommand object it is generally advisable to create a
shell script in the `/etc/icinga2/scripts` directory and have the
@ -1162,15 +1171,18 @@ Here is an example of a command definition which uses user-defined custom attrib
import "plugin-check-command"
command = [
PluginDir + "/check_ping",
"-4",
"-H", "$address$",
"-w", "$ping_wrta$,$ping_wpl$%",
"-c", "$ping_crta$,$ping_cpl$%",
"-p", "$ping_packets$",
"-t", "$ping_timeout$"
PluginDir + "/check_ping", "-4"
]
arguments = {
"-H" = "$ping_address$"
"-w" = "$ping_wrta$,$ping_wpl$%"
"-c" = "$ping_crta$,$ping_cpl$%"
"-p" = "$ping_packets$"
"-t" = "$ping_timeout$"
}
vars.ping_address = "$address$"
vars.ping_wrta = 100
vars.ping_wpl = 5
vars.ping_crta = 200
@ -1181,7 +1193,9 @@ Here is an example of a command definition which uses user-defined custom attrib
Custom attribute names used at runtime 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 (`$$`).
it with an additional dollar sign (`$$`). This example also makes use of the
[command arguments](#command-arguments) passed to the command line. `-4` must
be added as additional array key.
### <a id="runtime-custom-attributes-evaluation-order"></a> Runtime Custom Attributes Evaluation Order
@ -1226,14 +1240,23 @@ This is useful for example for hiding sensitive information on the command line
when passing credentials to database checks:
object CheckCommand "mysql-health" {
import "plugin-check-command",
import "plugin-check-command"
command = PluginDir + "/check_mysql -H $address$ -d $db$",
command = [
PluginDir + "/check_mysql"
]
vars.mysql_user = "icinga_check",
arguments = {
"-H" = "$mysql_address$"
"-d" = "$mysql_database$"
}
vars.mysql_address = "$address$"
vars.mysql_database = "icinga"
vars.mysql_user = "icinga_check"
vars.mysql_pass = "password"
env.MYSQLUSER = "$mysql_user$",
env.MYSQLUSER = "$mysql_user$"
env.MYSQLPASS = "$mysql_pass$"
}

View File

@ -68,25 +68,18 @@ remote client.
The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe`
can be embedded into the Icinga 2 `CheckCommand` configuration syntax.
You can use the `check_nrpe` plugin from the NRPE project to query the NRPE daemon.
Icinga 2 provides the [nrpe check command](#plugin-check-command-nrpe) for this:
Example:
object CheckCommand "check_nrpe" {
import "plugin-check-command"
command = [
PluginDir + "/check_nrpe",
"-H", "$address$",
"-c", "$remote_nrpe_command$",
]
}
object Service "users" {
import "generic-service"
host_name = "remote-nrpe-host"
check_command = "check_nrpe"
vars.remote_nrpe_command = "check_users"
check_command = "nrpe"
vars.nrpe_command = "check_users"
}
nrpe.cfg:

View File

@ -714,6 +714,19 @@ host and let the dependency ignore that on that instead of the hardcoded host na
to the Icinga 1.x example and a best practice hint only.
#### <a id="manual-config-migration-hints-distributed-setup"></a> Manual Config Migration Hints for Distributed Setups
* Icinga 2 does not use active/passive instances calling OSCP commands and requiring the NSCA
daemon for passing check results between instances.
* Icinga 2 does not support any 1.x NEB addons for check load distribution
* If your current setup consists of instances distributing the check load, you should consider
building a [load distribution](#cluster-scenarios-load-distribution) setup with Icinga 2.
* If your current setup includes active/passive clustering with external tools like Pacemaker/DRBD
consider the [High Availability](#cluster-scenarios-high-availability) setup.
* If you have build your own custom configuration deployment and check result collecting mechanism
you should re-design your setup and re-evaluate your requirements, and how they may be fulfilled
using the Icinga 2 cluster capabilities.
## <a id="differences-1x-2"></a> Differences between Icinga 1.x and 2
@ -977,7 +990,14 @@ With the freely definable custom attributes in Icinga 2 it looks like this:
vars.cpl = 60
}
The Classic UI feature named `Command Expander` does not work with Icinga 2.
> **Note**
>
> For better maintainability you should consider using [command arguments](#command-arguments)
> for your check commands.
> **Note**
>
> The Classic UI feature named `Command Expander` does not work with Icinga 2.
#### <a id="differences-1x-2-environment-macros"></a> Environment Macros