iReasoning SNMP API User Guide

1 I R E A S O N I N G S N M P L I B R A R Y. iReasoning snmp API user Guide Copyright 2002-2016 iDeskCentric Inc., All Rights Reserved. The information contained herein is the property of iDeskCentric Inc. This document may not be copied, reproduced, reduced to any electronic medium or machine readable form, or otherwise duplicated, and the information herein may not be used, disseminated or otherwise disclosed, except with the prior written consent of iDeskCentric Inc. I R E A S O N I N G S N M P L I B R A R Y. Table of Contents INTRODUCTION .. 1. About this document .. 1. Target Audience .. 1. INSTALLATION .. 2. Requirements .. 2. Installation Procedures .. 2. USING iReasoning snmp LIBRARY .. 4. Overview and Architecture .. 4. UML diagram .. 7. Configuration .. 8. Logger configuration.

2 8. Usage examples .. 8. SnmpSession class .. 8. Synchronous snmp Operations .. 9. Asynchronous snmp Operations .. 10. snmp Table Retrieval .. 11. SnmpTrapdSession class .. 12. SnmpTrapSender class .. 13. SnmpPoller class .. 13. Java Applet Example .. 14. FAQ .. 15. RESOURCES AND REFERENCE .. 19. GLOSSARY OF TERMS .. 20. I R E A S O N I N G S N M P L I B R A R Y. INTRODUCTION. About this document T. he purpose of this document is to provide the reader with enough knowledge to start developing software using the iReasoning 's snmp toolkit. Some examples are provided to better illustrate the usage of APIs. This document is not intended to provide detailed information about the snmp APIs. To effectively use the APIs, readers need to refer to javadoc help that has detailed instructions and examples.

3 The iReasoning snmp API is a Java toolset that greatly simplifies the development of applications for managing snmp agents. It provides full support for SNMPv1, SNMPv2c and SNMPv3. The design and implementation of this library were based on object-oriented methodology and followed recognized design patterns. These advantages, combined with a highly optimized code base, make iReasoning snmp library stand out from the competition. Target Audience This document is intended for users and engineers who are responsible for developing snmp based management applications. A user of this software does not have to be an expert in network management field. He or she should, however, be familiar with basic snmp concepts, such as snmp GET and GET_NEXT operations. Some basic knowledge about Java language is required to understand examples.

4 This software is designed to minimize the learning curve for users and achieve a given programming job with less code. A new user should therefore find it quite easy to learn and master this product. I R E A S O N I N G S N M P L I B R A R Y. Chapter 2. INSTALLATION. Requirements or a later version must be installed. You can download JDK from the Oracle's web site ( ). At least 32MB memory is required Installation Procedures Download and unzip Download iReasoning snmp library and unzip it to the desired directory, for example, C:\lib\ iReasoning \ snmp The directory structure will look like this: Directory Name Description lib contains binary jar files javadoc contains javadoc HTML files examples contains examples source code config configuration files I R E A S O N I N G S N M P L I B R A R Y.

5 Set up CLASSPATH. needs to be added to CLASSPATH environment variable. On Windows: If the iReasoning snmp library is installed at C:\lib\ iReasoning \ snmp , use the command set CLASSPATH=C:\lib\ iReasoning \ snmp \lib\ ;%CLASSPATH%. On Unix/Linux: If iReasoning snmp is installed at /usr/local/ iReasoning / snmp , use the command CLASSPATH=/usr/local/ iReasoning / snmp / ; export CLASSPATH. Run example program (Optional). Example code is located at examples/ snmp directory. They were pre- compiled and jarred into To verify that everything is working, you can follow the following steps to run the example programs. 1) Add to CLASSPATH. Take similar step, for instance, On Windows: set CLASSPATH=C:\lib\ iReasoning \ snmp \lib\ ;%CLASSPATH%. (assuming is located at C:\lib\ iReasoning \ snmp \lib\). On Unix/Linux CLASSPATH /usr/local/ iReasoning / snmp / ; export CLASSPATH.

6 (assuming is located at /usr/local/ iReasoning / snmp /lib/ ). 2) Run java snmpgetnext hostname . (Retrieve the first snmp variable). where hostname is the host name or IP address of an snmp agent. If you do not have an snmp agent, you can run (on Windows) to start an agent listening on port 161. Or you can use script to run examples on Windows. I R E A S O N I N G S N M P L I B R A R Y. Chapter 3. USING iReasoning . snmp LIBRARY. Overview and Architecture The iReasoning snmp library is designed and implemented using object oriented methodology and recognized design patterns. One of its design goals was to minimize the learning curve of snmp library for developers. Users only need to know a few classes, most of complex works are hidden from them. All versions of snmp (SNMPv1, SNMPv2c and SNMPv3) are supported in one library, and users do not have to learn the detailed underlying differences between three snmp versions.

7 Users can always use a unified interface to access snmp . agents speaking different snmp protocols. The example code shipped with this product clearly demonstrates the simplicity of this library. In those code, at first glance, users will realize how simple it is to write code to communicate with snmp . agents. The central class is the SnmpSession. It provides all the necessary mechanism to use snmp operations. A session represents a communication channel between an snmp manager and an agent. To communicate with multiple agents, multiple sessions have to be created. Each session is corresponding to each communication channel. A session needs to be created and then a connection needs to be established with the agent. After session is initialized, you are ready to issue snmp . commands against the agent.

8 There are four basic snmp operations: GET, GET_NEXT, SET, GET_BULK (SNMPv2c and SNMPv3). They are represented in SnmpSession class as snmpGetRequest, snmpGetNextRequest, snmpSetRequest, snmpGetBulkRequest methods. High-level snmp operations, such as GET_TABLE and WALK, are represented as snmpGetTable and snmpWalk methods. When a session is no longer needed, it needs to be closed to avoid resource leak. SnmpTrapdSession class is provided for creating trap receiver programs. A trapd session can be created and then waits for traps sent by agents. This session is able to understand all the SNMPv1, SNMPv2c and SNMPv3 traps. I R E A S O N I N G S N M P L I B R A R Y. Both synchronous and asynchronous requests are supported in SnmpSession. When sending synchronous requests, the session can only send one request at a time.

9 It must block and wait for the reply to the request before issuing next one. This mode is easier to understand and implement. When using asynchronous requests, the session does not need to wait for each reply. In this case, a session has a thread handling the replies and notifying callers when replies arrive. snmp data types are represented as child classes of SnmpDataType class. The remote agent is represented as the SnmpTarget class. Each agent is represented by a single SnmpTarget object. An SnmpTarget can be instantiated with the IP. address (or host name) and port number of the remote agent. Other properties of agent, such as community name, can also be specified. The class diagram is shown in figure 1. For detailed information about classes, you can refer to the javadoc files shipped with this library.

10 The snmp protocol uses UDP as the default transport layer protocol. UDP is connectionless and the delivery of packets is not guaranteed, but it is an efficient way to transport small amount of data. The iReasoning snmp API architecture also supports TCP besides UDP. snmp over TCP is a good fit for transferring large amount of data. The built-in features of TCP, such as flow control and efficient segmentation, make TCP perform better than UDP in this case. The agent has to be able to support snmp over TCP so that the snmp manager can choose TCP as an underlying transport layer protocol. I R E A S O N I N G S N M P L I B R A R Y. A MIB parser utility is also included in the library. MibUtil class can be used to parse MIBs and resolve OID and variable binding's value. It can look up MIB.