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/doc') 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