diff --git a/doc/1-about.md b/doc/1-about.md index ca2be02db..69a592456 100644 --- a/doc/1-about.md +++ b/doc/1-about.md @@ -54,6 +54,21 @@ Icinga 2 is available as [Vagrant Demo VM](#vagrant). ## 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 diff --git a/doc/2-getting-started.md b/doc/2-getting-started.md index bfaabaee6..89306da46 100644 --- a/doc/2-getting-started.md +++ b/doc/2-getting-started.md @@ -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`. */ diff --git a/doc/4-monitoring-basics.md b/doc/4-monitoring-basics.md index 510610581..e76a18d8d 100644 --- a/doc/4-monitoring-basics.md +++ b/doc/4-monitoring-basics.md @@ -943,8 +943,8 @@ definition based on these required parameters and/or default values. #### 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). + + #### 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 + } ### Runtime Custom Attributes Evaluation Order diff --git a/doc/7-configuring-icinga-2.md b/doc/7-configuring-icinga-2.md index 0e48192d1..63eac3350 100644 --- a/doc/7-configuring-icinga-2.md +++ b/doc/7-configuring-icinga-2.md @@ -908,6 +908,8 @@ Attributes: arguments |**Optional.** A dictionary of command arguments. +#### 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 " */ 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 "" */ 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, , 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]'` + ### 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). ### 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). ### 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$". #### 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. #### 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. #### 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. #### apt diff --git a/etc/icinga2/conf.d/hosts.conf b/etc/icinga2/conf.d/hosts.conf index ff9aef260..83f1e34ee 100644 --- a/etc/icinga2/conf.d/hosts.conf +++ b/etc/icinga2/conf.d/hosts.conf @@ -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`. */ diff --git a/itl/command-plugins.conf b/itl/command-plugins.conf index af8112c9b..589b049ff 100644 --- a/itl/command-plugins.conf +++ b/itl/command-plugins.conf @@ -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$"