Merge branch 'master' into support/1.0

Author: LordHepipud

.gitattributes

@@ -0,0 +1,5 @@
+# Exclude files related to git when generating an archive
+.git* export-ignore
+
+# Include version information on `git archive'
+VERSION export-subst

README.md

@@ -13,12 +13,13 @@ Please take a look at the following content to get to know the possibilities of
 
 * [Introduction](doc/01-Introduction.md)
 * [Installation Guide](doc/02-Installation.md)
-* [Icinga Integration](doc/05-IcingaIntegration.md)
+* [Icinga Integration](doc/05-Icinga-Integration.md)
+* [PowerShell as Service](doc/service/01-Install-Service.md)
 
 Developer Guide
 ------------
 
-If you wish to extend the Framework by yourself or write custom plugins for your environment, please have a look at the [Developer Guide](doc/04-DeveloperGuide.md) for detailed explanations of functions and code examples.
+If you wish to extend the Framework by yourself or write custom plugins for your environment, please have a look at the [Developer Guide](doc/04-Developer-Guide.md) for detailed explanations of functions and code examples.
 
 Contributing
 ------------

doc/02-Installation.md

@@ -21,3 +21,10 @@ Use-Icinga
 This command will initialise the entire module and load all available Cmdlets.
 
 Whenever you intend to use specific Cmdlets of the framework for Icinga Plugins, Testing or configuration you will require to run this command for each new PowerShell instance to initialise the framework.
+
+Service Installation
+---
+
+You can install a service which will allow you to run the PowerShell Framework as background daemon. This will add the possibility to register functions to run frequently for collecting data or execute different tasks on the system.
+
+To install the service you can either follow the `IcingaAgentInstallWizard` or do it [manually](service/01-Install-Service.md)

doc/04-Developer-Guide.md

@@ -12,3 +12,4 @@ A detailed overview of functions can be found below
 
 * [New-IcingaCheck](developerguide/01-New-IcingaCheck.md)
 * [New-IcingaCheckPackage](developerguide/02-New-IcingaCheckPackage.md)
+* [Custom Daemons](developerguide/10-Custom-Daemons.md)

doc/developerguide/01-New-IcingaCheck.md

@@ -42,10 +42,10 @@ For performance metrics you can provide a `Unit` to ensure your graphing is disp
 | ms   | Milliseconds | The input is indicated as time in milliseconds  |
 | us   | Microseconds | The input is indicated as time in microseconds  |
 | B    | Bytes        | The input is indicated as quantity in bytes     |
-| KB   | Kilobytes    | The input is indicated as quantity in kilobytes |
-| MB   | Megabytes    | The input is indicated as quantity in megabytes |
-| GB   | Gigabytes    | The input is indicated as quantity in gigabytes |
-| TB   | Terabytes    | The input is indicated as quantity in terabytes |
+| KB   | Kilobytes    | The input is indicated as quantity in Kilobytes |
+| MB   | Megabytes    | The input is indicated as quantity in Megabytes |
+| GB   | Gigabytes    | The input is indicated as quantity in Gigabytes |
+| TB   | Terabytes    | The input is indicated as quantity in Terabytes |
 | c    | Counter      | A continues counter increasing values over time |
 
 ## Object Functions

doc/developerguide/10-Custom-Daemons.md

@@ -1,7 +1,7 @@
 Install the framework with the Kickstart Script
 ===
 
