ipworksssnmp
Class Snmpagent

java.lang.Object
  |
  +--ipworksssnmp.Snmpagent

public class Snmpagent

extends java.lang.Object

The SNMPAgent bean is used to implement SNMP Agent Applications.

The SNMPAgent bean implements a standard SNMP Agent as specified in the SNMP RFCs. The bean supports SNMP v1, v2c, and v3.

The bean provides both encoding/decoding and transport capabilities, making the task of developing a custom SNMP agent as simple as setting a few key properties and handling a few events. SNMP data such as SNMP object id-s (OID-s) are exchanged as text strings, thus further simplifying the task of handling them.

The bean is activated/deactivated by setting the Active property. This property enables or disables sending and receiving.

The bean operates asynchronously. Requests are received through events such as GetRequest , GetBulkRequest , GetNextRequest , etc.. and the corresponding responses are automatically sent when the events return. Traps are sent through the SendTrap method.

SNMPv3 USM security passwords are requested through the GetUserPassword event, and event parameters such as User and SecurityLevel provide information about the security attributes of received requests, and enable granular decision capability about what to provide and what not to provide. The SendSecureTrap method is used to send authenticated (secure) SNMPv3 traps.

The AddUser , RemoveUser , ShowCache , ClearCache , AddEngine , and RemoveEngine methods are used to manage an internal authentication cache. This internal cache can be used as an alternative to the GetUserPassword event, automatically checking the cache against the security parameters provided in the request signature.

SNMP OIDs, types, and values are provided in arrays such as ObjId , ObjType , and ObjValue , for both sent and received packets. ObjCount provides the number of elements in each of the arrays.

Other packet information is provided through corresponding event parameters, such as Community, or RequestId.

Field Summary

static int	otCounter32
static int	otCounter64
static int	otEndOfMibView
static int	otGauge32
static int	otInteger
static int	otIPAddress
static int	otNoSuchInstance
static int	otNoSuchObject
static int	otNSAP
static int	otNull
static int	otObjectId
static int	otOctetString
static int	otOpaque
static int	otTimeTicks
static int	otUnsignedInteger32
static int	snmpverV1
static int	snmpverV2c
static int	snmpverV3

Constructor Summary

Snmpagent()

Method Summary

void	addSnmpagentEventListener(SnmpagentEventListener l)
void	addUser(java.lang.String user, java.lang.String authenticationPassword, java.lang.String encryptionPassword) Adds a user to the internal authentication cache.
void	clearCache() Clears the internal authentication database.
java.lang.String	config(java.lang.String configurationString) Sets or retrieves a beanconfiguration setting.
void	doEvents() Processes events from the internal message queue.
byte[]	getLocalEngineId() The Engine Id of the SNMP Agent.
java.lang.String	getLocalHost() The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
int	getLocalPort() The UDP port in the local host where the bean listens.
int	getObjCount() Number of objects in the current request.
java.lang.String	getObjId(int objIndex) Array of OIDs encoded as strings.
int	getObjType(int objIndex) Array of object types.
byte[]	getObjValue(int objIndex) Array of object values.
int	getRequestId() The request-id to mark outgoing packets with.
int	getSNMPVersion() Version of SNMP used for outgoing requests (traps).
int	getSysUpTime() Time passed since the agent was initialized (in hundredths of a second).
void	hashPasswords() Hashes all passwords in the cache.
boolean	isAcceptData() Enables or disables data reception.
boolean	isActive() Enables or disables sending and receiving of SNMP packets.
void	removeSnmpagentEventListener(SnmpagentEventListener l)
void	removeUser(java.lang.String user) Removes the user specified by User from the internal authentication cache.
void	reset() Clears the object arrays.
void	sendSecureTrap(java.lang.String remoteHost, java.lang.String trapOID, java.lang.String user, java.lang.String authenticationPassword, java.lang.String encryptionPassword) Sends an authenticated and/or encrypted SNMPv3 trap.
void	sendTrap(java.lang.String remoteHost, java.lang.String trapOID) Sends an SNMP Trap.
void	setAcceptData(boolean acceptData) Enables or disables data reception.
void	setActive(boolean active) Enables or disables sending and receiving of SNMP packets.
void	setLocalEngineId(byte[] localEngineId) The Engine Id of the SNMP Agent.
void	setLocalHost(java.lang.String localHost) The name of the local host or user-assigned IP interface through which connections are initiated or accepted.
void	setLocalPort(int localPort) The UDP port in the local host where the bean listens.
void	setObjCount(int objCount) Number of objects in the current request.
void	setObjId(int objIndex, java.lang.String objId) Array of OIDs encoded as strings.
void	setObjType(int objIndex, int objType) Array of object types.
void	setObjValue(int objIndex, byte[] objValue) Array of object values.
void	setRequestId(int requestId) The request-id to mark outgoing packets with.
void	setSNMPVersion(int SNMPVersion) Version of SNMP used for outgoing requests (traps).
void	setSysUpTime(int sysUpTime) Time passed since the agent was initialized (in hundredths of a second).
void	showCache() Lists all entries in the internal user authentication cache.
java.lang.String	value(java.lang.String OID) Returns the value corresponding to an OID.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

