![[Ericsson AB]](min_head.gif)
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).
The following datatypes are used in the functions below:
oid() = [byte()]
The oid() type is used to represent an ASN.1 OBJECT
IDENTIFIER.
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()} |
{verbosity, silence|warning|info|log|debug|trace}
dir() = string()
BinFileName = string()
Compiles the specified MIB file <File>.mib. The
compiled file BinFileName is called <File>.bin.
db specifies which database should
be used for the default instrumentation. Default is
volatile.
i specifies the path to search for
imported (compiled) MIB files. The directories should be
strings with a trailing directory delimiter. Default is
["./"].
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.
warnings specifies whether warning
messages should be shown. Default is true.
verbosity specifies the verbosity of
the SNMP mib compiler. I.e. if warning, info, log, debug
and trace messages shall be shown. Default is silence.
Note that if the option warnings is true and the
option verbosity is silence, warning messages will
still be shown.
group_check specifies whether the
mib compiler should check the OBJECT-GROUP macro and
the NOTIFICATION-GROUP macro for correctness or not.
Default is true.
deprecated specifies if a deprecated
definition should be kept or not. If the option is
false the MIB compiler will ignore all deprecated
definitions. Default is true.
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.
Note that if the agent shall support version 3, then the crypto app must be started before running this function (password generation).
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_dst(DateAndTime) -> [utc()]
Types:
DateAndTime = [int()]
utc() = {{Y,Mo,D},{H,M,S}}
Converts a DateAndTime list to a list of possible universal time(s). 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.
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.
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.
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_dst(Local) -> [DateAndTime]
Types:
Local = {{Y,Mo,D},{H,M,S}}
DateAndTime = [int()]
Converts a local time value to a list of possible DateAndTime list(s). 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.
calendar(3), erlc(1)