Usage of Westhawk's SNMP stack

Introduction

This document describes the delivery of this stack and how the stack can be used for SNMPv1, SNMPv2c and SNMPv3. The stack supports traps, authentication and privacy. As authentication protocols the stack offers MD5 and SHA1.

This document does not explain SNMP (Simple Network Management Protocol) itself. The reader is assumed to have basic knowledge of the protocol. If you want to learn more, see the Reading section.

The target applications are small applets, for that reason the stack has remained tiny. We wanted something lighter that we could just pop in a (browser) frame and leave there all day. It has no MIB (Management Information Base) browsing capabilities, you have to know the OID (Object Identifier) of what you want to monitor. There are many other packages that do MIB browsing and general network management.

The Westhawk Java SNMP stack comes with generated (javadoc) documentation and a faq. Check that documentation for the description of all methods that are not mentioned in this document or for the description of the method parameters.

The delivery

The file snmp<version>.zip contains the SNMP stack. The file stubBrowser<version>.zip contains the Stub Browser application. Both distributions can be downloaded from the Westhawk's SNMP page.

You best unpack both deliveries in the same directory. They are released separately because of their different license, but come from the same development source tree.

the contents of the snmp<version>.zip file

build.xml
The main Ant build.xml file.
example.xml
Contains the Ant target to build and run the examples.
oracle.xml
Contains the Ant targets to build, load and run the nothread examples.
doc/
The directory with the documentation (including the javadoc files).
lib/
The directory containing the jar files;
- tablelayout.jar
The jar file with the Table Layout Manager classes. This jar file is needed to run some of the examples.
- snmp<version>.jar
The jar file with the core of the SNMP stack classes. It contains the precompiled uk.westhawk.snmp.X packages. This jar file does not contain any examples or beans.
src/
The source of the SNMP stack;
- uk/co/westhawk/examplev1/
The directory with the source of examples how to use the stack for SNMPv1.
- uk/co/westhawk/examplev2c/
The directory with the source of examples how to use the stack for SNMPv2c.
- uk/co/westhawk/examplev3/
The directory with the source of examples how to use the stack for SNMPv3.
- uk/co/westhawk/nothread/
The directory with the source of example how to use the stack in environments where thread creation is unwanted, e.g. database JVMs such as the Oracle ™ JVM.
- uk/co/westhawk/snmp/beans/
The directory with the source of the different beans that come with the stack.
- uk/co/westhawk/snmp/pdu/
The directory with the source of the different PDUs (among other things the BlockPdu) that come with the stack.
- uk/co/westhawk/snmp/stack/
The directory with the source of the context and ASN functionality of the stack.

the contents of the stubBrowser<version>.zip file

build.xml
The main Ant build.xml file. This is the same file as in the snmp<version>.zip file
stub.xml
Contains the Ant targets to build and run the Stub Browser.
lib/stubBrowser<version>.jar
The jar file with the Stub Browser classes. It contains the precompiled uk.westhawk.stub package.
src/uk/co/westhawk/stub/
The directory with the source of the Stub Browser.

The context

Every PDU that is created needs a context. The same context can be used for a number of PDUs.

the context for SNMPv1

For SNMPv1 the context is built out of the following parameters:

The next section explains the use of the type of socket.

This SNMP stack provides three contexts for SNMPv1:

The SnmpContextPool contains a pool of SnmpContext and will share any context that it can share. This results in a reduced number of threads and other resources.

The PassiveSnmpContextPool contains the SNMP v1 context that is needed by a PDU to send a SNMP v1 request in environments where thread creation is unwanted, see the nothread notes.

the context for SNMPv2c

The context for SNMPv2c is very similar to the SNMPv1 context. It is built out of the following parameters:

The next section explains the use of the type of socket.

This SNMP stack provides three contexts for SNMPv2c:

The SnmpContextv2cPool contains a pool of SnmpContextv2c and will share any context that it can share. This results in a reduced number of threads and other resources.

The PassiveSnmpContextv2c contains the SNMP v2c context that is needed by a PDU to send a SNMP v2c request in environments where thread creation is unwanted, see the nothread notes.

the context for SNMPv3

For SNMPv3 the context is built out of the following parameters.

This SNMP stack provides two contexts for SNMPv3:

The SnmpContextv3Pool contains a pool of SnmpContextv3 and will share any context that it can share. This results in a reduced number of threads and other resources.

When sending traps or receiving request PDUs with SNMPv3, please read the section about the authoritative engine.

The socket type

At the moment three types of sockets can be used:

By default the standard socket will be used.

The TCP socket can be used for "Reliable SNMP", if your agent supports this. This socket can be used to send requests and listen for traps, however it doesn't provide the functionality to send a response back to a request, see sending a response to a request.

The Netscape socket provides extra functionality for the Netscape capabilities classes.
The caller needs to use the NETSCAPE_SOCKET socket type when this stack is used in an (JDK 1.1.X) applet that is running in Netscape 4.X and when the jar files needs to be signed. Unfortunately the developer.netscape.com site has ceased to exist, so the link Introduction to the capabilities classes no longer works. Please have a look at capabilities on www.mindprod.com.

Sending PDUs

Sending PDUs can be done in a number of ways:

Using the beans

The package uk.co.westhawk.snmp.beans contains all the beans in the stack. Except for the UsmDiscoveryBean and UsmBeingDiscoveredBean they all (still) relate to SNMPv1.

The beans form a bridge between the uk.co.westhawk.snmp.pdu (and uk.co.westhawk.snmp.stack) package(s) and any applet or application you may want to write.

The beans work via the (asynchronous) java.beans.PropertyChange mechanism. If you are using Swing, don't forget to use javax.swing.SwingUtilities.invokeLater(java.lang.Runnable) if you want to do any screen updates from the propertyChange method.

Our beans gather specific MIB information, i.e. the OID (Object Identifier) is hard coded. The beans should be easy enough to understand, and with little effort you can write a bean for your own purpose. The beans SNMPBean and SNMPRunBean contain some general information about the beans as well. The coding examples will show you how to use the beans as well.

Using the PDUs

The package uk.co.westhawk.snmp.pdu contains all the public accessible PDUs. All the PDUs (well, except for the BlockPdu) extend abstract uk.co.westhawk.snmp.stack.Pdu. The PDUs are non blocking and work via the java.util.Observer/java.util.Observable mechanism.

The idea is that for each class of problem you should subclass the abstract uk.co.westhawk.snmp.stack.Pdu class. You will have to implement the protected void new_value(int n, varbind res) and the protected void tell_them() methods. As example look at the uk.co.westhawk.snmp.pdu.OneIntPdu class or any other class in that package.

In order to use a PDU do the following:

  1. Create a context, giving it the host name and port number of your SNMP agent. If this is run in an applet then you can only connect back to that server!
  2. Create a PDU, passing it the context; GetPdu pdu = new GetPdu(context).
  3. Add the OIDs you are interested in with pdu.add_oid(oid).
  4. Add an observer with pdu.addObserver(observer). The argument is the object that wishes to be notified when the new value arrives. It must implement java.util.Observer, that is it must have a public void update(java.util.Observable obs, java.lang.Object obj) method. This method will get called when the value arrives. If you are using Swing, don't forget to use javax.swing.SwingUtilities.invokeLater(java.lang.Runnable) if you want to do any screen updates.
  5. Call pdu.send().
  6. Sleep, or do something else. Your update method will get called automatically when the data has arrived. Both the context and PDU objects spawn their own threads, so there is nothing further to do.

The stack was initially build with manager only functionality in mind, i.e. sending a request and receiving a response. It is possible to receive a request and send a response back, but the functionality is still very clunky.

Since a trap or a response does not get a reply, you can omit adding an observer (step 4) and implementing update (the last step) when sending one. When sending traps or receiving PDUs with SNMPv3, please read the section about the authoritative engine.

The coding examples will show you how to use the PDUs as well.

Using the blocking calls

The class uk.co.westhawk.snmp.pdu.BlockPdu is a wrapper class around the traditional (non blocking) PDU. It allows the user to send either a Set request, a Get request, a GetNext request or a GetBulk request by specifying the type of request, see the setPduType method. The caller has to add the necessary OIDs with the method addOid.

As the title suggests, the BlockPdu sends the request and waits for the response. We suggest that you only use this class if you have to; because the PDU blocks, you can not do anything else on that thread while it is waiting for a reply. If that thread is driving a UI, then the user may see a sluggish interface. If you can, use the beans or the PDUs. They are much faster as well.

There are four methods that send the request, wait for the response and return the variables or variable bindings. They throw the uk.co.westhawk.snmp.stack.PduException exception:

The OIDs that are added via addOid method for the request will not be replaced by the OIDs from the response. This means that every request will result in the same answer and that the GetNext does not walk the MIB

Receiving PDUs

There are different ways to receive incoming PDUs. Any combination of these ways can be used at the same time:

