Merge pull request #154 from Icinga/doc/Uninstall-agent-from-powershell

Doc: Add description on how to uninstall Icinga Agent and add KB for issues

doc/06-Framework-Usage.md

@@ -12,3 +12,4 @@ The Icinga PowerShell Framework ships with a bunch of Cmdlets for monitoring, me
 * [Read Icinga Agent Log/DebugLog](frameworkusage/31-Read-Icinga-Agent_Log_DebugLog.md)
 * [Test Icinga Agent Environment](frameworkusage/32-Test-Icinga-Agent-Environment.md)
 * [Run Icinga Agent as other Service User](frameworkusage/33-Run-Icinga-Agent-As-Other-Service-User.md)
+* [Uninstall Icinga Agent](frameworkusage/34-Uninstall-Icinga-Agent.md)

doc/10-Knowledge-Base.md

@@ -10,3 +10,4 @@ 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. |

doc/frameworkusage/34-Uninstall-Icinga-Agent.md

@@ -0,0 +1,33 @@
+# Uninstall Icinga Agent
+
+While the main purpose of the Icinga for Windows solution is check your systems and provided all required tools, including the Icinga Agent, it might be required to entirely uninstall the Icinga Agent. This sometimes might even include to flush the entire `ProgramData` folder, where certificates and other configurations are stored.
+
+**Note:** Before using any of the commands below you will have to initialize the Icinga PowerShell Framework inside a new PowerShell instance with `Use-Icinga`. Starting with version `1.2.0` of the Framework you can also simply type `icinga` into the command line.
+
+## Uninstalling the Icinga Agent
+
+### Keep ProgramData Content
+
+If you only want to uninstall the Icinga Agent itself, but keep configuration files and certificates, you can use the `Uninstall-IcingaAgent` Cmdlet.
+
+```powershell
+Uninstall-IcingaAgent;
+```
+
+By default there are not special arguments required and once completed you will be prompted with a message that the Icinga Agent has been removed
+
+### Remove ProgramData Content
+
+In some cases it might be helpful for troubleshooting to uninstall the Icinga Agent entirely, including the `ProgramData` content. We can do this with the same command, but add another argument:
+
+```powershell
+Uninstall-IcingaAgent -RemoveDataFolder;
+```
+
+Now the Icinga Agent will be installed and afterwards the entire content at `C:\ProgramData\ICINGA2` will be deleted.
+
+**Note**: If you missed to add `-RemoveDataFolder` on your first attempt, you can run the command with the argument set again. In case the Icinga Agent is not installed, this part will be skipped and the `ProgramData` folder content will be flushed.
+
+## Icinga Agent Service is "Marked for Deletion"
+
+This issue can happen during installation/uninstallation/upgrading processes. We have written the [Knowledge Base Article IWKB000003](../knowledgebase/IWKB000003.md) for this scenario.

doc/knowledgebase/IWKB000003.md

@@ -0,0 +1,26 @@
+# Icinga Knowledge Base - IWKB000003
+
+## Short Message
+
+The service cannot be started/modified/added because it is marked for deletion. Re-Installing the Icinga Agent fails and starting it is also not possible.
+
+## Example Exception
+
+The service cannot be started because it is marked for deletion.
+
+## Reason
+
+In some edge cases it can happen that the `icinga2` service is not removed during an upgrade or uninstallation process. The reason for this is that another tool might have a `lock` on the service, preventing Windows from deleting it. For example this could be the `services` window on where you can manage service, like restarting them or a PowerShell instance you used to work with to modify the service itself.
+
+## Solution
+
+The easiest way of course is to simply reboot the system - this will remove any lock on the service and once Windows is rebooted, the service is deleted.
+
+As this solution is how ever not really usable in enterprise environments, the best approach would be to close all windows which could interact with the service or you interacted with. This includes:
+
+* Windows Task Manager
+* PowerShell / Cmd instances
+* Services.msc
+* Visual Studio Code / PowerShell ISE (because of the PowerShell instance)
+
+Once you found the tool locking the service, it will be removed and you can reinstall the Icinga Agent properly.