NSClient

About

NSClient++ is the agent we recommend for monitoring hosts that run Microsoft Windows. It integrates very well with recent Windows Servers versions, copying its commands into the Registry and simplifying authentication. It also has versions for Linux, but OP5 has not tested against such implementations.

OP5 used to provide a modified version of NSClient++. Starting with version 0.4.x and moving into the 0.5.x series, the official NSClient++ release has a cleaner integration with OP5 Monitor as well as the operating system. We strongly recommend downloading the latest stable release directly from our friends there.

OP5 plugins that handle NSClient++ communication

NSCP out of the box has very few commands. Instead it comes with a plethora of modules that you can choose to load. This prevents wasting resources. It also calls back to the tool that it replaced many years ago, "NSClient for Windows" (which explains the double-plus increment in the name). These instructions will help you get it working with OP5's plugin scripts from the following families:

check_nt (deprecated)

In the past OP5 used it for all basic tests, such as CPU, memory, and disks. It could even check Windows services and performances counters, especially in Windows 2000 Server and Windows Server 2003.

Nevertheless this plugin has stopped receiving any new development. It does not work as well with more recent versions of Windows Server, in particular 2012 R2 and onward. OP5 strongly recommends using at least 'check_nrpe' or the newer script-based protocols for any custom scripts or other new work.

check_nrpe

This is the same plugin used with the NRPE agent. This makes it very easy to use the same check command for any host server, be it on Windows, Unix, or Linux. We already described how to configure such commands.

Please keep in mind that the 'check_nrpe' plugin and the NRPE agent are not the same thing. The plugin sits on the OP5 Monitor to make remote calls, while the Unix and Linux agent sits on hosts to listen for those calls. Thus you can use the same check command syntax against a Windows host as a Linux host, because the configuration file on the host will determine how the host will listen and respond.

Installation

On the Windows target host (hereout: 'wintarget'), Make sure the latest release of NSClient++ is installed and running in OP5 mode. If you are not certain, start from scratch:

  1. Download the latest installer of NSCP -- https://nsclient.org/download/
  2. Backup your NSCP scripts and INI files to some directory away from the NSCP installation directory;
  3. Stop the NSClient++ service;
  4. Uninstall all existing versions of NSCP;
  5. Delete "C:\Program Files\NSClient++\", "C:\Program Files\op5\nsclient++\", or any other residual NSCP directory (aside from your backups);
  6. Delete any Registry entries under "\\HKEY_LOCAL_MACHINE\SOFTWARE\NSClient++\".
  7. We have an example of a PowerShell script to run steps 3 through 6. Please review before making a similar implementation:

    uninstall_nscp.ps1

    $nsclient = Get-WmiObject -Class win32_product | Where-Object {$_.Name -match "NSClient"}
    $nsclient
    $nsclient.Uninstall()
    Remove-Item -Path hklm:\SOFTWARE\NSClient++ -Recurse
  8. Run the latest installer:
    1. Select 'OP5' for Monitoring Tool:
    2. You can select 'Complete' mode at the next screen to skip a lot of other questions;
    3. The one remaining question box will then ask for Allowed Hosts. Provide "127.0.0.1," then your OP5 Monitor server IP addresses. CIDR blocks such as '172.16.55.0/24' are acceptable:
  9. After the install wizard finishes, open "C:\Program Files\NSClient++\" (hereout: '%NSCP%') in the File Explorer (or the Administrator command prompt). Make certain the following subfolders exist inside that location or otherwise create them:
    • cache
    • crash-dumps

Configuration

NSClient++ operation used to be configured only in a set of plaintext files. These are still located in the installation directory, typically "C:\Program Files\NSClient++\". You can still edit these files and restart the NSCP service to make the changes take effect. However many changes are now easier from the Windows Registry, such as adding new INI files at load time.

Michael Medin, the head of the NSClient++ project, has provided very good documentation for writing configuration files. OP5 provides an in-depth presentation in our Knowledge Base. If you need configuration details for one of the deprecated releases (version 0.3.x and older), we have moved them to a separate page to avoid confusion. As we also mention on that page, we would strongly advise following the above steps to download the latest version, uninstall the old ones, install the newest one in OP5 mode, and get working within a few minutes.

