Provided by: libsnmp-extension-passpersist-perl_0.07-1_all bug

NAME

       SNMP::Extension::PassPersist - Generic pass/pass_persist extension framework for Net-SNMP

VERSION

       This is the documentation of "SNMP::Extension::PassPersist" version 0.07

SYNOPSIS

       Typical setup for a "pass" program:

           use strict;
           use SNMP::Extension::PassPersist;

           # create the object
           my $extsnmp = SNMP::Extension::PassPersist->new;

           # add a few OID entries
           $extsnmp->add_oid_entry($oid, $type, $value);
           $extsnmp->add_oid_entry($oid, $type, $value);

           # run the program
           $extsnmp->run;

       Typical setup for a "pass_persist" program:

           use strict;
           use SNMP::Extension::PassPersist;

           my $extsnmp = SNMP::Extension::PassPersist->new(
               backend_collect => \&update_tree
           );
           $extsnmp->run;

           sub update_tree {
               my ($self) = @_;

               # add a serie of OID entries
               $self->add_oid_entry($oid, $type, $value);
               ...

               # or directly add a whole OID tree
               $self->add_oid_tree(\%oid_tree);
           }

DESCRIPTION

       This module is a framework for writing Net-SNMP extensions using the "pass" or
       "pass_persist" mechanisms.

       When in "pass_persist" mode, it provides a mechanism to spare ressources by quitting from
       the main loop after a given number of idle cycles.

       This module can use "Sort::Key::OID" when it is available, for sorting OIDs faster than
       with the internal pure Perl function.

METHODS

   new()
       Creates a new object. Can be given any attributes as a hash or hashref.  See "ATTRIBUTES"
       for the list of available attributes.

       Examples:

       For a "pass" command, most attributes are useless:

           my $extsnmp = SNMP::Extension::PassPersist->new;

       For a "pass_persist" command, you'll usually want to at least set the "backend_collect"
       callback:

           my $extsnmp = SNMP::Extension::PassPersist->new(
               backend_collect => \&update_tree,
               idle_count      => 10,      # no more than 10 idle cycles
               refresh         => 10,      # refresh every 10 sec
           );

   run()
       This method does the following things:

       •   process the command line arguments in order to decide in which mode the program has to
           be executed

       •   call the backend init callback

       •   call the backend collect callback a first time

       Then, when in "pass" mode, the corresponding SNMP command is executed, its result is
       printed on the output filehandle, and "run()" returns.

       When in "pass_persist" mode, "run()" enters a loop, reading Net-SNMP queries on its input
       filehandle, processing them, and printing result on its output filehandle. The backend
       collect callback is called every "refresh" seconds. If no query is read from the input
       after "idle_count" cycles, "run()" returns.

   add_oid_entry(FUNC_OID, FUNC_TYPE, FUNC_VALUE)
       Add an entry to the OID tree.

   add_oid_tree(HASH)
       Merge an OID tree to the main OID tree, using the same structure as the one of the OID
       tree itself.

   dump_oid_tree()
       Print a complete listing of the OID tree on the output file handle.

ATTRIBUTES

       This module's attributes are generated by "Class::Accessor", and can therefore be passed
       as arguments to "new()" or called as object methods.

   backend_collect
       Set the code reference for the collect callback. See also "CALLBACKS".

   backend_fork
       When set to true, the backend callbacks will be executed in a separate process. Default
       value is false.

   backend_init
       Set the code reference for the init callback. See also "CALLBACKS".

   backend_pipe
       Contains the pipe used to communicate with the backend child, when executed in a separate
       process.

   dispatch
       Gives access to the internal dispatch table, stored as a hash with the following
       structure:

           dispatch => {
               SNMP_CMD  =>  { nargs => NUMBER_ARGS,  code => CODEREF },
               ...
           }

       where the SNMP command is always in lowercase, "nargs" gives the number of arguments
       expected by the command and "code" the callback reference.

       You should not modify this table unless you really know what you're doing.

   heap
       Give access to the heap.

   idle_count
       Get/set the number of idle cycles before ending the run loop.

   input
       Get/set the input filehandle.

   oid_tree
       Gives access to the internal OID tree, stored as a hash with the following structure:

           oid_tree => {
               FUNC_OID  =>  [ FUNC_TYPE, FUNC_VALUE ],
               ...
           }

       where "FUNC_OID" is the absolute OID of the SNMP function, "FUNC_TYPE" the function type
       ("integer", "counter", "gauge", etc), and "FUNC_VALUE" the function value.

       You should not directly modify this hash but instead use the appropriate methods for
       adding OID entries.

   output
       Get/set the output filehandle.

   refresh
       Get/set the refresh delay before calling the backend collect callback to update the OID
       tree.

