readme

开发snmp的开发包有两个开放的SNMP开发库

   Note: With ActiveState Perl (currently at 5.8.2 build 808) and
         possibly other versions of Perl on Windows, if a Perl script
         modifies a system environment variable and then calls a C
         function, the C function will not see the new environment
         variable.  This problem can be seen with the failure of test
         #3 in the SNMP conf test (perl/SNMP/t/conf.t).  The change to
         the SNMPCONFPATH env variable is not seen by the calls to the
         C SNMP module.

   The main Net-SNMP package must be compiled with the regex library.  
   See Net-SNMP README.win32 for compiling with MinGW.

   The following additional software is required:

    dmake:
    http://www.cpan.org/authors/id/GSAR/dmake-4.1pl1-win32.zip  

    ExtUtils-FakeConfig:
    http://search.cpan.org/~mbarbon/ExtUtils-FakeConfig-0.05/

   Note: A PPM package is available from ActiveState for
          ExtUtils-FakeConfig, but it does not include the
          make_implib.pl script.  Downloading from CPAN is
          recommended.

   Installing DMAKE and ExtUtils-FakeConfig:
   -----------------------------------------

   1.  Install DMAKE as described in the README.NOW contained in the DMAKE .ZIP 
       file ensuring the DMAKE program can be found in the system path.

   2.  Extract ExtUtils-FakeConfig-0.05.zip to a temporary folder.

   3.  Add the MinGW bin folder to your system path.

   4.  Open a Windows command prompt (cmd) and cd into
       ExtUtils-FakeConfig-0.05 and typet he following to build and
       install the ExtUtils-FakeConfig module:

       perl Makefile.PL
       dmake
       dmake install

   5.  A Perl import library needs to be created using the ExtUtils-FakeConfig 
       make_implib.pl script.  

       For ActiveState Perl 5.6.x installed to c:\Perl, type the
       following on one line:

         perl script/make_implib.pl --output-dir=C:/Perl/lib/CORE 
           --output-lib=libperl56.a --target=mingw c:/Perl/bin/Perl56.dll

       For ActiveState Perl 5.8.x installed to c:\Perl, type the
       following on one line:

         perl script/make_implib.pl --output-dir=C:/Perl/lib/CORE 
           --output-lib=libperl58.a --target=mingw c:/Perl/bin/Perl58.dll


Building the Perl module:
-------------------------

   1.  Complete the section titled 'Installing DMAKE and ExtUtils-FakeConfig'

   2.  Open an MSYS shell and cd into the net-snmp/Perl folder and type the 
       following on one line:

         perl -MConfig_m Makefile.PL -NET-SNMP-IN-SOURCE=true DEFINE=-DMINGW_PERL

   3.  Open a Windows command prompt (cmd) and cd into the net-snmp/perl folder 
       and type:

         dmake
         dmake test
         dmake install

       Note:  'dmake test' will automatically start and stop the agent(snmpd) and 
              trap receiver (snmptrapd) while testing the SNMP module.  

   4.  Remove the MinGW bin folder to your system path if it was not already in
       your path for step 3 of 'Installing DMAKE and ExtUtils-FakeConfig'.


   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.
    BestGuess   - defaults to the value of SNMP::best_guess at time of session
                  creation. this setting controls how <tags> are parsed.  setting 
                  to 0 causes a regular lookup.  setting to 1 causes a regular 
                  expression match (defined as -Ib in snmpcmd) and setting to 2 
                  causes a random access lookup (defined as -IR in snmpcmd).
    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
                      as defined by <non-repeaters>. For remaining Varbinds,
                      the m lexico instances are retrieved each of the remaining
                      Varbinds, where m is <max-repeaters>.
    bulkwalk(<non-repeaters>, <max-repeaters>, <vars> [, <callback>])
                    - do an "SNMP bulkwalk" on the given variables.  Bulkwalk is
                      implemented by sending an SNMP GETBULK request to fetch the
                      variables.  Objects are copied to the return list until the
                      sub-tree is exited.  If the request is not completed at the
                      end of a packet, a new request is created, starting where
                      the previous packet left off.  This implementation is able
                      to handle multiple repeated vars, as well as non-repeaters.
                      Returns a list (or, in scalar context, a reference to a
                      list) of arrays of VarBinds.  The VarBinds consist of the
                      responses for each requested variable.  bulkwalk() leaves
                      the original Varbinds list intact to facilitate querying
                      of multiple devices.

   SNMP::TrapSession - supports all applicable fields from SNMP::Session
                       (see above)
   methods:
    new(<fields>)   - Constructs a new SNMP::TrapSession object. The fields are
                      passed to the constructor as a hash list
                      (e.g., $trapsess = new SNMP::Session(DestHost => 'foo',
                      Community => 'private');), returns an object reference
                      or undef in case of error.
    trap(enterprise, agent, generic, specific, uptime, <vars>)
       $sess->trap(enterprise=>'.1.3.6.1.4.1.2021', # or 'ucdavis' [default]
                   agent => '127.0.0.1', # or 'localhost',[dflt 1st intf on host]
                   generic => specific,  # can be omitted if 'specific' supplied
                   specific => 5,        # can be omitted if 'generic' supplied
                   uptime => 1234,       # dflt to localhost uptime (0 on win32)
                   [[ifIndex, 1, 1],[sysLocation, 0, "here"]]); # optional vars
                                                                # always last
    or v2 format
    trap(oid, uptime, <vars>)
       $sess->trap(oid => 'snmpRisingAlarm',
                   uptime => 1234,
                   [[ifIndex, 1, 1],[sysLocation, 0, "here"]]); # optional vars
                                                                # always last


   Acceptable variable formats:
   <vars> may be one of the following forms:

    SNMP::VarList:  - represents an array of MIB objects to get or set,
                      implemented as a blessed reference to an array of
                      SNMP::Varbinds, (e.g., [<varbind1>, <varbind2>, ...])

    SNMP::Varbind:  - represents a single MIB object to get or set, implemented 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
                               scalar MIB objects use '0'
   		   <val>  - the SNMP data value retrieved from or being set
                               to the agents MIB. for (f)get(next) operations
                               <val> may have a variety of formats as determined by
                               session and package settings. However for set
                               operations the <val> format must be canonical to
                               ensure unambiguous translation. The canonical forms
                               are as follows:
   	                    OBJECTID => dotted-decimal (e.g., .1.3.6.1.2.1.1.1)
   			    OCTETSTR => perl scalar containing octets,
   		            INTEGER => decimal signed integer (or enum),
   			    NETADDR => dotted-decimal,
   			    IPADDR => dotted-decimal,
   			    COUNTER => decimal unsigned integer,
   			    COUNTER64  => decimal unsigned integer,
   			    GAUGE,  => decimal unsigned integer,
   			    UINTEGER,  => decimal unsigned integer,
                               TICKS,  => decimal unsigned integer,
                               OPAQUE => perl scalar containing octets,
          			    NULL,  => perl scalar containing nothing,


                      <type> - SNMP data type (see list above), this field is
                               populated by 'get' and 'getnext' operations. In
                               some cases the programmer needs to populate this
                               field when passing to a 'set' operation. this
                               field need not be supplied when the attribute
                               indicated by <tag> is already described by loaded