Table Of Contents. Loading MIBs...34 Unloading MIBs...36 Parsing MIBs...37

Transcription

1

2 Table Of Contents ADVENTNET SNMP API.NET EDITION 4.0 PRODUCT DOCUMENTATION... 4 QUICK TOUR... 5 About AdventNet SNMP API... 6 AdventNet SNMP API Experience... 7 Related Products Contact Customer Support TECHNOLOGY OVERVIEW SNMP Overview Versions of SNMP SNMPv3 Overview MIB Overview RELEASE NOTES INSTALLATION GUIDE System Requirements Installing SNMP API.NET Edition Package Structure Installing Service Pack DEVELOPING MANAGEMENT APPLICATIONS Using MIBs in Applications Loading MIBs...34 Unloading MIBs...36 Parsing MIBs...37 Parsing Levels Checks for Various Parsing Levels Checks in Detail Accessing Node Information...52 Retrieving MIB Information...54 Exceptions and Error Messages...55 Macro Type Constructs...60 Configuring SNMP Agent Parameters AdventNet, Inc. 1

3 Handling Datatypes Overview...71 SMI Datatypes...75 Integer INTEGER (Enumerated) Unsigned Gauge Counter Timeticks OCTET STRING OBJECT IDENTIFIER IpAddress Opaque BITS Textual Conventions Overview DateAndTime MacAddress Data Retrieval Operations SNMP GET SNMP GETNEXT SNMP GETBULK Data Altering Operations SNMP SET Setting Values for Datatypes Traps and Notifications Receiving Notifications Sending Notifications Table Handling in Applications SNMP Table Basics Fetching Tables Getting Row Data Getting Column Data Modifying Table Data Adding a Row Deleting a Row Error Messages AdventNet, Inc. 2

4 Using Transport Providers SNMP Transport Provider Custom Transport Provider Deployment Instructions Examples Setting Up the Environment SNMP GET SNMP GETNEXT SNMP GETBULK SNMP Walk SNMP SET Send Trap Receive Trap Send Inform Receive Inform MIB Details Tutorials Tutorials: SNMP GET Tutorials: SNMP GETNEXT Tutorials: SNMP GETBULK Tutorials: SNMP SET Tutorials: Send Trap Tutorials: Receive Trap MIB Node Information Performance Metrics FAQS Beginners FAQs FAQs - General Advanced FAQs KNOWN ISSUES APIDOCS AdventNet, Inc. 3

5 AdventNet SNMP API.NET Edition 4.0 Product Documentation Welcome to AdventNet SNMP API.NET Edition, a comprehensive toolkit for rapid development of SNMP-based management applications that are reliable and scalable. With well-proven APIs enriched with customer experience and an integrated set of easy-to-use tools and features, AdventNet SNMP API caters to the complete development life cycle of network element management. Network management developers can leverage AdventNet SNMP library to build standalone and Web-based applications. The library provides many of the commonly used functions and components out-of-the-box to make the development simpler. The core of AdventNet SNMP API.NET Edition is a set of APIs that can be integrated in any application. Built using the best software design patterns and optimized performance, it is a powerful suite to secure APIs to build cross-platform, real-time application for monitoring and tracking the performance of network elements. Quick Tour Technology Overview Release Notes Installation Guide Developing Management Applications FAQs Known Issues and Limitations APIdocs AdventNet, Inc. 4

6 Quick Tour About AdventNet SNMP API AdventNet SNMP API Experience Related Products Contact Customer Support This section gives you an overview of AdventNet SNMP API and the technologies on which it is built. It also gives an overview of the features and the various modules of AdventNet SNMP API. AdventNet, Inc. 5

7 About AdventNet SNMP API Target Market Benefits Key Features AdventNet SNMP API can be used for building management applications for delivering superior solutions that are appropriate for specific needs in the spheres of Internet Infrastructure Management. This API can be used and integrated into any programming infrastructure that might require network management solution. Target Market AdventNet SNMP API is built to address the needs of the following: Equipment Vendors and ISVs can build device and network element management applications. In addition, applications for performance monitoring, configuration, and managing resources on the network can be developed easily. Enterprises can build applications for measuring utilization and throughput monitoring and deploy them in various ways. Service Providers can develop applications for monitoring utilization and throughput besides service availability and performance management. Benefits Customization - provides a rich set of interfaces to deliver a highly customizable solution. Scalability - fundamentally designed as a multi-tier system, based on widely used Internet technologies for highly scalable solutions. Flexibility - provides a hierarchy of.net library packages, which allow flexible selection of the level of library support desired. Therefore, you can access the detailed SNMP information by using API. Conformance to standards - AdventNet SNMP API conforms to the following Internet RFC specifications. SNMPv1 - RFC 1155 and RFC 1157 SNMPv2c - RFC 3416 Coexistence between SNMPv1, SNMPv2c, SNMPv3 - RFC 3584 Notification Filtering and Proxy Forwarding - RFC 3413 Key Features Multi-lingual support: Complete support for SNMPv1 and SNMPv2c Robust SMIv1 and SMIv2 MIB Parser: Seamlessly parses the MIB definitions from any OEM vendor. Offers various flavors of parsing based on the MIB definitions. SNMP Broadcasting: Broadcasts snmp packets across the network to auto-discover snmp devices in the network. Command line utilities: Perform SNMP operations such as, SNMP GET, SNMP GETNEXT, SNMP SET, SNMP BULK, SNMP WALK, etc. on remote agents. AdventNet, Inc. 6

8 AdventNet SNMP API Experience All SNMP management applications communicate with one or more SNMP agents to deliver their functionality. Both the management application and the agent always conform to the SNMP, MIB, and SMI specifications. Although the management applications are diverse in nature, they all share a minimal common characteristics. All the SNMP agents typically behave in a standard way - processing requests from the manager applications and sending traps. SNMP agents on a network only differ in the various versions of the SNMP they support, and the MIB or the managed objects they maintain. The SNMP management applications communicate with the agents to retrieve and collect the necessary information. The following are the various factors that need to be considered while developing a management application Accessing the Data from the MIBs Supported by the Agent Collecting Data from the Agent Communicating with SNMP Agent Table Handling Polling Displaying the Retrieved Data Receiving Unsolicited Messages from the Agent Version of SNMP to Be Supported Fig: SNMP API Architecture SNMP Core: Implements SNMP communication related classes developed in C# MIBS API: Implements all the MIB handling support, such as MIB loading, unloading, etc., developed using J# Accessing the Data from the MIBs Supported by the Agent The management applications typically request management data or properties from one or more SNMP-enabled nodes. The application needs to know the names and types of objects in the managed device. This is available in the Management Information Base (MIB) modules, which are usually provided with the managed devices. AdventNet, Inc. 7

9 The data supported by the agent are available in the form of MIB files and the manager applications make use of the information available in the MIB files while querying the agent. For example, RFC1213-MIB, also known as MIB-II, is a MIB module that is supported by all SNMP agents on TCP/IP-enabled devices. Apart from supporting MIB-II, each device has its own MIB, such as a printer MIB, a modem MIB, or a switch MIB. These MIBs can be used to access the associated data with it. Management applications should be able to Load and unload MIB modules Access the information on managed objects using MIB Resolve the textual labels to numerical OIDs Determine the type of data of the MIB object Simple management applications normally make a request by manually loading the MIB file, entering the OID, data type, and data value of the each variable binding. Advanced applications require loading multiple MIBs, storing the MIBs, logging the management requests, and so on. Collecting Data from the Agent The SNMP management applications communicate with the agents to retrieve the data. Applications normally retrieve the data by synchronous/asynchronous communication or by polling at regular intervals. The applications, while communicating through the synchronous mode, wait for the response of the previous request before sending a new request. In the case of asynchronous mode, the manager application can keep sending requests to the agent without waiting for the response. The responses are retrieved using the callback mechanism. Though using asynchronous mode appears to lead to improved performance, it can be used when the manager application knows the OID of the object it has to query. The synchronous operation is relevant while retrieving something like a tabular data, in which the instance of the OID to be queried next is got from the response of the previous request. The data retrieving functions of the manager applications can be classified as follows: Communicating with SNMP agent Table handling Polling Communicating with SNMP Agent Management applications normally retrieve the properties of the devices using SNMP GET, GETNEXT, or GETBULK request to the OIDs. The request may be simply to check whether the node is alive or to periodically retrieve the values of specific managed objects. The sections Data Retrieval Operations and Data Altering Operations discuss how the applications communicate with the agent to access the data and the various ways of accessing the data using the SNMP protocol. Table Handling Most of the MIBs are designed to handle large data in the form of tables. Management applications should be able to retrieve tables in a quick and efficient way. Intuitive table handling GUIs should become part of the management applications. Table Handling in Applications explains the various table-related operations that can be performed using AdventNet SNMP API. AdventNet, Inc. 8

10 Polling The retrieval of data for specific managed objects at periodic interval of time is called polling. Polling is normally used to monitor data that may change over time. Repeated polling of data is required when the object is a critical resource or when it is required to monitor the performance. Displaying the Retrieved Data After the necessary data is collected from the agent, the management application has the option of displaying the result in the form of UI or non-ui. In case of displaying the results in the form of UI, the users have to build their own UI components. Receiving Unsolicited Messages from the Agent Traps are unsolicited messages sent from an SNMP agent to one or more SNMP management applications. The generation of a trap by an agent indicates that some predefined event has occurred. When the agent detects the occurrence, trap messages are generated and sent to specific trap destinations. Management applications running in these trap destinations receive the traps. Trigger actions can be configured on receiving the trap. This could be a change in color, an alarm sound, a blinking LED, an alert, or a pager alert. Applications should also allow the trap data to be logged to determine what kind of event caused the agent to generate the trap. This is done by examining the data stored in the variable bindings of each trap message. The varbinds may contain the identity and values of MIB variables that provide information on the specific event. Many trap messages do not contain any variable bindings. This is because there may be no data associated with the event that triggered the generation of the trap, or the trap message itself conveys the necessary information. Receiving Unsolicited Messages discusses the trap-handling features that are available in AdventNet SNMP API. Version of SNMP to Be Supported The management applications should be able to support all the SNMP versions, so that it can communicate with diverse set of devices/systems. SNMPv1 and v2c versions are predominantly used for monitoring and performance management. SNMPv3 with its enhanced security features can be used for configuration, accounting, and fault management. AdventNet SNMP API supports SNMPv1 and SNMPv2c. Applications have the flexibility of selecting any desired versions. AdventNet, Inc. 9

11 Related Products AdventNet provides a comprehensive range of network management products that address all the network and system management needs of your organization. The following is our comprehensive portfolio of development tools. Visit our Web site for the latest information on our products. This section talks briefly about AdventNet products that are closely related to AdventNet SNMP API. Java SNMP API AdventNet SNMP API is a comprehensive development environment that comprises Java SNMP library and protocol stack for building SNMP management applications. It supports all three versions of SNMP:SNMPv1, SNMPv2c, and SNMPv3 in one common API. For a detailed product overview, please see the Java SNMP API product page on our Web site. Web NMS An open, standards-based, scalable network management platform that enables easy development of custom element management system (EMS) and network management system (NMS) applications. For a detailed product overview, please see the Web NMS product page on our Web site. CLI API AdventNet CLI API supports CLI protocols, such as SSH stack (SSH1 and SSH2), CLI telnet, and CLI transport provider (for custom protocols); offers CLI command set and functions, such as CLI parsing. For a detailed product overview, please see the CLI API product page on our Web site. TL1 API AdventNet TL1 API combines the power of TL1 protocol stack and TL1 message parser and contains TL1 tools, such as TL1 craft interface and TL1 message builder that help in rapid application development. For a detailed product overview, please see the TL1 API product page on our Web site. Agent Toolkit Java Edition The AdventNet Agent Toolkit Java Edition is a rapid prototyping and development tool used for building Java-based standalone SNMP and TL1 agents. For a detailed product overview, please see the Agent Toolkit Java Edition product page on our Web site. Agent Toolkit C Edition AdventNet Agent Toolkit C Edition is a rapid prototyping and development tool for building SNMP agents, TL1 agents, CLI agents, and multi-protocol agents in strict ANSI C language. For a detailed product overview, please see the Agent Toolkit C Edition product page on our Web site. AdventNet, Inc. 10

12 SNMP Utilities AdventNet SNMP Utilities consists of tools that enable SNMP management, which supports SNMPv1, SNMPv2c, and SNMPv3. MIB Browser is one such tool for browsing MIBs in the MIB tree. For a detailed product overview, please see the SNMP Utilities product page on our Web site. Simulation Toolkit The AdventNet Simulation Toolkit provides a comprehensive set of tools for creating a simulated environment. It not only supports setting up a simulated agent but also simulating an entire network in Windows, Linux, and Solaris. For a detailed product overview, please see the Simulation Toolkit product page on our Web site. AdventNet, Inc. 11

13 Contact Customer Support AdventNet, the Internet Management Infrastructure Company is the leading provider of open, scalable, extensible, and cross-platform management solutions for managing the Internet and e- commerce infrastructure. AdventNet's solutions range in scope from optical and core inter-networking management systems, cable modem, DSL, storage, security management to e-commerce application management. In each of these fast-growing markets, AdventNet is the leading provider of technology. During the evaluation phase, AdventNet provides support "at no cost". This support includes access to our product specialists for problem resolution, clarifications in documentation, and technical guidance. Please send in your queries. We guarantee to respond as quickly as possible to make your evaluation a success. AdventNet is eager to hear your comments, feedback, and suggestions that would help us improve our products. We give you the contact information of our Corporate Headquarters, Sales, and Technical support teams. Corporate Headquarters Web Site AdventNet Headquarters AdventNet Development Center AdventNet, Inc Gibraltar Drive Pleasanton, CA USA Phone : Fax : [email protected] AdventNet Development Center (India) Private Limited Sree Narayana Complex 11, Sarathy Nagar Velachery, Chennai INDIA Phone : Fax : [email protected] Sales For sales and product licensing inquiries, please use the contact information available in the following URL. You can also send to [email protected] at the AdventNet Headquarters main switchboard below. Phone: and request for Sales Fax: Technical Support For support and bug-report, please mail to [email protected]. For those with support contracts, AdventNet provides priority support through with a reply usually within 24 hours. Please provide the following information while sending support mails. Release version of the product Operating System and version AdventNet, Inc. 12

14 Stack traces, if any Debug messages or hex dumps, if any CLASSPATH environment variable, if applicable Any other related information This would help us provide faster responses to your query. Feedback We welcome your feedback that will help us improve the APIs and provide future enhancements. Send your feedback to: AdventNet, Inc. 13

15 Technology Overview SNMP Overview Versions of SNMP SNMPv3 Overview MIB Overview This section gives an overview of SNMP and MIB basics. More Information If you would like to learn more about SNMP, we would recommend you taking a look at the following site for more information. SNMP FAQ available at AdventNet, Inc. 14

16 SNMP Overview A network provides ease of communication between computers. To use networks effectively, we need a set of rules by which all the networks should abide. The set of rules is called protocols. Simple Network Management Protocol (SNMP) is one among the various protocols that defines messages related to network management. In simple terms, SNMP is a primary protocol, used in the transfer of network management information between two or more network entities or nodes. Let us get to know more about SNMP and its features in the following sections. Need for SNMP Evolution Advantages Features Basic Operations Need for SNMP Network Management is all about keeping the network up and running, monitoring, and controlling network devices using conventional network technology. Local management and remote management are the two ways of managing a device connected to a network. Local management demands for a human manager where the managed object is situated. When the network devices are more and the network is widespread, management becomes tedious and impossible. Therefore, there arises the need to manage the network remotely. This is enhanced by SNMP. Using SNMP, one workstation running one or more management software applications can monitor management information collected by thousands of network devices. This information is used to establish the functioning of the network and also to identify the problems in the network. Evolution The ARPANET was the first research network sponsored by the United States Department of Defense (DOD), which connected many universities and government installations using leased telephone lines. When satellite and radio networks were added, trouble brewed and to resolve it, TCP/IP came into existence. This facilitated the connection of multiple networks in a seamless way. On Jan , TCP/IP became the only official protocol used by the DOD that marked a decline of the ARPANET. It was then Internet came into existence. Sometime in the mid-1980s, the growth of Internet was rapid, but there were no standardized network management models. Later, the three models were formulated: the High-Level Entity Management System (HEMS); the Common Management Information Protocol (CMIP) proposed by the Open Systems Interconnection (OSI), a group of International Standards Organization (ISO); and the Simple Gateway Monitoring Protocol (SGMP). CMIP over TCP was formed by the ISO as the actual network management protocol to be used for the Internet. In February 1988, the then Internet Architecture Board (IAB) convened an ad hoc committee to determine which of the three models should be used. It was then decided that CMOT would be a natural choice. The SGMP was the short-term solution before CMOT was distributed. For an effective transition of systems from SGMP to CMOT, a common network management framework had to be developed that would be used by both the models. This framework was named the Simple Network Management Protocol (SNMP). In April 1989, SNMP was promoted and given a recommended status as the de facto TCP/IP network management framework by the IAB. By then, AdventNet, Inc. 15

17 there were problems between CMOT and SNMP, which led to their independent developments. In May 1990, on reaching a consensus, IAB promoted SNMP as the standard network management protocol and a framework recommended for use on Internet and on all TCP/IP networks. Advantages As the name goes, the protocol is quite simple because it is easy to understand and the agent requires only minimal software. It is this simplicity that serves as a key reason for its widespread acceptance, besides being the chief Internet standard for network management. Implementing SNMP management in a networked device is far more straightforward than most other approaches to network management. Some of the benefits you derive on using SNMP are as follows. Standardized protocol: SNMP is the standard network management protocol for TCP/IP networks. Internet Protocols are open, nonproprietary standards developed through voluntary efforts by the Internet community, so is the SNMP that is actively maintained and all future enhancements to SNMP are based on existing protocol standards. Universal acceptance: All major vendors support SNMP. All SNMP-managed devices use the same type of management interface to support a common set of network management information. Portability: SNMP is independent of operating system and programming language. The functional design of SNMP is also portable and it defines a core set of operations that must function identically in all devices that support SNMP. Lightweight: SNMP facilitates the addition of management capability to a device without impacting the operation of the device or its performance. SNMP management may be added to a network device with very little increase in workload and demand on system resources. Extendibility: SNMP is a core set of operations that remain the same on all managed devices. SNMP has the capability of supporting any type of information on any type of device that may be part of any type of computer network. Widely deployed: SNMP is one of the most popular protocols in the protocol suite that every vendor is aware of. This popularity serves as one dominant factor for its wide deployment by the vendors. Features The three major components of the SNMP that form an integral part of its foundation are the network device, the agent and the manager. Network device: A network device or the Managed Object is a part of the network that requires some form of monitoring and management. Agent: An agent is a mediator between the manager and the device. The agent resides inside the network device. It collects the management information from the device and makes it available to the manager. It is to be understood that an agent is a program that resides in the device and is not a separate entity. A typical agent: Implements full SNMP protocol. Stores and retrieves management information as defined in the MIB. Collects and maintains information about its local environment. Asynchronously signals an event to the manager. Acts as a proxy for some non-snmp manageable network node. AdventNet, Inc. 16

18 Manager: A manager or management system is a separate entity that manages the agents from a remote place. This is typically a computer that is used to run one or more network management systems. Consider an organization having its branches in different geographical locations. Administration of all the computers present in different localities would be difficult. When the System Administrator s computer is installed with the manager and all other systems and devices across all the offices are installed with the agent, management becomes easier. The administrator has to just query the agent through its manger to know the functioning of the device. A typical manager: Implements the network management system. Implements full SNMP protocol. Queries agents, gets responses from agents, sets variables in agents, and acknowledges asynchronous events from agents. Communication Between the Manager and Agent: The communication between the manager and the agent in the network is enabled by means of Protocol Data Units (PDUs). These PDUs allow the manager to interact with the agent in the device. The extent of management possible depends on the data available to the manager from the agent. Before data can be transported across the network, it must be passed down the network mass and encapsulated. PDUs are encapsulated in the User Datagram Protocol (UDP). UDP is a connectionless transport protocol included in the TCP/IP suite and described in RFC 768. The SNMP network management is composed of three parts to which both the management applications and agents conform. They are: The protocol, which defines the functioning of the basic operations of SNMP and the format of the messages exchanged by management systems and agents. Structure of Management Information (SMI), which is a set of rules used to specify the format for defining managed objects or the devices that are accessed using SNMP. Management Information Base (MIB) is a collection of definitions, which define the properties of the managed object or the device. The MIB modules and the SMI are expressed using a text-based data description notation called as Abstract Syntax Notation One (ASN.1), which is an unambiguous description of data in an ASCII text format. The MIB data is conveyed across a network using SNMP messages, which are encoded using Basic Encoding Rules (BER). They are similar to SMI, but the messages are encoded in a binary format. Both the ASN.1 and BER are essential for the implementation of SNMP. Basic Operations SNMP is a request-and-response protocol. The basic SNMP operations performed are categorized as follows. Retrieving data Altering variables Receiving unsolicited messages Retrieving data: The manager sends a request to an agent to retrieve data by performing the following operations. GET: The GET operation is a request sent by the manager to the managed object. It is performed to retrieve one or more values from the managed objects. GETNEXT: This operation is similar to the GET operation. The significant difference is that the GETNEXT operation retrieves the value of the next OID in the tree. GETBULK: The GETBULK operation is used to retrieve voluminous data from large table. AdventNet, Inc. 17

19 Altering variables:at times,the manager might want to change the value of a variable. SET: This operation is used by the managers to modify the value of the network device. Receiving unsolicited messages: The agent, when faced by problems in the transmission of message, responds to the manager by sending unsolicited messages by using the TRAP operation. AdventNet, Inc. 18

20 Versions of SNMP Overview of the Versions SNMPv1 and SNMPv2c SNMPv1 and SMPv3 SNMPv1, SNMPv2c, and SNMPv3 Internet Engineering Task Force (IETF) publishes documents that are called Requests For Comments (RFCs). These documents specify standards, operational practices, opinions, humor, etc. for the Internet protocol suite. The different versions of SNMP are the SNMPv1, SNMPv2c, and SNMPv3. The following is a snippet of each version and it is followed by a detailed comparative overview of the versions. SNMPv1: This is the first version of the protocol, which is defined in RFCs 1155 and SNMPv2c: This is the revised protocol, which includes enhancements of SNMPv1 in the areas of protocol packet types, transport mappings, MIB structure elements but using the existing SNMPv1 administration structure ("community based" and hence SNMPv2c). It is defined in RFC 1901, RFC 1905, and RFC SNMPv3: SNMPv3 defines the secure version of the SNMP. SNMPv3 also facilitates remote configuration of the SNMP entities. It is defined by RFC 1905, RFC 1906, RFC 2571, RFC 2572, RFC 2574, and RFC The AdventNet SNMP API distribution supports all the three versions of the SNMP. The communication and MIB portions of the AdventNet SNMP API conform to the following Internet RFC specifications. SNMPv1 - RFC1155 and RFC1157 SNMPv2c - RFC1901 and RFC1907 SNMPv3 - RFC2571 and RFC2572 SNMPv3 USM - RFC2574 SNMPv3 VACM - RFC2575 Overview of SNMP Versions SNMPv1 was the standard version of SNMP. The SNMPv2 was created as an update of SNMPv1 with several features. The key enhancements of SNMPv2 are focused on the SMI, Manager-tomanager capability, and protocol operations. The SNMPv2c combined the community-based approach of SNMPv1 with the protocol operation of SNMPv2 and omitted all SNMPv2 security features. One notable deficiency in SNMP was the difficulty in monitoring networks, as opposed to nodes on networks. A substantial functional enhancement to SNMP was achieved by the definition of a set of standardized management objects referred to as the Remote Network Monitoring MIB (RMON MIB) objects. Another major deficiency in SNMP was the complete lack of security facilities. The development of SNMPv3 was based on the security issues. SNMPv3 defines two security-related capabilities, namely USM and VACM. SNMPv1 and SNMPv2c SNMPv2c provides several advantages over SNMPv1. SNMPv2c has expanded data types of 64-bit counter. It calls for improved efficiency and performance by introducing the GETBULK operation. Confirmed event notification is sought by the introduction of the Inform operator. Enhanced error AdventNet, Inc. 19

21 handling approach, improved sets, and a fine tuned Data Definition Language are some of the advantages of SNMPv2c over the SNMPv1. SNMPv1 and SNMPv3 The SNMPv1 framework distinguishes between application entities and protocol entities. In SNMPv3, these are renamed as applications and engines respectively. The SNMPv1 framework also introduces the concept of an authentication service supporting one or more authentication schemes. In SNMPv3, the concept of an authentication service is expanded to include other services, such as privacy. The SNMPv1 framework introduces access control based on a concept called an SNMP MIB view. The SNMPv3 framework specifies a fundamentally similar concept called view-based access control. SNMPv1, SNMPv2c, and SNMPv3 Both the versions v1 and v2c lack the following security-related features. Authentication Privacy Authorization and access control Remote configuration and administration capabilities SNMPv3 was formed mainly to address the deficiencies related to security and administration. AdventNet, Inc. 20

22 SNMPv3 Overview Comparative Overview of SNMPv3 with SNMPv1 and SNMPv2c SNMPv3 Message Format Due to lack of security with the use of SNMP, network administrators were using other means, such as telnet for configuration, accounting, and fault management. SNMPv3 addresses issues related to the large-scale deployment of SNMP, accounting, and fault management. Currently, SNMP is predominantly used for monitoring and performance management. SNMPv3 defines a secure version of SNMP and also facilitates remote configuration of the SNMP entities. Primary Goals of SNMPv3 1. To verify that each received SNMP message has not been modified during its transmission through the network. 2. To verify the identity of the user on whose behalf a received message claims to have been generated. 3. To detect received messages that contain management information, whose time of generation was not recent. 4. To assure that the contents of each received message are protected from disclosure. Comparative Overview of SNMPv3 with SNMPv1 and SNMPv2c SNMPv1 and SNMPv2c have a wide deployment base covering the following. A platform-independent data definition syntax - A subset of ASN.1 A platform-independent data transfer notation - BER Communication between the peer entities - SNMP communication protocol with message formats, message types, etc. o Message contains the SNMP version o Message contains the community string which is used to provide some security Guidelines for definition of management data - SMI Management data definition repository - The MIB files SNMPv3 provides a secure environment for the management of systems covering the following. Identification of SNMP entities to facilitate communication only between known SNMP entities - Each SNMP entity has an identifier called the SNMPEngineID, and SNMP communication is possible only if an SNMP entity knows the identity of its peer. Traps and Notifications are exceptions to this rule. Support for security models - A security model may define the security policy within an administrative domain or an intranet. SNMPv3 contains the specifications for USM. Definition of security goals where the goals of message authentication service include protection against the following. o Modification of Information - Protection against some unauthorized SNMP entity altering in-transit messages generated by an authorized principal. o Masquerade - Protection against attempting management operations not authorized for some principal by assuming the identity of another principal that has the appropriate authorizations. o Message Stream Modification - Protection against messages getting maliciously reordered, delayed, or replayed to effect unauthorized management operations. o Disclosure - Protection against eavesdropping on the exchanges between SNMP engines. AdventNet, Inc. 21

23 Specification for USM - USM consists of the general definition of the following communication mechanisms available. o Communication without authentication and privacy (NoAuthNoPriv). o Communication with authentication and without privacy (AuthNoPriv). o Communication with authentication and privacy (AuthPriv). Definition of different authentication and privacy protocols - Currently, the MD5 and SHA authentication protocols and the CBC_DES privacy protocols are supported in the USM. Definition of a discovery procedure - To find the SNMPEngineID of an SNMP entity for a given transport address and transport endpoint address. Definition of the time synchronization procedure - To facilitate authenticated communication between the SNMP entities. Definition of the SNMP framework MIB - To facilitate remote configuration and administration of the SNMP entity. Definition of the USM MIBs - To facilitate remote configuration and administration of the security module. Definition of the VACM MIBs - To facilitate remote configuration and administration of the access control module. The SNMPv3 focuses on two main aspects, namely security and administration. The security aspect is addressed by offering both strong authentication and data encryption for privacy. The administration aspect is focused on two parts, namely notification originators and proxy forwarders. SNMPv3 defines two security-related capabilities, namely the USM and VACM. USM provides authentication and privacy (encryption) functions and operates at the message level. VACM determines whether a given principal is allowed access to a particular MIB object to perform specific functions and operates at the PDU level. SNMPv3 Message Format The SNMPv3 message consists of the following fields. 1. msgversion - This field contains the SNMP message version. A value 0 is an SNMPv1 message, 1 is an SNMPv2c message, 2 is an SNMPv2 message, and 3 is an SNMPv3 message. The value of message version is used to choose between the different message processing models (SNMPv1, SNMPv2c, or SNMPv3) available in the SNMP engine/entity. The following fields are part of the SNMPv3 message and are not available in the SNMPv1 or SNMPv2c message. 2. msgid - This field contains the SNMP message identifier. This is the unique ID associated with the message. The msgid field is different from the reqid field available in the PDU. It is possible that a received PDU that is part of a message cannot be decoded due to security parameters between the SNMP entities. The msgid is used to relate the request with a response during a transaction. 3. msgmaxsize - This field gives the maximum size of the message which the requesting SNMP entity can accept. 4. msgflags - This field contains the message security level. The bit 0 of msgflags indicates whether a message is authenticated. The bit 1 indicates whether a message uses privacy. The bit 2 indicates whether a report PDU is expected for the message (in case the message is dropped or a response cannot be generated). 5. msgsecuritymodel - This field indicates the security model used to generate the message. It has a value of 3 when USM is used. 6. msgengineid - This field has the SNMPEngineID of the authoritative SNMP entity involved in the transaction. When a request PDU is generated from an SNMP engine, the remote peer (agent for Get request and manager for Trap request) is the authoritative SNMP entity. 7. msgengineboots - This field indicates the number of times the authoritative SNMP entity has booted. This field is used in authenticated message to validate the timeliness of a message. AdventNet, Inc. 22

24 8. msgenginetime - This field indicates the time since the authoritative SNMP entity has been rebooted. This field is used in authenticated messages to validate the timeliness of a message. 9. msgusername - This field contains the principal who originated the request. The fields msgusername and the msgengineid are used to locate the security data associated with the message from the USM database. This security data is used to authenticate and process the message. 10. msgsecurityparams - This field contains the security parameters that are security model dependent. It contains the authentication parameters and the privacy parameters for USM. For an AuthPriv message, the authentication parameter has the digest computed for the message using the authentication protocol applicable for the USM entry and the privacy parameter has the salt generated, while encrypting the message using the privacy protocol applicable to the USM entry. 11. contextengineid - Within an administrative domain, the contextengineid uniquely identifies an SNMP entity that may realize an instance of a context with a particular contextname. 12. contextname - A contextname is used to name a context. Each contextname must be unique within an SNMP entity. 13. PDU - The SNMP PDU (Protocol Data Unit) is used for communication between the SNMP entities. PDU encapsulates the SNMP request ID, error status, variable bindings, and so on. There are different types of PDUs, such as GetRequest-PDU, GetNextRequest-PDU, GetBulkRequest-PDU, Response-PDU, SetRequest-PDU, Trap-PDU, InformRequest-PDU, SNMPv2-Trap-PDU, and Report-PDU. The exact format of the PDU depends on the type of the PDU. AdventNet, Inc. 23

25 MIB Overview Management Information Bases (MIBs) are a collection of objects or definitions that define the properties of the managed objects. To enable the SNMP manager or management application to operate intelligently on the data available on the managed device, the manager needs to know the names and types of objects in the device. This is made possible by the MIB modules, which are specified in the MIB files usually provided with managed devices. It should be understood that MIB is only an abstraction of data and not a physical database or a physically executable object. The following sections are dealt with in detail in this topic: Evolution Object Identifiers MIB Objects Object Identifiers with Instance Indexes SMI Evolution IAB recommended a two-pronged strategy for the development of Internet network management standards. The SNMP was used in the short run and the use of OSI network management framework was examined in the long run. On this basis, two documents were created, which defined the SMI and MIB. The documents were framed to be compatible with both the SNMP and OSI network management framework. In the short run, this strategy proved successful. However, the report of the Second Ad Hoc Network Management Review Group stated that the SNMP and OSI framework did not fulfill the exact requirements. Therefore, both were suspended which in due course led to the drafting of MIB II. MIB-I was the first version issued as RFC1156. MIB-II is a super set of MIB-I with some additional objects and groups and is defined in RFC1213. Object Identifiers The SNMP manager or the management application uses a well-defined naming syntax to specify the variables to the SNMP agent. Object names in this syntax are called Object Identifiers (Object IDs or OIDs). OIDs are series of numbers that uniquely identify an object to an SNMP agent. OIDs are arranged in a hierarchical, inverted tree structure. The OID tree begins with the root and expands into branches. Each point in the OID tree is called a node and each node will have one or more branches, or will terminate with a leaf node. The format of OID is a sequence of numbers with dots in between. There are two roots for Object Identifiers, namely iso and ccit. iso starts with.1 and ccit starts with.0. Most Object Identifiers start with , where 1=iso, 3=org, 6= dod, 1 = internet. The internet subtree branches into mgmt and private. To understand the concept of relative and absolute Object Identifiers, let us consider the AdventNet Object Identifier It specifies the path from the root of the tree. The root does not have a name or a number but the initial 1 in this OID is directly below root. This is called an absolute OID. However, a path to the variable may be specified relative to some node in the OID tree. For AdventNet, Inc. 24