The conventional and default port to listen for request PDUs is 161, for traps this is 162. Since on UNIX and Linux systems only the root user is allowed to open these port, you will have to run as root in order to listen for incoming PDUs on that port, when running on any of those operating systems.

Receiving trap PDUs from a specific host

To receive traps, that is a Trapv1 or Trapv2 PDU, from a specific host do the following:

The SnmpContext fires decoded PDU events.

Receiving request PDUs from a specific host

To receive request PDUs, that is a GetRequest, SetRequest, GetNextRequest, GetBulkRequest or Inform PDU, from a specific host do the following:

The SnmpContext fires decoded PDU events. If you want to reply to the request, read the section on sending a response.

When receiving request PDUs with SNMPv3, please read the section about the authoritative engine.

Receiving PDUs from all hosts

The class uk.co.westhawk.snmp.stack.ListeningContextPool forms the base to receiving incoming packets. It contains a pool of uk.co.westhawk.snmp.stack.ListeningContext objects, that prevent the user from opening more than one listening object on the same port.

The ListeningContext fires undecoded PDU events.

Receiving unhandled PDUs

Unhandled PDUs are raw PDUs that are received (see PDUs for all hosts) but do not match any of the contexts (see trap PDUs from a specific host and request PDUs from a specific host):

The ListeningContext fires undecoded PDU events.

The PDU events

There are two types of PDU events:

All events are fired in a separate thread, so the listening context can go straight back to listening.

The decoded PDU events

Decoded PDU events are fired by the SnmpContext classes when receiving trap PDUs from a specific host or request PDUs from a specific host.

When receiving trap PDUs from a specific host the uk.co.westhawk.snmp.event.TrapEvent will contain one of the two trap PDUs:

When receiving request PDUs from a specific host the uk.co.westhawk.snmp.event.RequestPduEvent will contain one of the following request PDUs:

In both cases the event will contain the following:

The undecoded PDU events

Undecoded PDU events are fired by the ListeningContext class when receiving PDUs for all hosts and/or receiving unhandled PDUs. The uk.co.westhawk.snmp.event.RawPduEvent will contain the following:

To decode an undecoded PDU event, you create a context on the fly and call Pdu pdu = context.processIncomingPdu(byte[ ] message). The context should contain all the parameters needed to decode the message. For SNMPv3 this is not so obvious.

Sending a response to a request

The stack was initially build with manager only functionality in mind, i.e. sending a request and receiving a response. It is possible to receive a request by getting decoded PDU events and send a response back, but the functionality is still very clunky.

The TCP_SOCKET does not provide the functionality to send a response back. You'll have to use one of the other two, see the section on socket type.

As mentioned before, the stack offers no MIB parsing to help the user parse the request PDU. It is possible to send a uk.co.westhawk.snmp.stack.ResponsePdu, but how to fill it in is up to the user. Please do not forget to use the RequestPduEvent.getHostPort() when creating the context for the response.

When sending response PDUs with SNMPv3, please read the next section about the authoritative engine.

The authoritative engine

When sending traps or receiving requests the stack becomes an agent, or an authoritative engine as it is called in SNMPv3, rather than a manager, or a non-authoritative engine as it is called in SNMPv3.

In SNMPv3 the User-Based Security Model (USM) timeliness mechanism is different for authoritative and non-authoritative SNMP engines:

This distinction does not apply to SNMPv1 or SNMPv2c.

Since the stack is not a real agent, it cannot provide all the USM synchronisation parameters. For that reason the user has to provide an implementation of the interface uk.co.westhawk.snmp.stack.UsmAgent. See also the javadoc on SnmpContextv3. This interface provides the stack with the following information of its authoritative engine:

Coding example

The stack contains a lot of examples in the form of applications in the package uk.co.westhawk.examplev1. The package uk.co.westhawk.examplev2c contains a few examples for SNMPv2c. The package uk.co.westhawk.examplev3 contains a few examples for SNMPv3. These packages show you how to use the PDUs and beans. Note that because we implemented SNMPv3 before SNMPv2c, there are more examples for the former one.

How to run these examples is explained in the next section. If this example is not sufficient, check if the other examples do what you are looking for.

The next is a snippet of the uk.co.westhawk.examplev1.get_next example that walks the MIB with the GetNextPdu. The complete example is part of the source distribution. 

public class get_next implements Observer
{

