Name

mod_snmp – Dynamic loading SNMP module for Lite / W3-mSQL

Synopsis

 
modload "mod_snmp";

$cd = snmpopen($hostname, $community);
$result = snmpget($cd, $variables);
$result = snmpgetnext($cd, $variables);
snmpclose($cd);

 

Caveats

It is assumed that the reader is familiar both with programming in the Lite / W3-mSQL language and with the basic concepts of the Simple Network Management Protocol.

 

Description

The SNMP module adds support for the Simple Network Management Protocol Version 1 (SNMPv1) to Lite and W3-mSQL scripts. It is implemented as a dynamic loading module and must be loaded by each script that requires SNMP support. The module provides 4 interface routines that allow data acquisition via SNMP as outlined below.

An SNMP "connection" must be formed to a network device before data may be acquired from that device. To form such a connection, the snmpopen() function is called with both the hostname of the device and the SNMP community string. snmpopen() returns an integer value that is used as a connection descriptor for further SNMP actions on that connection. A returned value of –1 indicates an error. In the case of an error, an appropriate error message is stored in the $ERRMSG global variable.

Data is retrieved from the SNMP connection using either the snmpget() or snmpgetnext() module routines. Each routine is passed the connection descriptor and an array of SNMP variables. The variables may be specified in either numeric OID or symbolic textual notation. Both routines return a result array in which each array element is the result value of the corresponding element from the variable array passed to the routine. The result array elements include both the variable name and the variable value separated by the LITE_BRK character. LITE_BRK is an internal Lite macro that defines a non-textual "character" that can be used to delimit textual data. To retrieve the information from a result element, the element may be dissected using 

$data = split($result[$element], LITE_BRK);

$data[0] will contain the name of the variable and $data[1] will contain the resultant value. The result includes the variable name specifically for use with the snmpgetnext() routine as the variable returned will be the variable directly following the requested variable in the device’s OID tree.

 

Object ID Handling

The MIB module of the SNMP library has been written to be as flexible as possible with respect to the specification of SNMP variable names. Variables my be specified using either its numeric OID or its symbolic textual name. If a textual name is used, a specific search order is used to identify the required variable. Well known prefixes are identified and expanded internally. The known prefixes are

experimental

iso.org.dod.internet.experimental

enterprises

iso.org.dod.internet.private.enterprises

private

iso.org.dod.internet.private

Therefore, specifying a variable as

enterprises.cisco.local.lInterfaces.lifTable.lifEntry

expands to

iso.org.dod.internet.private.enterprises.cisco.local.lInterfaces.lifTable.lifEntry

Any prefix added to a variable internally by the SNMP library is stripped before the variable name is returned to the caller in the result array. If no prefix is identified, a default prefix of

iso.org.dod.internet.mgmt.mib-2

is used. An absolute variable name may be specified by simply starting the variable definition with the 'iso' token (i.e. a fully qualified variable name will be identified as such and left intact).

 

 MIB Handling

The SNMP library utilises the MOSY format for MIB files. The MOSY format is a compiled format and allows the library to load the required MIB definitions much faster than if the raw ASN.1 definition had to be parsed each time. The compiled MIB files are stored by default in /usr/local/Hughes/mibs (or a directory called 'mibs' in the mSQL installation directory). MIB files can be identified due to their .def filename extension. The number of MIB files parsed by the SNMP library governs the amount of time required to initialise the library. It is wise to only include the MIB files that you require. The MIBs to be loaded are listed, one file name to a line, in a file called 'mibs' in the mibs directory. A base installation should include at least

 
root.def
rfc1213.def
rfc1271.def

Care must be taken when editing the mibs file as MIBs often refer to other MIBs. If the MIB providing the referenced definition is not listed before the referencing MIB in the mibs file the variables will not be accessible. It is for this reason that the root.def file must be specified at all times and be listed as the first entry in the mibs file. For further information on adding custom MIBs to the library, please see the Hughes Technologies web site at www.Hughes.com.au. The site also includes a copy of the MIB compiler that can be used to generate MOSY formatted files from standard ASN.1 definition files.

Function List

Form SNMP "connection"

 
int snmpopen(host, community)
    char    host, community;

Close an SNMP connection

 
void snmpclose(cd)
    int     cd;

Perform SNMP GET operation

 
array snmpget(cd, vars)
    int     cd;
    array   vars;

Perform SNMP GETNEXT operation

 
array snmpgetnext (cd, vars)
    int     cd;
    array   vars;

 

 

Example

 
#!/usr/local/Hughes/bin/lite
/*
** 	Title   : RouteTable 
**	Purpose : Grab a box's route table via SNMP
**	Author  : David J. Hughes (bambi@Hughes.com.au)
*/
modload "mod_snmp";
 
$IPR = "ip.ipRouteTable.ipRouteEntry";
$routeTypes = ["Other","Invalid","Direct","Indirect"];

/*
** Check command line args
*/
if ($argc != 3)
{
	echo("\nUsage : routetable hostname community\n\n");
	exit(1);
}
printf("\nDumping route table from %s using a community of %s\n\n",
	$argv[1], $argv[2]);

/*
** Fire up SNMP and get a connection to the box
*/
$fd = snmpopen($argv[1],$argv[2]);
if ($fd < 0)
{
	printf("\n\n%s : %s!\n\n",$argv[0], $ERRMSG);
	exit(1);
}

/*
** Print a pretty header :-)
*/
echo(" IP Route Table\n");
echo(" ==============\n\n");
echo(" Dest Metric Next Hop Type\n");
echo("----------------------------------------------------------\n");

/*
** Setup the variables we want to grab and then loop until the
** getnext returns an object ID with a different prefix.
*/
$vars[0] = $IPR + ".ipRouteDest";
$vars[1] = $IPR+".ipRouteMetric1"; 
$vars[2] = $IPR+".ipRouteNextHop";
$vars[3] = $IPR+".ipRouteType";
 
while($vars[0] =~ $IPR+".ipRouteDest")
{
	$result = snmpgetnext($fd,$vars);
	$index = 0;
	if ( # $result == 0)
	{
		printf("\n%s : $ERRMSG\n",$argv[0]);
		exit(1);
	}

	/*
	** Loop through the returned array splitting the returned
	** OID from the returned data. Store each part in a new
	** array for later use.
	*/
	while($index < #$result)
	{
		$data = split($result[$index],LITE_BRK);
		$vars[$index] = $data[0];
		$out[$index] = $data[1];
		$index = $index + 1;
	}

	/*
	** Print the results
	*/
	if($vars[0] =~ $IPR+".ipRouteDest")
	{
		printf(" %-16s %-3s %-16s %-s\n",$out[0],
			$out[1],$out[2],$routeTypes[(int)$out[3] - 1]);
	}
}
echo("----------------------------------------------------------\n");

Author

mod_snmp was written by David J. Hughes (bambi@Hughes.com.au) and is copyright © 1998 Hughes Technologies Pty Ltd, Australia. The SNMP library on which it depends was originally developed as part of the Beholder RMON project and is copyright © 1993 by the DNPAP group of TU Delft in the Netherlands (tudelft.nl). The library has been modified by Hughes Technologies to provide better MIB handling and more consistent OID management. The SNMP library code was originally placed under the GNU Public License by the DNPAP Group. The modified library included with this module remains under the GPL.