/ 
Net-SNMP-2.00
River stage two • 41 direct dependents • 45 total dependents
/ Net::SNMP

NAME

Net::SNMP - Simple Network Management Protocol

SYNOPSIS

use Net::SNMP;

DESCRIPTION

The module Net::SNMP implements an object oriented interface to the Simple Network Management Protocol. Perl applications can use the module to retrieve or update information on a remote host using the SNMP protocol. Net::SNMP is implemented completely in Perl, requires no compiling, and uses only standard Perl modules. Both SNMPv1 and SNMPv2c (Community-Based SNMPv2) are supported by the module. The Net::SNMP module assumes that the user has a basic understanding of the Simple Network Management Protocol and related network management concepts.

METHODS

When named arguments are used with methods, two different styles are supported. All examples use the IO:: style:

$object->method(Argument => $value);

However, the dashed-option style is also allowed:

$object->method(-argument => $value);

session() - create a new Net::SNMP object

($session, $error) = Net::SNMP->session(
                                   [Hostname  => $hostname,]
                                   [Community => $community,]
                                   [Port      => $port,]
                                   [Version   => $version,]
                                   [Timeout   => $seconds,]
                                   [Retries   => $count,]
                                   [MTU       => $octets,]
                                   [Translate => $translate,]
                                   [VerifyIP  => $verifyip,]
                                   [Debug     => $debug]
                                );

This is the constructor for Net::SNMP objects. In scalar context, a reference to a new Net::SNMP object is returned if the creation of the object is successful. In list context, a reference to a new Net::SNMP object and an error message string is returned.

If an error occurs, the object reference returns the undefined value. The error string may be used when this method is used in list context to determine the cause of the error.

The Hostname, Community, and Port arguments are basic properties of a Net::SNMP object and cannot be changed after the object is created. All other arguments have methods that allow their values to be modified after the Net::SNMP object has been created. See the methods corresponding to these named arguments for their valid ranges and default values.

All arguments are optional and will take default values in the absence of a corresponding named argument.

  • The default value for the remote Hostname is "localhost". The hostname can either be a network hostname or the dotted IP address of the host.

  • The default value for the SNMP Community name is "public".

  • The default value for the destination UDP Port number is 161. This is the port on which hosts using default values expect to receive all SNMP messages except for traps. Port number 162 is the default port used by hosts expecting to receive SNMP traps.

close() - close the UDP socket and clear all buffers and errors

$session->close;

This method closes the UDP socket and clears the errors, hash pointers, and buffers associated with the object.

get_request() - send a SNMP get-request to the remote agent

$response = $session->get_request(@oids);

This method performs a SNMP get-request query to gather data from the remote agent on the host associated with the Net::SNMP object. The method takes a list of OBJECT IDENTIFIERs in dotted notation. Each OBJECT IDENTIFER is placed into a single SNMP GetRequest-PDU in the same order that it held in the original list.

Upon success, a reference to a hash is returned which contains the results of the query. The undefined value is returned when a failure has occurred. The error() method can be used to determine the cause of the failure.

The returned reference points to a hash constructed from the VarBindList contained in the SNMP GetResponse-PDU. The hash is created using the ObjectName and the ObjectSyntax pairs in the VarBindList. The keys of the hash consist of the OBJECT IDENTIFIERs in dotted notation corresponding to each ObjectName in the list. If any of the passed OBJECT IDENTIFIERs began with a leading dot, all of the OBJECT IDENTIFIER hash keys will be prefixed with a leading dot. The value of each hash entry is set to be the value of the associated ObjectSyntax. The hash reference can also be retrieved using the var_bind_list() method.

get_next_request() - send a SNMP get-next-request to the remote agent

$response = $session->get_next_request(@oids);

This method performs a SNMP get-next-request query to gather data from the remote agent on the host associated with the Net::SNMP object. The method takes a list of OBJECT IDENTIFIERs in dotted notation. Each OBJECT IDENTIFER is placed into a single SNMP GetNextRequest-PDU in the same order that it held in the original list.

