TUT:Writing a MIB Module

From Net-SNMP Wiki

Here we discuss how to write a simple mib module, to extend the agent using C code.

The 5.0 net-snmp agent is designed to give the mib module writer an easier task when it comes to writing mib code. To do this, it provides some "helper" modules that you can make use of to suit your specific needs. The net-snmp agent handles things in "chains" of these helpers, and you can add helpers to your calling chain to do things for you.

Contents 1 MIBs For Dummies and mib2c 2 A simple scalar attached to a variable 3 A simple scalar with the value returned from code 4 A table of data, stored within the agent 5 Sending SNMP notifications (traps and informs) from inside the agent. 6 The older (and thus backward compatible) ucd-snmp 4.X API 7 The MIB Module API 8 Compiling in your new MIB module 9 Set Processing 10 Tutorial Sections

MIBs For Dummies and mib2c

Here is tutorial on using mib2c and mib2c.mfd.conf (XXX: convert to wiki) to generate a code template for a table.

A simple scalar attached to a variable

Here is some example code that describes how to implement a simple, single scalar which is based on a variable.

A simple scalar with the value returned from code

Here is some example code 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 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 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 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 here.

The MIB Module API

The new API is documented more completely here. Additionally, see the complete list of (mostly) documented available helpers and other information here.

Compiling in your new MIB module

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 NET-SNMP-TUTORIAL-MIB MIB. To see how MIBs can be properly used by the tools, please see the mib-options tutorial.

1. Compile it into the master agent.

Lets assume you're going to compile in a new mib module. For our example, lets use the example mib module and it's 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
   

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

 % /usr/local/sbin/snmpd
   

And then running snmpget and snmpset on the scalar object [proper authentication information not shown in this command]:

 % snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentModuleObject.0
 NET-SNMP-TUTORIAL-MIB::nstAgentModuleObject.0 = INTEGER: 1
 
 % snmpset localhost NET-SNMP-TUTORIAL-MIB::nstAgentModuleObject.0 = 5
 NET-SNMP-TUTORIAL-MIB::nstAgentModuleObject.0 = INTEGER: 5
 
 % snmpget 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 the AgentX subagent protocol. Our libraries provide support to make this easy to do and this is discussed in greater detail in 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 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:

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.

Tutorial Sections

• Command Line Applications
  • snmptranslate: learning about the MIB tree.
  • snmpget: retrieving data from a host.
  • snmpgetnext: retrieving unknown indexed data.
  • snmpwalk: retrieving lots of data at once!
  • snmptable: displaying a table.
  • snmpset: peforming write operations.
  • snmpbulkget: communicates with a network entity using SNMP GETBULK request
  • snmpbulkwalk: retrieve a sub-tree of management values using SNMP GETBULK requests.
  • snmptrap: Sending and receiving traps, and acting upon them.
    • Traps/informs with SNMPv3: Sending and receiving SNMPv3 TRAPs and INFORMs
  • Common command line options:
    • Using and loading MIBS
    • SNMPv3 Options
    • Customized Output Formats
  • Writing mib2c config files
• SNMP Daemons
  • SNMP Agent (snmpd) Configuration
    • Configuration Basics
    • Access Control (VACM)
    • snmpconf
  • SNMP Notification Receiver (snmptrapd)
    • Configuring snmptrapd
    • Configuring SNMPv3 notifications
    • Configuring snmptrapd to understand vendor-specific MIBS (Cisco)
  • Agent Monitoring
    • DisMan Monitoring
    • Monitoring with MRTG
• Coding Tutorials
  • Client / Manager Coding Tutorials
    • Writing a simple application
    • Writing a simple asynchronous application
  • Agent Coding Tutorials
    • Writing a mib module to serve information described by an SNMP MIB, and how to compile it into the net-snmp snmpd agent.
    • Writing a Dynamically Loadable Object that can be loaded into the SNMP agent.
    • Writing a Subagent that can be run to attach to the snmpd master agent.
    • Writing a perl plugin to extend the agent using the NetSNMP::agent module.
    • Using mib2c to help write an agent code template for you
      • General mib2c Overview
      • Using the mib2c-update script to recode your code
      • mib2c.mfd.conf tutorial
  • Header files and autoconf
  • Building With Visual Studio 2005 Express
    • Using the command line and nmake
  • Debugging SNMP Applications and Agent's
    • Debugging output printed using the -D command line option
      • Putting DEBUGMSG tokens in your code
    • Using -Ddump to display packet breakdowns
    • Debugging using GDB