TUT:Writing a Subagent

From Net-SNMP Wiki
Revision as of 18:01, 27 February 2012 by Rstory (Talk | contribs) (→‎Running master agent as non-root)

Jump to: navigation, search

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]

Building and testing example subagent

Get the code

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.

Build the subagent

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).

Start the master agent

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.

Running master agent as non-root

You can run a test agent on a non-privileged port for test purposes: 

 % snmpd -f -Lo -C --rwcommunity=public --master=agentx --agentXSocket=tcp:localhost:1705 udp:1161

Configuring an existing agent as a master agent

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]

Test object without subagent

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

Start the subagent, which should attach to the master and offer the mib data in question

Unprivileged subagent

If you ran your master agent unprivilidged, you need to do the same with the subagent. 

 % ./mysubagent -x -f -Lo tcp:localhost:1705

subagent as root

 % ./mysubagent

Test object with subagent

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
example-demon.c The C code file containing "main" and net-snmp initialization
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

Beginner Tips

For all those of you that have just installed net-SMNP note that with the default snmpd.conf snmpget will keep giving you messages like

NET-SNMP-TUTORIAL-MIB::nstAgentModuleObject = No Such Object available on this agent at this OID

That's because the public community is restricted to .iso.org.dod.internet.mgmt.mib-2.system sub-tree. To grant access to the whole iso tree you should edit the snmpd.conf file (typically found at /etc/snmp).

Locate and comment the following line. 

 com2sec paranoid  default         public

Uncomment the two following lines. 

 com2sec readonly  default         public
 com2sec readwrite default         private

Make sure you have the following lines 

 rocommunity public
 rwcommunity private

Furthermore when using snmpget or snmpset you should use the -c <communityname> option, with 'public' for read only access and 'private' for read write access along with the -v1 or -v2c options.

These tips are just for making this tutorial work easily and with minimal changes to snmpd.conf. They provide really poor security and must be changed to suitable settings for a real-world subagent.

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.

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!

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.

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.

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:

Operating System Specific Tutorials

Retrieved from "https://net-snmp.sourceforge.io/wiki/index.php?title=TUT:Writing_a_Subagent&oldid=5499"