snmp4j

The org.snmp4j classes are capable of creating, sending, and receiving SNMPv1/v2c/v3 messages. A SNMP message is composed of its message header and its PDU payload. This package contains three main groups of classes and interfaces:

• Classes for SNMP message and target creation
• Classes for SNMP message sending (command generation)
• Classes for SNMP message dispatching (command responding)

The following UML package diagram illustrates the dependencies between the packages of the core SNMP4J API. Users of the API normally only need to use the org.snmp4j and the org.snmp4j.smi packages directly.

The following UML class diagram shows the most important classes of the org.snmp4j package and their relationships (relationships to other packages are not shown):.

SNMP Messages and Targets

To exchange a SNMP message with a remote system, that system has to be identified, retransmission, and timeout policy information about the message exchange has to be specified. A remote system is specified with SNMP4J by creating a Target instance appropriate for the SNMP protocol to be used.

• For SNMPv1 and SNMPv2c the CommunityTarget has to be used which provides community information in addition to the address, retransmission, and timeout policy information defined by the Target interface.
• For SNMPv3 the UserTarget has to be used instead. It extends the SecureTarget abstract class and provides the following User Based Security Model (USM) user information: security name, security level, security model (i.e. USM), and authoritative engine ID.

A SNMP message consists of the message's payload, the SNMP Protocol Data Unit (PDU) and a message header. Simplified said, in SNMP4J the message header information is represented by Target instances and the PDU is represented by one of the following classes:

• PDUv1 (SNMPv1)
• PDU (SNMPv2c)
• ScopedPDU (SNMPv3)

PDU Examples

• SNMPv1/v2c GETNEXT PDU

  
  import org.snmp4j.PDU;
  import org.snmp4j.smi.*;
  ...
  PDU pdu = new PDU();
  pdu.add(new VariableBinding(new OID("1.3.6.1.2.1.1.1"))); // sysDescr
  pdu.add(new VariableBinding(new OID("1.3.6.1.2.1.2.1"))); // ifNumber
  pdu.setType(PDU.GETNEXT);
  ...
      

• SNMPv3 GETBULK PDU

  
  import org.snmp4j.ScopedPDU;
  import org.snmp4j.smi.*;
  ...
  ScopedPDU pdu = new ScopedPDU();
  pdu.add(new VariableBinding(new OID("1.3.6.1.2.1.2.1"))); // ifNumber
  pdu.add(new VariableBinding(new OID("1.3.6.1.2.1.2.2.1.10"))); // ifInOctets
  pdu.add(new VariableBinding(new OID("1.3.6.1.2.1.2.2.1.16"))); // ifOutOctets
  pdu.setType(PDU.GETBULK);
  pdu.setMaxRepetitions(50);
  // Get ifNumber only once
  pdu.setNonRepeaters(1);
  // set context non-default context (default context does not need to be set)
  pdu.setContextName(new OctetString("subSystemContextA"));
  // set non-default context engine ID (to use targets authoritative engine ID
  // use an empty (size == 0) octet string)
  pdu.setContextEngineID(OctetString.fromHexString("80:00:13:70:c0:a8:01:0d"));
  ...
      

• SNMPv1 TRAP PDU

  
  import org.snmp4j.PDUv1;
  ...
  PDUv1 pdu = new PDUv1();
  pdu.setType(PDU.V1TRAP);
  pdu.setGenericTrap(PDUv1.COLDSTART);
  ...
      

• SNMPv2c/SNMPv3 INFORM PDU

  
  import org.snmp4j.ScopedPDU;
  ...
  ScopedPDU pdu = new ScopedPDU();
  pdu.setType(PDU.INFORM);
  // sysUpTime
  long sysUpTime = (System.currentTimeMillis() - startTime) / 10;
  pdu.add(new VariableBinding(SnmpConstants.sysUpTime, new TimeTicks(sysUpTime)));
  pdu.add(new VariableBinding(SnmpConstants.snmpTrapOID, SnmpConstants.linkDown));
  // payload
  pdu.add(new VariableBinding(new OID("1.3.6.1.2.1.2.2.1.1"+downIndex),
                              new Integer32(downIndex)));
  ...
      

