Subject: Re: coex draft

From: "C. M. Heard" <[email-masked]>
Date: Sat, 1 Mar 2003 23:59:05 -0800 (PST)

On Fri, 28 Feb 2003, David Levi wrote:
> Here is a change-bar version of the new coex draft (this is not
> the official version).  This will be submitted tomorrow to the
> ID editor.  Also, I've attached a list of responses to the lists
> of proposed changes.

I've gone over the changes in this version and I'd like to thank
the editors for all their hard work.  However, there are still a
few small things wrong that I feel should be corrected before the
document will be ready for last call.  They are listed below, and
in an attachment there is a suggestion for a re-ordering of the
change log that I think will be helpful to future readers.

Regards,

Mike Heard

[#1] The following text in Section 2.1.1 has a grammatical error:

(9)  If any INDEX clause contains a reference to an object with a syntax
     of NetworkAddress, then a new object MUST be created and placed in
     this INDEX clause immediately preceding the object whose syntax is
     NetworkAddress.  This new object MUST have a syntax of INTEGER, it
     MUST be not-accessible, and its value MUST always be 1.  This        |
     effect of this, and the preceding bullet, is to allow one to         |
     convert a MIB module in SMIv1 format                                 |
     to one in SMIv2 format, and then use it with the SNMPv1 protocol
     with no impact to existing SNMPv1 agents and managers.

Fix:  s/This effect of this,/The effect of this,/

[#2] There is probably an error in the nroff source that caused the last
line (marked X) of the following bullet in Section 3.2 to be lost:

(1)  The SNMPv1 enterprise parameter SHALL be determined as follows:

       -  If the SNMPv2 snmpTrapOID parameter is one of the standard
          traps as defined in RFC 3418 [RFC3418], then the SNMPv1         |
          enterprise parameter SHALL be                                   |
          set to the value of the variable-binding in the SNMPv2
          variable-bindings whose name is snmpTrapEnterprise.0 if that
          variable-binding exists.  If it does not exist, the SNMPv1      |
          enterprise parameter SHALL be set to the value                  |
          'snmpTraps' as defined in RFC 3418 [RFC3418].                   X

Fix:  re-arrange the nroff source so that the opening single quote
of 'snmpTraps' does not appear at the beginning of a line.

[#3] The following text at the end of Section 4.2.2 (which used to be 4.1.2)
appears to have been edited incorrectly.  The text says:

   The following sections describe the behaviour of a command responder
   application which supports multiple SNMP message versions, and which   |
   uses some SNMPv2 access to MIB data when processing an SNMPv2c or      |
   SNMPv3 message.                                                        |

However, the "changes.txt" attachment said this:

% >   I believe it would be easier to follow if the introduction to
% > section 4.1.2 stated up front, that the rest of the section
% > referred purely to SNMPv2 access to MIB data in response to
% > an SNMPv1 request.
% 
% Changed the text at the end of the section to state this.

It is suggested that the paragraph in question should read like this:

   The following sections describe the behaviour of a command responder
   application which supports multiple SNMP message versions, and which   |
   uses SNMPv2 access to MIB data when processing an SNMPv1 message.      |

[#4] The first paragraph of Section 4.2.2.1 has an incorrect reference:

   The SMIv2 [RFC2579] defines one new syntax that is incompatible with   |
   SMIv1.  This syntax is Counter64.  All other syntaxes defined by
   SMIv2 are compatible with SMIv1.

Fix:  s/[RFC2579]/[RFC2578]/

[#5] The following text in Section 5.3 has a grammatical error:

   Note that the snmpTargetAddrTMask object is only used where
   explicitly stated.  In particular, it is not used when generating
   notifications (i.e., when generating notifications, entries in the
   snmpTargetAddrTable only specify individual addresses).  If use of     |
   the snmpTargetAddrTMask object is not mentioned in text describing     |
   matching addresses in the snmpTargetAddrTable, then it's value MUST    |
   be ignored.                                                            |

Fix:  s/it's/its/

[#6] The most recent REVISION clause fails to document the following
changes:

  - the update to the DESCRIPTION clause of snmpCommunityName;

  - the addition of snmpCommunityMIBFullCompliance.

[#7] The following clarification in the definition of snmpCommunityName
does not appear to be correct:

      snmpCommunityName OBJECT-TYPE
          SYNTAX       OCTET STRING
          MAX-ACCESS   read-create
          STATUS       current
          DESCRIPTION
              "The community string for which a row in this table
               represents a configuration.  Although there is no SIZE     |
               restriction specified on this object, in practice, we do   |
               not expect people to use community names that are too      |
               long to cause the OID for an instance of this object to    |
               be more than 128 sub-identifiers. If they get longer,      |
               they may not be supported by (currently) existing SNMP     |
               engines."                                                  |
          ::= { snmpCommunityEntry 2 }

The revised description is written as if snmpCommunityName were being
used as an index, which is not the case (the index for this table is
snmpCommunityIndex, which is limited to 32 octets).  The following
alternate wording is suggested:

      snmpCommunityName OBJECT-TYPE
          SYNTAX       OCTET STRING
          MAX-ACCESS   read-create
          STATUS       current
          DESCRIPTION
              "The community string for which a row in this table
               represents a configuration.  There is no SIZE constraint   |
               specified for this object because RFC 1157 does not        |
               impose any explicit limitation on the length of community  |
               strings (their size is constrained indirectly by the       |
               SNMP message size).                                        |
          ::= { snmpCommunityEntry 2 }

[#8] The DESCRIPTION sub-clause of the following OBJECT clause of the
snmpCommunityMIBFullCompliance statement does not match the MIN-ACCESS:

              OBJECT           snmpCommunityName                          +
              MIN-ACCESS       read-create                                +
              DESCRIPTION     "Creation is not required."                 +

Fix: s/is not required/is required/

[#9] There are several omissions from the change log (and one error that
appears to be the result of an nroff source line that starts with a
single quote).  In addition, the somewhat randon order in which the
changes are listed makes it hard for someone (e.g., and implementor of
RFC 2576) to audit the changes and see what the differences are.  The
following diff contains suggestions for additions and corrections;  a
completely re-ordered change log with all of these fixes follows in
the subsequent attachment.

***************
*** 3230,3237 ****
--- 3230,3240 ----
  
     Section numbers below refer to the old section numbers from RFC 2576.
     Some section numbers have changed since RFC 2576.
  
+        -  Changed "MUST" to "SHOULD" in item (3) of the first list in
+           Section 2.1.1 to since unconstrained INTEGER is not actually
+           illegal in SMIv2.
  
         -  Changed "SHOULD" to "MUST" in item (13) of the first list in
            Section 2.1.1 to clarify that collecting related objects into
            groups is required when translating a MIB module from SMIv1 to
***************
*** 3247,3260 ****
--- 3250,3266 ----
         -  In the second bullet of the last part of Section 3 listing the
            SNMPv2 notification parameters, clarified that the snmpTrapOID
            parameter refers to the value portion (not the name portion)
            of the second variable-binding, and changed the wording in the
            text under bullet (1) of Section 3.2 from "the snmpTrapOID" to
            "the snmpTrapOID value" to emphasize this point.
  
+        -  In bullet (6) of Section 3.2 emphasized that the SNMPv2
+           variable-bindings do not include sysUpTime.0 an snmpTrapOID.0.
+ 
         -  In Section 4.2 clarified that the 'Upstream Version' refers to
            the version used between the command generator or notification
            receiver and the proxy, and the 'Downstream Version' refers to
            the version used between the proxy and the command responder
            or notification originator.  RFC 2576 neglected to mention the
            notification receiver and notification originator.
  
***************
*** 3261,3270 ****
         -  In Section 4.2.1 clarified that the error-index field must be
            set to zero in a translated GetResponse-PDU with an error-
!           status of 'tooBig'.
  
!        -  In Section 5.2.1 clarified that the scopedPDU's
!           contextSnmpEngineID and contextName values come from the
!           selected entry in the snmpCommunityTable.
  
         -  Added Section 5.2.4 on Proxy Forwarding Of Requests.
  
--- 3267,3283 ----
         -  In Section 4.2.1 clarified that the error-index field must be
            set to zero in a translated GetResponse-PDU with an error-
!           status of 'tooBig' and made explicit the rationale for retrying
!           a GetBulkRequest-PDU only once.
  
!        -  In Section 5.2.1 clarified that the securityName value and the
!           scopedPDU's contextSnmpEngineID and contextName values come
!           from the selected entry in the snmpCommunityTable.  Also
!           clarified how maxSizeResponseScopedPDU is determined and that
!           securityStateReference must contain the community string of
!           the original request.
  
         -  Added Section 5.2.4 on Proxy Forwarding Of Requests.
  
+        -  In Section 5.3 clarified that snmpTargetAddrTMask is to be
+           ignored whenever its use is not explicitly called for.
+ 
***************
*** 3287,3296 ****
  
         -  Updated the description of `snmpTargetAddrMMS' to clarify that
            a value of 0 means that the maximum message size is unknown.
  
!        -  Changed the name of 'snmpCommunityGroup' to a name conflict
!           with the SNMPv2-MIB.
  
         -  Divided references into Normative References and Informative
            Reference and updated them to point to current documents.
  
--- 3300,3310 ----
  
         -  Updated the description of `snmpTargetAddrMMS' to clarify that
            a value of 0 means that the maximum message size is unknown.
  
!        -  Changed the name of 'snmpCommunityGroup'
!           to 'snmpCommunityTableGroup' in order to
!           resolve a name conflict with the SNMPv2-MIB.
  
         -  Divided references into Normative References and Informative
            Reference and updated them to point to current documents.
  
***************
*** 3300,3307 ****
--- 3314,3333 ----
  
         -  Re-organized bullets in section 2.1.1 to improve clarity.
  
+        -  In Section 4.1.2 added text noting that SNMPv1 access to MIB
+           data SHOULD NOT be used when processing SNMPv2c or SNMPv3
+           messages and re-worded final paragraph to note that the
+           sub-sections that follow are concerned solely with command
+           responders that use SNMPv2 access to MIB data while processing
+           an SNMPv1 request.
+ 
         -  Re-worded first bullet, section 4.2.1, to make it more
            readable.
+ 
+        -  Added text to the Deployment Hint in Section 4.2.2 to clarify
+           that different principals should be used for SNMPv1 requests
+           and SNMPv2/v3c requests if for SNMPv1 requests a principal for
+           which Counter64 objects are not-in-view is used.
  
         -  Added text to abstract about conversion of MIBs from SMIv1 to
            SMIv2.
   B.1.  Changes From RFC 2576

   Section numbers below refer to the old section numbers from RFC 2576.
   Some section numbers have changed since RFC 2576.

       -  Added text to abstract about conversion of MIBs from SMIv1 to
          SMIv2.

       -  Added note at end of section 1.3 that all discussion of SNMPv2
          PDU types and protocol operations applies to both SNMPv2c and
          SNMPv3.

       -  Added text at end of section 1.4 to clarify that there is no
          such thing as 'SNMPv3 access to MIB data,' as SNMPv3 just uses
          SNMPv2 PDU types and protocol operations.

       -  Moved section 1.4 to the beginning of section 4.

       -  Changed "MUST" to "SHOULD" in item (3) of the first list in
          Section 2.1.1 to since unconstrained INTEGER is not actually
          illegal in SMIv2.

       -  Changed "SHOULD" to "MUST" in item (13) of the first list in
          Section 2.1.1 to clarify that collecting related objects into
          groups is required when translating a MIB module from SMIv1 to
          SMIv2.

       -  Re-organized bullets in section 2.1.1 to improve clarity.

       -  Changed "SHOULD" to "MUST" in items (1) and (2) of Section 2.3
          since those updates are indeed required when translating a
          capabilities statement from the language defined by RFC 1303
          into SMIv2.

       -  In the second bullet of the last part of Section 3 listing the
          SNMPv2 notification parameters, clarified that the snmpTrapOID
          parameter refers to the value portion (not the name portion)
          of the second variable-binding, and changed the wording in the
          text under bullet (1) of Section 3.2 from "the snmpTrapOID" to
          "the snmpTrapOID value" to emphasize this point.

       -  In bullet (6) of Section 3.2 emphasized that the SNMPv2
          variable-bindings do not include sysUpTime.0 an snmpTrapOID.0.

       -  In Section 4.2 clarified that the 'Upstream Version' refers to
          the version used between the command generator or notification
          receiver and the proxy, and the 'Downstream Version' refers to
          the version used between the proxy and the command responder
          or notification originator.  RFC 2576 neglected to mention the
          notification receiver and notification originator.

       -  In Section 4.1.2 added text noting that SNMPv1 access to MIB
          data SHOULD NOT be used when processing SNMPv2c or SNMPv3
          messages and re-worded final paragraph to note that the
          sub-sections that follow are concerned solely with command
          responders that use SNMPv2 access to MIB data while processing
          an SNMPv1 request.

       -  Re-worded first bullet, section 4.2.1, to make it more
          readable.

       -  In Section 4.2.1 clarified that the error-index field must be
          set to zero in a translated GetResponse-PDU with an error-
          status of 'tooBig' and made explicit the rationale for retrying
          a GetBulkRequest-PDU only once.

       -  Added text to the Deployment Hint in Section 4.2.2 to clarify
          that different principals should be used for SNMPv1 requests
          and SNMPv2/v3c requests if for SNMPv1 requests a principal for
          which Counter64 objects are not-in-view is used.

       -  In Section 5.2.1 clarified that the securityName value and the
          scopedPDU's contextSnmpEngineID and contextName values come
          from the selected entry in the snmpCommunityTable.  Also
          clarified how maxSizeResponseScopedPDU is determined and that
          securityStateReference must contain the community string of
          the original request.

       -  Added Section 5.2.4 on Proxy Forwarding Of Requests.

       -  In Section 5.3 clarified that snmpTargetAddrTMask is to be
          ignored whenever its use is not explicitly called for.

       -  Updated the LAST-UPDATED, CONTACT-INFO, and REVISION clauses
          and added a copyright notice to the DESCRIPTION clause of the
          MIB module's MODULE-IDENTITY invocation.

       -  Added text to DESCRIPTION of snmpCommunityName to clarify why
          the object has no size restriction.

       -  Updated the description of snmpCommunityTransportTag to make
          it consistent with the rest of the document.

       -  Updated the description of `snmpTargetAddrMMS' to clarify that
          a value of 0 means that the maximum message size is unknown.

       -  Changed the name of 'snmpCommunityGroup'
          to 'snmpCommunityTableGroup' in order to
          resolve a name conflict with the SNMPv2-MIB.

       -  Added compliance statement to SNMP-COMMUNITY-MIB for full
          read-create compliance.

       -  Divided references into Normative References and Informative
          Reference and updated them to point to current documents.

       -  Inserted current year into all copyright notices.

       -  Corrected various typographical and grammatical errors.