1SNMP(3)               User Contributed Perl Documentation              SNMP(3)
2
3
4

NAME

6       SNMP - The Perl5 'SNMP' Extension Module for the Net-SNMP SNMP package.
7

SYNOPSIS

9        use SNMP;
10        ...
11        $sess = new SNMP::Session(DestHost => localhost, Community => public);
12        $val = $sess->get('sysDescr.0');
13        ...
14        $vars = new SNMP::VarList([sysDescr,0], [sysContact,0], [sysLocation,0]);
15        @vals = $sess->get($vars);
16        ...
17        $vb = new SNMP::Varbind();
18        do {
19           $val = $sess->getnext($vb);
20           print "@{$vb}\n";
21        } until ($sess->{ErrorNum});
22        ...
23        $SNMP::save_descriptions = 1;
24        SNMP::initMib(); # assuming mib is not already loaded
25        print "$SNMP::MIB{sysDescr}{description}\n";
26

DESCRIPTION

28       Note: The perl SNMP 5.0 module which comes with net-snmp 5.0 and higher
29       is different than previous versions in a number of ways.  Most
30       importantly, it behaves like a proper net-snmp application and calls
31       init_snmp properly, which means it will read configuration files and
32       use those defaults where appropriate automatically parse MIB files,
33       etc.  This will likely affect your perl applications if you have, for
34       instance, default values set up in your snmp.conf file (as the perl
35       module will now make use of those defaults).  The documentation,
36       however, has sadly not been updated yet (aside from this note), nor is
37       the read_config default usage implementation fully complete.
38
39       The basic operations of the SNMP protocol are provided by this module
40       through an object oriented interface for modularity and ease of use.
41       The primary class is SNMP::Session which encapsulates the persistent
42       aspects of a connection between the management application and the
43       managed agent. Internally the class is implemented as a blessed hash
44       reference. This class supplies 'get', 'getnext', 'set', 'fget', and
45       'fgetnext' method calls. The methods take a variety of input argument
46       formats and support both synchronous and asynchronous operation through
47       a polymorphic API (i.e., method behaviour varies dependent on args
48       passed - see below).
49

SNMP::Session

