# snmpa

### MODULE

snmpa

### MODULE SUMMARY

Interface Functions to the SNMP toolkit agent

### DESCRIPTION

The module `snmpa` contains interface functions to the SNMP agent.

### Common Data Types

The following datatypes are used in the functions below:

- `oid() = [byte()]`

The `oid()` type is used to represent an ASN.1 OBJECT IDENTIFIER.

### EXPORTS

`add_agent_caps(SysORID, SysORDescr) -> SysORIndex`

Types:

`SysORID = oid()`
`SysORDescr = string()`
`SysORIndex = integer()`

This function can be used to add an AGENT-CAPABILITY statement to the sysORTable in the agent. The table is defined in the SNMPv2-MIB.

`del_agent_caps(SysORIndex) -> void()`

Types:

`SysORIndex = integer()`

This function can be used to delete an AGENT-CAPABILITY statement to the sysORTable in the agent. This table is defined in the SNMPv2-MIB.

`get_agent_caps() -> [[SysORIndex, SysORID, SysORDescr, SysORUpTime]]`

Types:

`SysORIndex = integer()`
`SysORId = oid()`
`SysORDescr = string()`
`SysORUpTime = integer()`

Returns all AGENT-CAPABILITY statements in the sysORTable in the agent. This table is defined in the SNMPv2-MIB.

`get(Agent,Vars) -> Values | {error, Reason}`
`get(Agent,Vars,Context) -> Values | {error, Reason}`

Types:

`Agent = pid() | atom()`
`Vars = [oid()]`
`Context = string()`
`Values = [term()]`
`Reason = {atom(), oid()}`

Performs a GET operation on the agent. All loaded MIB objects are visible in this operation. The agent calls the corresponding instrumentation functions just as if it was a GET request coming from a manager.