26 example, specifies the syscontact object in the system group, relative to the internet ( ) node in the OID tree. This is called a relative OID. MIB Objects The internet subtree branches into mgmt and private. All the standard MIBs are under mgmt, while the private MIBs are under the private.enterprises subtree. The standard MIBs are those that have been approved by the IAB. Equipment and software vendors define the private MIBs unilaterally. A branch within the private.enterprises subtree is allocated to each vendor who registers for an enterprise Object Identifier. The distinction between the standard and private MIBs is based on how the variables are defined. The best example of a standard MIB is the RFC1213-MIB (also known as MIB-II). It is a MIB module which is typically supported by all SNMP agents on TCP/IP-enabled devices or systems. This MIB file contains a description of the object hierarchy on the managed device, as well as the Object ID, syntax, and access privileges for each variable in the MIB. To know more on RFC, visit One key aspect of MIBs is that, only the types of objects on the managed device are specified by the MIB and not the specific objects (or instances). For example, ifinoctets in RFC 1213-MIB specifies a type of object, for number of input octets on an interface, but the specific objects or instances of that type are specified as ifinoctets.1, ifinoctets.2, etc., depending on the number of interfaces. When specifying an object to the SNMP agent, a proper Object ID, which includes the instance, needs to be used by the manager. When not properly specified, the agent responds with a "No such variable" error. Object Identifier with Instance Indexes To obtain values of objects from the agent, you need to specify the instance of the object. Appending an instance index to the object identifier specifies the instance of an object. For example, the last 0 in:.iso.3.dod.1.mgmt.mib-2.1.sysuptime.0 is the instance index. An instance index of "0" (zero) specifies the first instance, "1" specifies the second instance, and so on. Since sysuptime is a scalar object, it has only one instance. Therefore, an instance index of zero is always specified when retrieving the value of a scalar object. An instance index higher than 0 can only be used in the case of columnar objects (in table), which can have multiple instances. SMI Structure of Management Information (SMI) is a set of rules used to specify the format for defining managed objects. SMI describes the MIB naming tree that is used to identify managed objects and defines the branch of the MIB tree where SNMP managed objects reside. The SMI does not define a managed object but describes a format for defining a managed object. The two versions of SMI are SMIv1 and SMIv2. SMIv1 is defined by RFC1155, RFC1212, and RFC1215 and the SMIv2 is defined by RFC1902, RFC1903, and RFC1904. SMIv1 is a backward compatible update of SMIv1. This means that it is possible to convert an SMIv2 MIB to SMIv1 except for objects whose data type is Counter64. But when it comes to converting SMIv1 to SMIv2, there is no mechanical way of doing it because there is more information in the SMIv2 than in SMIv1. Also, the SMIv2 format contains constructs to define requirement specifications and implementation specifications, which do not form a part of the SMIv1. AdventNet, Inc. 25

27 Release Notes Issue in closing the session on calling session.close() is fixed. 100% cpu utilization on closing the session is fixed. Package changes in the product as per.net standard (refer to apidocs). AdventNet SNMP API.NET is tested with Microsoft Visual Studio.NET Framework 2.0 AdventNet, Inc. 26

28 Installation Guide System Requirements Installing SNMP API -.NET Edition Package Structure Installing Service Pack This section explains the system requirements and installation details of AdventNet SNMP API. AdventNet, Inc. 27

29 System Requirements Hardware Requirements Software Requirements Hardware Requirements The following table describes the suggested minimum configuration of the system that runs the product. Processor Type Processor Speed Memory Disk Space Pentium 500 MHz 128 MB RAM 150 MB Software Requirements Minimum requirement of.net Framework version 1.1 redistributable package to run applications developed using the.net Framework, which can be downloaded from Minimum requirement of Microsoft Visual J#.NET version 1.1 Redistributable Package to run your Visual J#.NET applications on a computer that already has the Microsoft.NET Framework version 1.1 installed. This can be downloaded from 7D674D2C7CA1&displaylang=en Note: The.NET Framework version 1.1 should be installed before installing the Visual J#.NET version 1.1 AdventNet, Inc. 28

30 Installing SNMP API.NET Edition The AdventNet SNMP API -.NET Edition is supplied as zip file. Download and extract the zip to install the product. AdventNet, Inc. 29

31 Package Structure The directory structure and the files present under the <AdventNet/SNMPAPI> distribution are provided below. All the files are extracted under <AdventNet/SNMPAPI>directory. The following image displays the package structure of AdventNet SNMP API. Directory/File bin conf examples tutorials help lib mibs COPYRIGHT LICENSE_AGREEMENT Description Contains the Update Manager utility for installing the service packs. Contains the config files Contains the example applications if SNMP and MIB applications. Contains the simple application tutorials. Contains the help documentation Contains the AdventNetMibsAPI.dll and AdventNetSnmp.dll. Contains the standard MIB files Copyright of the product Product License Agreement AdventNet, Inc. 30

32 Installing Service Pack AdventNet periodically provides service packs or patches which fix certain bugs or provide new features and update some files related to documentation. These patch files can be downloaded from the AdventNet Web Site and updated with the base release. AdventNet SNMP API provides you a tool, UpdateManger, to install the service packs. During the installation of a patch, the corresponding files are updated in the product installation directory and certain bugs are fixed. UpdateManager can be used to perform the following functions: Install the Service Pack View the Installed Service Pack Versions Uninstall the Service Pack Install the Service Pack To install the service pack, follow the steps given below: 1. Invoke the UpdateManager by executing the updatemanager.bat located in <SNMPAPI_Home>\bin directory. The options to install, uninstall, view installed Service Pack versions, and exit will be shown and you will be prompted to enter your choice. 2. Enter i to install a new Service Pack. The screen will prompt you to enter the path where the new Service Pack is located. 3. Enter the absolute path where the new Service Pack (.ppm file) is placed. You will see the update happening and the message Service Pack installed successfully will be shown. The screen will prompt you to mention whether you want to continue. 4. Choose y to go to the first step. 5. Choose n to close the application View the Installed Service Pack Versions 1. Invoke the UpdateManager by executing the updatemanager.bat located in <SNMPAPI_Home>\bin directory. The options to install, uninstall, view installed Service Pack versions, and exit will be shown and you will be prompted to enter your choice. 2. Enter v to view the details of the already installed Service Packs. The screen will show you the list of Service Packs installed in the product. The screen will prompt you to mention whether you want to continue. 3. Choose y to go back to the first step, choose n to close the application. Uninstall the Service Pack To uninstall the service pack, follow the setps given below: 1. Invoke the UpdateManager by executing the updatemanager.bat located in <SNMPAPI_Home>\bin directory. The options to install, uninstall, view installed Service Pack versions, and exit will be shown and you will be prompted to enter your choice. 2. Enter u to uninstall a Service Pack. The screen will show you the list of installed Service Packs and prompt you to select the one to be uninstalled. 3. Enter the number corresponding to the Service Pack to be uninstalled. You will see the uninstallation happening and the message "Uninstalled successfully" will be shown. The screen will prompt you to mention whether you want to continue. 4. Choose y to go back to the first step, choose n to close the application. AdventNet, Inc. 31

33 Developing Management Applications Using MIBs in Applications discusses the MIB-related aspects while developing the management applications. Configuring SNMP Agent Parameters discusses the common SNMPv2c parameters that need to be set while developing the applications. Handling Datatypes explains about the basic datatypes, application datatypes, and textual conventions. Data Retrieval Operations discusses the data retrieval operations such as GET, GETNEXT, GETBULK, and polling. Data Altering Operations discusses the SNMP SET operation using AdventNet SNMP API.NET Edition. Traps and Notifications explains how to receive and send traps using AdventNet SNMP API.NET Edition. Table Handling in Applications explains the various table-related operations that can be performed using AdventNet SNMP API.NET Edition. Error Messages details the various errors that are generated while using AdventNet SNMP API.NET Edition. Using Transport Providers discusses the transport providers that enable you to implement the protocol of your choice for SNMP communication. Deployment Instructions explains the steps involved in deploying the applications. Examples gives the detailed instructions on the usage of various command line tools and applications that are bundled with the AdventNet SNMP API product to query the SNMP devices/applications. Tutorials helps you get familiar with the development using AdventNet SNMP API.NET Edition. Sample CSharp programs are available that can be compiled and run. Performance Metrics gives the performance numbers for the various modules of AdventNet SNMP API.NET Edition. AdventNet, Inc. 32

34 Using MIBs in Applications Loading MIBs Unloading MIBs Parsing MIBs Accessing Node Information Retrieving MIB Information Exceptions and Error Messages Macro Type Constructs Management applications need to perform MIB-related operations, such as loading and parsing of MIBs, accessing the nodes in a MIB tree, getting information from leaf nodes, and so on. The MIB support API (mibs assembly) in AdventNet SNMP API provides the necessary support to perform these kinds of MIB-related operations. AdventNet, Inc. 33

35 Loading MIBs Applications can load the MIB modules directly from a file. The MibOperations class in the MIB support API provides the methods necessary to load and unload MIB modules in the management applications. The method loadmibmodules(string) of the MibOperations class can be used to load the MIBs. The loadmibmodules method loads a set of MIB modules specified by file names separated by space. The following piece of code illustrates how applications use MibOperations to load MIB files. MibOperations mibops = new MibOperations(); try { mibops.loadmibmodule("rfc1213-mib"); } catch (Exception ex){ System.err.println("Error loading MIBs: " +ex); } Factors to Consider While Loading MIB Files 1. The imported modules should be present in the current directory or the directory in which the MIB file is present. For example, the dependency file for the IF-MIB should be present in the same directory or in the current directory. 2. If the imported module is in a different directory, we can set the search path before loading the MIB. The search path can be set by using the method setmibpath(string). The API searches for the module in the path specified. Multiple paths can be given separated by a pipe( ) symbol. The following code snippet shows how to load a MIB file which has its dependency file in another directory. For example, if the IF-MIB is in mibs directory and if SNMPv2-MIB (dependency file for IF- MIB) is in the patchmibs directory, the following code shows how to load IF-MIB. MibOperations mibops = new MibOperations(); try { mibops.setmibpath("c:\adventnet\snmpapi\mibs\ C:\test\patchmibs\ "); mibops.loadmibmodule("if-mib"); } catch (Exception ex) { System.err.println("Error loading MIBs: " +ex); } 3. The API can load MIB files with the extensions mib, txt,and my. The method setmibfileextension(string) can be used to set the MIB file extension for the file to be loaded. Multiple extensions can be given separated by a space or a comma. Note that the extension names should not be cmi or cds because these extensions are reserved for loading compiled MIBs. AdventNet, Inc. 34

36 Loading Multiple Revisions of MibModules AdventNet SNMP API supports loading multiple revisions of MibModules. The setmultiplerevision(string revisionfilenames) method, is used for loading multiple revisions of MibModules, where the revision file names are given separated by a space or a pipe ( ) symbol. If we want to load multiple revisions of RFC1213-MIB, file names of this revision modules have to be set. For example, if the multiple revisions of RFC1213-MIB are in the files RFC1213-MIB.txt, RFC1213-MIB.mib, etc. we have to set these file names using the following method. mibops.setmultiplerevision("../mibs/rfc1213-mib.txt../mibs/rfc1213- MIB.mib"); After setting the multiple revisions, we should load these files explicitly. While loading, the file name is checked with the revisionfilenames we have set. If the file name matches, the modules are loaded with the names ModuleName+REVISION1, ModuleName+REVISION2, and so on. mibops.loadmibmodules("../mibs/rfc1213-mib.txt.../mibs/rfc1213- MIB.mib../mibs/RFC1213-MIB.my"); In this case, the modules will be loaded with the name of RFC1213-MIBREVISION1, RFC1213- MIBREVISION2, RFC1213-MIB. We have not set the file RFC1213-MIB.my in the setmultiplerevision() method and therefore it is loaded with the name of RFC1213-MIB. The files set in the setmultiplerevision() method and the files that are loaded should be exactly the same. If the file set in the setmultiplerevison() method is with respect to the relative path and the file loaded is with respect to the absolute path, both the files are considered as different although the path of the files is the same. For example, if the file set is../mibs/rfc1213-mib.txt, and the file loaded is /home/mibs/rfc1213-mib.txt, both these file names are considered as different and the module is loaded as RFC1213-MIB. The method getmultiplerevision() returns the multiple revision, if set. Otherwise it returns an empty string. The method IsMultipleRevision() is used to know whether the multiple revision is set or not. Applications can use addlabel(string addlabel) to add a label that is not treated as a reserved word by the parser. For example, "DisplayString", "PhysAddress", "TestAndIncr", "TimeStamp", "MacAddress", "RowStatus", "TimeInterval" and "DateAndTime" are not treated as reserved words. If your MIB uses some of the standard textual conventions or reserved words as a label for the MIB node, you can use the addlabel() method to tell the parser not to treat it as a reserved word. For example, if you do not wish to treat UInteger32 as a reserved word while parsing your MIB, use the following code. MibOperations mibops = new MibOperations(); mibops.addlabel("uinteger32"); try { mibops.loadmibmodules("your-mib"); } catch (Exception ex) { System.err.println("Error loading MIBs: " +ex); } AdventNet, Inc. 35

37 Unloading MIBs When a MIB module is unloaded, it dereferences all the node information corresponding to the unloaded module. When the MIB file is loaded again, a new reference for the MIB module is created. The MIB module is unloaded only if it is present in the module list. The method unloadmibmodule(mibmodule module) is used to unload the MIB module, given the MibModule instance. The method unloadmibmodule(string name) is used to unload MIB module by giving the name of the module, if present. Otherwise, it returns null. The method unloadallmibmodules() is used to unload all the MIB modules loaded in a MibOperations instance. AdventNet, Inc. 36

38 Parsing MIBs Parsing Levels Checks for Various Parsing Levels Checks in Detail This section explains the parsing and validating the syntax of the MIB module and constructing the MIB module into the tree structure. A detailed description of the different levels of parsing that can be set and their corresponding checks are also discussed in this section. AdventNet, Inc. 37

39 Parsing Levels Applications, while loading MIB files, perform the following operations. Parsing and validating the syntax of the MIB module Constructing the MIB module into the tree structure While performing the parsing and validation of the MIB files, if the MIB modules fail to conform to the SMI standards the loading will not be not done. However, the application requirements might mandate the loading of the non-standard files. On the other hand, some applications might require a stricter check on the compliance to the standards. The parsing and validating the syntax of the MIB file can be made configurable to suit the application requirements. AdventNet SNMP API handles this by providing the following set of parsing levels which facilitates to select the level of parsing required by the applications. Lenient Normal Serious Critical In addition to the above four parsing levels, SNMP API supports another level, which is user-defined. In case of user-defined level, you can define your own parsing level with the required checks at runtime. The code snippet for setting the parsing level is as follows. MibOperations mibops = new MibOperations(); mibops.setparsinglevel(miboperations.serious); try { loadmibmodules(filename); } catch(exception ex) { System.out.println(ex.getMessage()); } The various parsing levels are defined in the following constants. MibOperations.LENIENT MibOperations.NORMAL MibOperations.SERIOUS MibOperations.CRITICAL In the applications, parsing level has to be set first before loading a MIB. This level, once set, is used for subsequent MIBs that are loaded. If the level needs to be modified for the next set of MIBs loaded, it has to be set again. The parsing level can be set for the dependency file also. This can be done by using the method setimportsparsinglevel(sbyte parsinglevel). To get the parsing level of an imported MIB file, you need to use the getimportsparsinglevel() method. In addition, checks can be added or removed from a parsing level by using the methods addchecks(sbyte[] checks, sbyte parsinglevel) and removechecks(sbyte[] checks, sbyte parsinglevel) respectively. The getchecks(sbyte parsinglevel) method retrieves all the checks of the specified parsing level. AdventNet, Inc. 38

40 If there are any errors in the macro constructs, a parser exception is thrown. The geterrormodulenames() returns a vector of modules names, which contain the parsing errors. The geterrormessages(string module) returns a vector of MibErrorMessages object, which contains the error code, general error message associated with the parsing error, and a vector of ErrorObject objects. The object ErrorObject contains line number and the column number of the error messages and specific errors. Note: It is recommended to use the higher parsing level (SERIOUS, CRITICAL) for validating the MIB file and not for loading the MIB file in the application. It affects the performance of the application while loading the MIB files, because it takes considerable amount of time and resources, such as memory, CPU usage etc. Constructing the MIB Module into the Tree Structure If parsing is completed successfully, the API resolves the parent and child nodes in the current module. If there are any unresolved nodes, it tries to load from the imported module that is defined in the IMPORTS section. If the unresolved object is not present even in the imported module, unresolved TC construct {objectname1, objectname2,...} exception is thrown. AdventNet, Inc. 39

41 Checks for Various Parsing Levels The following tables describes the different levels of parsing that can be set and their corresponding checks. S.No Level of Parsing Checks 1 Lenient No Checks 2 Normal Default checks 3 Serious Serious Checks 4 Critical Critical Checks Description This level is the default level accepting all types of MIB files. For example, it allows both SMIv1 and v2. This level conforms to the obsolete standards, such as RFC 1902, RFC 1903, etc. Most MIBs follow the obsolete standard. This level strictly follows the current standard. It accepts the constructs with interoperability and implementation problems. This level completely follows the SMIv1 and v2 standards. However, it does not accept the backward compatibility constructs, constructs with interoperability and implementation problems, etc. Normal Parsing Level When the parsing level is normal, the following checks are included. OBJECT_IDENTIFIER_CONSTRUCT CHECK_DEFAULT Serious Parsing Level When the parsing level is serious, the following checks are done in addition to Normal checks. IMPORTS_CONSTRUCT MODULE_IDENTITY_CONSTRUCT OBJECT_TYPE_CONSTRUCT TRAP_TYPE_CONSTRUCT NOTIFICATION_TYPE_CONSTRUCT TEXTUAL_CONVENTION_CONSTRUCT Critical Parsing Level When the parsing level is critical, the following checks are done in addition to Serious checks. AGENT_CAPABILITIES_CONSTRUCT OBJECT_GROUP_CONSTRUCT MODULE_COMPLIANCE_CONSTRUCT CHECK_IDENTIFIERS CHECK_MISCELLANEOUS When the parsing level is Lenient (default parsing level), none of the above checks are done. Besides the above mentioned parsing levels, you can choose your own parsing level with the required checks. The method RegisterParsingLevel(sbyte[] checks, sbyte parsinglevel) in the MibOperations class can be used for configuring a new parsing level. If any of the parent check is enabled, the AdventNet, Inc. 40

42 corresponding child checks are done. To construct a new parsing level that contains checks for validating the OBJECT-TYPE construct, you can do the following. sbyte[] object_type_checks = new sbyte[1]; object_type_checks[0] = MibParserConstants.OBJECT_TYPE_CONSTRUCT miboperations.registerparsinglevel((sbyte)5, object_type_checks); Note that the new parsing level should be registered with sbyte values other than 0, 1, 2, and 3. If you want to add a check to an existing parsing level or remove a check from an existing parsing level, you can use the methods AddChecks() and RemoveChecks(). To add the check CHECK_IDENTIFIERS (Critical level) to Serious parsing level: sbyte[] iden_checks = new sbyte[1]; iden_checks[0] = MibParserConstants.CHECK_IDENTIFIERS miboperations.addchecks(iden_checks, MibOperations.SERIOUS); To remove the check TRAP_TYPE_CONSTRUCT from the Serious parsing level: sbyte[] remchecks = new sbyte[1]; remchecks[0] = MibParserConstants.TRAP_TYPE_CONSTRUCT miboperations.removechecks(remchecks, MibOperations.SERIOUS); You can set the different parsing level for the IMPORTS MIB file by using the setimportsparsinglevel(sbyte parsinglevel) method. There are some rules that a MIB file should follow, without which the MIB tree is not formed properly. When the parser encounters such violations, MibException is thrown. The OID construct should contain atleast two suboids. The second and its subsequent suboids should be number or namenumber to identify their ancestors and their position in the MIB tree. In the OBJECT_IDENTIFIER construct, if the first suboid is a number, it should be 0. 1, or 2. If the suboid is a name Number, it should be ccit(0), iso(1), or joint-iso-ccit(2). The label of the last suboid should be same as the descriptor. The maximum value of the sub-identifier cannot exceed The table entry should be defined as a child of the corresponding table object. The module name of the MIB file should start with uppercase letter. The TC name should not start with lowercase letter. Therefore, the following checks are done even when the parsing level is set to lenient. These checks are termed as "Very Critical Checks" and are done irrespective of the parsing level. CHECK_ATLEAST_TWO_SUBOID CHECK_SECOND_SUBOID CHECK_FIRST_SUBOID CHECK_LAST_SUBOID CHECK_LONG_SUBOID CHECK_TABLE_OBJECT VALIDATE_MODULE_NAME VALIDATE_TC_NAME AdventNet, Inc. 41

43 Checks in Detail The checks are based on the Imports, macro constructs, and some miscellaneous specifications of the MIB file. All the checks are grouped with the parent checks. Parent Checks o OBJECT_IDENTIFIER_CONSTRUCT o CHECK_DEFAULT o IMPORTS_CONSTRUCT o MODULE_IDENTITY_CONSTRUCT o OBJECT_TYPE_CONSTRUCT o TRAP_TYPE_CONSTRUCT o NOTIFICATION_TYPE_CONSTRUCT o TEXTUAL_CONVENTION_CONSTRUCT o AGENT_CAPABILITIES_CONSTRUCT o OBJECT_GROUP_CONSTRUCT o MODULE_COMPLIANCE_CONSTRUCT o CHECK_IDENTIFIERS o CHECK_DEFVAL o CHECK_TABLE_CONSTRUCT o CHECK_SYNTAX o CHECK_ACCESS o CHECK_MISCELLANEOUS Normal Checks o OBJECT_IDENTIFIER_CONSTRUCT o CHECK_DEFAULT Serious Checks o IMPORTS_CONSTRUCT o MODULE_IDENTITY_CONSTRUCT o OBJECT_TYPE_CONSTRUCT o TRAP_TYPE_CONSTRUCT o NOTIFICATION_TYPE_CONSTRUCT o TEXTUAL_CONVENTION_CONSTRUCT Critical Checks o AGENT_CAPABILITIES_CONSTRUCT o OBJECT_GROUP_CONSTRUCT o MODULE_COMPLIANCE_CONSTRUCT o CHECK_IDENTIFIERS o CHECK_MISCELLANEOUS AdventNet, Inc. 42

44 Normal Checks OBJECT_IDENTIFIER_CONSTRUCT In the OID construct the second suboid should be a CHECK_SECOND_SUBOID name or namenumber. The OBJECT IDENTIFIERS should have atleast two CHECK_ATLEAST_TWO_SUBOID sub-identifiers. In the OBJECT IDENTIFIER construct, the first subidentifier should be any one of the following. CHECK_FIRST_SUBOID CHECK_LAST_SUBOID CHECK_LONG_SUBOID Value Name 0 ccitt 1 iso 2 joint-iso-ccitt In the OID construct, the label of the last sub-oid should be same as the descriptor. In the OID construct, the numbered suboid value should not exceed CHECK_RESERVED_WORDS CHECK_DEFAULT The following are reserved keywords which must not be used as descriptors or module names: ABSENT ACCESS AGENT- CAPABILITIES ANY APPLICATION AUGMENTS BEGIN BIT BITS BOOLEAN BY CHOICE COMPONENT COMPONENTS CONTACT-INFO CREATION-REQUIRES Counter32 DEFAULT DEFINED DEFINITIONS DEFVAL DESCRIPTION DISPLAY- HINT END ENUMERATED ENTERPRISE EXPLICIT EXPORTS EXTERNAL FALSE FROM GROUP Gauge32 IDENTIFIER IMPLICIT IMPLIED IMPORTS INCLUDES INDEX INTEGER Integer32 IpAddress LAST-UPDATED MANDATORY- GROUPS MAX MAX-ACCESS MIN MIN-ACCESS MINUS-INFINITY MODULE MODULE-COMPLIANCE MODULE-IDENTITY NOTIFICATION-GROUP NOTIFICATION-TYPE NOTIFICATIONS NULL OBJECT OBJECT-GROUP OBJECT- IDENTITY OBJECT-TYPE OBJECTS OCTET OF OPTIONAL ORGANIZATION Opaque PLUS- INFINITY PRESENT PRIVATE PRODUCT-RELEASE REAL REFERENCE REVISION SEQUENCE SET SIZE STATUS AdventNet, Inc. 43

45 CHECK_DEFAULT CHECK_PROPER_FIELDS CHECK_MULTIPLE_OCCURRENCE_OF_NODE VALIDATE_TC_NAME CHECK_MULTIPLE_OCCURRENCE_OF_ENUM_LABEL CHECK_ROW_OBJID CHECK_TABLE_OBJECT VALIDATE_MODULE_NAME STRING SUPPORTS SYNTAX TAGS TEXTUAL-CONVENTION TRAP-TYPE TRUE TimeTicks UNITS UNIVERSAL Unsigned32 VARIABLES VARIATION WITH WRITE-SYNTAX In the SEQUENCE construct, each sequence member should be separated by a comma and there should not be a comma at the end of last sequence member. In the GROUPS construct, the SYNTAX, WRITE-SYNTAX, MIN- ACCESS clauses are not allowed. The descriptor should be unique and mnemonic. The identifier for the TEXTUAL- CONVENTION should start with uppercase letter. The labels used in the enumeration list should be unique. The table entry must present immediately beneath the corresponding table object. i.e., The table entry object should be the child of the table object with sub identifier as "1". The table entry should be defined as a child of the corresponding table object. An ASN.1 module name should begin with an upper-case letter and continues with zero or more letters, digits, or hyphens, except that a hyphen can not be the last character, nor can there be two consecutive hyphens. Serious Checks IMPORTS_CONSTRUCT The following must not be included in an IMPORTS statement. CHECK_INVALID_IMPORTS_VALUES Named types defined by ASN.1 namely INTEGER, OCTET STRING, OBJECT IDENTIFIER, SEQUENCE, SEQUENCE OF. The BITS construct. CHECK_EXPORT_CONSTRUCT CHECK_CONSTRUCT_IN_IMPORTS The EXPORTS statement is not allowed in an SMIv2 MIB. All the items defined in a module is automatically imported. If any of the following datatypes and macros are defined in this document, they must be imported AdventNet, Inc. 44

46 IMPORTS_CONSTRUCT using the IMPORTS statement. Counter32, Gauge32, Integer32, IpAddress, MODULE-IDENTITY, NOTIFICATION-TYPE, Opaque, OBJECT-TYPE, OBJECT-IDENTITY, TimeTicks, Unsigned32 In an SMIv2 MIB, if the IMPORTS section contains INVALID_IMPORTS_IN_V2 RFC1155-SMI, it should be replaced by SNMPv2- SMI. MODULE_IDENTITY_CONSTRUCT There must be only one MODULE-IDENTITY CHECK_MODULE_IDENTITY_INVOCATION macro defined in the MIB. The MODULE-IDENTITY macro must be CHECK_MODULE_IDENTITY_OCCURRENCE defined immediately after the IMPORTS section. The REVISION clause should be defined in REVERSE_CHRONOLOGICAL_ORDER the revers chronological order. i.e. the latest revision should occur first. The UTCTime format is YYMMDDHHMMZ or YYYYMMDDHHMMZ. It should contain 11 or 13 characters. CHECK_UTC_TIME CHECK_LUPDATED_REVISION_UTC_TIME where YY - last two digits of year (only years between ) YYYY - last four digits of the year (any year) MM - month (01 through 12) DD - day of month (01 through 31) HH - hours (00 through 23) MM - minutes (00 through 59) Z - denotes GMT (the ASCII character Z) For example, " Z" and " Z" represent 8:15pm GMT on 19 February Years after 1999 must use the four digit year format. Years may use the two or four digit format." The UTC Time value mentioned in the LAST- UPDATED field should be same as the UTC Time value in the first of the REVISION field. OBJECT_TYPE_CONSTRUCT The following are the checks that fall under OBJECT_TYPE_CONSTRUCT. CHECK_DEFVAL, CHECK_TABLE_CONSTRUCT, OBJECT_TYPE_CONSTRUCT CHECK_SYNTAX, CHECK_ACCESS, CHECK_STATUS These are parent checks, which in turn include many checks. AdventNet, Inc. 45

47 TRAP_TYPE_CONSTRUCT The trap number should range between CHECK_TRAP_NUMBER If the trap is generic, the trap number should be CHECK_GENERIC_TRAP_NUMBER between 0 to 6. If the enterprise value is other than snmp, the value CHECK_ENTERPRISE_VALUE should be registered under enterprise OID ( ). NOTIFICATION_TYPE_CONSTRUCT For the NOTIFICATION-TYPE macro, the objects CHECK_NT_OBJECTS_ACCESS should not have an MAX-ACCESS value of 'notaccessible'. TEXTUAL_CONVENTION_CONSTRUCT The DISPLAY-HINT clause must not be present if the Textual Convention is defined CHECK_OCCURRENCE_OF_DISPLAY_HINT with any of the following syntax. OBJECT IDENTIFIER, IpAddress, Counter32 or any enumerated syntax (BITS or INTEGER). The standard format for DISPLAY-HINT is as follows. INTEGER Format: <intdisplayhint> = "d" ["-" number] <singlechar> <singlechar> = o x b CHECK_DISPLAY_HINT_FORMAT CHECK_TC_AS_SYNTAX OCTET STRING Format: <octetdisplayhint> = <octdisplayspec> <octdisplayspec> = number <displayformat> [<sepchar>] "*" number <displayformat> [<sepchar> [<reptermchar>]] <displayformat> = "d" "b" "o" "x" number - unsigned integer <sepchar> - separator character, any character except "*" and decimal digit <reptermchar> - repeat terminator character: any character other than "*" and decimal digit. The SYNTAX clause of a Textual Convention can not refer to a previously defined Textual Convention. The syntax could be any one of the following SNMP datatypes with possible sub-typing: INTEGER, OCTET STRING, OBJECT IDENTIFIER, Integer32, IpAddress, Counter32, Gauge32, Unsigned32, TimeTicks, and Opaque. AdventNet, Inc. 46

48 Critical Checks AGENT_CAPABILITIES_CONSTRUCT The CREATION-REQUIRES clause must not be present unless the object named in CHECK_CREATION_REQUIRES the correspondings VARIATION clause is a conceptual row. All objects which are named in the CHECK_ACCESS_FOR_CREATION_REQUIRES CREATION-REQUIRES clause must have an access level of "read-create". OBJECT_GROUP_CONSTRUCT The objects defined in the OBJECT-GROUP CHECK_OBJECTS_IN_THIS_MODULE macro should be defined in the same module where this OBJECT-GROUP is defined. The MAX-ACCESS value of the objects defined in the OBJECTS clause must be one of the following. accessible-for-notify CHECK_OBJECTS_ACCESS read-only read-write read-create The objects defined in the OBJECTS clause CHECK_INVALID_OBJECTS should not start with upper case. MODULE_COMPLIANCE_CONSTRUCT A MIN-ACCESS clause should not be present for CHECK_MIN_ACCESS_CONSTRUCT 1. columnar objects 2. objects with syntax as Counter32. A group named in a GROUP clause must not be CHECK_MANDATORY_GROUPS the one defined in the corresponding MANDATORY-GROUPS clause. The access value specified in the MIN-ACCESS clause must not be greater than is specified in the CHECK_MIN_MAX_ACCESS MAX-ACCESS clause of the OBJECT-TYPE macro. In the MODULE-COMPLIANCE construct, if the CHECK_OBJECTS_IN_MC MODULE clause doesn't contain any modulename, the objects should be defined in this module. CHECK_IDENTIFIERS The hyphen are not allowed for an ASN.1 identifier (except for use by information CHECK_HYPHEN_IN_IDENTIFIERS modules converted from SMIv1 which did allow hyphens). The descriptor should not exceed 64 CHECK_NO_OF_CHARACTERS_EXCEEDS_64 characters in length. The descriptor should not exceed 32 CHECK_NO_OF_CHARACTERS_EXCEEDS_32 characters in length. The convention for the naming of the table object is: CHECK_TABLE_NAMING_CONVENTION The table name should start with lowercase letter and it should ends with "Table". AdventNet, Inc. 47

