NAME

Net::SNMP - Simple Network Management Protocol version-1

SYNOPSIS

use Net::SNMP;

DESCRIPTION

The module Net::SNMP implements an object oriented interface to the Simple Network Management Protocol version-1. The module allows a Perl application to retrieve or update information on a remote host using the SNMP protocol. The module assumes 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,]);

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.

All arguments are optional and will be given the following defaults 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.

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

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

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

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

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

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.

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() - toggle the translation flag for the object

$flag = $session->translate;

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 a null string.

This method is used to enable or disable this translation on a per object basis. Each call to the method will reverse the current state of translation. The new state of the translation flag is returned by the method. A true value indicates that translation will occur.

debug() - toggle the debug flag for the object

$flag = $session->debug;

This method is used to enable or disable debugging on a per object basis. By default, debugging is off. Each call to the method will reverse the current state of the debug flag. The new state of the translation flag is returned by the method. A true value indicates that debugging is enabled.

EXPORTS

Default

INTEGER, OCTET_STRING, NULL, OBJECT_IDENTIFIER, IPADDRESS, COUNTER, GAUGE, TIMETICKS, OPAQUE

Exportable

INTEGER, OCTET_STRING, NULL, OBJECT_IDENTIFIER, IPADDRESS, COUNTER, GAUGE, TIMETICKS, OPAQUE, COLD_START, WARM_START, LINK_DOWN, LINK_UP, AUTHENTICATION_FAILURE, EGP_NEIGHBOR_LOSS, ENTERPRISE_SPECIFIC

Tags

:asn1: INTEGER, OCTET_STRING, NULL, OBJECT_IDENTIFIER, IPADDRESS, COUNTER, GAUGE, TIMETICKS, OPAQUE
: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;
$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("Uptime 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;
  $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("System contact 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

To install Net::SNMP, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::SNMP

CPAN shell

perl -MCPAN -e shell
install Net::SNMP

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)