SNMP GET

The SNMP GET operation is used by the SNMP manager applications to retrieve one or more values from the managed objects maintained by the SNMP agent. The applications typically perform an SNMP GET request by providing the host name of the agent and one or more OIDs along with the specific instance of the OID. The agent respond with a return value or with an error.

The SNMP GET operation is normally used to query the scalar variables in a MIB. Each scalar variable is identified by its OID and its instance. The instance is used to identify the specific instance of the scalar variable. It is specified by appending a ".0" to its OID.

For example, if we want to perform a SNMP GET on the OID .1.3.6.1.2.1.1.3, we need to specify 1.3.6.1.2.1.3.1.3.0 to retrieve the OID's value. If the request is made without the instance value, the agent returns an error.

Using High-Level API explains the usage of high-level API in performing SNMP GET operation. It also discusses about loading MIBs, single variable requests, multi variable requests, PDU splitting, getting partial data while performing multi variable requests.

Using Low-Level API explains the usage of low-level API in performing SNMP GET operation.

Using High-level API

The SnmpTarget and the SnmpRequestServer beans of the high-level API are used in the applications and applets for performing the SNMP GET request. These beans are used for many of the common operations that are done with an SNMP agent, such as GET, GETNEXT, SET, and TRAP operations. The SnmpTarget bean is used for synchronous requests and the SnmpRequestServer bean is used for asynchronous requests.

The SnmpTarget and SnmpRequestServer beans extends the SnmpServer class. The SnmpServer class maintains all the resources required for SNMP manager applications and applets. Some of the resources are SnmpAPI, SnmpSession, MibOperations, etc. provided by the low-level API.

Most of the SNMP and MIB details are hidden for the user because the high-level API are built on top of the SNMP functions provided by the low-level API and therefore developing applications are simpler.

Following are steps involved in performing a simple SNMP GET operation using the SnmpTarget bean.

Instantiate the SnmpTarget bean.

SnmpTarget target = new SnmpTarget();

Specify the mandatory parameters.

//set the host in which the SNMP agent is running

target.setTargetHost("localhost");

// set the OID

target.setObjectID(".1.3.6.1.2.1.1.0");

Set the SNMP version using the setSnmpVersion() method and perform an SNMP GET request to the SNMP agent.

String result = target.snmpGet();

System.out.println("Response: "+result);

View the complete example present in <SnmpGet.java>.

Following are the factors related to the SNMP GET operation.

Loading MIBs

The method loadMibs() in the SnmpTarget bean is used for loading MIB files in the applications or applets. Multiple MIBs can be loaded by specifying the list of MIBs separated by a space. The loaded MIB thereafter is used by all the other beans in that application or applet.

Single variable request

To perform SNMP operations, we need to specify the Object ID that needs to be queried. The method setObjectID() is used for specifying the OIDs in the application. The OIDs can be given either in the numerical format or in the string format. If the OID does not start with a dot, it is prefixed by .1.3.6.1.2.1. Therefore, the OID 1.1.0 becomes .1.3.6.1.2.1.1.1.0.

If the OID is given in the string format, we need to load the corresponding MIB file. For numerical OIDs, the MIB files need not be loaded.

The method snmpGet() is used for performing SNMP GET operations. This method queries the host, specified in the setTargetHost(), for the OID, specified in the setObjectID(), and returns the SNMP variable as a string.

The following methods can also be used to perform SNMP GET requests.

snmpGetVariable() - returns an object of type SnmpVar.
snmpGetVariableBinding() - returns an instance of SnmpVarBind. A variable binding has both the OID and the value.

Multi variable requests

We can also perform multiple OID queries in a single request by using the setObjectIDList() method. This method accepts an array of OIDs as arguments and performs the request for all the OIDs specified in the list.

The method snmpGetList() is used for performing multiple OID requests. This method returns the list of data corresponding to the OIDs specified in the list.

The following methods can also be used for performing SNMP GET requests with multiple OIDs.

snmpGetVariables() - returns objects of type SnmpVar.
snmpGetVariableBindings() - returns instances of SnmpVarBind. A variable binding has both the OID and the value.

PDU Splitting

While performing SNMP requests, the operation may fail because the huge size of the message. The maximum size of the SNMP message that the AdventNet API can encode and send is 64KB. However, this also depends on the maximum size the agent can handle.

