SNMP::...ersist(3pm)

💖 SNMP::Extension::PassPersist 💖

okay bestie, so this page lives in the User Contributed Perl Documentation section (that's the 3pm vibe, iykyk), and it's literally your whole guide to the generic pass/pass_persist extension framework for Net-SNMP. grab a boba, we're doing this 💅

---

✨ NAME ✨

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

---

🌸 VERSION 🌸

This is the documentation of SNMP::Extension::PassPersist version 0.07. yes, that's the one, periodt.

---

🦋 SYNOPSIS 🦋

so here's the classic setup for a pass program — main character energy, no notes:

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;

and the classic setup for a pass_persist program, which is giving persistent 🔥:

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 💜

so basically: this module is a framework for writing Net-SNMP extensions using the pass or pass_persist mechanisms. that's the whole point, bestie.

when you're in pass_persist mode, it gives you a way to spare resources by quitting from the main loop after a given number of idle cycles. lowkey efficient, highkey iconic.

and when Sort::Key::OID is available, this module can use it to sort OIDs faster than with the internal pure Perl function. slay.

---

🎀 METHODS 🎀

new()

Creates a new object. you can hand it any attributes as a hash or a hashref. for the full menu of what you can pass, peek at "ATTRIBUTES".

Examples, because we love a demo:

for a pass command, most attributes are useless (ngl):

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()

okay so this method does the following things, in order:

1. process the command line arguments in order to decide in which mode the program has to be executed
2. call the backend init callback
3. call the backend collect callback a first time

then, when you're in pass mode, the corresponding SNMP command is executed, its result is printed on the output filehandle, and run() returns. bye 👋

when you're 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 gets called every refresh seconds. and if no query is read from the input after idle_count cycles, run() returns. it said "I'm done" and it meant it 💅

add_oid_entry(FUNC_OID, FUNC_TYPE, FUNC_VALUE)

Add an entry to the OID tree. that's it, that's the whole thing 🫶

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. matching vibes only.

dump_oid_tree()

Print a complete listing of the OID tree on the output file handle. show us the whole tree, bestie 🌈

---

⭐ ATTRIBUTES ⭐

This module's attributes are generated by Class::Accessor, which means you can pass them as arguments to new() or call them as object methods. flexible fr fr.

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. (not me forking, ok yes me forking 🙈)

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.

bestie listen — you should not modify this table unless you really know what you're doing. 💀

heap

Give access to the heap. it's your little storage closet, keep your stuff in there.

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.

okay so please don't directly modify this hash — instead use the appropriate methods for adding OID entries. we're not savages 💅

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. and there's a heap available for storing user-defined data. cute, right?

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). yes, only the child. 👑

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's a need to connect to a database — in that case both the init and collect callbacks 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. different vibe, still valid.

and 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>

---

😭 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>.

I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. we love a feedback loop 💖

---

🫶 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>
• 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>

---

💜 AUTHOR 💜

Sebastien Aperghis-Tramoni, "<sebastien at aperghis.net>" — king behavior, we stan 🌟

---

🎀 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.

---

and that's a wrap bestie!! this was SNMP::Extension::PassPersist for perl v5.34.0, dated 2022-06-17, filed under SNMP::...ersist(3pm). go forth and persist (respectfully) 💅✨🌸