Upon success, a reference to a hash is returned which contains the results of the query. The undefined value is returned when a failure has occurred. The error() method can be used to determine the cause of the failure.

The returned reference points to a hash constructed from the VarBindList contained in the SNMP GetResponse-PDU. The hash is created using the ObjectName and the ObjectSyntax pairs in the VarBindList. The keys of the hash consist of the OBJECT IDENTIFIERs in dotted notation corresponding to each ObjectName in the list. If any of the passed OBJECT IDENTIFIERs began with a leading dot, all of the OBJECT IDENTIFIER hash keys will be prefixed with a leading dot. The value of each hash entry is set to be the value of the associated ObjectSyntax. The hash reference can also be retrieved using the var_bind_list() method.

set_request() - send a SNMP set-request to the remote agent

$response = $session->set_request(
                         $oid, $type, $value 
                         [, $oid, $type, $value]
                      );

This method is used to modify data on the remote agent that is associated with the Net::SNMP object using a SNMP set-request. The method takes a list of values consisting of groups of an OBJECT IDENTIFIER, an object type, and the actual value to be set. The OBJECT IDENTIFIERs in each trio are to be in dotted notation. The object type is a byte corresponding to the ASN.1 type of value that is to be set. Each of the supported types have been defined and are exported by the package by default (see "EXPORTS").

Upon success, a reference to a hash is returned which contains the results of the query. The undefined value is returned when a failure has occurred. The error() method can be used to determine the cause of the failure.

The returned reference points to a hash constructed from the VarBindList contained in the SNMP GetResponse-PDU. The hash is created using the ObjectName and the ObjectSyntax pairs in the VarBindList. The keys of the hash consist of the OBJECT IDENTIFIERs in dotted notation corresponding to each ObjectName in the list. If any of the passed OBJECT IDENTIFIERs began with a leading dot, all of the OBJECT IDENTIFIER hash keys will be prefixed with a leading dot. The value of each hash entry is set to be the value of the associated ObjectSyntax. The hash reference can also be retrieved using the var_bind_list() method.

trap() - send an SNMP trap to the remote manager

$octets = $session->trap(
                       [Enterprise   => $oid,]
                       [AgentAddr    => $ipaddress,]
                       [GenericTrap  => $generic,]
                       [SpecificTrap => $specific,]
                       [TimeStamp    => $timeticks,]
                       [VarBindList  => \@oids,]
                    );

This method sends an SNMP trap to the remote manager associated with the Net::SNMP object. All arguments are optional and will be given the following defaults in the absence of a corresponding named argument:

  • The default value for the trap Enterprise is "1.3.6.1.4.1", which corresponds to "iso.org.dod.internet.private.enterprises". The enterprise value is expected to be an OBJECT IDENTIFER in dotted notation.

  • The default value for the trap AgentAddr is the local IP address from the host on which the script is running. The agent-addr is expected to be an IpAddress in dotted notation.

  • The default value for the GenericTrap type is 6 which corresponds to "enterpriseSpecific". The generic-trap types are defined and can be exported upon request (see "EXPORTS").

  • The default value for the SpecificTrap type is 0. No pre-defined values are available for specific-trap types.

  • The default value for the trap TimeStamp is the "uptime" of the script. The "uptime" of the script is the number of hundredths of seconds that have elapsed since the script started running. The time-stamp is expected to be a TimeTicks number in hundredths of seconds.

  • The default value for the trap VarBindList is an empty array reference. The variable-bindings are expected to be in an array format consisting of groups of an OBJECT IDENTIFIER, an object type, and the actual value of the object. This is identical to the list expected by the set_request() method. The OBJECT IDENTIFIERs in each trio are to be in dotted notation. The object type is a byte corresponding to the ASN.1 type for the value. Each of the supported types have been defined and are exported by default (see "EXPORTS").