49 CHECK_LC_NAME CHECK_ENUM_LABEL CHECK_TC_CASE VALIDATE_SEQUENCE_NAME CHECK_IDENTIFIERS The SEQUENCE object name should be same as the table name except, the initial lower case letter should be converted into upper case letter. The word "Table" should be replaced with the word "Entry". The table entry name should be same as the SEQUENCE name but the initial upper case letter should be converted into lower case letter. For example, table name: iftable SEQUENCE name: IfEntry entry name : ifentry The descriptors/identifiers for the following macros should not start with upper case letter. OBJECT-TYPE, NOTIFICATION-TYPE, NOTIFICATION-GROUP, OBJECT- GROUP, MODULE-COMPLIANCE, AGENT-CAPABILITIES TRAP-TYPE, OBJECT-IDENTITY, MODULE-IDENTITY The labels used in the enumeration list should not start with upper case or number and it should not contain hyphen. The descriptor for the TEXTUAL- CONVENTION should not consist of all upper case letters. The descriptor for the SEQUENCE construct should start with upper case. CHECK_DEFVAL The binary value should contains zeros and ones. The value should contain eight digits CHECK_BINARY_DEFVAL and should be enclosed within single quotes and should end with 'b 'or 'B'. The hex defval should contain even number of CHECK_HEX_DEFVAL digits. The value should be enclosed in single quotes and should end with 'h' or 'H'. The DEFVAL clause should not be present for CHECK_DEFVAL_FOR_COUNTER_SYNTAX the nodes whith syntax Counter/Counter32. For the nodes with syntax as OBJECT- CHECK_OID_OIDY_DEFVAL IDENTIFIER, the value of the DEFVAL clause should be an OBJECT-IDENTITY macro. For the nodes with syntax as OBJECT IDENTIFIER, the DEFVAL clause value should be: CHECK_INVALID_OID_DEFVAL 1. defined in this module or imported from any other MIB module. 2. expressed as a single ASN.1 identifier, and not as a collection of sub-identifiers. The value of the DEFVAL clause must correspond to the SYNTAX clause for the VALIDATE_DEFVAL object. Also, the default value should not contradict the range/values specified in syntax for a particular variable. AdventNet, Inc. 48

50 CHECK_TABLE_CONSTRUCT The number of nodes defined in the SEQUENCE construct should be same as the number of nodes actually defined. CHECK_SEQUENCE_CONSTRUCT Also the syntax defined in the SEQUENCE construct should not contradict with the syntax in the node definition. The index nodes cannot have the syntax CHECK_INDEX_NODE_SYNTAX Counter/Counter32. The node entry defined in the CHECK_RECURSIVE_AUGMENTS_CONSTRUCT AUGMENTS clause should not contains AUGMENTS clause. The SEQUENCE construct should CHECK_COLUMNAR_NODES contain atleast a single node which is not auxillary. The index node should not repeat in the CHECK_OCCURRENCE_OF_INDEX_NODE same INDEX clause. Atleast a single node in the SEQUENCE CHECK_OCCURRENCE_OF_ROWSTATUS_NODE construct should have RowStatus as syntax. In the INDEX clause, the IMPLIED CHECK_OCCURENCE_OF_IMPLIED_NODE keyword should be present only for the last node. In the INDEX clause, the IMPLIED keyword should be present only for the CHECK_IMPLIED_NODE_TYPE node with syntax as OCTET STRING with variable length or OBJECT- IDENTIFIER. The node present in the AUGMENTS CHECK_ENTRY_IN_AUGMENTS_CONSTRUCT construct should be a table entry. The subtyping information should not be CHECK_SEQUENCE_WITH_SUBTYPE present for the nodes present in the SEQUENCE construct. CHECK_FOR_SCALAR_INDEX The index node must not be scalar. The usage of the following named SMI types in the INDEX clause is allowed only in SMIv1 MIB. INTEGER OCTET STRING CHECK_INDEX_VALUE OBJECT IDENTIFIER NetworkAddress IpAddress These index values are not supported in SMIv2. CHECK_BITS_VALUE CHECK_SYNTAX The BITS value should be contiguous starting from 0 and if not contiguous, the next bit value should be multiple of eight (for e.g. 0,1,2,3,8,9,.). Although there is no SMI-specified limitation on the number of enumerations there may be implementation and AdventNet, Inc. 49

51 CHECK_SYNTAX interoperability limitations for sizes in excess of 128 bits. The enumerated value should not be CHECK_ENUM_IN_INTEGER32 present for the Integer32 type. For any object with an integer-valued SYNTAX clause, in which the corresponding INTEGER does not have a range restriction the object MUST have the value of the SYNTAX clause changed to Integer32, or have an appropriate range specified. If any object has a SYNTAX clause value CHECK_INVALID_V2_SYNTAX of Counter, the object MUST have the value of its SYNTAX clause changed to Counter32. If any object has a SYNTAX clause value of Gauge, the object MUST have the value of its SYNTAX clause changed to Gauge32, or Unsigned32 where appropriate. The syntax "NetworkAddress" should not CHECK_NETWORK_ADDRESS be used in an SMIv2-MIB. If the OCTET STRING syntax contains CHECK_FOR_SIZE_CLAUSE_IN_OCTET_STRING subtyping information, the SIZE clause must be present. The enumerated value start at 1 and must be numbered continuously. If the syntax of the objects defined in the CHECK_ZERO_IN_ENUM INDEX clause is enumerated Integer, the zero should not be used as an enumerated value. The SIZE clause should not be present CHECK_FOR_SIZE_CLAUSE_IN_INTEGER for the INTEGER and Integer32 syntax. In case of multiple ranges, the range CHECK_RANGE_INTERSECTION values should not overlap. The range definition ( ) is invalid. The range values should be unique. The range values should not duplicate. In the CHECK_RANGE_DUPLICATION range definition ( ). The value '150' is defined twice. The sub-typing information should not be present for the following syntax. CHECK_SUBTYPING_FOR_SYNTAX OBJECT IDENTIFIER, IpAddress, Counter32, and TimeTicks. The size of the OCTET STRING should CHECK_SIZE_FOR_OCTET_STRING not exceed The negative values should not be used CHECK_NEGATIVE_VALUE_IN_SIZE in the range definition. The keyword MAX and MIN should not CHECK_MAX_MIN_RANGE be used in the range definitions. The Opaque type is provided solely for CHECK_OPAQUE_SYNTAX backward-compatibility, and shall not be used for newly-defined object types. AdventNet, Inc. 50

52 CHECK_ACCESS If the syntax of the node is Counter/Counter32, the access value CHECK_ACCESS_FOR_COUNTER_SYNTAX should be either 'read-only' or 'accessible-for-notify'. If the syntax of the node is RowStatus, CHECK_ROWSTATUS_ACCESS the access value should be read-create. In a conceptual row, if any of the node has read-create as its access value, no CHECK_ACCESS_FOR_COLUMNAR_NODES other node in the same row can have the access value as read-write. The SMIv1 access value "notimplemented" should not be used in an CHECK_ACCESS_VALUE SMIv2 module. The access value for the table and table CHECK_ACCESS_IN_TABLE_AND_ENTRY_NODE entry should be 'not-accessible'. The access value for the index nodes CHECK_INDEX_NODE_ACCESS should be 'not-accessible'. CHECK_STATUS CHECK_STATUS The STATUS values for the SMIv2 MIB modules are current deprecated obsolete. CHECK_MISCELLANEOUS The object identifier value should not be placed between the module name and the "DEFINITIONS" keyword." CHECK_OID_BETN_MODNAME_DEFINITIONS TEST-MIB { iso org(3) dod(6) internet(1) private(4) enterprises(1) 2186} DEFINITIONS ::= BEGIN This is invalid. The ASN comments (--) should not be CHECK_COMMENTS_IN_TEXT present inside the quoted String. The SMIV1 keyword ACCESS should not be CHECK_ACCESS_KEYWORD used in an SMIv2 MIB. It should be replaced by MAX-ACCESS. The conceptual row should contain no more CHECK_NUMBER_OF_COLUMNAR_NODES than approximately 20 objects. The DEFVAL value should be present within CHECK_BRACES_IN_DEFVAL the braces. The value in the DEFVAL field should not be CHECK_EMPTY_DEFVAL empty. The SMIv1 macros must not be used in CHECK_FOR_SMIV1_CONSTRUCT SMIv2 information modules. AdventNet, Inc. 51

53 Accessing Node Information When a MIB file is loaded using the Miboperations class, a MibModule instance is created to store the information about the module loaded from the MIB file. The MibModule class is used to restrict the MIB operations to a specific MIB module. Some methods are present in both the MibModule class and the MibOperations class. If a method in MibOperations is used, it is applicable for the node in all the MIBs loaded in the application. If a method in the MibModule class is used, it is restricted to that particular module. The MIB file is parsed and MibNode objects are created to store information about each node. The MibNode class represents a MIB node in a MIB module tree. It contains references to its parents and children and also to its dependents. The LeafSyntax class represents the syntax of a leaf node in a MIB module. The MibNode and the LeafSyntax classes provide the methods necessary to access the information on the nodes in the MIB file. Apart from this, the classes also provide the following functions to the management applications. Ability to walk the loaded MIB modules as an ordered list of objects. Ability to access nodes with specific relationships to other nodes. The MIB file has to be loaded first using the loadmibmodule() of the MibOperations class. Then the getmibnode() is called to get the node associated with the MIB variable's object ID. This method can be called only when the name of the MIB module is not known. MibOperations mibops = new MibOperations(); try { mibops.loadmibmodule("rfc1213-mib"); } catch (Exception e) { System.out.println("Exception : "+e); System.exit(1); } MibNode node = mibops.getmibnode("sysdescr"); If the module name is known, the getmibnode() method of the MibModule class can be used to get the MIB node. When the getmibnode() method of the MibOperations class is called, the MIB node is searched in all the loaded MIB modules. Moreover, when a node occurs in more than one module, this method always returns the first occurrence of the node. For example, when getmibnode() method of MibOperations is called for the "rmon" node present in both RFC1271-MIB and RMON2-MIB, the MIB information corresponding to the first loaded module is returned. Therefore, to get a specific MIB node, it is advisable to use the getmibnode() method of the MibModule class. The MibNode class has methods to get all the details about a MIB variable. For example, the following code snippet gives some information about the selected MibNode. System.out.println("Syntax:"+node.getSyntax()); System.out.println("Access:"+node.printAccess()); System.out.println("Status:"+node.getStatus()); System.out.println("Reference:"+node.getReference()); System.out.println("OID:"+node.getNumberedOIDString()); System.out.println("Node:"+node.getOIDString()); System.out.println("Description:"+node.getDescription()); AdventNet, Inc. 52

54 The LeafSyntax class can be used to get the data type and value of the MibNode as shown below. LeafSyntax leafnode = node.getsyntax(); System.out.println("Value : "+leafnode.gettype()); System.out.println("Data-type : "+leafnode.getequivname()); Ability to walk the loaded MIB modules as an ordered list of objects The getnextleafnode() in the MibNode class returns the next leaf node by searching through the current module. This is useful for agents or manager applications looking for the OID or label for the next MIB node for GETNEXT requests. This method spans multiple modules. The getindexes(miboperations) and getindexnames() in MibNode class is used for getting the index name/node of the table. The getindexnames() returns vector of indexes (as String) for the table when invoked on the entry node of the table. On the other hand, getindexes() returns vector of indexes (as MibNode) when invoked on any of the column nodes except the entry node of the table. Ability to access nodes with specific relationships to other nodes Typically the relationship among the nodes are represented as parent-child or root-node because the MIBs are organized in an hierarchical format. The mibs namespace provides several methods that can be used to access the nodes with specific relationships. The method getparent() in the MibNode class gets the parent node of the current node and the method getchild(int subid) returns the child node corresponding to the particular subid. The getchildlist() returns the nodes children as a vector. The methods getrootnode() and the getrootnodes() in the MibModule class is used to get a reference to the root node in the loaded MibModule. If a module contains a single root node, both the methods getrootnode() and getrootnodes() return the root node. If a module contains more than one root node, the getrootnode() method returns null and the getrootnodes() method returns a vector of root nodes. MibOperations mibops = new MibOperations(); MibModule mibmodule; MibNode node; Vector childnodes; mibmodule = mibops.getmibmodule(your_mib_file_here); node = mibmodule.getrootnode(); childnodes = node.getchildlist();.... The methods isancestorof() and isdescendantof() is used to check whether the nodes is an ancestor or descendant of the specified node. The getcommonancestorwith(mibnode) method returns the common parent node of the selected MIB node. AdventNet, Inc. 53

55 Retrieving MIB Information Manipulating OIDs The MibModule class enables operations on the loaded MIB modules. This class instance for a MIB module is obtained by loading the MIB through the MibOperations object. The translatetonames(string) method of the MibModule is used for translating numbered OID String to named OID String. The translatetonumbers(string) method is used for translating named OID String to numbered OID String. If the OID does not start with a dot, the standard prefix is automatically appended and the OID String is returned. The getinstancestring(snmpoid) method of MibOperations class gets the instance component of the OID as a String. Instances of scalar objects are identified by the OID value of the object suffixed with ".0". Instances of columnar objects are identified by their OID values suffixed by their index components. The getinstancestring(snmpoid, MibNode) method of MibOperations class avoids having to search for node if already available. However, it is not ensured that a null is returned for a mismatched node. This returns the sub-string corresponding to the instance. For example, if the MibNode is system and the OID as sysdescr, the return value starts with the sub-id of mib-2. The intersection of the node OID and the given OID are eliminated from the returned OID string. The getnearestnode() method of MibModule class gets the nearest MIB node corresponding to the int array of the OID. The getnearestnode(snmpoid) method of MibOperations class searches all MIB modules loaded in this MibOperations instance and returns the OID if found. The getsubid() of the MibNode class gives the sub identifier of this node's object-identifier. The ObjectIdentifier have the 128 sub-identifiers, each sub-identifier can have the value ranges from 0 to The getnumberedoidstring() method of the MibNode class gives the numbered OID string of the node. The getoid() method of the MibNode class gives the numbered OID of the node as an int array. The getoidstring() method of the MibNode class gives the named OID of the node. The getoidvector() method of the MibNode class gets the named OID of the node as a vector. Processing MIB Information The createvariablebinding(string varname, String[] indexes, String value) method of the MibOperations class creates an SnmpVarBind instance with the supplied parameters. The method decodeinstancestring(string, Vector) of the LeafSyntax class decodes an instance string based on the instance and index nodes. The encodeinstancestring() method of the MibOperations class encodes an instance string based on the SNMP type of the index node. This encoded instance string should be concatenated to the node OID to get the complete OID. The encodeinstancestring() method of the LeafSyntax class encodes an instance string based on the index vector and index nodes. The createsnmpvarbind(vector, SnmpVar, Vector) method of the MibNode class creates an SnmpVarBind instance with the supplied parameters. The method decodedefval() of the MibNode class decodes the DEFVAL value that is defined for this node and returns the corresponding SnmpVar object. Displaying MIB Information To print the value in hex string format, you can use the tobytestring() method. To print the values in the NVT ASCII format, the setignorespecificcontrolcodes(boolean) method of the MibOperations class can be to set true. If the value is between 32 and 127, the ASCII value is printed. AdventNet, Inc. 54

56 Exceptions and Error Messages The possible exceptions while loading a MIB are tabulated below. Possible Exceptions FileNotFoundException Error parsing quoted filename Couldn't find file in search path specified Imported file name and module name mismatch Stream Corrupted Reasons If the file is not found in the path specified, this exception is thrown. The file name, if contains spaces, should be given within double quotes. If the quotes are not closed, this exception is thrown. The modules are searched in the path specified by the setmibpath() method. If the modules are not found, this exception is thrown. The imported MIB module name and its file name should be the same with any extensions. The default extensions are.my,.mib, and.txt. Other extensions can be set using setmibfileextension(). If any of the above conditions is not met, this exception is thrown. While loading MIBs, if the stream is corrupted, this exception is thrown. The various Parser Exceptions that you could get while using the MIBs API and the reasons for the same is tabulated below: Error Message The identifier should start with lowercase letter The identifier Module Name or Textual- Convention should start with an uppercase letter. The identifier should not start with number or special character. The MACRO definition (OBJECT-TYPE,TRAP- TYPE,...) may be missing. The identifier may be invalid. Reason When the identifier starts with an uppercase letter, a special character, or a number, this exception is thrown. The identifier, other than the Module Name and Textual-Convention, should start with a lower case letter. This exception is thrown when the identifiers Module Name and the Textual-Convention start with a lower case letter. If the identifier starts with a number or special character, this exception is thrown. If the identifier for the MACRO construct (OBJECT-TYPE, OBJECT IDENTIFIER, OBJECT-IDENTITY, TEXTUAL- CONVENTION, MODULE-IDENTITY, NOTIFICATION-TYPE, NOTIFICATION- GROUP, OBJECT-GROUP, TRAP-TYPE, AGENT-CAPABILITIES, MODULE- COMPLIANCE, SEQUENCE) is missing, this exception is thrown. sysdescr DisplayString (SIZE (0..255)) ACCESS read-only STATUS mandatory DESCRIPTION " description." ::= {system 1} Here the macro-type OBJECT- TYPE is missing. Also, if the identifier contains special character or numbers, this exception is thrown. AdventNet, Inc. 55

57 Error Message 1. The identifier should not start with uppercase letter or 2. In case of TEXTUAL- CONVENTION/SEQUENCE construct the keyword ASSIGNMENT (::=) was missing 1. The imported item should be separated by the symbol comma. 2. The IMPORTS construct should be terminated with the symbol semicolon. 3. The keyword 'FROM' was missing. Module name should start with the uppercase letter. The name of the Imported item should be 1. lowercase or 2. uppercase, if TEXTUAL-CONVENTION 3. SnmpConstruct or TypeName, which is the name of an SNMP type or construct defined in one of the SMI MIB modules; The OID component value should enclosed in brackets or the OID construct may not end with right brace. It may be expecting one of the following 1. The suboid may be missing. 2. The OID value reference should start with lowercase letter. 3. The OID value reference may start with modulename and separated with "." Atleast one object should be present in this construct, and 1. The object should start with lowercase letter. 2. The object may start with Modulename which is separated with period (ModuleName.objectName). 3. The objects should be separated by comma. The Enterprise name should start with lowercase letter or may start with module name which is separated with period. (ModuleName.enterprisesName) The keyword 'INDEX' or 'AUGMENTS' was missing. Reason If the Identifier starts with an uppercase letter, exception 1 is thrown. For example, EgpNeighborLoss TRAP-TYPE If the assignment symbol ::= is missing, then exception 2 is thrown. For example, DisplayString OCTET STRING In the IMPORTS section, for example, IMPORTS mgmt, NetworkAddress, IpAddress Counter, Gauge, TimeTicks FRM RFC1155-SMI 1. Comma missing between the imported items IpAddress and Counter. 2. Semicolon missing at the end of the IMPORTS construct. 3. The keyword FROM is mistyped. If the module name starts with a lower case letter, this exception is thrown. For example, rfc1213-mib DEFINITIONS ::= BEGIN In the IMPORTS section, The imported item other than the TC, may start with an upper case. The imported item may contain other than SnmpType or SnmpConstruct (all macros, such as OBJECT-TYPE, MODULE- IDENTITY etc. and base datatypes such as INTEGER, COUNTER etc..). This exception is thrown if the braces for the OID construct is missing or the parenthesis for the name number OID is missing. For example, mgmt OBJECT IDENTIFIER ::= { internet } 1. Here the suboid 2 is missing. mgmt OBJECT IDENTIFIER ::= { Internet 2 } 2. The OID value reference Internet starts with an uppercase letter. For example, In the OBJECT-GROUP construct, OBJECTS { ifinoctets ifoutoctets, ifinunknownprotos,ifinerrors, ifouterrors } 1. The object IfInErrors starts with an uppercase letter. 2. Comma missing between the object names ifinoctets and ifoutoctets. For example, ENTERPRISES Snmp Here the Enterprise name starts with uppercase letter. If the INDEX or AUGMENTS keywords are mistyped or missing in the Row Objects, this exception is thrown. AdventNet, Inc. 56

58 Error Message 1.The DEFVAL construct should enclosed in braces. 2. The default value within quotes. The additional comma present in the SEQUENCE member. The quoted string was expected. The non-negative integer number was expected. The default value is not correct The keyword 'SYNTAX' or 'SEQUENCE OF' is missing. 1.The keyword 'ACCESS' or 'MAX-ACCESS' was missing. or 2. The keyword 'SEQUENCE OF' was missing. or 3. The syntax with invalid subtype construct. The invalid OID construct in the OBJECT-TYPE construct. Was expecting the left brace or Was expecting the right brace. The keyword VARIABLES, DESCRIPTION, REFERENCE or the ASSIGNMENT (::=) may be missing. The keyword 'OBJECTS' or 'STATUS' may be missing. The keyword 'REFERENCE' or 'ASSIGNMENT (::=)' may be missing. The keyword 'REFERENCE' or 'MODULE' was missing Was expecting MANDATORY-GROUPS or GROUP/OBJECT keyword One of the following keyword is missing. 1. In case of OBJECT construct SYNTAX, WRITE-SYNTAX, MIN-ACCESS or DESCRIPTION may be missing. 2. In case of GROUP construct keyword DESCRIPTION was missing. Reason This exception is thrown when the braces are missing in the DEFVAL field or the value is not enclosed in quotes. This exception is thrown if there is an extra comma at the end of the last SEQUENCE member. This exceptions is thrown if the value of the Description and Reference fields is not enclosed in double quotes. For example, in the TRAP-TYPE, egpneighborloss TRAP-TYPE ENTERPRISE snmp VARIABLES { egpneighaddr } DESCRIPTION "description" ::= -5 Here the trap number is negative. This exception is thrown if the value in the DEFVAL field is not correct. This exception is thrown if the SYNTAX or the SEQUENCE OF keyword is missing in the OBJECT-TYPE construct. This exception is thrown if the keywords ACCESS, MAX-ACCESS or SEQUENCE OF are missing in the OBJECT-TYPE construct. This exception is thrown if the OID value may not terminate with a right brace in the OBJECT-TYPE construct. This exception is thrown if the brace (left or right) is missing. If one of the mentioned keywords are missing in the TRAP-TYPE construct, this exception is thrown. This exception is thrown if the keywords OBJECTS and STATUS are missing in the NOTIFICATION-TYPE construct. This exception is thrown if the REFERENCE or ASSIGNMENT keyword is missing in the NOTIFICATION-TYPE construct. This exception is thrown if the REFERENCE or MODULE field is missing in the MODULE- COMPLIANCE construct. This exception is thrown if the MANDATORY-GROUPS or GROUP/OBJECT keyword is missing in the MODULE-COMPLIANCE construct. This exception is thrown if the mentioned keywords are missing in the MODULE- COMPLIANCE construct. AdventNet, Inc. 57

59 Error Message The keyword 'REVISION' was missing. One of these keyword 'REFERENCE' 'SUPPORTS', 'VARIATIONS' or ASSIGNMENT (::=) may be missing. One of these keyword 'SYNTAX', 'WRITE- SYNTAX', 'ACCESS', 'CREATION-REQUIRES' or 'DEFVAL' may be missing. The keyword 'DESCRIPTION' or 'REFERENCE' was missing. The 'ASSIGNMENT' or 'DEFVAL' keyword was missing. The ASSIGNMENT keyword was missing." The keyword was missing For the table and row OBJECT-TYPE construct the ACCESS value should be 'not-accessible'. or The access should contain one of these values : SMIv1/v2 access values. Here access is ACCESS/MAX-ACCESS for SMIv1 and SMIv2 respectively. SMIv1 access values: not-accessible","read-only","read-write","writeonly" SMIv2 access values: "not-accessible","read-only","read-write","writeonly","read-create" accessible-for-notify", notimplemented" The 'INDEX' or 'AUGMENTS' keyword was missing in the table row object type construct which contains the sequence as {sequencename} Reason This exception is thrown if the REVISION keyword is missing in the MODULE- IDENTITY construct. This exception is thrown if the mentioned keywords are missing in the AGENT- CAPABILITIES construct. This exception is thrown if the mentioned keywords are missing in the AGENT- CAPABILITIES construct. This exception is thrown if the mentioned keywords are missing in the OBJECT- TYPE construct. This exception is thrown if the mentioned keywords are missing in the OBJECT- TYPE construct. This exception is thrown if the keyword "ASSIGNMENT" is missing. This exception is thrown if the keyword "keyword" is missing. The keywords are SEQUENCE, LAST-UPDATED, CONTACT- INFO, DESCRIPTION, DESCRIPTION, ORGANIZATION, DISPLAY-HINT, STATUS, REFERENCE, SYNTAX, ENTERPRISES, VARIABLES, ASSIGNMENT (::=), OBJECTS, ACCESS, UNITS, MAX- ACCESS, MIN-ACCESS, DEFVAL, SEQUENCE OF, SEQUENCE or OBJECT IDENTIFIER, PRODUCT- RELEASE,MODULE, MANDATORY- GROUPS, SUPPORTS, INCLUDES, VARIATION, WRITE-SYNTAX, CREATION-REQUIRES, NOTIFICATIONS, and OBJECT IDENTIFIER. For example, iftable OBJECT-TYPE SYNTAX SEQUENCE OF IfEntry ACCESS accessible STATUS mandatory DESCRIPTION "description" ::= { interfaces 2 } Here the ACCESS value is accessible, for the table node. For example, ifentry OBJECT-TYPE SYNTAX IfEntry ACCESS not-accessible STATUS mandatory DESCRIPTION "An interface entry containing objects at the AdventNet, Inc. 58

60 Error Message Couldn't resolve these TC constructs : {TCObject, nodeobject...} Couldn't resolve these sequence constructs : {sequencename} Cyclic TC keyvalue encountered in modulename. Was expecting a ModuleName and that should be in upper case or atleast in proper case Encountered a reserved word reservedword suboid value should not exceed Reason subnetwork layer and below for a particular interface." ::= { iftable 1 } This exception is thrown because here the field "INDEX { ifindex } " is missing. The 'INDEX' or 'AUGMENTS' keyword was missing in the table row object type construct which contains the sequence as IfEntry. These nodes might not be defined in the MIB or in the imported MIB module and therefore the corresponding TC or nodeobject could not be resolved throwing this exception. For example, iftable OBJECT-TYPE SYNTAX SEQUENCE OF IfEntry ACCESS not-accessible STATUS mandatory DESCRIPTION "description" ::= { interfaces 2 } ifentry OBJECT-TYPE SYNTAX Iftry ACCESS not-accessible STATUS mandatory DESCRIPTION "description." INDEX { ifindex } ::= { iftable 1 } Ifntry ::= SEQUENCE { Here in the entry node ifentry, the sequence name is mistyped as Iftry. This exception is thrown because there is no SEQUENCE by the name Iftry. Also the sequence name may not be the one that is defined in the syntax of iftable. TCString1 ::= TCString2 TCString2 ::= TCString1 Here the TCString syntax is TCString2 whose syntax is TCString1. It gets into an indefinite loop throwing the CyclicTC exception. This exception is thrown if the module name starts with a lower case letter or contains a special character other than hyphen. For example, Integer32 ::= INTEGER Here Integer32 is being used as a label for defining the TC. This exception is thrown because Integer32 is a reserved word. If you do not wish to treat Integer32 as a reserved word, you have to use the method addlabel(string label) of the MibOperations class before loading the MIB. This exception is thrown if the suboid value exceeds the maximum value AdventNet, Inc. 59

61 Macro Type Constructs The MIB file can contain one or more MIB modules. Following are the macros defined in the SMIv1 and SMIv2. OBJECT IDENTIFIER OBJECT-TYPE The following macro definition is defined only in SMIv1. TRAP-TYPE The following macro definitions are defined only in SMIv2. MODULE-IDENTITY NOTIFICATION-TYPE OBJECT-IDENTITY OBJECT-GROUP AGENT-CAPABILITIES NOTIFICATION-GROUP MODULE-COMPLIANCE TEXTUAL-CONVENTION OBJECT IDENTIFIER Macro Definition lcname OBJECT IDENTIFIER ::= oidvalue Example adventnet OBJECT IDENTIFIER ::= {enterprises 2162} OBJECT-TYPE Tables Macro Definition lcname OBJECT-TYPE SYNTAX SEQUENCE OF SequenceName MAX-ACCESS not-accessible STATUS StatusV2 DESCRIPTION Text [REFERENCE Text] ::= value (VALUE OBJECT IDENTIFIER) Examples iftable OBJECT-TYPE SYNTAX SEQUENCE OF IfEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "Description" -- quoted string uses the NVT ASCII character set ::= {interfaces 2} iftable OBJECT-TYPE SYNTAX SEQUENCE OF IfEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "Description" REFERENCE "reference" ::= {interfaces 2} AdventNet, Inc. 60

62 Row Objects Macro Definition lcname OBJECT-TYPE SYNTAX SequenceName MAX-ACCESS not-accessible STATUS StatusV2 DESCRIPTION Text [REFERENCE Text] Index ::= value (VALUE OBJECT IDENTIFIER) Index::= INDEX {[IMPLIED] nodeobjects [, nodeobjects]*} AUGMENTS {augments} -- * represents 0 or more occurrences Examples ifentry OBJECT-TYPE SYNTAX IfEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "description" INDEX { ifindex } ::= { iftable 1 } ifxentry OBJECT-TYPE SYNTAX IfXEntry MAX-ACCESS not-accessible STATUS current DESCRIPTION "description" AUGMENTS {ifentry} ::= {ifxtable 1} Columnar and Scalar Objects Macro Definition lcname OBJECT-TYPE SYNTAX SyntaxV2 [UNITS Text] MAX-ACCESS AccessV2 STATUS StatusV2 DESCRIPTION Text [REFERENCE Text] [DEFVAL {DefvalV2}] ::= value (VALUE OBJECT IDENTIFIER) Examples ifspeed OBJECT-TYPE SYNTAX Gauge32 MAX-ACCESS read-only STATUS current DESCRIPTION "description" ::= {ifentry 5} etherstatspkts OBJECT-TYPE SYNTAX Counter32 UNITS "Packets" MAX-ACCESS read-only STATUS current DESCRIPTION "description" ::= {etherstatsentry 5} ifspeed OBJECT-TYPE SYNTAX Gauge32 MAX-ACCESS read-only STATUS current DESCRIPTION "description" REFERENCE "reference" ::= {ifentry 5} AdventNet, Inc. 61

63 TRAP-TYPE Macro Definition Examples trapname TRAP-TYPE ENTERPRISE enterprisename VARIABLES {variable1, variable2, variable3} DESCRIPTION "description" REFERENCE "reference" ::= 5 lcname TRAP-TYPE ENTERPRISE value [VARIABLES {Objects}] [DESCRIPTION Text] [REFERENCE Text] ::= value -- non-negative integer (range upto 2^32-1) Objects::= objectname [, objectname]* --objectname is the scalar or columnar object's name trapname TRAP-TYPE ENTERPRISE enterprisename VARIABLES {variable1, variable2, variable3} DESCRIPTION "description" REFERENCE "reference" ::= 5 trapname TRAP-TYPE ENTERPRISE ModuleName.enterpriseName - - the ModuleName where the enterprisename was defined. VARIABLES {variable1, variable2, variable3} DESCRIPTION "description" REFERENCE "reference" ::= 5 trapname TRAP-TYPE ENTERPRISE enterprisename ::= 5 MODULE-IDENTITY Macro Definition lcname MODULE-IDENTITY LAST-UPDATED value(update UTCTime) ORGANIZATION Text CONTACT-INFO Text DESCRIPTION Text [Revisions]* Revisions ::= REVISION value(update UTCTime) DESCRIPTION Text Examples moduleidty MODULE-IDENTITY LAST-UPDATED " Z" ORGANIZATION "organization" CONTACT-INFO "contact information" DESCRIPTION "description" REVISION " Z" DESCRIPTION "revision description" ::= { oid 1 } moduleidty MODULE-IDENTITY LAST-UPDATED " Z" ORGANIZATION "organization" CONTACT-INFO "contact information DESCRIPTION "description" ::= { oid 2 } Note: UTC Time Format - YYMMDDHHMMZ where YY - last two digits of year MM - month (01 through 12) DD - day of month (01 through 31) HH - hours (00 through 23) MM - minutes (00 through 59) Z - denotes Greenwich Mean Time (GMT) AdventNet, Inc. 62

64 NOTIFICATION-TYPE Macro Definition lcname NOTIFICATION-TYPE [OBJECTS {Objects}] STATUS StatusV2 DESCRIPTION Text [REFERENCE Text] Examples notificationtype1 NOTIFICATION-TYPE OBJECTS {object1, object2, object3} STATUS current DESCRIPTION "Description" ::= {oid 1} notificationtype2 NOTIFICATION-TYPE STATUS current DESCRIPTION "Description" ::= {oid 2} notificationtype3 NOTIFICATION-TYPE OBJECTS {object1, object2, object3} STATUS current DESCRIPTION "Description" REFERENCE "reference" ::= {oid 3} OBJECT-IDENTITY Macro Definition lcname OBJECT-IDENTITY STATUS StatusV2 DESCRIPTION Text [REFERENCE Text] ::=value(value OBJECT IDENTIFIER) Examples objectidty OBJECT-IDENTITY STATUS current DESCRIPTION "OID description" REFERENCE "reference" ::= {oid 3} objectidty OBJECT-IDENTITY STATUS current DESCRIPTION "OID description" ::= {oid 4} OBJECT-GROUP Macro Definition lcname OBJECT-GROUP OBJECTS {Objects} STATUS StatusV2 DESCRIPTION Text [REFERENCE Text] ::=value(value OBJECT IDENTIFIER) Examples objgroup1 OBJECT-GROUP OBJECTS {object1, object2, object3} STATUS current DESCRIPTION "Description" ::= {oid 1} objgroup2 OBJECT-GROUP OBJECTS {object1, object2, object3} STATUS current DESCRIPTION "Description" REFERENCE "reference" ::= {oid 2} AdventNet, Inc. 63

