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

Merge pull request #493 from Icinga:doc/rest_api_doc_update

Browse source 
Doc: REST-Api section doc update

Updates doc for new IMC installation way and removes no longer required dependencies.
This commit is contained in:
Lord Hepipud 2022-03-17 08:59:38 +01:00 committed by GitHub
commit e6d820735d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 20 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

48
doc/110-Installation/30-API-Check-Forwarder.md
View file

@ -1,4 +1,4 @@
# API Check Forwader # API Check Forwarder
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. 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.
@ -12,30 +12,25 @@ To use this feature, you wil require the following
* Icinga for Windows v1.6.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 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)
## Install Dependencies ## Installation with IMC
### Additional Modules In order to install the REST-Api feature, you can simply enable it by using the IMC. On new installations with the IMC, the feature is enabled by default.
At first you will require to install both required modules, the [REST-Api](https://icinga.com/docs/icinga-for-windows/latest/restapi/doc/01-Introduction/) and [Api-Checks](https://github.com/Icinga/icinga-powershell-apichecks/blob/master/doc/01-Introduction.md) component. * At first, run `icinga` in your PowerShell to open the IMC
* Navigate to `Settings`
* Navigate to `Icinga for Windows Features`
* Toggle the setting `Api-Check Forwarder` by using the menu index entry (besides the feature is mentioned if it is `Enabled` or `Disabled`)
Like any other Icinga for Windows component, you can use the Framework tools to install them: Please note that you will require to have the [Icinga for Windows Service](https://icinga.com/docs/icinga-for-windows/latest/doc/service/01-Install-Service/) already installed. The menu entry will only ensure, that the entire configuration is made and that check commands are enabled as commands.
```powershell ## Manual Installation and Configuration
Install-IcingaComponent -Name restapi;
```
```powershell ### Install Icinga for Windows Service
Install-IcingaComponent -Name apichecks;
```
### Icinga for Windows Service
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). 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 ### Register Background Daemon
To access our REST-Api we have to register it as background daemon. 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:
@ -47,7 +42,7 @@ By default, it will start listening on Port `5668` on `localhost` and use the Ic
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). 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).
## Whitelist Check Commands ### Whitelist Check Commands
By default the Api-Checks module is rejecting every single request to execute commands, as long as they are not whitelisted. By default the Api-Checks module is rejecting every single request to execute commands, as long as they are not whitelisted.
@ -59,7 +54,7 @@ Add-IcingaRESTApiCommand -Command 'Invoke-IcingaCheck*' -Endpoint 'apichecks';
Of course, you can also whitelist every single command without wildcard for more security. Of course, you can also whitelist every single command without wildcard for more security.
## Blacklist Check Commands ### Blacklist Check Commands
If you do not want to execute certain checks, but keep the previous wildcard whitelist, you can blacklist a single command (or use wildcard to match multiple): If you do not want to execute certain checks, but keep the previous wildcard whitelist, you can blacklist a single command (or use wildcard to match multiple):
@ -69,7 +64,7 @@ Add-IcingaRESTApiCommand -Command 'Invoke-IcingaCheckCertificate' -Endpoint 'api
Blacklists are checked prior to whitelist. If you are running wildcard filters for both, whitelist and blacklist, blacklist entries will win first and block the execution if they match the filter. Blacklists are checked prior to whitelist. If you are running wildcard filters for both, whitelist and blacklist, blacklist entries will win first and block the execution if they match the filter.
## Enable Api Check Feature ### Enable Api Check Feature
Now as we configured our host with all required components, we simply require to enable the api checks feature: Now as we configured our host with all required components, we simply require to enable the api checks feature:
@ -85,7 +80,7 @@ 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. 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 ### Disable Api Check Feature
You can disable the Api check feature anytime by running You can disable the Api check feature anytime by running
@ -95,18 +90,11 @@ Disable-IcingaFrameworkApiChecks;
Once disabled checks will be executed within the local, current shell and not being forwarded to the API. Once disabled checks will be executed within the local, current shell and not being forwarded to the API.
## EventLog Errors ### Summary
In case a check could not be executed by using this experimental feature, either because of timeouts or other issues, they are added with `EventId 1553` inside the EventLog for `Icinga for Windows`. A description on why the check could not be executed is added within the event output.
## Summary
For quick installation, here the list of commands to get everything running: For quick installation, here the list of commands to get everything running:
```powershell ```powershell
Install-IcingaFrameworkComponent -Name restapi -Release;
Install-IcingaFrameworkComponent -Name apichecks -Release;
Register-IcingaBackgroundDaemon -Command 'Start-IcingaWindowsRESTApi'; Register-IcingaBackgroundDaemon -Command 'Start-IcingaWindowsRESTApi';
Add-IcingaRESTApiCommand -Command 'Invoke-IcingaCheck*' -Endpoint 'apichecks'; Add-IcingaRESTApiCommand -Command 'Invoke-IcingaCheck*' -Endpoint 'apichecks';
@ -114,3 +102,7 @@ Restart-IcingaWindowsService;
Enable-IcingaFrameworkApiChecks; Enable-IcingaFrameworkApiChecks;
``` ```
## EventLog Errors
In case a check could not be executed by using this experimental feature, either because of timeouts or other issues, they are added with `EventId 1553` inside the EventLog for `Icinga for Windows`. A description on why the check could not be executed is added within the event output.