Upon success, the number of bytes transmitted is returned. The undefined value is returned when a failure has occurred. The error() method can be used to determine the cause of the failure. Since there are no acknowledgements for Trap-PDUs, there is no way to determine if the remote host actually received the trap.

get_bulk_request() - send a SNMPv2 get-bulk-request to the remote agent

$response = $session->get_bulk_request(
                         [NonRepeaters   => $nonrepeaters,]
                         [MaxRepetitions => $maxrepetitions,]
                         [VarBindList    => \@oids,]
                      );

This method performs a SNMP get-bulk-request query to gather data from the remote agent on the host associated with the Net::SNMP object. All arguments are optional and will be given the following defaults in the absence of a corresponding named argument:

  • The default value for the get-bulk-request NonRepeaters is 0. The non-repeaters value specifies the number of variables in the variable-bindings list for which a single successor is to be returned.

  • The default value for the get-bulk-request MaxRepetitions is 0. The max-repetitions value specifies the number of successors to be returned for the remaining variables in the variable-bindings list.

  • The default value for the get-bulk-request VarBindList is an empty array reference. The variable-bindings are expected to be in an array format consisting of groups of an OBJECT IDENTIFIER, an object type, and the actual value of the object. This is identical to the list expected by the set_request() method. The OBJECT IDENTIFIERs in each trio are to be in dotted notation. The object type is a byte corresponding to the ASN.1 type for the value that is identified. Each of the supported types have been defined and are exported by default (see "EXPORTS").

Upon success, a reference to a hash is returned which contains the results of the query. The undefined value is returned when a failure has occurred. The error() method can be used to determine the cause of the failure.

The returned reference points to a hash constructed from the VarBindList contained in the SNMP GetResponse-PDU. The hash is created using the ObjectName and the ObjectSyntax pairs in the VarBindList. The keys of the hash consist of the OBJECT IDENTIFIERs in dotted notation corresponding to each ObjectName in the list. If any of the passed OBJECT IDENTIFIERs began with a leading dot, all of the OBJECT IDENTIFIER hash keys will be prefixed with a leading dot. The value of each hash entry is set to be the value of the associated ObjectSyntax. The hash reference can also be retrieved using the var_bind_list() method.

NOTE: This method can only be used when the version of the object is set to SNMPv2c.

inform_request() - send a SNMPv2 inform-request to the remote manager

$response = $session->inform_request(
                         $oid, $type, $value 
                         [, $oid, $type, $value]
                      );

This method is used to provide management information to the remote manager associated with the Net::SNMP object using a SNMPv2 inform-request. The method takes a list of values consisting of groups of an OBJECT IDENTIFIER, an object type, and the actual value to be set. The OBJECT IDENTIFIERs in each trio are to be in dotted notation. The object type is a byte corresponding to the ASN.1 type of value that is identified. Each of the supported types have been defined and are exported by the package by default (see "EXPORTS").

The first two variable-bindings fields in the inform-request are specified by SNMPv2 and should be:

  • sysUpTime.0 - ['1.3.6.1.2.1.1.3.0', TIMETICKS, $timeticks]

  • snmpTrapOID.0 - ['1.3.6.1.6.3.1.1.4.1.0', OBJECT_IDENTIFIER, $oid]

Upon success, a reference to a hash is returned which contains the results of the query. The undefined value is returned when a failure has occurred. The error() method can be used to determine the cause of the failure.

The returned reference points to a hash constructed from the VarBindList contained in the SNMP GetResponse-PDU. The hash is created using the ObjectName and the ObjectSyntax pairs in the VarBindList. The keys of the hash consist of the OBJECT IDENTIFIERs in dotted notation corresponding to each ObjectName in the list. If any of the passed OBJECT IDENTIFIERs began with a leading dot, all of the OBJECT IDENTIFIER hash keys will be prefixed with a leading dot. The value of each hash entry is set to be the value of the associated ObjectSyntax. The hash reference can also be retrieved using the var_bind_list() method.

