Configuration

Configuration is fairly simple and straight forward. Open the configuration file in notepad (or your favorite editor) "notepad <installation path>\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 [RemoteConfiguration] module but in short:

NSClient++ -noboot RemoteConfiguration ini2reg

A sample configuration file is included in the download but can also be found here trunk/NSC.dist

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.

A complete list of all available modules: ListTagged(module)?

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.

Module Configuration

NRPE Listener Sections

NRPE Section

This is section is included from the following page NRPEListener/config/nrpe

Overview

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

Option	Default	Description
port	5666	The port to listen to
allowed_hosts		A list of hosts allowed to connect via NRPE.
use_ssl	1	Boolean value to toggle SSL encryption on the socket connection
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.

Advanced options:

Option	Default	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.
script_dir		Load all scripts in a directory and use them as commands. Probably dangerous but usefull if you have loads of scripts :)
bind_to_address		The address to bind to when listening to sockets.

port

The port to listen to

Default

5666

allowed_hosts

A list (comma 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

Default

Empty list (falls back to the one defined under [Settings]

use_ssl

Boolean value to toggle SSL (Secure Socket Layer) encryption on the socket connection. This corresponds to the -n flag in check_nrpe

Values

Value	Meaning
0	Don't use SSL
1	Use SSL encryption

Default

1 (enabled)

bind_to_address

The address to bind to when listening to sockets. If not specified the "first" (all?) one will be used (often the correct one).

Values

IP address of any interface of the server.

Default

Empty (first (all?) interface will be used)

command_timeout

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 so internal commands may execute forever.

It is usually a good idea to set this to less then the timeout used with check_nrpe

Default

60

allow_arguments

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.

NOTICE That there are more then one place to set this!

Default

0 (means don't allow arguments)

Values

Value	Meaning
0	Don't allow arguments
1	Allow arguments.

allow_nasty_meta_chars

Allow NRPE execution to have “nasty” meta characters that might affect execution of external commands (things like > “ etc).

Default

0 (means don't allow meta characters)

Values

Value	Meaning
0	Don't allow meta characters
1	Allow meta characters

socket_timeout

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.

Default

30 seconds

script_dir

Load all scripts in a directory and use them as commands. Probably dangerous but useful if you have loads of scripts :)

Default

Empty (don't load any scripts)

performance_data

Send performance data back to Nagios (set this to 0 to remove all performance data)

Default

1

Values

Value	Meaning
0	Don't send performance data
1	Send 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

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.

Default

1024

NRPE Handlers Section

This is section is included from the following page NRPEListener/config/nrpe_handlers

Ovreview

DEPRECATED This part of the module is deprecated and should not be used. Refer to the [CheckExternalScripts] module instead. This module can add two types of command handlers.

First there are external command handlers that execute a separate program or script and simply return the output and return status from that. The other possibility is to create an alias for an internal command.

To add an external command you add a command definition under the “NRPE Handlers” section. A command definition has the following syntax:

[NRPE Handlers]
command_name=/some/executable with some arguments
test_batch_file=c:\test.bat foo $ARG1$ bar
command[check_svc]=inject CheckService checkAll

The above example will on an incoming “test_batch_file” execute the c:\test.bat file and return the output as text and the return code as the Nagios status.

Alias (builtin commands)

To add an internal command or alias is perhaps a better word. You add a command definition under the “NRPE Handlers” section. A command definition with the following syntax:

command_name=inject some_other_command with some arguments
check_cpu=inject checkCPU warn=80 crit=90 5 10 15

The above example will on an incoming “check_cpu” execute the internal command “checkCPU” with predefined arguments give in the command definition.

NRPE_NT Syntax

To leverage existing infrastructure you can copy your old definitions from NRPE_NT as-is. Thus the following:

command[check_svc]=inject CheckService checkAll

translates into a command called check_svc with the following definition:

CheckServcice checkAll

File Logging Sections

This is section is included from the following page FileLogger/config

Overview

This section has options for how logging is performed with the [FileLogger] module. First off notice that for logging to make sense you need to enable the “FileLogger.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	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
root_folder	exe	Root folder if not absolute

debug

A Boolean value that toggles if debug information should be logged or not. This can be either 1 or 0.

Default

0

Values

Value	Meaning
0	Don't log debug messages
1	Log debug messages

file

The file to write log data to. If no directory is used this is relative to the NSClient++ binary.

Default

nsclient.log

date_mask

The date format used when logging to a file

Default

%Y-%m-%d %H:%M:%S

root_folder

Root folder if not absolute

Default

exe

Values

local-app-data

The file system directory that contains application data for all users. A typical path is C:\Documents and Settings\All Users\Application Data. This folder is used for application data that is not user specific. For example, an application can store a spell-check dictionary, a database of clip art, or a log file in the CSIDL_COMMON_APPDATA folder. This information will not roam and is available to anyone using the computer.

exe

Location of NSClient++ binary

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 than 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.

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.
CheckResolution?	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.
ProcessEnumerationMethod?	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
MemoryCommitLimit?	\Memory\Commit Limit	Counter to use to check upper memory limit.
MemoryCommitByte?	\Memory\Committed Bytes	Counter to use to check current memory usage.
SystemSystemUpTime?	\System\System Up Time	Counter to use to check the uptime of the system.
SystemTotalProcessorTime?	\Processor(_total)\% Processor Time	Counter to use for CPU load.
ProcessEnumerationMethod?	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 CheckExternalScripts module. Syntax is: <command>=<script> <arguments> for instance:

check_es_long=scripts\long.bat
check_es_ok=scripts\ok.bat
check_es_nok=scripts\nok.bat
check_vbs_sample=cscript.exe //T:30 //NoLogo scripts\check_vb.vbs

External Alias

Works like the "inject" concept of NRPE scripts module. But in short a list of aliases available. An alias is an internal command that has been "wrapped" (to add arguments). Be careful so you don't create loops (ie check_loop=check_a, check_a=check_loop)

alias_cpu=checkCPU warn=80 crit=90 time=5m time=1m time=30s
alias_disk=CheckDriveSize MinWarn=10% MinCrit=5% CheckAll FilterType=FIXED
alias_service=checkServiceState CheckAll
alias_mem=checkMem MaxWarn=80% MaxCrit=90% ShowAll type=physical

Event Log Sections

This is section is included from the following page CheckEventLog/config

Configuration for CheckEventLog module

Section with configuration keys for the CheckEventLog module

Path / Section	Key	Default value	Description
/settings/eventlog/real-time	debug	0	DEBUG
/settings/eventlog/real-time	enabled	0	REAL TIME CHECKING
/settings/eventlog/real-time	log	application,system	LOGS TO CHECK
/settings/eventlog/real-time	startup age	30m	STARTUP AGE
/settings/eventlog/real-time/filters			REALTIME FILTERS
/settings/eventlog	debug	0	DEBUG
/settings/eventlog	lookup names	1	LOOKUP NAMES
/settings/eventlog	buffer size	131072	BUFFER_SIZE
/settings/eventlog	syntax		SYNTAX

CONFIGURE REALTIME CHECKING

A set of options to configure the real time checks

Section: /settings/eventlog/real-time

Keys:

Key	Default	Title	Description
debug	0	DEBUG	Log missed records (usefull to detect issues with filters) not usefull in production as it is a bit of a resource hog.
enabled	0	REAL TIME CHECKING	Spawns a backgrounnd thread which detects issues and reports them back instantly.
log	application,system	LOGS TO CHECK	Comma separated list of logs to check
startup age	30m	STARTUP AGE	The initial age to scan when starting NSClient++

Sample:

# CONFIGURE REALTIME CHECKING
# A set of options to configure the real time checks
[/settings/eventlog/real-time]
# DEBUG
# Log missed records (usefull to detect issues with filters) not usefull in production as it is a bit of a resource hog.
debug=0
# REAL TIME CHECKING
# Spawns a backgrounnd thread which detects issues and reports them back instantly.
enabled=0
# LOGS TO CHECK
# Comma separated list of logs to check
log=application,system
# STARTUP AGE
# The initial age to scan when starting NSClient++
startup age=30m

DEBUG

Description: Log missed records (usefull to detect issues with filters) not usefull in production as it is a bit of a resource hog.

Key: debug

Default value: 0

Used by: CheckEventlog?, CheckEventLog

Sample:

# DEBUG
# Log missed records (usefull to detect issues with filters) not usefull in production as it is a bit of a resource hog.
[/settings/eventlog/real-time]
debug=0

REAL TIME CHECKING

Description: Spawns a backgrounnd thread which detects issues and reports them back instantly.

Key: enabled

Default value: 0

Used by: CheckEventlog?, CheckEventLog

Sample:

# REAL TIME CHECKING
# Spawns a backgrounnd thread which detects issues and reports them back instantly.
[/settings/eventlog/real-time]
enabled=0

LOGS TO CHECK

Description: Comma separated list of logs to check

Key: log

Default value: application,system

Used by: CheckEventlog?, CheckEventLog

Sample:

# LOGS TO CHECK
# Comma separated list of logs to check
[/settings/eventlog/real-time]
log=application,system

STARTUP AGE

Description: The initial age to scan when starting NSClient++

Key: startup age

Default value: 30m

Used by: CheckEventlog?, CheckEventLog

Sample:

# STARTUP AGE
# The initial age to scan when starting NSClient++
[/settings/eventlog/real-time]
startup age=30m

REALTIME FILTERS

A set of filters to use in real-time mode

Section: /settings/eventlog/real-time/filters

Sample:

# REALTIME FILTERS
# A set of filters to use in real-time mode
[/settings/eventlog/real-time/filters]

EVENT LOG SECTION

Section for the EventLog? Checker (CheckEventLog.dll).

Section: /settings/eventlog

Keys:

Key	Default	Title	Description
debug	0	DEBUG	Log more information when filtering (usefull to detect issues with filters) not usefull in production as it is a bit of a resource hog.
lookup names	1	LOOKUP NAMES	Lookup the names of eventlog files
buffer size	131072	BUFFER_SIZE	The size of the buffer to use when getting messages this affects the speed and maximum size of messages you can recieve.
syntax		SYNTAX	Set this to use a specific syntax string for all commands (that don't specify one).

Sample:

# EVENT LOG SECTION
# Section for the EventLog Checker (CheckEventLog.dll).
[/settings/eventlog]
# DEBUG
# Log more information when filtering (usefull to detect issues with filters) not usefull in production as it is a bit of a resource hog.
debug=0
# LOOKUP NAMES
# Lookup the names of eventlog files
lookup names=1
# BUFFER_SIZE
# The size of the buffer to use when getting messages this affects the speed and maximum size of messages you can recieve.
buffer size=131072
# SYNTAX
# Set this to use a specific syntax string for all commands (that don't specify one).
syntax=

DEBUG

Description: Log more information when filtering (usefull to detect issues with filters) not usefull in production as it is a bit of a resource hog.

Key: debug

Default value: 0

Used by: CheckEventlog?, CheckEventLog

Sample:

# DEBUG
# Log more information when filtering (usefull to detect issues with filters) not usefull in production as it is a bit of a resource hog.
[/settings/eventlog]
debug=0

LOOKUP NAMES

Description: Lookup the names of eventlog files

Key: lookup names

Default value: 1

Used by: CheckEventlog?, CheckEventLog

Sample:

# LOOKUP NAMES
# Lookup the names of eventlog files
[/settings/eventlog]
lookup names=1

BUFFER_SIZE

Description: The size of the buffer to use when getting messages this affects the speed and maximum size of messages you can recieve.

Key: buffer size

Default value: 131072

Used by: CheckEventlog?, CheckEventLog

Sample:

# BUFFER_SIZE
# The size of the buffer to use when getting messages this affects the speed and maximum size of messages you can recieve.
[/settings/eventlog]
buffer size=131072

SYNTAX

Description: Set this to use a specific syntax string for all commands (that don't specify one).

Key: syntax

Used by: CheckEventlog?, CheckEventLog

Sample:

# SYNTAX
# Set this to use a specific syntax string for all commands (that don't specify one).
[/settings/eventlog]
syntax=

includes

A list of other configuration files to include when reading this file. Might be useful if you have a very complex setup or want to have setting split up in segments.

NSCA Agent

Options to configure the new NSCA module.

Option	Default value	Description
interval	60	Time in seconds between each report back to the server (cant as of yet be set individually so this is for all "checks")
nsca_host	...	The NSCA/Nagios(?) server to report results to.
nsca_port	5667	The NSCA server port
encryption_method	1	Number corresponding to the various encryption algorithms (see below). Has to be the same as the server or it wont work at all.
password		The password to use. Again has to be the same as the server or it wont work at all.

Advanced options:

Option	Default value	Description
hostname		The host name of this host if set to blank (default) the windows name of the computer will be used.
debug_threads	1	Number of threads to run, no reason to change this really (unless you want to stress test something)

Supported encryption methods:

#	Algorithm
0	None (Do NOT use this option)
1	Simple XOR (No security, just obfuscation, but very fast)
2	DES
3	3DES (Triple DES)
4	CAST-128
6	xTEA
8	BLOWFISH
9	TWOFISH
11	RC2
14	RIJNDAEL-128 (AES)
20	SERPENT

NSCA Commands

A list of commands to run and submit each time we report back to the NSCA server. A command starting with host_ will be submitted as a host command. For an example see below: This will report back one service check (called my_cpu_check) and one host check (host checks has no service name).

[NSCA Commands]
my_cpu_check=checkCPU warn=80 crit=90 time=20m time=10s time=4
host_check=check_ok

LUA Scripts

A list of LUA script to load at startup. In difference to "external checks" all LUA scripts are loaded at startup. Names have no meaning since the script (on boot) submit which commands are available and tie that to various functions.

[LUA Scripts]
scripts\test.lua

NRPE Handlers

This is a list of handlers for NRPE execution this can of course be used by any module (such as NSClient) but for historical reasons they are located in this section especially as NRPE plug-in is the one that does the actual execution.

The handlers can have two different syntaxes:

• command[my_command]=/some/executable
• my_command=/some/executable

The latter is the preferred way as it is shorter.

Running NSClient++ as LocalService? instead of as SYSTEM

Note: this is from the forums and might not work for all NSCLient++ modules! I would recommend you to test your setup under the System account first!

Here's how you can run NSClient++ as LocalService under Windows Server 2003 and Windows Server 2008:

1] ​Install NSClient++ as normal 2] From a command prompt in the NSClient++ directory:

net stop NSClientpp
sc config NSClientpp obj= "NT AUTHORITY\LocalService"
if not exist nsclient.log type NUL: > nsclient.log
cacls nsclient.log /e /g "NT AUTHORITY\LocalService":c
net start NSClientpp

which

[a] Stops the NSClientpp service, if it is running

[b] Configures the NSClientpp service to run as LocalService instead of SYSTEM

[c] Creates a nsclient.log file if it doesn't already exist - the NSClientpp service should have write access to this file

[d] Gives the NSClientpp service write access to nsclient.log

[e] Starts the NSClientpp service

I haven't tested this with NSClientListener.dll/check_nt, but it seems to work as expected with the following modules: FileLogger.dll, CheckSystem.dll, CheckDisk.dll, NRPEListener.dll, CheckEventLog.dll, CheckHelpers.dll

For those interested, a good explanation of the difference between the SYSTEM, LocalService, and NetworkService accounts can be found at ​http://go.microsoft.com/fwlink/?LinkId=41312