Debian Codegraph @

perl/SNMP/README

raw
1 The Perl5 'SNMP' Extension Module
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. Ideally, do not try
21 to build it independently, as it won't work as well. Instead of
22 running "perl Makefile.PL" in this directory, run it in the
23 net-snmp/perl directory instead which has a global makefile used to
24 build all the sub-modules in their proper order.
25 ******************************NOTE NOTE NOTE**************************
26
27 Note: The perl SNMP 5.x module 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://www.net-snmp.org/
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
53 http://www.net-snmp.org/download.html
54
55 (Note: The perl SNMP distribution obtained this way has the highest
56 chance of being up to date and compatible with the Net-SNMP version
57 with which it is bundled.)
58
59 A seperately bundled package of the SNMP module can be obtained from CPAN.
60
61 (Note: In previous releases this module was compatible with the CMU
62 SNMP library. Starting with Perl5/SNMP-1.7 this module will *only*
63 work with the Net-SNMP (aka ucd-snmp) library due to dependence on new
64 features)
65
66 Contact:
67
68 The following mailing list should be consider the primary support
69 mechanism for this module:
70
71 net-snmp-users ATATAT lists.sourceforge.net mail list
72
73 (see http://www.net-snmp.org/lists/users/ to subscribe)
74
75 Supported Platforms:
76
77 Linux 1.2.x, 2.x
78 Solaris 2.x (see the net-snmp README.solaris file!)
79 MS Windows
80 Many other UNIX variants
81 Let us know what it *doesn't* work on, as it should on most systems
82
83 Release Notes:
84
85 SNMP module version 5.x is being developed against NET-SNMP-5.0
86 see http://www.net-snmp.org/ for details.
87
88 Compatibility with earlier or later versions of Net-SNMP or
89 UCD-SNMP is not guaranteed due to the dynamic nature of open
90 software development :). The perl module will check the version of
91 net-snmp you have installed for a match and warn you if they don't
92 match exactly.
93
94 KNOWN BUGS:
95
96 The make test suite likely won't work perfectly. It relies on
97 running an existing Net-SNMP SNMP agent and various configuration
98 which makes it very hard to ensure exact compatibility. If "make
99 test" fails on you we suggest you install the module anyway.
100
101 (none?) (HA!)
102
103 **********************************************************************
104 * the rest of this file is likely out of date ************************
105 * the rest of this file is likely out of date ************************
106 * the rest of this file is likely out of date ************************
107 **********************************************************************
108
109 Installation:
110
111 Build and install the Net-SNMP package - see Net-SNMP README and
112 INSTALL docs.
113
114 (Note: To ensure that any previous Net-SNMP, ucd-snmp or cmu snmp
115 installation's library or headers are not used by mistake, use the
116 -NET-SNMP-CONFIG directive to explicitly set the path to the
117 net-snmp-config command that knows about the net-snmp installation you
118 want to use.)
119
120 NOTE: build all the perl modules at once using the Makefile.PL in the
121 net-snmp/perl directory rather than the one in this directory.
122
123 Unix:
124
125 cd net-snmp/perl
126 perl Makefile.PL [-NET-SNMP-CONFIG="sh ../../net-snmp-config"] [-NET-SNMP-IN-SOURCE=true]
127 make
128 make test
129 make install
130
131 FreeBSD:
132
133 cd net-snmp/perl
134 perl Makefile.PL -NET-SNMP-CONFIG="sh ../../net-snmp-config" -NET-SNMP-IN-SOURCE=true
135 make
136 make test
137 make install
138
139 Win32 (MSVC++)
140
141 This section covers installation of the Perl modules for Microsoft Visual
142 C++ 6.0 and Microsoft Microsoft Development Environment 2003/2003
143 (MSVC 7.0/7.1). See the following sections for Cygwin and MinGW.
144
145 Perl binaries build with MSVC++ are required.
146
147 Note: The source code should *not* be in a folder that contains a space. For
148 example, compiling in your 'My Documents' or your Desktop (usually
149 c:\Documents and Settings\xxxx\Desktop) is not supported.
150
151 Automatic building / testing with nmakeperl.bat:
152
153 1. Ensure a static version of Net-SNMP has been compiled and
154 installed. Also ensure the DLL version of snmplib has been
155 compiled and installed. The Perl modules will not function
156 correctly without a shared snmplib library or DLL.
157
158 2. Install the regex win32 package (gnu_regex.exe). It is available from
159
160 http://people.delphiforums.com/gjc/gnu_regex.html
161
162 a. Copy regex.h to the include folder of MSVC++
163
164 Example: "C:\Program Files\Microsoft Visual Studio .NET 2003\
165 Vc7\include\regex.h"
166
167 b. Copy gnu_regex.lib to the lib folder of MSVC++
168
169 Example: "C:\Program Files\Microsoft Visual Studio .NET 2003\
170 Vc7\lib\gnu_regex.lib"
171
172 c. Copy gnu_regex.dll to your %windir%\system32 folder
173
174 Example: "C:\winnt\system32\gnu_regex.dll"
175
176 3. Set the environment PATH to locate "nmake", "cl", and "link".
177 Visual Studio installs a VCVARS32.BAT batch file for this purpose.
178
179 4. Using a command prompt window, cd to the source base directory.
180
181 5. Invoke win32\nmakeperl.bat to build the Perl SNMP modules. If you see
182 errors, review the "nmake.out" file first. If no errors there,
183 then the modules built correctly, but the tests did not rigourously
184 prove the mettle of the modules. Review "nmaketest.out". If the
185 first three sections mostly pass, the modules are well formed.
186
187 NOTE: If the tests fail, there may be a perl application left hanging.
188 Use the Task Manager to remove any stale perl or snmp*.exe process.
189
190 6. The final step is to invoke "nmake install". If no errors occurred,
191 then the SNMP modules are available for use by your Perl programs.
192
193
194 Manual building / testing:
195
196 1. Ensure a static version of Net-SNMP has been compiled and
197 installed. Also ensure the DLL version of snmplib has been
198 compiled and installed. The Perl modules will not function
199 correctly without a shared snmplib library or DLL.
200
201 2. Install the regex win32 package (gnu_regex.exe). It is available from
202
203 http://people.delphiforums.com/gjc/gnu_regex.html
204
205 a. Copy regex.h to the include folder of MSVC++
206
207 Example: "C:\Program Files\Microsoft Visual Studio .NET 2003\
208 Vc7\include\regex.h"
209
210 b. Copy gnu_regex.lib to the lib folder of MSVC++
211
212 Example: "C:\Program Files\Microsoft Visual Studio .NET 2003\
213 Vc7\lib\gnu_regex.lib"
214
215 c. Copy gnu_regex.dll to your %windir%\system32 folder
216
217 Example: "C:\winnt\system32\gnu_regex.dll"
218
219 3. Set the environment PATH to locate "nmake", "cl", and "link".
220 Visual Studio installs a VCVARS32.BAT for this purpose.
221
222 4. Using a command prompt window, cd to the perl directory.
223
224 5. Type:
225
226 perl Makefile.PL CAPI=TRUE -NET-SNMP-IN-SOURCE=TRUE
227
228 to compile against the RELEASE version of Net-SNMP, or:
229
230 perl Makefile.PL CAPI=TRUE -NET-SNMP-IN-SOURCE=TRUE -NET-SNMP-DEBUG=TRUE
231
232 to compile against the DEBUG version of Net-SNMP.
233
234 nmake
235 nmake test
236 nmake install
237
238 Note: The --NET-SNMP-IN-SOURCE=TRUE causes the Makefile to use the
239 library files from the installed Net-SNMP directory.
240 To specify the installed Net-SNMP directory, use:
241
242 perl Makefile.PL CAPI=TRUE -NET-SNMP-PATH="c:\usr"
243
244 Note: -NET-SNMP-DEBUG has no effect while compiling against an
245 installed copy of Net-SNMP.
246
247 Note: To include OpenSSL, see the net-snmp/README.win32 to compile
248 libsnmp with libeay32 and see that libeay.lib is in the
249 lib folder, or in the lib folder of the installed
250 Net-SNMP if using -NET-SNMP-PATH. For example,
251 c:\usr\lib
252
253 Note: 'nmake test' will automatically start and stop the
254 agent(snmpd) and trap receiver (snmptrapd) while testing the
255 SNMP module.
256
257
258 Win32 (Cygwin):
259
260 cd net-snmp\perl
261 perl Makefile.PL -NET-SNMP-IN-SOURCE=true
262 make
263 make test
264 make install
265
266 If you get an error saying your system can't compile, you are
267 probably missing the regex library. Install regex from
268 http://mirrors.sunsite.dk/cygwin/release/regex/regex-4.4-2-src.tar.bz2
269
270 Note: The source code should *not* be in a folder that contains a space. For
271 example, compiling in your 'My Documents' or your Desktop (usually
272 c:\Documents and Settings\xxxx\Desktop) is not supported.
273
274
275 Win32 (MinGW):
276
277 Note: As of February 25th, 2004, the MinGW build of Net-SNMP does not
278 compile the DLL version of libsnmp. Some modules will not function
279 correctly without a shared library / DLL. The OID module does not
280 appear to work at all without the DLL, and some parts of other
281 modules may not work. For example, sharing configurations between
282 modules which is why the SNMP conf test fails.
283
284 Note: The source code should *not* be in a folder that contains a space. For
285 example, compiling in your 'My Documents' or your Desktop (usually
286 c:\Documents and Settings\xxxx\Desktop) is not supported.
287
288
289 Operational Description:
290 ------------------------
291
292 The basic operations of the SNMP protocol are provided by this module
293 through an object oriented interface for modularity and ease of use.
294 The primary class is SNMP::Session which encapsulates the persistent
295 aspects of a connection between the management application and the
296 managed agent. Internally the class is implemented as a blessed hash
297 reference. This class supplies 'get', 'getnext', 'set', 'fget', and
298 'fgetnext' and other method calls. The methods take a variety of input
299 argument formats and support both synchronous and asynchronous
300 operation through a polymorphic API (i.e., method behaviour varies
301 dependent on args passed - see below).
302
303 A description of the fields which can be specified when an
304 SNMP::Session object is created follows:
305
306 SNMP::Session
307 public:
308 DestHost - default 'localhost', hostname or ip addr of SNMP agent
309 Community - default 'public', SNMP community string (used for both R/W)
310 Version - default '1', [2 (same as 2c), 2c, 3]
311 RemotePort - default '161', allow remote UDP port to be overridden
312 Timeout - default '1000000', micro-seconds before retry
313 Retries - default '5', retries before failure
314 RetryNoSuch - default '0', if enabled NOSUCH errors in 'get' pdus will
315 be repaired, removing the varbind in error, and resent -
316 undef will be returned for all NOSUCH varbinds, when set
317 to '0' this feature is disabled and the entire get request
318 will fail on any NOSUCH error (applies to v1 only)
319 SecName - default 'initial', security name (v3)
320 SecLevel - default 'noAuthNoPriv', security level [noAuthNoPriv,
321 authNoPriv, authPriv] (v3)
322 SecEngineId - default <none>, security engineID, will be probed if not
323 supplied (v3)
324 ContextEngineId - default <SecEngineId>, context engineID, will be
325 probed if not supplied (v3)
326 Context - default '', context name (v3)
327 AuthProto - default 'MD5', authentication protocol [MD5, SHA] (v3)
328 AuthPass - default <none>, authentication passphrase
329 PrivProto - default 'DES', privacy protocol [DES] (v3)
330 PrivPass - default <none>, privacy passphrase (v3)
331 VarFormats - default 'undef', used by 'fget[next]', holds an hash
332 reference of output value formatters, (e.g., {<obj> =>
333 <sub-ref>, ... }, <obj> must match the <obj> and format
334 used in the get operation. A special <obj>, '*', may be
335 used to apply all <obj>s, the supplied sub is called to
336 translate the value to a new format. The sub is called
337 passing the Varbind as the arg
338 TypeFormats - default 'undef', used by 'fget[next]', holds an hash
339 reference of output value formatters, (e.g., {<type> =>
340 <sub-ref>, ... }, the supplied sub is called to translate
341 the value to a new format, unless a VarFormat mathces first
342 (e.g., $session->{TypeFormats}{INTEGER} = \&mapEnum();
343 although this can be done more efficiently by enabling
344 $SNMP::use_enums or session creation param 'UseEnums')
345 UseLongNames - defaults to the value of SNMP::use_long_names at time
346 of session creation. set to non-zero to have <tags>
347 for 'getnext' methods generated preferring longer Mib name
348 convention (e.g., system.sysDescr vs just sysDescr)
349 UseSprintValue - defaults to the value of SNMP::use_sprint_value at time
350 of session creation. set to non-zero to have return values
351 for 'get' and 'getnext' methods formatted with the libraries
352 sprint_value function. This will result in certain data types
353 being returned in non-canonical format Note: values returned
354 with this option set may not be appropriate for 'set' operations
355 (see discussion of value formats in <vars> description section)
356 UseEnums - defaults to the value of SNMP::use_enums at time of session
357 creation. set to non-zero to have integer return values
358 converted to enumeration identifiers if possible, these values
359 will also be acceptable when supplied to 'set' operations
360 UseNumeric - defaults to the value of SNMP::use_numeric at time of session
361 creation. set to non-zero to have <tags> returned by the 'get'
362 methods untranslated (i.e. dotted-decimal). Setting the
363 UseLongNames value for the session is highly recommended.
364 BestGuess - defaults to the value of SNMP::best_guess at time of session
365 creation. this setting controls how <tags> are parsed. setting
366 to 0 causes a regular lookup. setting to 1 causes a regular
367 expression match (defined as -Ib in snmpcmd) and setting to 2
368 causes a random access lookup (defined as -IR in snmpcmd).
369 ErrorStr - read-only, holds the error message assoc. w/ last request
370 ErrorNum - read-only, holds the snmp_err or status of last request
371 ErrorInd - read-only, holds the snmp_err_index when appropriate
372
373 private:
374 DestAddr - internal field used to hold the translated DestHost field
375 SessPtr - internal field used to cache a created session structure
376
377 methods:
378 new(<fields>) - Constructs a new SNMP::Session object. The fields are
379 passed to the constructor as a hash list
380 (e.g., $session = new SNMP::Session(DestHost => 'foo',
381 Community => 'private');), returns an object reference
382 or undef in case of error.
383 update(<fields>)- Updates the SNMP::Session object with the values fields
384 passed in as a hash list (similar to new(<fields>))
385 (WARNING! not fully implemented)
386 get(<vars>[,<callback>])
387 - do SNMP GET, multiple <vars> formats accepted.
388 for synchronous operation <vars> will be updated
389 with value(s) and type(s) and will also return
390 retrieved value(s). If <callback> supplied method
391 will operate asynchronously
392 fget(<vars>[,<callback>])
393 - do SNMP GET like 'get' and format the values according
394 the handlers specified in $sess->{VarFormats} and
395 $sess->{TypeFormats}. Async *not supported*
396 getnext(<vars>[,<callback>])
397 - do SNMP GETNEXT, multiple <vars> formats accepted,
398 returns retrieved value(s), <vars> passed as arguments are
399 updated to indicate next lexicographical <obj>,<iid>,<val>,
400 and <type> Note: simple string <vars>,(e.g., 'sysDescr.0')
401 form is not updated. If <callback> supplied method
402 will operate asynchronously
403 fgetnext(<vars>[,<callback>])
404 - do SNMP GETNEXT like getnext and format the values according
405 the handlers specified in $sess->{VarFormats} and
406 $sess->{TypeFormats}. Async *not supported*
407 set(<vars>[,<callback>])
408 - do SNMP SET, multiple <vars> formats accepted.
409 the value field in all <vars> formats must be in a canonical
410 format (i.e., well known format) to ensure unambiguous
411 translation to SNMP MIB data value (see discussion of
412 canonical value format <vars> description section),
413 returns true on success or undef on error. If <callback>
414 supplied method will operate asynchronously
415 getbulk(<non-repeaters>, <max-repeaters>, <vars> [, <callback>])
416 - do an SNMP GETBULK, from the list of Varbinds, the single
417 next lexico instance is fetched for the first n Varbinds
418 as defined by <non-repeaters>. For remaining Varbinds,
419 the m lexico instances are retrieved each of the remaining
420 Varbinds, where m is <max-repeaters>.
421 bulkwalk(<non-repeaters>, <max-repeaters>, <vars> [, <callback>])
422 - do an "SNMP bulkwalk" on the given variables. Bulkwalk is
423 implemented by sending an SNMP GETBULK request to fetch the
424 variables. Objects are copied to the return list until the
425 sub-tree is exited. If the request is not completed at the
426 end of a packet, a new request is created, starting where
427 the previous packet left off. This implementation is able
428 to handle multiple repeated vars, as well as non-repeaters.
429 Returns a list (or, in scalar context, a reference to a
430 list) of arrays of VarBinds. The VarBinds consist of the
431 responses for each requested variable. bulkwalk() leaves
432 the original Varbinds list intact to facilitate querying
433 of multiple devices.
434
435 SNMP::TrapSession - supports all applicable fields from SNMP::Session
436 (see above)
437 methods:
438 new(<fields>) - Constructs a new SNMP::TrapSession object. The fields are
439 passed to the constructor as a hash list
440 (e.g., $trapsess = new SNMP::Session(DestHost => 'foo',
441 Community => 'private');), returns an object reference
442 or undef in case of error.
443 trap(enterprise, agent, generic, specific, uptime, <vars>)
444 $sess->trap(enterprise=>'.1.3.6.1.4.1.2021', # or 'ucdavis' [default]
445 agent => '127.0.0.1', # or 'localhost',[dflt 1st intf on host]
446 generic => specific, # can be omitted if 'specific' supplied
447 specific => 5, # can be omitted if 'generic' supplied
448 uptime => 1234, # dflt to localhost uptime (0 on win32)
449 [[ifIndex, 1, 1],[sysLocation, 0, "here"]]); # optional vars
450 # always last
451 or v2 format
452 trap(oid, uptime, <vars>)
453 $sess->trap(oid => 'snmpRisingAlarm',
454 uptime => 1234,
455 [[ifIndex, 1, 1],[sysLocation, 0, "here"]]); # optional vars
456 # always last
457
458
459 Acceptable variable formats:
460 <vars> may be one of the following forms:
461
462 SNMP::VarList: - represents an array of MIB objects to get or set,
463 implemented as a blessed reference to an array of
464 SNMP::Varbinds, (e.g., [<varbind1>, <varbind2>, ...])
465
466 SNMP::Varbind: - represents a single MIB object to get or set, implemented as
467 a blessed reference to a 4 element array;
468 [<obj>, <iid>, <val>, <type>].
469 <obj> - one of the following forms:
470 1) leaf identifier (e.g., 'sysDescr') assumed to be
471 unique for practical purposes
472 2) fully qualified identifier (e.g.,
473 '.iso.org.dod.internet.mgmt.mib-2.system.sysDescr')
474 3) fully qualified, dotted-decimal, numeric OID (e.g.,
475 '.1.3.6.1.2.1.1.1')
476 <iid> - the dotted-decimal, instance identifier. for
477 scalar MIB objects use '0'
478 <val> - the SNMP data value retrieved from or being set
479 to the agents MIB. for (f)get(next) operations
480 <val> may have a variety of formats as determined by
481 session and package settings. However for set
482 operations the <val> format must be canonical to
483 ensure unambiguous translation. The canonical forms
484 are as follows:
485 OBJECTID => dotted-decimal (e.g., .1.3.6.1.2.1.1.1)
486 OCTETSTR => perl scalar containing octets,
487 INTEGER => decimal signed integer (or enum),
488 NETADDR => dotted-decimal,
489 IPADDR => dotted-decimal,
490 COUNTER => decimal unsigned integer,
491 COUNTER64 => decimal unsigned integer,
492 GAUGE, => decimal unsigned integer,
493 UINTEGER, => decimal unsigned integer,
494 TICKS, => decimal unsigned integer,
495 OPAQUE => perl scalar containing octets,
496 NULL, => perl scalar containing nothing,
497
498
499 <type> - SNMP data type (see list above), this field is
500 populated by 'get' and 'getnext' operations. In
501 some cases the programmer needs to populate this
502 field when passing to a 'set' operation. this
503 field need not be supplied when the attribute
504 indicated by <tag> is already described by loaded
505 Mib modules. for 'set's, if a numeric OID is used
506 and the object is not currently in the loaded Mib,
507 the <type> field must be supplied
508
509 simple string - light weight form of <var> used to 'set' or 'get' a
510 single attribute without constructing an SNMP::Varbind.
511 stored in a perl scalar, has the form '<tag>.<iid>',
512 (e.g., 'sysDescr.0'). for 'set' operations the value
513 is passed as a second arg. Note: This argument form is
514 not updated in get[next] operations as are the other forms.
515
516 Acceptable callback formats:
517 <callback> may be one of the following forms:
518
519 without arguments:
520 \&subname
521 sub { ... }
522 or with arguments:
523 [ \&subname, $arg1, ... ]
524 [ sub { ... }, $arg1, ... ]
525 [ "method", $obj, $arg1, ... ]
526
527 callback will be called when response is received or timeout
528 occurs. the last argument passed to callback will be a
529 SNMP::VarList reference. In case of timeout the last argument
530 will be undef.
531
532 SNMP package variables and functions:
533
534 $SNMP::VERSION - the current version specifier (e.g., 3.1.0)
535
536 $SNMP::auto_init_mib - default '1', set to 0 to disable automatic reading
537 of the MIB upon session creation. set to non-zero
538 to call initMib at session creation which will result
539 in MIB loading according to Net-SNMP env. variables
540 (see man mib_api)
541
542 $SNMP::verbose - default '0', controls warning/info output of
543 SNMP module, 0 => no output, 1 => enables warning/info
544 output from SNMP module itself (is also controlled
545 by SNMP::debugging - see below)
546
547 $SNMP::use_long_names - default '0', set to non-zero to enable the use of
548 longer Mib identifiers. see translateObj. will also
549 influence the formatting of <tag> in varbinds returned
550 from 'getnext' operations. Can be set on a per session
551 basis (UseLongNames)
552
553 $SNMP::use_sprint_value - default '0', set to non-zero to enable formatting of
554 response values using the snmp libraries sprint_value
555 function. can also be set on a per session basis (see
556 UseSprintValue) Note: returned values may not be
557 suitable for 'set' operations
558
559 $SNMP::use_enums - default '0',set non-zero to return values as enums and
560 allow sets using enums where appropriate. integer data
561 will still be accepted for set operations. can also be
562 set on a per session basis (see UseEnums)
563
564 $SNMP::use_numeric - default '0', set to non-zero to return tags as numeric
565 OID's, instead of translating them. Also setting
566 $SNMP::use_long_names to non-zero is highly recommended.
567
568 $SNMP::best_guess - default '0'. this setting controls how <tags> are
569 parsed. setting to 0 causes a regular lookup. setting
570 to 1 causes a regular expression match (defined as -Ib
571 in snmpcmd) and setting to 2 causes a random access
572 lookup (defined as -IR in snmpcmd). can also be set
573 on a per session basis (see BestGuess)
574
575 $SNMP::save_descriptions - default '0',set non-zero to have mib parser save
576 attribute descriptions. must be set prior to mib
577 initialization
578
579 $SNMP::debugging - default '0', controls debugging output level
580 within SNMP module and libsnmp
581 1 => enables 'SNMP::verbose' (see above)
582 2 => level 1 plus snmp_set_do_debugging(1),
583 3 => level 2 plus snmp_set_dump_packet(1)
584
585 $SNMP::dump_packet - default '0', set [non-]zero to independently set
586 snmp_set_dump_packet()
587
588 %SNMP::MIB - a tied hash to access parsed MIB information. After
589 the MIB has been loaded this hash allows access to
590 to the parsed in MIB meta-data(the structure of the
591 MIB (i.e., schema)). The hash returns blessed
592 references to SNMP::MIB::NODE objects which represent
593 a single MIB attribute. The nodes can be fetched with
594 multiple 'key' formats - the leaf name (e.g.,sysDescr)
595 or fully/partially qualified name (e.g.,
596 system.sysDescr) or fully qualified numeric OID. The
597 returned node object supports the following fields:
598
599 objectID - dotted decimal fully qualified OID
600 label - leaf textual identifier (e.g., 'sysDescr')
601 subID - leaf numeric OID component of objectID (e.g., '1')
602 moduleID - textual identifier for module (e.g., 'RFC1213-MIB')
603 parent - parent node
604 children - array reference of children nodes
605 nextNode - next lexico node (BUG!does not return in lexico order)
606 type - returns application type (see getType for values)
607 access - returns ACCESS (ReadOnly, ReadWrite, WriteOnly,
608 NoAccess, Notify, Create)
609 status - returns STATUS (Mandatory, Optional, Obsolete,
610 Deprecated, Current)
611 syntax - returns 'textualConvention' if defined else 'type'
612 textualConvention - returns TEXTUAL-CONVENTION
613 units - returns UNITS
614 hint - returns HINT
615 enums - returns hash ref {tag => num, ...}
616 ranges - returns array ref of hash ref [{low=>num, high=>num}]
617 defaultValue - returns default value
618 description - returns DESCRIPTION ($SNMP::save_descriptions must
619 be set prior to MIB initialization/parsing)
620
621
622 &SNMP::setMib(<file>) - allows dynamic parsing of the mib and explicit
623 specification of mib file independent of environment
624 variables. called with no args acts like initMib,
625 loading MIBs indicated by environment variables (see
626 Net-SNMP mib_api docs). passing non-zero second arg
627 forces previous mib to be freed and replaced
628 (Note: second arg not working since freeing previous
629 Mib is more involved than before).
630
631 &SNMP::initMib() - calls library netsnmp_init_mib function if MIB not
632 already loaded - does nothing if MIB already loaded.
633 Will parse directories and load modules according to
634 environment variables described in Net-SNMP
635 documentations.
636 (see man mib_api, MIBDIRS, MIBS, MIBFILE(S), etc.)
637
638 &SNMP::addMibDirs(<dir>,...) - calls library add_mibdir for each directory
639 supplied. will cause directory(s) to be added to
640 internal list and made available for searching in
641 subsequent loadModules calls
642
643 &SNMP::addMibFiles(<file>,...) - calls library read_mib function. The file(s)
644 supplied will be read and all Mib module definitions
645 contained therein will be added to internal mib tree
646 structure
647
648 &SNMP::loadModules(<mod>,...) - calls library read_module function. The
649 module(s) supplied will be searched for in the
650 current mibdirs and and added to internal mib tree
651 structure. Passing special <mod>, 'ALL', will cause
652 all known modules to be loaded.
653
654 &SNMP::unloadModules(<mod>,...) - *Not Implemented*
655
656 &SNMP::translateObj(<var>[,arg,[arg]]) - will convert a text obj tag to an
657 OID and vice-versa. Any iid suffix is retained
658 numerically. Default behaviour when converting a
659 numeric OID to text form is to return leaf identifier
660 only (e.g.,'sysDescr') but when $SNMP::use_long_names
661 is non-zero or a non-zero second arg is supplied it
662 will return a longer textual identifier. An optional
663 third argument of non-zero will cause the module name
664 to be prepended to the text name (e.g.
665 'SNMPv2-MIB::sysDescr'). When converting a text obj,
666 the $SNMP::best_guess option is used. If no Mib is
667 loaded when called and $SNMP::auto_init_mib is enabled
668 then the Mib will be loaded. Will return 'undef' upon
669 failure.
670
671 &SNMP::getType(<var>) - return SNMP data type for given textual identifier
672 OBJECTID, OCTETSTR, INTEGER, NETADDR, IPADDR, COUNTER
673 GAUGE, TIMETICKS, OPAQUE, or undef
674
675 &SNMP::mapEnum(<var>) - converts integer value to enumeration tag defined
676 in Mib or converts tag to integer depending on
677 input. the function will return the corresponding
678 integer value *or* tag for a given MIB attribute
679 and value. The function will sense which direction
680 to perform the conversion. Various arg formats are
681 supported
682 $val = SNMP::mapEnum($varbind);
683 # where $varbind is SNMP::Varbind or equiv
684 # note: $varbind will be updated
685 $val = SNMP::mapEnum('ipForwarding', 'forwarding');
686 $val = SNMP::mapEnum('ipForwarding', 1);
687
688 &SNMP::MainLoop([<timeout>, [<callback>]])
689 - to be used with async SNMP::Session
690 calls. MainLoop must be called after initial async calls
691 so return packets from the agent will not be processed.
692 If no args supplied this function enters an infinite loop
693 so program must be exited in a callback or externally
694 interrupted. If <timeout
695
696 &SNMP::finish()
697 - This function, when called from an SNMP::MainLoop()
698 callback function, will cause the current SNMP::MainLoop
699 to return after the callback is completed. finish() can
700 be used to terminate an otherwise-infinite MainLoop. A
701 new MainLoop() instance can then be started to handle
702 further requests.
703
704 Exported SNMP utility functions
705 &snmp_get() - takes args of SNMP::Session::new followed by those of
706 SNMP::Session::get
707
708 &snmp_getnext() - takes args of SNMP::Session::new followed by those of
709 SNMP::Session::getnext
710
711 &snmp_set() - takes args of SNMP::Session::new followed by those of
712 SNMP::Session::set
713
714 &snmp_trap() - takes args of SNMP::TrapSession::new followed by those of
715 SNMP::TrapSession::trap
716
717 Note: utility functions do not support async operation yet.
718
719 Trouble Shooting:
720
721 If problems occur there are number areas to look at to narrow down the
722 possibilities.
723
724 The first step should be to test the Net-SNMP installation
725 independently from the Perl5 SNMP interface.
726
727 Try running the apps from the Net-SNMP distribution.
728
729 Make sure your agent (snmpd) is running and properly configured with
730 read-write access for the community you are using.
731
732 Ensure that your MIBs are installed and environment variables are set
733 appropriately (see man mib_api)
734
735 Be sure to ensure headers and libraries from old CMU installations are
736 not being used by mistake (see -NET-SNMP-PATH).
737
738 If the problem occurs during compilation/linking check that the snmp
739 library being linked is actually the Net-SNMP library (there have been
740 name conflicts with existing snmp libs).
741
742 Also check that the header files are correct and up to date.
743
744 Sometimes compiling the Net-SNMP library with
745 'position-independent-code' enabled is required (HPUX specifically).
746
747 If you cannot resolve the problem you can post to
748 comp.lang.perl.modules or email [email protected].
749
750 please give sufficient information to analyze the problem (OS type,
751 versions for OS/Perl/net-SNMP/compiler, complete error output, etc.)
752
753 Acknowledgments:
754
755 Many thanks to all those who supplied patches, suggestions and
756 feedback.
757
758 Joe Marzot (the original author)
759 Wes Hardaker and the net-snmp-coders
760 Dave Perkins
761 Marcel Wiget
762 David Blackburn
763 John Stofell
764 Gary Hayward
765 Claire Harrison
766 Achim Bohnet
767 Doug Kingston
768 Jacques Vidrine
769 Carl Jacobsen
770 Wayne Marquette
771 Scott Schumate
772 Michael Slifcak
773 Srivathsan Srinivasagopalan
774 Bill Fenner
775 Jef Peeraer
776 Daniel Hagerty
777 Karl "Rat" Schilke and Electric Lightwave, Inc.
778 Perl5 Porters
779 Alex Burger
780
781 Apologies to any/all who's patch/feature/request was not mentioned or
782 included - most likely it was lost when paying work intruded on my
783 fun. Please try again if you do not see a desired feature. This may
784 actually turn out to be a decent package with such excellent help and
785 the fact that I have more time to work on it than in the past.
786
787 Copyright:
788
789 [See the COPYING file for the copyright license of Net-SNMP]
790
791 Copyright (c) 1995-2000 G. S. Marzot. All rights reserved.
792 This program is free software; you can redistribute it and/or
793 modify it under the same terms as Perl itself.
794
795 Copyright (c) 2001-2002 Networks Associates Technology, Inc. All
796 Rights Reserved. This program is free software; you can
797 redistribute it and/or modify it under the same terms as Perl
798 itself.
799
800 Copyright (c) 2003-2006 SPARTA, Inc. All Rights Reserved. This
801 program is free software; you can redistribute it and/or modify
802 it under the same terms as Perl itself.