====== sentinel.sh ======

^ Author | [[ goldfndr@gmail.com | Richard Finegold ]] |
^ Compatibility | Xymon 4.2 |
^ Requirements | bash with wget and printf |
^ Download | None |
^ Last Update | 2010-02-25 |

===== Description =====
This script tracks licenses in use for each SafeNet Sentinel Protection Server key, optionally graphing. For example, [[http://www.liscad.com/liscad/|LISCAD]] ([[http://www.leica-geosystems.com/en/Leica-LISCAD_4851.htm|Leica]]), [[http://www.leica-geosystems.com/en/Leica-Geo-Office_4611.htm|Leica Geo Office]], [[http://www.gtstrudl.gatech.edu/|GT STRUDL]]. It'll also show whether ESRI floating licensing is active, as ESRI uses SuperPro keys, but that isn't as useful.

===== Installation =====
=== Client side ===
  * If you haven't already, install the Sentinel Protection Server.
  * Note the port used by the Sentinel Protection Server (defaults to 6002). Make sure you can bring it up in a web page (e.g. http://example.com:6002/) and confirm that it invokes some Java. If you aren't sure what the port is, you can check within Microsoft Windows:
    - Run ''C:\Program Files\Common Files\SafeNet Sentinel\Sentinel Protection Server\loadserv.exe''
    - Press the "Configure..." pushbutton.
    - Check the Http Port.
  * On the resulting web page, note the Serial Numbers, and determine what each key protects.

=== Server side ===
Edit $BBHOME/etc/bb-hosts, adding a ''sentinel'' tag to the appropriate lines, with optional http port and/or key descriptions (used in status and optional graphing). Use the following syntax:

  * sentinel[://port//][,//hexval//=//name//[,//hexval//=//name//]...]

For example:
     sentinel:6102
     sentinel,3573=Master,0045=Slave

Copy sentinel.sh (below) to your $BBHOME/ext and make sure it's executable.

Add the following (or similar) to $BBHOME/etc/hobbitlaunch.cfg<code>
[sentinel]
        NEEDS hobbitd
        CMD /home/hobbit/server/ext/sentinel.sh
        LOGFILE $BBSERVERLOGS/sentinel.log
        INTERVAL 5m
</code>
== Optional graphing ==
<hidden onHidden="Show Section ⇲" onVisible="Hide Section ⇱">
  * Add the following to $BBHOME/etc/hobbitgraph.sh<code>
[sentinel]
        FNPATTERN InUse.(.+).rrd
        TITLE Sentinel Utilization
        YAXIS Used
        #DEF:in@RRDIDX@=sentinel,InUse_@RRDPARAM@.rrd:lambda:AVERAGE
        DEF:in@RRDIDX@=@RRDFN@:lambda:AVERAGE
        #DEF:t@RRDIDX@=sentinel,HardLimit_@RRDPARAM@.rrd:lambda:AVERAGE
        LINE1:in@RRDIDX@#@COLOR@:@RRDPARAM@ Used
        GPRINT:in@RRDIDX@:LAST: %3.1lf (cur)
        GPRINT:in@RRDIDX@:MAX: %3.1lf (max)
        GPRINT:in@RRDIDX@:MIN: %3.1lf (min)
        GPRINT:in@RRDIDX@:AVERAGE: %3.2lf (avg)\n
[sentinel1]
        FNPATTERN UsePercent.(.+).rrd
        TITLE Sentinel Utilization
        YAXIS Percent
        DEF:in@RRDIDX@=@RRDFN@:lambda:AVERAGE
        #DEF:t@RRDIDX@=sentinel,HardLimit_@RRDPARAM@.rrd:lambda:AVERAGE
        LINE1:in@RRDIDX@#@COLOR@:@RRDPARAM@ Used
        GPRINT:in@RRDIDX@:LAST: %3.1lf (cur)
        GPRINT:in@RRDIDX@:MAX: %3.1lf (max)
        GPRINT:in@RRDIDX@:MIN: %3.1lf (min)
        GPRINT:in@RRDIDX@:AVERAGE: %3.2lf (avg)\n
</code>
  * In $BBHOME/etc/hobbitserver.cfg, add the following to the existing ''TEST2RRD'' and ''GRAPHS'' lines, and add a ''SPLITNCV_sentinel'' line:<code>
TEST2RRD="[...],sentinel=ncv"
GRAPHS="[...],sentinel:sentinel|sentinel1"
SPLITNCV_sentinel="*:GAUGE"
</code>
</hidden>

===== Source =====
==== sentinel.sh ====

<hidden onHidden="Show Code ⇲" onVisible="Hide Code ⇱">
<code bash>
#!/bin/sh
# This script checks the Sentinel License Monitor on hosts
# and reports each key's usage and details.
# In your bb-hosts file, use the following syntax:
#	sentinel[:port][,hexval=name[,hexval=name...]]
# Where port is the port for your Sentinel License Monitor (default 6002),
#       hexval is 4 digits corresponding to the serial number, name is whatever.
# For example:
#  0.0.0.0 example1 # sentinel
#  0.0.0.0 examplep # sentinel:6202
#  0.0.0.0 examplen # sentinel,3573=Master,0045=Slave
# Note: this has only been tested with SuperPro keys.
#
# Requirements:
#  wget and printf must be available. 

# Notes:
#  For some keys, the detail columns should be (7.3.2):
#    IP Address    User Name    Log Time    Client PID    LicenseID
#  But this always uses the same method: (7.4.2):
#    Client/Access Mode    User Name    Client login time    Client PID
#
# This uses the machine name, and not the IP address, when checking.

BBHTAG=sentinel	  # What we put in bb-hosts to trigger this test
COLUMN=$BBHTAG	# Name of the column, often same as tag in bb-hosts
TABLEH="<table class=sortable border=1 cellpadding=5>"	#HTML for table start
EMPTYTABLES=0	#Show empty tables if non-zero 


#Make sure we have required executables. Allow interactive run from ext.
[ "`which wget`" -a "`which printf`" ] || { echo "wget and printf required"; exit 1; }
[ "$BBHOME" ] || { BBHOME=..; . ../etc/hobbitserver.cfg; BB=echo; }


#Just to avoid some excessive indenting, define a function
check_usage()
{
	echo "$TABLEH
<thead><tr><th>Client/Access Mode<th>User Name<th>Client Login Time<th>Client PID</tr></thead><tbody>" >> $COLUMN.$$

	#Although the keys are relatively easy to get, the counts are harder.
	#The server requires getting the counts page followed by xml.
	#Timing is everything. Grr...
			
	wget "${URL}licenseinfo.html?$KEY?$SERIALNUMBER" -O /dev/null -q
	wget "${URL}licenseinfo.xml" -O - -q | $SED 's/\r/\
/g' | $SED 's/<\/.*//g;s/>\(.\+\)/ : \1/g;s/.*>//;s/.*<//' | while read LLL; do
		tag=`echo "$LLL" | $SED 's/ : .*//'` #'s/[ \t]<//; s/>.*//'
		val=`echo "$LLL" | $SED 's/.* : //'` #'s/<\/.*//;s/.*>//'
		case $tag in
			ClientIPAddress) IPADDRESS="$val" ;;
			ClientUserName) USERNAME="$val" ;;
			ClientLogTime) LOGTIME="$val" ;;
			ClientProcessID) PID="$val"
				#Start with a colon to avoid NCV processing ($LOGTIME has colons)
				echo "<!--:--><tr><td>$IPADDRESS<td>$USERNAME<td>$LOGTIME<td>$PID</tr>" >> $COLUMN.$$
				;;
			#LicenseID) LICENSEID="$val" ;;
			#*) ;;
		esac
	done
	echo "</tbody></table>" >> $COLUMN.$$
}

