[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

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>