##################################################################
#       MRTG Extension Program for NetWare Server                #
#                    Version 1.46b                               #
#       Written by James Drews (drews@engr.wisc.edu)             #
# URL:  http://forge.novell.com/modules/xfmod/project/?mrtgext   #
##################################################################
# This program is freeware. *NO* warranty is expressed,          #
# implied, nor granted to you in any way.  Use of this           #
# program is at your own risk.  Your mileage may vary.           #
# This program was packed by weight, not by volume.              #
# Some settling may have occurred during shipment.               #
##################################################################

README.TXT

Thanks for looking at the MRTG Extension for NetWare. This 
combination NLM and perl script will allow you to graph 
some additional statistics from a NetWare server. If you 
like it, or would like to see some additional features, 
drop me a note.

If you find this utility useful, please feel free to
drop me a postcard to plaster to my office wall. 
The postcards can be sent to:
   James Drews
   University of Wisconsin - Madison
   1410 Engineering Drive
   Madison, WI 53706


INSTALLATION


To install this extension, simply copy the MRTGEXT.NLM to 
each NetWare server's SYS:SYSTEM directory that you wish to 
gather statistics from. Then edit the server's AUTOEXEC.NCF 
to "LOAD MRTGEXT" so it will load each time the server is 
restarted.  You also must have TCP/IP configured and 
running on the server. See your NetWare manuals for 
instructions on performing this task.

The MRTGEXT.NLM has two command line switches available:

"-port=<port>" will change the port that MRTGEXT listens on 
for statistic requests. By default, MRTGEXT will use port 
9999. For example, to have MRTGEXT use port 1023, add 
"-port=1023" to the load line. If you change the port 
number on the command line, be sure to modify the perl 
script as well. 

"-debug" will enable some debugging output to the System 
Console screen. This is only really useful when you are 
first configuring the extension.

"-mla=<license>" For those with an MLA license (mostly for
NetWare 5), the MRTGEXT.NLM currently can not obtain a 
valid value for the server license count. Using this option 
will tell the MRTGEXT.NLM the license count max to report. 
This is important if you use the NWEXTCFG.PL to create 
configuration files or if you use the servstat.pl script. 
For example, if you have a NetWare 5 MLA license and you 
really only have a 100 user server, then you would add 
"-mla=100" to your load command line. 

WHAT STATISTICS CAN MRTGEXT GATHER?

MRTGEXT will allow you to graph the following items:
	-Server CPU Utilization on a 1 minute average
	-Server CPU Utilization on a 5 minute average
	-Server CPU Utilization on a 15 minute average
	-Server Licensed Connection count
	-Server Max Licensed connection count used
    	-Server Peak connections allocated (under NetWare 4)
    	-Free disk space per specified volume
    	-Used disk space per specified volume
    	-Disk Cache Dirty Buffers
    	-Disk Cache Buffer Count
    	-Disk Cache Long Term Hit Percentage
    	-Disk Cache Least Requested Unit (LRU) sitting time
      	 (in both seconds and minutes)
    	-Per CPU utilization for NetWare 5.x and up
    	-Dirty Cache Buffers as a percentage of total
    	-Total Cache buffers as a percentage of original
    	-Number of SAP table entries
    	-Packet receive buffer count
    	-Server Version string
    	-DS Version string
    	-Purgable disk space per volume
    	-Non-purgable disk space per volume
    	-Open file count
    	-Current and maximum service processes (NW5.x and up)
    	-Abended Thread count (NW5.x and up)
    	-Timesync status
    	-NSS Stats (NW6 only)
    	-Directory Cache Buffer info
    	-Server memory pool information
        -Some NRM stats
    
The CPU load average is sampled at 1 second intervals and 
the average over 1, 5, and 15 minutes is calculated. It is 
currently using the published API to get the CPU load 
average. Under a multi-processor system, the load average (total)
is an average of all the cpus.


ADDING MRTGEXT TO YOUR MRTG INSTALLATION

