Merge branch 'master' into feature/add_code_cache_for_faster_framework_loading

Author: LordHepipud

README.md

@@ -16,6 +16,7 @@ Please take a look at the following content to get to know the possibilities of
 * [Icinga Integration](doc/05-Icinga-Integration.md)
 * [Framework Usage Examples](doc/06-Framework-Usage.md)
 * [Icinga PowerShell Framework as Service](doc/service/01-Install-Service.md)
+* [Knowledge Base](doc/10-Knowledge-Base.md)
 * [Changelog](doc/31-Changelog.md)
 
 Developer Guide

doc/10-Knowledge-Base.md

@@ -0,0 +1,12 @@
+# Icinga for Windows Knowledge Base
+
+While using Icinga for Windows you might run into issues, permissions problems or different problems during usage. Our main goal is to catch all of those problems and print proper error messages to give ideas on what went went wrong exactly.
+
+However, some problems might be more complex and require further detailed descriptions as an issue could be caused my multiple different events or possible solutions would be way too long to put into a plugin output for example.
+
+For this reason you will find a list of Icinga knowledge base entries below. Entries are assigned a unique 6 digit number referenced by issue messages, lead by the abbreviation `IWKB`. Example `IWKB000001`.
+
+| Knowledge Base Id                         | Short Message / Description |
+| ---                                       | ---           |
+| [IWKB000001](knowledgebase/IWKB000001.md) | The user you are running this command as does not have permission to access the requested Cim-Object. To fix this, please add the user the Agent is running with to the "Remote Management Users" groups and grant access to the WMI branch for the Class/Namespace mentioned above and add the permission "Remote enable". |
+| [IWKB000002](knowledgebase/IWKB000002.md) | Plugin execution fails because arguments could not be validated and properly set. An example error could be `The "*" was not recognized as the name of a program, cmdlet, function, script file, or executable. Check the spelling of the name and that the path is correct (if included), and repeat the process.` |

doc/31-Changelog.md

