Merge pull request #198 from Icinga:feature/add_support_to_flush_api_directory_by_cmdlet

Feature: Adds Cmdlet to flush Icinga Agent API directory

doc/06-Framework-Usage.md

@@ -17,3 +17,4 @@ The Icinga PowerShell Framework ships with a bunch of Cmdlets for monitoring, me
 * [Run Icinga Agent as other Service User](frameworkusage/33-Run-Icinga-Agent-As-Other-Service-User.md)
 * [Install/Update Icinga Agent](frameworkusage/35-Install-Update-Icinga-Agent.md)
 * [Uninstall Icinga Agent](frameworkusage/34-Uninstall-Icinga-Agent.md)
+* [Flush Icinga Agent API Directory](frameworkusage/36-Flush-Icinga-Agent-API-Directory.md)

doc/31-Changelog.md

@@ -14,6 +14,7 @@ Released closed milestones can be found on [GitHub](https://github.com/Icinga/ic
 ### Enhancements
 
 * [#193](https://github.com/Icinga/icinga-powershell-framework/pull/193) Adds optional support for adding milliseconds to `Get-IcingaUnixTime` with the `-Milliseconds` argument for more detailed time comparison
+* [#198](https://github.com/Icinga/icinga-powershell-framework/pull/198) Adds support to flush the content of the Icinga Agent API directory with a single Cmdlet `Clear-IcingaAgentApiDirectory`
 
 ## 1.3.1 (2021-02-04)
 

doc/frameworkusage/36-Flush-Icinga-Agent-API-Directory.md

@@ -0,0 +1,19 @@
+# Flush Icinga Agent API Directory
+
+In some cases it might be helpful or required to flush the local Icinga Agent API directory from the disk. To assist with this process, there is a simple Cmdlet available.
+
+## Delete the API Directory Content
+
+To flush the content, you will have to stop the Icinga Agent service and run the following Cmdlet within an Icinga Shell:
+
+```powershell
+Clear-IcingaAgentApiDirectory
+```
+
+## Delete API Directory with automated Icinga Agent handling
+
+In case you want to automate the process, you can add the `-Force` argument which will stop the Icinga Agent service for you, flush the API directory content and start the Icinga Agent afterwards again:
+
+```powershell
+Clear-IcingaAgentApiDirectory -Force
+```

lib/core/icingaagent/misc/Clear-IcingaAgentApiDirectory.psm1

@@ -0,0 +1,56 @@
+<#
+.SYNOPSIS
+   Clears the entire content of the Icinga Agent API directory located
+   at Program Data\icinga2\var\lib\icinga2\api\
+.DESCRIPTION
+   Clears the entire content of the Icinga Agent API directory located
+   at Program Data\icinga2\var\lib\icinga2\api\
+.FUNCTIONALITY
+   Clears the entire content of the Icinga Agent API directory located
+   at Program Data\icinga2\var\lib\icinga2\api\
+.EXAMPLE
+   PS>Clear-IcingaAgentApiDirectory;
+.EXAMPLE
+   PS>Clear-IcingaAgentApiDirectory -Force;
+.PARAMETER Force
+   In case the Icinga Agent service is running while executing the command,
+   the force argument will ensure the service is stopped before the API
+   directory is flushed and restarted afterwards
+.INPUTS
+   System.Boolean
+.LINK
+   https://github.com/Icinga/icinga-powershell-framework
+#>
+
+function Clear-IcingaAgentApiDirectory()
+{
+    param (
+        [switch]$Force = $FALSE
+    );
+
+    $IcingaService = (Get-IcingaServices -Service icinga2).icinga2;
+    $ApiDirectory  = (Join-Path -Path $Env:ProgramData -ChildPath 'icinga2\var\lib\icinga2\api\');
+
+    if ((Test-Path $ApiDirectory) -eq $FALSE) {
+        Write-IcingaConsoleError 'The Icinga Agent API directory is not present on this system. Please check if the Icinga Agent is installed';
+        return;
+    }
+
+    if ($IcingaService.configuration.Status.raw -eq 4 -And $Force -eq $FALSE) {
+        Write-IcingaConsoleError 'The API directory can not be deleted while the Icinga Agent is running. Use the "-Force" argument to stop the service, flush the directory and restart the service again.';
+        return;
+    }
+
+    if ($IcingaService.configuration.Status.raw -eq 4) {
+        Stop-IcingaService icinga2;
+        Start-Sleep -Seconds 1;
+    }
+
+    Write-IcingaConsoleNotice 'Flushing Icinga Agent API directory';
+    Remove-ItemSecure -Path (Join-Path -Path $ApiDirectory -ChildPath '*') -Recurse -Force | Out-Null;
+    Start-Sleep -Seconds 1;
+
+    if ($IcingaService.configuration.Status.raw -eq 4) {
+        Start-IcingaService icinga2;
+    }
+}