A perl script NWSTAT.PL is provided that will allow you to 
get the statistics from the MRTGEXT.NLM. Both the perl 
script and the MRTGEXT.NLM use TCP/IP to communicate.

In your MRTG configuration file you need to create a 
section and use NWSTAT.PL as an executable. See the MRTG 
documentation on how to do this.

To make things a bit easier, I have now included an 
additional perl script that will generate an MRTG config 
file.  The script NWEXTCFG.PL will create an MRTG 
configuration file to monitor the following:
  -5 and 15 minute utilization on one graph set
  -Connection count on one graph set
  -Disk space usage for each mounted volume on a separate
   graph set.
  -LRU Sitting Time
  -Dirty Cache Buffers
  -Percent long term cache hit rate

Thanks to James Moore, the script can also create a config file
for Cricket/RRDTool. See http://wirerimmed.com/?id=19
for more information

Before you use the NWEXTCFG.PL script, be sure to edit it
and change the "$nwstat = " to point to where you have
placed the NWSTAT.PL script on your system.

To use the script, just run it with the DNS name or IP 
number of the server you wish to monitor. The output will 
be sent to standard out. An example for an MRTG config
file would be:
  
  NWEXTCFG.PL -m myserver.mydomain.com >> mrtg.cfg

This will append the MRTG.CFG file with the configuration 
information for myserver.mydomain.com.


Should you wish to set up the configuration yourself, here 
is some information that you need to know.

The NWSTAT.PL script requires you to enter in three command 
line options. The first option is the DNS name or TCP/IP 
address of the NetWare server you wish to talk to. The 
second and third options are the two statistic items that 
you wish to graph.  Should you only want to graph one item 
(like used disk space) on a single graph, you can use the 
key word ZERO to have the NLM return a 0 (zero) for the 
second data item.

	NWSTAT.PL HOST OPT1 OPT2

where HOST is the DNS name or TCP/IP address of the NetWare 
server to query and OPT1 and OPT2 are any combination of 
the following (case is not important):

UTIL1        :  1 minute average CPU utilization
UTIL5        :  5 minute average CPU utilization
UTIL15       : 15 minute average CPU Utilization
CONNECT      : number currently licensed connections
CONNMAX      : Max licensed connections used
CONNPEAK     : Peak Connections
             : (NetWare 3 = error (-1))
             : (NetWare 4 = number connections allocated)
NAME         : Server's name
UPTIME       : Time that the server is operational
VF<vol>      : bytes free on <vol>
VU<vol>      : bytes used on <vol>
VS<vol>      : size of <vol> in bytes
VKF<vol>     : kbytes free on <vol>
VKU<vol>     : kbytes used on <vol>
VKS<vol>     : size of <vol> in kbytes
ZERO         : Returns a zero (0)
      
The following options were added to version 1.20:

S1           : Return the Long Term Cache Hit percentage
S2           : Return the current number of Cache Buffers
S3           : Return the current number of dirty cache buffers
S4           : Return the LRU sitting time in seconds
S5           : Return the LRU sitting time in minutes

The following options were added to version 1.30

S6           : Return the dirty cache buffers a percentage of the total
S7           : Return the total cache buffers as a percentage of the original
S8           : Original number of cache buffers
S9           : Number of entries in the SAP table
S9.<number>  : Number of entries in the SAP table for SAP type <number>
S10          : CPU count - NetWare 5.x only, returns 1 for other versions.
UTIL1.x      : One minute utilization on CPU x (start with CPU zero) - NetWare 5.x Only
UTIL5.x      : Five minute utilization on CPU x (start with CPU zero) - NetWare 5.x only
UTIL15.x     : Fifteen minute utilization on CPU x (start with CPU zero) - NetWare 5.x only

The following were added to version 1.31
S11          : Is the DS Database Open (1=yes, 0=no)
S12          : Are Logins Enabled (1=yes, 0=no)
S13          : Return the version of DS.NLM
S14          : Return the version of MRTGEXT.NLM
S15          : Packet receive buffer count
S16          : Max packet receive buffer count


