POE::Component::NetSNMP::agent - AgentX clients with NetSNMP::agent and POE
Version 0.600
Like a traditional NetSNMP::agent, made POE aware:
NetSNMP::agent
use NetSNMP::agent; use POE qw< Component::NetSNMP::agent >; my $agent = POE::Component::NetSNMP::agent->spawn( Alias => "snmp_agent", AgentX => 1, ); $agent->register(".1.3.6.1.4.1.32272", \&agent_handler); POE::Kernel->run; exit; sub agent_handler { my ($kernel, $heap, $args) = @_[ KERNEL, HEAP, ARG1 ]; my ($handler, $reg_info, $request_info, $requests) = @$args; # the rest of the code works like a classic NetSNMP::agent callback my $mode = $request_info->getMode; for (my $request = $requests; $request; $request = $request->next) { if ($mode == MODE_GET) { # ... } elsif ($mode == MODE_GETNEXT) { # ... } else { # ... } } }
Simpler, let the module do the boring stuff, but keep control of the loop:
use NetSNMP::ASN; use POE qw< Component::NetSNMP::agent >; my $agent = POE::Component::NetSNMP::agent->new( Alias => "snmp_agent", AgentX => 1, AutoHandle => ".1.3.6.1.4.1.32272", ); POE::Session->create( inline_states => { _start => sub { $_[KERNEL]->yield("update_tree"); }, update_tree => \&update_tree, }, ); POE::Kernel->run; exit; sub update_tree { my ($kernel, $heap) = @_[ KERNEL, HEAP ]; # populate the OID tree at regular intervals with # the add_oid_entry and add_oid_tree events }
Even simpler, let the module do all the boring stuff, leaving you nothing more to do than providing the handlers to update the OID trees:
use NetSNMP::ASN; use POE::Component::NetSNMP::agent; my $agent = POE::Component::NetSNMP::agent->new( AgentX => 1, AutoHandle => ".1.3.6.1.4.1.32272", AutoUpdate => [[ \&update_tree, 30 ]], ); $agent->run; sub update_tree { my ($self) = @_; # populate the OID tree with the add_oid_entry() and add_oid_tree() # methods, a la SNMP::Extension::PassPersist }
See also in eg/ for more ready-to-use examples.
This module is a thin wrapper around NetSNMP::agent to use it within a POE-based program, its basic use being the same as you would do without POE: register one or more OIDs with their associated callbacks, then within a callback process & answer the requests with setValue(), setOID(), setError(), etc.
register
setValue()
setOID()
setError()
POE::Component::NetSNMP::agent also provides a simpler mechanism, similar to SNMP::Extension::PassPersist, if you just want to handle get and getnext requests over an OID tree: set the Autohandle option to the a OID, then add OID entries with add_oid_entry or add_oid_tree.
POE::Component::NetSNMP::agent
SNMP::Extension::PassPersist
get
getnext
Autohandle
add_oid_entry
add_oid_tree
The module will try to automatically recover from a lost connection with AgentX master (see the Ping option), but you can force a check by posting to agent_check;
Ping
post
agent_check
Note that most of the API is available both as POE events and as object methods, in an attempt to make it a bit easier for people not fully used to event programming with POE.
This module can use Sort::Key::OID when it is available, for sorting OIDs faster than with the internal pure Perl function.
Sort::Key::OID
Create and return a POE session for handling NetSNMP requests.
NetSNMP::agent options
Name - (optional) sets the agent name, defaulting to "perl". The underlying library will try to read a $name.conf Net-SNMP configuration file.
Name
"perl"
AgentX - (optional) be a sub-agent (0 = false, 1 = true). The Net-SNMP master agent must be running first.
AgentX
Ports - (optional) sets the ports this agent will listen on (e.g.: "udp:161,tcp:161").
Ports
"udp:161,tcp:161"
Component options
Alias - (optional) sets the session alias
Alias
AutoHandle - (optional) sets the component to auto-handle get and getnext request to the given OID
AutoHandle
Debug - (optional) when true, enables debug mode on this session
Debug
Ping - (optional) sets the ping delay between manual agent checks in seconds; default is 10 seconds
Errback - (optional) sets the error callback.
Errback
Example:
my $agent = POE::Component::NetSNMP::agent->spawn( Alias => "snmp_agent", AgentX => 1, );
Simpler constructor: create all the POE sessions and events to handle absolutely all the boring stuff; just provide handlers to update the OID trees. Accept the same arguments than span plus the following:
span
AutoUpdate - expects a definition of handlers and their respective delay (in seconds) in the form of an array of arrays:
AutoUpdate
AutoUpdate => [ [ CODEREF, DELAY ], ... ],
Examples:
# create an agent with a single handler, called every 30 sec my $agent = POE::Component::NetSNMP::agent->new( AgentX => 1, AutoHandle => ".1.3.6.1.4.1.32272", AutoUpdate => [[ \&update_tree, 30 ]], ); # create an agent with two handlers, called respectively # every 10 and every 20 seconds my $agent = POE::Component::NetSNMP::agent->new( AgentX => 1, AutoHandle => ".1.3.6.1.4.1.32272", AutoUpdate => [ [ \&update_tree_1, 10 ], [ \&update_tree_2, 20 ], ], );
Run the main loop (executes POE::Kernel->run)
POE::Kernel->run
Register a callback handler for a given OID.
Arguments:
$agent->register(".1.3.6.1.4.1.32272.1", \&tree_1_handler); $agent->register(".1.3.6.1.4.1.32272.2", \&tree_2_handler);
Add an OID entry to be auto-handled by the agent.
NetSNMP::ASN
ASN_COUNTER
ASN_GAUGE
ASN_OCTET_STR
$agent->add_oid_entry(".1.3.6.1.4.1.32272.1", ASN_OCTET_STR, "oh hai"); $agent->add_oid_entry(".1.3.6.1.4.1.32272.2", ASN_OCTET_STR, "i can haz oh-eye-deez??");
Add multiple OID entries to be auto-handled by the agent.
{ OID => [ ASN_TYPE, VALUE ], ... }
%oid_tree = ( ".1.3.6.1.4.1.32272.1" => [ ASN_OCTET_STR, "oh hai" ]; ".1.3.6.1.4.1.32272.2" => [ ASN_OCTET_STR, "i can haz oh-eye-deez??" ]; ); $agent->add_oid_tree(\%oid_tree);
Access the heap dedicated to update handlers.
POE::Kernel->post($agent, register => ".1.3.6.1.4.1.32272.1", "tree_1_handler"); POE::Kernel->post($agent, register => ".1.3.6.1.4.1.32272.2", "tree_2_handler");
POE::Kernel->post($agent, add_oid_entry => ".1.3.6.1.4.1.32272.1", ASN_OCTET_STR, "oh hai"); POE::Kernel->post($agent, add_oid_entry => ".1.3.6.1.4.1.32272.2", ASN_OCTET_STR, "i can haz oh-eye-deez??");
%oid_tree = ( ".1.3.6.1.4.1.32272.1" => [ ASN_OCTET_STR, "oh hai" ]; ".1.3.6.1.4.1.32272.2" => [ ASN_OCTET_STR, "i can haz oh-eye-deez??" ]; ); POE::Kernel->post($agent, add_oid_tree => \%oid_tree);
POE, http://poe.perl.org/
NetSNMP::agent, NetSNMP::ASN, NetSNMP::OID
Net-SNMP web site: http://www.net-snmp.org/
You can find documentation for this module with the perldoc command.
perldoc POE::Component::NetSNMP::agent
You can also look for information at:
Search CPAN
http://search.cpan.org/dist/POE-Component-NetSNMP-agent/
Meta CPAN
https://metacpan.org/release/POE-Component-NetSNMP-agent
RT: CPAN's request tracker (report bugs here)
https://rt.cpan.org/Public/Dist/Display.html?Name=POE-Component-NetSNMP-agent
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/POE-Component-NetSNMP-agent
CPAN Ratings
http://cpanratings.perl.org/d/POE-Component-NetSNMP-agent
A known issue with this module is that if the snmpd daemon it is connected to dies, the default POE loop will spin over the half-closed Unix socket, eating 100% of CPU until the daemon is restarted and the sub-agent has reconnected. However, this problem can be worked around by selecting an alternative loop like AnyEvent, EV or EPoll (the other loops have the same bug).
https://github.com/maddingue/POE-Component-NetSNMP-agent/issues/1
Please report any bugs or feature requests to bug-poe-component-netsnmp-agent at rt.cpan.org, or through the web interface at https://rt.cpan.org/Public/Dist/Display.html?Name=POE-Component-NetSNMP-agent. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-poe-component-netsnmp-agent at rt.cpan.org
Thanks to Rocco Caputo and Rob Bloodgood for their help on #poe.
#poe
Sébastien Aperghis-Tramoni <sebastien at aperghis.net>
<sebastien at aperghis.net>
Copyright 2011 Sébastien Aperghis-Tramoni.
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.
To install POE::Component::NetSNMP::agent, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE::Component::NetSNMP::agent
CPAN shell
perl -MCPAN -e shell install POE::Component::NetSNMP::agent
For more information on module installation, please visit the detailed CPAN module installation guide.