NSClient documentation

February 2002 - Yves Rubin - rubiyz@yahoo.com
Official Web Site: http://www.ifrance.com/rubiyz/
FAQ J http://www.ifrance.com/rubiyz/faq.htm

Purpose

NSClient has been developed to get vital information concerning Windows NT servers from Netsaint. Virtually every performance counter of Windows can be retrieved by the plugin.

License

This tool has been developed in the same spirit as Netsaint, which means that it is freeware and release under the GNU General Public License.

Requirement

• Windows NT 4 or Windows 2000 ENGLISH or GERMAN version.
• Need the pdh.dll and psapi.dll libraries to work

For the compilation:

• Jedi Code Library (http://www.delphi-jedi.org)
• Full Win32 Api from Marcel van Brakel (http://www.delphi-jedi.org)

History

10.02.2002 – 1.06.2	Beta version - New psapi.dll, pdh.dll - new jedi library - use of jwaPDH library - new language in Counters.defs - compiled with Delphi 6
13.09.2001 – 1.06.0	Beta version - Fix the service start up error message - Improve the event log handling - Should work on any Windows version. Different platform languages shouldn’t be a problem anymore.
09.05.2001 – 1.05.2	Beta version - Fix some issue with the German support - Build using the Jedi Code release 1.2 - Add the psapi.dll library which should fix the PROCSTATE issue
18.04.2001 - 1.05.0	Beta version. - Add German support to NSClient
27.03.2001 - 1.04.5	Release version.  - Some documentation changes. - Fix the wrong check_nt.c in UnixSource folder.
06.03.2001 - 1.04.4	- Change the way the description is handled in the custom counter requests to improve the flexibility.
28.02.2001 - 1.04.3	- Fix an issue with process check under Windows 2000 SP1
26.02.2001 - 1.04.2	- Add the "custom counter" query feature - Fix some errors with pdh.dll calls - New version of pdh.dll - Better information in the EventLog
06.12.2000 - 1.03	- Add the memory usage feature
29.11.2000 - 1.02	- First release

Features

• Check CPU load on single or multiprocessors system during the last 24 hours.
• Check disk space
• Check memory use
• Check uptime time of the machine
• Check services states
• Check processes
• Can check every available performance counter

Installation

On the Windows machine

1. Copy pNSClient.exe in any directory on the machine you want to monitor. ie. (c:\nsclient).
2. Open a dos prompt in the installation directory
3. Run the following command : >pNSClient /install
4. Start the service 'Netsaint NT Agent' in the services applet of the control panel.

The installation will create an entry for the service in the registry and create a new key to store parameters. The created key is the following:

HKEY_LOCAL_MACHINE\SOFTWARE\NSClient

Please read if you are using another Windows version than English !

A new file “counters.defs” has been added in the NSClient folder. This file is the resource file for counters description for every language. At this time, only English and german are declared. You can easily add another language by defining all counters for this language. The language code can be found in the Windows Event Log in the NSClient startup message. I would be please to update this file if you provide me with the correct information for other languages.

On the Unix machine

1. Copy the file 'check_nt' under the libexec folder of Netsaint
2. Add the following lines to the commands.cfg file:

# NSClient
command[check_nt_disk]=$USER1$/check_nt -H $HOSTADDRESS$ -p 1248 -v USEDDISKSPACE -l $ARG1$ -w $ARG2$ -c $ARG3$
command[check_nt_cpuload]=$USER1$/check_nt -H $HOSTADDRESS$ -p 1248 -v CPULOAD -l $ARG1$
command[check_nt_uptime]=$USER1$/check_nt -H $HOSTADDRESS$ -p 1248 -v UPTIME
command[check_nt_clientversion]=$USER1$/check_nt -H $HOSTADDRESS$ -p 1248 -v CLIENTVERSION
command[check_nt_process]=$USER1$/check_nt -H $HOSTADDRESS$ -p 1248 -v PROCSTATE -l $ARG1$
command[check_nt_service]=$USER1$/check_nt -H $HOSTADDRESS$ -p 1248 -v SERVICESTATE -l $ARG1$
command[check_nt_memuse]=$USER1$/check_nt -H $HOSTADDRESS$ -p 1248 -v MEMUSE -w $ARG1$ -c $ARG2$
command[check_nt_pagingfile]=$USER1$/check_nt -H $HOSTADDRESS$ -p 1248 -v COUNTER -l "\\Paging File(_Total)\\% Usage","Paging File usage is %.2f %%" -w $ARG1$ -c $ARG2$

Uninstallation

1. Go to the installation directory and run the following command: >pNSClient /uninstall

All entries in the registry will be removed as well as the definition of the service..

Configuration

There are two parameters you can change: the port (default: 1248) and the password (default: 'None'). These two settings are store in the registry and can only be changed using 'regedit'. Open the following key and change the values if needed :

HKEY_LOCAL_MACHINE\SOFTWARE\NSClient\Parms

If you change the password, you will have to use the -s <password> with every request you send to NSClient.

Plugin syntax

CPULoad

Syntax: check_nt -H <hostname> -p <port> -v CPULOAD -l <minutes range>,<warning percent>,<critical percent>

• <minutes range> between 1 and 1440 (24 hours)
• <warning percent> and <critical percent> : thresholds between 1 and 100.

You can check several intervals in one shot. The follwing command get the average for the last 10min., 60min. and 24hours.

Example:
./check_nt -H 192.168.1.1 -p 1248 -v CPULOAD -l 10,80,95,60,80,95,1440,80,95

Disk usage

Syntax: check_nt -H <hostname> -p <port> -v USEDDISKSPACE -l <drive letter> [-w <warning percent> ] [-c <critical percent>]

• drive letter should be only one character.
• <warning percent> and <critical percent> : thresholds between 1 and 100.

Example:
./check_nt -H 192.168.1.1 -p 1248 -v USEDDISKSPACE -l C -w 80 -c 90

Uptime

Syntax: ./check_nt -H <hostname> -p <port> -v UPTIME

This plugin doesn't care about warning or critical values. Only the uptime of the machine is received.

Services states

Syntax: check_nt -H <hostname> -p <port> -v SERVICESTATE [-d SHOWALL] -l <service 1>[,<service 2>,<service 3>,...]

• <service> should be the real name of the service, not the displayed name. You can find this information when going to the registry for the corresponding service : HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services

or use the free utility: 'Service Manager NT' : http://www-rnks.informatik.tu-cottbus.de/~fsch/english/nttols.htm

• -d SHOWALL can be specified if you want to see all tested services including started ones.

You can specify serveral services in one request. No blank should appear in the list !

If not all services are running, you get the faulty one(s) and a critical state.

Example:
./check_nt -H 192.168.1.1 -p 1248 -v SERVICESTATE -d SHOWALL -l LanmanServer,Schedule

Processes states

Syntax: check_nt -H <hostname> -p <port> -v PROCSTATE [-d SHOWALL] -l <process 1>[,<process 2>,<process 3>,...]

• <processes> You can find process name in the Windows NT Task Manager.
• -d SHOWALL can be specified if you want to see all tested processes including running ones.

You can specify serveral processes in one request. No blank should appear in the list !

If not all processes are running, you get the faulty one(s) and a critical state.

Example:
./check_nt -H 192.168.1.1 -p 1248 -v PROCSTATE -d SHOWALL -l McShield.exe,RASMAN.EXE

Client version

Syntax: check_nt -H <hostname> -p <port> -v CLIENTVERSION

Return the NSClient version. No warning or critical threshold can be specified.

Memory usage

Syntax: check_nt -H <hostname> -p <port> -v MEMUSE [-w <warning percent> ] [-c <critical percent>]

• <warning percent> and <critical percent> : thresholds between 1 and 100.

Example: 
./check_nt -H 192.168.1.1 -p 1248 -v MEMUSE -w 80 -c 90

"Custom counter"

Syntax: check_nt -H <hostname> -p <port> -v COUNTER -l <counter name>[,<counter description>] [-w <warning percent> ] [-c <critical percent>]

• <counter name> is the exact description of the Windows counter. Is must be inclosed in " and the \ should be doubled.
• <counter description> is the description which is displayed in the "Service Information" column. This string is passed to a printf command, which mean that you need to give a precise and specific syntax to make it works. Have a look at any printf reference to get the full story about this C command. Here are some examples:
• "Paging file usage is %.2f %%" (the %.2f means that the result will be displayed with two decimal digits. The double % represents a % in the printf syntax.
• "%.f %% of the paging file used" (the %.f means that the result will be displayed with no decimal digit.

The results returned by NSClient have five decimal digits.

• <warning percent> and <critical percent> : thresholds between 1 and 100. If <warning percent> is higher than <critical percent>, the check is reversed.

Example: 
./check_nt -H 192.168.1.1 -p 1248 -v COUNTER -l "\\Paging File(_Total)\\% Usage","Paging file usage is %.2f %%" -w 80 -c 90
./check_nt -H 192.168.1.1 -p 1248 -v COUNTER -l "\\Process(_Total)\\Thread Count","Thread Count: %.f" -w 600 -c 800
./check_nt -H 192.168.1.1 -p 1248 -v COUNTER -l "\\Server\\Server Sessions","Server Sessions: %.f" -w 20 -c 30

Technical information

Windows agent

NSClient has been developed using Borland Delphi 5. It is installed as a service.

Every five seconds, NSClient query Windows to get the CPU load and store this information in a circular buffer which keeps the measures for the last 24 hours. That's the only task of the agent if no request is sent to him.

Have a look at the source code in case you want to know more about it. It's well documented so you shouldn't have too much pain to figure out how it works. Some functions and pieces of code where found on the internet, so I thank very much the programmers who release them as open source. When possible, credits are left in the code.

Unix plug in

The Unix plugin has been written in C, using a template by Ethan Galstad. It mostly uses common functions and shoud be compiled in the same directory as all other plugins. I hope that it will be included in the common distribution. 

Problems

In case of problems, have a look at the EventLog of the machine. You should find messages from Netsaint with an error code in hexadecimal. The corresponding english description can be found in NTSource\pdhmsg.pas.

Reported issues

• Wrong memory information reported by NSClient on some machine having lots of memory (bigger than 1GB). This is a Windows NT 4 bug and, according to Microsoft, should be corrected in SP7.