snmpa

模块

snmpa

模块摘要

接口函数到SNMP工具包代理

描述

该模块snmpa包含SNMP代理的接口功能。

数据类型

oid() = [byte()] 
atl_type() = read | write | read_write
notification_delivery_info() = #snmpa_notification_delivery_info{}

该oid()类型用于表示ASN.1 OBJECT标识符。

该记录snmpa_notification_delivery_info包含以下字段：

tag = term()

表示此通知的用户定义身份发送操作。

mod = module()

实现该snmpa_notification_delivery_info_receiver行为的模块。这个模块的信息功能将在不同的交付阶段被调用。

extra = term()

这是用户想要在回调模块中的函数被调用时提供的额外信息。

输出

`add_agent_caps(SysORID, SysORDescr) -> SysORIndex`

类型

该函数可用于向代理中的sysORTable添加AGENT-CAPABILITY语句。该表在SNMPv2-MIB中定义。

`del_agent_caps(SysORIndex) -> void()`

类型

这个函数可以用来删除代理中sysortable的AGENT-CAPABILITY语句。该表在SNMPv2-MIB中定义。

`get_agent_caps() -> [[SysORIndex, SysORID, SysORDescr, SysORUpTime]]`

类型

返回代理中sysORTable中的所有AGENT-CAPABILITY语句。该表在SNMPv2-MIB中定义。

`get(Agent, Vars) -> Values | {error, Reason}get(Agent, Vars, Context) -> Values | {error, Reason}`

类型

对代理执行GET操作。所有加载的MIB对象在此操作中都可见。代理程序调用相应的检测函数，就像它是来自管理器的GET请求一样。

请注意，current_request_id功能若被使用，则特定于请求的参数（例如）不适用于检测功能。

`get_next(Agent, Vars) -> Values | {error, Reason}get_next(Agent, Vars, Context) -> Values | {error, Reason}`

类型

对代理执行GET-NEXT操作。所有加载的MIB对象在此操作中都可见。代理程序调用相应的检测函数，就像它是来自管理器的GET请求一样。

请注意，请求特定参数（例如，snmpa:current_request_id/0如果使用此功能，则不能使用仪表功能。

`backup(BackupDir) -> ok | {error, Reason}backup(Agent, BackupDir) -> ok | {error, Reason}`

类型

备份由代理处理的持久/永久数据（例如local-db，mib-data和vacm）。

没有处理由mnesia存储的数据。

BackupDir不能与DbDir相同。

同时备份呼叫不容许。也就是说，两个不同的进程不能同时成功调用这个函数。其中之一将是第一个，并成功。第二个将失败并出现错误原因backup_in_progress。

`info() -> [{Key, Value}]info(Agent) -> [{Key, Value}]`

类型

返回包含有关代理信息的列表（字典）。信息包括加载的MIB，注册的子代理，关于内存分配的一些信息。

从版本4.4开始，信息的格式已经改变。要将信息转换为旧格式，请调用该old_info_format函数。

`old_info_format(NewInfo) -> OldInfo`

类型

从版本4.4开始，信息的格式已经改变。该功能用于转换为旧的（4.4前）信息格式。

`load_mib(Mib) -> ok | {error, Reason}load_mib(Agent, Mib) -> ok | {error, Reason}`

类型

将单个加载Mib到代理中。这MibName是Mib的名称，包括找到已编译的mib的路径。例如：

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}`

类型

将Mib加载到代理中。如果代理无法加载所有MIB（Force参数的默认值为false），它将指示加载中止的位置。 MibName是Mib的名称，包括找到已编译的mib的路径。例如，

Dir = code:priv_dir(my_app) ++ "/mibs/",
snmpa:load_mibs(snmp_master_agent, [Dir ++ "MY-MIB"]).

如果Force = true那么代理将继续尝试加载每个mib，即使在未加载先前的mib之后。小心使用。

`unload_mib(Mib) -> ok | {error, Reason}unload_mib(Agent, Mib) -> ok | {error, Reason}`

类型

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}`

类型

从代理卸载Mibs。如果无法卸载所有MIB（Force参数的默认值为false），它将指示卸载的中止位置。

如果Force = true那么代理将继续尝试卸载每个mib，即使在未能卸载之前的mib之后。小心使用。

`which_mibs() -> Mibswhich_mibs(Agent) -> Mibs`