#The main loop
#echo '10.1.207.3 crplic2 # sentinel,7532=Liscad,759c=LGO' | while read L; do
$BBHOME/bin/bbhostgrep --no-down $BBHTAG\* | while read L; do
	set $L     # To get one line of output from bbhostgrep

	HOSTIP="$1"
	MACHINEDOTS="$2"
	MACHINE=`echo "$2" | $SED 's/\./,/g'`
	PORT=`echo $4 | $SED "s/$BBHTAG//;s/,.*//"`
	if [ -z "$PORT" ]; then
		PORT=":6002"
	fi
	SUBST="`echo $4 | $SED 's/[^,]*//'`,"
	# either "http://$MACHINE$PORT/" or "http://$HOSTIP$PORT/"
	URL="http://$MACHINE$PORT/"

	COLOR=green
	KEY=0

	wget "${URL}keyinfo.xml" -O - -q | $SED 's/\r/\
/g' | $SED 's/<\/.*//g;s/>\(.\+\)/ : \1/g;s/.*>//;s/.*<//' | while read LL; do
		tag=`echo "$LL" | $SED 's/ : .*//'` #'s/[ \t]<//; s/>.*//'
		val=`echo "$LL" | $SED 's/.* : //'` #'s/<\/.*//;s/.*>//'
		case $tag in
			ServerVersion)	echo "Sentinel Protection Server Version is $val" > $COLUMN.$$;;
			SerialNumber)
				SERIALNUMBER="$val"
				SERIALSHORT="`echo $val | $SED 's/^0\+//'`"
				HEXSERIAL="`printf '%04x' $SERIALSHORT`"
				APPEND=$HEXSERIAL
				NAME="unknown"
				#Check for substitution
				#echo "Testing $HEXSERIAL (,$HEXSERIAL=) on $SUBST"
				#echo "$SUBST" | $GREP ",$HEXSERIAL="
				#echo "Testin $HEXSERIAL (,$HEXSERIAL=) on $SUBST"
				if [ `echo "$SUBST" | $GREP ",$HEXSERIAL="` ]; then
					NAME=`echo $SUBST | $SED "s/.*,$HEXSERIAL=//;s/,.*//"`
					APPEND=$NAME
				fi
			#echo "SERIAL: $SERIALNUMBER / $SERIALSHORT / $HEXSERIAL"
				;;
			HardLimit)	HARDLIMIT="$val" ;;
			LicenseInUse)	INUSE="$val" ;;
			NumTimeOut)	TIMEOUT="$val" ;;
			HighestUse)	HIGHESTUSE="$val" ;;
			PartNumber)	#PARTNUMBER="$val"
				USEPERCENT=$((INUSE * 100 / $HARDLIMIT))
				echo "<HR>Details for key $SERIALNUMBER (0x$HEXSERIAL) [$NAME]:

     InUse_$APPEND : $INUSE  ($USEPERCENT%)<!--
