readme

ucd-snmp源代码

	      The Perl5 'SNMP' Extension Module v4.2.0
		      for the Net-SNMP Library
	       G.S. Marzot ([e-mail])

Contents:
   Introduction:
   Availability:
   Contact:
   Supported Platforms:
   Release Notes:
   Installation:
   Operational Description:
   Trouble Shooting:
   Acknowledgments:
   History:
   Copyright:

Introduction:

This is the Perl5 'SNMP' extension module. The SNMP module provides a
full featured, tri-lingual SNMP (SNMPv3, SNMPv2c, SNMPv1) API. The
SNMP module also provides an interface to the SMI MIB parse-tree for
run-time access to parsed MIB data.  The SNMP module internals rely on
the Net-SNMP toolkit library (previously known as ucd-snmp). For
information on the Net-SNMP library see the documentation provided
with the Net-SNMP distribution or the project web page available on
'Source Forge':

http://sourceforge.net/projects/net-snmp

Availability:

The most recent release of the Perl5 SNMP module can be found bundled
with the latest Net-SNMP distibution available from:
http://sourceforge.net/projects/net-snmp

(Note: The perl SNMP distribution obtained this way has the highest
chance of being up to date and compatible with the Net-SNMP version
with which it is bundled.)

A seperately bundled package of the SNMP module can be obtained from CPAN.

Development and older releases may be found at the following FTP site:
ftp://ftp-east.baynetworks.com/netman/snmp/perl5

(Note: In previous releases this module was compatible with the CMU
SNMP library. Starting with Perl5/SNMP-1.7 this module will *only*
work with the Net-SNMP (aka ucd-snmp) library due to dependence on new
features)

Contact:
	the following forums may be helpful:

	comp.lang.perl.modules
	[e-mail] mail list
	(see http://sourceforge.net/projects/net-snmp to subscribe)
        [e-mail] (last resort)

Supported Platforms:
	Linux 1.2.x, 2.x
	Solaris 2.x
	Many other UNIX variants
	Win9x/NT

Release Notes:

SNMP module version 4.2.0 is being developed against NET-SNMP-4.2.0
see http://sourceforge.net/projects/net-snmp for details.

Compatibility with earlier or later versions of Net-SNMP or UCD-SNMP
is not guaranteed due to the dynamic nature of open software
development :).

the previous stable release is SNMP-3.1.0 and ucd-snmp-4.1.2.

Yes, I skipped some versions, do not be alarmed.

KNOWN BUGS:

(none?)

Installation:

Build and install the Net-SNMP package - see Net-SNMP README and
INSTALL docs.

(Note: To ensure that any previous Net-SNMP, ucd-snmp or cmu snmp
installation's library or headers are not used by mistake, use the
-NET-SNMP-PATH directive to explicitly set the default path)

Unix:

perl Makefile.PL [-NET-SNMP-PATH=/usr/local]
make
make test
make install

Win32:

This package only builds on NT as far as I know. Thes directions are
fo VC++ 5.0-6.0 (I will be interested to hear of success with cygwin).

First  run vcvars32.bat

for ActiveState Perl  (tested with AS Perl5.005_03 (515))

perl Makefile.PL CAPI=TRUE [-NET-SNMP-PATH=/usr]
nmake
nmake test
nmake install

OpenSSL note: see the net-snmp/README.win32 to compile libsnmp with
              libeay32 and see that libeay.lib is in usr\lib

for the older perl5.004_02 distribution by gsarathy

perl Makefile.PL
nmake
nmake test
nmake install


Win32 Testing Note:

'nmake test' requires that an agent(snmpd) and trap receiver (snmptrapd)
are running. Before running 'nmake test' start these servers using the
config file provided (t/snmpd.conf). You will be asked for the test host
and port numbers by Makefile.PL

Operational Description:

The basic operations of the SNMP protocol are provided by this module
through an object oriented interface for modularity and ease of use.
The primary class is SNMP::Session which encapsulates the persistent
aspects of a connection between the management application and the
managed agent. Internally the class is implemented as a blessed hash
reference. This class supplies 'get', 'getnext', 'set', 'fget', and
'fgetnext' and other method calls. The methods take a variety of input
argument formats and support both synchronous and asynchronous
operation through a polymorphic API (i.e., method behaviour varies
dependent on args passed - see below).

