Generic pass/pass_persist extension framework for net-snmp
This is the documentation of \*(C`SNMP::Extension::PassPersist\*(C' version 0.07
Typical setup for a \*(C`pass\*(C' 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 \*(C`pass_persist\*(C' 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); }
This module is a framework for writing Net-SNMP extensions using the \*(C`pass\*(C' or \*(C`pass_persist\*(C' mechanisms.
When in \*(C`pass_persist\*(C' 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 \*(C`Sort::Key::OID\*(C' when it is available, for sorting OIDs faster than with the internal pure Perl function.
Creates a new object. Can be given any attributes as a hash or hashref. See \*(L"\s-1ATTRIBUTES\s0\*(R" for the list of available attributes.
Examples:
For a \*(C`pass\*(C' command, most attributes are useless:
my $extsnmp = SNMP::Extension::PassPersist->new;
For a \*(C`pass_persist\*(C' command, you'll usually want to at least set the \*(C`backend_collect\*(C' 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 );
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 \*(C`pass\*(C' mode, the corresponding \s-1SNMP\s0 command is executed, its result is printed on the output filehandle, and \*(C`run()\*(C' returns.
When in \*(C`pass_persist\*(C' mode, \*(C`run()\*(C' 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 \*(C`refresh\*(C' seconds. If no query is read from the input after \*(C`idle_count\*(C' cycles, \*(C`run()\*(C' returns.
Add an entry to the \s-1OID\s0 tree.
Merge an \s-1OID\s0 tree to the main \s-1OID\s0 tree, using the same structure as the one of the \s-1OID\s0 tree itself.
Print a complete listing of the \s-1OID\s0 tree on the output file handle.
This module's attributes are generated by \*(C`Class::Accessor\*(C', and can therefore be passed as arguments to \*(C`new()\*(C' or called as object methods.
Set the code reference for the collect callback. See also \*(L"\s-1CALLBACKS\s0\*(R".
When set to true, the backend callbacks will be executed in a separate process. Default value is false.
Set the code reference for the init callback. See also \*(L"\s-1CALLBACKS\s0\*(R".
Contains the pipe used to communicate with the backend child, when executed in a separate process.
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 \s-1SNMP\s0 command is always in lowercase, \*(C`nargs\*(C' gives the number of arguments expected by the command and \*(C`code\*(C' the callback reference.
You should not modify this table unless you really know what you're doing.
Give access to the heap.
Get/set the number of idle cycles before ending the run loop.
Get/set the input filehandle.
Gives access to the internal \s-1OID\s0 tree, stored as a hash with the following structure:
oid_tree => { FUNC_OID => [ FUNC_TYPE, FUNC_VALUE ], ... }
where \*(C`FUNC_OID\*(C' is the absolute \s-1OID\s0 of the \s-1SNMP\s0 function, \*(C`FUNC_TYPE\*(C' the function type ("integer", "counter", "gauge", etc), and \*(C`FUNC_VALUE\*(C' the function value.
You should not directly modify this hash but instead use the appropriate methods for adding \s-1OID\s0 entries.
Get/set the output filehandle.
Get/set the refresh delay before calling the backend collect callback to update the \s-1OID\s0 tree.
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 \*(C`pass_persist\*(C' 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 \*(C`backend_init\*(C' attribute.
collect This callback is called every \*(C`refresh\*(C' seconds so the user can update the \s-1OID\s0 tree using the \*(C`add_oid_entry()\*(C' and \*(C`add_oid_tree()\*(C' methods.
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); }
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 \*(C`pass\*(C' or \*(C`pass_persist\*(C' 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>
Please report any bugs or feature requests to \*(C`bug-snmp-extension-passpersist at rt.cpan.org\*(C', 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.
You can find documentation for this module with the perldoc command.
perldoc SNMP::Extension::PassPersist
You can also look for information at:
Search \s-1CPAN\s0 http://search.cpan.org/dist/SNMP-Extension-PassPersist <http://search.cpan.org/dist/SNMP-Extension-PassPersist>
Meta \s-1CPAN\s0 https://metacpan.org/release/SNMP-Extension-PassPersist <https://metacpan.org/release/SNMP-Extension-PassPersist>
\s-1RT:\s0 \s-1CPAN\s0'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 \s-1CPAN\s0 documentation http://annocpan.org/dist/SNMP-Extension-PassPersist <http://annocpan.org/dist/SNMP-Extension-PassPersist>
\s-1CPAN\s0 Ratings http://cpanratings.perl.org/d/SNMP-Extension-PassPersist <http://cpanratings.perl.org/d/SNMP-Extension-PassPersist>
Se\*'bastien Aperghis-Tramoni, \*(C`<sebastien at aperghis.net>\*(C'
Copyright 2008-2011 Se\*'bastien 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.