mirror of
https://github.com/Icinga/icinga-powershell-framework.git
synced 2025-12-24 08:39:43 -05:00
Merge pull request #357 from Icinga:doc/icinga_for_windows_v1.6.0
Docs: Updates documentation for v1.6.0
This commit is contained in:
Lord Hepipud
GitHub
commit
2833e579f4
70 changed files with 1329 additions and 1359 deletions
20
README.md
20
README.md
|
|
@ -4,25 +4,27 @@ Icinga PowerShell Framework
|
|||
The Icinga PowerShell Framework provides a wide range of configuration 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 at the [Installation Guide](doc/02-Installation.md)
|
||||
Before you continue, please take a look at the [Installation Guide](doc/110-Installation/01-Getting-Started.md)
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
Please take a look at the following content to get to know the possibilities of the module including examples on how to use it.
|
||||
|
||||
* [Introduction](doc/01-Introduction.md)
|
||||
* [Installation Guide](doc/02-Installation.md)
|
||||
* [Icinga Integration](doc/05-Icinga-Integration.md)
|
||||
* [Framework Usage Examples](doc/06-Framework-Usage.md)
|
||||
* [Icinga PowerShell Framework as Service](doc/service/01-Install-Service.md)
|
||||
* [Knowledge Base](doc/10-Knowledge-Base.md)
|
||||
* [Changelog](doc/31-Changelog.md)
|
||||
* [Introduction](doc/000-Introduction.md)
|
||||
* [Installation Guide](doc/110-Installation/01-Getting-Started.md)
|
||||
* [Repository Management](doc/120-Repository-Manager)
|
||||
* [JEA](doc/130-JEA)
|
||||
* [Icinga Integration](doc/200-Icinga-Integration/)
|
||||
* [Framework Usage Examples](doc/frameworkusage)
|
||||
* [Icinga PowerShell Framework as Service](doc/110-Installation/05-Background-Daemons.md)
|
||||
* [Knowledge Base](doc/300-Knowledge-Base.md)
|
||||
* [Changelog](doc/100-General/10-Changelog.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-Developer-Guide.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/900-Developer-Guide) for detailed explanations of functions and code examples.
|
||||
|
||||
Contributing
|
||||
------------
|
||||
|
|
|
|||
|
|
@ -67,16 +67,16 @@ Below you will find a list of currently available modules published by the Icing
|
|||
|
||||
| Icinga PowerShell Kickstart | Icinga PowerShell Framework | Icinga PowerShell Plugins |
|
||||
| --- | --- | --- |
|
||||
| [](https://icinga.com/docs/windows/latest/kickstart/doc/01-Introduction/) | [](https://icinga.com/docs/windows/latest/doc/02-Installation/) | [](https://icinga.com/docs/windows/latest/plugins/doc/01-Introduction/) |
|
||||
| [](https://github.com/Icinga/icinga-powershell-kickstart) | [](https://icinga.com/docs/windows/latest/doc/02-Installation/) | [](https://icinga.com/docs/windows/latest/plugins/doc/01-Introduction/) |
|
||||
|
||||
### Extensions
|
||||
|
||||
| Icinga PowerShell REST-Api | Icinga PowerShell Inventory |
|
||||
| --- | --- |
|
||||
| [](https://icinga.com/docs/windows/latest/restapi/doc/01-Introduction/) | [](https://icinga.com/docs/windows/latest/inventory/doc/01-Introduction/) |
|
||||
| Icinga PowerShell REST-Api | Icinga PowerShell Inventory | Icinga PowerShell Api-Checks |
|
||||
| --- | --- | --- |
|
||||
| [](https://icinga.com/docs/windows/latest/restapi/doc/01-Introduction/) | [](https://icinga.com/docs/windows/latest/inventory/doc/01-Introduction/) | [](https://icinga.com/docs/icinga-for-windows/latest/apichecks/doc/01-Introduction/) |
|
||||
|
||||
### Additional Plugins
|
||||
|
||||
| Icinga PowerShell Hyper-V (soon)| Icinga PowerShell MSSQL |
|
||||
| --- | --- |
|
||||
|  | [](https://icinga.com/docs/windows/latest/mssql/doc/01-Introduction/) |
|
||||
| Icinga PowerShell Hyper-V | Icinga PowerShell MSSQL | Icinga PowerShell Cluster |
|
||||
| --- | --- | --- |
|
||||
| [](https://icinga.com/docs/icinga-for-windows/latest/hyperv/doc/01-Introduction/) | [](https://icinga.com/docs/windows/latest/mssql/doc/01-Introduction/) | [](https://icinga.com/docs/icinga-for-windows/latest/cluster/doc/01-Introduction/) |
|
||||
|
|
@ -1,40 +0,0 @@
|
|||
Installing the Icinga PowerShell Framework
|
||||
===
|
||||
|
||||
Installing the Icinga PowerShell Framework is managed by different ways, depending on the user environment including available possibilities.
|
||||
|
||||
Get the latest Version from [GitHub](https://github.com/Icinga/icinga-powershell-framework/releases/latest) or [PowerShell Gallery](https://www.powershellgallery.com/packages/icinga-powershell-framework).
|
||||
|
||||
Instructions
|
||||
---
|
||||
|
||||
* Install the Icinga PowerShell Framework with the [Kickstart Script](installation/01-Kickstart-Script.md)
|
||||
* Install the Icinga PowerShell Framework [manually](installation/02-Manual-Installation.md)
|
||||
* Install the Icinga PowerShell Framework with [PowerShell Gallery](installation/03-PowerShell-Gallery-Installation.md)
|
||||
|
||||
Testing the installation
|
||||
---
|
||||
|
||||
Once the Icinga PowerShell Framework is installed you can try if the installation was successfully by using the command
|
||||
|
||||
```powershell
|
||||
Use-Icinga
|
||||
```
|
||||
|
||||
This command will initialize the entire Icinga PowerShell Framework and load all available Cmdlets.
|
||||
|
||||
*Note:* Starting with Icinga PowerShell Framework `1.2.0` you can simply use `icinga` to open a Icinga PowerShell Framework shell.
|
||||
|
||||
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 initialize the framework.
|
||||
|
||||
Icinga Agent installation wizard
|
||||
---
|
||||
|
||||
Once the entire Framework is installed and the module is runnable, you can start the Icinga Agent installation wizard. Please follow the [Icinga Agent Wizard](installation/04-Icinga-Agent-Wizard.md) guide for examples and usage.
|
||||
|
||||
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)
|
||||
|
|
@ -1,35 +0,0 @@
|
|||
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-New-IcingaCheck.md)
|
||||
* [New-IcingaCheckPackage](developerguide/02-New-IcingaCheckPackage.md)
|
||||
* [New-IcingaCheckResult](developerguide/03-New-IcingaCheckResult.md)
|
||||
|
||||
General Handling
|
||||
---
|
||||
|
||||
There are some general guidelines, functions and toolsets available making the development in general easier. Here you can find a list of topics
|
||||
|
||||
* [Cim-Instance/Wmi-Object fetching](developerguide/50-Fetching-Cim_and_Wmi_Data.md)
|
||||
* [Working with Performance Counters](developerguide/51-Working-with-Performance-Counters.md)
|
||||
* [Testing of Commands](developerguide/52-Testing-of-Commands.md)
|
||||
|
||||
Example Usage
|
||||
---
|
||||
|
||||
To get started easier you can find detailed examples for developing modules/integrations/best practices in the following categories:
|
||||
|
||||
* [Custom Daemons](developerguide/10-Custom-Daemons.md)
|
||||
* [Custom Plugins](developerguide/11-Custom-Plugins.md)
|
||||
* [Custom API-Endpoints](developerguide/12-Custom-API-Endpoints.md)
|
||||
* [Using Console Outputs](developerguide/20-Using-Console-Outputs.md)
|
||||
* [Using EventLog Output](developerguide/21-Using-EventLog-Outputs.md)
|
||||
|
|
@ -1,23 +0,0 @@
|
|||
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 them inside service templates and services.
|
||||
|
||||
Before you get started, be aware that you always have to use
|
||||
|
||||
```powershell
|
||||
Use-Icinga
|
||||
```
|
||||
|
||||
before you can execute framework related Cmdlets and functions. Otherwise you might run into errors.
|
||||
|
||||
Configuring Check-Commands
|
||||
---
|
||||
|
||||
To get started, there are two ways to configure check command objects:
|
||||
|
||||
* [Automated Icinga Director configuration](icingaintegration/01-Director-Baskets.md) with Baskets
|
||||
* [Automated Icinga 2 configuration](icingaintegration/04-Icinga-Config.md) with plain Icinga config
|
||||
* [Manual configuration](icingaintegration/02-Manual-Integration.md) of check commands
|
||||
* [Using PowerShell Arrays in Icinga](icingaintegration/03-PowerShell-Arrays.md)
|
||||
* [Windows Terminal Integration](icingaintegration/50-Windows-Terminal.md)
|
||||
|
|
@ -1,28 +0,0 @@
|
|||
# Framework Usage
|
||||
|
||||
The Icinga PowerShell Framework ships with a bunch of Cmdlets for monitoring, measurement, analysis and Icinga Agent management. Below we have listed a collection of content to explain the general usage of certain Cmdlets and components.
|
||||
|
||||
## Framework Management
|
||||
|
||||
* [Automated Framework and Component deployment](frameworkusage/01-Automated-Framework-and-Component-Deployment.md)
|
||||
* [Enable Proxy Server](frameworkusage/02-Enable-Proxy-Server.md)
|
||||
* [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
|
||||
|
||||
* [Manage Icinga Agent Features](frameworkusage/30-Manage-Icinga-Agent-Features.md)
|
||||
* [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)
|
||||
* [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)
|
||||
|
||||
## Experimental
|
||||
|
||||
* [Forward checks to internal API](experimental/01-Forward-checks-to-internal-API.md)
|
||||
* [Management Console](experimental/02-Management-Console.md)
|
||||
|
|
@ -1,17 +0,0 @@
|
|||
# Repository Manager
|
||||
|
||||
Starting with Icinga for Windows v1.6.0, we provide a full feature-set to manage repositories for all components which are developed for Icinga for Windows. This includes all resources like framework, plugins the service binary and the Icinga Agent itself.
|
||||
|
||||
Below you will find a detailed description for core areas of the repository management, explaining on how to work with repositories.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
* [Add existing repositories](repositorymanager/01-Add-Existing-Repositories.md)
|
||||
* [Sync repositories](repositorymanager/02-Sync-Repositories.md)
|
||||
* [Enable/Disable/Remove Repositories](repositorymanager/03-Enable-Disable-Remove-Repositories.md)
|
||||
* [Search Repository for Components](repositorymanager/04-Search-Repository-For-Components.md)
|
||||
* [Lock/Unlock Components](repositorymanager/05-Lock-Unlock-Components.md)
|
||||
* [Install Components](repositorymanager/06-Install-Components.md)
|
||||
* [Create Own Repositories](repositorymanager/07-Create-Own-Repositories.md)
|
||||
|
||||
## Example Configurations
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
**The latest release announcements are available on [https://icinga.com/blog/](https://icinga.com/blog/).**
|
||||
|
||||
Please read the [upgrading](https://icinga.com/docs/windows/latest/doc/30-upgrading-framework)
|
||||
Please read the [upgrading](01-Upgrading.md)
|
||||
documentation before upgrading to a new release.
|
||||
|
||||
Released closed milestones can be found on [GitHub](https://github.com/Icinga/icinga-powershell-framework/milestones?state=closed).
|
||||
|
|
@ -75,7 +75,7 @@ You can read more on this on the [Knowledge Base Entry](https://icinga.com/docs/
|
|||
### Enhancements
|
||||
|
||||
* [#228](https://github.com/Icinga/icinga-powershell-framework/issues/228) Adds feature to suppress any kind of console output except for plugin output and performance data
|
||||
* [#229](https://github.com/Icinga/icinga-powershell-framework/pull/229) CustomFields defined as `SecureString` are now set to `hidden` within the Icinga Director configuration basket - please read the [upgrading docs](30-upgrading-framework.md) carefully
|
||||
* [#229](https://github.com/Icinga/icinga-powershell-framework/pull/229) CustomFields defined as `SecureString` are now set to `hidden` within the Icinga Director configuration basket - please read the [upgrading docs](01-Upgrading.md) carefully
|
||||
* [#234](https://github.com/Icinga/icinga-powershell-framework/pull/234) Adds support to allow custom exception lists for Icinga Exceptions, making it easier for different modules to ship their own exception messages
|
||||
* [#235](https://github.com/Icinga/icinga-powershell-framework/pull/235) Adds new Cmdlet `Show-IcingaEventLogAnalysis` to get a better overview on how many log entries are present within the EventLog based on hour, minute and day average/maximum for allowing a more dynamic configuration for `Invoke-IcingaCheckEventLog`
|
||||
* [#236](https://github.com/Icinga/icinga-powershell-framework/pull/236) Adds feature which stops the Icinga Agent before upgrading the Icinga PowerShell Framework and starting it again afterwards (in case it was running), to resolve some possible file lock issues
|
||||
|
|
@ -120,7 +120,7 @@ You can read more on this on the [Knowledge Base Entry](https://icinga.com/docs/
|
|||
|
||||
### Breaking Changes
|
||||
|
||||
There are changes made to the pre-compiled configuration files and `Get-IcingaCheckCommandConfig.` Please have a look on the [upgrading](30-upgrading-framework.md) before applying the new configuration files.
|
||||
There are changes made to the pre-compiled configuration files and `Get-IcingaCheckCommandConfig.` Please have a look on the [upgrading](01-Upgrading.md) before applying the new configuration files.
|
||||
|
||||
### Enhancements
|
||||
|
||||
|
|
@ -225,7 +225,7 @@ You can read more on this on the [Knowledge Base Entry](https://icinga.com/docs/
|
|||
|
||||
Check Command configuration generated by Icinga for Windows 1.2.0 require Icinga for Windows 1.2.0 or later deployed on all systems, otherwise you will run into issues with an unknown command `Exit-IcingaPluginNotInstalled` error.
|
||||
|
||||
* To properly catch errors on check execution you will have to import check commands as Director basket again by using `Get-IcingaCheckCommandConfig`. Further details can be found in the [upgrading docs](30-upgrading-framework.md)
|
||||
* To properly catch errors on check execution you will have to import check commands as Director basket again by using `Get-IcingaCheckCommandConfig`. Further details can be found in the [upgrading docs](01-Upgrading.md)
|
||||
|
||||
### Notes
|
||||
|
||||
|
|
@ -236,7 +236,7 @@ Check Command configuration generated by Icinga for Windows 1.2.0 require Icinga
|
|||
|
||||
### Enhancements
|
||||
|
||||
* Adds configuration for [Windows Terminal integration](icingaintegration/50-Windows-Terminal.md)
|
||||
* Adds configuration for [Windows Terminal integration](../110-Installation/50-Windows-Terminal.md)
|
||||
* Adds new Cmdlet `Show-IcingaPerformanceCounterInstances` to display all available instances for Performance Counters
|
||||
* [#76](https://github.com/Icinga/icinga-powershell-framework/issues/76) Adds support to test for required .NET Framework Version 4.6.0 or above before trying to install the Icinga Agent
|
||||
* [#87](https://github.com/Icinga/icinga-powershell-framework/issues/87) Adds wrapper command to test new code or functionality of Framework and/or plugins
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Framework Eventlog Documentation
|
||||
# Icinga for Windows Eventlog Documentation
|
||||
|
||||
Below you will find a list of EventId's which are exported by this module. The short and detailed message are both written directly into the eventlog. This documentation shall simply provide a summary of available EventId's
|
||||
|
||||
|
|
@ -1,89 +1,89 @@
|
|||
# Icinga for Windows Roadmap
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines our roadmap for the Icinga for Windows solution. It does not only cover the Icinga PowerShell Framework itself, but also plugins and other related modules.
|
||||
|
||||
## Milestones
|
||||
|
||||
The project is continuously developed and delivered as set of 3-month milestones. New features and functionality are provided within the [Icinga PowerShell Framework master branch](https://github.com/Icinga/icinga-powershell-framework) as well as other related repositories. Changes ahead on the master are always provided within the [changelog](https://github.com/Icinga/icinga-powershell-framework/blob/master/doc/31-Changelog.md) of each project.
|
||||
|
||||
## Icinga for Windows Roadmap / Timeline
|
||||
|
||||
Below is a schedule of milestones for new releases and components. The dates are rough estimates and are subject to change.
|
||||
|
||||
| Milestone End Date | Milestone Name | Preview Release Blog Post |
|
||||
| ------------------ | -------------- | ------------------------- |
|
||||
| 2020-02-19 | [1.0.0-framework] in Icinga for Windows<br>[1.0.0-plugins] in Icinga PowerShell Plugins | [Icinga for Windows 1.0.0 Release](https://icinga.com/2020/02/19/announcing-icinga-for-windows-v1-0/) |
|
||||
| 2020-03-18 | [1.0.1-framework] in Icinga for Windows | [Icinga for Windows 1.0.1 Release](https://icinga.com/2020/03/19/icinga-for-windows-bugfix-release-v1-0-1/) |
|
||||
| 2020-04-16 | [1.0.2-framework] in Icinga for Windows | |
|
||||
| 2020-06-02 | [1.1.0-framework] in Icinga for Windows<br>[1.1.0-plugins] in Icinga PowerShell Plugins<br>[1.0.0-restapi] in Icinga PowerShell REST-Api<br>[1.0.0-inventory] in Icinga PowerShell Inventory | [Icinga for Windows 1.1.0 Release](https://icinga.com/2020/06/03/icinga-for-windows-v1-1-0-release/) |
|
||||
| 2020-06-18 | [1.1.1-framework] in Icinga for Windows | |
|
||||
| 2020-06-26 | [1.1.2-framework] in Icinga for Windows | |
|
||||
| 2020-08-31 | [1.2.0-framework] in Icinga for Windows<br>[1.2.0-plugins] in Icinga PowerShell Plugins | [Icinga for Windows 1.2.0 Release](https://icinga.com/2020/08/31/releasing-icinga-for-windows-v1-2-0/) |
|
||||
| 2020-10-13 | [1.0.0-mssql] in Icinga PowerShell MSSQL | [Icinga PowerShell MSSQL v1.0.0 Release](https://icinga.com/2020/10/13/icinga-for-windows-mssql-plugin-release-v1-0-0/)
|
||||
| 2020-12-01 | [1.3.0-framework] in Icinga for Windows<br>[1.3.0-plugins] in Icinga PowerShell Plugins<br>[1.2.0-kickstart] in Icinga PowerShell Kickstart | [Icinga for Windows v1.3.0 – Yet another release!](https://icinga.com/blog/2020/12/01/icinga-for-windows-v1-3-0-yet-another-release/) |
|
||||
| 2021-01-12 | [1.0.0-hyperv] in Icinga PowerShell Hyper-V<br>[1.0.0-cluster] in Icinga PowerShell Cluster | tbd |
|
||||
| 2021-03-02 | [1.4.0-framework] in Icinga for Windows | tbd |
|
||||
|
||||
## Issue Triage & Prioritization
|
||||
|
||||
Opened issues, tasks and features are scheduled several times a week, labeled, and assigned to a milestone depending on the priority:
|
||||
|
||||
* Crash/Security: (crashes, unusable behavior, security issues, ...) issues are dealt with shortly including possible bugfix releases
|
||||
* Bug/Enhancement: issues, features or tasks are assigned to the current or future milestone
|
||||
|
||||
## Feature List
|
||||
|
||||
The following list contains a bunch of features we are planning to implement into the Icinga for Windows solution
|
||||
|
||||
> 📌 Note: We will update this list frequently in case new milestones and/or features are available and update this list accordingly
|
||||
|
||||
| Priority\* | Scenario | Description/Notes |
|
||||
| ---------- | -------- | ----------------- |
|
||||
| 1 | Performance Improvement | Reduce the impact of loading the entire Framework to a minimum.<br><br>Issue: [#106] |
|
||||
| 2 | Icinga API Integration | An easy way to communicate directly with the Icinga 2 API over Cmdlets for easier access. Authorization should be handled by certificates or user/password auth.<br><br>Issue: [#105] |
|
||||
| 2 | Improve module caching | While running the Icinga for Windows solution as background daemon we should make sure that recurring tasks/events are properly cached. For this we will need to cache objects recursively, including arrays and hashtables<br><br>Issue: [#5]
|
||||
| 2 | Improve Performance Counter Cache | We should improve the Performance Counter cache to be able to recognize if certain counter/instances are no longer present or have been added. This will resolve an issue while using the background daemon for regular tasks<br><br>Issue: [#11]
|
||||
| 2 | Plugin Re-Write | We should rewrite some of current implemented plugins to use new Framework features and improve usability |
|
||||
| 3 | Icinga Service Recovery | By default the Icinga Agent installer is not shipping with a service recovery solution in case the service crashes. We should allow the user to configure a custom rule set on what happens if Icinga crashes and how often a restart attempt is done for example<br><br>Issue: [#40]
|
||||
| 4 | Windows Update Installation | The idea behind this is for smaller customer environments to allow the installation of certain Windows updates by using Icinga for Windows. This was an initial requests and should be taken into consideration when nothing else is to do<br><br>Issue: [#7]
|
||||
| 4 | Hyper-V Monitoring | Add plugins for Hyper-V monitoring in an own separate module to cover this platform |
|
||||
| 4 | Cluster Monitoring | Add plugins for certain Cluster systems for monitoring |
|
||||
| 4 | Exchange Server Monitoring | Add plugins for Exchange Server monitoring in an own separate module to cover this platform |
|
||||
| 4 | Active Directory Monitoring | Add plugins for Active Directory Server monitoring in an own separate module to cover this platform |
|
||||
|
||||
Feature Notes:
|
||||
|
||||
\* Feature Priorities:
|
||||
|
||||
1. Mandatory <br/>
|
||||
2. Beneficial <br/>
|
||||
3. Optional <br/>
|
||||
4. Requires Sponsoring <br/>
|
||||
|
||||
[1.0.0-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/2
|
||||
[1.0.0-plugins]: https://github.com/Icinga/icinga-powershell-plugins/milestones/1/
|
||||
[1.0.0-restapi]: https://github.com/Icinga/icinga-powershell-restapi/releases/tag/v1.0.0
|
||||
[1.0.0-inventory]: https://github.com/Icinga/icinga-powershell-inventory/releases/tag/v1.0.0
|
||||
[1.0.0-mssql]: https://github.com/Icinga/icinga-powershell-mssql/milestone/1
|
||||
[1.0.1-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/5
|
||||
[1.0.2-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/6
|
||||
[1.1.0-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/4
|
||||
[1.1.0-plugins]: https://github.com/Icinga/icinga-powershell-plugins/milestones/2/
|
||||
[1.1.1-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/8
|
||||
[1.1.2-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/9
|
||||
[1.2.0-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/7
|
||||
[1.2.0-plugins]: https://github.com/Icinga/icinga-powershell-plugins/milestone/3
|
||||
[1.2.0-kickstart]: https://github.com/Icinga/icinga-powershell-kickstart/milestone/1
|
||||
[1.3.0-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/10
|
||||
[1.3.0-plugins]: https://github.com/Icinga/icinga-powershell-plugins/milestone/4
|
||||
[1.4.0-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/11
|
||||
[#5]: https://github.com/Icinga/icinga-powershell-framework/issues/5
|
||||
[#7]: https://github.com/Icinga/icinga-powershell-framework/issues/7
|
||||
[#11]: https://github.com/Icinga/icinga-powershell-framework/issues/11
|
||||
[#19]: https://github.com/Icinga/icinga-powershell-framework/issues/19
|
||||
[#40]: https://github.com/Icinga/icinga-powershell-framework/issues/40
|
||||
[#100]: https://github.com/Icinga/icinga-powershell-framework/issues/100
|
||||
[#105]: https://github.com/Icinga/icinga-powershell-framework/issues/105
|
||||
[#106]: https://github.com/Icinga/icinga-powershell-framework/issues/106
|
||||
# Icinga for Windows Roadmap
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines our roadmap for the Icinga for Windows solution. It does not only cover the Icinga PowerShell Framework itself, but also plugins and other related modules.
|
||||
|
||||
## Milestones
|
||||
|
||||
The project is continuously developed and delivered as set of 3-month milestones. New features and functionality are provided within the [Icinga PowerShell Framework master branch](https://github.com/Icinga/icinga-powershell-framework) as well as other related repositories. Changes ahead on the master are always provided within the [changelog](https://github.com/Icinga/icinga-powershell-framework/blob/master/doc/31-Changelog.md) of each project.
|
||||
|
||||
## Icinga for Windows Roadmap / Timeline
|
||||
|
||||
Below is a schedule of milestones for new releases and components. The dates are rough estimates and are subject to change.
|
||||
|
||||
| Milestone End Date | Milestone Name | Preview Release Blog Post |
|
||||
| ------------------ | -------------- | ------------------------- |
|
||||
| 2020-02-19 | [1.0.0-framework] in Icinga for Windows<br>[1.0.0-plugins] in Icinga PowerShell Plugins | [Icinga for Windows 1.0.0 Release](https://icinga.com/2020/02/19/announcing-icinga-for-windows-v1-0/) |
|
||||
| 2020-03-18 | [1.0.1-framework] in Icinga for Windows | [Icinga for Windows 1.0.1 Release](https://icinga.com/2020/03/19/icinga-for-windows-bugfix-release-v1-0-1/) |
|
||||
| 2020-04-16 | [1.0.2-framework] in Icinga for Windows | |
|
||||
| 2020-06-02 | [1.1.0-framework] in Icinga for Windows<br>[1.1.0-plugins] in Icinga PowerShell Plugins<br>[1.0.0-restapi] in Icinga PowerShell REST-Api<br>[1.0.0-inventory] in Icinga PowerShell Inventory | [Icinga for Windows 1.1.0 Release](https://icinga.com/2020/06/03/icinga-for-windows-v1-1-0-release/) |
|
||||
| 2020-06-18 | [1.1.1-framework] in Icinga for Windows | |
|
||||
| 2020-06-26 | [1.1.2-framework] in Icinga for Windows | |
|
||||
| 2020-08-31 | [1.2.0-framework] in Icinga for Windows<br>[1.2.0-plugins] in Icinga PowerShell Plugins | [Icinga for Windows 1.2.0 Release](https://icinga.com/2020/08/31/releasing-icinga-for-windows-v1-2-0/) |
|
||||
| 2020-10-13 | [1.0.0-mssql] in Icinga PowerShell MSSQL | [Icinga PowerShell MSSQL v1.0.0 Release](https://icinga.com/2020/10/13/icinga-for-windows-mssql-plugin-release-v1-0-0/)
|
||||
| 2020-12-01 | [1.3.0-framework] in Icinga for Windows<br>[1.3.0-plugins] in Icinga PowerShell Plugins<br>[1.2.0-kickstart] in Icinga PowerShell Kickstart | [Icinga for Windows v1.3.0 – Yet another release!](https://icinga.com/blog/2020/12/01/icinga-for-windows-v1-3-0-yet-another-release/) |
|
||||
| 2021-01-12 | [1.0.0-hyperv] in Icinga PowerShell Hyper-V<br>[1.0.0-cluster] in Icinga PowerShell Cluster | tbd |
|
||||
| 2021-03-02 | [1.4.0-framework] in Icinga for Windows | tbd |
|
||||
|
||||
## Issue Triage & Prioritization
|
||||
|
||||
Opened issues, tasks and features are scheduled several times a week, labeled, and assigned to a milestone depending on the priority:
|
||||
|
||||
* Crash/Security: (crashes, unusable behavior, security issues, ...) issues are dealt with shortly including possible bugfix releases
|
||||
* Bug/Enhancement: issues, features or tasks are assigned to the current or future milestone
|
||||
|
||||
## Feature List
|
||||
|
||||
The following list contains a bunch of features we are planning to implement into the Icinga for Windows solution
|
||||
|
||||
> 📌 Note: We will update this list frequently in case new milestones and/or features are available and update this list accordingly
|
||||
|
||||
| Priority\* | Scenario | Description/Notes |
|
||||
| ---------- | -------- | ----------------- |
|
||||
| 1 | Performance Improvement | Reduce the impact of loading the entire Framework to a minimum.<br><br>Issue: [#106] |
|
||||
| 2 | Icinga API Integration | An easy way to communicate directly with the Icinga 2 API over Cmdlets for easier access. Authorization should be handled by certificates or user/password auth.<br><br>Issue: [#105] |
|
||||
| 2 | Improve module caching | While running the Icinga for Windows solution as background daemon we should make sure that recurring tasks/events are properly cached. For this we will need to cache objects recursively, including arrays and hashtables<br><br>Issue: [#5]
|
||||
| 2 | Improve Performance Counter Cache | We should improve the Performance Counter cache to be able to recognize if certain counter/instances are no longer present or have been added. This will resolve an issue while using the background daemon for regular tasks<br><br>Issue: [#11]
|
||||
| 2 | Plugin Re-Write | We should rewrite some of current implemented plugins to use new Framework features and improve usability |
|
||||
| 3 | Icinga Service Recovery | By default the Icinga Agent installer is not shipping with a service recovery solution in case the service crashes. We should allow the user to configure a custom rule set on what happens if Icinga crashes and how often a restart attempt is done for example<br><br>Issue: [#40]
|
||||
| 4 | Windows Update Installation | The idea behind this is for smaller customer environments to allow the installation of certain Windows updates by using Icinga for Windows. This was an initial requests and should be taken into consideration when nothing else is to do<br><br>Issue: [#7]
|
||||
| 4 | Hyper-V Monitoring | Add plugins for Hyper-V monitoring in an own separate module to cover this platform |
|
||||
| 4 | Cluster Monitoring | Add plugins for certain Cluster systems for monitoring |
|
||||
| 4 | Exchange Server Monitoring | Add plugins for Exchange Server monitoring in an own separate module to cover this platform |
|
||||
| 4 | Active Directory Monitoring | Add plugins for Active Directory Server monitoring in an own separate module to cover this platform |
|
||||
|
||||
Feature Notes:
|
||||
|
||||
\* Feature Priorities:
|
||||
|
||||
1. Mandatory <br/>
|
||||
2. Beneficial <br/>
|
||||
3. Optional <br/>
|
||||
4. Requires Sponsoring <br/>
|
||||
|
||||
[1.0.0-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/2
|
||||
[1.0.0-plugins]: https://github.com/Icinga/icinga-powershell-plugins/milestones/1/
|
||||
[1.0.0-restapi]: https://github.com/Icinga/icinga-powershell-restapi/releases/tag/v1.0.0
|
||||
[1.0.0-inventory]: https://github.com/Icinga/icinga-powershell-inventory/releases/tag/v1.0.0
|
||||
[1.0.0-mssql]: https://github.com/Icinga/icinga-powershell-mssql/milestone/1
|
||||
[1.0.1-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/5
|
||||
[1.0.2-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/6
|
||||
[1.1.0-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/4
|
||||
[1.1.0-plugins]: https://github.com/Icinga/icinga-powershell-plugins/milestones/2/
|
||||
[1.1.1-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/8
|
||||
[1.1.2-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/9
|
||||
[1.2.0-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/7
|
||||
[1.2.0-plugins]: https://github.com/Icinga/icinga-powershell-plugins/milestone/3
|
||||
[1.2.0-kickstart]: https://github.com/Icinga/icinga-powershell-kickstart/milestone/1
|
||||
[1.3.0-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/10
|
||||
[1.3.0-plugins]: https://github.com/Icinga/icinga-powershell-plugins/milestone/4
|
||||
[1.4.0-framework]: https://github.com/Icinga/icinga-powershell-framework/milestone/11
|
||||
[#5]: https://github.com/Icinga/icinga-powershell-framework/issues/5
|
||||
[#7]: https://github.com/Icinga/icinga-powershell-framework/issues/7
|
||||
[#11]: https://github.com/Icinga/icinga-powershell-framework/issues/11
|
||||
[#19]: https://github.com/Icinga/icinga-powershell-framework/issues/19
|
||||
[#40]: https://github.com/Icinga/icinga-powershell-framework/issues/40
|
||||
[#100]: https://github.com/Icinga/icinga-powershell-framework/issues/100
|
||||
[#105]: https://github.com/Icinga/icinga-powershell-framework/issues/105
|
||||
[#106]: https://github.com/Icinga/icinga-powershell-framework/issues/106
|
||||
106
doc/110-Installation/01-Getting-Started.md
Normal file
106
doc/110-Installation/01-Getting-Started.md
Normal file
|
|
@ -0,0 +1,106 @@
|
|||
# Getting Started - Icinga for Windows
|
||||
|
||||
Icinga for Windows provides tools and functionality to entirely manage itself. This includes first-time deployment including later installation of new components or updating installed ones. To ensure a smooth setup procedure, we recommend using the by Icinga provided scripts and repositories as baseline for deployment inside environments.
|
||||
|
||||
## Requirements
|
||||
|
||||
* Windows 2012 R2 or later
|
||||
* PowerShell Version 4.0 or later
|
||||
* [Execution Policies](https://docs.microsoft.com/de-de/powershell/module/microsoft.powershell.core/about/about_execution_policies) allowing module/script execution
|
||||
* Access to [packages.icinga.com](https://packages.icinga.com) at least from one location
|
||||
|
||||
## Installation Dependencies
|
||||
|
||||
In order to install Icinga for Windows as easy as possible, we will require at least from one location access to [packages.icinga.com](https://packages.icinga.com). On this page we can find the sub-section [IcingaForWindows](https://packages.icinga.com/IcingaForWindows), which contains an installation script [IcingaForWindows.ps1](https://packages.icinga.com/IcingaForWindows/IcingaForWindows.ps1) and our repositories we can fetch our components, including the [Icinga PowerShell Framework](https://github.com/Icinga/icinga-powershell-framework) from.
|
||||
|
||||
**Note:** If you already installed Icinga for Windows, you can synchronize the exiting repository from [packages.icinga.com](https://packages.icinga.com/IcingaForWindows) and download and paste the [IcingaForWindows.ps1](https://packages.icinga.com/IcingaForWindows/IcingaForWindows.ps1) with our synced content to an internal webserver, network share or locally on systems. The next steps can then be adjusted depending on your locations.
|
||||
|
||||
## Install Icinga for Windows
|
||||
|
||||
To install Icinga for Windows from systems with internet access, we can simply run this short PowerShell code inside an `administrative` PowerShell, to download the [IcingaForWindows.ps1](https://packages.icinga.com/IcingaForWindows/IcingaForWindows.ps1) and execute it afterwards:
|
||||
|
||||
```powershell
|
||||
[Net.ServicePointManager]::SecurityProtocol = 'tls12, tls11';
|
||||
$ProgressPreference = 'SilentlyContinue';
|
||||
[string]$ScriptFile = 'C:\Users\Public\IcingaForWindows.ps1';
|
||||
|
||||
Invoke-WebRequest `
|
||||
-UseBasicParsing `
|
||||
-Uri 'https://packages.icinga.com/IcingaForWindows/IcingaForWindows.ps1' `
|
||||
-OutFile $ScriptFile;
|
||||
|
||||
& $ScriptFile
|
||||
```
|
||||
|
||||
This will write the PowerShell scriptfile into `C:\Users\Public`.
|
||||
|
||||
Once the script is executed, you will be prompted with several questions on where the Icinga PowerShell Framework should be installed (defaults to `C:\Program Files\WindowsPowerShell\Modules`) and if you would like to run the Icinga Management Console afterwards for completing the installation.
|
||||
|
||||
## Automate the installation
|
||||
|
||||
To automate the entire process, you can define several arguments during the script call.
|
||||
|
||||
### Script arguments
|
||||
|
||||
| Argument | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| IcingaRepository | String | The location (local, web or network share) of your Icinga for Windows repository. Defaults to `https://packages.icinga.com/IcingaForWindows/stable/ifw.repo.json` |
|
||||
| ModuleDirectory | String | Allows to specify in which PowerShell directory Icinga for Windows will be installed. If left empty, you will be prompted with a dialog, asking on where Icinga for Windows should be installed into. Defaults to `$null` |
|
||||
| AnswerFile | String | Allows you to provide an answer file, starting with Icinga for Windows 1.6.0, which will apply the specified configuration after the Framework has been installed. Defaults to `''` |
|
||||
| InstallCommand | String | Allows you to provide an install command, starting with Icinga for Windows 1.6.0, which will apply the specified configuration after the Framework has been installed. Defaults to `''` |
|
||||
| AllowUpdate | Switch | Defines if the Icinga PowerShell Framework should be updated during the kickstart run, in case it is already installed. Defaults to `$False` |
|
||||
| SkipWizard | Switch |Defines to only install the Icinga PowerShell Framework and/or update it if specified. Will skip the question for the installation wizard/Icinga Management Console afterwards and will ignore provided arguments `-AnswerFile` and `-InstallCommand`. Defaults to `$False` |
|
||||
|
||||
### Installation Examples
|
||||
|
||||
#### Automated installation with skipped wizard
|
||||
|
||||
```powershell
|
||||
[Net.ServicePointManager]::SecurityProtocol = 'tls12, tls11';
|
||||
$ProgressPreference = 'SilentlyContinue';
|
||||
[string]$ScriptFile = 'C:\Users\Public\IcingaForWindows.ps1';
|
||||
|
||||
Invoke-WebRequest `
|
||||
-UseBasicParsing `
|
||||
-Uri 'https://packages.icinga.com/IcingaForWindows/IcingaForWindows.ps1' `
|
||||
-OutFile $ScriptFile;
|
||||
|
||||
& $ScriptFile `
|
||||
-ModuleDirectory 'C:\Program Files\WindowsPowerShell\Modules\' `
|
||||
-SkipWizard;
|
||||
```
|
||||
|
||||
#### Automated installation with InstallCommand
|
||||
|
||||
```powershell
|
||||
[Net.ServicePointManager]::SecurityProtocol = 'tls12, tls11';
|
||||
$ProgressPreference = 'SilentlyContinue';
|
||||
[string]$ScriptFile = 'C:\Users\Public\IcingaForWindows.ps1';
|
||||
|
||||
Invoke-WebRequest `
|
||||
-UseBasicParsing `
|
||||
-Uri 'https://packages.icinga.com/IcingaForWindows/IcingaForWindows.ps1' `
|
||||
-OutFile $ScriptFile;
|
||||
|
||||
& $ScriptFile `
|
||||
-ModuleDirectory 'C:\Program Files\WindowsPowerShell\Modules\' `
|
||||
-InstallCommand '{"IfW-DirectorSelfServiceKey":{"Values":["651f889ca5f364e89ed709eabde6237fb02050ff"]},"IfW-DirectorUrl":{"Values":["https://icinga.example.com/icingaweb2/director"]}}';
|
||||
```
|
||||
|
||||
#### Automated installation with InstallCommand and own IcingaRepository
|
||||
|
||||
```powershell
|
||||
[Net.ServicePointManager]::SecurityProtocol = 'tls12, tls11';
|
||||
$ProgressPreference = 'SilentlyContinue';
|
||||
[string]$ScriptFile = 'C:\Users\Public\IcingaForWindows.ps1';
|
||||
|
||||
Invoke-WebRequest `
|
||||
-UseBasicParsing `
|
||||
-Uri 'https://icinga.example.com/IcingaForWindows.ps1' `
|
||||
-OutFile $ScriptFile;
|
||||
|
||||
& $ScriptFile `
|
||||
-ModuleDirectory 'C:\Program Files\WindowsPowerShell\Modules\' `
|
||||
-InstallCommand '{"IfW-DirectorSelfServiceKey":{"Values":["651f889ca5f364e89ed709eabde6237fb02050ff"]},"IfW-DirectorUrl":{"Values":["https://icinga.example.com/icingaweb2/director"]}}' `
|
||||
-IcingaRepository 'https://icinga.example.com/repositories/stable';
|
||||
```
|
||||
64
doc/110-Installation/02-Icinga-Management-Console.md
Normal file
64
doc/110-Installation/02-Icinga-Management-Console.md
Normal file
|
|
@ -0,0 +1,64 @@
|
|||
# Icinga Management Console (IMC) - Overview
|
||||
|
||||
As we now have deployed our Icinga PowerShell Framework on our Windows machine, we can continue the installation by using the IMC (Icinga Management Console).
|
||||
|
||||
**Note:** You can always open the IMC by running the following command:
|
||||
|
||||
```powershell
|
||||
icinga -Manage;
|
||||
```
|
||||
|
||||
## Navigating the IMC
|
||||
|
||||
To navigate through the IMC, you have to use numbers and letters confirmed by pressing on `Enter`.
|
||||
|
||||
| Input | Name | Description |
|
||||
| --- | --- | --- |
|
||||
| 0-x | Numeric | Numeric values are used on list views to select a specific index of an entry, to either enter a sub-menu or to select it. |
|
||||
| a | Advanced | Will only occur on several forms and will show advanced options for additional configuration settings (toogle) |
|
||||
| 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) |
|
||||
| l | Command | Will print the command being executed by the IMC for an entry (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 |
|
||||
|
||||
## Multi-Value Input
|
||||
|
||||
Some forms allow you to enter values, like your Icinga parent zone or your endpoint configuration for the Icinga Agent.
|
||||
|
||||
Input forms are always designed by having a (x/x) at the bottom right if your input form. The number of entries defined in the right side defines the maximum allowed entried, while the left side defines how many are currently added.
|
||||
|
||||
**Example:**
|
||||
|
||||
```text
|
||||
Input (Default c) (0/1):
|
||||
```
|
||||
|
||||
This means that we currently have `0` entries added out of a maximum of `1`.
|
||||
|
||||
To remove entries, we can use the `d` input and re-add our arguments. We can simply type our input as we would with the input commands:
|
||||
|
||||
```text
|
||||
Input (Default c) (0/1): master
|
||||
```
|
||||
|
||||
In this case, `master` would be our value we want to add and can confirm this by pressing `Enter`. If everything is successful, the result will look like this:
|
||||
|
||||
```text
|
||||
*******************************************
|
||||
** Icinga for Windows Management Console **
|
||||
** Copyright (c) 2021 Icinga GmbH | MIT **
|
||||
** User environment ws-icinga\icinga **
|
||||
** Icinga PowerShell Framework v1.6.0 **
|
||||
*******************************************
|
||||
|
||||
Please enter your parent Icinga zone:
|
||||
|
||||
"master"
|
||||
|
||||
[x] Exit [c] Continue [d] Delete [h] Help [l] Commands [m] Main [p] Previous
|
||||
|
||||
Input (Default c) (1/1):
|
||||
```
|
||||
66
doc/110-Installation/03-Installation-with-IMC.md
Normal file
66
doc/110-Installation/03-Installation-with-IMC.md
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
# Icinga Management Console (IMC) - Installation
|
||||
|
||||
We can now use the Icinga Management Console to configure our local Windows system and install every required component, or use the defined configuration as template for deployment on different hosts.
|
||||
|
||||
If we are not already inside the IMC, we can open it with
|
||||
|
||||
```powershell
|
||||
icinga -Manage;
|
||||
```
|
||||
|
||||
## Installation menu
|
||||
|
||||
By pressing `0` on the `main menu`, we can start the entire `Installation`:
|
||||
|
||||
```text
|
||||
*******************************************
|
||||
** Icinga for Windows Management Console **
|
||||
** Copyright (c) 2021 Icinga GmbH | MIT **
|
||||
** User environment ws-icinga\icinga **
|
||||
** Icinga PowerShell Framework v1.6.0 **
|
||||
*******************************************
|
||||
|
||||
What do you want to do?
|
||||
|
||||
[0] Installation
|
||||
[1] Install components
|
||||
[2] Update components
|
||||
[3] Remove components
|
||||
[4] Manage environment
|
||||
[5] List environment
|
||||
|
||||
[x] Exit [c] Continue [h] Help [l] Commands [m] Main
|
||||
|
||||
Input (Default 0 and c): 0
|
||||
```
|
||||
|
||||
### Optional Menu - Reconfigure/Continue
|
||||
|
||||
In case you already deployed a configuration before or aborted your previous attempt, you will be greeted with this menu:
|
||||
|
||||
```text
|
||||
*******************************************
|
||||
** Icinga for Windows Management Console **
|
||||
** Copyright (c) 2021 Icinga GmbH | MIT **
|
||||
** User environment ws-icinga\icinga **
|
||||
** Icinga PowerShell Framework v1.6.0 **
|
||||
*******************************************
|
||||
|
||||
Choose the configuration type:
|
||||
|
||||
[0] New configuration
|
||||
[1] Continue configuration
|
||||
[2] Reconfigure environment
|
||||
|
||||
[x] Exit [c] Continue [h] Help [l] Commands [m] Main [p] Previous
|
||||
|
||||
Input (Default 0 and c):
|
||||
```
|
||||
|
||||
Here you can choose if you want to reconfigure your current setup, continue on a previous attempt or start a new configuration. In case you start a new configuration, please note that `Reconfigure environment` will only be overwritten if you actually install this configuration.
|
||||
|
||||
You can use `New configuration` or `Continue configuration` and even `Reconfigure environment` to modify certain setthings to have them available for automated deployment on different machines.
|
||||
|
||||
### Continue installation
|
||||
|
||||
Depending on your infrastructure, required configurations and setup type, you can now navigiate through the entire process of the installation menu and configure the environment as you want. In case you are unsure about certain menu entries, you can use `h` to show the help including an explanation of required values.
|
||||
39
doc/110-Installation/04-Installation-Templates.md
Normal file
39
doc/110-Installation/04-Installation-Templates.md
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
# Installation Templates - Quickstarter
|
||||
|
||||
In case you are in a hurry, here are some command examples you can use for installing your Icinga for Windows environment.
|
||||
|
||||
## How to use below examples
|
||||
|
||||
The installation commands and answer files are simple JSON strings, containing required information for the IMC to work with. If you use these examples as `-InstallCommand`, you will have to wrap them inside single quotes `''`:
|
||||
|
||||
```powershell
|
||||
'{"IfW-DirectorSelfServiceKey":{"Values":["651f889ca5f364e89ed709eabde6237fb02050ff"]},"IfW-DirectorUrl":{"Values":["https://icinga.example.com/icingaweb2/director"]}}'
|
||||
```
|
||||
|
||||
If you want to use them as answer files, you can simply copy them as mentioned below inside a simple text file without modifications. This is required if you are using the `-AnswerFile` argument.
|
||||
|
||||
### Usage Examples
|
||||
|
||||
Using the `-InstallCommand` argument for `Install-Icinga`:
|
||||
|
||||
```powershell
|
||||
Install-Icinga -InstallCommand '{"IfW-DirectorSelfServiceKey":{"Values":["651f889ca5f364e89ed709eabde6237fb02050ff"]},"IfW-DirectorUrl":{"Values":["https://icinga.example.com/icingaweb2/director"]}}';
|
||||
```
|
||||
|
||||
Using the `-AnswerFile` argument for `Install-Icinga`:
|
||||
|
||||
```powershell
|
||||
Install-Icinga -AnswerFile 'C:\Users\Public\icinga_installation.json';
|
||||
```
|
||||
|
||||
**Note:** You can use the same arguments on the `IcingaForWindows.ps1` as described in the [Getting Started](01-Getting-Started.md) page, for a full automation without user interaction.
|
||||
|
||||
**Note 2:** The file type must not be `.json`, it just helps representing the content properly.
|
||||
|
||||
## Icinga Director Self-Service API
|
||||
|
||||
Use the Icinga Director Self-Service API without any custom modifications and install Icinga for Windows as defined inside the Icinga Director
|
||||
|
||||
```powershell
|
||||
{"IfW-DirectorSelfServiceKey":{"Values":["651f889ca5f364e89ed709eabde6237fb02050ff"]},"IfW-DirectorUrl":{"Values":["https://icinga.example.com/icingaweb2/director"]}}
|
||||
```
|
||||
74
doc/110-Installation/05-Background-Daemons.md
Normal file
74
doc/110-Installation/05-Background-Daemons.md
Normal file
|
|
@ -0,0 +1,74 @@
|
|||
# Background Daemons - Installation
|
||||
|
||||
Icinga for Windows supports to run tasks within a background daemon, allowing to collect metrics over time, providing a REST-Api and other functionality.
|
||||
|
||||
## Requirements
|
||||
|
||||
In order to work with background daemons, you will require to have the Icinga for Windows PowerShell service installed. You can do this during the initial run within the IMC, by installing the `service` component inside the IMC or by running the following command:
|
||||
|
||||
```powershell
|
||||
Install-IcingaComponent -Name service;
|
||||
```
|
||||
|
||||
**Note:** To install the service you require to add a [Icinga for Windows repository](20-Install-Components.md) to your environment.
|
||||
|
||||
## Managing Background Daemons
|
||||
|
||||
You can register, unregister and show background daemons including the configuration. Some background daemons might ship with independent configurations and possibilities, please have a look on the corresponding documentation.
|
||||
|
||||
### Register Background Daemons
|
||||
|
||||
In order to register a background daemon, you can run the command
|
||||
|
||||
```powershell
|
||||
Register-IcingaBackgroundDaemon;
|
||||
```
|
||||
|
||||
| Argument | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| Command | String | The name of the command being registered as background daemon. The command has to be defined of type background daemon. You cannot register any other command |
|
||||
| Arguments | Hashtable | In case background daemons allow the configuration and definition of arguments, you can set them as hashtable with this argument |
|
||||
|
||||
Icinga for Windows ships with an internal daemon to collect metrics over time. The daemon function is `Start-IcingaServiceCheckDaemon`:
|
||||
|
||||
```powershell
|
||||
Register-IcingaBackgroundDaemon `
|
||||
-Command 'Start-IcingaServiceCheckDaemon';
|
||||
```
|
||||
|
||||
In case the daemon is using arguments, you can provide the key/value pair for the argument as a hashtable. In case the argument is of type `Switch`, simply set the value to `$True` to add the argument.
|
||||
|
||||
```powershell
|
||||
Register-IcingaBackgroundDaemon `
|
||||
-Command 'Start-MyCustomDaemon' `
|
||||
-Arguments @{
|
||||
'-MySwitchParameter' = $True;
|
||||
'-MyIntegerParameter' = 42;
|
||||
'-MyStringParameter' = 'Example';
|
||||
};
|
||||
```
|
||||
|
||||
### Unregister Background Daemons
|
||||
|
||||
Once a daemon is registered, you can also unregister them from Icinga for Windows.
|
||||
|
||||
```powershell
|
||||
Register-IcingaBackgroundDaemon `
|
||||
-BackgroundDaemon 'Start-IcingaServiceCheckDaemon';
|
||||
```
|
||||
|
||||
### Show Background Daemons
|
||||
|
||||
To print a list of configured background daemons, you can run
|
||||
|
||||
```powershell
|
||||
Get-IcingaBackgroundDaemons;
|
||||
```
|
||||
|
||||
## Restart PowerShell Service
|
||||
|
||||
In order to apply any changes on background daemons, you will always to restart the Icinga for Windows PowerShell service. You can do so with the following command:
|
||||
|
||||
```powershell
|
||||
Restart-IcingaWindowsService;
|
||||
```
|
||||
122
doc/110-Installation/06-Collect-Metrics-over-Time.md
Normal file
122
doc/110-Installation/06-Collect-Metrics-over-Time.md
Normal file
|
|
@ -0,0 +1,122 @@
|
|||
# Collect Metrics over Time - Installation
|
||||
|
||||
Icinga for Windows provides the functionality directly build into the Icinga PowerShell Framework, to execute checks internally in defined time ranges and collect and store performance metrics from them.
|
||||
|
||||
Collected metrics are then, based on your configuration, added to an actual check execution from Icinga and added as performance data label to your check. By using the `-ThresholdInterval` argument of the plugins, you can also use the checks thresholds to compare them against the collected metrics instead of the current value.
|
||||
|
||||
## Requirements
|
||||
|
||||
For this feature to work, you will require the Icinga PowerShell Service being installed and know how to [manage background daemons](05-Background-Daemons.md).
|
||||
|
||||
## Register the Background Daemon
|
||||
|
||||
The Icinga PowerShell Framework ships with a build-in daemon, which allows to queue service checks internally to collect metrics. The Cmdlet for this daemon is `Start-IcingaServiceCheckDaemon`.
|
||||
|
||||
**Note:** Please note this daemon *only* collects the performance metrics and is not meant to actually apply monitoring tasks.
|
||||
|
||||
At first, we need to register this daemon:
|
||||
|
||||
```powershell
|
||||
Register-IcingaBackgroundDaemon `
|
||||
-BackgroundDaemon 'Start-IcingaServiceCheckDaemon';
|
||||
```
|
||||
|
||||
## Manage Service Checks
|
||||
|
||||
Once the daemon is registered, you can start configuring plugins which are frequently executed and the performance metrics collected. The intervall of execution including the time interval of which metrics are stored, can be configured individually.
|
||||
|
||||
**Note:** It is **not** supported to register the same plugin multiple times with different arguments. In case you want to collect several, different performance counters with `Invoke-IcingaCheckPerfCounter` for example, you will have to add all counters to one plugin call.
|
||||
|
||||
### Register Service Checks
|
||||
|
||||
In order to add service check to our daemon, we can use `Register-IcingaServiceCheck`.
|
||||
|
||||
| Arguments | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| CheckCommand | String | The plugin you want to execute inside the daemon |
|
||||
| Arguments | Hashtable | Plugin arguments which are added to the internal check |
|
||||
| Interval | Integer | The time interval in seconds on how often the check is executed |
|
||||
| TimeIndexes | Array | A list of Integer time indexes, for which time frames metrics should be collected |
|
||||
|
||||
#### Examples
|
||||
|
||||
##### Register CPU Plugin
|
||||
|
||||
We will register our CPU plugin to run every 30 seconds and collect the average metrics for 1, 3, 5 and 15 minutes:
|
||||
|
||||
```powershell
|
||||
Register-IcingaServiceCheck `
|
||||
-CheckCommand 'Invoke-IcingaCheckCPU' `
|
||||
-Interval 30 `
|
||||
-TimeIndexes 1, 3, 5, 15;
|
||||
```
|
||||
|
||||
##### Register Partition Space Plugin
|
||||
|
||||
Lets register our used partition space plugin, to run every 15 seconds, collect the average metrics for 1,3,5,20 and 60 minutes and only include drive C:
|
||||
|
||||
```powershell
|
||||
Register-IcingaServiceCheck `
|
||||
-CheckCommand 'Invoke-IcingaCheckUsedPartitionSpace' `
|
||||
-Arguments @{
|
||||
'-Include' = 'C';
|
||||
} `
|
||||
-Interval 15 `
|
||||
-TimeIndexes 1, 3, 5, 20, 60;
|
||||
```
|
||||
|
||||
##### Register Performance Counter Plugin with Multi-Values
|
||||
|
||||
Finally lets register our performance counter plugin to run every 30 seconds and collect average metrics for multiple, independent counters for 1, 3, 5, 10, 15 and 20 minutes:
|
||||
|
||||
```powershell
|
||||
Register-IcingaServiceCheck `
|
||||
-CheckCommand 'Invoke-IcingaCheckPerfCounter' `
|
||||
-Arguments @{
|
||||
'-PerfCounter' = @(
|
||||
'\Processor(*)\% Processor Time',
|
||||
'\Memory\% committed bytes in use',
|
||||
'\Memory\Available Bytes'
|
||||
);
|
||||
} `
|
||||
-Interval 15 `
|
||||
-TimeIndexes 1, 3, 5, 10, 15, 20;
|
||||
```
|
||||
|
||||
### Show Registered Service Checks
|
||||
|
||||
To fetch a list of currently registerd service checks, you can run the following command:
|
||||
|
||||
```powershell
|
||||
Show-IcingaRegisteredServiceChecks;
|
||||
```
|
||||
|
||||
```powershell
|
||||
[Notice]: Service Id: 1332191811682909517982372151451071972043015735175
|
||||
[Notice]:
|
||||
Name Value
|
||||
---- -----
|
||||
CheckCommand Invoke-IcingaCheckPerfCounter
|
||||
Interval 15
|
||||
Arguments @{-PerfCounter=System.Object[]}
|
||||
Id 1332191811682909517982372151451071972043015735175
|
||||
TimeIndexes {1, 3, 5, 10...}
|
||||
```
|
||||
|
||||
You will then receive a list of all configured plugins, including their configuration and `service id`.
|
||||
|
||||
### Unregister Service Checks
|
||||
|
||||
To unregister a service check from the daemon, you will require the `service id` of the registered service which you can get with `Show-IcingaRegisteredServiceChecks`. You can then use the id to unregister the service:
|
||||
|
||||
```powershell
|
||||
Unregister-IcingaServiceCheck -ServiceId 1332191811682909517982372151451071972043015735175;
|
||||
```
|
||||
|
||||
## Restart Icinga PowerShell Daemon
|
||||
|
||||
Finally to apply all your changes, we have to restart the Icinga for Windows Powershell Daemon
|
||||
|
||||
```powershell
|
||||
Restart-IcingaWindowsService;
|
||||
```
|
||||
73
doc/110-Installation/20-Install-Components.md
Normal file
73
doc/110-Installation/20-Install-Components.md
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
# Install Icinga for Windows Components
|
||||
|
||||
Icinga for Windows uses repositories, containing components which can be installed to extend the functionality of the monitoring and the capabilities of Icinga for Windows itself.
|
||||
|
||||
To use these repositories, you have to add them to your environment first.
|
||||
|
||||
## Add Official Icinga Repositories
|
||||
|
||||
By default, no repository is configured on Icinga for Windows after installation. The default repository `https://packages.icinga.com/IcingaForWindows/stable/ifw.repo.json` is added in case not being changed after a successful [IMC installation](03-Installation-with-IMC.md).
|
||||
|
||||
Of course you can also add the repositories manually.
|
||||
|
||||
### Add Official Icinga Stable Repository
|
||||
|
||||
For the latest stable releases, you can use this command:
|
||||
|
||||
```powershell
|
||||
Add-IcingaRepository `
|
||||
-Name 'Icinga Stable' `
|
||||
-RemotePath 'https://packages.icinga.com/IcingaForWindows/stable/ifw.repo.json';
|
||||
```
|
||||
|
||||
### Add Official Icinga Snapshot Repository
|
||||
|
||||
You can also add a snapshot repository to get the latest snapshot builds for components:
|
||||
|
||||
```powershell
|
||||
Add-IcingaRepository `
|
||||
-Name 'Icinga Snapshot' `
|
||||
-RemotePath 'https://packages.icinga.com/IcingaForWindows/snapshot/ifw.repo.json';
|
||||
```
|
||||
|
||||
### Add Official Icinga Development Repository for Components
|
||||
|
||||
In case you want to test out a certain feature which is currently in development, you can add a repository for this specific component including the development branch, the feature is developed in:
|
||||
|
||||
```powershell
|
||||
[string]$Project = 'icinga-powershell-framework';
|
||||
[string]$Branch = 'feature/adds_jea_profile_handling';
|
||||
|
||||
Add-IcingaRepository `
|
||||
-Name "$Project/$Branch" `
|
||||
-RemotePath "https://packages.icinga.com/IcingaForWindows/snapshot/$Project/$Branch/ifw.repo.json";
|
||||
```
|
||||
|
||||
Unlike other components, you can then install directly this development feature by using the branch name as version:
|
||||
|
||||
#### Code with variable placeholders
|
||||
|
||||
```powershell
|
||||
Install-IcingaComponent -Name $Project.Replace('icinga-powershell-', '') -Version $Branch -Snapshot -Force;
|
||||
```
|
||||
|
||||
#### Code with direct names
|
||||
|
||||
|
||||
```powershell
|
||||
Install-IcingaComponent -Name 'framework' -Version 'feature/adds_jea_profile_handling' -Snapshot -Force;
|
||||
```
|
||||
|
||||
### Add Own/Non-Official Repositories
|
||||
|
||||
You can create your [own repositories](../120-Repository-Manager/07-Create-Own-Repositories.md) or [sync existing repositories](../120-Repository-Manager/02-Sync-Repositories.md) as well, to install components from. Please have a look on the individual documentation pages.
|
||||
|
||||
## Install Component
|
||||
|
||||
You can use the [repository search](../120-Repository-Manager/04-Search-Repository.md) to lookup the repository and find components to install. Once you have the name, you can run the installation with the following command as example:
|
||||
|
||||
```powershell
|
||||
Install-IcingaComponent -Name 'plugins';
|
||||
```
|
||||
|
||||
You can find a detailed description of the command on the [install components documentation](../120-Repository-Manager/05-Install-Components.md).
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# Experimental: Forward Checks to internal API
|
||||
# API Check Forwader
|
||||
|
||||
With Icinga for Windows v1.4.0 we introduced a new experimental feature, allowing to forward executed checks to an internal REST-Api. This will move the check execution from the current PowerShell scope to an internal REST-Api daemon and endpoint and run the command with all provided arguments there.
|
||||
With Icinga for Windows v1.6.0 we introduced a new feature, allowing to forward executed checks to an internal REST-Api. This will move the check execution from the current PowerShell scope to an internal REST-Api daemon and endpoint and run the command with all provided arguments there.
|
||||
|
||||
This will reduce the performance impact on the CPU as well as lower the loading time of the Icinga PowerShell Framework, as only very basic core functionality is required for this.
|
||||
|
||||
|
|
@ -9,9 +9,9 @@ This will reduce the performance impact on the CPU as well as lower the loading
|
|||
To use this feature, you wil require the following
|
||||
|
||||
* Icinga Agent is certificates installed
|
||||
* Icinga for Windows v1.4.0 installed
|
||||
* Icinga for Windows v1.6.0 installed
|
||||
* [Icinga for Windows Service installed](https://icinga.com/docs/icinga-for-windows/latest/doc/service/01-Install-Service/)
|
||||
* Icinga for Windows v1.4.0 CheckCommand configuration applied (**Important:** Update your entire Windows environment to v1.4.0 before updating the Icinga configuration!)
|
||||
* Icinga for Windows v1.4.0+ CheckCommand configuration applied (**Important:** Update your entire Windows environment to v1.4.0+ before updating the Icinga configuration!)
|
||||
* [Icinga for Windows REST-Api](https://icinga.com/docs/icinga-for-windows/latest/restapi/doc/01-Introduction/)
|
||||
* [Icinga for Windows Api-Checks](https://github.com/Icinga/icinga-powershell-apichecks/blob/master/doc/01-Introduction.md)
|
||||
|
||||
|
|
@ -24,39 +24,29 @@ At first you will require to install both required modules, the [REST-Api](https
|
|||
Like any other Icinga for Windows component, you can use the Framework tools to install them:
|
||||
|
||||
```powershell
|
||||
Install-IcingaFrameworkComponent -Name restapi -Release;
|
||||
Install-IcingaComponent -Name restapi;
|
||||
```
|
||||
|
||||
```powershell
|
||||
Install-IcingaFrameworkComponent -Name apichecks -Release;
|
||||
Install-IcingaComponent -Name apichecks;
|
||||
```
|
||||
|
||||
If this does not work for you, please have a look on the [REST-Api installation guide](https://icinga.com/docs/icinga-for-windows/latest/restapi/doc/02-Installation/) and [Api-Checks installation guide](https://github.com/Icinga/icinga-powershell-apichecks/blob/master/doc/02-Installation.md).
|
||||
|
||||
### Icinga for Windows Service
|
||||
|
||||
To make this entire construct work, we will require to install the Icinga for Windows service. You can follow [this guide to install it manually](https://icinga.com/docs/icinga-for-windows/latest/doc/service/01-Install-Service/) if it is not already installed on your machine.
|
||||
To make this entire construct work, we will require to install the Icinga for Windows service. You can read more about this on the [background daemon page](05-Background-Daemons.md).
|
||||
|
||||
## Register Background Daemon
|
||||
|
||||
To access our REST-Api we have to register it as background daemon as mentioned inside the [REST-Api installation guide](https://icinga.com/docs/icinga-for-windows/latest/restapi/doc/02-Installation/#daemon-registration).
|
||||
|
||||
We can do this by running the command
|
||||
To access our REST-Api we have to register it as background daemon. We can do this by running the command:
|
||||
|
||||
```powershell
|
||||
Register-IcingaBackgroundDaemon -Command 'Start-IcingaWindowsRESTApi';
|
||||
```
|
||||
|
||||
By default, it will start listening on Port `5668` and use the Icinga Agents certificates for TLS encrypted communication. As long as the Windows firewall is not allowing access to this port, external communication is not possible.
|
||||
By default, it will start listening on Port `5668` on `localhost` and use the Icinga Agents certificates for TLS encrypted communication. As long as the Windows firewall is not allowing access to this port, external communication is not possible.
|
||||
|
||||
To modify any REST-Api arguments, please follow the [REST-Api installation guide](https://icinga.com/docs/icinga-for-windows/latest/restapi/doc/02-Installation/#daemon-registration).
|
||||
|
||||
Last but not least restart the Icinga for Windows service:
|
||||
|
||||
```powershell
|
||||
Restart-IcingaWindowsService;
|
||||
```
|
||||
|
||||
## Whitelist Check Commands
|
||||
|
||||
By default the Api-Checks module is rejecting every single request to execute commands, as long as they are not whitelisted.
|
||||
|
|
@ -87,7 +77,13 @@ Now as we configured our host with all required components, we simply require to
|
|||
Enable-IcingaFrameworkApiChecks;
|
||||
```
|
||||
|
||||
As long as the feature is enabled, the Icinga for Windows service is running, the REST-Api daemon is registered and both modules, [icinga-powershell-restapi](https://icinga.com/docs/icinga-for-windows/latest/restapi/doc/01-Introduction/) and [icinga-powershell-apichecks](https://github.com/Icinga/icinga-powershell-apichecks/blob/master/doc/01-Introduction.md) are installed, checks will be forwarded to the REST-Api and executed, if whitelisted.
|
||||
Last but not least restart the Icinga for Windows service:
|
||||
|
||||
```powershell
|
||||
Restart-IcingaWindowsService;
|
||||
```
|
||||
|
||||
As long as the feature is enabled, the Icinga for Windows service is running, the REST-Api daemon is registered and both modules, [icinga-powershell-restapi](https://icinga.com/docs/icinga-for-windows/latest/restapi/doc/01-Introduction/) and [icinga-powershell-apichecks](https://icinga.com/docs/icinga-for-windows/doc/icinga_for_windows_v1.6.0/apichecks/doc/01-Introduction/) are installed, checks will be forwarded to the REST-Api and executed, if whitelisted.
|
||||
|
||||
## Disable Api Check Feature
|
||||
|
||||
|
|
@ -1,76 +1,76 @@
|
|||
# Windows Terminal Integration
|
||||
|
||||
The new [Windows Terminal](https://www.microsoft.com/en-US/p/windows-terminal/9n0dx20hk701?activetab=pivot:overviewtab) provided by Microsoft offers a huge flexibility when it comes to working with different kind of shells. Not only does it finally support tabs and to split the current view into separate shells, it also allows the integration of pre-defined commands to execute for loading shells or environments.
|
||||
|
||||
In addition we can fully customize the apperance for our needs.
|
||||
|
||||
## Install the Icinga Shell Configuration
|
||||
|
||||
To install the Icinga Shell as native shell in your Windows Terminal dropdown, simply paste the following JSON under `profiles` -> `list`
|
||||
|
||||
```json
|
||||
{
|
||||
"fontFace" : "Consolas",
|
||||
"fontSize" : 12,
|
||||
"useAcrylic" : true,
|
||||
|
||||
"guid": "{fcd7a805-a41b-49f9-afee-9d17a2b76d42}",
|
||||
"name": "Icinga",
|
||||
"commandline" : "powershell.exe -noe -c \"&{ icinga; exit }\"",
|
||||
"hidden": false,
|
||||
"icon" : "ms-appdata:///roaming/icingawhite.png",
|
||||
|
||||
"acrylicOpacity" : 0.85,
|
||||
"backgroundImage" : "ms-appdata:///roaming/icingawhite.png",
|
||||
"backgroundImageOpacity" : 0.50,
|
||||
"backgroundImageStretchMode" : "none",
|
||||
"backgroundImageAlignment" : "topRight",
|
||||
"tabTitle": "Icinga for Windows - Loading",
|
||||
"colorScheme": "Icinga-Default"
|
||||
}
|
||||
```
|
||||
|
||||
As we are using the the custom theme `Icinga-Default` we will have to add this as well directly under the `schemes` section:
|
||||
|
||||
```json
|
||||
{
|
||||
"name" : "Icinga-Default",
|
||||
"cursorColor": "#FFFFFF",
|
||||
"selectionBackground": "#61C2FF",
|
||||
"background": "#04062A",
|
||||
"foreground" : "#EED7AA",
|
||||
// Arguments
|
||||
"black" : "#CC88DD",
|
||||
"brightBlack" : "#CC88DD",
|
||||
// Debug messages
|
||||
"blue" : "#A6A6A6",
|
||||
"brightBlue" : "#A6A6A6",
|
||||
// Strings
|
||||
"cyan" : "#39B5C6",
|
||||
"brightCyan" : "#39B5C6",
|
||||
"green" : "#31BB6C",
|
||||
"brightGreen" : "#31BB6C",
|
||||
"purple" : "#00607A",
|
||||
"brightPurple" : "#00607A",
|
||||
"red" : "#FF6B7A",
|
||||
"brightRed" : "#FF6B7A",
|
||||
// Commands
|
||||
"white" : "#FFFFFF",
|
||||
"brightWhite" : "#FFFFFF",
|
||||
// Commands/Console Input
|
||||
"yellow" : "#FFAA44",
|
||||
"brightYellow" : "#FFFFFF"
|
||||
}
|
||||
```
|
||||
|
||||
Last but not least we can setup our logo to appear on the top-right corner and as terminal icon. You can get the logo [here](https://icinga.com/docs/windows/latest/doc/images/03_windows_terminal/icingawhite.png).
|
||||
|
||||
To install it, copy it directly into the following path:
|
||||
|
||||
```text
|
||||
%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\RoamingState
|
||||
```
|
||||
|
||||
Now restart your Windows Terminal and enjoy the new look and the Icinga Shell integration!
|
||||
|
||||
|
||||
# Windows Terminal Integration
|
||||
|
||||
The new [Windows Terminal](https://www.microsoft.com/en-US/p/windows-terminal/9n0dx20hk701?activetab=pivot:overviewtab) provided by Microsoft offers a huge flexibility when it comes to working with different kind of shells. Not only does it finally support tabs and to split the current view into separate shells, it also allows the integration of pre-defined commands to execute for loading shells or environments.
|
||||
|
||||
In addition we can fully customize the apperance for our needs.
|
||||
|
||||
## Install the Icinga Shell Configuration
|
||||
|
||||
To install the Icinga Shell as native shell in your Windows Terminal dropdown, simply paste the following JSON under `profiles` -> `list`
|
||||
|
||||
```json
|
||||
{
|
||||
"fontFace" : "Consolas",
|
||||
"fontSize" : 12,
|
||||
"useAcrylic" : true,
|
||||
|
||||
"guid": "{fcd7a805-a41b-49f9-afee-9d17a2b76d42}",
|
||||
"name": "Icinga",
|
||||
"commandline" : "powershell.exe -noe -c \"&{ icinga; exit }\"",
|
||||
"hidden": false,
|
||||
"icon" : "ms-appdata:///roaming/icingawhite.png",
|
||||
|
||||
"acrylicOpacity" : 0.85,
|
||||
"backgroundImage" : "ms-appdata:///roaming/icingawhite.png",
|
||||
"backgroundImageOpacity" : 0.50,
|
||||
"backgroundImageStretchMode" : "none",
|
||||
"backgroundImageAlignment" : "topRight",
|
||||
"tabTitle": "Icinga for Windows - Loading",
|
||||
"colorScheme": "Icinga-Default"
|
||||
}
|
||||
```
|
||||
|
||||
As we are using the the custom theme `Icinga-Default` we will have to add this as well directly under the `schemes` section:
|
||||
|
||||
```json
|
||||
{
|
||||
"name" : "Icinga-Default",
|
||||
"cursorColor": "#FFFFFF",
|
||||
"selectionBackground": "#61C2FF",
|
||||
"background": "#04062A",
|
||||
"foreground" : "#EED7AA",
|
||||
// Arguments
|
||||
"black" : "#CC88DD",
|
||||
"brightBlack" : "#CC88DD",
|
||||
// Debug messages
|
||||
"blue" : "#A6A6A6",
|
||||
"brightBlue" : "#A6A6A6",
|
||||
// Strings
|
||||
"cyan" : "#39B5C6",
|
||||
"brightCyan" : "#39B5C6",
|
||||
"green" : "#31BB6C",
|
||||
"brightGreen" : "#31BB6C",
|
||||
"purple" : "#00607A",
|
||||
"brightPurple" : "#00607A",
|
||||
"red" : "#FF6B7A",
|
||||
"brightRed" : "#FF6B7A",
|
||||
// Commands
|
||||
"white" : "#FFFFFF",
|
||||
"brightWhite" : "#FFFFFF",
|
||||
// Commands/Console Input
|
||||
"yellow" : "#FFAA44",
|
||||
"brightYellow" : "#FFFFFF"
|
||||
}
|
||||
```
|
||||
|
||||
Last but not least we can setup our logo to appear on the top-right corner and as terminal icon. You can get the logo [here](../images/03_windows_terminal/icingawhite.png) (Right-Click the link and use `Save As`).
|
||||
|
||||
To install it, copy it directly into the following path:
|
||||
|
||||
```text
|
||||
%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\RoamingState
|
||||
```
|
||||
|
||||
Now restart your Windows Terminal and enjoy the new look and the Icinga Shell integration!
|
||||
|
||||
|
||||
41
doc/111-Updates-and-Uninstallation/01-Update-Environment.md
Normal file
41
doc/111-Updates-and-Uninstallation/01-Update-Environment.md
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
# Update Icinga for Windows
|
||||
|
||||
Before you update your environment, please have a look on the [upgrading docs](../100-General/01-Upgrading.md).
|
||||
|
||||
## Preparations
|
||||
|
||||
In general updating the entire Icinga for Windows environment is straight forward. If you are using official repositories, you can apply updates once a new package is available. For [own repositories](../120-Repository-Manager/07-Create-Own-Repositories.md) you will either have to [synchronize](../120-Repository-Manager/02-Sync-Repositories.md) them again or copy files manually there.
|
||||
|
||||
The command for updating is `Update-Icinga` and provides the following arguments:
|
||||
|
||||
| Argument | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| Name | String | Allows to define a specific component of being updated, instead of all of them |
|
||||
| Release | Switch | Default. Will update all components by using the release repositories |
|
||||
| Snapshot | Switch | This will allow to update all components by using snapshot repositories |
|
||||
| Confirm | Switch | Each component being updated will ask for a prompt if the package should be updated. Use this switch to confirm the installation and continue |
|
||||
| Force | Switch | Allows to re-install components in case the no new version was found with the name version |
|
||||
|
||||
## Updating all components
|
||||
|
||||
To update all components at once, you can simply run the following command:
|
||||
|
||||
```powershell
|
||||
Update-Icinga;
|
||||
```
|
||||
|
||||
This will lookup every single component, check if a new version is available and update it. In case you have [JEA](../130-JEA/01-JEA-Profiles.md) enabled, the profile is updated during the process as well.
|
||||
|
||||
## Updating specific component
|
||||
|
||||
To update specific components only, you can use the `-Name` argument:
|
||||
|
||||
```powershell
|
||||
Update-Icinga -Name 'plugins;
|
||||
```
|
||||
|
||||
You have to proceed this step then for all components you want to update.
|
||||
|
||||
## Pinned components
|
||||
|
||||
If you never want to update a certain component in the near future, you can also [pin components](../120-Repository-Manager/06-Pinning-Versions.md) a certain version. Once you run an update, the component will be ignored in case the pinned version is already installed.
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
# Uninstall Icinga for Windows Components
|
||||
|
||||
If you no longer require certain components on your system, you can uninstall them directly with the build-in command `Uninstall-IcingaComponent`. It includes the following arguments:
|
||||
|
||||
| Argument | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| Name | String | The name of the component to uninstall |
|
||||
| RemovePackageFiles | Switch | This argument will ensure that remaining files which are not PowerShell related will be removed as well. This includes for example the `ProgramData` folder of the Icinga Agent and the `service binary` for the Icinga for Windows service |
|
||||
|
||||
## Uninstall component
|
||||
|
||||
To uninstall a component, you simply specify the name and run the uninstall command:
|
||||
|
||||
```powershell
|
||||
Uninstall-IcingaComponent -Name 'plugins';
|
||||
```
|
||||
|
||||
The component will then be removed from the system. For the Icinga Agent for example, you can use the `-RemovePackageFiles` argument, to also remove the `ProgramData` folder which includes the certificates as example:
|
||||
|
||||
```powershell
|
||||
Uninstall-IcingaComponent -Name 'agent' -RemovePackageFiles;
|
||||
```
|
||||
|
||||
## Uninstall Icinga for Windows
|
||||
|
||||
To remove Icinga for Windows entirely from your system, you can run the command
|
||||
|
||||
```powershell
|
||||
Uninstall-IcingaForWindows;
|
||||
```
|
||||
|
||||
If you are using [JEA](../130-JEA/01-JEA-Profiles.md) and used a different user as managed user then `icinga`, you can specify this user with the `-IcingaUser` argument:
|
||||
|
||||
```powershell
|
||||
Uninstall-IcingaForWindows -IcingaUser 'MyCustomUser';
|
||||
```
|
||||
|
||||
Otherwise it will lookup the default user `icinga` and remove it, in case it is managed by Icinga for Windows.
|
||||
|
||||
To get rid of the confirmation message, simply add the `-Force` argument:
|
||||
|
||||
```powershell
|
||||
Uninstall-IcingaForWindows -Force;
|
||||
```
|
||||
|
||||
**Note:** This command will uninstall every single Icinga for Windows component, including the service, the Icinga Agent and the Icinga PowerShell Framework itself.
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Add Existing Repositories
|
||||
# Add Repositories
|
||||
|
||||
The easiest way to extend the functionality of Icinga for Windows, is by installing new components. Components are delivered by repositories you can add to your environment. This includes external repositories but also internal ones.
|
||||
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
In case you require local copies of repositories to frequently access them or to make a public repository available for systems unable to access public spaces, you can use `Sync-IcingaRepository`.
|
||||
|
||||
Like with [adding existing repositories](01-Add-Existing-Repositories.md), each synced repositories require a unique name you can set with `-Name`. The name will not interfere on how the sync works.
|
||||
Like with [adding existing repositories](01-Add-Repositories.md), each synced repositories require a unique name you can set with `-Name`. The name will not interfere on how the sync works.
|
||||
|
||||
## Available Arguments
|
||||
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# Enable/Disable/Remove Repositories
|
||||
# Manage Repositories
|
||||
|
||||
Besides [adding](01-Add-Existing-Repositories.md) and [syncing])(02-Sync-Repositories.md) of repositories, you can also `enable`, `disable` and `remove` repositories from your local machine.
|
||||
Besides [adding](01-Add-Repositories.md) and [syncing](02-Sync-Repositories.md) of repositories, you can also `enable`, `disable` and `remove` repositories from your local machine.
|
||||
|
||||
Please note that **removing** a repository will only remove the Icinga for Windows configuration and **not** the files on the disk. You have to do this step manually.
|
||||
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# Search Repository For Components
|
||||
# Search Repository
|
||||
|
||||
Once you [added](01-Add-Existing-Repositories.md) and/or [synced])(02-Sync-Repositories.md) your repositories, you can search them for available components.
|
||||
Once you [added](01-Add-Repositories.md) and/or [synced](02-Sync-Repositories.md) your repositories, you can search them for available components.
|
||||
|
||||
We can do this with the command `Search-IcingaRepository` and filter for a component `Name`, it's `Version` and if we want to include `Release` or `Snapshot` packages.
|
||||
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# Install Components
|
||||
|
||||
Once you [added](01-Add-Existing-Repositories.md) and/or [synced])(02-Sync-Repositories.md) your repositories and configured - if required - your [locks](05-Lock-Unlock-Components.md), we can start installing components.
|
||||
Once you [added](01-Add-Repositories.md) and/or [synced](02-Sync-Repositories.md) your repositories and configured - if required - your [locks](06-Pinning-Versions.md), we can start installing components.
|
||||
|
||||
For this we will use `Install-IcingaComponent`.
|
||||
|
||||
|
|
@ -11,7 +11,7 @@ For this we will use `Install-IcingaComponent`.
|
|||
| Argument | Type | Description |
|
||||
| --- |--- | --- |
|
||||
| Name | String | The name of the component you want to install |
|
||||
| Version | String | Specifies to install a specific version of the component, instead of the latest one found. Is ignored in case you added a [lock](05-Lock-Unlock-Components.md) to this component |
|
||||
| Version | String | Specifies to install a specific version of the component, instead of the latest one found. Is ignored in case you added a [lock](06-Pinning-Versions.md) to this component |
|
||||
| Release | Switch | Includes release versions only if set. If neither Release nor Snapshot is defined, it will enforce release |
|
||||
| Snapshot | Switch | Includes snapshots versions only if set. If neither Release nor Snapshot is defined, it will enforce release |
|
||||
| Confirm | Switch | Skips the message asking you if you want to install this component |
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Lock/Unlock Components
|
||||
# Pinning Versions
|
||||
|
||||
Sometimes you might require to `lock` certain components to a specific version. This means regardless of any version available, this component will not be updated or touched, unless the version it is locked to is not yet installed.
|
||||
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# Create Own Repositories
|
||||
|
||||
Besides [adding](01-Add-Existing-Repositories.md) and/or [syncing])(02-Sync-Repositories.md) already existing repositories, you can create entire new ones from scratch with `New-IcingaRepository`.
|
||||
Besides [adding](01-Add-Repositories.md) and/or [syncing](02-Sync-Repositories.md) already existing repositories, you can create entire new ones from scratch with `New-IcingaRepository`.
|
||||
|
||||
## Preparing Repositories
|
||||
|
||||
|
|
@ -45,4 +45,4 @@ This will ensure that you will require administrative privileges beforehand to m
|
|||
|
||||
## Getting Started
|
||||
|
||||
To get started with the Icinga for Windows JEA profile, have a look on the [installation guide](jea/01-Installation.md).
|
||||
To get started with the Icinga for Windows JEA profile, have a look on the [installation guide](02-Installation.md).
|
||||
|
|
@ -1,103 +1,103 @@
|
|||
# Manage Icinga Agent Features
|
||||
|
||||
The Icinga PowerShell Framework is shipping wish a bunch of Cmdlets to manage the Icinga Agent in a very easy way. This includes the managing for features enabled or disabled for the Icinga Agent.
|
||||
|
||||
**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.
|
||||
|
||||
## List Icinga Agent Features
|
||||
|
||||
To view a list of currently enabled and disabled features, you can use the command `Get-IcingaAgentFeatures`:
|
||||
|
||||
```powershell
|
||||
Get-IcingaAgentFeatures;
|
||||
```
|
||||
|
||||
```text
|
||||
Name Value
|
||||
---- -----
|
||||
Disabled {api, checker, debuglog, elasticsearch...}
|
||||
Enabled {mainlog}
|
||||
```
|
||||
|
||||
For a full list you can directly access each object:
|
||||
|
||||
```powershell
|
||||
(Get-IcingaAgentFeatures).Disabled;
|
||||
```
|
||||
|
||||
```text
|
||||
api
|
||||
checker
|
||||
debuglog
|
||||
elasticsearch
|
||||
gelf
|
||||
graphite
|
||||
influxdb
|
||||
notification
|
||||
opentsdb
|
||||
perfdata
|
||||
```
|
||||
|
||||
```powershell
|
||||
(Get-IcingaAgentFeatures).Enabled;
|
||||
```
|
||||
|
||||
```text
|
||||
mainlog
|
||||
```
|
||||
|
||||
## Enable Icinga Agent Features
|
||||
|
||||
To simply enable an Icinga Agent feature you can use `Enable-IcingaAgentFeature` followed by the name of the feature. In case the feature is already enabled, you will receive a notification and no change will be made:
|
||||
|
||||
```powershell
|
||||
Enable-IcingaAgentFeature -Feature api;
|
||||
```
|
||||
|
||||
```text
|
||||
[Notice]: Feature "api" was successfully enabled
|
||||
```
|
||||
|
||||
In case the feature is already enabled:
|
||||
|
||||
```text
|
||||
[Notice]: This feature is already enabled [api]
|
||||
```
|
||||
|
||||
Now restart your Icinga Agent to take the changes into effect:
|
||||
|
||||
```powershell
|
||||
Restart-IcingaService icinga2
|
||||
```
|
||||
|
||||
```text
|
||||
[Notice]: Restarting service "icinga2"
|
||||
```
|
||||
|
||||
## Disable Icinga Agent Features
|
||||
|
||||
To simply disable an Icinga Agent feature you can use `Disable-IcingaAgentFeature` followed by the name of the feature. In case the feature is already disabled, you will receive a notification and no change will be made:
|
||||
|
||||
```powershell
|
||||
Disable-IcingaAgentFeature -Feature api;
|
||||
```
|
||||
|
||||
```text
|
||||
[Notice]: Feature "api" was successfully disabled
|
||||
```
|
||||
|
||||
In case the feature is already enabled:
|
||||
|
||||
```text
|
||||
[Notice]: This feature is already disabled [api]
|
||||
```
|
||||
|
||||
Now restart your Icinga Agent to take the changes into effect:
|
||||
|
||||
```powershell
|
||||
Restart-IcingaService icinga2
|
||||
```
|
||||
|
||||
```text
|
||||
[Notice]: Restarting service "icinga2"
|
||||
```
|
||||
# Manage Icinga Agent Features
|
||||
|
||||
The Icinga PowerShell Framework is shipping wish a bunch of Cmdlets to manage the Icinga Agent in a very easy way. This includes the managing for features enabled or disabled for the Icinga Agent.
|
||||
|
||||
**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.
|
||||
|
||||
## List Icinga Agent Features
|
||||
|
||||
To view a list of currently enabled and disabled features, you can use the command `Get-IcingaAgentFeatures`:
|
||||
|
||||
```powershell
|
||||
Get-IcingaAgentFeatures;
|
||||
```
|
||||
|
||||
```text
|
||||
Name Value
|
||||
---- -----
|
||||
Disabled {api, checker, debuglog, elasticsearch...}
|
||||
Enabled {mainlog}
|
||||
```
|
||||
|
||||
For a full list you can directly access each object:
|
||||
|
||||
```powershell
|
||||
(Get-IcingaAgentFeatures).Disabled;
|
||||
```
|
||||
|
||||
```text
|
||||
api
|
||||
checker
|
||||
debuglog
|
||||
elasticsearch
|
||||
gelf
|
||||
graphite
|
||||
influxdb
|
||||
notification
|
||||
opentsdb
|
||||
perfdata
|
||||
```
|
||||
|
||||
```powershell
|
||||
(Get-IcingaAgentFeatures).Enabled;
|
||||
```
|
||||
|
||||
```text
|
||||
mainlog
|
||||
```
|
||||
|
||||
## Enable Icinga Agent Features
|
||||
|
||||
To simply enable an Icinga Agent feature you can use `Enable-IcingaAgentFeature` followed by the name of the feature. In case the feature is already enabled, you will receive a notification and no change will be made:
|
||||
|
||||
```powershell
|
||||
Enable-IcingaAgentFeature -Feature api;
|
||||
```
|
||||
|
||||
```text
|
||||
[Notice]: Feature "api" was successfully enabled
|
||||
```
|
||||
|
||||
In case the feature is already enabled:
|
||||
|
||||
```text
|
||||
[Notice]: This feature is already enabled [api]
|
||||
```
|
||||
|
||||
Now restart your Icinga Agent to take the changes into effect:
|
||||
|
||||
```powershell
|
||||
Restart-IcingaService icinga2
|
||||
```
|
||||
|
||||
```text
|
||||
[Notice]: Restarting service "icinga2"
|
||||
```
|
||||
|
||||
## Disable Icinga Agent Features
|
||||
|
||||
To simply disable an Icinga Agent feature you can use `Disable-IcingaAgentFeature` followed by the name of the feature. In case the feature is already disabled, you will receive a notification and no change will be made:
|
||||
|
||||
```powershell
|
||||
Disable-IcingaAgentFeature -Feature api;
|
||||
```
|
||||
|
||||
```text
|
||||
[Notice]: Feature "api" was successfully disabled
|
||||
```
|
||||
|
||||
In case the feature is already enabled:
|
||||
|
||||
```text
|
||||
[Notice]: This feature is already disabled [api]
|
||||
```
|
||||
|
||||
Now restart your Icinga Agent to take the changes into effect:
|
||||
|
||||
```powershell
|
||||
Restart-IcingaService icinga2
|
||||
```
|
||||
|
||||
```text
|
||||
[Notice]: Restarting service "icinga2"
|
||||
```
|
||||
|
|
@ -1,41 +1,41 @@
|
|||
# Read Icinga Agent Log/DebugLog
|
||||
|
||||
The Icinga PowerShell Framework is shipping wish a bunch of Cmdlets to manage the Icinga Agent in a very easy way. This includes reading the Icinga Agent log/debug log file.
|
||||
|
||||
**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.
|
||||
|
||||
## Read the default Icinga Agent log file
|
||||
|
||||
Icinga is writing current events by default in an own log file. The default location is `C:\ProgramData\icinga2\var\log\icinga2\icinga2.log`. To make it easier to read the log from the command line, we can use the `Read-IcingaAgentLogFile` Cmdlet which will update the command line for any new log line which is written by the Icinga Agent during the usage of the command:
|
||||
|
||||
```powershell
|
||||
Read-IcingaAgentLogFile;
|
||||
```
|
||||
|
||||
```text
|
||||
[2020-08-12 15:44:20 +0200] information/ConfigObject: Dumping program state to file 'C:\ProgramData\icinga2\var\lib\icinga2/icinga2.state'
|
||||
[2020-08-12 15:49:20 +0200] information/ConfigObject: Dumping program state to file 'C:\ProgramData\icinga2\var\lib\icinga2/icinga2.state'
|
||||
[2020-08-12 15:50:08 +0200] information/Application: Received request to shut down.
|
||||
[2020-08-12 15:50:08 +0200] information/Application: Shutting down...
|
||||
[2020-08-12 15:50:42 +0200] information/FileLogger: 'main-log' started.
|
||||
[2020-08-12 15:50:42 +0200] information/ConfigItem: Activated all objects.
|
||||
...
|
||||
```
|
||||
|
||||
## Read Icinga Agent debug log
|
||||
|
||||
As for the default log file, the Icinga Agent also writes more detailed entries into an own debug log. This has to be enabled as [Icinga Agent Feature](30-Manage-Icinga-Agent-Features.md) with the name `debuglog`. Once enabled, you can locate it on the default location `C:\ProgramData\icinga2\var\log\icinga2\debug.log` and access it with the Cmdlet `Read-IcingaAgentDebugLogFile`:
|
||||
|
||||
```powershell
|
||||
Read-IcingaAgentDebugLogFile;
|
||||
```
|
||||
|
||||
```text
|
||||
[2020-08-12 16:36:53 +0200] information/FileLogger: 'debug-file' started.
|
||||
[2020-08-12 16:36:53 +0200] information/FileLogger: 'main-log' started.
|
||||
[2020-08-12 16:36:53 +0200] information/ConfigItem: Activated all objects.
|
||||
[2020-08-12 16:36:53 +0200] notice/WorkQueue: Stopped WorkQueue threads for 'DaemonCommand::Run'
|
||||
[2020-08-12 16:36:53 +0200] notice/ApiListener: Updating object authority for local objects.
|
||||
[2020-08-12 16:36:53 +0200] debug/IcingaApplication: In IcingaApplication::Main()
|
||||
...
|
||||
```
|
||||
# Read Icinga Agent Log/DebugLog
|
||||
|
||||
The Icinga PowerShell Framework is shipping wish a bunch of Cmdlets to manage the Icinga Agent in a very easy way. This includes reading the Icinga Agent log/debug log file.
|
||||
|
||||
**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.
|
||||
|
||||
## Read the default Icinga Agent log file
|
||||
|
||||
Icinga is writing current events by default in an own log file. The default location is `C:\ProgramData\icinga2\var\log\icinga2\icinga2.log`. To make it easier to read the log from the command line, we can use the `Read-IcingaAgentLogFile` Cmdlet which will update the command line for any new log line which is written by the Icinga Agent during the usage of the command:
|
||||
|
||||
```powershell
|
||||
Read-IcingaAgentLogFile;
|
||||
```
|
||||
|
||||
```text
|
||||
[2020-08-12 15:44:20 +0200] information/ConfigObject: Dumping program state to file 'C:\ProgramData\icinga2\var\lib\icinga2/icinga2.state'
|
||||
[2020-08-12 15:49:20 +0200] information/ConfigObject: Dumping program state to file 'C:\ProgramData\icinga2\var\lib\icinga2/icinga2.state'
|
||||
[2020-08-12 15:50:08 +0200] information/Application: Received request to shut down.
|
||||
[2020-08-12 15:50:08 +0200] information/Application: Shutting down...
|
||||
[2020-08-12 15:50:42 +0200] information/FileLogger: 'main-log' started.
|
||||
[2020-08-12 15:50:42 +0200] information/ConfigItem: Activated all objects.
|
||||
...
|
||||
```
|
||||
|
||||
## Read Icinga Agent debug log
|
||||
|
||||
As for the default log file, the Icinga Agent also writes more detailed entries into an own debug log. This has to be enabled as [Icinga Agent Feature](04-Manage-Icinga-Agent-Features.md) with the name `debuglog`. Once enabled, you can locate it on the default location `C:\ProgramData\icinga2\var\log\icinga2\debug.log` and access it with the Cmdlet `Read-IcingaAgentDebugLogFile`:
|
||||
|
||||
```powershell
|
||||
Read-IcingaAgentDebugLogFile;
|
||||
```
|
||||
|
||||
```text
|
||||
[2020-08-12 16:36:53 +0200] information/FileLogger: 'debug-file' started.
|
||||
[2020-08-12 16:36:53 +0200] information/FileLogger: 'main-log' started.
|
||||
[2020-08-12 16:36:53 +0200] information/ConfigItem: Activated all objects.
|
||||
[2020-08-12 16:36:53 +0200] notice/WorkQueue: Stopped WorkQueue threads for 'DaemonCommand::Run'
|
||||
[2020-08-12 16:36:53 +0200] notice/ApiListener: Updating object authority for local objects.
|
||||
[2020-08-12 16:36:53 +0200] debug/IcingaApplication: In IcingaApplication::Main()
|
||||
...
|
||||
```
|
||||
|
|
@ -1,118 +1,118 @@
|
|||
# Test Icinga Agent Environment
|
||||
|
||||
The Icinga PowerShell Framework is shipping wish a bunch of Cmdlets to manage the Icinga Agent in a very easy way. This includes a test for the entire configuration and state of the Icinga Agent on the machine.
|
||||
|
||||
**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.
|
||||
|
||||
## Testing for errors
|
||||
|
||||
A very important part of an Agent is to ensure that it is running properly and no configuration error is present. In addition it is important that required directories are accessable by the service user the Icinga Agent is running with. For this you can use the Cmdlet `Test-IcingaAgent`:
|
||||
|
||||
```powershell
|
||||
Test-IcingaAgent;`
|
||||
```
|
||||
|
||||
Once executed you will receive a status of tests which are performed:
|
||||
|
||||
```text
|
||||
[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 writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Icinga Agent configuration is valid
|
||||
[Passed]: Icinga Agent debug log is disabled
|
||||
```
|
||||
|
||||
In order to make the Icinga Agent and the Icinga PowerShell Framework work properly, all above mentioned tests have to be in the state `Passed`. An exception is the `debug log` which will simply print a warning in case it is activated as this should be for short term tests only and not for production environments:
|
||||
|
||||
```text
|
||||
[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 writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Icinga Agent configuration is valid
|
||||
[Warning]: The debug log of the Icinga Agent is enabled. Please keep in mind to disable it once testing is done, as a huge amount of data is generated
|
||||
```
|
||||
|
||||
## Handling of errors
|
||||
|
||||
In addition for testing, the Icinga PowerShell Framework will suggest methods to fix certain issues. One example is the missing permission for service users to access required directories. In case the service user is not granted permissions, chances are high that the Icinga Agent service will not start:
|
||||
|
||||
```text
|
||||
[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 writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Failed]: Directory "C:\ProgramData\icinga2\var" is not accessible by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
\_ Please run the following command to fix this issue: Set-IcingaAcl -Directory 'C:\ProgramData\icinga2\var'
|
||||
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Icinga Agent configuration is valid
|
||||
[Passed]: Icinga Agent debug log is disabled
|
||||
```
|
||||
|
||||
As you can see, the mandatory directory `C:\ProgramData\icinga2\var` is not accessable by our `NT AUTHORITY\NetworkService` user. To resolve this, the Framework provides the Cmdlet `Set-IcingaAcl`. It will automatically set the correct permissions for a specific directory for the service user the Icinga Agent is running with:
|
||||
|
||||
```powershell
|
||||
Set-IcingaAcl -Directory 'C:\ProgramData\icinga2\var';
|
||||
```
|
||||
|
||||
```text
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
```
|
||||
|
||||
Now if we run the test again, the issue is resolved:
|
||||
|
||||
```text
|
||||
[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 writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Icinga Agent configuration is valid
|
||||
[Passed]: Icinga Agent debug log is disabled
|
||||
```
|
||||
|
||||
## Handling of configuration errors
|
||||
|
||||
Once in a while it might happen that your Icinga Agent configuration throws an error. By using `Test-IcingaAgent` you will be notified about this issue:
|
||||
|
||||
```powershell
|
||||
Test-IcingaAgent;`
|
||||
```
|
||||
|
||||
```text
|
||||
[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 writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Failed]: Icinga Agent configuration contains errors. Run this command for getting a detailed error report: "Test-IcingaAgentConfig -WriteStackTrace | Out-Null"
|
||||
[Passed]: Icinga Agent debug log is disabled
|
||||
```
|
||||
|
||||
As our configuration is for some reason broken we have to resolve this. The Icinga PowerShell Framework is not able to do this automatically, but it provides the toolset to easily address the source of the issue with the Cmdlet `Test-IcingaAgentConfig`:
|
||||
|
||||
```powershell
|
||||
Test-IcingaAgentConfig -WriteStackTrace | Out-Null;
|
||||
```
|
||||
|
||||
By using the argument `-WriteStackTrace` we will print the actual error ouptut from the Icinga Agent binary to our console for troubleshooting:
|
||||
|
||||
```text
|
||||
[2020-08-12 16:54:26 +0200] information/cli: Icinga application loader (version: v2.12.0)
|
||||
[2020-08-12 16:54:26 +0200] information/cli: Loading configuration file(s).
|
||||
[2020-08-12 16:54:26 +0200] critical/config: Error: syntax error, unexpected T_IDENTIFIER
|
||||
Location: in C:\ProgramData\icinga2\etc\icinga2/icinga2.conf: 20:6-20:11
|
||||
C:\ProgramData\icinga2\etc\icinga2/icinga2.conf(18): */
|
||||
C:\ProgramData\icinga2\etc\icinga2/icinga2.conf(19): include "zones.conf"
|
||||
C:\ProgramData\icinga2\etc\icinga2/icinga2.conf(20): this config is broken!
|
||||
^^^^^^
|
||||
C:\ProgramData\icinga2\etc\icinga2/icinga2.conf(21): /**
|
||||
C:\ProgramData\icinga2\etc\icinga2/icinga2.conf(22): * The Icinga Template Library (ITL) provides a number of useful templates
|
||||
|
||||
|
||||
[2020-08-12 16:54:26 +0200] critical/cli: Config validation failed. Re-run with 'icinga2 daemon -C' after fixing the config.
|
||||
```
|
||||
|
||||
As we are now having the path to our configuration error, we can start to resolve it.
|
||||
# Test Icinga Agent Environment
|
||||
|
||||
The Icinga PowerShell Framework is shipping wish a bunch of Cmdlets to manage the Icinga Agent in a very easy way. This includes a test for the entire configuration and state of the Icinga Agent on the machine.
|
||||
|
||||
**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.
|
||||
|
||||
## Testing for errors
|
||||
|
||||
A very important part of an Agent is to ensure that it is running properly and no configuration error is present. In addition it is important that required directories are accessable by the service user the Icinga Agent is running with. For this you can use the Cmdlet `Test-IcingaAgent`:
|
||||
|
||||
```powershell
|
||||
Test-IcingaAgent;
|
||||
```
|
||||
|
||||
Once executed you will receive a status of tests which are performed:
|
||||
|
||||
```text
|
||||
[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 writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Icinga Agent configuration is valid
|
||||
[Passed]: Icinga Agent debug log is disabled
|
||||
```
|
||||
|
||||
In order to make the Icinga Agent and the Icinga PowerShell Framework work properly, all above mentioned tests have to be in the state `Passed`. An exception is the `debug log` which will simply print a warning in case it is activated as this should be for short term tests only and not for production environments:
|
||||
|
||||
```text
|
||||
[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 writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Icinga Agent configuration is valid
|
||||
[Warning]: The debug log of the Icinga Agent is enabled. Please keep in mind to disable it once testing is done, as a huge amount of data is generated
|
||||
```
|
||||
|
||||
## Handling of errors
|
||||
|
||||
In addition for testing, the Icinga PowerShell Framework will suggest methods to fix certain issues. One example is the missing permission for service users to access required directories. In case the service user is not granted permissions, chances are high that the Icinga Agent service will not start:
|
||||
|
||||
```text
|
||||
[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 writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Failed]: Directory "C:\ProgramData\icinga2\var" is not accessible by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
\_ Please run the following command to fix this issue: Set-IcingaAcl -Directory 'C:\ProgramData\icinga2\var'
|
||||
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Icinga Agent configuration is valid
|
||||
[Passed]: Icinga Agent debug log is disabled
|
||||
```
|
||||
|
||||
As you can see, the mandatory directory `C:\ProgramData\icinga2\var` is not accessable by our `NT AUTHORITY\NetworkService` user. To resolve this, the Framework provides the Cmdlet `Set-IcingaAcl`. It will automatically set the correct permissions for a specific directory for the service user the Icinga Agent is running with:
|
||||
|
||||
```powershell
|
||||
Set-IcingaAcl -Directory 'C:\ProgramData\icinga2\var';
|
||||
```
|
||||
|
||||
```text
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
```
|
||||
|
||||
Now if we run the test again, the issue is resolved:
|
||||
|
||||
```text
|
||||
[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 writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Icinga Agent configuration is valid
|
||||
[Passed]: Icinga Agent debug log is disabled
|
||||
```
|
||||
|
||||
## Handling of configuration errors
|
||||
|
||||
Once in a while it might happen that your Icinga Agent configuration throws an error. By using `Test-IcingaAgent` you will be notified about this issue:
|
||||
|
||||
```powershell
|
||||
Test-IcingaAgent;`
|
||||
```
|
||||
|
||||
```text
|
||||
[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 writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writable by the Icinga Service User "NT AUTHORITY\NetworkService"
|
||||
[Failed]: Icinga Agent configuration contains errors. Run this command for getting a detailed error report: "Test-IcingaAgentConfig -WriteStackTrace | Out-Null"
|
||||
[Passed]: Icinga Agent debug log is disabled
|
||||
```
|
||||
|
||||
As our configuration is for some reason broken we have to resolve this. The Icinga PowerShell Framework is not able to do this automatically, but it provides the toolset to easily address the source of the issue with the Cmdlet `Test-IcingaAgentConfig`:
|
||||
|
||||
```powershell
|
||||
Test-IcingaAgentConfig -WriteStackTrace | Out-Null;
|
||||
```
|
||||
|
||||
By using the argument `-WriteStackTrace` we will print the actual error ouptut from the Icinga Agent binary to our console for troubleshooting:
|
||||
|
||||
```text
|
||||
[2020-08-12 16:54:26 +0200] information/cli: Icinga application loader (version: v2.12.0)
|
||||
[2020-08-12 16:54:26 +0200] information/cli: Loading configuration file(s).
|
||||
[2020-08-12 16:54:26 +0200] critical/config: Error: syntax error, unexpected T_IDENTIFIER
|
||||
Location: in C:\ProgramData\icinga2\etc\icinga2/icinga2.conf: 20:6-20:11
|
||||
C:\ProgramData\icinga2\etc\icinga2/icinga2.conf(18): */
|
||||
C:\ProgramData\icinga2\etc\icinga2/icinga2.conf(19): include "zones.conf"
|
||||
C:\ProgramData\icinga2\etc\icinga2/icinga2.conf(20): this config is broken!
|
||||
^^^^^^
|
||||
C:\ProgramData\icinga2\etc\icinga2/icinga2.conf(21): /**
|
||||
C:\ProgramData\icinga2\etc\icinga2/icinga2.conf(22): * The Icinga Template Library (ITL) provides a number of useful templates
|
||||
|
||||
|
||||
[2020-08-12 16:54:26 +0200] critical/cli: Config validation failed. Re-run with 'icinga2 daemon -C' after fixing the config.
|
||||
```
|
||||
|
||||
As we are now having the path to our configuration error, we can start to resolve it.
|
||||
|
|
@ -1,91 +1,91 @@
|
|||
# Run Icinga Agent as other Service User
|
||||
|
||||
The Icinga PowerShell Framework is shipping wish a bunch of Cmdlets to manage the Icinga Agent in a very easy way. This includes changing the current assigned Service User of the Icinga Agent to another one.
|
||||
|
||||
**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.
|
||||
|
||||
## Getting started
|
||||
|
||||
There are many reasons to run the Icinga Agent as a different user than the `NT AUTHORITY\NetworkService` user. One could be additional permissions required, another could be to run the Icinga Agent as own independent user which is entirely managed by your Active Directory or locally available.
|
||||
|
||||
For easier integration the Icinga PowerShell Framework is providing the Cmdlet `Set-IcingaAgentServiceUser`.
|
||||
|
||||
This Cmdlet ships with 4 arguments which not all of them are mandatory:
|
||||
|
||||
| Argument | Mandatory | Type | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| User | * | String | The name of the user the Icinga Agent should run with. Example: `NT AUTHORITY\NetworkService`, `mydomain\icinga`, `icinga` |
|
||||
| Password | | SecureString | If the defined user is requiring a password authentication, you define it as SecureString. This is not required for system users like `NT AUTHORITY\NetworkService` or `NT AUTHORITY\SYSTEM` |
|
||||
| Service | | String | The name of the service you want to modify. By default it is already set to `icinga2` |
|
||||
| SetPermission | | Switch | If the argument is set required permissions will be set. This includes directory permissions and the permissions for users to be allowed to run as service |
|
||||
|
||||
## Changing the Service User
|
||||
|
||||
Now as we are aware on how our Cmdlet `Set-IcingaAgentServiceUser` is working, we can use it to modify our service user.
|
||||
|
||||
### Example 1: Change Service User to LocalSystem
|
||||
|
||||
Our first example will simply change the service user from `NT AUTHORITY\NetworkService` to `NT AUTHORITY\SYSTEM`:
|
||||
|
||||
```powershell
|
||||
Set-IcingaAgentServiceUser -User 'NT AUTHORITY\SYSTEM' -SetPermission;
|
||||
```
|
||||
|
||||
```text
|
||||
[Notice]: The Icinga Service User already has permission to run as service
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\etc" is accessible and writable by the Icinga Service User "NT AUTHORITY\SYSTEM"
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writable by the Icinga Service User "NT AUTHORITY\SYSTEM"
|
||||
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writable by the Icinga Service User "NT AUTHORITY\SYSTEM"
|
||||
[Notice]: Service User successfully updated
|
||||
```
|
||||
|
||||
As we have set the argument `-SetPermission`, all directory and service permissions have been granted. As you can see the user already had permission to run as service which means no modification was done there.
|
||||
|
||||
### Example 2: Change Service User to local user with password
|
||||
|
||||
The most common requirement will be to set the Icinga Agent Service User to either a local or domain user. This will how ever require the usage of the `-Password` argument, which is a SecureString which can not simply be parsed.
|
||||
|
||||
Of course the Framework provides the Cmdlet `ConvertTo-IcingaSecureString` which will properly secure a regular String into a SecureString, might how ever not be secure enough for most environments. It will depend on how you apply the configuration.
|
||||
|
||||
To make things easier and we only require it locally and have not many machines to deploy, we can use the Windows `Get-Credential` Cmdlet to assist us. This will pop up a promt on where we can enter the `UserName` and `Password`:
|
||||
|
||||
```powershell
|
||||
$cred = Get-Credential -Message 'User credentials for icinga2 service:';
|
||||
Set-IcingaAgentServiceUser -User $cred.UserName -Password $cred.Password;
|
||||
```
|
||||
|
||||
In case we leave the `-SetPermission` argument aside, we simply get the update notification:
|
||||
|
||||
```text
|
||||
[Notice]: Service User successfully updated
|
||||
```
|
||||
|
||||
If we how ever run our Cmdlet `Test-IcingaAgent` (which is described [here](32-Test-Icinga-Agent-Environment.md)), we will receive some errors:
|
||||
|
||||
```text
|
||||
[Failed]: The specified user "icinga" is not allowed to run as service
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\etc" is accessible and writable by the Icinga Service User "icinga"
|
||||
[Failed]: Directory "C:\ProgramData\icinga2\var" is not accessible by the Icinga Service User "icinga"
|
||||
\_ Please run the following command to fix this issue: Set-IcingaAcl -Directory 'C:\ProgramData\icinga2\var'
|
||||
```
|
||||
|
||||
To simply resolve this, we can run the command from above again but this time with the `-SetPermission` argument:
|
||||
|
||||
```powershell
|
||||
$cred = Get-Credential -Message 'User credentials for icinga2 service:';
|
||||
Set-IcingaAgentServiceUser -User $cred.UserName -Password $cred.Password -SetPermission;
|
||||
```
|
||||
|
||||
```text
|
||||
[Passed]: The specified user "icinga" is allowed to run as service
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\etc" is accessible and writable by the Icinga Service User "icinga"
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writable by the Icinga Service User "icinga"
|
||||
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writable by the Icinga Service User "icinga"
|
||||
[Notice]: Service User successfully updated
|
||||
```
|
||||
|
||||
The same procedure applies to domain specific users. All you have to do is to provide the domain before the `Username`:
|
||||
|
||||
```text
|
||||
mydomain\Username
|
||||
```
|
||||
# Run Icinga Agent as other Service User
|
||||
|
||||
The Icinga PowerShell Framework is shipping wish a bunch of Cmdlets to manage the Icinga Agent in a very easy way. This includes changing the current assigned Service User of the Icinga Agent to another one.
|
||||
|
||||
**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.
|
||||
|
||||
## Getting started
|
||||
|
||||
There are many reasons to run the Icinga Agent as a different user than the `NT AUTHORITY\NetworkService` user. One could be additional permissions required, another could be to run the Icinga Agent as own independent user which is entirely managed by your Active Directory or locally available.
|
||||
|
||||
For easier integration the Icinga PowerShell Framework is providing the Cmdlet `Set-IcingaAgentServiceUser`.
|
||||
|
||||
This Cmdlet ships with 4 arguments which not all of them are mandatory:
|
||||
|
||||
| Argument | Mandatory | Type | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| User | * | String | The name of the user the Icinga Agent should run with. Example: `NT AUTHORITY\NetworkService`, `mydomain\icinga`, `icinga` |
|
||||
| Password | | SecureString | If the defined user is requiring a password authentication, you define it as SecureString. This is not required for system users like `NT AUTHORITY\NetworkService` or `NT AUTHORITY\SYSTEM` |
|
||||
| Service | | String | The name of the service you want to modify. By default it is already set to `icinga2` |
|
||||
| SetPermission | | Switch | If the argument is set required permissions will be set. This includes directory permissions and the permissions for users to be allowed to run as service |
|
||||
|
||||
## Changing the Service User
|
||||
|
||||
Now as we are aware on how our Cmdlet `Set-IcingaAgentServiceUser` is working, we can use it to modify our service user.
|
||||
|
||||
### Example 1: Change Service User to LocalSystem
|
||||
|
||||
Our first example will simply change the service user from `NT AUTHORITY\NetworkService` to `NT AUTHORITY\SYSTEM`:
|
||||
|
||||
```powershell
|
||||
Set-IcingaAgentServiceUser -User 'NT AUTHORITY\SYSTEM' -SetPermission;
|
||||
```
|
||||
|
||||
```text
|
||||
[Notice]: The Icinga Service User already has permission to run as service
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\etc" is accessible and writable by the Icinga Service User "NT AUTHORITY\SYSTEM"
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writable by the Icinga Service User "NT AUTHORITY\SYSTEM"
|
||||
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writable by the Icinga Service User "NT AUTHORITY\SYSTEM"
|
||||
[Notice]: Service User successfully updated
|
||||
```
|
||||
|
||||
As we have set the argument `-SetPermission`, all directory and service permissions have been granted. As you can see the user already had permission to run as service which means no modification was done there.
|
||||
|
||||
### Example 2: Change Service User to local user with password
|
||||
|
||||
The most common requirement will be to set the Icinga Agent Service User to either a local or domain user. This will how ever require the usage of the `-Password` argument, which is a SecureString which can not simply be parsed.
|
||||
|
||||
Of course the Framework provides the Cmdlet `ConvertTo-IcingaSecureString` which will properly secure a regular String into a SecureString, might how ever not be secure enough for most environments. It will depend on how you apply the configuration.
|
||||
|
||||
To make things easier and we only require it locally and have not many machines to deploy, we can use the Windows `Get-Credential` Cmdlet to assist us. This will pop up a promt on where we can enter the `UserName` and `Password`:
|
||||
|
||||
```powershell
|
||||
$cred = Get-Credential -Message 'User credentials for icinga2 service:';
|
||||
Set-IcingaAgentServiceUser -User $cred.UserName -Password $cred.Password;
|
||||
```
|
||||
|
||||
In case we leave the `-SetPermission` argument aside, we simply get the update notification:
|
||||
|
||||
```text
|
||||
[Notice]: Service User successfully updated
|
||||
```
|
||||
|
||||
If we how ever run our Cmdlet `Test-IcingaAgent` (which is described [here](06-Test-Icinga-Installation.md)), we will receive some errors:
|
||||
|
||||
```text
|
||||
[Failed]: The specified user "icinga" is not allowed to run as service
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\etc" is accessible and writable by the Icinga Service User "icinga"
|
||||
[Failed]: Directory "C:\ProgramData\icinga2\var" is not accessible by the Icinga Service User "icinga"
|
||||
\_ Please run the following command to fix this issue: Set-IcingaAcl -Directory 'C:\ProgramData\icinga2\var'
|
||||
```
|
||||
|
||||
To simply resolve this, we can run the command from above again but this time with the `-SetPermission` argument:
|
||||
|
||||
```powershell
|
||||
$cred = Get-Credential -Message 'User credentials for icinga2 service:';
|
||||
Set-IcingaAgentServiceUser -User $cred.UserName -Password $cred.Password -SetPermission;
|
||||
```
|
||||
|
||||
```text
|
||||
[Passed]: The specified user "icinga" is allowed to run as service
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\etc" is accessible and writable by the Icinga Service User "icinga"
|
||||
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writable by the Icinga Service User "icinga"
|
||||
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writable by the Icinga Service User "icinga"
|
||||
[Notice]: Service User successfully updated
|
||||
```
|
||||
|
||||
The same procedure applies to domain specific users. All you have to do is to provide the domain before the `Username`:
|
||||
|
||||
```text
|
||||
mydomain\Username
|
||||
```
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
Developer Guide: Custom Daemons
|
||||
===
|
||||
|
||||
By [installing the PowerShell Framework as service](../service/01-Install-Service.md) you have the possibility to [register custom daemons](../service/02-Register-Daemons.md) which are executed in the background. This developer guide article will assist you in creating custom daemons.
|
||||
By installing the PowerShell Framework as service you have the possibility to [register custom daemons](../110-Installation/05-Background-Daemons.md) which are executed in the background. This developer guide article will assist you in creating custom daemons.
|
||||
|
||||
Creating A New Module
|
||||
---
|
||||
|
|
@ -31,7 +31,7 @@ Testing The Module
|
|||
|
||||
Once the modules files are created and unblocked, we can start testing if the autoloader is properly working and our module is detected.
|
||||
|
||||
For this open the file `icinga-powershell-agentservice.psm1` in your prefered editor and add the following code snippet
|
||||
For this open the file `icinga-powershell-agentservice.psm1` in your preferred editor and add the following code snippet
|
||||
|
||||
```powershell
|
||||
function Test-MyIcingaAgentServiceCommand()
|
||||
|
|
@ -53,7 +53,7 @@ inside your console prompt. After that try again to execute the command `Test-My
|
|||
Create A New function
|
||||
---
|
||||
|
||||
Once everything is working properly we can create our starting function we will later use for [registering our daemon](../service/02-Register-Daemons.md).
|
||||
Once everything is working properly we can create our starting function we will later use for [registering our daemon](../110-Installation/05-Background-Daemons.md).
|
||||
|
||||
For naming guidelines we will have to begin with the `Start` naming and an identifier of what are going to achieve with our daemon. In our example we will frequently check if the Icinga 2 agent service is active and running. In case it failed, we will restart the service.
|
||||
|
||||
|
|
@ -424,7 +424,7 @@ function Start-IcingaAgentServiceTest()
|
|||
Register Our Daemon
|
||||
---
|
||||
|
||||
Now as our daemon is ready we can simply [register it](../service/02-Register-Daemons.md) by using the Framework commands
|
||||
Now as our daemon is ready we can simply [register it](../110-Installation/05-Background-Daemons.md) by using the Framework commands
|
||||
|
||||
```powershell
|
||||
Register-IcingaBackgroundDaemon -Command 'Start-IcingaAgentServiceTest';
|
||||
|
|
@ -123,4 +123,4 @@ A huge benefit of the implementation we choose is the possibility to export the
|
|||
Publish-IcingaEventlogDocumentation -Namespace 'Framework' -OutFile 'C:\users\public\eventlog-doc.md':
|
||||
```
|
||||
|
||||
An example on how the exported result looks like can be found on the [Framework Eventlog Documentation](https://icinga.com/docs/windows/latest/doc/20-Eventlog/).
|
||||
An example on how the exported result looks like can be found on the [Framework Eventlog Documentation](../100-General/20-Eventlog.md).
|
||||
|
|
@ -32,6 +32,14 @@ icinga { Write-IcingaConsoleError 'Hello from Icinga' }
|
|||
|
||||
The command will load the entire Framework and all components and output the result of your code.
|
||||
|
||||
## Rebuilding Framework Cache
|
||||
|
||||
Starting with Icinga for Windows v1.6.0, a caching is natively implement to speed-up the loading of the Framework. In case modifications are done on the Framework itself, you can use the `icinga` alias together with the argument `-RebuildCache` and your code snippet to rebuild the cache and run your code within the updated state.
|
||||
|
||||
```powershell
|
||||
icinga { Write-IcingaConsoleError 'Hello from Icinga' } -RebuildCache
|
||||
```
|
||||
|
||||
## Improved Shell handling
|
||||
|
||||
In addition to above mentioned example, you can not only execute code snippets but also start a new PowerShell with the entire Framework loaded. The benefit of this is, that while mostly an `exit` should be handled, it might still cause your shell to close. With the `icinga` command, you will only close an additional shell and keep your own shell open:
|
||||
|
|
@ -1,17 +1,17 @@
|
|||
# Install the Framework with PowerShell Gallery
|
||||
|
||||
PowerShell Gallery provides a collection of PowerShell modules and scripts which can easily be installed on target machines. For a further description, please have a look on the [PowerShell Gallery website](https://www.powershellgallery.com/).
|
||||
|
||||
## Getting Started
|
||||
|
||||
Icinga is providing PowerShell Gallery packages within the [Icinga Profile](https://www.powershellgallery.com/profiles/Icinga) for the Framework itself and other related components.
|
||||
|
||||
To install the Icinga PowerShell Framework you can simply use `Install-Module` in case it is available and configured on your system:
|
||||
|
||||
```powershell
|
||||
Install-Module -Name icinga-powershell-framework;
|
||||
```
|
||||
|
||||
## Execute the Icinga Agent installation wizard
|
||||
|
||||
Once the entire Framework is installed and the module is runnable, you can start the Icinga Agent installation wizard. Please follow the [Icinga Agent Wizard](04-Icinga-Agent-Wizard.md) guide for examples and usage.
|
||||
# Install the Framework with PowerShell Gallery
|
||||
|
||||
PowerShell Gallery provides a collection of PowerShell modules and scripts which can easily be installed on target machines. For a further description, please have a look on the [PowerShell Gallery website](https://www.powershellgallery.com/).
|
||||
|
||||
## Getting Started
|
||||
|
||||
Icinga is providing PowerShell Gallery packages within the [Icinga Profile](https://www.powershellgallery.com/profiles/Icinga) for the Framework itself and other related components.
|
||||
|
||||
To install the Icinga PowerShell Framework you can simply use `Install-Module` in case it is available and configured on your system:
|
||||
|
||||
```powershell
|
||||
Install-Module -Name icinga-powershell-framework;
|
||||
```
|
||||
|
||||
## Execute the Icinga Agent installation wizard
|
||||
|
||||
Once the entire Framework is installed and the module is runnable, you can start the Icinga Agent installation wizard. Please follow the [Icinga Agent Wizard](04-Icinga-Agent-Wizard.md) guide for examples and usage.
|
||||
|
|
@ -1,97 +1,97 @@
|
|||
# Icinga Agent installation wizard
|
||||
|
||||
It doesn't matter if you installed the Icinga PowerShell Framework with he [Kickstart Script](01-Kickstart-Script.md) or [Manually](02-Manual-Installation.md). In the and you can use the Icinga Agent installation wizard to configure the system additional, to install the Agent and deploy plugins as well install the Icinga PowerShell Service.
|
||||
|
||||
## Start the Icinga Agent wizard
|
||||
|
||||
To start the Icinga Agent installation wizard you will have to open a PowerShell as Administrator first and enter
|
||||
|
||||
```powershell
|
||||
Use-Icinga
|
||||
```
|
||||
|
||||
*Note:* Starting with Icinga PowerShell Framework `1.2.0` you can simply type `icinga` to open an Icinga PowerShell Framework shell,
|
||||
|
||||
Once the command is executed, the Framework and all required components are loaded. To get started, we can now run
|
||||
|
||||
```powershell
|
||||
Start-IcingaAgentInstallWizard;
|
||||
```
|
||||
|
||||
The wizard will ask a bunch of questions, for example if you are using the semi-automated Director Self-Service API or if you configure everything by yourself.
|
||||
|
||||
Depending on how you configure the system, there might different questions occur. The goal of the wizard is to cover most of the possible configurations available for the Icinga Agent. This includes
|
||||
|
||||
* How your certificates are generated
|
||||
* If you Icinga Agent or the Master/Satellites are establishing the connection
|
||||
* Definition of the service user the Icinga Agent will run with
|
||||
* Ensuring that the Icinga Agent with the provided configuration and settings is able to start and everything is valid
|
||||
|
||||
Once you completed the wizard you are asked if the configuration is correct and if you want to execute the configuration. In any way, you are always printed the configuration command with your configured settings.
|
||||
This command can be executed on `any` Windows machine which has the Icinga PowerShell Framework installed. It contains the entire configuration for the system. Of course you can modify the values to match certain network zones or requirements.
|
||||
|
||||
You can find the Self Service API Key in the Agent tab of a Host Template in Icinga Director. You can find the Ticket number in the Agent tab of a Host.
|
||||
|
||||
## Configuration Command Examples
|
||||
|
||||
Below you will find some examples for different kind of configuration commands which can be executed to configure the Icinga Agent and to install plugins.
|
||||
|
||||
**Important Note:** Each argument represents a corresponding question during the wizard. Some questions will result in more than one argument being set. In general it is not required to set every single available argument, as some of them are only required if certain configurations are set.
|
||||
|
||||
### Config Example 1: Director Self-Service
|
||||
|
||||
This example will use the Icinga Director Self-Service API and use a host template key to register the current machine within the Icinga Director and fetch the correct configuration for the host. In addition we will not override any provided variables and convert our Icinga endpoint configuration to actual IPs. For example if our Icinga parent node is registered with address `icinga2-master.example.com` the FQDN will automatically be translated to the referring IP address. This is important as in case of a DNS failure we want to ensure the monitoring is still working properly. In addition we leave the Ticket handling empty as the Self-Service will take care of it and we neither want to install the Plugins nor the Icinga PowerShell Service.
|
||||
|
||||
Last but not least we want to directly run the installer.
|
||||
|
||||
```powershell
|
||||
Start-IcingaAgentInstallWizard -SelfServiceAPIKey '56756378658n56t85679765n97649m7649m76' -UseDirectorSelfService 1 -DirectorUrl 'https://example.com/icingaweb2/director/' -OverrideDirectorVars 0 -ConvertEndpointIPConfig 1 -Ticket '' -EmptyTicket 1 -InstallFrameworkPlugins 0 -InstallFrameworkService 0 -RunInstaller;
|
||||
```
|
||||
|
||||
### Config Example 2: Director Self-Service with Argument override
|
||||
|
||||
This is the same example as above, but this time we will override our `CAEndpoint` for the Icinga certificate authority:
|
||||
|
||||
```powershell
|
||||
Start-IcingaAgentInstallWizard -SelfServiceAPIKey '56756378658n56t85679765n97649m7649m76' -UseDirectorSelfService 1 -DirectorUrl 'https://example.com/icingaweb2/director/' -OverrideDirectorVars 0 -ConvertEndpointIPConfig 1 -Ticket '' -EmptyTicket 1 -InstallFrameworkPlugins 0 -InstallFrameworkService 0 -CAEndpoint 'icinga2-ca.example.com' -RunInstaller;
|
||||
```
|
||||
|
||||
### Config Example 3: Configure Icinga Agent to connect to Parents and use Cert-Proxy
|
||||
|
||||
This example will configure the Icinga Agent to use the local hostname including the FQDN as lower case, download the latest stable version of the Icinga Agent from packages.icinga.com and connect to the parent nodes. As we are not providing a `Ticket` with the installation, we will later have to sign the request on our Icinga master with `icinga2 ca sign <request>` (to get all pending requests you can use `icinga2 ca list` on your Icinga master).
|
||||
|
||||
Like before, we are not installing the Icinga PowerShell Service or the plugins in this step.
|
||||
|
||||
```powershell
|
||||
Start-IcingaAgentInstallWizard -UseDirectorSelfService 0 -AutoUseFQDN 1 -AutoUseHostname 0 -LowerCase 1 -UpperCase 0 -AllowVersionChanges 1 -UpdateAgent 1 -AgentVersion 'release' -PackageSource 'https://packages.icinga.com/windows/' -Endpoints icinga2a,icinga2b -CAPort 5665 -AcceptConnections 0 -AddFirewallRule 0 -ConvertEndpointIPConfig 1 -EndpointConnections 192.168.0.1,192.168.0.2 -ParentZone master -AddDirectorGlobal 1 -AddGlobalTemplates 1 -GlobalZones @() -CAEndpoint 192.168.0.1 -Ticket '' -EmptyTicket 1 -ServiceUser 'NT Authority\NetworkService' -InstallFrameworkPlugins 0 -InstallFrameworkService 0 -RunInstaller;
|
||||
```
|
||||
|
||||
### Config Example 4: Install the Icinga PowerShell Service during wizard run
|
||||
|
||||
Of course you can install the Icinga PowerShell Service directly during the runtime of the wizard. To do so, take the above examples and `replace` the argument `-InstallFrameworkService 0` with:
|
||||
|
||||
```powershell
|
||||
-InstallFrameworkService 1 -FrameworkServiceUrl 'https://github.com/Icinga/icinga-powershell-service/releases/download/v1.1.0/icinga-service-v1.1.0.zip' -ServiceDirectory 'C:\Program Files\icinga-framework-service\'
|
||||
```
|
||||
|
||||
**Explanation:**
|
||||
|
||||
The argument `FrameworkServiceUrl` is asking for a path pointing to the `.zip` file which contains the service binary. The file can either be located on a web resource or a local/network share. The `ServiceDirectory` argument will point to the target on where the `.exe` file itself is being extracted to. This location is then being used to register the Windows Service object to which is later executed. In general there is an additional argument `ServiceBin` available which will define the direct path to the service binary. This can be left empty how ever of the official `.zip` file of Icinga for the service package is used.
|
||||
|
||||
### Config Example 5: Install the Icinga Plugins during wizard run
|
||||
|
||||
Just like the service you can also directly run the installation of the plugins during the wizard runtime. For this you will have to replace `-InstallFrameworkPlugins 0` of the above mentioned examples with:
|
||||
|
||||
```powershell
|
||||
-InstallFrameworkPlugins 1 -PluginsUrl 'https://github.com/Icinga/icinga-powershell-plugins/archive/master.zip'
|
||||
```
|
||||
|
||||
Just like the service binary, you can specify a different path to the `.zip` file of the plugins. This can either be a web resource or a local/network share path.
|
||||
|
||||
## Install Icinga PowerShell Components
|
||||
|
||||
Besides installing the Icinga PowerShell Plugins during the installation, you can also install them with a dedicated Cmdlet: `Install-IcingaFrameworkComponent`
|
||||
|
||||
This Cmdlet is using a namespace to ensure that the location is handled and each resource can be accessed properly. As with the above mentioned service binary and plugin repository, you can specify a custom location for the `.zip` file include the name of of the repository.
|
||||
|
||||
For more details please have a look on the [Icinga Plugin Installation Guide](https://icinga.com/docs/windows/latest/plugins/doc/02-Installation/). This does also apply to every other Icinga Framework Component in the future.
|
||||
# Icinga Agent installation wizard
|
||||
|
||||
It doesn't matter if you installed the Icinga PowerShell Framework with he [Kickstart Script](01-Kickstart-Script.md) or [Manually](02-Manual-Installation.md). In the and you can use the Icinga Agent installation wizard to configure the system additional, to install the Agent and deploy plugins as well install the Icinga PowerShell Service.
|
||||
|
||||
## Start the Icinga Agent wizard
|
||||
|
||||
To start the Icinga Agent installation wizard you will have to open a PowerShell as Administrator first and enter
|
||||
|
||||
```powershell
|
||||
Use-Icinga
|
||||
```
|
||||
|
||||
*Note:* Starting with Icinga PowerShell Framework `1.2.0` you can simply type `icinga` to open an Icinga PowerShell Framework shell,
|
||||
|
||||
Once the command is executed, the Framework and all required components are loaded. To get started, we can now run
|
||||
|
||||
```powershell
|
||||
Start-IcingaAgentInstallWizard;
|
||||
```
|
||||
|
||||
The wizard will ask a bunch of questions, for example if you are using the semi-automated Director Self-Service API or if you configure everything by yourself.
|
||||
|
||||
Depending on how you configure the system, there might different questions occur. The goal of the wizard is to cover most of the possible configurations available for the Icinga Agent. This includes
|
||||
|
||||
* How your certificates are generated
|
||||
* If you Icinga Agent or the Master/Satellites are establishing the connection
|
||||
* Definition of the service user the Icinga Agent will run with
|
||||
* Ensuring that the Icinga Agent with the provided configuration and settings is able to start and everything is valid
|
||||
|
||||
Once you completed the wizard you are asked if the configuration is correct and if you want to execute the configuration. In any way, you are always printed the configuration command with your configured settings.
|
||||
This command can be executed on `any` Windows machine which has the Icinga PowerShell Framework installed. It contains the entire configuration for the system. Of course you can modify the values to match certain network zones or requirements.
|
||||
|
||||
You can find the Self Service API Key in the Agent tab of a Host Template in Icinga Director. You can find the Ticket number in the Agent tab of a Host.
|
||||
|
||||
## Configuration Command Examples
|
||||
|
||||
Below you will find some examples for different kind of configuration commands which can be executed to configure the Icinga Agent and to install plugins.
|
||||
|
||||
**Important Note:** Each argument represents a corresponding question during the wizard. Some questions will result in more than one argument being set. In general it is not required to set every single available argument, as some of them are only required if certain configurations are set.
|
||||
|
||||
### Config Example 1: Director Self-Service
|
||||
|
||||
This example will use the Icinga Director Self-Service API and use a host template key to register the current machine within the Icinga Director and fetch the correct configuration for the host. In addition we will not override any provided variables and convert our Icinga endpoint configuration to actual IPs. For example if our Icinga parent node is registered with address `icinga2-master.example.com` the FQDN will automatically be translated to the referring IP address. This is important as in case of a DNS failure we want to ensure the monitoring is still working properly. In addition we leave the Ticket handling empty as the Self-Service will take care of it and we neither want to install the Plugins nor the Icinga PowerShell Service.
|
||||
|
||||
Last but not least we want to directly run the installer.
|
||||
|
||||
```powershell
|
||||
Start-IcingaAgentInstallWizard -SelfServiceAPIKey '56756378658n56t85679765n97649m7649m76' -UseDirectorSelfService 1 -DirectorUrl 'https://example.com/icingaweb2/director/' -OverrideDirectorVars 0 -ConvertEndpointIPConfig 1 -Ticket '' -EmptyTicket 1 -InstallFrameworkPlugins 0 -InstallFrameworkService 0 -RunInstaller;
|
||||
```
|
||||
|
||||
### Config Example 2: Director Self-Service with Argument override
|
||||
|
||||
This is the same example as above, but this time we will override our `CAEndpoint` for the Icinga certificate authority:
|
||||
|
||||
```powershell
|
||||
Start-IcingaAgentInstallWizard -SelfServiceAPIKey '56756378658n56t85679765n97649m7649m76' -UseDirectorSelfService 1 -DirectorUrl 'https://example.com/icingaweb2/director/' -OverrideDirectorVars 0 -ConvertEndpointIPConfig 1 -Ticket '' -EmptyTicket 1 -InstallFrameworkPlugins 0 -InstallFrameworkService 0 -CAEndpoint 'icinga2-ca.example.com' -RunInstaller;
|
||||
```
|
||||
|
||||
### Config Example 3: Configure Icinga Agent to connect to Parents and use Cert-Proxy
|
||||
|
||||
This example will configure the Icinga Agent to use the local hostname including the FQDN as lower case, download the latest stable version of the Icinga Agent from packages.icinga.com and connect to the parent nodes. As we are not providing a `Ticket` with the installation, we will later have to sign the request on our Icinga master with `icinga2 ca sign <request>` (to get all pending requests you can use `icinga2 ca list` on your Icinga master).
|
||||
|
||||
Like before, we are not installing the Icinga PowerShell Service or the plugins in this step.
|
||||
|
||||
```powershell
|
||||
Start-IcingaAgentInstallWizard -UseDirectorSelfService 0 -AutoUseFQDN 1 -AutoUseHostname 0 -LowerCase 1 -UpperCase 0 -AllowVersionChanges 1 -UpdateAgent 1 -AgentVersion 'release' -PackageSource 'https://packages.icinga.com/windows/' -Endpoints icinga2a,icinga2b -CAPort 5665 -AcceptConnections 0 -AddFirewallRule 0 -ConvertEndpointIPConfig 1 -EndpointConnections 192.168.0.1,192.168.0.2 -ParentZone master -AddDirectorGlobal 1 -AddGlobalTemplates 1 -GlobalZones @() -CAEndpoint 192.168.0.1 -Ticket '' -EmptyTicket 1 -ServiceUser 'NT Authority\NetworkService' -InstallFrameworkPlugins 0 -InstallFrameworkService 0 -RunInstaller;
|
||||
```
|
||||
|
||||
### Config Example 4: Install the Icinga PowerShell Service during wizard run
|
||||
|
||||
Of course you can install the Icinga PowerShell Service directly during the runtime of the wizard. To do so, take the above examples and `replace` the argument `-InstallFrameworkService 0` with:
|
||||
|
||||
```powershell
|
||||
-InstallFrameworkService 1 -FrameworkServiceUrl 'https://github.com/Icinga/icinga-powershell-service/releases/download/v1.1.0/icinga-service-v1.1.0.zip' -ServiceDirectory 'C:\Program Files\icinga-framework-service\'
|
||||
```
|
||||
|
||||
**Explanation:**
|
||||
|
||||
The argument `FrameworkServiceUrl` is asking for a path pointing to the `.zip` file which contains the service binary. The file can either be located on a web resource or a local/network share. The `ServiceDirectory` argument will point to the target on where the `.exe` file itself is being extracted to. This location is then being used to register the Windows Service object to which is later executed. In general there is an additional argument `ServiceBin` available which will define the direct path to the service binary. This can be left empty how ever of the official `.zip` file of Icinga for the service package is used.
|
||||
|
||||
### Config Example 5: Install the Icinga Plugins during wizard run
|
||||
|
||||
Just like the service you can also directly run the installation of the plugins during the wizard runtime. For this you will have to replace `-InstallFrameworkPlugins 0` of the above mentioned examples with:
|
||||
|
||||
```powershell
|
||||
-InstallFrameworkPlugins 1 -PluginsUrl 'https://github.com/Icinga/icinga-powershell-plugins/archive/master.zip'
|
||||
```
|
||||
|
||||
Just like the service binary, you can specify a different path to the `.zip` file of the plugins. This can either be a web resource or a local/network share path.
|
||||
|
||||
## Install Icinga PowerShell Components
|
||||
|
||||
Besides installing the Icinga PowerShell Plugins during the installation, you can also install them with a dedicated Cmdlet: `Install-IcingaFrameworkComponent`
|
||||
|
||||
This Cmdlet is using a namespace to ensure that the location is handled and each resource can be accessed properly. As with the above mentioned service binary and plugin repository, you can specify a custom location for the `.zip` file include the name of of the repository.
|
||||
|
||||
For more details please have a look on the [Icinga Plugin Installation Guide](https://icinga.com/docs/windows/latest/plugins/doc/02-Installation/). This does also apply to every other Icinga Framework Component in the future.
|
||||
|
|
@ -4,7 +4,7 @@ Icinga for Windows ships with a bunch of Cmdlets, allowing users to manage the e
|
|||
|
||||
## 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`.
|
||||
To update the Framework it is not required to run the [installation process](../110-Installation/01-Getting-Started.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
|
||||
|
||||
|
|
@ -1,83 +0,0 @@
|
|||
# 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';
|
||||
```
|
||||
|
|
@ -1,265 +0,0 @@
|
|||
# Automated Framework and Component deployment
|
||||
|
||||
Installing and configuring the Icinga PowerShell Framework can be done by many different ways. A detailled overview is described in the [installation guide](../02-Installation.md).
|
||||
|
||||
## Getting Started
|
||||
|
||||
In the [installation guide](../02-Installation.md) we already refered to possible automation options by adding arguments to the [Icinga PowerShell Kickstart](../installation/01-Kickstart-Script.md).
|
||||
|
||||
This allows you to deploy the Framework unattended and automated on your Windows machines without having to touch them. The execution of the code snippet could be done by automation tools like SCCM, Puppet, Ansible, PowerShell Remote Execution or any other tool.
|
||||
|
||||
To fully automate the entire monitoring deployment on Windows, we will use the argument handling for the [Icinga PowerShell Kickstart](../installation/01-Kickstart-Script.md) and the description on how to use the `Start-IcingaAgentInstallWizard` automation handling as mentioned in [Icinga Agent Agent Wizard guide](../installation/04-Icinga-Agent-Wizard.md).
|
||||
|
||||
## Automating the deployment
|
||||
|
||||
As we are now aware on how we can setup the arguments for each step of the Kickstart and the Icinga Agent wizard, we move forward to build a small automation handling.
|
||||
|
||||
The code snippets we will provide below are build on top of each other. If you simply require a fully finished code block, head to the end of this guide.
|
||||
|
||||
### Setting up connection handling
|
||||
|
||||
At first we will allow TLS 1.2 and 1.1 in our session to ensure our PowerShell can connect to every system without issues. In addition to that, we will disable possible progress bars to speed up file downloads:
|
||||
|
||||
```powershell
|
||||
# Ensure TLS 1.2 and 1.1 are supported. This will prevent possible HTTPS errors on older systems
|
||||
[Net.ServicePointManager]::SecurityProtocol = "tls12, tls11";
|
||||
# Disable any progress bars. In addition, this will speed-up downloads
|
||||
$ProgressPreference = "SilentlyContinue";
|
||||
```
|
||||
|
||||
### Setting Kickstart-Script source location
|
||||
|
||||
In the next step we will assign a variable which will point directly to your `kickstart-script.ps1` file. It doesnt matter if the file is available on a web share, local drive or network share:
|
||||
|
||||
```powershell
|
||||
# Ensure TLS 1.2 and 1.1 are supported. This will prevent possible HTTPS errors on older systems
|
||||
[Net.ServicePointManager]::SecurityProtocol = "tls12, tls11";
|
||||
# Disable any progress bars. In addition, this will speed-up downloads
|
||||
$ProgressPreference = "SilentlyContinue";
|
||||
# Destination on where to load our Kickstart-Script file from.
|
||||
# It doesn't matter if it is a web ressource, local drive or network share
|
||||
$KickStartScriptFile = 'https://example.com/icinga/kickstart-script.ps1';
|
||||
```
|
||||
|
||||
### Fetching the Script content
|
||||
|
||||
Now as our base is ready, we have to actually fetch the content of our script file. To ensure it will work for local drives, networks shares and web ressources we will setup an empty `ScriptBlock` variable and depending on our location load the content from our file into it:
|
||||
|
||||
```powershell
|
||||
# Ensure TLS 1.2 and 1.1 are supported. This will prevent possible HTTPS errors on older systems
|
||||
[Net.ServicePointManager]::SecurityProtocol = "tls12, tls11";
|
||||
# Disable any progress bars. In addition, this will speed-up downloads
|
||||
$ProgressPreference = "SilentlyContinue";
|
||||
# Destination on where to load our Kickstart-Script file from.
|
||||
# It doesn't matter if it is a web ressource, local drive or network share
|
||||
$KickStartScriptFile = 'https://example.com/icinga/kickstart-script.ps1';
|
||||
# Setup an emptry variable which will contain our code block later
|
||||
$ScriptBlock = $null;
|
||||
|
||||
# Now check for your location and use the appropiate method to get the content
|
||||
if ((Test-Path $KickStartScriptFile)) {
|
||||
# Use local drive or network share
|
||||
$ScriptBlock = Get-Content -Path $KickStartScriptFile -Raw;
|
||||
} else {
|
||||
# Use our web ressource and download the file
|
||||
$ScriptBlock = (Invoke-WebRequest -UseBasicParsing -Uri $KickStartScriptFile).Content;
|
||||
}
|
||||
```
|
||||
|
||||
### Add function and automation call to our script
|
||||
|
||||
As our `ScriptBlock` now contains the downloaded content from either a local drive, network share or web ressource we can continue to work with that. The content in our `ScriptBlock` variable is actual PowerShell code which is parsed as a string. We can use this to later create an executable PowerShell script which will apply all tasks we intend.
|
||||
|
||||
Right now we only contain the Icinga Kickstart functionallty, but no actual call to the function `Start-IcingaFrameworkWizard`.
|
||||
|
||||
To do so, we can now extend our `ScriptBlock` variable with code like this:
|
||||
|
||||
```powershell
|
||||
$ScriptBlock += "`r`n`r`n Start-IcingaFrameworkWizard;";
|
||||
```
|
||||
|
||||
This will add two new lines to the end of the script file and call the function `Start-IcingaFrameworkWizard`. As described in the [Icinga PowerShell Kickstart](../installation/01-Kickstart-Script.md) guide you can of course add arguments to this call. In our example we will download version 1.1.2 of the Icinga PowerShell Framework, install it into `C:\Program Files\WindowsPowerShell\modules`, allow updates and skip the Icinga Agent wizard:
|
||||
|
||||
```powershell
|
||||
# Ensure TLS 1.2 and 1.1 are supported. This will prevent possible HTTPS errors on older systems
|
||||
[Net.ServicePointManager]::SecurityProtocol = "tls12, tls11";
|
||||
# Disable any progress bars. In addition, this will speed-up downloads
|
||||
$ProgressPreference = "SilentlyContinue";
|
||||
# Destination on where to load our Kickstart-Script file from.
|
||||
# It doesn't matter if it is a web ressource, local drive or network share
|
||||
$KickStartScriptFile = 'https://example.com/icinga/kickstart-script.ps1';
|
||||
# Setup an emptry variable which will contain our code block later
|
||||
$ScriptBlock = $null;
|
||||
|
||||
# Now check for your location and use the appropiate method to get the content
|
||||
if ((Test-Path $KickStartScriptFile)) {
|
||||
# Use local drive or network share
|
||||
$ScriptBlock = Get-Content -Path $KickStartScriptFile -Raw;
|
||||
} else {
|
||||
# Use our web ressource and download the file
|
||||
$ScriptBlock = (Invoke-WebRequest -UseBasicParsing -Uri $KickStartScriptFile).Content;
|
||||
}
|
||||
|
||||
# Start our Kickstart wizard with our installation arguments for the Framework.
|
||||
# This will ensure an automated run later on
|
||||
$ScriptBlock += "`r`n`r`n Start-IcingaFrameworkWizard -RepositoryUrl 'https://github.com/Icinga/icinga-powershell-framework/archive/v1.1.2.zip' -ModuleDirectory 'C:\Program Files\WindowsPowerShell\modules\' -AllowUpdate 1 -SkipWizard;";
|
||||
```
|
||||
|
||||
### Additional automation tasks
|
||||
|
||||
With the above code we have very good foundation and can now continue directly to install our Icinga Agent including other components. To do so, we will extend the `ScriptBlock` variable again with our function call to `Start-IcingaAgentInstallWizard` and provide all arguments for our automation tasks. To make things easier, we will use the Icinga Director Self-Service API and install the PowerShell Framework as service. For this we will download the release `.zip` from `https://github.com/Icinga/icinga-powershell-service/releases/download/v1.1.0/icinga-service-v1.1.0.zip` and use `C:\Program Files\icinga-framework-service\` as location for your service binary.
|
||||
|
||||
Additional examples can be found in the [Icinga Agent Agent Wizard guide](../installation/04-Icinga-Agent-Wizard.md).
|
||||
|
||||
```powershell
|
||||
# Ensure TLS 1.2 and 1.1 are supported. This will prevent possible HTTPS errors on older systems
|
||||
[Net.ServicePointManager]::SecurityProtocol = "tls12, tls11";
|
||||
# Disable any progress bars. In addition, this will speed-up downloads
|
||||
$ProgressPreference = "SilentlyContinue";
|
||||
# Destination on where to load our Kickstart-Script file from.
|
||||
# It doesn't matter if it is a web ressource, local drive or network share
|
||||
$KickStartScriptFile = 'https://example.com/icinga/kickstart-script.ps1';
|
||||
# Setup an emptry variable which will contain our code block later
|
||||
$ScriptBlock = $null;
|
||||
|
||||
# Now check for your location and use the appropiate method to get the content
|
||||
if ((Test-Path $KickStartScriptFile)) {
|
||||
# Use local drive or network share
|
||||
$ScriptBlock = Get-Content -Path $KickStartScriptFile -Raw;
|
||||
} else {
|
||||
# Use our web ressource and download the file
|
||||
$ScriptBlock = (Invoke-WebRequest -UseBasicParsing -Uri $KickStartScriptFile).Content;
|
||||
}
|
||||
|
||||
# Start our Kickstart wizard with our installation arguments for the Framework.
|
||||
# This will ensure an automated run later on
|
||||
$ScriptBlock += "`r`n`r`n Start-IcingaFrameworkWizard -RepositoryUrl 'https://github.com/Icinga/icinga-powershell-framework/archive/v1.1.2.zip' -ModuleDirectory 'C:\Program Files\WindowsPowerShell\modules\' -AllowUpdate 1 -SkipWizard;";
|
||||
|
||||
# We will call our Start-IcingaAgentInstallWizard and provide automation arguments to install
|
||||
# and configure the Icinga Agent by using the Icinga Director Self-Service API. In addition,
|
||||
# we will install the Framework as service
|
||||
$ScriptBlock += "`r`n`r`n Start-IcingaAgentInstallWizard -SelfServiceAPIKey '56756378658n56t85679765n97649m7649m76' -UseDirectorSelfService 1 -DirectorUrl 'https://example.com/icingaweb2/director/' -OverrideDirectorVars 0 -ConvertEndpointIPConfig 1 -Ticket '' -EmptyTicket 1 -InstallFrameworkPlugins 0 -InstallFrameworkService 1 -FrameworkServiceUrl 'https://github.com/Icinga/icinga-powershell-service/releases/download/v1.1.0/icinga-service-v1.1.0.zip' -ServiceDirectory 'C:\Program Files\icinga-framework-service\' -RunInstaller;"
|
||||
```
|
||||
|
||||
### Add Framework component installation tasks
|
||||
|
||||
You might have realised that we are not installing the Icinga PowerShell Plugins with `Start-IcingaAgentInstallWizard`. Instead, we will use the component installer of the Icinga PowerShell Framework to install them. You can repeat this newly added line for any additional Framework component you want to install:
|
||||
|
||||
```powershell
|
||||
# Ensure TLS 1.2 and 1.1 are supported. This will prevent possible HTTPS errors on older systems
|
||||
[Net.ServicePointManager]::SecurityProtocol = "tls12, tls11";
|
||||
# Disable any progress bars. In addition, this will speed-up downloads
|
||||
$ProgressPreference = "SilentlyContinue";
|
||||
# Destination on where to load our Kickstart-Script file from.
|
||||
# It doesn't matter if it is a web ressource, local drive or network share
|
||||
$KickStartScriptFile = 'https://example.com/icinga/kickstart-script.ps1';
|
||||
# Setup an emptry variable which will contain our code block later
|
||||
$ScriptBlock = $null;
|
||||
|
||||
# Now check for your location and use the appropiate method to get the content
|
||||
if ((Test-Path $KickStartScriptFile)) {
|
||||
# Use local drive or network share
|
||||
$ScriptBlock = Get-Content -Path $KickStartScriptFile -Raw;
|
||||
} else {
|
||||
# Use our web ressource and download the file
|
||||
$ScriptBlock = (Invoke-WebRequest -UseBasicParsing -Uri $KickStartScriptFile).Content;
|
||||
}
|
||||
|
||||
# Start our Kickstart wizard with our installation arguments for the Framework.
|
||||
# This will ensure an automated run later on
|
||||
$ScriptBlock += "`r`n`r`n Start-IcingaFrameworkWizard -RepositoryUrl 'https://github.com/Icinga/icinga-powershell-framework/archive/v1.1.2.zip' -ModuleDirectory 'C:\Program Files\WindowsPowerShell\modules\' -AllowUpdate 1 -SkipWizard;";
|
||||
|
||||
# We will call our Start-IcingaAgentInstallWizard and provide automation arguments to install
|
||||
# and configure the Icinga Agent by using the Icinga Director Self-Service API. In addition,
|
||||
# we will install the Framework as service
|
||||
$ScriptBlock += "`r`n`r`n Start-IcingaAgentInstallWizard -SelfServiceAPIKey '56756378658n56t85679765n97649m7649m76' -UseDirectorSelfService 1 -DirectorUrl 'https://example.com/icingaweb2/director/' -OverrideDirectorVars 0 -ConvertEndpointIPConfig 1 -Ticket '' -EmptyTicket 1 -InstallFrameworkPlugins 0 -InstallFrameworkService 1 -FrameworkServiceUrl 'https://github.com/Icinga/icinga-powershell-service/releases/download/v1.1.0/icinga-service-v1.1.0.zip' -ServiceDirectory 'C:\Program Files\icinga-framework-service\' -RunInstaller;"
|
||||
|
||||
# Install the Icinga PowerShell Plugins by using the Framework component installer
|
||||
$ScriptBlock += "`r`n`r`n Install-IcingaFrameworkComponent -Name 'plugins' -Release;";
|
||||
```
|
||||
|
||||
### Create the Script-Block and make it executable
|
||||
|
||||
Now as our PowerShell code itself is finished and we added our automation tasks, we can create a working script block based on our `ScriptBlock` variable and execute it.
|
||||
|
||||
```powershell
|
||||
# Ensure TLS 1.2 and 1.1 are supported. This will prevent possible HTTPS errors on older systems
|
||||
[Net.ServicePointManager]::SecurityProtocol = "tls12, tls11";
|
||||
# Disable any progress bars. In addition, this will speed-up downloads
|
||||
$ProgressPreference = "SilentlyContinue";
|
||||
# Destination on where to load our Kickstart-Script file from.
|
||||
# It doesn't matter if it is a web ressource, local drive or network share
|
||||
$KickStartScriptFile = 'https://example.com/icinga/kickstart-script.ps1';
|
||||
# Setup an emptry variable which will contain our code block later
|
||||
$ScriptBlock = $null;
|
||||
|
||||
# Now check for your location and use the appropiate method to get the content
|
||||
if ((Test-Path $KickStartScriptFile)) {
|
||||
# Use local drive or network share
|
||||
$ScriptBlock = Get-Content -Path $KickStartScriptFile -Raw;
|
||||
} else {
|
||||
# Use our web ressource and download the file
|
||||
$ScriptBlock = (Invoke-WebRequest -UseBasicParsing -Uri $KickStartScriptFile).Content;
|
||||
}
|
||||
|
||||
# Start our Kickstart wizard with our installation arguments for the Framework.
|
||||
# This will ensure an automated run later on
|
||||
$ScriptBlock += "`r`n`r`n Start-IcingaFrameworkWizard -RepositoryUrl 'https://github.com/Icinga/icinga-powershell-framework/archive/v1.1.2.zip' -ModuleDirectory 'C:\Program Files\WindowsPowerShell\modules\' -AllowUpdate 1 -SkipWizard;";
|
||||
|
||||
# We will call our Start-IcingaAgentInstallWizard and provide automation arguments to install
|
||||
# and configure the Icinga Agent by using the Icinga Director Self-Service API. In addition,
|
||||
# we will install the Framework as service
|
||||
$ScriptBlock += "`r`n`r`n Start-IcingaAgentInstallWizard -SelfServiceAPIKey '56756378658n56t85679765n97649m7649m76' -UseDirectorSelfService 1 -DirectorUrl 'https://example.com/icingaweb2/director/' -OverrideDirectorVars 0 -ConvertEndpointIPConfig 1 -Ticket '' -EmptyTicket 1 -InstallFrameworkPlugins 0 -InstallFrameworkService 1 -FrameworkServiceUrl 'https://github.com/Icinga/icinga-powershell-service/releases/download/v1.1.0/icinga-service-v1.1.0.zip' -ServiceDirectory 'C:\Program Files\icinga-framework-service\' -RunInstaller;"
|
||||
|
||||
# Install the Icinga PowerShell Plugins by using the Framework component installer
|
||||
$ScriptBlock += "`r`n`r`n Install-IcingaFrameworkComponent -Name 'plugins' -Release;";
|
||||
|
||||
# Create a script block based on our ScriptBlock variable and execute the code
|
||||
Invoke-Command -ScriptBlock ([Scriptblock]::Create($ScriptBlock));
|
||||
```
|
||||
|
||||
This is it - your automation task is completed and every single component is installed and configured.
|
||||
|
||||
### Create a Script/Module file with above mentioned code
|
||||
|
||||
Last but not least we can do some additional tweaks/improvements to the above mentioned code. This how ever depends on your internal policies and systems you are using.
|
||||
|
||||
#### PowerShell Remote Execution
|
||||
|
||||
You can run the entire above code on different machines. For this you can simply add `-ComputerName "FQDN of your target machine"` as argument to `Invoke-Command`. The `ScriptBlock` itself will be entirely build and constructed on your local machine, the actual code how ever will be executed on the remote host.
|
||||
|
||||
#### Create a Script-File to download
|
||||
|
||||
You can put all of the above mentioned code inside an own `.ps1` file and make it downloadable on a local ressource, network share of web resource. Afterwards you can use the above code as example to have less lines for execution. Lets assume you have stored the file as `icinga-automation.ps1` on the same location as the Kickstart script file mentioned above:
|
||||
|
||||
```powershell
|
||||
# Ensure TLS 1.2 and 1.1 are supported. This will prevent possible HTTPS errors on older systems
|
||||
[Net.ServicePointManager]::SecurityProtocol = "tls12, tls11";
|
||||
# Disable any progress bars. In addition, this will speed-up downloads
|
||||
$ProgressPreference = "SilentlyContinue";
|
||||
# Destination on where to load our Kickstart-Script file from.
|
||||
# It doesn't matter if it is a web ressource, local drive or network share
|
||||
$KickStartScriptFile = 'https://example.com/icinga/icinga-automation.ps1';
|
||||
# Setup an emptry variable which will contain our code block later
|
||||
$ScriptBlock = $null;
|
||||
|
||||
# Now check for your location and use the appropiate method to get the content
|
||||
if ((Test-Path $KickStartScriptFile)) {
|
||||
# Use local drive or network share
|
||||
$ScriptBlock = Get-Content -Path $KickStartScriptFile -Raw;
|
||||
} else {
|
||||
# Use our web ressource and download the file
|
||||
$ScriptBlock = (Invoke-WebRequest -UseBasicParsing -Uri $KickStartScriptFile).Content;
|
||||
}
|
||||
|
||||
# Create a script block based on our ScriptBlock variable and execute the code
|
||||
Invoke-Command -ScriptBlock ([Scriptblock]::Create($ScriptBlock));
|
||||
```
|
||||
|
||||
As you see the code is identical, we do how ever download the `icinga-automation.ps1` which contains the entire code examle with your Icinga Agent installation arguments including the additional Framework components. To make global changes, we can now simply modify our `icinga-automation.ps1` and have effect it our entire infrastructure at once.
|
||||
|
||||
#### Create a PowerShell Module
|
||||
|
||||
To make things a lot easier you can create an own module based on the code above with a custom installation function. The function then would allow you to parse arguments to, enabling a better and more dynamic configuration for each host. In addition, you would make use of the PowerShell Remote Execution handling to parse target hosts as arguments to connect to and deploy Icinga for Windows solution.
|
||||
|
||||
This could be used on a local automation host which will simply execute the local module, connect to the remote host and deploy the intended configuration.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 14 KiB After Width: | Height: | Size: 18 KiB |
|
|
@ -20,7 +20,7 @@ The issue on this method is, that even while we only load the `Processor` Perfor
|
|||
|
||||
At the moment there is no solution available to resolve this issue. Permissions to these counters cannot be granted. Disabling these Performance Counter endpoints is not suitable as well, because it might break different applications and it is also **not** adviced to run the Icinga Agent or checks in `LocalSystem` context for security reasons.
|
||||
|
||||
Right now a workaround would be the experimental feature [Forward Checks to Internal API](../experimental/01-Forward-checks-to-internal-API.md), which is not yet ready for production.
|
||||
Right now a workaround would be the experimental feature [Forward Checks to Internal API](../110-Installation/30-API-Check-Forwarder.md), which is not yet ready for production.
|
||||
|
||||
As Performance Counter libraries are loaded during startup, they will only occur once you start the Icinga for Windows service with this daemon. Every single check executed afterwards will use Performance Counter libraries, but the current shell session has already loaded required components and therefor only access objects we want.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,29 +0,0 @@
|
|||
Run the PowerShell Framework 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/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 receive an average of time for the CPU load for example.
|
||||
|
||||
Install the Service
|
||||
---
|
||||
|
||||
A detailed documentation on how to download and install the service and be found directly on the services [installation guide](https://icinga.com/docs/windows/latest/service/doc/02-Installation/).
|
||||
|
||||
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.
|
||||
|
|
@ -1,62 +0,0 @@
|
|||
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-IcingaWindowsService;
|
||||
```
|
||||
|
||||
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-IcingaWindowsService;
|
||||
```
|
||||
|
||||
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).
|
||||
|
|
@ -1,85 +0,0 @@
|
|||
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-IcingaWindowsService;
|
||||
```
|
||||
|
||||
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-IcingaWindowsService;
|
||||
```
|
||||
|
||||
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-IcingaWindowsService;
|
||||
```
|
||||
Loading…
Reference in a new issue