65 AGENT-CAPABILITIES Macro Definition lcname AGENT-CAPABILITIES PRODUCT-RELEASE Text STATUS StatusV2 DESCRIPTION Text [REFERENCE Text] [Module]* ::=value(value OBJECT IDENTIFIER) Module ::= SUPPORTS ModuleName INCLUDES {Groups} [Variations]* Variations ::= ObjectVariation NotificationVariation NotificationVariation ::= VARIATION Objects [ACCESS AccessV2] DESCRIPTION Text ObjectVariation ::= VARIATION Objects [SYNTAX SyntaxV2] [WRITE SYNTAX SyntaxV2] [ACCESS AccessV2] [CREATION-REQUIRES {Objects}] [DEFVAL {Defval}] DESCRIPTION Text Defval ::= Text OID nodename ModuleName.nodeName ipaddress binarynumber hexnumber number Examples agentcap1 AGENT-CAPABILITIES PRODUCT-RELEASE "Product-Release" STATUS current DESCRIPTION "Description" REFERENCE "REF" SUPPORTS RFC1213-MIB INCLUDES {groupobject1, groupobject2} VARIATION object1 SYNTAX IpAddress WRITE-SYNTAX INTEGER ACCESS read-only DEFVAL { 1 } DESCRIPTION "Variation Description" ::= {oid 1} agentcap2 AGENT-CAPABILITIES PRODUCT-RELEASE "Product-Release" STATUS current DESCRIPTION "Description" REFERENCE "REF" ::= {oid 2} agentcap3 AGENT-CAPABILITIES PRODUCT-RELEASE "Product-Release" STATUS current DESCRIPTION "Description" REFERENCE "REF" SUPPORTS RFC1213-MIB INCLUDES {groupobject1, groupobject2} ::= {oid 3} NOTIFICATION-GROUP Macro Definition lcname NOTIFICATION-GROUP NOTIFICATIONS {Objects} STATUS StatusV2 DESCRIPTION Text [REFERENCE Text] ::=value(value OBJECT IDENTIFIER) Examples notificationgroup1 NOTIFICATION-GROUP NOTIFICATIONS {object1, object2} STATUS current DESCRIPTION "Description" ::= {oid 1} notificationgroup2 NOTIFICATION-GROUP NOTIFICATIONS {object1, object2} STATUS current DESCRIPTION "Description" REFERENCE "reference" ::= {oid 1} AdventNet, Inc. 64

66 MODULE-COMPLIANCE Macro Definition lcname MODULE-COMPLIANCE STATUS StatusV2 DESCRIPTION Text [REFERENCE Text] [Module]* ::=value(value OBJECT IDENTIFIER) Module ::= MODULE ModuleName [MANDATORY-GROUPS {Objects }] [ComplianceGroup Object] ComplianceGroup ::= GROUP {Objects} DESCRIPTION Text Object ::= OBJECT {Objects} [SYNTAX SyntaxV2] [WRITE-SYNTAX SyntaxV2] [MIN-ACCESS AccessV2] DESCRIPTION Text Examples modulecompliance1 MODULE-COMPLIANCE STATUS obsolete DESCRIPTION "Description" MODULE RFC1213-MIB MANDATORY-GROUPS {object1, object2} GROUP groupobject1 DESCRIPTION "Description" GROUP groupobject2 DESCRIPTION "Description" GROUP groupobject3 DESCRIPTION "Description" OBJECT object1 SYNTAX INTEGER MIN-ACCESS read-only DESCRIPTION "Description" OBJECT object2 SYNTAX INTEGER MIN-ACCESS read-only DESCRIPTION "Description" ::= {oid 1} TEXTUAL-CONVENTION Macro Definition ucname TEXTUAL-CONVENTION [DISPLAY-HINT Text] [STATUS StatusV2] DESCRIPTION Text [REFERENCE Text] SYNTAX SyntaxV2 Examples TcName ::= TEXTUAL-CONVENTION DISPLAY-HINT "1x:" STATUS current DESCRIPTION "description" REFERENCE "reference" SYNTAX OCTET STRING TcName ::= TEXTUAL-CONVENTION STATUS current DESCRIPTION "description" SYNTAX OCTET STRING For more information on textual conventions, refer Textual Conventions. AdventNet, Inc. 65

67 Configuring SNMP Agent Parameters AdventNet SNMP API provides methods to configure the common agent parameters. The following table describes the API methods used for configuring the agent parameters: Agent Parameter SNMP Version Host Name Port Number Community Name Description Refers to the SNMP version of the agent. If the SNMP version is not explicitly set, the default version is taken as SNMPv1. To set the specific SNMP version, we need to use the following methods. The value 1 is for SNMPv2c. This refers to the network address or the host name of the node in which the agent is installed. Applications use the host name or the IP address of the device to communicate with the agent of the device. The management applications communicate with the SNMP agents in the managed node in a particular port number. This remote port number is the UDP port 161. By default, all the SNMP request messages are received in this port. Sometimes, the agent may also be configured to receive messages in ports other than 161. The management applications normally have the provision to send request to the default port and also the option to set different port numbers. Community strings are used to authenticate SNMP PDUs. Since SNMP packets are usually sent using UDP packets, there is no connection established as in the case of TCP/IP packets. Therefore, when a UDP packet arrives at the agent, the agent validates the packet. It accepts and sends a response if the community string of the PDU is equal to that set on the agent, else drops the packet. The agent does not change the community name after communicating. Applications typically communicate with the SNMP agents by specifying the community name of the agent. Class/Component Name SnmpSession SnmpPDU UDPProtocolOptions UDPProtocolOptions SnmpSession SnmpPDU API Methods Version = int value RemoteAddress = InetAddress RemoteHost = String value RemotePort = int value Community = String value WriteCommunity = String value AdventNet, Inc. 66

68 Agent Parameter Timeout and Retries Max Repetitions Non Repeaters Description The timeout is the time interval that an application waits for a response message from an agent. Typically these values are given in milliseconds or in seconds. If the value is 5 seconds, the application waits for 5 seconds for the response before timing out. Retries are the number of times a request is sent when a timeout occurs. If the retry value is 0, the request is not re-transmitted during timeout. The Max Repetitions value specifies the number of lexicographic successors to be returned for the remaining variables in the variablebindings list. The default value is 50. The Non Repeaters value specifies the number of variables in the variable bindings list for which a single lexicographic successor is to be returned. The default value is 0. Class/Component Name SnmpSession SnmpPDU SnmpSession SnmpPDU SnmpSession SnmpPDU API Methods Timeout = int value Retries = int value MaxRepetitions = int value NonRepeaters = int)- value Warning: When an application sends an SNMPv1 PDU using a session whose version is set to SNMP_VERSION_2C, a SNMPv2c message is sent to the peer. This problem arises because the API uses SNMP_VERSION_1 as the default PDU version and it could not distinguish between applications leaving the version in PDU to default and setting it explicitly to SNMP_VERSION_1. To circumvent this problem, applications should set session version to SNMP_VERSION_1 and set the PDU version explicitly to SNMP_VERSION_2C while communicating with v2c peers. Note: 1. The remotehost and remoteport attribute of SnmpPDU overrides the one set in SnmpSession. This means, when remotehost is null in SnmpPDU, messages are sent to the host, peername, set in the session. When remotehost is not null in SnmpPDU, messages are sent to the remotehost. Default peername is null, meaning when both peername in session and remotehost in PDU are null, the exception "No remote IP address specified" is thrown. Similarly, when the remoteport in SnmpPDU is 0, the message is sent to remoteport specified in the session. 2. AdventNet SNMP API follows "exponential back off" algorithm to calculate the timeout and retry value. The timeout value specified increases exponentially with the retry value. In general, for the timeout value is 'T' and the retry value is 'R', the total time taken for the entire SNMP operation can be given as follows: r=r Total time taken = Σ T x 2^r r=0 If the response is received in between, it is notified to the user either by returning the response PDU (in case of synchronous request) or by calling the Callback method (in case of asynchronous request). AdventNet, Inc. 67

69 Trap Parameters Management applications can receive trap messages sent by the agent. Following are the trap parameters that are to be set while developing applications. Enterprise OID This is the OID of the management enterprise that defines the trap message. The value is represented as an OBJECT IDENTIFIER and has a variable length. The following table displays the method that can be used for setting the enterprise OID. Class/Component Name SNMP PDU API Methods EnterpriseOID = SnmpOID Agent Address This specifies the source IP address from which the trap was sent. The following table displays the method that can be used for setting the agent address. Class/Component Name SNMP PDU API Methods AgentAddr = String value Generic and Specific Type The SNMP standard defines seven traps that can be generated by SNMPv1 agents. Six of these traps are "generic" traps and the seventh trap is enterprise specific. The enterprisespecific trap is used by the private organizations to define their device-specific traps. The six generic trap types defined for SNMPv1 agents are as follows. coldstart trap (0) warmstart trap (1) linkdown trap(2) linkup trap(3) authenticationfailure trap(4) egpneighborloss trap(5) The generic traps are fixed and cannot be defined. On the other hand, it is possible to define multiple enterprise-specific traps. The trap message identity is determined based on the values contained in the Enterprises, Standard Trap Type, and Specific Trap Type fields of the Trap PDU. If the Trap Type value is zero through five, the trap is one of the generic traps and the value of the Specific Trap Type field will be zero. If the Trap type value is six, the trap is enterprise specific and is defined in a private MIB. It can take any integer value between 0 and The following table lists the methods that can be used for setting the trap type. The following table lists the methods that can be used for setting the generic and specific traps. AdventNet, Inc. 68

70 Class/Component Name SnmpPDU API Methods TrapType = int value SpecificType = String value Remarks The TrapType method sets the generic type of the trap and the SpecificType sets the specific type of the trap. Time Stamp This is the value stored in the MIB-II sysuptime variable converted into hours, minutes, and seconds. It is a 32-bit unsigned value indicating the number of centiseconds that have elapsed since the start of the SNMP agent and the sending of the trap. The following table displays the method that can be used for setting the time stamp. Class/Component Name SNMP PDU API Methods UpTime = long value Trap Port The traps are normally received in the UDP port no 162. However, this port number can be different and the applications should be able to handle this. The following table lists the methods that can be used for setting the trap port. Class/Component Name UDPProtocolOptions API Methods LocalPort = int value An SNMPv2 trap may need to be translated to an SNMPv1 trap. The following table shows the notification parameters that make up an SNMPv1 trap and SNMPv2 traps. SNMPv1 Trap enterprise value agent address generic-trap value specific-trap value timestamp variable-bindings SNMPv2 Trap sysuptime (first variable -binding) snmptrapoid value (next variable bindings) snmptrapenterprise value (optional) additional variable bindings AdventNet, Inc. 69

71 Handling Datatypes Overview SMI Datayptes Textual Conventions AdventNet SNMP API provides separate classes for the all the base data types, such as Integer, Counter, and so on. This section gives a detailed overview on the SMI datatypes. Moreover, AdventNet SNMP API supports the textual conventions MacAddress and DateAndTime, according to their definitions. AdventNet, Inc. 70

72 Overview AdventNet SNMP API provides separate classes for all the base data types, such as Integer, Counter, and so on. Moreover, the textual convention objects do not need separate classes because they are resolved into base data types. The textual convention objects are handled internally in the mibs package. AdventNet SNMP API supports the TAddress, MacAddress, and DateAndTime, according to their definitions. SNMP API supports the standard RFC's SMIv1 and SMIv2. The various data types for management information are given in the following table. Data Types SMIv1 Data Types INTEGER INTEGER (Enumerated) Gauge Counter TimeTicks OCTET STRING OBJECT IDENTIFIER IpAddress NetworkAddress Opaque SMIv2 Data Types Integer32 INTEGER (Enumerated) Unsigned32 Gauge32 Counter32 TimeTicks OCTET STRING OBJECT IDENTIFIER IpAddress Opaque BITS SMIv1 MIB Data Types Data Type Name INTEGER Description Specifies a value whose range may include both positive and negative numbers. Range = -2e31 to 2e31-1 (SMIv1 does not specify minimum or maximum values for the range). Examples: INTEGER (0..127) -- corresponds to an unsigned 8-bit integer INTEGER ( ) INTEGER ( ) -- corresponds to a signed 32-bit integer INTEGER (Enumerated) Specifies a list of labeled integer values. In SMIv1, the values should be greater than 0, whereas SMIv2 allows any values in the range (-2e31 to 2e31-1) Example: INTEGER { true(1), false(2) } Gauge Counter Represents a non-negative integer, which holds at the maximum or minimum value specified in the range when the actual value goes over or below the range, respectively. Specifies a value which represents a count. The range is 0 to AdventNet, Inc. 71

73 Data Type Name TimeTicks OCTET STRING Description Specifies the elapsed time between two events, in units of hundredth of a second. The range is 0 to 2e32-1. Specifies octets of binary or textual information. While SMIv1 doesn't limit the number of octets, SMIv2 specifies a limit of octets. A size may be specified which can be fixed, varying, or of multiple ranges. Examples: OCTET STRING -- length can vary from 0 to bytes OCTET STRING (SIZE(0..255)) OCTET STRING (SIZE(4)) -- fixed length of 4 bytes. OCTET STRING (SIZE(0 4 6)) -- varying with 0, 4, or 6 bytes OBJECT IDENTIFIER IpAddress NetworkAddress Opaque Identifies a type that has an assigned Object Identifier value Specifies an IPv4 address as a string of 4 octets. Allows a network address of any type to be specified. However, it is now obsolete. A value of this type is an IPv4 address. SMIv2 supports this type through the IpAddress type. Specifies octets of binary information. SMIv2 specifies a limit of octets while there is no limit in SMIv1. A size may be specified which can be fixed, varying, or of multiple ranges. A value of this type must be an encapsulation of ASN.1 BER encoded value. Examples: Opaque -- length can vary from 0 to bytes Opaque (SIZE(0..255)) Opaque (SIZE(4)) -- fixed length of 4 bytes. Opaque (SIZE(0 4 6)) -- varying with 0, 4, or 6 bytes SMIv2 MIB Data Types Data Type Name Description Specifies a value whose range may include both positive and negative numbers. Range is 2e31 to 2e31-1 (SMIv1 doesn't specify minimum or maximum values for the range). Examples: Integer32 Integer32(0..127) -- corresponds to an unsigned 8-bit integer Integer32 -- same as -- Integer32 ( ) Integer32( ) INTEGER (Enumerated) Specifies a list of labeled integer values. In SMIv1 the values should be greater than 0, whereas SMIv2 allows any value in the range ( -2e31 to 2e31-1). Examples: AdventNet, Inc. 72

74 Data Type Name Description INTEGER { true(1), false(2) } INTEGER { lessthan(-1), equal(0), greaterthan(1) } Specifies a value whose range includes only non-negative integers (0 to 2e31-1). Examples: Unsigned32 Unsigned32 -- same as Unsigned32( ) Unsigned32( ) -- corresponds to an unsigned 16 bit integer Unsigned32( ) Gauge32 Counter32 TimeTicks OCTET STRING Represents a non-negative integer, which holds at the maximum or minimum value specified in the range when the actual value goes over or below the range, respectively. Specifies a value which represents a count. The range is 0 to Specifies the elapsed time between two events, in units of hundredth of a second. Range is 0 to 2e32-1. Specifies octets of binary or textual information. While SMIv1 doesn't limit the number of octets, SMIv2 specifies a limit of octets. A size may be specified which can be fixed, varying, or of multiple ranges. Examples: OCTET STRING -- length can vary from 0 to bytes. OCTET STRING (SIZE(0..255)) OCTET STRING (SIZE(4)) -- fixed length of 4 bytes. OCTET STRING (SIZE(0 4 6)) -- varying with 0, 4, or 6 bytes OBJECT IDENTIFIER IpAddress Opaque Identifies a type that has an assigned Object Identifier value. Specifies an IPv4 address as a string of 4 octets. Specifies octets of binary information. SMIv2 specifies a limit of octets while there is no limit in SMIv1. A size may be specified which can be fixed, varying, or of multiple ranges. A value of this type must be an encapsulation of ASN.1 BER encoded value. Examples: Opaque -- length can vary from 0 to bytes. Opaque (SIZE(0..255)) Opaque (SIZE(4)) -- fixed length of 4 bytes. Opaque (SIZE(0 4 6)) -- varying with 0, 4, or 6 bytes Specifies a collection of labeled bits. It provides a way to label individual bits in an octet (an extension of OCTET STRING type). BITS Example: BITS {0 (tcp), 1(netware), 2(netbios)} AdventNet, Inc. 73

75 The following table lists all the various syntax supported in our SNMP API and their equivalent data type in.net. S.No. MIB Syntax Equivalent Data Type in.net 1 INTEGER Integer 2 Integer32 Integer 3 Unsigned32 long 4 Gauge/Gauge32 long 5 Counter/Counter32 long 7 TimeTicks long 8 OCTET STRING/BITS sbyte[] 9 OBJECT IDENTIFIER int[] 10 NULL Null 11 IpAddress sbyte[4] 12 Opaque sbyte[] AdventNet, Inc. 74

76 SMI Datatypes Integer32 Integer (Enumerated) Unsigned32 Gauge32 Counter32 Timeticks OCTET STRING OBJECT IDENTIFIER IpAddress Opaque BITS AdventNet SNMP API provides separate classes for all the SMI data types, such as INTEGER, OCTET STRING, and so on. Refer to Setting Values for Datatypes to know the various values that are to be specified in a SET operation with respect to the SYNTAX of this object. AdventNet, Inc. 75

77 Integer32 Integer32 specifies a value whose range may include both positive and negative numbers. Range is - 2e31 to 2e31-1. Examples Integer32(0..127) -- corresponds to an unsigned 8-bit integer Integer32 -- same as -- Integer32 ( ) Integer32( ) Create Variable Using SnmpVar class The SnmpVar class is the base class for all SNMP variable classes. The CreateVariable(String value, sbyte type) method creates a new SnmpVar object with the specified type and value. String value = " "; SnmpVar snmpvar = SnmpVar.CreateVariable(value, SnmpAPI.INTEGER); The string value should only be in decimal. Valid Usage SnmpVar snmpvar = SnmpVar.CreateVariable("123456", SnmpAPI.INTEGER); SnmpVar snmpvar = SnmpVar.CreateVariable("-12345", SnmpAPI.INTEGER); Invalid Usage SnmpVar snmpvar = SnmpVar.CreateVariable("test", SnmpAPI.INTEGER); The above usage is invalid because only decimal values are accepted and not any type of strings. SnmpVar snmpvar = SnmpVar.CreateVariable("0x12abcd", SnmpAPI.INTEGER); The above usage is invalid because only decimal values are accepted and not any hexadecimal values. SnmpVar snmpvar = SnmpVar.CreateVariable(" ", SnmpAPI.INTEGER); The above usage is invalid because the value exceeds the maximum limit of an integer. For all of the above invalid usages, an SnmpException is thrown. Using SnmpInt class The constructor of this class creates an SnmpInt object by taking integer value as argument. int value = ; SnmpInt snmpint = new SnmpInt(value); AdventNet, Inc. 76

78 Using mibs package The following code snippet creates an SnmpVar object of Integer32 data type using the LeafSyntax class. String mibfile = "<mib name>"; String modulename = "IF-MIB"; String nodename = "ifmtu"; MibOperations mibops = new MibOperations(); mibops.loadmibmodule(mibfile); MibModule module = mibops.getmibmodule(modulename); SnmpOID snmpoid = mibops.getsnmpoid(nodename); MibNode node = module.getmibnode(snmpoid); LeafSyntax syntax = node.getsyntax(); String value = " "; SnmpVar snmpvar = syntax.createvariable(value); Valid Usage SnmpVar snmpvar = syntax.createvariable("65535");//decimal format SnmpVar snmpvar = syntax.createvariable("' 'b");//binary format SnmpVar snmpvar = syntax.createvariable("'ffff'h");//hex format Note: In the binary format, the value should be enclosed within single quotes and end with 'b or 'B. In the hex format, the value should be enclosed within single quotes and end with 'h or 'H. Retrieve Value from Variable Using SnmpVar class Following are the methods of SnmpInt class that are used to retrieve value from the created variable. 1. The GetVarObject() method returns the integer value as Integer object. int value = 12345; // 0x3039 SnmpInt snmpint = new SnmpInt(value); Integer obj = (Integer)snmpint.GetVarObject(); 2. The ToValue() method returns the integer value as Integer object. Integer obj = (Integer)snmpint.ToValue(); 3. The ToBytes() method returns the integer as a sbyte array of length 4. sbyte[] array = snmpint.tobytes(); This sbyte array contains the following values. array[0] = 0x00; array[1] = 0x00; array[2] = 0x30; array[3] = 0x39; AdventNet, Inc. 77

79 4. The ToString() method returns the integer value in decimal as a printable form. String value = snmpint.tostring(); 5. The ToTagString() method returns the integer value in decimal with tag 'INTEGER' attached to it. String tagstring = snmpint.totagstring(); This string contain the value "INTEGER: 12345". 6. The IntValue() method returns the integer value as "int" int value = snmpint.intvalue(); Using mibs package The tostring() and tobytestring() methods of the MibOperations class are used to retrieve the value of the variable as String. The following commands retrieve the value of the created variable. String value = mibops.tostring(snmpvar, snmpoid); This string contains the value " ". String value = mibops.tostring(snmpvarbind); This string contains the value "ifmtu:--> ". String value = mibops.tobytestring(snmpvar, snmpoid); This string contains the value " ". String value = mibops.tobytestring(snmpvarbind); This string contains the value "ifmtu:--> ". String value = mibops.tostring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifMtu INTEGER: String value = mibops.tobytestring(snmppdu); AdventNet, Inc. 78

80 This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifMtu INTEGER: String value = mibops.totagstring(snmpvarbind); This string contains the following value. Object ID:.iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifMtu INTEGER: The value of an instance of an object with the syntax defined using this textual convention can be displayed using the DISPLAY-HINT clause. Refer Textual Conventions for more information on the DISPLAY-HINT clause. AdventNet, Inc. 79

81 INTEGER (Enumerated) Enumerated integer specifies a list of labeled integer values. For example, INTEGER{min(1), max(32)} is an enumeration of integer. It should not be equated as range of numbers between 1 to 32. We cannot set number other than 1 and 32. If we try to set it will throw DataException. To set all numbers between 1 to 32, we must define the syntax as range of integer. The range of Integer should be defined as INTEGER(1..32), only then we can set value of 1 to 32. Example INTEGER {up(1), down(2), testing(3)} Create Variable Using SnmpVar class The SnmpVar class is the base class for all SNMP variable classes. The CreateVariable(String value, sbyte type) method creates a new SnmpVar object with the specified type and value. String value = " "; SnmpVar snmpvar = SnmpVar.CreateVariable(value, SnmpAPI.INTEGER) The string value should only be in decimal. Valid Usage SnmpVar snmpvar = SnmpVar.CreateVariable("123456", SnmpAPI.INTEGER); SnmpVar snmpvar = SnmpVar.CreateVariable("-12345", SnmpAPI.INTEGER); Invalid Usage SnmpVar snmpvar = SnmpVar.CreateVariable("test", SnmpAPI.INTEGER); The above usage is invalid because only decimal values are accepted and not any type of strings. SnmpVar snmpvar = SnmpVar.CreateVariable("0x12abcd", SnmpAPI.INTEGER); The above usage is invalid because only decimal values are accepted and not any hexadecimal values. SnmpVar snmpvar = SnmpVar.CreateVariable(" ", SnmpAPI.INTEGER); The above usage is invalid because the value exceeds the maximum limit of an integer. For all of the above invalid usages, an SnmpException is thrown. AdventNet, Inc. 80

82 Using SnmpInt class The constructor of this class creates an SnmpInt object by taking integer value as argument. int value = ; SnmpInt snmpint = new SnmpInt(value); Using mibs package Let us now create an SnmpVar object of type enumerated integer using the LeafSyntax class. String mibfile = "<mib name>"; String modulename = "RFC1213-MIB"; String nodename = "ifoperstatus"; MibOperations mibops = new MibOperations(); mibops.loadmibmodule(mibfile); MibModule module = mibops.getmibmodule(modulename); SnmpOID snmpoid = mibops.getsnmpoid(nodename); MibNode node = module.getmibnode(snmpoid); LeafSyntax syntax = node.getsyntax(); String value = "up"; SnmpVar snmpvar = syntax.createvariable(value); Valid Usage SnmpVar snmpvar = syntax.createvariable("1"); SnmpVar snmpvar = syntax.createvariable("up"); Note: Binary and hex values cannot be given for creating enumerated integers. Retrieve Value from Variable Using SnmpVar Class Following are the methods of SnmpInt class that are used to retrieve value from the created variable. 1. The GetVarObject() method returns the integer value as Integer object. int value = 12345; // 0x3039 SnmpInt snmpint = new SnmpInt(value); Integer obj = (Integer)snmpint.GetVarObject(); 2. The ToValue() method returns the integer value as Integer object. Integer obj = (Integer)snmpint.ToValue(); 3. The ToBytes() method returns the integer as a sbyte array of length 4. sbyte[] array = snmpint.tobytes(); This sbyte array contains the following values. array[0] = 0x00; array[1] = 0x00; array[2] = 0x30; array[3] = 0x39; AdventNet, Inc. 81

83 4. The ToString() method returns the integer value in decimal as a printable form. String value = snmpint.tostring(); 5. The ToTagString() method returns the integer value in decimal with tag 'INTEGER' attached to it. String tagstring = snmpint.totagstring(); This string contain the value "INTEGER: 12345". 6. The IntValue() method returns the integer value as "int" int value = snmpint.intvalue(); Using mibs package The tostring() and tobytestring() methods of the MibOperations class are used to retrieve the value of the variable as String. The following commands retrieve the value of the created variable. String value = mibops.tostring(snmpvar, snmpoid); This string contains the value "up(1)". String value = mibops.tostring(snmpvarbind); This string contains the value "ifoperstatus:-->up(1)". String value = mibops.tobytestring(snmpvar, snmpoid); This string contains the value "up(1)". String value = mibops.tobytestring(snmpvarbind); This string contains the value "ifoperstatus:-->up(1)". String value = mibops.tostring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifOperStatus INTEGER: up(1) String value = mibops.tobytestring(snmppdu); AdventNet, Inc. 82

84 This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifOperStatus INTEGER: up(1) String value = mibops.totagstring(snmpvarbind); **This string contains the following value. Object ID:.iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifOperStatus INTEGER: up(1) The getenumlabels() gets the enumeration labels from LeafSyntax object. String[] labels = syntax.getenumlabels(); for(int i =0; i< labels.length; i++) { System.Console.Out.WriteLine("enum labels: "+labels[i]); } The getenumint() method is used to get the enumerated integers. int[] values = syntax.getenumint(); for(int j =0; j< values.length; j++) { System.Console.Out.WriteLine("enum int: "+values[j]); } The GetLabel() method of the LeafSyntax class gets the label corresponding to integer value. The GetInt() method gets the integer value corresponding to label. AdventNet, Inc. 83

85 Unsigned32 Unsigned32 specifies a value whose range includes only non-negative integers (0 to ). Examples Unsigned32 -- same as Unsigned32( ) Unsigned32( ) -- corresponds to an unsigned 16 bit integer Unsigned32( ) Create Variable Using SnmpVar class The SnmpVar class is the base class for all SNMP variable classes. The CreateVariable(String value, sbyte type) method creates a new SnmpVar object with the specified type and value. String value = " "; SnmpVar snmpvar = SnmpVar.CreateVariable(value, SnmpAPI.UNSIGNED32) The string value should only be in decimal. Valid Usage SnmpVar snmpvar = SnmpVar.CreateVariable(" ", SnmpAPI.UNSIGNED32) // 0xffffffff SnmpVar snmpvar = SnmpVar.CreateVariable("0", SnmpAPI.UNSIGNED32) SnmpVar snmpvar = SnmpVar.CreateVariable(" ", SnmpAPI.UNSIGNED32) // 0x The above usage should be used carefully. The given value will be converted to zero while sending an SNMP request because only the least significant 4 bytes are taken. Invalid Usage SnmpVar snmpvar = SnmpVar.CreateVariable("test", SnmpAPI.UNSIGNED32); The above usage is invalid because only decimal values are accepted. SnmpVar snmpvar = SnmpVar.CreateVariable(" ", SnmpAPI.UNSIGNED32); The above usage is invalid because, the value given exceeds the maximum limit of the "long" value. SnmpVar snmpvar = SnmpVar.CreateVariable("0x123abc", SnmpAPI.UNSIGNED32); The above usage is invalid because only decimal values are accepted and not any hexadecimal values. For all of the above invalid usages, an SnmpException is thrown. AdventNet, Inc. 84

86 Using SnmpUnsignedInt class The constructor of this class creates an SnmpUnsignedInt object by taking a long type as argument. long value = ; SnmpUnsignedInt snmpunsignedint = new SnmpUnsignedInt(value); Using mibs package The following code snippet creates an SnmpVar object of Unsigned32 data type using the LeafSyntax class. String mibfile = "<mib name>"; String modulename = "<module name>"; String oid = "<OID>"; MibOperations mibops = new MibOperations(); mibops.loadmibmodule(mibfile); MibModule module = mibops.getmibmodule(modulename); SnmpOID snmpoid = mibops.getsnmpoid(oid); MibNode node = module.getmibnode(snmpoid); LeafSyntax syntax = node.getsyntax(); String value = " "; SnmpVar snmpvar = syntax.createvariable(value); Valid Usage SnmpVar snmpvar = syntax.createvariable("65535"); SnmpVar snmpvar = syntax.createvariable("' 'b"); SnmpVar snmpvar = syntax.createvariable("'ffff'h"); Note: The value can be given in decimal, hex or binary format while sending an SNMP request because only the least significant 4 bytes are taken. Retrieve Value from Variable Using SnmpVar Class Following are the methods of SnmpUnsignedInt class that are used to retrieve value from the created variable. 1. The GetVarObject() returns the value as Long object. long value = 0xffffffffL; // the maximum value of an Unsigned32 SnmpUnsignedInt unsigned = new SnmpUnsignedInt(value); Long obj = (Long)unsigned.GetVarObject(); 2. The ToValue() method returns the value as Long object. Long obj = (Long )unsigned.tovalue(); 3. The ToBytes() method returns the integer as a sbyte array of length 4. sbyte[] array = unsigned.tobytes(); AdventNet, Inc. 85

87 This sbyte array will contain the following values. array[0] = 0xff; array[1] = 0xff; array[2] = 0xff; array[3] = 0xff; 4. The ToString() method returns the integer value in decimal as a printable form. String value = unsigned.tostring(); This string contains the value " ". 5. The ToTagString() method returns the integer value in decimal with the tag "UNSIGNED" attached to it. String tagstring = unsigned.totagstring(); This string contains the value "UNSIGNED: ". 6. The LongValue() method returns the value as "long" long value = unsigned.longvalue(); Using mibs package The tostring() and tobytestring() methods of the MibOperations class are used to retrieve the value of the variable as String. String value = mibops.tostring(snmpvar, snmpoid); AdventNet, Inc. 86

88 Gauge32 Gauge32 represents a non-negative integer, which holds at the maximum or minimum value specified in the range when the actual value goes over or below the range, respectively. Create Variable Using SnmpVar class The SnmpVar class is the base class for all SNMP variable classes. The CreateVariable(String value, sbyte type) method creates a new SnmpVar object with the specified type and value. String value = " "; SnmpVar snmpvar = SnmpVar.CreateVariable(value, SnmpAPI.GAUGE); The string value should only be in decimal. Valid Usage SnmpVar snmpvar = SnmpVar.CreateVariable(" ", SnmpAPI.GAUGE);// 0xffffffff SnmpVar snmpvar = SnmpVar.CreateVariable("0", SnmpAPI.GAUGE); SnmpVar snmpvar = SnmpVar.CreateVariable(" ", SnmpAPI.GAUGE);// 0x The above usage should be used carefully. The given value will be converted to zero while sending an SNMP request because only the least significant 4 bytes are taken. Invalid Usage SnmpVar snmpvar = SnmpVar.CreateVariable("test", SnmpAPI.GAUGE); The above usage is invalid because only decimal values are accepted. SnmpVar snmpvar = SnmpVar.CreateVariable(" ", SnmpAPI.GAUGE); The above usage is invalid because, the value given exceeds the maximum limit of the "long" value. SnmpVar snmpvar = SnmpVar.CreateVariable("0x123abc", SnmpAPI.GAUGE); The above usage is invalid because only decimal values are accepted and not any hexadecimal values. For all of the above invalid usages, an SnmpException is thrown. Using SnmpGauge class The constructor of this class creates an SnmpGauge object by taking a long type as argument. long value = ; SnmpGauge gauge= new SnmpGauge(value); AdventNet, Inc. 87

