snmp_mgr

MODULE

snmp_mgr

MODULE SUMMARY

SNMP Manager

DESCRIPTION

The module snmp_mgr provides a simple SNMP (Simple Network Management Protocol) manager. It is used for test purposes during agent development. There are two modes of operation. First, it can be used as a simple command line manager. Second, it can be used to write test suites for testing the MIB implementation in the SNMP agent.

The command line manager uses the Erlang shell. It supports all SNMPv1 requests, i.e. set, get and get-next. For example, snmp_mgr:s([{[1,2,3,0], "hej"}]), sends a set request to the agent and snmp_mgr:g([[1,2,3,0], [myVar,0]]) gets two values. The manager operates asynchronously. This implies that the return value of most functions is nonsense. When the manager gets a response message from the agent, it is echoed to the display.

The start-up option quiet tells the manager not to display incoming SNMP responses and traps. Messages are sent to the Erlang process that started the manager. This makes it possible to process them from an application or a test suite.

Use the expect function (that operates on the message queue) to write test suites. Examples of how to write a test suite can be found in snmp_mgr_tests.erl.

MIBs (Management Information Base) can be loaded in the manager. There are two reasons for doing this. OBJECT IDENTIFIERs (Oids) can be entered in symbolic form. Example: instead of [1,3,6,1,2,1,1,1], the symbolic name sysDescr can be used. The other reason is to take advantage of the type information in the MIB when sending set requests.

An Oid is represented as a list. For convenience, nested lists are allowed. There is one exception though. If an oid is entered in symbolic form, this symbol must be the first item in the list. A symbolic name includes the complete path from the top of the global naming tree. Accordingly, an oid can only contain one symbolic name.

Examples of valid Oids are: [myVar, 0], [1,2,3,4,5,0], [myColumn, 95], [myTable, 4, 123, [5|"eklas"]].

The last example refers to column 4 of the row with the two keys 123 and [5|"eklas"] of table myTable.

Known bug: There is not yet a {timeout, Msecs} option.

EXPORTS

expect(Id, What) -> ok | {error, Id, Reason}
expect(Id, ErrorStatus,ErrorIndex,Varbinds)
expect(Id, trap, Enterp, Generic, Specific, Varbinds)

Types:
Id = term()
What = any|trap|timeout|Varbinds|ErrorStatus
ErrorIndex = integer()
Enterp = oid()
Generic = integer()
Specific = integer()

• Id is used to help identifying this particular test in a long test suite. It is not used by the manager.
  
• The atom any makes the test succeed for any response.
  
• timeout succeeds if the message queue is empty for 3.5 seconds. This can be used to ensure that no messages are pending.
  
• ErrorStatus is an atom which describes an error message. See documentation for the SNMP agent.
  
• Varbinds is a list of {Oid, Value}|{Oid,any}.
  

If a response other than the expected one is received, an error message is displayed and and {error, Id, Reason} is returned. A call to expect is normally directly preceeded by sending a message.

g(Oids) -> void()

Types:
Oids = [oid()]

Sends a get-request.

gb(NonRepeaters, MaxRepetitions, Oids) -> void()

Types:
NonRepeaters = integer()
MaxRepetitions = integer()
Oids = [oid()]

Sends a get-bulk-request (See RFC1905).

gn(Oids) -> void()

Types:
Oids = [oid()]

Sends a get-next-request.

gn() -> void()

Sends yet another get-next-request constructed from the previous response. This is a nice feature for manually traversing a MIB.

gn(N) -> void()

Types:
N = integer()

Sends N get-next-request requests.

The last response is used as the start value. Works somewhat like a get-bulk-request (see SNMPv2).

r() -> void()

Resends the last request.

s(Varbinds) -> void()

Types:
Varbinds = [varbind()]

Sends a set-request.

Varbind is:

• {Oid, Value} if the object with Oid Oid is loaded by the manager.
  
• {Oid, TypeTag, Value} where TypeTag is s|o|i (String, Oid, Integer). This syntax is used if this object isn't defined in a MIB loaded by the manager. (Or if you explicitly want to send a request of wrongly typed data.)
  

start(Options)
start_link(Options) -> void()

Types:
Options = [options()]

Starts the SNMP manager.

Mandatary options are:

• {agent, Agent} - where Agent is the IP address of the agent {int(),int(),int(),int()} or the name of the host (string()).
  

Optional options are:

• {agent_udp, int()} - the UDP port that the agent listens to. Default is 4000.
  
• {trap_udp, int()} - the UDP port where the manager will receive traps. Default is 5000.
  
• {community, string()} - the community string that is sent in the requests from the manager. Default is "public".
  
• {mibs, List of filename} - MIBs to be loaded in the manager. Default is no MIBs. The MIBs must be compiled.
  
• {receive_type, pdu | msg} - defines the format of delivered messages. Default is pdu.
  
• quiet - incoming responses are not displayed. Messages are sent to the Erlang process that started the manager. The format of the message depends on the value of receive_type. If it is pdu (default), message is {snmp_pdu, PDU} where PDU is a pdu() or a trappdu() record defined in snmp_types.hrl. If it is msg, message is {snmp_msg, Msg, Ip, Udp}. Default is that this option is not present, i.e. all incoming requests are displayed. This option must be present when running test suites.
  
• v1|v2 - what SNMP version to use. Default is v1.
  

stop() -> void()

Stops the SNMP manager.

AUTHORS

Martin Björklund - mbj@erlang.ericsson.se
Klas Eriksson - eklas@erlang.ericsson.se