Skip to content

Commit 2e9158d

Browse files
LordHepipudLordHepipud
authored
Merge pull request #274 from Icinga:doc/update_docs_for_1.5.0
Docs: Update docs to 1.5.0 and add more usage exmaples
2 parents 212a80c + f573d62 commit 2e9158d

File tree

5 files changed

+254
-3
lines changed

5 files changed

+254
-3
lines changed

‎doc/06-Framework-Usage.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ The Icinga PowerShell Framework ships with a bunch of Cmdlets for monitoring, me
99
* [Install Wizard Guide](frameworkusage/03-Install-Wizard-Guide.md)
1010
* [Disable Certificate Validation](frameworkusage/04-Disable-Certificate-Validation.md)
1111
* [Enable Framework Code Caching](frameworkusage/05-Enable-Framework-Code-Caching.md)
12+
* [Update Framework and Components](frameworkusage/06-Update-Framework-And-Components.md)
13+
* [Analyse EventLog](frameworkusage/07-Analyse-EventLog.md)
1214

1315
## Icinga Agent Management
1416

@@ -23,3 +25,4 @@ The Icinga PowerShell Framework ships with a bunch of Cmdlets for monitoring, me
2325
## Experimental
2426

2527
* [Forward checks to internal API](experimental/01-Forward-checks-to-internal-API.md)
28+
* [Management Console](experimental/02-Management-Console.md)