89 Using mibs package The following code snippet creates an SnmpVar object of Gauge32 data type using the LeafSyntax class. String mibfile = "<mib name>"; String modulename = "IF-MIB"; String nodename = "ifspeed"; MibOperations mibops = new MibOperations(); mibops.loadmibmodule(mibfile); MibModule module = mibops.getmibmodule(modulename); SnmpOID snmpoid = mibops.getsnmpoid(nodename); MibNode node = module.getmibnode(snmpoid); LeafSyntax syntax = node.getsyntax(); String value = " "; SnmpVar snmpvar = syntax.createvariable(value); Valid Usage SnmpVar snmpvar = syntax.createvariable("65535"); SnmpVar snmpvar = syntax.createvariable("' 'b"); SnmpVar snmpvar = syntax.createvariable("'ffff'h"); Note: The value can be given in decimal, hex or binary format while sending an SNMP request because only the least significant 4 bytes are taken. Retrieve Value from Variable Using SnmpVar Class Following are the methods of SnmpGauge class that are used to retrieve value from the created variable. 1. The GetVarObject() returns the SnmpGauge value as Long object. long value = 0xffffffffL; // the maximum value of an Unsigned32 SnmpGauge gauge32 = new SnmpGauge(value); Long obj = (Long)gauge32.GetVarObject(); 2. The ToValue() method returns the SnmpGauge value as Long object. Long obj = (Long)gauge32.ToValue(); 3. The ToBytes() method returns the integer as a sbyte array of length 4. sbyte[] array = gauge32.tobytes(); This sbyte array will contain the following values. array[0] = 0xff; array[1] = 0xff; array[2] = 0xff; array[3] = 0xff; 4. The ToString() method returns the integer value in decimal as a printable form. String value = gauge32.tostring(); AdventNet, Inc. 88

90 This string contains the value " ". 5. The ToTagString() method returns the integer value in decimal with the tag "Gauge" attached to it. String tagstring = gauge32.totagstring(); This string contains the value "Gauge: ". 6. The LongValue() method returns the SnmpGauge value as "long". long value = gauge32.longvalue(); Using mibs package The tostring() and tobytestring() methods of the MibOperations class are used to retrieve the value of the variable as String. The following commands retrieve the value of the created variable. String value = mibops.tostring(snmpvar, snmpoid); This string contains the value " ". String value = mibops.tostring(snmpvarbind); This string contains the value "ifspeed:--> ". String value = mibops.tobytestring(snmpvar, snmpoid); This string contains the value " ". String value = mibops.tobytestring(snmpvarbind); This string contains the value "ifspeed:--> ". String value = mibops.tostring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifSpeed GAUGE: String value = mibops.tobytestring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) AdventNet, Inc. 89

91 SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifSpeed GAUGE: String value = mibops.totagstring(snmpvarbind); This string contains the following value. Object ID:.iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifSpeed GAUGE: AdventNet, Inc. 90

92 Counter32 Counter32 specifies a value which represents a count. The range is 0 to Create Variable Using SnmpVar class The SnmpVar class is the base class for all SNMP variable classes. The CreateVariable(String value, sbyte type) method creates a new SnmpVar object with the specified type and value. String value = " "; SnmpVar snmpvar = SnmpVar.CreateVariable(value, SnmpAPI.COUNTER) The string value should only be in decimal. Valid Usage SnmpVar snmpvar = SnmpVar.CreateVariable(" ", SnmpAPI.COUNTER);// 0xffffffff SnmpVar snmpvar = SnmpVar.CreateVariable("0", SnmpAPI.COUNTER); SnmpVar snmpvar = SnmpVar.CreateVariable(" ", SnmpAPI.COUNTER);// 0x The above usage should be used carefully. The given value will be converted to zero while sending an SNMP request because only the least significant 4 bytes are taken. Invalid Usage SnmpVar snmpvar = SnmpVar.CreateVariable("test", SnmpAPI.COUNTER); The above usage is invalid because only decimal values are accepted. SnmpVar snmpvar = SnmpVar.CreateVariable(" ", SnmpAPI.COUNTER); The above usage is invalid because, the value given exceeds the maximum limit of the "long" value. SnmpVar snmpvar = SnmpVar.CreateVariable("0x123abc", SnmpAPI.COUNTER); The above usage is invalid because only decimal values are accepted and not any hexadecimal values. For all of the above invalid usages, an SnmpException is thrown. Using SnmpCounter class The constructor of this class creates an SnmpCounter object by taking a long type as argument. long value = ; SnmpCounter counter32 = new SnmpCounter(value); AdventNet, Inc. 91

93 Using mibs package The following code snippet creates an SnmpVar object of Counter32 data type using the LeafSyntax class. String mibfile = "<mib name>"; String modulename = "IF-MIB"; String nodename = "ifinoctets"; MibOperations mibops = new MibOperations(); mibops.loadmibmodule(mibfile); MibModule module = mibops.getmibmodule(modulename); SnmpOID snmpoid = mibops.getsnmpoid(nodename); MibNode node = module.getmibnode(snmpoid); LeafSyntax syntax = node.getsyntax(); String value = " "; SnmpVar snmpvar = syntax.createvariable(value); Valid Usage SnmpVar snmpvar = syntax.createvariable("65535"); SnmpVar snmpvar = syntax.createvariable("' 'b"); SnmpVar snmpvar = syntax.createvariable("'ffff'h"); Note: The value can be given in decimal, hex or binary format while sending an SNMP request because only the least significant 4 bytes are taken. Retrieve Value from Variable Using SnmpVar Class Following are the methods of SnmpCounter class that are used to retrieve value from the created variable. 1. The GetVarObject() returns the SnmpCounter value as Long object. long value = 0xffffffffL; // the maximum value of an Unsigned32 SnmpCounter counter32 = new SnmpCounter(value); Long obj = (Long)counter32.GetVarObject(); 2. The ToValue() method returns the SnmpCounter value as Long object. Long obj = (Long)counter32.ToValue(); 3. The ToBytes() method returns the integer as a sbyte array of length 4. sbyte[] array = counter32.tobytes(); This sbyte array will contain the following values. array[0] = 0xff; array[1] = 0xff; array[2] = 0xff; array[3] = 0xff; 4. The ToString() method returns the integer value in decimal as a printable form. String value = counter32.tostring(); AdventNet, Inc. 92

94 This string contains the value " ". 5. The ToTagString() method returns the integer value in decimal with the tag "Counter" attached to it. String tagstring = counter32.totagstring(); This string contains the value "Counter: ". 6. The LongValue() method returns the SnmpCounter value as an "long" long value = counter32.longvalue(); Using mibs package The tostring() and tobytestring() methods of the MibOperations class are used to retrieve the value of the variable as String. The following commands retrieve the value of the created variable. String value = mibops.tostring(snmpvar, snmpoid); This string contains the value " ". String value = mibops.tostring(snmpvarbind); This string contains the value "ifinoctets:--> ". String value = mibops.tobytestring(snmpvar, snmpoid); This string contains the value " ". String value = mibops.tobytestring(snmpvarbind); This string contains the value "ifinoctets:--> ". String value = mibops.tostring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifInOctets COUNTER: String value = mibops.tobytestring(snmppdu); AdventNet, Inc. 93

95 This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifInOctets COUNTER: String value = mibops.totagstring(snmpvarbind); This string contains the following value. Object ID:.iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifInOctets COUNTER: AdventNet, Inc. 94

96 Timeticks This represents a non-negative integer which specifies the elapsed time between two events, in units of hundredth of a second. The range is 0 to 2e32-1. When object types are defined in the MIB which use this ASN.1 type, the description of the object type identifies the reference period. Create Variable Using SnmpVar class The SnmpVar class is the base class for all SNMP variable classes. The CreateVariable(String value, sbyte type) method creates a new SnmpVar object with the specified type and value. SnmpVar snmpvar = SnmpVar.CreateVariable(" ", SnmpAPI.TIMETICKS) The string value should only be in decimal. Valid Usage SnmpVar snmpvar = SnmpVar.CreateVariable(" ", SnmpAPI.TIMETICKS) // 0xffffffff SnmpVar snmpvar = SnmpVar.CreateVariable("0", SnmpAPI.TIMETICKS) SnmpVar snmpvar = SnmpVar.CreateVariable(" ", SnmpAPI.TIMETICKS) // 0x Invalid Usage Note: The above usage should be used carefully. The given value will be converted to zero while sending an SNMP request because only the least significant 4 bytes are taken. SnmpVar snmpvar = SnmpVar.CreateVariable("test", SnmpAPI.TIMETICKS); The above usage is invalid because only decimal values are accepted. SnmpVar snmpvar = SnmpVar.CreateVariable(" ", SnmpAPI.TIMETICKS); The above usage is invalid because, the value given exceeds the maximum limit of the "long" value. SnmpVar snmpvar = SnmpVar.CreateVariable("0x123abc", SnmpAPI.TIMETICKS); The above usage is invalid because only decimal values are accepted and not any hexadecimal values. For all of the above invalid usages, an SnmpException is thrown. Using SnmpTimeticks class The constructor of this class creates an SnmpTimeticks object by taking a long type as argument. SnmpTimeticks timeticks = new SnmpTimeticks( ); AdventNet, Inc. 95

97 Using mibs package The following code snippet creates an SnmpVar object of Timeticks data type using the LeafSyntax class. String mibfile = "<mib name>"; String modulename = "RFC1213-MIB"; String nodename = "sysuptime"; MibOperations mibops = new MibOperations(); mibops.loadmibmodule(mibfile); MibModule module = mibops.getmibmodule(modulename); SnmpOID snmpoid = mibops.getsnmpoid(nodename); MibNode node = module.getmibnode(snmpoid); LeafSyntax syntax = node.getsyntax(); String value = " "; SnmpVar snmpvar = syntax.createvariable(value); Retrieve Value from Variable Using SnmpVar Class Following are the methods of SnmpTimeticks class that are used to retrieve value from the created variable. 1. The GetVarObject() returns the SnmpTimeticks value as Long object. long value = 0xffffffffL; // the maximum value of an Unsigned32 SnmpTimeticks timetick = new SnmpTimeticks(value); Long obj = (Long)timetick.GetVarObject(); 2. The ToValue() method returns the SnmpTimeticks value as Long object. Long obj = (Long )timetick.tovalue(); 3. The ToBytes() method returns the integer as a sbyte array of length 4. sbyte[] array = timetick.tobytes(); This sbyte array will contain the following values. array[0] = 0xff; array[1] = 0xff; array[2] = 0xff; array[3] = 0xff; 4. The ToString() method returns the SnmpTimeticks value as a printable form. String value = timetick.tostring(); This string contains the value in the form, "31 days, 1 hours, 39 minutes, 14 seconds". 5. The ToTagString() method returns the integer value in decimal with the tag "Timeticks" attached to it. String tagstring = timetick.totagstring(); AdventNet, Inc. 96

98 This string contains the value "Timeticks: ". 6. The LongValue() method returns the SnmpTimeticks value as "long". long value = timetick.longvalue(); Using mibs package The tostring() and tobytestring() methods of the MibOperations class are used to retrieve the value of the variable as String. The following commands retrieve the value of the created variable. String value = mibops.tostring(snmpvar, snmpoid); This string contains the value "497 days, 2 hours, 27 minutes, 52 seconds". String value = mibops.tostring(snmpvarbind); This string contains the value "sysuptime:-->497 days, 2 hours, 27 minutes, 52 seconds". String value = mibops.tobytestring(snmpvar, snmpoid); This string contains the value "497 days, 2 hours, 27 minutes, 52 seconds". String value = mibops.tobytestring(snmpvarbind); This string contains the value "sysuptime:-->497 days, 2 hours, 27 minutes, 52 seconds". String value = mibops.tostring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.system.sysUpTime TIMETICKS: 497 days, 2 hours, 27 minutes, 52 seconds. String value = mibops.tobytestring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 AdventNet, Inc. 97

99 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.system.sysUpTime TIMETICKS: 497 days, 2 hours, 27 minutes, 52 seconds. String value = mibops.totagstring(snmpvarbind); This string contains the following value. Object ID:.iso.org.dod.internet.mgmt.mib-2.system.sysUpTime TIMETICKS: 497 days, 2 hours, 27 minutes, 52 seconds. AdventNet, Inc. 98

100 OCTET STRING OCTET STRING specifies octets of binary or textual information. While SMIv1 doesn't limit the number of octets, SMIv2 specifies a limit of octets. A size may be specified which can be fixed, varying, or of multiple ranges. Examples OCTET STRING -- length can vary from 0 to bytes OCTET STRING (SIZE(0..255)) OCTET STRING (SIZE(4)) -- fixed length of 4 bytes. OCTET STRING (SIZE(0 4 6)) -- varying with 0, 4, or 6 bytes The OCTET STRING type is used to specify octets of binary or textual information. There is no limit to the maximum number of octets in a value of this type specified in SMI v1. For setting the value for a variable of type OCTET STRING, the type should be SnmpApi.STRING. If you want to set the value in hex format, the value should be within the single quotes and each octet should be separated by a colon(:). For setting value for variable of type MacAddress(octet string size(6)) you have to give value as colon separated string and should be enclosed within single quotes for example: "'12:13:14:15:16:17'". Create Variable Using SnmpVar class The SnmpVar class is the base class for all SNMP variable classes. The CreateVariable(String value, sbyte type) method creates a new SnmpVar object with the specified type and value. String value = "60000"; SnmpVar snmpvar = SnmpVar.CreateVariable(value, SnmpAPI.STRING); Any string can be given here. The string can also be given in ASCII and each sbyte should be specified in hexadecimal, separated by a colon and enclosed in single quotes. SnmpVar var = SnmpVar.CreateVariable("'10:ff:1a:b2'", SnmpAPI.STRING); Using SnmpString class The constructor of this class creates an SnmpString object by taking a string as argument. String str = "teststring"; SnmpString snmpstring = new SnmpString(str); The string can also be given in ASCII. Here each sbyte should be specified in hexadecimal, separated by a colon. This should be enclosed within single quotes. String str = "'10:ff:1a:b2'"; SnmpString snmpstring = new SnmpString(str); AdventNet, Inc. 99

101 The SnmpString can be created using a specific character encoding using the following constructor. String str = "test"; String enc_string = "ISO8859_1"; SnmpString snmpstring = new SnmpString(str, enc_string); Using mibs package The following code snippet creates an SnmpVar object of OCTET STRING data type using the LeafSyntax class. String mibfile = "<mib name>"; String modulename = "RMON-MIB"; String nodename = "hostaddress"; MibOperations mibops = new MibOperations(); mibops.loadmibmodule(mibfile); MibModule module = mibops.getmibmodule(modulename); SnmpOID snmpoid = mibops.getsnmpoid(nodename); MibNode node = module.getmibnode(snmpoid); LeafSyntax syntax = node.getsyntax(); String value = "test"; // any string SnmpVar snmpvar = syntax.createvariable(value); Retrieve Value from Variable Using SnmpVar Class Following are the methods of SnmpString class that are used to retrieve value from the created variable. 1. The GetVarObject() returns the OCTET STRING value as String object. String str = "test"; SnmpString snmpstring = new SnmpString(str); String obj = (String)snmpstring.GetVarObject(); 2. The ToValue() method returns the OCTET STRING value as String object. String obj = (String )snmpstring.tovalue(); 3. The ToBytes() method returns the OCTET STRING value as a sbyte array. String obj = (String )snmpstring.tovalue(); This sbyte array contains the following values. array[0] = 0x74; // ascii value of "t" array[1] = 0x65; // ascii value of "e" array[2] = 0x73; // ascii value of "s" array[3] = 0x74; // ascii value of "t" This string contains the value " ". These are the hexadecimal representation of each of the bytes. 4. The ToString() method returns the OCTET STRING as a printable form. String value = snmpstring.tostring(); AdventNet, Inc. 100

102 This string contains the value "test". 5. The ToTagString() method returns the OCTET STRING with the tag "STRING" attached to it. String tagstring = snmpstring.totagstring(); This string will contain the value "STRING: test". 6. The ToByteString() method returns a string with each of the bytes in the OCTET STRING in hexa decimal form. String bytestring = snmpstring.tobytestring(); Using mibs package The tostring() and tobytestring() methods of the MibOperations class are used to retrieve the value of the variable as String. The following commands retrieve the value of the created variable. String value = mibops.tostring(snmpvar, snmpoid); This string contains the value "test". String value = mibops.tostring(snmpvarbind); This string contains the value "hostaddress:-->test". String value = mibops.tobytestring(snmpvar, snmpoid); This string contains the value " ". String value = mibops.tobytestring(snmpvarbind); This string contains the value "hostaddress:--> ". String value = mibops.tostring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.rmon.hosts.hostTable.hostEntry.hostAddress STRING: test String value = mibops.tobytestring(snmppdu); AdventNet, Inc. 101

103 This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.rmon.hosts.hostTable.hostEntry.hostAddress STRING: String value = mibops.totagstring(snmpvarbind); This string contains the following value. Object ID:.iso.org.dod.internet.mgmt.mib-2.rmon.hosts.hostTable.hostEntry.hostAddress STRING: test DISPLAY-HINT The value of an instance of an object with the syntax defined using this textual convention can be displayed using the DISPLAY-HINT clause. Refer Textual Conventions for more information. AdventNet, Inc. 102

104 OBJECT IDENTIFIER OBJECT IDENTIFIER identifies a type that has an assigned Object Identifier value. Create Variable Using SnmpVar class The SnmpVar class is the base class for all SNMP variable classes. The CreateVariable(String value, sbyte type) method creates a new SnmpVar object with the specified type and value. If the OID does not start with a dot, the string " " is prefixed to the OID. String value = " "; SnmpVar snmpvar= SnmpVar.CreateVariable(value, SnmpAPI.OBJID); Valid Usage SnmpVar var = SnmpVar.CreateVariable("1.1.0", SnmpAPI.OBJID); SnmpVar var = SnmpVar.CreateVariable(" ", SnmpAPI.OBJID); The above usage should be used carefully. The given value will be converted to zero while sending an SNMP request because only the least significant 4 bytes are taken. Invalid Usage SnmpVar var = SnmpVar.CreateVariable("sysDescr", SnmpAPI.OBJID); /td> The above usage is invalid because, the string argument will accept OIDs only in dotted form and not as a string. SnmpVar var = SnmpVar.CreateVariable(" abcd", SnmpAPI.OBJID); The above usage is invalid because, each of the sub-identifier should be an integer in decimal form. SnmpVar var = SnmpVar.CreateVariable(".1a.b3.6d.ff.1.2.a", SnmpAPI.OBJID); The above usage is invalid because, each of the sub-identifier should be an integer in decimal form and not in hexa decimal form. Using SnmpOID class The constructor of this class creates an SnmpOID object by taking String as argument. String value = " "; SnmpOID snmpoid = new SnmpOID(value); The following command also creates an SnmpOID object. int[] oids = {1, 3, 6, 1, 2, 1, 1, 1, 0}; SnmpOID oid = new SnmpOID(oids); AdventNet, Inc. 103

105 Using mibs package The following code snippet creates an SnmpVar object of OBJECT IDENTIFIER data type using the LeafSyntax class. String mibfile = "<mib name>"; String modulename = "<RFC1213-MIB>"; String nodename = "sysobjectid"; MibOperations mibops = new MibOperations(); mibops.loadmibmodule(mibfile); MibModule module = mibops.getmibmodule(modulename); SnmpOID snmpoid = mibops.getsnmpoid(nodename); MibNode node = module.getmibnode(snmpoid); LeafSyntax syntax = node.getsyntax(); String value = " "; //valid numbered OID SnmpVar snmpvar = syntax.createvariable(value); Valid Usage SnmpVar snmpvar = syntax.createvariable(" "); SnmpVar snmpvar = syntax.createvariable("1.1.0"); Note: If the OID does not start with a dot, the string " " is prefixed to the OID. Retrieve Value from Variable Using SnmpVar Class Following are the methods of SnmpOID class that are used to retrieve value from the created variable. 1. The GetVarObject() returns the OBJECT IDENTIFIER value as Long object. String str = " "; SnmpOID oid = new SnmpOID(str); String obj = (String)snmpoid.GetVarObject(); This string contains the value " ". 2. The ToValue() method returns the OBJECT IDENTIFIER value as an array of ints. int[] obj = (int[])snmpoid.tovalue(); This integer array contains the following values in the given order. obj[0] = 1; obj[1] = 3; obj[2] = 6; obj[3] = 1; obj[4] = 2; obj[5] = 1; obj[6] = 1; obj[7] = 1; obj[8] = 0; AdventNet, Inc. 104

106 3. The ToBytes() method returns the OBJECT IDENTIFIER as a sbyte array. sbyte[] array = snmpoid.tobytes(); This sbyte array will contain the following values. array[0] = 0x00; array[1] = 0x00; array[2] = 0x00; array[3] = 0x01; array[4] = 0x00; array[5] = 0x00; array[6] = 0x00; array[7] = 0x03; array[8] = 0x00; array[9] = 0x00; array[10] = 0x00; array[11] = 0x06; array[12] = 0x00; array[13] = 0x00; array[14] = 0x00; array[15] = 0x01; array[16] = 0x00; array[17] = 0x00; array[18] = 0x00; array[19] = 0x02; array[20] = 0x00; array[21] = 0x00; array[22] = 0x00; array[23] = 0x01; array[24] = 0x00; array[25] = 0x00; array[26] = 0x00; array[27] = 0x01; array[28] = 0x00; array[29] = 0x00; array[30] = 0x00; array[31] = 0x01; array[32] = 0x00; array[33] = 0x00; array[34] = 0x00; array[35] = 0x00; Here each of the value in the integer array will be converted into an array of 4 bytes. 4. The ToString() method returns the OBJECT IDENTIFIER value as a printable form. String value = snmpoid.tostring(); This string will contain the value " ". 5. The ToTagString() method returns the integer value in decimal with the tag "Object ID" attached to it. String tagstring = snmpoid.totagstring(); This string will contain the value "Object ID: ". Using mibs package The tostring() and tobytestring() methods of the MibOperations class are used to retrieve the value of the variable as String. The following commands retrieve the value of the created variable. String value = mibops.tostring(snmpvar, snmpoid); This string contains the value ".iso.org.dod.internet.mgmt.mib-2.system.sysdescr.0". String value = mibops.tostring(snmpvarbind); This string contains the value "sysobjectid:-->.iso.org.dod.internet.mgmt.mib-2.system.sysdescr.0". String value = mibops.tobytestring(snmpvar, snmpoid); This string contains the value ".iso.org.dod.internet.mgmt.mib-2.system.sysdescr.0". String value = mibops.tobytestring(snmpvarbind); This string contains the value "sysobjectid:-->.iso.org.dod.internet.mgmt.mib-2.system.sysdescr.0". String value = mibops.tostring(snmppdu); AdventNet, Inc. 105

107 This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.system.sysObjectID OBJID:.iso.org.dod.internet.mgmt.mib-2.system.sysDescr.0 String value = mibops.tobytestring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.system.sysObjectID OBJID:.iso.org.dod.internet.mgmt.mib-2.system.sysDescr.0 String value = mibops.totagstring(snmpvarbind); This string contains the following value. Object ID:.iso.org.dod.internet.mgmt.mib-2.system.sysObjectID OBJID:.iso.org.dod.internet.mgmt.mib-2.system.sysDescr.0 AdventNet, Inc. 106

108 IpAddress IpAddress is the string of four octets. A value of IpAddress type is an IPv4 address. A value is encoded as four bytes in network sbyte order. Create Variable Using SnmpVar class The SnmpVar class is the base class for all SNMP variable classes. The CreateVariable(String value, sbyte type) method creates a new SnmpVar object with the specified type and value. String value = " "; SnmpVar snmpvar = SnmpVar.CreateVariable(value, SnmpAPI.IPADDRESS) Valid Usage SnmpVar var = SnmpVar.CreateVariable(" ", SnmpAPI.IPADDRESS); SnmpVar var = SnmpVar.CreateVariable("localhost", SnmpAPI.IPADDRESS); Invalid Usage SnmpVar var = SnmpVar.CreateVariable("someUnknownHost", SnmpAPI.IPADDRESS); SnmpVar var = SnmpVar.CreateVariable(" ", SnmpAPI.IPADDRESS);//invalid OID Using SnmpIpAddress class The constructor of this class creates an SnmpIpAddress object by String as argument. String value = " "; SnmpIpAddress ipadd = new SnmpIpAddress(value); The following command also creates an SnmpIpAddress object. sbyte[] values = {(sbyte)192, (sbyte)168, (sbyte)5, (sbyte)99}; SnmpIpAddressipadd = new SnmpIpAddress(values); Valid Usage String str = " "; SnmpIpAddress snmpipaddress = new SnmpIpAddress(str); String str = "localhost"; SnmpIpAddress snmpipaddress = new SnmpIpAddress(str); sbyte[] array = { 1, 2, 3, 4 }; // represents SnmpIpAddress snmpipaddress = new SnmpIpAddress(array); sbyte[] array = { -64, -88, 1, -119 }; // represents SnmpIpAddress snmpipaddress = new SnmpIpAddress(array) AdventNet, Inc. 107

109 Invalid Usage String str = " "; SnmpIpAddress addr = new SnmpIpAddress(str); String str = "someunknownhost"; SnmpIpAddress snmpipaddress = new SnmpIpAddress(str); For the above usages, the IP address in that message is sent as null. That is, an IP address of length zero is sent. sbyte[] array = { 1, 2, 3 }; SnmpIpAddress snmpipaddress = new SnmpIpAddress(array); sbyte[] array = { 1, 2, 3, 4, 5 }; SnmpIpAddress snmpipaddress = new SnmpIpAddress(array); sbyte[] array = null; SnmpIpAddress snmpipaddress = new SnmpIpAddress(array); For the above three usages, the IP address is sent as Using mibs package The following code snippet creates an SnmpVar object of SnmpIpAddress data type using the LeafSyntax class. String mibfile = "<mib name>"; String modulename = "RFC1213-MIB"; String nodename = " udplocaladdress"; MibOperations mibops = new MibOperations(); mibops.loadmibmodule(mibfile); MibModule module = mibops.getmibmodule(modulename); SnmpOID snmpoid = mibops.getsnmpoid(nodename); MibNode node = module.getmibnode(snmpoid); LeafSyntax syntax = node.getsyntax(); String value = " "; //valid IP address SnmpVar snmpvar= syntax.createvariable(value); Valid Usage SnmpVar snmpvar = syntax.createvariable(" ");//dotted IP address SnmpVar snmpvar = syntax.createvariable("<hostname>");//valid host name SnmpVar snmpvar = syntax.createvariable("'c0a80164'h");//hex format SnmpVar snmpvar = syntax.createvariable("' 'b");//bina ry format Note: The input can be given in the hex and binary format. The value should contain four bytes. UnknownHostException is thrown if the host name or the IpAddress is invalid. AdventNet, Inc. 108

110 Retrieve Value from Variable Using SnmpVar Class Following are the methods of SnmpIpAddress class that are used to retrieve value from the created variable. 1. The GetVarObject() returns the SnmpIpAddress value as String object. String str = " "; SnmpIpAddress snmpipaddress = new SnmpIpAddress(str); String str = (String)snmpipaddress.GetVarObject(); The above string contains the value " ". 2. The ToValue() method returns the SnmpIpAddress value as String object. String str = (String)snmpipaddress.ToValue(); The above string contains the value " ". 3. The ToBytes() method returns as a sbyte array. sbyte[] array = snmpipaddress.tobytes(); The above sbyte array contains the following values. array[0] = 0xc0; // 192 in decimal array[1] = 0xa8; // 168 in decimal array[2] = 0x01; // 1 in decimal array[3] = 0x89; // 137 in decimal 4. The ToString() method returns the value as a printable form. String str = snmpipaddress.tostring(); The above string contains the value " ". 5. The ToTagString() method returns the value with the tag "IpAddress" attached to it. String str = snmpipaddress.totagstring(); The above string contains the value "IpAddress: ". Using mibs package The tostring() and tobytestring() methods of the MibOperations class are used to retrieve the value of the variable as String. The following commands retrieve the value of the created variable. String value = mibops.tostring(snmpvar, snmpoid); This string contains the value " ". AdventNet, Inc. 109

111 String value = mibops.tostring(snmpvarbind); This string contains the value "udplocaladdress:--> ". String value = mibops.tobytestring(snmpvar, snmpoid); This string contains the value " ". String value = mibops.tobytestring(snmpvarbind); This string contains the value "udplocaladdress:--> ". String value = mibops.tostring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.udp.udpTable.udpEntry.udpLocalAddress IPADDRESS: String value = mibops.tobytestring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.udp.udpTable.udpEntry.udpLocalAddress IPADDRESS: String value = mibops.totagstring(snmpvarbind); This string contains the following value. Object ID:.iso.org.dod.internet.mgmt.mib-2.udp.udpTable.udpEntry.udpLocalAddress IPADDRESS: AdventNet, Inc. 110

112 Opaque Opaque specifies octets of binary information. SMIv2 specifies a limit of octets while there is no limit in SMIv1. A size may be specified which can be fixed, varying, or of multiple ranges. A value of this type must be an encapsulation of ASN.1 BER encoded value. The Opaque type is provided solely for backward-compatibility, and shall not be used for newlydefined object types. This type supports the capability to pass arbitrary ASN.1 syntax. A value is encoded using the ASN.1 Basic Encoding Rules [4] into a string of octets. This, in turn, is encoded as an OCTET STRING, in effect "double-wrapping" the original ASN.1 value. Note that a conforming implementation need only be able to accept and recognize opaquely-encoded data. It need not be able to unwrap the data and then interpret its contents. A requirement on "standard" MIB modules is that no object may have a SYNTAX clause value of Opaque. Hence this data type should not be used for newly-defined object types. AdventNet, Inc. 111

113 BITS BITS is a pseudo data type that specifies a collection of labelled bits. It provides a way to label individual bits in an octet (an extension of OCTET STRING type). BITS is numbered by its position starting at zero an must be contiguously numbered till the last bit. Position zero is the high order bit of the first octet of the string. Position 7 is the low order bit in the second octet of the string. Position 8 is the high order bit in the second octet of string and so on. When the number of bits is not a multiple of eight, the remaining bits will be in the final octet. If the number of bits is 11, the first eight bits will be in the first octet and the next 3 bits will be in the second (final) octet. The remaining five bits in the final octet will be set to zero by default. The value of the BITS datatype can be either hexadecimal or binary. Hexadecimal values end with 'h'/'h'and binary values end with 'b'/ 'B'. Example Consider the syntax for BITS as follows. BITS {sunday(0), monday(1), tuesday(2), wednesday(3), thursday(4), friday(5), saturday(6)} If we want to set the value for monday, tuesday, and friday, the value can be set in any of the following format. {sunday(0), monday(1), tuesday(2), wednesday(3), thursday(4), friday(5), saturday(6)} In binary format, any of the following values can be set. ' 'b ' 'B b B b B In hex format, the following values can be set. '64'h '64'H 64H 64h In binary format, we append the zeros to get the minimum of 8 bits. For example, if the value is '80'h, you can give it as '8'h or '1'b. We append the zeros to get the multiple of 8 bits. Therefore, it becomes '80'h or ' 'b. In both cases, note that the last character is 'b' or 'h'. We can also set the value by giving the BITS label which is separated by a comma or a space. And the value can be a combination of the bits label and the bits number. For example, "monday tuesday friday" "monday 2 friday" -- 2 is the bits position for tuesday Here the bits label or bits number can be of any order like "tuesday monday friday". AdventNet, Inc. 112

114 The BITSTRING data type was deprecated in the SMIV2. (Structure of Management Information). Initially the BITSTRING defined with type value is 3. However, this was replaced with the BITS type. The BITS type is not new ASN.1 type. This is same as OCTET STRING type with a way to label individual bits. Therefore, our AdventNet API returns the type value is 4. (The type value for the OCTET STRING is 4). Create Variable Using SnmpVar class Consider the above example of the BITS syntax. Using bits, first a sbyte array should be constructed. Here since there are only 7 bits, a single sbyte can be used to represent this BITS value. The value of the above binary number is or 0x64. Therefore, the bye array is as follows. sbyte[] array = { (sbyte)0x64 }; String str = new String(array); SnmpVar var = SnmpVar.CreateVariable(str, SnmpAPI.STRING); Using SnmpBits class Valid Usage sbyte[] array = { (sbyte)0x64 }; SnmpBits bits1 = new SnmpBits(array); String str = " "; SnmpBits bits2 = new SnmpBits(str, 2); String str = "64"; SnmpBits bits2 = new SnmpBits(str, 16); Invalid Usage String str = "1234"; /p> SnmpBits bits2 = new SnmpBits(str, 2); String str = "xyz"; SnmpBits bits2 = new SnmpBits(str, 16); Using mibs package The following code snippet creates an SnmpVar object of Opaque data type using the LeafSyntax class. String mibfile = "<mib name>"; String modulename = "DATATYPE-MIB"; String nodename = "nodename27"; MibOperations mibops = new MibOperations(); mibops.loadmibmodule(mibfile); MibModule module = mibops.getmibmodule(modulename); SnmpOID snmpoid= mibops.getsnmpoid(nodename); MibNode node = module.getmibnode(snmpoid); LeafSyntax syntax = node.getsyntax(); String value = "monday 2 friday"; SnmpVar snmpvar = syntax.createvariable(value); AdventNet, Inc. 113