51       $sess = new SNMP::Session(DestHost => 'host', ...)
52
53       The following arguments may be passed to new as a hash.
54
55   Basic Options
56       DestHost
57           Hostname or IP address of the SNMP agent you want to talk to.
58           Specified in Net-SNMP formatted agent addresses.  These addresses
59           typically look like one of the following:
60
61             localhost
62             tcp:localhost
63             tls:localhost
64             tls:localhost:9876
65             udp6:[::1]:9876
66             unix:/some/path/to/file/socket
67
68           Defaults to 'localhost'.
69
70       Version
71           SNMP version to use.
72
73           The default is taken from library configuration - probably 3 [1, 2
74           (same as 2c), 2c, 3].
75
76       Timeout
77           The number of micro-seconds to wait before resending a request.
78
79           The default is '1000000'
80
81       Retries
82           The number of times to retry a request.
83
84           The default is '5'
85
86       RetryNoSuch
87           If enabled NOSUCH errors in 'get' pdus will be repaired, removing
88           the varbind in error, and resent - undef will be returned for all
89           NOSUCH varbinds, when set to '0' this feature is disabled and the
90           entire get request will fail on any NOSUCH error (applies to v1
91           only)
92
93           The default is '0'.
94
95   SNMPv3/TLS Options
96       OurIdentity
97           Our X.509 identity to use, which should either be a fingerprint or
98           the filename that holds the certificate.
99
100       TheirIdentity
101           The remote server's identity to connect to, specified as either a
102           fingerprint or a file name.  Either this must be specified, or the
103           hostname below along with a trust anchor.
104
105       TheirHostname
106           The remote server's hostname that is expected.  If their
107           certificate was signed by a CA then their hostname presented in the
108           certificate must match this value or the connection fails to be
109           established (to avoid man-in-the-middle attacks).
110
111       TrustCert
112           A trusted certificate to use as trust anchor (like a CA
113           certificate) for verifying a remote server's certificate.  If a CA
114           certificate is used to validate a certificate then the
115           TheirHostname parameter must also be specified to ensure their
116           presented hostname in the certificate matches.
117
118   SNMPv3/USM Options
119       SecName
120           The SNMPv3 security name to use (most for SNMPv3 with USM).
121
122           The default is 'initial'.
123
124       SecLevel
125           The SNMPv3 security level to use [noAuthNoPriv, authNoPriv,
126           authPriv] (v3)
127
128           The default is 'noAuthNoPriv'.
129
130       SecEngineId
131           The SNMPv3 security engineID to use (if the snmpv3 security model
132           needs it; for example USM).
133
134           The default is <none>, security engineID and it will be probed if
135           not supplied (v3)
136
137       ContextEngineId
138           The SNMPv3 context engineID to use.
139
140           The default is the <none> and will be set either to the SecEngineId
141           value if set or discovered or will be discovered in other ways if
142           using TLS (RFC5343 based discovery).
143
144       Context
145           The SNMPv3 context name to use.
146
147           The default is '' (an empty string)
148
149       AuthProto
150           The SNMPv3/USM authentication protocol to use [MD5, SHA].
151
152           The default is 'MD5'.
153
154       AuthPass
155           The SNMPv3/USM authentication passphrase to use.
156
157           default <none>, authentication passphrase
158
159       PrivProto
160           The SNMPv3/USM privacy protocol to use [DES, AES].
161
162           The default is 'DES'.
163
164       PrivPass
165           The SNMPv3/USM privacy passphrase to use.
166
167           default <none>, privacy passphrase (v3)
168
169       AuthMasterKey
170       PrivMasterKey
171       AuthLocalizedKey
172       PrivLocalizedKey
173           Directly specified SNMPv3 USM user keys (used if you want to
174           specify the keys instead of deriving them from a password as
175           above).
176
177   SNMPv1 and SNMPv2c Options
178       Community
179           For SNMPv1 and SNMPv2c, the clear-text community name to use.
180
181           The default is 'public'.
182
183   Other Configuration Options
184       VarFormats
185           default 'undef', used by 'fget[next]', holds an hash reference of
186           output value formatters, (e.g., {<obj> => <sub-ref>, ... }, <obj>
187           must match the <obj> and format used in the get operation. A
188           special <obj>, '*', may be used to apply all <obj>s, the supplied
189           sub is called to translate the value to a new format. The sub is
190           called passing the Varbind as the arg
191
192       TypeFormats
193           default 'undef', used by 'fget[next]', holds an hash reference of
194           output value formatters, (e.g., {<type> => <sub-ref>, ... }, the
195           supplied sub is called to translate the value to a new format,
196           unless a VarFormat mathces first (e.g.,
197           $sess->{TypeFormats}{INTEGER} = \&mapEnum(); although this can be
198           done more efficiently by enabling $SNMP::use_enums or session
199           creation param 'UseEnums')
200
201       UseLongNames
202           defaults to the value of SNMP::use_long_names at time of session
203           creation. set to non-zero to have <tags> for 'getnext' methods
204           generated preferring longer Mib name convention (e.g.,
205           system.sysDescr vs just sysDescr)
206
207       UseSprintValue
208           defaults to the value of SNMP::use_sprint_value at time of session
209           creation. set to non-zero to have return values for 'get' and
210           'getnext' methods formatted with the libraries snprint_value
211           function. This will result in certain data types being returned in
212           non-canonical format Note: values returned with this option set may
213           not be appropriate for 'set' operations (see discussion of value
214           formats in <vars> description section)
215
216       UseEnums
217           defaults to the value of SNMP::use_enums at time of session
218           creation. set to non-zero to have integer return values converted
219           to enumeration identifiers if possible, these values will also be
220           acceptable when supplied to 'set' operations
221
222       UseNumeric
223           defaults to the value of SNMP::use_numeric at time of session
224           creation. set to non-zero to have <tags> for get methods returned
225           as numeric OID's rather than descriptions.  UseLongNames will be
226           set so that the full OID is returned to the caller.
227
228       BestGuess
229           defaults to the value of SNMP::best_guess at time of session
230           creation. this setting controls how <tags> are parsed.  setting to
231           0 causes a regular lookup.  setting to 1 causes a regular
232           expression match (defined as -Ib in snmpcmd) and setting to 2
233           causes a random access lookup (defined as -IR in snmpcmd).
234
235       NonIncreasing
236           defaults to the value of SNMP::non_increasing at time of session
237           creation. this setting controls if a non-increasing OID during
238           bulkwalk will causes an error. setting to 0 causes the default
239           behaviour (which may, in very badly performing agents, result in a
240           never-ending loop).  setting to 1 causes an error (OID not
241           increasing) when this error occur.
242
243       ErrorStr
244           read-only, holds the error message assoc. w/ last request
245
246       ErrorNum
247           read-only, holds the snmp_err or staus of last request
248
249       ErrorInd
250           read-only, holds the snmp_err_index when appropriate
251
252       Private variables:
253
254       DestAddr
255           internal field used to hold the translated DestHost field
256
257       SessPtr
258           internal field used to cache a created session structure
259
260       RemotePort
261           Obsolete.  Please use the DestHost specifier to indicate the
262           hostname and port combination instead of this paramet.
263
264   SNMP::Session methods
265       $sess->update(<fields>)
266           Updates the SNMP::Session object with the values fields passed in
267           as a hash list (similar to new(<fields>)) (WARNING! not fully
268           implemented)
269
270       $sess->get(<vars> [,<callback>])
271           do SNMP GET, multiple <vars> formats accepted.  for syncronous
272           operation <vars> will be updated with value(s) and type(s) and will
273           also return retrieved value(s). If <callback> supplied method will
274           operate asynchronously
275
276       $sess->fget(<vars> [,<callback>])
277           do SNMP GET like 'get' and format the values according the handlers
278           specified in $sess->{VarFormats} and $sess->{TypeFormats}
279
280       $sess->getnext(<vars> [,<callback>])
281           do SNMP GETNEXT, multiple <vars> formats accepted, returns
282           retrieved value(s), <vars> passed as arguments are updated to
283           indicate next lexicographical <obj>,<iid>,<val>, and <type>
284
285           Note: simple string <vars>,(e.g., 'sysDescr.0') form is not
286           updated. If <callback> supplied method will operate asynchronously
287
288       $sess->fgetnext(<vars> [,<callback>])
289           do SNMP GETNEXT like getnext and format the values according the
290           handlers specified in $sess->{VarFormats} and $sess->{TypeFormats}
291
292       $sess->set(<vars> [,<callback>])
293           do SNMP SET, multiple <vars> formats accepted.  the value field in
294           all <vars> formats must be in a canonical format (i.e., well known
295           format) to ensure unambiguous translation to SNMP MIB data value
296           (see discussion of canonical value format <vars> description
297           section), returns snmp_errno. If <callback> supplied method will
298           operate asynchronously
299
300       $sess->getbulk(<non-repeaters>, <max-repeaters>, <vars>)
301           do an SNMP GETBULK, from the list of Varbinds, the single next
302           lexico instance is fetched for the first n Varbinds as defined by
303           <non-repeaters>. For remaining Varbinds, the m lexico instances are
304           retrieved each of the remaining Varbinds, where m is
305           <max-repeaters>.
306
307       $sess->bulkwalk(<non-repeaters>, <max-repeaters>, <vars> [,<callback>])
308           Do a "bulkwalk" of the list of Varbinds.  This is done by sending a
309           GETBULK request (see getbulk() above) for the Varbinds.  For each
310           requested variable, the response is examined to see if the next
311           lexico instance has left the requested sub-tree.  Any further
312           instances returned for this variable are ignored, and the walk for
313           that sub-tree is considered complete.
314
315           If any sub-trees were not completed when the end of the responses
316           is reached, another request is composed, consisting of the
317           remaining variables.  This process is repeated until all sub-trees
318           have been completed, or too many packets have been exchanged (to
319           avoid loops).
320
321           The bulkwalk() method returns an array containing an array of
322           Varbinds, one for each requested variable, in the order of the
323           variable requests.  Upon error, bulkwalk() returns undef and sets
324           $sess->ErrorStr and $sess->ErrorNum.  If a callback is supplied,
325           bulkwalk() returns the SNMP request id, and returns immediately.
326           The callback will be called with the supplied argument list and the
327           returned variables list.
328
329           Note: Because the client must "discover" that the tree is complete
330           by comparing the returned variables with those that were requested,
331           there is a potential "gotcha" when using the max-repeaters value.
332           Consider the following code to print a list of interfaces and byte
333           counts:
334
335               $numInts = $sess->get('ifNumber.0');
336               ($desc, $in, $out) = $sess->bulkwalk(0, $numInts,
337                             [['ifDescr'], ['ifInOctets'], ['ifOutOctets']]);
338
339               for $i (0..($numInts - 1)) {
340                   printf "Interface %4s: %s inOctets, %s outOctets\n",
341                             $$desc[$i]->val, $$in[$i]->val, $$out[$i]->val;
342               }
343
344           This code will produce *two* requests to the agent -- the first to
345           get the interface values, and the second to discover that all the
346           information was in the first packet.  To get around this, use
347           '$numInts + 1' for the max_repeaters value.  This asks the agent to
348           include one additional (unrelated) variable that signals the end of
349           the sub-tree, allowing bulkwalk() to determine that the request is
350           complete.
351
352       $results = $sess->gettable(<TABLE OID>, <OPTIONS>)
353           This will retrieve an entire table of data and return a hash
354           reference to that data.  The returned hash reference will have
355           indexes of the OID suffixes for the index data as the key.  The
356           value for each entry will be another hash containing the data for a
357           given row.  The keys to that hash will be the column names, and the
358           values will be the data.
359
360           Example:
361
362             #!/usr/bin/perl
363
364             use SNMP;
365             use Data::Dumper;
366
367             my $s = new SNMP::Session(DestHost => 'localhost');
368
369             print Dumper($s->gettable('ifTable'));
370
371           On my machine produces:
372
373             $VAR1 = {
374                       '6' => {
375                                'ifMtu' => '1500',
376                                'ifPhysAddress' => 'PV',
377                                # ...
378                                'ifInUnknownProtos' => '0'
379                              },
380                       '4' => {
381                                'ifMtu' => '1480',
382                                'ifPhysAddress' => '',
383                                # ...
384                                'ifInUnknownProtos' => '0'
385                              },
386                       # ...
387                      };
388
389           By default, it will try to do as optimized retrieval as possible.
390           It'll request multiple columns at once, and use GETBULK if
391           possible.  A few options may be specified by passing in an OPTIONS
392           hash containing various parameters:
393
394           noindexes => 1
395               Instructs the code not to parse the indexes and place the
396               results in the second hash.  If you don't need the index data,
397               this will be faster.
398
399           columns => [ colname1, ... ]
400               This specifies which columns to collect.  By default, it will
401               try to collect all the columns defined in the MIB table.
402
403           repeat => COUNT
404               Specifies a GETBULK repeat COUNT.  IE, it will request this
405               many varbinds back per column when using the GETBULK operation.
406               Shortening this will mean smaller packets which may help going
407               through some systems.  By default, this value is calculated and
408               attempts to guess at what will fit all the results into 1000
409               bytes.  This calculation is fairly safe, hopefully, but you can
410               either raise or lower the number using this option if desired.
411               In lossy networks, you want to make sure that the packets don't
412               get fragmented and lowering this value is one way to help that.
413
414           nogetbulk => 1
415               Force the use of GETNEXT rather than GETBULK.  (always true for
416               SNMPv1, as it doesn't have GETBULK anyway).  Some agents are
417               great implementers of GETBULK and this allows you to force the
418               use of GETNEXT operations instead.
419
420           callback => \&subroutine
421           callback => [\&subroutine, optarg1, optarg2, ...]
422               If a callback is specified, gettable will return quickly
423               without returning results.  When the results are finally
424               retrieved the callback subroutine will be called (see the other
425               sections defining callback behaviour and how to make use of
426               SNMP::MainLoop which is required for this to work).  An
427               additional argument of the normal hash result will be added to
428               the callback subroutine arguments.
429
430               Note 1: internally, the gettable function uses it's own
431               callbacks which are passed to getnext/getbulk as appropriate.
432
433               Note 2: callback support is only available in the SNMP module
434               version 5.04 and above.  To test for this in code intending to
435               support both versions prior to 5.04 and 5.04 and up, the
436               following should work:
437
438                 if ($response = $sess->gettable('ifTable', callback => \&my_sub)) {
439                     # got a response, gettable doesn't support callback
440                     my_sub($response);
441                     $no_mainloop = 1;
442                 }
443
444               Deciding on whether to use SNMP::MainLoop is left as an
445               exercise to the reader since it depends on whether your code
446               uses other callbacks as well.
447

SNMP::TrapSession

449       $sess = new SNMP::Session(DestHost => 'host', ...)
450
451       supports all applicable fields from SNMP::Session (see above)
452
453   SNMP::TrapSession methods
454       $sess->trap(enterprise, agent, generic, specific, uptime, <vars>)
455               $sess->trap(enterprise=>'.1.3.6.1.4.1.2021', # or 'ucdavis' [default]
456                           agent => '127.0.0.1', # or 'localhost',[dflt 1st intf on host]
457                           generic => specific,  # can be omitted if 'specific' supplied
458                           specific => 5,        # can be omitted if 'generic' supplied
459                           uptime => 1234,       # dflt to localhost uptime (0 on win32)
460                           [[ifIndex, 1, 1],[sysLocation, 0, "here"]]); # optional vars
461                                                                        # always last
462
463       trap(oid, uptime, <vars>) - v2 format
464               $sess->trap(oid => 'snmpRisingAlarm',
465                           uptime => 1234,
466                           [[ifIndex, 1, 1],[sysLocation, 0, "here"]]); # optional vars
467                                                                        # always last
468

Acceptable variable formats:

470       <vars> may be one of the following forms:
471
472       SNMP::VarList
473           represents an array of MIB objects to get or set, implemented as a
474           blessed reference to an array of SNMP::Varbinds, (e.g.,
475           [<varbind1>, <varbind2>, ...])
476
477       SNMP::Varbind
478           represents a single MIB object to get or set, implemented as a
479           blessed reference to a 4 element array; [<obj>, <iid>, <val>,
480           <type>].
481
482           <obj>
483               one of the following forms:
484
485               1)  leaf identifier (e.g., 'sysDescr') assumed to be unique for
486                   practical purposes
487
488               2)  fully qualified identifier (e.g.,
489                   '.iso.org.dod.internet.mgmt.mib-2.system.sysDescr')
490
491               3)  fully qualified, dotted-decimal, numeric OID (e.g.,
492                   '.1.3.6.1.2.1.1.1')
493
494           <iid>
495               the dotted-decimal, instance identifier. for scalar MIB objects
496               use '0'
497
498           <val>
499               the SNMP data value retrieved from or being set to the agents
500               MIB. for (f)get(next) operations <val> may have a variety of
501               formats as determined by session and package settings. However
502               for set operations the <val> format must be canonical to ensure
503               unambiguous translation. The canonical forms are as follows:
504
505               OBJECTID
506                   dotted-decimal (e.g., .1.3.6.1.2.1.1.1)
507
508               OCTETSTR
509                   perl scalar containing octets
510
511               INTEGER
512                   decimal signed integer (or enum)
513
514               NETADDR
515                   dotted-decimal
516
517               IPADDR
518                   dotted-decimal
519
520               COUNTER
521                   decimal unsigned integer
522
523               COUNTER64
524                   decimal unsigned integer
525
526               GAUGE
527                   decimal unsigned integer
528
529               UINTEGER
530                   decimal unsigned integer
531
532               TICKS
533                   decimal unsigned integer
534
535               OPAQUE
536                   perl scalar containing octets
537
538               NULL
539                   perl scalar containing nothing
540
541           <type>
542               SNMP data type (see list above), this field is populated by
543               'get' and 'getnext' operations. In some cases the programmer
544               needs to populate this field when passing to a 'set' operation.
545               this field need not be supplied when the attribute indicated by
546               <tag> is already described by loaded Mib modules. for 'set's,
547               if a numeric OID is used and the object is not currently in the
548               loaded Mib, the <type> field must be supplied
549
550       simple string
551           light weight form of <var> used to 'set' or 'get' a single
552           attribute without constructing an SNMP::Varbind.  stored in a perl
553           scalar, has the form '<tag>.<iid>', (e.g., 'sysDescr.0'). for 'set'
554           operations the value is passed as a second arg. Note: This argument
555           form is not updated in get[next] operations as are the other forms.
556