A description of the fields which can be specified when an
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 (used for both R/W)
 Version     - default '1', [2 (same as 2c), 2c, 3]
 RemotePort  - default '161', allow remote UDP port to be overridden
 Timeout     - default '1000000', micro-seconds before retry
 Retries     - default '5', retries before failure
 RetryNoSuch - default '0', if enabled NOSUCH errors in 'get' pdus will
               be repaired, removing the varbind in error, and resent -
               undef will be returned for all NOSUCH varbinds, when set
               to '0' this feature is disabled and the entire get request
               will fail on any NOSUCH error (applies to v1 only)
 SecName     - default 'initial', security name (v3)
 SecLevel    - default 'noAuthNoPriv', security level [noAuthNoPriv,
               authNoPriv, authPriv] (v3)
 SecEngineId - default <none>, security engineID, will be probed if not
               supplied (v3)
 ContextEngineId - default <SecEngineId>, context engineID, will be
                   probed if not supplied (v3)
 Context     - default '', context name (v3)
 AuthProto   - default 'MD5', authentication protocol [MD5, SHA] (v3)
 AuthPass    - default <none>, authentication passphrase
 PrivProto   - default 'DES', privacy protocol [DES] (v3)
 PrivPass    - default <none>, privacy passphrase (v3)
 VarFormats  - default 'undef', used by 'fget[next]', 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[next]', 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();
                although this can be done more efficiently by enabling
                $SNMP::use_enums or session creation param 'UseEnums')
 UseLongNames - defaults to the value of SNMP::use_long_names at time
               of session creation. set to non-zero to have <tags>
               for 'getnext' methods generated preferring longer Mib name
               convention (e.g., system.sysDescr vs just sysDescr)
 UseSprintValue - defaults to the value of SNMP::use_sprint_value at time
               of session creation. set to non-zero to have return values
               for 'get' and 'getnext' methods formatted with the libraries
               sprint_value function. This will result in certain data types
               being returned in non-canonical format Note: values returned
               with this option set may not be appropriate for 'set' operations
               (see discussion of value formats in <vars> description section)
 UseEnums    - defaults to the value of SNMP::use_enums at time of session
               creation. set to non-zero to have integer return values
               converted to enumeration identifiers if possible, these values
               will also be acceptable when supplied to 'set' operations
 UseNumeric  - defaults to the value of SNMP::use_numeric at time of session
               creation. set to non-zero to have <tags> returned by the 'get'
               methods untranslated (i.e. dotted-decimal).  Setting the
               UseLongNames value for the session is highly recommended.
 TimeStamp   - defaults to the value of SNMP::timestamp_vars at time of
               session creation. set to non-zero to add an additional element
               to each Varbind, containing a time(2) timestamp.  Reference
               the Varbind timestamp through the $varbind_ref->stamp() method.
	       Do not modify a timestamp value -- it is shared between all
	       variables that were received at the same time.

 ErrorStr    - read-only, holds the error message assoc. w/ last request
 ErrorNum    - read-only, holds the snmp_err or status 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 constructor as a hash list
                   (e.g., $session = new SNMP::Session(DestHost => 'foo',
                   Community => 'private');), returns an object reference
                   or undef in case of error.
 update(<fields>)- Updates the SNMP::Session object with the values fields
                   passed in as a hash list (similar to new(<fields>))
                   (WARNING! not fully implemented)
 get(<vars>[,<callback>])
                 - do SNMP GET, multiple <vars> formats accepted.
                   for synchronous operation <vars> will be updated
                   with value(s) and type(s) and will also return
                   retrieved value(s). If <callback> supplied method
                   will operate asynchronously
 fget(<vars>[,<callback>])
                 - do SNMP GET like 'get' and format the values according
                   the handlers specified in $sess->{VarFormats} and
                   $sess->{TypeFormats}. Async *not supported*
 getnext(<vars>[,<callback>])
                 - do SNMP GETNEXT, multiple <vars> formats accepted,
                   returns retrieved value(s), <vars> passed as arguments are
                   updated to indicate next lexicographical <obj>,<iid>,<val>,
                   and <type> Note: simple string <vars>,(e.g., 'sysDescr.0')
                   form is not updated. If <callback> supplied method
                   will operate asynchronously
 fgetnext(<vars>[,<callback>])
                 - do SNMP GETNEXT like getnext and format the values according
                   the handlers specified in $sess->{VarFormats} and
                   $sess->{TypeFormats}. Async *not supported*
 set(<vars>[,<callback>])
                 - do SNMP SET, multiple <vars> formats accepted.
                   the value field in all <vars> formats must be in a canonical
                   format (i.e., well known format) to ensure unambiguous
                   translation to SNMP MIB data value (see discussion of
                   canonical value format <vars> description section),
                   returns true on success or undef on error. If <callback>
                   supplied method will operate asynchronously
 getbulk(<non-repeaters>, <max-repeaters>, <vars> [, <callback>])
                 - do an SNMP GETBULK, from the list of Varbinds, the single
                   next lexico instance is fetched for the first n Varbinds