aboutsummaryrefslogtreecommitdiffstats
path: root/lib/snmp/doc/src
diff options
context:
space:
mode:
authorMicael Karlberg <[email protected]>2013-06-25 12:38:17 +0200
committerMicael Karlberg <[email protected]>2013-07-04 11:21:43 +0200
commita6ba7a3327b146d8472b154cc8ba4544f9d4d0fe (patch)
tree051a8e4d9168e8d369663ddcfb68fc9bb9fb5af0 /lib/snmp/doc/src
parentf9967a625fe06d47f374e30959f6bb6f098cb25e (diff)
downloadotp-a6ba7a3327b146d8472b154cc8ba4544f9d4d0fe.tar.gz
otp-a6ba7a3327b146d8472b154cc8ba4544f9d4d0fe.tar.bz2
otp-a6ba7a3327b146d8472b154cc8ba4544f9d4d0fe.zip
[snmp/agent] Cleanup, renaming, appup, proper version and release notes
Add utility functions for checking view masks. Code cleanup, function renaming and comment fix (%% instead of %). Also updated the mask check in the vacm config file check function. Finally, release notes and some cosmetic changes to the agent config-file(s) user guide chapter.
Diffstat (limited to 'lib/snmp/doc/src')
-rw-r--r--lib/snmp/doc/src/notes.xml74
-rw-r--r--lib/snmp/doc/src/snmp_agent_config_files.xml260
2 files changed, 197 insertions, 137 deletions
diff --git a/lib/snmp/doc/src/notes.xml b/lib/snmp/doc/src/notes.xml
index 80de9738f1..9f668bf28a 100644
--- a/lib/snmp/doc/src/notes.xml
+++ b/lib/snmp/doc/src/notes.xml
@@ -34,6 +34,80 @@
<section>
+ <title>SNMP Development Toolkit 4.24.1</title>
+ <p>Version 4.24.1 supports code replacement in runtime from/to
+ version 4.24, 4.23.1 and 4.23. </p>
+
+ <section>
+ <title>Improvements and new features</title>
+ <p>-</p>
+
+<!--
+ <list type="bulleted">
+ <item>
+ <p>[agent,manager] Updated to support the new crypto interface. </p>
+ <p>Own Id: OTP-11009</p>
+ </item>
+
+ </list>
+-->
+
+ </section>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+<!--
+ <p>-</p>
+-->
+
+ <list type="bulleted">
+ <item>
+ <p>[agent] Reading the value of the vacmViewTreeFamilyMask returns
+ it in the wrong (internal bitlist) format. </p>
+ <p>The vacmViewTreeFamilyMask is defined as a bit string in the MIB
+ (OCTET STRING). Internally a bitlist (list of 1's and 0's,
+ see <seealso marker="snmp_agent_config_files#vacm">vacm config file</seealso>
+ for more info) is used.
+ However, the MIB implementation assumed the latter, effectively
+ rendering all attempts to read/set masks via SNMP unsuccessful. </p>
+ <p>Since the mask is used in hot paths (e.g. access permission checks
+ for each SNMP operation, the bitlist representation of the mask has
+ benefits (e.g. faster processing). Reading/writing the view mask
+ objects is less time-critical. Therefore, to fix the issue, convert
+ between the bitlist (internal) representation and bitstring
+ (external) when the vacmViewTreeFamilyMask objects are accessed. </p>
+ <p>Also, the check of the vacm config file was invalid with
+ regard to the mask value. It was assumed to be a proper oid, which
+ is not strictly the case (see bitlist above). </p>
+ <p>Own Id: OTP-11177</p>
+ <p>Stefan Zegenhagen</p>
+ </item>
+
+ </list>
+
+ </section>
+
+ <section>
+ <title>Incompatibilities</title>
+ <p>-</p>
+
+<!--
+ <list type="bulleted">
+ <item>
+ <p>[manager] The old Addr-and-Port based API functions, previously
+ long deprecated and marked for deletion in R16B, has now been
+ removed. </p>
+ <p>Own Id: OTP-10027</p>
+ </item>
+
+ </list>
+-->
+ </section>
+
+ </section> <!-- 4.24.1 -->
+
+
+ <section>
<title>SNMP Development Toolkit 4.24</title>
<p>Version 4.24 supports code replacement in runtime from/to
version 4.23.1 and 4.23. </p>
diff --git a/lib/snmp/doc/src/snmp_agent_config_files.xml b/lib/snmp/doc/src/snmp_agent_config_files.xml
index bd5c537522..866b00b77b 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>2011</year>
+ <year>1997</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -32,13 +32,15 @@
<file>snmp_agent_config_files.xml</file>
</header>
<p>All configuration data must be included in configuration files
- that are located in the configuration directory. The name of this
- directory is given in the <c>config_dir</c> configuration
- parameter. These files are read at start-up, and are used to
- initialize the SNMPv2-MIB or STANDARD-MIB, SNMP-FRAMEWORK-MIB,
- SNMP-MPD-MIB, SNMP-VIEW-BASED-ACM-MIB, SNMP-COMMUNITY-MIB,
- SNMP-USER-BASED-SM-MIB, SNMP-TARGET-MIB and SNMP-NOTIFICATION-MIB
- (refer to the <seealso marker="snmp_agent_funct_descr#management">Management of the Agent</seealso> for a description of the MIBs). </p>
+ that are located in the configuration directory. The name of this
+ directory is given in the <c>config_dir</c> configuration
+ parameter. These files are read at start-up, and are used to
+ initialize the SNMPv2-MIB or STANDARD-MIB, SNMP-FRAMEWORK-MIB,
+ SNMP-MPD-MIB, SNMP-VIEW-BASED-ACM-MIB, SNMP-COMMUNITY-MIB,
+ SNMP-USER-BASED-SM-MIB, SNMP-TARGET-MIB and SNMP-NOTIFICATION-MIB
+ (refer to the
+ <seealso marker="snmp_agent_funct_descr#management">Management of the Agent</seealso>
+ for a description of the MIBs). </p>
<p>The files are: </p>
<list type="bulleted">
<item>
@@ -79,35 +81,35 @@
</item>
</list>
<p>The directory where the configuration files are found is given as
- a parameter to the agent. </p>
+ a parameter to the agent. </p>
<p>The entry format in all files are Erlang terms, separated by a
- '<em>.</em>' and a <em>newline</em>. In the following sections, the
- formats of these terms are described. Comments may be specified as
- ordinary Erlang comments. </p>
+ '<em>.</em>' and a <em>newline</em>. In the following sections, the
+ formats of these terms are described. Comments may be specified as
+ ordinary Erlang comments. </p>
<p>Syntax errors in these files are discovered and reported with the
- function <c>config_err/2</c> of the error report module at start-up. </p>
-
+ function <c>config_err/2</c> of the error report module at start-up. </p>
+
+ <marker id="agent_information"></marker>
+
<section>
- <marker id="agent_information"></marker>
<title>Agent Information</title>
<p>The agent information should be stored in a file called
- <c>agent.conf</c>.
- </p>
- <p>Each entry is a tuple of size two:
- </p>
+ <c>agent.conf</c>. </p>
+ <p>Each entry is a tuple of size two:</p>
<p><c>{AgentVariable, Value}.</c></p>
<list type="bulleted">
- <item><c>AgentVariable</c> is one of the variables is
- SNMP-FRAMEWORK-MIB or one of the internal variables
- <c>intAgentUDPPort</c>, which defines which UDP port the agent
- listens to, or <c>intAgentIpAddress</c>, which defines the IP
- address of the agent.
+ <item>
+ <p><c>AgentVariable</c> is one of the variables is
+ SNMP-FRAMEWORK-MIB or one of the internal variables
+ <c>intAgentUDPPort</c>, which defines which UDP port the agent
+ listens to, or <c>intAgentIpAddress</c>, which defines the IP
+ address of the agent. </p>
</item>
- <item><c>Value</c> is the value for the variable.
+ <item>
+ <p><c>Value</c> is the value for the variable.</p>
</item>
</list>
- <p>The following example shows a <c>agent.conf</c> file:
- </p>
+ <p>The following example shows a <c>agent.conf</c> file: </p>
<pre>
{intAgentUDPPort, 4000}.
{intAgentIpAddress,[141,213,11,24]}.
@@ -115,49 +117,47 @@
{snmpEngineMaxPacketSize, 484}.
</pre>
<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>
+ deployed agent should have a very specific structure. See
+ RFC 2271/2571 for details.</p>
+
+ <marker id="context"></marker>
</section>
<section>
- <marker id="context"></marker>
<title>Contexts</title>
<p>The context information should be stored in a file called
- <c>context.conf</c>. The default context <c>""</c>
- need not be present.
- </p>
+ <c>context.conf</c>. The default context <c>""</c>
+ need not be present.</p>
<p>Each row defines a context in the agent. This information is
- used in the table <c>vacmContextTable</c> in the
- SNMP-VIEW-BASED-ACM-MIB.
- </p>
- <p>Each entry is a term:
- </p>
+ used in the table <c>vacmContextTable</c> in the
+ SNMP-VIEW-BASED-ACM-MIB.</p>
+ <p>Each entry is a term:</p>
<p><c>ContextName.</c></p>
<list type="bulleted">
- <item><c>ContextName</c> is a string.
+ <item>
+ <p><c>ContextName</c> is a string.</p>
</item>
</list>
+
+ <marker id="system_information"></marker>
</section>
<section>
- <marker id="system_information"></marker>
<title>System Information</title>
<p>The system information should be stored in a file called
- <c>standard.conf</c>.
- </p>
- <p>Each entry is a tuple of size two:
- </p>
+ <c>standard.conf</c>.</p>
+ <p>Each entry is a tuple of size two:</p>
<p><c>{SystemVariable, Value}.</c></p>
<list type="bulleted">
- <item><c>SystemVariable</c> is one of the variables in the
- system group, or <c>snmpEnableAuthenTraps</c>.
+ <item>
+ <p><c>SystemVariable</c> is one of the variables in the
+ system group, or <c>snmpEnableAuthenTraps</c>. </p>
</item>
- <item><c>Value</c> is the value for the variable.
+ <item>
+ <p><c>Value</c> is the value for the variable. </p>
</item>
</list>
- <p>The following example shows a valid <c>standard.conf</c> file:
- </p>
+ <p>The following example shows a valid <c>standard.conf</c> file: </p>
<pre>
{sysDescr, "Erlang SNMP agent"}.
{sysObjectID, [1,2,3]}.
@@ -167,59 +167,60 @@
{snmpEnableAuthenTraps, enabled}.
</pre>
<p>A value must be provided for all variables, which lack default
- values in the MIB.
- </p>
+ values in the MIB. </p>
+
+ <marker id="community"></marker>
</section>
<section>
- <marker id="community"></marker>
<title>Communities</title>
<p>The community information should be stored in a file called
- <c>community.conf</c>. It must be present if the agent is
- configured for SNMPv1 or SNMPv2c.
- </p>
+ <c>community.conf</c>. It must be present if the agent is
+ configured for SNMPv1 or SNMPv2c. </p>
<p>An SNMP <em>community</em> is a relationship between an SNMP
agent and a set of SNMP managers that defines authentication, access
control and proxy characteristics. </p>
<p>The corresponding table is <c>snmpCommunityTable</c> in the
- SNMP-COMMUNITY-MIB. </p>
+ SNMP-COMMUNITY-MIB. </p>
<p>Each entry is a term: </p>
- <p><c>{CommunityIndex, CommunityName, SecurityName, ContextName, TransportTag}.</c></p>
+ <p><c>{CommunityIndex, CommunityName, SecurityName, ContextName, TransportTag}.</c> </p>
<list type="bulleted">
- <item><c>CommunityIndex</c> is a non-empty string.
+ <item>
+ <p><c>CommunityIndex</c> is a non-empty string.</p>
</item>
- <item><c>CommunityName</c> is a string.
+ <item>
+ <p><c>CommunityName</c> is a string.</p>
</item>
- <item><c>SecurityName</c> is a string.
+ <item>
+ <p><c>SecurityName</c> is a string.</p>
</item>
- <item><c>ContextName</c> is a string.
+ <item>
+ <p><c>ContextName</c> is a string.</p>
</item>
- <item><c>TransportTag</c> is a string.
+ <item>
+ <p><c>TransportTag</c> is a string.</p>
</item>
</list>
+
+ <marker id="vacm"></marker>
</section>
<section>
- <marker id="vacm"></marker>
<title>MIB Views for VACM</title>
<p>The information about MIB Views for VACM should be stored in a
- file called
- <c>vacm.conf</c>.
- </p>
+ file called <c>vacm.conf</c>.</p>
<p>The corresponding tables are <c>vacmSecurityToGroupTable</c>,
- <c>vacmAccessTable</c> and <c>vacmViewTreeFamilyTable</c> in the
- SNMP-VIEW-BASED-ACM-MIB.
- </p>
+ <c>vacmAccessTable</c> and <c>vacmViewTreeFamilyTable</c> in the
+ SNMP-VIEW-BASED-ACM-MIB.</p>
<p>Each entry is one of the terms, one entry corresponds to one
- row in one of the tables.
- </p>
+ row in one of the tables.</p>
<p><c>{vacmSecurityToGroup, SecModel, SecName, GroupName}.</c></p>
<p><c>{vacmAccess, GroupName, Prefix, SecModel, SecLevel, Match, ReadView, WriteView, NotifyView}.</c></p>
<p><c>{vacmViewTreeFamily, ViewIndex, ViewSubtree, ViewStatus, ViewMask}.</c></p>
<list type="bulleted">
<item>
<p><c>SecModel</c> is <c>any</c>, <c>v1</c>, <c>v2c</c>, or
- <c>usm</c>.</p>
+ <c>usm</c>.</p>
</item>
<item>
<p><c>SecName</c> is a string.</p>
@@ -232,7 +233,7 @@
</item>
<item>
<p><c>SecLevel</c> is <c>noAuthNoPriv</c>, <c>authNoPriv</c>,
- or <c>authPriv</c></p>
+ or <c>authPriv</c></p>
</item>
<item>
<p><c>Match</c> is <c>prefix</c> or <c>exact</c>.</p>
@@ -244,8 +245,7 @@
<p><c>WriteView</c> is a string.</p>
</item>
<item>
- <p><c>NotifyView</c> is a string.
- </p>
+ <p><c>NotifyView</c> is a string.</p>
</item>
<item>
<p><c>ViewIndex</c> is an integer.</p>
@@ -258,33 +258,29 @@
</item>
<item>
<p><c>ViewMask</c> is either <c>null</c> or a list of ones and
- zeros. Ones nominate that an exact match is used for this
- sub-identifier. Zeros are wild-cards which match any
- sub-identifier. If the mask is shorter than the sub-tree, the
- tail is regarded as all ones. <c>null</c> is shorthand for a
- mask with all ones.</p>
+ zeros. Ones nominate that an exact match is used for this
+ sub-identifier. Zeros are wild-cards which match any
+ sub-identifier. If the mask is shorter than the sub-tree, the
+ tail is regarded as all ones. <c>null</c> is shorthand for a
+ mask with all ones. </p>
</item>
</list>
+
+ <marker id="usm"></marker>
</section>
<section>
- <marker id="usm"></marker>
<title>Security data for USM</title>
<p>The information about Security data for USM should be stored in a
- file called
- <c>usm.conf</c>, which must be present if the agent is configured
- for SNMPv3.
- </p>
+ file called <c>usm.conf</c>, which must be present if the agent is
+ configured for SNMPv3. </p>
<p>The corresponding table is <c>usmUserTable</c> in the
- SNMP-USER-BASED-SM-MIB.
- </p>
- <p>Each entry is a term:
- </p>
+ SNMP-USER-BASED-SM-MIB.</p>
+ <p>Each entry is a term:</p>
<p><c>{EngineID, UserName, SecName, Clone, AuthP, AuthKeyC, OwnAuthKeyC, PrivP, PrivKeyC, OwnPrivKeyC, Public, AuthKey, PrivKey}.</c></p>
<list type="bulleted">
<item>
- <p><c>EngineID</c> is a string.
- </p>
+ <p><c>EngineID</c> is a string.</p>
</item>
<item>
<p><c>UserName</c> is a string.</p>
@@ -297,7 +293,7 @@
</item>
<item>
<p><c>AuthP</c> is a <c>usmNoAuthProtocol</c>,
- <c>usmHMACMD5AuthProtocol</c>, or <c>usmHMACSHAAuthProtocol</c>.</p>
+ <c>usmHMACMD5AuthProtocol</c>, or <c>usmHMACSHAAuthProtocol</c>.</p>
</item>
<item>
<p><c>AuthKeyC</c> is a string.</p>
@@ -307,7 +303,7 @@
</item>
<item>
<p><c>PrivP</c> is a <c>usmNoPrivProtocol</c>,
- <c>usmDESPrivProtocol</c> or <c>usmAesCfb128Protocol</c>.</p>
+ <c>usmDESPrivProtocol</c> or <c>usmAesCfb128Protocol</c>.</p>
</item>
<item>
<p><c>PrivKeyC</c> is a string.</p>
@@ -319,66 +315,59 @@
<p><c>Public</c> is a string.</p>
</item>
<item>
- <p><c>AuthKey</c> is a list (of integer). This is the User's secret
- localized authentication key. It is not visible in the MIB. The length
- of this key needs to be 16 if <c>usmHMACMD5AuthProtocol</c> is used, and
- 20 if <c>usmHMACSHAAuthProtocol</c> is used.</p>
+ <p><c>AuthKey</c> is a list (of integer). This is the User's secret
+ localized authentication key. It is not visible in the MIB. The length
+ of this key needs to be 16 if <c>usmHMACMD5AuthProtocol</c> is used,
+ and 20 if <c>usmHMACSHAAuthProtocol</c> is used.</p>
</item>
<item>
<p><c>PrivKey</c> is a list (of integer). This is the User's secret
- localized encryption key. It is not visible in the MIB. The length
- of this key needs to be 16 if <c>usmDESPrivProtocol</c> or
- <c>usmAesCfb128Protocol</c> is used.
- </p>
+ localized encryption key. It is not visible in the MIB. The length
+ of this key needs to be 16 if <c>usmDESPrivProtocol</c> or
+ <c>usmAesCfb128Protocol</c> is used. </p>
</item>
</list>
+
+ <marker id="notify"></marker>
</section>
<section>
- <marker id="notify"></marker>
<title>Notify Definitions</title>
<p>The information about Notify Definitions should be stored in a
- file called
- <c>notify.conf</c>.
- </p>
+ file called <c>notify.conf</c>. </p>
<p>The corresponding table is <c>snmpNotifyTable</c> in the
- SNMP-NOTIFICATION-MIB.
- </p>
- <p>Each entry is a term:
- </p>
+ SNMP-NOTIFICATION-MIB.</p>
+ <p>Each entry is a term:</p>
<p><c>{NotifyName, Tag, Type}.</c></p>
<list type="bulleted">
<item>
- <p><c>NotifyName</c> is a unique non-empty string.
- </p>
+ <p><c>NotifyName</c> is a unique non-empty string.</p>
</item>
<item>
- <p><c>Tag</c> is a string.
- </p>
+ <p><c>Tag</c> is a string.</p>
</item>
<item>
- <p><c>Type</c> is <c>trap</c> or <c>inform</c>.
- </p>
+ <p><c>Type</c> is <c>trap</c> or <c>inform</c>.</p>
</item>
</list>
+
+ <marker id="target_addr"></marker>
</section>
<section>
- <marker id="target_addr"></marker>
<title>Target Address Definitions</title>
<p>The information about Target Address Definitions should be
- stored in a file called <c>target_addr.conf</c>. </p>
+ stored in a file called <c>target_addr.conf</c>. </p>
<p>The corresponding tables are <c>snmpTargetAddrTable</c> in the
- SNMP-TARGET-MIB and <c>snmpTargetAddrExtTable</c> in the
- SNMP-COMMUNITY-MIB. </p>
+ SNMP-TARGET-MIB and <c>snmpTargetAddrExtTable</c> in the
+ SNMP-COMMUNITY-MIB. </p>
<p>Each entry is a term: </p>
<p><c>{TargetName, Ip, Udp, Timeout, RetryCount, TagList, ParamsName, EngineId}.</c> <br></br> or <br></br>
<c>{TargetName, Ip, Udp, Timeout, RetryCount, TagList, ParamsName, EngineId, TMask, MaxMessageSize}.</c> <br></br> or <br></br>
-<c>{TargetName, Domain, Ip, Udp, Timeout, RetryCount, TagList, ParamsName, EngineId, TMask, MaxMessageSize}.</c></p>
+<c>{TargetName, Domain, Ip, Udp, Timeout, RetryCount, TagList, ParamsName, EngineId, TMask, MaxMessageSize}.</c> </p>
<list type="bulleted">
<item>
- <p><c>TargetName</c> is a unique non-empty string.
- </p>
+ <p><c>TargetName</c> is a unique non-empty string. </p>
</item>
<item>
<p><c>Domain</c> is one of the atoms:
@@ -414,40 +403,37 @@
</item>
</list>
<p>Note that if <c>EngineId</c> has the value <c>discovery</c>,
- the agent cannot send
- <c>inform</c> messages to that manager until it has performed the
- <em>discovery</em> process with that manager. </p>
+ the agent cannot send
+ <c>inform</c> messages to that manager until it has performed the
+ <em>discovery</em> process with that manager. </p>
+
+ <marker id="target_params"></marker>
</section>
<section>
- <marker id="target_params"></marker>
<title>Target Parameters Definitions</title>
<p>The information about Target Parameters Definitions should be
- stored in a file called <c>target_params.conf</c>. </p>
+ stored in a file called <c>target_params.conf</c>. </p>
<p>The corresponding table is <c>snmpTargetParamsTable</c> in the
- SNMP-TARGET-MIB. </p>
+ SNMP-TARGET-MIB. </p>
<p>Each entry is a term: </p>
<p><c>{ParamsName, MPModel, SecurityModel, SecurityName, SecurityLevel}.</c></p>
<list type="bulleted">
<item>
- <p><c>ParamsName</c> is a unique non-empty string.
- </p>
+ <p><c>ParamsName</c> is a unique non-empty string. </p>
</item>
<item>
<p><c>MPModel</c> is <c>v1</c>, <c>v2c</c> or <c>v3</c></p>
</item>
<item>
- <p><c>SecurityModel</c> is <c>v1</c>, <c>v2c</c>, or <c>usm</c>.
- </p>
+ <p><c>SecurityModel</c> is <c>v1</c>, <c>v2c</c>, or <c>usm</c>.</p>
</item>
<item>
- <p><c>SecurityName</c> is a string.
- </p>
+ <p><c>SecurityName</c> is a string.</p>
</item>
<item>
<p><c>SecurityLevel</c> is <c>noAuthNoPriv</c>, <c>authNoPriv</c>
- or <c>authPriv</c>.
- </p>
+ or <c>authPriv</c>. </p>
</item>
</list>
</section>