otInteger

public static final int otInteger

See Also:

Constant Field Values

otOctetString

public static final int otOctetString

See Also:

Constant Field Values

otNull

public static final int otNull

See Also:

Constant Field Values

otObjectId

public static final int otObjectId

See Also:

Constant Field Values

otIPAddress

public static final int otIPAddress

See Also:

Constant Field Values

otCounter32

public static final int otCounter32

See Also:

Constant Field Values

otGauge32

public static final int otGauge32

See Also:

Constant Field Values

otTimeTicks

public static final int otTimeTicks

See Also:

Constant Field Values

otOpaque

public static final int otOpaque

See Also:

Constant Field Values

otNSAP

public static final int otNSAP

See Also:

Constant Field Values

otCounter64

public static final int otCounter64

See Also:

Constant Field Values

otUnsignedInteger32

public static final int otUnsignedInteger32

See Also:

Constant Field Values

otNoSuchObject

public static final int otNoSuchObject

See Also:

Constant Field Values

otNoSuchInstance

public static final int otNoSuchInstance

See Also:

Constant Field Values

otEndOfMibView

public static final int otEndOfMibView

See Also:

Constant Field Values

snmpverV1

public static final int snmpverV1

See Also:

Constant Field Values

snmpverV2c

public static final int snmpverV2c

See Also:

Constant Field Values

snmpverV3

public static final int snmpverV3

See Also:

Constant Field Values

Constructor Detail

Snmpagent

public Snmpagent()

Method Detail

isAcceptData

public boolean isAcceptData()

Enables or disables data reception.

Setting the property to False temporarily disables data reception. Setting the property to True re-enables data reception.

setAcceptData

public void setAcceptData(boolean acceptData)
                   throws IPWorksSSNMPException

Enables or disables data reception.

Setting the property to False temporarily disables data reception. Setting the property to True re-enables data reception.

IPWorksSSNMPException

isActive

public boolean isActive()

Enables or disables sending and receiving of SNMP packets.

The Active property must be set to True before any SNMP requests or traps are sent or received.

setActive

public void setActive(boolean active)
               throws IPWorksSSNMPException

Enables or disables sending and receiving of SNMP packets.

The Active property must be set to True before any SNMP requests or traps are sent or received.

IPWorksSSNMPException

getLocalEngineId

public byte[] getLocalEngineId()

The Engine Id of the SNMP Agent.

This property is only used for SNMPv3 packets (when SNMPVersion is 3).

setLocalEngineId

public void setLocalEngineId(byte[] localEngineId)
                      throws IPWorksSSNMPException

The Engine Id of the SNMP Agent.

This property is only used for SNMPv3 packets (when SNMPVersion is 3).

IPWorksSSNMPException

getLocalHost

public java.lang.String getLocalHost()

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.

If the bean is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

setLocalHost

public void setLocalHost(java.lang.String localHost)
                  throws IPWorksSSNMPException

The name of the local host or user-assigned IP interface through which connections are initiated or accepted.

The LocalHost property contains the name of the local host as obtained by the gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the bean initiate connections (or accept in the case of server beans) only through that interface.

If the bean is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

NOTE: LocalHost is not persistent. You must always set it in code, and never in the property window.

IPWorksSSNMPException

getLocalPort

public int getLocalPort()

The UDP port in the local host where the bean listens.

The LocalPort property must be set before the bean is activated ( Active is set to True). It instructs the bean to bind to a specific port (or communication endpoint) in the local machine (default 161).

You may also set LocalPort to 0. This allows the TCP/IP stack to choose a port at random. The value chosen is provided via the LocalPort property after the bean is activated through the Active property.

LocalPort cannot be changed once the bean is Active . Any attempt to set the LocalPort property when the bean is Active will generate an error.

setLocalPort

public void setLocalPort(int localPort)
                  throws IPWorksSSNMPException

The UDP port in the local host where the bean listens.