类型

检索加载到该代理的所有mib的列表。默认是主代理。

`whereis_mib(MibName) -> {ok, MibFile} | {error, Reason}whereis_mib(Agent, MibName) -> {ok, MibFile} | {error, Reason}`

类型

获取（编译的）mib文件的完整路径。

`current_request_id() -> {value, RequestId} | falsecurrent_context() -> {value, Context} | falsecurrent_community() -> {value, Community} | falsecurrent_address() -> {value, Address} | false`

类型

获取代理当前正在处理的请求的请求标识，上下文，社区和地址。

请注意，这些函数只能在代理过程的上下文中执行（例如，如果从派生过程中调用它，则不起作用），这些函数只能在工具函数中调用。

`enum_to_int(Name, Enum) -> {value, Int} | falseenum_to_int(Db, Name, Enum) -> {value, Int} | false`

类型

将符号值转换为Enum枚举对象的相应整数或Name在MIB中键入。MIB必须加载。

如果对象或类型未在任何加载的MIB中定义，或者未将枚举的符号值定义，则返回false。

Db是对符号存储数据库的引用（通过调用get_symbolic_store_db/0来检索）。

`int_to_enum(Name, Int) -> {value, Enum} | falseint_to_enum(Db, Name, Int) -> {value, Enum} | false`

类型

将整数转换为Int枚举对象的相应符号值或Name在MIB中键入。MIB必须加载。

如果对象或类型未在任何加载的MIB中定义，或者未将枚举的符号值定义，则返回false。

Db是对符号存储数据库的引用（通过调用来检索get_symbolic_store_db/0）。

`name_to_oid(Name) -> {value, oid()} | falsename_to_oid(Db, Name) -> {value, oid()} | false`

类型

给定符号名称，查找MIB对象的OBJECT IDENTIFIER。请注意，OBJECT IDENTIFIER是针对该对象给出的，而不是针对实例。

