From dbacaf9db7977c3ad4ff35f7f6fe0085a6ab9956 Mon Sep 17 00:00:00 2001
From: Micael Karlberg
Date: Tue, 5 Apr 2011 14:37:40 +0200
Subject: Documentation updated.
---
lib/snmp/doc/src/notes.xml | 15 ++
lib/snmp/doc/src/snmp_agent_netif.xml | 198 ++++++++++++++++-----------
lib/snmp/doc/src/snmpa.xml | 251 +++++++++++++++++++++-------------
3 files changed, 291 insertions(+), 173 deletions(-)
(limited to 'lib/snmp')
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
@@ -43,6 +43,21 @@
-
-->
+ -
+
[agent] Pass extra info through the agent to the net-if
+ process when sending notifications.
+ See
+
+ snmpa:send_notification2/3 for more info.
+ See also the incomming net-if messages when sending a
+ trap
+ and
+
+ notification.
+ Own Id: OTP-9183
+ Aux Id: Seq 11817
+
+
-
[agent] Added support for sending traps to IPv6 targets.
See the
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 @@
-
+
@@ -65,16 +65,19 @@
+
Messages
The section Messages describes mandatory messages, which
Net if must send and be able to receive.
+
Outgoing Messages
Net if must send the following message when it receives an
- SNMP PDU from the network that is aimed for the MasterAgent:
-
+ SNMP PDU from the network that is aimed for the MasterAgent:
+
+
MasterAgent ! {snmp_pdu, Vsn, Pdu, PduMS, ACMData, From, Extra}
@@ -106,9 +109,10 @@ MasterAgent ! {snmp_pdu, Vsn, Pdu, PduMS, ACMData, From, Extra}
the request.
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.
-
+ request has been received. The only request an agent can send
+ is an Inform-Request.
+
+
Pid ! {snmp_response_received, Vsn, Pdu, From}
@@ -131,119 +135,153 @@ Pid ! {snmp_response_received, Vsn, Pdu, From}
+
Incoming Messages
This section describes the incoming messages which a Net if
- process must be able to receive.
-
+ process must be able to receive.
+
-
+
{snmp_response, Vsn, Pdu, Type, ACMData, To, Extra}
This message is sent to the Net if process from a master
agent as a response to a previously received request.
- - Vsn is either 'version-1',
- 'version-2', or 'version-3'.
+
-
+
Vsn is either 'version-1',
+ 'version-2', or 'version-3'.
- - Pdu is an SNMP PDU record (as defined in
- snmp_types.hrl) with the SNMP response.
+
-
+
Pdu is an SNMP PDU record (as defined in
+ snmp_types.hrl) with the SNMP response.
- - Type is the #pdu.type of the original
- request.
+
-
+
Type is the #pdu.type
+ of the original request.
- - ACMData is data used by the Access Control
- Module in use. Normally this is just sent to
- snmpa_mpd:generate_response_message (see Reference Manual).
+
-
+
ACMData is data used by the Access Control
+ Module in use. Normally this is just sent to
+ snmpa_mpd:generate_response_message
+ (see Reference Manual).
- - To is the destination address. If UDP over IP
- is used, this should be a 2-tuple {IP, UDPport},
- where IP is a 4-tuple with the IP address, and
- UDPport is an integer.
+
-
+
To is the destination address. If UDP over IP
+ is used, this should be a 2-tuple {IP, UDPport},
+ where IP is a 4-tuple with the IP address, and
+ UDPport is an integer.
- - Extra is the term that the Net if process
- sent to the agent when the request was sent to the agent.
+
-
+
Extra is the term that the Net if process
+ sent to the agent when the request was sent to the agent.
-
+
{discarded_pdu, Vsn, ReqId, ACMData, Variable, Extra}
This message is sent from a master agent if it for some
- reason decided to discard the pdu.
-
+ reason decided to discard the pdu.
- - Vsn is either 'version-1',
- 'version-2', or 'version-3'.
+
-
+
Vsn is either 'version-1',
+ 'version-2', or 'version-3'.
- - ReqId is the request id of the original
- request.
+
-
+
ReqId is the request id of the original request.
- - ACMData is data used by the Access Control
- Module in use. Normally this is just sent to
- snmpa_mpd:generate_response_message (see Reference Manual).
+
-
+
ACMData is data used by the Access Control
+ Module in use. Normally this is just sent to
+ snmpa_mpd:generate_response_message
+ (see Reference Manual).
- - Variable is the name of an snmp counter that
- represents the error, e.g. snmpInBadCommunityUses.
+
-
+
Variable is the name of an snmp counter that
+ represents the error, e.g. snmpInBadCommunityUses.
- - Extra is the term that the Net if process
- sent to the agent when the request was sent to the agent.
+
-
+
Extra is the term that the Net if process
+ sent to the agent when the request was sent to the agent.
-
-
{send_pdu, Vsn, Pdu, MsgData, To}
+
+ {send_pdu, Vsn, Pdu, MsgData, To, Extra}
This message is sent from a master agent when a trap is
- to be sent.
-
+ to be sent.
- - Vsn is either 'version-1',
- 'version-2', or 'version-3'.
+
-
+
Vsn is either 'version-1',
+ 'version-2', or 'version-3'.
- - Pdu is an SNMP PDU record (as defined in
- snmp_types.hrl) with the SNMP response.
+
-
+
Pdu is an SNMP PDU record (as defined in
+ snmp_types.hrl) with the SNMP response.
+
+ -
+
MsgData is the message specific data used in
+ the SNMP message. This value is normally sent to
+ snmpa_mpd:generate_message/4. In SNMPv1 and
+ SNMPv2c, this message data is the community string. In
+ SNMPv3, it is the context information.
- - MsgData is the message specific data used in
- the SNMP message. This value is normally sent to
- snmpa_mpd:generate_message/4. In SNMPv1 and
- SNMPv2c, this message data is the community string. In
- SNMPv3, it is the context information.
+
-
+
To is a list of the destination addresses and
+ their corresponding security parameters. This value is
+ normally sent to snmpa_mpd:generate_message/4.
- - To is a list of the destination addresses and
- their corresponding security parameters. This value is
- normally sent to snmpa_mpd:generate_message/4.
+
-
+
Extra is any term that the notification sender
+ wishes to pass to the Net if process when sending a notification
+ (see
+ send notification
+ for more info).
-
-
{send_pdu_req, Vsn, Pdu, MsgData, To, Pid}
- 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
- snmp_response_received message.
-
-
- - Vsn is either 'version-1',
- 'version-2', or 'version-3'.
-
- - Pdu is an SNMP PDU record (as defined in
- snmp_types.hrl) with the SNMP response.
-
- - MsgData is the message specific data used in
- the SNMP message. This value is normally sent to
- snmpa_mpd:generate_message/4. In SNMPv1 and
- SNMPv2c, this message data is the community string. In
- SNMPv3, it is the context information.
+
+
{send_pdu_req, Vsn, Pdu, MsgData, To, Pid, Extra}
+ 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 snmp_response_received message.
+
+ -
+
Vsn is either 'version-1',
+ 'version-2', or 'version-3'.
+
+ -
+
Pdu is an SNMP PDU record (as defined in
+ snmp_types.hrl) with the SNMP response.
+
+ -
+
MsgData is the message specific data used in
+ the SNMP message. This value is normally sent to
+ snmpa_mpd:generate_message/4. In SNMPv1 and
+ SNMPv2c, this message data is the community string. In
+ SNMPv3, it is the context information.
+
+ -
+
To is a list of the destination addresses and
+ their corresponding security parameters. This value is
+ normally sent to snmpa_mpd:generate_message/4.
+
+ -
+
Pid is a process identifier.
+
+ -
+
Extra is any term that the notification sender
+ wishes to pass to the Net if process when sending a notification
+ (see
+ send notification
+ for more info).
- - To is a list of the destination addresses and
- their corresponding security parameters. This value is
- normally sent to snmpa_mpd:generate_message/4.
-
- - Pid is a process identifier.
-
-
+
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
Agent.
-
+
+
+
+ send_notification2(Agent, Notification, SendOpts) -> void()
+ Send notification
+
+ Agent = pid() | atom()
+ Notification = atom()
+ SendOpts = [send_option()]
+ send_option() = {receiver, receiver()} | {name, notify_name()} | {context, context_name()} | {varbinds, varbinds()} | {local_engine_id, string()} | {extra, extra_info()}
+ override_option() = atom()
+ receiver() = no_receiver | {tag(), tag_receiver()} | notification_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()} | {column(), row_index(), value()} | {oid(), value()}
+ variable() = atom()
+ value() = term()
+ column() = atom()
+ row_index() = [int()]
+ extra_info() = term()
+
+
+ Send the notification Notification to the management
+ targets defined for notify-name (name) in the
+ snmpNotifyTable in SNMP-NOTIFICATION-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 delivery of Inform-Requests should be sent. The agent
+ sends Inform-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
+ either 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
+ 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.
+
+
+ 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 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 extra info is not normally interpreted by the agent,
+ instead it is passed through to the
+ net-if process. It is
+ up to the implementor 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
+
+ notification for more info.
+
+
+
+
+
+
+
send_notification(Agent, Notification, Receiver)
send_notification(Agent, Notification, Receiver, Varbinds)
@@ -907,29 +1036,25 @@ snmp_agent:register_subagent(SA1,[1,2,3], SA2).
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.
-
+ 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:
+ 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
@@ -937,6 +1062,12 @@ snmp_agent:register_subagent(SA1,[1,2,3], SA2).
above for details.
+ -
+
{Tag, Recv} - The information is delivered either via
+ messages or via a function call according to the value of
+ Recv.
+
+
@@ -1064,86 +1195,20 @@ snmp_agent:register_subagent(SA1,[1,2,3], SA2).
(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_default_notification_extra_info will, in this context,
+ be considered belonging to this application, and may be processed
+ by the agent.
+
+
-
discovery(TargetName, Notification) -> {ok, ManagerEngineID} | {error, Reason}
--
cgit v1.2.3