upstream/icinga-powershell-framework
1
0
Fork 0
mirror of https://github.com/Icinga/icinga-powershell-framework.git synced 2025-12-20 23:00:35 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions

Adds general doc description for Agent management

Browse source
This commit is contained in:
Lord Hepipud 2020-08-12 17:30:48 +02:00
parent b5d51ac99a
commit 5b1f076432
5 changed files with 360 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
doc/06-Framework-Usage.md
View file

@ -5,3 +5,10 @@ The Icinga PowerShell Framework ships with a bunch of Cmdlets for monitoring, me
## Framework Management
* [Automated Framework and Component deployment](frameworkusage/01-Automated-Framework-and-Component-Deployment.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)

103
doc/frameworkusage/30-Manage-Icinga-Agent-Features.md Normal file
View file

@ -0,0 +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"
```

41
doc/frameworkusage/31-Read-Icinga-Agent_Log_DebugLog.md Normal file
View file

@ -0,0 +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()
...
```

118
doc/frameworkusage/32-Test-Icinga-Agent-Environment.md Normal file
View file

@ -0,0 +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 writeable by the Icinga Service User "NT AUTHORITY\NetworkService"
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writeable by the Icinga Service User "NT AUTHORITY\NetworkService"
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writeable by the Icinga Service User "NT AUTHORITY\NetworkService"
[Passed]: Icinga Agent configuration is valid
[Passed]: Icinga Agent debug log is disabled
```
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 writeable by the Icinga Service User "NT AUTHORITY\NetworkService"
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writeable by the Icinga Service User "NT AUTHORITY\NetworkService"
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writeable by the Icinga Service User "NT AUTHORITY\NetworkService"
[Passed]: Icinga Agent configuration is valid
[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 writeable 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 writeable 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 writeable 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 writeable by the Icinga Service User "NT AUTHORITY\NetworkService"
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writeable by the Icinga Service User "NT AUTHORITY\NetworkService"
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writeable by the Icinga Service User "NT AUTHORITY\NetworkService"
[Passed]: Icinga Agent configuration is valid
[Passed]: Icinga Agent debug log is disabled
```
## 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 writeable by the Icinga Service User "NT AUTHORITY\NetworkService"
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writeable by the Icinga Service User "NT AUTHORITY\NetworkService"
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writeable by the Icinga Service User "NT AUTHORITY\NetworkService"
[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.

91
doc/frameworkusage/33-Run-Icinga-Agent-As-Other-Service-User.md Normal file
View file

@ -0,0 +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 writeable by the Icinga Service User "NT AUTHORITY\SYSTEM"
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writeable by the Icinga Service User "NT AUTHORITY\SYSTEM"
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writeable 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 writeable 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 writeable by the Icinga Service User "icinga"
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writeable by the Icinga Service User "icinga"
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writeable 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
```