![[Ericsson AB]](min_head.gif)
The module snmpa contains interface functions to the
SNMP agent.
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.
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.
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.
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()
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()
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).
Types:
Result = [atom()]
Types:
Result = [atom()]
Types:
Result = [atom()]
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()
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.
calendar(3), erlc(1)