Merge pull request #701 from Icinga:feature/add_icinga_for_windows_test_command

Feature: Adds new command to test the functionality of Icinga for Windows

Adds new command `Test-IcingaForWindows`to check the current environment health by also improving internal handlings on how service information are fetched, preventing a lock on those

Author: LordHepipud

doc/100-General/10-Changelog.md

@@ -37,6 +37,7 @@ Released closed milestones can be found on [GitHub](https://github.com/Icinga/ic
 * [#694](https://github.com/Icinga/icinga-powershell-framework/pull/694) Adds support for check objects not being added to summary header
 * [#695](https://github.com/Icinga/icinga-powershell-framework/pull/695) Adds security hardening to JEA profiles by always prohibit certain cmdlets
 * [#700](https://github.com/Icinga/icinga-powershell-framework/pull/700) Adds feature to support using pipes and multi lines for plugin documentation
+* [#701](https://github.com/Icinga/icinga-powershell-framework/pull/701) Adds new command `Test-IcingaForWindows`to check the current environment health by also improving internal handlings on how service information are fetched, preventing a lock on those
 
 ## 1.11.1 (2023-11-07)
 

doc/300-Knowledge-Base.md

@@ -25,3 +25,4 @@ For this reason you will find a list of Icinga knowledge base entries below. Ent
 | [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>:`\\".\\"" |
 | [IWKB000016](knowledgebase/IWKB000016.md) | Checks using Performance Counter fail with various messages like `Exception of type 'System.OutOfMemoryException' was thrown` or `Icinga Invalid Configuration Error was thrown: PerfCounterCategoryMissing: Category "Memory" not found` |
 | [IWKB000017](knowledgebase/IWKB000017.md) | Icinga throws exception during plugin execution after uninstalling SCOM or other vendor software using PowerShell modules |
+| [IWKB000018](knowledgebase/IWKB000018.md) | Icinga for Windows services throws event id 1500 with error `Exception while calling AuthenticateAsServer: The credentials supplied to the package were not recognized` |

doc/knowledgebase/IWKB000018.md

@@ -0,0 +1,33 @@
+# Icinga Knowledge Base - IWKB000018
+
+## Short Message
+
+Icinga for Windows services throws event id 1500 with error `Exception while calling AuthenticateAsServer: The credentials supplied to the package were not recognized`
+
+## Example Exception
+
+Icinga for Windows throws an error with event id 1500:
+
+```
+Failed to securely establish a communication between this server and the client
+
+A client connection could not be established to this server. This issue is mostly caused by using Self-Signed/Icinga 2 Agent certificates for the server and the client not trusting the certificate. To resolve this issue, either use trusted certificates signed by your trusted CA or setup the client to accept untrusted certificates
+
+Icinga for Windows exception report:
+
+Exception Message:
+Exception calling "AuthenticateAsServer" with "4" argument(s): "The credentials supplied to the package were not recognized"
+
+Command Origin:
+Internal
+
+...
+```
+
+## Reason
+
+This message happens in case the user assigned to run the Icinga for Windows has no sufficient permissions to access the `icingaforwindows.pfx` certificate file or has no permissions to read the private key from the certificate file.
+
+## Solution
+
+To resolve this issue, you will either have to use [JEA-Profiles](../130-JEA/01-JEA-Profiles.md) or use a different user having enough permissions to access private key to the file. In general, only `LocalSystem` or `Administrators` have access to this key, which is why we highly recommend the use of JEA.

icinga-powershell-framework.psm1

@@ -58,6 +58,14 @@ function Use-Icinga()
 
     if ($LibOnly -eq $FALSE -And $Daemon -eq $FALSE) {
         Register-IcingaEventLog;
+
+        if ($Minimal -eq $FALSE -And (Test-IcingaFunction -Name 'Invoke-IcingaWindowsScheduledTask')) {
+
+            if (Test-IcingaFunction -Name 'Invoke-IcingaWindowsScheduledTask') {
+                # Use scheduled tasks to fetch our current service configuration for faster load times afterwards
+                Set-IcingaServiceEnvironment;
+            }
+        }
     }
 }
 

jobs/GetWindowsService.ps1

@@ -9,16 +9,23 @@ Use-Icinga -Minimal;
 [hashtable]$ServiceData = @{
     'Status'      = '';
     'Present'     = $FALSE;
-    'Name'        = 'Unknown';
-    'DisplayName' = 'Unknown';
+    'Name'        = $ServiceName;
+    'DisplayName' = $ServiceName;
+    'User'        = 'Unknown';
+    'ServicePath' = '';
 };
 
 try {
-    $SvcData                 = Get-Service "$ServiceName" -ErrorAction Stop;
-    $ServiceData.Status      = [string]$SvcData.Status;
-    $ServiceData.Name        = $SvcData.Name;
-    $ServiceData.DisplayName = $SvcData.DisplayName;
-    $ServiceData.Present     = $TRUE;
+    $SvcData = Get-IcingaServices "$ServiceName" -ErrorAction Stop;
+
+    if ($null -ne $SvcData) {
+        $ServiceData.Status      = [string]$SvcData."$ServiceName".configuration.Status.value;
+        $ServiceData.User        = [string]$SvcData."$ServiceName".configuration.ServiceUser;
+        $ServiceData.ServicePath = [string]$SvcData."$ServiceName".configuration.ServicePath;
+        $ServiceData.Name        = $SvcData."$ServiceName".metadata.ServiceName;
+        $ServiceData.DisplayName = $SvcData."$ServiceName".metadata.DisplayName;
+        $ServiceData.Present     = $TRUE;
+    }
 } catch {
     $ErrMsg  = [string]::Format('Failed to get data for service "{0}": {1}', $ServiceName, $_.Exception.Message);
 }

lib/core/framework/Install-IcingaForWindowsService.psm1

@@ -28,7 +28,7 @@ function Install-IcingaForWindowsService()
 {
     param(
         $Path,
-        $User,
+        $User                   = 'NT Authority\NetworkService',
         [SecureString]$Password
     );
 
@@ -38,14 +38,13 @@ function Install-IcingaForWindowsService()
     }
 
     $UpdateFile = [string]::Format('{0}.update', $Path);
-
-    $ServiceStatus = (Get-Service 'icingapowershell' -ErrorAction SilentlyContinue).Status;
+    $IfWService = $Global:Icinga.Protected.Environment.'PowerShell Service';
 
     if ((Test-Path $UpdateFile)) {
 
         Write-IcingaConsoleNotice 'Updating Icinga PowerShell Service binary';
 
-        if ($ServiceStatus -eq 'Running') {
+        if ($IfWService.Status -eq 'Running') {
             Write-IcingaConsoleNotice 'Stopping Icinga PowerShell service';
             Stop-IcingaWindowsService;
             Start-Sleep -Seconds 1;
@@ -68,8 +67,10 @@ function Install-IcingaForWindowsService()
         (Get-IcingaPowerShellModuleFile)
     );
 
-    if ($null -eq $ServiceStatus) {
+    if ($IfWService.Present -eq $FALSE) {
         $ServiceCreation = Start-IcingaProcess -Executable 'sc.exe' -Arguments ([string]::Format('create icingapowershell binPath= "{0}" DisplayName= "Icinga PowerShell Service" start= auto', $Path));
+        $Global:Icinga.Protected.Environment.'PowerShell Service'.Present = $TRUE;
+        $Global:Icinga.Protected.Environment.'PowerShell Service'.User    = $User;
 
         if ($ServiceCreation.ExitCode -ne 0) {
             throw ([string]::Format('Failed to install Icinga PowerShell Service: {0}{1}', $ServiceCreation.Message, $ServiceCreation.Error));
@@ -90,8 +91,9 @@ function Install-IcingaForWindowsService()
     Restart-IcingaForWindows;
     Start-Sleep -Seconds 1;
     Stop-IcingaWindowsService;
+    Start-Sleep -Seconds 1;
 
-    if ($ServiceStatus -eq 'Running') {
+    if ($IfWService.Status -eq 'Running') {
         Write-IcingaConsoleNotice 'Starting Icinga PowerShell service';
         Start-IcingaService 'icingapowershell';
         Start-Sleep -Seconds 1;

lib/core/framework/New-IcingaEnvironmentVariable.psm1

@@ -69,5 +69,11 @@ function New-IcingaEnvironmentVariable()
         $Global:Icinga.Protected.Add('Minimal', $FALSE);
         $Global:Icinga.Protected.Add('ThreadName', '');
         $Global:Icinga.Protected.Add('GarbageCollector', @{ });
+        $Global:Icinga.Protected.Add(
+            'Environment', @{
+                'Icinga Service'     = $null;
+                'PowerShell Service' = $null;
+            }
+        );
     }
 }

lib/core/framework/Test-IcingaForWindowsService.psm1

@@ -4,8 +4,10 @@ function Test-IcingaForWindowsService()
         [switch]$ResolveProblems = $FALSE
     );
 
+    Set-IcingaServiceEnvironment;
+
     $ServiceData   = Get-IcingaForWindowsServiceData;
-    $ServiceConfig = (Get-IcingaServices -Service 'icingapowershell').icingapowershell.configuration;
+    $ServiceConfig = $Global:Icinga.Protected.Environment.'PowerShell Service';
     [bool]$Passed  = $TRUE;
 
     if ($null -eq $ServiceConfig) {
@@ -18,7 +20,7 @@ function Test-IcingaForWindowsService()
         $ServiceData.FullPath,
         (Get-IcingaPowerShellModuleFile)
     );
-    [string]$ServicePath         = $ServiceConfig.ServicePath.SubString(0, $ServiceConfig.ServicePath.IndexOf(' "'));
+    [string]$ServicePath = $ServiceConfig.ServicePath.SubString(0, $ServiceConfig.ServicePath.IndexOf(' "'));
 
     if ($ServicePath.Contains('"')) {
         Write-IcingaTestOutput -Severity 'Passed' -Message 'Your service installation is not affected by IWKB000009';

lib/core/framework/Uninstall-IcingaForWindows.psm1

@@ -45,6 +45,7 @@ function Uninstall-IcingaForWindows()
         }
     }
 
+    Set-IcingaServiceEnvironment;
     Set-IcingaPSLocation;
 
     Write-IcingaConsoleNotice 'Uninstalling Icinga for Windows from this host';

lib/core/framework/Uninstall-IcingaForWindowsService.psm1

@@ -22,6 +22,8 @@ function Uninstall-IcingaForWindowsService()
         [switch]$RemoveFiles = $FALSE
     );
 
+    Set-IcingaServiceEnvironment;
+
     $ServiceData = Get-IcingaForWindowsServiceData;
 
     Stop-IcingaWindowsService;
@@ -32,6 +34,7 @@ function Uninstall-IcingaForWindowsService()
     switch ($ServiceCreation.ExitCode) {
         0 {
             Write-IcingaConsoleNotice 'Icinga PowerShell Service was successfully removed';
+            $Global:Icinga.Protected.Environment.'PowerShell Service'.Present = $FALSE;
         }
         1060 {
             Write-IcingaConsoleWarning 'The Icinga PowerShell Service is not installed';