Acceptable callback formats

558       <callback> may be one of the following forms:
559
560       without arguments
561           \&subname
562           sub { ... }
563       or with arguments
564           [ \&subname, $arg1, ... ]
565           [ sub { ... }, $arg1, ... ]
566           [ "method", $obj, $arg1, ... ]
567
568       callback will be called when response is received or timeout occurs.
569       the last argument passed to callback will be a SNMP::VarList reference.
570       In case of timeout the last argument will be undef.
571
572       &SNMP::MainLoop([<timeout>, [<callback>]])
573           to be used with async SNMP::Session calls. MainLoop must be called
574           after initial async calls so return packets from the agent will be
575           processed.  If no args supplied this function enters an infinite
576           loop so program must be exited in a callback or externally
577           interrupted. If <timeout(sic)
578
579       &SNMP::finish()
580           This function, when called from an SNMP::MainLoop() callback
581           function, will cause the current SNMP::MainLoop() to return after
582           the callback is completed.  finish() can be used to terminate an
583           otherwise-infinite MainLoop.  A new MainLoop() instance can then be
584           started to handle further requests.
585

SNMP package variables and functions

587       $SNMP::VERSION
588           the current version specifier (e.g., 3.1.0)
589
590       $SNMP::auto_init_mib
591           default '1', set to 0 to disable automatic reading of the MIB upon
592           session creation. set to non-zero to call initMib at session
593           creation which will result in MIB loading according to Net-SNMP
594           env. variables (see man mib_api)
595
596       $SNMP::verbose
597           default '0', controls warning/info output of SNMP module, 0 => no
598           output, 1 => enables warning/info output from SNMP module itself
599           (is also controlled by SNMP::debugging - see below)
600
601       $SNMP::use_long_names
602           default '0', set to non-zero to enable the use of longer Mib
603           identifiers. see translateObj. will also influence the formatting
604           of <tag> in varbinds returned from 'getnext' operations. Can be set
605           on a per session basis (UseLongNames)
606
607       $SNMP::use_sprint_value
608           default '0', set to non-zero to enable formatting of response
609           values using the snmp libraries snprint_value function. can also be
610           set on a per session basis (see UseSprintValue) Note: returned
611           values may not be suitable for 'set' operations
612
613       $SNMP::use_enums
614           default '0',set non-zero to return values as enums and allow sets
615           using enums where appropriate. integer data will still be accepted
616           for set operations. can also be set on a per session basis (see
617           UseEnums)
618
619       $SNMP::use_numeric
620           default to '0',set to non-zero to have <tags> for 'get' methods
621           returned as numeric OID's rather than descriptions.  UseLongNames
622           will be set so that the entire OID will be returned.  Set on a per-
623           session basis (see UseNumeric).
624
625       $SNMP::best_guess
626           default '0'.  This setting controls how <tags> are parsed.  Setting
627           to 0 causes a regular lookup.  Setting to 1 causes a regular
628           expression match (defined as -Ib in snmpcmd) and setting to 2
629           causes a random access lookup (defined as -IR in snmpcmd).  Can
630           also be set on a per session basis (see BestGuess)
631
632       $SNMP::save_descriptions
633           default '0',set non-zero to have mib parser save attribute
634           descriptions. must be set prior to mib initialization
635
636       $SNMP::debugging
637           default '0', controls debugging output level within SNMP module and
638           libsnmp
639
640           1.  enables 'SNMP::verbose' (see above)
641
642           2.  level 1 plus snmp_set_do_debugging(1)
643
644           3.  level 2 plus snmp_set_dump_packet(1)
645
646       $SNMP::dump_packet
647           default '0', set [non-]zero to independently set
648           snmp_set_dump_packet()
649
650       SNMP::register_debug_tokens()
651           Allows to register one or more debug tokens, just like the -D
652           option of snmpd.  Each debug token enables a group of debug
653           statements. An example:
654           SNMP::register_debug_tokens("tdomain,netsnmp_unix");
655

