File 3490-snmp-agent-doc-Add-description-for-the-new-transport.patch of Package erlang
From ff925e1763803e889a69545f38907b1825627946 Mon Sep 17 00:00:00 2001
From: Micael Karlberg <bmk@erlang.org>
Date: Fri, 2 Oct 2020 18:29:03 +0200
Subject: [PATCH 20/21] [snmp|agent|doc] Add description for the new transports
Also restructure the agent config documentation a bit.
Link the doc up properly, so that we can find the needed
doc from each entry point (agent information config or
net-if config).
OTP-16649
---
lib/snmp/doc/src/snmp_agent_config_files.xml | 84 ++++++++++++++++----
lib/snmp/doc/src/snmp_app.xml | 27 ++++---
lib/snmp/doc/src/snmp_config.xml | 23 ++++--
3 files changed, 99 insertions(+), 35 deletions(-)
diff --git a/lib/snmp/doc/src/snmp_agent_config_files.xml b/lib/snmp/doc/src/snmp_agent_config_files.xml
index 7fda4da31f..e4f261410b 100644
--- a/lib/snmp/doc/src/snmp_agent_config_files.xml
+++ b/lib/snmp/doc/src/snmp_agent_config_files.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>
@@ -100,7 +100,7 @@
<p><c>{AgentVariable, Value}.</c></p>
<list type="bulleted">
<item>
- <p><c>AgentVariable</c> is one of the variables is
+ <p><c>AgentVariable</c> is one of the variables in
SNMP-FRAMEWORK-MIB or one of the internal variables
<c>intAgentUDPPort</c>, which defines which UDP port the agent
listens to, or <c>intAgentTransports</c>, which defines the
@@ -119,29 +119,79 @@
{snmpEngineID, "mbj's engine"}.
{snmpEngineMaxPacketSize, 484}.
</pre>
- <p>The value of <c>intAgentTransports</c> is a list of
- <c>{Domain, Addr}</c> tuples, where <c>Domain</c>
- is either <c>transportDomainUdpIpv4</c> or <c>transportDomainUdpIpv6</c>,
- and <c>Addr</c> is the address in the domain.
- <c>Addr</c> can be specified either as an
- <c>IpAddr</c> or as an <c>{IpAddr, IpPort}</c> tuple.
- <c>IpAddr</c> is either a regular Erlang/OTP
- <seealso marker="kernel:inet#type-ip_address"><c>ip_address()</c></seealso>
- or a traditional SNMP integer list and <c>IpPort</c> is an integer.
- </p>
- <p>When the <c>Addr</c> value does not contain a port number,
+ <p>These are the supported entries and their value types: </p>
+
+ <pre>
+ {snmpEngine, string()}. % Mandatory
+ {snmpEngineMaxMessageSize, non_neg_integer()}. % Mandatory
+ {intAgentUDPPort, pos_integer()}. % Optional
+ {intAgentTransports, intAgentTransports()}. % Mandatory
+ </pre>
+
+ <p>And here are the transport value types: </p>
+
+ <pre>
+ intAgentTransports() :: [intAgentTransport()].
+ intAgentTransport() :: {TDomain, Addr} |
+ {TDomain, EAddr, Kind} |
+ {TDomain, EAddr, Opts} |
+ {TDomain, EAddr, Kind, Opts}
+ TDomain :: transportDomainUdpIpv4 | transportDomainUdpIpv6.
+ Addr :: {IpAddr, IpPort} | IpAddr.
+ IpAddr :: <seealso marker="kernel:inet#type-ip_address"><c>inet:ip_address()</c></seealso> | snmpIpAddr().
+ snmpIpAddr() :: [non_neg_integer()].
+ IpPort :: pos_integer().
+ EAddr :: {<seealso marker="kernel:inet#type-ip_address"><c>inet:ip_address()</c></seealso>, PortInfo}.
+ PortInfo :: pos_integer() | system | range() | ranges().
+ range() :: {Min :: pos_integer(), Max :: pos_integer()}, Min < Max
+ ranges() :: [pos_integer() | range()].
+ Kind :: req_responder | trap_sender.
+ Opts :: list().
+ </pre>
+
+ <p>If a "traditional" transport is specified (without explicit <c>Kind</c>,
+ handling both requests and traps) for a transport domain, its <em>not</em>
+ possible to also specify a transport (for that domain) with a specific
+ <c>Kind</c>. This is for example <em>not</em> allowed:</p>
+
+ <pre>
+ [{transportDomainUdpIpv4, {{141,213,11,24}, 4000}},
+ {transportDomainUdpIpv4, {{141,213,11,24}, 4001}, trap_sender}].
+ </pre>
+
+ <p>Note that only one transport per kind for each transport domain
+ can be configured. </p>
+
+ <p><c>PortInfo</c> <c>system</c> is used to indicate that the 'system'
+ should choose (the way port number '0' (zero) is normally used).
+ Port info '0' (zero) cannot be used for this, since it is (internally) used
+ to represent the 'default' port number. </p>
+
+ <p>In the traditional transport entries, when the <c>Addr</c> value
+ does not contain a port number,
the value of <c>intAgentUDPPort</c> is used.</p>
- <p>The legacy and intermediate variables <c>intAgentIpAddress</c>
- and <c>intAgentTransportDomain</c> are still supported so old
- <c>agent.conf</c> files will work.
- </p>
+ <p>Note that the (new) extended transport entries (including <c>Kind</c>
+ and <c>Opts</c>) <em>must</em> specify port-info as they ignore
+ any value specified by <c>intAgentUDPPort</c>.</p>
+ <p><c>Opts</c> is the same as for the
+ <seealso marker="snmp_config#agent_ni_opts">net-if</seealso>
+ process <em>and</em>
+ takes precedence (for that transport) if present.
+ The point is that each transport can have its own socket options. </p>
+
<p>The value of <c>snmpEngineID</c> is a string, which for a
deployed agent should have a very specific structure. See
RFC 2271/2571 for details.</p>
+ <note><p>The legacy and intermediate variables <c>intAgentIpAddress</c>
+ and <c>intAgentTransportDomain</c> are still supported so old
+ <c>agent.conf</c> files will work.</p>
+ <p>But they <em>cannot</em> be combined with intAgentTransports.</p>
+ </note>
+
<marker id="context"></marker>
</section>
diff --git a/lib/snmp/doc/src/snmp_app.xml b/lib/snmp/doc/src/snmp_app.xml
index 3f26476365..31cd01bf61 100644
--- a/lib/snmp/doc/src/snmp_app.xml
+++ b/lib/snmp/doc/src/snmp_app.xml
@@ -271,16 +271,23 @@ in the snmp_config file!
<c><![CDATA[agent_net_if_options() = [agent_net_if_option()] <optional>]]></c></tag>
<item>
<p><c>agent_net_if_option() = {bind_to, bind_to()} |
- {sndbuf, sndbuf()} |
- {recbuf, recbuf()} |
- {no_reuse, no_reuse()} |
- {req_limit, req_limit()} |
- {filter, agent_net_if_filter_options()} |
- {extra_sock_opts, extra_socket_options()}</c></p>
- <p>These options are actually specific to the used module.
- The ones shown here are applicable to the default
- <c>agent_net_if_module()</c>.</p>
- <p>For defaults see the options in <c>agent_net_if_option()</c>.</p>
+ {sndbuf, sndbuf()} |
+ {recbuf, recbuf()} |
+ {no_reuse, no_reuse()} |
+ {req_limit, req_limit()} |
+ {filter, agent_net_if_filter_options()} |
+ {extra_sock_opts, extra_socket_options()}</c></p>
+ <p>These options are actually specific to the used module.
+ The ones shown here are applicable to the default
+ <c>agent_net_if_module()</c>.</p>
+ <note>
+ <p>If the user has configured transports <em>with</em> options
+ then those will take precedence over these options.
+ See
+ <seealso marker="snmp_agent_config_files#agent_information">agent information</seealso>
+ for more info. </p>
+ </note>
+ <p>For defaults see the options in <c>agent_net_if_option()</c>.</p>
</item>
<tag><marker id="agent_ni_req_limit"></marker>
diff --git a/lib/snmp/doc/src/snmp_config.xml b/lib/snmp/doc/src/snmp_config.xml
index 58933ebb2b..97274efbb2 100644
--- a/lib/snmp/doc/src/snmp_config.xml
+++ b/lib/snmp/doc/src/snmp_config.xml
@@ -256,15 +256,22 @@
<c><![CDATA[agent_net_if_options() = [agent_net_if_option()] <optional>]]></c></tag>
<item>
<p><c>agent_net_if_option() = {bind_to, bind_to()} |
- {sndbuf, sndbuf()} |
- {recbuf, recbuf()} |
- {no_reuse, no_reuse()} |
- {req_limit, req_limit()} |
- {filter, agent_net_if_filter_options()} |
- {extra_sock_opts, extra_socket_options()}</c></p>
+ {sndbuf, sndbuf()} |
+ {recbuf, recbuf()} |
+ {no_reuse, no_reuse()} |
+ {req_limit, req_limit()} |
+ {filter, agent_net_if_filter_options()} |
+ {extra_sock_opts, extra_socket_options()}</c></p>
<p>These options are actually specific to the used module.
- The ones shown here are applicable to the default
- <c>agent_net_if_module()</c>.</p>
+ The ones shown here are applicable to the default
+ <c>agent_net_if_module()</c>.</p>
+ <note>
+ <p>If the user has configured transports <em>with</em> options
+ then those will take precedence over these options.
+ See
+ <seealso marker="snmp_agent_config_files#agent_information">agent information</seealso>
+ for more info. </p>
+ </note>
<p>For defaults see the options in <c>agent_net_if_option()</c>.</p>
</item>
--
2.26.2
