Skip to main content

Windows NSClient API

Overview​

NSClient++ provides its own REST API using the webserver module. This REST API give the possibility to exploit monitoring data from Windows servers through HTTPS connections.

Plugin-Pack assets​

Monitored objects​

  • Windows Server OS from 2003 SP2 version
  • Windows Workstation from XP version

Monitored metrics​

Metric nameDescription
Sessions_valueNumber of actived sessions. Unit: Count

Prerequisites​

Centreon NSClient++​

To monitor an Windows Servers through NSClient++ API, install the Centreon packaged version of the NSClient++ agent. Please follow our official documentation and make sure that the Webserver / RESTApi configuration is correct.

Installation​

  1. Install the Centreon Plugin package on every Centreon Poller expected to monitor Windows ressources using REST API:
yum install centreon-plugin-Operatingsystems-Windows-Restapi
  1. On the Centreon Web interface, install the Windows NSClient API Centreon Pack on the Configuration > Plugin Packs > Manager page

Configuration​

  • Log into Centreon and add a new Host through Configuration > Hosts.
  • Apply the OS-Windows-NSClient-05-Restapi-custom template and configure all the mandatory Macros:
MandatoryNameDescription
XNSCPRESTAPIPORTPort of the REST API NSclient++ (default: 8443)
XNSCPRESTAPIPROTOProtocol used (default: https)
XNSCPRESTAPILEGACYPASSWORDPassword used (configured in the prerequisites section)
NSCPRESTAPIEXTRAOPTIONSAny extra option you may want to add to the command (eg. a --verbose flag)

How do I test my configuration through the CLI and what do the main parameters stand for ?​

Once the Centreon plugin installed, you can test it logging with the centreon-engine user:

/usr/lib/centreon/plugins//centreon_nsclient_restapi.pl \
  --plugin=apps::nsclient::restapi::plugin \
  --mode=query --hostname='192.168.1.24' \
  --port='8443' \
  --proto='https' \
  --legacy-password='centreon' \
  --command=check_cpu \
  --arg="warning=time = '5m' and load > 80" \
  --arg="critical=time = '5m' and load > 90" \
  --arg=show-all

OK: 5m: 40%, 1m: 42%, 5s: 39% | 
'total 5m'=40%;80;90;; 
'total 1m'=42%;80;90;; 
'total 5s'=39%;80;90;;

The command above request the REST API NSclient++ (--plugin=apps::nsclient::restapi::plugin) on the port 8443 (--port='8443'). It uses HTTPS protocol (--proto='https') and the password created in the prerequisites section (--legacy-password='centreon'). This command checks the cpu usage of the server (--command=check_cpu).

This command will trigger alerts :

  • a WARNING alert if the metric "total 5m" (warning=time = 5m) is superior to 80% (load > 80%)
  • a CRITICAL alert if the metric "total 5m" (warning=time = 5m) is superior to 90% (load > 90%)

You can display all of the modes that come with the Plugin with the command below: 

/usr/lib/centreon/plugins//centreon_nsclient_restapi.pl \
  --plugin=apps::nsclient::restapi::plugin \
  --list-mode

The available thresholds as well as all of the options that can be used with this Plugin can be displayed by adding the --help parameter to the command:

/usr/lib/centreon/plugins//centreon_nsclient_restapi.pl \
  --plugin=apps::nsclient::restapi::plugin \
  --mode=query \
  --help

Troubleshooting​

UNKNOWN: Cannot decode json response: malformed UTF-8 character in JSON string​

If you receive this message, enable debug messages by adding --debug:

/usr/lib/centreon/plugins//centreon_nsclient_restapi.pl \
  --plugin=apps::nsclient::restapi::plugin \
  --mode=query \
  --hostname='192.168.1.24' \
  --port='8443' \
  --proto='https' \
  --legacy-password='centreon' \
  --http-backend=curl  \
  --curl-opt="CURLOPT_SSL_VERIFYPEER => 0" \
  --timeout=30 \
  --command=check_centreon_plugins \
  --arg='os::windows::local::plugin' \
  --arg='sessions' \
  --arg='--filter-sessionname="" \
  --config="scripts/centreon/conf/qwinsta.xml" \
  --language="fr" \
  --debug

UNKNOWN: Cannot decode json response: malformed UTF-8 character in JSON string, at character offset 724 (before "\x{fffd}u0090RIPH\x{fffd}...") at /usr/lib/centreon/plugins//centreon_nsclient_restapi.pl line 133.
== Info: About to connect() to 192.168.1.24 port 8443 (#0)
== Info:   Trying 192.168.1.24...
== Info: Connected to 192.168.1.24 (192.168.1.24) port 8443 (#0)
.......
Cannot write statefile '/var/lib/centreon/centplugins/windows_sessions_a181a603769c1f98ad927e7367c7aa51_a181a603769c1f98ad927e7367c7aa51'. 
Need write/exec permissions on directory.
  • The folder /var/lib/centreon/centplugins doesn't exist on your Windows Server, change the cache directory by using the options --statefile-dir

"UNKNOWN: 500 Can't connect to x.x.x.x:8443"​

To fix this issue, add the option --http-backend=curl to the host macro NSCPRESTAPIEXTRAOPTIONS.