Net-SNMP Wiki - User contributions [en]

Talk:TUT:Writing a MIB Module

2009-03-10T13:01:44Z

Octo: Added tasks for "A simple scalar attached to a variable".

== Tasks ==

=== A simple scalar attached to a variable ===

<tasks>
[ ] Explain the return value of netsnmp_register_int_instance.
</tasks>

TUT:Writing a Dynamically Loadable Object

2009-03-05T09:57:10Z

Octo: /* Initialization */ Clarify what the problem with multiple loads is.

This page describes how to build extension for Net-SNMP as shared objects, binary files that can be loaded by the SNMPd daemon directly and are executed as part of the daemon. This differs from the concept introduced in [[TUT:Writing a MIB Module|Writing a MIB Module]] in that the extension resides in its own binary file and is loaded by the agent at runtime. This adds the flexibility to add new functionality / MIBs after the agent has been compiled, enabling you to extent the daemon provided by a binary package without the need to roll your own modified package.

Yet another possibility is offered by Subagents, see [[TUT:Writing a Subagent|Writing a Subagent]]: Subagents are separate processes that do not share memory, file descriptors and so on with the daemon and must use interprocess communication (IPC) to communicate with the daemon.

Writing dynamically loadable objects is interesting because you will have the entire API provided by Net-SNMP at your disposal, for example a caching infrastructure. Shared objects loaded this way usually get their configuration from the same configuration file the core daemon uses, which often is a nice thing. Disadvantages are that a programming mistake in your custom extension may crash the entire daemon and that your code is by design always executed as the same user the core daemon is executed as, i. e. potentially with unnecessary privileges — or too little, depending on your setup.

== Prerequisites ==

While not strictly necessary, you'll probably have an easier time building a shared object if you start with an already functioning MIB module (extension) as described in [[TUT:Writing a MIB Module|Writing a MIB Module]]. This section of the tutorials will assume you have a working extension build directly into the daemon already and tells you how to move that out of the daemon and into a shared object.

For demonstration purposes, we'll refer to some example MIB objects and code: the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mib_module/NET-SNMP-TUTORIAL-MIB.txt NET-SNMP-TUTORIAL-MIB] MIB, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.c example MIB module] and it's [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.h header file].

Note: The <code>dlmod</code> code is based on the <code>UCD-DLMOD-MIB</code>. It resides in the <code>ucdExperimental</code> name-space, but since nothing has changed since 1999 it's pretty safe to assume this interface is stable. You can find the MIB in <code>mibs/UCD-DLMOD-MIB.txt</code> in the source-code distribution.

The Net-SNMP package must have been built with dynamically loadable module support for the following to work. You should therefore enable the UCD MIB when configuring the sources:

$ ./configure --with-mib-modules="ucd_snmp $OTHER_MIBS" $OTHER_OPTIONS

Besides the right MIB, you need of course support for shared objects. This is enabled with the <code>--enable-shared</code> argument of <code>configure</code>, but should be automatically enabled if your system supports dynamically loaded objects. You can check for support in your agent but looking at the output of the <code>snmpd -H</code> command for the "dlmod" token. If its listed, the compiled agent supports it.

Note: All command line options below assume you have an appropriately setup <code>~/.snmp/snmp.conf</code> file that allows you to not have to specify a SNMP version number, community name, username, or whatever else in order to talk to your agent. The agent, of course, must have a matching <code>/usr/local/share/snmp/snmpd.conf</code> file (or equivalent).

{{TUT:File-Table-Top-and-basics}}
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] || The MIB module's header file
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] || The MIB module's C source code
|}

== Initialization ==

After loading the shared object to memory, the object loader will look for an initialization function inside the shared object. The name of this function is <code>init_name</code>, where "name" is the name of your extension. The name of the example module is "nstAgentPluginObject", so the loader will look for a function with the following prototype:

void init_nstAgentPluginObject (void);

There's a complementary function, called <code>deinit_name</code>, which is called when the module is unloaded, for example when the daemon is shutting down. Unsurprisingly, the prototype of the example deinit-function is:

void deinit_nstAgentPluginObject (void);

These are the only two functions called by the object loaded. All other functions (and module-global variables) therefore should be declared <code>static</code>.

It is important to note that nothing prevents the agent from a second "load" of the same shared object. The module isn't actually loaded a second time, but the initialization function is run again. Modules should be able to handle that, for example by checking if they were already initialized when returning without further actions if so. The same applies to the de-initialization functions.

Further when the last unload happens the module is unloaded and so the code disappears. When this happens everything registered with the agent from the module must be unregistered since not doing so is an open invitation to core dumps.

You can check the names of currently loaded modules using the <code>UCD-DLMOD-MIB::dlmodName</code> OID.

== Configuration ==

As mentioned in the introduction, you can register own configuration options which extend the daemon's configuration. To do so, you need to provide two callback functions which are called when appropriate: One that handles a configuration statement, and one that cleans up when necessary. A short example is given below and registers the foobar option:

static const char *global_foobar = NULL;
…
static void config_handle (const char *key, char *value)
{
if (strcasecmp ("foobar", key) == 0)
{
char *tmp = strdup (value);
if (tmp != NULL)
{
free (global_foobar);
global_foobar = tmp;
}
}
else if …
} /* void config_handle */

static void config_free (void)
{
free (global_foobar);
global_foobar = NULL;
}
…
snmpd_register_config_handler ("foobar",
config_handle, config_free,
"The foobar option does something incredible!");

Do not just assign the <code>value</code> pointer to a global variable or dreadful things may happen!

== Writing the module ==

