*** WARNING WARNING WARNING ***

The AgentX support in net-snmp versions prior to 5.1 is beta level quality. Although many people have used it successfully, we strongly recommend AgentX sub-agent developers use 5.1.2 or higher.

Sub-Agent Demon tutorial

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, download the example files as follows:

git clone https://github.com/net-snmp/subagent-example.git

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

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