%SNMP::MIB

657       a tied hash to access parsed MIB information. After the MIB has been
658       loaded this hash allows access to to the parsed in MIB meta-data(the
659       structure of the MIB (i.e., schema)). The hash returns blessed
660       references to SNMP::MIB::NODE objects which represent a single MIB
661       attribute. The nodes can be fetched with multiple 'key' formats - the
662       leaf name (e.g.,sysDescr) or fully/partially qualified name (e.g.,
663       system.sysDescr) or fully qualified numeric OID. The returned node
664       object supports the following fields:
665
666       objectID
667           dotted decimal fully qualified OID
668
669       label
670           leaf textual identifier (e.g., 'sysDescr')
671
672       subID
673           leaf numeric OID component of objectID (e.g., '1')
674
675       moduleID
676           textual identifier for module (e.g., 'RFC1213-MIB')
677
678       parent
679           parent node
680
681       children
682           array reference of children nodes
683
684       nextNode
685           next lexico node (BUG!does not return in lexico order)
686
687       type
688           returns application type (see getType for values)
689
690       access
691           returns ACCESS (ReadOnly, ReadWrite, WriteOnly, NoAccess, Notify,
692           Create)
693
694       status
695           returns STATUS (Mandatory, Optional, Obsolete, Deprecated)
696
697       syntax
698           returns 'textualConvention' if defined else 'type'
699
700       textualConvention
701           returns TEXTUAL-CONVENTION
702
703       TCDescription
704           returns the TEXTUAL-CONVENTION's DESCRIPTION field.
705
706       units
707           returns UNITS
708
709       hint
710           returns HINT
711
712       enums
713           returns hash ref {tag => num, ...}
714
715       ranges
716           returns array ref of hash ref [{low => num, high => num}, ...]
717
718       description
719           returns DESCRIPTION ($SNMP::save_descriptions must be set prior to
720           MIB initialization/parsing)
721
722       reference
723           returns the REFERENCE clause
724
725       indexes
726           returns the objects in the INDEX clause
727
728       implied
729           returns true if the last object in the INDEX is IMPLIED
730

