--- name: "SNMP::Extension::PassPersist" section: "3pm" platform: "linux" package: "libsnmp-extension-passpersist-perl" version: "0.07-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/SNMP::Extension::PassPersist" --- # SNMP::Extension::PassPersist(3pm) Generic pass/pass\_persist extension framework for Net-SNMP ## 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 resources 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 program 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: \ - • configuring a pass or pass\_persist extension: \ ## BUGS Please report any bugs or feature requests to `"bug-snmp-extension-passpersist at rt.cpan.org"`, or through the web interface at \. 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 \ - • Meta CPAN \ - • RT: CPAN's request tracker \ - • AnnoCPAN: Annotated CPAN documentation \ - • CPAN Ratings \ ## AUTHOR Sebastien Aperghis-Tramoni, `""` ## 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.