userapps/opensource/net-snmp/perl/SNMP/README

   1               The Perl5 'SNMP' Extension Module v5.0
   2                       for the Net-SNMP Library
   3
   4 Contents:
   5    Introduction:
   6    Availability:
   7    Contact:
   8    Supported Platforms:
   9    Release Notes:
  10    Installation:
  11    Operational Description:
  12    Trouble Shooting:
  13    Acknowledgments:
  14    History:
  15    Copyright:
  16
  17 Introduction:
  18
  19 ******************************NOTE NOTE NOTE**************************
  20   This module now relies on many other modules.  Do not try to build
  21   it independently, as it won't work.  Instead of running "perl
  22   Makefile.PL" in this directory, run it in the net-snmp/perl
  23   directory instead which has a global makefile used to build all the
  24   sub-modules in their proper order.
  25 ******************************NOTE NOTE NOTE**************************
  26
  27 Note: The perl SNMP 5.0module which comes with net-snmp 5.0 and
  28 higher is different than previous versions in a number of ways.  Most
  29 importantly, it behaves like a proper net-snmp application and calls
  30 init_snmp properly, which means it will read configuration files and
  31 use those defaults where appropriate automatically parse MIB files,
  32 etc.  This will likely affect your perl applications if you have, for
  33 instance, default values set up in your snmp.conf file (as the perl
  34 module will now make use of those defaults).  The docmuentation,
  35 however, has sadly not been updated yet (aside from this note).
  36
  37 This is the Perl5 'SNMP' extension module. The SNMP module provides a
  38 full featured, tri-lingual SNMP (SNMPv3, SNMPv2c, SNMPv1) API. The
  39 SNMP module also provides an interface to the SMI MIB parse-tree for
  40 run-time access to parsed MIB data.  The SNMP module internals rely on
  41 the Net-SNMP toolkit library (previously known as ucd-snmp). For
  42 information on the Net-SNMP library see the documentation provided
  43 with the Net-SNMP distribution or the project web page available on
  44 'Source Forge':
  45
  46 http://sourceforge.net/projects/net-snmp
  47
  48 Availability:
  49
  50 The most recent release of the Perl5 SNMP module can be found bundled
  51 with the latest Net-SNMP distibution available from:
  52 http://sourceforge.net/projects/net-snmp
  53
  54 (Note: The perl SNMP distribution obtained this way has the highest
  55 chance of being up to date and compatible with the Net-SNMP version
  56 with which it is bundled.)
  57
  58 A seperately bundled package of the SNMP module can be obtained from CPAN.
  59
  60 Development and older releases may be found at the following FTP site:
  61 ftp://ftp-east.baynetworks.com/netman/snmp/perl5
  62
  63 (Note: In previous releases this module was compatible with the CMU
  64 SNMP library. Starting with Perl5/SNMP-1.7 this module will *only*
  65 work with the Net-SNMP (aka ucd-snmp) library due to dependence on new
  66 features)
  67
  68 Contact:
  69         the following forums may be helpful:
  70
  71         comp.lang.perl.modules
  72         net-snmp-users@lists.sourceforge.net mail list
  73         (see http://www.net-snmp.org/lists/users/ to subscribe)
  74
  75 Supported Platforms:
  76         Linux 1.2.x, 2.x
  77         Solaris 2.x
  78         Many other UNIX variants
  79         Win9x/NT
  80
  81 Release Notes:
  82
  83 SNMP module version 5.0 is being developed against NET-SNMP-5.0
  84 see http://sourceforge.net/projects/net-snmp for details.
  85
  86 Compatibility with earlier or later versions of Net-SNMP or UCD-SNMP
  87 is not guaranteed due to the dynamic nature of open software
  88 development :).
  89
  90 KNOWN BUGS:
  91
  92 (none?)
  93
  94 Installation:
  95
  96 Build and install the Net-SNMP package - see Net-SNMP README and
  97 INSTALL docs.
  98
  99 (Note: To ensure that any previous Net-SNMP, ucd-snmp or cmu snmp
 100 installation's library or headers are not used by mistake, use the
 101 -NET-SNMP-CONFIG directive to explicitly set the path to the
 102 net-snmp-config command that knows about the net-snmp installation you
 103 want to use.)
 104
 105 NOTE: build all the perl modules at once using the Makefile.PL in the
 106 net-snmp/perl directory rather than the one in this directory.
 107
 108 Unix:
 109
 110 cd net-snmp/perl
 111 perl Makefile.PL [-NET-SNMP-CONFIG="sh ../../net-snmp-config"] [-NET-SNMP-IN-SOURCE=true]
 112 make
 113 make test
 114 make install
 115
 116 Win32:
 117
 118 This package only builds on NT as far as I know. Thes directions are
 119 fo VC++ 5.0-6.0 (I will be interested to hear of success with cygwin).
 120
 121 First  run vcvars32.bat
 122
 123 for ActiveState Perl  (not tested with the latest net-snmp 5.0 code)
 124
 125 perl net-snmp/Makefile.PL CAPI=TRUE [-NET-SNMP-PATH=/usr]
 126 nmake
 127 nmake test
 128 nmake install
 129
 130 OpenSSL note: see the net-snmp/README.win32 to compile libsnmp with
 131               libeay32 and see that libeay.lib is in usr\lib
 132
 133 for the older perl5.004_02 distribution by gsarathy
 134
 135 perl Makefile.PL
 136 nmake
 137 nmake test
 138 nmake install
 139
 140
 141 Win32 Testing Note:
 142
 143 'nmake test' requires that an agent(snmpd) and trap receiver (snmptrapd)
 144 are running. Before running 'nmake test' start these servers using the
 145 config file provided (t/snmpd.conf). You will be asked for the test host
 146 and port numbers by Makefile.PL
 147
 148 Operational Description:
 149
 150 The basic operations of the SNMP protocol are provided by this module
 151 through an object oriented interface for modularity and ease of use.
 152 The primary class is SNMP::Session which encapsulates the persistent
 153 aspects of a connection between the management application and the
 154 managed agent. Internally the class is implemented as a blessed hash
 155 reference. This class supplies 'get', 'getnext', 'set', 'fget', and
 156 'fgetnext' and other method calls. The methods take a variety of input
 157 argument formats and support both synchronous and asynchronous
 158 operation through a polymorphic API (i.e., method behaviour varies
 159 dependent on args passed - see below).
 160
 161 A description of the fields which can be specified when an
 162 SNMP::Session object is created follows:
 163
 164 SNMP::Session
 165 public:
 166  DestHost    - default 'localhost', hostname or ip addr of SNMP agent
 167  Community   - default 'public', SNMP community string (used for both R/W)
 168  Version     - default '1', [2 (same as 2c), 2c, 3]
 169  RemotePort  - default '161', allow remote UDP port to be overridden
 170  Timeout     - default '1000000', micro-seconds before retry
 171  Retries     - default '5', retries before failure
 172  RetryNoSuch - default '0', if enabled NOSUCH errors in 'get' pdus will
 173                be repaired, removing the varbind in error, and resent -
 174                undef will be returned for all NOSUCH varbinds, when set
 175                to '0' this feature is disabled and the entire get request
 176                will fail on any NOSUCH error (applies to v1 only)
 177  SecName     - default 'initial', security name (v3)
 178  SecLevel    - default 'noAuthNoPriv', security level [noAuthNoPriv,
 179                authNoPriv, authPriv] (v3)
 180  SecEngineId - default <none>, security engineID, will be probed if not
 181                supplied (v3)
 182  ContextEngineId - default <SecEngineId>, context engineID, will be
 183                    probed if not supplied (v3)
 184  Context     - default '', context name (v3)
 185  AuthProto   - default 'MD5', authentication protocol [MD5, SHA] (v3)
 186  AuthPass    - default <none>, authentication passphrase
 187  PrivProto   - default 'DES', privacy protocol [DES] (v3)
 188  PrivPass    - default <none>, privacy passphrase (v3)
 189  VarFormats  - default 'undef', used by 'fget[next]', holds an hash
 190                reference of output value formatters, (e.g., {<obj> =>
 191                <sub-ref>, ... }, <obj> must match the <obj> and format
 192                used in the get operation. A special <obj>, '*', may be
 193                used to apply all <obj>s, the supplied sub is called to
 194                translate the value to a new format. The sub is called
 195                passing the Varbind as the arg
 196  TypeFormats - default 'undef', used by 'fget[next]', holds an hash
 197                reference of output value formatters, (e.g., {<type> =>
 198                <sub-ref>, ... }, the supplied sub is called to translate
 199                the value to a new format, unless a VarFormat mathces first
 200                (e.g., $session->{TypeFormats}{INTEGER} = \&mapEnum();
 201                 although this can be done more efficiently by enabling
 202                 $SNMP::use_enums or session creation param 'UseEnums')
 203  UseLongNames - defaults to the value of SNMP::use_long_names at time
 204                of session creation. set to non-zero to have <tags>
 205                for 'getnext' methods generated preferring longer Mib name
 206                convention (e.g., system.sysDescr vs just sysDescr)
 207  UseSprintValue - defaults to the value of SNMP::use_sprint_value at time
 208                of session creation. set to non-zero to have return values
 209                for 'get' and 'getnext' methods formatted with the libraries
 210                sprint_value function. This will result in certain data types
 211                being returned in non-canonical format Note: values returned
 212                with this option set may not be appropriate for 'set' operations
 213                (see discussion of value formats in <vars> description section)
 214  UseEnums    - defaults to the value of SNMP::use_enums at time of session
 215                creation. set to non-zero to have integer return values
 216                converted to enumeration identifiers if possible, these values
 217                will also be acceptable when supplied to 'set' operations
 218  UseNumeric  - defaults to the value of SNMP::use_numeric at time of session
 219                creation. set to non-zero to have <tags> returned by the 'get'
 220                methods untranslated (i.e. dotted-decimal).  Setting the
 221                UseLongNames value for the session is highly recommended.
 222  ErrorStr    - read-only, holds the error message assoc. w/ last request
 223  ErrorNum    - read-only, holds the snmp_err or status of last request
 224  ErrorInd    - read-only, holds the snmp_err_index when appropriate
 225
 226 private:
 227  DestAddr    - internal field used to hold the translated DestHost field
 228  SessPtr     - internal field used to cache a created session structure
 229
 230 methods:
 231  new(<fields>)   - Constructs a new SNMP::Session object. The fields are
 232                    passed to the constructor as a hash list
 233                    (e.g., $session = new SNMP::Session(DestHost => 'foo',
 234                    Community => 'private');), returns an object reference
 235                    or undef in case of error.
 236  update(<fields>)- Updates the SNMP::Session object with the values fields
 237                    passed in as a hash list (similar to new(<fields>))
 238                    (WARNING! not fully implemented)
 239  get(<vars>[,<callback>])
 240                  - do SNMP GET, multiple <vars> formats accepted.
 241                    for synchronous operation <vars> will be updated
 242                    with value(s) and type(s) and will also return
 243                    retrieved value(s). If <callback> supplied method
 244                    will operate asynchronously
 245  fget(<vars>[,<callback>])
 246                  - do SNMP GET like 'get' and format the values according
 247                    the handlers specified in $sess->{VarFormats} and
 248                    $sess->{TypeFormats}. Async *not supported*
 249  getnext(<vars>[,<callback>])
 250                  - do SNMP GETNEXT, multiple <vars> formats accepted,
 251                    returns retrieved value(s), <vars> passed as arguments are
 252                    updated to indicate next lexicographical <obj>,<iid>,<val>,
 253                    and <type> Note: simple string <vars>,(e.g., 'sysDescr.0')
 254                    form is not updated. If <callback> supplied method
 255                    will operate asynchronously
 256  fgetnext(<vars>[,<callback>])
 257                  - do SNMP GETNEXT like getnext and format the values according
 258                    the handlers specified in $sess->{VarFormats} and
 259                    $sess->{TypeFormats}. Async *not supported*
 260  set(<vars>[,<callback>])
 261                  - do SNMP SET, multiple <vars> formats accepted.
 262                    the value field in all <vars> formats must be in a canonical
 263                    format (i.e., well known format) to ensure unambiguous
 264                    translation to SNMP MIB data value (see discussion of
 265                    canonical value format <vars> description section),
 266                    returns true on success or undef on error. If <callback>
 267                    supplied method will operate asynchronously
 268  getbulk(<non-repeaters>, <max-repeaters>, <vars> [, <callback>])
 269                  - do an SNMP GETBULK, from the list of Varbinds, the single
 270                    next lexico instance is fetched for the first n Varbinds
 271                    as defined by <non-repeaters>. For remaining Varbinds,
 272                    the m lexico instances are retrieved each of the remaining
 273                    Varbinds, where m is <max-repeaters>.
 274  bulkwalk(<non-repeaters>, <max-repeaters>, <vars> [, <callback>])
 275                  - do an "SNMP bulkwalk" on the given variables.  Bulkwalk is
 276                    implemented by sending an SNMP GETBULK request to fetch the
 277                    variables.  Objects are copied to the return list until the
 278                    sub-tree is exited.  If the request is not completed at the
 279                    end of a packet, a new request is created, starting where
 280                    the previous packet left off.  This implementation is able
 281                    to handle multiple repeated vars, as well as non-repeaters.
 282                    Returns a list (or, in scalar context, a reference to a
 283                    list) of arrays of VarBinds.  The VarBinds consist of the
 284                    responses for each requested variable.  bulkwalk() leaves
 285                    the original Varbinds list intact to facilitate querying
 286                    of multiple devices.
 287
 288 SNMP::TrapSession - supports all applicable fields from SNMP::Session
 289                     (see above)
 290 methods:
 291  new(<fields>)   - Constructs a new SNMP::TrapSession object. The fields are
 292                    passed to the constructor as a hash list
 293                    (e.g., $trapsess = new SNMP::Session(DestHost => 'foo',
 294                    Community => 'private');), returns an object reference
 295                    or undef in case of error.
 296  trap(enterprise, agent, generic, specific, uptime, <vars>)
 297     $sess->trap(enterprise=>'.1.3.6.1.4.1.2021', # or 'ucdavis' [default]
 298                 agent => '127.0.0.1', # or 'localhost',[dflt 1st intf on host]
 299                 generic => specific,  # can be omitted if 'specific' supplied
 300                 specific => 5,        # can be omitted if 'generic' supplied
 301                 uptime => 1234,       # dflt to localhost uptime (0 on win32)
 302                 [[ifIndex, 1, 1],[sysLocation, 0, "here"]]); # optional vars
 303                                                              # always last
 304  or v2 format
 305  trap(oid, uptime, <vars>)
 306     $sess->trap(oid => 'snmpRisingAlarm',
 307                 uptime => 1234,
 308                 [[ifIndex, 1, 1],[sysLocation, 0, "here"]]); # optional vars
 309                                                              # always last
 310
 311
 312 Acceptable variable formats:
 313 <vars> may be one of the following forms:
 314
 315  SNMP::VarList:  - represents an array of MIB objects to get or set,
 316                    implemented as a blessed reference to an array of
 317                    SNMP::Varbinds, (e.g., [<varbind1>, <varbind2>, ...])
 318
 319  SNMP::Varbind:  - represents a single MIB object to get or set, implemented as
 320                    a blessed reference to a 4 element array;
 321                    [<obj>, <iid>, <val>, <type>].
 322                    <obj>  - one of the following forms:
 323                           1) leaf identifier (e.g., 'sysDescr') assumed to be
 324                              unique for practical purposes
 325                           2) fully qualified identifier (e.g.,
 326                              '.iso.org.dod.internet.mgmt.mib-2.system.sysDescr')
 327                           3) fully qualified, dotted-decimal, numeric OID (e.g.,
 328                              '.1.3.6.1.2.1.1.1')
 329                    <iid>  - the dotted-decimal, instance identifier. for
 330                             scalar MIB objects use '0'
 331                    <val>  - the SNMP data value retrieved from or being set
 332                             to the agents MIB. for (f)get(next) operations
 333                             <val> may have a variety of formats as determined by
 334                             session and package settings. However for set
 335                             operations the <val> format must be canonical to
 336                             ensure unambiguous translation. The canonical forms
 337                             are as follows:
 338                             OBJECTID => dotted-decimal (e.g., .1.3.6.1.2.1.1.1)
 339                             OCTETSTR => perl scalar containing octets,
 340                             INTEGER => decimal signed integer (or enum),
 341                             NETADDR => dotted-decimal,
 342                             IPADDR => dotted-decimal,
 343                             COUNTER => decimal unsigned integer,
 344                             COUNTER64  => decimal unsigned integer,
 345                             GAUGE,  => decimal unsigned integer,
 346                             UINTEGER,  => decimal unsigned integer,
 347                             TICKS,  => decimal unsigned integer,
 348                             OPAQUE => perl scalar containing octets,
 349                             NULL,  => perl scalar containing nothing,
 350
 351
 352                    <type> - SNMP data type (see list above), this field is
 353                             populated by 'get' and 'getnext' operations. In
 354                             some cases the programmer needs to populate this
 355                             field when passing to a 'set' operation. this
 356                             field need not be supplied when the attribute
 357                             indicated by <tag> is already described by loaded
 358                             Mib modules. for 'set's, if a numeric OID is used
 359                             and the object is not currently in the loaded Mib,
 360                             the <type> field must be supplied
 361
 362  simple string   - light weight form of <var> used to 'set' or 'get' a
 363                    single attribute without constructing an SNMP::Varbind.
 364                    stored in a perl scalar, has the form '<tag>.<iid>',
 365                    (e.g., 'sysDescr.0'). for 'set' operations the value
 366                    is passed as a second arg. Note: This argument form is
 367                    not updated in get[next] operations as are the other forms.
 368
 369 Acceptable callback formats:
 370 <callback> may be one of the following forms:
 371
 372  without arguments:
 373     \&subname
 374     sub { ... }
 375  or with arguments:
 376     [ \&subname, $arg1, ... ]
 377     [ sub { ... }, $arg1, ... ]
 378     [ "method", $obj, $arg1, ... ]
 379
 380 callback will be called when response is received or timeout
 381 occurs. the last argument passed to callback will be a
 382 SNMP::VarList reference. In case of timeout the last argument
 383 will be undef.
 384
 385 SNMP package variables and functions:
 386
 387  $SNMP::VERSION       - the current version specifier (e.g., 3.1.0)
 388
 389  $SNMP::auto_init_mib - default '1', set to 0 to disable automatic reading
 390                         of the MIB upon session creation. set to non-zero
 391                         to call initMib at session creation which will result
 392                         in MIB loading according to Net-SNMP env. variables
 393                         (see man mib_api)
 394
 395  $SNMP::verbose       - default '0', controls warning/info output of
 396                         SNMP module, 0 => no output, 1 => enables warning/info
 397                         output from SNMP module itself (is also controlled
 398                         by SNMP::debugging - see below)
 399
 400  $SNMP::use_long_names - default '0', set to non-zero to enable the use of
 401                         longer Mib identifiers. see translateObj. will also
 402                         influence the formatting of <tag> in varbinds returned
 403                         from 'getnext' operations. Can be set on a per session
 404                         basis (UseLongNames)
 405
 406  $SNMP::use_sprint_value - default '0', set to non-zero to enable formatting of
 407                         response values using the snmp libraries sprint_value
 408                         function. can also be set on a per session basis (see
 409                         UseSprintValue) Note: returned values may not be
 410                         suitable for 'set' operations
 411
 412  $SNMP::use_enums     - default '0',set non-zero to return values as enums and
 413                         allow sets using enums where appropriate. integer data
 414                         will still be accepted for set operations. can also be
 415                         set on a per session basis (see UseEnums)
 416
 417  $SNMP::use_numeric   - default '0', set to non-zero to return tags as numeric
 418                         OID's, instead of translating them.  Also setting
 419                         $SNMP::use_long_names to non-zero is highly recommended.
 420
 421  $SNMP::save_descriptions - default '0',set non-zero to have mib parser save
 422                         attribute descriptions. must be set prior to mib
 423                         initialization
 424
 425  $SNMP::debugging     - default '0', controls debugging output level
 426                         within SNMP module and libsnmp
 427                         1 => enables 'SNMP::verbose' (see above)
 428                         2 => level 1 plus snmp_set_do_debugging(1),
 429                         3 => level 2 plus snmp_set_dump_packet(1)
 430
 431  $SNMP::dump_packet   - default '0', set [non-]zero to independently set
 432                         snmp_set_dump_packet()
 433
 434  %SNMP::MIB           - a tied hash to access parsed MIB information. After
 435                         the MIB has been loaded this hash allows access to
 436                         to the parsed in MIB meta-data(the structure of the
 437                         MIB (i.e., schema)). The hash returns blessed
 438                         references to SNMP::MIB::NODE objects which represent
 439                         a single MIB attribute. The nodes can be fetched with
 440                         multiple 'key' formats - the leaf name (e.g.,sysDescr)
 441                         or fully/partially qualified name (e.g.,
 442                         system.sysDescr) or fully qualified numeric OID. The
 443                         returned node object supports the following fields:
 444
 445         objectID      - dotted decimal fully qualified OID
 446         label         - leaf textual identifier (e.g., 'sysDescr')
 447         subID         - leaf numeric OID component of objectID (e.g., '1')
 448         moduleID      - textual identifier for module (e.g., 'RFC1213-MIB')
 449         parent        - parent node
 450         children      - array reference of children nodes
 451         nextNode      - next lexico node (BUG!does not return in lexico order)
 452         type          - returns application type (see getType for values)
 453         access        - returns ACCESS (ReadOnly, ReadWrite, WriteOnly,
 454                         NoAccess, Notify, Create)
 455         status        - returns STATUS (Mandatory, Optional, Obsolete,
 456                         Deprecated, Current)
 457         syntax        - returns 'textualConvention' if defined else 'type'
 458         textualConvention - returns TEXTUAL-CONVENTION
 459         units         - returns UNITS
 460         hint          - returns HINT
 461         enums         - returns hash ref {tag => num, ...}
 462         ranges        - returns array ref of hash ref [{low=>num, high=>num}]
 463         defaultValue  - returns default value
 464         description   - returns DESCRIPTION ($SNMP::save_descriptions must
 465                         be set prior to MIB initialization/parsing)
 466
 467
 468  &SNMP::setMib(<file>) - allows dynamic parsing of the mib and explicit
 469                          specification of mib file independent of environment
 470                          variables. called with no args acts like initMib,
 471                          loading MIBs indicated by environment variables (see
 472                          Net-SNMP mib_api docs). passing non-zero second arg
 473                          forces previous mib to be freed and replaced
 474                          (Note: second arg not working since freeing previous
 475                           Mib is more involved than before).
 476
 477  &SNMP::initMib()     - calls library init_mib function if Mib not already
 478                         loaded - does nothing if Mib already loaded. will
 479                         parse directories and load modules according to
 480                         environment variables described in Net-SNMP
 481                         documentations.
 482                         (see man mib_api, MIBDIRS, MIBS, MIBFILE(S), etc.)
 483
 484  &SNMP::addMibDirs(<dir>,...) - calls library add_mibdir for each directory
 485                         supplied. will cause directory(s) to be added to
 486                         internal list and made available for searching in
 487                         subsequent loadModules calls
 488
 489  &SNMP::addMibFiles(<file>,...) - calls library read_mib function. The file(s)
 490                        supplied will be read and all Mib module definitions
 491                        contained therein will be added to internal mib tree
 492                        structure
 493
 494  &SNMP::loadModules(<mod>,...) - calls library read_module function. The
 495                        module(s) supplied will be searched for in the
 496                        current mibdirs and and added to internal mib tree
 497                        structure. Passing special <mod>, 'ALL', will cause
 498                        all known modules to be loaded.
 499
 500  &SNMP::unloadModules(<mod>,...) - *Not Implemented*
 501
 502  &SNMP::translateObj(<var>[,arg]) - will convert a text obj tag to an OID and
 503                             vice-versa. any iid suffix is retained numerically.
 504                             default behaviour when converting a numeric OID
 505                             to text form is to return leaf identifier only
 506                             (e.g.,'sysDescr') but when $SNMP::use_long_names
 507                             is non-zero or a non-zero second arg is supplied
 508                             will return longer textual identifier. If no Mib
 509                             is loaded when called and $SNMP::auto_init_mib is
 510                             enabled then the Mib will be loaded. Will return
 511                             'undef' upon failure.
 512
 513  &SNMP::getType(<var>) - return SNMP data type for given textual identifier
 514                         OBJECTID, OCTETSTR, INTEGER, NETADDR, IPADDR, COUNTER
 515                         GAUGE, TIMETICKS, OPAQUE, or undef
 516
 517  &SNMP::mapEnum(<var>) - converts integer value to enumeration tag defined
 518                          in Mib or converts tag to integer depending on
 519                          input. the function will return the corresponding
 520                          integer value *or* tag for a given MIB attribute
 521                          and value. The function will sense which direction
 522                          to perform the conversion. Various arg formats are
 523                          supported
 524                          $val = SNMP::mapEnum($varbind);
 525                          # where $varbind is SNMP::Varbind or equiv
 526                          # note: $varbind will be updated
 527                          $val = SNMP::mapEnum('ipForwarding', 'forwarding');
 528                          $val = SNMP::mapEnum('ipForwarding', 1);
 529
 530  &SNMP::MainLoop([<timeout>, [<callback>]])
 531                    - to be used with async SNMP::Session
 532                      calls. MainLoop must be called after initial async calls
 533                      so return packets from the agent will not be processed.
 534                      If no args supplied this function enters an infinite loop
 535                      so program must be exited in a callback or externally
 536                      interrupted. If <timeout
 537
 538  &SNMP::finish()
 539                    - This function, when called from an SNMP::MainLoop()
 540                      callback function, will cause the current SNMP::MainLoop
 541                      to return after the callback is completed. finish() can
 542                      be used to terminate an otherwise-infinite MainLoop. A
 543                      new MainLoop() instance can then be started to handle
 544                      further requests.
 545
 546 Exported SNMP utility functions
 547 &snmp_get() - takes args of SNMP::Session::new followed by those of
 548               SNMP::Session::get
 549
 550 &snmp_getnext() - takes args of SNMP::Session::new followed by those of
 551                   SNMP::Session::getnext
 552
 553 &snmp_set() - takes args of SNMP::Session::new followed by those of
 554               SNMP::Session::set
 555
 556 &snmp_trap() - takes args of SNMP::TrapSession::new followed by those of
 557                SNMP::TrapSession::trap
 558
 559 Note: utility functions do not support async operation yet.
 560
 561 Trouble Shooting:
 562
 563 If problems occur there are number areas to look at to narrow down the
 564 possibilities.
 565
 566 The first step should be to test the Net-SNMP installation
 567 independently from the Perl5 SNMP interface.
 568
 569 Try running the apps from the Net-SNMP distribution.
 570
 571 Make sure your agent (snmpd) is running and properly configured with
 572 read-write access for the community you are using.
 573
 574 Ensure that your MIBs are installed and environment variables are set
 575 appropriately (see man mib_api)
 576
 577 Be sure to ensure headers and libraries from old CMU installations are
 578 not being used by mistake (see -NET-SNMP-PATH).
 579
 580 If the problem occurs during compilation/linking check that the snmp
 581 library being linked is actually the Net-SNMP library (there have been
 582 name conflicts with existing snmp libs).
 583
 584 Also check that the header files are correct and up to date.
 585
 586 Sometimes compiling the Net-SNMP library with
 587 'position-independent-code' enabled is required (HPUX specifically).
 588
 589 If you cannot resolve the problem you can post to
 590 comp.lang.perl.modules or email net-snmp-users@lists.sourceforge.net.
 591
 592 please give sufficient information to analyze the problem (OS type,
 593 versions for OS/Perl/net-SNMP/compiler, complete error output, etc.)
 594
 595 Acknowledgments:
 596
 597 Many thanks to all those who supplied patches, suggestions and
 598 feedback.
 599
 600 Wes Hardaker and the net-snmp-coders
 601 Dave Perkins
 602 Marcel Wiget
 603 David Blackburn
 604 John Stofell
 605 Gary Hayward
 606 Claire Harrison
 607 Achim Bohnet
 608 Doug Kingston
 609 Jacques Vidrine
 610 Carl Jacobsen
 611 Wayne Marquette
 612 Scott Schumate
 613 Michael Slifcak
 614 Srivathsan Srinivasagopalan
 615 Bill Fenner
 616 Jef Peeraer
 617 Daniel Hagerty
 618 Karl "Rat" Schilke and Electric Lightwave, Inc.
 619 Perl5 Porters
 620
 621 Apologies to any/all who's patch/feature/request was not mentioned or
 622 included - most likely it was lost when paying work intruded on my
 623 fun. Please try again if you do not see a desired feature. This may
 624 actually turn out to be a decent package with such excellent help and
 625 the fact that I have more time to work on it than in the past.
 626
 627 ------
 628 History:
 629
 630 Bugs fixed and changes in 3.1.0
 631 1) update to ucd-snmp-4.1.0
 632
 633 2) support much of SNMPv3
 634
 635 3) add support for getbulk - Thanks Daniel
 636
 637 4) further regularize error return codes - will return undef on error
 638 for most cases except where values are expected from a varbind (will
 639 themselves be undef)
 640
 641 5) fix bug where session deletion inadvertently occurred with async calls
 642 if calling Session went out of scope - a reference is saved which will
 643 not destruct until after async callback completes
 644
 645 6) pass protocol errors to callbacks
 646
 647 7) added lower level async API so SNMP events can be integrated with
 648 arbitrary event loop (Event.pm?) - thanks Jef
 649
 650 8) Major enhancement to 'make test' - thanks Sri
 651
 652 9) POD documentation - thanks Bill
 653
 654 10) fix OBJECTID translations (unsigned long)
 655
 656 11) display Mib info on 'status' and 'indexes'
 657
 658
 659 Bugs fixed and changes in 1.8.2
 660 1) minor bug fix
 661
 662 Bugs fixed and changes in 1.8.1
 663
 664 1) updated docs
 665
 666 2) fixed #defines from MAX_NAME_LEN to MAX_OID_LEN (mslifcak)
 667
 668 3) reverted __tag2oid to use read_objid rather than get_node. this
 669 gives full name resolution provided by libsnmp and no longer creates
 670 problems on failure since 3.6.2 removes the call to 'exit' in
 671 read_objid
 672
 673 4) fixed Makefile.PL to use win32 'type' vs. 'cat'
 674
 675 Bugs fixed and changes in 1.8
 676
 677 1) added async API (async api should be considered beta -
 678    potential changes are most likely in the event loop integration
 679    area - would like to integrate with Event.pm)
 680
 681 2) added trap generation API (implemented v1 traps only for now)
 682
 683 3) added and exported non-OO utility API (snmp_get, snmp_set, etc.)
 684
 685 4) added $SNMP::debugging to dynamically control libsnmp debugging output
 686
 687 5) added $SNMP::save_descriptions to control libsnmp parsing/saving
 688    of MIB descriptions
 689
 690 6) added $SNMP::dump_packet to control libsnmp packet dumping
 691
 692 7) implemented the SNMP::mapEnum function (thanks to Wayne Marquette)
 693
 694 8) officially added(documented) tied %SNMP::MIB hash to allow access
 695    to parsed MIB meta-data (new support for textualConvention and syntax)
 696
 697 9) fixed bug related to AUTOLOAD recursion
 698
 699 10) fixed bug with SNMP::use_enums so 'set' (and trap) should now accept
 700    enums as input values
 701
 702 11) fixed bug with fget[next] - formatted values are supplied as return
 703     values as well as within args passed
 704
 705 12) fixed Makefile to link with -kstat on solaris
 706
 707 13) fixed bug when handling noSuchName returns for getnext calls with
 708     varbinds w/ no iid supplied (__get_label_iid should not use the
 709     FAIL_ON_NULL_IID flag)
 710
 711 14) fixed bug with uninitialized sprintval_flag
 712
 713 15) fixed bug when no val is passed to SNMP::Session::set - now
 714     will not core or complain about uninitialized data
 715
 716 16) fixed bug with __translate_appl_type in case of NULL or empty string
 717
 718 17) eliminated the use of strtoul for portability - use sscanf(,"%lu",)
 719
 720 18) getType() supports all tag formats now
 721
 722 19) fixed bug when setting values of type OBJID (thanks Scott Schumate)
 723
 724 20) *WARNING* RetryNoSuch in session creation had a bug which prevented
 725     it from being disabled. It now defaults to being disabled - this may
 726     break code *WARNING*
 727
 728
 729 Bugs fixed and changes in 1.7
 730
 731 1) fixed seg fault on use of unknown/unparsed attribute in Varbind or
 732    passed to translateObj
 733
 734 2) fixed truncation of last char of attribute name in translateObj
 735
 736 3) handles variable args to setMib without complaint
 737
 738 4) added SNMP::getType to query data type of a given attribute and
 739    extended Varbind structure to return type wherever possible
 740
 741 5) added RemotePort to SNMP::Session initialization list to allow override
 742    of port 161
 743
 744 6) removed noisy announcement of mib parse success unless verbose is set
 745
 746                *WARNING*  *this may break existing scripts*
 747 7) changed return format for IpAddress and ObjID data types - these are
 748    now always returned as dotted decimal strings as opposed to the
 749    packed binary forms in 1.6
 750                *WARNING*  *this may break existing scripts*
 751
 752 8) Session now sets ErrorInd (e.g., $session->{ErrorInd}) where appropriate
 753
 754 9) Support for ucd-snmp-3.2 (and greater) style of Mib loading
 755
 756 10) Fully qualified attribute names and numeric OIDs are now valid <obj>
 757    definitions.
 758
 759 11) Numeric OIDs can be used even if they have not been parsed in the
 760     current Mib - Mib loading is now optional
 761
 762 12) Support for Win32 perl
 763
 764 13) Updated docs and examples
 765
 766 14) Reworked/extended the test harness to use the perl t/* facility
 767     (thanks to jfs@fluent.com)
 768
 769 15) fixed up error handling to be more consistent with library and more
 770     useful in general. Now returns both library API errors and snmp
 771     protocol error numbers and strings.
 772
 773 16) added per object and per type formatting of returned values - more
 774     control of value formatting with UseEnums and UseSprintValue
 775
 776 Copyright:
 777
 778      Copyright (c) 1995-2000 G. S. Marzot. All rights reserved.
 779      This program is free software; you can redistribute it and/or
 780      modify it under the same terms as Perl itself.
 781
 782      Copyright (c) 2001-2002 Networks Associates Technology, Inc.  All
 783      Rights Reserved.  This program is free software; you can
 784      redistribute it and/or modify it under the same terms as Perl
 785      itself.