Enabling External Scripts

  1. Create a new file in %NSCP%, 'custom.ini';
  2. Add the following to it to execute scripts not originally from NRPE or NSCP and to instantiate one in particular:
  3. custom.ini

    [/modules]
    CheckExternalScripts = enabled

    [/settings/external scripts/scripts]
    check_okay = scripts\check_ok.bat
  4. Use the Windows Registry to add the custom initialization file. The most common way is via Windows GUI:
    1. Open 'regedit';
    2. Go to "\\HKEY_LOCAL_MACHINE\SOFTWARE\NSClient++\includes";
    3. Create a new string value key;
    4. Give it the name 'custom' and the value 'custom.ini'
  5. From an Administrator command prompt, change to the "C:\Program Files\NSClient++" directory and run the command "nscp settings --show". Make sure that 'custom.ini' now appears in the list;
  6. If you run "nscp settings --list" from the same prompt, you will already see your new external command in the output. However you still need to restart the NSCP service to get the external script processing to work. You can either restart the service as you would with any Windows service, or simply run the following from our existing prompt:
  7. nscp service --restart

  8. Run "nscp test" to start a test environment. There will be a lot of output before you get a prompt again:
  9. nscp test output

    C:\Users\Administrator>nscp testD       
    core NSClient++ 0.5.2.35 2018-01-28 x64 Loading settings and logger...D
    core Settings not ready so we cant lookup: base-pathD
    core Settings not ready so we cant lookup: exe-pathD
    settings Boot.ini found in: C:\Program Files\NSClient++/boot.iniD
    settings Activating: registry://HKEY_LOCAL_MACHINE/software/NSClient++D
    settings Creating instance for: registry://HKEY_LOCAL_MACHINE/software/NSClient++D
    settings Creating instance for: ://op5.iniD
    core Settings not ready so we cant lookup: shared-pathD
    core Settings not ready so we cant lookup: shared-pathD
    settings Loading: C:\Program Files\NSClient++/op5.iniD
    settings Creating instance for: ://custom.iniD
    core Settings not ready so we cant lookup: shared-pathD
    core Settings not ready so we cant lookup: shared-pathD
    settings Loading: C:\Program Files\NSClient++/custom.iniD
    core NSClient++ 0.5.2.35 2018-01-28 x64 booting...D
    core Booted settings subsystem...D
    core On crash: restart: NSCPD
    core Archiving crash dumps in: C:\Program Files\NSClient++/crash-dumpsD
    core Found: CheckDiskD
    core Found: CheckEventLogD
    core Found: CheckExternalScriptsD
    core Found: CheckHelpersD
    core Found: CheckSystemD
    core Found: CheckTaskSchedD
    core Found: NRPEServerD
    core Found: NSClientServerD
    core Loading module C:\Program Files\NSClient++\modules\CheckDisk.dll ()D
    core Loading module C:\Program Files\NSClient++\modules\CheckEventLog.dll ()D
    core Loading module C:\Program Files\NSClient++\modules\CheckExternalScripts.dll ()D
    core Loading module C:\Program Files\NSClient++\modules\CheckHelpers.dll ()D
    core Loading module C:\Program Files\NSClient++\modules\CheckSystem.dll ()D
    core Loading module C:\Program Files\NSClient++\modules\CheckTaskSched.dll ()D
    core Loading module C:\Program Files\NSClient++\modules\NRPEServer.dll ()D
    core Loading module C:\Program Files\NSClient++\modules\NSClientServer.dll ()D
    core Loading plugin: CheckDiskD
    core Loading plugin: CheckEventLogD
    core Loading plugin: CheckExternalScriptsD ext-script No aliases found (adding default)D core Loading plugin: CheckHelpersD core Loading plugin: CheckSystemD core Loading plugin: CheckTaskSchedD core Loading plugin: NRPEServerD nrpe Allowed hosts definition: 127.0.0.1(255.255.255.255), 9.34.75.0(255.255.255.0)D nrpe Server config: address: :5666, ssl enabled: none, no certificate, dh: C:\Program Files\NSClient++/security/nrpe_dh_512.pem, ciphers: ADH, ca: C:\Program Files\NSClient++/security/ca.pem, options:D nrpe Binding to: [::]:5666(ipv6)D nrpe Attempting to bind to: [::]:5666(ipv6)D nrpe Binding to: 0.0.0.0:5666(ipv4), reopen: true, reuse: trueD nrpe Attempting to bind to: 0.0.0.0:5666(ipv4)D core Loading plugin: NSClientServerD check_nt Allowed hosts definition: 127.0.0.1(255.255.255.255), 9.34.75.0(255.255.255.0)D check_nt Binding to: [::]:1248(ipv6)D check_nt Attempting to bind to: [::]:1248(ipv6)D check_nt Binding to: 0.0.0.0:1248(ipv4), reopen: true, reuse: trueD check_nt Attempting to bind to: 0.0.0.0:1248(ipv4)D core NSClient++ - 0.5.2.35 2018-01-28 Started!D core Loading module C:\Program Files\NSClient++\modules\CommandClient.dll ()D core Loading plugin: CommandClient...D cli Enter command to execute, help for help or exit to exit...D w32system Loading counter: disk_queue_length_0 C: = \\WINTARGET\PhysicalDisk(0 C:)\% Disk TimeD w32system Loading counter: disk_queue_length__Total = \\WINTARGET\PhysicalDisk(_Total)\% Disk Time
  10. Provide the key for the external script as an argument and make sure it leads to your desired results. Back to our example above:
  11. check_okay

  12. Type "exit" once it completes.