The LocalPort property must be set before the bean is activated ( Active is set to True). It instructs the bean to bind to a specific port (or communication endpoint) in the local machine (default 161).

You may also set LocalPort to 0. This allows the TCP/IP stack to choose a port at random. The value chosen is provided via the LocalPort property after the bean is activated through the Active property.

LocalPort cannot be changed once the bean is Active . Any attempt to set the LocalPort property when the bean is Active will generate an error.

IPWorksSSNMPException

getObjCount

public int getObjCount()

Number of objects in the current request.

The ObjCount property provides the number of elements in the various Obj arrays ( ObjId , ObjType , ObjValue ).

The arrays may be cleared at any time by setting the ObjCount to 0.

setObjCount

public void setObjCount(int objCount)
                 throws IPWorksSSNMPException

Number of objects in the current request.

The ObjCount property provides the number of elements in the various Obj arrays ( ObjId , ObjType , ObjValue ).

The arrays may be cleared at any time by setting the ObjCount to 0.

IPWorksSSNMPException

getObjId

public java.lang.String getObjId(int objIndex)
                          throws IPWorksSSNMPException

Array of OIDs encoded as strings.

The object id-s are encoded as strings of numbers separated by "."-s, for instance: "1.3.6.1.2.1.1.1.0" (OID for "system description").

The size of the array is determined by the ObjCount property. Element indexes start at 1.

The array is populated and its size is set every time an SNMP packet is received. It is also used to create outgoing SNMP packets.

The corresponding object type and value (if any) are specified by the ObjType and ObjValue property arrays.

Example

 SNMPControl.ObjCount = 2
 SNMPControl.ObjID(1) = "1.3.6.1.2.1.1.1.0"
 SNMPControl.ObjID(2) = "1.3.6.1.2.1.1.2.0" 

IPWorksSSNMPException

setObjId

public void setObjId(int objIndex,
                     java.lang.String objId)
              throws IPWorksSSNMPException

Array of OIDs encoded as strings.

The object id-s are encoded as strings of numbers separated by "."-s, for instance: "1.3.6.1.2.1.1.1.0" (OID for "system description").

The size of the array is determined by the ObjCount property. Element indexes start at 1.

The array is populated and its size is set every time an SNMP packet is received. It is also used to create outgoing SNMP packets.

The corresponding object type and value (if any) are specified by the ObjType and ObjValue property arrays.

Example

 SNMPControl.ObjCount = 2
 SNMPControl.ObjID(1) = "1.3.6.1.2.1.1.1.0"
 SNMPControl.ObjID(2) = "1.3.6.1.2.1.1.2.0" 

IPWorksSSNMPException

getObjType

public int getObjType(int objIndex)
               throws IPWorksSSNMPException

Array of object types.

The size of the array is determined by the ObjCount property. Element indexes start at 1.

The array is populated and its size is set every time an SNMP packet is received. It is also used to create an outgoing SNMP packet when a send or request method is called. The default type is NULL (5).

The corresponding object id and value are specified by the ObjId and ObjValue property arrays.

Possible object type values include:

otInteger (2)

2

otOctetString (4)

4

otNull (5)

5

otObjectID (6)

6

otIPAddress (64)

64

otCounter32 (65)

65

otGauge32 (66)

66

otTimeTicks (67)

67

otOpaque (68)

68

otNSAP (69)

69

otCounter64 (70)

70

otUnsignedInteger32 (71)

71

The bean also supports the following artificial object values used to designate error conditions:

otNoSuchObject (128)

No such object error.

otNoSuchInstance (129)

No such instance error.

otEndOfMibView (130)

End of MIB View error.

IPWorksSSNMPException

setObjType

public void setObjType(int objIndex,
                       int objType)
                throws IPWorksSSNMPException

Array of object types.

The size of the array is determined by the ObjCount property. Element indexes start at 1.

The array is populated and its size is set every time an SNMP packet is received. It is also used to create an outgoing SNMP packet when a send or request method is called. The default type is NULL (5).

The corresponding object id and value are specified by the ObjId and ObjValue property arrays.

Possible object type values include:

otInteger (2)

2

otOctetString (4)

4

otNull (5)

5

otObjectID (6)

6

otIPAddress (64)

64

otCounter32 (65)

65

otGauge32 (66)

66

otTimeTicks (67)

67

otOpaque (68)

68

otNSAP (69)

69

otCounter64 (70)

70

otUnsignedInteger32 (71)

71

The bean also supports the following artificial object values used to designate error conditions:

otNoSuchObject (128)

No such object error.

otNoSuchInstance (129)

No such instance error.

otEndOfMibView (130)

