# FAQ on Westhawk's SNMP stack

This file is part of the stack's distribution and is available online as well. The links in this document should work in the former case, but not necessarily in the later case.

### Basic questions:

Where can I download the stack from?
Where can I get more information on how to use your stack?
Where can I find examples on how to use the stack?
How do I compile the stack?
Which version of the JDK should I use?

### Usage questions:

What functionality does the stack offer?
Can I write an agent with your stack?
Does the stack have any MIB browser functionality?
Why do you not support the Report PDU?
How do I create an ASN.1 IP Address object?
Does the stack support IPv6?
How can I set the timeout and the number of retries of a request?
Why doesn't the stack decode incoming PDU requests or traps for me?

### Problem solving:

Why doesn't the number of threads reduce?
I get errors like `AsnObject.AsnMakeMe(): Bad Type 0xA6`. What do they mean?
My user interface seems to hang. Any idea?
Why does `AsnOctets.toString()` print hex, instead of a readable String?
Why does `AsnOctets.toString()` print a String, instead of a hex?

### General information:

How did you test your stack?
Is the stack vulnerable to malformed requests?
Where can I find more information on SNMP?
What about copyright, license and costs?
Which companies are using this stack?

### Basic questions:

Where can I download the stack from?

The latest version is available from our website.

Where can I get more information on how to use your stack?

You can Google our SNMP site, using (excludes javadoc)

Help on the stack can be found in this FAQ, the Stack Usage document (also online), the javadoc documentation (not online) and the examples that are distributed with the stack. Please search the archives of the mailing list(s).

We do not have a buglist or a todo list. We are thinking about realising all of these, but have not done so yet.

If your question is not answered by any of the above, you can post it to the snmp mailing list (you have to be subscribed to do so). We will answer when our resources permit us to do so. When posting, please consider the following:

- Useful Subject. Please give your email a useful subject. Help or Question do not tell us the nature of your problem or request.
- Be Precise. Please tell us precisely what you are doing, and precisely what is happening. Please mention:
  - any error messages or exception trace
  - JDK version, Platform, Stack version
- Be Polite. The stack is free, so please realise we have no obligation to answer your questions. Aggressive language, excessive use of capitals, and multiple exclamation points or question marks are all considered rude and are not appreciated.
- Proper English. It does not have to be perfect English, but please no hacker, geek or SMS like speech, like l8r or C U. If it is too hard to read, you can't expect people to help you.
- Tell Us Your Name. It feels good to know who we are talking to.

Where can I find examples on how to use the stack?

The packages uk.co.westhawk.examplev1, uk.co.westhawk.examplev2c and uk.co.westhawk.examplev3 contain examples. The Stack Usage document explains how to configure and run them.

How do I compile the stack?

Unless you want to change our code, there is no need to compile the whole stack. All the `uk.westhawk.snmp.XX` packages are bundled in the `snmp<version>.jar` file.

The stack comes with Ant build files. Type `ant compile` to compile the stack.

However, the best thing to do is to import the package(s) and/or example(s) into your favourite IDE, like JBuilder or Forte, and take it from there. You should be able to add the `snmp<version>.jar` file to the library of your IDE.

Which version of the JDK should I use?

The stack is compiled with JDK 1.4.1. The packages uk.co.westhawk.nothread.oscar and uk.co.westhawk.nothread.trap have to be compliant with JDK 1.2.X, since that is what Oracle™ 9i supports. However, this can be done by setting the javac target option to 1.2.

### Usage questions:

What functionality does the stack offer?

The stack provides manager and (the basis of) agent functionality for SNMPv1, SNMPv2c and SNMPv3 (both authentication and privacy).

PDU type | Sending | Receiving
Get Request | Yes | Yes
GetNext Request | Yes | Yes
Set Request | Yes | Yes
GetBulk Request (v2c, v3) | Yes | Yes
Inform Request (v2c, v3) | Yes | Yes
Response | Yes | Yes
Trap v1 | Yes | Yes
Trap v2 (v2c, v3) | Yes | Yes
Report | No | No

Can I write an agent with your stack?

The stack was originally written with manager only functionality. In v4_14 we added the code that enables the stack to receive incoming requests from different sources & of different types, and the interface that allows the stack to act as authoritative engine.

However, an agent (or authoritative engine) should not only be able to receive requests, it has to act on them as well. This is much more tricky. For a 'generic' agent framework you need a tool that takes a MIB and creates a heap of java that will return the right types for a given OID. It also needs to generate stub methods which are then implemented (i.e. go off and get the real value from the correct hardware register or whatever).

The stack does not offer any help in this area. We would like to build such a generic framework, but are not sure (yet) on the design. Doing this properly takes a lot of effort and ongoing (paid) projects have priority. As always we would appreciate feedback on this matter.

Does the stack have any MIB browser functionality?

No. The idea is to write dedicated PDUs or beans that gather specific MIB information, i.e. the OID (Object Identifier) is hard coded.

We use Scotty, that is based on Tk/Tcl. We have written an experimental Stub Browser, using the Mibble MIB Parser. Please read the section in the Stack Usage document.

Why do you not support the Report PDU?

The Report PDU is implemented as part of the SNMPv3 timeliness discovery. As far as we know Report PDUs are not used in "higher level" engine to engine communication, like the Request PDUs are. If you think otherwise, please post to the mailing list, mentioning the RFC where the Report PDU behaviour is defined.

How do I create an ASN.1 IP Address object?

You can use one of the following three AsnOctets constructors:

