readme

snmp的源代码,已经在我的ubuntu下编译通过

        textualConvention - returns TEXTUAL-CONVENTION
        units         - returns UNITS
        hint          - returns HINT
        enums         - returns hash ref {tag => num, ...}
        ranges        - returns array ref of hash ref [{low=>num, high=>num}]
        defaultValue  - returns default value
        description   - returns DESCRIPTION ($SNMP::save_descriptions must
                        be set prior to MIB initialization/parsing)


 &SNMP::setMib(<file>) - allows dynamic parsing of the mib and explicit
                         specification of mib file independent of environment
                         variables. called with no args acts like initMib,
                         loading MIBs indicated by environment variables (see
                         Net-SNMP mib_api docs). passing non-zero second arg
                         forces previous mib to be freed and replaced
                         (Note: second arg not working since freeing previous
                          Mib is more involved than before).

 &SNMP::initMib()     - calls library init_mib function if Mib not already
                        loaded - does nothing if Mib already loaded. will
                        parse directories and load modules according to
                        environment variables described in Net-SNMP
                        documentations.
                        (see man mib_api, MIBDIRS, MIBS, MIBFILE(S), etc.)

 &SNMP::addMibDirs(<dir>,...) - calls library add_mibdir for each directory
                        supplied. will cause directory(s) to be added to
                        internal list and made available for searching in
                        subsequent loadModules calls

 &SNMP::addMibFiles(<file>,...) - calls library read_mib function. The file(s)
                       supplied will be read and all Mib module definitions
                       contained therein will be added to internal mib tree
                       structure

 &SNMP::loadModules(<mod>,...) - calls library read_module function. The
                       module(s) supplied will be searched for in the
                       current mibdirs and and added to internal mib tree
                       structure. Passing special <mod>, 'ALL', will cause
                       all known modules to be loaded.

 &SNMP::unloadModules(<mod>,...) - *Not Implemented*

 &SNMP::translateObj(<var>[,arg,[arg]]) - will convert a text obj tag to an 
                       OID and vice-versa. Any iid suffix is retained 
                       numerically.  Default behaviour when converting a 
                       numeric OID to text form is to return leaf identifier 
                       only (e.g.,'sysDescr') but when $SNMP::use_long_names 
                       is non-zero or a non-zero second arg is supplied it 
                       will return a longer textual identifier.  An optional 
                       third argument of non-zero will cause the module name 
                       to be prepended to the text name (e.g. 
                       'SNMPv2-MIB::sysDescr').  When converting a text obj, 
                       the $SNMP::best_guess option is used.  If no Mib is 
                       loaded when called and $SNMP::auto_init_mib is enabled 
                       then the Mib will be loaded. Will return 'undef' upon 
                       failure.

 &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 enumeration tag defined
                         in Mib or converts tag to integer depending on
                         input. the function will return the corresponding
                         integer value *or* tag for a given MIB attribute
                         and value. The function will sense which direction
                         to perform the conversion. Various arg formats are
                         supported
                         $val = SNMP::mapEnum($varbind);
                         # where $varbind is SNMP::Varbind or equiv
                         # note: $varbind will be updated
                         $val = SNMP::mapEnum('ipForwarding', 'forwarding');
                         $val = SNMP::mapEnum('ipForwarding', 1);

 &SNMP::MainLoop([<timeout>, [<callback>]])
                   - to be used with async SNMP::Session
                     calls. MainLoop must be called after initial async calls
                     so return packets from the agent will not be processed.
                     If no args supplied this function enters an infinite loop
                     so program must be exited in a callback or externally
                     interrupted. If <timeout

 &SNMP::finish()
		   - This function, when called from an SNMP::MainLoop()
		     callback function, will cause the current SNMP::MainLoop
		     to return after the callback is completed. finish() can
		     be used to terminate an otherwise-infinite MainLoop. A
		     new MainLoop() instance can then be started to handle
		     further requests.

Exported SNMP utility functions
&snmp_get() - takes args of SNMP::Session::new followed by those of
              SNMP::Session::get

&snmp_getnext() - takes args of SNMP::Session::new followed by those of
                  SNMP::Session::getnext

&snmp_set() - takes args of SNMP::Session::new followed by those of
              SNMP::Session::set

&snmp_trap() - takes args of SNMP::TrapSession::new followed by those of
               SNMP::TrapSession::trap

Note: utility functions do not support async operation yet.

Trouble Shooting:

If problems occur there are number areas to look at to narrow down the
possibilities.

The first step should be to test the Net-SNMP installation
independently from the Perl5 SNMP interface.

Try running the apps from the Net-SNMP distribution.

Make sure your agent (snmpd) is running and properly configured with
read-write access for the community you are using.

Ensure that your MIBs are installed and environment variables are set
appropriately (see man mib_api)

Be sure to ensure headers and libraries from old CMU installations are
not being used by mistake (see -NET-SNMP-PATH).

If the problem occurs during compilation/linking check that the snmp
library being linked is actually the Net-SNMP library (there have been
name conflicts with existing snmp libs).

Also check that the header files are correct and up to date.

Sometimes compiling the Net-SNMP library with
'position-independent-code' enabled is required (HPUX specifically).

If you cannot resolve the problem you can post to
comp.lang.perl.modules or email [e-mail].

