snmpa(3erl) Erlang Module Definition snmpa(3erl)
NAME
snmpa - Interface Functions to the SNMP toolkit agent
DESCRIPTION
The module snmpa contains interface functions to the SNMP agent.
DATA TYPES
oid() = [byte()]
atl_type() = read | write | read_write
notification_delivery_info() = #snmpa_notification_delivery_info{}
The oid() type is used to represent an ASN.1 OBJECT IDENTIFIER.
The record snmpa_notification_delivery_info contains the following
fields:
tag = term():
A user defined identity representing this notification send opera-
tion.
mod = module():
A module implementing the snmpa_notification_delivery_info_receiver
behaviour. The info functions of this module will be called at var-
ious stages of delivery.
extra = term():
This is any extra info the user wants to have supplied when the
functions in the callback module is called.
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 SN-
MPv2-MIB.
del_agent_caps(SysORIndex) -> void()
Types:
SysORIndex = integer()
This function can be used to delete an AGENT-CAPABILITY state-
ment 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_re-
quest_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 ob-
jects are visible in this operation. The agent calls the corre-
sponding instrumentation functions just as if it was a GET re-
quest coming from a manager.
Note that the request specific parameters (such as snmpa:cur-
rent_request_id/0 are not accessible for the instrumentation
functions if this function is used.
backup(BackupDir) -> ok | {error, Reason}
backup(Agent, BackupDir) -> ok | {error, Reason}
Types:
BackupDir = string()
Agent = pid() | atom()
Reason = backup_in_progress | term()
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.
Simultaneous backup calls are not allowed. That is, two differ-
ent processes cannot simultaneously successfully call this func-
tion. One of them will be first, and succeed. The second will
fail with the error reason backup_in_progress.
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 sub-agents,
some information about the memory allocation.
load_mib(Mib) -> ok | {error, Reason}
load_mib(Agent, Mib) -> ok | {error, Reason}
Types:
Agent = pid() | atom()
MibName = string()
Reason = already_loaded | term()
Load a single Mib into an agent. 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_mib(snmp_master_agent, Dir ++ "MY-MIB").
load_mibs(Mibs) -> ok | {error, Reason}
load_mibs(Mibs, Force) -> ok | {error, Reason}
load_mibs(Agent, Mibs) -> ok | {error, Reason}
load_mibs(Agent, Mibs, Force) -> ok | {error, Reason}
Types:
Agent = pid() | atom()
Mibs = [MibName]
Force = boolean()
MibName = string()
Reason = {'load aborted at', MibName, InternalReason}
InternalReason = already_loaded | term()
Load Mibs into an agent. If the agent cannot load all MIBs (the
default value of the Force argument is false), 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 exam-
ple,
Dir = code:priv_dir(my_app) ++ "/mibs/",
snmpa:load_mibs(snmp_master_agent, [Dir ++ "MY-MIB"]).
If Force = true then the agent will continue attempting to load
each mib even after failing to load a previous mib. Use with
care.
unload_mib(Mib) -> ok | {error, Reason}
unload_mib(Agent, Mib) -> ok | {error, Reason}
Types:
Agent = pid() | atom()
MibName = string()
Reason = not_loaded | term()
Unload a single Mib from an agent.
unload_mibs(Mibs) -> ok | {error, Reason}
unload_mibs(Mibs, Force) -> ok | {error, Reason}
unload_mibs(Agent, Mibs) -> ok | {error, Reason}
unload_mibs(Agent, Mibs, Force) -> ok | {error, Reason}
Types:
Agent = pid() | atom()
Mibs = [MibName]
Force = boolean()
MibName = string()
Reason = {'unload aborted at', MibName, InternalReason}
InternalReason = not_loaded | term()
Unload Mibs from an agent. If it cannot unload all MIBs (the de-
fault value of the Force argument is false), it will indicate
where unloading was aborted.
If Force = true then the agent will continue attempting to un-
load each mib even after failing to unload a previous mib. Use
with care.
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. De-
fault 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 re-
quest currently being processed by the agent.
Note that these functions is intended to be called by the in-
strumentation 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 enu-
merated.
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 enu-
merated.
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 sym-
bolic 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 IDENTI-
FIER.
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.
which_notifications() -> Result
Types:
Result = [{Name, MibName, Info}]
Name = atom()
MibName = atom()
Info = term()
Retrieve all notifications (and traps) known to the agent.
log_to_txt(LogDir)
log_to_txt(LogDir, Block | Mibs)
log_to_txt(LogDir, Mibs, Block | OutFile) -> ok | {ok, Cnt} | {error,
Reason}
log_to_txt(LogDir, Mibs, OutFile, Block | LogName) -> ok | {ok, Cnt} |
{error, Reason}
log_to_txt(LogDir, Mibs, OutFile, LogName, Block | LogFile) -> ok |
{ok, Cnt} | {error, Reason}
log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block | Start) ->
ok | {ok, Cnt} | {error, Reason}
log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start) -> ok
| {ok, Cnt} | {error, Reason}
log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop) -> ok
| {ok, Cnt} | {error, Reason}
log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop)
-> ok | {ok, Cnt} | {error, Reason}
Types:
LogDir = string()
Mibs = [MibName]
MibName = string()
Block = boolean()
OutFile = string()
LogName = string()
LogFile = string()
Start = Stop = null | calendar:datetime() | {local_time, cal-
endar:datetime()} | {universal_time, calendar:datetime()}
Cnt = {NumOK, NumERR}
NumOK = non_neg_integer()
NumERR = pos_integer()
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 de-
faults to "./snmpa_log.txt". LogName defaults to "snmpa_log".
LogFile defaults to "snmpa.log".
The Block option indicates if the log should be blocked during
conversion. This could be usefull when converting large logs
(when otherwise the log could wrap during conversion). Defaults
to true.
See snmp:log_to_txt for more info.
log_to_io(LogDir) -> ok | {ok, Cnt} | {error, Reason}
log_to_io(LogDir, Block | Mibs) -> ok | {ok, Cnt} | {error, Reason}
log_to_io(LogDir, Mibs, Block | LogName) -> ok | {ok, Cnt} | {error,
Reason}
log_to_io(LogDir, Mibs, LogName, Block | LogFile) -> ok | {ok, Cnt} |
{error, Reason}
log_to_io(LogDir, Mibs, LogName, LogFile, Block | Start) -> ok | {ok,
Cnt} | {error, Reason}
log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start) -> ok | {ok,
Cnt} | {error, Reason}
log_to_io(LogDir, Mibs, LogName, LogFile, Start, Stop) -> ok | {ok,
Cnt} | {error, Reason}
log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop) -> ok |
{ok, Cnt} | {error, Reason}
Types:
LogDir = string()
Mibs = [MibName]
MibName = string()
Block = boolean()
LogName = string()
LogFile = string()
Start = Stop = null | calendar:datetime() | {local_time, cal-
endar:datetime()} | {universal_time, calendar:datetime()}
Cnt = {NumOK, NumERR}
NumOK = non_neg_integer()
NumERR = pos_integer()
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 format and prints it
on stdio. LogName defaults to "snmpa_log". LogFile defaults to
"snmpa.log".
The Block option indicates if the log should be blocked during
conversion. This could be usefull when converting large logs
(when otherwise the log could wrap during conversion). Defaults
to true.
See snmp:log_to_io 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(3erl) in Kernel Reference Manual for a de-
scription 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 remembered across reboots.
set_log_type(NewType) -> {ok, OldType} | {error, Reason}
set_log_type(Agent, NewType) -> {ok, OldType} | {error, Reason}
Types:
NewType = OldType = atl_type()
Agent = pid() | atom()
Reason = term()
Changes the run-time Audit Trail log type.
Note that this has no effect on the application configuration as
defined by configuration files, so a node restart will revert
the config to whatever is in those files.
This function is primarily useful in testing/debugging scenar-
ios.
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 vari-
able, the Oid must be <Oid for var>.0 and if it is a table, Oid
must be <table>.<entry>.<col>.<any>
invalidate_mibs_cache() -> void()
invalidate_mibs_cache(Agent) -> void()
Types:
Agent = pid() | atom()
Invalidate the mib server cache.
The entire contents of the cache will be deleted.
enable_mibs_cache() -> void()
enable_mibs_cache(Agent) -> void()
Types:
Agent = pid() | atom()
Enable the mib server cache.
disable_mibs_cache() -> void()
disable_mibs_cache(Agent) -> void()
Types:
Agent = pid() | atom()
Disable the mib server cache.
which_mibs_cache_size() -> void()
which_mibs_cache_size(Agent) -> void()
Types:
Agent = pid() | atom()
Retreive the size of the mib server cache.
gc_mibs_cache() -> {ok, NumElementsGCed} | {error, Reason}
gc_mibs_cache(Agent) -> {ok, NumElementsGCed} | {error, Reason}
gc_mibs_cache(Age) -> {ok, NumElementsGCed} | {error, Reason}
gc_mibs_cache(Agent, Age) -> {ok, NumElementsGCed} | {error, Reason}
gc_mibs_cache(Age, GcLimit) -> {ok, NumElementsGCed} | {error, Reason}
gc_mibs_cache(Agent, Age, GcLimit) -> {ok, NumElementsGCed} | {error,
Reason}
Types:
Agent = pid() | atom()
Age = integer() > 0
GcLimit = integer() > 0 | infinity
NumElementsGCed = integer() >= 0
Reason = term()
Perform mib server cache gc.
Manually performs a mib server cache gc. This can be done re-
gardless of the value of the autogc option. The NumElementsGCed
value indicates how many elements where actually removed from
the cache.
enable_mibs_cache_autogc() -> void()
enable_mibs_cache_autogc(Agent) -> void()
Types:
Agent = pid() | atom()
Enable automatic gc of the mib server cache.
disable_mibs_cache_autogc() -> void()
disable_mibs_cache_autogc(Agent) -> void()
Types:
Agent = pid() | atom()
Disable automatic gc of the mib server cache.
update_mibs_cache_age(NewAge) -> ok | {error, Reason}
update_mibs_cache_age(Agent, NewAge) -> ok | {error, Reason}
Types:
Agent = pid() | atom()
NewAge = integer() > 0
Reason = term()
Change the mib server cache age property.
update_mibs_cache_gclimit(NewGcLimit) -> ok | {error, Reason}
update_mibs_cache_gclimit(Agent, NewGCLimit) -> ok | {error, Reason}
Types:
Agent = pid() | atom()
NewGcLimit = integer() > 0 | infinity
Reason = term()
Change the mib server cache gclimit property.
register_notification_filter(Id, Mod, Data) -> ok | {error, Reason}
register_notification_filter(Agent, Id, Mod, Data) -> ok | {error, Rea-
son}
register_notification_filter(Id, Mod, Data, Where) -> ok | {error, Rea-
son}
register_notification_filter(Agent, Id, Mod, Data, Where) -> ok | {er-
ror, 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, fil-
ter_id()} | {insert_after, filter_id()}
Registers a notification filter.
Mod is a module implementing the snmpa_notification_filter be-
haviour.
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()
Unregister 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.
set_request_limit(NewLimit) -> {ok, OldLimit} | {error, Reason}
set_request_limit(Agent, NewLimit) -> {ok, OldLimit} | {error, Reason}
Types:
NewLimit = OldLimit = infinity | integer() >= 0
Agent = pid() | atom()
Reason = term()
Changes the request limit.
Note that this has no effect on the application configuration as
defined by configuration files, so a node restart will revert
the config to whatever is in those files.
This function is primarily useful in load regulation scenarios.
register_subagent(Agent, SubTreeOid, Subagent) -> ok | {error, Reason}
Types:
Agent = pid() | atom()
SubTreeOid = oid()
SubAgent = pid()
Registers a sub-agent under a sub-tree of another agent.
It is easy to make mistakes when registering sub-agents and this
activity should be done carefully. For example, a strange behav-
iour 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()
Unregister a sub-agent. If the second argument is a pid, then
that sub-agent will be unregistered from all trees in Agent.
send_notification2(Agent, Notification, SendOpts) -> void()
Types:
Agent = pid() | atom()
Notification = atom()
SendOpts = [send_option()]
send_option() = {receiver, receiver()} | {name, no-
tify_name()} | {context, context_name()} | {varbinds,
varbinds()} | {local_engine_id, string()} | {extra, ex-
tra_info()}
receiver() = no_receiver | {tag(), tag_receiver()} | notifi-
cation_delivery_info()
tag() = term(()
tag_receiver() = pid() | registered_name() | {Mod, Func,
Args}
registered_name() = atom()
Mod = atom()
Func = atom()
Args = list()
notify_name() = string()
context_name() = string()
varbinds() = [varbind()]
varbind() = {variable(), value()} | {{process_oid(), vari-
able()}, value()} | {column(), row_index(), value()} |
variable() = aliasname() | oid()
aliasname() = atom()
process_oid() = keep (default) | truncate
value() = term()
column() = atom()
row_index() = [int()]
extra_info() = term()
Send the notification Notification to the management targets de-
fined for notify-name (name) in the snmpNotifyTable in SNMP-NO-
TIFICATION-MIB from the specified context.
If no name is specified (or if it is ""), the notification is
sent to all management targets.
If no context is specified, the default context, "", is used.
The send option receiver specifies where information about de-
livery of Inform-Requests should be sent. The agent sends In-
form-Requests and waits for acknowledgments from the management
targets. The receiver can have three values:
* no_receiver - No information is delivered.
* notification_delivery_info() - The information is delivered
via a function call according to this data. See the DATA
TYPES section above for details.
* {tag(), tag_receiver()} - The information is delivered ei-
ther via messages or via a function call according to the
value of tag_receiver().
Delivery is done differently depending on the value of
tag_receiver():
* pid() | registered_name() - The info will be delivered in
the following messages:
* {snmp_targets, tag(), Addresses}
This informs the user which target addresses the notifi-
cation was sent to.
* {snmp_notification, tag(), {got_response, Address}}
This informs the user that this target address acknowl-
edged the notification.
* {snmp_notification, tag(), {no_response, Address}}
This informs the user that this target address did not
acknowledge the notification.
The notification is sent as an Inform-Request to each tar-
get address in Addresses and if there are no targets for
which an Inform-Request is sent, Addresses is the empty
list [].
The tag_receiver() will first be sent the snmp_targets
message, and then for each address in Addresses list, one
of the two snmp_notification messages.
* {Mod, Func, Args} - The info will be delivered via the
function call:
Mod:Func([Msg | Args])
where Msg has the same content and purpose as the messages
descrived above.
The 'process oid' "tag" that can be provided with the variable
name / oids is indended to be used for oid post processing. The
value 'keep', which is the default, leaves the oid as is. The
value 'truncate', will cause the oid to be "truncated". That is,
any trailing ".0" will be removed.
Note:
There is a way to exclude a varbind from the notification. In
the normal varbinds list, providing the special value '$ignore-
oid' (instead of a normal value) will exclude this varbind from
the notification.
A define for this has been added to the snmp_types.hrl include
file, NOTIFICATION_IGNORE_VB_VALUE.
Note:
The extra info is not normally interpreted by the agent, instead
it is passed through to the net-if process. It is up to the im-
plementor of that process to make use of this data.
The version of net-if provided by this application makes no use
of this data, with one exception: Any tuple containing the atom
snmpa_default_notification_extra_info may be used by the agent
and is therefor reserved.
See the net-if incomming messages for sending a trap and noti-
fication for more info.
send_notification(Agent, Notification, Receiver)
send_notification(Agent, Notification, Receiver, Varbinds)
send_notification(Agent, Notification, Receiver, NotifyName, Varbinds)
send_notification(Agent, Notification, Receiver, NotifyName, Con-
textName, Varbinds) -> void()
send_notification(Agent, Notification, Receiver, NotifyName, Con-
textName, Varbinds, LocalEngineID) -> void()
Types:
Agent = pid() | atom()
Notification = atom()
Receiver = no_receiver | {Tag, Recv} | notification_deliv-
ery_info()
Tag = term()
Recv = receiver()
receiver() = pid() | atom() | {Mod, Func, Args}
Mod = atom()
Func = atom()
Args = list()
NotifyName = string()
ContextName = string()
Varbinds = varbinds()
varbinds() = [varbind()]
varbind() = {Variable, Value} | {Column, RowIndex, Value} |
{OID, Value}
Variable = atom()
Column = atom()
OID = oid()
Value = term()
RowIndex = [int()]
LocalEngineID = string()
Sends the notification Notification to the management targets
defined for NotifyName in the snmpNotifyTable in SNMP-NOTIFICA-
TION-MIB from the specified context.
If no NotifyName is specified (or if it is ""), the notification
is sent to all management targets (Addresses below).
If no ContextName is specified, the default "" context is used.
The parameter Receiver specifies where information about deliv-
ery of Inform-Requests should be sent. The agent sends Inform-
Requests and waits for acknowledgments from the managers. Re-
ceiver can have three values:
* no_receiver - No information is delivered.
* notification_delivery_info() - The information is delivered
via a function call according to this data. See the DATA
TYPES section above for details.
* {Tag, Recv} - The information is delivered either via mes-
sages or via a function call according to the value of Recv.
If Receiver has the value {Tag, Recv}, the delivery is done ac-
cording to Recv:
* pid() | atom() - The info will be delivered in the following
messages:
* {snmp_targets, Tag, Addresses}
This inform the user which target addresses the notifica-
tion was sent to.
* {snmp_notification, Tag, {got_response, Address}}
This informs the user that this target address acknowl-
edged the notification.
* {snmp_notification, Tag, {no_response, Address}}
This informs the user that this target address did not ac-
knowledge notification.
The notification is sent as an Inform-Request to each target
address in Addresses and if there are no targets for which
an Inform-Request is sent, Addresses is the empty list [].
The receiver will first be sent the snmp_targets message,
and then for each address in Addresses list, one of the two
snmp_notification messages.
* {Mod, Func, Args} - The info will be delivered via the func-
tion call:
Mod:Func([Msg | Args])
where Msg has the same content and purpose as the messages
descrived above.
Address is a management target address and Addresses is a list
of management target addresses. They are defined as followes:
Addresses = [address()]
Address = address()
address() = v1_address() | v3_address()
v1_address() = {TDomain, TAddress}
v3_address() = {{TDomain, TAddress}, V3MsgData}
TDomain = tdoamin()
TAddress = taddress()
tdomain() = The oid of snmpUDPDomain
This is the only supported transport domain.
taddress() = [A1, A2, A3, A4, P1, P3]
The 4 first bytes makes up the IP-address and the last 2,
the UDP-port number.
V3MsgData = v3_msg_data()
v3_msg_data() = term()
If Receiver is a notification_delivery_info() record, then the
information about the notification delivery will be delivered to
the receiver via the callback functions defined by the snmpa_no-
tification_delivery_info_receiver behaviour according to the
content of the notification_delivery_info() record.
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 specifica-
tion.
* {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 IDENTI-
FIER sent in the notification is the RowIndex appended to
the OBJECT IDENTIFIER for the table column. This is the OB-
JECT IDENTIFIER which specifies the element.
* {OID, Value}, where OID is the OBJECT IDENTIFIER for an in-
stance 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 gen-
erated .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 informa-
tion. If an error occurs, user_err/2 of the error report module
is called and the notification is discarded.
Note:
Note that the use of the LocalEngineID argument is only intended
for special cases, if the agent is to "emulate" multiple En-
gineIDs! By default, the agent uses the value of SnmpEngineID
(see SNMP-FRAMEWORK-MIB).
ExtraInfo is not normally used in any way by the agent. It is
intended to be passed along to the net-if process, which is a
component that a user can implement themself. The users own net-
if may then make use of ExtraInfo. The net-if provided with this
application does not process ExtraInfo.
There is one exception. Any tuple containing the atom snmpa_de-
fault_notification_extra_info will, in this context, be consid-
ered belonging to this application, and may be processed by the
agent.
discovery(TargetName, Notification) -> {ok, ManagerEngineID} | {error,
Reason}
discovery(TargetName, Notification, Varbinds) -> {ok, ManagerEngineID}
| {error, Reason}
discovery(TargetName, Notification, DiscoHandler) -> {ok, Man-
agerEngineID} | {error, Reason}
discovery(TargetName, Notification, ContextName, Varbinds) -> {ok, Man-
agerEngineID} | {error, Reason}
discovery(TargetName, Notification, Varbinds, DiscoHandler) -> {ok,
ManagerEngineID} | {error, Reason}
discovery(TargetName, Notification, ContextName, Varbinds, DiscoHan-
dler) -> {ok, ManagerEngineID} | {error, Reason}
discovery(TargetName, Notification, ContextName, Varbinds, DiscoHan-
dler, ExtraInfo) -> {ok, ManagerEngineID} | {error, Reason}
Types:
TargetName = string()
Notification = atom()
ContextName = string() (defaults to "")
Varbinds = varbinds()
varbinds() = [varbind()]
DiscoHandler = snmpa_discovery_handler()
ExtraInfo = term()
snmpa_discovery_handler() = Module implementing the sn-
mpa_discovery_handler behaviour
ManagerEngineID = string()
varbind() = {Variable, Value} | {Column, RowIndex, Value} |
{OID, Value}
Variable = atom()
Column = atom()
OID = oid()
Value = term()
RowIndex = [int()]
Reason = term()
Initiate the discovery process with the manager identified by
TargetName using the notification Notification.
This function is synchronous, which means that it will return
when the discovery process has been completed or failed.
The DiscoHandler module is used during the discovery process.
See discovery handler for more info.
The ExtraInfo argument is passed on to the callback functions of
the DiscoHandler.
Note:
If we are not at security-level noAuthNoPriv, this could be com-
plicated, since the agent will then continue with stage 2, be-
fore which the usm-related updates must be done.
Note:
The default discovery handler will require additional actions by
the caller and the discovery will not work if the security-level
is higher then noAuthNoPriv.
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 the Configuring the application chapter of the SNMP user's
guide.
restart_worker() -> void()
restart_worker(Agent) -> void()
Types:
Agent = pid() | atom()
Restart the worker process of a multi-threaded agent.
This is a utility function, that can be useful when e.g. debug-
ging instrumentation functions.
restart_set_worker() -> void()
restart_set_worker(Agent) -> void()
Types:
Agent = pid() | atom()
Restart the set worker process of a multi-threaded agent.
This is a utility function, that can be useful when e.g. debug-
ging instrumentation functions.
print_mib_info() -> void()
Prints the content of all the (snmp) tables and variables for
all mibs handled by the snmp agent.
print_mib_tables() -> void()
Prints the content of all the (snmp) tables for all mibs handled
by the snmp agent.
print_mib_variables() -> void()
Prints the content of all the (snmp) variables for all mibs han-
dled by the snmp agent.
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 ver-
bosity silence, nothing is printed. The higher the verbosity,
the more is printed.
SEE ALSO
calendar(3erl), erlc(1)
Ericsson AB snmp 5.6 snmpa(3erl)