The following were added to version 1.32
VP<vol>      : bytes of purgable files on <vol>
VKP<vol>     : kbytes of purgable files on <vol>
VNP<vol>     : bytes of not-yet-purgable files on <vol>
VKNP<vol>    : kbytes of not-yet-purgable files on <vol>
S17          : Abended thread count (NW5.x only)
S18          : Open file count
S19          : NetWare version string
S20          : Maximum service processes
S21          : Current service processes (NW5.x only)
                
The following were added to version 1.33
S22          : Timesync Status (0=No, 1=Yes, in sync to the network)

The following were added to version 1.40
NSS1:<stat>  : Statistics from _Admin:Manage_NSS\GeneralStats.xml
NSS2:<stat>  : Statistics from _Admin:Manage_NSS\BufferCache.xml
NSS3:<stat>  : statistics from _Admin:Manage_NSS\NameCache.xml
NSS4:<stat>  : statistics from _Admin:Manage_NSS\FileStats.xml
NSS5:<stat>  : statistics from _Admin:Manage_NSS\ObjectCache.xml
NSS6:<stat>  : statistics from _Admin:Manage_NSS\Thread.xml
NSS7:<stat>  : statistics from _Admin:Manage_NSS\AuthorizationCache.xml
NSSV:<vol>:<stat>   : Statistics from _Admin:Manage_NSS\Volume\<vol>\VolumeInfo.xml
NSSP:<pool>:<stat>  : Statistics from _Admin:Manage_NSS\Pool\<pool>\PoolINfo.xml

The following were added to Version 1.41
S23:<nlm>    : Is the <nlm> loaded.
S24:<nlm>    : Version of <nlm>
       for the above two options, you need to specify the full name of the NLM.
       That is, if you want to see if DS.NLM is loaded, you would use:
            S23:ds.nlm
VMF<vol>     : Volume Free Space in Megabytes
VMU<vol>     : Volume Used Space in Megabytes
VMS<vol>     : Volume Size in Megabytes
VMP<vol>     : Total size in Megabytes of the purgable files
VMNP<vol>    : Total size in Megabytes of the Not yet purgable files


The following were added to version 1.42
S25          : Minimum Directory Cache Buffres
S26          : Maximum Directory Cache Buffers
S27          : Current Directory Cache Buffers

The following were added to version 1.43
S28          : Current Service Processes MP
S29          : Total Server Memory (bytes)
S30          : Allocated Memory (bytes)
S31          : Cache Buffer Memory (bytes)
S32          : Cache non-movalbe memory (bytes)
S33          : Cache movable memory (bytes)
S34          : Code and data memory (bytes)


The following were added to version 1.46
NRMH:<stat>  : Return the overall server health (0 = Good, 1 = suspect, 2 = bad)
               The data is taken from the file _admin:Novell\\NRM\\NRMHealth.xml
               For the most part, the <stat> should be set to Server_Health_Status
NRMP:<stat>  : Returns the current value for a NRM health item. The items are
               found in _admin:Novell\\NRM\\NRMHealth.xml. Because MRTGEXT takes
               its parameters as space deliniated, the <stat> should have any
               spaces converted to underscores.  For example, if you want the
               "Disk Throughput" item, you would use the command:
                     NRMP:DISK_THROUGHPUT
NRMM:<stat>  : Like the NSS statistics, but the item is take from the file
               _admin:Novell\\NRM\\NRMMemory.xml to report back memory stats.
NRMS:<stat>  : Like the NSS Stats format, but uses the file 
               _admin:Novell\\NRM\\NRMSwap.xml to report back swap file stats.


Notes about NSS Statistics:
  I decided to keep the interface to the NSS Statistics more generic. I suggest
  you look in the files listed above to find the statistics you are interested
  in monitoring.  Each of the files is in XML format. The NSS MRTGEXT commands
  will parse the selected file looking for the stat requested. For example, if 
  I wanted the number of fileReadCounts from the FileStats.xml file, I would use
  the command:
     NSS4:fileReadCounts

  You can also get stats for specific NSS volumes or NSS pools with the NSSV and 
  NSSP commands. You just need to specify which volume or pool you are intersted
  in. So, if I wanted to know how many files are on the VOL1 volume, I would use:
     NSSV:vol1:files

  Do not put the angle brackets on the stat requested. The NLM is doing that 
  already. That is, do NOT send a command like:
     NSS4:<fileReadCounts>
  as you will get a -1 as a result.  Any time the file can't be opened, or the
  stat was not found, you will get a -1 as a result.

  Novell has told me they do not plan to back-port this interface to NetWare 5.x,
  so this will remain a NetWare 6 (and future) feature.

