Extends KB for execution policy and path

doc/10-Knowledge-Base.md

@@ -11,3 +11,5 @@ For this reason you will find a list of Icinga knowledge base entries below. Ent
 | [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.` |
 | [IWKB000003](knowledgebase/IWKB000003.md) | The Icinga Agent service `icinga2` cannot be started/modified/added because it is marked for deletion. |
+| [IWKB000004](knowledgebase/IWKB000004.md) | Use-Icinga : The 'Use-Icinga' command was found in the module 'icinga-powershell-framework', but the module could not be loaded. For more information, run 'Import-Module icinga-powershell-framework' |
+| [IWKB000005](knowledgebase/IWKB000005.md) | powershell.exe : Failed to start service 'Icinga PowerShell Service (icingapowershell)'. |

doc/knowledgebase/IWKB000004.md

@@ -0,0 +1,84 @@
+# Icinga Knowledge Base - IWKB000004
+
+## Short Message
+
+Use-Icinga : The 'Use-Icinga' command was found in the module 'icinga-powershell-framework', but the module could not be loaded. For more information, run 'Import-Module icinga-powershell-framework'
+
+## Example Exception
+
+Use-Icinga : The 'Use-Icinga' command was found in the module 'icinga-powershell-framework', but the module could not be loaded. For more information, run 'Import-Module icinga-powershell-framework'.
+
+At line:1 char:1 + Use-Icinga; exit Invoke-IcingaCheckMemory -CriticalPercent 99 -Warnin ... + ~~~~~~~~~~
+
+\+ CategoryInfo : ObjectNotFound:
+(Use-Icinga:String) [], CommandNotFoundException + FullyQualifiedErrorId : CouldNotAutoloadMatchingModule Invoke-IcingaCheckMemory : The term 'Invoke-IcingaCheckMemory' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.
+
+At line:1 char:18 + Use-Icinga; exit Invoke-IcingaCheckMemory -CriticalPercent 99 -Warnin ... + ~~~~~~~~~~~~~~~~~~~~~~~~ + CategoryInfo : ObjectNotFound: (Invoke-IcingaCheckMemory:String ) [], CommandNotFoundException + FullyQualifiedErrorId : CommandNotFoundException
+
+## Reason
+
+This error can have multiple reasons and different solutions. Most of the time this issue is caused either by `Execution Policies` and/or PowerShell files being blocked on the system. It does how ever mean the installation of the specific PowerShell module itself is fine and just some smaller tweaks are required.
+
+## Solutions
+
+### Import the Module
+
+Sometimes this issue can already be resolved by simply importing the module once with a user. In that case, all files are properly read and the module is available on the system. The corresponding module is always named within the exception messages. In this example, it is the `icinga-powershell-framework`. To import this module we simply run
+
+```powershell
+Import-Module 'icinga-powershell-framework';
+```
+
+In case no error occurs, we can continue this step for all affected modules and check if Icinga can now execute the commands. If not, please read on.
+
+### Unblock PowerShell Files
+
+Sometimes even with proper defined `Execution Policies` the execution of plugins or commands could fail. To resolve this, you can simply unblock the files of a specific folder. In this example we will assume that that modules are installed into `C:\Program Files\WindowsPowerShell\Modules` and our module name is `icinga-powershell-framework`.
+
+```powershell
+Get-ChildItem `
+    -Path 'C:\Program Files\WindowsPowershell\Modules\icinga-powershell-framework' `
+    -Recurse | Unblock-File
+```
+
+Repeat this for all affected modules and try again to execute plugins by Icinga. If the issue is not resolved, please read on
+
+### Configure Execution Policies
+
+Within the [Microsoft Docs](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy) there is a very detailed article on how `Execution Policies` work. In general these policies define on how PowerShell scripts and modules are being handled and if they can be executed by users.
+
+Before doing any modifications on `Execution Policies`, please check your internal security guidelines which rules should apply.
+
+To check on how the current `Execution Policies` are configured on the host, you can run this:
+
+```powershell
+Get-ExecutionPolicy -List
+```
+
+There are different scopes available to set policies for:
+
+* **MachinePolicy**: Set by a Group Policy for all users of the computer
+* **UserPolicy**: Set by a Group Policy for the current user of the computer
+* **Process**: Affects only the current PowerShell session
+* **CurrentUser**: Affects only the current user
+* **LocalMachine**: Default scope that affects all users of the computer
+
+For each scope, you can define a policy on how modules and scripts are checked and possibly blocked:
+
+* **AllSigned**: Requires that all scripts and configuration files are signed by a trusted publisher, including scripts written on the local computer
+* **Bypass**: Nothing is blocked and there are no warnings or prompts
+* **Default**: Sets the default execution policy. Restricted for Windows clients or RemoteSigned for Windows servers
+* **RemoteSigned**: Requires that all scripts and configuration files downloaded from the Internet are signed by a trusted publisher. The default execution policy for Windows server computers
+* **Restricted**: Doesn't load configuration files or run scripts. The default execution policy Windows client computers
+* **Undefined**: No execution policy is set for the scope. Removes an assigned execution policy from a scope that is not set by a Group Policy. If the execution policy in all scopes is Undefined, the effective execution policy is Restricted
+* **Unrestricted**: Loads all configuration files and runs all scripts. If you run an unsigned script that was downloaded from the Internet, you are prompted for permission before it runs
+
+In case your internal security policy defines that PowerShell scripts and modules require being **RemoteSigned**, you can do this for yourself as Icinga is not shipping signed modules. To do so, please have a look on the [Microsoft Docs About Signing](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_signing).
+
+To modify the `Execution Policies`, you have to run the PowerShell as Administrator and provide the `Scope` as well as the `Execution Policy`:
+
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine
+```
+
+Once applied, you can try to use `Import-Module` again for the affected PowerShell module and checking your Icinga again if checks are now properly executed.

doc/knowledgebase/IWKB000005.md

@@ -0,0 +1,87 @@
+# Icinga Knowledge Base - IWKB000005
+
+## Short Message
+
+powershell.exe : Failed to start service 'Icinga PowerShell Service (icingapowershell)'.
+
+## Example Exception
+
+powershell.exe : Failed to start service 'Icinga PowerShell Service (icingapowershell)'.
+
+At C:\Program
+Files\WindowsPowerShell\Modules\icinga-powershell-framework\lib\core\framework\Restart-IcingaService.psm1:29 char:9
+
+\+         powershell.exe -Command {
+
+\+         ~~~~~~~~~~~~~~~~~~~~~~~~~
+
+\+ CategoryInfo          : OpenError: (System.ServiceProcess ServiceController:ServiceController) [Restart-Service], ServiceCommandException
+
+\+ FullyQualifiedErrorId :
+StartServiceFailed,Microsoft.PowerShell.Commands.RestartServiceCommand
+
+### Event Log Entry
+
+error-event (Source: Icinga
+PowerShell Service, Event ID 0):
+
+Service cannot be started. System.ComponentModel.Win32Exception
+(0x80004005): The system cannot find the file specified
+
+at System.Diagnostics.Process.StartWithCreateProcess(ProcessStartInfo
+startInfo)
+
+at icinga_service.src.classes.Agent.StartAgent()
+
+at System.ServiceProcess.ServiceBase.ServiceQueuedMainCallback(Object
+state)
+
+## Reason
+
+The `icingapowershell` service of the `Icinga for Windows` solution is unable to locate `powershell.exe`. The service is using `powershell.exe` natively without any directory configuration and looking up the `PATH` variable which normally includes a path like `C:\Windows\System32\WindowsPowerShell\v1.0` which contains the required `powershell.exe`
+
+## Solution
+
+To resolve this issue, ensure that your `PATH` environment variable is containing a directory which inherits a `powershell.exe`. By default, this should be `C:\Windows\System32\WindowsPowerShell\v1.0`.
+
+You can check this by opening a PowerShell by running the following command:
+
+```powershell
+($ENV:Path).Split(';')
+```
+
+If there is no directory listed containing a `powershell.exe`, you will have to add this path manually. You can either use the UI for this or modify and run the following PowerShell code within an Administrator shell to add a new path permanently to the `PATH` variable by modifying the registry:
+
+```powershell
+# The variable containing the folder we want to include
+$PathDir = 'please enter the path here';
+
+# Read PATH from registry
+$CurrentPath = (Get-ItemProperty `
+    -Path 'HKLM:\System\CurrentControlSet\Control\Session Manager\Environment' `
+    -Name 'PATH'
+).path;
+
+# Add our defined path to the CurrentPath variable
+$CurrentPath = [string]::Format('{0};{1}', $CurrentPath, $PathDir);
+
+# Write the modified Path into the registry
+Set-ItemProperty `
+    -Path 'HKLM:\System\CurrentControlSet\Control\Session Manager\Environment' `
+    -Name 'PATH' `
+    -Value $CurrentPath;
+```
+
+Now open a new PowerShell session again and check of the new directory was added:
+
+```powershell
+($ENV:Path).Split(';')
+```
+
+Once the directory is there, restart the `icingapowershell` service by running
+
+```powershell
+Restart-Service 'icingapowershell'
+```
+
+Now the error should be resolved the the service should be running.