End of MIB View error.

IPWorksSSNMPException

getObjValue

public byte[] getObjValue(int objIndex)
                   throws IPWorksSSNMPException

Array of object values.

The size of the array is determined by the ObjCount property. Element indexes start at 1.

The array is populated and its size is set every time an SNMP packet is received. It is also used to create an outgoing SNMP packet when a send or request method is called.

The corresponding object id and type are specified by the ObjId and ObjType property arrays.

Example

 SNMPControl.ObjCount = 1
 SNMPControl.ObjID(1) = "1.3.6.1.2.1.1.1.0"
 SNMPControl.ObjValue(1) = "New Value" 

IPWorksSSNMPException

setObjValue

public void setObjValue(int objIndex,
                        byte[] objValue)
                 throws IPWorksSSNMPException

Array of object values.

The size of the array is determined by the ObjCount property. Element indexes start at 1.

The array is populated and its size is set every time an SNMP packet is received. It is also used to create an outgoing SNMP packet when a send or request method is called.

The corresponding object id and type are specified by the ObjId and ObjType property arrays.

Example

 SNMPControl.ObjCount = 1
 SNMPControl.ObjID(1) = "1.3.6.1.2.1.1.1.0"
 SNMPControl.ObjValue(1) = "New Value" 

IPWorksSSNMPException

getRequestId

public int getRequestId()

The request-id to mark outgoing packets with.

If a custom value is needed for RequestId , the property must be set before sending the request. The bean increments RequestId automatically after sending each packet.

setRequestId

public void setRequestId(int requestId)
                  throws IPWorksSSNMPException

The request-id to mark outgoing packets with.

If a custom value is needed for RequestId , the property must be set before sending the request. The bean increments RequestId automatically after sending each packet.

IPWorksSSNMPException

getSNMPVersion

public int getSNMPVersion()

Version of SNMP used for outgoing requests (traps).

This property takes one of the following values:

snmpverV1 (1)

SNMP Version 1.

snmpverV2c (2)

SNMP Version 2c.

snmpverV3 (3)

SNMP Version 3.

setSNMPVersion

public void setSNMPVersion(int SNMPVersion)
                    throws IPWorksSSNMPException

Version of SNMP used for outgoing requests (traps).

This property takes one of the following values:

snmpverV1 (1)

SNMP Version 1.

snmpverV2c (2)

SNMP Version 2c.

snmpverV3 (3)

SNMP Version 3.

IPWorksSSNMPException

getSysUpTime

public int getSysUpTime()

Time passed since the agent was initialized (in hundredths of a second).

This property is used when sending SNMP traps, and it normally provides the time since the system was restarted in 1/100s of a second.

If another value is desired, you may set this property to a custom value. From that point on, SysUpTime will return the value set plus time elapsed.

setSysUpTime

public void setSysUpTime(int sysUpTime)
                  throws IPWorksSSNMPException

Time passed since the agent was initialized (in hundredths of a second).

This property is used when sending SNMP traps, and it normally provides the time since the system was restarted in 1/100s of a second.

If another value is desired, you may set this property to a custom value. From that point on, SysUpTime will return the value set plus time elapsed.

IPWorksSSNMPException

config

public java.lang.String config(java.lang.String configurationString)
                        throws IPWorksSSNMPException

Sets or retrieves a beanconfiguration setting.

Config is a generic method available in every bean. It is used to set and retrieveconfiguration settingsfor the bean.

Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the bean, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY , you must call Config("PROPERTY=VALUE") , where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY") . The value will be returned as a string.

IPWorksSSNMPException

addUser

public void addUser(java.lang.String user,
                    java.lang.String authenticationPassword,
                    java.lang.String encryptionPassword)
             throws IPWorksSSNMPException

Adds a user to the internal authentication cache.

The internal authentication cache can be used as an alternative to the GetUserPassword event, automatically checking the cache against the security parameters provided in the request signature.

The ShowCache method is used to show the contents of the internal authentication cache.

The ClearCache method can be used to completely clear the cache.

IPWorksSSNMPException

clearCache

public void clearCache()
                throws IPWorksSSNMPException

Clears the internal authentication database.

All user records are removed from the internal authentication cache as a result of this call.

IPWorksSSNMPException

doEvents

public void doEvents()
              throws IPWorksSSNMPException

Processes events from the internal message queue.

When DoEvents is called, the bean processes any available events. If no events are available, it waits for a preset period of time, and then returns.

IPWorksSSNMPException

hashPasswords

public void hashPasswords()
                   throws IPWorksSSNMPException

