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.

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.

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);
    }