Revision as of 21:34, 27 September 2007

Right now there is not a whole lot here, but this should eventually be a tutorial for using all the various perl modules, including how to embed perl directly within the net-snmp agent (similar to how mod_perl support allows you to embed perl directly into the apache web server).

For the time being, I'll offer a perl module source code which can be used as a perl SNMP agent, perl subagent, or sourced directly within a agent containing embedded perl support. To make it work directly within your agent, you must have compiled the net-snmp package using --enable-embedded-perl and then in your snmpd.conf file you can put:

 perl do "/path/to/perl_module.pl";

Extended example of embedded perl agent in snmpd

I hope the following can help with ideas / Owen Brotherwood, DK 2007.

Please use http://www.net-snmp.org/wiki/index.php?title=Talk:Tut:Extending_snmpd_using_perl&action=edit to discuss this page.
I will flet the discussion into this document.

Status: waiting for feedback from developers via "discussion" in the twiki

Oxo 10:10, 25 September 2007 (PDT)

Embedded perl agent in snmpd (snmpd.conf)

snmpd.conf

If one has perl enabled for snmpd, it is possible to add the following in snmpd.conf:

perl print STDERR "Hello world";

- or any other nice perl things.

Or one could:

perl do "/etc/snmp/myext.pl"

Which will "do" a program.

@ARGV

The definition of variables in snmpd.conf is a whole section in this tutorial.

This doesn't work :(

perl do "perl.pl arg1 arg2" 

Using $a and $b in program works :)

perl $a=1; $b=1; do "perl.pl"

But the following doesn't work :(
- and will be a problem for the handler subroutine you will read about in a bit.
If you are using $a in a subroutine, $a = 2 will be for both instances (the second instance has overwritten the $a = 1 with $a = 2).

perl $a=1; $b=1; do "perl.pl" 
perl $a=2; $b=1; do "perl.pl" 

So watch out when passing parameters :)

But the problem goes further ...

Using $debugging=1?
But if you have two programs and define $debugging=1 outside of the handler subroutine, then it will affect any other programs that have defined $debugging...

And what if one defines a subroutine, say 'helpfull' in more than one program: which one get's called by the handler subroutine...
- correct, the wrong one.

../share/snmp/snmp_perl.pl

If embedded perl support is enabled, the default initialisation is equivalent to the directives:

disablePerl  false
perlInitFile /usr/local/share/snmp/snmp_perl.pl

On my system, /usr/share/snmp/snmp_perl.pl is:

##
## SNMPD perl initialization file.
##

use NetSNMP::agent;
$agent = new NetSNMP::agent('dont_init_agent' => 1,
                            'dont_init_lib' => 1);

Question:

• one could write everything in snmp_perl.pl, but lets just make our own "do" for the time being.
• why is it there

NetSNMP::agent module

And here we continue where http://www.net-snmp.org/tutorial/tutorial-5/toolkit/perl/perl_module.pl left off with the NetSNMP::agent module concentrating on starting an agent from snmpd.conf.

In a bit, we'll go over to a largish piece of example code, but let's do some more research in NetSNMP::agent first
We use http://search.cpan.org/dist/NetSNMP-agent/ and especially http://search.cpan.org/dist/NetSNMP-agent/agent.pm for referance.
- although the page http://search.cpan.org/dist/NetSNMP-agent/agent.pm contains "what is this" comments :(

"All" that is needed to create a perl agent that is embedded in snmpd via snmpd.conf is:

# place this in a .pl file, and then in your snmpd.conf file put:
#    perl do '/path/to/file.pl';

use NetSNMP::OID (':all'); 
use NetSNMP::agent (':all'); 
use NetSNMP::ASN (':all'); 

sub myhandler {
  my ($handler, $registration_info, $request_info, $requests) = @_;
# ...
  for ($request = $requests; $request; $request = $request->next()) { 
#...
  }
#...
}
{
#...
  my $regoid = new NetSNMP::OID($regat); 
  $agent->register("my_agent_name", $regoid, \&myhandler);
}

So read the referance material concerning the functions to see what they do and you should be set to understand what is happening when the functions are called

Now all you need to do is find out where/how/when should data be collected/altered/stored and presented when snmpwalk-ed
- that's the hard bit

Parameters revisited

While going through the referance material, you will find:

getRootOID ()
        Returns a NetSNMP::OID object that describes the registration
        point that the handler is getting called for (in case you
        register one handler function with multiple OIDs, which should
        be rare anyway)

        $root_oid = $request->getRootOID();

Hmm, intresting...
Why not make a hash of values to the perl programs. We presume that a number of perl agents will soon be available with different objectives and need a "standard" way of retrieving parameters from snmpd.conf.
All the information could be hard coded in the perl agent (or at installation) but it would be nicer if the OID and which configuration file the agent uses could be defined at the least.

Example:

perl  $regat = '.1.3.6.1.4.1.8072.999'; $root_oid = new NetSNMP::OID($regat); $config_file{root_oid} = "/etc/snmpd/snmpagent.conf"; do "snmpagent.pl";

And referance $config_file{$root_oid} in the program.

