NSClient documentation

ClearCentral Software Inc. - support.tsmgsoftware.com
Original author - Yves Rubin – rubiyz1047@swyz.com

Contents

Purpose
License
Requirements
History
Features
Installation
Uninstallation
Configuration
Plugin Syntax
        CPU Load
        Disk Usage
        Uptime
        Service States
        Process States
        Client Version
        Memory Usage
        File Age Usage
        Custom Counter
        Instances
Technical Information
Problems
Known Issues

Purpose

NSClient has been developed to get performance information from Windows Servers and return them to Nagios using the check_nt client. In addition to the standard metrics, a generic COUNTER function is provided to return the value of any counter maintained by Windows.

License

This software is released under the GNU General Public License. A copy of the license is included here.

Requirements

• Windows NT 4, Windows 2000 or Windows XP

For compilation:

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

    These must downloaded, extracted and added to your Delphi library path.

• SvCom components

    These must be installed on your development system. There are automatically added to the Delphi environment.

History

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
• Check file age
• Can check every available performance counter  
• Can return a list of instances for a given performance object

|
Installation

On the Windows machine

1. Copy pNSClient.exe, pdh.dll, psapi.dll and counters.defs 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.exe /install
4. Type 'net start nsclient' on the command line or start the service 'Nagios 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 !

The cpu load, disk usage, uptime and memory usage parameters are collected internally using queries to the Windows performance counters. These counters are language-specific. The language of a version of Windows is defined by a hex code (English is 0x049)  Additionally, the System Processor usage counter changed from Windows NT to Windows 2000/XP.A file “counters.defs” is in the NSClient folder. This file contains translations of the counter names into various other languages organized by the languages hex code and operating system version. On startup, NSClient looks up the operating system version and language code and then queries the file for the appropriate counter names. If you are using a language that is not included in the file, it must be added for NSClient to function correctly. These is no requirement to add any other counters to this file.

On the Unix machine

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

# NSClient basic return types

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_fileage]=$USER1$/check_nt -H $HOSTADDRESS$ -p 1248 -v FILEAGE –l $ARG1$ -w $ARG2$ -c $ARG3$

# Custom counters (one per required counter, or define a generic one and use $ARG1$ to specify the requested counter).

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.exe /uninstall (ensure that the services applet and Event Viewer are closed).

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

CPU Load

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

File Age Usage

Syntax: check_nt -H <hostname> -p <port> -v FILEAGE –l <filename>[,<date format>] [-w <warning> ] [-c <critical >]

• <filename> : file to check. Don’t forget to use \\ for each \ (c:\\autoexec.bat). Filename can contain wildcards (c:\\*.bat). When wildcards are used the returned date will be from the first file found that matches and there is no order to the files. If no file matching the pattern is found it will return that no file was found except if the wildcard *.* is used, then it will return the last modification time of the directory.
• <date format> :the string and formatted to display the file's date. The date is passed to the strftime function which requires uses specific characters to format the date. View this reference on the strftime function for all its options. If the date format is not passed, it will default to Date: mm/dd/yyyy hh:mm:ss am/pm. This default is compiled into the check_nt source code. If you want a different default, find the following line in check_nt.c

strftime(description, 50, "Date: %D %I:%M:%S %p", localtime(&rettime));

Change the "Date: %D %I:%M:%S %p" part to what you want as a default and then compile it.

• <warning> and <critical> : maximum number of minutes since the last update of the file.

Example: 
./check_nt -H 192.168.1.1 -p 1248 -v FILEAGE –l "c:\\program files\\nsclient\\pnsclient.exe" -w 1440 -c 2880
./check_nt -H 192.168.1.1 -p 1248 -v FILEAGE -l "c:\\program files\\nsclient\\pnsclient.exe","Date: %d-%m-%Y %I:%M:%S %p" -w 1440 -c 2880

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 enclosed 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 means that you need to give a precise and specific syntax to make it work. 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  

Instances

Syntax: check_nt -H <hostname> -p <port> -v INSTANCES -l <counter object>

• <counter object> is a Windows Perfmon Counter object (eg. Process), if it is two words, it should be enclosed in quotes
• The returned results will be a comma-separated list of instances on the selected computer for that object.
• The purpose of this is to be run from command line to determine what instances are available for monitoring without having to log onto the Windows server to run Perfmon directly.
• It can also be used in scripts that automatically create Nagios service configuration files.

Example

./check_nt -H 192.168.1.1 -p 1248 -v INSTANCES -l Process

Technical information

Windows agent

NSClient has been developed using Borland Delphi 7. 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. It also collects the uptime, memory and disk utilization metrics every 5 seconds and stores them in global variables. When requested, the client returns these results from the global variables.

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 should 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 Event Log of the machine. You should find messages from Nagios with an error code in hexadecimal. The corresponding English description can be found in NTSource\pdhmsg.pas.

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