File 5224-snmp-doc-Add-documentation-for-the-new-Net-If-active.patch of Package erlang
From 4956b3a8a5bef1c574c46dc3050df935f1d01b5e Mon Sep 17 00:00:00 2001
From: Micael Karlberg <bmk@erlang.org>
Date: Wed, 26 Feb 2020 19:12:37 +0100
Subject: [PATCH 4/5] [snmp|doc] Add documentation for the new Net If active
supervision
Add documentation for the new (server) feature of active
Net If supervision.
OTP-16447
---
lib/snmp/doc/src/snmp_agent_netif.xml | 4 +-
lib/snmp/doc/src/snmp_app.xml | 34 ++++-
lib/snmp/doc/src/snmp_config.xml | 38 ++++-
lib/snmp/doc/src/snmp_manager_netif.xml | 257 +++++++++++++++++++-------------
lib/snmp/doc/src/snmpm_user.xml | 10 +-
5 files changed, 233 insertions(+), 110 deletions(-)
diff --git a/lib/snmp/doc/src/snmp_agent_netif.xml b/lib/snmp/doc/src/snmp_agent_netif.xml
index a8dea5ab7b..66a1bd900f 100644
--- a/lib/snmp/doc/src/snmp_agent_netif.xml
+++ b/lib/snmp/doc/src/snmp_agent_netif.xml
@@ -36,7 +36,7 @@
<image file="snmp_agent_netif_1.gif">
<icaption>The Purpose of Agent Net if</icaption>
</image>
- <p>The Network Interface (Net if) process delivers SNMP PDUs to a
+ <p>The Network Interface (Net If) process delivers SNMP PDUs to a
master agent, and receives SNMP PDUs from the master agent. The most
common behaviour of a Net if process is that is receives bytes from
a network, decodes them into an SNMP PDU, which it sends to a master
@@ -70,7 +70,7 @@
<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.
+ Net If must send and be able to receive.
</p>
<p>In this section an <c>Address</c> field is a
<c>{Domain, Addr}</c> tuple where <c>Domain</c> is
diff --git a/lib/snmp/doc/src/snmp_app.xml b/lib/snmp/doc/src/snmp_app.xml
index 54a7eafe76..978aff59b1 100644
--- a/lib/snmp/doc/src/snmp_app.xml
+++ b/lib/snmp/doc/src/snmp_app.xml
@@ -4,7 +4,7 @@
<appref>
<header>
<copyright>
- <year>1997</year><year>2019</year>
+ <year>1997</year><year>2020</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -594,7 +594,7 @@ in the snmp_config file!
<tag><marker id="manager_server"></marker>
<c><![CDATA[server() = [server_opt()] <optional>]]></c></tag>
<item>
- <p><c>server_opt() = {timeout, server_timeout()} | {verbosity, verbosity()} | {cbproxy, server_cbproxy()}</c></p>
+ <p><c>server_opt() = {timeout, server_timeout()} | {verbosity, verbosity()} | {cbproxy, server_cbproxy()} | {netif_sup, server_nis()}</c></p>
<p>Specifies the options for the manager server process.</p>
<p>Default is <c>silence</c>.</p>
</item>
@@ -641,6 +641,36 @@ in the snmp_config file!
<p>Default is <c>temporary</c>.</p>
</item>
+ <tag><marker id="manager_server_nis"></marker>
+ <c><![CDATA[server_nis() = none (default) | {PingTO, PongTO} <optional>]]></c></tag>
+ <item>
+ <p>This option specifies if the server should actively supervise the
+ net-if process.
+ Note that this will only work if the used net-if process actually supports
+ the protocol. See
+ <seealso marker="snmpm_network_interface">snmpm_network_interface</seealso> behaviour for more info. </p>
+ <taglist>
+ <tag><marker id="manager_server_nis_none"></marker>
+ <c><![CDATA[none (default)]]></c></tag>
+ <item>
+ <p>No active supervision of the net-if process. </p>
+ </item>
+
+ <tag><marker id="manager_server_nis_active"></marker>
+ <c><![CDATA[{PingTO :: pos_integer(), PongTO :: pos_integer()}]]></c></tag>
+ <item>
+ <p>The <c>PingTO</c> time specifies the between a successful ping
+ (or start) and the time when a ping message is to be sent to the net-if
+ process (basically the time between ping). </p>
+ <p>The <c>PongTO</c> time specifies how long time the net-if process
+ has to respond to a ping message, with a <em>pong</em> message.
+ Its starts counting when the ping message has been sent.</p>
+ <p>Both times are in milli seconds.</p>
+ </item>
+ </taglist>
+ <p>Default is <c>none</c>.</p>
+ </item>
+
<tag><marker id="manager_config"></marker>
<c><![CDATA[manager_config() = [manager_config_opt()] <mandatory>]]></c></tag>
<item>
diff --git a/lib/snmp/doc/src/snmp_config.xml b/lib/snmp/doc/src/snmp_config.xml
index d615edcec0..79c6703c94 100644
--- a/lib/snmp/doc/src/snmp_config.xml
+++ b/lib/snmp/doc/src/snmp_config.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>1997</year><year>2016</year>
+ <year>1997</year><year>2020</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -612,7 +612,7 @@ in so far as it will be converted to the new format if found.
<tag><marker id="manager_server"></marker>
<c><![CDATA[server() = [server_opt()] <optional>]]></c></tag>
<item>
- <p><c>server_opt() = {timeout, server_timeout()} | {verbosity, verbosity()} | {cbproxy, server_cbproxy()}</c></p>
+ <p><c>server_opt() = {timeout, server_timeout()} | {verbosity, verbosity()} | {cbproxy, server_cbproxy()} | {netif_sup, server_nis()}</c></p>
<p>Specifies the options for the manager server process.</p>
<p>Default is <c>silence</c>.</p>
</item>
@@ -659,6 +659,40 @@ in so far as it will be converted to the new format if found.
<p>Default is <c>temporary</c>.</p>
</item>
+ <tag><marker id="manager_server_nis"></marker>
+ <c><![CDATA[server_nis() = none (default) | {PingTO, PongTO} <optional>]]></c></tag>
+ <item>
+ <p>This option specifies if the server should actively supervise the
+ net-if process.
+ Note that this will only work if the used net-if process actually supports
+ the protocol. See
+ <seealso marker="snmpm_network_interface">snmpm_network_interface</seealso> behaviour for more info. </p>
+ <taglist>
+ <tag><marker id="manager_server_nis_none"></marker>
+ <c><![CDATA[none (default)]]></c></tag>
+ <item>
+ <p>No active supervision of the net-if process. </p>
+ </item>
+
+ <tag><marker id="manager_server_nis_active"></marker>
+ <c><![CDATA[{PingTO :: pos_integer(), PongTO :: pos_integer()}]]></c></tag>
+ <item>
+ <p>The <c>PingTO</c> time specifies the between a successful ping
+ (or start) and the time when a
+ <seealso marker="snmp_manager_netif#im_ping">ping</seealso>
+ message is to be sent to the net-if
+ process (basically the time between ping:s). </p>
+ <p>The <c>PongTO</c> time specifies how long time the net-if process
+ has to respond to a ping message, with a
+ <seealso marker="snmp_manager_netif#om_pong">pong</seealso>
+ message.
+ It starts counting when the ping message has been sent.</p>
+ <p>Both times are in milli seconds.</p>
+ </item>
+ </taglist>
+ <p>Default is <c>none</c>.</p>
+ </item>
+
<tag><marker id="manager_config"></marker>
<c><![CDATA[manager_config() = [manager_config_opt()] <mandatory>]]></c></tag>
<item>
diff --git a/lib/snmp/doc/src/snmp_manager_netif.xml b/lib/snmp/doc/src/snmp_manager_netif.xml
index 0dfcdbda0d..9825f3f3bd 100644
--- a/lib/snmp/doc/src/snmp_manager_netif.xml
+++ b/lib/snmp/doc/src/snmp_manager_netif.xml
@@ -37,7 +37,7 @@
<icaption>The Purpose of Manager Net if</icaption>
</image>
- <p>The Network Interface (Net if) process delivers SNMP PDUs to the
+ <p>The Network Interface (Net If) process delivers SNMP PDUs to the
manager server, and receives SNMP PDUs from the manager server.
The most common behaviour of a Net if process is that is receives
request PDU from the manager server, encodes the PDU into bytes
@@ -54,131 +54,186 @@
both uses UDP as the transport protocol i.e the transport domains
<c>transportDomainUdpIpv4</c> and/or <c>transportDomainUdpIpv6</c>.
The difference between the two modules is that the latter is
- "multi-threaded", i.e. for each message/request a new process
+ "multi-threaded", i.e. for each message/request a new process
is created that processes the message/request and then exits. </p>
+ <p>There is a <c>server</c> config option,
+ <seealso marker="snmp_config#manager_server_nis">netif_sup</seealso>
+ that enables "active" Net If supervision. This is very simple mechanism.
+ The (supervising) process simply sends a
+ <seealso marker="#im_ping">ping</seealso> message and expects a
+ <seealso marker="#om_pong">pong</seealso> message response
+ (withing a specific time).
+ The interval between each <c>ping/pong</c> exhange is user configurable.
+ As is the time that is allowed for the
+ <seealso marker="#om_pong">pong</seealso>
+ message to arrive.
+ Both the NetIf module(s) provided with the app supports active supervision.
+ If a NetIf module/process is used which do not implement this, then
+ the server cannot be configured with active supervision. </p>
+
<p>It is also possible to write your own Net if process and
this section describes how to do that.</p>
<section>
<marker id="mandatory_functions"></marker>
<title>Mandatory Functions</title>
- <p>A Net if process must implement the SNMP manager
+ <p>A Net If process must implement the SNMP manager
<seealso marker="snmpm_network_interface">network interface behaviour</seealso>. </p>
</section>
<section>
<title>Messages</title>
- <p>The section <em>Messages</em> describes mandatory messages, which
- Net if must send to the manager server process.
- </p>
+ <p>The section <em>Messages</em> describes mandatory (with exception
+ for the ping/pong messages) messages,
+ which Net If must send to the manager server process. </p>
<p>In this section a <c>Domain</c> field is the transport domain i.e
one of <c>transportDomainUdpIpv4</c> or <c>transportDomainUdpIpv6</c>,
and an <c>Addr</c> field is an
<c>{</c><seealso marker="kernel:inet#type-ip_address"><c>IpAddr</c></seealso><c>,IpPort}</c> tuple.</p>
- <p>Net if must send the following message when it receives an
- SNMP PDU from the network that is aimed for the MasterAgent:
- </p>
- <pre>
+ <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>
+ <pre>
Server ! {snmp_pdu, Pdu, Domain, Addr}
- </pre>
- <list type="bulleted">
- <item>
- <p><c>Pdu</c> is an SNMP PDU record, as defined in
- <c>snmp_types.hrl</c>, with the SNMP request.</p>
- </item>
- <item>
- <p><c>Domain</c> is the source transport domain. </p>
- </item>
- <item>
- <p><c>Addr</c> is the source address. </p>
- </item>
- </list>
- <pre>
+ </pre>
+ <list type="bulleted">
+ <item>
+ <p><c>Pdu</c> is an SNMP PDU record, as defined in
+ <c>snmp_types.hrl</c>, with the SNMP request.</p>
+ </item>
+ <item>
+ <p><c>Domain</c> is the source transport domain. </p>
+ </item>
+ <item>
+ <p><c>Addr</c> is the source address. </p>
+ </item>
+ </list>
+
+ <pre>
Server ! {snmp_trap, Trap, Domain, Addr}
- </pre>
- <list type="bulleted">
- <item>
- <p><c>Trap</c> is either an SNMP pdu record or an trappdu record,
- as defined in <c>snmp_types.hrl</c>, with the SNMP request.</p>
- </item>
- <item>
- <p><c>Domain</c> is the source transport domain. </p>
- </item>
- <item>
- <p><c>Addr</c> is the source address. </p>
- </item>
- </list>
- <pre>
+ </pre>
+ <list type="bulleted">
+ <item>
+ <p><c>Trap</c> is either an SNMP pdu record or an trappdu record,
+ as defined in <c>snmp_types.hrl</c>, with the SNMP request.</p>
+ </item>
+ <item>
+ <p><c>Domain</c> is the source transport domain. </p>
+ </item>
+ <item>
+ <p><c>Addr</c> is the source address. </p>
+ </item>
+ </list>
+
+ <pre>
Server ! {snmp_inform, Ref, Pdu, PduMS, Domain, Addr}
- </pre>
- <list type="bulleted">
- <item>
- <p><c>Ref</c> is either the atom <c>ignore</c> or something
- that can be used to identify the inform-request (e.g. request-id).
- <c>ignore</c> is used if the response (acknowledgment) to the
- inform-request has already been sent (this means that the server
- will not make the call to the
- <seealso marker="snmpm_network_interface#inform_response">inform_response</seealso>
- function). See the
- <seealso marker="snmp_config#manager_irb">inform request behaviour</seealso>
- configuration option for more info.</p>
- </item>
- <item>
- <p><c>Pdu</c> is an SNMP PDU record, as defined in
- <c>snmp_types.hrl</c>, with the SNMP request.</p>
- </item>
- <item>
- <p><c>Domain</c> is the source transport domain. </p>
- </item>
- <item>
- <p><c>Addr</c> is the source address. </p>
- </item>
- </list>
- <pre>
+ </pre>
+ <list type="bulleted">
+ <item>
+ <p><c>Ref</c> is either the atom <c>ignore</c> or something
+ that can be used to identify the inform-request (e.g. request-id).
+ <c>ignore</c> is used if the response (acknowledgment) to the
+ inform-request has already been sent (this means that the server
+ will not make the call to the
+ <seealso marker="snmpm_network_interface#inform_response">inform_response</seealso>
+ function). See the
+ <seealso marker="snmp_config#manager_irb">inform request behaviour</seealso>
+ configuration option for more info.</p>
+ </item>
+ <item>
+ <p><c>Pdu</c> is an SNMP PDU record, as defined in
+ <c>snmp_types.hrl</c>, with the SNMP request.</p>
+ </item>
+ <item>
+ <p><c>Domain</c> is the source transport domain. </p>
+ </item>
+ <item>
+ <p><c>Addr</c> is the source address. </p>
+ </item>
+ </list>
+
+ <pre>
Server ! {snmp_report, Data, Domain, Addr}
- </pre>
- <list type="bulleted">
- <item>
- <p><c>Data</c> is either <c>{ok, Pdu}</c> or
- <c>{error, ReqId, ReasonInfo, Pdu}</c>. Which one is used depends
- on the return value from the MPD
- <seealso marker="snmpm_mpd#process_msg">process_msg</seealso> function. If the MsgData is <c>ok</c>,
- the first is used, and if it is <c>{error, ReqId, Reason}</c>
- the latter is used.</p>
- </item>
- <item>
- <p><c>Pdu</c> is an SNMP PDU record, as defined in
- <c>snmp_types.hrl</c>, with the SNMP request.</p>
- </item>
- <item>
- <p><c>ReqId</c> is an integer.</p>
- </item>
- <item>
- <p><c>ReasonInfo</c> is a term().</p>
- </item>
- <item>
- <p><c>Domain</c> is the source transport domain. </p>
- </item>
- <item>
- <p><c>Addr</c> is the source address. </p>
- </item>
- </list>
+ </pre>
+ <list type="bulleted">
+ <item>
+ <p><c>Data</c> is either <c>{ok, Pdu}</c> or
+ <c>{error, ReqId, ReasonInfo, Pdu}</c>. Which one is used depends
+ on the return value from the MPD
+ <seealso marker="snmpm_mpd#process_msg">process_msg</seealso> function. If the MsgData is <c>ok</c>,
+ the first is used, and if it is <c>{error, ReqId, Reason}</c>
+ the latter is used.</p>
+ </item>
+ <item>
+ <p><c>Pdu</c> is an SNMP PDU record, as defined in
+ <c>snmp_types.hrl</c>, with the SNMP request.</p>
+ </item>
+ <item>
+ <p><c>ReqId</c> is an integer.</p>
+ </item>
+ <item>
+ <p><c>ReasonInfo</c> is a term().</p>
+ </item>
+ <item>
+ <p><c>Domain</c> is the source transport domain. </p>
+ </item>
+ <item>
+ <p><c>Addr</c> is the source address. </p>
+ </item>
+ </list>
+
+ <marker id="om_pong"></marker>
+ <pre>
+Supervisor ! {pong, self()}
+ </pre>
+ <list type="bulleted">
+ <item>
+ <p><c>Supervisor</c> is the process that sent the
+ <seealso marker="#im_ping">ping</seealso> message (see below). </p>
+ </item>
+ </list>
+ </section>
<section>
- <title>Notes</title>
- <p>Since the Net if process is responsible for encoding and
- decoding of SNMP messages, it must also update the relevant
- counters in the SNMP group in MIB-II. It can use the functions
- in the module <c>snmpm_mpd</c> for this purpose (refer to the
- Reference Manual, section <c>snmp</c>, module <c>snmpm_mpd</c>
- for more details).
- </p>
- <p>There are also some useful functions for encoding and
- decoding of SNMP messages in the module <c>snmp_pdus</c>.
- </p>
+ <marker id="incoming_messages"></marker>
+ <title>Incoming Messages</title>
+ <p>This section describes the incoming messages which a Net If
+ process may choose to respond to. </p>
+
+ <list type="bulleted">
+ <item>
+ <marker id="im_ping"></marker>
+ <p><c>{ping, Supervisor}</c></p>
+ <p>This message is sent to the Net If process by a process that
+ has been configured to perfor "active supervision" of the Net If
+ process. The Net If process should respond immediately with
+ a <seealso marker="#om_pong">pong</seealso> message. </p>
+ <list type="bulleted">
+ <item>
+ <p><c>Supervisor</c> is a <c>pid()</c>. </p>
+ </item>
+ </list>
+ </item>
+ </list>
</section>
</section>
+
+ <section>
+ <title>Notes</title>
+ <p>Since the Net if process is responsible for encoding and
+ decoding of SNMP messages, it must also update the relevant
+ counters in the SNMP group in MIB-II. It can use the functions
+ in the module <c>snmpm_mpd</c> for this purpose (refer to the
+ Reference Manual, section <c>snmp</c>, module <c>snmpm_mpd</c>
+ for more details). </p>
+
+ <p>There are also some useful functions for encoding and
+ decoding of SNMP messages in the module <c>snmp_pdus</c>. </p>
+ </section>
</chapter>
diff --git a/lib/snmp/doc/src/snmpm_user.xml b/lib/snmp/doc/src/snmpm_user.xml
index c961300490..fe0ac0b0d2 100644
--- a/lib/snmp/doc/src/snmpm_user.xml
+++ b/lib/snmp/doc/src/snmpm_user.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>2004</year><year>2016</year>
+ <year>2004</year><year>2020</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -96,7 +96,7 @@ snmp_v1_trap_info() :: {Enteprise :: snmp:oid(),
<name since="">handle_error(ReqId, Reason, UserData) -> void()</name>
<fsummary>Handle error</fsummary>
<type>
- <v>ReqId = integer()</v>
+ <v>ReqId = netif | integer()</v>
<v>Reason = {unexpected_pdu, SnmpInfo} | {invalid_sec_info, SecInfo, SnmpInfo} | {empty_message, Addr, Port} | term()</v>
<v>SnmpInfo = snmp_gen_info()</v>
<v>SecInfo = term()</v>
@@ -115,7 +115,11 @@ snmp_v1_trap_info() :: {Enteprise :: snmp:oid(),
<p>If <c>ReqId</c> is less then 0, it means that this
information was not available to the manager (that info was
never retrieved before the message was discarded). </p>
- <p>For <c>SnmpInfo</c> see handle_agent below.</p>
+ <p>For <c>SnmpInfo</c> see handle_agent below.</p>
+ <p>Note that there is a special case when the value of <c>ReqId</c>
+ has the value of the atom <c>netif</c>. This means that the NetIF
+ process has suffered a "fatal" error and been restarted.
+ With possible loss of traffic! </p>
<marker id="handle_agent"></marker>
</desc>
--
2.16.4
