Skip to content

Installing NSClient++

This is a growing process before it was all manual but slowly we are getting a more “automated” installation process so hopefully this will keep improving in the future as well and some of the steps might go away.

See Supported platforms for the Windows and Linux version matrix, including the difference between the standard and legacy Windows editions.

Table of Contents

Introduction

NSClient++ comes with an interactive installer (MSI) which is the preferred method of installation. There is also a command line option for registering (and de-registering) the service but as the Installer is the preferred way.

More detailed information on how to do silent installs and automated installs in large environments can be found below. For most people installing NSClient++ is simply running the MSI entering some options and clicking next. BUT this is only where the fun begins. After installing NSClient++ you need to configure it.

Configuration

NSClient++ support multiple configuration storage backends but here we will assume you are using the ini file which is the default.

To check where the configuration is stored, you can run the following command:

$ nscp settings --show
INI settings: (ini://${shared-path}/nsclient.ini, C:\source\build\x64\dev/nsclient.ini)

Now this configuration can include other configuration backends and files so your setup might be more complicated. For details on the configuration options check the the reference documentation

Windows Firewall

  1. Windows firewall exception for NRPE and check_nt is installed (optionally) by the installer. If you have another firewall then the built-in one you might have to manually add exceptions to all incoming traffic if you which to use check_nrpe and/or check_nt.
  2. External Firewall (optional)

Firewall configuration should be pretty straight forward:

  • If you use NRPEServer (check_nrpe, NRPEListener) you need the NRPE port open (usually 5666) from the Nagios server towards the client.
  • If you use the NSClientServer (check_nt, NSClientListener) you need the (modified) NSClient port open (usually 12489) from the Nagios server towards the client.
  • If you use the NSCA Module (passive checks) you need the NSCA port open from the client towards the Nagios server. client:* -> Nagios:5667
  • Also be aware that ports are configurable so if you override the defaults you obviously need to update the firewall rules accordingly.
  • There a multitude of other protocol which you can also use with NSClient++ (including, NRPE, NSCA, Syslog, SMTP, etc etc) so please review what your firewall setup in conjunction with you NSClient++ design.
Protocol Source Source port Destination Destination port Comment
NRPE Nagios client 5666 The nagios server initiates a call to the client on port 5666
NSClient Nagios client 12489 The nagios server initiates a call to the client on port 12489
NSCA client Nagios 5667 The client initiates a call to the Nagios server on port 5667
NRPE-proxy client remote-client 5666 The client initiates a call to the remote client on port 5666
  • Nagios is the IP/host of the main monitoring server
  • client is the Windows computer where you have installed NSClient++
  • remote-client is the “other” client you want to check from NSClient++ (using NSClient++ as a proxy)

All these ports can be changed so be sure to check your nsclient.ini for your ports.

Installing on Linux (.deb / .rpm)

On Linux NSClient++ ships as a standard .deb (Ubuntu / Debian) or .rpm (Rocky / RHEL / AlmaLinux / Fedora) package. See the package matrix in README.md for the file to download from the releases page.

Important

The Linux packages do not include the web management UI. The daemon, REST API, NRPE/NSCA listeners and all check modules are bundled in the .deb/.rpm as usual; only the React/Vite frontend lives in a separate release artifact (NSCP-Web-<version>.zip). Run sudo nscp web install-ui after installing the package to fetch the matching UI bundle. See Installing the web UI bundle below.

This split is driven by Debian/Fedora packaging policy (no npm install during package builds) and only applies to the Linux packages. The Windows MSI keeps bundling the UI inline.

Debian / Ubuntu

# Replace the file name with the one matching your release / arch from
# the README package matrix.
sudo apt install ./NSCP-<version>-ubuntu-24.04-amd64.deb

postinst enables and starts the nsclient systemd service. The first-install output also reminds you that the UI hasn’t been fetched yet:

NSClient++: web UI is not installed. Run 'nscp web install-ui' as root to fetch it.

Until you run that command, hitting the web port in a browser will show a small built-in placeholder page that repeats the instruction. The REST API, NRPE, NSCA and all other listeners work normally without the UI bundle.

Rocky / RHEL / Fedora-family

sudo dnf install ./NSCP-<version>-rocky-10-x86_64.rpm

Same as above: the service starts immediately, and the UI bundle needs a separate sudo nscp web install-ui step.

File locations

The official .deb/.rpm packages install under the standard FHS prefix /usr:

What Location
Daemon /usr/sbin/nscp
Check modules /usr/lib/nsclient/modules
Private libraries /usr/lib/nsclient
Scripts / web /usr/lib/nsclient/{scripts,web}
Shipped certificates /usr/lib/nsclient/security (NRPE DH parameters, server TLS certificate)
Configuration /etc/nsclient
Fleet identity /var/lib/nsclient/security/agent-state.json
Fleet-managed config /var/lib/nsclient/fleet
State / cache /var/lib/nsclient
Logs /var/log/nsclient
systemd unit /lib/systemd/system/nsclient.service

The split matters: /usr/lib/nsclient belongs to the package and is not written at runtime, while everything the service rewrites lives under /var. The service runs as the unprivileged nsclient user, so it cannot write into the package directory - and /usr has to stay mountable read-only. See File layout for the whole picture.

These are derived from the build’s install prefix; a package built for a different prefix (e.g. /opt/nsclient) places everything under that prefix and the daemon resolves its paths accordingly. To point an already-built daemon at a boot.ini in a non-standard location, start it with --path-override boot-conf=/path/to/boot.ini. See Choosing an install prefix in the build guide for building against a custom prefix.

Installing the web UI bundle

Once the package is installed, fetch the matching UI bundle:

sudo nscp web install-ui

This downloads NSCP-Web-<version>.zip and its .sha256 companion from the project’s GitHub release that matches your installed daemon version, verifies the checksum, and unpacks the bundle into the configured web-path (usually /usr/lib/nsclient/web). sudo is required because that directory is root-owned.

Companion commands:

sudo nscp web install-ui --force       # overwrite an existing install
sudo nscp web ui-status                # show installed version, size, source URL
sudo nscp web uninstall-ui             # remove only the files this command installed

After install-ui succeeds you can reload the daemon and the UI replaces the placeholder. If WEBServer is already running, an immediate browser refresh picks up the new files — no restart needed.

Offline / air-gapped UI install

For hosts without outbound internet access, download NSCP-Web-<version>.zip (and optionally NSCP-Web-<version>.sha256) on a machine that has access, copy them to the target, and point the installer at the local file:

sudo nscp web install-ui --from /tmp/NSCP-Web-<version>.zip

When a sibling .zip.sha256 (or <basename>.sha256) is present next to the zip, the installer verifies it. Without one, it skips verification and prints a warning — you opted into trusting a local path.

Automated installation (Windows MSI)

The NSClient++ installer for windows is a standard MSI installer which means it can be installed using pretty much all deployment techniques available on the windows platform.

Basic command line

To customize the installation you can use the standard MSI options to add/remove features and set properties. An example of this is shown below.

$ msiexec /i NSCP-VERSION-x64.msi ADDLOCAL=ALL REMOVE=PythonScript INSTALLLOCATION=c:\FooBar

MSI Options

A list of all the MSI options can be found below.

Keyword Description
INSTALLLOCATION Folder where NSClient++ is installed.
ADD_DEFAULTS Add default values to the configuration file.
ALLOWED_HOSTS Set allowed hosts value
ALLOW_CONFIGURATION If set to 1 allows configuration changes. If set to 0 disable all configuration support in the installer
CONFIGURATION_TYPE Configuration context to use
CONF_CHECKS Enable default check plugins
CONF_NRPE Enable NRPE server
CONF_NSCA Enable NSCA Collection /OU probably need scheduler as well)
CONF_NSCLIENT Enable NSClient Server (check_nt)
CONF_SCHEDULER Enable Scheduler (required by NSCA)
CONF_WEB Enabled WEB Server
NRPEMODE NRPE Mode (LEGACY, SECURE for using ceretificates)
NSCLIENT_PWD Password to use for check_nt (and web server)
CONF_INCLUDES Additional files to include in the config syntax: ; For instance CONF_INCLUDES=op5;op5.ini;local;local.ini
OP5_SERVER OP5 Server if you want to automatically submit passive checks via Op5 northbound API.
OP5_USER The username to login with on the OP5_SERVER
OP5_PASSWORD The password to login with on the OP5_SERVER
OP5_HOSTGROUPS Additional hostgroups to add to the host.
OP5_CONTACTGROUP Additional contactgroups to add to the host.
NO_SERVICE Set to 1 to disable installing the service (then you can manually create and activate the service when needed)
TLS_VERSION The TLS version to use (1.0, 1.1, 1.2, 1.3)
TLS_VERIFY_MODE The TLS verify mode to use (none, peer, fail_if_no_peer_cert)
TLS_CA The CA file to use for TLS connections (defaults to the Windows ROOT store)
CONF_SET Set a configuration value in the form of section1;key1;value1;section2;key2;value2…
IMPORT_CONFIG URL or file path to a configuration file to copy during install and use as the configuration for NSClient++
FLEET_SERVER Fleet server url (https://fleet.example.com) to enroll this host with during install
FLEET_TOKEN The one-time bootstrap token from the install command generated by the fleet server (required with FLEET_SERVER)
FLEET_HOSTNAME Host name to report to the fleet server (defaults to this machine’s host name)
FLEET_CA CA bundle used to verify the fleet server certificate (defaults to the Windows ROOT store)
FLEET_VERIFY_MODE TLS verify mode for the enrollment call (certificate, none). none requires FLEET_INSECURE=1
FLEET_INSECURE Set to 1 to allow an unauthenticated enrollment: a plain http:// FLEET_SERVER, or FLEET_VERIFY_MODE=none
LAYOUT On-disk layout: modern keeps the writable state in %ProgramData%\NSClient++ restricted to SYSTEM and administrators, legacy (default) keeps it in the install folder. Omit it to keep whatever the host already uses. Experimental - see below

On-disk layout (LAYOUT)

By default everything lives in the install folder, C:\Program Files\NSClient++\, which any logged-in user can read - including nsclient.ini with the web and NRPE passwords, the server’s TLS private key and the fleet identity. LAYOUT=modern moves that writable half to C:\ProgramData\NSClient++\ and restricts it to SYSTEM and Administrators; the program itself stays where it was installed.

msiexec /qn /i NSCP-<version>-x64.msi LAYOUT=modern

The same command on an upgrade moves the existing installation’s configuration, certificates and fleet identity for you.

Leaving the property out keeps the layout the host already has. An upgrade therefore never moves an installation that did not ask to move, and never moves a modern one back to legacy just because the property was not repeated.

LAYOUT=legacy against a host that is already on the modern layout is logged and ignored. The installer only ever moves files into the protected folder, so honouring it would record a layout whose files had not moved. To go back, use the agent itself, which migrates in both directions and can show you the plan first:

nscp settings --migrate-layout legacy --dry-run

Experimental

The modern layout is opt-in and marked experimental: upgrades in particular have not been tested at scale. Prefer it for new installs; for existing installs test the upgrade in your own environment first - configuration management, backups and scripts that reference the old paths are what will notice.

An already-installed host can also be switched later, without reinstalling: nscp settings --migrate-layout modern --dry-run shows exactly what would move.

See Securing NSClient++ for what it fixes and File layout for what lives where.

Features

NSClient++ consists of the following features most which can be disabled when doing silent installations.

Feature Name Title Description
CheckPlugins Check Plugins Various plugins to check your system. (Includes all check plugins)
ExtraClientPlugin Various client plugins Plugins to connect to various systems such as syslog, graphite and smtp
FirewallConfig Firewall Exception A firewall exception to allow NSClient++ to open ports
LuaScript Lua Scripting Allows running INTERNAL scripts written in Lua
NRPEPlugins NRPE Support NRPE Server Plugin. Support for the more versatile NRPE protocol (check_nrpe)
MySQLPlugin MySQL Support Plugin to check MySQL, MariaDB and Percona servers (includes the MariaDB Connector/C client library)
NSCAPlugin NSCA plugin Plugin to submit passive results to an NSCA server
CheckMK Check MK support Experimental support for check_mk server and clients
ElasticPlugin Elastic Search support Support for submitting metrics to elastic
NSCPlugins check_nt support NSClient Server Plugin. Support for the old NSClient protocol (check_nt)
PythonScript Python Scripting Allows running INTERNAL scripts written in Python
SampleScripts Scripts Scripts for checking and testing various aspects of your computer and NSClient++
Shortcuts Shortcuts Main Service shortcuts
WEBPlugins WEB Server NSClient WEB Server. Use this to administrate or check NSClient via a browser or REST API
OP5Monitoring OP5 Monitoring Scripts/config for the op5 monitoring system.

Silent install

Now we can put all this together using the normal silent installer which is again part of the standard windows install toolkit. So if you already have a framework for managing installs use that instead of this command line. The gist of it is: msiexec /quiet /i <MSI FILE> PROPERTY=PropertyValue ...

For instance Installing NSClient++ into c:\foobar using registry as configuration and not installing the Python script binaries.

msiexec /qn /l* log.txt /i NSCP-0.4.3.50-x64.msi INSTALLLOCATION=c:\FooBar CONFIGURATION_TYPE=registry://HKEY_LOCAL_MACHINE/software/NSClient++ ADDLOCAL=ALL REMOVE=PythonScript

Debugging

If you run into any issues or want to report a bug a good first step is to enable logging of the installation process. This is done by adding /l* log.txt to the command line (you can of course change the log file name to whatever you want).

BEWARE: The log file can contain sensitive information such as passwords so be careful when sharing it with others.

Specifying your monitoring tool

There is an option which can be used to define a base-line for your monitoring tool. If you do not have a supported monitoring tool you can set it to “none” which will use the generic configuration which works with all monitoring tools.

msiexec /i NSCP-<version>.msi MONITORING_TOOL=none

Silent op5 install

To enable active checks via NRPE from OP5 you can set the MONITORING_TOOL option to OP5.

msiexec /i NSClient++.msi MONITORING_TOOL=OP5

Silent op5 install (Northbound)

To enable passive reports via OP5s Northbound API you can set the OP5_SERVER, OP5_USER and OP5_PASSWORD options. In this case setting MONITORING_TOOL is done automatically when ever OP5_SERVER is detected.

msiexec /i NSClient++.msi OP5_SERVER=https://op5.com OP5_USER=monitor OP5_PASSWORD=rotinom

Enrolling with a fleet server

If you manage your agents from an NSClient fleet server, the installer can enroll the host while it installs, so the machine is managed from the moment the service starts. Generate an install command on the fleet server and pass the server url and the bootstrap token it gives you:

msiexec /qn /i NSCP-<version>-x64.msi FLEET_SERVER=https://fleet.example.com FLEET_TOKEN=<bootstrap-token>

During the install NSClient++ generates a key pair, sends a certificate request together with the token to FLEET_SERVER, and stores the certificate material it gets back as agent-state.json in the security folder. It also adds an include for the fleet-managed configuration ([/includes] fleet = ${fleet-folder}/fleet.ini). The service picks all of this up on the next start and begins syncing its configuration from the fleet server; there is no module to enable.

Both land wherever the host’s layout puts them - beside the installation by default, or under C:\ProgramData\NSClient++\ with LAYOUT=modern. The include is written as the ${fleet-folder} token rather than a resolved path, so it follows the layout rather than pinning it.

A few things worth knowing:

  • Enrollment is required to succeed. If the fleet server cannot be reached, or rejects the token, the install fails with an error explaining what went wrong rather than leaving you with an agent that never joined the fleet. Bootstrap tokens are one-time and are burned on first use, so a rejected token means generating a new install command.
  • The installer has to be allowed to write the configuration. Enrollment is what adds the include that makes the host read what the fleet server sends it, so combining FLEET_SERVER with ALLOW_CONFIGURATION=0 - or installing onto a configuration the installer cannot update - fails the install rather than enrolling a host that then ignores everything the fleet server tells it. The install log names the reason the configuration was held to be unchangeable.
  • An already enrolled host keeps its identity. If agent-state.json already exists (an upgrade, a repair, or a re-install over an existing installation) the enrollment is skipped and the existing identity is kept. Delete the file to enroll again.
  • Uninstalling discards the enrollment. agent-state.json holds this host’s private key and client certificate, so uninstalling removes it along with the other key material. The identity does not survive an uninstall/reinstall cycle, and because bootstrap tokens are one-time you need a fresh install command from the fleet server to enroll again - keep the host’s registration on the server in mind before uninstalling to reinstall. Upgrading in place is unaffected.
  • The fleet server is verified. The enrollment response supplies the certificate the agent pins for every later call and the key it trusts for executable bundles, so the connection is verified against the Windows ROOT store by default. Use FLEET_CA=<file> if the fleet server uses a private CA. FLEET_INSECURE=1 (with a http:// url and/or FLEET_VERIFY_MODE=none) opts out of that, which is only reasonable on a trusted network or for testing.
  • Keep the token out of your logs. The token is hidden from the MSI log, but treat the deployment script that carries it as a secret; the token is a credential that exchanges for this host’s client certificate.

The same enrollment can be done after installation with the command line:

nscp enroll --server https://fleet.example.com --token <bootstrap-token>

Copy configuration from a HTTP server

Staring with version 0.10.5 it is possible to download a configuration file from a HTTP server and use that as the configuration for NSClient++.

msiexec /i NSClient++.msi IMPORT_CONFIG=http://myserver.com/nsclient.ini
This will then copy the config file from the server and use that as the configuration file. This is useful if you do not have a good way to manage Windows Machines.

Use configuration from a HTTP server

A simple way to manage NSClient++ configuration is to use the HTTP configuration backend. This way you can manage the configuration from a central server and all your clients will automatically pick up the configuration from there. Any changes you make to the configuration file on the server will automatically be picked up by the clients.

msiexec /i NSClient++.msi CONFIGURATION_TYPE=http://myserver.com/nsclient.ini

Verifying the settings server

Over https the installer verifies the server certificate before it uses what it downloaded - that file becomes the whole configuration of the agent, including its external script definitions, so whoever can answer for the settings host would otherwise own the machine.

The certificate is checked against the Windows ROOT certificate store, which the installer exports to a temporary bundle for the duration of the install (the service maintains its own copy at ${ca-path}, but that file does not exist yet while the installer is running). Nothing needs to be configured for a settings server whose certificate was issued by a public CA, or by an internal CA that has been rolled out to the machine’s trust store.

For a private CA that is not in the Windows store, point TLS_CA at the issuing CA instead:

msiexec /i NSClient++.msi CONFIGURATION_TYPE=https://myserver.com/nsclient.ini TLS_CA=c:\certs\my-ca.pem

TLS_CA is used verbatim and replaces the exported store, so it also works for pinning a single issuer. It is written to boot.ini, so the service keeps using it for later fetches.

As a last resort verification can be turned off with TLS_VERIFY_MODE=none, which makes the download trust whatever answers. Do this only on a network you control; it is the one setting that turns a compromised or spoofed settings server into remote code execution on every agent that boots against it.