Updates doc for 1.5.0

doc/06-Framework-Usage.md

@@ -9,6 +9,8 @@ The Icinga PowerShell Framework ships with a bunch of Cmdlets for monitoring, me
 * [Install Wizard Guide](frameworkusage/03-Install-Wizard-Guide.md)
 * [Disable Certificate Validation](frameworkusage/04-Disable-Certificate-Validation.md)
 * [Enable Framework Code Caching](frameworkusage/05-Enable-Framework-Code-Caching.md)
+* [Update Framework and Components](frameworkusage/06-Update-Framework-And-Components.md)
+* [Analyse EventLog](frameworkusage/07-Analyse-EventLog.md)
 
 ## Icinga Agent Management
 
@@ -23,3 +25,4 @@ The Icinga PowerShell Framework ships with a bunch of Cmdlets for monitoring, me
 ## Experimental
 
 * [Forward checks to internal API](experimental/01-Forward-checks-to-internal-API.md)
+* [Management Console](experimental/02-Management-Console.md)

doc/experimental/02-Management-Console.md

@@ -0,0 +1,83 @@
+# Experimental: Management Console
+
+With Icinga for Windows v1.4.0, we added a new experimental feature to easier manage Icinga for Windows and the agent: The `Management Console`
+
+It is directly build into the Framework an can be called from a PowerShell (`administrative`) with
+
+```powershell
+icinga -Manage;
+```
+
+## First Look
+
+```powershell
+***********************************************************************
+**               Icinga for Windows Management Console               **
+**               Copyright (c) 2021 Icinga GmbH | MIT                **
+**                 User environment ws-icinga\icinga                  **
+**                Icinga PowerShell Framework v1.5.0                 **
+**      This is an experimental feature and might contain bugs       **
+**       Please provide us with feedback, issues and input at        **
+**   https://github.com/Icinga/icinga-powershell-framework/issues    **
+***********************************************************************
+
+What do you want to do?
+
+[0] Installation
+[1] Update environment
+[2] Manage environment
+[3] Remove components
+
+[x] Exit [c] Continue [h] Help [m] Main
+
+Input (Default 0 and c):
+```
+
+## Using The Management Console
+
+Navigating inside the Management Console work as with any other console around. On the left side of the menu entries you can find a number, which you have to type in and press enter afterwards to enter this menu.
+If you want to `Manage environment`, you will have to type in `2` and press `enter` to switch to the menu.
+
+In addition, there is a bunch of other options below the menu list items, telling you what you can do. Here is a full list you can type in and press enter afterwards:
+
+* `a` (Advanced): Will only occur on several forms and will show advanced options for additional configuration settings
+* `c` (Continue): Will mostly be used as default and allows you to continue. Might not always be present
+* `d` (Delete): Allows you to delete values for forms on which you have to enter data to continue
+* `h` (Help): Will either print the help for each entry and menu section or disables it (toogle)
+* `m` (Main): Allows you to jump back to the main menu
+* `p` (Previous): Allows you to jump to the previous menu, in case you are not inside the root of another element
+* `x` (Exit): Will close the Management Console
+
+## Capabilities
+
+Right now you can do the following tasks:
+
+* Install Icinga Agent, Icinga for Windows and all components
+* Use the Icinga Director Self-Service API
+* Manage Icinga Agent features
+* Remove Icinga Agent or any installed Icinga for Windows component
+* Enable Icinga PowerShell Framework Features (including experimental)
+* Configure installed background daemons (register/unregister)
+* Start/Restart/Stop Icinga Agent and Icinga for Windows service
+
+If you configured your Icinga Agent and Icinga for Windows setup on this machine with the Management Console, you can reconfigure the current active configuration by navigating to `Manage environment` -> `Icinga Agent` -> `Reconfigure Installation`.
+
+Once you did your initial configuration with the new wizard, the configuration is stored within the Frameworks config and can easily and simply be adjusted from this UI or used to export your configuration command or file.
+
+## Automation With The Management Console
+
+To automate your setuo, you can export your configuration either as command or into a file and can use it later on a different system
+
+### Configuration Command
+
+```powershell
+Install-Icinga -InstallCommand '{"IfW-ParentAddress":{"Values":{"icinga2":["127.0.0.1"]}},"IfW-CodeCache":{"Selection":"0"},"IfW-Hostname":{"Selection":"3"},"IfW-ParentZone":{"Values":["master"]},"IfW-Connection":{"Selection":"2"},"IfW-ParentNodes":{"Values":["icinga2"]}}';
+```
+
+### Configuration File
+
+The configuration file is a simple `JSON` file, identical to the argument value for `-InstallCommand` above, but stored inside a file. You can load this file into the command, for easier management.
+
+```powershell
+Install-Icinga -InstallFile 'C:\Icinga2\IfW_answer.json';
+```

