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 manager supports SNMPv1, SNMPv2c and SNMPv3, including authentication and privacy.

The command line manager uses the Erlang shell. It supports all SNMPv1, v2 and v3 requests, i.e. set, get, get-next and get-bulk. 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, traps and informs. 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)
expect(Id, v2trap, Varbinds)
expect(Id, report, Varbinds)
expect(Id, {inform, InformReply}, Varbinds)

Types:
Id = term()
What = any|trap|timeout|Varbinds|ErrorStatus
ErrorIndex = integer()
Enterp = oid()
Generic = integer()
Specific = integer()
InformReply = true | false | {error, ErrorStatus, ErrorIndex}

• 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.

The reply to a received Inform request can be controlled. If InformReply is true, a noError reply is sent. If it is false no reply is sent. If it is {error, ErrorStatus, ErrorIndex}, a reply indicating the error is sent.

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()

Resend the last request.

oid_to_name(Oid) -> {ok, Name} | {error, Reason}

Types:
Oid = oid()
Name = atom()

Transform a oid to it's aliasname.

name_to_oid(Name) -> {ok, Oid} | {error, Reason}

Types:
Name = atom()
Oid = oid()

Transform a aliasname to it's oid.

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 is not 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".
  


• {context, string()} - the context that is sent in v3 requests from the manager. Default is "".
  


• {user, string()} - the USM user name that is sent in v3 requests from the manager. Default is "initial".
  


• {engine_id, string()} - the engine ID of the agent. Used in v3 only. Default is "agentEngine".
  


• {context_engine_id, string()} - the context engine ID used in v3 requests. Default is the same as engine_id.
  


• {sec_level, noAuthNoPriv + authNoPriv | authPriv} - the requested security level. Used in v3 only. Default is noAuthNoPriv.
  


• {dir, string()} - the directory where the file usm.conf is located. This file is only needed if v3 is used. The file has the same syntax as the usm.conf file for the agent.
  


• {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 the value is pdu (default),the message is {snmp_pdu, PDU} where PDU is a pdu() or a trappdu() record defined in snmp_types.hrl. If the value is msg, the message is {snmp_msg, Msg, Ip, Udp}. If the request was issued with an erroneous oid, the message is {oid_error, Reason}, where Reason is a printable string. Default is, this option is not present, i.e. all incoming requests are displayed. This option must be present when running test suites.
  


• v1|v2|v3 - what SNMP version to use. Default is v1.
  


• {recbuf, integer()} - defines the size of a UDP socket receive buffer.
  This is important when sending large regusts to the agent (i.e. requests which will gererate large responses).
  Also consider the max size of the agents outgoing message (defined e.g. by snmpEngineMaxMessageSize in SNMP-FRAMEWORK-MIB). Default is 1024.
  

stop() -> void()

Stops the SNMP manager.

AUTHORS

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