---------------------------------------------------------------------- readme.txt ---------------------------------------------------------------------- jSNMP Enterprise(tm) 3.2 Copyright (c) 2003 jSNMP Enterprises All Rights Reserved ---------------------------------------------------------------------- ----------------- TABLE OF CONTENTS ----------------- SECTION 1. General Information SECTION 2. Known jSNMP Enterprise Issues SECTION 3. Known Agent Issues SECTION 4: Changes/Bug Fixes SECTION 5: Trademarks ------------------------------ SECTION 1. General Information ------------------------------ jSNMP Enterprise is a highly optimized Java Package for communicating with SNMP devices and services. It is written entirely in Java and is completely portable. jSNMP Enterprise provides complete SNMPv1, SNMPv2c and SNMPv3 support. jSNMP Enterprise also includes a Java-based MIB compiler, jMIBC. While jSNMP Enterprise is a complete solution for managing SNMP devices, certain functionality within jSNMP may require the installation of additional Java packages depending upon your environment. If you wish to run RMI applets in IE, you must install the RMI patch from Microsoft (ftp://ftp.microsoft.com/developr/MSDN/UnSup-ed/rmi.zip) or IBM (http://www.alphaworks.ibm.com/formula/RMI). If you wish to use the SNMPv3 encryption or authentication capabilities of jSNMP, you must install and configure a Java Cryptography Extension. Sun provides a standard implementation at http://java.sun.com/products/jce/index.html. More information on both of these topics is provided in the User's Guide and the FAQ located in this directory. For detailed information on the use and operation of jSNMP, see the jSNMPEnterpriseUserGuide.pdf document included in this distribution. For detailed information on the use and operation of jMIBC, see the jMIBCUserGuide.pdf document included in this distribution. For differences between this version of jSNMP Enterprise and previous versions, please consult the jSNMP Enterprise User Guide and the changes.txt file. For a complete reference to all jSNMP Enterprise interfaces, please see the Javadoc index.html file in the doc directory. ---------------------------------------- SECTION 2. Known jSNMP Enterprise Issues ---------------------------------------- Uncompressed JAR's ------------------ To support the broadest number of development and runtime environments, jSNMP Enterprise is shipped with uncompressed JAR's. If you wish to use compressed JAR's to save space or download time, it is a simple task to un-JAR and then re-JAR them with various jar and unzip utilities available. For example, to extract all the contents of the jSNMP.jar and rebuild a compressed jar, use the following steps: 1. Extract the JAR archive using an unzip utility: // extract all files, retain directory structure unzip jSNMPEnterprise.jar 2. Create a compressed jar using the JAR utility shipped with Sun's JDK: // make a jar from all class files under the com directory jar cvf jSNMPEnterpriseCompressed.jar com See the InfoZip home page (http://www.freesoftware.com/pub/infozip/) and the Sun Documentation Site (http://developer.java.sun.com/) for more information. CAB's for Internet Explorer 3.X ------------------------------- Earlier versions of Microsoft Internet Explorer could not use the JAR format. In order to make a jSNMP Enterprise applet work in an IE 3.X browser, a CAB file must be created. The easiest method of building the CAB is to explode the JAR (using the JDK 'jar' utility or an unzip utility), and then build the CAB using the CABARC tool included in Microsoft Java SDK 2.X. See the Microsoft Java Home Page (http://www.microsoft.com/java/) for more information. Trap Handling on Unix Platforms ------------------------------- Because UNIX requires root privileges to open a socket with a port less than 1024, any applications built with jSNMP Enterprise and designed to receive traps must be run with root access. SNMPv3 Encryption ----------------- jSNMP Enterprise supports DES encryption in SNMPv3 requests. To support DES encryption a Java Cryptography Extension (JCE- http://java.sun.com/products/jce/index.html) must be installed. Other JCE providers other than Sun can be found at http://java.sun.com/products/jce/jce12_providers.html. Note that the JCE requires a JDK/JRE or version 1.2.1 or later. If the encryption feature of SNMPv3 is not used, a JCE is not required. SNMPv3 Applets in Browsers -------------------------- jSNMP Enterprise applets that make SNMPv3 requests using authentication and/or encryption may fail by throwing a java.lang.NoClassDefFoundError exception, as the MessageDigest class (Netscape) is not available when using authentication and the com/sun/crypto/provider/SunJCE package (Netscape and Internet Explorer) is not available when using authentication and/or encryption. The solution is to install the Java Plug-in in the Browser (http://java.sun.com/products/plugin/) using JRE 1.2.2 or later and a JCE for encryption. Trap/Inform Bursts ------------------ Large "bursts" of traps/informs may cause some of these traps/informs to be lost when listening for traps/informs. jSNMP Enterprise is able to handle sustained "bursts" of 100-400 or more incoming traps/informs per second without loss depending on the operating environment. The trap/inform queue capacity and expansion size can be manipulated through SnmpServiceConfiguration class methods. This should not be needed as the defaults, though large, are optimal. NULL SnmpVarBind in SnmpCustomer.deliverSuccessfulOrder() --------------------------------------------------------- It is possible that a SnmpCustomer.deliverSuccessfulOrder() method will receive a null SnmpVarBind. While unlikely, jSNMP Enterprise programmers should test for NULL on the SnmpVarBind argument. Large number of Varbinds in orders ---------------------------------- Large OID arrays can be used when placing orders. While jSNMP Enterprise can handle large OID arrays, illicit timeouts may occur. The optimal number of OIDs will be dependent upon the speed of the host, the speed of the network, and the speed of the remote agent. It is recommended that the programmer limit the number of OIDs in a request to a reasonable number, or when targeting SNMPv2/3 agents, make use of the SnmpService.placeGetBulkOrder() request. ----------------------------- SECTION 3. Known Agent Issues ----------------------------- Timeouts -------- Some SNMP agents will not issue a response to PDUs which contain invalid OIDs. As jSNMP Enterprise optimizes network traffic by placing multiple orders in the same PDU, valid requests would timeout. As a workaround, jSNMP Enterprise will split apart packets which have timed out and send each with a single order. This provides the desired behavior when dealing with these those agents that will not issue responses to requests containing invalid OIDs. Invalid Length for ASN.1 Counters and Gauges -------------------------------------------- Some agents incorrectly encode ASN.1 unsigned 32-bit types by specifying their length to be 5 bytes in the PDU packet, when in fact the data only occupies 4 bytes. The workaround in jSNMP Enterprise is to ignore the error, and treat the value as it occupies 4 bytes, then continue processing the PDU. ------------------ SECTION 4. Changes ------------------ jSNMP Enterprise 3.2 is a new product release. Detailed information on the changes from previous versions can be found in the Changes.txt file. --------------------- SECTION 5. Trademarks --------------------- jSNMP, jSNMP Enterprise, and jMIBC are either trademarks or registered trademarks of jSNMP Enterprises. Java and JDK are either trademarks or registered trademarks of Sun Microsystems, Inc. All other company or product names are either trademarks or registered trademarks of their respective companies.