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

Documentation: Explain macro array support, repeat_key, add icmp example 

fixes #7868
fixes #7867
This commit is contained in:
Michael Friedrich 2014-11-27 16:57:58 +01:00
parent 3c84824883
commit 842b3a9cd7
6 changed files with 175 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
doc/1-about.md
View File

@ -54,6 +54,21 @@ Icinga 2 is available as [Vagrant Demo VM](#vagrant).
## <a id="whats-new"></a> What's new
### What's New in Version 2.2.1
> **Note**
>
> To-be-released.
#### Changes
* Support arrays in [command argument macros](#command-passing-parameters) #6709
* Allows to define multiple parameters for [nrpe -a](#plugin-check-command-nrpe), [nscp -l](#plugin-check-command-nscp), [disk -p](#plugin-check-command-disk), [dns -a](#plugin-check-command-dns).
#### Issues
### What's New in Version 2.2.0
#### Changes

2
doc/2-getting-started.md
View File

@ -516,7 +516,7 @@ check.
/* No parameters. */
}
vars.disks["disk /"] = {
disk_partition = "/"
disk_partitions = "/"
}
/* Define notification mail attributes for notification apply rules in `notifications.conf`. */

152
doc/4-monitoring-basics.md
View File

@ -943,8 +943,8 @@ definition based on these required parameters and/or default values.
#### <a id="command-passing-parameters"></a> Passing Check Command Parameters from Host or Service
Unlike Icinga 1.x check command parameters are defined as custom attributes
which can be accessed as runtime macros by the executed check command.
Check command parameters are defined as custom attributes 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
@ -961,7 +961,6 @@ The default custom attributes can be overridden by 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 "my-disk" {
import "plugin-check-command"
@ -970,34 +969,55 @@ can also be inherited from a parent template using additive inheritance (`+=`).
arguments = {
"-w" = "$disk_wfree$%"
"-c" = "$disk_cfree$%"
"-W" = "$disk_inode_wfree$%"
"-K" = "$disk_inode_cfree$%"
"-p" = "$disk_partitions$"
"-x" = "$disk_partitions_excluded$"
}
vars.disk_wfree = 20
vars.disk_cfree = 10
}
> **Note**
>
> A proper example for the `check_disk` plugin is already shipped with Icinga 2
> ready to use with the [plugin check commands](#plugin-check-command-disk).
The host `localhost` with the service `my-disk` checks all disks with modified
custom attributes (warning thresholds at `10%`, critical thresholds at `5%`
The host `localhost` with the applied service `basic-partitions` checks a basic set of disk partitions
with modified custom attributes (warning thresholds at `10%`, critical thresholds at `5%`
free disk space).
object Host "localhost" {
import "generic-host"
The custom attribute `disk_partition` can either hold a single string or an array of
string values for passing multiple partitions to the `check_disk` check plugin.
object Host "my-server" {
import "generic-host"
address = "127.0.0.1"
address6 = "::1"
vars.local_disks["basic-partitions"] = {
disk_partitions = [ "/", "/tmp", "/var", "/home" ]
}
}
object Service "my-disk" {
apply Service for (disk => config in host.vars.local_disks) {
import "generic-service"
host_name = "localhost"
check_command = "my-disk"
vars += config
vars.disk_wfree = 10
vars.disk_cfree = 5
assign where host.vars.local_disks
}
More details on using arrays in custom attributes can be found in
[this chapter](#runtime-custom-attributes).
#### <a id="command-arguments"></a> Command Arguments
By defining a check command line using the `command` attribute Icinga 2
@ -1050,6 +1070,10 @@ If the `vars.http_ssl` custom attribute is set in the service, host or command
object definition, Icinga 2 will add the `-S` argument based on the `set_if`
numeric value to the command line. String values are not supported.
If the macro value cannot be resolved, Icinga 2 will not add the defined argument
to the final command argument array. Empty strings for macro values won't omit
the argument.
That way you can use the `check_http` command definition for both, with and
without SSL enabled checks saving you duplicated command definitions.
@ -1701,52 +1725,100 @@ it is escaped like this: `entry1;ent\;ry2;entry3`.
Custom attributes may be used in command definitions to dynamically change how the command
is executed.
Additionally there are Icinga 2 features such as the `PerfDataWriter` type
Additionally there are Icinga 2 features such as the [PerfDataWriter](#performance-data) feature
which use custom runtime attributes to format their output.
> **Tip**
>
> Custom attributes are identified by the 'vars' dictionary attribute as short name.
> Accessing the different attribute keys is possible using the '.' accessor.
> Custom attributes are identified by the `vars` dictionary attribute as short name.
> Accessing the different attribute keys is possible using the [index accessor](#indexer) `.`.
Custom attributes in command definitions or performance data templates are evaluated at
runtime when executing a command. These custom attributes cannot be used elsewhere
(e.g. in other configuration attributes).
runtime when executing a command. These custom attributes cannot be used somewhere else
for example in other configuration attributes.
Custom attribute values must be either a string, a number or a boolean value. Arrays
and dictionaries cannot be used.
Custom attribute values must be either a string, a number, a boolean value or an array.
Dictionaries cannot be used at the time of writing.
Here is an example of a command definition which uses user-defined custom attributes:
Arrays can be used to pass multiple arguments with or without repeating the key string.
This helps passing multiple parameters to check plugins requiring them. Prominent
plugin examples are:
object CheckCommand "my-ping" {
* [check_disk -p](#plugin-check-command-disk)
* [check_nrpe -a](#plugin-check-command-nrpe)
* [check_nscp -l](#plugin-check-command-nscp)
* [check_dns -a](#plugin-check-command-dns)
More details on how to use `repeat_key` and other command argument options can be
found in [this section](#objecttype-checkcommand-arguments).
> **Note**
>
> If a macro value cannot be resolved, be it a single macro, or a recursive macro
> containing an array of macros, the entire command argument is skipped.
This is an example of a command definition which uses user-defined custom attributes:
object CheckCommand "my-icmp" {
import "plugin-check-command"
command = [
PluginDir + "/check_ping", "-4"
]
command = [ "/bin/sudo", PluginDir + "/check_icmp" ]
arguments = {
"-H" = "$ping_address$"
"-w" = "$ping_wrta$,$ping_wpl$%"
"-c" = "$ping_crta$,$ping_cpl$%"
"-p" = "$ping_packets$"
"-t" = "$ping_timeout$"
"-H" = {
value = "$icmp_targets$"
repeat_key = false
order = 1
}
"-w" = "$icmp_wrta$,$icmp_wpl$%"
"-c" = "$icmp_crta$,$icmp_cpl$%"
"-s" = "$icmp_source$"
"-n" = "$icmp_packets$"
"-i" = "$icmp_packet_interval$"
"-I" = "$icmp_target_interval$"
"-m" = "$icmp_hosts_alive$"
"-b" = "$icmp_data_bytes$"
"-t" = "$icmp_timeout$"
}
vars.ping_address = "$address$"
vars.ping_wrta = 100
vars.ping_wpl = 5
vars.ping_crta = 200
vars.ping_cpl = 15
vars.ping_packets = 5
vars.ping_timeout = 0
vars.icmp_wrta = 200.00
vars.icmp_wpl = 40
vars.icmp_crta = 500.00
vars.icmp_cpl = 80
vars.notes = "Requires setuid root or sudo."
}
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 (`$$`). This example also makes use of the
[command arguments](#command-arguments) passed to the command line. `-4` must
be added as additional array key.
Custom attribute names used at runtime must be enclosed in two `$` signs,
for example `$address$`.
> **Note**
>
> When using the `$` sign as single character, you need to escape it with an
> additional dollar sign (`$$`).
This example also makes use of the [command arguments](#command-arguments) passed
to the command line.
You can integrate the above example `CheckCommand` definition
[passing command argument parameters](#command-passing-parameters) like this:
object Host "my-icmp-host" {
import "generic-host"
address = "192.168.1.10"
vars.address_mgmt = "192.168.2.10"
vars.address_web = "192.168.10.10"
vars.icmp_targets = [ "$address$", "$host.vars.address_mgmt$", "$host.vars.address_web$" ]
}
apply Service "my-icmp" {
check_command = "icmp"
check_interval = 1m
retry_interval = 30s
vars.icmp_targets = host.vars.icmp_targets
assign where host.vars.icmp_targets
}
### <a id="runtime-custom-attributes-evaluation-order"></a> Runtime Custom Attributes Evaluation Order

34
doc/7-configuring-icinga-2.md
View File

@ -908,6 +908,8 @@ Attributes:
arguments |**Optional.** A dictionary of command arguments.
#### <a id="objecttype-checkcommand-arguments"></a> CheckCommand Arguments
Command arguments can be defined as key-value-pairs in the `arguments`
dictionary. If the argument requires additional configuration for example
a `description` attribute or an optional condition, the value can be defined
@ -923,11 +925,13 @@ CheckCommand:
arguments = {
"-X" = {
value = "$x_val$"
key = "-Xnew" /* optional, set a new key identifier */
description = "My plugin requires this argument for doing X."
required = false /* optional, no error if not set */
skip_key = false /* always use "-X <value>" */
set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
order = -1 /* first position */
repeat_key = true /* if `value` is an array, repeat the key as parameter: ... 'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]' ... */
}
"-Y" = {
value = "$y_val$"
@ -936,21 +940,33 @@ CheckCommand:
skip_key = true /* don't prefix "-Y" only use "<value>" */
set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
order = 0 /* second position */
repeat_key = false /* if `value` is an array, do not repeat the key as parameter: ... 'key' 'value[0]' 'value[1]' 'value[2]' ... */
}
}
Option | Description
------------|--------------
value | Optional argument value.
key | Optional argument key overriding the key identifier.
description | Optional argument description.
required | Required argument. Execution error if not set. Defaults to false (optional).
skip_key | Use the value as argument and skip the key.
set_if | Argument is added if the macro resolves to a defined numeric value. String values are not supported.
order | Set if multiple arguments require a defined argument order.
repeat_key | If the argument value is an array, repeat the argument key, or not. Defaults to true (repeat).
Argument order:
`..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...`
Argument array `repeat_key = true`:
`'key' 'value[0]' 'key' 'value[1]' 'key' 'value[2]'`
Argument array `repeat_key = false`:
`'key' 'value[0]' 'value[1]' 'value[2]'`
### <a id="objecttype-notificationcommand"></a> NotificationCommand
@ -993,7 +1009,7 @@ Attributes:
zone |**Optional.** The zone this object is a member of.
arguments |**Optional.** A dictionary of command arguments.
Command arguments can be used the same way as for `CheckCommand` objects.
Command arguments can be used the same way as for [CheckCommand objects](#objecttype-checkcommand-arguments).
### <a id="objecttype-eventcommand"></a> EventCommand
@ -1020,7 +1036,7 @@ Attributes:
timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
arguments |**Optional.** A dictionary of command arguments.
Command arguments can be used the same way as for `CheckCommand` objects.
Command arguments can be used the same way as for [CheckCommand objects](#objecttype-checkcommand-arguments).
### <a id="objecttype-notification"></a> Notification
@ -2104,7 +2120,7 @@ Custom Attributes:
Name | Description
-------------------|--------------
ftp_address | **Optional.** The host's address. Defaults to "$address".
ftp_address | **Optional.** The host's address. Defaults to "$address$".
#### <a id="plugin-check-command-smtp"></a> smtp
@ -2208,8 +2224,10 @@ disk_wfree | **Optional.** The free space warning threshold in %. Defaults
disk_cfree | **Optional.** The free space critical threshold in %. Defaults to 10.
disk_inode_wfree | **Optional.** The free inode warning threshold.
disk_inode_cfree | **Optional.** The free inode critical threshold.
disk_partition | **Optional.** The partition.
disk_partition_excluded | **Optional.** The excluded partition.
disk_partition | **Optional.** The partition. **Deprecated in 2.3.**
disk_partition_excluded | **Optional.** The excluded partition. **Deprecated in 2.3.**
disk_partitions | **Optional.** The partition(s). Multiple partitions must be defined as array.
disk_partitions_excluded | **Optional.** The excluded partition(s). Multiple partitions must be defined as array.
#### <a id="plugin-check-command-users"></a> users
@ -2333,7 +2351,8 @@ Name | Description
---------------------|--------------
dns_lookup | **Optional.** The hostname or IP to query the DNS for. Defaults to $host_name$.
dns_server | **Optional.** The DNS server to query. Defaults to the server configured in the OS.
dns_expected_answer | **Optional.** The answer to look for. A hostname must end with a dot.
dns_expected_answer | **Optional.** The answer to look for. A hostname must end with a dot. **Deprecated in 2.3.**
dns_expected_answers | **Optional.** The answer(s) to look for. A hostname must end with a dot. Multiple answers must be defined as array.
dns_authoritative | **Optional.** Expect the server to send an authoritative answer.
#### <a id="plugin-check-command-dig"></a> dig
@ -2374,7 +2393,7 @@ nscp_address | **Optional.** The host's address. Defaults to "$address$".
nscp_port | **Optional.** The NSClient++ port. Defaults to 12489.
nscp_password | **Optional.** The NSClient++ password.
nscp_variable | **Required.** The variable that should be checked.
nscp_params | **Optional.** Parameters for the query.
nscp_params | **Optional.** Parameters for the query. Multiple parameters must be defined as array.
nscp_warn | **Optional.** The warning threshold.
nscp_crit | **Optional.** The critical threshold.
nscp_timeout | **Optional.** The query timeout in seconds.
@ -2423,6 +2442,7 @@ nrpe_command | **Optional.** The command that should be executed.
nrpe_no_ssl | **Optional.** Whether to disable SSL or not. Defaults to `false`.
nrpe_timeout_unknown | **Optional.** Whether to set timeouts to unknown instead of critical state. Defaults to `false`.
nrpe_timeout | **Optional.** The timeout in seconds.
nrpe_arguments | **Optional.** Arguments that should be passed to the command. Multiple arguments must be defined as array.
#### <a id="plugin-check-command-apt"></a> apt

2
etc/icinga2/conf.d/hosts.conf
View File

@ -40,7 +40,7 @@ object Host NodeName {
/* No parameters. */
}
vars.disks["disk /"] = {
disk_partition = "/"
disk_partitions = "/"
}
/* Define notification mail attributes for notification apply rules in `notifications.conf`. */

24
itl/command-plugins.conf
View File

@ -62,7 +62,6 @@ object CheckCommand "hostalive" {
vars.ping_cpl = 100
}
template CheckCommand "fping-common" {
import "plugin-check-command"
@ -415,8 +414,16 @@ object CheckCommand "disk" {
"-c" = "$disk_cfree$%"
"-W" = "$disk_inode_wfree$%"
"-K" = "$disk_inode_cfree$%"
"-p" = "$disk_partition$"
"-x" = "$disk_partition_excluded$"
"-p" = "$disk_partitions$"
"-p_old" = {
key = "-p"
value = "$disk_partition$"
}
"-x" = "$disk_partitions_excluded$"
"-x_old" = {
key = "-x"
value = "$disk_partition_excluded$"
}
}
vars.disk_wfree = 20
@ -635,7 +642,11 @@ object CheckCommand "dns" {
arguments = {
"-H" = "$dns_lookup$"
"-s" = "$dns_server$"
"-a" = "$dns_expected_answer$"
"-a" = "$dns_expected_answers$"
"-a_old" = {
key = "-a"
value ="$dns_expected_answer$"
}
"-A" = {
set_if = "$dns_authoritative$"
}
@ -671,7 +682,10 @@ object CheckCommand "nscp" {
value = "$nscp_variable$"
required = true
}
"-l" = "$nscp_params$"
"-l" = {
value = "$nscp_params$"
repeat_key = false
}
"-w" = "$nscp_warn$"
"-c" = "$nscp_crit$"
"-t" = "$nscp_timeout$"