如果对象未在任何加载的MIB中定义，则返回false。

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} | falseoid_to_name(Db, OID) -> {value, Name} | false`

类型

给定OBJECT IDENTIFIER，查找MIB对象的符号名称。

如果对象未在任何加载的MIB中定义，则返回false。

Db是对符号存储数据库的引用（通过调用get_symbolic_store_db/0来检索）。

`which_aliasnames() -> Result`

类型

检索代理已知的所有别名。

`which_tables() -> Result`

类型

检索代理已知的所有表。

`which_variables() -> Result`

类型

检索代理已知的所有变量。

`which_notifications() -> Result`

类型

检索代理已知的所有通知（和陷阱）。

log_to_txt(LogDir)log_to_txt(LogDir, Block | Mibs)log_to_txt(LogDir, Mibs, Block | OutFile) -> ok | {error, Reason}log_to_txt(LogDir, Mibs, OutFile, Block | LogName) -> ok | {error, Reason}log_to_txt(LogDir, Mibs, OutFile, LogName, Block | LogFile) -> ok | {error, Reason}log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block | Start) -> ok | {error, Reason}log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start) -> ok | {error, Reason}log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop) -> ok | {error, Reason}log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Block, Start, Stop) -> ok | {error, Reason}

类型

将审计跟踪日志转换为可读的文本文件。 OutFile默认为“./snmpa_log.txt”。 LogName默认为“snmpa_log”。 LogFile默认为“snmpa.log”。

该Block选项指示是否应在转换期间阻止日志。转换大型日志时这可能是有用的（否则日志可能会在转换过程中进行换行）。默认为true。

更多信息查看snmp:log_to_txt。

log_to_io(LogDir) -> ok | {error, Reason}log_to_io(LogDir, Block | Mibs) -> ok | {error, Reason}log_to_io(LogDir, Mibs, Block | LogName) -> ok | {error, Reason}log_to_io(LogDir, Mibs, LogName, Block | LogFile) -> ok | {error, Reason}log_to_io(LogDir, Mibs, LogName, LogFile, Block | Start) -> ok | {error, Reason}log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start) -> ok | {error, Reason}log_to_io(LogDir, Mibs, LogName, LogFile, Start, Stop) -> ok | {error, Reason}log_to_io(LogDir, Mibs, LogName, LogFile, Block, Start, Stop) -> ok | {error, Reason}

类型

将审计跟踪日志转换为可读格式并将其打印在stdio上。LogName默认为“snmpa_log”。LogFile默认为“snmpa.log”。

该Block选项指示是否应在转换期间阻止日志。转换大型日志时这可能是有用的（否则日志可能会在转换过程中进行换行）。默认为true。

更多信息查看snmp:log_to_io。

`change_log_size(NewSize) -> ok | {error, Reason}`

类型

更改审计跟踪日志的日志大小。应用程序必须配置为使用审计跟踪日志功能。有关如何更改日志大小的说明，请参阅“内核参考手册”中的disk_log（3）。

只要日志未被删除，更改就是永久的。这意味着，重新启动时会记住日志大小。

`set_log_type(NewType) -> {ok, OldType} | {error, Reason}set_log_type(Agent, NewType) -> {ok, OldType} | {error, Reason}`

类型

更改运行时审计跟踪日志类型。

请注意，这对配置文件定义的应用程序配置没有影响，因此节点重新启动会将配置恢复为这些文件中的任何配置。

此功能主要用于测试/调试场景。

`mib_of(Oid) -> {ok, MibName} | {error, Reason}mib_of(Agent, Oid) -> {ok, MibName} | {error, Reason}`

类型

找到与Oid对应的mib。如果它是一个变量，则Oid必须是<Oid for var> .0，如果它是一个表，则Oid必须是<table>。<entry>。<col>。<any>

`me_of(Oid) -> {ok, Me} | {error, Reason}me_of(Agent, Oid) -> {ok, Me} | {error, Reason}`

类型

找到对应的mib条目Oid。如果它是一个变量，则Oid必须是<Oid for var> .0，如果它是一个表，则Oid必须是<table>。<entry>。<col>。<any>

`invalidate_mibs_cache() -> void()invalidate_mibs_cache(Agent) -> void()`

类型

使mib服务器缓存无效。

缓存的全部内容将被删除。

`enable_mibs_cache() -> void()enable_mibs_cache(Agent) -> void()`

类型

启用mib服务器缓存。

`disable_mibs_cache() -> void()disable_mibs_cache(Agent) -> void()`

类型

禁用mib服务器缓存。

`which_mibs_cache_size() -> void()which_mibs_cache_size(Agent) -> void()`

类型

检索mib服务器缓存的大小。

`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}`

类型

执行mib服务器缓存gc。

手动执行mib服务器缓存gc。无论autogc选项的值如何，这都可以完成。 NumElementsGCed值表示实际从缓存中删除了多少个元素。

`enable_mibs_cache_autogc() -> void()enable_mibs_cache_autogc(Agent) -> void()`

类型

启用mib服务器缓存的自动gc。

`disable_mibs_cache_autogc() -> void()disable_mibs_cache_autogc(Agent) -> void()`

类型

禁用mib服务器缓存的自动gc。

`update_mibs_cache_age(NewAge) -> ok | {error, Reason}update_mibs_cache_age(Agent, NewAge) -> ok | {error, Reason}`

类型

更改mib服务器缓存age属性。

`update_mibs_cache_gclimit(NewGcLimit) -> ok | {error, Reason}update_mibs_cache_gclimit(Agent, NewGCLimit) -> ok | {error, Reason}`

类型

更改mib服务器缓存gclimit属性。

`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}`

类型

注册通知过滤器。

Mod是一个实现该snmpa_notification_filter行为的模块。

Data 将在调用行为函数时传递给过滤器。

`unregister_notification_filter(Id) -> ok | {error, Reason}unregister_notification_filter(Agent, Id) -> ok | {error, Reason}`

类型

取消注册通知过滤器。

`which_notification_filter() -> Filterswhich_notification_filter(Agent) -> Filters`

类型

列出代理中的所有通知过滤器。

`set_request_limit(NewLimit) -> {ok, OldLimit} | {error, Reason}set_request_limit(Agent, NewLimit) -> {ok, OldLimit} | {error, Reason}`

类型

更改请求限制。

请注意，这对配置文件定义的应用程序配置没有影响，因此节点重新启动会将配置恢复为这些文件中的任何配置。

该功能主要用于负载调节场景。

`register_subagent(Agent, SubTreeOid, Subagent) -> ok | {error, Reason}`

类型

在另一个代理的子树下注册一个子代理。

在注册子代理人时很容易犯错，而且这项活动应该小心谨慎。例如，下面的配置会导致一个奇怪的行为：

snmp_agent:register_subagent(MAPid,[1,2,3,4],SA1),
snmp_agent:register_subagent(SA1,[1,2,3], SA2).

SA2不会从对象标识符开始获取请求，[1,2,3]因为SA1不会。

`unregister_subagent(Agent, SubagentOidOrPid) -> ok | {ok, SubAgentPid} | {error, Reason}`

类型

注销一个子代理。如果第二个参数是一个PID，那么该子代理将从所有树Agent中注销。

`send_notification2(Agent, Notification, SendOpts) -> void()`

类型

将通知通知发送到SNMP-NOTIFICATION-MIB中从指定上下文的snmpNotifyTable中为notify-name（name）定义的管理目标。

如果没有name指定（或者如果是""），则通知被发送到所有管理目标。

如果没有 context指定，则使用默认上下文""。

发送选项接收器指定应发送关于发送信息请求的信息。代理发送Inform-Requests并等待来自管理目标的确认。接收器可以有三个值：

no_receiver - 没有信息传递。
notification_delivery_info() - 根据此数据通过函数调用传递信息。有关DATA TYPES详情，请参阅上面的部分。
{tag(), tag_receiver()}- 信息通过消息或通过函数调用根据的值传递tag_receiver()。根据以下价值，交付的执行方式有所不同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 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 the notification.

通知作为通知请求发送到地址中的每个目标地址，并且如果没有发送通知请求的目标，地址是空列表[]。

tag_receiver（）将首先发送snmp_targets消息，然后为地址列表中的每个地址发送两个snmp_notification消息之一。

-  `{Mod, Func, Args}` - The info will be delivered via the function call:

注意

额外的信息通常不是由代理解释的，而是通过net-if进程传递的。利用这些数据取决于该过程的实现者。

此应用程序提供的net-if版本不使用此数据，但有一个例外：任何包含该原子的元组snmpa_default_notification_extra_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, ContextName, Varbinds) -> void()send_notification(Agent, Notification, Receiver, NotifyName, ContextName, Varbinds, LocalEngineID) -> void()`