If the size exceeds the limit , then the agent sends the manager a GetResponse-PDU with the error-status value field "too big ". In this case, we need to split the PDU into multiple requests.

The method setAttemptComplete(boolean) in the SnmpTarget bean allows the splitting of the PDU. By default, this method is set to false. Setting a true value to this method enables the manager application to split the varbinds into multiple request. When the request is sent, the PDU is split and sent in smaller units. The data is returned by the agent in more than one unit.

If the request made is a multi variable request, then the number of varbinds per request can be set using setVarBindCount(int) method. The PDU is split accordingly with the specified number of varbinds. By default, the value is zero.

If the request still fails because of the "tooBig" error, the number of varbinds is further split and the request is repeated until it succeeds.

Getting partial data while doing multi-variable requests

While making multi variable requests, the operation may fail even if one of the OIDs is invalid. However, the application can get the data from the valid OIDs by using the method setAttemptPartial(boolean)By default, this method is set to false. Setting it to true enables the application to get partial data from an agent during multiple variable requests. However, the invalid OIDs are returned with a value "null".

Using Low-level API

The SnmpAPI, SnmpSession, and SnmpPDU classes are used for most of the management operations in the low-level API.

To use the communication services available with the API, we must instantiate and initialize SnmpAPI. The SnmpAPI class is a thread which monitors SNMP sessions and it contains various SNMP parameters.

To communicate with SNMP entities, we need to instantiate the SnmpSession class. The open() method is to be invoked to get a socket for SNMP communications. Various parameters, such as remote host, remote port, version, community, retries, and timeouts can be set using this class.

Following are the steps involved in performing a simple SNMP GET operation using the low-level API.

Instantiate the SnmpAPI class.

SnmpAPI api = new SnmpAPI();

Instantiate and open the SnmpSession class.

SnmpSession session = new SnmpSession(api);

session.open();

The default protocol used for SNMP communications is UDP. Every packet that is sent through SnmpSession goes through the UDP implementation of SnmpTransportProvider. Parameters that are required for such operations are given through the UDPProtocolOptions class. After SnmpSession is opened for SNMP communication, the default values such as remoteHost and remotePort can be set using the UDPProtocolOptions object. If the remoteHost and remotePort is not specified in the SnmpPDU object, the API takes it from SnmpSession.

An SnmpPDU instance needs to be created to send any request to an SNMP peer. The SnmpPDU provides most of the communication parameters related methods that are available with SnmpSession and it overrides the value in the session.

Set the SNMP version using the setVersion() method and use the setCommand() method to send an SNMP request. The command constants are defined in the SnmpAPI class. The following command sets the constant to GET_REQ_MSG to perform an SNMP GET operation.

//Build GET Request PDU

SnmpPDU pdu = new SnmpPDU();

UDPProtocolOptions option = new UDPProtocolOptions("localhost");

pdu.setProtocolOptions(option); //sets the host in which the agent is running

pdu.setCommand(SnmpAPI.GET_REQ_MSG);

To make a query for an OID or a list of OIDs, the SnmpOID class is to be instantiated. SnmpOID is the sub class of the SnmpVar class that provides abstract methods to present a uniform interface for applications working with the SNMP variables.

The OID can be given in the form x.x.x... or .x.x.x.... The OID given in the form .x.x.x.x is assumed to be fully qualified, and the OID in the form x.x.x is not fully qualified in which case the value of the SnmpAPI.getOIDPrefix() method is added to the OID as a prefix.

This prefix can be changed by the user but it should be to applied across the entire application or applet. The addNull method in the SnmpPDU class adds a variable binding with the OID specified and a null variable value. Multiple OIDs can also be given as input.

SnmpOID oid = new SnmpOID("1.1.0"); //Here the OID is .1.3.6.1.2.1.1.0

pdu.addNull(oid);

After the SnmpPDU and the OID is setup using the above methods, it should be sent over a session to the peer SNMP entity. The method syncSend(pdu) is used to send synchronous requests. The printVarBinds() methods is used to print the descriptive value of the OID and the variables. An error message is displayed if the request fails.

SnmpPDU result = session.syncSend(pdu);

System.out.println(result.printVarBinds());

Close the session and the API thread.

session.close();

api.close();

Writing applications using low-level APIs is slightly complex when compared to writing applications using high-level APIs. View the complete example present in <tutorials/lowlevelapi/SnmpGet.java>.