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

SNMP::TrapSession

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

Acceptable variable formats:

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

Acceptable callback formats

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

SNMP package variables and functions

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

%SNMP::MIB

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

MIB Functions

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

Exported SNMP utility functions

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

Trouble Shooting

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

Acknowledgements

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

AUTHOR

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