MIB Functions

732       &SNMP::setMib(<file>)
733           allows dynamic parsing of the mib and explicit specification of mib
734           file independent of environment variables. called with no args acts
735           like initMib, loading MIBs indicated by environment variables (see
736           Net-SNMP mib_api docs). passing non-zero second arg forces previous
737           mib to be freed and replaced (Note: second arg not working since
738           freeing previous Mib is more involved than before).
739
740       &SNMP::initMib()
741           calls library init_mib function if Mib not already loaded - does
742           nothing if Mib already loaded. will parse directories and load
743           modules according to environment variables described in Net-SNMP
744           documentations.  (see man mib_api, MIBDIRS, MIBS, MIBFILE(S), etc.)
745
746       &SNMP::addMibDirs(<dir>,...)
747           calls library add_mibdir for each directory supplied. will cause
748           directory(s) to be added to internal list and made available for
749           searching in subsequent loadModules calls
750
751       &SNMP::addMibFiles(<file>,...)
752           calls library read_mib function. The file(s) supplied will be read
753           and all Mib module definitions contained therein will be added to
754           internal mib tree structure
755
756       &SNMP::loadModules(<mod>,...)
757           calls library read_module function. The module(s) supplied will be
758           searched for in the current mibdirs and and added to internal mib
759           tree structure. Passing special <mod>, 'ALL', will cause all known
760           modules to be loaded.
761
762       &SNMP::unloadModules(<mod>,...)
763           *Not Implemented*
764
765       &SNMP::translateObj(<var>[,arg,[arg]])
766           will convert a text obj tag to an OID and vice-versa.  Any iid
767           suffix is retained numerically.  Default behaviour when converting
768           a numeric OID to text form is to return leaf identifier only
769           (e.g.,'sysDescr') but when $SNMP::use_long_names is non-zero or a
770           non-zero second arg is supplied it will return a longer textual
771           identifier.  An optional third argument of non-zero will cause the
772           module name to be prepended to the text name (e.g.
773           'SNMPv2-MIB::sysDescr').  When converting a text obj, the
774           $SNMP::best_guess option is used.  If no Mib is loaded when called
775           and $SNMP::auto_init_mib is enabled then the Mib will be loaded.
776           Will return 'undef' upon failure.
777
778       &SNMP::getType(<var>)
779           return SNMP data type for given textual identifier OBJECTID,
780           OCTETSTR, INTEGER, NETADDR, IPADDR, COUNTER GAUGE, TIMETICKS,
781           OPAQUE, or undef
782
783       &SNMP::mapEnum(<var>)
784           converts integer value to enumertion tag defined in Mib or converts
785           tag to integer depending on input. the function will return the
786           corresponding integer value *or* tag for a given MIB attribute and
787           value. The function will sense which direction to perform the
788           conversion. Various arg formats are supported
789
790           $val = SNMP::mapEnum($varbind);
791               where $varbind is SNMP::Varbind or equiv.  note: $varbind will
792               be updated
793
794           $val = SNMP::mapEnum('ipForwarding', 'forwarding');
795           $val = SNMP::mapEnum('ipForwarding', 1);
796