115 Retrieve Value from Variable Using SnmpVar Class Following are the methods of SnmpString class that are used to retrieve value from the created variable. 1. The GetVarObject() method returns the OCTET STRING value as String object. String obj = (String)snmpstring.GetVarObject(); 2. The ToValue() method returns the OCTET STRING as String object. String obj = (String )snmpstring.tovalue(); 3. The ToBytes() method returns OCTET STRING as a sbyte array. sbyte[] array = snmpstring.tobytes(); This sbyte array contains the following value. array[0] = 0x64; 4. The ToByteString() method returns string with each of the bytes in the OCTET STRING in hexadecimal form. String bytestring = snmpstring.tobytestring(); This string will contain the value "64". These are the hexadecimal representation of each of the bytes. 5. The ToString() method returns OCTET STRING as a printable string form. String value = snmpstring.tostring(); This string contains the ASCII representation of the value 0x The ToTagString() method returns the OCTET STRING value with tag of "STRING" attached to it. This string contains the ASCII representation of the value 0x64. String tagstring = snmpstring.totagstring(); This string contains the value "STRING: ". Using mibs package The tostring() and tobytestring() methods of the MibOperations class are used to retrieve the value of the variable as String. The following commands retrieve the value of the created variable. String value = mibops.tostring(snmpvar, snmpoid); This string contains the value "monday(1), tuesday(2), friday(5)". String value = mibops.tostring(snmpvarbind); AdventNet, Inc. 114

116 This string contains the value "nodename27:-->monday(1), tuesday(2), friday(5)". String value = mibops.tobytestring(snmpvar, snmpoid); This string contains the value "monday(1), tuesday(2), friday(5)". String value = mibops.tobytestring(snmpvarbind); This string contains the value "nodename27:-->monday(1), tuesday(2), friday(5)". String value = mibops.tostring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.private.enterprises.adventnet.snmpMIB.allNodes.nodeName27 STRING: monday(1), tuesday(2), friday(5) String value = mibops.tobytestring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.private.enterprises.adventnet.snmpMIB.allNodes.nodeName27 STRING: monday(1), tuesday(2), friday(5) String value = mibops.totagstring(snmpvarbind); This string contains the following value. Object ID:.iso.org.dod.internet.private.enterprises.adventnet.snmpMIB.allNodes.nodeName27 STRING: monday(1), tuesday(2), friday(5) AdventNet, Inc. 115

117 Textual Conventions Overview DateAndTime MacAddress While designing a MIB module, it is often useful to define new types similar to those defined in the SMI. These new types with different names, a similar syntax, and a more precise semantics are termed as textual conventions. The textual convention objects do not need separate classes because they are resolved into base data types. The textual convention objects are handled internally in the mibs package. AdventNet SNMP API supports the MacAddress and DateAndTime, according to their definitions. AdventNet, Inc. 116

118 Overview Objects defined using a textual convention are always encoded by means of the rules that define their primitive type. The ASN.1 macro, TEXTUAL-CONVENTION, is used to concisely convey the syntax and semantics of a textual convention. The macro construct for textual convention and an example is given below. ucname TEXTUAL-CONVENTION [DISPLAY-HINT Text] [STATUS Status] DESCRIPTION Text [REFERENCE Text] SYNTAX Syntax MacAddress ::= TEXTUAL-CONVENTION DISPLAY-HINT "1x:" STATUS current DESCRIPTION "Represents an 802 MAC address represented in the 'canonical' order defined by IEEE 802.1a, i.e., as if it were transmitted least significant bit first, even though (in contrast to other 802.x protocols) requires MAC addresses to be transmitted most significant bit first." SYNTAX OCTET STRING (SIZE (6)) DISPLAY-HINT Clause The DISPLAY-HINT clause defines how the value of an instance of an object with the syntax defined using this textual convention should be displayed. If the syntax of the TEXTUAL-CONVENTION has an underlying primitive type of INTEGER, the DISPLAY-HINT consists of an integer-format specification, containing two parts. <intdisplayhint> = "d" ["-" number] <singlechar> <singlechar> = o x b The hint can be a single character for the display format, 'x' for hexadecimal, 'd' for decimal, 'o' for octal and 'b' for binary. For displaying the value in the decimal format, the "d" can be followed by a hyphen and a decimal number, which defines the implied decimal point for the value. If the syntax of the TEXTUAL-CONVENTION has an underlying primitive type of OCTET STRING, <octetdisplayhint> = number <displayformat> [<sepchar>] number <displayformat> [<sepchar> [<reptermchar>]] number - unsigned integer <displayformat> - d a o x <sepchar> - separator character: any character except * and decimal digit <reptermchar> - repeat terminator character: any character other than * and decimal digit Example for DISPLAY-HINT is "2a:" where 2 is the number a is the display format : is the separator character AdventNet, Inc. 117

119 Displaying the Value in the DISPLAY-HINT Format If you need to print the value in the DISPLAY-HINT, format, the method enabledisplayhint(boolean) in the MibOperations class must be set to true. MibOperations mibops = new MibOperations(); mibops.loadmibmodules(mibfile); SnmpOID oid = mibops.getsnmpoid("nodename"); MibNode node = mibops.getmibnode(oid); LeafSyntax = node.getsyntax(); SnmpVar var = syntax.createvariable("displaytest"); If the syntax of the node is a TC whose base syntax is INTEGER/Integer32 and the DISPLAY-HINT is "d-2", SnmpVar var = syntax.createvariable("12345"); mibops.enabledisplayhint(true); String outdisplaystr = mibops.tostring(var,oid); Here outdisplaystr is If the method enabledisplayhint(boolean) is not called or if the boolean is set to false, the outdisplaystr is Refer the Integer32 section for more information on displaying integer values. If the syntax of the node is a TC whose base syntax is OCTET STRING and the DISPLAY-HINT is "2a:", SnmpVar var = syntax.createvariable("displaytest"); mibops.enabledisplayhint(true); String outdisplaystr = mibops.tostring(var,oid); Here, the outdisplaystr is di:sp:la:yt:es:t: If the method enabledisplayhint(boolean) is not called or if the boolean is set to false, the outdisplaystr is displaytest. Refer the OCTET STRING section for more information on displaying String values. AdventNet, Inc. 118

120 DateAndTime DateAndTime is a standard Textual Convention which is defined in the SNMPv2-TC. DateAndTime is resolved to base data type OCTET STRING. The DISPLAY-HINT format for DataAndTime is given as follows. DISPLAY-HINT "2d-1d-1d,1d:1d:1d.1d,1a1d:1d" The date-time specification is as follows. Field Octets Contents Range year month day hour minutes seconds (use 60 for leapsecond) deci-seconds direction from UTC '+' / '-' 9 10 hours from UTC minutes from UTC Note: The value of year is in network-byte order. Create Variable with DateAndTime Syntax Using mibs package For creating a value for a node, the createvariable() method in the LeafSyntax class is used. The DateAndTime format value can be either 8 or 11 bytes. If the value is given in hex format, each octets should be separated by a colon and the value should be enclosed within single quotes. The following code snippet creates an SnmpVar object of DateAndTime type using the LeafSyntax class. String mibfile = "<mib name>"; String modulename = "HOST-RESOURCES-MIB"; String nodename = "hrsystemdate"; MibOperations mibops = new MibOperations(); mibops.loadmibmodule(mibfile); MibModule module = mibops.getmibmodule(modulename); SnmpOID snmpoid = mibops.getsnmpoid(nodename); MibNode node = module.getmibnode(snmpoid); LeafSyntax syntax = node.getsyntax(); String value = " ,12:20:32.3,+5:30"; SnmpVar snmpvar = syntax.createvariable(value); AdventNet, Inc. 119

121 Valid Usage SnmpVar snmpvar = syntax.createvariable("'07:d2:09:03:0c:14:20:03:2b:07:00'");//hex format, length 11 bytes SnmpVar snmpvar = syntax.createvariable("'07:d2:09:03:0c:14:20:03'");//hex format, length 8 bytes SnmpVar snmpvar = syntax.createvariable(" ,13:53:32.3,- 7:0");//string format, length 11 bytes SnmpVar snmpvar = syntax.createvariable(" ,13:53:32.3");//string format, length 8 bytes Note: The hex value should be enclosed with the single quotes. If the value is in any of the above formats, the value is recognized as DateAndTime value. In the first format, each octets separated by colon is considered as a sbyte and these bytes are stored in a sbyte array of length 8 or 11. If the value is in the second format, the value is translated to hex string based on DISPLAY-HINT and the bytes are stored in the sbyte array. Retrieve Value from Variable Using mibs package The tostring() and tobytestring() methods of the MibOperations class are used to retrieve the value of the variable as String. The following commands retrieve the value of the created variable. String value = mibops.tostring(snmpvar, snmpoid); This string contains the value " ,12:20:32.3,+5:30". String value = mibops.tostring(snmpvarbind); This string contains the value "hrsystemdate:--> ,12:20:32.3,+5:30". String value = mibops.tobytestring(snmpvar, snmpoid); This string contains the value " ,12:20:32.3,+5:30". String value = mibops.tobytestring(snmpvarbind); This string contains the value "hrsystemdate:--> ,12:20:32.3,+5:30". String value = mibops.tostring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 AdventNet, Inc. 120

122 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.host.hrSystem.hrSystemDate STRING: ,12:20:32.3,+5:30 String value = mibops.tobytestring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.host.hrSystem.hrSystemDate STRING: ,12:20:32.3,+5:30 String value = mibops.totagstring(snmpvarbind); This string contains the following value. Object ID:.iso.org.dod.internet.mgmt.mib-2.host.hrSystem.hrSystemDate STRING: ,12:20:32.3,+5:30 AdventNet, Inc. 121

123 MacAddress MacAddress is a standard TEXTUAL-CONVENTION defined in SNMPv2-TC. MacAddress is resolved to the base datatype OCTET STRING. The DISPLAY-HINT format for MacAddress is given as follows. DISPLAY-HINT "1x:" Create Variable Using mibs package For creating a value for a node, the CreateVariable() method in the LeafSyntax class is used. The MacAddress value should be six bytes. Each sbyte should be separated by colon(:) and the value should be enclosed in single quotes. The following code snippet creates an SnmpVar object of MacAddress type using the LeafSyntax class. String mibfile = "<mib name>"; String modulename = "TOKENRING-MIB"; String nodename = "dot5upstream"; MibOperations mibops = new MibOperations(); mibops.loadmibmodule(mibfile); MibModule module = mibops.getmibmodule(modulename); SnmpOID snmpoid = mibops.getsnmpoid(nodename); MibNode node = module.getmibnode(snmpoid); LeafSyntax syntax = node.getsyntax(); String value = "a:b:c:d:e:f"; SnmpVar snmpvar = syntax.createvariable(value); Retrieve Value from Variable Using mibs package The tostring() and tobytestring() methods of the MibOperations class are used to retrieve the value of the variable as String. The following commands retrieve the value of the created variable. String value = mibops.tostring(snmpvar, snmpoid); This string contains the value "0a 0b 0c 0d 0e 0f". String value = mibops.tostring(snmpvarbind); This string contains the value "dot5upstream:-->0a 0b 0c 0d 0e 0f". String value = mibops.tobytestring(snmpvar, snmpoid); This string contains the value "0a 0b 0c 0d 0e 0f". String value = mibops.tobytestring(snmpvarbind); AdventNet, Inc. 122

124 This string contains the value "dot5upstream:-->0a 0b 0c 0d 0e 0f". String value = mibops.tostring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.transmission.dot5.dot5Table.dot5Entry.dot5UpStream STRING: 0a 0b 0c 0d 0e 0f String value = mibops.tobytestring(snmppdu); This string contains the following value. SNMP PDU (type unknown/unspecified) SNMP Version: Version 1 Remote Port: 0 Community: null Request ID: 0 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID:.iso.org.dod.internet.mgmt.mib-2.transmission.dot5.dot5Table.dot5Entry.dot5UpStream STRING: 0a 0b 0c 0d 0e 0f String value = mibops.totagstring(snmpvarbind); This string contains the following value. Object ID:.iso.org.dod.internet.mgmt.mib-2.transmission.dot5.dot5Table.dot5Entry.dot5UpStream STRING: 0a 0b 0c 0d 0e 0f AdventNet, Inc. 123

125 Data Retrieval Operations SNMP GET SNMP GETNEXT SNMP GETBULK This section discusses the various data retrieval operations. AdventNet, Inc. 124

126 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 , we need to specify to retrieve the OID's value. If the request is made without the instance value, the agent returns an error. The SnmpAPI, SnmpSession, and SnmpPDU classes are used for most of the management operations. 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 API. 1. Instantiate the SnmpAPI class. SnmpAPI api = new SnmpAPI(); 2. Instantiate and open the SnmpSession class. SnmpSession session = new SnmpSession(api); session.open(); 3. 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 Version() method and use the Command() 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(); //get the value from the command line UDPProtocolOptions option = new UDPProtocolOptions(remoteHost); pdu.protocoloptions=option; pdu.command=snmpapi.get_req_msg; AdventNet, Inc. 125

127 4. 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. 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 pdu.addnull(oid); 5. 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.Console.Out.WriteLine(result.PrintVarBinds()); 6. Close the session and the API thread. session.close(); api.close(); AdventNet, Inc. 126

128 SNMP GETNEXT The SNMP GETNEXT operation is similar to the SNMP GET operation. The GETNEXT operation retrieves the value of the next OID in the tree. The GETNEXT operation is particularly useful for retrieving the table data and also for variables that cannot be specifically named. It is used for traversing the MIB tree. Unlike SNMP GET, providing the instance value as part of the OID is not mandatory. The SNMP GETNEXT operation always returns the next OID in the MIB tree regardless of whether we specify the particular instance of OID. This is similar to performing a SNMP GET operation as discussed in SNMP GET topic. To perform the SNMP GETNEXT operation, we need to use the GETNEXT_REQ_MSG command constant instead of GET_REQ_MSG. //Build GETNEXT Request PDU SnmpPDU pdu = new SnmpPDU(); //get the value from the command line UDPProtocolOptions option = new UDPProtocolOptions(remoteHost); pdu.protocoloptions=option; pdu.command=snmpapi.getnext_req_msg; The rest of the steps remain the same as SNMP GET. AdventNet, Inc. 127

129 SNMP GETBULK The GETBULK operation is normally used for retrieving large amount of data, particularly from large tables. A GETBULK request is made by giving an OID list along with a Max-Repetitions value and a Nonrepeaters value. The GETBULK operation performs a continuous GETNEXT operation based on the Max-Repetitions value. The Nonrepeaters value determines the number of variables in the variable list for which a simple GETNEXT operation has to be done. For the remaining variables, the continuous GETNEXT operation is done based on the Max-Repetitions value. In other words, the SNMP GETBULK operation does a simple GETNEXT operation for the first N variable bindings in the request and does M GETNEXT operation (continuous) for each of the remaining R variable bindings in the request list where N is the minimum of the value of the Non-Repeaters field in the request the number of variable bindings in the request M is the Max-Repetitions field of the request R is the maximum of the number of variable bindings in the request zero Thus the total number of varbinds in the response message is (N + M x R). This is similar to performing a SNMP GET operation as discussed in SNMP GET topic. The additional parameters for the SNMP GETBULK operations can be set using the following methods. MaxRepetitions() NonRepeaters() To perform an SNMP GETBULK operation, the command constant GETBULK_REQ_MSG defined in the SnmpAPI class is used. //Build GETNEXT Request PDU SnmpPDU pdu = new SnmpPDU(); //get the value from the command line UDPProtocolOptions option = new UDPProtocolOptions(remoteHost); pdu.protocoloptions=option; pdu.command=snmpapi.getbulk_req_msg; pdu.maxrepetitions=10; pdu.nonrepeaters=0; The rest of the steps will remain the same as the SNMP GET operation. AdventNet, Inc. 128

130 Data Altering Operations SNMP SET Setting Values for Datatypes This section discusses the various data altering operations. AdventNet, Inc. 129

131 SNMP SET The SNMP SET operation is used by the management applications to modify the value of the managed object. Most of the managed objects have a default value maintained by the agent. Sometimes the applications might want to modify one or more MIB variables by using the SNMP SET operation. The applications typically perform an SNMP SET operation by providing the host name of the agent, one or more OIDs along with its instance, and the new value. The agent processes the request and assigns the new value to the MIB variable. If an error occurs, the new value is not assigned. The SnmpAPI, SnmpSession, and SnmpPDU classes are used for most of the management operations. To use the communication services available with the API, we must instantiate 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 the socket, SnmpTransportProvider, (DatagramSocket in case of UDP) for SNMP communication. 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 SET operation using the API. Instantiate the SnmpAPI class. SnmpAPI api = new SnmpAPI(); Instantiate and open the SnmpSession class. SnmpSession session = new SnmpSession(api); session.open(); To perform SNMP SET operations, the command constant SET_REQ_MSG defined in the SnmpAPI class should be used. // Build set request PDU SnmpPDU pdu = new SnmpPDU(); pdu.command=snmpapi.set_req_msg; To perform SET operations we need to know the OID, its type, and its value. These values are needed to build the varbind and can be received as user input. The variable binding or the varbind is the pairing of the OID and its corresponding value. This varbind should be added to the PDU for performing SET operations. The type of the variable can be INTEGER, STRING, COUNTER, etc. The SnmpAPI class provides constants for all the SNMP data types. Using this type, the value an instance of SnmpVar is created. String value = "localhost"; sbyte datatype = SnmpAPI.STRING; SnmpOID oid = new SnmpOID("1.5.0"); // sysname SnmpVar var = null; // create SnmpVar instance for the value and the type var = SnmpVar.CreateVariable(value_Renamed, datatype); AdventNet, Inc. 130

132 This SnmpVar object is used to create the varbind. //create varbind SnmpVarBind varbind = new SnmpVarBind(oid, var); The variable binding is then added to the PDU. //add variable binding pdu.addvariablebinding(varbind); Now the request 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. result = session.syncsend(pdu); System.Console.Out.WriteLine("Response PDU received from " + result.address+ ", community: " + result.community); System.Console.Out.WriteLine(result.PrintVarBinds()); Close the session and the API thread. session.close(); api.close(); AdventNet, Inc. 131

133 Setting Values for Datatypes The various values that are to be specified in a SET operation with respect to the SYNTAX of the object is given in the following table. Base How to Set the Value Data Types or TCs Value Value in Hexadecimal Value in Binary INTEGER 100 '64'h ' 'b Integer32 Unsigned '64'h ' 'b OCTET STRING adventnet OBJECT IDENTIFIER or NULL Counter 100 '64'h ' 'b Counter32 Gauge Gauge '64'h ' 'b BITS STRING '54'h/'54'H or ' 'b BITS {zero(0), one(1), h/54H '010101'b two(2), three(3), one three five b four(4), five(5) } one 3 five '50'h'/'50'H or '5'h/'50'H b TIMETICKS 100 '64'h ' 'b IpAddress / hostname NetworkAddress / hostname OPAQUE '64'h , 13:53:32.3, -7:0 '07:cb:09:15:0d:35: 20:03:2d:07:00' DateAndTime TAddress MacAddress or , 13:53: / 161 or '07:cb:09:15:0d:35: 20:03' f1:f2:f3:f4:f5:f6 Refer Handling Datatypes for more information on datatypes. AdventNet, Inc. 132

134 Traps and Notifications Receiving Notifications Sending Notifications This section discusses the various trap handling operations. AdventNet, Inc. 133

135 Receiving Notifications The interface SnmpClient is used by applications to send and receive messages asynchronously. The SnmpClient interface implements callback, authentication, and debugging functions. We implement SnmpClient in our main class. public class SnmpTrapd : SnmpClient { We need to instantiate and start the SnmpAPI and open SnmpSession. We need to add the SnmpClient interface implementation to the session to invoke the callback, authentication, and debugging functions. By convention, the traps are received at the port 162. In this example, we set the local port to 8001 for receiving the traps. // set local port SnmpPDU pdu = new SnmpPDU(); UDPProtocolOptions option = new UDPProtocolOptions(); option.localport=8001; session.protocoloptions=option; // Open the session try { session.open(); } catch (SnmpException e) { System.Console.Error.WriteLine("Error opening socket: " + e); } System.Console.Out.WriteLine("Waiting to receive traps " + "..."); Now, we have to implement three methods of the SnmpClient interface. The Authenticate() method should check the community received in the response PDU with the community of the particular session. The "community" argument in the Authenticate() method is same as the session.community and the "pdu" argument is the received PDU. public virtual bool Authenticate(SnmpPDU pdu, System.String community) { System.Console.Out.WriteLine("Inside the authenticate"); return (pdu.community.equals(community)); } The Callback() method should handle the PDU received for a particular session. The "session" argument is the session for which the PDU is received. The "pdu" argument is the PDU received. The "requestid" is the request ID of the sent PDU for which the response is received. The received trap information is handled here. public virtual bool Callback(SnmpSession session, SnmpPDU pdu, int requestid) { // print the received trap information AdventNet, Inc. 134

136 System.Console.Out.WriteLine("Inside the call back"); System.Console.Out.WriteLine("Trap received from: " + pdu.address + ", community: " + pdu.community); System.Console.Out.WriteLine("Enterprise: " + pdu.enterprise); System.Console.Out.WriteLine("Agent: " + pdu.agentaddress); System.Console.Out.WriteLine("TRAP_TYPE: " + pdu.traptype); System.Console.Out.WriteLine("SPECIFIC NUMBER: " + pdu.specifictype); System.Console.Out.WriteLine("Time: " + pdu.uptime + "\nvarbinds:"); System.Console.Out.WriteLine(pdu.PrintVarBinds()); return true; } The DebugPrint is used for printing any debug information. public virtual void DebugPrint(System.String debugoutput) { System.Console.Out.WriteLine("Inside the debug"); System.Console.Out.WriteLine(debugOutput); return ; } Trap Performance AdventNet SNMP API can receive about 2000 to 2500 traps per second continuously without dropping packets. When a burst of traps is sent in a short time, it can receive more than the abovementioned number. The trap performance is dependent on various factors such as the type of the OS, network traffic, etc. As a result, the trap receiver applications might not always receive all the traps. One main reason for loss of traps is the UDP buffer overflow. As of now, the trap pool is the UDP buffer. Therefore, the application gets all the traps from the UDP buffer. If the application performs some action each time it receives a trap, there is a chance that UDP buffer overflows resulting in loss of packets. One way to avoid this is to have a trap receiver that continuously receives the trap and puts it into a buffer. Then another job can be scheduled to process these traps from the buffer one at a time. This way, we can implement a buffering technique to process traps. Alternatively, we can use the Callbackthread() = boolean method of SnmpSession class to implement the callback mechanism. By default, this method is set to false. Setting it true enables to run the callback in a separate thread. This is recommended only if any significant implementation is to be done in the callback. Calling the callback from a separate thread deteriorates the performance of the receiver thread in receiving responses or traps. AdventNet, Inc. 135

137 Sending Notifications Sending notifications are normally the functions of the SNMP agents. This functionality should be used only for testing and simulating purposes. A full-fledged notification functionality is the responsibility of the agent Following are the steps involved in sending notifications. /Instantiate an SnmpPDU class SnmpPDU pdu = new SnmpPDU(); /// Start SNMP API SnmpAPI api; api = new SnmpAPI(); api.start(); api.debug=true; // Open session SnmpSession session = new SnmpSession(api); // set remote Host session.peername=remotehost; // set remote port session.remoteport=8001; //Build SNMPv2c trap pdu.command=adventnet.snmp.snmp2.snmpapi.trp_req_msg; //Add the Up time variable binding - mandatory SnmpOID oid = new SnmpOID(OID); var = SnmpVar.CreateVariable(value_Renamed, datatype);... SnmpVarBind varbind = new SnmpVarBind(oid,var); pdu.addvariablebinding(varbind); //Add the Trap OID variable binding - mandatory oid = new SnmpOID(" "); var = SnmpVar.CreateVariable(trapoidvalue,SnmpAPI.OBJID);... SnmpVarBind varbind = new SnmpVarBind(oid,var); pdu.addvariablebinding(varbind); //Add additional variable bindings, if required //Send the Trap PDU SnmpSession session = new SnmpSession(api); session.open(); session.send(pdu); AdventNet, Inc. 136

138 Table Handling in Applications SNMP Table Basics Fetching Tables Getting Row Data Getting Column Data Modifying Table Data Adding a Row Deleting a Row An SNMP table can be defined as an ordered collection of objects consisting of zero or more rows. Each row may contain one or more objects. Each object in a table is identified using the table index. A table can have a single index or multiple indices. This section explains some of the basic concepts related to SNMP tables. AdventNet, Inc. 137

139 SNMP Table Basics An SNMP table can be defined as an ordered collection of objects consisting of zero or more rows. Each row may contain one or more objects. Each object in a table is identified using the table index. A table can have a single index or multiple indices. A scalar variable has a single instance and is identified by its ".0". On the other hand, a table object or the columnar variable can have one or more instances and is identified by its index value. To identify a specific columnar variable, the index of the row has to be appended to its OID. For example for a table with OID x.x.xTable, with the column name yy and the index value ind1, the value of the column yy can be got by appending the instance ind1 to the columnar OID x.x.xTable.xEntry.yy. If the table has multiple indices namely ind1 and ind2 then the value of the column yy can be got by using the OID x.x.xTable.xEntry.yy.ind1.ind2. For example, consider tcpconntable. It has four indices namely tcpconnlocaladdress, tcpconnlocalport, tcpconnremaddress, and tcpconnremport where the values of the table are as follows. tcpconnstate tcpconnlocaladdress tcpconnlocaport tcpconnremaddress tcpconnremport listen(2) listen(2) listen(2) listen(2) established(5) established(5) closewait(8) To get the value of the column tcpconnstate for the last row, you have to query with the OID tcpconnstate where is the value of tcpconnlocaladdress for the last row, 1156 is the value of tcpconnlocalport for the last row is the value of tcpconnremaddress for the last row 80 is the value of tcpconnremport for the last row. Also if the index is of integer type, it can be in any order. For example in a table, if the values of the index column are {1,2,3,4}, it can have values in any order say {2,4,3,1}. Augmented Table Augmented Table comes into picture when there is one-to-one dependency between rows of one table and rows in another table. In such cases, one table is the base and the other is the augmenting table. This might arise when a particular MIB imports another MIB and shares the same table. A classic example is IF-MIB importing the group interfaces defined in RFC 1213-MIB, where IF-MIB augments the iftable defined in RFC 1213-MIB. Table with Implied Index An index may be qualified by a modifier IMPLIED if the type of the variable is of varying length (e.g. OctetString or IpAddress or OID). If the index of a table is implied, then there is no need to specify the length of the instance variable. If the base type (SYNTAX) is IpAddress and the index is qualified by the modifier IMPLIED, the length of the instance is taken as 4. AdventNet, Inc. 138

140 Tables with External Index These tables are similar to the augmented tables which share the index values with other tables. However these are SMIv1 tables and augmented tables are SMIv2 tables. Tables with EntryStatus and RowStatus Column In an SNMP table, adding or deleting rows are possible only if the table has the EntryStatus column defined (if it is an SMIv1 table) or with the RowStatus column defined (if it is an SMIv2 table). SMIv1 Tables with EntryStatus Column The EntryStatus column is used to manage the creation and deletion of conceptual rows in SMIv1 tables. This represents the status of a table entry. The status column can have the following. 'valid(1)' - indicates that the row exists and is available for use. 'createrequest(2)' - supplied by the manager wishing to create a row. 'undercreation(3)' - indicates that the row is being created. 'invalid(4)' - supplied by the manager wishing to invalidate the corresponding entry. If a manager wishes to add a row, then the entrystatus column should be set to createrequest(2). Immediately after the creation, the agent sets this object to undercreation(3). The entry remains in the undercreation(3) state until it is configured. Then its value is set to valid(1). If the status remains undercreation(3) for an abnormally long period, then the agent sets the status to invalid(4). SMIv2 Tables with RowStatus Column In SMIv2 tables, the RowStatus column is used to manage the creation and deletion of conceptual rows. This column has six defined values as follows. active(1) - indicates that the conceptual row with all columns is available for use by the managed device. notinservice(2) - indicates that the conceptual row exists in the agent, but is unavailable for use by the managed device. notready(3) - indicates that the conceptual row exists in the agent, one or more required columns in the row are not instantiated. createandgo(4) - supplied by a manager wishing to create a new instance of a conceptual row and make it available for use. createandwait(5) - supplied by a manager wishing to create a new instance of a conceptual row but not making it available for use. destroy(6) - supplied by a manager wishing to delete all of the instances associated with an existing conceptual row. An existing conceptual row can be in any one of the three states, 'notready', 'notinservice', or 'active'. If the manager wishes to add a row in a single shot with values for all the columns, the status column should be given as 'createandgo(4)'. After the creation of a row, its value is set to active(1). If a row has to be created with values for only some columns, the status column should be 'createandwait(5)'. Also, this row with partially filled columns has the status 'notready(3)'. The entry remains in this state until the values for all the columns is set. After all the values are set, the agent changes this value to active(1). AdventNet, Inc. 139

141 Fetching Tables To retrieve the table data, the SnmpAPI, SnmpSession, and SnmpPDU classes of the snmp2 namespace are used. The table data can be fetched by adding the columnoids (column names) of the table to the PDU and performing GETNEXT repeatedly. Following is the sample table. ID managerhost managerport 3 localhost server printer switch 8080 If the columnoids are , , , to get the table data the following code snippet can be used. SnmpAPI api = new SnmpAPI(); SnmpSession session = new SnmpSession(api); SnmpPDU pdu = new SnmpPDU(); UDPProtocolOptions option = new UDPProtocolOptions("localhost"); pdu.protocoloptions = option; //sets the host in which the agent is running SnmpOID[] oids = new SnmpOID[3]; oids[0]=new SnmpOID(" "); oids[1]=new SnmpOID(" "); oids[2]=new SnmpOID(" "); for(int i=0;i<3;i++) { pdu.addnull(oids[i]); } pdu.command = SnmpAPI.GETNEXT_REQ_MSG; //send PDU SnmpPDU result = session.syncsend(pdu); System.Console.Out.WriteLine(result.PrintVarBinds() + "\n"); AdventNet, Inc. 140

142 Getting Row Data Sometimes, the specifications require to fetch a particular row from a SNMP table. To retrieve a particular row from a table, the index value of the row should be known. To get the data of a row from the table, the OIDs (columnsoid.instance) can be added to the PDU using pdu.addnull(oids) and the request can be sent by setting the request command SnmpAPI.GET_REQ_MSG in the PDU. This fetches the data for the specified row. Consider the sample table. ID managerhost managerport 3 localhost server printer switch 8080 If the columnoids are , , , following is the code to fetch the values for the second row in the table. SnmpAPI api = new SnmpAPI(); SnmpSession session = new SnmpSession(api); SnmpPDU pdu = new SnmpPDU(); UDPProtocolOptions option = new UDPProtocolOptions("localhost"); pdu.protocoloptions = option; //sets the host in which the agent is running SnmpOID[] oids = new SnmpOID[3]; oids[0]=new SnmpOID(" "); oids[1]=new SnmpOID(" "); oids[2]=new SnmpOID(" "); for(int i=0;i<oids.length;i++) { pdu.addnull(oids[i]); } pdu.command = SnmpAPI.GET_REQ_MSG; try { session.open(); } catch (SnmpException e ) { System.Console.Error.WriteLine("Error opening socket: "+e); } try { session.syncsend(pdu); } catch (SnmpException ex) { System.Console.Error.WriteLine("Error sending SNMP request: "+ex); } AdventNet, Inc. 141

143 Getting Column Data Similar to retrieving row data of a table, applications might also require to retrieve one or more column data. To retrieve a specific column or columns from a table, the columnoid of the row should be known. If the data for a single column alone is required, the columnoid can be set in the PDU and request can be sent using session.syncsend() method. ID managerhost managerport 3 localhost server printer switch 8080 If the columnoids are , , , following code gets the second column (managerhost). SnmpAPI api = new SnmpAPI(); SnmpSession session = new SnmpSession(api); SnmpPDU pdu = new SnmpPDU(); UDPProtocolOptions option = new UDPProtocolOptions("localhost"); pdu.protocoloptions = option; //sets the host in which the agent is running SnmpOID oid = new SnmpOID(" "); pdu.command = SnmpAPI.GETNEXT_REQ_MSG; session.open(); session.syncsend(pdu); SnmpOID oid = new SnmpOID(" "); pdu.addnull(oid); pdu.command = SnmpAPI.GETNEXT_REQ_MSG; try{ session.open(); session.syncsend(pdu); } catch(snmpexeption e) { System.Console.Error.WriteLine("Error opening socket or sending SNMP request: "+e); } AdventNet, Inc. 142

