TUT:Writing a Subagent
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 mib module portion of the toolkit tutorial. The AgentX library support we offer provides an easy-to-use interface that allows the same mib module API to be used in either the core agent or in a agentx subagent, and thus your code can be designed to operate in either mode [no re-writing required!].
When you're first testing your code, we do recommend compiling it directly into the main agent even if you're going to use AgentX later. Compiling it directly into the master agent often makes debugging a little bit easier and takes the AgentX protocol out of the mix just to be sure. Once it's working right in the master agent, then it's easy to simply remove the support from the master agent and make a subagent instead [and, again, the nifty thing is that the mib API code doesn't need to change]
For example purposes, we'll refer to some example MIB objects and code: the NET-SNMP-TUTORIAL-MIB MIB, and the example mib module and it's header file.
There are two ways to compile a mib module into a subagent. You can do it yourself, described in detail below, or you can take your mib module and attempt to make a quick-and-dirty subagent automatically using the net-snmp-config script:
- ignore the warnings that the script generates due to un-prototyped init_ functions
% net-snmp-config --compile-subagent mysubagent nstAgentSubagentObject.c generating the tmporary code file: netsnmptmp.12259.c checking for init_nstAgentSubagentObject in nstAgentSubagentObject.c init_nstAgentSubagentObject(void) running: gcc -Dlinux -I. -I/usr/local/include -o nstAgentSubagentObject netsnmptmp.12259.c nstAgentSubagentObject.c -L/usr/local/lib -lnetsnmpagent -lnetsnmphelpers -lnetsnmpmibs -lnetsnmp netsnmptmp.12259.c: In function `main': netsnmptmp.12259.c:26: warning: implicit declaration of function `init_nstAgentSubagentObject' removing the tmporary code file: netsnmptmp.12259.c subagent program nstAgentSubagentObject created
If all goes well, this should have produced a mysubagent binary file (like the script output above chose). You can then start the snmpd master agent (if you didn't do so in the previous example and then start your subagent test it's results.
When you run the net-snmp snmpd master agent, in your snmpd.conf file you must put a line that says "master agentx" to turn on the AgentX master agent support. If you haven't done this you'll have to stop the agent, add the configuration line, and restart the snmpd master agent before the below example will work. [note that the previous example didn't have you did this, since it wasn't relying on AgentX support]
before you start the subagent, you should get an error
% snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 = No Such Object available on this agent at this OID
Start the subagent [as root], which should attach to the master and offer the mib data in question
% ./mysubagent &
now the request should return valid data
% snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 = INTEGER: 2 % snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 = INTEGER: 2 % snmpset localhost NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 = 5 NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 = INTEGER: 5 % snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 = INTEGER: 5
Instrumenting your own code with agentx subagent support
It's probably more likely that you want to compile in your new code into a previously existing application, and the auto-building of the subagent using the net-snmp-config command isn't appropriate.
Lets take the previous example and implement it in our own process which attaches to the master agent using the AgentX protocol. This is easier than you might think, as we provide libraries to do the work for you. We merely compile it ourselves this time, outside the main net-snmp package and put a main() wrapper around it. Functionally, this is all the net-snmp-config --compile-subagent script is doing for you above.
First, the example files you'll need:
Here are the files discussed in this example so you can download them:
File | Description |
---|---|
Makefile | A simple makefile used to build the projects |
NET-SNMP-TUTORIAL-MIB.txt | The MIB we'll be writing code for in the various pieces of the agent extension tutorial |
nstAgentSubagentObject.c | The nstAgentSubagentObject.c mib C code file |
nstAgentSubagentObject.h | The nstAgentSubagentObject.h mib code header file |
Build the example demon using the Makefile, as shown below. Note that to compile it, the Makefile uses the net-snmp-config command to generate a list of needed compilation flags and compilation libraries. You might run the following commands in a shell to see what type of output they provide:
% make example-demon gcc -I. `net-snmp-config --cflags` -c -o example-demon.o example-demon.c gcc -I. `net-snmp-config --cflags` -c -o nstAgentSubagentObject.o nstAgentSubagentObject.c gcc -o example-demon example-demon.o nstAgentSubagentObject.o `net-snmp-config --agent-libs`
Then, fire up the net-snmp snmpd master agent if you haven't yet. In your snmpd.conf file you must put a line that says "master agentx" to turn on the master agent support, so do this before running snmpd. If you have the mysubagent application shown above still running, make sure you kill it first as this subagent will conflict with that one.
You should then be able to run your new program (example-demon) and access the data housed within it. A good test is to do is to ensure that you can't access your data before starting it, and that you can after starting it. An example of all of this is shown below (which looks almost exactly like the above "auto-built" example):
before you start the subagent, you should get an error
% snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 = No Such Object available on this agent at this OID
Start the subagent [as root], which should attach to the master and offer the mib data in question
% ./example-demon &
now the request should return valid data
% snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 = INTEGER: 2 % snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 = INTEGER: 2 % snmpset localhost NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 = 5 NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 = INTEGER: 5 % snmpget localhost NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 NET-SNMP-TUTORIAL-MIB::nstAgentSubagentObject.0 = INTEGER: 5
Debugging Tips
If you're having problems, it's helpful to pass -Dagentx on the command line to the snmpd master agent to get it to spew out a bunch of debugging information about it's agentx transactions. Note that normally the agent will print this debugging information to it's normal log file, so you might add the -f and -L flags to make it print to the screen
Tutorial Sections
About the SNMP Protocol
These tutorial links talk about SNMP generically and how the protocol itself works. They are good introductory reading 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 the example commands in these tutorials works if you try it yourself, as they're all examples that talk to our online Net-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.
- 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 snmpd
- Common command line options:
- Writing mib2c config files
Application Configuration
All of our applications support configuration to allow you to customize how they behave.
Net-SNMP Daemons
Net-SNMP comes with two long-running daemons: a SNMP agent (snmpd) for responding to management requests and a notification receiver (snmptrapd) for receiving SNMP notifications.
- SNMP Agent (snmpd) Configuration
- SNMP Notification Receiver (snmptrapd)
- Agent Monitoring
Coding Tutorials
Net-SNMP comes with a highly flexible and extensible API. The API allows you to create your own commands, add extensions to the agent to support your own MIBs and perform specialized processing of notifications.
- Client / Manager Coding Tutorials
- Agent Coding Tutorials
- The Agent Architecture page might be worth reading before or after the agent coding tutorials, and describes how the Agent Helpers work under the hood.
- 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 you
- Header files and autoconf
Debugging SNMP Applications and Agents
All our tools and applications have extensive debugging output. These tutorials talk about how the debugging system works and how you can add your own debugging statements to you code:
- Debugging output printed using the -D command line option
- Using -Ddump to display packet breakdowns
- Debugging using GDB
Operating System Specific Tutorials
- Building With Visual Studio 2005 Express
- Building Net-SNMP 64-bit with Visual C++ 2010 Express
- Net-Snmp on Ubuntu
- Net-SNMP and lm-sensors on Ubuntu 10.04
- Net-SNMP for windows: