Adds docs and adds plain config writer for ifw-api support

doc/100-General/10-Changelog.md

@@ -21,11 +21,9 @@ Released closed milestones can be found on [GitHub](https://github.com/Icinga/ic
 
 ### Enhancements
 
-* [#623](https://github.com/Icinga/icinga-powershell-framework/issues/623) Adds support to provide the Icinga service user written as `user@domain`
-
-### Enhancements
-
 * [#619](https://github.com/Icinga/icinga-powershell-framework/pull/619) Adds feature to securely read enum provider values with new function `Get-IcingaProviderEnumData`
+* [#623](https://github.com/Icinga/icinga-powershell-framework/issues/623) Adds support to provide the Icinga service user written as `user@domain`
+* [#633](https://github.com/Icinga/icinga-powershell-framework/pull/633) Adds support for Icinga 2.14.0 native Icinga for Windows API communication
 
 ## 1.10.1 (2022-12-20)
 

doc/110-Installation/30-API-Check-Forwarder.md

@@ -106,3 +106,111 @@ Enable-IcingaFrameworkApiChecks;
 ## EventLog Errors
 
 In case a check could not be executed by using this experimental feature, either because of timeouts or other issues, they are added with `EventId 1553` inside the EventLog for `Icinga for Windows`. A description on why the check could not be executed is added within the event output.
+
+## Icinga Communication to API
+
+With Icinga 2.14.0 and later, you can enable the Icinga Agent to natively communicate with the Icinga for Windows API, allowing checks being executed without having to start a PowerShell.
+
+This is a huge performance boost and should be **mandatory** on all Windows machines.
+
+To enable this feature, ensure you have **all** plugins updated by importing the latest version of the Icinga Director baskets or use the latest `.conf` files for Icinga provided by each plugin repository.
+
+Once your configuration is updated, you have to enable this feature.
+
+### Requirements
+
+* Icinga for Windows v1.11.0 or later
+* Icinga Director v.1.11.0 or later
+* Icinga 2.14.0 or later (at least master)
+
+### Icinga Director
+
+Navigate to `Icinga Director` and click on `Commands` -> `Commands` and search for `PowerShell Base`.
+
+Click on this CheckCommand and under the `Import` section add the check `ifw-api`.
+
+If the CheckCommand `ifw-api` does not exist, click on the `Icinga Director` on the menu and then `Icinga Infrastructure` -> `Kickstart Wizard` and then `Run Import` to import the latest CheckCommands shipped with Icinga. Please ensure you have updated to Icinga 2.14.0 or later on your master, otherwise this command is not available.
+
+You can verify that the `ifw-api` CheckCommand was installed by clicking on `Icinga Director` on the menu and then `Activity Log`. You should now see an entry like this:
+
+```
+[username] create command "ifw-api"
+```
+
+Now proceed with the previous step, to update the `PowerShell Base` to import the `ifw-api` CheckCommand.
+
+![Icinga Director IfW Api](../images/05_installation/02_ifw-api/01_powershell_base.png)
+
+Once you deploy the configuration, Icinga will communicate directly with the Icinga for Windows API, as long as on the Agent side 2.14.0 or later is installed. In case you are running an older version, Icinga will fall back to the previous handling and check the system either with or without API, depending on the configuration.
+
+### Icinga Plain Configuration
+
+Ensure you have updated to the latest version of Icinga and all `.conf` files for the Icinga for Windows CheckCommands are updated to the latest version.
+
+Afterwards navigate to the file containing your `PowerShell Base` CheckCommand and add the following line
+
+```
+import "ifw-api"
+```
+
+directly below `import "plugin-check-command"`
+
+**Note:** For backwards compatibility, if you didn't manage to update your entire environment (Master, Satellite and Agents) to v2.14.0 or later, you will have to deploy an additional check command on your global zones. This global configuration will create a dummy check-command `ifw-api`, ensuring the older Agents and Satellites older than 2.14.0 will not fail with a configuration error. Please read the section **`Global Zone Config`** for more details below.
+
+**Example:**
+
+```
+object CheckCommand "PowerShell Base" {
+    import "plugin-check-command"
+    import "ifw-api"
+
+...
+```
+
+Once modified, save the file and test your Icinga configuration with
+
+```
+icinga2 daemon -C
+```
+
+If the configuration is valid, restart your Icinga service
+
+```
+systemctl restart icinga2
+```
+
+**Global Zone Config:**
+
+<span style="color:red">**This only applies in multi-version environments NOT using Icinga Director and not fully upgraded to v2.14.0**!</span>
+
+Please validate your Icinga zones.conf for your global zone in (`/etc/icinga2/zones.conf`). There should be a zone configured as `global = true`, like `global-templates`. Please **DO NOT USE** `director-global`!
+
+In case your global zone is using the default `global-templates`, create a new file at the location
+
+`/etc/icinga2/zones.d/global-templates`
+
+with the name `ifw-fallback.conf` and add the following content:
+
+```
+if (! globals.System || ! System.get_template || ! get_template(CheckCommand, "ifw-api-check-command")) {
+  object CheckCommand "ifw-api" {
+    import "plugin-check-command"
+  }
+}
+```
+
+Full path example: `/etc/icinga2/zones.d/global-templates/ifw-fallback.conf`
+
+Now validate your configuration and restart your master.
+
+```
+icinga2 daemon -C
+```
+
+If the configuration is valid, restart your Icinga service
+
+```
+systemctl restart icinga2
+```
+
+Icinga will now communicate directly with the Icinga for Windows API, as long as on the Agent side 2.14.0 or later is installed. In case you are running an older version, Icinga will fall back to the previous handling and check the system either with or without API, depending on the configuration.

doc/300-Knowledge-Base.md

@@ -22,3 +22,4 @@ For this reason you will find a list of Icinga knowledge base entries below. Ent
 | [IWKB000012](knowledgebase/IWKB000012.md) | Icinga for Windows cannot be used with Microsoft Defender: `Windows Defender Antivirus has detected malware or other potentially unwanted software` |
 | [IWKB000013](knowledgebase/IWKB000013.md) | The local Icinga Agent certificate seems not to be signed by our Icinga CA yet. Using this certificate for the REST-Api as example might not work yet. Please check the state of the certificate and complete the signing process if required |
 | [IWKB000014](knowledgebase/IWKB000014.md) | Installing or Updating Icinga for Windows causes error messages regarding `framework_cache.psm1` errors |
+| [IWKB000015](knowledgebase/IWKB000015.md) | Got JSON, but not an object, from IfW API on host 'localhost' port '5668': "Exception while calling \\"Fill\\" with 1 arguments: \\"Invalid syntax near \\"`<Argument>:`\\".\\"" |

doc/knowledgebase/IWKB000015.md

@@ -0,0 +1,23 @@
+# Icinga Knowledge Base - IWKB000015
+
+## Short Message
+
+Got JSON, but not an object, from IfW API on host 'localhost' port '5668': "Exception while calling \\"Fill\\" with 1 argument: \\"Invalid syntax near \\"`<Argument>:`\\".\\""
+
+## Example Exception
+
+Got JSON, but not an object, from IfW API on host 'localhost' port '5668': "Exception while calling \\"Fill\\" with 1 arguments: \\"Invalid syntax near \\"SQLServer:`\\".\\""
+
+## Reason
+
+This issue is caused by using the native communication over the Icinga for Windows API with Icinga 2.14.0 or later, while using values for arguments manually escaped by the user with `''`:
+
+![String Escaping](../images/04_knowledgebase/IWKB000015/01_stringescape.png)
+
+## Solution
+
+Remove all added `' '` from your Icinga configuration, regardless if you are using the Icinga Director or plain Icinga configuration files. Latest Icinga for Windows versions, will escape and build strings properly anyway, even without the new Icinga communication feature.
+
+Once the `' '` are removed from your configuration, deploy your configuration and the check will run just fine.
+
+![String Escaped Correctly](../images/04_knowledgebase/IWKB000015/02_stringescaped_correctly.png)

lib/core/tools/Get-IcingaCheckCommandConfig.psm1

@@ -213,7 +213,7 @@ function Get-IcingaCheckCommandConfig()
                 'object_type' = 'object';
                 'vars'        = @{
                     'ifw_api_arguments' = @{ };
-		};
+                };
             }
         );
 
@@ -316,14 +316,14 @@ function Get-IcingaCheckCommandConfig()
             }
 
             if ($parameter.type.name -eq 'SwitchParameter') {
-                $Basket.Command[$check].vars.ifw_api_arguments.Add([string]::Format('-{0}', $parameter.Name), @{
+                $Basket.Command[$check].vars.ifw_api_arguments.Add([string]::Format('{0}', $parameter.Name), @{
                     'set_if' = $IcingaCustomVariable;
                 });
             } else {
-                $Basket.Command[$check].vars.ifw_api_arguments.Add([string]::Format('-{0}', $parameter.Name), @{
+                $Basket.Command[$check].vars.ifw_api_arguments.Add([string]::Format('{0}', $parameter.Name), @{
                     'value' = $IcingaCustomVariable;
                 });
-	    }
+	        }
 
             # Determine wether a parameter is required based on given syntax-information
             if ($parameter.required -eq $TRUE) {
@@ -626,11 +626,47 @@ function Write-IcingaPlainConfigurationFiles()
 
         # In case we pre-define custom variables, we should add them here
         if ($CheckCommand.vars.Count -ne 0) {
-            $IcingaConfig += New-IcingaNewLine;
+            $IcingaConfig    += New-IcingaNewLine;
+            [bool]$AddNewLine = $FALSE;
 
             foreach ($var in $CheckCommand.vars.Keys) {
-                [string]$Value = $CheckCommand.vars[$var];
-                $IcingaConfig += [string]::Format('    vars.{0} = {1}{2}', $var, $Value.ToLower(), (New-IcingaNewLine));
+                if ($CheckCommand.vars[$var] -Is [Hashtable]) {
+                    if ($AddNewLine) {
+                        $IcingaConfig += New-IcingaNewLine;
+                    }
+                    [string]$HashtableArguments = '';
+                    [bool]$AddConfigNewLine     = $FALSE;
+                    foreach ($item in $CheckCommand.vars[$var].Keys) {
+                        if ($AddConfigNewLine) {
+                            $HashtableArguments += New-IcingaNewLine;
+                        }
+                        $HashtableArguments += [string]::Format('        "{0}" = {{{1}', $item, (New-IcingaNewLine));
+
+                        if ($CheckCommand.vars[$var][$item] -Is [Hashtable]) {
+                            foreach ($icingaconf in $CheckCommand.vars[$var][$item].Keys) {
+                                [string]$Value = $CheckCommand.vars[$var][$item][$icingaconf];
+                                $HashtableArguments += [string]::Format('            {0} = "{1}"{2}', $icingaconf, $Value, (New-IcingaNewLine));
+                            }
+                        } else {
+                            [string]$Value = $CheckCommand.vars[$var][$item];
+                            $HashtableArguments += [string]::Format('            value = "{0}"{1}', $Value, (New-IcingaNewLine));
+                        }
+                        $HashtableArguments += '        }';
+                        $AddConfigNewLine = $TRUE;
+                    }
+
+                    $IcingaConfig += [string]::Format('    vars.{0} = {{{1}', $var, (New-IcingaNewLine));
+                    $IcingaConfig += [string]::Format('{0}{1}', $HashtableArguments, (New-IcingaNewLine));
+                    $IcingaConfig += '    }';
+                    $AddNewLine = $TRUE;
+                } else {
+                    if ($AddNewLine) {
+                        $IcingaConfig += New-IcingaNewLine;
+                        $AddNewLine    = $FALSE;
+                    }
+                    [string]$Value = $CheckCommand.vars[$var];
+                    $IcingaConfig += [string]::Format('    vars.{0} = {1}{2}', $var, $Value.ToLower(), (New-IcingaNewLine));
+                }
             }
         } else {
             $IcingaConfig += New-IcingaNewLine;