NagiosAddons--NSClient++

一. About NSClient++

NSClient++ (or nscp as I tend to call it nowadays) aims to be a simple yet powerful and secure monitoring daemon for Windows operating systems. It is built for Nagios, but nothing in the daemon is actually Nagios specific and could probably, with little or no change, be integrated into any monitoring software that supports running user tools for polling.

The structure of the daemon is a simple NT service that loads plug-ins to an internal stack. The plug-ins can then request data (poll performance data) from the other plug-ins through the internal stack. As of now there are a few plug-ins for basic performance data collection. For details of supplied modules, see .

NSClient++ can be extended in two ways: you can either write your own plug-in or you can execute an external script (as of now batch/exe/*). Writing your own plug-in is, of course, the most powerful way but requires knowledge of C++ or other languages which can produce DLLs and interface with regular C programs (generally, every other language available, but there is some simple API helpers for C/C++ as well as descriptions).

As for checking with NSClient++, I would recommend NRPE as it is a lot more flexible than check_nt. But NSClient has full support for check_nt, and if there is an interest, I could probably add support for check_nt from nc_net.

Supported OS/Platform

NSClient++ should run on the following operating systems:

• NT4 (SP5?)
• Windows 2000 W2K
• Windows XP
• Windows 2003
• Windows Vista
• ...

...as well as the following platforms:

• Win32
• x64 (AMT64/EMT64)
• IA64 (Itanium)

Whats in a name?

Since I have noticed some ppl. use other names for the client I decided to list them here to make it simpler (ie. Goggle might find it) for people to find it.

• NSClient++ (the "real" name)
• NSCP (what I sometimes use)
• NSClientpp (version of NSCLient++)
• NSClient (?)
• Saw a French (Spanish) site use: NSC++

Again I myself as stated before prefer NSClient++ or NSCP.

二. Installation

NSClient++ comes with simple command line option for registering (and deregistering) the service but it does not have a GUI installer.

Thus to install the Client you only need to copy the files to a directory of your choice and then run “NSClient++ /install”.

Before you start NSClient++ you need to configure it by editing the configuration file (NSC.ini). The configuration file is a simple text file and is explained in detail under . The files needed by NSClient++ varies but mainly the exe and DLL's in the NSClient++ root are required as well as all the modules you plan to use from the modules subdirectory (/modules/*).

The configuration file (NSC.ini) NEEDS to be configured as for security reasons all plug-ins are disabled by default. The reason for this is so no one will accidentally install this and get potential security issues, I believe that things should be "off" by default. Also notice that by default allowed_hosts are 127.0.0.1 so you need to modify this as well.

If you plan to use the module (that shows a system tray icon on the desktop you need to install the module as well as NSClient++. To install NSClient++ execute the following command:

 NSClient++ /install
 NSClient++ SysTray install

To uninstall NSClient++ execute the following command:

 NSClient++ SysTray uninstall
 NSClient++ /uninstall

To start NSClient++ execute the following command:

 NSClient++ /start

To stop NSClient++ execute the following command:

 NSClient++ /stop

If you only wish to test it or debug the client you can use the following without installing it first.

 NSClient++ /test

Firewall

Firewall configuration should be pretty straight forward:

If you use NRPEListener (check_nrpe) you need the NRPE port open (usually 5666) from the nagios server towards the client.

nagios:* -> client:5666

If you use the NSClientListener (check_nt) you need the (modified) NSClient port open (usually 12489) from the nagios server towards the client.

nagios:* -> client:12489

If you use the NSCA Module (passive checks) you need the NSCA port open from the client towards the nagios server.

client:* -> nagios:5667

If you use the NRPEClient module to check any remote systems (use NSClient++ as a proxy) you need to have NRPE port (usually 5666) open from NSClient++ (the proxy) to the remote-client in addition to the method you use to submit the results to the server.

nsclient-proxy:* -> remote-client:5666

All these ports can be changed so check your nsc.ini.

NT4

NT4 does not come with the PDH library and you need to install that before using NSClient++. PDH can be downloaded from Microsoft: and the simplest way to install it is to uncompress it directly into the NSClient++ directory.

NT4 also (sometimes) lack the PSAPI helper which is available in the "Platform SDK Redistributable: PSAPI for Windows NT" from Microsoft. as with the PDH either install in system32 or local NSClient++ directory.

三. Configuration

Configuration is fairly simple and straight forward. Open the configuration file in notepad (or you favorite editor) "notepad \NSC.ini" and edit it accordingly. A longer description of the Configuration file is included in the following page.

The file has sections (denoted with section name in brackets) and key/value pairs (denoted by key=value). Thus it has the same syntax as pretty much any other INI file in windows.

The sections are described in short below. The default configuration file has a lot of examples and comments so make sure you change this before you use NSClient++ as some of the examples might be potential security issues.

The configuration can also be stored in the system registry (HKLM\Software\NSClient++) there is currently no UI to configure this so the simplest way is to maintain the configuration in the INI file and "Migrate that" to the registry. This is can be done via the [] module but in short:

NSClient++ -noboot RemoteConfiguration ini2reg

A sample configuration file is included in the download but can also be found here

Modules

This is a list of modules to load at startup. All the modules included in this list has to be NSClient++ modules and located in the modules subdirectory. This is in effect the list of plug-ins that will be available as the service is running. For information on the various plug-ins check the Modules section in the navigation box.

A good idea here is to disable all modules you don’t actually use for two reasons. One less code equals less potential security holes and two less modules means less resource drain.

Settings

This section has generic options for how NSClient++will work, some of these settings (such as allowed_hosts) is inherited in sections below so it is probably a better idea to set them here in the "global" section.

The options you have available here are

Option	Default value	Description
obfuscated_password	...	An obfuscated version of password. For more details refer to the password option below. To create the obfuscated Password use: "NSClient++.exe /encrypt"
password	...	The password used by various (presently only NSClient) daemons. If no password is set everyone will be able to use this service remotely.
allowed_hosts	127.0.0.1	A list (comma separated) with hosts that are allowed to connect and query data. If this is empty all hosts will be allowed to query data. BEWARE: NSClient++ will not resolve the IP address of DNS entries if the service is set to startup automatically. Use an IP address instead.
use_file	0	Has to be set to 1 if you want the file to be read (if set to 0, and the use_reg is set to 1 the registry will be used instead)

Advanced options:

Option	Default value	Description
master_key	...	The secret "key" used when (de)obfuscating passwords.
cache_allowed_hosts	1	Used to cache looked up hosts if you check dynamic/changing hosts set this to 0.

Log

This section has options for how logging is performed. First off notice that for logging to make sense you need to enable the “.dll” module that logs all log data to a text file in the same directory as the NSClient++ binary if you don’t enable any logging module nothing will be logged.

The options you have available here are

Option	Default value	Description
debug	0	A Boolean value that toggles if debug information should be logged or not. This can be either 1 or 0.
file	nsclient.log	The file to write log data to. If no directory is used this is relative to the NSClient++ binary.
date_mask	%Y-%m-%d %H:%M:%S	The date format used when logging to a file

NSClient

This is the NSClient module configuration options.

Option	Default value	Description
port	12489	The port to listen to
obfuscated_password		An obfuscated version of password. For more details refer to the password option below.
password		The password that incoming client needs to authorize themselves by. This option will replace the one found under Settings for NSClient. If this is blank the option found under Settings will be used. If both are blank everyone will be granted access.
allowed_hosts		A list (coma separated) with hosts that are allowed to poll information from NSClient++. This will replace the one found under Setting for NSClient if present. If not present the same option found under Settings will be used. If both are blank all hosts will be allowed to access the system. BEWARE: NSClient++ will not resolve the IP address of DNS entries if the service is set to startup automatically. Use an IP address instead or set cache_allowed_hosts=0 see above.
bind_to_address		The address to bind to when listening to sockets, useful if you have more then one NIC/IP address and want the agent to answer on a specific one.
socket_timeout	30	The timeout when reading packets on incoming sockets. If the data has not arrived within this time we will bail out. and discard the connection.
version	auto	The version number to return for the CLIENTVERSION check (useful to "simulate" an old/different version of the client, auto will be generated from the compiled version string inside NSClient++

Advanced options:

Option	Default value	Description
socket_back_log		Number of sockets to queue before starting to refuse new incoming connections. This can be used to tweak the amount of simultaneous sockets that the server accepts. This is an advanced option and should not be used.

NRPE

This is configuration for the NRPE module that controls how the NRPE listener operates.

Option	Default value	Description
port	5666	The port to listen to
allowed_hosts		A list (coma separated) with hosts that are allowed to poll information from NRPE. This will replace the one found under Setting for NRPE if present. If not present the same option found under Settings will be used. If both are blank all hosts will be allowed to access the system
use_ssl	1	Boolean value to toggle SSL encryption on the socket connection
bind_to_address		The address to bind to when listening to sockets.
command_timeout	60	The maximum time in seconds that a command can execute. (if more then this execution will be aborted). NOTICE this only affects external commands not internal ones.
allow_arguments	0	A Boolean flag to determine if arguments are accepted on the incoming socket. If arguments are not accepted you can still use external commands that need arguments but you have to define them in the NRPE handlers below. This is similar to the NRPE "dont_blame_nrpe" option.
allow_nasty_meta_chars	0	Allow NRPE execution to have “nasty” meta characters that might affect execution of external commands (things like > “ etc).
socket_timeout	30	The timeout when reading packets on incoming sockets. If the data has not arrived within this time we will bail out. and discard the connection.
script_dir		Load all scripts in a directory and use them as commands. Probably dangerous but usefull if you have loads of scripts :)

Advanced options:

Option	Default value	Description
performance_data	1	Send performance data back to nagios (set this to 0 to remove all performance data)
socket_back_log		Number of sockets to queue before starting to refuse new incoming connections. This can be used to tweak the amount of simultaneous sockets that the server accepts. This is an advanced option and should not be used.
string_length	1024	Length of payload to/from the NRPE agent. This is a hard specific value so you have to "configure" (read recompile) your NRPE agent to use the same value for it to work.

Check System

Here you can set various options to configure the System Check module.

Option	Default value	Description
CPUBufferSize	1h	The time to store CPU load data.
	10	Time between checks in 1/10 of seconds.

Advanced options:

Option	Default value	Description
auto_detect_pdh	1	Set this to 0 to disable auto detect (counters.defs) PDH language and OS version.
dont_use_pdh_index	0	Set this to 1 if you dont want to use indexes for finding PDH counters.
force_language		Set this to a locale ID if you want to force auto-detection of counters from that locale.
	auto	Set the method to use when enumerating processes PSAPI, TOOLHELP or auto
check_all_services[SERVICE_BOOT_START]	ignored	Set how to handle services set to SERVICE_BOOT_START state when checking all services
check_all_services[SERVICE_SYSTEM_START]	ignored	Set how to handle services set to SERVICE_SYSTEM_START state when checking all services
check_all_services[SERVICE_AUTO_START]	started	Set how to handle services set to SERVICE_AUTO_START state when checking all services
check_all_services[SERVICE_DEMAND_START]	ignored	Set how to handle services set to SERVICE_DEMAND_START state when checking all services
check_all_services[SERVICE_DISABLED]	stopped	Set how to handle services set to SERVICE_DISABLED state when checking all services
	\Memory\Commit Limit	Counter to use to check upper memory limit.
	\Memory\Committed Bytes	Counter to use to check current memory usage.
	\System\System Up Time	Counter to use to check the uptime of the system.
	\Processor(_total)\% Processor Time	Counter to use for CPU load.
	auto	Set the PROCESS enumeration method (auto or TOOLHELP or PSAPI)

External Script

Configure how the External Scripts module works (not to be confused with the "External Scripts" section below that holds scripts that can be run.

Option	Default value	Description
command_timeout	60	The maximum time in seconds that a command can execute. (if more then this execution will be aborted). NOTICE this only affects external commands not internal ones.
allow_arguments	0	A Boolean flag to determine if arguments are accepted on the incoming socket. If arguments are not accepted you can still use external commands that need arguments but you have to define them in the NRPE handlers below. This is similar to the NRPE "dont_blame_nrpe" option.
allow_nasty_meta_chars	0	Allow NRPE execution to have “nasty” meta characters that might affect execution of external commands (things like > “ etc).
script_dir		When set all files in this directory will be available as scripts. This is pretty dangerous but can be a bit useful if you use many scripts and you are sure no one else can add files there.

External Scripts

A list of scripts available to run from the module. Syntax is: =