Documentation: Add command arguments.

Fixes #5933

doc/3-monitoring-basics.md

@@ -310,8 +310,8 @@ all available options. Our example defines warning (`-w`) and
 critical (`-c`) thresholds for the disk usage. Without any
 partition defined (`-p`) it will check all local partitions.
 
-Define the default check command custom attribute `wfree` and `cfree` freely
+Define the default check command custom attribute `disk_wfree` and `disk_cfree`
-definable naming schema) and their default threshold values. You can
+freely definable naming schema) and their default threshold values. You can
 then use these custom attributes as runtime macros on the command line.
 
 The default custom attributes can be overridden by the custom attributes
@@ -453,6 +453,49 @@ information in the check output (`-o`).
       ]
     }
 
+### <a id="commands-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
+required to extend the arguments list based on a met condition evaluated
+at command execution. Or making arguments optional - only set if the
+macro value can be resolved by Icinga 2.
+
+    object CheckCommand "check_http" {
+      import "plugin-check-command"
+
+      command = PluginDir + "/check_http"
+
+      arguments = {
+        "-H" = "$http_vhost$"
+        "-I" = "$http_address$"
+        "-u" = "$http_uri$"
+        "-p" = "$http_port$"
+        "-S" = {
+          set_if = "$http_ssl$"
+        }
+        "-w" = "$http_warn_time$"
+        "-c" = "$http_critical_time$"
+      }
+
+      vars.http_address = "$address$"
+      vars.http_ssl = false
+    }
+
+The example shows the `check_http` check command defining the most common
+arguments. Each of them is optional by default and will be omitted if
+the value is not set. For example if the service calling the check command
+does not have `vars.http_port` set, it won't get added to the command
+line.
+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`
+option to the command line.
+That way you can use the `check_http` command definition for both, with and
+without SSL enabled checks saving you duplicated command definitions.
+
+Details on all available options can be found in the
+[CheckCommand object definition](#objecttype-checkcommand).
+
 
 ## <a id="notifications"></a> Notifications
 

doc/5-configuring-icinga-2.md

@@ -989,19 +989,27 @@ defined here.
 
 Example:
 
-    object CheckCommand "check_snmp" {
+    object CheckCommand "check_http" {
       import "plugin-check-command"
 
-      command = [
+      command = PluginDir + "/check_http"
-        PluginDir + "/check_snmp",
-	"-H", "$address$",
-	"-C", "$community$",
-	"-o", "$oid$"
-      ]
 
-      vars.address = "127.0.0.1"
+      arguments = {
-      vars.community = "public"
+        "-H" = "$http_vhost$"
+        "-I" = "$http_address$"
+        "-u" = "$http_uri$"
+        "-p" = "$http_port$"
+        "-S" = {
+          set_if = "$http_ssl$"
         }
+        "-w" = "$http_warn_time$"
+        "-c" = "$http_critical_time$"
+      }
+
+      vars.http_address = "$address$"
+      vars.http_ssl = false
+    }
+
 
 Attributes:
 
@@ -1012,6 +1020,41 @@ Attributes:
   env             |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
   vars            |**Optional.** A dictionary containing custom attributes that are specific to this command.
   timeout         |**Optional.** The command timeout in seconds. Defaults to 5 minutes.
+  arguments       |**Optional.** A dictionary of command 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
+as dictionary specifying additional options.
+
+Service:
+
+    vars.x_val = "My command argument value."
+    vars.have_x = "true"
+
+CheckCommand:
+
+    arguments = {
+      "-X" = {
+        value = "$x_val$"
+        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 */
+        order = 0           /* first position */
+      }
+    }
+
+  Option      | Description
+  ------------|--------------
+  value       | Optional argument value.
+  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 added if value is set (macro resolves to a defined value).
+  order       | Set if multiple arguments require a defined argument order.
+
 
 ### <a id="objecttype-notificationcommand"></a> NotificationCommand
 
@@ -1051,6 +1094,9 @@ Attributes:
   env             |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
   vars            |**Optional.** A dictionary containing custom attributes that are specific to this command.
   timeout         |**Optional.** The command timeout in seconds. Defaults to 5 minutes.
+  arguments       |**Optional.** A dictionary of command arguments.
+
+Command arguments can be used the same way as for `CheckCommand` objects.
 
 ### <a id="objecttype-eventcommand"></a> EventCommand
 
@@ -1074,6 +1120,9 @@ Attributes:
   env             |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
   vars            |**Optional.** A dictionary containing custom attributes that are specific to this command.
   timeout         |**Optional.** The command timeout in seconds. Defaults to 5 minutes.
+  arguments       |**Optional.** A dictionary of command arguments.
+
+Command arguments can be used the same way as for `CheckCommand` objects.
 
 ### <a id="objecttype-perfdatawriter"></a> PerfdataWriter