Icinga for Windows v1.4.0 – Join the next level

by | Mar 2, 2021

Not a long time ago, we released Icinga for Windows v1.3.1, fixing plenty of reported issues from our amazing community and user bases. Today however, we want to talk about the next big release for Icinga for Windows and are excited to tell you more about all the new features!

 

We need more plugins

With Icinga for Windows v1.4.0 we are going to release two new plugins, which will help you to monitor your infrastructure.

 

Invoke-IcingaCheckTCP

This plugin allows you to connect to a list of ports for a given address and determine if the port is reachable or not. Besides the status (Connected/Not Connected), you can also measure the connection speed. The plugin allows you to send alerts if the connection could be established, if the connection failed and if a response was not given within a set time frame. To make things easier, you can add multiple ports to your check for one address. Further details can be found on the plugin documentation.

 

Invoke-IcingaCheckUNCPath

Another plugin we added allows you to check directly for specific volumes, network drives and other related shares. The plugin connects to the given path and fetches the total size of the share as well as the current share size and free space. This enables you to monitor your integrated Windows network shares without having to install third party software or clients on your Windows server or storage device.

Since a network path might be to long to properly fit into any kind of alerting system, you can assign a display alias. Instead of printing \\this\is\the\path\to\my\network\share\I\want\to\checkyou can use something more use friendly, like Backup-Shareto be displayed. Find more details in the plugin documentation.

 

Improvements and fixes

Invoke-IcingaCheckEventLog

As we constantly move forward with developing new plugins, of course we also upgrade existing plugins and improve the way developers can add new ones by themself. For example, we updated Invoke-IcingaCheckEventLog to be more user friendly, as you now can simply filter timeframes by adding “5h” or “1d” within the -After argument for filtering. We still support the “hardcoded” version of like “2021/1/30“, however the new approach adds more flexibility.

 

Reworked Background Daemons

We did some work on our background daemon to ensure that spawned threads will no longer interfere with each other. This fixes an issue on environments with multiple daemons and background checks installed, which might result in memory leaks, invalid data and high CPU usage. There is no need for updating your current code in case you used the functionality the Framework provides. In case you are running modules shipped by us, like the REST-Api, you should update to the latest version as well.

 

Customize Check Labels

In addition to this, developers can now modify the performance data label name of their checks by using the new argument -LabelNamefor the `New-IcingaCheck` Cmdlet. This will ensure your label names are clean and easy to parse in graphing solutions, while the name for alerting provides additional details.

 

Flush Icinga Agent Api Directory

Sometimes it can be required to flush the Icinga Agent API directory, because of either invalid files or to ensure no other zone data remains. With Icinga for Windows v1.4.0 we added a new command which will clear the entire directory for you.

Clear-IcingaAgentApiDirectory;

 

Uninstall Icinga for Windows

While we are shipping an installer for all components related to Icinga for Windows, only some parts could be removed by using the Cmdlets. With Icinga for Windows v1.4.0 this changes, as we now fully support to uninstall single components or to uninstall the entire Icinga for Windows solution from a host, allowing you to start from scratch again.

To uninstall a single component, you run a simple command:

Uninstall-IcingaFrameworkComponent -Name 'plugins';

To uninstall everything, you can run the following command. By default you will be presented with a list of PowerShell modules that will be removed during the process. The command also provides a -Forceflag, which skips the confirmation message.

Uninstall-IcingaForWindows;

[Warning]: You are about to uninstall the Icinga Agent with all components (including certificates) and all Icinga for Windows Components: icinga-powershell-apichecks, icinga-powershell-cluster, icinga-powershell-framework, icinga-powershell-hyperv, icinga-powershell-mssql, icinga-powershell-plugins, icinga-powershell-restapi
Are you sure you want to proceed? (y/N)

 

New Configuration Files

With Icinga for Windows v1.4.0 we are going to change the way Icinga is executing check plugins. First, we fixed minor issue with rendering Icinga arrays when using the Icinga DSL Additionally, the plugin execution is done by a Framework function now, which is required for a new experimental feature we are going to talk about later in this blogpost.

 

Icinga DSL rendering for arrays

Until now rendering of arrays was done very simple. We looped through all entries of the array, no matter if you’re using plain config files or Icinga Director, and built an array out of it which worked with PowerShell. However, due to your feedback we quickly realized that there is an issue in case you have spaces inside of them. This could have happened if you monitor Windows Services and the manufacturer didn’t care about spaces in the service. Or if you wanted to check for Performance Counters: very often they contain spaces as well.

The latest version of the Icinga DSL renderer will ensure that in case you are using a string inside an array element, it is automatically escaped with single quotes. But don’t worry! If you already followed our Knowledge Base and you were aware of this issue already and added single quotes in your arrays, you do not have to do anything. In case the string is already escaped with single quotes, we do not modify it and leave it as it is.

 

New check execution

With the latest version of the configuration files we are moving most of the logic how the plugin is executed directly to the Framework. If you review our new configuration, you might notice that the Use-Icingafunction is now called with a -Minimal flag and that we added a new function Exit-IcingaExecutePlugin. This has two benefits:

  • We can work on different features and improvements for loading the Framework and plugin execution simultaneously
  • You will no longer require to upgrade your entire Windows infrastructure before you can apply new configuration

The new approach is way more flexible as it will allow a wider gap between Icinga for Windows versions between single hosts, starting with v1.4.0.

IMPORTANT: It is required to update all your Windows machines to Icinga for Windows v1.4.0 before you can apply the new configuration either shipped by each plugin collection for the Icinga Director and Icinga 2 itself. New configuration files generated by the Exit-IcingaExecutePluginCmdlet also require Icinga for Windows v.1.4.0!

 

