Linux Certif

Toute la documentation sur la certification Linux LPI

snmpa

MODULE

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

mod = module():

A module implementing the snmpa_notification_delivery_info_receiver behaviour. The info functions of this module will be called at various 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 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.

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.
BackupDir cannot be identical to DbDir.

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

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()

Retrieve the list of all the mibs loaded into this agent. Default 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 request currently being 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).

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.

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

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()

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 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()

Unregister a sub-agent. If the second argument is a pid, then that sub-agent 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} | notification_delivery_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()]

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 (Addresses below). 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 acknowledgments from the managers. Receiver can have three values:

*

no_receiver - No information is delivered.

*

{Tag, Recv} - The information is delivered either via messages or via a function call according to the value of Recv.

*

notification_delivery_info() - The information is delivered via a function call according to this data. See the DATA TYPES section above for details.

If Receiver has the value {Tag, Recv}, the delivery is done according 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 notification was sent to.

-

{snmp_notification, Tag, {got_response, Address}}

This informs the user that this target address acknowledged the notification.

-

{snmp_notification, Tag, {no_response, Address}}

This informs the user that this target address did not acknowledge 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 function 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_notification_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 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.

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 usefull when e.g. debugging 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 usefull when e.g. debugging instrumentation functions.

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.

SEE ALSO

calendar(3), erlc(1)