aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--lib/snmp/doc/src/notes.xml15
-rw-r--r--lib/snmp/doc/src/snmp_agent_netif.xml198
-rw-r--r--lib/snmp/doc/src/snmpa.xml251
3 files changed, 291 insertions, 173 deletions
diff --git a/lib/snmp/doc/src/notes.xml b/lib/snmp/doc/src/notes.xml
index f5fa7065fb..e9787c17da 100644
--- a/lib/snmp/doc/src/notes.xml
+++ b/lib/snmp/doc/src/notes.xml
@@ -44,6 +44,21 @@
-->
<list type="bulleted">
<item>
+ <p>[agent] Pass extra info through the agent to the net-if
+ process when sending notifications. </p>
+ <p>See
+ <seealso marker="snmpa#send_notification2">
+ snmpa:send_notification2/3</seealso> for more info.
+ See also the incomming net-if messages when sending a
+ <seealso marker="snmp_agent_netif#im_send_pdu">trap</seealso>
+ and
+ <seealso marker="snmp_agent_netif#im_send_pdu_req">
+ notification</seealso>. </p>
+ <p>Own Id: OTP-9183</p>
+ <p>Aux Id: Seq 11817</p>
+ </item>
+
+ <item>
<p>[agent] Added support for sending traps to IPv6 targets. </p>
<p>See the
<seealso marker="snmp_agent_config_files#target_addr">target address config file</seealso>,
diff --git a/lib/snmp/doc/src/snmp_agent_netif.xml b/lib/snmp/doc/src/snmp_agent_netif.xml
index 1f2dbe80db..d751740a82 100644
--- a/lib/snmp/doc/src/snmp_agent_netif.xml
+++ b/lib/snmp/doc/src/snmp_agent_netif.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
@@ -65,16 +65,19 @@
</section>
<section>
+ <marker id="messages"></marker>
<title>Messages</title>
<p>The section <em>Messages</em> describes mandatory messages, which
Net if must send and be able to receive.
</p>
<section>
+ <marker id="outgoing_messages"></marker>
<title>Outgoing Messages</title>
<p>Net if must send the following message when it receives an
- SNMP PDU from the network that is aimed for the MasterAgent:
- </p>
+ SNMP PDU from the network that is aimed for the MasterAgent:
+ </p>
+ <marker id="om_snmp_pdu"></marker>
<pre>
MasterAgent ! {snmp_pdu, Vsn, Pdu, PduMS, ACMData, From, Extra}
</pre>
@@ -106,9 +109,10 @@ MasterAgent ! {snmp_pdu, Vsn, Pdu, PduMS, ACMData, From, Extra}
the request.</item>
</list>
<p>The following message is used to report that a response to a
- request has been received. The only request an agent can send
- is an Inform-Request.
- </p>
+ request has been received. The only request an agent can send
+ is an Inform-Request.
+ </p>
+ <marker id="om_snmp_response_received"></marker>
<pre>
Pid ! {snmp_response_received, Vsn, Pdu, From}
</pre>
@@ -131,119 +135,153 @@ Pid ! {snmp_response_received, Vsn, Pdu, From}
</section>
<section>
+ <marker id="incoming_messages"></marker>
<title>Incoming Messages</title>
<p>This section describes the incoming messages which a Net if
- process must be able to receive.
- </p>
+ process must be able to receive.
+ </p>
<list type="bulleted">
<item>
+ <marker id="im_snmp_response"></marker>
<p><c>{snmp_response, Vsn, Pdu, Type, ACMData, To, Extra}</c></p>
<p>This message is sent to the Net if process from a master
agent as a response to a previously received request.
</p>
<list type="bulleted">
- <item><c>Vsn</c> is either <c>'version-1'</c>,
- <c>'version-2'</c>, or <c>'version-3'</c>.
+ <item>
+ <p><c>Vsn</c> is either <c>'version-1'</c>,
+ <c>'version-2'</c>, or <c>'version-3'</c>. </p>
</item>
- <item><c>Pdu</c> is an SNMP PDU record (as defined in
- snmp_types.hrl) with the SNMP response.
+ <item>
+ <p><c>Pdu</c> is an SNMP PDU record (as defined in
+ snmp_types.hrl) with the SNMP response. </p>
</item>
- <item><c>Type</c> is the <c>#pdu.type</c> of the original
- request.
+ <item>
+ <p><c>Type</c> is the <c>#pdu.type</c>
+ of the original request. </p>
</item>
- <item><c>ACMData</c> is data used by the Access Control
- Module in use. Normally this is just sent to
- <c>snmpa_mpd:generate_response_message</c> (see Reference Manual).
+ <item>
+ <p><c>ACMData</c> is data used by the Access Control
+ Module in use. Normally this is just sent to
+ <c>snmpa_mpd:generate_response_message</c>
+ (see Reference Manual). </p>
</item>
- <item><c>To</c> is the destination address. If UDP over IP
- is used, this should be a 2-tuple <c>{IP, UDPport}</c>,
- where <c>IP</c> is a 4-tuple with the IP address, and
- <c>UDPport</c> is an integer.
+ <item>
+ <p><c>To</c> is the destination address. If UDP over IP
+ is used, this should be a 2-tuple <c>{IP, UDPport}</c>,
+ where <c>IP</c> is a 4-tuple with the IP address, and
+ <c>UDPport</c> is an integer. </p>
</item>
- <item><c>Extra</c> is the term that the Net if process
- sent to the agent when the request was sent to the agent.
+ <item>
+ <p><c>Extra</c> is the term that the Net if process
+ sent to the agent when the request was sent to the agent. </p>
</item>
</list>
</item>
<item>
+ <marker id="im_discarded_pdu"></marker>
<p><c>{discarded_pdu, Vsn, ReqId, ACMData, Variable, Extra}</c></p>
<p>This message is sent from a master agent if it for some
- reason decided to discard the pdu.
- </p>
+ reason decided to discard the pdu. </p>
<list type="bulleted">
- <item><c>Vsn</c> is either <c>'version-1'</c>,
- <c>'version-2'</c>, or <c>'version-3'</c>.
+ <item>
+ <p><c>Vsn</c> is either <c>'version-1'</c>,
+ <c>'version-2'</c>, or <c>'version-3'</c>. </p>
</item>
- <item><c>ReqId</c> is the request id of the original
- request.
+ <item>
+ <p><c>ReqId</c> is the request id of the original request. </p>
</item>
- <item><c>ACMData</c> is data used by the Access Control
- Module in use. Normally this is just sent to
- <c>snmpa_mpd:generate_response_message</c> (see Reference Manual).
+ <item>
+ <p><c>ACMData</c> is data used by the Access Control
+ Module in use. Normally this is just sent to
+ <c>snmpa_mpd:generate_response_message</c>
+ (see Reference Manual). </p>
</item>
- <item><c>Variable</c> is the name of an snmp counter that
- represents the error, e.g. <c>snmpInBadCommunityUses</c>.
+ <item>
+ <p><c>Variable</c> is the name of an snmp counter that
+ represents the error, e.g. <c>snmpInBadCommunityUses</c>. </p>
</item>
- <item><c>Extra</c> is the term that the Net if process
- sent to the agent when the request was sent to the agent.
+ <item>
+ <p><c>Extra</c> is the term that the Net if process
+ sent to the agent when the request was sent to the agent. </p>
</item>
</list>
</item>
<item>
- <p><c>{send_pdu, Vsn, Pdu, MsgData, To}</c></p>
+ <marker id="im_send_pdu"></marker>
+ <p><c>{send_pdu, Vsn, Pdu, MsgData, To, Extra}</c></p>
<p>This message is sent from a master agent when a trap is
- to be sent.
- </p>
+ to be sent. </p>
<list type="bulleted">
- <item><c>Vsn</c> is either <c>'version-1'</c>,
- <c>'version-2'</c>, or <c>'version-3'</c>.
+ <item>
+ <p><c>Vsn</c> is either <c>'version-1'</c>,
+ <c>'version-2'</c>, or <c>'version-3'</c>.</p>
</item>
- <item><c>Pdu</c> is an SNMP PDU record (as defined in
- snmp_types.hrl) with the SNMP response.
+ <item>
+ <p><c>Pdu</c> is an SNMP PDU record (as defined in
+ snmp_types.hrl) with the SNMP response. </p>
+ </item>
+ <item>
+ <p><c>MsgData</c> is the message specific data used in
+ the SNMP message. This value is normally sent to
+ <c>snmpa_mpd:generate_message/4</c>. In SNMPv1 and
+ SNMPv2c, this message data is the community string. In
+ SNMPv3, it is the context information. </p>
</item>
- <item><c>MsgData</c> is the message specific data used in
- the SNMP message. This value is normally sent to
- <c>snmpa_mpd:generate_message/4</c>. In SNMPv1 and
- SNMPv2c, this message data is the community string. In
- SNMPv3, it is the context information.
+ <item>
+ <p><c>To</c> is a list of the destination addresses and
+ their corresponding security parameters. This value is
+ normally sent to <c>snmpa_mpd:generate_message/4</c>. </p>
</item>
- <item><c>To</c> is a list of the destination addresses and
- their corresponding security parameters. This value is
- normally sent to <c>snmpa_mpd:generate_message/4</c>.
+ <item>
+ <p><c>Extra</c> is any term that the notification sender
+ wishes to pass to the Net if process when sending a notification
+ (see
+ <seealso marker="snmpa#send_notification2">send notification
+ </seealso> for more info). </p>
</item>
</list>
</item>
<item>
- <p><c>{send_pdu_req, Vsn, Pdu, MsgData, To, Pid}</c></p>
- <p>This <marker id="message"></marker>
- message is sent from a master
- agent when a request is
- to be sent. The only request an agent can send is
- Inform-Request. The net if process needs to remember the
- request id and the Pid, and when a response is received for
- the request id, send it to Pid, using a
- <c>snmp_response_received</c> message.
- </p>
- <list type="bulleted">
- <item><c>Vsn</c> is either <c>'version-1'</c>,
- <c>'version-2'</c>, or <c>'version-3'</c>.
- </item>
- <item><c>Pdu</c> is an SNMP PDU record (as defined in
- snmp_types.hrl) with the SNMP response.
- </item>
- <item><c>MsgData</c> is the message specific data used in
- the SNMP message. This value is normally sent to
- <c>snmpa_mpd:generate_message/4</c>. In SNMPv1 and
- SNMPv2c, this message data is the community string. In
- SNMPv3, it is the context information.
+ <marker id="im_send_pdu_req"></marker>
+ <p><c>{send_pdu_req, Vsn, Pdu, MsgData, To, Pid, Extra}</c></p>
+ <p>This message is sent from a master agent when a request is to
+ be sent. The only request an agent can send is Inform-Request.
+ The net if process needs to remember the request id and the Pid,
+ and when a response is received for the request id, send it to Pid,
+ using a <c>snmp_response_received</c> message. </p>
+ <list type="bulleted">
+ <item>
+ <p><c>Vsn</c> is either <c>'version-1'</c>,
+ <c>'version-2'</c>, or <c>'version-3'</c>.</p>
+ </item>
+ <item>
+ <p><c>Pdu</c> is an SNMP PDU record (as defined in
+ snmp_types.hrl) with the SNMP response. </p>
+ </item>
+ <item>
+ <p><c>MsgData</c> is the message specific data used in
+ the SNMP message. This value is normally sent to
+ <c>snmpa_mpd:generate_message/4</c>. In SNMPv1 and
+ SNMPv2c, this message data is the community string. In
+ SNMPv3, it is the context information. </p>
+ </item>
+ <item>
+ <p><c>To</c> is a list of the destination addresses and
+ their corresponding security parameters. This value is
+ normally sent to <c>snmpa_mpd:generate_message/4</c>. </p>
+ </item>
+ <item>
+ <p><c>Pid</c> is a process identifier. </p>
+ </item>
+ <item>
+ <p><c>Extra</c> is any term that the notification sender
+ wishes to pass to the Net if process when sending a notification
+ (see
+ <seealso marker="snmpa#send_notification2">send notification
+ </seealso> for more info). </p>
</item>
- <item><c>To</c> is a list of the destination addresses and
- their corresponding security parameters. This value is
- normally sent to <c>snmpa_mpd:generate_message/4</c>.
- </item>
- <item><c>Pid</c> is a process identifier.
- </item>
- </list>
+ </list>
</item>
</list>
</section>
diff --git a/lib/snmp/doc/src/snmpa.xml b/lib/snmp/doc/src/snmpa.xml
index 1d680e80f5..1800bbc91a 100644
--- a/lib/snmp/doc/src/snmpa.xml
+++ b/lib/snmp/doc/src/snmpa.xml
@@ -872,10 +872,139 @@ snmp_agent:register_subagent(SA1,[1,2,3], SA2).
then that sub-agent will be unregistered from all trees in
<c>Agent</c>. </p>
- <marker id="send_notification"></marker>
+ <marker id="send_notification2"></marker>
</desc>
</func>
+
+ <func>
+ <name>send_notification2(Agent, Notification, SendOpts) -> void()</name>
+ <fsummary>Send notification</fsummary>
+ <type>
+ <v>Agent = pid() | atom()</v>
+ <v>Notification = atom()</v>
+ <v>SendOpts = [send_option()]</v>
+ <v>send_option() = {receiver, receiver()} | {name, notify_name()} | {context, context_name()} | {varbinds, varbinds()} | {local_engine_id, string()} | {extra, extra_info()}</v>
+ <v>override_option() = atom()</v>
+ <v>receiver() = no_receiver | {tag(), tag_receiver()} | notification_delivery_info()</v>
+ <v>tag() = term(()</v>
+ <v>tag_receiver() = pid() | registered_name() | {Mod, Func, Args}</v>
+ <v>registered_name() = atom()</v>
+ <v>Mod = atom()</v>
+ <v>Func = atom()</v>
+ <v>Args = list()</v>
+ <v>notify_name() = string()</v>
+ <v>context_name() = string()</v>
+ <v>varbinds() = [varbind()]</v>
+ <v>varbind() = {variable(), value()} | {column(), row_index(), value()} | {oid(), value()}</v>
+ <v>variable() = atom()</v>
+ <v>value() = term()</v>
+ <v>column() = atom()</v>
+ <v>row_index() = [int()]</v>
+ <v>extra_info() = term()</v>
+ </type>
+ <desc>
+ <p>Send the notification <c>Notification</c> to the management
+ targets defined for notify-name (<c>name</c>) in the
+ <c>snmpNotifyTable</c> in SNMP-NOTIFICATION-MIB from the
+ specified <c>context</c>. </p>
+
+ <p>If no <c>name</c> is specified (or if it is <c>""</c>), the
+ notification is sent to all management targets. </p>
+
+ <p>If no <c>context</c> is specified, the default context, <c>""</c>,
+ is used. </p>
+
+ <p>The send option <c>receiver</c> specifies where information
+ about delivery of Inform-Requests should be sent. The agent
+ sends Inform-Requests and waits for acknowledgments from the
+ management targets.
+ The <c>receiver</c> can have three values: </p>
+
+ <list type="bulleted">
+ <item>
+ <p><c>no_receiver</c> - No information is delivered. </p>
+ </item>
+
+ <item>
+ <p><c>notification_delivery_info()</c> - The information is
+ delivered via a function call according to this data. See the
+ <seealso marker="#data_types">DATA TYPES</seealso> section
+ above for details. </p>
+ </item>
+
+ <item>
+ <p><c>{tag(), tag_receiver()}</c> - The information is delivered
+ either via messages or via a function call according to the value
+ of <c>tag_receiver()</c>. </p>
+ <p>Delivery is done differently depending on the value
+ of <c>tag_receiver()</c>: </p>
+
+ <list>
+ <item>
+ <p><c>pid() | registered_name()</c> - The info will be delivered in
+ the following messages: </p>
+ <list>
+ <item>
+ <p><c>{snmp_targets, tag(), Addresses}</c></p>
+ <p>This informs the user which target addresses the
+ notification was sent to. </p>
+ </item>
+ <item>
+ <p><c>{snmp_notification, tag(), {got_response, Address}}</c></p>
+ <p>This informs the user that this target address
+ acknowledged the notification. </p>
+ </item>
+ <item>
+ <p><c>{snmp_notification, tag(), {no_response, Address}}</c></p>
+ <p>This informs the user that this target address
+ did not acknowledge the notification. </p>
+ </item>
+ </list>
+ <p>The notification is sent as an Inform-Request to each
+ target address in <c>Addresses</c> and if there are no
+ targets for which an Inform-Request is sent, <c>Addresses</c>
+ is the empty list <c>[]</c>. </p>
+ <p>The <c>tag_receiver()</c> will first be sent the
+ <c>snmp_targets</c> message, and then for each address in
+ <c>Addresses</c> list, one of the two <c>snmp_notification</c>
+ messages. </p>
+ </item>
+
+ <item>
+ <p><c>{Mod, Func, Args}</c> - The info will be delivered via
+ the function call: </p>
+ <p><c>Mod:Func([Msg | Args])</c></p>
+ <p>where <c>Msg</c> has the same content and purpose as the
+ messages descrived above.</p>
+ </item>
+
+ </list>
+ </item>
+ </list>
+
+ <note>
+ <p>The <c>extra</c> info is not normally interpreted by the agent,
+ instead it is passed through to the
+ <seealso marker="snmp_agent_netif">net-if</seealso> process. It is
+ up to the implementor of that process to make use of this data. </p>
+ <p>The version of net-if provided by this application makes no use
+ of this data, with one exception:
+ Any tuple containing the atom
+ <c>snmpa_default_notification_extra_info</c>
+ may be used by the agent and is therefor <em>reserved</em>. </p>
+ <p>See the net-if incomming messages for sending a
+ <seealso marker="snmp_agent_netif#im_send_pdu">
+ trap</seealso> and
+ <seealso marker="snmp_agent_netif#im_send_pdu_req">
+ notification</seealso> for more info. </p>
+ </note>
+
+ <marker id="send_notification"></marker>
+ </desc>
+ </func>
+
+
<func>
<name>send_notification(Agent, Notification, Receiver)</name>
<name>send_notification(Agent, Notification, Receiver, Varbinds)</name>
@@ -907,18 +1036,19 @@ snmp_agent:register_subagent(SA1,[1,2,3], SA2).
</type>
<desc>
<p>Sends the notification <c>Notification</c> to the
- management targets defined for <c>NotifyName</c> in the
- <c>snmpNotifyTable</c> in SNMP-NOTIFICATION-MIB from the
- specified context. If no <c>NotifyName</c> is specified (or
- if it is <c>""</c>), the notification is sent to all
- management targets (<c>Addresses</c> below). If no <c>ContextName</c>
- is specified, the default <c>""</c> context is used.
- </p>
+ management targets defined for <c>NotifyName</c> in the
+ <c>snmpNotifyTable</c> in SNMP-NOTIFICATION-MIB from the
+ specified context. </p>
+ <p>If no <c>NotifyName</c> is specified (or if it is <c>""</c>),
+ the notification is sent to all management targets
+ (<c>Addresses</c> below). </p>
+ <p>If no <c>ContextName</c> is specified, the default <c>""</c>
+ context is used. </p>
<p>The parameter <c>Receiver</c> specifies where information
- about delivery of Inform-Requests should be sent. The agent
- sends Inform-Requests and waits for acknowledgments from the
- managers. <c>Receiver</c> can have three values: </p>
+ about delivery of Inform-Requests should be sent. The agent
+ sends Inform-Requests and waits for acknowledgments from the
+ managers. <c>Receiver</c> can have three values: </p>
<list type="bulleted">
<item>
@@ -926,17 +1056,18 @@ snmp_agent:register_subagent(SA1,[1,2,3], SA2).
</item>
<item>
- <p><c>{Tag, Recv}</c> - The information is delivered either via messages
- or via a function call according to the value of <c>Recv</c>. </p>
- </item>
-
- <item>
<p><c>notification_delivery_info()</c> - The information is
delivered via a function call according to this data. See the
<seealso marker="#data_types">DATA TYPES</seealso> section
above for details. </p>
</item>
+ <item>
+ <p><c>{Tag, Recv}</c> - The information is delivered either via
+ messages or via a function call according to the value of
+ <c>Recv</c>. </p>
+ </item>
+
</list>
@@ -1064,86 +1195,20 @@ snmp_agent:register_subagent(SA1,[1,2,3], SA2).
(see SNMP-FRAMEWORK-MIB). </p>
</note>
-<!--
- <marker id="send_trap"></marker>
--->
- <marker id="discovery"></marker>
+ <p><c>ExtraInfo</c> 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. </p>
+ <p>There is one exception. <em>Any</em> tuple containing the atom
+ <c>snmpa_default_notification_extra_info</c> will, in this context,
+ be considered belonging to this application, and may be processed
+ by the agent. </p>
+
+ <marker id="discovery"></marker>
</desc>
</func>
-<!--
- <func>
- <name>send_trap(Agent,Trap,Community)</name>
- <name>send_trap(Agent,Trap,Community,Varbinds) -> void()</name>
- <fsummary>Send a trap</fsummary>
- <type>
- <v>Agent = pid() | atom()</v>
- <v>Trap = atom()</v>
- <v>Community = string()</v>
- <v>Varbinds = [Varbind]</v>
- <v>Varbind = {Variable, Value} | {Column, RowIndex, Value} | {OID, Value}</v>
- <v>Variable = atom()</v>
- <v>Column = atom()</v>
- <v>OID = oid()</v>
- <v>Value = term()</v>
- <v>RowIndex = [int()]</v>
- </type>
- <desc>
- <p>Note! This function is only kept for backwards
- compatibility reasons. Use <c>send_notification</c> instead.
- </p>
- <p>Sends the trap <c>Trap</c> to the managers defined for
- <c>Community</c> in the <c>intTrapDestTable</c> in
- OTP-SNMPEA-MIB. The optional argument <c>Varbinds</c> defines
- values for the objects in the trap. If no value is given for
- an object, the <c>Agent</c> performs a get-operation to
- retrieve the value.
- </p>
- <p><c>Varbinds</c> is a list of <c>Varbind</c>, where each
- <c>Varbind</c> is one of:
- </p>
- <list type="bulleted">
- <item><c>{Variable, Value}</c>, where <c>Variable</c> is the
- symbolic name of a scalar variable referred to in the trap
- specification.
- </item>
- <item><c>{Column, RowIndex, Value}</c>, where <c>Column</c>
- is the symbolic name of a column variable.
- <c>RowIndex</c> is a list of indices for the specified
- element. If this is the case, the OBJECT IDENTIFIER sent
- in the trap is the <c>RowIndex</c> appended to the OBJECT
- IDENTIFIER for the table column. This is the OBJECT
- IDENTIFIER which specifies the element.
- </item>
- <item><c>{OID, Value}</c>, where <c>OID</c> is the OBJECT
- IDENTIFIER for an instance of an object, scalar variable,
- or column variable.
- </item>
- </list>
- <p>For example, to specify that <c>sysLocation</c> should have the
- value <c>"upstairs"</c> in the trap, we could use one of:
- </p>
- <list type="bulleted">
- <item><c>{sysLocation, "upstairs"}</c> or</item>
- <item><c>{[1,3,6,1,2,1,1,6,0], "upstairs"}</c> or</item>
- <item><c>{?sysLocation_instance, "upstairs"}</c> (provided
- that the generated <c>.hrl</c> file is included)</item>
- </list>
- <p>If a variable in the trap is a table element, the
- <c>RowIndex</c> for the element must be given in the
- <c>Varbinds</c> 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.
- </p>
- <p>This function is asynchronous, and does not return any
- information. If an error occurs, <c>snmp_error:user_err/2</c>
- is called and the trap is discarded. </p>
-
- <marker id="discovery"></marker>
- </desc>
- </func>
--->
<func>
<name>discovery(TargetName, Notification) -> {ok, ManagerEngineID} | {error, Reason}</name>