# 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

snmp 3.4
Copyright © 1991-2003 Ericsson Utvecklings AB