Magfr: Created page with "This page is the first in a series to guide you through the creation of custom extensions to the core Net-SNMP daemon, usually called an SNMP "agent". In this article we will..."

2023-09-12T05:36:23Z

Created page with "This page is the first in a series to guide you through the creation of custom extensions to the core Net-SNMP daemon, usually called an SNMP "agent". In this article we will..."

New page

This page is the first in a series to guide you through the creation of custom extensions to the core Net-SNMP daemon, usually called an SNMP "agent". In this article we will describe how to build your extension into the daemon. The two following articles will describe how to put your changes into a shared object (see [[TUT:Writing a Dynamically Loadable Object|Writing a Dynamically Loadable Object]]) and a separate daemon (see [[TUT:Writing a Subagent|Writing a Subagent]]).

Extensions (or "MIB modules") usually make use of the API provided by Net-SNMP and are therefore written in C. For instructions on writing extensions in Perl, please read [[Tut:Extending snmpd using perl|Extending SNMPd using Perl]].

== The "Big Picture" ==

The main task of custom extensions is to register a callback function which handles requests for a specific [[OID]]. Version 5.0 of the Net-SNMP agent tries to make this task as easy as possible by providing so called [[Agent Helpers|helper modules]]. Each request is handled in a chain in Net-SNMP, as described in the [[Agent Architecture]]. You can inject helper modules into this chain, so that helper modules are called before control reaches the actual callback function. This can, for example, be used to install a cache in front of the actual data acquisition, which may be costly.

== Recommended Reading List ==

It is most helpful if you have the time to read through some documentation that describes how the Net-SNMP agent architecture works. Thus, if you're starting from scratch, the suggested reading order for information about the agent is:

* The [[Agent Architecture]] describes the internals of the agent, and how the ''handler'' system works.
* The [[Agent Helpers]] list describes the available MIB helpers available, which will be used in detail below.
* The rest of the tutorial below where you actually get to play with some code.

Can you skip some things on this list and jump straight to the real-code below? Absolutely! But you'll probably regret it later.

== Writing Your First Module ==

We will now walk you through the process of developing increasingly more complex MIB objects, beginning with a scalar, then a table, persistent data, notifications, and so on.

=== MIBs For Dummies and mib2c ===

Writing modules for MIBs is a long and sometimes troublesome process, much like writing a parser. And just like writing a parser, you don't have to do everything by hand: MIBs can already be processed by computers pretty well, so there is no need to start from square one every time. The tool to convert an existing MIB to some C code is called mib2c and is part of the Net-SNMP distribution. There is a [[MIB for Dummies]] tutorial on using [[mib2c]] and ''{{code|local/mib2c.mfd.conf}}'' to generate a code template for a table.

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