类型

将通知通知发送到在指定上下文的SNMP-NOTIFICATION-MIB的snmpNotifyTable中为NotifyName定义的管理目标。

如果未指定NotifyName（或者它是“”），则通知将发送到所有管理目标（下面的地址）。

如果没有ContextName指定，""则使用默认上下文。

该参数Receiver指定应该发送关于传送“通知请求”的信息。代理发送Inform-Requests并等待管理员的确认。Receiver可以有三个值：

no_receiver - 没有信息传递。
notification_delivery_info() - 根据此数据通过函数调用传递信息。有关DATA TYPES详情，请参阅上面的部分。
{Tag, Recv}- 信息通过消息或通过函数调用根据的值传递Recv。

如果Receiver具有值{Tag，Recv}，则根据Recv完成交付：

pid() | atom() - 信息将在以下消息中传递：

-  `{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.

通知作为通知请求发送到地址中的每个目标地址，并且如果没有发送通知请求的目标，地址是空列表[]。

接收者将首先发送snmp_targets消息，然后为地址列表中的每个地址发送两条snmp_notification消息之一。

{Mod, Func, Args}： -该信息将通过函数调用传递 Mod:Func([Msg | Args]) ，其中Msg有相同的内容和目的与上述descrived的消息。

Address是管理对象地址，Addresses是管理对象地址的一览。它们被定义为以下内容：

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

如果Receiver是notification_delivery_info()记录，则关于通知传递的信息将receiver通过snmpa_notification_delivery_info_receiver根据notification_delivery_info()记录内容的行为定义的回调函数传递给该记录。

可选参数Varbinds为通知中的对象定义值。如果对象没有给定值，则Agent执行get-operation以检索该值。

Varbinds是一个列表Varbind，其中每个列表Varbind是：

{Variable, Value}，其中Variable是通知规范中引用的标量变量的符号名称。
{Column, RowIndex, Value}，其中Column是列变量的符号名称。RowIndex是指定元素的索引列表。如果是这种情况，通知中发送的OBJECT IDENTIFIER被RowIndex附加到表列的OBJECT IDENTIFIER中。这是指定元素的OBJECT IDENTIFIER。
{OID, Value}，其中OID是对象实例，标量变量或列变量的OBJECT IDENTIFIER。

例如，要指定sysLocation应具有"upstairs"通知中的值，我们可以使用以下之一：

{sysLocation, "upstairs"} or
{[1,3,6,1,2,1,1,6,0], "upstairs"} or
{?sysLocation_instance, "upstairs"}（只要.hrl包含生成的文件）

如果通知中的变量是表格元素，则RowIndex该元素必须在Varbinds列表中给出。在这种情况下，通知中发送的OBJECT IDENTIFIER是标识此元素的OBJECT IDENTIFIER。这个OBJECT IDENTIFIER可以在稍后的get操作中使用。

这个函数是异步的，并且不返回任何信息。如果发生错误，则user_err/2调用错误报告模块，并且通知将被丢弃。

注意

请注意，使用LocalEngineID参数仅适用于特殊情况，如果代理要“模拟”多个EngineID！默认情况下，代理使用值SnmpEngineID（请参阅SNMP-FRAMEWORK-MIB）。

ExtraInfo通常不以代理人的任何方式使用。它旨在传递给net-if进程，该进程是用户可以自行实现的组件。用户自己的net-if可能会使用ExtraInfo。该应用程序提供的net-if不处理ExtraInfo。

有一个例外。在这种情况下，包含原子的任何元组snmpa_default_notification_extra_info都将被视为属于此应用程序，并且可能由代理处理。

discovery(TargetName, Notification) -> {ok, ManagerEngineID} | {error, Reason}discovery(TargetName, Notification, Varbinds) -> {ok, ManagerEngineID} | {error, Reason}discovery(TargetName, Notification, DiscoHandler) -> {ok, ManagerEngineID} | {error, Reason}discovery(TargetName, Notification, ContextName, Varbinds) -> {ok, ManagerEngineID} | {error, Reason}discovery(TargetName, Notification, Varbinds, DiscoHandler) -> {ok, ManagerEngineID} | {error, Reason}discovery(TargetName, Notification, ContextName, Varbinds, DiscoHandler) -> {ok, ManagerEngineID} | {error, Reason}discovery(TargetName, Notification, ContextName, Varbinds, DiscoHandler, ExtraInfo) -> {ok, ManagerEngineID} | {error, Reason}

类型

与通过TargetName使用通知识别的经理启动发现过程Notification。

此功能是同步的，这意味着它将在发现过程完成或失败时返回。

该DiscoHandler模块在发现过程中使用。更多信息查看discovery handler。

该ExtraInfo参数被传递给DiscoHandler的回调函数。

注意

如果我们不在安全级别noAuthNoPriv，这可能会很复杂，因为代理将继续进行第2阶段，在这之前必须完成与usm相关的更新。

注意

默认发现处理程序将需要调用方执行其他操作，如果安全级别高于noAuthNoPriv，则发现将不起作用。

`convert_config(OldConfig) -> AgentConfig`

类型

这个离线实用程序功能可用于将旧的snmp应用程序配置（pre snmp-4.0）转换为新的snmp代理配置（从snmp-4.0开始）。

有关旧config（OldConfig）的信息，请参阅OTP R9C文档。

有关当前代理config（AgentConfig）的信息，请参阅SNMP application参考手册的一部分或Configuring the applicationSNMP用户指南的一章。

`restart_worker() -> void()restart_worker(Agent) -> void()`

类型

重新启动多线程代理的工作进程。

这是一个实用程序功能，在例如调试仪器功能时非常有用。

`restart_set_worker() -> void()restart_set_worker(Agent) -> void()`

类型

重新启动多线程代理的设置工作进程。

这是一个实用程序功能，在例如调试仪器功能时非常有用。

`print_mib_info() -> void()`

打印由snmp代理处理的所有mib的所有（snmp）表和变量的内容。

`print_mib_tables() -> void()`

打印由snmp代理处理的所有mib的所有（snmp）表的内容。

`print_mib_variables() -> void()`

打印由snmp代理处理的所有mib的所有（snmp）变量的内容。

`verbosity(Ref,Verbosity) -> void()`

类型

设定指定进程的详细程度。对于最低的冗长度silence，什么都不打印。冗长度越高，打印的越多。

扩展内容

calendar(3), erlc(1)

本文档系腾讯云开发者社区成员共同维护，如有问题请联系 cloudcommunity@tencent.com

最后更新于：2017-12-18