The Perl script already includes NAME and UPTIME so you 
don't need to include those options. They are just listed 
for completeness of the documentation.
                                 
Example: To get the server utilization for 5 and 15 minutes 
on the myserv.mydomain.com.          
                                                       
   NWSTAT.PL myserv.mydomain.com UTIL5 UTIL15          
                                                       
Example: To graph the disk space usage on the SYS volume on 
myserv.mydomain.com.               
                                                       
   NWSTAT.PL myserv.mydomain.com VFsys VUsys           

OTHER NOTES
The server side NLM can take ALL the options on the command 
line at once. However, MRTG is written to only graph two 
variables at a time. Should some ambitious person modify 
the program to graph more than two items at once, this 
program can easily be expanded to output more items.                      

The NLM can take every option at once. The only restriction 
is the length of the line. The NLM stops accepting data 
after 1024 characters or when it finds the first `\n' 
(newline) character. 

The NLM also will accept a few more commands than what is 
listed above. The NLM will also take the LICENSE and 
VOLUMES options. The LICENSE option will display the number 
of connections the server is licensed for. The VOLUMES 
option will list the names of all the mounted volumes. 
These along with VS and VKS can be used to generate config 
files without having to know the values for each server. 

REVISION HISTORY

Version 1.46b
 Changes to MRTGEXT.NLM (contributed by Alex Warmerdam)
 -Fixes so NRMH can work on Netware 6.0
 Changes to MRTGEXT.NLM (Contributed by Mario Bell/Robert Ingraham)
 -Fixed the ShowVol* routines to do the math in 64bit to avoid problems
  with very large volumes.

Version 1.46
 Changes to MRTGEXT.NLM (contributed by Alex Warmerdam)
 -Added the NRM? items
 -Changed -debug to also output to sys:\etc\mrtgextd.log

  
Version 1.44b
 Changes to MRTGEXT.NLM
 -Fixed a problem with NSS Stats. If you asked for two NSS based stats
  in the same query, the first one returned a value, all others returned
  an error.

Version 1.44a
 Changes to MRTGEXT.NLM
 -Fixed a CPU Hog abend after the server was told to go down or restart
  (socket listener went into a tight loop after the server shut down the
  tcpip socket it was listening on)

Versoin 1.44
 Changes to MRTGEXT.NLM
  -Fixed a CPU Hog abend with NetWare 6.5 in the open file scan of all connections
  -Added S35 to get open file count by scanning all connections
  -Changed S18 (open file count) to use the public API when it exists,
      otherwise scans all connections
  -Added event listener for server down command

Version 1.43
  Changes to MRTGEXT.NLM
  -Fixed service process thread count
  -Added MP service process count (S28)
  -Added memory pool stats (S29 through S34)
  
Version 1.42
  Changes to MRTGEXT.NLM
  -Added the ability to get Directory Cache Information

Version 1.41
  -Added -bindip= command line option
  -Added S23:<nlm>  (is NLM Loaded)
  -Added S24:<nlm>  (get specific NLM Version)
  -Added VMF<vol>,VMS<vol>,VMS<vol>,VMP<vol>,VMNP<vol>  
           (megabyte returns of volume information)

Version 1.40
 Changes to MRTGEXT.NLM
  -Added ability to get gobs of NSS stats for NetWare 6

Version 1.33
 Changes to MRTGEXT.NLM
  -Added ability to get timesync status
 Changes to NWSTAT.PL
  -Thanks to Kevin Keyser <kevin-keyser@uiowa.edu> for fixing
   a problem where any 'W' would be removed from the server name
 Added SERVSTAT5.PL to the distribution

Version 1.32
 Changes to MRTGEXT.NLM
  -Added getting OS Version string
  -Added getting purgable files (in bytes and kbytes)
  -Added getting open file count
  -Added getting Abended thread count (NW5.x only)
  -Added getting Maximum service processes
  -Added getting current service processes (NW5.x only)
 Changes to SERVSTAT scripts
  -Updated to display open files/service processes, abend count
    and server os version.

Version 1.31a
 Added the VOLSTAT.PL script to the distribution

Version 1.31
 Changes to MRTGEXT.NLM
  -Added getting DS Status open/closed (1=Open 0=Closed)
  -Added getting login enabled status (1=Enabled 0=Disabled)
  -Added getting DS version string
  -Added getting MRTGEXT version string
  -Added getting packet receive buffer count
  -Added getting max packet receive buffer count setting
  -Fixed unload problem on 4.x servers (again), I must have
   uncommented some code that shouldn't have been. I have now
   removed that code entirely.
 Changes to SERVSTAT scripts
  -Updated it to display DS Open Status, Logins Enabled stats 
   and DS Version.
  
Version 1.30
 Changes to NWEXTCFG.PL
  -Added ability to create a Cricket/RRDTool style config
   file thanks to James Moore
  -Made sure the Options[x]: Guage is present for each entry
 Changes to MRTGEXT.NLM
  -Added Per/CPU utilization stats when running on NetWare 5.x
  -Can report dirty cache buffers as percentage of total
  -Can report total cache buffers as percentage of original
  -Ability to return counts from the SAP table
  -Source is now available. It is released under the Artistic 
   License.
 
Version 1.21
 Changes to NWEXTCFG.PL
  -Added the kilo and kMG options to the disk space
   stats. This will allow the labels to be correct
   on the graphs.
 Changes to MRTGEXT.NLM
  -Converted to using the MetroWorks compiler instead of
   Watcom.

Version 1.20
 Changes to MRTGEXT.NLM
  -Fixed a problem where the NLM may not unload correctly.
   It appears the changes done in 1.10a to fix a possible
   ABEND on unload were not completely removed. The exit
   routine was redone to prevent this problem. I was able to
   reproduce the unload problem with 1.10a, and can no longer
   get it to happen with 1.20.
  -Added several disk cache statistics.
 Changes to NWEXTCFG.PL
  -Updated the perl script to add graphs for disk cache
   statistics.

Version 1.10a
 Added the SERVSTAT.PL to create HTML based server status
  pages.
 Changes to MRTGEXT.NLM
  -added some checks to see if it is running on a 3.x server
   as one documented API that is supposed to work under 3.x
   isn't. This fixed the "license" and "volumes" commands.
  -Fixed (or appear to) a possible ABEND under 3.x when
   unloading the NLM.

Version 1.10
 Changes to MRTGEXT.NLM                               
  -Added the VOLUMES command to get the list of        
   volumes on a server. Useful for configuration file        
   generators.                                         
  -Added the VS and VKS commands to get the total size 
   of a volume. Useful for config file generators     
  -Changed the NLM to only put '\n' characters to      
   separate each line instead of '\r\n'. Perl likes to 
   work with just the '\n' characters by default       
 Changes to NWSTAT.PL                                 
  -Changed to script to be more friendly to OS/2       
 Added NWEXTCFG.PL                                      
  -Automatic configuration file generation script. See the    
   README.TXT file for information.                        
                                                       
Version 1.00b 
 Changes to MRTGEXT.NLM
  -Changed the way disk space usage was calculated. In cases
   where the result was near or over 4gig, it would return an
   incorrect result.
 Changes to NWSTAT.PL
  -If the script could not contact the host, it would exit 
   in such a way that the MRTG perl script would not process
   any entries. This has been corrected.

Version 1.00a 
 Changes to MRTGEXT.NLM
  -Changed VF and VU to output in bytes instead of kbytes
  -Added VKF and VKU in case output in kbytes is desired.

