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.

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.

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.

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.

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.

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, snmp_error:user_err/2 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