-The easiest way to install the framework is by using the Kickstart Script provided from [this repository](https://github.com/Icinga/icinga-framework-kickstart).
+The easiest way to install the framework is by using the Kickstart Script provided from [this repository](https://github.com/Icinga/icinga-powershell-kickstart).
 
 The code provided there will ask questions on where to install the framework and where the framework files are provided from. The code below is a straight copy of the initial required code-block. Simply open a PowerShell instance as administrator and copy the following code block into it:
 

doc/installation/01-Kickstart-Script.md

@@ -1,4 +1,4 @@
-Run the PowerShell Module as Windows Service
+Run the PowerShell Framework as Windows Service
 ===
 
 Requirements
@@ -8,6 +8,11 @@ As PowerShell Scripts / Modules can not be installed directly as Windows Service
 
 In order to make this work, you will require the Icinga Windows Service which can be downloaded directly from the [GitHub Repository](https://github.com/Icinga/icinga-powershell-service).
 
+Benefits
+---
+
+Running the PowerShell Framework as background service will add the possibility to register certain functions which are executed depending on their configuration / coding. One example would be to frequently collect monitoring metrics from the installed plugins, allowing you to receice an average of time for the CPU load for example.
+
 Install the Service
 ---
 
@@ -36,3 +41,13 @@ Install-IcingaFrameworkService -Path 'C:\Program Files\Icinga-Framework-Service\
 You can validate if the service has been installed properly by using the Get Service Cmdlet:
 
 Each enabled background daemon component is afterwards being started and executed.
+
+Register Functions
+---
+
+As the service is now installed we can start to [register daemons](02-Register-Daemons.md) which are executed within an own thread within a PowerShell session. Depending on the registered function/module, additional configuration may be required.
+
+Background Service Check
+---
+
+Once you registered the Daemon `Start-IcingaServiceCheckDaemon` with the [register functions](02-Register-Daemons.md) feature you will be able to [register service checks](10-Register-Service-Checks.md) which are frequently executed to collect metrics from plugins.

doc/10-Install-Service.md renamed to doc/service/01-Install-Service.md

@@ -0,0 +1,62 @@
+Register Background Daemons
+===
+
+One huge advantage of the entire PowerShell Framework for Icinga is to run the PowerShell environment as background service. Once you [installed the service](01-Install-Service.md) you can simply register functions which are executed.
+
+Register Daemon
+---
+
+To register daemons which are executed on the backkground daemon, you can use the build in command `Register-IcingaBackgroundDaemon`. An example would be to enable the frequent service check daemon which ships with this framework
+
+```powershell
+Register-IcingaBackgroundDaemon -Command 'Start-IcingaServiceCheckDaemon';
+```
+
+The `Start-IcingaServiceCheckDaemon` is a directly integrated PowerShell function which will itself start an own thread for executing regular service checks which have been registered.
+
+Once you made changes, please remember to restart the PowerShell Service
+
+```powershell
+Restart-IcingaService 'icingapowershell';
+```
+
+List Enabled Daemons
+---
+
+To list all registered background daemons you can use a build-in command for this
+
+```powershell
+Get-IcingaBackgroundDaemons;
+```
+
+Once executed you will receive a list of all daemons which are started
+
+```powershell
+Name                           Value
+----                           -----
+Start-IcingaServiceCheckDaemon {}
+```
+
+Remove Daemons
+---
+
+Besides adding and displaying registered background daemons you can also use the unregister command to remove them
+
+```powershell
+Unregister-IcingaBackgroundDaemon -BackgroundDaemon 'Start-IcingaServiceCheckDaemon';
+```
+
+Once you restart the PowerShell service the pending changes are applied
+
+```powershell
+Restart-IcingaService 'icingapowershell';
+```
+
+Write Custom Daemons
+---
+
+In addition you are free to write your own extensions you can register within the framework. Every PowerShell daemon which is available within a single PowerShell session - even from different modules - can be used.
+
+Best practice would be to create an own custom PowerShell Module which will create a new thread and executing certain tasks. Once this module is available in your PowerShell session, you can simply register and use it.
+
+For a detailed guide you should check out the [daemon developer guide](../developerguide/10-Custom-Daemons.md).

doc/service/02-Register-Daemons.md

@@ -0,0 +1,85 @@
+Register Background Service Checks
+===
+
+Once the PowerShell Framework is [installed as service](01-Install-Service.md) and you enabled the `Start-IcingaServiceCheckDaemon` daemon by [registering it](02-Register-Daemons.md), you are free to configure service checks which are frequently executed on a custom time period.
+
+Register Service Checks
+---
+
+Registering a service check will execute them frequently on a custom defined time. To do so you will have to register the check plugin you wish you collect metrics over time and add a execution time intervall including time indexes for which averages should be calculcated for.
+
+As example we want to frequently collect our `CPU load` values with an `check interval of 30 seconds` and calculate `averages for 1m, 3m, 5m, and 15m`.
+
+```powershell
+Register-IcingaServiceCheck -CheckCommand 'Invoke-IcingaCheckCPU' -Interval 30 -TimeIndexes 1, 3, 5, 15;
+```
+
+Once you registered a service check, you will have to restart the PowerShell service
+
+```powershell
+Restart-IcingaService 'icingapowershell';
+```
+
+As collected metrics are written to disk as well, a restart will not flush previous data but load it again. A quick service restart will not cause missing data points.
+
+Once the service check is executed from the background daemon, it will add additional output to your regular check execution from Icinga 2. If we execute our `Invoke-IcingaCheckCPU` now again, we will see additional metrics based on our configuration
+
+```powershell
+[OK] Check package "CPU Load"
+| 'core_0_15'=1.17%;;;0;100 'core_0_3'=1.12%;;;0;100 'core_0_5'=1.65%;;;0;100 'core_0_1'=1.36%;;;0;100 'core_0'=0.19%;;;0;100 'core_1_1'=0.86%;;;0;100 'core_1_15'=4.59%;;;0;100 'core_1_5'=5.28%;;;0;100 'core_1_3'=1.15%;;;0;100 'core_total_5'=5.2%;;;0;100 'core_total_15'=4.32%;;;0;100 'core_total_1'=3.41%;;;0;100 'core_total_3'=3.79%;;;0;100 'core_total'=1.85%;;;0;100
+```
+
+As you can see, each time index we added for the `TimeIndexes` argument is added as separat metric to our performance output. The calculation is done by all collected values over the execution period.
+
+List Service Checks
+---
+
+To list all registered service checks you can simply use
+
+```powershell
+Show-IcingaRegisteredServiceChecks;
+```
+
+This will print a detailed list of all checks and their configuration
+
+```powershell
+Service Id: 5275219864641021224811420224776891459631192206
+
+Name                           Value
+----                           -----
+CheckCommand                   Invoke-IcingaCheckCPU
+Interval                       30
+Arguments
+Id                             5275219864641021224811420224776891459631192206
+TimeIndexes                    {1, 3, 5, 15}
+```
+
+Modify Service Checks
+---
+
+To modify service checks you can simply use the `Register-IcingaServiceCheck` command again with the identical check command, but overwritting interval and time indexes for example
+
+```powershell
+Register-IcingaServiceCheck -CheckCommand 'Invoke-IcingaCheckCPU' -Interval 60 -TimeIndexes 1, 3, 5, 15, 20;
+```
+
+Once you modified a service check, you will have to restart the PowerShell service
+
+```powershell
+Restart-IcingaService 'icingapowershell';
+```
+
+Unregister Service Checks
+---
+
+If you wish to remove a service check from the daemon, you can simply unregister it with the `id` displayed on the `Show-IcingaRegisteredServiceChecks` Cmdlet
+
+```powershell
+Unregister-IcingaServiceCheck -ServiceId 5275219864641021224811420224776891459631192206;
+```
+
+Once you removed a service check, you will have to restart the PowerShell service
+
+```powershell
+Restart-IcingaService 'icingapowershell';
+```