[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
guidelines changes to date (WAS: comments on mib review guidelines01)
Howdy all,
Now that IETF 57 is over, I'd like to move forward with the updates
to the MIB review guidelines document ... it's due to expire on
August 24, and I'd like to post a new version before then.
In that vein, I've attached a couple of diffs (one without any
context, and one with full context) showing the list of whi I
understand are the agreed-upon changes. I _think_ this addresses
all the comments I've received on this list to date except for the
following:
(a) replace editor's note in Sec. 3.8 w/ IANA MIB copyright template
(b) add PhysicalIndex and PhysicalIndexOrZero to Appendix D
(c) disposition of Appendices B and C
I'll deal with these other issues in separate e-mail messages in an
attempt to drive them to closure. Please be sure to let me know if
there are any open issues I've missed, or if one of the alleged
agreed-upon changes either was not agreed to or is otherwise flawed.
Regards,
Mike
*** draft-ietf-ops-mib-review-guidelines-01.txt Mon Feb 24 09:27:55 2003
--- draft-ietf-ops-mib-review-guidelines-XX.txt Fri Jul 11 09:53:18 2003
***************
*** 175,184 ****
! Some time ago the IESG instituted a policy of requiring OPS area
! review of IETF standards-track specifications containing MIB modules.
! These reviews were established to ensure that such specifications
! follow established IETF documentation practices and that the MIB
! modules they contain meet certain generally accepted standards of
! quality, including (but not limited to) compliance with all syntactic
! and semantic requirements of SMIv2 (STD 58) [RFC2578] [RFC2579]
! [RFC2580] that are applicable to "standard" MIB modules. The purpose
! of this memo is to document the guidelines that are followed in such
! reviews.
--- 175,183 ----
! Some time ago the IESG instituted a policy of requiring expert review
! of IETF standards-track specifications containing MIB modules. These
! reviews were established to ensure that such specifications follow
! established IETF documentation practices and that the MIB modules
! they contain meet certain generally accepted standards of quality,
! including (but not limited to) compliance with all syntactic and
! semantic requirements of SMIv2 (STD 58) [RFC2578] [RFC2579] [RFC2580]
! that are applicable to "standard" MIB modules. The purpose of this
! memo is to document the guidelines that are followed in such reviews.
***************
*** 223 ****
--- 223 ----
+
***************
*** 288 ****
! conjunction with the IF-MIB [RFC2863] and are required to document
--- 288 ----
! conjunction with the IF-MIB [RFC2863] and are REQUIRED to document
***************
*** 292 ****
! configuration and multiplexing of interface sublayers must contain a
--- 292 ----
! configuration and multiplexing of interface sublayers MUST contain a
***************
*** 431 ****
! module that will appear in the published RFC must contain a pointer
--- 431 ----
! module that will appear in the published RFC MUST contain a pointer
***************
*** 498,500 ****
! the current pool of OPS Area MIB reviewers is that the SMIv2
! recommendation to limit descriptors, TC names, and labels to 32
! characters SHOULD be set aside in favor of promoting clarity and
--- 498,500 ----
! the current pool of MIB reviewers is that the SMIv2 recommendation to
! limit descriptors, TC names, and labels to 32 characters SHOULD be
! set aside in favor of promoting clarity and uniqueness and that
***************
*** 509,510 ****
! uniqueness and that automated tools such as MIB compilers SHOULD NOT
! by default generate warnings for violating that recommendation.
--- 509,510 ----
! automated tools such as MIB compilers SHOULD NOT by default generate
! warnings for violating that recommendation.
***************
*** 773 ****
! possible for such other unusual/irregular events to occur, the the
--- 773 ----
! possible for such other unusual/irregular events to occur, the
***************
*** 780 ****
! of such a discontinuity indicator see the ifCounterDisconuityTime
--- 780 ----
! of such a discontinuity indicator see the
***************
*** 789 ****
! object in the IF-MIB [RFC2863].
--- 789 ----
! ifCounterDiscontinuityTime object in the IF-MIB [RFC2863].
***************
*** 973 ****
! list can be expected to to grow as additional TCs are developed.
--- 973 ----
! list can be expected to grow as additional TCs are developed.
***************
*** 1131,1132 ****
! Complete requirements for the RowStatus and StorageType TCs are can
! be found in RFC 2579, in the DESCRIPTION clauses for those TCs.
--- 1131,1132 ----
! Complete requirements for the RowStatus and StorageType TCs can be
! found in RFC 2579, in the DESCRIPTION clauses for those TCs.
***************
*** 1323 ****
! statement contains the following contains the OBJECT clause (*)
--- 1323 ----
! statement contains the following OBJECT clause (*)
***************
*** 1389,1394 ****
! pool of OPS Area MIB reviewers is that they should be allowed with
! TCs. MIB module authors should be aware that some MIB compilers
! follow the strict reading of RFC 2578 and require that the TC be
! replaced by its base type (INTEGER or BITS) when enumerations are
! refined. That usage is legal, and it can be found in some older MIB
! modules such as the IF-MIB [RFC2863].
--- 1389,1394 ----
! pool of MIB reviewers is that they should be allowed with TCs. MIB
! module authors should be aware that some MIB compilers follow the
! strict reading of RFC 2578 and require that the TC be replaced by its
! base type (INTEGER or BITS) when enumerations are refined. That
! usage is legal, and it can be found in some older MIB modules such as
! the IF-MIB [RFC2863].
***************
*** 1410 ****
! - The MODULE-IDENTITY invocation must be updated to include
--- 1410 ----
! - The MODULE-IDENTITY invocation MUST be updated to include
***************
*** 1617,1619 ****
! 2434. Note that module itself must be in an appendix that will
! disappear after publication and that the IANA Considerations section
! that will appear in the RFC must contain a pointer to that module.
--- 1617,1619 ----
! 2434. Note that the IANA Considerations section that will appear in
! the RFC MUST contain a pointer to that module.
!
*** draft-ietf-ops-mib-review-guidelines-01.txt Mon Feb 24 09:27:55 2003
--- draft-ietf-ops-mib-review-guidelines-XX.txt Fri Jul 11 09:53:18 2003
***************
*** 173,185 ****
1. Introduction
! Some time ago the IESG instituted a policy of requiring OPS area
! review of IETF standards-track specifications containing MIB modules.
! These reviews were established to ensure that such specifications
! follow established IETF documentation practices and that the MIB
! modules they contain meet certain generally accepted standards of
! quality, including (but not limited to) compliance with all syntactic
! and semantic requirements of SMIv2 (STD 58) [RFC2578] [RFC2579]
! [RFC2580] that are applicable to "standard" MIB modules. The purpose
! of this memo is to document the guidelines that are followed in such
! reviews.
--- 173,184 ----
1. Introduction
! Some time ago the IESG instituted a policy of requiring expert review
! of IETF standards-track specifications containing MIB modules. These
! reviews were established to ensure that such specifications follow
! established IETF documentation practices and that the MIB modules
! they contain meet certain generally accepted standards of quality,
! including (but not limited to) compliance with all syntactic and
! semantic requirements of SMIv2 (STD 58) [RFC2578] [RFC2579] [RFC2580]
! that are applicable to "standard" MIB modules. The purpose of this
! memo is to document the guidelines that are followed in such reviews.
***************
*** 223 ****
--- 223 ----
+
***************
*** 285,295 ****
MUST be noted in the overview section, as MUST any special
interpretations of objects in other MIB modules. For instance, so-
called media-specific MIB modules are always implemented in
! conjunction with the IF-MIB [RFC2863] and are required to document
how certain objects in the IF-MIB are used. In addition, media-
specific MIB modules that rely on the ifStackTable [RFC2863] and the
ifInvStackTable [RFC2864] to maintain information regarding
! configuration and multiplexing of interface sublayers must contain a
description of the layering model.
3.3. Definitions Section
--- 285,295 ----
MUST be noted in the overview section, as MUST any special
interpretations of objects in other MIB modules. For instance, so-
called media-specific MIB modules are always implemented in
! conjunction with the IF-MIB [RFC2863] and are REQUIRED to document
how certain objects in the IF-MIB are used. In addition, media-
specific MIB modules that rely on the ifStackTable [RFC2863] and the
ifInvStackTable [RFC2864] to maintain information regarding
! configuration and multiplexing of interface sublayers MUST contain a
description of the layering model.
3.3. Definitions Section
***************
*** 424,438 ****
3.8. Copyright Notices
IETF MIB documents MUST contain the copyright notices specified in
Section 4.3 of RFC 2223bis [RFC2223bis] and Section 10.4 Bullet (C)
of RFC 2026 [RFC2026]. Authors and reviewers MUST check make sure
that the correct year is inserted into these notices. In addition,
the DESCRIPTION clause of the MODULE-IDENTITY invocation of each MIB
! module that will appear in the published RFC must contain a pointer
to the copyright notices in the RFC. A template suitable for
inclusion in an Internet Draft is as follows:
DESCRIPTION
" [ ... ]
Copyright (C) The Internet Society (date). This version
--- 424,438 ----
3.8. Copyright Notices
IETF MIB documents MUST contain the copyright notices specified in
Section 4.3 of RFC 2223bis [RFC2223bis] and Section 10.4 Bullet (C)
of RFC 2026 [RFC2026]. Authors and reviewers MUST check make sure
that the correct year is inserted into these notices. In addition,
the DESCRIPTION clause of the MODULE-IDENTITY invocation of each MIB
! module that will appear in the published RFC MUST contain a pointer
to the copyright notices in the RFC. A template suitable for
inclusion in an Internet Draft is as follows:
DESCRIPTION
" [ ... ]
Copyright (C) The Internet Society (date). This version
***************
*** 486,515 ****
4.2. Descriptors, TC Names, and Labels
RFC 2578 Sections 3.1, 7.1.1, and 7.1.4 and RFC 2579 Section 3
recommend that descriptors and names associated with macro
invocations and labels associated with enumerated INTEGER and BITS
values be no longer than 32 characters, but require that they be no
longer than 64 characters.
Restricting descriptors, TC names, and labels to 32 characters often
conflicts with the recommendation that they be mnemonic and (for
descriptors and TC names) with the requirement that they be unique
(see RFC 2578 Section 3.1 and RFC 2579 Section 3). The consensus of
! the current pool of OPS Area MIB reviewers is that the SMIv2
! recommendation to limit descriptors, TC names, and labels to 32
! characters SHOULD be set aside in favor of promoting clarity and
OPS Area Expires August 2003 [Page 9]
Internet Draft Guidelines for MIB Authors and Reviewers February 2003
! uniqueness and that automated tools such as MIB compilers SHOULD NOT
! by default generate warnings for violating that recommendation.
Note that violations of the 64 character limit MUST NOT be ignored;
they MUST be treated as errors.
See Appendix E for suggested descriptor and TC naming conventions.
--- 486,515 ----
4.2. Descriptors, TC Names, and Labels
RFC 2578 Sections 3.1, 7.1.1, and 7.1.4 and RFC 2579 Section 3
recommend that descriptors and names associated with macro
invocations and labels associated with enumerated INTEGER and BITS
values be no longer than 32 characters, but require that they be no
longer than 64 characters.
Restricting descriptors, TC names, and labels to 32 characters often
conflicts with the recommendation that they be mnemonic and (for
descriptors and TC names) with the requirement that they be unique
(see RFC 2578 Section 3.1 and RFC 2579 Section 3). The consensus of
! the current pool of MIB reviewers is that the SMIv2 recommendation to
! limit descriptors, TC names, and labels to 32 characters SHOULD be
! set aside in favor of promoting clarity and uniqueness and that
OPS Area Expires August 2003 [Page 9]
Internet Draft Guidelines for MIB Authors and Reviewers February 2003
! automated tools such as MIB compilers SHOULD NOT by default generate
! warnings for violating that recommendation.
Note that violations of the 64 character limit MUST NOT be ignored;
they MUST be treated as errors.
See Appendix E for suggested descriptor and TC naming conventions.
***************
*** 769,803 ****
- It is OK to use Counter32/64 for counters that may/will be reset
when the management subsystem is re-initialized or when other
unusual/irregular events occur (e.g., counters maintained on a line
card may be reset when the line card is reset). However, if it is
! possible for such other unusual/irregular events to occur, the the
DESCRIPTION clause MUST state that this is so and MUST describe
those other unusual/irregular events in sufficient detail that it
is possible for a management application to determine whether a
reset has occurred since the last time the counter was polled. The
RECOMMENDED way to do this is to provide a discontinuity indicator
as described in RFC 2578 Sections 7.1.6 and 7.1.10. For an example
! of such a discontinuity indicator see the ifCounterDisconuityTime
OPS Area Expires August 2003 [Page 14]
Internet Draft Guidelines for MIB Authors and Reviewers February 2003
! object in the IF-MIB [RFC2863].
- It is NOT OK to put in the DESCRIPTION clause of a Counter32/64
that there is a requirement that on a discontinuity the counter
MUST reset to zero or to any other specific value.
- It is NOT OK to put in the DESCRIPTION clause of a Counter32/64
that there is a requirement that it MUST reset at any specific
time/event (e.g., midnight).
- It is NOT OK for one manager to request the agent to reset the
value of counter(s) to zero, and Counter32/64 is the wrong syntax
for "counters" which regularly reset themselves to zero. For the
latter it is better to define or use textual conventions such as
those in RFC 2493 [RFC2493].
--- 769,803 ----
- It is OK to use Counter32/64 for counters that may/will be reset
when the management subsystem is re-initialized or when other
unusual/irregular events occur (e.g., counters maintained on a line
card may be reset when the line card is reset). However, if it is
! possible for such other unusual/irregular events to occur, the
DESCRIPTION clause MUST state that this is so and MUST describe
those other unusual/irregular events in sufficient detail that it
is possible for a management application to determine whether a
reset has occurred since the last time the counter was polled. The
RECOMMENDED way to do this is to provide a discontinuity indicator
as described in RFC 2578 Sections 7.1.6 and 7.1.10. For an example
! of such a discontinuity indicator see the
OPS Area Expires August 2003 [Page 14]
Internet Draft Guidelines for MIB Authors and Reviewers February 2003
! ifCounterDiscontinuityTime object in the IF-MIB [RFC2863].
- It is NOT OK to put in the DESCRIPTION clause of a Counter32/64
that there is a requirement that on a discontinuity the counter
MUST reset to zero or to any other specific value.
- It is NOT OK to put in the DESCRIPTION clause of a Counter32/64
that there is a requirement that it MUST reset at any specific
time/event (e.g., midnight).
- It is NOT OK for one manager to request the agent to reset the
value of counter(s) to zero, and Counter32/64 is the wrong syntax
for "counters" which regularly reset themselves to zero. For the
latter it is better to define or use textual conventions such as
those in RFC 2493 [RFC2493].
***************
*** 965,981 ****
4.6.1.10. Other Data Types
There exist a number of standard TCs that cater to some of the more
common requirements for specialized data types. Some have been
mentioned above, and Appendix D contains a partial list that includes
those plus some others that are a bit more specialized. Note that
there exist many standard TCs that are not mentioned there; that
! list can be expected to to grow as additional TCs are developed.
Whenever a standard TC already conveys the desired semantics, it
SHOULD be used in an object definition instead of the corresponding
base type or a locally-defined TC. This is especially true of the
TCs defined in SNMPv2-TC [RFC2579] and SNMP-FRAMEWORK-MIB [RFC3411]
because they are Internet Standards, and so modules that refer to
them will not suffer delay in advancement on the standards track on
account of such references.
--- 965,981 ----
4.6.1.10. Other Data Types
There exist a number of standard TCs that cater to some of the more
common requirements for specialized data types. Some have been
mentioned above, and Appendix D contains a partial list that includes
those plus some others that are a bit more specialized. Note that
there exist many standard TCs that are not mentioned there; that
! list can be expected to grow as additional TCs are developed.
Whenever a standard TC already conveys the desired semantics, it
SHOULD be used in an object definition instead of the corresponding
base type or a locally-defined TC. This is especially true of the
TCs defined in SNMPv2-TC [RFC2579] and SNMP-FRAMEWORK-MIB [RFC3411]
because they are Internet Standards, and so modules that refer to
them will not suffer delay in advancement on the standards track on
account of such references.
***************
*** 1130,1133 ****
! Complete requirements for the RowStatus and StorageType TCs are can
! be found in RFC 2579, in the DESCRIPTION clauses for those TCs.
--- 1130,1133 ----
! Complete requirements for the RowStatus and StorageType TCs can be
! found in RFC 2579, in the DESCRIPTION clauses for those TCs.
***************
*** 1314,1332 ****
Sometimes MIB module authors will want to specify that a compliant
implementation needs to support only a subset of the values allowed
by an object's SYNTAX clause. For accessible objects this may be
done either by specifying the required values in an object's
DESCRIPTION clause or by providing an OBJECT clause with a refined
SYNTAX in a compliance statement. The latter method is RECOMMENDED
for most cases, and is REQUIRED if there are multiple compliance
statements with different value subsets required. The DIFFSERV-MIB
[RFC3289] illustrates this point. The diffServMIBFullCompliance
! statement contains the following contains the OBJECT clause (*)
OBJECT diffServDataPathStatus
SYNTAX RowStatus { active(1) }
WRITE-SYNTAX RowStatus { createAndGo(4), destroy(6) }
DESCRIPTION
"Support for createAndWait and notInService is not required."
whereas the diffServMIBReadOnlyCompliance statement contains this:
--- 1314,1332 ----
Sometimes MIB module authors will want to specify that a compliant
implementation needs to support only a subset of the values allowed
by an object's SYNTAX clause. For accessible objects this may be
done either by specifying the required values in an object's
DESCRIPTION clause or by providing an OBJECT clause with a refined
SYNTAX in a compliance statement. The latter method is RECOMMENDED
for most cases, and is REQUIRED if there are multiple compliance
statements with different value subsets required. The DIFFSERV-MIB
[RFC3289] illustrates this point. The diffServMIBFullCompliance
! statement contains the following OBJECT clause (*)
OBJECT diffServDataPathStatus
SYNTAX RowStatus { active(1) }
WRITE-SYNTAX RowStatus { createAndGo(4), destroy(6) }
DESCRIPTION
"Support for createAndWait and notInService is not required."
whereas the diffServMIBReadOnlyCompliance statement contains this:
***************
*** 1383,1400 ****
_______________________________
(*) There has been some dispute as to whether syntax refinements that
restrict enumerations (RFC 2578, Section 9) are permitted with TCs,
as shown in these examples, or are allowed only with the base types
INTEGER and BITS, as suggested by a strict reading of RFC 2578. The
rough consensus of the editors of the SMIv2 documents and the current
! pool of OPS Area MIB reviewers is that they should be allowed with
! TCs. MIB module authors should be aware that some MIB compilers
! follow the strict reading of RFC 2578 and require that the TC be
! replaced by its base type (INTEGER or BITS) when enumerations are
! refined. That usage is legal, and it can be found in some older MIB
! modules such as the IF-MIB [RFC2863].
OPS Area Expires August 2003 [Page 25]
--- 1383,1400 ----
_______________________________
(*) There has been some dispute as to whether syntax refinements that
restrict enumerations (RFC 2578, Section 9) are permitted with TCs,
as shown in these examples, or are allowed only with the base types
INTEGER and BITS, as suggested by a strict reading of RFC 2578. The
rough consensus of the editors of the SMIv2 documents and the current
! pool of MIB reviewers is that they should be allowed with TCs. MIB
! module authors should be aware that some MIB compilers follow the
! strict reading of RFC 2578 and require that the TC be replaced by its
! base type (INTEGER or BITS) when enumerations are refined. That
! usage is legal, and it can be found in some older MIB modules such as
! the IF-MIB [RFC2863].
OPS Area Expires August 2003 [Page 25]
***************
*** 1405,1415 ****
4.9. Revisions to MIB Modules
RFC 2578 Section 10 specifies general rules that apply any time a MIB
module is revised. Specifically:
! - The MODULE-IDENTITY invocation must be updated to include
information about the revision. In particular, the LAST-UPDATED
clause value MUST be set to the revision time, a REVISION clause
with the same UTC time and an associated DESCRIPTION clause
describing the changes MUST be added, and any obsolete information
in the existing DESCRIPTION, ORGANIZATION, and CONTACT-INFO clauses
--- 1405,1415 ----
4.9. Revisions to MIB Modules
RFC 2578 Section 10 specifies general rules that apply any time a MIB
module is revised. Specifically:
! - The MODULE-IDENTITY invocation MUST be updated to include
information about the revision. In particular, the LAST-UPDATED
clause value MUST be set to the revision time, a REVISION clause
with the same UTC time and an associated DESCRIPTION clause
describing the changes MUST be added, and any obsolete information
in the existing DESCRIPTION, ORGANIZATION, and CONTACT-INFO clauses
***************
*** 1614,1622 ****
7.) IANA Considerations Section -- if the draft contains the initial
version of an IANA-maintained module, verify that the MODULE-IDENTITY
invocation contains maintenance instructions that comply with RFC
! 2434. Note that module itself must be in an appendix that will
! disappear after publication and that the IANA Considerations section
! that will appear in the RFC must contain a pointer to that module.
--- 1614,1622 ----
7.) IANA Considerations Section -- if the draft contains the initial
version of an IANA-maintained module, verify that the MODULE-IDENTITY
invocation contains maintenance instructions that comply with RFC
! 2434. Note that the IANA Considerations section that will appear in
! the RFC MUST contain a pointer to that module.
!