NSClient++ 0.5.0, REST API and Icinga 2 integration

by | Sep 16, 2016

Michael Medin released NSClient++ 0.5.0 this week. We’re of course considering to update the bundled NSClient++ installer inside the Windows package.
First things first – the NSClient++ 0.5.0 Changelog mentions breaking changes, so we’ll need to test the ITL CheckCommands still working prior to the next Icinga 2 release (follow #12733). In case you want to help test yourself – you can safely upgrade the NSClient++ application in Windows yourself and fire your Icinga 2 checks against it (just install the new 0.5.0 package).
One cool thing to note about NSClient++ 0.5.0 – it comes with its own web server which also provides a REST API. That could introduce a solution for querying metrics via REST API which require rate calculation (CPU) from a running nscp service. This could be easily integrated into a native Icinga 2 client check plugin then. Let’s just try this out on my Windows 10 VM! 🙂


Webserver setup

You can enable the webserver during setup already or using the cli command. Later on you’ll need to edit the nsclient.ini with Administrator permissions inside the “[/settings/WEB/server]” section.
icinga2_nsclient_0-5-0_setup_webserver icinga2_nsclient_0-5-0_setup_webserver_manual
I did have trouble with “nscp web password set=icinga”, it did not work for me. Update 2016-09-19: Michael explained that over here: “nscp web password — –set icinga”.
I manually edited the nsclient.ini configuration file, added the “password” entry in the “[/settings/WEB/server]” section and restarted the service using cmd.exe run as administrator.
icinga2_nsclient_0-5-0_setup_webserver_config_password icinga2_nsclient_0-5-0_setup_webserver_service_restart

Web interface

The next thing – logging into https://localhost:8443. This works in Edge as well as Chrome.
Sweet, that metric overview.
Now let’s try some Queries. This failed using Edge, so I switched to Chrome.
Woah – just awesome! 

Powershell and REST API

Now guess what comes next – some reverse engineering parts for running an action on that HTTP URL we’ve seen above. I’m pretty new to Powershell myself, so it is a hell of Googling involved here. Open the start menu and start typing “Powershell” followed by [Enter].
I stumbled over the 0.4.3 release announcement which shows a simple curl example. Now I learned how to pass the “password” token inside the header (just an auth token, no basic auth!). Furthermore the REST API endpoint is different to the web URL, it is “https://localhost:8443/query/check_cpu” (that’s a TODO in the NSClient++ documentation but you can extract that from the web interface itself).
The important bits here:

  • Use Invoke-Request,
  • Add -UseBasicParsing since otherwise there’s some cryptic internet explorer engine warning.
  • Send the password as -Headers @{“password” = “icinga”}
  • Set the -Content-Type to “application/json”
  • I’m also using a script local workaround to signal “Invoke-Request” that all local requests without certificates are valid (basically the infamous “-s” option of curl). Real-life production examples should use valid certificates!

Script example:

add-type @"
    using System.Net;
    using System.Security.Cryptography.X509Certificates;
    public class TrustAllCertsPolicy : ICertificatePolicy {
        public bool CheckValidationResult(
            ServicePoint srvPoint, X509Certificate certificate,
            WebRequest request, int certificateProblem) {
            return true;
[System.Net.ServicePointManager]::CertificatePolicy = New-Object TrustAllCertsPolicy
$result = Invoke-Webrequest -UseBasicParsing -Uri https://localhost:8443/query/check_cpu -Headers @{"password" = "icinga"} -Method GET -ContentType 'application/json'

Hooray – our first REST API call to NSClient++. That requires sort of JSON parsing as well. Lucky me found this technet blog entry.

PS C:\Users\michi> $result | ConvertFrom-Json | Select -expand payload | Select -expand lines | Select -expand perf
alias    int_value
-----    ---------
total 5m @{critical=90; unit=%; value=2; warning=80}
total 1m @{critical=90; unit=%; value=4; warning=80}
total 5s @{critical=90; unit=%; value=2; warning=80}

There is probably a more elegant way to handle this, thus putting that into a generic check plugin executed by the Icinga 2 client. I’m leaving that exercise to the reader this time 😉
Share your findings with us, e.g. on Icinga Exchange and/or on Twitter. We’ll keep you updated – kindly follow #12733 and help make a deeper integration between Icinga 2 and NSClient++ happen!
I’m hoping that my reverse engineering adventure does not unveil too much for Michael’s OSMC talk on NSClient++ this year 😉 We also have the opportunity to discuss such scenarios later on the upcoming Icinga Camps in Belgrade, Stockholm, San Diego and Berlin!
Update 2016-09-19: I found a crash with the most recent 0.5.62 release. Michael kindly responded that probably a different module was causing this. And voilà – checks are working again. So we can proceed with resolving #12733.

You May Also Like…

Why Icinga?

Why Icinga?

We have decided to make some short educational videos about Icinga, and today we will be releasing the first one: Why...

Subscribe to our Newsletter

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