Target Examples

• Community Target

  
  CommunityTarget target = new CommunityTarget();
  target.setCommunity(new OctetString("public"));
  target.setAddress(targetAddress);
  target.setVersion(SnmpConstants.version1);
      

• User Target

  
  UserTarget target = new UserTarget();
  target.setAddress(targetAddress);
  target.setRetries(1);
  // set timeout to 500 milliseconds -> 2*500ms = 1s total timeout
  target.setTimeout(500);
  target.setVersion(SnmpConstants.version3);
  target.setSecurityLevel(SecurityLevel.AUTH_PRIV);
  target.setSecurityName(new OctetString("MD5DES"));
      

Sending SNMP messages

SNMP message are sent with SNMP4J by using a instance of the SNMP Session interface. The default implementation of this interface is the Snmp class.

To setup a Snmp instance it is sufficient to call its constructor with a TransportMapping instance. The transport mapping is used by the SNMP session to send (and receive) SNMP message to a remote systems by using a transport protocol, for example the User Datagram Protocol (UDP).

A SNMP4J Snmp instance supports SNMP v1, v2c, and v3 by default. By sub-classing Snmp other combinations of those SNMP protocol versions can be supported.

With SNMP4J, SNMP messages can be sent synchronously (blocking) and asynchronously (non-blocking). The Snmp class does not use an internal thread to process responses on asynchronous and synchronous requests. Nevertheless it uses the receiver threads of the transport mappings to process responses.

Asynchronous responses are returned by calling a callback method on an object instance that implements the ResponseListener interface. The callback is carried out on behalf of the transport mapping thread that received the response packet from the wire. Thus, if the called method blocks, the delivery of synchronous and asynchronous messages received on the listen port of that transport mapping will be also blocked. Other transport mapping will not be affected. Blocking can be avoided by either using synchronous messages only or by decoupling the processing within the callback method.

Example for Sending a Synchronous Message

import org.snmp4j.*;
...
Snmp snmp = new Snmp(new DefaultUdpTransportMapping());
...
ResponseEvent response = snmp.send(requestPDU, target);
if (response.getResponse() == null) {
    // request timed out
    ...
}
else {
    System.out.println("Received response from: "+
                       response.getPeerAddress());
    // dump response PDU
    System.out.println(response.getResponse().toString());
}

Example for Sending an Asynchronous Message