Note that the request specific parameters (such as `snmpa:current_request_id/0` are not accessible for the instrumentation functions if this function is used.

`get_next(Agent,Vars) -> Values | {error, Reason}`
`get_next(Agent,Vars,Context) -> Values | {error, Reason}`

Types:

`Agent = pid() | atom()`
`Vars = [oid()]`
`Context = string()`
`Values = [{oid(), term()}]`
`Reason = {atom(), oid()}`

Performs a GET-NEXT operation on the agent. All loaded MIB objects are visible in this operation. The agent calls the corresponding instrumentation functions just as if it was a GET request coming from a manager.

Note that the request specific parameters (such as `snmpa:current_request_id/0` are not accessible for the instrumentation functions if this function is used.

`get_symbolic_store_db() -> Db`

Types:

`Db = term()`

Retrieve the symbolic store database reference. This is used for faster access to the database using the functions: `int_to_enum/3`, `enum_to_int/3`, `name_to_oid/2`, `oid_to_name/2`.

`info() -> [{Key, Value}]`
`info(Agent) -> [{Key, Value}]`

Types:

`Agent = pid() | atom()`

Returns a list (a dictionary) containing information about the agent. Information includes loaded MIBs, registered subagents, some information about the memory allocation.

`load_mibs(Mibs) -> ok | {error, Reason}`
`load_mibs(Agent,Mibs) -> ok | {error, Reason}`

Types:

`Agent = pid() | atom()`
`Mibs = [MibName]`
`MibName = string()`
`Reason = term()`

Loads `Mibs` into an agent. If the agent cannot load all MIBs, it will indicate where loading was aborted. The `MibName` is the name of the Mib, including the path to where the compiled mib is found. For example,

              Dir = code:priv_dir(my_app) ++ "/mibs/",
              snmpa:load_mibs(snmp_master_agent, [Dir ++ "MY-MIB"]).

`unload_mibs(Mibs) -> ok | {error, Reason}`
`unload_mibs(Agent,Mibs) -> ok | {error, Reason}`

Types:

`Agent = pid() | atom()`
`Mibs = [MibName]`
`MibName = string()`

Unloads MIBs into an agent. If it cannot unload all MIBs, it will indicate where unloading was aborted.

`which_mibs() -> Mibs`
`which_mibs(Agent) -> Mibs`

Types:

`Agent = pid() | atom()`
`Mibs = [{MibName, MibFile}]`
`MibName = atom()`
`MibFile = string()`

Retrieve the list of all the mibs loaded into this agent. Default is the master agent.

`whereis_mib(MibName) -> {ok, MibFile} | {error, Reason}`
`whereis_mib(Agent, MibName) -> {ok, MibFile} | {error, Reason}`

Types:

`Agent = pid() | atom()`
`MibName = atom()`
`MibFile = string()`
`Reason = term()`

Get the full path to the (compiled) mib-file.

`enum_to_int(Name,Enum) -> {value, Int} | false`
`enum_to_int(Db,Name,Enum) -> {value, Int} | false`

Types:

`Db = term()`
`Name = atom()`
`Enum = atom()`
`Int = int()`

Converts the symbolic value `Enum` to the corresponding integer of the enumerated object or type `Name` in a MIB. The MIB must be loaded.

`false` is returned if the object or type is not defined in any loaded MIB, or if it does not define the symbolic value as enumerated.

`Db` is a reference to the symbolic store database (retrieved by a call to `get_symbolic_store_db/0`).

`int_to_enum(Name,Int) -> {value, Enum} | false`
`int_to_enum(Db,Name,Int) -> {value, Enum} | false`

Types:

`Db = term()`
`Name = atom()`
`Int = int()`
`Enum = atom()`

Converts the integer `Int` to the corresponding symbolic value of the enumerated object or type `Name` in a MIB. The MIB must be loaded.

`false` is returned if the object or type is not defined in any loaded MIB, or if it does not define the symbolic value as enumerated.

`Db` is a reference to the symbolic store database (retrieved by a call to `get_symbolic_store_db/0`).

`name_to_oid(Name) -> {value, oid()} | false`
`name_to_oid(Db,Name) -> {value, oid()} | false`

Types:

`Db = term()`
`Name = atom()`

Looks up the OBJECT IDENTIFIER of a MIB object, given the symbolic name. Note, the OBJECT IDENTIFIER is given for the object, not for an instance.

`false` is returned if the object is not defined in any loaded MIB.

`Db` is a reference to the symbolic store database (retrieved by a call to `get_symbolic_store_db/0`).

`oid_to_name(OID) -> {value, Name} | false`
`oid_to_name(Db,OID) -> {value, Name} | false`

Types:

`Db = term()`
`OID = oid()`
`Name = atom()`

Looks up the symbolic name of a MIB object, given OBJECT IDENTIFIER.

`false` is returned if the object is not defined in any loaded MIB.

`Db` is a reference to the symbolic store database (retrieved by a call to `get_symbolic_store_db/0`).

`which_aliasnames() -> Result`

Types:

`Result = [atom()]`

Retrieve all alias-names known to the agent.

`log_to_txt(LogDir, Mibs)`
`log_to_txt(LogDir, Mibs, OutFile) -> ok | {error, Reason}`
`log_to_txt(LogDir, Mibs, OutFile, LogName) -> ok | {error, Reason}`
`log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile) -> ok | {error, Reason}`
`log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start) -> ok | {error, Reason}`
`log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop) -> ok | {error, Reason}`

Types:

`LogDir = string()`
`Mibs = [MibName]`
`MibName = string()`
`OutFile = string()`
`LogName = string()`
`LogFile = string()`
`Start = Stop = null | datetime() | {local_time,datetime()} | {universal_time,datetime()}`
`Reason = term()`

Converts an Audit Trail Log to a readable text file. `OutFile` defaults to "./snmpa_log.txt". `LogName` defaults to "snmpa_log". `LogFile` defaults to "snmpa.log". See snmp:log_to_txt for more info.

`change_log_size(NewSize) -> ok | {error, Reason}`

Types:

`NewSize = {MaxBytes, MaxFiles}`
`MaxBytes = integer()`
`MaxFiles = integer()`
`Reason = term()`

Changes the log size of the Audit Trail Log. The application must be configured to use the audit trail log function. Please refer to disk_log(3) in Kernel Reference Manual for a description of how to change the log size.

The change is permanent, as long as the log is not deleted. That means, the log size is remebered across reboots.

`mib_of(Oid) -> {ok, MibName} | {error, Reason}`
`mib_of(Agent, Oid) -> {ok, MibName} | {error, Reason}`

Types:

`Agent = pid() | atom()`
`Oid = oid()`
`MibName = atom()`
`Reason = term()`

Finds the mib corresponding to the `Oid`. If it is a variable, the Oid must be <Oid for var>.0 and if it is a table, Oid must be <table>.<entry>.<col>.<any>

`me_of(Oid) -> {ok, Me} | {error, Reason}`
`me_of(Agent, Oid) -> {ok, Me} | {error, Reason}`

Types:

`Agent = pid() | atom()`
`Oid = oid()`
`Me = #me{}`
`Reason = term()`

Finds the mib entry corresponding to the `Oid`. If it is a variable, the Oid must be <Oid for var>.0 and if it is a table, Oid must be <table>.<entry>.<col>.<any>

`register_notification_filter(Id, Mod, Data) -> ok | {error, Reason}`
`register_notification_filter(Agent, Id, Mod, Data) -> ok | {error, Reason}`
`register_notification_filter(Id, Mod, Data, Where) -> ok | {error, Reason}`
`register_notification_filter(Agent, Id, Mod, Data, Where) -> ok | {error, Reason}`

Types:

`Agent = pid() | atom()`
`Id = filter_id()`
`filter_id() = term()`
`Mod = atom()`
`Data = term()`
`Where = filter_position()`
`Reason = term()`
`filter_position() = first | last | {insert_before, filter_id()} | {insert_after, filter_id()}`

Registers a notification filter.

`Mod` is a module implementing the `snmpa_notification_filter` behaviour.

`Data` will be passed on to the filter when calling the functions of the behaviour.

`unregister_notification_filter(Id) -> ok | {error, Reason}`
`unregister_notification_filter(Agent, Id) -> ok | {error, Reason}`

Types:

`Agent = pid() | atom()`
`Id = filter_id()`
`filter_id() = term()`

Unregisters a notification filter.

`which_notification_filter() -> Filters`
`which_notification_filter(Agent) -> Filters`

Types:

`Agent = pid() | atom()`
`Filters = [filter_id()]`
`filter_id() = term()`

List all notification filters in an agent.

`register_subagent(Agent,SubTreeOid,Subagent) -> ok | {error, Reason}`

Types:

`Agent = pid() | atom()`
`SubTreeOid = oid()`
`SubAgent = pid()`

Registers a subagent under a subtree of another agent.

It is easy to make mistakes when registering subagents and this activity should be done carefully. For example, a strange behaviour would result from the following configuration:

    snmp_agent:register_subagent(MAPid,[1,2,3,4],SA1),
    snmp_agent:register_subagent(SA1,[1,2,3], SA2).

`SA2` will not get requests starting with object identifier `[1,2,3]` since `SA1` does not.

`unregister_subagent(Agent,SubagentOidOrPid) -> ok | {ok, SubAgentPid} | {error, Reason}`

Types:

`Agent = pid() | atom()`
`SubTreeOidorPid = oid() | pid()`

Unregisters a subagent. If the second argument is a pid, then that subagent will be unregistered from all trees in `Agent`.

`send_notification(Agent,Notification,Receiver)`
`send_notification(Agent,Notification,Receiver,Varbinds)`
`send_notification(Agent,Notification,Receiver, NotifyName,Varbinds)`
`send_notification(Agent,Notification,Receiver, NotifyName,ContextName,Varbinds) -> void()`

Types:

`Agent = pid() | atom()`
`Notification = atom()`
`Receiver = no_receiver | {Tag, Recv}`
`Tag = term()`
`Recv = pid() | atom() | {Mod,Func,Args}`
`Mod = atom()`
`Func = atom()`
`Args = list()`
`NotifyName = string()`
`ContextName = string()`
`Varbinds = [Varbind]`
`Varbind = {Variable, Value} | {Column, RowIndex, Value} | {OID, Value}`
`Variable = atom()`
`Column = atom()`
`OID = oid()`
`Value = term()`
`RowIndex = [int()]`

Sends the notification `Notification` to the management targets defined for `NotifyName` in the `snmpNotifyTable` in SNMP-NOTIFICATION-MIB from the specified context. If no `NotifyName` is specified (or if it is `""`), the notification is sent to all management targets. If no `ContextName` is specified, the default `""` context is used.

The parameter `Receiver` specifies where information about delivery of Inform-Requests should be sent. The agent sends Inform-Requests and waits for acknowledgements from the managers. If the `Receiver` is specified as `no_receiver`, nothing is sent. Otherwise, it is specified as `{Tag, Recv}`. The receiver (`Recv`) gets a message:

- `{snmp_targets, Tag, Addresses}`

`Addresses` is a list of management target addresses. If UDP over IP is used, this is a 2-tuple `{IP, UDPport}`, where `IP` is a 4-tuple with the IP address, and `UDPport` is an integer. The notification is sent as an Inform-Request to each target address in `Addresses`. If there are no targets for which an Inform-Request is sent, `Addresses` is the empty list `[]`.

For each such `Address` is the `Addresses` list, one of the following two messages is sent to `Recv`:

- `{snmp_notification, Tag, {got_response, Address}}`
- `{snmp_notification, Tag, {no_response, Address}}`

The optional argument `Varbinds` defines values for the objects in the notification. If no value is given for an object, the `Agent` performs a get-operation to retrieve the value.

`Varbinds` is a list of `Varbind`, where each `Varbind` is one of:

- `{Variable, Value}`, where `Variable` is the symbolic name of a scalar variable referred to in the notification specification.
- `{Column, RowIndex, Value}`, where `Column` is the symbolic name of a column variable. `RowIndex` is a list of indices for the specified element. If this is the case, the OBJECT IDENTIFIER sent in the notification is the `RowIndex` appended to the OBJECT IDENTIFIER for the table column. This is the OBJECT IDENTIFIER which specifies the element.
- `{OID, Value}`, where `OID` is the OBJECT IDENTIFIER for an instance of an object, scalar variable, or column variable.

For example, to specify that `sysLocation` should have the value `"upstairs"` in the notification, we could use one of:

- `{sysLocation, "upstairs"}` or
- `{[1,3,6,1,2,1,1,6,0], "upstairs"}` or
- `{?sysLocation_instance, "upstairs"}` (provided that the generated `.hrl` file is included)

If a variable in the notification is a table element, the `RowIndex` for the element must be given in the `Varbinds` list. In this case, the OBJECT IDENTIFIER sent in the notification is the OBJECT IDENTIFIER that identifies this element. This OBJECT IDENTIFIER could be used in a get operation later.

This function is asynchronous, and does not return any information. If an error occurs, `user_err/2` of the error report module is called and the notification is discarded.

`send_trap(Agent,Trap,Community)`
`send_trap(Agent,Trap,Community,Varbinds) -> void()`

Types:

`Agent = pid() | atom()`
`Trap = atom()`
`Community = string()`
`Varbinds = [Varbind]`
`Varbind = {Variable, Value} | {Column, RowIndex, Value} | {OID, Value}`
`Variable = atom()`
`Column = atom()`
`OID = oid()`
`Value = term()`
`RowIndex = [int()]`

Note! This function is only kept for backwards compatibility reasons. Use `send_notification` instead.

Sends the trap `Trap` to the managers defined for `Community` in the `intTrapDestTable` in OTP-SNMPEA-MIB. The optional argument `Varbinds` defines values for the objects in the trap. If no value is given for an object, the `Agent` performs a get-operation to retrieve the value.

`Varbinds` is a list of `Varbind`, where each `Varbind` is one of:

- `{Variable, Value}`, where `Variable` is the symbolic name of a scalar variable referred to in the trap specification.
- `{Column, RowIndex, Value}`, where `Column` is the symbolic name of a column variable. `RowIndex` is a list of indices for the specified element. If this is the case, the OBJECT IDENTIFIER sent in the trap is the `RowIndex` appended to the OBJECT IDENTIFIER for the table column. This is the OBJECT IDENTIFIER which specifies the element.
- `{OID, Value}`, where `OID` is the OBJECT IDENTIFIER for an instance of an object, scalar variable, or column variable.

For example, to specify that `sysLocation` should have the value `"upstairs"` in the trap, we could use one of:

- `{sysLocation, "upstairs"}` or
- `{[1,3,6,1,2,1,1,6,0], "upstairs"}` or
- `{?sysLocation_instance, "upstairs"}` (provided that the generated `.hrl` file is included)

If a variable in the trap is a table element, the `RowIndex` for the element must be given in the `Varbinds` list. In this case, the OBJECT IDENTIFIER sent in the trap is the OBJECT IDENTIFIER that identifies this element. This OBJECT IDENTIFIER could be used in a get operation later.

This function is asynchronous, and does not return any information. If an error occurs, `snmp_error:user_err/2` is called and the trap is discarded.

`verbosity(Ref,Verbosity) -> void()`

Types:

`Ref = pid() | sub_agents | master_agent | net_if | mib_server | symbolic_store | note_store | local_db`
`Verbosity = verbosity() | {subagents, verbosity()}`
`verbosity() = silence | info | log | debug | trace`

Sets verbosity for the designated process. For the lowest verbosity `silence`, nothing is printed. The higher the verbosity, the more is printed.

### See Also

calendar(3), erlc(1)

### AUTHORS

Micael Karlberg - support@erlang.ericsson.se

snmp 4.1.1
Copyright © 1991-2005 Ericsson AB