doc/frameworkusage/06-Update-Framework-And-Components.md

@@ -0,0 +1,111 @@
+# Update Framework and Components
+
+Icinga for Windows ships with a bunch of Cmdlets, allowing users to manage the entire environment without much effort. This includes features to install entire components, but also allows to update them.
+
+## Updating Icinga PowerShell Framework
+
+To update the Framework it is not required to run the [installation process](..\02-Installation.md) again. The Framework ships with a native command for this and is recommended to use, as this allows you to keep your current configuration and cache files. The command is `Install-IcingaFrameworkUpdate`.
+
+### Interactive Update
+
+To start the interactive update with a wizard, asking you on how to update, simply type the command inside your Icinga shell or call `Use-Icinga` before.
+
+```powershell
+Install-IcingaFrameworkUpdate;
+```
+
+Afterwards you will be asked a bunch of questions, which we explain in the following.
+
+```text
+Do you provide a custom repository for "Icinga Framework"? (y/N):
+```
+
+Like any other component, you can type in y or n for this answer. The custom repository is defined as a `.zip` file you might have downloaded directly from GitHub for the Framework at placed it either on your Icinga webserver somewhere, or locally. If you type no, you can choose if you want to install the latest stable or snapshot.
+
+```text
+Which version of the "Icinga Framework" do you want to install? (release/snapshot) (Defaults: "release"):
+```
+
+By default the command will connect to `https://github.com/Icinga/icinga-powershell-framework` and either fetch the latest stable release if you select `release` or the current master branch if you use `snapshot`.
+Lets assume we update our production environment and therefor using `release`.
+
+```powershell
+icinga> Install-IcingaFrameworkUpdate
+Do you provide a custom repository for "Icinga Framework"? (y/N):
+Which version of the "Icinga Framework" do you want to install? (release/snapshot) (Defaults: "release"):
+[Notice]: Downloading "Icinga Framework" into "C:\Users\Administrator\AppData\Local\Temp\tmp_icinga1262975608.d"
+[Notice]: Installing module into "C:\Users\Administrator\AppData\Local\Temp\tmp_icinga1262975608.d"
+[Notice]: Using content of folder "C:\Users\Administrator\AppData\Local\Temp\tmp_icinga1262975608.d\icinga-powershell-framework-1.4.1" for updates
+[Notice]: Stopping Icinga Agent service
+[Notice]: Stopping service "icinga2"
+[Notice]: Removing files from framework
+[Notice]: Copying new files to framework
+[Notice]: Unblocking Icinga PowerShell Files
+[Notice]: Cleaning temporary content
+[Notice]: Updating Framework cache file
+[Notice]: The code caching feature is currently not enabled. You can enable it with "Enable-IcingaFrameworkCodeCache"
+[Notice]: Framework update has been completed. Please start a new PowerShell instance now to complete the update
+[Passed]: Icinga Agent service is installed
+[Passed]: The specified user "NT Authority\NetworkService" is allowed to run as service
+[Passed]: Directory "C:\ProgramData\icinga2\etc" is accessible and writeable by the Icinga Service User "NT Authority\NetworkService"
+[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writeable by the Icinga Service User "NT Authority\NetworkService"
+[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writeable by the Icinga Service User "NT Authority\NetworkService"
+[Passed]: Icinga Agent configuration is valid
+[Passed]: Icinga Agent debug log is disabled
+[Notice]: Starting Icinga Agent service
+[Notice]: Starting service "icinga2"
+```
+
+Thats it. Your Icinga Agent will now continue it's work behind without requiring additional actions. If you want to use the new Framework features, you should open a new PowerShell instance to apply the updates to your current session.
+
+### Update With Defined Package
+
+To avoid the above wizard and to properly automate the task, the Cmdlet `Install-IcingaFrameworkUpdate` ships with one additional argument: `-FrameworkUrl`
+
+As `-FrameworkUrl` you can define the target to the Icinga PowerShell Frameworks `.zip` file and directly install this version with the same result as above, but fully automated without questions.
+
+#### Examples For URL
+
+Local File:
+
+```powershell
+Install-IcingaFrameworkUpdate -FrameworkUrl 'C:\Icinga2\icinga-powershell-framework-1.5.0.zip';
+```
+
+NetworkShare File:
+
+```powershell
+Install-IcingaFrameworkUpdate -FrameworkUrl '\\icinga.example.com\IcingaForWindows\Icinga2\icinga-powershell-framework-1.5.0.zip';
+```
+
+Custom Web Path:
+
+```powershell
+Install-IcingaFrameworkUpdate -FrameworkUrl 'https://example.com/Icinga/icinga-powershell-framework-1.5.0.zip';
+```
+
+GitHub Release:
+
+```powershell
+Install-IcingaFrameworkUpdate -FrameworkUrl 'https://github.com/Icinga/icinga-powershell-framework/archive/refs/tags/v1.5.0.zip';
+```
+
+GitHub Master Branch:
+
+```powershell
+Install-IcingaFrameworkUpdate -FrameworkUrl 'https://github.com/Icinga/icinga-powershell-framework/archive/refs/heads/master.zip';
+```
+
+GitHub Branch
+
+```powershell
+Install-IcingaFrameworkUpdate -FrameworkUrl 'https://github.com/Icinga/icinga-powershell-framework/archive/refs/heads/fix/framework_root_folder_lookup.zip';
+```
+
+Once you enter the command, the update process will continue as shown above earlier
+
+## Updating Icinga PowerShell Components
+
+Updating components like [plugins](https://icinga.com/docs/icinga-for-windows/latest/plugins/doc/01-Introduction/) is as easy as installing them. If you used the [Framework Component Installer](https://icinga.com/docs/icinga-for-windows/latest/plugins/doc/02-Installation/#icinga-framework-component-installer) as described in every plugin repository, you can use the same command to update the plugins as well.
+
+The command `Install-IcingaFrameworkComponent` is designed to both, install components on a fresh environment and also keeps them updated if you run the same command again.

doc/frameworkusage/07-Analyse-EventLog.md

@@ -0,0 +1,54 @@
+# Analyse EventLog
+
+With Icinga for Windows v1.5.0, we added a simple Cmdlet, allowing you to analyse your EventLog, which might help you to configure your [Invoke-IcingaCheckEventlog](https://icinga.com/docs/icinga-for-windows/latest/plugins/doc/plugins/06-Invoke-IcingaCheckEventlog/) plugin and to increase performance. The command is called `Show-IcingaEventLogAnalysis`
+
+## Analyse Specific Logs
+
+Like the [Invoke-IcingaCheckEventlog](https://icinga.com/docs/icinga-for-windows/latest/plugins/doc/plugins/06-Invoke-IcingaCheckEventlog/), you have to specify an EventLog to analyse by using the argument `-LogName`.
+The EventLog analyser will then load all events present in this log, and analyse the following:
+
+* Total amount of logs
+* Average logs per day/hour/minute
+* Oldes and newest logs
+
+Example:
+
+```powershell
+icinga> Show-IcingaEventLogAnalysis -LogName Application;
+[Notice]: Analysing EventLog "Application"...
+[Notice]: Logging Mode: Circular
+[Notice]: Maximum Size: 0.02 GB
+[Notice]: Current Entries: 62036
+[Notice]: Average Logs per Day: 8863
+[Notice]: Average Logs per Hour: 447
+[Notice]: Average Logs per Minute: 15
+[Notice]: Maximum Logs per Day: 26143
+[Notice]: Maximum Logs per Hour: 1724
+[Notice]: Maximum Logs per Minute: 239
+[Notice]: Newest entry timestamp: 2021-06-02 09:06:42
+[Notice]: Oldest entry timestamp: 2021-05-27 15:11:53
+[Notice]: Analysing Time: 11.19s
+```
+
+Based on these information, you can improve the EventLog check on this system even more, as we added the `-MaxEntries` argument to [Invoke-IcingaCheckEventlog](https://icinga.com/docs/icinga-for-windows/latest/plugins/doc/plugins/06-Invoke-IcingaCheckEventlog/), which will limit the amount of logs loaded for the check. The value currently defaults to `40000`.
+
+## Understanding The Data
+
+As we now run the analyse command for the log we want to monitor, we can have a look on the data. The idea behind this, is to understand on how many log entries are present on a specific time range, as this will help us to determine if we require to load the default of `40000` events or can reduce this number and therefor the execution time of the plugin.
+
+Lets assume we are going to run our EventLog check every `5 minutes`. The average log amount per Minute is `15`, while the maximum ever occurred is `239` per minute.
+We will always recommend to use the maximum log amount as base calculation. In addition, once you did the calculation double the value to ensure you always have enough buffer left in case more entries are logged.
+
+As we can simply use the maximum minute value in our example, the calculation would be this:
+
+```text
+239 maximum logs per minute * 5 minute check interval * 2 = 2390 logs
+```
+
+We can now use this value, to improve the EventLog check:
+
+```powershell
+Invoke-IcingaCheckEventlog -LogName Application -Warning 5 -IncludeEntryType Warning -Before 5m -MaxEntries 2390;
+
+[OK] EventLog: 1 Ok
+```

doc/frameworkusage/35-Install-Update-Icinga-Agent.md

@@ -13,7 +13,7 @@ The Icinga PowerShell Framework ships with a simple Cmdlet to install/update the
 To simply install the latest version of the Icinga Agent, you can run the following command:
 
 ```powershell
-Install-IcingaAgent -Version 'latest'
+Install-IcingaAgent -Version 'release'
 ```
 
 This will lookup the default installation source `https://packages.icinga.com/windows/`, fetch the latest version, download and install it.
@@ -33,7 +33,7 @@ This will download Icinga Agent `2.11.6` from `https://packages.icinga.com/windo
 Similar to the above examples, you can also update or downgrade the Icinga Agent with this command. All argument handling as before applies. However, to tell the command to perform an upgrade or downgrade, you will have to set the argument `-AllowUpdates` in addition (which also applies to downgrades):
 
 ```powershell
-Install-IcingaAgent -Version 'latest' -AllowUpdates 1
+Install-IcingaAgent -Version 'release' -AllowUpdates 1
 ```
 
 ## Customizing the Installer
@@ -50,5 +50,5 @@ Of course, you can also modify the `Install-IcingaAgent` command with different
 For example we can distribute Icinga Agents over a local network share for better update management.
 
 ```powershell
-Install-IcingaAgent -Version 'latest' -AllowUpdates 1 -Source '\\example.com\icinga\icingaagent\'
+Install-IcingaAgent -Version 'release' -AllowUpdates 1 -Source '\\example.com\icinga\icingaagent\'
 ```