diff options
Diffstat (limited to 'lib/snmp/doc')
| -rw-r--r-- | lib/snmp/doc/src/notes.xml | 22 | ||||
| -rw-r--r-- | lib/snmp/doc/src/snmp_agent_config_files.xml | 260 |
2 files changed, 145 insertions, 137 deletions
diff --git a/lib/snmp/doc/src/notes.xml b/lib/snmp/doc/src/notes.xml index 40e761b2af..21c417f0c1 100644 --- a/lib/snmp/doc/src/notes.xml +++ b/lib/snmp/doc/src/notes.xml @@ -62,6 +62,28 @@ <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> + + <item> <p>[agent] The counter increment function in the local-db was incorrect. It did not handle counter wrap correctly. </p> <p>Own Id: OTP-11192</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> |