# snmp

### MODULE

snmp

### MODULE SUMMARY

Interface Functions to the SNMP toolkit

### DESCRIPTION

The module `snmp` contains interface functions to the SNMP toolkit. Some functions are off-line functions (e.g. `c` to compile a MIB), and some are functions called by instrumentation functions in a target system (e.g. `current_address`).

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

`c(File)`
`c(File,Options) -> {ok, BinFileName} | {error, Reason}`

Types:

`File = string()`
`Options = [opt()]`
`opt() = {db, volatile|persistent|mnesia} | {i, [dir()]} | {il, [dir()]} | {outdir, dir()} | {warnings, bool()} | {group_check, bool()} | {deprecated, bool()} | {description, bool()}`
`dir() = string()`
`BinFileName = string()`

Compiles the specified MIB file `<File>.mib`. The compiled file `BinFileName` is called `<File>.bin`.

- The option `db` specifies which database should be used for the default instrumentation. Default is `volatile`.
- The option `i` specifies the path to search for imported (compiled) MIB files. The directories should be strings with a trailing directory delimiter. Default is `["./"]`.
- The option `il` (include_lib) also specifies a list of directories to search for imported MIBs. It assumes that the first element in the directory name corresponds to an OTP application. The compiler will find the current installed version. For example, the value ["snmp/mibs/"] will be replaced by ["snmp-3.1.1/mibs/"] (or what the current version may be in the system). The current directory and the `<snmp-home>/priv/mibs/` are always listed last in the include path.
- The option `warnings` specifies whether warning messages should be shown. Default is `true`.
- The option `group_check` specifies whether the mib compiler should check the OBJECT-GROUP macro for correctness or not. Default is `true`.
- The option `deprecated` specifies if a deprecated definition should be ignored or not. If the option is true will the MIB-compilator ignore all deprecated definitions. Default is `false`.
- The option `description` specifies if the text of the DESCRIPTION field will be included or not. Default is `false`, in which case the description will be replaced by the atom `undefined`.

The MIB compiler understands both SMIv1 and SMIv2 MIBs. It uses the `MODULE-IDENTITY` statement to determine if the MIB is version 1 or 2.

The MIB compiler can be invoked from the OS command line by using the command `erlc`. `erlc` recognises the extension `.mib`, and invokes the SNMP MIB compiler for files with that extension. The options `db`, `group_check` and `deprecated` have to be specified to `erlc` using the syntax `+term`. See `erlc(1)` for details.

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

Types:

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

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.

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

A simple interactive SNMP agent configuration tool. Simple configuration files can be generated, but more complex configurations still have to be edited manually.

The tool is a textual based tool that asks some questions and generates `sys.config` and `*.conf` files.

`current_address() -> {value, {IP, UDP}} | false`

Types:

`IP = [int(), int(), int(), int()]`
`UDP = int()`

Retrieves the IP address of the management station sending the request. It must be called from the same process that is handling the request (normally an instrumentation function).

Returns `false` if no request is currently handled.

`current_community() -> {value, Community} | false`

Types:

`Community = string()`

Retrieves the community referred to in the current request. It must be called from the same process that is handling the request (normally an instrumentation function).

Returns `false` if no request is currently handled.

NOTE: This function should only be used if the agent speaks SNMPv1 or SNMPv2c only. Otherwise, use `current_context/0`.

`current_context() -> {value, ContextName} | false`

Types:

`ContextName = string()`

Retrieves the context referred to in the current request. It must be called from the same process that is handling the request (normally an instrumentation function).

Returns `false` if no request is currently handled.

`current_net_if_data() -> {value, NetIfData} | false`

Types:

`NetIfData = term()`

Retrieves the Net_if data for the current pdu being handled. This data is defined in the Net_if process, and can be used to forward information about the packet to the instrumentation functions. With the default Net_if implementation, it is nil. It must be called from the same process that handles the request (normally an instrumentation function).

Returns `false` if no request is currently handled.

`current_request_id() -> {value, RequestId} | false`

Types:

`RequestId = int()`

Retrieves the request Id of the current request. It must be called from the same process that is handling the request (normally an instrumentation function).

Returns `false` if no request is currently handled.

`date_and_time() -> DateAndTime`

Types:

`DateAndTime = [int()]`

Returns current date and time as the data type DateAndTime, as specified in RFC1903. This is an OCTET STRING.

`date_and_time_to_universal_time(DateAndTime) -> UTC`

Types:

`DateAndTime = [int()]`
`UTC = {{Y,Mo,D},{H,M,S}}`

Converts a DateAndTime list to universal time. The unversal time value on the same format as defined in calendar(3).

`date_and_time_to_string(DateAndTime) -> string()`

Types:

`DateAndTime = [int()]`