Exported SNMP utility functions

798       Note: utility functions do not support async operation yet.
799
800       &snmp_get()
801           takes args of SNMP::Session::new followed by those of
802           SNMP::Session::get
803
804       &snmp_getnext()
805           takes args of SNMP::Session::new followed by those of
806           SNMP::Session::getnext
807
808       &snmp_set()
809           takes args of SNMP::Session::new followed by those of
810           SNMP::Session::set
811
812       &snmp_trap()
813           takes args of SNMP::TrapSession::new followed by those of
814           SNMP::TrapSession::trap
815

Trouble Shooting

817       If problems occur there are number areas to look at to narrow down the
818       possibilities.
819
820       The first step should be to test the Net-SNMP installation
821       independently from the Perl5 SNMP interface.
822
823       Try running the apps from the Net-SNMP distribution.
824
825       Make sure your agent (snmpd) is running and properly configured with
826       read-write access for the community you are using.
827
828       Ensure that your MIBs are installed and enviroment variables are set
829       appropriately (see man mib_api)
830
831       Be sure to remove old net-snmp installations and ensure headers and
832       libraries from old CMU installations are not being used by mistake.
833
834       If the problem occurs during compilation/linking check that the snmp
835       library being linked is actually the Net-SNMP library (there have been
836       name conflicts with existing snmp libs).
837
838       Also check that the header files are correct and up to date.
839
840       Sometimes compiling the Net-SNMP library with
841       'position-independent-code' enabled is required (HPUX specifically).
842
843       If you cannot resolve the problem you can post to
844       comp.lang.perl.modules or
845       net-snmp-users@net-snmp-users@lists.sourceforge.net
846
847       please give sufficient information to analyze the problem (OS type,
848       versions for OS/Perl/Net-SNMP/compiler, complete error output, etc.)
849