NOTE: This method can only be used when the version of the object is set to SNMPv2c.

snmpv2_trap() - send a SNMPv2 snmpV2-trap to the remote manager

$octets = $session->snmpv2_trap(
                       $oid, $type, $value 
                       [, $oid, $type, $value]
                    );

This method sends an SNMPv2 snmpV2-trap to the remote manager associated with the Net::SNMP object. The method takes a list of values consisting of groups of an OBJECT IDENTIFIER, an object type, and the actual value to be set. The OBJECT IDENTIFIERs in each trio are to be in dotted notation. The object type is a byte corresponding to the ASN.1 type of value that is being identified. Each of the supported types have been defined and are exported by the package by default (see "EXPORTS").

The first two variable-bindings fields in the snmpV2-trap are specified by SNMPv2 and should be:

  • sysUpTime.0 - ['1.3.6.1.2.1.1.3.0', TIMETICKS, $timeticks]

  • snmpTrapOID.0 - ['1.3.6.1.6.3.1.1.4.1.0', OBJECT_IDENTIFIER, $oid]

Upon success, the number of bytes transmitted is returned. The undefined value is returned when a failure has occurred. The error() method can be used to determine the cause of the failure. Since there are no acknowledgements for SNMPv2-Trap-PDUs, there is no way to determine if the remote host actually received the snmpV2-trap.

NOTE: This method can only be used when the version of the object is set to SNMPv2c.

get_table() - retrieve a table from the remote agent

$response = $session->get_table($oid);

This method performs repeated SNMP get-next-request queries to gather data from the remote agent on the host associated with the Net::SNMP object. The method takes a single OBJECT IDENTIFIER. This OBJECT IDENTIFIER is used as the base object for the SNMP get-next-requests. Repeated SNMP get-next-requests are issued until the OBJECT IDENTIFER in the response is no longer a subtree of the base OBJECT IDENTIFIER.

Upon success, a reference to a hash is returned which contains the results of the query. The undefined value is returned when a failure has occurred. The error() method can be used to determine the cause of the failure.

The returned reference points to a hash constructed from the VarBindList contained in the SNMP GetResponse-PDU. The hash is created using the ObjectName and the ObjectSyntax pairs in the VarBindList. The keys of the hash consist of the OBJECT IDENTIFIERs in dotted notation corresponding to each ObjectName in the list. If any of the passed OBJECT IDENTIFIERs began with a leading dot, all of the OBJECT IDENTIFIER hash keys will be prefixed with a leading dot. The value of each hash entry is set to be the value of the associated ObjectSyntax. The hash reference can also be retrieved using the var_bind_list() method.

WARNING: Results from this method can become very large if the base OBJECT IDENTIFIER is close the root of the SNMP MIB tree.

version() - set or get the SNMP version for the object

This method is used to set or get the current SNMP version associated with the Net::SNMP object. The module supports SNMP version-1 (SNMPv1) and SNMP version-2c (SNMPv2c). The default version used by the module is SNMP version-1.

The method accepts the digit '1' or the string 'SNMPv1' for SNMP version-1 and the digit '2', or the strings '2c', 'SNMPv2', or 'SNMPv2' for SNMP version-2c. The undefined value is returned upon an error and the error() method may be used to determine the cause.

The method returns the current value for the SNMP version. The returned value is the corresponding version number defined by the RFCs for the protocol version field (i.e. SNMPv1 == 0 and SNMPv2c == 1).

error() - get the current error message from the object

$error_message = $session->error;

This method returns a text string explaining the reason for the last error. A null string is returned if no error has occurred.

error_status() - get the current SNMP error-status from the object

$error_status = $session->error_status;

This method returns the numeric value of the error-status contained in the last SNMP GetResponse-PDU.

error_index() - get the current SNMP error-index from the object

$error_index = $session->error_index;