import org.snmp4j.*;
import org.snmp4j.event.*;
...
Snmp snmp = new Snmp(new DefaultUdpTransportMapping());
...
ResponseListener listener = new ResponseListener() {
    public void onResponse(ResponseEvent event) {
        PDU response = event.getResponse();
        PDU request = event.getRequest();
        if (response == null) {
            System.out.println("Request "+request+" timed out");
        }
        else {
            System.out.println("Received response "+response+" on request "+
                               request);
    }
};
snmp.sendPDU(request, target, null, listener);
...

Receiving SNMP messages

SNMP4J receives SNMP messages through the listen port of transport mappings. In order to be able to receive responses or requests, that port needs to be set into listen mode. This has to be done by calling the listen() method of the TransportMapping instance to start the transport mappings internal listen thread. The internal thread is stopped and the listen port is closed by calling the close() method on the TransportMapping instance or the associated Snmp instance.

The transport mapping just receives the SNMP mesage as a stream of bytes and forwards the message to associated MessageDispatcher instances. By default, SNMP4J uses one instance of the MessageDispatcherImpl class for decoding and dispatching incoming messages. That instance is created and used internally by the Snmp class.

The Snmp class processes responses to outstanding requests and forwards PDUs of other SNMP messages to registered CommandResponder listener instances. To receive SNMP messages it is thus sufficient to

1. Create a TransportMapping and initialize its listen port by calling TransportMapping.listen().
2. Create a Snmp instance with the above TransportMapping.
3. Instantiate a class that implements the CommandResponder interface and register it with the Snmp instance by calling Snmp.addCommandResponder(CommandResponder).

When a unhandled SNMP message (thus a SNMP message where no corresponding outstanding request exists) is received, then the processPdu(CommandResponderEvent) method of the CommandResponder will be called with the decoded PDU and additional information about the received SNMP message provided by the message processing model that has decoded the SNMP message.

Example for Receiving SNMP Messages

import org.snmp4j.*;
import org.snmp4j.smi.*;
import org.snmp4j.mp.SnmpConstants;
...
TransportMapping transport =
    new DefaultUdpTransportMapping(new UdpAddress("0.0.0.0/161"));
Snmp snmp = new Snmp(transport);
if (version == SnmpConstants.version3) {
    byte[] localEngineID =
        ((MPv3)snmp.getMessageProcessingModel(MessageProcessingModel.MPv3)).createLocalEngineID();
    USM usm = new USM(SecurityProtocols.getInstance(),
                      new OctetString(localEngineID), 0);
    SecurityModels.getInstance().addSecurityModel(usm);
    snmp.setLocalEngine(localEngineID, 0, 0);
    // Add the configured user to the USM
    ...
}
snmp.addCommandResponder(this);
transport.listen();
...
public synchronized void processPdu(CommandResponderEvent e) {
    PDU command = e.getPdu();
    if (command != null) {
    ...
    }
}

The org.snmp4j.asn1 classes are capable of serializing of ASN.1 formatted values into a byte stream and deserializing the same from a byte stream. There are three groups of classes/interfaces in this package:

• The BER class implements the BER serialization and deserialization by providing static methods for encoding/decoding of primitive ASN.1 and Structure of Management Information (SMI) data types.
• The BERSerializable interface provides a common interface for all objects that are (de)serializable according to the Basic Encoding Rules (BER).
• The BERInputStream and the BEROutputStream provide optimized implementations for the serialization and deserialization of the InputStream and OutputStream abstract classes.

The following UML class diagram shows the most important classes of the org.snmp4j.asn1 package and their relationships (relationships to other packages are not shown):

The org.snmp4j.event classes and interfaces provide means to allow internal and external modules to listen on SNMP4J internal events to:

• Process SNMP response messages.
• Take additional actions on USM user events.
• Increment event counters.

The org.snmp4j.mp classes provide services to process SNMP messages. The services provided are defined in the MessageProcessingModel interface and include the following:

• Prepare data elements from an incoming SNMP message as described in RFC3412 §7.2.
• Prepare a response message as defined in RFC3412 §7.1.
• Prepare an outgoing message as defined in RFC3412 §7.1.

This interface is implemented by the message processing model classes for the SNMP versions 1, v2c, and v3: MPv1, MPv2c, and MPv3.

To be able to match requests and responses SNMP uses request IDs. Since request IDs are created by the command generator, the request IDs are unique within such a command generator only. SNMP4J therefore has to abstract from request IDs and uses PduHandle instances instead.

If a PDU is processed for sending by the SNMP4J MessageDispatcherImpl and the PDU's request ID is set to 0, then a SNMP4J application wide unique ID is generated and set as request ID of the supplied PDU. In any case, the PDU's request ID will be used as transaction ID of the outgoing message. The transaction ID identifies a messages PduHandle.

If a PDU is received by the SNMP4J MessageDispatcherImpl a unique transaction ID is generated so that command responders as well as the message processing model can match requests and responses.

The following UML class diagram shows the most important classes of the org.snmp4j.mp package and their relationships (relationships to other packages are not shown):

The org.snmp4j.security package contains three groups of classes and interfaces:

• The authentication protocols group contains interfaces and classes for authentication of SNMP(v3) messages.
• The privacy protocols group contains interfaces and classes for encryption and decryption of SNMP(v3) messages.
• The security model group combines authentication and privacy protocols to provide security services to message processing models.

Authentication as well as privacy protocols are security protocols and thus both are derived from the common interface SecurityProtocol. In order to be able to use a security protocol with SNMP4J, the protocol implementation class has to be registered with the SecurityProtocols singleton, which provides access to authentication and privacy protocols.

Authentication Protocols

All SNMP4J authentication protocol implementations have to implement the AuthenticationProtocol interface. SNMP4J provides implementation for the following authentication protocols:

• MD5, which is implemented by AuthMD5 and
• SHA, which is implemented by AuthSHA.

Privacy Protocols

All SNMP4J privacy protocol implementations have to implement the PrivacyProtocol interface. SNMP4J provides implementation for the following privacy protocols:

• DES in CBC mode, which is implemented by PrivDES and
• AES with 128bit key, which is implemented by PrivAES128.
• AES with 192bit key, which is implemented by PrivAES192.
• AES with 256bit key, which is implemented by PrivAES256. In order to be able to use 256bit strong encryption, the strong encryption enhancement package has to be downloaded and installed.

Security Models

All SNMP4J security models have to implement the SecurityModel interface. Before a security model can be used with SNMP4J, it has to be registered with the SecurityModels singleton which provides access to security models. SNMP4J implements a single security model, the User Based Security Model (USM).

The USM class uses a user name table (which contains user names) and a user table (which contains localized user information) to store user information. A time table is used to store time information about SNMP engines to protect SNMP communication against replay attacks if the corresponding security level has chosen.

The following UML class diagram shows the most important classes of the org.snmp4j.security package and their relationships (relationships to other packages are not shown):

The org.snmp4j.smi classes are capable of BER encoding and decoding themself to/from a byte stream. In addition, the SMI data type classes provide convenient functions for manipulating their content.

The VariantVariable is a special class that can be used in command responder applications to intercept access to a SMI value.

Variable Binding Examples

import org.snmp4j.smi.*;
...
VariableBinding vb = new VariableBinding(new OID("1.3.6.1.2.1.1.4.0"));
vb.setValue(new OctetString("SNMP4J Text"));
...
vb = new VariableBinding();
vb.setOid(new OID(new int[] { 1,3,6,1,2,1,1,2,0 }));
...
vb = new VariableBinding(vb.getOid(), new IpAddress("255.255.255.255"));
...
vb = new VariableBinding(vb.getOid(), new Gauge32(2^32-1));
int syntax = vb.getSyntax();
if (syntax != SMIConstants.SYNTAX_GAUGE32) {
  // never reached
}
else {
  long value = ((UnsignedInteger32)vb.getValue()).getValue();
  System.out.println(vb.getOid() + " = " + value);
  // prints: 1.3.6.1.2.1.1.2.0 = 4294967295
}
...

The following UML class diagram shows the most important classes of the org.snmp4j.smi package and their relationships (relationships to other packages are not shown):

The org.snmp4j.transport classes are capable of sending and receiving byte messages to and from a network using transport mapping specific transport protocol. All SNMP4J transport mappings have to implement the org.snmp4j.TransportMapping interface. SNMP4J supports two transport mappings for the transport protocols UDP and TCP:

• The UDP transport mapping is the default SNMP transport mapping. It is implemented by the DefaultUdpTransportMapping class.
• The TCP transport mapping is implemented by the DefaultTcpTransportMapping using the java.nio package.

Additional transport mappings can be easily added. It is sufficient to implement the org.snmp4j.TransportMapping interface and add an instance of that class to the Snmp (or MessageDispatcher) object. To be able to lookup a transport mapping by an Address class via the TransportMappings (as Snmp does for notification listeners), a transport mapping has to be registered in a transport mapping registration file. The default file is transports.properties in the org.snmp4j.transport package. To use a different file, set the system property org.snmp4j.transportMappings.

Connection-oriented transport mappings like TCP should implement the ConnectionOrientedTransportMapping interface to support MessageLengthDecoder and TransportStateListener.

The following UML class diagram shows the classes of the org.snmp4j.transport package and their relationships (relationships to other packages are not shown):

The org.snmp4j.util contains the following groups of classes:

• Classes for SNMP table retrieval. The class TableUtils can be used to asynchronously retrieve table data effeciently row by row.
• Classes for support of multi-threaded message dispatching. The class MultiThreadedMessageDispatcher implements the MessageDispatcher interface and uses the MessageDispatcherImpl class to dispatch incoming message using the threads of a ThreadPool.

The following UML class diagram shows the classes of the org.snmp4j.util package and their relationships (relationships to other packages are not shown):