The first example, [http://www.net-snmp.org/dev/agent/scalar__int_8c-example.html scalar_int.c], only consists of an initialization function, <code>init_scalar_int</code>, which registers the module-global integer <code>example1</code> with the SNMP agent (aka. "daemon"). The prototype and name of the initialization function must follow this schema:

void init_module_name (void);

In the example code, the module's name is "scalar_int", hence the name of the initialization function.

Within the initialization function, the API function [http://www.net-snmp.org/dev/agent/group__instance.html#ga20 netsnmp_register_int_instance] is called to actually register the integer at a specified OID. The prototype of that API function is:

int netsnmp_register_int_instance (const char *name,
oid *reg_oid,
size_t reg_oid_len,
int *it,
Netsnmp_Node_Handler *subhandler);

The first argument, name, is a the short description of the object being registered. The second argument is the OID to assign to this object — the length of the OID is stored in the third argument. It is recommended to use the <code>OID_LENGTH</code> macro which will only work with statically allocated OIDs (arrays work, pointers don't).

For the sake of simplicity the default subhandler is used in the example code, therefore <code>NULL</code> is passed as fifth argument. The default handler allows the integer to be read with a <code>GET</code> request as well as set with a <code>SET</code> request.

Simple integer registration functions, including read-only registration and the default handlers, are declared in <code>agent/instance.h</code>.

=== A simple scalar with the value returned from code ===

Here is [http://www.net-snmp.org/dev/agent/delayed__instance_8c-example.html some example code about writing a MIB Module] that describes how to implement a generic instance (not tied to a variable, like the above example) as well as how to delay answering queries for a bit (in the example, an alarm is set to add a delay to the answer).

=== A table of data, stored within the agent ===

Here is [http://www.net-snmp.org/dev/agent/data__set_8c-example.html a more complex example] that implements a table, where the table data is completely contained within the agent.

=== Sending SNMP notifications (traps and informs) from inside the agent. ===

Here is [http://www.net-snmp.org/dev/agent/notification_8c-example.html an example of how to use the agent's internal notification sending API] to send a notification to all of the agent's trap receivers.

=== The older (and thus most backward compatible) ucd-snmp 4.X API ===

Of course, you can continue to write code using the older API set. A tutorial on it can be found [http://www.net-snmp.org/tutorial/tutorial-4/toolkit/mib_module/ here].

== The MIB Module API ==

The new API is documented more completely [http://www.net-snmp.org/dev/agent/group__handler.html here]. Additionally, see the complete list of (mostly) documented available helpers and other information [http://www.net-snmp.org/tutorial/tutorial-4/toolkit/mib_module/ here].

== Compiling in your new MIB module ==

'''Note: you will need to have previously installed the Net-SNMP Source Package on your system before proceeding.'''

There are a few ways to get your new MIB module loaded and accessible via SNMP requests. We'll discuss all three ways separately. To make this easy to test the procedures outlined below, we've provided three simple mib modules which implement the three simple scalars in the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mib_module/NET-SNMP-TUTORIAL-MIB.txt NET-SNMP-TUTORIAL-MIB] MIB. To see how MIBs can be properly used by the tools, please see the [[TUT:Using_and_loading_mibs | mib-options tutorial]].

#; Compile it into the master agent.

Lets assume you're going to compile in a new mib module. For our example, lets use the [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mib_module/nstAgentModuleObject.c example mib module] and it's [http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mib_module/nstAgentModuleObject.h header file]. To do this, you would put the nstAgentModuleObject.h and nstAgentModuleObject.c files into the net-snmp source code directory. You do this by copying them into a agent/mibgroup/nstAgentModuleObject.h and agent/mibgroup/nstAgentModuleObject.c file.

Next, you have to configure the package to find them and compile them into the agent. To do this, you run the configure script giving it the extra module names you want it to load:

% '''./configure --with-mib-modules="nstAgentModuleObject"'''

If you had multiple modules to include (like a second "XXX" module, for example), you can separate them with spaces inside the quotes (e.g., --with-mib-modules="nstAgentModuleObject XXX").

Note that nstAgentModuleObject is the prefix and the configure script will actually look for a nstAgentModuleObject.h and a nstAgentModuleObject.c file. You must have a .h file and you can not get it to work with just a .c file.

Build your new agent with your new code in it by running make:

% '''make'''

Finally, install the whole lot by running make install:

% '''make install'''

Now that the agent is installed, you need to add some basic configuration (see other tutorials for
more configuration options). Here we just add a simple read-only and read-write community strings
(''tutget'' and ''tutset'', respectively) for the tutorial MIB branch:

% '''echo "rocommunity tutget 127.0.0.1 .1.3.6.1.4.1.8072.2.4" >> /usr/local/etc/snmp/snmpd.conf'''
% '''echo "rwcommunity tutset 127.0.0.1 .1.3.6.1.4.1.8072.2.4" >> /usr/local/etc/snmp/snmpd.conf'''

You can test out the functionality by starting the snmpd agent:

% '''/usr/local/sbin/snmpd -f -L -d'''

Incoming and outgoing packets are printed (-d), to show what's happening, and the agent is run as a 'non-daemon' command (-f -L) so that you can see these messages. Note that this ties up the current shell, so you'll need to run the following checks in a different terminal window.

And then running snmpget and snmpset on the scalar object:

% '''snmpget -v2c -c tutget localhost NET-SNMP-TUTORIAL-MIB::nstAgentModuleObject.0'''
NET-SNMP-TUTORIAL-MIB::nstAgentModuleObject.0 = INTEGER: 1

% '''snmpset -v2c -c tutset localhost NET-SNMP-TUTORIAL-MIB::nstAgentModuleObject.0 = 5'''
NET-SNMP-TUTORIAL-MIB::nstAgentModuleObject.0 = INTEGER: 5

% '''snmpget -v2c -c tutget localhost NET-SNMP-TUTORIAL-MIB::nstAgentModuleObject.0'''
NET-SNMP-TUTORIAL-MIB::nstAgentModuleObject.0 = INTEGER: 5

You can also compile your code into a "subagent" which then attaches itself to the master agent using [http://www.scguild.com/agentx/ the AgentX subagent protocol]. Our libraries provide support to make this easy to do and this is discussed in greater detail in [[TUT:Writing_a_Subagent | a later section]].

Finally, you can also compile your code into pluggable shared object and tell the snmpd agent to load it. This is also discussed in greater detail in [[TUT:Writing_a_Dynamically_Loadable_Object | a later section ]].

== Set Processing ==

To process an SNMP-SET, the agent must use a series of calls to the mib module code to ensure that processing of all sets in the incoming packet can be successful. This gives you or other mib modules the chance to bail out early on in the transaction sequence and thus stop all of the transactions in the set from happening. This is important for continuity. However, it makes set code processing a bit more complex. Let's examine a simple state diagram that the master agent uses at each step of the way:

[[Image:set-actions.jpg]]

In a perfect operation with no failures, we take the vertical path on the left. If any of the mib modules being acted upon returns an error of any kind, we will branch to the right to one of the failure states where you must clean up and possibly undo what you did in previous steps.

If you need even finer-grained SET processing with even more states, check out the [[baby_steps]] [[Agent Helpers|helper]] module.

{{TUT:LIST}}

TUT:Writing a MIB Module - Revision history

Magfr: Created page with "This page is the first in a series to guide you through the creation of custom extensions to the core Net-SNMP daemon, usually called an SNMP "agent". In this article we will..."