Converts a DateAndTime list to a printable string, according to the DISPLAY-HINT definition in RFC1903.

`debug(Agent,Bool) -> void()`

Types:

`Agent = pid() | atom()`
`Bool = bool()`

Turns debugging of the agent on/off. Debug information is printed whenever an instrumentation function is called, and when a packet is received or sent. This actually sets verbosity to `log` or `silence` for the snmp_master_agent and snmp_net_if.

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

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

Types:

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

`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. `Db` is a reference to the symbolic store database (retrieved by a call to `get_symbolic_store_db/0<c>). <p><c>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.

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

Types:

`Agent = pid() | atom()`
`Vars = [oid()]`
`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. That the request specific parameters (such as `snmp:current_request_id/0` are not accessible for the instrumentation functions if this function is used.

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

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

Types:

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

`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. `Db` is a reference to the symbolic store database (retrieved by a call to `get_symbolic_store_db/0<c>). <p><c>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.

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

Types:

`Mibs = [MibName]`
`MibName = string()`

Checks for multiple usage of object identifiers and traps between MIBs.

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

Types:

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

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/",
              snmp:load_mibs(snmp_master_agent, [Dir ++ "MY-MIB"]).

`local_time_to_date_and_time(Local) -> DateAndTime`

Types:

`Local = {{Y,Mo,D},{H,M,S}}`
`DateAndTime = [int()]`

Converts a local time value to a DateAndTime list. The local time value on the same format as defined in calendar(3).

`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]`
`OutFile = string()`
`MibName = string()`
`LogName = string()`
`LogFile = string()`
`Start = Stop = null | datetime() | {local_time,datetime()} | {universal_time,datetime()}`

Converts an Audit Trail Log to a readable text file, where each item has a trailing TAB character, and any TAB character in the body of an item has been replaced by ESC TAB.

The function can be used on a running system, or by copying the entire log directory and calling this function. SNMP must be running in order to provide MIB information.

`LogDir` is the name of the directory where the audit trail log is stored. `Mibs` is a list of Mibs to be used. The function uses the information in the Mibs to convert for example object identifiers to their symbolic name. `OutFile` is the name of the generated textfile. It defaults to `"./snmp_log.txt"`. `LogName` is the name of the log (default is `"snmp log"`), `LogFile` is the name of the log file (default is `"snmp.log"`). `Start` is the start (first) date and time from which log events will be converted and `Stop` is the stop (last) date and time to which log events will be converted.

The format of an audit trail log text item is as follows:

`Tag Addr - Community [TimeStamp] Vsn`
`PDU`

where `Tag` is `request`, `response`, `report`, `trap` or `inform`; Addr is `IP:Port` (or comma space separated list of such); `Community` is the community parameter (SNMP version v1 and v2), or `SecLevel:"AuthEngineID":"UserName"` (SNMP v3); `TimeStamp` is a date and time stamp, and `Vsn` is the SNMP version. `PDU` is a textual version of the protocol data unit. There is a new line between `Vsn` and `PDU`.

`mib_to_hrl(MibName) -> ok | {error, Reason}`

Types:

`MibName = string()`

Generates a `.hrl` file with definitions of Erlang constants for the objects in the MIB. The `.hrl` file is called `<MibName>.hrl`. The MIB must be compiled, and present in the current directory.

The `mib_to_hrl` generator can be invoked from the OS command line by using the command `erlc`. `erlc` recognises the extension `.bin`, and invokes this function for files with that extension.

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

Types:

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

`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. `Db` is a reference to the symbolic store database (retrieved by a call to `get_symbolic_store_db/0<c>). <p><c>false` is returned if the object is not defined in any loaded MIB.

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

Types:

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

`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. `Db` is a reference to the symbolic store database (retrieved by a call to `get_symbolic_store_db/0<c>). <p><c>false` is returned if the object is not defined in any loaded MIB.

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

`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() | {M,F,A}`
`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.

`universal_time_to_date_and_time(UTC) -> DateAndTime`

Types:

`UTC = {{Y,Mo,D},{H,M,S}}`
`DateAndTime = [int()]`

Converts a universal time value to a DateAndTime list. The unversal time value on the same format as defined in calendar(3).

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

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

`validate_date_and_time(DateAndTime) bool()`

Types:

`DateAndTime = term()`

Checks if `DateAndTime` is a correct DateAndTime value, as specified in RFC1903. This function can be used in instrumentation functions to validate a DateAndTime value.

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

Types:

`Ref = pid() | snmp_master_agent | snmp_net_if | snmp_mib | snmp_symbolic_store | snmp_note_store | snmp_local_db`
`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

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

snmp 3.3.5
Copyright © 1991-2002 Ericsson Utvecklings AB