UsePercent_$APPEND : $USEPERCENT -->
HighestUse_$APPEND : $HIGHESTUSE  ($((HIGHESTUSE * 100 / $HARDLIMIT))%)
 HardLimit_$APPEND : $HARDLIMIT
" >> $COLUMN.$$
				if [ "$EMPTYTABLES" != "0" -o "$INUSE" != "0" ]; then
					KEY=$(($KEY+1))
					check_usage
				fi
				;;
			#*) ;;
		esac
	done
	MSG="status $MACHINE.$COLUMN $COLOR `date` [$MACHINEDOTS] $BBHTAG status
`cat $COLUMN.$$`"
	$BB $BBDISP "$MSG"
	$RM $COLUMN.$$
done
 
exit 0
</code>
</hidden>

===== Known  Bugs and Issues =====
  * As noted in the source code, this depends on timing between checking licenseinfo.html followed immediately by licenseinfo.xml. So try to avoid having two servers requesting these simultaneously.
  * The licenseinfo.xml doesn't seem very reliable. Possibly due to the above, possibly due to other circumstances.
  * It has only been tested with SuperPro keys.

===== To Do =====
  * Discover a method for querying other than checking XML over HTTP results. Yes, there is a usage log file, but parsing that seems likely to require storing state information.

===== Credits =====
I wish I could give credit to someone else for determining the licenseinfo details, but I had to discover it on my own.

===== Changelog =====

  * **2010-02-25**
    * Initial release