This could be made "the official" way to pass parameters in snmpd.conf
Some of the work could be in a function library contained in ../share/snmp/snmp_perl.pl ....
And be called by something like:

setconfig($regat, "/etc/snmpd/snmpagent.conf")

Giving an entry in snmpd.conf like:

perl $regat = '.1.3.6.1.4.1.8072.999'; setconfig($regat, "/etc/snmpd/snmpagent.conf"); do "/etc/snmpd/snmpagent.pl";

The snmpagent.pl could use a call to getRootID in order to referance the hash $config_file{$request->getRootID()}

OXO Example

MODE_GET

"snmpget" is trivial as the requester knows what it wants and, if the agent has it, the reply is a simple hash lookup.

MODE_GETNEXT

"snmpwalk" is harder.

The request almost knows what it wants, and the agent need's to reply to anything that is in the area for the OID it has registered.

Take $regat, '.1.3.6.1.4.1.8072.999'. We have a .1 extension that we would like to serve, with values in .1.1 .1.2 etc .2.1 .2.2 etc etc.

The secret is to fill in the blanks in the hash for next OID's where a value has not been assigned.
So:

• In general, if $regat, $regat.1 or $regat.1.1 etc are requested, the agent should supply the next OID that has a value, and it's value.
• Check for OID < $regat.1.1.1, reply with $regat.1.1.1 and it's value.
• For $regat.1.1.<max> $regat.1.2.<max> etc, take a look at the hashs for OID's and pay attention to how $OID_next{$prev_OID} = $this_OID is used in the example.

Input CSV

In order to give the example some "dynamic" data to display, an input "csv" is supplied
-the format of the input csv is "made for the moment".

For example with $delimT='=' and $delimV=':' (the oidname is only used for documentation/comment).

oidname1=4=value1:value2
oidname2=4=value3:value4

Which gives relative to $regat, with $extension = '1':

NET-SNMP-MIB::netSnmp.999.1.1.1 = STRING: "value1"
NET-SNMP-MIB::netSnmp.999.1.1.2 = STRING: "value2"
NET-SNMP-MIB::netSnmp.999.1.2.1 = STRING: "value3"
NET-SNMP-MIB::netSnmp.999.1.2.2 = STRING: "value4"

By the way:
The 4 is ASN_OCTET_STR on my system. I would have liked to have written ASN_OCTET_STR as type but my perl programming experience couldn't help me in taking the ASN_OCTET_STR and use it directly in the reply: I would just like to take the type as written and not use a if else test sequence ... (Input please ...:) )

For example

Here is a "fun" one: walk passwd

perl print STDERR "Perl extentsions:\n"
perl $debugging = '1';
perl $verbose = '1';
perl $regat = '.1.3.6.1.4.1.8072.999'; $extension = '1'; $mibdata = '/etc/passwd'; $delimT=''; $delimV=':'; do "/etc/snmp/snmpagent.pl";

Note that if $delimT="" we assume the input is ASN_OCTET_STR and only parse for values with $delimV

While I still have the following in my clipboard, the following, although nice to look at, doesn't work :(

perl {
        $regat = '.1.3.6.1.4.1.8072.999'; $extension = '1';
        $mibdata = '/etc/passwd'; $delimT=''; $delimV=':';
        do "/etc/snmp/snmpagent.pl";
}

"Code" : perl do

"snapshot" or see http://svn.berlios.de/wsvn/odp/trunk/bin/snmpagent.pl?op=file&rev=0&sc=0

#!/usr/bin/perl 

########################################
#
# 
# Owen Brotherwood, DK 2007 
# Based on original perl module example 
# GNU General Public License V3 
#
#
######################################### 

$program = $0;

if (!defined($regat)) {
        help('No $regat defined');
}

sub help {
        my ($message) = @_;
        print STDERR '
ERROR: ' .  $program . ':' . $message . 
'

Here is some help ...

        This program should be started from snmpd.conf, an example for allowing one to walk /etc/passwd would be when this program is /etc/snmp/snmpagent.pl:
                perl print STDERR \'Perl extentsions:\' . \n\"
                perl $debugging = \'1\';
                perl $verbose = \'1\';
                perl {$regat = \'.1.3.6.1.4.1.8072.999\'; $extension = \'1\'; $mibdata = \'/etc/passwd\'; $delimT=\'\'; $delimV=\':\'; do \'/etc/snmp/snmpagent.pl\';}

        Use snmpd -f to see what is going on.

        If $delimT is defined, the first two values are comment(for documentation) and type, for example 4.
        If $delimT is \'\', ASN_OCTET_STR (4) is presummed.

        So, with $delimV=\':\' and $delimT=\'=\':
                oidname1=4=value1:value2
                oidname2=4=value3:value4

        The result of a snmpwalk with $regat = '.1.3.6.1.4.1.8072.999' and $extension = '1' would be:
                NET-SNMP-MIB::netSnmp.999.1.1.1 = STRING: "value1"
                NET-SNMP-MIB::netSnmp.999.1.1.2 = STRING: "value2"
                NET-SNMP-MIB::netSnmp.999.1.1.1 = STRING: "value3"
                NET-SNMP-MIB::netSnmp.999.1.1.1 = STRING: "value4"

        NB: snmptable requires a MIB to work.

        Owen Brotherwood, DK 2007
        GNU General Public License V3
';
        die($message);
}

use NetSNMP::OID (':all');
use NetSNMP::agent (':all');
use NetSNMP::ASN (':all');

sub my_snmp_handler { 
            my ($handler, $registration_info, $request_info, $requests) = @_; 
            my $request; 
            my %my_oid = (); 
        my @mibdata;
        my $ASN_OCTET_STR = 4;
# for this example, wasteful read test data in every time ... 
    	open(MIB,$mibdata); 
            @mibdata = <MIB>; 
            close(MIB); 
# we append .1 to $regat for the area which the test data is available
    	$base_oid = new NetSNMP::OID($regat . '.' . $extension); 
# start taking in values 
        undef($prev_oid); 
        $jndex = 1; 
        foreach $line (@mibdata) { 
# fill the hash pipe 
                chomp $line; 
                if ($delimT != ''){
                        ($index_name, $index_type, $index_values) = split(/$delimT/, $line); 
                }else{
                        $index_values = $line;
                        $index_name = 'Unknown';
                        $index_type = $ASN_OCTET_STR;
                }
                my @value = split(/$delimV/, $index_values); 
                my $index = 1; 
                foreach $mibit (@value) { 
                        $this_oid = new NetSNMP::OID($base_oid . '.' . $jndex . '.' . $index); 
                        $oid_type{$this_oid} = $index_type;
                        $oid_value{$this_oid} = $mibit; 
                        $oid_index{$this_oid} = $index; 
                        $oid_jndex{$this_oid} = $jndex; 
                        if (defined($prev_oid)){ 
                                $oid_next{$prev_oid} = $this_oid; 
                        } 
                        $prev_oid = $this_oid; 
                        print STDERR "Loading $this_oid $oid_type{$this_oid}::$oid_value{$this_oid}  \n" if ($verbose); 
                        $index++; 
                } 
                $jndex++; 
        } 
        $mjndex = $jndex;
        $mindex = $index;
# fill in some blanks
	for ($jndex = 1; $jndex < $mjndex; $jndex++) {
                $this_oid = new NetSNMP::OID($base_oid . '.' . $jndex);
                $next_oid = new NetSNMP::OID($this_oid . '.1');
                $oid_next{$this_oid} = $next_oid;
        }
        for ($request = $requests; $request; $request = $request->next()) { 
                $oid = $request->getOID(); 
                print STDERR "$program @ $oid " if ($debugging); 
                if ($request_info->getMode() == MODE_GET) { 
# easy to get 
                        print STDERR " GET " if ($debugging); 
                        if (exists $oid_value{$oid}) { 
                                print STDERR "->$oid_value{$oid}\n" if ($debugging); 
                                $request->setValue($oid_type{$oid}, $oid_value{$oid}); 
                        }else{ 
                                print STDERR " No value ...\n"; 
                        } 
                }elsif ($request_info->getMode() == MODE_GETNEXT) { 
# long way to walk 
                        print STDERR " GETNEXT " if($debugging); 
                        if (defined($oid_next{$oid})) { 
                                $next_oid = $oid_next{$oid}; 
                                $type_oid = $oid_type{$next_oid}; 
                                $value_oid = $oid_value{$next_oid}; 
                                $request->setOID($next_oid); 
                                $request->setValue($type_oid, $value_oid); 
                        }elsif ($oid <= $base_oid) { 
                                $next_oid = new NetSNMP::OID($base_oid . '.1.1');
                                $type_oid = $oid_type{$next_oid};
                                $value_oid = $oid_value{$next_oid};
                                $request->setOID($next_oid); 
                                $request->setValue($type_oid, $value_oid); 
                        }else{
                                print STDERR "Hit by a truck whilst walking ...\n" if ($debugging);
                        }
                } 
        } 
} 

{
        if (!$agent) {
               help('No $agent defined');
        }

        print STDERR "$0 @ $regat using $mibdata ($delimV) ($delimT)\n";

        my $regoid = new NetSNMP::OID($regat); 

        $agent->register($program, $regoid, \&my_snmp_handler);
}
########################################################################

Well, the example is just an example: reading a big file in every time isn't the best way ...

Funny ideas:

• Use set to trigger a read
• The data is already formatted as a hash in a file
• Find another way ...

Conclussion

A bit premature, as I'm not really finished yet but ...

Using embeded perl agents from snmpd.conf may not be a good idea: note, I wrote plural of agent
If one has only one agent in snmpd.conf, there won't be to many side effects as in the @ARG section.

It hasn't been a total waste of time: brushed up some very rusty perl and maybe found out how to snmpwalk correctly which I can allways reuse in "the next step".

The next step for me is get a perl agent up and running that is not started from snmpd.conf and analyze that.Oxo 13:18, 27 September 2007 (PDT)

And remember, use the extending of snmpd to allow other snmp programs access to intresting information instead of using, for example, txt files or SQL DB's that are normally used to lock the information in.