/ 
SNMP-Agent-0.06
River stage zero No dependents
/ SNMP::Agent

NAME

SNMP::Agent - A simple SNMP AgentX subagent

VERSION

Version 0.06

SYNOPSIS

Eliminates most of the hassle in developing simple SNMP subagents in perl. A list of SNMP OIDs are registered to callbacks that return the data.

FUNCTIONS

new

Get an SNMP::Agent object. See EXAMPLES for use.

register_get_next_oid

If your agent needs to support an OID subtree, the provided handler will be called to find out what the next OID is from the previous one.

Must return undef if there is not a next OID below the registered root OID.

register_get_asn_type

If your agent needs to support an OID subtree, the provided handler will be called to find out what the ASN type is for an OID. Required if the ASN type differs from the default provided for an OID subtree.

Can return undef to use the default assigned ASN for the registered root OID.

run

Called on an SNMP::Agent object with no arguments to start the agent. Does not return until shutdown called.

shutdown

Stop the agent.

EXAMPLES

Simple handler

use SNMP::Agent;
use NetSNMP::ASN qw/ASN_GAUGE/;

sub do_one { return int(rand(10)) }
sub do_two { return "two" }

my $root_oid = '1.3.6.1.4.1.8072.9999.9999.123';
my %handlers = (
  '1' => { handler => \&do_one, type => ASN_GAUGE },
  '2' => { handler => \&do_two },     # default type ASN_OCTET_STR
);

my $agent = new SNMP::Agent('my_agent', $root_oid, \%handlers);
$agent->run();

Output

$ snmpwalk -v 2c -c public localhost 1.3.6.1.4.1.8072.9999.9999.123
iso.3.6.1.4.1.8072.9999.9999.123.1 = Gauge32: 2
iso.3.6.1.4.1.8072.9999.9999.123.2 = STRING: "two"

OID Tree

use SNMP::Agent;

my $root_oid = 'netSnmpPlaypen.7375.1';

my @wasting_time = qw/Sittin' on the dock of the bay/;

sub stats_handler {
  my $oid = shift;     # a NetSNMP::OID object

  return "root oid" if($oid =~ /$root_oid$/);

  my $idx = ($oid->to_array())[$oid->length - 1];
  return $wasting_time[$idx - 1];
}

sub next_oid_handler {
  my $oid = shift;

  if($oid eq $root_oid) {
    return join('.', ($root_oid, '.1'));
  }

  if($oid =~ /$root_oid\.(\d+)$/) {
    my $idx = $1;
    if ($idx <= $#wasting_time)
    {
      my $next_oid = join('.', ($root_oid, $idx + 1));
      return $next_oid;
    }
  }

  return;     # no next OID
}

my %handlers = (
  $root_oid => { handler => \&stats_handler },
);

my $agent = new SNMP::Agent('my_agent', '', \%handlers);
$agent->register_get_next_oid(\&next_oid_handler);
$agent->run();

Output

snmpwalk -v 2c -c public localhost netSnmpPlaypen.7375
NET-SNMP-MIB::netSnmpPlaypen.7375.1 = STRING: "root oid"
NET-SNMP-MIB::netSnmpPlaypen.7375.1.1 = STRING: "Sittin'"
NET-SNMP-MIB::netSnmpPlaypen.7375.1.2 = STRING: "on"
NET-SNMP-MIB::netSnmpPlaypen.7375.1.3 = STRING: "the"
NET-SNMP-MIB::netSnmpPlaypen.7375.1.4 = STRING: "dock"
NET-SNMP-MIB::netSnmpPlaypen.7375.1.5 = STRING: "of"
NET-SNMP-MIB::netSnmpPlaypen.7375.1.6 = STRING: "the"
NET-SNMP-MIB::netSnmpPlaypen.7375.1.7 = STRING: "bay"

NOTES

Callbacks

The callback functions specified to handle OID requests are called for SNMP sets as well as get requests. The requested OID and the request type are passed as arguments to the callback. If the mode is MODE_SET_ACTION there is a third argument, the value to be set.

use NetSNMP::agent qw(MODE_SET_ACTION);
my $persistent_val = 0;

sub do_one
{
  my ($oid, $mode, $value) = @_;
  if ($mode == MODE_SET_ACTION)
  {
    $persistent_val = $value;
  }
  else
  {
    return $persistent_val;
  }
}

If asked to provide a value for an OID out of range, the handler should return an undefined value.

OIDs

The OID passed to each callback function is a NetSNMP::OID object. This may be a symbolic or numeric OID, and will be dependent on your system configuration. If in doubt, convert it to a numeric representation before using it:

use NetSNMP::OID;
my $oid = new NetSNMP::OID('netSnmpPlaypen');
my $numeric = join '.', $oid->to_array();

print "symbolic: $oid\n";
print "numeric: $numeric\n";

symbolic: netSnmpPlaypen
numeric: 1.3.6.1.4.1.8072.9999.9999

Caching

No caching of responses is done by SNMP::Agent. Any results from expensive operations should probably be cached for some time in case of duplicate requests for the same information.

AUTHOR

Alexander Else, <aelse at else.id.au>

BUGS

Please report any bugs or feature requests to bug-snmp-agent at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SNMP-Agent. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COUNTER64

Strange values are returned for non-zero 64 bit counters. I suspect something in either NetSNMP::agent or communication between it and the snmp daemon. From cursory investigation it does not appear to be a simple endian problem. I may be wrong.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc SNMP::Agent

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2011 Alexander Else.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.