This method returns the numeric value of the error-index contained in the last SNMP GetResponse-PDU.

var_bind_list() - get the hash reference to the last SNMP response

$response = $session->var_bind_list;

This method returns a reference to the hash returned from the query or set methods. The undefined value is returned if this value is empty.

timeout() - set or get the current timeout period for the object

$seconds = $session->timeout([$seconds]);

This method returns the current value for the UDP timeout for the Net::SNMP object. This value is the number of seconds that the object will wait for a response from the agent on the remote host. The default timeout is 2.0 seconds.

If a parameter is specified, the timeout for the object is set to the provided value if it falls within the range 1.0 to 60.0 seconds. The undefined value is returned upon an error and the error() method may be used to determine the cause.

retries() - set or get the current retry count for the object

$count = $session->retries([$count]);

This method returns the current value for the number of times to retry sending a SNMP message to the remote host. The default number of retries is 2.

If a parameter is specified, the number of retries for the object is set to the provided value if it falls within the range 0 to 20. The undefined value is returned upon an error and the error() method may be used to determine the cause.

mtu() - set or get the current MTU for the object

$octets = $session->mtu([$octets]);

This method returns the current value for the Maximum Transport Unit for the Net::SNMP object. This value is the largest value in octets for an SNMP message that can be transmitted or received by the object. The default MTU is 484 octets.

If a parameter is specified, the Maximum Transport Unit is set to the provided value if it falls within the range 30 to 65535 octets. The undefined value is returned upon an error and the error() method may be used to determine the cause.

translate() - enable or disable the translation mode for the object

$mode = $session->translate([$mode]);

When the object decodes the GetResponse-PDU that is returned in response to a SNMP message, certain values are translated into a more "human readable" form. By default the following translations occur:

  • OCTET STRINGs containing non-printable characters are converted into a hexadecimal representation prefixed with "0x".

  • TimeTicks integer values are converted to a time format.

  • NULL values return the string "NULL" instead of an empty string.

  • noSuchObject exception values return the string "noSuchObject" instead of an empty string. If translation is not enabled, the SNMP error-status field is set to 128 which is equal to the exported definition NOSUCHOBJECT (see "EXPORTS").

  • noSuchInstance exception values return the string "noSuchInstance" instead of an empty string. If translation is not enabled, the SNMP error-status field is set to 129 which is equal to the exported definition NOSUCHINSTANCE (see "EXPORTS").

  • endOfMibView exception values return the string "endOfMibView" instead of an empty string. If translation is not enabled, the SNMP error-status field is set to 130 which is equal to the exported definition ENDOFMIBVIEW (see "EXPORTS").

If a parameter is specified, the translation mode is set to either enabled or disabled depending on the value of the passed parameter. Any value that Perl would treat as a true value will set the mode to be enabled, while a false value will disable translation. The current state of the translation mode is returned by the method.

verify_ip() - enable or disable IP verification for the object

$mode = $session->verify_ip([$mode]);

When the object receives an UDP packet, the IP address and UDP port with which the object was created are compared to the values in the received packet. By default, if these values do not match, the UDP packet is ignored and an error message is returned. This check is to insure that the data the object has just received is from the host to which the message was sent. However this can cause problems with multi-homed hosts which respond from a different interface than the one to which the message was sent.

This method is used to enable or disable IP verification on a per object basis. By default, IP address and port verification is enabled. If a parameter is specified, the verification mode is set to either enabled or disabled depending on the value of the passed parameter. Any value that Perl would treat as a true value will set the mode to be enabled, while a false value will disable IP verification. The current state of the IP verification mode is returned by the method.

debug() - set or get the debug mode for the object

$mode = $session->debug([$mode]);

This method is used to enable or disable debugging on a per object basis. By default, debugging is off. If a parameter is specified, the debug mode is set to either enabled or disabled depending on the value of the passed parameter. Any value that Perl would treat as a true value will set the mode to be enabled, while a false value will disable debugging. The current state of the debugging mode is returned by the method.

