Merge pull request #465 from Icinga:doc/knowledge_base_extension

Docs: Extend knowledge base

Author: LordHepipud

doc/300-Knowledge-Base.md

@@ -17,3 +17,5 @@ For this reason you will find a list of Icinga knowledge base entries below. Ent
 | [IWKB000007](knowledgebase/IWKB000007.md) | Icinga Director Self-Service API fails with errors. [Error]: The remote host for address "..." could not be resolved [Error]: Failed to connect to your Icinga Director at "...". Please try again. |
 | [IWKB000008](knowledgebase/IWKB000008.md) | The EventLog contains many `Perflib`, `PerfNet` and `PerfProc` errors/warnings with EventId `1008`, `2002` and `2004` |
 | [IWKB000009](knowledgebase/IWKB000009.md) | The remote Windows host has at least one service installed that uses an unquoted service path, which contains at least one whitespace. A local attacker can gain elevated privileges by inserting an executable file in the path of the affected service |
+| [IWKB000010](knowledgebase/IWKB000010.md) | The Icinga PowerShell Framework is either not installed on the system or not configured properly. Please check https://icinga.com/docs/windows for further details Error: The term 'Use-Icinga' 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. |
+| [IWKB000011](knowledgebase/IWKB000011.md) | The Icinga PowerShell Framework is either not installed on the system or not configured properly. Please check https://icinga.com/docs/windows for further details Error: The term 'Use-Icinga' 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. |

doc/knowledgebase/IWKB000010.md

@@ -0,0 +1,52 @@
+# Icinga Knowledge Base - IWKB000010
+
+## Short Message
+
+The Icinga PowerShell Framework is either not installed on the system or not configured properly. Please check https://icinga.com/docs/windows for further details
+Error: The term 'Use-Icinga' 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.
+
+Components:
+
+Module-Path:
+
+C:\windows\ServiceProfiles\NetworkService\Documents\WindowsPowerShell\Modules;C:\Program Files (x86)\WindowsPowerShell\Modules;C:\windows\system32\WindowsPowerShell\v1.0\Modules
+
+## Reason
+
+The Icinga PowerShell Framework is either not installed on the system, the service user running the Icinga Agent is unable to access the PowerShell module folder it is installed into or you have installed the wrong architecture of the Icinga Agent.
+
+## Solution
+
+### Test Installation
+
+First check locally if Icinga for Windows is installed properly. You can do so by opening a PowerShell and type `icinga` into the prompt. If you are greeted with an Icinga shell, the installation is working properly.
+
+In case this fails, ensure you are running the correct PowerShell on your system.
+
+For `x86` systems, there is only one PowerShell present.
+
+For `x64` systems (the majority), you will have to open the `Windows PowerShell`, **NOT** the `Windows PowerShell (x86)`.
+
+If you have ensured the correct PowerShell is started, try again with the `icinga` command
+
+### Check PowerShell Module Folders
+
+Ensure that the folder you have installed the Icinga PowerShell Framework into is listed at `$Env:PSModulePath`. The above error message also provides a list of module folders which are checked by the service user. Ensure the module folder you have installed everything into is listed there.
+If it is not present, either move the Icinga for Windows files to a listed folder or add it to the environment variables.
+
+If you installed Icinga for Windows into `C:\Program Files\WindowsPowerShell\Modules` and it is not listed in aboves messages, please read on.
+
+### Wrong Agent Architecture
+
+In case you receive above error while installing Icinga for Windows into `C:\Program Files\WindowsPowerShell\Modules`, it means you have installed the `x86` version of the Icinga Agent instead of the `x64` version.
+This mostly happens when you start the wrong PowerShell architecture (see `Test Installation` above) and install Icinga for Windows from this shell. If you started an `x86` shell on an `x64` system, the Icinga for Windows installer will install the `x86` Icinga Agent, which then have no access to the `x64` files, causing the above error.
+
+To resolve this, open the correct PowerShell and run the following command:
+
+```powershell
+Install-IcingaComponent -Name agent -Force -Confirm;
+```
+
+This will uninstall the wrong `x86` and install the correct `x64` version of the Icinga Agent.
+
+If you receive an error `[SC] ChangeServiceConfig FAILED 1072: The specified service has been marked for deletion` error, please have a look on the next [Knowledge Base entry IWKB000011](IWKB000011.md)

doc/knowledgebase/IWKB000011.md

@@ -0,0 +1,28 @@
+# Icinga Knowledge Base - IWKB000011
+
+## Short Message
+
+[SC] ChangeServiceConfig FAILED 1072: The specified service has been marked for deletion
+
+## Reason
+
+While updating the Icinga Agent, the above error message can occur during the upgrade process. This is caused as the Icinga Agent installer is not allowing an upgrade over CLI, but requires an uninstallation before.
+Even when updating the Icinga Agent by the GUI version of the MSI installer, an upgrade will always remove the Icinga Agent service from the system, installing it later again.
+
+Because of several possible remaining access from the current PowerShell, a Task Manager view, an open Service view or other reasons, the service is not being deleted right away, but marked for deletion instead. This prevents the Icinga Agent installer to install the new service, as the old one is still present.
+
+## Solution
+
+To resolve this issue, you will have to close all PowerShell instances, the Task Manager and the Service view in case open. Once closed, you can repair the Icinga Agent service with the following command:
+
+```powershell
+Repair-IcingaService;
+```
+
+This will check if the Icinga Agent is installed on a default location and install the service again.
+
+In case you have installed the Icinga Agent inside a different folder, you can provide the Icinga Agent root folder with the argument `-RootFolder`:
+
+```powershell
+Repair-IcingaService -RootFolder 'D:\Programs\ICINGA2';
+```