		      Perl5 SNMP Extension Module
		  Version 1.7 (supports UCD port only)
				6/16/96
		  G.S.Marzot(gmarzot@baynetworks.com)


Introduction:

This is a Perl5 extension module which provides an interface to the UCD
port of the CMU SNMP toolkit/library. This version was developed on a
linux box and tested with perl5.004 and ucd-snmp-3.2 (based on
cmu-snmp-2.1.2.1). There have been reports of success on sunos, hpux,
aix, irix and solaris systems so far. (Let me know of problems and/or
successes on other boxes please)

The most recent version of the module can be retrieved from
ftp:/ftp.wellfleet.com/netman/snmp/perl5/SNMP.tar.gz
(as well as the usual perl archives, CPAN)

The ucd port of cmu source may be found at the following location:
ftp://ftp.ece.ucdavis.edu/pub/snmp

(NOTE: this release supports the UCD port exclusively and provides
       only SNMP v1 functionality - work is being done on a version of
       this module which will interface to an updated, SNMPv2c ,
       version of the mainline CMU code - see XXXX for more details)

Description:

The basic operations offered by SNMP are provided through an object
oriented interface for modularity and ease of use. The primary class is
SNMP::Session which is implemented as a blessed hash reference. This
class supplies 'get', 'fget', 'set', and 'getnext' method calls. All
calls are currently blocking/synchronous (i.e., they must receive a
response or timeout before control is returned to the caller - an
asyncronous implementation is very high on the todo list). The methods
take a variety of input argument formats (see below). A description of
the fields which can be initialized/overriden when a SNMP::Session
object is created follows:

SNMP::Session
public:
 DestHost    - default 'localhost', hostname or ip addr of SNMP agent
 Community   - default 'public', SNMP community string
 Version     - default '1', v1 support only for now
 RemotePort  - default '161', allow remote UDP port to be overriden
 Timeout     - default '1000000', micro-seconds before retry
 Retries     - default '5', retries before failure
 RetryNoSuch - default '1', 'get' request NOSUCH errors in the pdu will
               be repaired, removing the varbind in error, and resent -
               undef will be returned for all NOSUCH varbinds, setting
               to '0' disables this feature and the entire get request
               will fail on any NOSUCH error
 VarFormats  - default 'undef', used by 'fget', holds an hash
               reference of output value formatters, (e.g., {<obj> =>
               <sub-ref>, ... }, <obj> must match the <obj> and format
               used in the get operation. A special <obj>, '*', may be
               used to apply all <obj>s, the supplied sub is called to
               translate the value to a new format. The sub is called
               passing the Varbind as the arg
 TypeFormats - default 'undef', used by 'fget', holds an hash
               reference of output value formatters, (e.g., {<type> =>
               <sub-ref>, ... }, the supplied sub is called to translate
               the value to a new format, unless a VarFormat mathces first
               (e.g., $session->{TypeFormats}{INTEGER} = \&mapEnum();)
 ErrorStr    - read-only, holds the error message assoc. w/ last request
 ErrorNum    - read-only, holds the snmp_err or staus of last request
 ErrorInd    - read-only, holds the snmp_err_index when appropriate

private:
 DestAddr    - internal field used to hold the translated DestHost field
 SessPtr     - internal field used to cache a created session structure

methods:
 new(<fields>)   - Constructs a new SNMP::Session object. The fields are
                   passed to the contructor as a hash list
                   (e.g., $session = new SNMP::Session(DestHost => 'foo',
                    Community => 'private');
 get(<vars>)     - do SNMP GET, multiple <vars> formats accepted,
                   updates <vars>, returns retrieved value(s)
 fget(<vars>)
                 - do SNMP GET and format the values according
                   the handlers specified in $sess->{VarFormats} and
                   $sess->{TypeFormats}
 getnext(<vars>) - do SNMP GETNEXT, multiple <vars> formats accepted,
                   updates <vars>, returns retrieved value(s)
 set(<vars>)     - do SNMP SET, multiple <vars> formats accepted,
                   returns snmp_errno

 getbulk(<non-repeaters>, <max-repeaters>, <vars>)
                 - * Not Implemented *

<vars> may be one of the following forms:

 SNMP::VarList:  - Implemeted as a blessed reference to an array of
                   SNMP::Varbinds, [<varbind1>, <varbind2>, ...]

 SNMP::Varbind:  - Implemeted as a blessed reference to a 4 element array;
		   [<obj>, <iid>, <val>, <type>].
                   <obj>  - one of the following forms:
                          1) leaf identifier (e.g., 'sysDescr') assumed to be
                             unique for practical purposes
                          2) fully qualified identifier (e.g.,
			     '.iso.org.dod.internet.mgmt.mib-2.system.sysDescr')
                          3) fully qualified, dotted-decimal, numeric OID (e.g.,
                             '.1.3.6.1.2.1.1.1')
                   <iid>  - the dotted-decimal, instance identifier. for
                            scalars use '0'
		   <val>  - the SNMP data value retrieved from, or being set
                            to, the agent
                   <type> - SNMP data type, this field need not be supplied for
                            set operations to attributes already described in
                            the Mib. If a numeric OID is used to set an object
                            which is not in the Mib being used, <type> must be
                            supplied (see 'getType' for values)

 simple scalar   - light weight form of <var> used to 'set' or 'get' a
                   single attribute without constructing an SNMP::Varbind.
                   (e.g., 'sysDescr.0'). for 'set' operations the value
                   is passed as a second arg. This form is not updated
                   in getnext and only returns values on the stack