EXPORTS

Default

INTEGER, INTEGER32, OCTET_STRING, NULL, OBJECT_IDENTIFIER, IPADDRESS, COUNTER, COUNTER32, GAUGE, GAUGE32, UNSIGNED32, TIMETICKS, OPAQUE, COUNTER64, NOSUCHOBJECT, NOSUCHINSTANCE, ENDOFMIBVIEW

Exportable

INTEGER, INTEGER32, OCTET_STRING, NULL, OBJECT_IDENTIFIER, IPADDRESS, COUNTER, COUNTER32, GAUGE, GAUGE32, UNSIGNED32, TIMETICKS, OPAQUE, COUNTER64, NOSUCHOBJECT, NOSUCHINSTANCE, ENDOFMIBVIEW, COLD_START, WARM_START, LINK_DOWN, LINK_UP, AUTHENTICATION_FAILURE, EGP_NEIGHBOR_LOSS, ENTERPRISE_SPECIFIC

Tags
:asn1

INTEGER, INTEGER32, OCTET_STRING, NULL, OBJECT_IDENTIFIER, IPADDRESS, COUNTER, COUNTER32, GAUGE, GAUGE32, UNSIGNED32, TIMETICKS, OPAQUE, COUNTER64, NOSUCHOBJECT, NOSUCHINSTANCE, ENDOFMIBVIEW

:generictrap

COLD_START, WARM_START, LINK_DOWN, LINK_UP, AUTHENTICATION_FAILURE, EGP_NEIGHBOR_LOSS, ENTERPRISE_SPECIFIC

:ALL

All of the above exportable items.

EXAMPLES

This example gets the system uptime from a remote host:

#!/bin/env perl

use Net::SNMP;

$hostname  = shift || 'localhost';
$community = shift || 'public';
$port      = shift || 161;

($session, $error) = Net::SNMP->session(
                                   Hostname  => $hostname,
                                   Community => $community,
                                   Port      => $port
                                );

if (!defined($session)) {
   printf("ERROR: %s\n", $error);
   exit 1;
}

$sysUpTime = '1.3.6.1.2.1.1.3.0';

if (!defined($response = $session->get_request($sysUpTime))) {
   printf("ERROR: %s\n", $session->error);
   $session->close;
   exit 1;
}

printf("sysUpTime for host '%s' is %s\n", $hostname, 
   $response->{$sysUpTime}
);

$session->close;

exit 0;

This example sets the system contact information to "Help Desk":

  #!/bin/env perl

  use Net::SNMP;

  $hostname  = shift || 'localhost';
  $community = shift || 'private';
  $port      = shift || 161;

  ($session, $error) = Net::SNMP->session(
                                     Hostname  => $hostname,
                                     Community => $community,
                                     Port      => $port
                                  );

  if (!defined($session)) {
     printf("ERROR: %s\n", $error);
     exit 1;
  }

  $sysContact = '1.3.6.1.2.1.1.4.0';
  $contact    = 'Help Desk';

  $response = $session->set_request($sysContact, OCTET_STRING, $contact);

  if (!defined($response)) { 
     printf("ERROR: %s\n", $session->error);
     $session->close;
     exit 1;
  }


  printf("sysContact for host '%s' set to '%s'\n", $hostname, 
     $response->{$sysContact}
  );

  $session->close;

  exit 0;

AUTHOR

David M. Town <dtown@fore.com>

ACKNOWLEDGMENTS

The original concept for this module was based on SNMP_Session.pm written by Simon Leinen <simon@switch.ch>.

The Abstract Syntax Notation One (ASN.1) encode and decode methods were derived by example from the CMU SNMP package whose copyright follows: Copyright (c) 1988, 1989, 1991, 1992 by Carnegie Mellon University. All rights reserved.

COPYRIGHT

Copyright (c) 1998-1999 David M. Town. All rights reserved. This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.