@@ -19,16 +19,20 @@ Released closed milestones can be found on [GitHub](https://github.com/Icinga/ic
 * [#141](https://github.com/Icinga/icinga-powershell-framework/pull/141) Adds Cmdlet `Convert-IcingaPluginThresholds` as generic approach to convert Icinga Thresholds with units to the lowest unit of this type.
 * [#134](https://github.com/Icinga/icinga-powershell-framework/pull/134) Adds Cmdlet `Test-IcingaWindowsInformation` to check if a WMI class exist and if we can fetch data from it. In addition we add support for binary value comparison with the new Cmdlet `Test-IcingaBinaryOperator`
 * [#142](https://github.com/Icinga/icinga-powershell-framework/pull/142) **Experimental:** Adds feature to cache the Framework code into a single file to speed up the entire loading process, mitigating the impact on performance on systems with few CPU cores. You enable disables this feature by using `Enable-IcingaFrameworkCodeCache` and `Disable-IcingaFrameworkCodeCache`. Updating the cache is done with `Write-IcingaFrameworkCodeCache`
+* [#149](https://github.com/Icinga/icinga-powershell-framework/pull/149) Adds support to add Wmi permissions for a specific user and namespace with `Add-IcingaWmiPermissions`. In addition you can remove users from Wmi namespaces by using `Remove-IcingaWmiPermissions`
 
 ### Bugfixes
 
 * [#059](https://github.com/Icinga/icinga-powershell-framework/issues/059), [#060](https://github.com/Icinga/icinga-powershell-framework/pull/060) Fixes interface handling for multiple interfaces and returns only the main interface by fallback to routing table and adds support for Windows 2008 R2
+* [#114](https://github.com/Icinga/icinga-powershell-framework/issues/114)[#146](https://github.com/Icinga/icinga-powershell-framework/pull/146) Fixes Icinga Agent API being wrongly disabled after successful certificate configuration and installation
 * [#127](https://github.com/Icinga/icinga-powershell-framework/issues/127) Fixes wrong error message on failed MSSQL connection due to database not reachable by using `-IntegratedSecurity`
 * [#128](https://github.com/Icinga/icinga-powershell-framework/issues/128) Fixes unhandled output from loading `System.Reflection.Assembly` which can cause weird side effects for plugin outputs
 * [#130](https://github.com/Icinga/icinga-powershell-framework/issues/130) Fix crash while running services as background task to collect metrics over time by missing Performance Counter cache initialisation
+* [#133](https://github.com/Icinga/icinga-powershell-framework/issues/133), [#147](https://github.com/Icinga/icinga-powershell-framework/pull/147) Fixes an issue while changing the hostname between upper/lower case which might cause unwanted exceptions on one hand but also required manual signing of requests on the CA master as the signing process was not completed
 * [#138](https://github.com/Icinga/icinga-powershell-framework/issues/138) Fixes possible value overflow on `Convert-Bytes` while converting from anything larger than MB to Bytes
 * [#140](https://github.com/Icinga/icinga-powershell-framework/issues/140) Fixes version fetching for not loaded modules during upgrades/plugin calls with `Get-IcingaPowerShellModuleVersion`
 * [#143](https://github.com/Icinga/icinga-powershell-framework/issues/143) Fixes the annoying hint from the analyzer to check space before open brace
+* [#152](https://github.com/Icinga/icinga-powershell-framework/issues/152) Fixes incorrect rendering for empty arrays which used `$null` incorrectly instead of `@()` and fixed ValidateSet which now also supports arrays as data type
 
 ## 1.2.0 (2020-08-28)
 

doc/images/04_knowledgebase/IWKB000002/01_Plugin_Output_Error.png

@@ -0,0 +1,57 @@
+# Icinga Knowledge Base - IWKB000001
+
+## Short Message
+
+The user you are running this command as does not have permission to access the requested Cim-Object. To fix this, please add the user the Agent is running with to the "Remote Management Users" groups and grant access to the WMI branch for the Class/Namespace mentioned above and add the permission "Remote enable".
+
+## Example Exception
+
+[UNKNOWN]: Icinga Permission Error was thrown: CimInstance: Class: "MSFT_PhysicalDisk", Namespace: "root\Microsoft\Windows\Storage"
+
+## Reason
+
+To access WMI Objects by either `Get-WmiObject` or `Get-CimInstance` you will require to grant permissions to the user running the plugins to be allowed to fetch data from them. In general default system users should already inherit these permissions.
+
+However, if you are running custom users like an AD user or local users you might require to grant additional permissions.
+
+## Required Permissions
+
+Each plugin should contain a section for WMI permissions in case the plugin fetches WMI data, to give a better understanding which WMI area is accessed and permissions are required. For most plugins, the default space is `Root\Cimv2`, but additional spaces might be required.
+
+## Solution
+
+In case you are running into this issue, you will have to grant permissions on the corresponding WMI path printed at the `Namespace` within the exception message or include the WMI path from the plugin permissions documentation. An example plugin would be [Invoke-IcingaCheckDiskHealth](https://icinga.com/docs/windows/latest/plugins/doc/plugins/20-Invoke-IcingaCheckDiskHealth/#permissions).
+
+### Adding Permissions
+
+#### Using UI configuration
+
+There is a detailed description on the [Microsoft Docs](https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc771551(v=ws.11)) available on how permissions for WMI are set. Please keep in mind that granting permissions to the `primary namespace` might not be enough and you will require to change the user permissions to apply for `This namespace and subnamespaces`.
+
+#### Using PowerShell
+
+To add permissions for WMI namespaces you can use our Icinga for Windows Cmdlets. Simply open a new PowerShell as `Administrator` and create a new Icinga Shell instance by typing `icinga`.
+After the Icinga PowerShell Framework is loaded, we can use our Wmi permission Cmdlet:
+
+```powershell
+Add-IcingaWmiPermissions -User 'icinga' -Namespace 'root\Microsoft\Windows\Storage' -Enable -RemoteAccess -Recurse;
+```
+
+The above command will grant the user `icinga` the read and remote access permission for the `root\Microsoft\Windows\Storage` namespace. In addition by using `-Recurse` we will set the permissions for `subnamespaces` in addition.
+
+### Permission Table
+
+| Flag           | Description |
+| ---            | ---         |
+| Enable         | Enables the account and grants the user read permissions. This is a default access right for all users and corresponds to the Enable Account permission on the Security tab of the WMI Control. For more information, see Setting Namespace Security with the WMI Control. |
+| MethodExecute  | Allows the execution of methods. Providers can perform additional access checks. This is a default access right for all users and corresponds to the Execute Methods permission on the Security tab of the WMI Control. |
+| FullWrite      | Allows a user account to write to classes in the WMI repository as well as instances. A user cannot write to system classes. Only members of the Administrators group have this permission. WBEM_FULL_WRITE_REP corresponds to the Full Write permission on the Security tab of the WMI Control. |
+| PartialWrite   | Allows you to write data to instances only, not classes. A user cannot write classes to the WMI repository. Only members of the Administrators group have this right. WBEM_PARTIAL_WRITE_REP corresponds to the Partial Write permission on the Security tab of the WMI Control. |
+| ProviderWrite  | Allows writing classes and instances to providers. Note that providers can do additional access checks when impersonating a user. This is a default access right for all users and corresponds to the Provider Write permission on the Security tab of the WMI Control. |
+| RemoteAccess   | Allows a user account to remotely perform any operations allowed by the permissions described above. Only members of the Administrators group have this right. WBEM_REMOTE_ACCESS corresponds to the Remote Enable permission on the Security tab of the WMI Control. |
+| Subscribe      | Specifies that a consumer can subscribe to the events delivered to a sink. Used in IWbemEventSink::SetSinkSecurity. |
+| Publish        | Specifies that the account can publish events to the instance of __EventFilter that defines the event filter for a permanent consumer. Available in wbemcli.h. |
+| ReadSecurity   | The right to read the information in the objects security descriptor, not including the information in the system access control list (SACL). |
+| WriteSecurity  | The right to modify the discretionary access control list (DACL) in the objects security descriptor. |
+
+**Note:** By default the Cmdlet `Add-IcingaWmiPermissions` only has direct build-in support for `-Enable` and `-RemoteAccess`. To apply different permissions, you will have to use the `-Flags` argument and add the flags by their name as shown in the table.

doc/images/04_knowledgebase/IWKB000002/02_Director_Config.png

@@ -0,0 +1,27 @@
+# Icinga Knowledge Base - IWKB000002
+
+## Short Message
+
+Plugin execution fails because arguments could not be validated and properly set. An example error could be `The "*" was not recognized as the name of a program, cmdlet, function, script file, or executable. Check the spelling of the name and that the path is correct (if included), and repeat the process.`
+
+## Example Exception
+
+![Plugin Output Error](../images/04_knowledgebase/IWKB000002/01_Plugin_Output_Error.png)
+
+## Reason
+
+This error can happen if array arguments either contain special characters, like `*` or spaces. By using the configuration provided by Icinga for Windows, array arguments are taken from your configuration and re-rendered using Icinga DSL as PowerShell arrays.
+
+In addition Icinga is not ensuring string values with included spaces are properly escaped.
+
+## Solution
+
+To fix this you can simply put the input values, regardless if you are within an array element of a string, into single quotes `'`. This will ensure multi-part strings are always rendered as one element during plugin execution.
+
+**Example:**
+
+![Escape Strings](../images/04_knowledgebase/IWKB000002/02_Director_Config.png)
+
+Once the Performance Counter is put between single quotes `'`, we can view the proper check result output:
+
+![Escape Strings](../images/04_knowledgebase/IWKB000002/03_Fixed_Output.png)

doc/images/04_knowledgebase/IWKB000002/03_Fixed_Output.png

@@ -1,3 +1,47 @@
+<#
+.SYNOPSIS
+    Installs the required certificates for the Icinga Agent including the entire
+    signing process either by using the CA-Proxy, the CA-Server directly or
+    by manually signing the request on the CA master
+.DESCRIPTION
+    Installs the required certificates for the Icinga Agent including the entire
+    signing process either by using the CA-Proxy, the CA-Server directly or
+   by manually signing the request on the CA master
+.FUNCTIONALITY
+    Creates, installs and signs required certificates for the Icinga Agent
+.EXAMPLE
+    # Connect to the CA server with a ticket to fully complete the request
+    PS>Install-IcingaAgentCertificates -Hostname 'windows.example.com' -Endpoint 'icinga2.example.com' -Ticket 'my_secret_ticket';
+.EXAMPLE
+    # Connect to the CA server without a ticket, to create the sign request on the master
+    PS>Install-IcingaAgentCertificates -Hostname 'windows.example.com' -Endpoint 'icinga2.example.com';
+.EXAMPLE
+    # Uses the Icinga ca.crt from a local filesystem and prepares the Icinga Agent for receiving connections from the Master/Satellite for signing
+    PS>Install-IcingaAgentCertificates -Hostname 'windows.example.com' -CACert 'C:\users\public\icinga2\ca.crt';
+.EXAMPLE
+    # Uses the Icinga ca.crt from a web resource and prepares the Icinga Agent for receiving connections from the Master/Satellite for signing
+    PS>Install-IcingaAgentCertificates -Hostname 'windows.example.com' -CACert 'https://example.com/icinga2/ca.crt';
+.PARAMETER Hostname
+    The hostname of the local system. Has to match the object name within the Icinga configuration
+.PARAMETER Endpoint
+    The address of either the Icinga CA master or a parent node of the Agent to transmit the request to the CA master
+.PARAMETER Port
+    The port used for Icinga communication. Uses 5665 as default
+.PARAMETER CACert
+    Allows to specify the path to the ca.crt from the Icinga CA master on a local, network or web share to allow certificate generation
+    in case the Icinga Agent is not able to connect to it's parent hosts
+.PARAMETER Ticket
+    The ticket number for the signing request which is either generated by Icinga 2 or the Icinga Director
+.PARAMETER Force
+    Ignores existing certificates and will force the creation, overriding existing certificates
+.INPUTS
+   System.String
+.OUTPUTS
+   System.Boolean
+.LINK
+   https://github.com/Icinga/icinga-powershell-framework
+#>
+
 function Install-IcingaAgentCertificates()
 {
     param(
@@ -38,6 +82,9 @@ function Install-IcingaAgentCertificates()
             Write-IcingaConsoleError 'Failed to generate host certificate';
             return $FALSE;
         }
+
+        # Once we generated new host certificates, we always require to sign them if possible
+        $Force = $TRUE;
     }
 
     if ([string]::IsNullOrEmpty($Endpoint) -And [string]::IsNullOrEmpty($CACert)) {
@@ -182,8 +229,9 @@ function Test-IcingaAgentCertificates()
         return $FALSE;
     }
 
-    [string]$hostCRT = [string]::Format('{0}.crt', $Hostname);
-    [string]$hostKEY = [string]::Format('{0}.key', $Hostname);
+    [string]$hostCRT       = [string]::Format('{0}.crt', $Hostname);
+    [string]$hostKEY       = [string]::Format('{0}.key', $Hostname);
+    [bool]$CertNameInvalid = $FALSE;
 
     $certificates = Get-ChildItem -Path $CertDirectory;
     # Now loop each file and match their name with our hostname
@@ -192,11 +240,18 @@ function Test-IcingaAgentCertificates()
             $file = $cert.Name.Replace('.key', '').Replace('.crt', '');
             if (-Not ($file -clike $Hostname)) {
                 Write-IcingaConsoleWarning ([string]::Format('Certificate file {0} is not matching the hostname {1}. Certificate generation is required.', $cert.Name, $Hostname));
-                return $FALSE;
+                $CertNameInvalid = $TRUE;
+                break;
             }
         }
     }
 
+    if ($CertNameInvalid) {
+        Remove-Item -Path (Join-Path -Path $CertDirectory -ChildPath $hostCRT) -Force;
+        Remove-Item -Path (Join-Path -Path $CertDirectory -ChildPath $hostKEY) -Force;
+        return $FALSE;
+    }
+
     Write-IcingaConsoleNotice 'Icinga host certificates are present and valid. No generation required';
 
     return $TRUE;

doc/knowledgebase/IWKB000001.md

@@ -561,7 +561,7 @@ function Start-IcingaAgentInstallWizard()
             Install-IcingaAgentBaseFeatures;
             $CertsInstalled = Install-IcingaAgentCertificates -Hostname $Hostname -Endpoint $CAEndpoint -Port $CAPort -CACert $CAFile -Ticket $Ticket;
             Write-IcingaAgentApiConfig -Port $CAPort;
-            if ($EmptyCA -eq $TRUE -Or $CertsInstalled -eq $FALSE) {
+            if ($EmptyCA -eq $TRUE -And $CertsInstalled -eq $FALSE) {
                 Disable-IcingaAgentFeature 'api';
                 Write-IcingaConsoleWarning `
                     -Message '{0}{1}{2}{3}{4}' `

doc/knowledgebase/IWKB000002.md

@@ -165,7 +165,7 @@ function Get-IcingaCheckCommandConfig()
                         'value' = @{
                             'type' = 'Function';
                             'body' = [string]::Format(
-                                'var arr = macro("{0}");{1}if (len(arr) == 0) {2}{1}return "$null";{1}{3}{1}return arr.join(",");',
+                                'var arr = macro("{0}");{1}if (len(arr) == 0) {2}{1}return "@()";{1}{3}{1}return arr.join(",");',
                                 $IcingaCustomVariable,
                                 "`r`n",
                                 '{',
@@ -259,10 +259,16 @@ function Get-IcingaCheckCommandConfig()
                 );
 
                 if ($IsDataList) {
+                    [string]$DataListDataType = 'string';
+
+                    if ($parameter.type.name -eq 'Array') {
+                        $DataListDataType = 'array';
+                    }
+
                     $Basket.Datafield[[string]$FieldID].Add(
                         'settings', @{
                             'datalist'  = $DataListName;
-                            'data_type' = 'string';
+                            'data_type' = $DataListDataType;
                             'behavior'  = 'strict';
                         }
                     );

lib/core/icingaagent/installer/Install-IcingaAgentCertificates.psm1

@@ -8,20 +8,10 @@ function Get-IcingaUserSID()
         $User = 'NT Authority\SYSTEM';
     }
 
-    [string]$Username = '';
-    [string]$Domain   = '';
-
-    if ($User.Contains('\')) {
-        $TmpArray = $User.Split('\');
-        $Domain   = $TmpArray[0];
-        $Username = $TmpArray[1];
-    } else {
-        $Domain   = Get-IcingaNetbiosName;
-        $Username = $User;
-    }
+    $UserData = Split-IcingaUserDomain -User $User;
 
     try {
-        $NTUser       = New-Object System.Security.Principal.NTAccount($Domain, $Username);
+        $NTUser       = New-Object System.Security.Principal.NTAccount($UserData.Domain, $UserData.User);
         $SecurityData = $NTUser.Translate([System.Security.Principal.SecurityIdentifier]);
     } catch {
         throw $_.Exception;