The next steps are basically the same as those steps outlined in [[TUT:Writing a MIB Module|Writing a MIB Module]], i. e. register one or more data sets at some OIDs, for example using the [http://www.net-snmp.org/dev/agent/group__table__dataset.html#ga14 netsnmp_register_table_data_set], see [http://www.net-snmp.org/dev/agent/data__set_8c-example.html the data_set.c example]. Please see [[TUT:Writing a MIB Module|the introductory documentation]].

== Compiling and linking the shared object ==

Building shared objects for Net-SNMP works just like building any other shared object. If you have not done that so far, you should probably read your compilers documentation on the subject. When using the GNU Compiler Collection (GCC), you will most likely need the <code>-fPIC -shared</code> flags.

You should use the <code>net-snmp-config</code> script to determine additional compiler and linker flags. For example:

$ cc `net-snmp-config --cflags` -fPIC -shared -g -O0 -o nstAgentPluginObject.so nstAgentPluginObject.c `net-snmp-config --libs`

You can find example Makefiles at <code>agent/mibgroup/examples/Makefile.dlmod</code> in the source-code distribution and at [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demoapp/Makefile]. Hopefully this'll get you started.

== Steps to test the shared object via runtime MIB configuration ==

# Start the snmpd and watch the dlmod and nstAgentPluginObject modules interact using the debugging flag (this assumes you already have access control set up properly for your agent):
#:% '''snmpd -f -L -DnstAgentPluginObject,dlmod'''
# In another window, test to make sure that the agent doesn't currently support the nstAgentPluginObject (if you get different results running this command you need to recompile the net-snmp agent without the nstAgentPluginObject mib module compiled in directly):
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0'''
#:nstAgentPluginObject.0 = No Such Object available on this agent at this OID
# Then, run snmpset to create a new row in the dlmod table:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i create'''
#:dlmodStatus.1 = create(6)
# See that the row was created:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#:SNMP table: dlmodTable
#:
#:dlmodName dlmodPath dlmodError dlmodStatus
#: unloaded
#Then set the properties of the row up to point to our new object and to give it a name:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodName.1 s "nstAgentPluginObject" UCD-DLMOD-MIB::dlmodPath.1 s "/path/to/nstAgentPluginObject.so" '''
#:dlmodName.1 = "nstAgentPluginObject"
#:dlmodName.1 = "/path/to/nstAgentPluginObject.so"
#:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#: SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so unloaded
#Finally, load the shared object into the running agent:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i load '''
#:dlmodStatus.1 = loaded(1)
#:
#:% snmptable localhost UCD-DLMOD-MIB::dlmodTable
#:SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so loaded
#If everything above was done correctly, then the following command should work and will access the shared object's data:
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0 '''
#: nstAgentPluginObject.0 = INTEGER: 3

== Loading via the snmpd.conf file ==

A more common method of loading the shared object is to instruct the agent to load the extension at startup in the <code>snmpd.conf</code> configuration file. This can be achieved using the <code>dlmod</code> configuration option:

dlmod nstAgentPluginObject /path/to/nstAgentPluginObject.so

The first argument specifies the shared object's module name, the second argument specifies the full pathname of the shared object file. The module name used here must match the name of the initialization function, see [[#Initialization]].

All custom configuration options, as described in [[#Configuration]], must succeed the <code>dlmod</code> statement.

== See also ==

* [[TUT:Writing a MIB Module]]
* [[Net-snmp extensions]] List of extensions, some of which are built as dynamically loaded objects.

{{TUT:LIST}}

Talk:TUT:Writing a Dynamically Loadable Object

2009-03-05T09:53:46Z

Octo: Oh, right, dlopen behaves different from what I recalled.

How is loading the shared object multiple times problematic? As long as non-static symbols of the are not exported by default, both objects should live in their private little happy place. Actually, I doubt that setting <code>RTLD_GLOBAL</code> or similar would be a problem, because actually not symbol resolution takes place.. octo 21:45, 3 March 2009 (UTC)

The problem is that dlopening the same module a second time will return a reference to the same object as the first dlopen, so both copies will work with the same static data. magfr 2009-03-04T22:07 UTC
* Oh, that's right.. I should have checked dlopen(3) first.. octo 09:53, 5 March 2009 (UTC)

Talk:Tut:Extending snmpd using perl

2009-03-04T07:32:05Z

Octo: Moved completed tasks here.

Thank you for your input 
Just write comments below

''<tasks>
[x] Check handling of non-FQPN "perl do" files - ? searches @INC?
[x] Do external perl command files need to be executable or not?
</tasks>''

* Moved completed tasks to here. Maybe other tasks should be taken out of the normal text and put here instead, too? octo 07:32, 4 March 2009 (UTC)

Tut:Extending snmpd using perl

2009-03-04T07:29:16Z

Octo: /* Simple Example */ Improved the description of "do" and added "require".

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.

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 <code>snmpd.conf</code> fragment

perl print "Hello, world!\n";

Obviously, this can only server as a very basic example in the context of an SNMP agent.

''<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 <code>do</code> function will look for the file using <code>@INC</code> if it is not an absolute path. It will then read and parse the contents of that file, executing the global scope. The global <code>%INC</code> 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 <code>do</code> and <code>require</code>, 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 <code>perl</code> 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). 
<pre>
perl $a=1; $b=1; do "perl.pl"
perl $a=2; $b=1; do "perl.pl"
</pre>
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 <code>perl</code> directive, the agent will execute the code
in the file <code>/usr/share/snmp/snmp_perl.pl</code>. By default,
this contains the following:

<pre>
##
## SNMPD perl initialization file.
##

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

The location of this initialisation file can be changed using the
snmpd.conf token <code>perlInitFile</code>, 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 [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/perl/perl_module.pl|perl_module] 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 <code>NetSNMP::agent</code> 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:

<pre>
use NetSNMP::OID (':all');
use NetSNMP::agent (':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);
}
</pre>

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
<code>$request_info->getMode()</code> 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 <code>snmpwalk</code> 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:
<pre>
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();
</pre>

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:
<pre>
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";
</pre>
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:
<pre>
setconfig($regat, "/etc/snmpd/snmpagent.conf")
</pre>
Giving an entry in snmpd.conf like:
<pre>
perl $regat = '.1.3.6.1.4.1.8072.999'; \
setconfig($regat, "/etc/snmpd/snmpagent.conf"); \
do "/etc/snmpd/snmpagent.pl";
</pre>

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).
<pre>
oidname1=4=value1:value2
oidname2=4=value3:value4
</pre>
Which gives relative to $regat, with $extension = '1':
<pre>
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"
</pre>
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
<pre>
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";
</pre>
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 :(
<pre>
perl {
$regat = '.1.3.6.1.4.1.8072.999'; $extension = '1';
$mibdata = '/etc/passwd'; $delimT=''; $delimV=':';
do "/etc/snmp/snmpagent.pl";
}
</pre>

== "Code" : perl do ==
"snapshot" or see http://svn.berlios.de/wsvn/odp/trunk/bin/snmpagent.pl?op=file&rev=0&sc=0
<pre>
#!/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);
}
########################################################################

</pre>

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.[[User:Oxo|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!

Talk:TUT:Writing a Dynamically Loadable Object

2009-03-03T21:45:11Z

Octo: Why is loading an object multiple times a problem?

TUT:Writing a Dynamically Loadable Object

2009-03-03T21:35:58Z

Octo: Added section "See also".

This page describes how to build extension for Net-SNMP as shared objects, binary files that can be loaded by the SNMPd daemon directly and are executed as part of the daemon. This differs from the concept introduced in [[TUT:Writing a MIB Module|Writing a MIB Module]] in that the extension resides in its own binary file and is loaded by the agent at runtime. This adds the flexibility to add new functionality / MIBs after the agent has been compiled, enabling you to extent the daemon provided by a binary package without the need to roll your own modified package.

Yet another possibility is offered by Subagents, see [[TUT:Writing a Subagent|Writing a Subagent]]: Subagents are separate processes that do not share memory, file descriptors and so on with the daemon and must use interprocess communication (IPC) to communicate with the daemon.

Writing dynamically loadable objects is interesting because you will have the entire API provided by Net-SNMP at your disposal, for example a caching infrastructure. Shared objects loaded this way usually get their configuration from the same configuration file the core daemon uses, which often is a nice thing. Disadvantages are that a programming mistake in your custom extension may crash the entire daemon and that your code is by design always executed as the same user the core daemon is executed as, i. e. potentially with unnecessary privileges — or too little, depending on your setup.

== Prerequisites ==

While not strictly necessary, you'll probably have an easier time building a shared object if you start with an already functioning MIB module (extension) as described in [[TUT:Writing a MIB Module|Writing a MIB Module]]. This section of the tutorials will assume you have a working extension build directly into the daemon already and tells you how to move that out of the daemon and into a shared object.

For demonstration purposes, we'll refer to some example MIB objects and code: the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mib_module/NET-SNMP-TUTORIAL-MIB.txt NET-SNMP-TUTORIAL-MIB] MIB, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.c example MIB module] and it's [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.h header file].

Note: The <code>dlmod</code> code is based on the <code>UCD-DLMOD-MIB</code>. It resides in the <code>ucdExperimental</code> name-space, but since nothing has changed since 1999 it's pretty safe to assume this interface is stable. You can find the MIB in <code>mibs/UCD-DLMOD-MIB.txt</code> in the source-code distribution.

The Net-SNMP package must have been built with dynamically loadable module support for the following to work. You should therefore enable the UCD MIB when configuring the sources:

$ ./configure --with-mib-modules="ucd_snmp $OTHER_MIBS" $OTHER_OPTIONS

Besides the right MIB, you need of course support for shared objects. This is enabled with the <code>--enable-shared</code> argument of <code>configure</code>, but should be automatically enabled if your system supports dynamically loaded objects. You can check for support in your agent but looking at the output of the <code>snmpd -H</code> command for the "dlmod" token. If its listed, the compiled agent supports it.

Note: All command line options below assume you have an appropriately setup <code>~/.snmp/snmp.conf</code> file that allows you to not have to specify a SNMP version number, community name, username, or whatever else in order to talk to your agent. The agent, of course, must have a matching <code>/usr/local/share/snmp/snmpd.conf</code> file (or equivalent).

{{TUT:File-Table-Top-and-basics}}
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] || The MIB module's header file
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] || The MIB module's C source code
|}

== Initialization ==

After loading the shared object to memory, the object loader will look for an initialization function inside the shared object. The name of this function is <code>init_name</code>, where "name" is the name of your extension. The name of the example module is "nstAgentPluginObject", so the loader will look for a function with the following prototype:

void init_nstAgentPluginObject (void);

There's a complementary function, called <code>deinit_name</code>, which is called when the module is unloaded, for example when the daemon is shutting down. Unsurprisingly, the prototype of the example deinit-function is:

void deinit_nstAgentPluginObject (void);

These are the only two functions called by the object loaded. All other functions (and module-global variables) therefore should be declared <code>static</code>.

You can check the names of currently loaded modules using the <code>UCD-DLMOD-MIB::dlmodName</code> OID.

== Configuration ==

As mentioned in the introduction, you can register own configuration options which extend the daemon's configuration. To do so, you need to provide two callback functions which are called when appropriate: One that handles a configuration statement, and one that cleans up when necessary. A short example is given below and registers the foobar option:

static const char *global_foobar = NULL;
…
static void config_handle (const char *key, char *value)
{
if (strcasecmp ("foobar", key) == 0)
{
char *tmp = strdup (value);
if (tmp != NULL)
{
free (global_foobar);
global_foobar = tmp;
}
}
else if …
} /* void config_handle */

static void config_free (void)
{
free (global_foobar);
global_foobar = NULL;
}
…
snmpd_register_config_handler ("foobar",
config_handle, config_free,
"The foobar option does something incredible!");

Do not just assign the <code>value</code> pointer to a global variable or dreadful things may happen!

== Writing the module ==

The next steps are basically the same as those steps outlined in [[TUT:Writing a MIB Module|Writing a MIB Module]], i. e. register one or more data sets at some OIDs, for example using the [http://www.net-snmp.org/dev/agent/group__table__dataset.html#ga14 netsnmp_register_table_data_set], see [http://www.net-snmp.org/dev/agent/data__set_8c-example.html the data_set.c example]. Please see [[TUT:Writing a MIB Module|the introductory documentation]].

== Compiling and linking the shared object ==

Building shared objects for Net-SNMP works just like building any other shared object. If you have not done that so far, you should probably read your compilers documentation on the subject. When using the GNU Compiler Collection (GCC), you will most likely need the <code>-fPIC -shared</code> flags.

You should use the <code>net-snmp-config</code> script to determine additional compiler and linker flags. For example:

$ cc `net-snmp-config --cflags` -fPIC -shared -g -O0 -o nstAgentPluginObject.so nstAgentPluginObject.c `net-snmp-config --libs`

You can find example Makefiles at <code>agent/mibgroup/examples/Makefile.dlmod</code> in the source-code distribution and at [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demoapp/Makefile]. Hopefully this'll get you started.

== Steps to test the shared object via runtime MIB configuration ==

# Start the snmpd and watch the dlmod and nstAgentPluginObject modules interact using the debugging flag (this assumes you already have access control set up properly for your agent):
#:% '''snmpd -f -L -DnstAgentPluginObject,dlmod'''
# In another window, test to make sure that the agent doesn't currently support the nstAgentPluginObject (if you get different results running this command you need to recompile the net-snmp agent without the nstAgentPluginObject mib module compiled in directly):
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0'''
#:nstAgentPluginObject.0 = No Such Object available on this agent at this OID
# Then, run snmpset to create a new row in the dlmod table:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i create'''
#:dlmodStatus.1 = create(6)
# See that the row was created:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#:SNMP table: dlmodTable
#:
#:dlmodName dlmodPath dlmodError dlmodStatus
#: unloaded
#Then set the properties of the row up to point to our new object and to give it a name:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodName.1 s "nstAgentPluginObject" UCD-DLMOD-MIB::dlmodPath.1 s "/path/to/nstAgentPluginObject.so" '''
#:dlmodName.1 = "nstAgentPluginObject"
#:dlmodName.1 = "/path/to/nstAgentPluginObject.so"
#:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#: SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so unloaded
#Finally, load the shared object into the running agent:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i load '''
#:dlmodStatus.1 = loaded(1)
#:
#:% snmptable localhost UCD-DLMOD-MIB::dlmodTable
#:SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so loaded
#If everything above was done correctly, then the following command should work and will access the shared object's data:
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0 '''
#: nstAgentPluginObject.0 = INTEGER: 3

== Loading via the snmpd.conf file ==

A more common method of loading the shared object is to instruct the agent to load the extension at startup in the <code>snmpd.conf</code> configuration file. This can be achieved using the <code>dlmod</code> configuration option:

dlmod nstAgentPluginObject /path/to/nstAgentPluginObject.so

The first argument specifies the shared object's module name, the second argument specifies the full pathname of the shared object file. The module name used here must match the name of the initialization function, see [[#Initialization]].

All custom configuration options, as described in [[#Configuration]], must succeed the <code>dlmod</code> statement.

== See also ==

* [[TUT:Writing a MIB Module]]
* [[Net-snmp extensions]] List of extensions, some of which are built as dynamically loaded objects.

{{TUT:LIST}}

TUT:Writing a Dynamically Loadable Object

2009-03-03T21:32:45Z

Octo: /* Compiling and linking the shared object */ Rewrote the section to describe what *really* needs to be done.

This page describes how to build extension for Net-SNMP as shared objects, binary files that can be loaded by the SNMPd daemon directly and are executed as part of the daemon. This differs from the concept introduced in [[TUT:Writing a MIB Module|Writing a MIB Module]] in that the extension resides in its own binary file and is loaded by the agent at runtime. This adds the flexibility to add new functionality / MIBs after the agent has been compiled, enabling you to extent the daemon provided by a binary package without the need to roll your own modified package.

Yet another possibility is offered by Subagents, see [[TUT:Writing a Subagent|Writing a Subagent]]: Subagents are separate processes that do not share memory, file descriptors and so on with the daemon and must use interprocess communication (IPC) to communicate with the daemon.

Writing dynamically loadable objects is interesting because you will have the entire API provided by Net-SNMP at your disposal, for example a caching infrastructure. Shared objects loaded this way usually get their configuration from the same configuration file the core daemon uses, which often is a nice thing. Disadvantages are that a programming mistake in your custom extension may crash the entire daemon and that your code is by design always executed as the same user the core daemon is executed as, i. e. potentially with unnecessary privileges — or too little, depending on your setup.

== Prerequisites ==

While not strictly necessary, you'll probably have an easier time building a shared object if you start with an already functioning MIB module (extension) as described in [[TUT:Writing a MIB Module|Writing a MIB Module]]. This section of the tutorials will assume you have a working extension build directly into the daemon already and tells you how to move that out of the daemon and into a shared object.

For demonstration purposes, we'll refer to some example MIB objects and code: the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mib_module/NET-SNMP-TUTORIAL-MIB.txt NET-SNMP-TUTORIAL-MIB] MIB, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.c example MIB module] and it's [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.h header file].

Note: The <code>dlmod</code> code is based on the <code>UCD-DLMOD-MIB</code>. It resides in the <code>ucdExperimental</code> name-space, but since nothing has changed since 1999 it's pretty safe to assume this interface is stable. You can find the MIB in <code>mibs/UCD-DLMOD-MIB.txt</code> in the source-code distribution.

The Net-SNMP package must have been built with dynamically loadable module support for the following to work. You should therefore enable the UCD MIB when configuring the sources:

$ ./configure --with-mib-modules="ucd_snmp $OTHER_MIBS" $OTHER_OPTIONS

Besides the right MIB, you need of course support for shared objects. This is enabled with the <code>--enable-shared</code> argument of <code>configure</code>, but should be automatically enabled if your system supports dynamically loaded objects. You can check for support in your agent but looking at the output of the <code>snmpd -H</code> command for the "dlmod" token. If its listed, the compiled agent supports it.

Note: All command line options below assume you have an appropriately setup <code>~/.snmp/snmp.conf</code> file that allows you to not have to specify a SNMP version number, community name, username, or whatever else in order to talk to your agent. The agent, of course, must have a matching <code>/usr/local/share/snmp/snmpd.conf</code> file (or equivalent).

{{TUT:File-Table-Top-and-basics}}
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] || The MIB module's header file
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] || The MIB module's C source code
|}

== Initialization ==

After loading the shared object to memory, the object loader will look for an initialization function inside the shared object. The name of this function is <code>init_name</code>, where "name" is the name of your extension. The name of the example module is "nstAgentPluginObject", so the loader will look for a function with the following prototype:

void init_nstAgentPluginObject (void);

There's a complementary function, called <code>deinit_name</code>, which is called when the module is unloaded, for example when the daemon is shutting down. Unsurprisingly, the prototype of the example deinit-function is:

void deinit_nstAgentPluginObject (void);

These are the only two functions called by the object loaded. All other functions (and module-global variables) therefore should be declared <code>static</code>.

You can check the names of currently loaded modules using the <code>UCD-DLMOD-MIB::dlmodName</code> OID.

== Configuration ==

As mentioned in the introduction, you can register own configuration options which extend the daemon's configuration. To do so, you need to provide two callback functions which are called when appropriate: One that handles a configuration statement, and one that cleans up when necessary. A short example is given below and registers the foobar option:

static const char *global_foobar = NULL;
…
static void config_handle (const char *key, char *value)
{
if (strcasecmp ("foobar", key) == 0)
{
char *tmp = strdup (value);
if (tmp != NULL)
{
free (global_foobar);
global_foobar = tmp;
}
}
else if …
} /* void config_handle */

static void config_free (void)
{
free (global_foobar);
global_foobar = NULL;
}
…
snmpd_register_config_handler ("foobar",
config_handle, config_free,
"The foobar option does something incredible!");

Do not just assign the <code>value</code> pointer to a global variable or dreadful things may happen!

== Writing the module ==

The next steps are basically the same as those steps outlined in [[TUT:Writing a MIB Module|Writing a MIB Module]], i. e. register one or more data sets at some OIDs, for example using the [http://www.net-snmp.org/dev/agent/group__table__dataset.html#ga14 netsnmp_register_table_data_set], see [http://www.net-snmp.org/dev/agent/data__set_8c-example.html the data_set.c example]. Please see [[TUT:Writing a MIB Module|the introductory documentation]].

== Compiling and linking the shared object ==

Building shared objects for Net-SNMP works just like building any other shared object. If you have not done that so far, you should probably read your compilers documentation on the subject. When using the GNU Compiler Collection (GCC), you will most likely need the <code>-fPIC -shared</code> flags.

You should use the <code>net-snmp-config</code> script to determine additional compiler and linker flags. For example:

$ cc `net-snmp-config --cflags` -fPIC -shared -g -O0 -o nstAgentPluginObject.so nstAgentPluginObject.c `net-snmp-config --libs`

You can find example Makefiles at <code>agent/mibgroup/examples/Makefile.dlmod</code> in the source-code distribution and at [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demoapp/Makefile]. Hopefully this'll get you started.

== Steps to test the shared object via runtime MIB configuration ==

# Start the snmpd and watch the dlmod and nstAgentPluginObject modules interact using the debugging flag (this assumes you already have access control set up properly for your agent):
#:% '''snmpd -f -L -DnstAgentPluginObject,dlmod'''
# In another window, test to make sure that the agent doesn't currently support the nstAgentPluginObject (if you get different results running this command you need to recompile the net-snmp agent without the nstAgentPluginObject mib module compiled in directly):
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0'''
#:nstAgentPluginObject.0 = No Such Object available on this agent at this OID
# Then, run snmpset to create a new row in the dlmod table:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i create'''
#:dlmodStatus.1 = create(6)
# See that the row was created:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#:SNMP table: dlmodTable
#:
#:dlmodName dlmodPath dlmodError dlmodStatus
#: unloaded
#Then set the properties of the row up to point to our new object and to give it a name:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodName.1 s "nstAgentPluginObject" UCD-DLMOD-MIB::dlmodPath.1 s "/path/to/nstAgentPluginObject.so" '''
#:dlmodName.1 = "nstAgentPluginObject"
#:dlmodName.1 = "/path/to/nstAgentPluginObject.so"
#:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#: SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so unloaded
#Finally, load the shared object into the running agent:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i load '''
#:dlmodStatus.1 = loaded(1)
#:
#:% snmptable localhost UCD-DLMOD-MIB::dlmodTable
#:SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so loaded
#If everything above was done correctly, then the following command should work and will access the shared object's data:
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0 '''
#: nstAgentPluginObject.0 = INTEGER: 3

== Loading via the snmpd.conf file ==

A more common method of loading the shared object is to instruct the agent to load the extension at startup in the <code>snmpd.conf</code> configuration file. This can be achieved using the <code>dlmod</code> configuration option:

dlmod nstAgentPluginObject /path/to/nstAgentPluginObject.so

The first argument specifies the shared object's module name, the second argument specifies the full pathname of the shared object file. The module name used here must match the name of the initialization function, see [[#Initialization]].

All custom configuration options, as described in [[#Configuration]], must succeed the <code>dlmod</code> statement.

{{TUT:LIST}}

TUT:Writing a Dynamically Loadable Object

2009-03-03T21:22:59Z

Octo: /* Loading via the snmpd.conf file */ Improved the "Loading via the snmpd.conf file" section.

This page describes how to build extension for Net-SNMP as shared objects, binary files that can be loaded by the SNMPd daemon directly and are executed as part of the daemon. This differs from the concept introduced in [[TUT:Writing a MIB Module|Writing a MIB Module]] in that the extension resides in its own binary file and is loaded by the agent at runtime. This adds the flexibility to add new functionality / MIBs after the agent has been compiled, enabling you to extent the daemon provided by a binary package without the need to roll your own modified package.

Yet another possibility is offered by Subagents, see [[TUT:Writing a Subagent|Writing a Subagent]]: Subagents are separate processes that do not share memory, file descriptors and so on with the daemon and must use interprocess communication (IPC) to communicate with the daemon.

Writing dynamically loadable objects is interesting because you will have the entire API provided by Net-SNMP at your disposal, for example a caching infrastructure. Shared objects loaded this way usually get their configuration from the same configuration file the core daemon uses, which often is a nice thing. Disadvantages are that a programming mistake in your custom extension may crash the entire daemon and that your code is by design always executed as the same user the core daemon is executed as, i. e. potentially with unnecessary privileges — or too little, depending on your setup.

== Prerequisites ==

While not strictly necessary, you'll probably have an easier time building a shared object if you start with an already functioning MIB module (extension) as described in [[TUT:Writing a MIB Module|Writing a MIB Module]]. This section of the tutorials will assume you have a working extension build directly into the daemon already and tells you how to move that out of the daemon and into a shared object.

For demonstration purposes, we'll refer to some example MIB objects and code: the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mib_module/NET-SNMP-TUTORIAL-MIB.txt NET-SNMP-TUTORIAL-MIB] MIB, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.c example MIB module] and it's [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.h header file].

Note: The <code>dlmod</code> code is based on the <code>UCD-DLMOD-MIB</code>. It resides in the <code>ucdExperimental</code> name-space, but since nothing has changed since 1999 it's pretty safe to assume this interface is stable. You can find the MIB in <code>mibs/UCD-DLMOD-MIB.txt</code> in the source-code distribution.

The Net-SNMP package must have been built with dynamically loadable module support for the following to work. You should therefore enable the UCD MIB when configuring the sources:

$ ./configure --with-mib-modules="ucd_snmp $OTHER_MIBS" $OTHER_OPTIONS

Besides the right MIB, you need of course support for shared objects. This is enabled with the <code>--enable-shared</code> argument of <code>configure</code>, but should be automatically enabled if your system supports dynamically loaded objects. You can check for support in your agent but looking at the output of the <code>snmpd -H</code> command for the "dlmod" token. If its listed, the compiled agent supports it.

Note: All command line options below assume you have an appropriately setup <code>~/.snmp/snmp.conf</code> file that allows you to not have to specify a SNMP version number, community name, username, or whatever else in order to talk to your agent. The agent, of course, must have a matching <code>/usr/local/share/snmp/snmpd.conf</code> file (or equivalent).

{{TUT:File-Table-Top-and-basics}}
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] || The MIB module's header file
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] || The MIB module's C source code
|}

== Initialization ==

After loading the shared object to memory, the object loader will look for an initialization function inside the shared object. The name of this function is <code>init_name</code>, where "name" is the name of your extension. The name of the example module is "nstAgentPluginObject", so the loader will look for a function with the following prototype:

void init_nstAgentPluginObject (void);

There's a complementary function, called <code>deinit_name</code>, which is called when the module is unloaded, for example when the daemon is shutting down. Unsurprisingly, the prototype of the example deinit-function is:

void deinit_nstAgentPluginObject (void);

These are the only two functions called by the object loaded. All other functions (and module-global variables) therefore should be declared <code>static</code>.

You can check the names of currently loaded modules using the <code>UCD-DLMOD-MIB::dlmodName</code> OID.

== Configuration ==

As mentioned in the introduction, you can register own configuration options which extend the daemon's configuration. To do so, you need to provide two callback functions which are called when appropriate: One that handles a configuration statement, and one that cleans up when necessary. A short example is given below and registers the foobar option:

static const char *global_foobar = NULL;
…
static void config_handle (const char *key, char *value)
{
if (strcasecmp ("foobar", key) == 0)
{
char *tmp = strdup (value);
if (tmp != NULL)
{
free (global_foobar);
global_foobar = tmp;
}
}
else if …
} /* void config_handle */

static void config_free (void)
{
free (global_foobar);
global_foobar = NULL;
}
…
snmpd_register_config_handler ("foobar",
config_handle, config_free,
"The foobar option does something incredible!");

Do not just assign the <code>value</code> pointer to a global variable or dreadful things may happen!

== Writing the module ==

The next steps are basically the same as those steps outlined in [[TUT:Writing a MIB Module|Writing a MIB Module]], i. e. register one or more data sets at some OIDs, for example using the [http://www.net-snmp.org/dev/agent/group__table__dataset.html#ga14 netsnmp_register_table_data_set], see [http://www.net-snmp.org/dev/agent/data__set_8c-example.html the data_set.c example]. Please see [[TUT:Writing a MIB Module|the introductory documentation]].

== Steps to build the shared object ==

# First off we must get the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demoapp/Makefile Makefile] file, the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] file, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] file.
# '''make nstAgentPluginObject.so'''

== Steps to test the shared object via runtime MIB configuration ==

# Start the snmpd and watch the dlmod and nstAgentPluginObject modules interact using the debugging flag (this assumes you already have access control set up properly for your agent):
#:% '''snmpd -f -L -DnstAgentPluginObject,dlmod'''
# In another window, test to make sure that the agent doesn't currently support the nstAgentPluginObject (if you get different results running this command you need to recompile the net-snmp agent without the nstAgentPluginObject mib module compiled in directly):
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0'''
#:nstAgentPluginObject.0 = No Such Object available on this agent at this OID
# Then, run snmpset to create a new row in the dlmod table:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i create'''
#:dlmodStatus.1 = create(6)
# See that the row was created:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#:SNMP table: dlmodTable
#:
#:dlmodName dlmodPath dlmodError dlmodStatus
#: unloaded
#Then set the properties of the row up to point to our new object and to give it a name:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodName.1 s "nstAgentPluginObject" UCD-DLMOD-MIB::dlmodPath.1 s "/path/to/nstAgentPluginObject.so" '''
#:dlmodName.1 = "nstAgentPluginObject"
#:dlmodName.1 = "/path/to/nstAgentPluginObject.so"
#:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#: SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so unloaded
#Finally, load the shared object into the running agent:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i load '''
#:dlmodStatus.1 = loaded(1)
#:
#:% snmptable localhost UCD-DLMOD-MIB::dlmodTable
#:SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so loaded
#If everything above was done correctly, then the following command should work and will access the shared object's data:
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0 '''
#: nstAgentPluginObject.0 = INTEGER: 3

== Loading via the snmpd.conf file ==

A more common method of loading the shared object is to instruct the agent to load the extension at startup in the <code>snmpd.conf</code> configuration file. This can be achieved using the <code>dlmod</code> configuration option:

dlmod nstAgentPluginObject /path/to/nstAgentPluginObject.so

The first argument specifies the shared object's module name, the second argument specifies the full pathname of the shared object file. The module name used here must match the name of the initialization function, see [[#Initialization]].

All custom configuration options, as described in [[#Configuration]], must succeed the <code>dlmod</code> statement.

{{TUT:LIST}}

TUT:Writing a Dynamically Loadable Object

2009-03-03T21:15:13Z

Octo: /* Introduction */ Clarified the distinction between built-in and dynamically loaded MIB objects.

This page describes how to build extension for Net-SNMP as shared objects, binary files that can be loaded by the SNMPd daemon directly and are executed as part of the daemon. This differs from the concept introduced in [[TUT:Writing a MIB Module|Writing a MIB Module]] in that the extension resides in its own binary file and is loaded by the agent at runtime. This adds the flexibility to add new functionality / MIBs after the agent has been compiled, enabling you to extent the daemon provided by a binary package without the need to roll your own modified package.

Yet another possibility is offered by Subagents, see [[TUT:Writing a Subagent|Writing a Subagent]]: Subagents are separate processes that do not share memory, file descriptors and so on with the daemon and must use interprocess communication (IPC) to communicate with the daemon.

Writing dynamically loadable objects is interesting because you will have the entire API provided by Net-SNMP at your disposal, for example a caching infrastructure. Shared objects loaded this way usually get their configuration from the same configuration file the core daemon uses, which often is a nice thing. Disadvantages are that a programming mistake in your custom extension may crash the entire daemon and that your code is by design always executed as the same user the core daemon is executed as, i. e. potentially with unnecessary privileges — or too little, depending on your setup.

== Prerequisites ==

While not strictly necessary, you'll probably have an easier time building a shared object if you start with an already functioning MIB module (extension) as described in [[TUT:Writing a MIB Module|Writing a MIB Module]]. This section of the tutorials will assume you have a working extension build directly into the daemon already and tells you how to move that out of the daemon and into a shared object.

For demonstration purposes, we'll refer to some example MIB objects and code: the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mib_module/NET-SNMP-TUTORIAL-MIB.txt NET-SNMP-TUTORIAL-MIB] MIB, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.c example MIB module] and it's [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.h header file].

Note: The <code>dlmod</code> code is based on the <code>UCD-DLMOD-MIB</code>. It resides in the <code>ucdExperimental</code> name-space, but since nothing has changed since 1999 it's pretty safe to assume this interface is stable. You can find the MIB in <code>mibs/UCD-DLMOD-MIB.txt</code> in the source-code distribution.

The Net-SNMP package must have been built with dynamically loadable module support for the following to work. You should therefore enable the UCD MIB when configuring the sources:

$ ./configure --with-mib-modules="ucd_snmp $OTHER_MIBS" $OTHER_OPTIONS

Besides the right MIB, you need of course support for shared objects. This is enabled with the <code>--enable-shared</code> argument of <code>configure</code>, but should be automatically enabled if your system supports dynamically loaded objects. You can check for support in your agent but looking at the output of the <code>snmpd -H</code> command for the "dlmod" token. If its listed, the compiled agent supports it.

Note: All command line options below assume you have an appropriately setup <code>~/.snmp/snmp.conf</code> file that allows you to not have to specify a SNMP version number, community name, username, or whatever else in order to talk to your agent. The agent, of course, must have a matching <code>/usr/local/share/snmp/snmpd.conf</code> file (or equivalent).

{{TUT:File-Table-Top-and-basics}}
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] || The MIB module's header file
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] || The MIB module's C source code
|}

== Initialization ==

After loading the shared object to memory, the object loader will look for an initialization function inside the shared object. The name of this function is <code>init_name</code>, where "name" is the name of your extension. The name of the example module is "nstAgentPluginObject", so the loader will look for a function with the following prototype:

void init_nstAgentPluginObject (void);

There's a complementary function, called <code>deinit_name</code>, which is called when the module is unloaded, for example when the daemon is shutting down. Unsurprisingly, the prototype of the example deinit-function is:

void deinit_nstAgentPluginObject (void);

These are the only two functions called by the object loaded. All other functions (and module-global variables) therefore should be declared <code>static</code>.

You can check the names of currently loaded modules using the <code>UCD-DLMOD-MIB::dlmodName</code> OID.

== Configuration ==

As mentioned in the introduction, you can register own configuration options which extend the daemon's configuration. To do so, you need to provide two callback functions which are called when appropriate: One that handles a configuration statement, and one that cleans up when necessary. A short example is given below and registers the foobar option:

static const char *global_foobar = NULL;
…
static void config_handle (const char *key, char *value)
{
if (strcasecmp ("foobar", key) == 0)
{
char *tmp = strdup (value);
if (tmp != NULL)
{
free (global_foobar);
global_foobar = tmp;
}
}
else if …
} /* void config_handle */

static void config_free (void)
{
free (global_foobar);
global_foobar = NULL;
}
…
snmpd_register_config_handler ("foobar",
config_handle, config_free,
"The foobar option does something incredible!");

Do not just assign the <code>value</code> pointer to a global variable or dreadful things may happen!

== Writing the module ==

The next steps are basically the same as those steps outlined in [[TUT:Writing a MIB Module|Writing a MIB Module]], i. e. register one or more data sets at some OIDs, for example using the [http://www.net-snmp.org/dev/agent/group__table__dataset.html#ga14 netsnmp_register_table_data_set], see [http://www.net-snmp.org/dev/agent/data__set_8c-example.html the data_set.c example]. Please see [[TUT:Writing a MIB Module|the introductory documentation]].

== Steps to build the shared object ==

# First off we must get the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demoapp/Makefile Makefile] file, the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] file, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] file.
# '''make nstAgentPluginObject.so'''

== Steps to test the shared object via runtime MIB configuration ==

# Start the snmpd and watch the dlmod and nstAgentPluginObject modules interact using the debugging flag (this assumes you already have access control set up properly for your agent):
#:% '''snmpd -f -L -DnstAgentPluginObject,dlmod'''
# In another window, test to make sure that the agent doesn't currently support the nstAgentPluginObject (if you get different results running this command you need to recompile the net-snmp agent without the nstAgentPluginObject mib module compiled in directly):
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0'''
#:nstAgentPluginObject.0 = No Such Object available on this agent at this OID
# Then, run snmpset to create a new row in the dlmod table:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i create'''
#:dlmodStatus.1 = create(6)
# See that the row was created:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#:SNMP table: dlmodTable
#:
#:dlmodName dlmodPath dlmodError dlmodStatus
#: unloaded
#Then set the properties of the row up to point to our new object and to give it a name:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodName.1 s "nstAgentPluginObject" UCD-DLMOD-MIB::dlmodPath.1 s "/path/to/nstAgentPluginObject.so" '''
#:dlmodName.1 = "nstAgentPluginObject"
#:dlmodName.1 = "/path/to/nstAgentPluginObject.so"
#:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#: SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so unloaded
#Finally, load the shared object into the running agent:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i load '''
#:dlmodStatus.1 = loaded(1)
#:
#:% snmptable localhost UCD-DLMOD-MIB::dlmodTable
#:SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so loaded
#If everything above was done correctly, then the following command should work and will access the shared object's data:
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0 '''
#: nstAgentPluginObject.0 = INTEGER: 3

== Loading via the snmpd.conf file ==
You can also load shared objects using the "dlmod" token in the snmpd.conf file by putting a line like this in your snmpd.conf file:
dlmod nstAgentPluginObject /path/to/nstAgentPluginObject.so

The first argument specifies the shared object's module name (UCD-DLMOD-MIB::dlmodName) and second argument specifies the full pathname of the shared object file.

{{TUT:LIST}}

TUT:Writing a Dynamically Loadable Object

2009-03-03T21:05:15Z

Octo: /* Prerequisites */ Rephrased much of the section.

This page describes how to build extension for Net-SNMP as shared objects, binary files that can be loaded by the SNMPd daemon directly and are executed as part of the daemon. This differs from the concept of Subagents, see [[TUT:Writing a Subagent|Writing a Subagent]]: Subagents are separate processes that do not share memory, file descriptors and so on with the daemon and must use interprocess communication (IPC) to communicate with the daemon.

Writing dynamically loadable objects is interesting because you will have the entire API provided by Net-SNMP at your disposal, for example a caching infrastructure. Shared objects loaded this way usually get their configuration from the same configuration file the core daemon uses, which often is a nice thing. Disadvantages are that a programming mistake in your custom extension may crash the entire daemon and that your code is by design always executed as the same user the core daemon is executed as, i. e. potentially with unnecessary privileges — or too little, depending on your setup.

== Prerequisites ==

While not strictly necessary, you'll probably have an easier time building a shared object if you start with an already functioning MIB module (extension) as described in [[TUT:Writing a MIB Module|Writing a MIB Module]]. This section of the tutorials will assume you have a working extension build directly into the daemon already and tells you how to move that out of the daemon and into a shared object.

For demonstration purposes, we'll refer to some example MIB objects and code: the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mib_module/NET-SNMP-TUTORIAL-MIB.txt NET-SNMP-TUTORIAL-MIB] MIB, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.c example MIB module] and it's [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.h header file].

Note: The <code>dlmod</code> code is based on the <code>UCD-DLMOD-MIB</code>. It resides in the <code>ucdExperimental</code> name-space, but since nothing has changed since 1999 it's pretty safe to assume this interface is stable. You can find the MIB in <code>mibs/UCD-DLMOD-MIB.txt</code> in the source-code distribution.

The Net-SNMP package must have been built with dynamically loadable module support for the following to work. You should therefore enable the UCD MIB when configuring the sources:

$ ./configure --with-mib-modules="ucd_snmp $OTHER_MIBS" $OTHER_OPTIONS

Besides the right MIB, you need of course support for shared objects. This is enabled with the <code>--enable-shared</code> argument of <code>configure</code>, but should be automatically enabled if your system supports dynamically loaded objects. You can check for support in your agent but looking at the output of the <code>snmpd -H</code> command for the "dlmod" token. If its listed, the compiled agent supports it.

Note: All command line options below assume you have an appropriately setup <code>~/.snmp/snmp.conf</code> file that allows you to not have to specify a SNMP version number, community name, username, or whatever else in order to talk to your agent. The agent, of course, must have a matching <code>/usr/local/share/snmp/snmpd.conf</code> file (or equivalent).

{{TUT:File-Table-Top-and-basics}}
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] || The MIB module's header file
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] || The MIB module's C source code
|}

== Initialization ==

After loading the shared object to memory, the object loader will look for an initialization function inside the shared object. The name of this function is <code>init_name</code>, where "name" is the name of your extension. The name of the example module is "nstAgentPluginObject", so the loader will look for a function with the following prototype:

void init_nstAgentPluginObject (void);

There's a complementary function, called <code>deinit_name</code>, which is called when the module is unloaded, for example when the daemon is shutting down. Unsurprisingly, the prototype of the example deinit-function is:

void deinit_nstAgentPluginObject (void);

These are the only two functions called by the object loaded. All other functions (and module-global variables) therefore should be declared <code>static</code>.

You can check the names of currently loaded modules using the <code>UCD-DLMOD-MIB::dlmodName</code> OID.

== Configuration ==

As mentioned in the introduction, you can register own configuration options which extend the daemon's configuration. To do so, you need to provide two callback functions which are called when appropriate: One that handles a configuration statement, and one that cleans up when necessary. A short example is given below and registers the foobar option:

static const char *global_foobar = NULL;
…
static void config_handle (const char *key, char *value)
{
if (strcasecmp ("foobar", key) == 0)
{
char *tmp = strdup (value);
if (tmp != NULL)
{
free (global_foobar);
global_foobar = tmp;
}
}
else if …
} /* void config_handle */

static void config_free (void)
{
free (global_foobar);
global_foobar = NULL;
}
…
snmpd_register_config_handler ("foobar",
config_handle, config_free,
"The foobar option does something incredible!");

Do not just assign the <code>value</code> pointer to a global variable or dreadful things may happen!

== Writing the module ==

The next steps are basically the same as those steps outlined in [[TUT:Writing a MIB Module|Writing a MIB Module]], i. e. register one or more data sets at some OIDs, for example using the [http://www.net-snmp.org/dev/agent/group__table__dataset.html#ga14 netsnmp_register_table_data_set], see [http://www.net-snmp.org/dev/agent/data__set_8c-example.html the data_set.c example]. Please see [[TUT:Writing a MIB Module|the introductory documentation]].

== Steps to build the shared object ==

# First off we must get the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demoapp/Makefile Makefile] file, the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] file, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] file.
# '''make nstAgentPluginObject.so'''

== Steps to test the shared object via runtime MIB configuration ==

# Start the snmpd and watch the dlmod and nstAgentPluginObject modules interact using the debugging flag (this assumes you already have access control set up properly for your agent):
#:% '''snmpd -f -L -DnstAgentPluginObject,dlmod'''
# In another window, test to make sure that the agent doesn't currently support the nstAgentPluginObject (if you get different results running this command you need to recompile the net-snmp agent without the nstAgentPluginObject mib module compiled in directly):
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0'''
#:nstAgentPluginObject.0 = No Such Object available on this agent at this OID
# Then, run snmpset to create a new row in the dlmod table:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i create'''
#:dlmodStatus.1 = create(6)
# See that the row was created:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#:SNMP table: dlmodTable
#:
#:dlmodName dlmodPath dlmodError dlmodStatus
#: unloaded
#Then set the properties of the row up to point to our new object and to give it a name:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodName.1 s "nstAgentPluginObject" UCD-DLMOD-MIB::dlmodPath.1 s "/path/to/nstAgentPluginObject.so" '''
#:dlmodName.1 = "nstAgentPluginObject"
#:dlmodName.1 = "/path/to/nstAgentPluginObject.so"
#:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#: SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so unloaded
#Finally, load the shared object into the running agent:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i load '''
#:dlmodStatus.1 = loaded(1)
#:
#:% snmptable localhost UCD-DLMOD-MIB::dlmodTable
#:SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so loaded
#If everything above was done correctly, then the following command should work and will access the shared object's data:
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0 '''
#: nstAgentPluginObject.0 = INTEGER: 3

== Loading via the snmpd.conf file ==
You can also load shared objects using the "dlmod" token in the snmpd.conf file by putting a line like this in your snmpd.conf file:
dlmod nstAgentPluginObject /path/to/nstAgentPluginObject.so

The first argument specifies the shared object's module name (UCD-DLMOD-MIB::dlmodName) and second argument specifies the full pathname of the shared object file.

{{TUT:LIST}}

TUT:Writing a Dynamically Loadable Object

2009-03-03T20:38:05Z

Octo: Added section "Configuration".

This page describes how to build extension for Net-SNMP as shared objects, binary files that can be loaded by the SNMPd daemon directly and are executed as part of the daemon. This differs from the concept of Subagents, see [[TUT:Writing a Subagent|Writing a Subagent]]: Subagents are separate processes that do not share memory, file descriptors and so on with the daemon and must use interprocess communication (IPC) to communicate with the daemon.

Writing dynamically loadable objects is interesting because you will have the entire API provided by Net-SNMP at your disposal, for example a caching infrastructure. Shared objects loaded this way usually get their configuration from the same configuration file the core daemon uses, which often is a nice thing. Disadvantages are that a programming mistake in your custom extension may crash the entire daemon and that your code is by design always executed as the same user the core daemon is executed as, i. e. potentially with unnecessary privileges — or too little, depending on your setup.

== Prerequisites ==

First off, you need to write a MIB module first before you can do this part of the tutorial. We assume you have read and completed the [[TUT:Writing_a_MIB_Module | MIB module portion]] of the toolkit tutorial. This part of the tutorial shows how to install a dynamic module into the agent, assuming you already have written a MIB module which we'll then compile into a dynamic module. For example purposes, we'll refer to some example MIB objects and code: the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mib_module/NET-SNMP-TUTORIAL-MIB.txt NET-SNMP-TUTORIAL-MIB] MIB, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.c example MIB module] and it's [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.h header file].

Note: For this to work, you must have compiled the net-snmp package with dynamically loadable module support turned on, as well as built it with <code>--enable-shared</code> turned on. (It's on by default, if your system supports it). You can check for support in your agent but looking at the output of the <code>snmpd -H</code> command for the "dlmod" token. If its listed, the compiled agent supports it.

Note: All command line options below assume you have an appropriately setup <code>~/.snmp/snmp.conf</code> file that allows you to not have to specify a SNMP version number, community name, username, or whatever else in order to talk to your agent. The agent, of course, must have a matching <code>/usr/local/share/snmp/snmpd.conf</code> file (or equivalent).

{{TUT:File-Table-Top-and-basics}}
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] || The MIB module's header file
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] || The MIB module's C source code
|}

== Initialization ==

After loading the shared object to memory, the object loader will look for an initialization function inside the shared object. The name of this function is <code>init_name</code>, where "name" is the name of your extension. The name of the example module is "nstAgentPluginObject", so the loader will look for a function with the following prototype:

void init_nstAgentPluginObject (void);

There's a complementary function, called <code>deinit_name</code>, which is called when the module is unloaded, for example when the daemon is shutting down. Unsurprisingly, the prototype of the example deinit-function is:

void deinit_nstAgentPluginObject (void);

These are the only two functions called by the object loaded. All other functions (and module-global variables) therefore should be declared <code>static</code>.

You can check the names of currently loaded modules using the <code>UCD-DLMOD-MIB::dlmodName</code> OID.

== Configuration ==

As mentioned in the introduction, you can register own configuration options which extend the daemon's configuration. To do so, you need to provide two callback functions which are called when appropriate: One that handles a configuration statement, and one that cleans up when necessary. A short example is given below and registers the foobar option:

static const char *global_foobar = NULL;
…
static void config_handle (const char *key, char *value)
{
if (strcasecmp ("foobar", key) == 0)
{
char *tmp = strdup (value);
if (tmp != NULL)
{
free (global_foobar);
global_foobar = tmp;
}
}
else if …
} /* void config_handle */

static void config_free (void)
{
free (global_foobar);
global_foobar = NULL;
}
…
snmpd_register_config_handler ("foobar",
config_handle, config_free,
"The foobar option does something incredible!");

Do not just assign the <code>value</code> pointer to a global variable or dreadful things may happen!

== Writing the module ==

The next steps are basically the same as those steps outlined in [[TUT:Writing a MIB Module|Writing a MIB Module]], i. e. register one or more data sets at some OIDs, for example using the [http://www.net-snmp.org/dev/agent/group__table__dataset.html#ga14 netsnmp_register_table_data_set], see [http://www.net-snmp.org/dev/agent/data__set_8c-example.html the data_set.c example]. Please see [[TUT:Writing a MIB Module|the introductory documentation]].

== Steps to build the shared object ==

# First off we must get the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demoapp/Makefile Makefile] file, the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] file, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] file.
# '''make nstAgentPluginObject.so'''

== Steps to test the shared object via runtime MIB configuration ==

# Start the snmpd and watch the dlmod and nstAgentPluginObject modules interact using the debugging flag (this assumes you already have access control set up properly for your agent):
#:% '''snmpd -f -L -DnstAgentPluginObject,dlmod'''
# In another window, test to make sure that the agent doesn't currently support the nstAgentPluginObject (if you get different results running this command you need to recompile the net-snmp agent without the nstAgentPluginObject mib module compiled in directly):
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0'''
#:nstAgentPluginObject.0 = No Such Object available on this agent at this OID
# Then, run snmpset to create a new row in the dlmod table:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i create'''
#:dlmodStatus.1 = create(6)
# See that the row was created:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#:SNMP table: dlmodTable
#:
#:dlmodName dlmodPath dlmodError dlmodStatus
#: unloaded
#Then set the properties of the row up to point to our new object and to give it a name:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodName.1 s "nstAgentPluginObject" UCD-DLMOD-MIB::dlmodPath.1 s "/path/to/nstAgentPluginObject.so" '''
#:dlmodName.1 = "nstAgentPluginObject"
#:dlmodName.1 = "/path/to/nstAgentPluginObject.so"
#:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#: SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so unloaded
#Finally, load the shared object into the running agent:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i load '''
#:dlmodStatus.1 = loaded(1)
#:
#:% snmptable localhost UCD-DLMOD-MIB::dlmodTable
#:SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so loaded
#If everything above was done correctly, then the following command should work and will access the shared object's data:
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0 '''
#: nstAgentPluginObject.0 = INTEGER: 3

== Loading via the snmpd.conf file ==
You can also load shared objects using the "dlmod" token in the snmpd.conf file by putting a line like this in your snmpd.conf file:
dlmod nstAgentPluginObject /path/to/nstAgentPluginObject.so

The first argument specifies the shared object's module name (UCD-DLMOD-MIB::dlmodName) and second argument specifies the full pathname of the shared object file.

{{TUT:LIST}}

TUT:Writing a Dynamically Loadable Object

2009-03-03T20:11:15Z

Octo: Added section "Initialization".

This page describes how to build extension for Net-SNMP as shared objects, binary files that can be loaded by the SNMPd daemon directly and are executed as part of the daemon. This differs from the concept of Subagents, see [[TUT:Writing a Subagent|Writing a Subagent]]: Subagents are separate processes that do not share memory, file descriptors and so on with the daemon and must use interprocess communication (IPC) to communicate with the daemon.

Writing dynamically loadable objects is interesting because you will have the entire API provided by Net-SNMP at your disposal, for example a caching infrastructure. Shared objects loaded this way usually get their configuration from the same configuration file the core daemon uses, which often is a nice thing. Disadvantages are that a programming mistake in your custom extension may crash the entire daemon and that your code is by design always executed as the same user the core daemon is executed as, i. e. potentially with unnecessary privileges — or too little, depending on your setup.

== Prerequisites ==

First off, you need to write a MIB module first before you can do this part of the tutorial. We assume you have read and completed the [[TUT:Writing_a_MIB_Module | MIB module portion]] of the toolkit tutorial. This part of the tutorial shows how to install a dynamic module into the agent, assuming you already have written a MIB module which we'll then compile into a dynamic module. For example purposes, we'll refer to some example MIB objects and code: the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mib_module/NET-SNMP-TUTORIAL-MIB.txt NET-SNMP-TUTORIAL-MIB] MIB, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.c example MIB module] and it's [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.h header file].

Note: For this to work, you must have compiled the net-snmp package with dynamically loadable module support turned on, as well as built it with <code>--enable-shared</code> turned on. (It's on by default, if your system supports it). You can check for support in your agent but looking at the output of the <code>snmpd -H</code> command for the "dlmod" token. If its listed, the compiled agent supports it.

Note: All command line options below assume you have an appropriately setup <code>~/.snmp/snmp.conf</code> file that allows you to not have to specify a SNMP version number, community name, username, or whatever else in order to talk to your agent. The agent, of course, must have a matching <code>/usr/local/share/snmp/snmpd.conf</code> file (or equivalent).

{{TUT:File-Table-Top-and-basics}}
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] || The MIB module's header file
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] || The MIB module's C source code
|}

== Initialization ==

After loading the shared object to memory, the object loader will look for an initialization function inside the shared object. The name of this function is <code>init_name</code>, where "name" is the name of your extension. The name of the example module is "nstAgentPluginObject", so the loader will look for a function with the following prototype:

void init_nstAgentPluginObject (void);

There's a complementary function, called <code>deinit_name</code>, which is called when the module is unloaded, for example when the daemon is shutting down. Unsurprisingly, the prototype of the example deinit-function is:

void deinit_nstAgentPluginObject (void);

These are the only two functions called by the object loaded. All other functions (and module-global variables) therefore should be declared <code>static</code>.

You can check the names of currently loaded modules using the <code>UCD-DLMOD-MIB::dlmodName</code> OID.

== Steps to build the shared object ==

# First off we must get the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demoapp/Makefile Makefile] file, the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] file, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] file.
# '''make nstAgentPluginObject.so'''

== Steps to test the shared object via runtime MIB configuration ==

# Start the snmpd and watch the dlmod and nstAgentPluginObject modules interact using the debugging flag (this assumes you already have access control set up properly for your agent):
#:% '''snmpd -f -L -DnstAgentPluginObject,dlmod'''
# In another window, test to make sure that the agent doesn't currently support the nstAgentPluginObject (if you get different results running this command you need to recompile the net-snmp agent without the nstAgentPluginObject mib module compiled in directly):
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0'''
#:nstAgentPluginObject.0 = No Such Object available on this agent at this OID
# Then, run snmpset to create a new row in the dlmod table:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i create'''
#:dlmodStatus.1 = create(6)
# See that the row was created:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#:SNMP table: dlmodTable
#:
#:dlmodName dlmodPath dlmodError dlmodStatus
#: unloaded
#Then set the properties of the row up to point to our new object and to give it a name:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodName.1 s "nstAgentPluginObject" UCD-DLMOD-MIB::dlmodPath.1 s "/path/to/nstAgentPluginObject.so" '''
#:dlmodName.1 = "nstAgentPluginObject"
#:dlmodName.1 = "/path/to/nstAgentPluginObject.so"
#:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#: SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so unloaded
#Finally, load the shared object into the running agent:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i load '''
#:dlmodStatus.1 = loaded(1)
#:
#:% snmptable localhost UCD-DLMOD-MIB::dlmodTable
#:SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so loaded
#If everything above was done correctly, then the following command should work and will access the shared object's data:
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0 '''
#: nstAgentPluginObject.0 = INTEGER: 3

== Loading via the snmpd.conf file ==
You can also load shared objects using the "dlmod" token in the snmpd.conf file by putting a line like this in your snmpd.conf file:
dlmod nstAgentPluginObject /path/to/nstAgentPluginObject.so

The first argument specifies the shared object's module name (UCD-DLMOD-MIB::dlmodName) and second argument specifies the full pathname of the shared object file.

{{TUT:LIST}}

TUT:Writing a Dynamically Loadable Object

2009-03-03T20:00:50Z

Octo: Wrote an introduction to the tutorial, so the user knows what's expecting her.

This page describes how to build extension for Net-SNMP as shared objects, binary files that can be loaded by the SNMPd daemon directly and are executed as part of the daemon. This differs from the concept of Subagents, see [[TUT:Writing a Subagent|Writing a Subagent]]: Subagents are separate processes that do not share memory, file descriptors and so on with the daemon and must use interprocess communication (IPC) to communicate with the daemon.

Writing dynamically loadable objects is interesting because you will have the entire API provided by Net-SNMP at your disposal, for example a caching infrastructure. Shared objects loaded this way usually get their configuration from the same configuration file the core daemon uses, which often is a nice thing. Disadvantages are that a programming mistake in your custom extension may crash the entire daemon and that your code is by design always executed as the same user the core daemon is executed as, i. e. potentially with unnecessary privileges — or too little, depending on your setup.

== Prerequisites ==

First off, you need to write a MIB module first before you can do this part of the tutorial. We assume you have read and completed the [[TUT:Writing_a_MIB_Module | MIB module portion]] of the toolkit tutorial. This part of the tutorial shows how to install a dynamic module into the agent, assuming you already have written a MIB module which we'll then compile into a dynamic module. For example purposes, we'll refer to some example MIB objects and code: the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mib_module/NET-SNMP-TUTORIAL-MIB.txt NET-SNMP-TUTORIAL-MIB] MIB, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.c example MIB module] and it's [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.h header file].

Note: For this to work, you must have compiled the net-snmp package with dynamically loadable module support turned on, as well as built it with <code>--enable-shared</code> turned on. (It's on by default, if your system supports it). You can check for support in your agent but looking at the output of the <code>snmpd -H</code> command for the "dlmod" token. If its listed, the compiled agent supports it.

Note: All command line options below assume you have an appropriately setup <code>~/.snmp/snmp.conf</code> file that allows you to not have to specify a SNMP version number, community name, username, or whatever else in order to talk to your agent. The agent, of course, must have a matching <code>/usr/local/share/snmp/snmpd.conf</code> file (or equivalent).

{{TUT:File-Table-Top-and-basics}}
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] || The MIB module's header file
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] || The MIB module's C source code
|}

The shared object loader calls the "<code>init_nstAgentPluginObject()</code>" function in the above code when it gets loaded, and calls the "<code>deinit_nstAgentPluginObject()</code>" when (and if) the module is unloaded. These function names to use are built by adding the shared object's module name (<code>UCD-DLMOD-MIB::dlmodName</code>) to the "<code>init_</code>" and "<code>deinit_</code>" prefixes.

== Steps to build the shared object ==

# First off we must get the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demoapp/Makefile Makefile] file, the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] file, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] file.
# '''make nstAgentPluginObject.so'''

== Steps to test the shared object via runtime MIB configuration ==

# Start the snmpd and watch the dlmod and nstAgentPluginObject modules interact using the debugging flag (this assumes you already have access control set up properly for your agent):
#:% '''snmpd -f -L -DnstAgentPluginObject,dlmod'''
# In another window, test to make sure that the agent doesn't currently support the nstAgentPluginObject (if you get different results running this command you need to recompile the net-snmp agent without the nstAgentPluginObject mib module compiled in directly):
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0'''
#:nstAgentPluginObject.0 = No Such Object available on this agent at this OID
# Then, run snmpset to create a new row in the dlmod table:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i create'''
#:dlmodStatus.1 = create(6)
# See that the row was created:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#:SNMP table: dlmodTable
#:
#:dlmodName dlmodPath dlmodError dlmodStatus
#: unloaded
#Then set the properties of the row up to point to our new object and to give it a name:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodName.1 s "nstAgentPluginObject" UCD-DLMOD-MIB::dlmodPath.1 s "/path/to/nstAgentPluginObject.so" '''
#:dlmodName.1 = "nstAgentPluginObject"
#:dlmodName.1 = "/path/to/nstAgentPluginObject.so"
#:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#: SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so unloaded
#Finally, load the shared object into the running agent:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i load '''
#:dlmodStatus.1 = loaded(1)
#:
#:% snmptable localhost UCD-DLMOD-MIB::dlmodTable
#:SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so loaded
#If everything above was done correctly, then the following command should work and will access the shared object's data:
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0 '''
#: nstAgentPluginObject.0 = INTEGER: 3

== Loading via the snmpd.conf file ==
You can also load shared objects using the "dlmod" token in the snmpd.conf file by putting a line like this in your snmpd.conf file:
dlmod nstAgentPluginObject /path/to/nstAgentPluginObject.so

The first argument specifies the shared object's module name (UCD-DLMOD-MIB::dlmodName) and second argument specifies the full pathname of the shared object file.

{{TUT:LIST}}

TUT:Writing a Dynamically Loadable Object

2009-03-03T19:44:50Z

Octo: Improve markup in the introduction.

First off, you need to write a MIB module first before you can do this part of the tutorial. We assume you have read and completed the [[TUT:Writing_a_MIB_Module | MIB module portion]] of the toolkit tutorial. This part of the tutorial shows how to install a dynamic module into the agent, assuming you already have written a MIB module which we'll then compile into a dynamic module. For example purposes, we'll refer to some example MIB objects and code: the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mib_module/NET-SNMP-TUTORIAL-MIB.txt NET-SNMP-TUTORIAL-MIB] MIB, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.c example MIB module] and it's [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/nstAgentSubagentObject.h header file].

Note: For this to work, you must have compiled the net-snmp package with dynamically loadable module support turned on, as well as built it with <code>--enable-shared</code> turned on. (It's on by default, if your system supports it). You can check for support in your agent but looking at the output of the <code>snmpd -H</code> command for the "dlmod" token. If its listed, the compiled agent supports it.

Note: All command line options below assume you have an appropriately setup <code>~/.snmp/snmp.conf</code> file that allows you to not have to specify a SNMP version number, community name, username, or whatever else in order to talk to your agent. The agent, of course, must have a matching <code>/usr/local/share/snmp/snmpd.conf</code> file (or equivalent).

{{TUT:File-Table-Top-and-basics}}
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] || The MIB module's header file
|-
| [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] || The MIB module's C source code
|}

The shared object loader calls the "<code>init_nstAgentPluginObject()</code>" function in the above code when it gets loaded, and calls the "<code>deinit_nstAgentPluginObject()</code>" when (and if) the module is unloaded. These function names to use are built by adding the shared object's module name (<code>UCD-DLMOD-MIB::dlmodName</code>) to the "<code>init_</code>" and "<code>deinit_</code>" prefixes.

=== Steps to build the shared object ===

# First off we must get the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demoapp/Makefile Makefile] file, the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.h nstAgentPluginObject.h] file, and the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/dlmod/nstAgentPluginObject.c nstAgentPluginObject.c] file.
# '''make nstAgentPluginObject.so'''

=== Steps to test the shared object via runtime MIB configuration ===

# Start the snmpd and watch the dlmod and nstAgentPluginObject modules interact using the debugging flag (this assumes you already have access control set up properly for your agent):
#:% '''snmpd -f -L -DnstAgentPluginObject,dlmod'''
# In another window, test to make sure that the agent doesn't currently support the nstAgentPluginObject (if you get different results running this command you need to recompile the net-snmp agent without the nstAgentPluginObject mib module compiled in directly):
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0'''
#:nstAgentPluginObject.0 = No Such Object available on this agent at this OID
# Then, run snmpset to create a new row in the dlmod table:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i create'''
#:dlmodStatus.1 = create(6)
# See that the row was created:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#:SNMP table: dlmodTable
#:
#:dlmodName dlmodPath dlmodError dlmodStatus
#: unloaded
#Then set the properties of the row up to point to our new object and to give it a name:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodName.1 s "nstAgentPluginObject" UCD-DLMOD-MIB::dlmodPath.1 s "/path/to/nstAgentPluginObject.so" '''
#:dlmodName.1 = "nstAgentPluginObject"
#:dlmodName.1 = "/path/to/nstAgentPluginObject.so"
#:
#:% '''snmptable localhost UCD-DLMOD-MIB::dlmodTable '''
#: SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so unloaded
#Finally, load the shared object into the running agent:
#:% '''snmpset localhost UCD-DLMOD-MIB::dlmodStatus.1 i load '''
#:dlmodStatus.1 = loaded(1)
#:
#:% snmptable localhost UCD-DLMOD-MIB::dlmodTable
#:SNMP table: dlmodTable
#:
#: dlmodName dlmodPath dlmodError dlmodStatus
#: nstAgentPluginObject /path/to/nstAgentPluginObject.so loaded
#If everything above was done correctly, then the following command should work and will access the shared object's data:
#:% '''snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentPluginObject.0 '''
#: nstAgentPluginObject.0 = INTEGER: 3

=== Loading via the snmpd.conf file ===
You can also load shared objects using the "dlmod" token in the snmpd.conf file by putting a line like this in your snmpd.conf file:
dlmod nstAgentPluginObject /path/to/nstAgentPluginObject.so

The first argument specifies the shared object's module name (UCD-DLMOD-MIB::dlmodName) and second argument specifies the full pathname of the shared object file.

{{TUT:LIST}}