CALLBACKS

       The callbacks are invoked with the corresponding object as first argument, as for a normal
       method. A heap is available for storing user-defined data.

       In the specific case of a programm running in "pass_persist" mode with a forked backend,
       the callbacks are only executed in the child process (the forked backend).

       The currently implemented callbacks are:

       •   init

           This callback is called once, before the first collect invocation and before the main
           loop. It can be accessed and modified through the "backend_init" attribute.

       •   collect

           This callback is called every "refresh" seconds so the user can update the OID tree
           using the "add_oid_entry()" and "add_oid_tree()" methods.

   Examples
       For simple needs, only the collect callback needs to be defined:

           my $extsnmp = SNMP::Extension::PassPersist->new(
               backend_collect => \&update_tree,
           );

           sub update_tree {
               my ($self) = @_;

               # fetch the number of running processes
               my $nb_proc = @{ Proc::ProcessTable->new->table };

               $self->add_oid_entry(".1.3.6.1.4.1.32272.10", gauge", $nb_proc);
           }

       A more advanced example is when there is a need to connect to a database, in which case
       both the init and collect callback need to be defined:

           my $extsnmp = SNMP::Extension::PassPersist->new(
               backend_init    => \&connect_db,
               backend_collect => \&update_tree,
           );

           sub connect_db {
               my ($self) = @_;
               my $heap = $self->heap;

               # connect to a database
               my $dbh = DBI->connect($dsn, $user, $password);
               $heap->{dbh} = $dbh;
           }

           sub update_tree {
               my ($self) = @_;
               my $heap = $self->heap;

               # fetch the number of records from a given table
               my $dbh = $heap->{dbh};
               my $sth = $dbh->prepare_cached("SELECT count(*) FROM whatever");
               $sth->execute;
               my ($count) = $sth->fetchrow_array;

               $self->add_oid_entry(".1.3.6.1.4.1.32272.20", "gauge", $count);
           }

SEE ALSO

       SNMP::Persist is another pass_persist backend for writing Net-SNMP extensions, but relies
       on threads.

       The documentation of Net-SNMP, especially the part on how to configure a "pass" or
       "pass_persist" extension:

       •   main site: http://www.net-snmp.org/ <http://www.net-snmp.org/>

       •   configuring a pass or pass_persist extension:
           http://www.net-snmp.org/docs/man/snmpd.conf.html#lbBB <http://www.net-
           snmp.org/docs/man/snmpd.conf.html#lbBB>

BUGS

       Please report any bugs or feature requests to "bug-snmp-extension-passpersist at
       rt.cpan.org", or through the web interface at
       http://rt.cpan.org/Public/Dist/Display.html?Name=SNMP-Extension-PassPersist
       <http://rt.cpan.org/Public/Dist/Display.html?Name=SNMP-Extension-PassPersist>.  I will be
       notified, and then you'll automatically be notified of progress on your bug as I make
       changes.

SUPPORT

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

           perldoc SNMP::Extension::PassPersist

       You can also look for information at:

       •   Search CPAN

           http://search.cpan.org/dist/SNMP-Extension-PassPersist
           <http://search.cpan.org/dist/SNMP-Extension-PassPersist>

       •   Meta CPAN

           https://metacpan.org/release/SNMP-Extension-PassPersist
           <https://metacpan.org/release/SNMP-Extension-PassPersist>

       •   RT: CPAN's request tracker

           http://rt.cpan.org/Public/Dist/Display.html?Name=SNMP-Extension-PassPersist
           <http://rt.cpan.org/Public/Dist/Display.html?Name=SNMP-Extension-PassPersist>

       •   AnnoCPAN: Annotated CPAN documentation

           http://annocpan.org/dist/SNMP-Extension-PassPersist <http://annocpan.org/dist/SNMP-
           Extension-PassPersist>

       •   CPAN Ratings

           http://cpanratings.perl.org/d/SNMP-Extension-PassPersist
           <http://cpanratings.perl.org/d/SNMP-Extension-PassPersist>

AUTHOR

       Sebastien Aperghis-Tramoni, "<sebastien at aperghis.net>"

COPYRIGHT & LICENSE

       Copyright 2008-2011 Sebastien Aperghis-Tramoni, all rights reserved.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.