Acknowledgements

851       Many thanks to all those who supplied patches, suggestions and
852       feedback.
853
854        Joe Marzot (the original author)
855        Wes Hardaker and the net-snmp-coders
856        Dave Perkins
857        Marcel Wiget
858        David Blackburn
859        John Stofell
860        Gary Hayward
861        Claire Harrison
862        Achim Bohnet
863        Doug Kingston
864        Jacques Vidrine
865        Carl Jacobsen
866        Wayne Marquette
867        Scott Schumate
868        Michael Slifcak
869        Srivathsan Srinivasagopalan
870        Bill Fenner
871        Jef Peeraer
872        Daniel Hagerty
873        Karl "Rat" Schilke and Electric Lightwave, Inc.
874        Perl5 Porters
875        Alex Burger
876
877       Apologies to any/all who's patch/feature/request was not mentioned or
878       included - most likely it was lost when paying work intruded on my fun.
879       Please try again if you do not see a desired feature. This may actually
880       turn out to be a decent package with such excellent help and the fact
881       that I have more time to work on it than in the past.
882

AUTHOR

884       bugs, comments, questions to net-snmp-users@lists.sourceforge.net
885
887            Copyright (c) 1995-2000 G. S. Marzot. All rights reserved.
888            This program is free software; you can redistribute it and/or
889            modify it under the same terms as Perl itself.
890
891            Copyright (c) 2001-2002 Networks Associates Technology, Inc.  All
892            Rights Reserved.  This program is free software; you can
893            redistribute it and/or modify it under the same terms as Perl
894            itself.
895
896
897
898perl v5.30.2                      2020-04-09                           SNMP(3)
Impressum