# 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 current_request_id) 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`.

`backup(BackupDir) -> ok | {error, Reason}`
`backup(Agent, BackupDir) -> ok | {error, Reason}`

Types:

`BackupDir = string()`
`Agent = pid() | atom()`

Backup persistent/permanent data handled by the agent (such as local-db, mib-data and vacm).

Data stored by mnesia is not handled.

BackupDir cannot be identical to DbDir.

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

As of version 4.4 the format of the info has been changed. To convert the info to the old format, call the old_info_format.

`old_info_format(NewInfo) -> OldInfo`

Types:

`OldInfo = NewInfo = [{Key, Value}]`

As of version 4.4 the format of the info has been changed. This function is used to convert to the old (pre-4.4) info format.

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

`current_request_id() -> {value, RequestId} | false`
`current_context() -> {value, Context} | false`
`current_community() -> {value, Community} | false`
`current_address() -> {value, Address} | false`

Types:

`RequestId = integer()`
`Context = string()`
`Community = string()`
`Address = term()`

Get the request-id, context, community and address of the request currently beeing processed by the agent.

Note that these functions is intended to be called by the instrumentation functions and only if they are executed in the context of the agent process (e.g. it does not work if called from a spawned process).

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

`which_tables() -> Result`

Types:

`Result = [atom()]`

Retrieve all tables known to the agent.

`which_variables() -> Result`

Types:

`Result = [atom()]`

Retrieve all variables 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 = disk_log_open_error() | file_open_error() | term()`
`disk_log_open_error() = {LogName, term()}`
`file_open_error() = {OutFile, 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.

`convert_config(OldConfig) -> AgentConfig`

Types:

`OldConfig = list()`
`AgentConfig = list()`

This off-line utility function can be used to convert the old snmp application config (pre snmp-4.0) to the new snmp agent config (as of snmp-4.0).

For information about the old config (`OldConfig`) see the OTP R9C documentation.

For information about the current agent config (`AgentConfig`), see either the SNMP application part of the reference manual or the Configuring the application chapter of the SNMP user's guide.

`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.7.4
Copyright © 1991-2006 Ericsson AB