| 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. |