Sébastien Aperghis-Tramoni > POE-Component-NetSNMP-agent-0.400 > POE::Component::NetSNMP::agent

Download:
POE-Component-NetSNMP-agent-0.400.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.400   Source   Latest Release: POE-Component-NetSNMP-agent-0.500

NAME ^

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

VERSION ^

Version 0.400

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


    POE::Session->create(
        inline_states => {
            _start => sub {
                $_[HEAP]{agent} = POE::Component::NetSNMP::agent->spawn(
                    Alias       => "snmp_agent",
                    AgentX      => 1,
                    AutoHandle  => ".1.3.6.1.4.1.32272",
                );

                $_[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 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

Component options

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:

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

Register a callback handler for a given OID.

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

POE EVENTS ^

register

Register a callback handler for a given OID.

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

SEE ALSO ^

POE, http://poe.perl.org/

NetSNMP::agent, NetSNMP::ASN, NetSNMP::OID

Net-SNMP web site: http://www.net-snmp.org/

SUPPORT ^

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

    perldoc POE::Component::NetSNMP::agent

You can also look for information at:

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 ^

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.

syntax highlighting: