Tut:Extending snmpd using perl
This tutorial is intended as a brief introduction to the technique of embedding perl code within the snmpd agent (similar to how mod_perl support allows you to embed perl directly into the apache web server).
Embedded perl
In order to use embedded perl within the agent, the package must have been configured with this facility enabled:
configure --enable-embedded-perl .....
Prior to release 5.4, this must be done explicitly when compiling the code. From 5.4 onwards, this is enabled by default.
Note: If you get the error 'Can't locate ExtUtils/Embed.pm', make sure ExtUtils-Embed is installed. Fedora users can install the package 'perl-ExtUtils-Embed'.
This mechanism allows you to include perl code within the snmpd.conf file, using the basic syntax
perl statements;
Simple Example
The traditional simple example would be the following snmpd.conf fragment
perl print "Hello, world!\n";
Obviously, this can only server as a very basic example in the context of an SNMP agent.
Note: If you get the error 'embedded perl support failed to initalize', make sure NetSNMP::agent is installed. Fedora and CentOS users can install the package 'net-snmp-perl'.
<tasks> [ ] Provide workable simple examples of embedded perl - e.g. control of normal snmpd.conf directives </tasks>
The most common form of embedding Perl modules is to include an external Perl module:
perl do "/path/to/external/file.pl";
The Perl do function will look for the file using @INC if it is not an absolute path. It will then read and parse the contents of that file, executing the global scope. The global %INC will also be updated. That file therefore doesn't need to be executable.
A much cleaner and more Perl-like solution would be the use of a "real" Perl module:
perl require Foo::Bar; Foo::Bar->init (file => "/path/to/somewhere", debug => 1);
For more information on the behavior of do and require, see the Perl documentation at:
$ perldoc -f do $ perldoc -f require
Variables
There are a few things to be aware of with regard to the handling of variables in embedded perl code.
Firstly, the "do file.pl" mechanism is not the same as invoking a perl program from the command line. It just takes the name of the file to run - not a command plus parameters. So the snmpd.conf fragment
perl do "file.pl one two";
won't work as you might expect. (It's actually looking for a file called file.pl one two, which almost certainly doesn't exist!)
However it is possible to mimic the behaviour of parameters by defining variables in the perl statement, and then referring to these variables in the external file:
perl $argv1="one"; $argv2="two"; do "file.pl";
Secondly, the various perl statements are executed in
order, so the fragment above could equally be represented as
perl $argv1="one"; perl $argv2="two"; perl do "file.pl";
<tasks> [ ] Is this true?? [ ] Check the variable scoping behaviour </tasks>
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.
Initialisation
If embedded perl support is enabled, then immediately before executing
the first perl directive, the agent will execute the code
in the file /usr/share/snmp/snmp_perl.pl. By default,
this contains the following:
##
## SNMPD perl initialization file.
##
use NetSNMP::agent;
$agent = new NetSNMP::agent('dont_init_agent' => 1,
'dont_init_lib' => 1);
The location of this initialisation file can be changed using the
snmpd.conf token perlInitFile, and embedded perl
support can be turned off completely using the directive
disablePerl true
Question:
- one could write everything in snmp_perl.pl, but lets just make our own "do" for the time being.
- why is it there
Embedded Agent modules
One of the most important uses of embedded perl is to implement a MIB module within the agent, using perl code (rather than a C code module). Elements of this are covered in the [1] tutorial page.
This code 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, save this file somewhere on your local system, and use the following snmpd.conf fragment:
perl do "/path/to/perl_module.pl";
<tasks> [ ] Does this work as it stands, or are there any tweaks needed to the code? </tasks>
There is also some documentation on the NetSNMP::agent perl module
available at http://search.cpan.org/dist/NetSNMP-agent/agent.pm
Agent framework
The basic structure of a perl MIB module implementation is as follows:
use NetSNMP::OID (':all');
use NetSNMP::agent (':all');
use NetSNMP::ASN (':all');
#
# Handler routine to deal with SNMP requests
#
sub myhandler {
my ($handler, $registration_info, $request_info, $requests) = @_;
for ($request = $requests; $request; $request = $request->next()) {
#
# Work through the list of varbinds
#
}
}
{
#
# Associate the handler with a particular OID tree
#
my $rootOID = ".1.3.6.1.4.1.8072.999";
my $regoid = new NetSNMP::OID($rootOID);
$agent->register("my_agent_name", $regoid, \&myhandler);
}
The reference material mentioned above has more information about what these functions do, and how they should handle different types of request.
GET requests
The type of SNMP request can be retrieved using the
$request_info->getMode() call, which can
be used to distinguish between GET and GETNEXT requests,
and the various phases of processing a SET request.
The GET request is the simplest case, as the request will have specified a particular OID. All that the perl module has to do is to return the value associated with this OID:
my $oid = $request->getOID();
if ($request_info->getMode() == MODE_GET) {
if ($oid == new NetSNMP::OID($rootOID . ".1.2.1")) {
$request->setValue(ASN_OCTET_STR, "hello world");
}
}
or indicate the appropriate error if this is not actually a
valid MIB instance:
<tasks> [ ] How to report noSuchInstance/Object in a perl module? </tasks>
The tasks of identifying valid OIDs, and providing the appropriate value are the main issues facing the perl coder.
GETNEXT requests
Processing a GETNEXT request (either individually or as part of
an snmpwalk command) is basically similar to handling
a GET request. But first, the MIB module must examine the OID
provided, and decide which is the next valid MIB instance:
my $oid = $request->getOID();
if ($request_info->getMode() == MODE_GETNEXT) {
if ($oid < new NetSNMP::OID($rootOID . ".1.2.1")) {
$nextOID = $rootOID.".1.2.1";
and then return this OID, together with the corresponding value:
$request->setOID($nextOID);
$request->setValue(ASN_OCTET_STR, "hello world");
}
}
SET requests
<tasks> [ ] Describe SET processing </tasks>
Scalar objects
Tables
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 reference $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()}
Third party examples
- From http://vincent.bernat.im/en/blog/2012-extending-netsnmp.html#perl-and-python
- ethtool stats AgentX sub-agent https://github.com/vincentbernat/extend-netsnmp/blob/master/agentx-perl/ethtool-stats.pl
- ethtool pass_persist https://github.com/vincentbernat/extend-netsnmp/tree/master/passpersist-perl
- Redis server agent https://github.com/masterzen/redis-snmp
- POE snmp component https://github.com/maddingue/POE-Component-NetSNMP-agent
- Haproxy http://www.haproxy.org/download/contrib/netsnmp-perl/haproxy.pl
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 extensions:\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.2.1 = STRING: "value3"
NET-SNMP-MIB::netSnmp.999.1.2.2 = 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 ...
Conclusion
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: http://openfacts.berlios.de/index-en.phtml?title=odp
Good luck!
For a complete implementation of perl subagent see also net-snmp-subagent-shell and it's documentation