SNMP package variables and functions:

 $SNMP::VERSION       - the current version specifier (e.g., 1.7)

 $SNMP::auto_init_mib - default '1', enables the immediate loading of the
                        ASN.1 mib when the package is loaded - if set to '0'
                        mib loading must be done explicitly (see SNMP::setMib)

 $SNMP::verbose       - default '0', verbosity level, 0 => no output

 &SNMP::setMib(<file>) - allows dynamic (re)parsing of the mib and explicit
                        specification of mib file independent of enviroment
                        variables. called with no args will exhibit default 
                        behaviour indicated by environment variables (see
                        ucd mib_api docs). subsequent calls to setMib will
                        cause previous mib to be freed and replaced.

 &SNMP::addMib(<file>) - allows dynamic (re)parsing of the mib and explicit
                        specification of mib file to be added to currently pare
                        seed Mib tree

 &SNMP::translateObj(<var>) - will convert a text object tag to an OID and
                            vice-versa. iid suffix is retained numerically

 &SNMP::getType(<var>) - return SNMP data type for given textual identifier
                        OBJECTID, OCTETSTR, INTEGER, NETADDR, IPADDR, COUNTER
                        GAUGE, TIMETICKS, OPAQUE, or undef

 &SNMP::mapEnum(<var>) - converts integer value to enumertion tag defined
                        in Mib

Installation:

build/install ucd-snmp-3.2 libsnmp.a (e.g., /usr/local/lib)

make sure header files are available someplace (e.g., /usr/local/include)

after that it is basically

perl Makefile.PL
make
make test
make install

the SNMP tool-kit requires that an ASN.1 mib be available. 'mib.txt' is
the default name looked for first in the local directory and then in
/etc. See UCD/CMU-SNMP docs for details on overriding the default or set
mib explicitly with SNMP::setMib and SNMP::addMib.

------

Many thanks to those in the Perl community and perl5-porters list who
helped immensely.

bugs, comments, questions to gmarzot@baynetworks.com


------
Bugs fixed and changes in 1.7

1) fixed seg fault on use of unknown/unparsed attribute in Varbind or
   passed to translateObj

2) fixed truncation of last char of attribute name in tranlsateObj

3) handles variable args to setMib without complaint

4) added SNMP::getType to query data type of a given attribute and
   extended Varbind structure to hold type as well

5) added RemotePort to SNMP::Session initialation list to allow override
   of port 161

6) removed noisy announcement of mib parse success unless verbose is set

	       *WARNING*  *this may break existing scripts*
7) changed return format for IpAddress and ObjID data types - these are
   now always returned as dotted decimal strings as opposed to the
   packed binary forms in 1.6
	       *WARNING*  *this may break existing scripts*

8) Session now sets ErrorInd (e.g., $session->{ErrorInd}) where appropriate

9) Fully qualified attriubute names and numeric OIDs are now valid <obj>
   defintions.

10) Numeric OIDs can be used even if they have not been parsed in the
    current Mib (note: <type> must be supplied)
