NAME

POE::Component::NetSNMP::agent - AgentX clients with NetSNMP::agent and POE

VERSION

Version 0.600

SYNOPSIS

Like a traditional NetSNMP::agent, made POE aware:

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.

DESCRIPTION

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.

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.

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;

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.

METHODS

spawn

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.
AgentX - (optional) be a sub-agent (0 = false, 1 = true). The Net-SNMP master agent must be running first.
Ports - (optional) sets the ports this agent will listen on (e.g.: "udp:161,tcp:161").

Component options

Alias - (optional) sets the session alias
AutoHandle - (optional) sets the component to auto-handle get and getnext request to the given OID
Debug - (optional) when true, enables debug mode on this session
Ping - (optional) sets the ping delay between manual agent checks in seconds; default is 10 seconds
Errback - (optional) sets the error callback.

Example:

my $agent = POE::Component::NetSNMP::agent->spawn(
    Alias   => "snmp_agent",
    AgentX  => 1,
);

new

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:

AutoUpdate - expects a definition of handlers and their respective delay (in seconds) in the form of an array of arrays:
```
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

Run the main loop (executes POE::Kernel->run)

register

Arguments:

1. (mandatory) OID to register
2. (mandatory) request handler callback; must be a coderef

Example:

$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_oid_entry

Add an OID entry to be auto-handled by the agent.

Arguments:

1. (mandatory) OID
2. (mandatory) ASN type; use the constants given by NetSNMP::ASN like ASN_COUNTER, ASN_GAUGE, ASN_OCTET_STR..
3. (mandatory) value

Example:

$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_oid_tree

Add multiple OID entries to be auto-handled by the agent.

Arguments:

1. (mandatory) OID tree; must be a hashref with the following structure:

{
    OID => [ ASN_TYPE, VALUE ],
    ...
}

Example:

%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);

heap

Access the heap dedicated to update handlers.

POE EVENTS

register

Arguments:

ARG0: (mandatory) OID to register
ARG1: (mandatory) request handler callback; must be an event name or a coderef

Example:

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

add_oid_entry

Add an OID entry to be auto-handled by the agent.

Arguments:

ARG0: (mandatory) OID
ARG1: (mandatory) ASN type; use the constants given by NetSNMP::ASN like ASN_COUNTER, ASN_GAUGE, ASN_OCTET_STR..
ARG2: (mandatory) value

Example:

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??");

add_oid_tree

Add multiple OID entries to be auto-handled by the agent.

Arguments:

ARG0: (mandatory) OID tree; must be a hashref with the following structure:

{
    OID => [ ASN_TYPE, VALUE ],
    ...
}

Example:

%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);

SUPPORT

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

CAVEATS

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

BUGS

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.

ACKNOWLEDGEMENTS

Thanks to Rocco Caputo and Rob Bloodgood for their help on #poe.

AUTHOR

Sébastien Aperghis-Tramoni <sebastien at aperghis.net>

LICENSE AND COPYRIGHT

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.

	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)

NAME

VERSION

SYNOPSIS

DESCRIPTION

METHODS

spawn

new

run

register

add_oid_entry

add_oid_tree

heap

POE EVENTS

register

add_oid_entry

add_oid_tree

SEE ALSO

SUPPORT

CAVEATS

BUGS

ACKNOWLEDGEMENTS

AUTHOR

LICENSE AND COPYRIGHT

Module Install Instructions