mirror of
https://github.com/Icinga/icinga-powershell-framework.git
synced 2025-12-21 07:10:15 -05:00
Add first draft of new documentation
This commit is contained in:
Lord Hepipud
parent
613ab12067
commit
c5d5874917
14 changed files with 374 additions and 107 deletions
17
README.md
17
README.md
|
|
@ -1,14 +1,10 @@
|
|||
Icinga Module for Windows
|
||||
==============
|
||||
|
||||
## This Module is a Technical-Preview and should **NOT** be used actively in production!
|
||||
**This Module is a Technical-Preview and should **NOT** be used actively in production!**
|
||||
|
||||
This repository provides a PowerShell Module to fetch information and data of Windows Hosts, allowing a wide range of integrations
|
||||
|
||||
* Remote Execeution
|
||||
* Icinga Web 2 integration
|
||||
* Usage with the Icinga 2 Agent
|
||||
* ...
|
||||
The Icinga PowerShell Framework provides a wide range of configurarion and check possibilities to ensure an easy integration and full monitoring of windows environments.
|
||||
Each single chapter of this documentation will describe parts of the module and the possibilities.
|
||||
|
||||
Before you continue, please take a look on the [installation guide](doc/02-Installation.md)
|
||||
|
||||
|
|
@ -19,7 +15,12 @@ Please take a look on the following content to get to know the possibilities of
|
|||
|
||||
* [Introduction](doc/01-Introduction.md)
|
||||
* [Installation Guide](doc/02-Installation.md)
|
||||
* [Execution Policies](doc/03-ExecutionPolicy.md)
|
||||
* [Icinga Integration](doc/05-IcingaIntegration.md)
|
||||
|
||||
Developer Guide
|
||||
------------
|
||||
|
||||
If you wish to extend the Framework by yourself or write custom plugins for your environment, please have a look on the [Developer Guide](doc/04-DeveloperGuide.md) for detailed explanations of functions and code examples.
|
||||
|
||||
Contributing
|
||||
------------
|
||||
|
|
|
|||
|
|
@ -1,23 +1,13 @@
|
|||
Introduction
|
||||
==============
|
||||
===
|
||||
|
||||
This PowerShell Module will provide a basic framework to retreive data from Windows Hosts. The module will work with the current common Windows Versions, starting from Windows 7 / 2008 R2. Older versions might also work, are however not official supported.
|
||||
This PowerShell Framework will provide a collection of Cmdlets to entirely manage an Icinga 2 Agent setup and provide check plugins to fetch information from Windows hosts.
|
||||
|
||||
The module will execute local PowerShell scripts (modules) and return the result as formatted JSON. This result can later be parsed by any software to either do inventory or monitoring tasks.
|
||||
|
||||
### Architecture
|
||||
|
||||
|
||||
|
||||
The module provides three ways to fetch data:
|
||||
|
||||
* An active Rest-Api
|
||||
* A passive Checker component
|
||||
* PowerShell Cmdlets
|
||||
It will ensure all required Icinga configurations are handled and present and offer an easy way to extend the monitoring with custom plugins. The framework will provide a standardised set of Cmdlets, Tools and Providers to make daily work, integrations and testing available to everyone, regardless if you are a Developer, System Engineer or enthusiast.
|
||||
|
||||
The following requirements have to be fullfilled:
|
||||
|
||||
* Windows 7 / Windows 2008 R2 or later
|
||||
* PowerShell Version 3.x or higher
|
||||
* PowerShell Version 4.x or higher
|
||||
|
||||
If you are ready to get started, take a look on the [installation guide](02-Installation.md).
|
||||
|
|
@ -1,66 +1,23 @@
|
|||
Installing the Module
|
||||
=====================================
|
||||
===
|
||||
|
||||
Before you can use this module, you will require to install and configure it. Once done, you are ready to start.
|
||||
Installing the module is managed by differen ways, depending on the user environment including available possibitilies
|
||||
|
||||
Install the module
|
||||
--------------
|
||||
Instructions
|
||||
---
|
||||
|
||||
At first we need to obtain folders in which we can install the module. To get a list of available directories, you can use this command:S
|
||||
```powershell
|
||||
echo $env:PSModulePath
|
||||
```
|
||||
* Install the Module with the [Kickstart Script](installation\01-KickstartScript.md)
|
||||
* Install the module [manually](installation\02-ManualInstallation.md)
|
||||
|
||||
***We do recommend to use the Program Files folder (in case it's present) to install the module into, which will make the installation as service easier***
|
||||
Testing the installation
|
||||
---
|
||||
|
||||
To be able to use the module, you will require to have named the folder **exactly** as the .psm1 and .psd1 files inside the repository.
|
||||
|
||||
Example folder path:
|
||||
|
||||
```
|
||||
C:\Program Files\WindowsPowerShell\Modules\icinga-module-windows
|
||||
```
|
||||
|
||||
To validate if the module is installed properly, you can start a new PowerShell instance and type the following command
|
||||
Once the module is installed you can try if the installation was successfully by using the command
|
||||
|
||||
```powershell
|
||||
Get-Module -ListAvailable -Name icinga-module-windows
|
||||
Use-Icinga
|
||||
```
|
||||
|
||||
If you receive an output stating that the module is installed, you are fine to continue.
|
||||
This command will initialise the entire module and load all available Cmdlets.
|
||||
|
||||
Configure the module
|
||||
--------------
|
||||
|
||||
Once the module is installed, you will want to run the initial setup. Therefor you will simply have to type in the command
|
||||
|
||||
```powershell
|
||||
Install-Icinga
|
||||
```
|
||||
|
||||
This will create the base configuration of the module including the setup of directories and required files within the **PowerShell Module Directory**.
|
||||
|
||||
Once completed successfully, you are ready to get started with using it. This will include
|
||||
|
||||
* Using it localy with scripts
|
||||
* Integration into for the Icinga 2 Agent
|
||||
* Use it as Remote Execution target
|
||||
* Integrate it into Icinga Web 2
|
||||
|
||||
If you wish to provide a Rest-Api of this module, you can run this Module as daemon. It will then listen on the default port **5891**
|
||||
|
||||
```powershell
|
||||
Start-Icinga-Daemon
|
||||
```
|
||||
|
||||
Of course if you wish to actively send data to Icinga Web 2 for example, you can do so by running the Checker component
|
||||
|
||||
```powershell
|
||||
Start-Icinga-Checker
|
||||
```
|
||||
|
||||
For additional setup possibilities, please take a look on the following pages:
|
||||
|
||||
* [Use the module as Icinga Plugin Framework](12-Icinga2AgentExample.md)
|
||||
* [Install the module as Windows Service](10-InstallService.md)
|
||||
* [Integration into Icinga Web 2](11-IcingaWeb2Integration.md)
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -1,12 +0,0 @@
|
|||
Setting Execution Policies
|
||||
=====================================
|
||||
|
||||
In order to be able to run the module on certain Windows Hosts, it might be required to either update the execution policies and/or unblock the module script files.
|
||||
|
||||
The prefered way is to simply unblock the script files, allowing them to be executed on the system. This can be done by running a PowerShell instance as **Administrator** and enter the following command (we assume the module is installed at `C:\Program Files\WindowsPowershell\Modules\icinga-module-windows`. If not, please modify the command with the correct location)
|
||||
|
||||
```powershell
|
||||
Get-ChildItem -Path 'C:\Program Files\WindowsPowershell\Modules\icinga-module-windows' -Recurse | Unblock-File
|
||||
```
|
||||
|
||||
Once done, please try again if you are now able to run the module on your host. If you are still not able to run the module and/or its scripts, please have a look on the Microsoft documentation for the [Set-Execution-Policy](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-6) Cmdlet to modify the Execution Policy for running PowerShell modules on your host, matching your internal guidelines.
|
||||
40
doc/03-WebIntegration.md
Normal file
40
doc/03-WebIntegration.md
Normal file
|
|
@ -0,0 +1,40 @@
|
|||
Web Integration (Deprecated)
|
||||
===
|
||||
|
||||
Before you can use this module, you will require to install and configure it. Once done, you are ready to start.
|
||||
|
||||
Configure the module
|
||||
---
|
||||
|
||||
Once the module is installed, you will want to run the initial setup. Therefor you will simply have to type in the command
|
||||
|
||||
```powershell
|
||||
Install-Icinga
|
||||
```
|
||||
|
||||
This will create the base configuration of the module including the setup of directories and required files within the **PowerShell Module Directory**.
|
||||
|
||||
Once completed successfully, you are ready to get started with using it. This will include
|
||||
|
||||
* Using it localy with scripts
|
||||
* Integration into for the Icinga 2 Agent
|
||||
* Use it as Remote Execution target
|
||||
* Integrate it into Icinga Web 2
|
||||
|
||||
If you wish to provide a Rest-Api of this module, you can run this Module as daemon. It will then listen on the default port **5891**
|
||||
|
||||
```powershell
|
||||
Start-Icinga-Daemon
|
||||
```
|
||||
|
||||
Of course if you wish to actively send data to Icinga Web 2 for example, you can do so by running the Checker component
|
||||
|
||||
```powershell
|
||||
Start-Icinga-Checker
|
||||
```
|
||||
|
||||
For additional setup possibilities, please take a look on the following pages:
|
||||
|
||||
* [Use the module as Icinga Plugin Framework](12-Icinga2AgentExample.md)
|
||||
* [Install the module as Windows Service](10-InstallService.md)
|
||||
* [Integration into Icinga Web 2](11-IcingaWeb2Integration.md)
|
||||
13
doc/04-DeveloperGuide.md
Normal file
13
doc/04-DeveloperGuide.md
Normal file
|
|
@ -0,0 +1,13 @@
|
|||
Developer Guide for Custom Plugins
|
||||
===
|
||||
|
||||
This PowerShell Framework provides a wide collection of Cmdlets and Tools to allow an easy extension and developing of custom Check Plugins for Icinga.
|
||||
|
||||
To ensure the overall functionality of the framework is supported by your custom Plugins, we would advice you to cover all topics of this Developer guide.
|
||||
|
||||
Functions
|
||||
---
|
||||
|
||||
A detailed overview of functions can be found below
|
||||
|
||||
* [New-IcingaCheck](developerguide/01-NewIcingaCheck.md)
|
||||
20
doc/05-IcingaIntegration.md
Normal file
20
doc/05-IcingaIntegration.md
Normal file
|
|
@ -0,0 +1,20 @@
|
|||
Icinga Integration
|
||||
===
|
||||
|
||||
Once you followed the [Installation Guide](02-Installation.md) you are ready to start the integration into Icinga 2. This will allow you to configure your Check-Commands and start using configuring service-templates and services.
|
||||
|
||||
Before you are getting started, be aware that you will always have to use
|
||||
|
||||
```powershell
|
||||
Use-Icinga
|
||||
```
|
||||
|
||||
before you are executing framework related Cmdlets and functions. Otherwise you might run into errors.
|
||||
|
||||
Configuring Check-Commands
|
||||
---
|
||||
|
||||
To get started, there are two ways for getting all Check-Commands configured.
|
||||
|
||||
* [Automated coniguration](icingaintegration/01-DirectorBaskets.md) with Baskets
|
||||
* [Manual configuration](icingaintegration/02-Icinga2AgentExample.md) of Check-Commands
|
||||
|
|
@ -1,15 +1,15 @@
|
|||
Run the PowerShell Module as Windows Service
|
||||
=====================================
|
||||
===
|
||||
|
||||
Requirements
|
||||
--------------
|
||||
---
|
||||
|
||||
As PowerShell Scripts / Modules can not be installed directly as Windows Service, we will require a little assistance here.
|
||||
|
||||
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/LordHepipud/icinga-windows-service).
|
||||
|
||||
Install the Service
|
||||
--------------
|
||||
---
|
||||
|
||||
At first you will require the Service Binary from the [Icinga Windows Service GitHub Repository](https://github.com/LordHepipud/icinga-windows-service) and copy the binary locally to your system. A recommended path would be your Program Files / Program Files (x86) directory.
|
||||
|
||||
|
|
@ -17,33 +17,33 @@ Any other custom location is fully supported, has to be however accessable from
|
|||
|
||||
Once you have found a location, the PowerShell Module will assist you with setting up the service itself. In this documentation we will assume the path you have chosen to copy the binary to is
|
||||
|
||||
```
|
||||
C:\Program Files\Icinga Windows Service
|
||||
```powershell
|
||||
C:\Program Files\Icinga-Framework-Service
|
||||
```
|
||||
|
||||
and the binary name is
|
||||
|
||||
```
|
||||
icinga-service.exe
|
||||
```powershell
|
||||
icinga-service.exe
|
||||
```
|
||||
|
||||
Now lets install the service with the help of the PowerShell Module:
|
||||
|
||||
```powershell
|
||||
Install-Icinga-Service -IcingaServicePath 'C:\Program Files\Icinga Windows Service\icinga-service.exe'
|
||||
Install-IcingaFrameworkService -ServicePath 'C:\Program Files\Icinga-Framework-Service\icinga-service.exe'
|
||||
```
|
||||
|
||||
You can validate if the service has been installed properly by using the Get Service Cmdlet:
|
||||
|
||||
```
|
||||
Get-Icinga-Service
|
||||
```powershell
|
||||
Get-IcingaFrameworkService
|
||||
```
|
||||
|
||||
Of course there are more Cmdlets available, making the management of this Icinga Service alot easier, which should be self explaining:
|
||||
|
||||
* Start-Icinga-Service
|
||||
* Stop-Icinga-Service
|
||||
* Restart-Icinga-Service
|
||||
* Uninstall-Icinga-Service
|
||||
* Start-IcingaFrameworkService
|
||||
* Stop-IcingaFrameworkService
|
||||
* Restart-IcingaFrameworkService
|
||||
* Uninstall-IcingaFrameworkService
|
||||
|
||||
**Note:** If you run the PowerShell Module as service, both the Daemon and Checker component will be started. To prevent external access to the Daemon, you should ensure to block port **5891** on this host.
|
||||
Each enabled background daemon component is afterwards being started and executed.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
Integrating Icinga Web 2
|
||||
Integrating Icinga Web 2 (Deprecated)
|
||||
=====================================
|
||||
|
||||
The PowerShell Module provides the possibility to directly (or indirectly over Proxies) connect to an Icinga Web 2 Api to send informations there.
|
||||
|
|
|
|||
140
doc/developerguide/01-NewIcingaCheck.md
Normal file
140
doc/developerguide/01-NewIcingaCheck.md
Normal file
|
|
@ -0,0 +1,140 @@
|
|||
# Developer Guide: New-IcingaCheck
|
||||
|
||||
Below you will find a list of functions and detailed descriptions including use cases for Cmdlets and features the PowerShell Framework provides.
|
||||
|
||||
| Type | Return Value | Description |
|
||||
| --- | --- | --- |
|
||||
| Cmdlet | PowerShell Object | Check Object containing values and handling warning / error states |
|
||||
|
||||
The `IcingaCheck` is the basic start point for determining on how a certain value is performing. Checks will provide a bunch of internal commands within the PowerShell Object to analyse a value and get the Icinga result `Ok`, `Warning`, `Critical` including performance metrics.
|
||||
|
||||
Checks are always used wihtin Check Plugins to have a standardised method for properly handling the input.
|
||||
|
||||
It will be used like in this example:
|
||||
|
||||
```powershell
|
||||
$IcingaCheck = New-IcingaCheck -Name 'My Check' -Value 25 -Unit '%';
|
||||
```
|
||||
|
||||
You will have to provide a `Name` for each check which **must** be unique within each Check Plugin. This will make it easier to differentiate between checks for results. The `Value` is mandatory as this will be the base for each single check to fetch the actual status.
|
||||
|
||||
For performance metrics you can provide a `Unit` to ensure your graphing is displaying values as the should be
|
||||
|
||||
## Arguments
|
||||
|
||||
| Argument | Input | Mandatory | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| Name | String | * | The unique name of each check within a plugin. Will be display in the check output. |
|
||||
| Value | Object | * | The value all comparison is done with. In general this should be a `Numeric` or `String` value |
|
||||
| Unit | Units | | Specify the unit for a value to display graph properly |
|
||||
| Minimum | String | | The minimum value which is displayed on your graphs |
|
||||
| Maximum | String | | The maximum value which is displayed on your graphs |
|
||||
| ObjectExists | Bool | | If you are using values coming from objects, like Services, you can use this argument to determin if the object itself exist or not. In case it doesn't, you will receive a proper output on the check result |
|
||||
| Translation | Hashtable | | In case you want to map values to certain descriptions, you can place a hashtable at this argument which will then map the value to the description on the check result. For example this would apply to service running states |
|
||||
| NoPerfData | Switch | | Disables Performance Data output for this check object |
|
||||
|
||||
## Units
|
||||
|
||||
| Unit | Name | Description |
|
||||
| --- | --- | --- |
|
||||
| % | Percentage | The input value is a percentual value |
|
||||
| s | Seconds | The input is indicated as time seconds |
|
||||
| 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 |
|
||||
| TB | Terabytes | The input is indicated as quantity in terabytes |
|
||||
| c | Counter | A continues counter increasing values over time |
|
||||
|
||||
## Object Functions
|
||||
|
||||
The `New-IcingaCheck` Cmdlet will return a custom PowerShell object which provides a bunch of functions to easier manage the handling of the output.
|
||||
|
||||
Please note that most of the listed functions below will return itself as object, which means you will have to drop the content with `| Out-Null` after calling them.
|
||||
|
||||
### Wrong
|
||||
|
||||
```powershell
|
||||
$IcingaCheck.WarnOutOfRange(10)
|
||||
```
|
||||
|
||||
### Correct
|
||||
|
||||
```powershell
|
||||
$IcingaCheck.WarnOutOfRange(10) | Out-Null
|
||||
```
|
||||
|
||||
### Nested functions
|
||||
|
||||
An example for a nested function call could be this
|
||||
|
||||
```powershell
|
||||
$IcingaCheck.WarnOutOfRange(10).CritOutOfRange(20) | Out-Null
|
||||
```
|
||||
|
||||
### Functions
|
||||
|
||||
For most parts it is recommended to use the `OutOfRange` functions for `warning` and `critical` checks as the user is able to dynamicly set the range with the arguments of the plugins. For string values the `Like` and `Match` functions should be used.
|
||||
|
||||
#### Recommended functions
|
||||
|
||||
| Function | Parameters | Description | Example |
|
||||
| --- | --- | --- | --- |
|
||||
| WarnOutOfRange | Warning | This will make use of the Icinga Threshhold handling, like `10`, `~:10`, `@10:20` and properly return the correct ok / warning state of the plugin | $IcingaCheck.WarnOutOfRange(10) | Out-Null |
|
||||
| CritOutOfRange | Critial | This will make use of the Icinga Threshhold handling, like `10`, `~:10`, `@10:20` and properly return the correct ok / critical state of the plugin | $IcingaCheck.CritOutOfRange(10) | Out-Null |
|
||||
| WarnIfLike | Warning | Will return warning in case the input is `like` the value | $IcingaCheck.WarnIfLike('\*running\*') |
|
||||
| WarnIfNotLike | Warning | Will return warning in case the input is `not like` the value | $IcingaCheck.WarnIfNotLike('\*running\*') |
|
||||
| WarnIfMatch | Warning | Will return warning in case the input is `matching` the value | $IcingaCheck.WarnIfMatch('running') |
|
||||
| WarnIfNotMatch | Warning | Will return warning in case the input is `not matching` the value | $IcingaCheck.WarnIfNotMatch('running') |
|
||||
| CritIfLike | Critial | Will return critical in case the input is `like` the value | $IcingaCheck.CritIfLike('\*running\*') |
|
||||
| CritIfNotLike | Critial | Will return critical in case the input is `not like` the value | $IcingaCheck.CritIfNotLike('\*running\*') |
|
||||
| CritIfMatch | Critial | Will return critical in case the input is `matching` the value | $IcingaCheck.CritIfMatch('running') |
|
||||
| CritIfNotMatch | Critial | Will return critical in case the input is `not matching` the value | $IcingaCheck.CritIfNotMatch('running') |
|
||||
|
||||
#### All other functions
|
||||
|
||||
| Function | Parameters | Description | Example |
|
||||
| --- | --- | --- | --- |
|
||||
| WarnIfBetweenAndEqual | Min, Max | Will return warning in case the input is `between or equal` the `min` and `max` value | $IcingaCheck.WarnIfBetweenAndEqual(10, 20) |
|
||||
| WarnIfBetween | Min, Max | Will return warning in case the input is between the `min` and `max` value | $IcingaCheck.WarnIfBetween(10, 20) |
|
||||
| WarnIfLowerThan | Warning | Will return warning in case the input is `lower` than the value | $IcingaCheck.WarnIfLowerThan(10) |
|
||||
| WarnIfLowerEqualThan | Warning | Will return warning in case the input is `lower or equal` than the value | $IcingaCheck.WarnIfLowerEqualThan(10) |
|
||||
| WarnIfGreaterThan | Warning | Will return warning in case the input is `greater` than the value | $IcingaCheck.WarnIfGreaterThan(10) |
|
||||
| WarnIfGreaterEqualThan | Warning | Will return warning in case the input is `greater or equal` than the value | $IcingaCheck.WarnIfGreaterEqualThan(10) |
|
||||
| CritIfBetweenAndEqual | Min, Max | Will return critical in case the input is `between or equal` the `min` and `max` value | $IcingaCheck.CritIfBetweenAndEqual(10, 20) |
|
||||
| CritIfBetween | Min, Max | Will return critical in case the input is between the `min` and `max` value | $IcingaCheck.CritIfBetween(10, 20) |
|
||||
| CritIfLowerThan | Critial | Will return critical in case the input is `lower` than the value | $IcingaCheck.CritIfLowerThan(10) |
|
||||
| CritIfLowerEqualThan | Critial | Will return critical in case the input is `lower or equal` than the value | $IcingaCheck.CritIfLowerEqualThan(10) |
|
||||
| CritIfGreaterThan | Critial | Will return critical in case the input is `greater` than the value | $IcingaCheck.CritIfGreaterThan(10) |
|
||||
| CritIfGreaterEqualThan | Critial | Will return critical in case the input is `greater or equal` than the value | $IcingaCheck.CritIfGreaterEqualThan(10) |
|
||||
|
||||
### Examples
|
||||
|
||||
#### Example 1
|
||||
|
||||
Simple check item which will return `critical` as the value is `37` and we want throw `warning` above `20` and `critical` above `35`
|
||||
|
||||
```powershell
|
||||
$IcingaCheck = New-IcingaCheck -Name 'My Check' -Value 37 -Unit '%';
|
||||
$IcingaCheck.WarnOutOfRange(20).CritOutOfRange(35) | Out-Null;
|
||||
```
|
||||
|
||||
#### Example 2
|
||||
|
||||
Check item with `ObjectExists` argument including `Translation`. As the input status `4` is an integer, we will convert the status to the string value `Running` and use the `Translation` argument to properly print the output in human readable strings
|
||||
|
||||
```powershell
|
||||
$Service = Get-IcingaServices -Service 'icinga2';
|
||||
$ConvertedStatus = ConvertTo-ServiceStatusCode -Status 4;
|
||||
$StatusRaw = $Service.Values.configuration.Status.raw;
|
||||
|
||||
$IcingaCheck = New-IcingaCheck -Name 'Icinga 2 Service' -Value $StatusRaw -ObjectExists $Service -Translation $ProviderEnums.ServiceStatusName;
|
||||
$IcingaCheck.CritIfNotMatch($ConvertedStatus) | Out-Null;
|
||||
```
|
||||
|
||||
Output after parsed into `New-IcingaCheckResult`
|
||||
|
||||
```text
|
||||
[CRITICAL]: Icinga 2 Service Stopped is not matching Running
|
||||
```
|
||||
44
doc/icingaintegration/01-DirectorBaskets.md
Normal file
44
doc/icingaintegration/01-DirectorBaskets.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
Icinga Basket Generator
|
||||
===
|
||||
|
||||
To make the integration as easy as possible, the Framework is shipping with an Icinga Director Basket configuration generator. Each Check-Plugin available within the Framework is able to auto-generate a basket config which can later be imported into the Icinga Director
|
||||
|
||||
Generating Baskets
|
||||
---
|
||||
|
||||
To automaticly generate the Basket configuration, open a PowerShell terminal and type in
|
||||
|
||||
```powershell
|
||||
Use-Icinga
|
||||
```
|
||||
|
||||
to load the framework Cmdlets.
|
||||
|
||||
Afterwards use the command
|
||||
|
||||
```powershell
|
||||
Get-IcingaCheckCommandConfig
|
||||
```
|
||||
|
||||
to automatically generate the configuration for all Check-Commands.
|
||||
|
||||
If you wish to specify specific commands only, you can filter them as well:
|
||||
|
||||
```powershell
|
||||
Get-IcingaCheckCommandConfig -CheckName Invoke-IcingaCheckBiosSerial, Invoke-IcingaCheckCPU
|
||||
```
|
||||
|
||||
Last but not least you can output the JSON-Basket directly into a file. To do this, simply use the `OutFile` argument. You only require to specify a directory here, as the file including a timestamp is generated by the Cmdlet itself
|
||||
|
||||
```powershell
|
||||
Get-IcingaCheckCommandConfig -OutFile 'C:\Users\myuser\Documents\
|
||||
```
|
||||
|
||||
Once the file is exported, you can navigate to your Icinga Director Basket menu and import the generated file. Afterwards all specified Check-Commands are available and ready to use
|
||||
|
||||
Developer Note
|
||||
---
|
||||
|
||||
The generated Basket configuration will benefit from a detailed documentation of the module and each single argument. Descriptions for arguments are parsed into the Director description field, informing users of what the argument actually does. Furthermore arguments are automaticly mapped to certain object types. A `switch` argument for example will always be rendered with a `yes/no` drop-down-field, while arguments with a fixed set of input types like `Running`, `Stopped`, and so on for services is rendered within a fixed custom list.
|
||||
|
||||
This will increase the entire usability of the module and prevent you from having to document the a plugin multiple times.
|
||||
30
doc/installation/01-KickstartScript.md
Normal file
30
doc/installation/01-KickstartScript.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
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/LordHepipud/icinga-framework-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:
|
||||
|
||||
Getting Started
|
||||
---
|
||||
|
||||
```powershell
|
||||
[Net.ServicePointManager]::SecurityProtocol = "tls12, tls11";
|
||||
$ProgressPreference = "SilentlyContinue";
|
||||
|
||||
$Script = (Invoke-WebRequest -UseBasicParsing -Uri 'https://raw.githubusercontent.com/LordHepipud/icinga-framework-kickstart/master/script/icinga-framework-kickstart.ps1').Content;
|
||||
|
||||
Invoke-Command -ScriptBlock ([Scriptblock]::Create($Script));
|
||||
```
|
||||
|
||||
What this block will do is to download the PowerShell Script from the repository, add it into a ScriptBlock to allow execution and finally execute it.
|
||||
|
||||
The ServicePointManager part will ensure communication is possible to GitHub for example, as by default PowerShell will be unable to open a secure connection otherwise.
|
||||
Last but not least we will set the progress preference to `SilentlyContinue`, ensuring the PowerShell progress bar will not slow down our installation.
|
||||
|
||||
Next Steps
|
||||
---
|
||||
|
||||
Once the above step is completed, simply follow the instructions and answer the questions the wizard will ask you. Once the framework is installed, the wizard will ask you if you wish to continue with the Agent installation wizard.
|
||||
|
||||
The entire purpose is to offer a fluent and seamless installation experience.
|
||||
44
doc/installation/02-ManualInstallation.md
Normal file
44
doc/installation/02-ManualInstallation.md
Normal file
|
|
@ -0,0 +1,44 @@
|
|||
Install the framework manually
|
||||
===
|
||||
|
||||
To install the module manually we will at first fetch information on where we can actually install the module into. PowerShell provides some default directories, which can however also extended manually.
|
||||
|
||||
Getting Started
|
||||
---
|
||||
|
||||
To do this, we can run the following command within PowerShell
|
||||
|
||||
```powershell
|
||||
echo $env:PSModulePath
|
||||
```
|
||||
|
||||
***We do recommend to use the Program Files folder (in case it's present) to install the module into, which will make the installation as service easier***
|
||||
|
||||
To be able to use the module, you will require to have named the folder **exactly** as the .psm1 and .psd1 files inside the repository.
|
||||
|
||||
Example folder path:
|
||||
|
||||
```powershell
|
||||
C:\Program Files\WindowsPowerShell\Modules\icinga-module-windows
|
||||
```
|
||||
|
||||
To validate if the module is installed properly, you can start a **new** PowerShell instance and type the following command
|
||||
|
||||
```powershell
|
||||
Get-Module -ListAvailable -Name icinga-module-windows
|
||||
```
|
||||
|
||||
If you receive an output stating that the module is installed, you are fine to continue.
|
||||
|
||||
Execution Policies and File Blocking
|
||||
---
|
||||
|
||||
In order to be able to run the module on certain Windows Hosts, it might be required to either update the execution policies and/or unblock the module script files.
|
||||
|
||||
The prefered way is to simply unblock the script files, allowing them to be executed on the system. This can be done by running a PowerShell instance as **Administrator** and enter the following command (we assume the module is installed at `C:\Program Files\WindowsPowershell\Modules\icinga-module-windows`. If not, please modify the command with the correct location)
|
||||
|
||||
```powershell
|
||||
Get-ChildItem -Path 'C:\Program Files\WindowsPowershell\Modules\icinga-module-windows' -Recurse | Unblock-File
|
||||
```
|
||||
|
||||
Once done, please try again if you are now able to run the module on your host. If you are still not able to run the module and/or its scripts, please have a look on the Microsoft documentation for the [Set-Execution-Policy](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-6) Cmdlet to modify the Execution Policy for running PowerShell modules on your host, matching your internal guidelines.
|
||||
Loading…
Reference in a new issue