Framework Code Cache leaves experimental

With the previous release we added an experimental feature to mitigate the loading time of the Icinga PowerShell Framework while using Use-Icingaor simply icinga. With Icinga for Windows v.1.4.0 we are going to allow this feature in production and remove the experimental state. The feature reads all module files from the Icinga PowerShell Framework and adds them to one single file. In case the feature is enabled, this file will be imported for initialization. In case you modify content manually on the Framework or update manually without the Framework tools, you have to rebuild the cache manually. If you use the Framework tools, everything is done automatically. You can read more about this feature in the documentation.

Enable the feature:

Enable-IcingaFrameworkCodeCache;

Write the cache file or rebuild it if required:

Write-IcingaFrameworkCodeCache;

 

New Experimental Features

With Icinga for Windows v1.4.0 we are adding two new experimental features we are extremely excited about. These features are in our opinion not yet ready for production use, but we want to share them with you in an experimental state to collect feedback, suggestions, and ideas. Please note that we will not officially support these features yet in production, but will of course collect your feedback and issues, try to resolve them, and analyze why they occur.

 

Forward check to internal API

The idea

The first experimental feature we want to talk about is an internal API, processing all incoming checks triggered by Exit-IcingaExecutePlugin(as you can read more about above). This new experimental feature is an attempt to mitigate the performance impact for systems with fewer resources available. Regardless of the usage of the Icinga Agent or check_by_powershell (or any other method), the feature will catch the plugin execution and forward it to a local REST-Api. Once sent, the check is executed within our REST-Api daemon and the result is sent back to the plugin.

Now, the check is still executed on the local system, but with some benefits:

  • We do no longer require loading the full Framework (Use-Icinga -Minimal), because only core parts are required for communicating with the REST-Api
  • Objects are already initialized within the REST-Api daemon once a check is executed, resulting in the next identical check being executed much faster
  • Reduced CPU impact because many core parts are already loaded within the REST-Api and it’s internal threads

 

Error handling

Of course, the question is, what happens if the background daemon crashes, something goes wrong, or we run into timeouts. In case the Icinga for Windows service is not running, the feature is not enabled, the background daemon not registered, and so on the plugin execution function will fall back to load the entire Framework and execute the plugin without the REST call in the local shell.

By doing the handling this way we have several benefits:

  • No matter what we do, checks are always executed (if they do not run into an Icinga timeout)
  • We can keep improving the Framework and Plugin loader later to get quicker started for executing plugins
  • In case the plugin execution fails because of any other reason, we still get a proper [Unknown] reporting on our check execution

 

How to use it

To try this feature out, you require two additional components to be installed on the system:

Here is the entire code block describing how to enable and install everything. It is required that the Icinga for Windows service is already installed.

Install-IcingaFrameworkComponent -Name restapi -Release;
Install-IcingaFrameworkComponent -Name apichecks -Release;

Register-IcingaBackgroundDaemon -Command 'Start-IcingaWindowsRESTApi';
Restart-Service icingapowershell;

Add-IcingaRESTApiCommand -Command 'Invoke-IcingaCheck*' -Endpoint 'apichecks';

Enable-IcingaFrameworkApiChecks;

Now every single check executed locally using Exit-IcingaExecutePluginis queued over the REST-Api. For man be found inside the documentation.

IMPORTANT: In order for this to work it is required that you update your Icinga configuration with the latest CheckCommands shipped by us. It is required to update all your Windows machines to Icinga for Windows v1.4.0 before you can apply the new configuration either shipped by each plugin collection for the Icinga Director and Icinga 2 itself. New configuration files generated by the Get-IcingaCheckCommandConfigCmdlet also require Icinga for Windows v.1.4.0!

 

Meet the Management Console

Another experimental feature we want to share with you is our Icinga for Windows Management Console. From many sides we received feedback that your current Icinga for Windows installer is fine, but for new users it is a little to complex and to many questions are asked. To make things easier, we will work on a  new integration to replace the current installer in the long term. You can enter the Management Console by using Install-Icingaor simply icinga -Manage.

The idea behind this is to provide a graphical interface to manage Icinga for Windows and to provide menus and actions for default tasks. For example, the above mentioned experimental feature for using a REST-Api for the checks can be enabled directly from this menu.

Basically, we are trying to ask only a few questions during the setup and automate most tasks in the background. However, if you configure the system this way, you can still use the Management Console to automate your entire installation of Icinga for Windows, but with less overhead and simpler tasks behind. It will validate your input on the fly and the included help for each section will give inexperienced users a better understanding about what is required and where to get data from. We are very excited about this and can’t wait for you to test the new feature! If you have additional feature requests or ideas, please feel free to share them with us – we will happily evaluate them.

 

This was a long one

Finally, we are at the end of this blogpost. As you can see, we are trying very hard to make Icinga for Windows appealing to everyone, trying new things and improving the tool itself by collecting as much feedback as possible. Automating the solution, making the live easier for developers while still having a look on the performance and the impact monitoring has on target machines.

With this release we published new versions of almost every single module we developed:

Of course our Hyper-V and Cluster plugins received a small update as well, as the configuration changed – which applies to MSSQL as well.

We love what we do and appreciate the acceptance, integrations and support from our community as well as our customers. Thank you to everyone and don’t hesitate to contact us or open issues/feature requests on out GitHub projects. Sharing your knowledge on our community forum is always a great way of helping each other.

You May Also Like…

Subscribe to our Newsletter

A monthly digest of the latest Icinga news, releases, articles and community topics.