Hashes all passwords in the cache.

Forces computation of all passwords hashes in the cache. Used together with the HashPassword event to enable implementations of external password hash storage.

IPWorksSSNMPException

removeUser

public void removeUser(java.lang.String user)
                throws IPWorksSSNMPException

Removes the user specified by User from the internal authentication cache.

The internal authentication cache can be used as an alternative to the GetUserPassword event, automatically checking the cache against the security parameters provided in the request signature.

The ShowCache method is used to show the contents of the internal authentication cache.

The ClearCache method can be used to completely clear the cache.

IPWorksSSNMPException

reset

public void reset()
           throws IPWorksSSNMPException

Clears the object arrays.

Clears the object arrays, and sets the trap and error properties to their default values. This is useful for reinitializing all the properties that are used to create outgoing packets before building a new packet.

IPWorksSSNMPException

sendSecureTrap

public void sendSecureTrap(java.lang.String remoteHost,
                           java.lang.String trapOID,
                           java.lang.String user,
                           java.lang.String authenticationPassword,
                           java.lang.String encryptionPassword)
                    throws IPWorksSSNMPException

Sends an authenticated and/or encrypted SNMPv3 trap.

Similar to the SendTrap method except that User and AuthenticationPassword are used to authenticate the trap, and EncryptionPassword (if not empty) is used to encrypt the message.

The user and password arguments used to send the trap will be added to the internal user cache. If the user is already in the cache, its passwords will be updated with those supplied.

IPWorksSSNMPException

sendTrap

public void sendTrap(java.lang.String remoteHost,
                     java.lang.String trapOID)
              throws IPWorksSSNMPException

Sends an SNMP Trap.

Depending upon the value of the SNMPVersion property, the packet is constructed as an SNMPv1 or SNMPv2 Trap PDU. The following configuration settings provide more control about how traps are generated:TrapPort,TrapAgentAddress,TrapCommunity,TrapEnterprise. The SysUpTime property provides the trap timestamp.

SendTrap sends an unauthenticated trap. The SendSecureTrap method is used to send authenticated SNMPv3 traps.

If any values are provided in the ObjId , ObjType , ObjValue arrays, (i.e. ObjCount is greater than 0), they are sent unchanged. In the case of an SNMPv2 or SNMPv3 Trap, if ObjCount is 0, the following values are set: sysUpTime.0 equal to SysUpTime and snmpTrapOID.0 equal to TrapOID .

For SNMPv2 and SNMPv3 Traps, TrapOID must contain the full OID of the Trap. For SNMPv1, TrapOID must be a string of the form "generic.specific" where generic and specific are numeric values providing the Trap Generic Type and Specific Type.

For SNMPv1, TrapOID must be of the form "GenericTrap.SpecificTrap". These values are sent in the PDU header.TrapAgentAddressandTrapEnterpriseare taken from the corresponding configuration settings.

Additionally, the following symbolic values are recognized and translated as follows:

Trap NameOID (SNMPv2 and above)

SNMPv1 GenericType

coldStart \011\0111.3.6.1.6.3.1.1.5.1

0

warmStart \011\0111.3.6.1.6.3.1.1.5.2

1

linkDown \011\0111.3.6.1.6.3.1.1.5.3

2

linkUp \011\011\0111.3.6.1.6.3.1.1.5.4

3

authenticationFailure1.3.6.1.6.3.1.1.5.5

4

egpNeighborLoss1.3.6.1.6.3.1.1.5.6

5

enterpriseSpecific\0111.3.6.1.6.3.1.1.5.7\011

6

IPWorksSSNMPException

showCache

public void showCache()
               throws IPWorksSSNMPException

Lists all entries in the internal user authentication cache.

A CacheEntry event is fired for every record in the internal user authentication cache.

The internal authentication cache can be used as an alternative to the GetUserPassword event, automatically checking the cache against the security parameters provided in the request signature.

The ShowCache method is used to show the contents of the internal authentication cache.

The ClearCache method can be used to completely clear the cache.

IPWorksSSNMPException

value

public java.lang.String value(java.lang.String OID)
                       throws IPWorksSSNMPException

Returns the value corresponding to an OID.

If the OID does not exist in the ObjId array, a trappable error is generated.

Please refer to the ObjId and ObjValue properties for more information.

IPWorksSSNMPException

addSnmpagentEventListener

public void addSnmpagentEventListener(SnmpagentEventListener l)
                               throws java.util.TooManyListenersException

java.util.TooManyListenersException

removeSnmpagentEventListener

public void removeSnmpagentEventListener(SnmpagentEventListener l)