please give sufficient information to analyze the problem (OS type,
versions for OS/Perl/net-SNMP/compiler, complete error output, etc.)

Acknowledgments:

Many thanks to all those who supplied patches, suggestions and
feedback.

Joe Marzot (the original author)
Wes Hardaker and the net-snmp-coders
Dave Perkins
Marcel Wiget
David Blackburn
John Stofell
Gary Hayward
Claire Harrison
Achim Bohnet
Doug Kingston
Jacques Vidrine
Carl Jacobsen
Wayne Marquette
Scott Schumate
Michael Slifcak
Srivathsan Srinivasagopalan
Bill Fenner
Jef Peeraer
Daniel Hagerty
Karl "Rat" Schilke and Electric Lightwave, Inc.
Perl5 Porters
Alex Burger

Apologies to any/all who's patch/feature/request was not mentioned or
included - most likely it was lost when paying work intruded on my
fun. Please try again if you do not see a desired feature. This may
actually turn out to be a decent package with such excellent help and
the fact that I have more time to work on it than in the past.

------
History:

Bugs fixed and changes in 3.1.0
1) update to ucd-snmp-4.1.0

2) support much of SNMPv3

3) add support for getbulk - Thanks Daniel

4) further regularize error return codes - will return undef on error
for most cases except where values are expected from a varbind (will
themselves be undef)

5) fix bug where session deletion inadvertently occurred with async calls
if calling Session went out of scope - a reference is saved which will
not destruct until after async callback completes

6) pass protocol errors to callbacks

7) added lower level async API so SNMP events can be integrated with
arbitrary event loop (Event.pm?) - thanks Jef

8) Major enhancement to 'make test' - thanks Sri

9) POD documentation - thanks Bill

10) fix OBJECTID translations (unsigned long)

11) display Mib info on 'status' and 'indexes'


Bugs fixed and changes in 1.8.2
1) minor bug fix

Bugs fixed and changes in 1.8.1

1) updated docs

2) fixed #defines from MAX_NAME_LEN to MAX_OID_LEN (mslifcak)

3) reverted __tag2oid to use read_objid rather than get_node. this
gives full name resolution provided by libsnmp and no longer creates
problems on failure since 3.6.2 removes the call to 'exit' in
read_objid

4) fixed Makefile.PL to use win32 'type' vs. 'cat'

Bugs fixed and changes in 1.8

1) added async API (async api should be considered beta -
   potential changes are most likely in the event loop integration
   area - would like to integrate with Event.pm)

2) added trap generation API (implemented v1 traps only for now)

3) added and exported non-OO utility API (snmp_get, snmp_set, etc.)

4) added $SNMP::debugging to dynamically control libsnmp debugging output

5) added $SNMP::save_descriptions to control libsnmp parsing/saving
   of MIB descriptions

6) added $SNMP::dump_packet to control libsnmp packet dumping

7) implemented the SNMP::mapEnum function (thanks to Wayne Marquette)

8) officially added(documented) tied %SNMP::MIB hash to allow access
   to parsed MIB meta-data (new support for textualConvention and syntax)

9) fixed bug related to AUTOLOAD recursion

10) fixed bug with SNMP::use_enums so 'set' (and trap) should now accept
   enums as input values

11) fixed bug with fget[next] - formatted values are supplied as return
    values as well as within args passed

12) fixed Makefile to link with -kstat on solaris

13) fixed bug when handling noSuchName returns for getnext calls with
    varbinds w/ no iid supplied (__get_label_iid should not use the
    FAIL_ON_NULL_IID flag)

14) fixed bug with uninitialized sprintval_flag

15) fixed bug when no val is passed to SNMP::Session::set - now
    will not core or complain about uninitialized data

16) fixed bug with __translate_appl_type in case of NULL or empty string

17) eliminated the use of strtoul for portability - use sscanf(,"%lu",)

18) getType() supports all tag formats now

19) fixed bug when setting values of type OBJID (thanks Scott Schumate)

20) *WARNING* RetryNoSuch in session creation had a bug which prevented
    it from being disabled. It now defaults to being disabled - this may
    break code *WARNING*


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 translateObj

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 return type wherever possible

5) added RemotePort to SNMP::Session initialization 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) Support for ucd-snmp-3.2 (and greater) style of Mib loading

10) Fully qualified attribute names and numeric OIDs are now valid <obj>
   definitions.

11) Numeric OIDs can be used even if they have not been parsed in the
    current Mib - Mib loading is now optional

12) Support for Win32 perl

13) Updated docs and examples

14) Reworked/extended the test harness to use the perl t/* facility
    (thanks to [e-mail])

15) fixed up error handling to be more consistent with library and more
    useful in general. Now returns both library API errors and snmp
    protocol error numbers and strings.

16) added per object and per type formatting of returned values - more
    control of value formatting with UseEnums and UseSprintValue

Copyright:

     Copyright (c) 1995-2000 G. S. Marzot. All rights reserved.
     This program is free software; you can redistribute it and/or
     modify it under the same terms as Perl itself.

     Copyright (c) 2001-2002 Networks Associates Technology, Inc.  All
     Rights Reserved.  This program is free software; you can
     redistribute it and/or modify it under the same terms as Perl
     itself.