Index of /~plonka/Altoids

Name	Last modified	Size

Parent Directory		-
old/	2014-05-25 12:01	-
ReadMe	1999-01-27 17:16	769
Altoids1.017.tar.gz	1999-01-28 17:04	48K

Altoids - SNMP get/walk functionality with built-in name to OID translation

NAME
SYNOPSIS
DESCRIPTION
METHODS
EXAMPLES
NOTES
BUGS
AUTHOR

NAME

Altoids - SNMP get/walk functionality with built-in name to OID translation

SYNOPSIS

   use Altoids;

   $snmp = Altoids->new(\%hints, @oid_files);
   $snmp->open($gateway, $community, $port);
   %retblock = $snmp->get($name, $index);
   %retblock = $snmp->walk($name);
   $snmp->close();

DESCRIPTION

Altoids is based upon SNMP_Session.pm and BER.pm, a self-contained, low-level perl SNMP implementation. This module mainly provides two simple calling interfaces: get and walk, which are the roughly equivalent to the correspondingly named snmpget and snmpwalk commands of the CMU SNMP package. Additionally, it is able to assimilate information from SunNet Manager file.oid files so that short alpha names (eg. ``sysName'') are used rather than having to use the cumbersome dotted-decimal OIDs (eg. ``1.3.6.1.2.1.1.5''). (It does this as an alternative to a full-blown MIB compiler to translate OIDs - hence the name Altoids.)

METHODS

Documention on the class and object methods that make up the API follows. If you find some of the details confusing, please see the EXAMPLES below.

Altoids->new([hints_hashref] [[,] oid_file [...]])

This is the Altoids constructor. It has the following argument types:

hints

