SNMP::Extension::PassPersist - Generic pass/pass_persist extension framework for Net-SNMP
This is the documentation of SNMP::Extension::PassPersist version 0.07
SNMP::Extension::PassPersist
Typical setup for a pass program:
pass
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:
pass_persist
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 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.
Sort::Key::OID
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:
backend_collect
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 pass mode, the corresponding SNMP command is executed, its result is printed on the output filehandle, and run() returns.
run()
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.
refresh
idle_count
Add an entry to the OID tree.
Merge an OID tree to the main OID tree, using the same structure as the one of the OID tree itself.
Print a complete listing of the OID tree on the output file handle.
This module's attributes are generated by Class::Accessor, and can therefore be passed as arguments to new() or called as object methods.
Class::Accessor
new()
Set the code reference for the collect callback. See also "CALLBACKS".
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 "CALLBACKS".
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 SNMP command is always in lowercase, nargs gives the number of arguments expected by the command and code the callback reference.
nargs
code
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 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.
FUNC_OID
FUNC_TYPE
"integer"
"counter"
"gauge"
FUNC_VALUE
You should not directly modify this hash but instead use the appropriate methods for adding OID entries.
Get/set the output filehandle.
Get/set the refresh delay before calling the backend collect callback to update the OID 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 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.
backend_init
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.
add_oid_entry()
add_oid_tree()
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 pass or pass_persist extension:
main site: http://www.net-snmp.org/
configuring a pass or pass_persist extension: http://www.net-snmp.org/docs/man/snmpd.conf.html#lbBB
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. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-snmp-extension-passpersist at rt.cpan.org
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
Meta CPAN
https://metacpan.org/release/SNMP-Extension-PassPersist
RT: CPAN's request tracker
http://rt.cpan.org/Public/Dist/Display.html?Name=SNMP-Extension-PassPersist
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/SNMP-Extension-PassPersist
CPAN Ratings
http://cpanratings.perl.org/d/SNMP-Extension-PassPersist
Sébastien Aperghis-Tramoni, <sebastien at aperghis.net>
<sebastien at aperghis.net>
Copyright 2008-2011 Sé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.
To install SNMP::Extension::PassPersist, copy and paste the appropriate command in to your terminal.
cpanm
cpanm SNMP::Extension::PassPersist
CPAN shell
perl -MCPAN -e shell install SNMP::Extension::PassPersist
For more information on module installation, please visit the detailed CPAN module installation guide.