Agreed, it might feel like routine by now, but we are still happy to announce today’s release of Icinga for Windows v1.3.0. This includes Icinga PowerShell Plugins v1.3.0 as well as Icinga PowerShell Kickstart v1.2.0. Like with every release we appreciate all feedback, testing and bug reports, from our community and user base, as without you we wouldn’t be able to make such great progress with this project.
Please ensure to read and follow the upgrading documentation before you proceed with an update, ensuring a smooth experience!
New Icinga Plugins
This time two new plugins will be shipped with Icinga for Windows:
- Invoke-IcingaCheckNetworkInterface: Checks availability, state and Usage of Network interfaces and Interface Teams
- Invoke-IcingaCheckStoragePool: Checks availability, utilization, and state of a Storage Pools
What’s new in Version 1.3.0
Thanks to your feedback we were able to track down a lot of bugs and issues which might occur from time to time on different systems. Not only did we get rid of those issues, but also tried to improve the overall error handling and catching for better tracking. Within the next Icinga for Windows releases, we will improve this even more to ensure errors will be parsed properly and result in correct Icinga states.
Besides bug fixing, we also improved the Framework for developers by adding new functionality and more generic approaches for certain tasks, like converting plugin thresholds more dynamically with one single function: `Convert-IcingaPluginThresholds`
Parse Arguments to Icinga Shell
In case you are using `icinga` for either testing of new code or to execute plugins/commands, we finally added support to parse arguments to the newly created Icinga Shell. This will allow you create credential objects within the main shell for example and re-use them within the new Icinga Shells for single code execution, which no longer requires to re-define certain objects within your test setup. An example can look like this:
icinga> $credentials = Get-Credential -Message 'MSSQL Login';
icinga> icinga {
$cred = $IcingaShellArgs[0];
Invoke-IcingaCheckMSSQLHealth `
-SqlUsername $cred.Username `
-SqlPassword $cred.Password `
-SqlHost 'example.com';
} -ArgumentList $credentials;
By using `-ArgumentList` you can add variables from your current shell into the new Icinga Shell and access them by using the variable `$IcingaShellArgs`, followed by the index key. They index key is simply the order on which you passed your variables into the argument list.
Proxy Server Support for Web Requests
A long-requested feature was to add support for proxy servers, ensuring that web requests are using a defined server sa proxy. This feature is now supported and can be enabled with `Set-IcingaFrameworkProxyServer`. You simply require setting your proxy server and the configuration is stored within the Framework. Once a web request is executed, it will be routed through the proxy.
Set-IcingaFrameworkProxyServer -Server 'http://example.com:8080';
For easier lookup, as added a documentation entry on the Framework Usage section of Icinga for Windows.
Testing Commands as different User
Normally you wouldn’t run your Icinga commands or plugins with your local administrative user, but with either a default service user or a custom user. To ensure testing in such cases is a lot easier, we added a new command with 1.3.0: `Start-IcingaShellAsUser`
This allows you to open a new Icinga Shell for a specific user environment and run commands from there, testing if all required permissions are set and Icinga for Windows is configured properly.
****************************************************** ** Icinga PowerShell Framework v1.3.0 ** Copyright (c) 2020 Icinga GmbH | MIT ** User environment MSSQL\Administrator ****************************************************** icinga> Start-IcingaShellAsUser
A new login prompt will then appear in which you simply have to enter the credentials for the user you want to login with. Once completed, a new PowerShell instance will open for the specified user.
****************************************************** ** Icinga PowerShell Framework v1.3.0 ** Copyright (c) 2020 Icinga GmbH | MIT ** User environment MSSQL\icinga ****************************************************** icinga>
On the top of the Icinga Shell we will now also print user environment information, telling you which machine you are on and to which user this shell belongs.
Meet the Icinga for Windows Knowledgebase
With Icinga for Windows v1.3.0 we started to write a Knowledgebase, which will be expanded over time to cover frequently asked questions, problems and to add a deep dive into issues printed by the plugins or the framework. Not only will it cover further explanation in case errors occur, but also on how to fix them and describe the approach. In addition to that, Icinga for Windows will print a link to the Knowledgebase entry for issues which are already covered there. During the next release we will extend this even further.
[UNKNOWN]: Icinga Permission Error was thrown: : Class: "Win32_Service", Namespace: "root/cimv2" The user you are running this command as does not have permission to access the requested Cim-Object. To fix this, please add the user the Agent is running with to the "Remote Management Users" groups and grant access to the WMI branch for the Class/Namespace mentioned above and add the permission "Remote enable". Further details can be found on the Icinga for Windows Knowledge base: https://icinga.com/docs/windows/latest/doc/knowledgebase/IWKB000001
If you were running into general issues regarding permissions or code execution and found a way to resolve it, we are looking forward to your input to add it to the Knowledgebase.
Icinga 2 Configuration File Generator
While it was already possible to generate Icinga Director Baskets for plugins, users not using the Icinga Director had to manually write the required CheckCommands for Icinga 2. With Icinga for Windows v1.3.0 this belongs to the past, as we now support to natively write Icinga 2 `.conf` files. The same benefits as for the baskets apply in this case, as all automation is the same, allowing the proper setting of arguments, values and descriptions for arguments. Even the handling for switch parameters and arrays is included. For example, switch parameters only require you to the the corresponding custom variable to `true` to set the argument. Of course, we also added a documentation entry for this on the Icinga Integration section.
In addition, all new plugin releases, starting with Icinga PowerShell Plugins v1.3.0 will ship with pre-compiled configurations for the Icinga Director and Icinga 2. You can simply use them directly from downloaded packages or get them directly from the repos GitHub for example.
Wmi Permissions made easy
Since plugins are executed by users with limited permissions in general, we are constantly working on solutions to make things easier. For example, plugins will now ship with a permission documentation entry, telling users which permissions are required to ensure the plugin is working properly. However, setting these configurations can sometimes be more complicated. For this reason, we are shipping Wmi permission management Cmdlets with Icinga for Windows v1.3.0. This will allow users to set permissions for a specific users for certain Wmi trees.
Add-IcingaWmiPermissions `
-User 'icinga' `
-Namespace 'root\Microsoft\Windows\Storage' `
-Enable `
-RemoteAccess `
-Recurse;
This example will grant the user `icinga` read-only and remote access permissions (over PowerShell Remote execution for example) to the Wmi tree `root\Microsoft\Windows\Storage` and all sub-containers and sub-namespaces. Now this user can use the Invoke-IcingaCheckDiskHealth plugin without problems. Of course, you can also remove Wmi permissions for a certain tree and user again:
Remove-IcingaWmiPermissions -User 'icinga' -Namespace 'root\Microsoft\Windows\Storage';
A more detailed explanation and description is available within the Knowledgebase Entry IWKB000001.
Experimental: Icinga for Windows Code Cache
Finally, we would like to talk about an experimental feature we added with Icinga for Windows v1.3.0: Code caching
On systems with few CPU cores available, the load is something that makes the difference between working and not-working. Running multiple checks based on Icinga for Windows might increase the load so much that the systems itself feels unresponsive. We are aware of this situation and are working on different solutions and attempts to mitigate and resolve this in the end. For now, we added an experimental feature called code caching. What it does, is collecting all PowerShell module files from the Icinga PowerShell Framework and writes them into one single cache file. Now when the Icinga PowerShell Framework is loaded by using `Use-Icinga` or simply `icinga`, the Framework will initialize based on this single cache file. On certain systems this can decrease the loading time and therefor the blocking time of the CPU cores by 50% up to 75%.
The catch is, that while this works perfectly fine within our test environment, every change done to the Framework (like adding new functions, fixing bugs, and so on) requires a quick rebuild of the cache file. By using the Framework integrated commands, this is done during the update process in case the Framework Code Cache is enabled.
To enable this experimental feature, you can simply use
Enable-IcingaFrameworkCodeCache; [Warning]: This is an experimental feature and might cause some side effects during usage. Please use this function with caution. Please run "Write-IcingaFrameworkCodeCache" in addition to ensure your cache is updated. This should be done after each update of the Framework in case the feature was disabled during the update run.
The warning is just here to inform about the caching behavior, and that this is still an experimental feature. In addition, it tells the user about the command `Write-IcingaFrameworkCodeCache` which can be typed into the shell to rebuild the cache file based on the current Framework code. In case the cache file is not present, and anything is calling `Use-Icinga` or `icinga`, the cache file is built during this run.
To disable the Framework cache again, you can simply use this command:
Disable-IcingaFrameworkCodeCache;
To ensure the user knows about the possible activation of the feature, it is printed on top at the Icinga Shell output
****************************************************** ** Icinga PowerShell Framework v1.3.0 ** Copyright (c) 2020 Icinga GmbH | MIT ** User environment win-icinga\icinga ** Warning: Icinga Framework Code Caching is enabled ****************************************************** icinga>
In case you modify code while the cache is enabled, please ensure to always re-create the cache by using `Write-IcingaFrameworkCodeCache`. Depending on the system, this may take several seconds.
Thats it so far for the release of Icinga for Windows v1.3.0. We hope you enjoy it and look forward receiving all your feedback and suggestions. Please make sure to read and follow the upgrading documentation before upgrading, just in case! If you are eager to lean what’s next, please have a look on the Icinga for Windows Roadmap. For now, we are already evaluating and testing new Plugins for Hyper-V and Cluster monitoring, which will hopefully be released soon!
Thank you for all your support and feedback! Please feel free to reach out to us if you require support, assistance, training, or anything related.