    public void init() 
    {
        try 
        {
            context = createContext(host, port, socketType, community);
            GetNextPdu pdu = createPdu(context, new varbind(oid), this);
            pdu.send();
        }
        catch (java.io.IOException exc)
        {
            context.destroy();
            System.exit(1);
        }
        catch(uk.co.westhawk.snmp.stack.PduException exc)
        {
            context.destroy();
            System.exit(1);
        }
    }

    protected SnmpContext createContext(String host, int port, String socketType, 
    String community)
    throws java.io.IOException
    {
        SnmpContext con = new SnmpContext(host, port, socketType);
        con.setCommunity(community);
        return con;
    }

    protected GetNextPdu createPdu(SnmpContext context, varbind var, Observer obs)
    {
        GetNextPdu newPdu = new GetNextPdu(context);
        newPdu.addOid(var);
        newPdu.addObserver(obs);
        return newPdu;
    }

    public void update(Observable obs, Object ov)
    {
        GetNextPdu pdu = (GetNextPdu) obs;
        if (pdu.getErrorStatus() == AsnObject.SNMP_ERR_NOERROR)
        {
            try
            {
                varbind[] vars = pdu.getResponseVarbinds();
                varbind var = vars[0];
                System.out.println(var.toString());

                pdu = createPdu(context, new varbind(var.getOid()), this);
                pdu.send();
            }
            catch(java.io.IOException exc)
            {
                System.out.println("update(): IOException " 
                      + exc.getMessage());
            }
            catch(uk.co.westhawk.snmp.stack.PduException exc)
            {
                System.out.println("update(): PduException " 
                      + exc.getMessage());
            }
        }
        else
        {
            context.destroy();
            System.exit(0);
        }
    }
}

Running the applications

Running the stack examples

To run the examples, you need to have Ant installed.

The uk.co.westhawk.examplev1, uk.co.westhawk.examplev2c and uk.co.westhawk.examplev3 directories contain example applications, that can be run using the Ant runExample target, defined in example.xml.

Type on the command line: 

% ant runExample

Unless changed (see below), this target will run the uk.co.westhawk.examplev1.get_next application, with the properties file src/uk/co/westhawk/examplev1/get_next.properties as argument.

The runExample target has a number of properties (defined in example.xml) that you can change to run another example:

The properties file (get_next.properties) contains the initialisation parameters of the example, such as the hostname and the port number. When the argument is missing, the application will look for the file <classname>.properties in the used package directory.

The target first compiles the package (into the directory classes) and then runs it. The classpath is set to:

Running the Stub Browser

The Stub Browser is an experimental piece of software that offers the user a UI to generate a PDU out of selected OIDs. It is an add-on to the Mibble Mib Browser. It is not "fool-proof", and (as always) we appreciate your feedback.

To run the Stub Browser you need to have Ant installed. You have to download

and configure the location of

Now run on the command line: 

% ant runStubBrowser

First select all the OIDs you want to include in your Java stub file. Select an OID be by right clicking on a leaf in the MIB tree. A small popup menu will appear with the "Add to Stubs" menu item. Each selected stub will be listed in the lower pane.

When you are happy with your list, select "Generate Stubs" from the File menu. This will bring up a second "Stub Files" frame with the Java code. Every time you generate a stub file, the new code will be added in a new tab.

You can save each tab individually to disk. The code will try to replace the classname and packagename place holders, but please check the code before trying to compile. Compilation of the new java files, is outside the scope of the Stub Browser.

Please note that the Stub Browser is not a fancy development tool. For example, when exiting the application or closing a tab, it will not check if you have saved the latest version.

Reading

Our article on Simple Times (issue Dec 2001) explains the history and design decisions of the stack.

The SimpleWeb provides links and information on network management, including software, RFCs and tutorials. The focus is on SNMP and Internet management.

For more background on SNMP we recommend the following books:

Third party packages

All the jar files that are needed for the core stack are delivered with the stack. A few jar files are used in other packages that do not come with the stack:

Copyright & License

Only the Stub Browser is released under the GNU GPL License, since it uses Mibble.

The stack is freeware. The license (see the header of each file) means that you can do whatever you like with it without cost, except

  1. blame us when it does/doesn't work
  2. remove our copyright

Strictly the license requires that you acknowledge our code, by mentioning its origin in the documentation of any product that uses it (in some cases there may be no documentation).

There are no commercial license fees, nor do we have any GPL-style open-source requirements on our stack.

If you want software written that uses the stack or modifications to it to better suit your project, we would be happy to quote you for the work.

We also offer commercial support for organisations who want it.

01 Feb 2006

Post to the mailing list or contact the snmp group at Westhawk Ltd