NAME¶
SNMP::Extension::PassPersist - Generic pass/pass_persist extension framework for
Net-SNMP
VERSION¶
This is the documentation of "SNMP::Extension::PassPersist" version
0.06
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.
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.