‎doc/experimental/02-Management-Console.md

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# Experimental: Management Console
2+
3+
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`
4+
5+
It is directly build into the Framework an can be called from a PowerShell (`administrative`) with
6+
7+
```powershell
8+
icinga -Manage;
9+
```
10+
11+
## First Look
12+
13+
```powershell
14+
***********************************************************************
15+
** Icinga for Windows Management Console **
16+
** Copyright (c) 2021 Icinga GmbH | MIT **
17+
** User environment ws-icinga\icinga **
18+
** Icinga PowerShell Framework v1.5.0 **
19+
** This is an experimental feature and might contain bugs **
20+
** Please provide us with feedback, issues and input at **
21+
** https://github.com/Icinga/icinga-powershell-framework/issues **
22+
***********************************************************************
23+
24+
What do you want to do?
25+
26+
[0] Installation
27+
[1] Update environment
28+
[2] Manage environment
29+
[3] Remove components
30+
31+
[x] Exit [c] Continue [h] Help [m] Main
32+
33+
Input (Default 0 and c):
34+
```
35+
36+
## Using The Management Console
37+
38+
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.
39+
If you want to `Manage environment`, you will have to type in `2` and press `enter` to switch to the menu.
40+
41+
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:
42+
43+
* `a` (Advanced): Will only occur on several forms and will show advanced options for additional configuration settings
44+
* `c` (Continue): Will mostly be used as default and allows you to continue. Might not always be present
45+
* `d` (Delete): Allows you to delete values for forms on which you have to enter data to continue
46+
* `h` (Help): Will either print the help for each entry and menu section or disables it (toogle)
47+
* `m` (Main): Allows you to jump back to the main menu
48+
* `p` (Previous): Allows you to jump to the previous menu, in case you are not inside the root of another element
49+
* `x` (Exit): Will close the Management Console
50+
51+
## Capabilities
52+
53+
Right now you can do the following tasks:
54+
55+
* Install Icinga Agent, Icinga for Windows and all components
56+
* Use the Icinga Director Self-Service API
57+
* Manage Icinga Agent features
58+
* Remove Icinga Agent or any installed Icinga for Windows component
59+
* Enable Icinga PowerShell Framework Features (including experimental)
60+
* Configure installed background daemons (register/unregister)
61+
* Start/Restart/Stop Icinga Agent and Icinga for Windows service
62+
63+
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`.
64+
65+
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.
66+
67+
## Automation With The Management Console
68+
69+
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
70+
71+
### Configuration Command
72+
73+
```powershell
74+
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"]}}';
75+
```
76+
77+
### Configuration File
78+
79+
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.
80+
81+
```powershell
82+
Install-Icinga -InstallFile 'C:\Icinga2\IfW_answer.json';
83+
```

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

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# Update Framework and Components
2+
3+
Icinga for Windows ships with a bunch of Cmdlets, allowing users to manage the entire environment without much effort. This includes features to install entire components, but also allows to update them.
4+
5+
## Updating Icinga PowerShell Framework
6+
7+
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`.
8+
9+
### Interactive Update
10+
11+
To start the interactive update with a wizard, asking you on how to update, simply type the command inside your Icinga shell or call `Use-Icinga` before.
12+
13+
```powershell
14+
Install-IcingaFrameworkUpdate;
15+
```
16+
17+
Afterwards you will be asked a bunch of questions, which we explain in the following.
18+
19+
```text
20+
Do you provide a custom repository for "Icinga Framework"? (y/N):
21+
```
22+
23+
Like any other component, you can type in y or n for this answer. The custom repository is defined as a `.zip` file you might have downloaded directly from GitHub for the Framework at placed it either on your Icinga webserver somewhere, or locally. If you type no, you can choose if you want to install the latest stable or snapshot.
24+
25+
```text
26+
Which version of the "Icinga Framework" do you want to install? (release/snapshot) (Defaults: "release"):
27+
```
28+
29+
By default the command will connect to `https://github.com/Icinga/icinga-powershell-framework` and either fetch the latest stable release if you select `release` or the current master branch if you use `snapshot`.
30+
Lets assume we update our production environment and therefor using `release`.
31+
32+
```powershell
33+
icinga> Install-IcingaFrameworkUpdate
34+
Do you provide a custom repository for "Icinga Framework"? (y/N):
35+
Which version of the "Icinga Framework" do you want to install? (release/snapshot) (Defaults: "release"):
36+
[Notice]: Downloading "Icinga Framework" into "C:\Users\Administrator\AppData\Local\Temp\tmp_icinga1262975608.d"
37+
[Notice]: Installing module into "C:\Users\Administrator\AppData\Local\Temp\tmp_icinga1262975608.d"
38+
[Notice]: Using content of folder "C:\Users\Administrator\AppData\Local\Temp\tmp_icinga1262975608.d\icinga-powershell-framework-1.4.1" for updates
39+
[Notice]: Stopping Icinga Agent service
40+
[Notice]: Stopping service "icinga2"
41+
[Notice]: Removing files from framework
42+
[Notice]: Copying new files to framework
43+
[Notice]: Unblocking Icinga PowerShell Files
44+
[Notice]: Cleaning temporary content
45+
[Notice]: Updating Framework cache file
46+
[Notice]: The code caching feature is currently not enabled. You can enable it with "Enable-IcingaFrameworkCodeCache"
47+
[Notice]: Framework update has been completed. Please start a new PowerShell instance now to complete the update
48+
[Passed]: Icinga Agent service is installed
49+
[Passed]: The specified user "NT Authority\NetworkService" is allowed to run as service
50+
[Passed]: Directory "C:\ProgramData\icinga2\etc" is accessible and writeable by the Icinga Service User "NT Authority\NetworkService"
51+
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writeable by the Icinga Service User "NT Authority\NetworkService"
52+
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writeable by the Icinga Service User "NT Authority\NetworkService"
53+
[Passed]: Icinga Agent configuration is valid
54+
[Passed]: Icinga Agent debug log is disabled
55+
[Notice]: Starting Icinga Agent service
56+
[Notice]: Starting service "icinga2"
57+
```
58+
59+
Thats it. Your Icinga Agent will now continue it's work behind without requiring additional actions. If you want to use the new Framework features, you should open a new PowerShell instance to apply the updates to your current session.
60+
61+
### Update With Defined Package
62+
63+
To avoid the above wizard and to properly automate the task, the Cmdlet `Install-IcingaFrameworkUpdate` ships with one additional argument: `-FrameworkUrl`
64+
65+
As `-FrameworkUrl` you can define the target to the Icinga PowerShell Frameworks `.zip` file and directly install this version with the same result as above, but fully automated without questions.
66+
67+
#### Examples For URL
68+
69+
Local File:
70+
71+
```powershell
72+
Install-IcingaFrameworkUpdate -FrameworkUrl 'C:\Icinga2\icinga-powershell-framework-1.5.0.zip';
73+
```
74+
75+
NetworkShare File:
76+
77+
```powershell
78+
Install-IcingaFrameworkUpdate -FrameworkUrl '\\icinga.example.com\IcingaForWindows\Icinga2\icinga-powershell-framework-1.5.0.zip';
79+
```
80+
81+
Custom Web Path:
82+
83+
```powershell
84+
Install-IcingaFrameworkUpdate -FrameworkUrl 'https://example.com/Icinga/icinga-powershell-framework-1.5.0.zip';
85+
```
86+
87+
GitHub Release:
88+
89+
```powershell
90+
Install-IcingaFrameworkUpdate -FrameworkUrl 'https://github.com/Icinga/icinga-powershell-framework/archive/refs/tags/v1.5.0.zip';
91+
```
92+
93+
GitHub Master Branch:
94+
95+
```powershell
96+
Install-IcingaFrameworkUpdate -FrameworkUrl 'https://github.com/Icinga/icinga-powershell-framework/archive/refs/heads/master.zip';
97+
```
98+
99+
GitHub Branch
100+
101+
```powershell
102+
Install-IcingaFrameworkUpdate -FrameworkUrl 'https://github.com/Icinga/icinga-powershell-framework/archive/refs/heads/fix/framework_root_folder_lookup.zip';
103+
```
104+
105+
Once you enter the command, the update process will continue as shown above earlier
106+
107+
## Updating Icinga PowerShell Components
108+
109+
Updating components like [plugins](https://icinga.com/docs/icinga-for-windows/latest/plugins/doc/01-Introduction/) is as easy as installing them. If you used the [Framework Component Installer](https://icinga.com/docs/icinga-for-windows/latest/plugins/doc/02-Installation/#icinga-framework-component-installer) as described in every plugin repository, you can use the same command to update the plugins as well.
110+
111+
The command `Install-IcingaFrameworkComponent` is designed to both, install components on a fresh environment and also keeps them updated if you run the same command again.

‎doc/frameworkusage/07-Analyse-EventLog.md

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

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ The Icinga PowerShell Framework ships with a simple Cmdlet to install/update the
1313
To simply install the latest version of the Icinga Agent, you can run the following command:
1414

1515
```powershell
16-
Install-IcingaAgent -Version 'latest'
16+
Install-IcingaAgent -Version 'release'
1717
```
1818

1919
This will lookup the default installation source `https://packages.icinga.com/windows/`, fetch the latest version, download and install it.
@@ -33,7 +33,7 @@ This will download Icinga Agent `2.11.6` from `https://packages.icinga.com/windo
3333
Similar to the above examples, you can also update or downgrade the Icinga Agent with this command. All argument handling as before applies. However, to tell the command to perform an upgrade or downgrade, you will have to set the argument `-AllowUpdates` in addition (which also applies to downgrades):
3434

3535
```powershell
36-
Install-IcingaAgent -Version 'latest' -AllowUpdates 1
36+
Install-IcingaAgent -Version 'release' -AllowUpdates 1
3737
```
3838

3939
## Customizing the Installer
@@ -50,5 +50,5 @@ Of course, you can also modify the `Install-IcingaAgent` command with different
5050
For example we can distribute Icinga Agents over a local network share for better update management.
5151

5252
```powershell
53-
Install-IcingaAgent -Version 'latest' -AllowUpdates 1 -Source '\\example.com\icinga\icingaagent\'
53+
Install-IcingaAgent -Version 'release' -AllowUpdates 1 -Source '\\example.com\icinga\icingaagent\'
5454
```

0 commit comments

Comments
 (0)