Built-in check command: ifw-api

doc/10-icinga-template-library.md

@@ -187,6 +187,82 @@ Name            | Description
 ----------------|--------------
 sleep\_time     | **Optional.** The duration of the sleep in seconds. Defaults to 1s.
 
+### ifw-api <a id="itl-ifw-api"></a>
+
+Built-in check command for executing arbitrary PowerShell check commands via the
+[Icinga for Windows REST API](https://icinga.com/docs/icinga-for-windows/latest/doc/110-Installation/30-API-Check-Forwarder/).
+
+That feature lets the PowerShell processes spawned by Icinga just talk
+to the pre-loaded IfW API instead of loading all PowerShell check commands
+by itself on every check. In contrast the `ifw-api` command doesn't even spawn
+any process, but communicates directly with the IfW API.
+
+Ideally you run the Icinga Director and have imported our PowerShell check commands from
+[their basket](https://icinga.com/docs/icinga-for-windows/latest/doc/200-Icinga-Integration/01-Director-Baskets/).
+In this case adding `ifw-api` to the imports of the _PowerShell Base_
+check command is enough to enable `ifw-api` globally.
+
+!!! warning
+
+    Do the latter only if your **entire** Icinga cluster runs v2.14+! Otherwise,
+    all older nodes which load the modified _PowerShell Base_ (e.g. from a global
+    zone) will reject all new configuration as the imported `ifw-api` is missing.
+
+For a cluster which may contain older Icinga instances there's a workaround:
+Put the following command in a global zone and import it instead of `ifw-api`:
+
+```
+object CheckCommand "ifw-api-if-exists" {
+    try {
+        import "ifw-api"
+    } except {
+    }
+}
+```
+
+In any case re-running the Kickstart Wizard is required
+for the Director to recognise these new check commands.
+
+The `ifw-api` command may be also used like e.g. [check_by_ssh](#plugin-check-command-by-ssh).
+Its custom variables provide high flexibility.
+From using a custom CA to controlling the IfW API directly from a Linux satellite.
+
+Optional custom variables passed as [command parameters](03-monitoring-basics.md#command-passing-parameters):
+
+| Name                    | Default           | Description                                                                                                 |
+|-------------------------|-------------------|-------------------------------------------------------------------------------------------------------------|
+| ifw\_api\_command       | `$command.name$`  | Command to run.                                                                                             |
+| ifw\_api\_arguments     | {} (none)         | Arguments for the command, similar to [CheckCommand](09-object-types.md#objecttype-checkcommand)#arguments. |
+| ifw\_api\_host          | null (localhost)  | IfW API host.                                                                                               |
+| ifw\_api\_port          | 5668              | IfW API port.                                                                                               |
+| ifw\_api\_expected\_san | `$ifw_api_host$`  | Peer TLS certificate SAN (and SNI). null means agent NodeName.                                              |
+| ifw\_api\_cert          | null (Icinga PKI) | TLS client certificate path.                                                                                |
+| ifw\_api\_key           | null (Icinga PKI) | TLS client private key path.                                                                                |
+| ifw\_api\_ca            | null (Icinga PKI) | Peer TLS CA certificate path.                                                                               |
+| ifw\_api\_crl           | null (Icinga PKI) | Path to TLS CRL to check peer against.                                                                      |
+| ifw\_api\_username      | null (none)       | Basic auth username.                                                                                        |
+| ifw\_api\_password      | null (none)       | Basic auth password.                                                                                        |
+
+!!! info
+
+    Due to how Icinga 2 resolves macros and serializes the resolved values for
+    sending to a command endpoint (if any), ifw\_api\_arguments may not directly
+    contain functions for the case `ifw-api` is used with command endpoints. Only
+    macro strings referring to custom variables which are set to functions work.
+
+The above defaults allow enabling `ifw-api(-if-exists)` globally by importing
+it into _PowerShell Base_ without additional configuration elsewhere:
+
+* `$command.name$` is resolved at runtime to the name of the specific
+  check command being run and not any of the templates it imports, i.e. it
+  becomes e.g. "Invoke-IcingaCheckCPU", not "PowerShell Base" or even "ifw-api"
+* Our PowerShell framework provides ifw\_api\_arguments for all of its commands.
+* `ifw-api` connects to localhost (if ifw\_api\_host is null), but expects
+  the peer to identify itself via TLS with the NodeName of the endpoint
+  actually running the command (if ifw\_api\_expected\_san is null)
+* The actual values of ifw\_api\_cert, ifw\_api\_key, ifw\_api\_ca and ifw\_api\_crl
+  are also resolved on the command endpoint if null
+
 <!-- keep this anchor for URL link history only -->
 <a id="plugin-check-commands"></a>
 

itl/command-icinga.conf

@@ -39,3 +39,19 @@ object CheckCommand "exception" {
 object CheckCommand "sleep" {
     import "sleep-check-command"
 }
+
+object CheckCommand "ifw-api" {
+	import "ifw-api-check-command"
+
+	vars.ifw_api_command = "$command.name$"
+	vars.ifw_api_arguments = {}
+	vars.ifw_api_host = null
+	vars.ifw_api_port = 5668
+	vars.ifw_api_expected_san = "$ifw_api_host$"
+	vars.ifw_api_cert = null
+	vars.ifw_api_key = null
+	vars.ifw_api_ca = null
+	vars.ifw_api_crl = null
+	vars.ifw_api_username = null
+	vars.ifw_api_password = null
+}

lib/methods/CMakeLists.txt

@@ -9,6 +9,7 @@ set(methods_SOURCES
   dummychecktask.cpp dummychecktask.hpp
   exceptionchecktask.cpp exceptionchecktask.hpp
   icingachecktask.cpp icingachecktask.hpp
+  ifwapichecktask.cpp ifwapichecktask.hpp
   nullchecktask.cpp nullchecktask.hpp
   nulleventtask.cpp nulleventtask.hpp
   pluginchecktask.cpp pluginchecktask.hpp