144 Modifying Table Data To set any value for a particular cell in the table, the row and column index should be known. The value can be set only if the data for the row, which contains the cell, is fetched by the table before a new value is set. To set any value for a particular cell, the SnmpVarBind object with the OID of the cell, which is the columnoid appended by the row index for which new value has to be set, and the new value can be added to the PDU. Then the request can be sent using the SyncSend() method in SnmpSession class. ID managerhost managerport 3 localhost server printer switch 8080 For example, the following code snippet is used to change the managerhost column value 'switch' to a new value 'value' where the numeric OIDs for these columnoids be , , SnmpPDU pdu=new SnmpPDU(); pdu.command = SnmpAPI.SET_REQ_MSG; SnmpOID oid=new SnmpOID(" "); SnmpVar var=snmpvar.createvariable("value",snmpapi.string); SnmpVarBind varbind = new SnmpVarBind(oid, var); pdu.addvariablebinding(varbind); session.syncsend(pdu); AdventNet, Inc. 143

145 Adding a Row To add a new row to a SNMP table from the manager, the table should be an SMIv1 table with EntryStatus column defined or a SMIv2 table with RowStatus column defined in it. For more information on EntryStatus and RowStatus, refer SNMP Table Basics. To retrieve the table data, the SnmpAPI, SnmpSession, and SnmpPDU classes of the snmp2 namespace are to be used. For SMIv2 tables ID managerhost managerport rowstatus 3 localhost server printer switch The following code snippet creates SnmpOID[] for the columnoids to add a row to this table with index 15 where the numeric OIDs for these columnoids are , , , and SnmpOID oid[]=new SnmpOID[4]; oid[1]=new SnmpOID(" "); oid[2]=new SnmpOID(" "); oid[3]=new SnmpOID(" "); oid[4]=new SnmpOID(" "); The following code creates the SnmpVar objects with the value and the type of the value. SnmpVar var[]=new SnmpVar[4]; var[0]=snmpvar.createvariable("15",snmpapi.integer); var[1]=snmpvar.createvariable("switch2 quot;,snmpapi.string); var[2]=snmpvar.createvariable("9000",snmpapi.integer); var[3]=snmpvar.createvariable("4",snmpapi.integer); // the value 4 refers to createandgo. The following code creates SnmpVariableBindings using this SnmpOID and SnmpVar and adds it to the PDU using addvariablebinding(). for(int i=0;i<oid.length;i++){ SnmpVarBind varbind=new SnmpVarBind(oid[i],var[i]); pdu.addvariablebinding(varbind); } Then perform Session.SyncSend(pdu) to add a new row to the table. Now the rowstatus column value is changed to active(1) by the agent. While creating a row, either createandgo(4) or createandwait(5) can be given to the RowStatus column depending on the number of columns for which values are to be set. Add a row with partially filled columns, set the value of the rowstatus column to 5 (createandwait). This value is changed by the agent as notready(3). After all the column values are set, the rowstatus value is changed by the agent to active(1). AdventNet, Inc. 144

146 For SMIv1 tables The procedure for adding a row for SMIv1 tables is the same as that of SMIv2 tables. However, the EntryStatus column should be set to 2 (createrequest). After the creation of row, this value is set to undercreation(3). The entry remains in this state until the entry is configured and then the status is set to valid(1). If there is a delay in configuring the entry, then the agent sets the status to invalid(4). AdventNet, Inc. 145

147 Deleting a Row To delete a row from an SNMP table, the table should be a SMIv1 table with EntryStatus column defined or a SMIv2 table with RowStatus column defined. For more information on EntryStatus and RowStatus, refer SNMP Table Basics. To retrieve the table data, the SnmpAPI, SnmpSession and the SnmpPDU classes of the snmp2 namespace has to be used. For deleting a row from the table, the RowStatus (for SMIv2 tables) or the EntryStatus (for SMIv1 tables) column should be set to 6 and 4 respectively. For more information on rowstatus and EntryStatus refer the SNMP Table Basics section. From SMIv2 table To delete a row in an SNMP table with index 15, the rowstatus value for that row should be set to 'Destroy(6)'. The following command creates SnmpOID for the columnoid in the sample table where the numeric OIDs for the rowstatus column are SnmpOID oid=new SnmpOID(" "); The following command creates the SnmpVar object with the value and the type of the value. SnmpVar var = SnmpVar.CreateVariable("6",SnmpAPI.INTEGER);//6 refers to destroy. The following code snippet creates SnmpVariableBindings using this SnmpOID and SnmpVar and adds it to the PDU using AddVariableBinding(). SnmpVarBind varbind = new SnmpVarBind(oid,var); pdu.addvariablebinding(varbind); Then perform Session.SyncSend(pdu) to delete the row with index 15 from the table. From SMIv1 table The procedure for deleting a row from the SMIv1 table is the same as the that of SMIv2 table. Note that the entrystatus value should be set to the value of 'Invalid(4)' to delete a row in a SMIv1 table. AdventNet, Inc. 146

148 Error Messages The following are the error messages that you could get while using AdventNet SNMP low-level API. S.No. Error Message When it occurs 1 Cannot bind to address: This is set when UnknownHostException is thrown because of the wrong local Address in SnmpSession or UDPProtocolOptions. This message is displayed when the Open() method of SnmpSession is called after setting the local address using the method LocalAddresses() of SnmpSession or UDPProtocolOptions. 2 Transport provider not configured 3 Error in open : 4 5 No remote IP address specified. Session Remote Host Unknown. This is set when the protocol used is other than IP and the SnmpTransportProvider interface is not implemented and the class name is not specified in the "snmptransport.config" file. This message is displayed if an error occurs in reading that file or creating an instance of the class specified. This error occurs when the open method of SnmpSession is called. This is set when there is problem in the open method after successful instantiation of the class specified in the snmptransport.config" file. This is set when the send or SyncSend method of SnmpSession is called without setting the remote host either on the PDU or on the session. This is set when the send or SyncSend method of SnmpSession is called by setting an invalid remote host. 6 Invalid OID Format: This is set when the OID specified is not correct. 7 Parse Error: unrecognized SNMP message This is set if the SNMP message cannot be parsed. Note: The strings in the "Error Message" column are exact. They may be appended by or prepended by other strings based on the type of exceptions. AdventNet, Inc. 147

149 Using Transport Providers SNMP Transport Providers Custom Transport Provider SNMP protocol standards define UDP to be used as the default protocol for communication. UDP, being a connectionless protocol, is most suitable for exchanging messages with smaller packet sizes. It is appropriate for the network management system that requires to perform quick queries on lot of devices. In case of database retrievals and updates, where the packet sizes are large, TCP might be the preferred protocol. Also developers might want to choose their own protocol for implementation, such as IPX, HTTP, TCP, Serial port communication, and so on. Users requiring more security can also implement SSL below the SNMP for secure communication. To facilitate this, AdventNet SNMP API includes a new transport provider framework, whereby the users can plug-in their own transport protocol. This framework enables the developers to implement the protocol of their choice for SNMP communication. The API implements UDP/IP as the default protocol implementation. We also provide TCP/IP as the reference implementation that uses the transport provider framework. AdventNet, Inc. 148

150 SNMP Transport Provider The SNMP transport provider is responsible for all communication between the SNMP manager and agent. It essentially acts as a bridge between the SNMP API and the actual transport protocol used. The advantage of using this approach is that the SNMP API need not be aware of the underlying protocol used and the user can virtually run SNMP over anything. For using a particular transport protocol, the user has to implement that protocol and plug-in (or register) it with the SNMP transport provider. Multiple protocols, such as TCP, UDP, and Serial communication can be used simultaneously in an application to communicate with various agents having SNMP over different protocols. The corresponding protocol providers are to be implemented by the user. We have provided simple command-line examples that use the TCP/IP protocol over SNMP transport provider to perform basic operations, such as GET, SET, GETNEXT, GETBULK, TRAPS, INFORM, and WALK. Also command-line example has been provided that performs SNMP GET operation with UDP/IP and SNMP GETNEXT operation with TCP/IP protocol. APIs used for plugging-in your protocol implementation These interfaces are part of the adventnet.snmp.snmp2 namespace. 1. SnmpTransportProvider - This interface provides the basic I/O operations. It contains the following API methods. Refer the APIdocs files for exact syntax. open - Opens the transport interface over which the data is sent/received. close - Closes the transport interface after communication is over. read - Receives data from the peer over the transport interface. write - Sends data to the peer over the transport interface. 2. ProtocolOptions - This interface defines some parameters that are to be implemented by the user. It contains the following API methods. Refer the APIdocs files for exact syntax. 3. SnmpTransportPacket - This class contains the details of the ProtocolOptions used by the SNMP API and the details of message sent or received. This contains the following API methods. Refer the APIdocs files for exact syntax. GetProtocolOptions - Returns the transport parameters set on the transport packet for sending/receiving messages. ProtocolOptions - Sets the protocol options on SnmpTransportPacket. GetProtocolData - Gets the SNMP message to be sent or received. ProtocolData - Sets the protocol data on SnmpTransportPacket. You can also implement your own transport provider. Refer Custom Transport Provider for more information AdventNet, Inc. 149

151 Custom Transport Provider How to plug in your protocol implementation in the SNMP transport provider framework 1. Provide implementation of SnmpTransportProvider - This class provides the open, close, read, and write implementation required for TCP/IP communication. This can be used to set up the basic communication between the SNMP entities. Reference Implementation is provided for TCP. 2. Provide implementation of ProtocolOptions - This class provides the necessary parameters needed for the protocol communication, such as the host, port etc. for TCP/IP. 3. Provide a configuration file snmptransport.config that contains the name of the implemented SnmpTransportProvider class. Reference file for TCP is provided in the <conf> directory. Note: In the application, the following points should be taken care of while using the transport provider framework.(for actual implementation details, see examples for SNMP GET, SET, etc. for TCP/IP.) After creating the session object, set the protocol to SnmpSession.TRANSPORT_PROVIDER using setprotocol method. We provide UDP/IP as the default protocol. Create a ProtocolOptions object with the necessary parameters. Set this on the session object using setprotocoloptions method. It is mandatory for all the protocol options to be set first on the SnmpSession object before opening the session. AdventNet, Inc. 150

152 Deployment Instructions The deployed environment should have the following installed: 1. The.NET Framework version 1.1 redistributable package to run applications developed using the.net Framework, which can be downloaded from 2. The Microsoft Visual J#.NET version 1.1 Redistributable Package to run your Visual J#.NET applications on a computer that already has the Microsoft.NET Framework version 1.1 installed. This can be downloaded from 7D674D2C7CA1&displaylang=en The application meant for deployment should have the following in the PATH mscorlib (part of the.net Framework version 1.1 redistributable) AdventNetSnmp.dll <your application libraries> In addition to the above, if the application has some reference to the MIB, the following needs to be in the PATH vjslib (part of the Microsoft Visual J#.NET version 1.1 redistributable) AdventNetMibsAPI.dll AdventNet, Inc. 151

153 Examples Setting Up the Environment SNMP GET SNMP GETNEXT SNMP GETBULK SNMP Walk Send Trap Receive Trap Send Inform Receive Inform MIB Details This section details about the various example applications that are bundled with AdventNet SNMP API and the instructions on setting up the environment to use them. AdventNet, Inc. 152

154 Setting Up the Environment There are multiple example files, such as snmpget, snmpgetnext, etc. available with this package. You can use them to query information from the SNMP agents. All the examples that are used to query an agent have identical syntax. These examples can also be used as tools to perform some simple SNMP management operations on remote agents. Detailed usage instructions on the examples provided in the AdventNet SNMP API package are explained in the subsequent sections. You can use these applications to manage devices and applications easily. Before using the examples, the following needs to be done: 1. Installing the.net Framework version 1.1 Redistributable 2. Installing the Visual J# version 1.1 Redistributable 3. Setting the Path to the Redistributables 4. Copying the necessary dll's to the example directory 5. Compiling the examples Installing the.net Framework version 1.1 Redistributable The.NET Framework version 1.1 redistributable package has to be installed in the system to run applications developed using the.net Framework. The redisributable package can be downoaded from the following URL: Installing the Visual J# version 1.1 Redistributable The Microsoft Visual J#.NET version 1.1 Redistributable Package has to be installed in the system to run your Visual J#.NET applications on a computer that already has the Microsoft.NET Framework version 1.1 installed. This can be downloaded from the following URL: 7D674D2C7CA1&displaylang=en Setting the Path to the Redistributables After installing the redistributables, PATH needs to be set to the.net libraries for compiling the examples. For example, set PATH=C:\WINNT\Microsoft.NET\Framework\v ;%PATH%; Copying the necessary dll's to the example directory The AdventNetMibsAPI.dll and the AdventNetSnmp.dll needs to be copied to the local directory for running the examples. To copy the dll's, execute the init.bat located in <SNMPAPI_HOME>\examples directory. Compiling the examples To compile the example, execute the script compile.bat located in <SNMPAPI_HOME>\examples\snmpapps and <SNMPAPI_HOME>\examples\mibapps directory. compile <filename>, where <filename> refers to the name of the example file. This creates an executable (.exe) in the same location. AdventNet, Inc. 153

155 SNMP GET The snmpget example is used to query SNMP information in a remote host in which the agent runs. The following command can be used to perform an SNMP query. snmpget localhost The above command performs a GET operation on the SNMP agent running on localhost to get the value of the variable 1.1 (sysdescr) and display the results. Depending on whether the localhost has an SNMP agent installed, you get sysdescr or time out message. It takes several seconds for either result. By default, it uses the UDP port 161, SNMP version 1, and the community name public. Other options, such as timeout, retries, setting the debug on, etc. can also be set in the command line. For example we can give the following command for a v2c request in the port (8001) with community name private. snmpget -v v2 -c private -p 8001 localhost Note that the given OID does not start with a dot (.). OIDs not starting with a dot are prefixed by Therefore, the entire OID of becomes We can also give the entire OID for the request. We can also make multiple OID queries in a single request as follows snmpget localhost One of the common errors that are made during the snmpget request is to query the agent without giving the instance value of the object. To specify an object to an SNMP agent, both the Object ID (which defines the type of object) and the instance (the specific object of the given type) need to be provided. For non-tabular or scalar objects, this is simply an instance of 0 (e.g. sysdescr.0). For example, if we make the following request without giving the instance value, snmpget localhost 1.1 we get the following error: Error in response: Error Status: There is no such variable name in this MIB. Error Index: 1 Therefore, we need to make sure that we completely specify the OID plus instance as follows. snmpget localhost The example source file is available in <examples\snmpapps\snmpget.cs> AdventNet, Inc. 154

156 With MIB Support The OID can also be given in the String format instead of the numeric format if we load the corresponding MIB file. For example, snmpget -m..\..\mibs\rfc1213-mib localhost sysdescr.0 snmpget -m..\..\mibs\rfc1213-mib localhost.iso.org.dod.internet.mgmt.mib-2.system.sysdescr.0 The example source file is available in <examples\mibapps\snmpget.cs> AdventNet, Inc. 155

157 SNMP GETNEXT The snmpgetnext example is similar to the snmpget example, except that GETNEXT retrieves the value of the next OID in the tree. For example: snmpgetnext localhost The above command performs a GETNEXT operation with the SNMP agent running on localhost to get the value of the variable 1.2. (sysobject ID) and display the results. Depending on whether the localhost has an SNMP agent installed, you get the next OID sysobjectid or time out message. It takes several seconds for either result. Note that it does not return the value of 1.1 but 1.2, the OID next to 1.1. All the remaining options such as making multiple OID requests, specifying versions, etc., are applicable to this utility also. Refer SNMP GET for details. Also, providing the instance value as part of the OID is not mandatory. The snmpgetnext always returns the next OID in the MIB tree regardless of whether we specify the particular instance of OID. Therefore, the following command is equally valid. snmpgetnext localhost 1.1 The example files are available in <examples\snmpapps\snmpgetnext.cs> and <examples\mibapps\snmpgetnext.cs> AdventNet, Inc. 156

158 SNMP GETBULK The snmpbulk performs an SNMP GETBULK operation on a remote agent. The syntax and the command line arguments are similar to the snmpget and the snmpgetnext with two additional parameters specific to GETBULK operation namely Nonrepeaters and Max-repetitions. The GETBULK operation can be used only for v2c version. For example, the following command works only if the agent version is v2c. snmpbulk localhost The above command performs a GETBULK operation with the SNMP agent running on localhost to get the value of all the variables under the subtree 1.1. and display the results. Depending on whether the localhost has an SNMP agent installed, you get OIDs based on the Max-repetitions value, Nonrepeaters value, and the OID or time out message. All the remaining options such as making multiple OID requests, specifying versions, etc., are applicable to this utility also. Refer SNMP GET for details. The example source file is available in <examples\mibapps\snmpbulk.cs> AdventNet, Inc. 157

159 SNMP Walk The snmpwalk example does a walk on one or more OIDs by performing a series of GETNEXTs and stops inside the range of the OID. For example: snmpwalk localhost 1.1 The above command displays all the results for the system group in the localhost where the agent runs. It stops within the range of system group OID. Depending on whether the localhost has an SNMP agent installed, you get all the OIDs belonging to the "system" tree or time out message. It takes several seconds for either result. All the remaining options such as setting retries values, specifying versions, etc., are applicable to this utility also. Refer SNMP GET for details. The example files are available in <examples\snmpapps\snmpwalk.cs> and <examples\mibapps\snmpwalk.cs> AdventNet, Inc. 158

160 SNMP SET The snmpset example allows the management application or the manager to SET the value of an attribute of a managed object in the agent. To perform the SET operation in a remote host in which the agent resides, we need to specify the OID, the data type and the value to be set. In this example, the datatype is taken from the MIB file. For example: snmpset -m..\..\mibs\rfc1213-mib localhost testing The above command performs a SET operation with the SNMP agent running on localhost to set the value of the variable 1.5. (sysname) to "testing". The above command results in an SNMP SET operation to the localhost on the syscontact OID. Depending on whether the localhost has an SNMP agent installed, you get syscontact or time out message. It takes several seconds for either result. To check the new value, you can perform an snmpget and see the new value being retrieved. To perform the SET operation, loading the MIB file is a must because the type of the object is retrieved from the MIB file. If the MIB file is not available, we must give the type of the OID. We have provided another example for performing the SET operation without loading the MIB file. We need to have write permission to set the value for the managed object. Otherwise, the following error occurs (if the version is v1). Request failed or timed out. Error Indication in response: There is no such variable name in this MIB. Errindex: 1 If the version is v2c, the following error message appears. Request failed or timed out. Error Indication in response: A no creation error occurred. Errindex: 1 The source code of this example is available in <examples\mibapps\snmpset.cs> Without MIB Support API The snmpset_without_mib example allows the management application or the manager to set (write) the value of an attribute of a managed object in the agent. To perform the SET operation in a remote host where the agent resides, we need to specify the OID, the data type, and the value to be set. In the previous example, the datatype is taken from the loaded MIB file. In this example, instead of loading the MIB file, we will specify the data type explicitly. For example: snmpset localhost STRING testing The above command performs a SET operation with the SNMP agent running on localhost to set (write) the value of the variable 1.5. (sysname) to "testing". To check the new value we can do the snmpget and see the new value being retrieved. Unlike the previous example we are not loading the MIB file here, because we are specifying the type of the OID. The source code of this example is available in <examples\snmpapps\snmpset.cs> AdventNet, Inc. 159

161 Send Trap Traps are unsolicited messages sent by the agent to the management stations to report the conditions of the managed node. The sendv2trap example can be used to send v2c traps. SNMP v2c traps are also called as notifications. SNMP v2 notification is different from the v1 traps with much simplification. To send the v2c notification, you need to provide the following values. remotehost - the manager station to which the trap message is sent. timeticks - the time elapsed between the last initialization of the network and the generation of the trap. trapoid - the trap OID. MIB file, OID, and value - values for building the varbinds. Trap messages not containing any varbinds do not need OID and value. The following commands generate a simple v2c notification. snmpv2ctrap -p 8003 localhost STRING test The above command sends a trap to the manager station in the remotehost. A trap receiver program in the manager station can receive and display the traps. By default, the traps are sent to the port 162 of the manager station. The source code of the example is available in 1. examples\snmpapps\snmpv1trap.cs 2. examples\snmpapps\snmpv2ctrap.cs 3. examples\mibapps\snmpv1trap.cs 4. examples\mibapps\snmpv2ctrap.cs AdventNet, Inc. 160

162 Receive Trap Traps are unsolicited messages sent by the agent to the management applications to report the conditions of the managed node. The snmptrapd example can be used to receive the traps sent by the agents. For example: snmptrapd The above command waits for the trap in the port 162, the default port for receiving traps, and prints the received traps. If the port is occupied, the following error occurs: adventnet.snmp.snmp2.snmpexception: Error in open : System.Net.Sockets.SocketException: Only one usage of each socket address (protocol/network address/port)is normally permitted In such cases, you can specify the port in which the trap can be received as follows. snmptrapd -p 8003 Here, the traps are received in the port For example, the following v1 trap: snmpv1trap -d -p 8003 localhost localhost STRING testing gives the following output in the snmptrapd demon. Got a trap from: xx.xx.xx.xx SNMP Trap PDU SNMP Version: Version 1 Remote Host: xx.xx.xx.xx Remote Port: 1430 Community: public Request ID: 0 Timeout: 0 Retries: 0 Enterprise: Trap Type: 0 Specific Type: 6 UpTime: 1000 Error Status: no error SNMP PDU Variable Bindings: Object ID: STRING: testing The output of the snmptrapd is different if we send a v2c trap. snmpv2ctrap -d -p 8003 localhost STRING test AdventNet, Inc. 161

163 Output of the snmptrapd is: Got a trap from: SNMP V2 Trap PDU SNMP Version: Version 2C Remote Host: Remote Port: 1436 Community: public Request ID: 2 Timeout: 0 Retries: 0 Error Status: no error SNMP PDU Variable Bindings: Object ID: TIMETICKS: 0 hours, 0 minutes, 50 seconds. Object ID: OBJID: Object ID: STRING: test The example files are available in 1. examples\snmpapps\snmptrapd 2. examples\mibapps\snmptrapd AdventNet, Inc. 162

164 Send Inform The snmpv2cinformreq example can be used to send v2c inform requests. The inform requests can be sent from a manager to another manager. A trap receiver program in the manager station can receive and display inform messages. By default, the inform requests are sent to the port 162 of the manager station. Refer to the source code of the example at the following location <examples\snmpapps\snmpv2cinformreq.cs> AdventNet, Inc. 163

165 Receive Inform The snmpv2cinformreqd example can be used to receive v2c inform requests. The inform requests can be sent from a manager to another manager. A trap receiver program in the manager station can receive and display inform messages. By default, the inform requests are sent to the port 162 of the manager station Refer to the source code of the example at <examples\snmpapps\snmpv2cinformreqd.cs> AdventNet, Inc. 164

166 MIB Details This sample application illustrates how to get the mibnode and the MibTable details of the OID specified by you. To get the details of a specific node, use the following command mibnodeinfo -s -n -l -D -P -m..\..\mibs\rfc1213-mib To get the details of the Mib Table, the following command is used. getmibtableinfo -m..\..\mibs\rfc1213-mib The example source code is available at 1. examples\mibapps\mibnodeinfo.cs 2. examples\mibapps\getmibtableinfo.cs AdventNet, Inc. 165

167 Tutorials SNMP GET SNMP GETNEXT SNMP GETBULK SNMP SET Send Trap Receive Trap MIB Node Information This section details about the various tutorials that are bundled with AdventNet SNMP API namespace and the instructions on setting up the environment to use them. The tutorials present in this section helps you get familiar with development using of AdventNet SNMP API. Example programs are available that can be compiled and run. Follow the links to learn more. AdventNet, Inc. 166

168 Tutorials: SNMP GET We will explain the steps involved in developing a simple application using the AdventNet SNMP API (adventnet.snmp.snmp2 namespace). We will make a GET request for a single variable in a host in which the agent runs. The adventnet.snmp.snmp2 namespace implements the core functions of the protocol. We need to import the adventnet.snmp.snmp2 namespace in addition to the.net packages as follows. using System; using adventnet.snmp.snmp2; We will define the class and the static main function required for the applications. public class snmpget { public static void Main(System.String[] args) { We will get the host name and the OID from the command line // getting the hostname and the OID from the command line System.String remotehost = args[0]; System.String OID = args[1]; To use the adventnet.snmp.snmp2 namespace, we need to instantiate and start the SnmpAPI class. The SnmpAPI class is a thread which monitors SNMP sessions and contains various SNMP parameters. We will enable the debug option by setting Debug() to true. In the debug mode, the PDU data is printed in hex format. SnmpAPI api = new SnmpAPI(); api.debug(true); To communicate with SNMP entities, we need to instantiate the SnmpSession class. The Open() method has to be invoked to get a socket for SNMP communication. Various parameters, such as remote host, remote port, version, community, retries, timeouts, etc. can be set using this class. SnmpSession session = new SnmpSession(api); session.open(); For our example, we use the ProtocolOptions() of the SnmpPDU class to set the host to which we make request. Use Command() 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(); //get the value from the command line UDPProtocolOptions option = new UDPProtocolOptions(remoteHost); pdu.protocoloptions=option; pdu.command=snmpapi.get_req_msg; We will set the OID for which we have to query by instantiating the SnmpOID class. SnmpOID is the subclass of the SnmpVar class, which provides abstract methods to present a uniform interface for applications working with the SNMP variables. The AddNull method in the SnmpPDU class adds a variable binding with the OID specified and a null variable value. // add OIDs for (int i = 1; i < args.length; i++) { SnmpOID oid = new SnmpOID(args[i]); 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. We use the PrintVarBinds() method to print the descriptive value of the OID and the variables. SnmpPDU result=null; // Send PDU and receive response PDU AdventNet, Inc. 167

169 try { result= session.syncsend(pdu); } catch (SnmpException e) { System.Console.Error.WriteLine("Error sending SNMP request: " + e); } // print the response pdu varbinds System.Console.Out.WriteLine(result.PrintVarBinds()); Finally, we close the session and the API thread. // close session session.close(); //close the api thread api.close(); Now, we can compile the program, snmpget, and view the result. AdventNet, Inc. 168

170 Tutorials: SNMP GETNEXT We will explain the steps involved in developing a simple application for performing the SNMP GETNEXT operation. This is similar to the SNMP GET tutorial. The SNMP GETNEXT operation retrieves one or more values from the managed agent's MIB for the next object in the tree of objects on the managed device. The mandatory values we need to provide are the host name in which the agent resides and the OID that needs to be queried. We need to import the adventnet.snmp.snmp2 namespace in addition to the.net packages as follows. using System; using adventnet.snmp.snmp2; We will define the class and the static main function required for the applications. public class snmpgetnext { public static void Main(System.String[] args) { The following code snippet gets the hostname and the OID as command line inputs. if (args.length < 2) { System.Console.Out.WriteLine("Usage: snmpgetnext hostname OID"); System.Environment.Exit(0); } // getting the hostname and the OID from the command line System.String remotehost = args[0]; System.String OID = args[1]; To use the adventnet.snmp.snmp2 namespace, we need to instantiate and start the SnmpAPI class. The SnmpAPI class is a thread which monitors SNMP sessions and contains various SNMP parameters. We will enable the debug option by setting Debug() to true. In the debug mode, the PDU data is printed in hex format. SnmpAPI api = new SnmpAPI(); api.debug(true); To communicate with SNMP entities, we need to instantiate the SnmpSession class. The Open() method has to be invoked to get a socket for SNMP communication. Various parameters, such as remote host, remote port, version, community, retries, timeouts, etc. can be set using this class. SnmpSession session = new SnmpSession(api); session.open(); For our example, we use the ProtocolOptions() of the SnmpPDU class to set the host to which we make request. Use Command() to send an SNMP request. The command constants are defined in the SnmpAPI class. The following command sets the constant to GETNEXT_REQ_MSG to perform an SNMP GETNEXT operation. //Build GETNEXT Request PDU SnmpPDU pdu = new SnmpPDU(); //get the value from the command line UDPProtocolOptions option = new UDPProtocolOptions(remoteHost); pdu.protocoloptions=option; pdu.command=snmpapi.getnext_req_msg; We will set the OID for which we have to query by instantiating the SnmpOID class. SnmpOID is the subclass of the SnmpVar class, which provides abstract methods to present a uniform interface for applications working with the SNMP variables. The AddNull method in the SnmpPDU class adds a variable binding with the OID specified and a null variable value. // add OIDs for (int i = 1; i < args.length; i++) AdventNet, Inc. 169

171 { SnmpOID oid = new SnmpOID(args[i]); 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. We use the PrintVarBinds() method to print the descriptive value of the OID and the variables. SnmpPDU result=null; // Send PDU and receive response PDU try { result= session.syncsend(pdu); } catch (SnmpException e) { System.Console.Error.WriteLine("Error sending SNMP request: " + e); } // print the response pdu varbinds System.Console.Out.WriteLine(result.PrintVarBinds()); Finally, we close the session and the API thread. // close session session.close(); //close the api thread api.close(); Now, we can compile the program, snmpgetnext, and view the result. We can modify this example further to receive the MIB file also as a command line input. In this case, we need to import adventnet.snmp.mibs namespace in addition to the adventnet.snmp.snmp2 namespace. After invoking the open() method of the SnmpSession class, we need to load the MIB file. The MIB files are loaded using the MibOperations class. This class provides method to load multiple MIBs. All modules loaded through a particular MibOperations instance are registered only with that particular MibOperations object and do not interfere with other MibOperations instances. Under normal circumstances, it is sufficient to have one MibOperations instance. The methods available in the mibs namespace allow to query the MIB data to retrieve numeric or named OID, look-up range validations, and extract outputs in readable formats. MibOperations mibops = new MibOperations(); try { mibops.loadmibmodules(mibfile); } catch (Exception ex) { System.Console.Error.WriteLine("Error loading MIBs: " + ex); } Then, invoke the command() of the SnmpPDU class to send an SNMP request. The rest of the code remain the same. AdventNet, Inc. 170

172 Tutorials: SNMP GETBULK We will explain the steps involved in developing a simple application for performing the SNMP GETBULK operation. The SNMP GETBULK operation performs a continuous GETNEXT operation based on the Max- Repetitions value. The Nonrepeaters value determines the number of variables in the variable list for which a simple GETNEXT operation has to be done. For the remaining variables, the continuous GETNEXT operation is done based on the Max-Repetitions value. We need to import the adventnet.snmp.snmp2 namespace in addition to the.net packages as follows. using System; using adventnet.snmp.snmp2; We will define the class and the static main function required for the applications. public class SnmpGetBulk { public static void Main(System.String[] args) { The following code snippet gets the hostname as command line input. if (args.length!= 1) { System.Console.WriteLine("Usage SnmpBulk hostname"); System.Environment.Exit(0); } // getting the hostname from the command line System.String remotehost = args[0]; To use the adventnet.snmp.snmp2 namespace, we need to instantiate and start the SnmpAPI class. The SnmpAPI class is a thread which monitors SNMP sessions and contains various SNMP parameters. SnmpAPI api = new SnmpAPI(); To communicate with SNMP entities, we need to instantiate the SnmpSession class. The Open() method has to be invoked to get a socket for SNMP communication. Various parameters, such as remote host, remote port, version, community, retries, timeouts, etc. can be set using this class. SnmpSession session = new SnmpSession(api); session.open(); For our example, we use the ProtocolOptions() of the SnmpPDU class to set the host to which we make request. Use Command() to send an SNMP request. The command constants are defined in the SnmpAPI class. The following command sets the constant to GETNEXT_REQ_MSG to perform an SNMP GETNEXT operation. //Build GETNEXT Request PDU SnmpPDU pdu = new SnmpPDU(); //get the value from the command line UDPProtocolOptions option = new UDPProtocolOptions(remoteHost); pdu.protocoloptions=option; pdu.command=snmpapi.getbulk_req_msg; pdu.maxrepetitions=10; pdu.nonrepeaters=0; We will set the OID for which we have to query by instantiating the SnmpOID class. SnmpOID is the subclass of the SnmpVar class, which provides abstract methods to present a uniform interface for applications working with the SNMP variables. The AddNull method in the SnmpPDU class adds a variable binding with the OID specified and a null variable value. AdventNet, Inc. 171

173 // Provide the OID SnmpOID oid = new SnmpOID("1.3.1"); 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. We use the PrintVarBinds() method to print the descriptive value of the OID and the variables. // Send PDU and receive response PDU SnmpPDU result = session.syncsend(pdu); if (result == null) { System.Console.Out.WriteLine("Request timed out!"); } else { if (result.errstat == 0) { // print the response pdu varbinds System.Console.Out.WriteLine(result.PrintVarBinds()); } else { System.Console.Out.WriteLine(result.Error); } } Finally, we close the session and the API thread. // close session session.close(); //close the api thread api.close(); Now, we can compile the program, snmpgetbulk, and view the result AdventNet, Inc. 172

174 Tutorials: SNMP SET We will explain the steps involved in developing a simple application for performing the SNMP SET operation. The SET operation allows the management application or the manager to set the value of an attribute of a managed object in the agent. To perform the SET operation, we need to provide the host name in which the agent resides, OID, the type, and the value for the managed object. We get the host name, OID, type, and value as command line inputs. if (args.length < 4) { System.Console.Out.WriteLine("Usage: SnmpSet hostname OID type value"); System.Environment.Exit(0); } // get the hostname, OID, type and value System.String remotehost = args[0]; System.String OID = args[1]; System.String type = args[2]; System.String value_renamed = args[3]; We need to instantiate and start the SnmpAPI and open SnmpSession. Then, we instantiate SnmpPDU and use Command() to send an SNMP SET request. The command constants are defined in the SnmpAPI class. SnmpPDU pdu = new SnmpPDU(); pdu.command=snmpapi.set_req_msg; To perform the SET operation, we need to build the variable binding or the varbinds. The variable binding or the varbind is the pairing of the OID and its corresponding value. Therefore, we need to know the OID, the type of the OID, and its value to build the varbind. Instantiate the SnmpOID class and the get the OID from the command line. // add OID SnmpOID oid = new SnmpOID(OID); The type of the variable can be INTEGER, STRING, COUNTER, etc. The SnmpAPI class provides constants for all the SNMP data types. Therefore, we check the validity of the data type. In this example, we check only for the type STRING. The code should include all the known SNMP data types. // get the type sbyte datatype; if (type.equals("string")) { datatype = SnmpAPI.STRING; } else { System.Console.Error.WriteLine("Invalid variable type: " + type); return ; } The CreateVariable() method available in the SnmpVar class provides a means of creating any SNMP variable object with a given value. This method takes the type of SNMP data and the value and returns an SnmpVar object. The type argument can take any value as defined in the SnmpAPI class. AdventNet, Inc. 173

175 SnmpVar var = null; try { var = SnmpVar.CreateVariable(value_Renamed, datatype); } catch (SnmpException e) { System.Console.Error.WriteLine("Cannot create variable: " + oid + " with value: " + value_renamed); return; } A varbind is a combination of an OID and an SNMP variable The SnmpVarBind class is used for variables and methods needed for variable bindings. SnmpVarBind contains SnmpOID and SnmpVar, where the SnmpOID is the OID and the SnmpVar, the value. SnmpVarBind varbind = new SnmpVarBind(oid, var); Now, we need to add this varbind to the PDU. The SnmpPDU class provides methods to work with the variable bindings. // add variable binding pdu.addvariablebinding(varbind); We use the synchronous method SyncSend(pdu) to send the PDU. We use PrintVarBinds() to print the descriptive value of the OID and the variables result = session.syncsend(pdu); System.Console.Out.WriteLine("Response PDU received from " + result.address+ ", community: " + result.community); System.Console.Out.WriteLine(result.PrintVarBinds()); Finally, we close the session and the API thread. session.close(); api.close(); Now we can compile and run the program and view the result. We can modify this example further to receive the MIB file also as a command line input. In this case, we need to import adventnet.snmp.mibs namespace in addition to the adventnet.snmp.snmp2 namespace. After invoking the Open() method of the SnmpSession class, we need to load the MIB file. The MIB files are loaded using the MibOperations class. This class provides method to load multiple MIBs. All modules loaded through a particular MibOperations instance are registered with only that particular MibOperations object and do not interfere with other MibOperations instances. Under normal circumstances, it is sufficient to have one MibOperations instance. The methods available in the mibs package allows to query the MIB data to retrieve numeric or named OID, look-up range validations, and extract outputs in readable formats. MibOperations mibops = new MibOperations(); try { mibops.loadmibmodules(mibfile); } AdventNet, Inc. 174

176 catch (Exception ex) { System.Console.Error.WriteLine("Error loading MIBs: "+ex); } Then, invoke the Command() of the SnmpPDU class to send an SNMP SET request. The rest of the code remain the same. AdventNet, Inc. 175

177 Tutorials: Send Trap We will explain the steps involved in developing a simple application to send an SNMPv1 trap message. Trap messages are unsolicited message sent by the agent to the management stations to report the conditions of the managed node. To send the v1 trap message, we need to provide the following values. remotehost - the manager station to which the trap message is sent. enterprise - the enterprise OID (sysobjectid for generic traps). agent-addr - the agent address from which the trap is generated. generic trap - the code for generic trap type. specific-trap - the code for specific trap type. timeticks - the time elapsed between the last initialization of the network and the generation of the trap. OID, type, and value - values for building the varbinds. All the above values can be received as command line inputs. if (args.length < 8) { System.Console.Out.WriteLine("Usage : SnmpSendTrap hostname enterprise agent-addr generic-trap specific-trap timeticks OID type value"); System.Environment.Exit(0); } System.String remotehost = args[0]; System.String enterprise = args[1]; System.String agentaddr = args[2]; System.String generictrap = args[3]; System.String specifictrap = args[4]; System.String timeticks = args[5]; System.String OID = args[6]; System.String type = args[7]; System.String value_renamed = args[8]; We need to instantiate and start SnmpAPI and open SnmpSession. By convention, the traps are received at the port 162. In this example, we set the port to // Start SNMP API SnmpAPI api; api = new SnmpAPI(); api.start(); api.debug=true; // Open session SnmpSession session = new SnmpSession(api); // set remote Host session.peername=remotehost; // set remote port session.remoteport=8001; Instantiate SnmpPDU and use Command() to send an SNMP TRAP request. The command constants are defined in the SnmpAPI class. // Build SNMPv1 Trap PDU SnmpPDU pdu = new SnmpPDU(); pdu.command=adventnet.snmp.snmp2.snmpapi.trp_req_msg; We fill in all the v1 trap PDU fields that are received from the command line. AdventNet, Inc. 176

178 // fill in v1 trap PDU fields SnmpOID oids = new SnmpOID(enterprise); try { pdu.enterprise=oids; pdu.agentaddress=system.net.dns.resolve(agentaddr).addresslist[0]; pdu.traptype=system.int32.parse(generictrap); pdu.specifictype=system.int32.parse(specifictrap); pdu.uptime=system.int32.parse(timeticks); } catch (System.Exception ex) { System.Console.Error.WriteLine("error in one or more required fields: " + ex); } Now, we build the variable bindings with the given OID, type, and value. In this example, we check only for the type STRING. The code should include all the known SNMP data types. // add OID SnmpOID oid = new SnmpOID(OID); // get the type sbyte datatype; if (type.equals("string")) { datatype = SnmpAPI.STRING; } else { System.Console.Error.WriteLine("Invalid variable type: " + type); return ; } // create SnmpVar instance for the value and the type SnmpVar var = null; try { var = SnmpVar.CreateVariable(value_Renamed, datatype); } catch (SnmpException e) { System.Console.Error.WriteLine("Cannot create variable: " + oid + " with value: " + value_renamed); return ; } //create varbind SnmpVarBind varbind = new SnmpVarBind(oid, var); // add variable binding pdu.addvariablebinding(varbind); We use the asynchronous method Send(pdu) to send the PDU. // send PDU try { session.send(pdu); } catch (SnmpException e) { AdventNet, Inc. 177

179 System.Console.Error.WriteLine("Sending PDU" + e.message); } Finally, we exit the program. System.Environment.Exit(0); Now, we can compile and run the program and view the result. We have also provided another example in which all the trap fields are given. You need to give only the remote host name as the input for running the application. AdventNet, Inc. 178

180 Tutorials: Receive Trap We will explain the steps involved in developing a simple application to receive the trap messages sent by agent. Traps are unsolicited message sent by the agent to the management stations to report the conditions of the managed node. The interface SnmpClient is used by applications to send and receive messages asynchronously. The SnmpClient interface implements callback, authentication, and debugging functions. We implement SnmpClient in our main class. public class SnmpTrapd : SnmpClient { We need to instantiate and start the SnmpAPI and open SnmpSession. We need to add the SnmpClient interface implementation to the session to invoke the callback, authentication, and debugging functions. // Open session SnmpSession session = new SnmpSession(api); session.addsnmpclient(new SnmpTrapd()); By convention, the traps are received at the port 162. In this example, we set the local port to 8001 for receiving the traps. // set local port SnmpPDU pdu = new SnmpPDU(); UDPProtocolOptions option = new UDPProtocolOptions(); option.localport=8001; session.protocoloptions=option; // Open the session try { session.open(); } catch (SnmpException e) { System.Console.Error.WriteLine("Error opening socket: " + e); } System.Console.Out.WriteLine("Waiting to receive traps " + "..."); Now, we have to implement three methods of the SnmpClient interface. The Authenticate() method should check the community received in the response PDU with the community of the particular session. The "community" argument in the Authenticate() method is same as the session.community and the "pdu" argument is the received PDU. public virtual bool Authenticate(SnmpPDU pdu, System.String community) { System.Console.Out.WriteLine("Inside the authenticate"); return (pdu.community.equals(community)); } AdventNet, Inc. 179

181 The Callback() method should handle the PDU received for a particular session. The "session" argument is the session for which the PDU is received. The "pdu" argument is the PDU received. The "requestid" is the request ID of the sent PDU for which the response is received. The received trap information is handled here. public virtual bool Callback(SnmpSession session, SnmpPDU pdu, int requestid) { // print the received trap information System.Console.Out.WriteLine("Inside the call back"); System.Console.Out.WriteLine("Trap received from: " + pdu.address + ", community: " + pdu.community); System.Console.Out.WriteLine("Enterprise: " + pdu.enterprise); System.Console.Out.WriteLine("Agent: " + pdu.agentaddress); System.Console.Out.WriteLine("TRAP_TYPE: " + pdu.traptype); System.Console.Out.WriteLine("SPECIFIC NUMBER: " + pdu.specifictype); System.Console.Out.WriteLine("Time: " + pdu.uptime + "\nvarbinds:"); System.Console.Out.WriteLine(pdu.printVarBinds()); return true; } The debugprint is used for printing any debug information. public virtual void DebugPrint(System.String debugoutput) { System.Console.Out.WriteLine("Inside the debug"); System.Console.Out.WriteLine(debugOutput); return ; } Now we can compile and run the program and view the result. The application waits for traps. If any trap message is received at the port 8001, the application prints the trap information. We can modify this example further to receive the MIB file as a command line input. AdventNet, Inc. 180

182 MIB Node Information We will explain the steps involved in developing simple application that can be used to retrieve the node information from the MIB files. The MibNode and the LeafSyntax class provide the methods necessary to access information available about the nodes in the MIB file. In this example, we also explain the usage of the MibNode class in retrieving the node information. Import the com.adventnet.snmp.snmp2 namespace and the adventnet.snmp.mibs namespace using System; using adventnet.snmp.snmp2; using adventnet.snmp.mibs; Define the required class and the static main function. public class MibNodeInfo { public static void Main(System.String[] args) { Get the OID and the MIB file as the command line inputs. if (args.length < 2) { System.out.println("Usage : MibNodeInfo mibfile OID "); System.Environment.Exit(0); } System.String mibfile = args[0]; System.String OID = args[1]; Load the MIB file. The MIB files are loaded using the MibOperations class. This class provides method to load multiple MIBs. All modules loaded through a particular MibOperations instance are registered only with that particular MibOperations object and do not interfere with other MibOperations instances. Under normal circumstances, it is sufficient to have one MibOperations instance. MibOperations mibops = new MibOperations(); try { mibops.loadmibmodules(mibfile); } catch (System.Exception ex) { System.err.println("Error loading MIBs: " + ex); } Instantiate the SnmpOID class to get the OID for which we need the information by using GetSnmpOID() of the MibOperations class. SnmpOID oid = mibops.getsnmpoid(oid); Instantiate the MibNode class and use GetMibNode() in the MibOperations class to get the MibNode. MibNode node = mibops.getmibnode(oid); MibNode, say for the OID sysdescr in RFC1213-MIB, can also be got directly as follows. MibNode node = mibops.getmibnode("sysdescr"); For this, the MIB file has to be loaded first in the MibOperations class. The GetMibNode() is available both in MibOperations and MibModule class. If the methods in MibOperations are used, they are applicable for the node in all the MIBs loaded in the application. If the methods in the MibModule class are used, they are restricted to that particular module. Therefore, for better performance, it is recommended to use mibmodule.getmibnode(). The MibNode class has methods to get all the details about a MIB variable. We can get information about the selected MibNode, such as its syntax, OID, description, etc. System.Console.Out.WriteLine("Syntax:" + node.getsyntax() + "\n" + AdventNet, Inc. 181

183 "Access:" + node.printaccess() + "\n" + "Status:" + node.getstatus()+ "\n" + "Reference:" + node.getreference() + "\n" + "OID:" + node.getnumberedoidstring() + "\n" + "Node:" + node.getoidstring() + "\n" + "Description:" + node.getdescription() + "\n"); We can also use the method totagstring() to get the node information. Now, we can compile the program and view the result. Ensure that you provide the correct MIB file name and the proper OID in the command line. You can build similar applications effortlessly. AdventNet, Inc. 182

184 Performance Metrics The tests were performed on: Operating System - Windows 2000 RAM: 512 MB Processor: P4, 1.6 GHz.NET Framework Version: 1.1 Host for SNMP Request: localhost OID Queried: Number of requests sent: Performance Numbers for Modules Type v1 v2c (Requests/second) (Requests/second) Synchronous Asynchronous Note: All requests are SNMP GET requests. Performance Numbers for Traps AdventNet's Trap Receiver can receive approximately 1800 traps/sec if there are no processing for traps received. If the incoming trap rate is greater than 1800, the TrapReceiver may start losing traps. All the traps were received by the TrapReceiver without any loss. All traps were SNMPv1 traps. AdventNet, Inc. 183

185 FAQs Beginners FAQs General FAQs Advanced FAQs This section contains FAQs related to various packages of the API. AdventNet, Inc. 184

186 Beginners FAQs 1. What is AdventNet SNMP API? 2. What can I do with this product? 3. How do I start using this package? 4. What do I need to start developing applications using the AdventNet SNMP package? 5. How do I run the various example applications provided? 6. I am able to execute the example applications but I am not getting results. What should I do? 7. What is the difference between SNMPv1, SNMPv2c, and SNMPv3? 8. Which versions of SNMP are supported by AdventNet SNMP API? 9. What are the best sources of information on SNMP? 1. What is AdventNet SNMP API? AdventNet SNMP API is a set of class libraries in.net Framework for writing the network management applications. 2. What can I do with this product? This package can be used to develop SNMP management applications to manage SNMPv1 and SNMPv2c agents and talk to agent systems using any of the two versions at the same time. 3. How do I start using this package? AdventNet SNMP API distribution consists of the SNMP API - a set of class libraries in.net to build SNMP management applications. The product distribution also includes various example applications. It provides a hierarchy of.net packages for SNMP and MIBs, which helps in developing various applications. 4. What do I need to start developing applications using the AdventNet SNMP package? You need the.net Framework version 1.1 and Visual J# version 1.1 redistributables to develop applications using this AdventNet SNMP package. In addition, you need to download and setup the AdventNet SNMP package classes. 5. How do I run the various example applications provided? The product distribution includes various example applications in the example directory. Examples include applications, such as snmpget, and snmpgetnext. You can use them to query information from the SNMP agents on your network. All the applications that are used to query an agent have identical syntax. In general, all the command line tools gives help information when you type the following. command-name For example, to get help information on the command snmpgetnext, type: snmpgetnext To execute the application, you have to set the PATH to.net Framework redistributables and the necessary dll's needs to be copied to the example directory. For compiling the example applications, you can use the utility compile.bat located under the examples\ snmpapps and examples\mibapps directory. For example, compile snmpgetnext.cs will create snmpgetnext.exe. AdventNet, Inc. 185

187 6. I am able to execute the example applications but I am not getting results. What should I do? If you get a timeout error after executing the application, the remote host given by you might not have an SNMP agent running on it. The agent should be running on the system on which you are querying. Therefore, install an SNMP agent in the machine or try on some other host which has the SNMP agent. Your network administrator might know more about this. In general, routers, ethernet switches, and network printers have the SNMP agent. You can try querying these devices. 7. What is the difference between SNMPv1, SNMPv2c, and SNMPv3? SNMPv1 is the original protocol and framework which is described in RFCs 1155 and SNMPv2c is the revised protocol which includes improvements to SNMPv1 in the areas of protocol packet types, transport mappings, and MIB structure elements. However, it uses the existing SNMPv1 administration structure ("community-based" and hence SNMPv2c). SNMPv3 defines the secure version of the SNMP. SNMPv3 also facilitates remote configuration of the SNMP entities which makes remote administration of SNMP entities a much simpler task. 8. Which versions of SNMP are supported by AdventNet SNMP API? The AdventNet SNMP API distribution supports v1 and v2c versions of SNMP. The communication and MIB portions of the AdventNet SNMP API conform to the following Internet RFC specifications. SNMPv1 - RFC 1155 and RFC 1157 SNMPv2c - RFC 3416 Coexistence between SNMPv1, SNMPv2c, SNMPv3 - RFC 3584 Notification Filtering and Proxy Forwarding - RFC What are the best sources of information on SNMP? We would recommend you to take a look at the following site for more information. SNMP FAQ AdventNet, Inc. 186

188 FAQs - General 1. I am able to perform an SNMP GET successfully but I get an error if I perform an SNMP SET. Why? 2. What would be the maximum packet size supported by AdventNet SNMP stack and how do I find this number? 3. How many SnmpSession instances can I open in a single SnmpAPI? 4. What are the PDU timeout units? 5. Do the sizes of a datagram vary, or are they of constant size? 6. What are the advantages of sending individual GETs compared to sending GETs with multiple OIDs? 7. If multiple requests are sent to the same destination [agent] through multiple threads concurrently, does the SNMP stack serialize hem? Or does it treat them as separate requests and assign a port per request? 8. Is there a way by which I can ensure that the SNMP commands come only through AdventNet and not through a source that uses y 161 port? Can I disable SNMP to everyone but AdventNet? 9. Suppose a response comes back in 4.9 seconds on an SNMP timeout of 5 seconds. However, the CPU being very busy causes a delay of 0.2 seconds before picking up the response from the incoming buffer. In this case, would the response be used or would a timeout situation occur? 10. I get "out of environment space" error when I try to start the example application batch files. What should I do? 1. I am able to perform an SNMP GET successfully but I get an error if I perform an SNMP SET. Why? Load the corresponding MIB file to perform the SNMP SET operation. This solves the problem. Loading the MIB is a must because the type of the object is retrieved from the MIB file. To perform a SET operation, we need the OID, type, and value. If you load the corresponding MIB file, the API finds the type of the OID from the MIB. If the MIB file is not available, we need to either load the MIB file or explicitly give the type of the object. Go through the examples given in examples/mibapps directory. For snmpset and trap examples, loading the MIB is a must. Loading MIB files is normally done by using the -m option. The following is a sample usage of the SNMP SET command. snmpset -m "..\mibs\rfc1213-mib" syslocation.0 paradise sysname.0 whatever If you develop an application for performing SNMP SET, loading MIB files can be done by using loadmibs() of the MibOperation class in the mibs package. 2. What would be the maximum packet size supported by AdventNet SNMP stack and how do I find this number? The maximum packet size supported is 64KB. The methods GetPacketBufferSize() and GetPacketBufferSize() of SnmpSession is used to get and set the packet size of the response PDU. However, this also depends on the maximum size the agent can handle. AdventNet, Inc. 187

189 If the size exceeds the limit, the agent sends the manager a GetResponse-PDU with the value of error-status field "too big". In this case, you need to split the PDU into multiple requests and send them. 3. How many SnmpSession instances can I open in a single SnmpAPI? Each instance of SnmpSession takes resources. It is better to share the same session instance because apart from additional threads, each session also uses socket resources. 4. What are the PDU timeout units? The PDU timeout values in SnmpPDU class and the SnmpSession are specified in milliseconds. 5. Do the sizes of a datagram vary, or are they of constant size? The datagram size is not a constant. It varies and the size depends on the number of the varbinds. The default underlying protocol used by AdventNet SNMP API is User Datagram Protocol (UDP). The maximum message size of a UDP packet is 64 KB. Therefore, the API could not receive packets of length greater than this value. 6. What are the advantages of sending GETs with multiple OIDs over GETs with individual OIDs? To minimize overhead and maximize throughout you should always send as many GETs in a PDU as you can (within the limits of the maximum UDP frame size of your network). The more UDP frames you send, the higher the chance for collision and the longer it takes to get the information. The real overhead is in the reception and transmission of the frame and not in the assembly and disassembly of a PDU with multiple requests. 7. If multiple requests are sent to the same destination [agent] through multiple threads concurrently, does the SNMP stack serialize them? Or does it treat them as separate requests and assign a port per request? The SNMP stack does not serialize the requests. Ultimately, the UDPClient takes care of this. The UDPClient is opened once per session and it binds to the available port on the local machine. Concurrent requests are sent through this port. The responses can come in any order and they are matched to the request based on the request ID. Also, the UDPClient.receive() method is synchronized. Therefore, all the requests are sent concurrently and the responses are processed one by one inside synchronized methods in the order in which they are received. 8. Is there a way by which I can ensure that the SNMP commands come only through AdventNet and not through a source that uses my 161 port? Can I disable SNMP to everyone but AdventNet? There is no way to ensure that the SNMP commands come from a particular SNMP entity. SNMP standards do not define any method/procedure for this. The only way is to authenticate the community string, where SNMP messages from an SNMP entity can be sent with a particular community. 9. Suppose a response comes back in 4.9 seconds on an SNMP timeout of 5 seconds. However, the CPU being very busy causes a delay of 0.2 seconds before picking up the response from the incoming buffer. In this case, would the response be used or would a timeout situation occur? In this case, a timeout situation occurs. AdventNet, Inc. 188

190 10. I get "out of environment space" error when I try to start the example application batch files in Windows. What should I do? This has been a problem with the Windows environment variable settings. To overcome this, you have to modify the properties of your DOS prompt. You need to right-click of the titlebar of the DOS prompt window and select Properties. Choose memory tab in the Properties dialog box and increase the value of the initial environment field (preferably 4096). It can also be solved by adding the following entry in config.sys file. SHELL=C:\Windows\COMMAND.COM/P/E:4096 AdventNet, Inc. 189

191 Advanced FAQs 1. Can SnmpSession automatically detect the version of the SNMP agent on the other end? 2. I use the API to perform an SNMP GET. I want to get only the String and not the message. Also, I want the string in sbyte format instead of hex format. What should I do? 3. I use SnmpString, defined in the Snmp2 namespace, for both String and Octet String. While decoding a response, how do we differentiate between the two? There does not seem to be a method/field in the SnmpString attribute. 4. I would like to use your API in a multithreaded application to collect some data. Is AdventNet SNMP API multithread safe? 5. What is an OCTET in terms of bits? I am trying to determine a bandwidth utilization factor and I need to figure out how to represent an OCTET or a packet in bits. 6. I instantiate the SnmpAPI and SnmpSession classes and various parameters, such as remotehost, community, etc. for the session object is set. When I call Session.Open(), everything works fine but the process started by the other Web-based application does not terminate. Is this because of the SNMPSession or API objects? Do I need to call Close() or Stop()? 7. How should I specify the SET value for two objects with the SYNTAX BITS and OCTET STRING object when I want to use an OCTET STRING of length 1? 8. Can I perform a multiple OID query? If yes, how many OIDs can I query with a single SNMP GET? 9. It is understood that SnmpOID only accepts dot-formatted OID strings. I would like to request SNMP values using names and dot-formatted strings. Is there a class available that can help me maintain a database of variable OIDs and names? 10. In view of the SnmpAdventNet GetNext() facility, is there a way to detect the end of the GET rather than iterating till the end of the MIB. For example: if we do a GETNEXT on we get which is correct. But if we do getnext() we get Is there a way to make this return an error instead, since we are really going to the "next item"? 11. When I receive a PDU from the SNMP agent, how can I differentiate between a normal String and HEX-answer? 12. I would like to set the OID of type EntryStatus but I cannot find this type in the SnmpAPI class. What should I do? What is the sbyte value for this type? 13. How do I set UDP port explicitly for sending GET/SET/GETNEXT request? 14. When I ask for 10 rows in an SNMP table, the GETBULK returns only 6 rows and the last attribute of the sixth row is null. The sixth row seem to be truncated. Why is this so? 15. I want to use your SNMP API to build a PDU packet. Is there a way to encode the PDU packet without sending it? I do not use UDP/IP to send packets. I use my own transport mechanism. As of now, the encoding of the PDU packet is done only when I actually send it out. Do you have a separate encoding function? 16. The problem is that the callback method is not invoked and deadlock occurs in the application while performing the SET operation. The table row is created in host and the OID and values are as follows :octet_string : :INTEGER : 4 (createandgo) :octet_string:ssssssssssssssssss 17. If I have more than one SnmpClient in SnmpSession, the callback method of all the SnmpClients is called whenever the session receives a response. How can I tell the SnmpSession that only one of the clients should receive the response for a particular request? AdventNet, Inc. 190

192 1. Can SnmpSession automatically detect the version of the SNMP agent on the other end? The SnmpSession is used to send/receive PDUs from any SNMP peer. Therefore, while sending requests, the session simply sends the PDU to the remote host with the PDU version set to the SnmpPDU version. If the SnmpPDU version is not specified, the SnmpSession version is used. The default version is v1. In this case, you can initially send a v1 PDU by setting the SnmpPDU version to v1. Then you can send a v2 PDU. You can use the AdventNet SNMP API for sending v1/v2 requests. Depending on the response, you can find out the version of the agent. If a particular version is not supported by the agent, the request times out. 2. I use the API to perform an SNMP GET. I want to get only the String and not the message. Also, I want the string in sbyte format instead of hex format. What should I do? The API does not have methods to return the sbytes in string format. However, the SnmpVar class has the ToBytes() method which returns an array of bytes. The following code snippet gets the result in string format. sbyte [] b = pdu.getvariablebinding(0).getvariable().tobytes(); String bstr = ""; for(int i=0; i < b.length ; i++ ) bstr+=" " +b[i]; System.Console.Out.WriteLine(bstr); 3. I use SnmpString, defined in the Snmp2 namespace, for both String and Octet String. While decoding a response, how do we differentiate between the two? There does not seem to be a method/field in the SnmpString attribute. The SNMP variable does not contain the Textual Convention information. DisplayString is a Textual Convention but the variable is an OCTET STRING. You need to get that from the MIB information for that MIB node, based on the OID in the variable binding. From the MibNode class, you can get the syntax for the object. When the MIB is not loaded, there is no way to distinguish. 4. I would like to use your API in a multithreaded application to collect some data. Is AdventNet SNMP API multithread safe? Yes, it is multithread safe. You need to close the session to get rid of the threads. 5. What is an OCTET in terms of bits? I am trying to determine a bandwidth utilization factor and I need to figure out how to represent an OCTET or a packet in bits. An OCTET is 8 bits. SnmpPDU.GetData() returns the data to be sent or received as a byte array. The length of this array gives you the packet size in bytes. 6. I instantiate the SnmpAPI and SnmpSession classes and various parameters, such as remotehost, community, etc. for the session object is set. When I call Session.Open(), everything works fine but the process started by the other Web-based application does not terminate. Is this because of the SNMPSession or API objects? Do I need to call Close() or Stop()? Both SnmpAPI and SnmpSession are threads. Stop the threads to release the resources if these objects are not used. Our API has SnmpSession.Close() method to stop the session thread and SnmpAPI.Close() method to stop the api thread and the session threads belonging to it. AdventNet, Inc. 191

193 7. How should I specify the SET value for two objects with the SYNTAX BITS and OCTET STRING object when I want to use an OCTET STRING of length 1? Set the type of the object as SnmpAPI.BITSTRING. Give the value as a string. If you want to use a string of length 1, give a single character string without quotes. 8. Can I perform a multiple OID query? If yes, how many OIDs can I query with a single SNMP GET? You can perform SNMP GET operation with multiple OIDs. The SnmpPDU class is used for making multiple OID request. You can make about 200 requests within a single PDU. It also depends on the agent from which you request the data. 9. It is understood that SnmpOID only accepts dot-formatted OID strings. I would like to request SNMP values using names and dot-formatted strings. Is there a class available that can help me maintain a database of variable OIDs and names? To handle named OIDs, you need to load the corresponding MIBs. The method GetSnmpOID() in MibModule and MibOperations classes accepts the name and returns the corresponding SnmpOID. Refer the apidocs of the com.adventnet.snmp.mibs namespace for more details. 10. In view of the SnmpAdventNet GetNext() facility, is there a way to detect the end of the GET rather than iterating till the end of the MIB. For example: if we do a GETNEXT on we get which is correct. But if we do getnext() we get Is there a way to make this return an error instead, since we are really going to the "next item"? You can try performing a walk instead of GETNEXT. For example, if you walk on the system with OID , it fetches upto the number of children under it stops after that. There is a method named IsInSubTree() which is used to detect the end of the walk for the corresponding parent node. 11. When I receive a PDU from the SNMP agent, how can I differentiate between a normal String and HEX-answer? By default, the API displays the value of type STRING as normal strings. However, if the string has a null character, it is interpreted as an HEX string. If you want to interpret any value as an HEX string, the method ToByteString() in SnmpString class is used. 12. I would like to set the OID of type EntryStatus but I cannot find this type in the SnmpAPI class. What should I do? What is the byte value for this type? In RFC1271-MIB, the EntryStatus is defined as follows. EntryStatus ::= INTEGER { valid(1), createrequest(2), undercreation(3), invalid(4) } So to perform a SET operation, you need to specify the type as SnmpAPI.INTEGER and the value should be in the set {1,2,3,4}. 13. How do I set UDP port explicitly for sending GET/SET/GETNEXT request? You can set the UDP port by using the method LocalPort() in SnmpSession. The method Port() in the SnmpTrapReceiver bean can be used to receive the traps in that port. You can also set the port using SnmpAPI. You can use any port to send traps and informrequest. AdventNet, Inc. 192

194 14. We would like to use a GETBULK to get several rows from our SNMP table at a time. The problem is that when I ask for 10 rows, the GETBULK returns only 6 rows and the last attribute of the sixth row is null. The sixth row seem to be truncated. Why is this so? The number of rows you get back may be limited by the PDU size permitted by your agent, manager, or transport. 15. I want to use your SNMP API to build a PDU packet. Is there a way to encode the PDU packet without sending it? I do not use UDP/IP to send packets. I use my own transport mechanism. As of now, the encoding of the PDU packet is done only when I actually send it out. Do you have a separate encoding function? As of now, there is no separate public method to encode the PDU. Therefore, you need to use your own encoding routines. We may in future provide an encoding routine to suite your design. 16. The problem is that the callback method is not invoked and deadlock occurs in the application while performing the SET operation. The table row is created in host and the OID and values are as follows :octet_string : :INTEGER : 4 (createandgo) :octet_string:ssssssssssssssssss. In SnmpPDU, you set the community as private. In SnmpSession, it is public by default. If the authenticate (pdu, writecommunity) method returns false, SnmpSession does not call the callback. Therefore, the following method is used. SnmpSession.WriteCommunity = writecommunity //Set writecommunity for outgoing requests 17. If I have more than one SnmpClient in SnmpSession, the callback method of all the SnmpClients is called whenever the session receives a response. How can I tell the SnmpSession that only one of the clients should receive the response for a particular request? The method "AddSnmpClientWithID(SnmpClient)" provided in the SnmpSession in the AdventNet SNMP API, helps you to do this. Instead of "AddSnmpClient(SnmpClient)", use "AddSnmpClientWithID(SnmpClient)" to add the SnmpClient. This method returns an integer called ClientID, which is associated with this client. Therefore, whenever an asynchronous SNMP request is sent using the "Send(SnmpPDU)" method, set this clientid in the PDU using the method "ClientID =int value" in SnmpPDU. By doing this, only the callback method of the SnmpClient, which corresponds to that ID is called. The following code snippet illustrates this feature. SnmpSession session = new SnmpSession(api); /* where api is the SnmpAPI instance. */ session.open(); int clientid = session.addsnmpclientwithid(snmpclient); /* where snmpclient is the instance of SnmpClient. */ SnmpPDU pdu = new SnmpPDU(); /* set all relevent parameters */ pdu.clientid = clientid; session.send(pdu); /* asynchronous SNMP request */ AdventNet, Inc. 193

195 Known Issues 1. Counter64 datatype is not supported AdventNet, Inc. 194

196 APIdocs APIdocs contains the classes and methods pertaining to various modules of SNMP API, which are categorized as follows. 1. com.adventnet.snmp.snmp2: This package implements snmp communication and snmp variables defined in ASN.1, such as SnmpOID, SnmpInteger, etc. 2. com.adventnet.snmp.mibs: This package provides all the MIB handling support, such as MIB loading, unloading, etc. Refer to the APIdocs of AdventNet SNMP API.NET Edition for more information. AdventNet, Inc. 195