tut_writing a mib module - net-snmp wiki
TRANSCRIPT
15/08/13 TUT:Writing a MIB Module - Net-SNMP Wiki
www.net-snmp.org/wiki/index.php/TUT:Writing_a_MIB_Module 1/7
TUT:Writing a MIB Module
From Net-SNMP Wiki
This page is the first in a series to guide you through the creation of custom extensions to the core Net-SNMPdaemon, usually called an SNMP "agent". In this article we will describe how to build your extension into thedaemon. The two following articles will describe how to put your changes into a shared object (see Writing aDynamically Loadable Object) and a separate daemon (see Writing a Subagent).
Extensions (or "MIB modules") usually make use of the API provided by Net-SNMP and are therefore writtenin C. For instructions on writing extensions in Perl, please read Extending SNMPd using Perl.
Contents
1 The "Big Picture"
2 Recommended Reading List3 Writing Your First Module
3.1 MIBs For Dummies and mib2c
3.2 A simple scalar attached to a variable3.3 A simple scalar with the value returned from code
3.4 A table of data, stored within the agent
3.5 Sending SNMP notifications (traps and informs) from inside the agent.
3.6 The older (and thus most backward compatible) ucd-snmp 4.X API
4 The MIB Module API
5 Compiling in your new MIB module6 Set Processing
7 Tutorial Sections7.1 About the SNMP Protocol
7.2 Net-SNMP Command Line Applications7.3 Application Configuration
7.4 Net-SNMP Daemons
7.5 Coding Tutorials
7.6 Debugging SNMP Applications and Agents
7.7 Operating System Specific Tutorials
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 helpermodules. Each request is handled in a chain in Net-SNMP, as described in the Agent Architecture. You caninject helper modules into this chain, so that helper modules are called before control reaches the actualcallback function. This can, for example, be used to install a cache in front of the actual data acquisition, whichmay be costly.
15/08/13 TUT:Writing a MIB Module - Net-SNMP Wiki
www.net-snmp.org/wiki/index.php/TUT:Writing_a_MIB_Module 2/7
Recommended Reading List
It is most helpful if you have the time to read through some documentation that describes how the Net-SNMPagent architecture works. Thus, if you're starting from scratch, the suggested reading order for information aboutthe 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 probablyregret it later.
Writing Your First Module
We will now walk you through the process of developing increasingly more complex MIB objects, beginningwith 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 justlike writing a parser, you don't have to do everything by hand: MIBs can already be processed by computerspretty well, so there is no need to start from square one every time. The tool to convert an existing MIB to someC code is called mib2c and is part of the Net-SNMP distribution. There is a MIB for Dummies tutorial on usingmib2c and local/mib2c.mfd.conf (http://net-snmp.git.sourceforge.net/git/gitweb.cgi?p=net-snmp/net-snmp;a=blob_plain;f=local/mib2c.mfd.conf;hb=HEAD) to generate a code template for a table.
A simple scalar attached to a variable
The first example, scalar_int.c (http://www.net-snmp.org/dev/agent/scalar__int_8c-example.html) , only consistsof an initialization function, init_scalar_int, which registers the module-global integer example1 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 netsnmp_register_int_instance (http://www.net-snmp.org/dev/agent/group__instance.html#ga20) is called to actually register the integer at a specified OID. Theprototype 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 theOID to assign to this object — the length of the OID is stored in the third argument. It is recommended to usethe OID_LENGTH macro which will only work with statically allocated OIDs (arrays work, pointers don't).
15/08/13 TUT:Writing a MIB Module - Net-SNMP Wiki
www.net-snmp.org/wiki/index.php/TUT:Writing_a_MIB_Module 3/7
For the sake of simplicity the default subhandler is used in the example code, therefore NULL is passed as fifth
argument. The default handler allows the integer to be read with a GET request as well as set with a SET request.
Simple integer registration functions, including read-only registration and the default handlers, are declared inagent/instance.h.
A simple scalar with the value returned from code
Here is some example code about writing a MIB Module (http://www.net-snmp.org/dev/agent/delayed__instance_8c-example.html) 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 theexample, 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 (http://www.net-snmp.org/dev/agent/data__set_8c-example.html) thatimplements 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 (http://www.net-snmp.org/dev/agent/notification_8c-example.html) 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 here(http://www.net-snmp.org/tutorial/tutorial-4/toolkit/mib_module/) .
The MIB Module API
The new API is documented more completely here (http://www.net-snmp.org/dev/agent/group__handler.html) .Additionally, see the complete list of (mostly) documented available helpers and other information here(http://www.net-snmp.org/tutorial/tutorial-4/toolkit/mib_module/) .
Compiling in your new MIB module
Note: you will need to have previously installed the Net-SNMP Source Package on your systembefore proceeding.
There are a few ways to get your new MIB module loaded and accessible via SNMP requests. We'll discuss allthree ways separately. To make this easy to test the procedures outlined below, we've provided three simplemib modules which implement the three simple scalars in the NET-SNMP-TUTORIAL-MIB (http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mib_module/NET-SNMP-TUTORIAL-MIB.txt) MIB. To see how MIBscan 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(http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mib_module/nstAgentModuleObject.c) and it's header file(http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mib_module/nstAgentModuleObject.h) . To do this, you
15/08/13 TUT:Writing a MIB Module - Net-SNMP Wiki
www.net-snmp.org/wiki/index.php/TUT:Writing_a_MIB_Module 4/7
would put the nstAgentModuleObject.h and nstAgentModuleObject.c files into the net-snmp source codedirectory. You do this by copying them into a agent/mibgroup/nstAgentModuleObject.h andagent/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 theconfigure 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 withspaces inside the quotes (e.g., --with-mib-modules="nstAgentModuleObject XXX").
Note that nstAgentModuleObject is the prefix and the configure script will actually look for anstAgentModuleObject.h and a nstAgentModuleObject.c file. You must have a .h file and you can not get it towork 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 moreconfiguration options). Here we just add a simple read-only and read-write community strings (tutget andtutset, respectively) for the tutorial MIB branch:
% echo "rocommunity tutget .1.3.6.1.4.1.8072.2.4" > /usr/local/etc/snmpd.conf
% echo "rwcommunity tutset .1.3.6.1.4.1.8072.2.4" > /usr/local/etc/snmpd.conf
You can test out the functionality by starting the snmpd agent:
% /usr/local/sbin/snmpd -f -L -d -p 9999
This runs the agent on a temporary port ( -p 9999) so that it doesn't need special priviledges, or interfere withyour 'normal' agent. Incoming and outgoing packets are printed (-d), to show what's happening, and the agent isrun as a 'non-daemon' command (-f -L) so that you can see these messages. Note that this ties up the currentshell, 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:9999 NET-SNMP-TUTORIAL-MIB::nstAgentModuleObject.0
NET-SNMP-TUTORIAL-MIB::nstAgentModuleObject.0 = INTEGER: 1
% snmpset -v2c -c tutset localhost:9999 NET-SNMP-TUTORIAL-MIB::nstAgentModuleObject.0 = 5
NET-SNMP-TUTORIAL-MIB::nstAgentModuleObject.0 = INTEGER: 5
15/08/13 TUT:Writing a MIB Module - Net-SNMP Wiki
www.net-snmp.org/wiki/index.php/TUT:Writing_a_MIB_Module 5/7
% snmpget -v2c -c tutget localhost:9999 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 theAgentX subagent protocol (http://www.scguild.com/agentx/) . Our libraries provide support to make this easy todo 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 isalso 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 thatprocessing of all sets in the incoming packet can be successful. This gives you or other mib modules the chanceto 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 asimple state diagram that the master agent uses at each step of the way:
Error creating thumbnail: Unable to save thumbnail to
destinationIn a perfect operation with no failures, we take the vertical path on the left. If any of the mib modules beingacted upon returns an error of any kind, we will branch to the right to one of the failure states where you mustclean 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 helper module.
Tutorial Sections
About the SNMP Protocol
These tutorial links talk about SNMP generically and how the protocol itself works. They are good introductoryreading material and the concepts are important to understand before diving into the later tutorials about Net-SNMP itself.
How SNMP Works: About the protocol itself (GETs, GETNEXTs, etc)What data is in SNMP: All about SNMP Management Information Bases (MIBs)
Securing SNMP: How to use the SNMP protocol securely
Net-SNMP Command Line Applications
These tutorial pages discuss the command line tools provided in the Net-SNMP suite of tools. Nearly all theexample commands in these tutorials works if you try it yourself, as they're all examples that talk to our onlineNet-SNMP test agent. Given them a shot!
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.
15/08/13 TUT:Writing a MIB Module - Net-SNMP Wiki
www.net-snmp.org/wiki/index.php/TUT:Writing_a_MIB_Module 6/7
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/USM: Sending and receiving SNMPv3/USM TRAPs and
INFORMs
Sending Traps/Informs via AgentX: Sending notifications from the command line through snmpdCommon command line options:
Using and loading MIBS
SNMPv3/USM Options
Using SNMPv3 over TLS and DTLS
Customized Output Formats
Writing mib2c config files
Application Configuration
All of our applications support configuration to allow you to customize how they behave.
Configuration files for Net-SNMP applications
Net-SNMP Daemons
Net-SNMP comes with two long-running daemons: a SNMP agent (snmpd) for responding to managementrequests and a notification receiver (snmptrapd) for receiving SNMP notifications.
SNMP Agent (snmpd) Configuration
Configuration Basics
Access Control (VACM)
snmpconf
SNMP Notification Receiver (snmptrapd)
Configuring snmptrapdConfiguring SNMPv3 notifications
Configuring snmptrapd to understand vendor-specific MIBS (Cisco)
Agent Monitoring
DisMan Monitoring
Monitoring with MRTG
Coding Tutorials
Net-SNMP comes with a highly flexible and extensible API. The API allows you to create your owncommands, add extensions to the agent to support your own MIBs and perform specialized processing ofnotifications.
Client / Manager Coding Tutorials
Writing a simple application
Writing a simple asynchronous application
Agent Coding Tutorials
The Agent Architecture page might be worth reading before or after the agent coding tutorials, anddescribes how the Agent Helpers work under the hood.
15/08/13 TUT:Writing a MIB Module - Net-SNMP Wiki
www.net-snmp.org/wiki/index.php/TUT:Writing_a_MIB_Module 7/7
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.
Writing shell scripts to extend the agent
Using mib2c to help write an agent code template for youGeneral mib2c Overview
Using the mib2c-update script to recode your code
mib2c.mfd.conf tutorial (http://www.net-snmp.org/tutorial/tutorial-5/toolkit/mfd/)
Header files and autoconf
Debugging SNMP Applications and Agents
All our tools and applications have extensive debugging output. These tutorials talk about how the debuggingsystem works and how you can add your own debugging statements to you code:
Debugging output printed using the -D command line option
Putting DEBUGMSG tokens in your codeUsing -Ddump to display packet breakdowns
Debugging using GDB
Operating System Specific Tutorials
Building With Visual Studio 2005 Express
Using the command line and nmake
Net-Snmp on Ubuntu
Net-SNMP and lm-sensors on Ubuntu 10.04Net-SNMP for windows:
How to install: [1] (http://www.netadmintools.com/art487.html)
How to configure: [2] (http://www.netadmintools.com/art488.html)
Retrieved from "http://www.net-snmp.org/wiki/index.php?title=TUT:Writing_a_MIB_Module&oldid=5513"
This page was last modified on 27 March 2012, at 14:57.