The hints_hashref argument, if supplied, must be the first argument. This argument is used to inform your Altoids object about the type of various items in a MIB. (This is necessary in some instances because Altoids contains no MIB compiler so it can't know about a given item from a MIB definition.)

An example hints_hashref is defined in the file altoids.pl that will be installed with this package. This example is used by the altwalk and altget utilities, also supplied. If you find the need to write your own ``hints'', or to augment that example, the following discussion is an attempt to explain this feature.

hints_hashref is a reference to a hash containing entries of this form:

      shortname => {
         attribute => value(s),
      },

where shortname is the short name by which you'd like to refer to a given OID. attribute is an attribute of this entry. The possible attributes are: oid, humanoid, lhs, rhs, rhstrans.

oid

The oid attribute simply specifies the OID as a scalar string. For example (for ifAdminStatus):

      oid => '1.3.6.1.2.1.2.2.1.7',

Definition of this attribute is not necessary if you have specified an appropriate oid file, which contains this definition, as an argument to the constructor.

humanoid

The humanoid attribute simply specifies the ``humanly-readable'' symbolic version of the OID as a scalar string. For example:

      humanoid => 'iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifAdminStatus',

Definition of this attribute is not necessary if you have specified an appropriate oid file, which contains this definition, as an argument to the constructor.

lhs

The lhs attribute, meaning ``Left-Hand Side'', specifies data type(s) of information that is encoded as a suffix within the OID. It is an array reference. This SNMP feature is sometimes referred to as ``conceptual rows''. For example for lesMacRegEntry:

      lhs => [ 'nstring', 'index', 'macaddr' ],

Possible values for the elements of this array are atmaddr, ipaddr, macaddr, nstring, string, and ushort:

atmaddr: An byte ATM address.
ipaddr: A 4 byte IP address.
macaddr: A 6 byte MAC address.
nstring: An ASCII string, preceeded by its numeric (1-255) length.
string: An ASCII string terminated by the end of the OID. (Therefore this must be the last element of an lhs attribute array.)
ushort: An unsigned 16-bit value (i.e. one that is assembled from two OID octets).

rhs

Possibly values for rhs are atmaddr, string, and ushort:

atmaddr: An byte ATM address.
string: An ASCII string.
ushort: An unsigned 16-bit value (i.e. one that is assembled from two octets).

rhstrans

The rhstrans attribute, meaning ``Right-Hand Side'', specifies a translation table for the value. This is often used to translate integer values to meaningful strings. For example, for ifAdminStatus:

         rhstrans => {
            1 => 'up(1)',
            2 => 'down(2)',
            3 => 'testing(3)'
         }

So, a full example of the elements of a hints hash might be:

      ifAdminStatus => {
         humanoid => 'iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifAdminStatus',
         oid => '1.3.6.1.2.1.2.2.1.7',
         rhstrans => {
            1 => 'up(1)',
            2 => 'down(2)',
            3 => 'testing(3)'
         }
      },

      sysDescr => {
         rhs => 'string' # sysDescr is a printable ASCII string
      },

      # ...

files

The oid_file arguments are the names of files containing the symbolic name (e.g. ``sysName'') to OID (e.g. ``1.3.6.1.2.1.1.5'') translation. The format of the files is that used by SunNet Manager. Files of this form can be hand-written (examples shipped with this package) or are available at ``http://www.cisco.com/public/mibs/oid''. These were apparently created from the MIB definitions using a tool called ``MIB2SCHEMA''.

$snmp->walk(SHORTNAME [, HASHREF ])

Takes a short name and returns a hash where the human-readable OID segments are the keys and either hashes or, ultimately, the OID values as scalar values. That is, it is a hash of hashes of values in the simplest case.

If a hash reference is passed as the last argument, the referenced hash will also be populated with the returned values.

If no name can be translated to an OID or the named variables are not available returns an empty hash. Returns (-1, -1) on other errors.

$snmp->get(SHORTNAME, INDEX [, INDEX [...] ] [, HASHREF ])

Takes a short name and index number(s) and returns a hash where the human-readable OID segments are the keys and either hashes or, ultimately, the OID values is the value. That is, it is a hash of a hash of a value in the simplest case. In a scalar context, returns just the value.

If a hash reference is passed as the last argument, the referenced hash will also be populated with the returned values.

If the name can't be translated to an OID or the named variable is not available returns an empty hash. Returns (-1, -1) on other errors.

$snmp->oid(SHORTNAME)

Takes a short name and returns a dotted-decimal OID in a scalar context, or array of the OID decimals in an array context.

EXAMPLES

example.pl:

   use Altoids;

   $hints = {
      sysDescr => { # from "RFC1213-MIB"
         humanoid => 'iso.org.dod.internet.mgmt.mib-2.system.sysDescr',
              oid => '1.3.6.1.2.1.1.1',
              rhs => 'string',
      },
   };

   $snmp = Altoids->new($hints);
   $snmp->open('localhost', 'public', 161);
   %retblock = $snmp->get('sysDescr', 0);
   die "get failed.\n" if (-1 == $retblock{-1});
   print $retblock{sysDescr}{0}, "\n";
   $snmp->close();

   exit

example2.pl:

   use Altoids;

   $snmp = Altoids->new('oids/RFC1213-MIB.oid');
   $snmp->open('localhost', 'public', 161);
   %retblock = $snmp->walk('system');
   die "walk failed.\n" if (-1 == $retblock{-1});
   hashprint('', %retblock);
   $snmp->close();

   exit;

   sub hashprint {
      my $prefix  = shift @_;
      my %hash  = @_;
      my ($val, $key);

      while (($key, $val) = each(%hash)) {
         if ('HASH' eq ref($val)) {
            hashprint($prefix? $prefix . '.' . $key : $key, %{$val})
         } else {
            print $prefix, '.', "$key = $val\n"
         }
      }
   }

NOTES

Enable verbose mode (informational messages to STDERR) by:

   $Altoids::verbose = 1;

BUGS

When performing a get or a walk you can't specify the index portion of the OID symbolicly. That is, you must specify the index as integers, even when you have defined the given item as a ``conceptual row'' in your ``hints'' by specifying an lhs attribute. In practice, this isn't usually a problem for walk because you can simply walk the parent item rather than performing a single get on just the item in which you're interested.

This package sometimes dies when bad things happen.

AUTHOR

Dave Plonka