1. AsnOctets(byte[] s, byte t) , where t = SnmpConstants.IPADDRESS
2. AsnOctets(java.net.InetAddress iad)
3. AsnOctets(java.net.Inet4Address iad, byte t) , where t = SnmpConstants.IPADDRESS

Note that the ASN.1 IP Address object only represents IPv4 addresses.

Does the stack support IPv6?

Yes it does, as far as your operating and your j2se version do (or "don't" as we found out painfully). See the Networking IPv6 User Guide for J2SDK/JRE 1.4 and JDK/JRE 5.0 and Core Java APIs on Mac OS X.
The stack doesn't do anything special to send packets over IPv6; it relies on the JVM (and hence the operating system).
As of version 4_14, we added additional methods to the AsnOctets class to deal with IPv6 MIB values. Please note that the IPv6 address doesn't have its own ASN.1 type (like IPv4 does). As far as we know, there are currently two MIB IPv6 address representations:

- Ipv6Address - see IPV6-TC
- InetAddressIPv6 - see INET-ADDRESS-MIB

In both case the IPv6 address is a "TEXTUAL-CONVENTION" of an OCTET STRING (SIZE (16)). This means that the stack doesn't know when a MIB OID value is a IPv6 address. You will have to build that knowledge into your application.

How can I set the timeout and the number of retries of a request?

You can set both with the method `Pdu.setRetryIntervals(int[])`.

Why doesn't the stack decode incoming PDU requests or traps for me?

Indeed the stack requires a SnmpContext to decode each incoming (unsolicited) PDU. This context needs to be configured with the host name and parameters of your SNMP agent/manager.
It would be possible for SNMPv1 and SNMPv2 to decode trap automatically, i.e. ignoring the host and community name. We don't think that this is a good idea, because:

- it is a security problem - any fool can send a trap with a spoofed 'from' address and your software will accept and decode it. The only protection you have in v1 and v2c (and this isn't much) is in the form of the shared secret of the community name.
- it would cause the stack to behave differently for SNMPv3, since unless you know stuff about the sender of a v3 trap you can't authenticate it or decrypt it on the fly.

### Problem solving:

Why doesn't the number of threads reduce?

Make sure you call `AbstractSnmpContext.destroy()` when you are finished with a context. The method `AbstractSnmpContext.getDebugString()` returns the thread usage of the context.

I get errors like `AsnObject.AsnMakeMe(): Bad Type 0xA6`. What do they mean?

This means that the PDU packet is malformed. Either the engine sent a malformed packet or the stack did not read in the whole message. The later can be tuned with the method `AbstractSnmpContext.setMaxRecvSize(int no)`.

My user interface seems to hang. Any idea?

If you are using Swing and you are changing your user interface in the `update()` or `propertyChange()` method, you should do this via `Swing.InvokeLater()` to make sure the update is done on the Swing thread. See AnnexModemStatusBean.java for an example.

Why does `AsnOctets.toString()` print hex, instead of a readable String? or
Why does `AsnOctets.toString()` print a String, instead of a hex?

The problem is that the stack has no MIB knowledge, so the method `AsnOctets.toString()` does a best guess and tries to figure out whether the octets are printable or not.
If you know the AsnOctets represent a DateAndTime use `AsnOctets.toCalendar()`, or a DisplayString use `AsnOctets.toDisplayString()`.
In version 4_14 we have added the interface `uk.co.westhawk.snmp.stack.AsnOctetsPrintableFace` and the class `uk.co.westhawk.snmp.stack.DefaultAsnOctetsPrintable` to allow you to control this behaviour yourself. The interface also allows you to specify how to print the octets as InternationalDisplayString.

### General information:

How did you test your stack?

We have tested the v3 implementation against MG-SOFT's agent and NET-SNMP (formerly known as UCD-SNMP). Our users have used it against many other agents. As far as we know there is no standards body that tests SNMPv3 compliance.

The test matrices on our last version is included in the distribution file, see test.html and trap.html. More information on how the test works can be found in the javadoc.

Is the stack vulnerable to malformed requests?

Since the stack is written in Java and Java is immune to most types of buffer overrun, we are far better off than the C-based stacks.

We did run the PROTOS test suite against our stack. This caused some problems whilst decoding the packets. The worse one caused the stack to throw ClassCastExceptions, killing the receive thread. We amended the stack (version 4_12) so it catches all exceptions. Other packets only produced error messages.

The bulk of the vulnerabilities are against agents, our stack is only a manager. If we ever extend the stack to become an agent, we will run the test suite again.

Where can I find more information on SNMP?

Please read the section in the Stack Usage document.

What about copyright, license and costs?

Please read the section in the Stack Usage document.

Which companies are using this stack?

That is a little hard to say, since many use it for internal purposes (or indeed in products) without informing us. Here are some links to companies we know have used it:

- Adherent, now part of Tektronix Cambridge
- Advanced Networking Group
- Advent Communications
- Arsin
- Aspect
- Avitech
- BBN Technologies
- Bell Labs
- Cherry
- Cisco Systems
- Cygsoft
- DF soft
- ERG Group
- Greenpacket
- HP - PCM+
- Imagine Broadband
- Intel
- Iskratel
- Multicast Visualisation Tool (MUVI)
- NET2S
- NetIQ
- Netopia
- New Break
- Phonologies
- RegulusSoft
- Reuters
- Riftware Development
- Roadrunner
- Siemens
- Spawar
- Sterling Commerce
- TCOM
- Travelocity
- Tripwire
- Verizon
- Virtual Technology
- Visionael
- VoIP
- Westpoint
- Zuma Networks

01 Feb 2006

Post to the mailing list or contact the snmp group at Westhawk Ltd