[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Proposed "Last Call" version of draft-ietf-ops-mib-review-guidelines



MIB Doctors,

Let me begin by wishing everyone a productive 2005.  In that spirit,
I have attached a proposed update for the MIB review guidelines
document for your review, along with a context diff showing the
proposed content changes.  If everyone here agrees, I think this
version would be suitable to go to IETF last call.

My main objective in producing this update was to resolve lingering
inconsistencies between draft-ietf-ops-mib-review-guidelines-03.txt
and the updated "Instructions to RFC Authors" draft and IPR
documents, available at ftp://ftp.rfc-editor.org/in-notes/authors/
as draft-rfc-editor-rfc2223bis-08.txt and rfc390[78].txt,
respectively.  This has resulted in a re-organization of Section 3
and the checklist and some relocation of other sections, but there
have been only minimal content changes as a result of this effort.
In order to make this clear, the the context diff that I've attached
omits all diffs that were just a result of the document
reorganization -- it only shows the actual changes to the content.

My second objective was to fix up inadequacies that have been
exposed as a result of actual experience in using the document. This
resulted in two changes:  I added some text stating that it's not
necessary to have paired 32 and 64 bit counter objects (although
that is still allowed), as requested by Joseph Dinakaran;  and I
removed the checklist item for the copyright notice on the front
page, as requested by Dave Thaler.

There were a couple of other things that people brought up that I
did NOT fix.  One was the following from request Dave Thaler:

> In section 4.6.1.7 (IpAddress), it would be good to provide more
> guidance on when it's acceptable to vary from the SHOULD.  
> (Same comment can be applied to 3291bis as well.)  Specifically
> one example is a MIB object which instruments an inherently
> IPv4-specific thing.

I did not make this change because it was not clear to me that there
is any situation where it would be acceptable to use IpAddress in a
new standards-track MIB module.  If a consensus exists that it is
acceptable to do so under certain circumstances, and if someone will
supply the text saying what those circumstances are, then I will be
happy to incorporate the change, but otherwise I'm going to leave
things as they are.

The other item was this:

> -----Original Message-----
> From: Michelle S. Cotton [mailto:cotton@icann.org]
> Sent: Thursday, December 02, 2004 07:27
> To: Bert Wijnen (Bert)
> Subject: FW: Fwd: RE: Evaluation: 
> draft-ietf-ipv6-rfc2013-update-04.txt
> to ProposedStandard
> 
> 
> Bert,
> 
> I think there is a follow-up question here with regards to the
> MIB review guidelines text.
> 
> Not sure what we need to do for the future.  I believe that 
> all is OK for the document to go forward.
> 
> Michelle
> 
> -----Original Message-----
> From: John Flick [mailto:john.flick@hp.com]
> Sent: Thursday, October 28, 2004 4:36 PM
> To: Bill Fenner
> Cc: margaret@thingmagic.com; narten@us.ibm.com; bwijnen@lucent.com;
> bob.hinden@nokia.com; brian@innovationslab.net; cotton@icann.org;
> iana@iana.org
> Subject: Re: Fwd: RE: Evaluation: 
> draft-ietf-ipv6-rfc2013-update-04.txt
> to ProposedStandard
> 
> 
> I agree with Bill.
> 
> Note to Bert: The IANA Considerations text that prompted this question
> from IANA was the verbatim text recommended in section 3.7.3 of the
> MIB review guidelines.  Do we need to consult with IANA to determine
> what this text should look like so that they don't need to come back
> and request clarification?  If so, we should update the MIB review
> guidelines to make sure that the IANA considerations lets IANA know
> what they need to do.
> 
> John
> 
> Bill Fenner wrote:
> >>Do we need to change the references for those mib-2 values
> >>or do they remain the same?
> > 
> > 
> > The references for {mib-2 7} and {mib-2 50} should be updated to
> > this spec, yup.  I don't think there are any other IANA actions.
> > 
> >   Bill

I wrote a follow-up note to Michelle Cotton asking if any changes
were necessary, but I didn't receive a reply, so I haven't made any
changes. Maybe we'll get some comments in last call about this;  if
we do I guess we can resolve them at that time.

I have a couple of questions regarding references.  The proposed
updates points to RFCs 3907 and 3908 even though they are still in
AUTH48.  I'm hoping that these will indeed be published by the time
it's time to post the draft.  Second, I still have two normative
references to documents whose publication status is uncertain -- I
refer here to rfc2223bis and rfc2737bis.  Bert, can you check on the
status of these things and do whatever nudging is appropriate to
move them along, particularly 3907 and 3908, which have been in
AUTH48 since early November?

Regards & thanks,

Mike
***************

*** 1,21 ****

  

  INTERNET-DRAFT                                       C. M. Heard, Editor

!                                                                June 2004

  

           Guidelines for Authors and Reviewers of MIB Documents

  

!              <draft-ietf-ops-mib-review-guidelines-03.txt>

  

  Status of this Memo

  

!    This document is an Internet-Draft and is subject to all provisions

!    of Section 3 of RFC 3667.

  

-    By submitting this Internet-Draft, I certify that any applicable

-    patent or other IPR claims of which I am aware have been disclosed,

-    and any of which I become aware will be disclosed, in accordance with

-    RFC 3668.

- 

     Internet-Drafts are draft documents valid for a maximum of six months

     and may be updated, replaced, or obsoleted by other documents at any

     time.  It is inappropriate to use Internet-Drafts as reference

--- 1,23 ----

  

  INTERNET-DRAFT                                       C. M. Heard, Editor

!                                                             January 2005

  

           Guidelines for Authors and Reviewers of MIB Documents

  

!              <draft-ietf-ops-mib-review-guidelines-04.txt>

  

  Status of this Memo

  

!    By submitting this Internet-Draft, each author represents that any

!    applicable patents or other IPR claims of which he or she is aware

!    have been or will be disclosed, and any of which he or she becomes

!    aware will be disclosed, in accordance with Section 6 of BCP 79.

! 

!    Internet-Drafts are working documents of the Internet Engineering

!    Task Force (IETF), its areas, and its working groups.  Note that

!    other groups may also distribute working documents as Internet-

!    Drafts.

  

     Internet-Drafts are draft documents valid for a maximum of six months

     and may be updated, replaced, or obsoleted by other documents at any

     time.  It is inappropriate to use Internet-Drafts as reference

***************

*** 34,40 ****

  

  Copyright Notice

  

!    Copyright (C) The Internet Society (2004).  All Rights Reserved.

  

  Abstract

  

--- 36,42 ----

  

  Copyright Notice

  

!    Copyright (C) The Internet Society (2005).  All Rights Reserved.

  

  Abstract

  

***************

*** 98,114 ****

  3.  General Documentation Guidelines

  

     In general, IETF standards-track specifications containing MIB

!    modules MUST conform to the requirements for IETF standards-track

!    RFCs documented in [RFC2223bis].  Because the version under review

!    will be an Internet-Draft, the notices on the front page will comply

!    with the requirements of http://www.ietf.org/ietf/1id-guidelines.txt

!    and not with those of [RFC2223bis].  The rest of the requirements in

!    [RFC2223bis], however, do apply (see http://www.ietf.org/ID-

!    Checklist.html for additional details).

  

     Section 4 of [RFC2223bis] lists the sections that may exist in an

!    RFC.  The "body of memo" part of an RFC in general contains multiple

!    sections, and in a MIB document MUST contain at least the following:

  

      o MIB boilerplate section

  

--- 100,119 ----

  3.  General Documentation Guidelines

  

     In general, IETF standards-track specifications containing MIB

!    modules are subject to the same requirements as IETF standards-track

!    RFCs (see [RFC2223bis]), although there are some differences.  In

!    particular, since the version under review will be an Internet-Draft,

!    the notices on the front page MUST comply with the requirements of

!    http://www.ietf.org/ietf/1id-guidelines.txt and not with those of

!    [RFC2223bis].  In addition, since the specification under review is

!    expected to be submitted to the IESG, it MUST comply with certain

!    requirements that do not necessarily apply to RFCs;  see

!    http://www.ietf.org/ID-Checklist.html for details.

  

     Section 4 of [RFC2223bis] lists the sections that may exist in an

!    RFC.  Sections from the abstract onward may also be present in an

!    Internet-Draft.  The "body of memo" is always required, and in a MIB

!    document MUST contain at least the following:

  

      o MIB boilerplate section

  

***************

*** 116,122 ****

  

      o Definitions section

  

!     o Intellectual Property section

  

     Section-by-section guidelines follow.

  

--- 121,131 ----

  

      o Definitions section

  

!     o Security Considerations section

! 

!     o IANA Considerations section

! 

!     o References section.

  

     Section-by-section guidelines follow.

  

***************

*** 333,339 ****

!  3.8.  Copyright Notices

  

     IETF MIB documents MUST contain the copyright notices and disclaimer

!    specified in Sections 5.4 and 5.5 of RFC 3667 [RFC3667].  Authors and

     reviewers MUST check to 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

--- 342,348 ----

! 3.7.  Copyright Notices

  

     IETF MIB documents MUST contain the copyright notices and disclaimer

!    specified in Sections 5.4 and 5.5 of RFC 3907 [RFC3907].  Authors and

     reviewers MUST check to 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

***************

*** 359,365 ****

              Copyright (C) The Internet Society (date).  The initial

              version of this MIB module was published in RFC yyyy;

              for full legal notices see the RFC itself.  Supplementary

!             information may be available on

              http://www.ietf.org/copyrights/ianamib.html.";

     -- RFC Ed.: replace yyyy with actual RFC number & remove this note

  

--- 368,374 ----

              Copyright (C) The Internet Society (date).  The initial

              version of this MIB module was published in RFC yyyy;

              for full legal notices see the RFC itself.  Supplementary

!             information may be available at:

              http://www.ietf.org/copyrights/ianamib.html.";

     -- RFC Ed.: replace yyyy with actual RFC number & remove this note

  

***************

*** 368,377 ****

  

! 3.4.  Intellectual Property Section

  

!    Section 5 of RFC 3668 [RFC3668] contains a notice regarding

     intellectual property rights or other rights that must appear in all

!    IETF RFCs.  A verbatim copy of that notice MUST appear in every IETF

!    MIB document.

  

  4.  SMIv2 Usage Guidelines

  

--- 377,386 ----

  

! 3.8.  Intellectual Property Section

  

!    Section 5 of RFC 3908 [RFC3908] contains a notice regarding

     intellectual property rights or other rights that must appear in all

!    IETF RFCs.  A verbatim copy of that notice SHOULD appear in every

!    IETF MIB document.

  

  4.  SMIv2 Usage Guidelines

  

***************

*** 693,699 ****

     this restriction.  Henceforth "standard" MIB modules MAY use the

     Counter64 type when it makes sense to do so, and MUST use Counter64

     if the information being modelled would wrap in less than one hour if

!    the Counter32 type was used instead.

  

     There also exist closely-related textual conventions

     ZeroBasedCounter32 and ZeroBasedCounter64 defined in RMON2-MIB

--- 702,710 ----

     this restriction.  Henceforth "standard" MIB modules MAY use the

     Counter64 type when it makes sense to do so, and MUST use Counter64

     if the information being modelled would wrap in less than one hour if

!    the Counter32 type was used instead.  Note also that there is no

!    longer a requirement to define Counter32 counterparts for each

!    Counter64 object, although one is still allowed to do so.

  

     There also exist closely-related textual conventions

     ZeroBasedCounter32 and ZeroBasedCounter64 defined in RMON2-MIB

***************

*** 701,707 ****

  

     The only difference between ZeroBasedCounter32/64 TCs and

     Counter32/64 is their starting value;  at time=X, where X is their

!    minimum-wrap-time after they were created, the behaviour of

     ZeroBasedCounter32/64 becomes exactly the same as Counter32/64.

     Thus, the preceding paragraphs/rules apply not only to Counter32/64,

     but also to ZeroBasedCounter32/64 TCs.

--- 712,718 ----

  

     The only difference between ZeroBasedCounter32/64 TCs and

     Counter32/64 is their starting value;  at time=X, where X is their

!    minimum-wrap-time after they were created, the behavior of

     ZeroBasedCounter32/64 becomes exactly the same as Counter32/64.

     Thus, the preceding paragraphs/rules apply not only to Counter32/64,

     but also to ZeroBasedCounter32/64 TCs.

***************

*** 1360,1366 ****

     the differences between two revisions of a MIB module.  Please see

     http://www.ops.ietf.org/mib-review-tools.html for more information.

  

! Acknowledgments

  

     Most of the material on usage of data types was based on input

     provided by Bert Wijnen with assistance from Keith McCloghrie, David

--- 1371,1377 ----

     the differences between two revisions of a MIB module.  Please see

     http://www.ops.ietf.org/mib-review-tools.html for more information.

  

! 5.  Acknowledgments

  

     Most of the material on usage of data types was based on input

     provided by Bert Wijnen with assistance from Keith McCloghrie, David

***************

*** 1373,1384 ****

     and to the contributors who supplied the material for that list.

     Finally, thanks are due to the following individuals whose comments

     on earlier versions of this memo contained many valuable suggestions

!    for additions, clarifications, and corrections:  Andy Bierman, David

!    Harrington, Harrie Hazewinkel, Michael Kirkham, Keith McCloghrie,

!    David T. Perkins, Randy Presuhn, Dan Romascanu, Juergen

!    Schoenwaelder, Frank Strauss, Dave Thaler, and Bert Wijnen.

  

! Security Considerations

  

     Implementation and deployment of a MIB module in a system may result

     in security risks that would not otherwise exist.  It is important

--- 1384,1396 ----

     and to the contributors who supplied the material for that list.

     Finally, thanks are due to the following individuals whose comments

     on earlier versions of this memo contained many valuable suggestions

!    for additions, clarifications, and corrections:  Andy Bierman, Bob

!    Braden, Michelle Cotton, Joseph Dinakaran, David Harrington, Harrie

!    Hazewinkel, Michael Kirkham, Keith McCloghrie, David T. Perkins,

!    Randy Presuhn, Dan Romascanu, Juergen Schoenwaelder, Frank Strauss,

!    Dave Thaler, and Bert Wijnen.

  

! 6.  Security Considerations

  

     Implementation and deployment of a MIB module in a system may result

     in security risks that would not otherwise exist.  It is important

***************

*** 1387,1402 ****

     http://www.ops.ietf.org/mib-security.html so that all such risks are

     adequately disclosed.

  

! IANA Considerations

! 

!    NOTE TO RFC Editor:  this section is to be removed prior to

!    publication as an RFC.

! 

!    The IANA is requested to review the portions of this memo dealing

!    IANA Considerations sections in MIB documents to make sure that the

!    proposed guidelines are acceptable.

  

!    This document does not require that the IANA update any existing

     registry or create any new registry.

  

  Appendix A:  MIB Review Checklist

--- 1399,1409 ----

     http://www.ops.ietf.org/mib-security.html so that all such risks are

     adequately disclosed.

  

! 7.  IANA Considerations

  

!    This document affects the IANA to the extent that it describes what

!    is required to be present in the IANA Considerations Section of a MIB

!    document, but it does not require that the IANA update any existing

     registry or create any new registry.

  

  Appendix A:  MIB Review Checklist

***************

*** 1420,1449 ****

     approved SNMP Network Management Framework boilerplate from the OPS

     area web site (http://www.ops.ietf.org/mib-boilerplate.html).

  

!    4.) IPR Notice -- verify that the draft contains a verbatim copy of

!    the IPR notice specified in Section 5 of RFC 3668.

! 

!    5.) References -- verify that the references are properly divided

!    between normative and informative references, that RFC 2119 is

!    included as a normative reference if the terminology defined therein

!    is used in the document, that all references required by the

!    boilerplate are present, that all MIB modules containing imported

!    items are cited as normative references, and that all citations point

!    to the most current RFCs unless there is a valid reason to do

!    otherwise (for example, it is OK to include an informative reference

!    to a previous version of a specification to help explain a feature

!    included for backward compatibility).

! 

!    6.) Security Considerations Section -- verify that the draft uses the

     latest approved template from the OPS area web site

     (http://www.ops.ietf.org/mib-security.html) and that the guidelines

     therein have been followed.

  

!    7.) IANA Considerations Section -- this section must always be

     present.  If the draft requires no action from the IANA, ensure that

     this is explicitly noted.  If the draft requires OID values to be

     assigned, ensure that the IANA Considerations section contains the

!    information specified in Section 3.7 of these guidelines.  If the

     draft contains the initial version of an IANA-maintained module,

     verify that the MODULE-IDENTITY invocation contains maintenance

     instructions that comply with the requirements in RFC 2434.  In the

--- 1427,1442 ----

     approved SNMP Network Management Framework boilerplate from the OPS

     area web site (http://www.ops.ietf.org/mib-boilerplate.html).

  

!    4.) Security Considerations Section -- verify that the draft uses the

     latest approved template from the OPS area web site

     (http://www.ops.ietf.org/mib-security.html) and that the guidelines

     therein have been followed.

  

!    5.) IANA Considerations Section -- this section must always be

     present.  If the draft requires no action from the IANA, ensure that

     this is explicitly noted.  If the draft requires OID values to be

     assigned, ensure that the IANA Considerations section contains the

!    information specified in Section 3.5 of these guidelines.  If the

     draft contains the initial version of an IANA-maintained module,

     verify that the MODULE-IDENTITY invocation contains maintenance

     instructions that comply with the requirements in RFC 2434.  In the

***************

*** 1450,1464 ****

     latter case the IANA Considerations section that will appear in the

     RFC MUST contain a pointer to the actual IANA-maintained module.

  

!    8.) Copyrights -- verify that the draft contains a copyright notice

!    on the front page and in the DESCRIPTION clause of the MODULE-

!    IDENTITY invocation and there is a full copyright notice section with

!    text matching that in recently published RFCs.  Make sure that the

!    year is up-to-date in all three places.

  

     9.) Other issues -- check for any issues mentioned in

!    http://www.ietf.org/ID-Checklist.html (other than MIB compilation)

!    that are not covered above.

  

     10.) Technical content -- review the actual technical content for

     compliance with the guidelines in this document.  The use of a MIB

--- 1443,1472 ----

     latter case the IANA Considerations section that will appear in the

     RFC MUST contain a pointer to the actual IANA-maintained module.

  

!    6.) References -- verify that the references are properly divided

!    between normative and informative references, that RFC 2119 is

!    included as a normative reference if the terminology defined therein

!    is used in the document, that all references required by the

!    boilerplate are present, that all MIB modules containing imported

!    items are cited as normative references, and that all citations point

!    to the most current RFCs unless there is a valid reason to do

!    otherwise (for example, it is OK to include an informative reference

!    to a previous version of a specification to help explain a feature

!    included for backward compatibility).

! 

!    7.) Copyright Notices -- verify that the draft contains an

!    abbreviated copyright notice in the DESCRIPTION clause of each

!    MODULE-IDENTITY invocation and that it contains the full copyright

!    notice and disclaimer specified in Sections 5.4 and 5.5 of RFC 3907

!    at the end of the document.  Make sure that the correct year is used

!    in all copyright dates.

! 

!    8.) IPR Notice -- if the draft does not contains a verbatim copy of

!    the IPR notice specified in Section 5 of RFC 3908, recommend that the

!    IPR notice be included.

  

     9.) Other issues -- check for any issues mentioned in

!    http://www.ietf.org/ID-Checklist.html that are not covered elsewhere.

  

     10.) Technical content -- review the actual technical content for

     compliance with the guidelines in this document.  The use of a MIB

***************

*** 1512,1518 ****

  

     InetAddressType             enumerated INTEGER

     InetAddress                 OCTET STRING (SIZE (0..255))

!    InetAddressPrefixLength     Unsigned32

     InetPortNumber              Unsigned32 (0..65535))

     InetAutonomousSystemNumber  Unsigned32

     InetScopeType               enumerated INTEGER

--- 1520,1526 ----

  

     InetAddressType             enumerated INTEGER

     InetAddress                 OCTET STRING (SIZE (0..255))

!    InetAddressPrefixLength     Unsigned32 (0..2040)

     InetPortNumber              Unsigned32 (0..65535))

     InetAutonomousSystemNumber  Unsigned32

     InetScopeType               enumerated INTEGER

***************

*** 1666,1672 ****

  [RFC2223bis]

              Reynolds, J., and R. Braden, "Instructions to Request for

              Comments (RFC) Authors", work in progress (currently <draft-

!             rfc-editor-rfc2223bis-07.txt>).

  

  [RFC2277]   Alvestrand, H., "IETF Policy on Character Sets and

              Languages", BCP 18, RFC 2277, January 1998.

--- 1674,1680 ----

  [RFC2223bis]

              Reynolds, J., and R. Braden, "Instructions to Request for

              Comments (RFC) Authors", work in progress (currently <draft-

!             rfc-editor-rfc2223bis-08.txt>).

  

  [RFC2277]   Alvestrand, H., "IETF Policy on Character Sets and

              Languages", BCP 18, RFC 2277, January 1998.

***************

*** 1681,1691 ****

  [RFC2864]   McCloghrie, K. and G. Hanson, "The Inverted Stack Table

              Extension to the Interfaces Group MIB", RFC 2864, June 2000.

  

! [RFC3667]   Bradner, S., "IETF Rights in Contributions", BCP 78, RFC

!             3667 February 2004.

  

! [RFC3668]   Bradner, S., "Intellectual Property Rights in IETF

!             Technology", BCP 79, RFC 3668, February 2004.

  

  [RFC3593]   Tesink, K., "Textual Conventions for MIB Modules Using

              Performance History Based on 15 Minute Intervals", RFC 3593,

--- 1689,1699 ----

  [RFC2864]   McCloghrie, K. and G. Hanson, "The Inverted Stack Table

              Extension to the Interfaces Group MIB", RFC 2864, June 2000.

  

! [RFC3907]   Bradner, S., "IETF Rights in Contributions", BCP 78, RFC

!             3907, January 2005.

  

! [RFC3908]   Bradner, S., "Intellectual Property Rights in IETF

!             Technology", BCP 79, RFC 3908, January 2005.

  

  [RFC3593]   Tesink, K., "Textual Conventions for MIB Modules Using

              Performance History Based on 15 Minute Intervals", RFC 3593,

***************

*** 1707,1713 ****

              Daniele, M., Haberman, B., Routhier, S. and J.

              Schoenwaelder, "Textual Conventions for Internet Network

              Addresses", work in progress (currently draft-ietf-ops-

!             rfc3291bis-05.txt).

  

  [RFC2287]   Krupczak, C. and J. Saperia, "Definitions of System-Level

              Managed Objects for Applications", RFC 2287, February 1998.

--- 1715,1721 ----

              Daniele, M., Haberman, B., Routhier, S. and J.

              Schoenwaelder, "Textual Conventions for Internet Network

              Addresses", work in progress (currently draft-ietf-ops-

!             rfc3291bis-06.txt).

  

  [RFC2287]   Krupczak, C. and J. Saperia, "Definitions of System-Level

              Managed Objects for Applications", RFC 2287, February 1998.

***************

*** 1731,1737 ****

  

  [RFC2737bis]

              McCloghrie, K. and A. Bierman, "Entity MIB (Version 3)",

!             work in progress (currently draft-ietf-entmib-v3-04.txt).

  

  Informative References

  

--- 1739,1745 ----

  

  [RFC2737bis]

              McCloghrie, K. and A. Bierman, "Entity MIB (Version 3)",

!             work in progress (currently draft-ietf-entmib-v3-05.txt).

  

  Informative References

  

***************

*** 1797,1806 ****

  

  Full Copyright Statement

  

!    Copyright (C) The Internet Society (2004).  This document is subject

!    to the rights, licenses and restrictions contained in BCP 78, and

!    except as set forth therein, the authors retain all their rights.

  

     This document and the information contained herein are provided on an

     "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS

     OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, AND THE INTERNET

--- 1805,1816 ----

  

  Full Copyright Statement

  

!    Copyright (C) The Internet Society (2005).

  

+    This document is subject to the rights, licenses and restrictions

+    contained in BCP 78, and except as set forth therein, the authors

+    retain all their rights.

+ 

     This document and the information contained herein are provided on an

     "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS

     OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, AND THE INTERNET

***************

*** 2123,2129 ****

        from the modules defined in the SMIv2 documents.

  

        6.)  The instructions for IPR notices in Section 3.4 (and also

!       those in Appendix A) to refer to RFC 3668 instead of RFC 2026.

  

        7.)  In Section 3.5 the [RFC2223bis] section number reference was

        updated to match <draft-rfc-editor-rfc2223bis-07.txt>, and text

--- 2133,2139 ----

        from the modules defined in the SMIv2 documents.

  

        6.)  The instructions for IPR notices in Section 3.4 (and also

!       those in Appendix A) now refer to RFC 3668 instead of RFC 2026.

  

        7.)  In Section 3.5 the [RFC2223bis] section number reference was

        updated to match <draft-rfc-editor-rfc2223bis-07.txt>, and text

***************

*** 2169,2175 ****

        3667 and 3668, all references to I-Ds that have since been

        published have been changed to point to the RFCs, and the

        references to RFC 2737 and RFC 3291 were replaced by references to

!       the I-Ds that update those documents.  Note that RFC2373bis and

        RFC3291bis are both normative references since Appendix B lists

        some TCs from those drafts that are available nowhere else.

  

--- 2179,2185 ----

        3667 and 3668, all references to I-Ds that have since been

        published have been changed to point to the RFCs, and the

        references to RFC 2737 and RFC 3291 were replaced by references to

!       the I-Ds that update those documents.  Note that RFC2737bis and

        RFC3291bis are both normative references since Appendix B lists

        some TCs from those drafts that are available nowhere else.

  

***************

*** 2176,2181 ****

--- 2186,2258 ----

        17.) An IANA Considerations section (to be removed upon

        publication) was added, and the Open Issues section was removed.

  

+    The following changes were made to <draft-ietf-ops-mib-review-

+    guidelines-03.txt> to produce <draft-ietf-ops-mib-review-

+    guidelines-04.txt>:

+ 

+       1.)  The I-D boilerplate on the front page was updated to comply

+       with http://www.ietf.org/ietf/1id-guidelines.txt.

+ 

+       2.)  The introductory part of Section 3 has been wordsmithed to

+       align it with http://www.ietf.org/ietf/1id-guidelines.txt,

+       http://www.ietf.org/ID-Checklist.html, and RFC2223bis, and the

+       sub-sections have been re-ordered to match the order recommended

+       by RFC 2223bis for sections in an RFC.  As a result, the following

+       section numbers have changed:

+ 

+       -03 Section Number      -04 Section Number

+               3.4                     3.8

+               3.5                     3.6

+               3.6                     3.4

+               3.7                     3.5

+               3.8                     3.7

+ 

+       3.)  The instructions for copyright notices in Section 3.7 (and

+       also those in Appendix A) refer to RFC 3907 instead of RFC 3667,

+       and the wording for the abbreviated notice used in IANA-maintained

+       was changed so that it agrees with RFC  3907.  In addition, the

+       requirement to check for the presence of a copyright notice on the

+       front page of a document has been deleted from Appendix A, since

+       Internet-Drafts no longer require such a notice.

+ 

+       4.)  The instructions for IPR notices in Section 3.8 (and also

+       those in Appendix A) now refer to RFC 3908 instead of RFC 3668.

+       In addition, these sections treat the notice as a SHOULD, since

+       the IPR notice is no longer required in Internet-Drafts (although

+       it is recommended)

+ 

+       5.)  Text has been added to Section 4.6.1.2 to clarify that there

+       is no longer a requirement to define a Counter32 counterpart for

+       each Counter64 object.

+ 

+       6.)  The Acknowledgments, Security Considerations, and IANA

+       Considerations sections have been relocated before the appendices,

+       as recommended by RFC 2223bis, and the Intellectual Property

+       Section has been relocated to the end of the document, as required

+       by RFC 2223bis (and in accordance with the practice in recent

+       RFCs).

+ 

+       7.)  Several previously unacknowledged individuals who have

+       provided helpful comments have been named in the Acknowledgments

+       section.

+ 

+       8.)  The IANA Considerations section is now non-null, and the

+       editor's note requesting that it be removed prior to publication

+       has been deleted.

+ 

+       9.)  The checklist items in Appendix A have been re-ordered to

+       match the order of presentation in Section 3.

+ 

+       10.) Appendix B now correctly lists the SYNTAX of

+       InetAddressPrefixLength as Unsigned32 (0..2040).

+ 

+       11.) The references to RFCs 3667 and 3668 were replaced by

+       references to RFCs 3907 and 3908, and the references to RFC

+       2223bis, RFC 2737bis and RFC 3291bis were updated to point to the

+       most current drafts.

+ 

+       12.) Several typos and spelling errors were corrected.

+ 

        ************************************************************

        * NOTES TO RFC Editor (to be removed prior to publication) *

        *                                                          *

***************

*** 2199,2204 ****

        * occurrences of "2737bis" with the number of that RFC.    *

        *                                                          *

        * 4.) The "Editor's Notes" and "Notes to RFC Editor" in    *

!       * Sections 3.7, 3.8, and 4.5 are examples to authors and   *

        * are intended to appear in the final text.                *

        ************************************************************

--- 2276,2281 ----

        * occurrences of "2737bis" with the number of that RFC.    *

        *                                                          *

        * 4.) The "Editor's Notes" and "Notes to RFC Editor" in    *

!       * Sections 3.5, 3.7, and 4.5 are examples to authors and   *

        * are intended to appear in the final text.                *

        ************************************************************








INTERNET-DRAFT                                       C. M. Heard, Editor

                                                            January 2005





         Guidelines for Authors and Reviewers of MIB Documents



             <draft-ietf-ops-mib-review-guidelines-04Pre1.txt>





Status of this Memo



   By submitting this Internet-Draft, each author represents that any

   applicable patents or other IPR claims of which he or she is aware

   have been or will be disclosed, and any of which he or she becomes

   aware will be disclosed, in accordance with Section 6 of BCP 79.



   Internet-Drafts are working documents of the Internet Engineering

   Task Force (IETF), its areas, and its working groups.  Note that

   other groups may also distribute working documents as Internet-

   Drafts.



   Internet-Drafts are draft documents valid for a maximum of six months

   and may be updated, replaced, or obsoleted by other documents at any

   time.  It is inappropriate to use Internet-Drafts as reference

   material or to cite them other than as "work in progress."



   The list of current Internet-Drafts can be accessed at

   http://www.ietf.org/ietf/1id-abstracts.txt



   The list of Internet-Draft Shadow Directories can be accessed at

   http://www.ietf.org/shadow.html



   Comments on this memo should be submitted to the

   <ietfmibs@ops.ietf.org> mailing list.  To subscribe to this mailing

   list send an e-mail message to <ietfmibs-request@ops.ietf.org> with

   the word "subscribe" in the message body.



Copyright Notice



   Copyright (C) The Internet Society (2005).  All Rights Reserved.



Abstract



   This memo provides guidelines for authors and reviewers of IETF

   standards-track specifications containing MIB modules.  Applicable

   portions may used as a basis for reviews of other MIB documents.











OPS Area                    Expires June 2005                   [Page 1]



Internet-Draft        Guidelines for MIB Documents          January 2005





Table of Contents



      1 Introduction ..............................................    4

      2 Terminology ...............................................    4

      3 General Documentation Guidelines ..........................    5

      3.1 MIB Boilerplate Section .................................    5

      3.2 Narrative Sections ......................................    5

      3.3 Definitions Section .....................................    6

      3.4 Security Considerations Section .........................    6

      3.5 IANA Considerations Section .............................    7

      3.5.1 Documents that Create a New Name Space ................    7

      3.5.2  Documents  that  Require  Assignments  in  Existing

           Namespace(s) ...........................................    8

      3.5.3 Documents with no IANA Requests .......................    9

      3.6 References Sections .....................................    9

      3.7 Copyright Notices .......................................   10

      3.8 Intellectual Property Section ...........................   10

      4 SMIv2 Usage Guidelines ....................................   11

      4.1 Module Names ............................................   11

      4.2 Descriptors, TC Names, and Labels .......................   11

      4.3 Naming Hierarchy ........................................   12

      4.4 IMPORTS Statement .......................................   12

      4.5 MODULE-IDENTITY Invocation ..............................   13

      4.6 Textual Conventions and Object Definitions ..............   14

      4.6.1 Usage of Data Types ...................................   14

      4.6.1.1 INTEGER, Integer32, Gauge32, and Unsigned32 .........   15

      4.6.1.2 Counter32 and Counter64 .............................   16

      4.6.1.3 CounterBasedGauge64 .................................   18

      4.6.1.4 OCTET STRING ........................................   18

      4.6.1.5 OBJECT IDENTIFIER ...................................   19

      4.6.1.6 The BITS Construct ..................................   19

      4.6.1.7 IpAddress ...........................................   19

      4.6.1.8 TimeTicks ...........................................   20

      4.6.1.9 TruthValue ..........................................   20

      4.6.1.10 Other Data Types ...................................   20

      4.6.2 DESCRIPTION and REFERENCE Clauses .....................   21

      4.6.3 DISPLAY-HINT Clause ...................................   21

      4.6.4 Conceptual Table Definitions ..........................   21

      4.6.5 OID Values Assigned to Objects ........................   23

      4.6.6 OID Length Limitations and Table Indexing .............   24

      4.7 Notification Definitions ................................   25

      4.8 Compliance Statements ...................................   26

      4.9 Revisions to MIB Modules ................................   28

      5 Acknowledgments ...........................................   31

      6 Security Considerations ...................................   32

      7 IANA Considerations .......................................   32

       Appendix A:  MIB Review Checklist ..........................   32

       Appendix B:  Commonly Used Textual Conventions .............   34







OPS Area                    Expires June 2005                   [Page 2]



Internet-Draft        Guidelines for MIB Documents          January 2005





       Appendix C:  Suggested Naming Conventions ..................   36

       Appendix D:  Suggested OID Layout ..........................   37

       Normative References .......................................   38

       Informative References .....................................   40

       Editor's Address ...........................................   41

       Full Copyright Statement ...................................   41

       Intellectual Property ......................................   41

























































































OPS Area                    Expires June 2005                   [Page 3]



Internet-Draft        Guidelines for MIB Documents          January 2005





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.



   Please note that the guidelines in this memo are not intended to

   alter requirements or prohibitions (in the sense of "MUST", "MUST

   NOT", "SHALL", or "SHALL NOT" as defined in RFC 2119 [RFC2119]) of

   existing BCPs or Internet Standards except where those requirements

   or prohibitions are ambiguous or contradictory.  In the exceptional

   cases where ambiguities or contradictions exist this memo documents

   the current generally accepted interpretation.  In certain instances

   the guidelines in this memo do alter recommendations (in the sense of

   "SHOULD", "SHOULD NOT", "RECOMMENDED", or "NOT RECOMMENDED" as

   defined in RFC 2119) of existing BCPs or Internet Standards.  This

   has been done where practical experience has shown that the published

   recommendations are suboptimal.  In addition, this memo provides

   guidelines for the selection of certain SMIv2 options (in the sense

   of "MAY" or "OPTIONAL" as defined in RFC 2119) in cases where there

   is a consensus on a preferred approach.



   Although some of the guidelines in this memo are not applicable to

   non-standards track or non-IETF MIB documents, authors and reviewers

   of those documents should consider using the ones that do apply.



   Reviewers and authors need to be aware that some of the guidelines in

   in this memo do not apply to MIB modules that have been translated to

   SMIv2 from SMIv1 (STD 16) [RFC1155] [RFC1212] [RFC1215].



2.  Terminology



   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",

   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and

   "OPTIONAL", when used in the guidelines in this memo, are to be

   interpreted as described in RFC 2119 [RFC2119].



   The terms "MIB module" and "information module" are used

   interchangeably in this memo.  As used here, both terms refer to any

   of the three types of information modules defined in Section 3 of RFC

   2578 [RFC2578].









OPS Area                    Expires June 2005                   [Page 4]



Internet-Draft        Guidelines for MIB Documents          January 2005





   The term "standard", when it appears in quotes, is used in the same

   sense as in the SMIv2 documents [RFC2578] [RFC2579] [RFC2580].  In

   particular, it is used to refer to the requirements that those

   documents levy on "standard" modules or "standard" objects.



3.  General Documentation Guidelines



   In general, IETF standards-track specifications containing MIB

   modules are subject to the same requirements as IETF standards-track

   RFCs (see [RFC2223bis]), although there are some differences.  In

   particular, since the version under review will be an Internet-Draft,

   the notices on the front page MUST comply with the requirements of

   http://www.ietf.org/ietf/1id-guidelines.txt and not with those of

   [RFC2223bis].  In addition, since the specification under review is

   expected to be submitted to the IESG, it MUST comply with certain

   requirements that do not necessarily apply to RFCs;  see

   http://www.ietf.org/ID-Checklist.html for details.



   Section 4 of [RFC2223bis] lists the sections that may exist in an

   RFC.  Sections from the abstract onward may also be present in an

   Internet-Draft.  The "body of memo" is always required, and in a MIB

   document MUST contain at least the following:



    o MIB boilerplate section



    o Narrative sections



    o Definitions section



    o Security Considerations section



    o IANA Considerations section



    o References section.



   Section-by-section guidelines follow.



3.1.  MIB Boilerplate Section



   This section MUST contain a verbatim copy of the latest approved

   Internet-Standard Management Framework boilerplate, which is

   available on-line at http://www.ops.ietf.org/mib-boilerplate.html.



3.2.  Narrative Sections



   The narrative part MUST include an overview section that describes

   the scope and field of application of the MIB modules defined by the

   specification and that specifies the relationship (if any) of these







OPS Area                    Expires June 2005                   [Page 5]



Internet-Draft        Guidelines for MIB Documents          January 2005





   MIB modules to other standards, particularly to standards containing

   other MIB modules.  The narrative part SHOULD include one or more

   sections to briefly describe the structure of the MIB modules defined

   in the specification.



   If the MIB modules defined by the specification import definitions

   from other MIB modules (except for those defined in the SMIv2

   documents [RFC2578] [RFC2579] [RFC2580]) or are always implemented in

   conjunction with other MIB modules, then those facts 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



   This section contains the MIB module(s) defined by the specification.

   These MIB modules MUST be written in SMIv2 [RFC2578] [RFC2579]

   [RFC2580];  SMIv1 [RFC1155] [RFC1212] [RFC1215] has "Not Recommended"

   status [RFC3410] and is no longer acceptable in IETF MIB modules.



   See Section 4 for guidelines on SMIv2 usage.



3.4.  Security Considerations Section



   Each specification that defines one or more MIB modules MUST contain

   a section that discusses security considerations relevant to those

   modules.  This section MUST be patterned after the latest approved

   template (available at http://www.ops.ietf.org/mib-security.html).

   In particular, writeable MIB objects that could be especially

   disruptive if abused MUST be explicitly listed by name and the

   associated security risks MUST be spelled out;  similarly, readable

   MIB objects that contain especially sensitive information or that

   raise significant privacy concerns MUST be explicitly listed by name

   and the reasons for the sensitivity/privacy concerns MUST be

   explained.  If there are no risks/vulnerabilities for a specific

   category of MIB objects, then that fact MUST be explicitly stated.

   Failure to mention a particular category of MIB objects will not be

   equated to a claim of no risks/vulnerabilities in that category;

   rather, it will be treated as an act of omission and will result in

   the document being returned to the author for correction.  Remember

   that the objective is not to blindly copy text from the template, but

   rather to think and evaluate the risks/vulnerabilities and then

   state/document the result of this evaluation.







OPS Area                    Expires June 2005                   [Page 6]



Internet-Draft        Guidelines for MIB Documents          January 2005





3.5.  IANA Considerations Section



   In order to comply with IESG policy as set forth in

   http://www.ietf.org/ID-Checklist.html, every Internet-Draft that is

   submitted to the IESG for publication MUST contain an IANA

   Considerations section.  The requirements for this section vary

   depending what actions are required of the IANA.



3.5.1.  Documents that Create a New Name Space



   If an Internet-Draft defines a new name space that is to be

   administered by the IANA, then the document MUST include an IANA

   Considerations section conforming to the guidelines set forth in RFC

   2434 [RFC2434] that specifies how the name space is to be

   administered.



   Name spaces defined by MIB documents generally consist of the range

   of values for some type (usually an enumerated INTEGER) defined by a

   TEXTUAL-CONVENTION (TC) or of a set of administratively-defined

   OBJECT IDENTIFIER (OID) values.  In each case the definitions are

   housed in stand-alone MIB modules that are maintained by the IANA.

   These IANA-maintained MIB modules are separate from the MIB modules

   defined in standards-track specifications so that new assignments can

   be made without having to republish a standards-track RFC.  Examples

   of IANA-maintained MIB modules include the IANAifType-MIB

   (http://www.iana.org/assignments/ianaiftype-mib), which defines a

   name space used by the IF-MIB [RFC2863], and the IANA-RTPROTO-MIB

   (http://www.iana.org/assignments/ianaiprouteprotocol-mib), which

   defines a name space used by the IPMROUTE-STD-MIB [RFC2932].



   The current practice for such cases is to include a detailed IANA

   Considerations section complying with RFC 2434 in the DESCRIPTION

   clause of the MODULE-IDENTITY invocation in each IANA-maintained MIB

   module and for the IANA Considerations section of the MIB document

   that defines the name spaces to refer to the URLs for the relevant

   modules.  See RFC 2932 [RFC2932] for an example.  This creates a

   chicken-and-egg problem for MIB documents that have not yet been

   published as RFCs because the relevant IANA-maintained MIB modules

   will not yet exist.  The accepted way out of this dilemma is to

   include the initial content of each IANA-maintained MIB module in a

   non-normative section of the initial issue of the document that

   defines the name space;  for an example see [RFC1573], which

   documents the initial version of the IANAifType-MIB.  That material

   is usually omitted from subsequent updates to the document since the

   IANA-maintained modules are then available on-line (cf. [RFC2863]).



   Reviewers of draft MIB documents to which these considerations apply

   MUST check that the IANA Considerations section proposed for







OPS Area                    Expires June 2005                   [Page 7]



Internet-Draft        Guidelines for MIB Documents          January 2005





   publication in the RFC is present and contains pointers to the

   appropriate IANA-maintained MIB modules.  Reviewers of Internet

   Drafts that contain the proposed initial content of IANA-maintained

   MIB modules MUST also verify that the DESCRIPTION clauses of the

   MODULE-IDENTITY invocations contain an IANA Considerations section

   compliant with the guidelines in RFC 2434.



3.5.2.  Documents that Require Assignments in Existing Namespace(s)



   If an Internet-Draft requires the IANA to update an existing registry

   prior to publication as an RFC, then the IANA Considerations section

   in the draft MUST document that fact.  MIB documents that contain the

   initial version of a MIB module will generally require that the IANA

   assign an OBJECT IDENTIFIER value for the MIB module's MODULE-

   IDENTITY value and possibly to make other assignments as well.

   Internet-Drafts containing such MIB modules MUST contain an IANA

   Considerations section that specifies the registries that are to be

   updated, the descriptors to which OBJECT IDENTIFIER values are being

   assigned, and the subtrees under which the values are to be

   allocated.  The text SHOULD be crafted so that after publication it

   will serve to document the OBJECT IDENTIFIER assignments.  For

   example, something along the following lines would be appropriate for

   an Internet-Draft containing a single MIB module with MODULE-IDENTITY

   descriptor powerEthernetMIB that is to be assigned a value under the

   'mib-2' subtree:



      The MIB module in this document uses the following IANA-assigned

      OBJECT IDENTIFIER values recorded in the SMI Numbers registry:



      Descriptor        OBJECT IDENTIFIER value

      ----------        -----------------------



      powerEthernetMIB  { mib-2 XXX }



      Editor's Note (to be removed prior to publication):  the IANA is

      requested to assign a value for "XXX" under the 'mib-2'

      subtree and to record the assignment in the SMI Numbers registry.

      When the assignment has been made, the RFC Editor is asked to

      replace "XXX" (here and in the MIB module) with the assigned

      value and to remove this note.



   Note well:  prior to official assignment by the IANA, a draft

   document MUST use placeholders (such as "XXX" above) rather than

   actual numbers.  See Section 4.5 for an example of how this is done

   in a draft MIB module.













OPS Area                    Expires June 2005                   [Page 8]



Internet-Draft        Guidelines for MIB Documents          January 2005





3.5.3.  Documents with no IANA Requests



   If an Internet-Draft makes no requests of the IANA, then that fact

   MUST be documented in the IANA Considerations section.  When an

   Internet-Draft contains an update of a previously published MIB

   module, it typically will not require any action on the part of the

   IANA, but it may inherit an IANA Considerations section documenting

   existing assignments from the RFC that contains the previous version

   of the MIB module.  In such cases the draft MUST contain a note (to

   be removed prior to publication) explicitly indicating that nothing

   is required from the IANA.  For example, a draft that contains an

   updated version of the POWER-ETHERNET-MIB [RFC3621] might include an

   IANA Considerations section like the following:



      The MIB module in this document uses the following IANA-assigned

      OBJECT IDENTIFIER values recorded in the SMI Numbers registry:



      Descriptor        OBJECT IDENTIFIER value

      ----------        -----------------------



      powerEthernetMIB  { mib-2 105 }



      Editor's Note (to be removed prior to publication):  this draft

      makes no additional requests of the IANA.



   If an Internet-Draft makes no requests of the IANA and there are no

   existing assignments to be documented, then suitable text for the

   draft would be something along the following lines:



      No IANA actions are required by this document.



3.6.  References Sections



   Section 4.7f of [RFC2223bis] specifies the requirements for the

   references sections.  In particular, there MUST be separate lists of

   normative and informative references, each in a separate section.

   The style SHOULD follow that of recently published RFCs.



   The standard MIB boilerplate available at

   http://www.ops.ietf.org/mib-boilerplate.html includes lists of

   normative and informative references that MUST appear in all IETF

   specifications that contain MIB modules.  If items from other MIB

   modules appear in an IMPORTS statement in the Definitions section,

   then the specifications containing those MIB modules MUST be included

   in the list of normative references.  When items are imported from an

   IANA-maintained MIB module the corresponding normative reference

   SHALL point to the on-line version of that MIB module.  It is the

   policy of the RFC Editor that all references must be cited in the







OPS Area                    Expires June 2005                   [Page 9]



Internet-Draft        Guidelines for MIB Documents          January 2005





   text;  such citations MUST appear in the overview section where

   documents containing imported definitions (other those already

   mentioned in the MIB boilerplate) are required to be mentioned (cf.

   Section 3.2).



   In general, each normative reference SHOULD point to the most recent

   version of the specification in question.



3.7.  Copyright Notices



   IETF MIB documents MUST contain the copyright notices and disclaimer

   specified in Sections 5.4 and 5.5 of RFC 3907 [RFC3907].  Authors and

   reviewers MUST check to 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,

   appropriate for MIB modules other than those that are to be

   maintained by the IANA, is as follows:



          DESCRIPTION

            " [ ... ]



            Copyright (C) The Internet Society (date).  This version

            of this MIB module is part of RFC yyyy;  see the RFC

            itself for full legal notices."

   -- RFC Ed.: replace yyyy with actual RFC number & remove this note



   A template suitable for MIB modules that are to be maintained by the

   IANA is as follows:



          DESCRIPTION

            " [ ... ]



            Copyright (C) The Internet Society (date).  The initial

            version of this MIB module was published in RFC yyyy;

            for full legal notices see the RFC itself.  Supplementary

            information may be available at:

            http://www.ietf.org/copyrights/ianamib.html.";

   -- RFC Ed.: replace yyyy with actual RFC number & remove this note



   In each case the current year is to be inserted in place of the word

   "date".



3.8.  Intellectual Property Section



   Section 5 of RFC 3908 [RFC3908] contains a notice regarding

   intellectual property rights or other rights that must appear in all







OPS Area                    Expires June 2005                  [Page 10]



Internet-Draft        Guidelines for MIB Documents          January 2005





   IETF RFCs.  A verbatim copy of that notice SHOULD appear in every

   IETF MIB document.



4.  SMIv2 Usage Guidelines



   In general, MIB modules in IETF standards-track specifications MUST

   comply with all syntactic and semantic requirements of SMIv2

   [RFC2578] [RFC2579] [RFC2580] that apply to "standard" MIB modules

   and except as noted below SHOULD comply with SMIv2 recommendations.

   The guidelines in this section are intended to supplement the SMIv2

   documents in the following ways:



    o to document the current generally accepted interpretation when

      those documents contain ambiguities or contradictions;



    o to update recommendations in those documents that have been shown

      by practical experience to be out-of-date or otherwise suboptimal;



    o to provide guidance in selection of SMIv2 options in cases where

      there is a consensus on a preferred approach.



4.1.  Module Names



   RFC 2578 Section 3 specifies the rules for module names.  Note in

   particular that names of "standard" modules MUST be unique, MUST

   follow the syntax rules in RFC 2578 Section 3, and MUST NOT be

   changed when a MIB module is revised (see also RFC 2578 Section 10).



   It is RECOMMENDED that module names be mnemonic.  See Appendix C for

   suggested naming conventions.



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

   automated tools such as MIB compilers SHOULD NOT by default generate

   warnings for violating that recommendation.







OPS Area                    Expires June 2005                  [Page 11]



Internet-Draft        Guidelines for MIB Documents          January 2005





   Note that violations of the 64 character limit MUST NOT be ignored;

   they MUST be treated as errors.



   See Appendix C for suggested descriptor and TC naming conventions.



4.3.  Naming Hierarchy



   RFC 2578 Section 4 describes the object identifier subtrees that are

   maintained by IANA and specifies the usages for those subtrees.  In

   particular, the mgmt subtree { iso 3 6 1 2 } is used to identify IETF

   "standard" objects, while the experimental subtree { iso 3 6 1 3 } is

   used to identify objects that are under development in the IETF.  It

   is REQUIRED that objects be moved from the experimental subtree to

   the mgmt subtree when a MIB module enters the IETF standards track.



   Experience has shown that it is impractical to move objects from one

   subtree to another once those objects have seen large-scale use in an

   operational environment.  Hence any object that is targeted for

   deployment in an operational environment MUST NOT be registered under

   the experimental subtree, irrespective of the standardization status

   of that object.  The experimental subtree should be used only for

   objects that are intended for limited experimental deployment.  Such

   objects typically are defined in Experimental RFCs.



   Note:  the term "object", as used here and in RFC 2578 Section 4, is

   to be broadly interpreted as any construct that results in an OBJECT

   IDENTIFIER registration.  The list of such constructs is specified in

   RFC 2578 Section 3.6.



4.4.  IMPORTS Statement



   RFC 2578 Section 3.2 specifies which symbols must be imported and

   also lists certain pre-defined symbols that must not be imported.



   The general requirement is that if an external symbol other than a

   predefined ASN.1 type or the BITS construct is used, then it MUST be

   mentioned in the module's IMPORTS statement.  The words "external

   object" in the first paragraph of that section may give the

   impression that such symbols are limited to those that refer to

   object definitions, but that is not the case, as subsequent

   paragraphs should make clear.



   Note that exemptions to this general requirement are granted by RFC

   2580 Sections 5.4.3 and 6.5.2 for descriptors of objects appearing in

   the OBJECT clause of a MODULE-COMPLIANCE statement or in the

   VARIATION clause of an AGENT-CAPABILITIES statement.  Some MIB

   compilers also grant exemptions to descriptors of notifications

   appearing in a VARIATION clause and to descriptors of object groups







OPS Area                    Expires June 2005                  [Page 12]



Internet-Draft        Guidelines for MIB Documents          January 2005





   and notification groups referenced by a MANDATORY-GROUPS clause, a

   GROUP clause, or an INCLUDES clause, although RFC 2580 (through

   apparent oversight) does not mention those cases.  The exemptions are

   sometimes seen as unhelpful because they make IMPORTS rules more

   complicated and inter-module dependencies less obvious than they

   otherwise would be.  External symbols referenced by compliance

   statements and capabilities statements MAY therefore be listed in the

   IMPORTS statement;  if this is done, it SHOULD be done consistently.



   Finally, even though it is not forbidden by the SMI, it is considered

   poor style to import symbols that are not used, and standards-track

   MIB modules SHOULD NOT do so.



4.5.  MODULE-IDENTITY Invocation



   RFC 2578 Section 3 requires that all SMIv2 MIB modules start with

   exactly one invocation of the MODULE-IDENTITY macro.  This invocation

   MUST appear immediately after the IMPORTS statement.



   RFC 2578 Section 5 describes how the various clauses are used.  The

   following additional guidelines apply to all MIB modules over which

   the IETF has change control:



   - If the module was developed by an IETF working group, then the

     ORGANIZATION clause MUST provide the full name of the working

     group, and the CONTACT-INFO clause MUST include working group

     mailing list information.  The CONTACT-INFO clause SHOULD also

     provide a pointer to the working group's web page.



   - A REVISION clause MUST be present for each revision of the MIB

     module, and the UTC time of the most recent REVISION clause MUST

     match that of the LAST-UPDATED clause.  The DESCRIPTION clause

     associated with each revision MUST state in which RFC that revision

     appeared and SHOULD provide a list of all significant changes.

     When a MIB module is revised UTC times in all REVISION clauses

     SHOULD be updated to use four-digit year notation.



   - The value assigned to the MODULE-IDENTITY descriptor MUST be unique

     and (for IETF standards-track MIB modules) SHOULD reside under the

     mgmt subtree [RFC2578].  Most often it will be an IANA-assigned

     value directly under mib-2 [RFC2578], although for media-specific

     MIB modules that extend the IF-MIB [RFC2863] it is customary to use

     an IANA-assigned value under transmission [RFC2578].  In the past

     some IETF working groups have made their own assignments from

     subtrees delegated to them by IANA, but that practice has proven

     problematic and is NOT RECOMMENDED.











OPS Area                    Expires June 2005                  [Page 13]



Internet-Draft        Guidelines for MIB Documents          January 2005





   While a MIB module is under development, the RFC number in which it

   will eventually be published is usually unknown and must be filled in

   by the RFC Editor prior to publication.  An appropriate form for the

   REVISION clause applying to a version under development would be

   something along the following lines:



          REVISION    "200212132358Z"  -- December 13, 2002

          DESCRIPTION "Initial version, published as RFC yyyy."

   -- RFC Ed.: replace yyyy with actual RFC number & remove this note



   Note that after RFC publication a REVISION clause is present only for

   published versions of a MIB module and not for interim versions that

   existed only as Internet-Drafts.  Thus, a draft version of a MIB

   module MUST contain just one new REVISION clause that covers all

   changes since the last published version (if any).



   When the initial version of a MIB module is under development, the

   value assigned to the MODULE-IDENTITY descriptor will be unknown if

   an IANA-assigned value is used, because the assignment is made just

   prior to publication as an RFC.  The accepted form for the MODULE-

   IDENTITY statement in draft versions of such a module is something

   along the following lines:



      <descriptor> MODULE-IDENTITY



          [ ... ]



          ::= { <subtree> XXX }

   -- RFC Ed.: replace XXX with IANA-assigned number & remove this note



   where <descriptor> is whatever descriptor has been selected for the

   module and <subtree> is the subtree under which the module is to be

   registered (e.g., mib-2 or transmission).  Note that XXX must be

   temporarily replaced by a number in order for the module to compile.



   Note well:  prior to official assignment by the IANA, a draft

   document MUST use a placeholder (such as "XXX" above) rather than an

   actual number.  If trial implementations are desired during the

   development process, then an assignment under the 'experimental'

   subtree may be obtained from the IANA (cf. Section 4.3).



4.6.  Textual Conventions and Object Definitions



4.6.1.  Usage of Data Types















OPS Area                    Expires June 2005                  [Page 14]



Internet-Draft        Guidelines for MIB Documents          January 2005





4.6.1.1.  INTEGER, Integer32, Gauge32, and Unsigned32



   The 32-bit integer data types INTEGER, Integer32, Gauge32, and

   Unsigned32 are described in RFC 2578 Section 2 and further elaborated

   in RFC 2578 Sections 7.1.1, 7.1.7, and 7.1.11.  The following

   guidelines apply when selecting one of these data types for an object

   definition or a textual convention:



   - For integer-valued enumerations:



     - INTEGER is REQUIRED;

     - Integer32, Unsigned32, and Gauge32 MUST NOT be used.



   Note that RFC 2578 recommends (but does not require) that integer-

   valued enumerations start at 1 and be numbered contiguously.  This

   recommendation SHOULD be followed unless there is a valid reason to

   do otherwise, e.g., to match values of external data or to indicate

   special cases, and any such special-case usage SHOULD be clearly

   documented.  For an example see the InetAddressType TC [RFC3291bis].



   Although the SMI allows DEFVAL clauses for integer-valued

   enumerations to specify the default value either by label or by

   numeric value, the label form is preferred since all the examples in

   RFC 2578 are of that form and some tools do not accept the numeric

   form.



   - If the value range is between -2147483648..2147483647 (inclusive)

     and negative values are possible, then:



     - Integer32 is RECOMMENDED;

     - INTEGER is acceptable;

     - Unsigned32 and Gauge32 MUST NOT be used.



   - If the value range is between 0..4294967295 (inclusive) and the

     value of the information being modelled may increase above the

     maximum value or decrease below the minimum value, then:



     - Gauge32 is RECOMMENDED;

     - Unsigned32 is acceptable;

     - INTEGER and Integer32 MUST NOT be used if

       values greater than 2147483647 are possible.



   - If the value range is between 0..4294967295 (inclusive), and values

     greater than 2147483647 are possible, and the value of the

     information being modelled does not increase above the maximum

     value nor decrease below the minimum value, then:



     - Unsigned32 is RECOMMENDED;







OPS Area                    Expires June 2005                  [Page 15]



Internet-Draft        Guidelines for MIB Documents          January 2005





     - Gauge32 is acceptable;

     - INTEGER and Integer32 MUST NOT be used.



   - If the value range is between 0..2147483647 (inclusive), and the

     value of the information being modelled does not increase above the

     maximum value nor decrease below the minimum value, then:



     - Unsigned32 is RECOMMENDED;

     - INTEGER, Integer32, and Gauge32 are acceptable.



   - For integer-valued objects that appear in an INDEX clause or for

     integer-valued TCs that are to be used in an index column:



     - Unsigned32 with a range that excludes zero is RECOMMENDED for

       most index objects.  It is acceptable to include zero in the

       range when it is semantically significant or when it is used as

       the index value for a unique row with special properties.   Such

       usage SHOULD be clearly documented in the DESCRIPTION clause.



     - Integer32 or INTEGER with a non-negative range is acceptable.

       Again, zero SHOULD be excluded from the range except when it is

       semantically significant or when it is used as the index value

       for a unique row with special properties, and in such cases the

       usage SHOULD be clearly documented in the DESCRIPTION clause.



     - Use of Gauge32 is acceptable for index objects that have gauge

       semantics.



   The guidelines above combine both the usage rules for integer data

   types and the INDEX rules in RFC 2578 Section 7.7 up to and including

   bullet (1) plus the next-to-last paragraph on page 28.



   Sometimes it will be necessary for external variables to represent

   values of an index object -- e.g., ifIndex [RFC2863].  In such cases

   authors of the module containing that object SHOULD consider defining

   TCs such as InterfaceIndex and/or InterfaceIndexOrZero [RFC2863].



   Note that INTEGER is a pre-defined ASN.1 type and MUST NOT be present

   in a module's IMPORTS statement, whereas Integer32, Gauge32, and

   Unsigned32 are defined by SNMPv2-SMI and MUST be imported from that

   module if used.



4.6.1.2.  Counter32 and Counter64



   Counter32 and Counter64 have special semantics as described in RFC

   2578 Sections 7.1.6 and 7.1.10 respectively.  Object definitions MUST

   (and textual conventions SHOULD) respect these semantics.  That

   means:







OPS Area                    Expires June 2005                  [Page 16]



Internet-Draft        Guidelines for MIB Documents          January 2005





   - 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

     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(s) 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 3593 [RFC3593] or RFC 3705 [RFC3705].



   RFC 2578 Section 7.1.10 places a requirement on "standard" MIB

   modules that the Counter64 type may be used only if the information

   being modelled would wrap in less than one hour if the Counter32 type

   was used instead.  Now that SNMPv3 is an Internet Standard and SNMPv1

   is Historic (see http://www.rfc-editor.org/rfcxx00.html for status

   and [RFC3410] for rationale) there is no reason to continue enforcing

   this restriction.  Henceforth "standard" MIB modules MAY use the

   Counter64 type when it makes sense to do so, and MUST use Counter64

   if the information being modelled would wrap in less than one hour if

   the Counter32 type was used instead.  Note also that there is no

   longer a requirement to define Counter32 counterparts for each

   Counter64 object, although one is still allowed to do so.



   There also exist closely-related textual conventions

   ZeroBasedCounter32 and ZeroBasedCounter64 defined in RMON2-MIB

   [RFC2021] and HCNUM-TC [RFC2856], respectively.



   The only difference between ZeroBasedCounter32/64 TCs and

   Counter32/64 is their starting value;  at time=X, where X is their

   minimum-wrap-time after they were created, the behavior of







OPS Area                    Expires June 2005                  [Page 17]



Internet-Draft        Guidelines for MIB Documents          January 2005





   ZeroBasedCounter32/64 becomes exactly the same as Counter32/64.

   Thus, the preceding paragraphs/rules apply not only to Counter32/64,

   but also to ZeroBasedCounter32/64 TCs.



4.6.1.3.  CounterBasedGauge64



   SMIv2 unfortunately does not provide 64-bit integer base types.  In

   order to make up for this omission, the CounterBasedGauge64 textual

   convention is defined in HCNUM-TC [RFC2856].  This TC uses Counter64

   as a base type, but discards the special counter semantics, which is

   allowed under the generally accepted interpretation of RFC 2579

   Section 3.3.  It does inherit all the syntactic restrictions of that

   type, which means that it MUST NOT be subtyped and that objects

   defined with it MUST NOT appear in an INDEX clause, MUST NOT have a

   DEFVAL clause, and MUST have a MAX-ACCESS of read-only or accessible-

   for-notify.



   This TC SHOULD be used for object definitions that require a 64-bit

   unsigned data type with gauge semantics.  If a 64-bit unsigned data

   type with different semantics is needed, then a different TC based on

   Counter64 MUST be used, since one TC cannot refine another (cf. RFC

   2579 Section 3.5).



4.6.1.4.  OCTET STRING



   The OCTET STRING type is described in RFC 2578 Section 7.1.2.  It

   represents arbitrary binary or textual data whose length is between 0

   and 65535 octets inclusive.  Objects and TCs whose SYNTAX is of this

   type SHOULD have a size constraint when the actual bounds are more

   restrictive than the SMI-imposed limits.  This is particularly true

   for index objects.  Note, however, that size constraints SHOULD NOT

   be imposed arbitrarily, as the SMI does not permit them to be changed

   afterward.



   There exist a number of standard TCs that cater to some of the more

   common requirements for specialized OCTET STRING types.  In

   particular, SNMPv2-TC [RFC2579] contains the DisplayString,

   PhysAddress, MacAddress, and DateAndTime TCs, the SNMP-FRAMEWORK-MIB

   [RFC3411] contains the SnmpAdminString TC, and the SYSAPPL-MIB

   [RFC2287] contains the Utf8String and LongUtf8String TCs.  When a

   standard TC provides the desired semantics, it SHOULD be used in an

   object's SYNTAX clause instead of OCTET STRING or an equivalent

   locally-defined TC.



   Note that OCTET STRING is a pre-defined ASN.1 type and MUST NOT be

   present in a module's IMPORTS statement.











OPS Area                    Expires June 2005                  [Page 18]



Internet-Draft        Guidelines for MIB Documents          January 2005





4.6.1.5.  OBJECT IDENTIFIER



   The OBJECT IDENTIFIER type is described in RFC 2578 Section 7.1.3.

   Its instances represent administratively assigned names.  Note that

   both the SMI and the SNMP protocol limit instances of this type to

   128 sub-identifiers and require that each sub-identifier be within

   the range 0 to 4294967295 inclusive.  Sub-typing is not allowed.



   The purpose of OBJECT IDENTIFIER values is to provide authoritative

   identification either for some type of item or for a specific

   instance of some type of item.  Among the items that can be

   identified in this way are definitions in MIB modules created via the

   MODULE-IDENTITY, OBJECT-IDENTITY, OBJECT-TYPE, NOTIFICATION-TYPE,

   OBJECT-GROUP, NOTIFICATION-GROUP, MODULE-COMPLIANCE, and AGENT-

   CAPABILITIES constructs, instances of objects defined in MIB modules,

   protocols, languages, specifications, interface types, hardware, and

   software.  For some of these uses other possibilities exist, e.g.,

   OCTET STRING or enumerated INTEGER values.  The OBJECT IDENTIFIER

   type SHOULD be used instead of the alternatives when the set of

   identification values needs to be independently extensible without

   the need for a registry to provide centralized coordination.



   There exist a number of standard TCs that cater to some of the more

   common requirements for specialized OBJECT IDENTIFIER types.  In

   particular, SNMPv2-TC [RFC2579] contains the AutonomousType,

   VariablePointer, and RowPointer TCs.  When a standard TC provides the

   desired semantics, it SHOULD be used in an object's SYNTAX clause

   instead of OBJECT IDENTIFIER or an equivalent locally-defined TC.



   Note that OBJECT IDENTIFIER is a pre-defined ASN.1 type and MUST NOT

   be present in a module's IMPORTS statement.



4.6.1.6.  The BITS Construct



   The BITS construct is described in RFC 2578 Section 7.1.4.  It

   represents an enumeration of named bits.  The bit positions in a TC

   or object definition whose SYNTAX is of this type MUST start at 0 and

   SHOULD be contiguous.



   Note that the BITS construct is defined by the macros that use it and

   therefore MUST NOT be present in a module's IMPORTS statement.



4.6.1.7.  IpAddress



   The IpAddress type described in RFC 2578 Section 7.1.5 SHOULD NOT be

   used in new MIB modules.  The InetAddress/InetAddressType textual

   conventions [RFC3291bis] SHOULD be used instead.









OPS Area                    Expires June 2005                  [Page 19]



Internet-Draft        Guidelines for MIB Documents          January 2005





4.6.1.8.  TimeTicks



   The TimeTicks type is described in RFC 2578 Section 7.1.8.  It

   represents the time in hundredths of a second between two epochs,

   reduced modulo 2^32.  It MUST NOT be sub-typed, and the DESCRIPTION

   clause of any object or TC whose SYNTAX is of this type MUST identify

   the reference epochs.



   The TimeTicks type SHOULD NOT be used directly in definitions of

   objects that are snapshots of sysUpTime [RFC3418].  The TimeStamp TC

   [RFC2579] already conveys the desired semantics and SHOULD be used

   instead.



4.6.1.9.  TruthValue



   The TruthValue TC is defined in SNMPv2-TC [RFC2579].  It is an

   enumerated INTEGER type that assumes the values true(1) and false(2).



   This TC SHOULD be used in the SYNTAX clause of object definitions

   that require a Boolean type.  MIB modules SHOULD NOT use enumerated

   INTEGER types or define TCs that duplicate its semantics.



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 B contains a partial list that includes

   those plus some others that are a bit more specialized.  An on-line

   version of that list, which is updated as new TCs are developed, can

   be found at http://www.ops.ietf.org/mib-common-tcs.html.



   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.



   MIB module authors need to be aware that enumerated INTEGER or BITS

   TCs may in some cases be extended with additional enumerated values

   or additional bit positions.  When an imported TC that may be

   extended in this way is used to define an object that may be written

   or that serves as an index in a read-create table, then the set of

   values or bit positions that needs to be supported SHOULD be

   specified either in the object's DESCRIPTION clause or in an OBJECT

   clause in the MIB module's compliance statement(s).  This may be done

   by explicitly listing the required values or bit positions, or it may







OPS Area                    Expires June 2005                  [Page 20]



Internet-Draft        Guidelines for MIB Documents          January 2005





   be done by stating that an implementation may support a subset of

   values or bit positions of its choosing.



4.6.2.  DESCRIPTION and REFERENCE Clauses



   It is hard to overemphasize the importance of an accurate and

   unambiguous DESCRIPTION clause for all objects and TCs.  The

   DESCRIPTION clause contains the instructions that implementors will

   use to implement an object, and if they are inadequate or ambiguous,

   then implementation quality will suffer.  Probably the single most

   important job of a MIB reviewer is to ensure that DESCRIPTION clauses

   are sufficiently clear and unambiguous to allow interoperable

   implementations to be created.



   A very common problem is to see an object definition for, say,

   'stdMIBPoofpoofCounter' with a DESCRIPTION clause that just says

   "Number of poofpoofs" with no indication what a 'poofpoof' is.  In

   such cases it is strongly RECOMMENDED that there either be at least a

   minimal explanation or else a REFERENCE clause to point to the

   definition of a 'poofpoof'.



   For read-write objects (other than columns in read-create tables that

   have well-defined persistence properties) it is RECOMMENDED that the

   DESCRIPTION clause specify what happens to the value after an agent

   reboot.  Among the possibilities are that the value remains

   unchanged, that it reverts to a well-defined default value, or that

   the result is implementation-dependent.



4.6.3.  DISPLAY-HINT Clause



   The DISPLAY-HINT clause is used in a TC to provide a non-binding hint

   to a management application as to how the value of an instance of an

   object defined with the syntax in the TC might be displayed.  Its

   presence is optional.



   Although management applications typically default to decimal format

   ("d") for integer TCs which are not enumerations and to a hexadecimal

   format ("1x:" or "1x " or "1x_") for octet string TCs when the

   DISPLAY-HINT clause is absent, it should be noted that SMIv2 does not

   actually specify any defaults.  MIB authors should be aware that a

   clear hint is provided to applications only when the DISPLAY-HINT

   clause is present.



4.6.4.  Conceptual Table Definitions



   RFC 2578 Sections 7.1.12 and 7.1.12.1 specify the rules for defining

   conceptual tables, and RFC 2578 Sections 7.7, 7.8, and 7.8.1 specify

   conceptual table indexing rules.  The following guidelines apply to







OPS Area                    Expires June 2005                  [Page 21]



Internet-Draft        Guidelines for MIB Documents          January 2005





   such definitions:



   - For conceptual rows:



     - If the row is an extension of a row in some other table, then an

       AUGMENTS clause MUST be used if the relationship is one-to-one,

       and an INDEX clause MUST be used if the relationship is sparse.

       In the latter case the INDEX clause SHOULD be identical to that

       of the original table.



     - If the row is an element of an expansion table -- that is, if

       multiple row instances correspond to a single row instance in

       some other table -- then an INDEX clause MUST be used, and the

       first-mentioned elements SHOULD be the indices of that other

       table, listed in the same order.



     - If objects external to the row are present in the INDEX clause,

       then the conceptual row's DESCRIPTION clause MUST specify how

       those objects are used in identifying instances of its columnar

       objects, and in particular MUST specify for which values of those

       index objects the conceptual row may exist.



     - Use of the IMPLIED keyword is NOT RECOMMENDED for any index

       object that may appear in the INDEX clause of an expansion table.

       Since this keyword may be associated only with the last object in

       an INDEX clause, it cannot be associated with the same index

       object in a primary table and an expansion table.  This will

       cause the sort order to be different in the primary table and any

       expansion tables.  As a consequence, an implementation will be

       unable to reuse indexing code from the primary table in expansion

       tables, and data structures meant to be extended might actually

       have to be replicated.  Designers who are tempted to use IMPLIED

       should consider that the resulting sort order rarely meets user

       expectations, particularly for strings that include both upper

       and lower-case letters, and it does not take the user language or

       locale into account.



   - If dynamic row creation and/or deletion by management applications

     is supported, then:



     - There MUST be one columnar object with a SYNTAX value of

       RowStatus [RFC2579] and a MAX-ACCESS value of read-create.  This

       object is called the status column for the conceptual row.  All

       other columnar objects MUST have a MAX-ACCESS value of read-

       create, read-only, accessible-for-notify, or not-accessible;  a

       MAX-ACCESS value of read-write is not allowed.











OPS Area                    Expires June 2005                  [Page 22]



Internet-Draft        Guidelines for MIB Documents          January 2005





     - There either MUST be one columnar object with a SYNTAX value of

       StorageType [RFC2579] and a MAX-ACCESS value of read-create, or

       else the row object (table entry) DESCRIPTION clause MUST specify

       what happens to dynamically-created rows after an agent restart.



     - If the agent itself may also create and/or delete rows, then the

       conditions under which this can occur MUST be clearly documented

       in the row object DESCRIPTION clause.



   - For conceptual rows that include a status column:



     - The DESCRIPTION clause of the status column MUST specify which

       columnar objects (if any) have to be set to valid values before

       the row can be activated.  If any objects in cascading tables

       have to be populated with related data before the row can be

       activated, then this MUST also be specified.



     - The DESCRIPTION clause of the status column MUST specify whether

       or not it is possible to modify other columns in the same

       conceptual row when the status value is active(1).  Note that in

       many cases it will be possible to modify some writeable columns

       when the row is active but not others.  In such cases the

       DESCRIPTION clause for each writeable column SHOULD state whether

       or not that column can be modified when the row is active, and

       the DESCRIPTION clause for the status column SHOULD state that

       modifiability of other columns when the status value is active(1)

       is specified in the DESCRIPTION clauses for those columns (rather

       than listing the modifiable columns individually).



   - For conceptual rows that include a StorageType column:



     - The DESCRIPTION clause of the StorageType column MUST specify

       which read-write or read-create columnar objects in permanent(4)

       rows an agent must, at a minimum, allow to be writable.



   Complete requirements for the RowStatus and StorageType TCs can be

   found in RFC 2579, in the DESCRIPTION clauses for those TCs.



4.6.5.  OID Values Assigned to Objects



   RFC 2578 Section 7.10 specifies the rules for assigning OBJECT

   IDENFIFIER (OID) values to OBJECT-TYPE definitions.  In particular:



   - A conceptual table MUST have exactly one subordinate object, which

     is a conceptual row.  The OID assigned to the conceptual row MUST

     be derived by appending a sub-identifier of "1" to the OID assigned

     to the conceptual table.









OPS Area                    Expires June 2005                  [Page 23]



Internet-Draft        Guidelines for MIB Documents          January 2005





   - A conceptual row has as many subordinate objects as there are

     columns in the row;  there MUST be at least one.  The OID assigned

     to each columnar object MUST be derived by appending a non-zero

     sub-identifier, unique within the row, to the OID assigned to the

     conceptual row.



   - A columnar or scalar object MUST NOT have any subordinate objects.



   - The last sub-identifier of an OID assigned to any object (be it

     table, row, column, or scalar) MUST NOT be equal to zero.  Note

     that sub-identifiers of intermediate nodes MAY be equal to zero.



   - The OID assigned to an object definition MUST NOT also be assigned

     to another definition that results in OID registration.  RFC 2578

     Section 3.6 lists the constructs that create OID registrations.



   Although it is not specifically required by the SMI, it is customary

   (and strongly RECOMMENDED) that object definitions not be registered

   beneath group definitions, compliance statements, capabilities

   statements, or notification definitions.  It is also customary (and

   strongly RECOMMENDED) that group definitions, compliance statements,

   capabilities statements, and notification definitions not be

   registered beneath object definitions.  See Appendix D for a

   RECOMMENDED OID assignment scheme.



4.6.6.  OID Length Limitations and Table Indexing



   As specified in RFC 2578 Section 3.5, all OIDs are limited to 128

   sub-identifiers.  While this is not likely to cause problems with

   administrative assignments, it does place some limitations on table

   indexing.  That is true because the length limitation also applies to

   OIDs for object instances, and these consist of the concatenation of

   the "base" OID assigned in the object definition plus the index

   components.  When a table has multiple indices of types such as OCTET

   STRING or OBJECT IDENTIFIER that resolve to multiple sub-identifiers,

   then the 128 sub-identifier limit can be quickly reached.



   Despite its inconvenience, the 128 sub-identifier limit is not

   something that can be ignored.  In addition to being imposed by the

   SMI, it is also imposed by the SNMP (see the last paragraph in

   Section 4.1 of RFC 3416 [RFC3416]).  It follows that any table with

   enough indexing components to violate this limit cannot be read or

   written using the SNMP and so is unusable.  Hence table design MUST

   take the 128 sub-identifier limit into account.  It is RECOMMENDED

   that all MIB documents make explicit any limitations on index

   component lengths that management software must observe.  This may be

   done either by including SIZE constraints on the index components or

   by specifying applicable constraints in the conceptual row







OPS Area                    Expires June 2005                  [Page 24]



Internet-Draft        Guidelines for MIB Documents          January 2005





   DESCRIPTION clause or in the surrounding documentation.



4.7.  Notification Definitions



   RFC 2578 Section 8 specifies the rules for notification definitions.

   In particular:



   - Inaccessible objects MUST NOT appear in the OBJECTS clause.



   - For each object type mentioned in the OBJECTS clause, the

     DESCRIPTION clause MUST specify which object instance is to be

     present in the transmitted notification and MUST specify the

     information/meaning conveyed.



   - The OBJECT IDENTIFIER (OID) value assigned to each notification

     type MUST have a next-to-last sub-identifier of zero, so that it is

     possible to convert an SMIv2 notification definition into an SMIv1

     trap definition and back again without information loss (see

     [RFC3584] Section 2.1.2) and possible for a multilingual proxy

     chain to translate an SNMPv2 trap into an SNMPv1 trap and back

     again without information loss (see [RFC3584] Section 3).  In

     addition, the OID assigned to a notification definition MUST NOT

     also be assigned to another definition that results in OID

     registration.  RFC 2578 Section 3.6 lists the constructs that

     create OID registrations.



   Although it is not specifically required by the SMI, it is customary

   (and strongly RECOMMENDED) that notification definitions not be

   registered beneath group definitions, compliance statements,

   capabilities statements, or object definitions (this last is

   especially unwise, as it may result in an object instance and a

   notification definition sharing the same OID).  It is also customary

   (and strongly RECOMMENDED) that the OIDs assigned to notification

   types be leaf OIDs (i.e., that there be no OID registrations

   subordinate to a notification definition).  See Appendix D for a

   RECOMMENDED OID assignment scheme.



   In many cases notifications will be triggered by external events, and

   sometimes it will be possible for those external events to occur at a

   sufficiently rapid rate that sending a notification for each

   occurrence would overwhelm the network.  In such cases a mechanism

   MUST be provided for limiting the rate at which the notification can

   be generated.  A common technique is to require that the notification

   generator use throttling -- that is, to require that it generate no

   more than one notification for each event source in any given time

   interval of duration T.  The throttling period T MAY be configurable,

   in which case it is specified in a MIB object, or it MAY be fixed, in

   which case it is specified in the notification definition.  Examples







OPS Area                    Expires June 2005                  [Page 25]



Internet-Draft        Guidelines for MIB Documents          January 2005





   of the fixed time interval technique can be found in the SNMP-

   REPEATER-MIB [RFC2108] and in the ENTITY-MIB [RFC2737bis].



4.8.  Compliance Statements



   RFC 2580 Sections 3, 4, and 5 specify the rules for conformance

   groups and compliance statements.  In particular:



   - Every object with a MAX-ACCESS value other than "not-accessible"

     MUST be contained in at least one object group.



   - Every notification MUST be contained in at least one notification

     group.



   - There MUST be at least one compliance statement defined for each

     "standard" MIB module.  It may reside either within that MIB module

     or within a companion MIB module.



   In writing compliance statements there are several points that are

   easily overlooked:



   - An object group or notification group that is not mentioned either

     in the MANDATORY-GROUPS clause or in any GROUP clause of a MODULE-

     COMPLIANCE statement is unconditionally optional with respect to

     that compliance statement.  An alternate way to indicate that an

     object group or notification group is optional is to mention it in

     a GROUP clause whose DESCRIPTION clause states that the group is

     optional.  The latter method is RECOMMENDED (for optional groups

     that are relevant to the compliance statement) in order to make it

     clear that the optional status is intended rather than being the

     result of an act of omission.



   - If there are any objects with a MAX-ACCESS value of read-write or

     read-create for which there is no OBJECT clause that specifies a

     MIN-ACCESS of read-only, then implementations must support write

     access to those objects in order to be compliant with that MODULE-

     COMPLIANCE statement.  This fact sometimes catches MIB module

     authors by surprise.  When confronted with such cases, reviewers

     SHOULD verify that this is indeed what the authors intended, since

     it often is not.



   - On the other side of the coin, MIB module authors need to be aware

     that while a read-only compliance statement is sufficient to

     support interoperable monitoring applications, it is not sufficient

     to support interoperable configuration applications.  A technique

     commonly used in MIB modules that are intended to support both

     monitoring and configuration is to provide both a read-only

     compliance statement and a full compliance statement.  A good







OPS Area                    Expires June 2005                  [Page 26]



Internet-Draft        Guidelines for MIB Documents          January 2005





     example is provided by the DIFFSERV-MIB [RFC3289].  Authors SHOULD

     consider using this technique when it is applicable.



   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:



    OBJECT       diffServDataPathStatus

    SYNTAX       RowStatus { active(1) }

    MIN-ACCESS   read-only

    DESCRIPTION

       "Write access is not required, and active is the only status that

       needs to be supported."



   One cannot do this for inaccessible index objects because they cannot

   be present in object groups and cannot be mentioned in OBJECT

   clauses.  There are situations, however, in which one might wish to

   indicate that an implementation is required to support only a subset

   of the possible values of some index in a read-create table.  In such

   cases the requirements MUST be specified either in the index object's

   DESCRIPTION clause (RECOMMENDED if there is only one value subset) or

   in the DESCRIPTION clause of a MODULE-COMPLIANCE statement (REQUIRED

   if the value subset is unique to the compliance statement).



   In many cases a MIB module is always implemented in conjunction with

   one or more other MIB modules.  That fact is REQUIRED to be noted in

   the surrounding documentation (see Section 3.2 above), and it SHOULD

   also be noted in the relevant compliance statements as well.  In

   cases where a particular compliance statement in (say) MIB module A

   requires the complete implementation of some other MIB module B, then

   the RECOMMENDED approach is to include a statement to that effect in

   the DESCRIPTION clause of the compliance statement(s) in MIB module

   A.  It is also possible, however, that MIB module A might have







OPS Area                    Expires June 2005                  [Page 27]



Internet-Draft        Guidelines for MIB Documents          January 2005





   requirements that are different from those that are expressed by any

   any compliance statement of module B -- for example, module A might

   not require any of the unconditionally mandatory object groups from

   module B but might require mandatory implementation of an object

   group from module B that is only conditionally mandatory with respect

   to the compliance statement(s) in module B.  In such cases the

   RECOMMENDED approach is for the compliance statement(s) in module A

   to formally specify requirements with respect to module B via

   appropriate MODULE, MANDATORY-GROUPS, GROUP, and OBJECT clauses.  An

   example is provided by the compliance statements in the DIFFSERV-MIB

   [RFC3289], which list the ifCounterDiscontinuityGroup from IF-MIB

   [RFC2863] as a mandatory group.  That group is not sufficient to

   satisfy any IF-MIB compliance statement, and it is conditionally

   mandatory in the IF-MIB's current compliance statement ifCompliance3.



   _______________________________

   (*) 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].



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

     MUST be replaced with up-to-date information.  See Section 4.5

     above for additional requirements that apply to MIB modules that

     are under IETF change control.



   - On the other hand, the module name MUST NOT be changed (except to

     correct typographical errors), existing definitions (even obsolete

     ones) MUST NOT be removed from the MIB module, and descriptors and

     OBJECT IDENTIFIER values associated with existing definitions MUST

     NOT be changed or re-assigned.







OPS Area                    Expires June 2005                  [Page 28]



Internet-Draft        Guidelines for MIB Documents          January 2005





   It is important to note that the purpose in forbidding certain kinds

   of changes is to ensure that a revised MIB module is compatible with

   fielded implementations based on previous versions of the module.

   There are two distinct aspects of this backward compatibility

   requirement.  One is "over the wire" compatibility of agent and

   manager implementations that are based on different revisions of the

   MIB module.  The other is "compilation" compatibility with MIB

   modules that import definitions from the revised MIB module.  The

   rules forbidding changing or re-assigning OBJECT IDENTIFIER values

   are necessary to ensure "over the wire" compatibility;  the rules

   against changing module names or descriptors or removing obsolete

   definitions are necessary to ensure compilation compatibility.



   RFC 2578 Section 10.2 specifies rules that apply to revisions of

   object definitions.  The following guidelines correct some errors in

   these rules and provided some clarifications:



   - Bullet (1) allows the labels of named numbers and named bits in

     SYNTAX clauses of type enumerated INTEGER or BITS to be changed.

     This can break compilation compatibility, since those labels may be

     used by DEFVAL clauses in modules that import the definitions of

     the affected objects.  Therefore, labels of named numbers and named

     bits MUST NOT be changed when revising IETF MIB modules (except to

     correct typographical errors), and they SHOULD NOT be changed when

     revising enterprise MIB modules.



   - Although not specifically permitted in bullets (1) through (8), it

     is generally considered acceptable to add range constraints to the

     SYNTAX clause of an integer-valued object, provided that the

     constraints simply make explicit some value restrictions that were

     implicit in the definition of the object.  The most common example

     is an auxiliary object with a SYNTAX of INTEGER or Integer32 with

     no range constraint.  Since an auxiliary object is not permitted to

     assume negative values, adding the range constraint (0..2147483647)

     cannot possibly result in any "over the wire" change, nor will it

     cause any compilation compatibility problems with a correctly

     written MIB module.  Such a change SHOULD be treated by a reviewer

     as an editorial change, not as a semantic change.  Similarly,

     removal of a range or size constraint from an object definition

     when that range or size constraint is enforced by the underlying

     data type SHOULD be treated by a reviewer as an editorial change.



   RFC 2578 Section 10.3 specifies rules that apply to revisions of

   notification definitions.  No clarifications or corrections are

   required.



   RFC 2579 Section 5 specifies rules that apply to revisions of textual

   convention definitions.  The following guideline corrects an error in







OPS Area                    Expires June 2005                  [Page 29]



Internet-Draft        Guidelines for MIB Documents          January 2005





   these rules:



   - Bullet (1) allows the labels of named numbers and named bits in

     SYNTAX clauses of type enumerated INTEGER or BITS to be changed.

     This can break compilation compatibility, since those labels may be

     used by DEFVAL clauses in modules that import the definitions of

     the affected TCs.  Therefore, labels of named numbers and named

     bits MUST NOT be changed when revising IETF MIB modules (except to

     correct typographical errors), and they SHOULD NOT be changed when

     revising enterprise MIB modules.



   RFC 2580 Section 7.1 specifies rules that apply to revisions of

   conformance groups.  Two point are worth re-iterating:



   - Objects and notifications MUST NOT be added to or removed from an

     existing object group or notification group.  Doing so could cause

     a compilation failure or (worse) a silent change in the meaning of

     a compliance statement or capabilities statement that refers to

     that group.



   - The status of a conformance group is independent of the status of

     its members.  Thus, a current group MAY refer to deprecated objects

     or notifications.  This may be desirable in certain cases, e.g., a

     set of widely-deployed objects or notifications may be deprecated

     when they are replaced by a more up-to-date set of definitions, but

     the conformance groups that contain them may remain current in

     order to encourage continued implementation of the deprecated

     objects and notifications.



   RFC 2580 Section 7.2 specifies rules that apply to revisions of

   compliance statements.  The following guidelines correct an omission

   from these rules and emphasize one important point:



   - RFC 2580 should (but does not) recommend that an OBJECT clause

     specifying support for the original set of values be added to a

     compliance statement when an enumerated INTEGER object or a BITS

     object referenced by the compliance statement has enumerations or

     named bits added, assuming that no such clause is already present

     and that the effective MIN-ACCESS value is read-write or read-

     create.  This is necessary in order to avoid a silent change to the

     meaning of the compliance statement.  MIB module authors and

     reviewers SHOULD watch for this to ensure that such OBJECT clauses

     are added when needed.  Note that this may not always be possible

     to do, since affected compliance statements may reside in modules

     other than the one that contains the revised definition(s).



   - The status of a compliance statement is independent of the status

     of its members.  Thus, a current compliance statement MAY refer to







OPS Area                    Expires June 2005                  [Page 30]



Internet-Draft        Guidelines for MIB Documents          January 2005





     deprecated object groups or notification groups.  This may be

     desirable in certain cases, e.g., a set of widely-deployed object

     or notification groups may be deprecated when they are replaced by

     a more up-to-date set of definitions, but compliance statements

     that refer to them may remain current in order to encourage

     continued implementation of the deprecated groups.



   RFC 2580 Section 7.3 specifies rules that apply to revisions of

   capabilities statements.  The following guideline corrects an

   omission from these rules:



   - RFC 2580 should (but does not) recommend that VARIATION clauses

     specifying support for the original set of values be added to a

     capabilities statement when enumerated INTEGER objects or BITS

     objects referenced by the capabilities statement have enumerations

     added, assuming that no such clauses are already present.  This is

     necessary in order to avoid a silent change to the meaning of the

     capabilities statement.



   In certain exceptional situations the cost of strictly following the

   SMIv2 rules governing MIB modules revisions may exceed the benefit.

   In such cases the rules can be waived, but when that is done both the

   change and the justification for it MUST be thoroughly documented.

   One example is provided by Section 3.1.5 of RFC 2863, which documents

   the semantic change that was made to ifIndex in the transition from

   MIB-II [RFC1213] to the IF-MIB [RFC2863] and provides a detailed

   justification for that change.  Another example is provided by the

   REVISION clause of the SONET-MIB [RFC2558] that documents raising the

   MAX-ACCESS of several objects to read-write while adding MIN-ACCESS

   of read-only for compatibility with the previous version [RFC1595].



   Authors and reviewers may find it helpful to use tools that can list

   the differences between two revisions of a MIB module.  Please see

   http://www.ops.ietf.org/mib-review-tools.html for more information.



5.  Acknowledgments



   Most of the material on usage of data types was based on input

   provided by Bert Wijnen with assistance from Keith McCloghrie, David

   T. Perkins, and Juergen Schoenwaelder.  Much of the other material on

   SMIv2 usage was taken from an unpublished guide for MIB authors and

   reviewers by Juergen Schoenwaelder.  Some of the recommendations in

   these guidelines are based on material drawn from the on-line SMIv2

   errata list at http://www.ibr.cs.tu-bs.de/ietf/smi-errata/.  Thanks

   to Frank Strauss and Juergen Schoenwaelder for maintaining that list

   and to the contributors who supplied the material for that list.

   Finally, thanks are due to the following individuals whose comments

   on earlier versions of this memo contained many valuable suggestions







OPS Area                    Expires June 2005                  [Page 31]



Internet-Draft        Guidelines for MIB Documents          January 2005





   for additions, clarifications, and corrections:  Andy Bierman, Bob

   Braden, Michelle Cotton, Joseph Dinakaran, David Harrington, Harrie

   Hazewinkel, Michael Kirkham, Keith McCloghrie, David T. Perkins,

   Randy Presuhn, Dan Romascanu, Juergen Schoenwaelder, Frank Strauss,

   Dave Thaler, and Bert Wijnen.



6.  Security Considerations



   Implementation and deployment of a MIB module in a system may result

   in security risks that would not otherwise exist.  It is important

   for authors and reviewers of documents that define MIB modules to

   ensure that those documents fully comply with the guidelines in

   http://www.ops.ietf.org/mib-security.html so that all such risks are

   adequately disclosed.



7.  IANA Considerations



   This document affects the IANA to the extent that it describes what

   is required to be present in the IANA Considerations Section of a MIB

   document, but it does not require that the IANA update any existing

   registry or create any new registry.



Appendix A:  MIB Review Checklist



   The purpose of a MIB review is to review the MIB module both for

   technical correctness and for adherence to IETF documentation

   requirements.  The following checklist may be helpful when reviewing

   a draft document:



   1.) I-D Boilerplate -- verify that the draft contains the required

   Internet-Draft boilerplate (see http://www.ietf.org/ietf/1id-

   guidelines.txt), including the appropriate statement to permit

   publication as an RFC, and that I-D boilerplate does not contain

   references or section numbers.



   2.) Abstract -- verify that the abstract does not contain references,

   that it does not have a section number, and that its content follows

   the guidelines in [RFC2223bis].



   3.) MIB Boilerplate -- verify that the draft contains the latest

   approved SNMP Network Management Framework boilerplate from the OPS

   area web site (http://www.ops.ietf.org/mib-boilerplate.html).



   4.) Security Considerations Section -- verify that the draft uses the

   latest approved template from the OPS area web site

   (http://www.ops.ietf.org/mib-security.html) and that the guidelines

   therein have been followed.









OPS Area                    Expires June 2005                  [Page 32]



Internet-Draft        Guidelines for MIB Documents          January 2005





   5.) IANA Considerations Section -- this section must always be

   present.  If the draft requires no action from the IANA, ensure that

   this is explicitly noted.  If the draft requires OID values to be

   assigned, ensure that the IANA Considerations section contains the

   information specified in Section 3.5 of these guidelines.  If the

   draft contains the initial version of an IANA-maintained module,

   verify that the MODULE-IDENTITY invocation contains maintenance

   instructions that comply with the requirements in RFC 2434.  In the

   latter case the IANA Considerations section that will appear in the

   RFC MUST contain a pointer to the actual IANA-maintained module.



   6.) References -- verify that the references are properly divided

   between normative and informative references, that RFC 2119 is

   included as a normative reference if the terminology defined therein

   is used in the document, that all references required by the

   boilerplate are present, that all MIB modules containing imported

   items are cited as normative references, and that all citations point

   to the most current RFCs unless there is a valid reason to do

   otherwise (for example, it is OK to include an informative reference

   to a previous version of a specification to help explain a feature

   included for backward compatibility).



   7.) Copyright Notices -- verify that the draft contains an

   abbreviated copyright notice in the DESCRIPTION clause of each

   MODULE-IDENTITY invocation and that it contains the full copyright

   notice and disclaimer specified in Sections 5.4 and 5.5 of RFC 3907

   at the end of the document.  Make sure that the correct year is used

   in all copyright dates.



   8.) IPR Notice -- if the draft does not contains a verbatim copy of

   the IPR notice specified in Section 5 of RFC 3908, recommend that the

   IPR notice be included.



   9.) Other issues -- check for any issues mentioned in

   http://www.ietf.org/ID-Checklist.html that are not covered elsewhere.



   10.) Technical content -- review the actual technical content for

   compliance with the guidelines in this document.  The use of a MIB

   compiler is recommended when checking for syntax errors;  see

   http://www.ops.ietf.org/mib-review-tools.html for more information.

   Checking for correct syntax, however, is only part of the job.  It is

   just as important to actually read the MIB document from the point of

   view of a potential implementor.  It is particularly important to

   check that DESCRIPTION clauses are sufficiently clear and unambiguous

   to allow interoperable implementations to be created.













OPS Area                    Expires June 2005                  [Page 33]



Internet-Draft        Guidelines for MIB Documents          January 2005





Appendix B:  Commonly Used Textual Conventions



   The following TCs are defined in SNMPv2-TC [RFC2579]:



   DisplayString               OCTET STRING (SIZE (0..255))

   PhysAddress                 OCTET STRING

   MacAddress                  OCTET STRING (SIZE (6))

   TruthValue                  enumerated INTEGER

   TestAndIncr                 INTEGER (0..2147483647)

   AutonomousType              OBJECT IDENTIFIER

   VariablePointer             OBJECT IDENTIFIER

   RowPointer                  OBJECT IDENTIFIER

   RowStatus                   enumerated INTEGER

   TimeStamp                   TimeTicks

   TimeInterval                INTEGER (0..2147483647)

   DateAndTime                 OCTET STRING (SIZE (8 | 11))

   StorageType                 enumerated INTEGER

   TDomain                     OBJECT IDENTIFIER

   TAddress                    OCTET STRING (SIZE (1..255))



   Note 1.  InstancePointer is obsolete and MUST NOT be used.



   Note 2.  DisplayString does not support internationalized text.

            It MUST NOT be used for objects that are required to

            hold internationalized text (which is always the case

            if the object is intended for use by humans [RFC2277]).

            Designers SHOULD consider using SnmpAdminString,

            Utf8String, or LongUtf8String for such objects.





   The following TC is defined in SNMP-FRAMEWORK-MIB [RFC3411]:



   SnmpAdminString             OCTET STRING (SIZE (0..255))





   The following TCs are defined in SYSAPPL-MIB [RFC2287]:



   Utf8String                  OCTET STRING (SIZE (0..255))

   LongUtf8String              OCTET STRING (SIZE (0..1024))

























OPS Area                    Expires June 2005                  [Page 34]



Internet-Draft        Guidelines for MIB Documents          January 2005





   The following TCs are defined in INET-ADDRESS-MIB [RFC3291bis]:



   InetAddressType             enumerated INTEGER

   InetAddress                 OCTET STRING (SIZE (0..255))

   InetAddressPrefixLength     Unsigned32 (0..2040)

   InetPortNumber              Unsigned32 (0..65535))

   InetAutonomousSystemNumber  Unsigned32

   InetScopeType               enumerated INTEGER

   InetZoneIndex               Unsigned32

   InetVersion                 enumerated INTEGER





   The following TCs are defined in TRANSPORT-ADDRESS-MIB [RFC3419]:



   TransportDomain             OBJECT IDENTIFIER

   TransportAddressType        enumerated INTEGER

   TransportAddress            OCTET STRING (SIZE (0..255))





   The following TC is defined in RMON2-MIB [RFC2021]:



   ZeroBasedCounter32          Gauge32





   The following TCs are defined in HCNUM-TC [RFC2856]:



   ZeroBasedCounter64          Counter64

   CounterBasedGauge64         Counter64





   The following TCs are defined in IF-MIB [RFC2863]:



   InterfaceIndex              Integer32 (1..2147483647)

   InterfaceIndexOrZero        Integer32 (0..2147483647)





   The following TCs are defined in ENTITY-MIB [RFC2737bis]:



   PhysicalIndex               Integer32 (1..2147483647)

   PhysicalIndexOrZero         Integer32 (0..2147483647)





   The following TCs are defined in PerfHist-TC-MIB [RFC3593]:



   PerfCurrentCount            Gauge32

   PerfIntervalCount           Gauge32

   PerfTotalCount              Gauge32









OPS Area                    Expires June 2005                  [Page 35]



Internet-Draft        Guidelines for MIB Documents          January 2005





   The following TCs are defined in HC-PerfHist-TC-MIB [RFC3705]:



   HCPerfValidIntervals        Integer32 (0..96)

   HCPerfInvalidIntervals      Integer32 (0..96)

   HCPerfTimeElapsed           Integer32 (0..86399)

   HCPerfIntervalThreshold     Unsigned32 (0..900)

   HCPerfCurrentCount          Counter64

   HCPerfIntervalCount         Counter64

   HCPerfTotalCount            Counter64



Appendix C:  Suggested Naming Conventions



   Authors and reviewers of IETF MIB modules have often found the

   following naming conventions to be helpful in the past, and authors

   of new IETF MIB modules are urged to consider following them.



   - The module name should be of the form XXX-MIB (or XXX-TC-MIB for a

     module with TCs only), where XXX is a unique prefix (usually all

     caps with hyphens for separators) that is not used by any existing

     module.  For example, the module for managing optical interfaces

     [RFC3591] uses the prefix OPT-IF and has module name OPT-IF-MIB.



   - The descriptor associated with the MODULE-IDENTITY invocation

     should be of the form xxxMIB, xxxMib, or xxxMibModule, where xxx is

     a mixed-case version of XXX starting with a lower-case letter and

     without any hyphens.  For example, the OPT-IF-MIB uses the prefix

     optIf, and the descriptor associated with its MODULE-IDENTITY

     invocation is optIfMibModule.



   - Other descriptors within the MIB module should start with the same

     prefix xxx.  OPT-IF-MIB uses the prefix optIf for all descriptors.



   - Names of TCs that are specific to the MIB module and names of

     SEQUENCE types that are used in conceptual table definitions should

     start with a prefix Xxx that is the same as xxx but with the

     initial letter changed to upper case.  OPT-IF-MIB uses the prefix

     OptIf on the names of TCs and SEQUENCE types.



   - The descriptor associated with a conceptual table should be of the

     form xxxZzzTable;  the descriptor associated with the corresponding

     conceptual row should be of the form xxxZzzEntry;  the name of the

     associated SEQUENCE type should be of the form XxxZzzEntry;  and

     the descriptors associated with the subordinate columnar objects

     should be of the form xxxZzzSomeotherName.  An example from the

     OPT-IF-MIB is the OTMn table.  The descriptor of the table object

     is optIfOTMnTable, the descriptor of the row object is

     optIfOTMnEntry, the name of the associated SEQUENCE type is

     OptIfOTMnEntry, and the descriptors of the columnar objects are







OPS Area                    Expires June 2005                  [Page 36]



Internet-Draft        Guidelines for MIB Documents          January 2005





     optIfOTMnOrder, optIfOTMnReduced, optIfOTMnBitRates,

     optIfOTMnInterfaceType, optIfOTMnTcmMax, and optIfOTMnOpticalReach.



   - When abbreviations are used, then they should be used consistently.

     Inconsistent usage such as



       xxxYyyDestAddr

       xxxZzzDstAddr



     should be avoided.



Appendix D:  Suggested OID Layout



   As noted in RFC 2578 Section 5.6, it is common practice to use the

   value of the MODULE-IDENTITY invocation as a subtree under which

   other OBJECT IDENTIFIER values assigned within the module are

   defined.  That, of course, leaves open the question of how OIDs are

   assigned within that subtree.  One assignment scheme that has gained

   favor -- and which is RECOMMENDED unless there is a specific reason

   not use it -- is to have three separate branches immediately below

   the MODULE-IDENTITY value dedicated (respectively) to notification

   definitions, object definitions, and conformance definitions, and to

   further subdivide the conformance branch into separate sub-branches

   for compliance statements and object/notification groups.  This

   structure is illustrated below, with naming conventions following

   those outlined in Appendix C.  The numbers in parentheses are the

   sub-identifiers assigned to the branches.



         xxxMIB

         |

         +-- xxxNotifications(0)

         +-- xxxObjects(1)

         +-- xxxConformance(2)

             |

             +-- xxxCompliances(1)

             +-- xxxGroups(2)



   When using this scheme notification definition values are assigned

   immediately below the xxxNotifications node.  This ensures that each

   OID assigned to a notification definition has a next-to-last sub-

   identifier of zero, which is REQUIRED by Section 4.7 above.  The

   other sub-branches may have additional sub-structure, but none beyond

   that specified in Section 4.6.5 above is actually required.



   One example of a MIB module whose OID assignments follow this scheme

   is the POWER-ETHERNET-MIB [RFC3621].











OPS Area                    Expires June 2005                  [Page 37]



Internet-Draft        Guidelines for MIB Documents          January 2005





Normative References



[RFC2578]   McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J.,

            Rose, M. and S. Waldbusser, "Structure of Management

            Information Version 2 (SMIv2)", STD 58, RFC 2578, April

            1999.



[RFC2579]   McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J.,

            Rose, M.  and S. Waldbusser, "Textual Conventions for

            SMIv2", STD 58, RFC 2579, April 1999.



[RFC2580]   McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J.,

            Rose, M. and S. Waldbusser, "Conformance Statements for

            SMIv2", STD 58, RFC 2580, April 1999.



[RFC2119]   Bradner, S., "Key words for use in RFCs to Indicate

            Requirements Levels", BCP 14, RFC 2119, March 1997.



[RFC2223bis]

            Reynolds, J., and R. Braden, "Instructions to Request for

            Comments (RFC) Authors", work in progress (currently <draft-

            rfc-editor-rfc2223bis-08.txt>).



[RFC2277]   Alvestrand, H., "IETF Policy on Character Sets and

            Languages", BCP 18, RFC 2277, January 1998.



[RFC2434]   Alvestrand, H., "Guidelines for Writing an IANA

            Considerations Section in RFCs", BCP 26, RFC 2434, October

            1998.



[RFC2863]   McCloghrie, K. and F. Kastenholz, "The Interfaces Group

            MIB", RFC 2863, June 2000.



[RFC2864]   McCloghrie, K. and G. Hanson, "The Inverted Stack Table

            Extension to the Interfaces Group MIB", RFC 2864, June 2000.



[RFC3907]   Bradner, S., "IETF Rights in Contributions", BCP 78, RFC

            3907, January 2005.



[RFC3908]   Bradner, S., "Intellectual Property Rights in IETF

            Technology", BCP 79, RFC 3908, January 2005.



[RFC3593]   Tesink, K., "Textual Conventions for MIB Modules Using

            Performance History Based on 15 Minute Intervals", RFC 3593,

            September 2003.



[RFC3705]   Ray, B. and R. Abbi, "High Capacity Textual Conventions for

            MIB Modules Using Performance History Based on 15 Minute







OPS Area                    Expires June 2005                  [Page 38]



Internet-Draft        Guidelines for MIB Documents          January 2005





            Intervals", RFC 3705, February 2004.



[RFC2021]   Waldbusser, S., "Remote Network Monitoring Management

            Information Base Version 2 using SMIv2", RFC 2021, January

            1997.



[RFC2856]   Bierman, A., McCloghrie, K. and R. Presuhn, "Textual

            Conventions for Additional High Capacity Data Types", RFC

            2856, June 2000.



[RFC3291bis]

            Daniele, M., Haberman, B., Routhier, S. and J.

            Schoenwaelder, "Textual Conventions for Internet Network

            Addresses", work in progress (currently draft-ietf-ops-

            rfc3291bis-06.txt).



[RFC2287]   Krupczak, C. and J. Saperia, "Definitions of System-Level

            Managed Objects for Applications", RFC 2287, February 1998.



[RFC3411]   Harrington, D., Presuhn, R. and B. Wijnen, "An Architecture

            for Describing Simple Network Management Protocol (SNMP)

            Management Frameworks", STD 62, RFC 3411, December 2002.



[RFC3416]   Presuhn, R., Case, J., McCloghrie, K., Rose, M. and S.

            Waldbusser, "Protocol Operations for the Simple Network

            Management Protocol (SNMP)", STD 62, RFC 3416, December

            2002.



[RFC3418]   Presuhn, R., Case, J., McCloghrie, K., Rose, M. and S.

            Waldbusser, "Management Information Base (MIB) for the

            Simple Network Management Protocol (SNMP)", STD 62, RFC

            3418, December 2002.



[RFC3419]   M. Daniele, M. and J. Schoenwaelder, "Textual Conventions

            for Transport Addresses", RFC 3419, December 2002.



[RFC2737bis]

            McCloghrie, K. and A. Bierman, "Entity MIB (Version 3)",

            work in progress (currently draft-ietf-entmib-v3-05.txt).

























OPS Area                    Expires June 2005                  [Page 39]



Internet-Draft        Guidelines for MIB Documents          January 2005





Informative References



[RFC3410]   Case, J., Mundy, R., Partain, D. and B. Stewart,

            "Introduction and Applicability Statements for Internet-

            Standard Management Framework", RFC 3410, December 2002.



[RFC1155]   Rose, M. and K. McCloghrie, "Structure and Identification of

            Management Information for TCP/IP-based Internets", STD 16,

            RFC 1155, May 1990.



[RFC1212]   Rose, M. and K. McCloghrie, "Concise MIB Definitions", STD

            16, RFC 1212, March 1991.



[RFC1215]   Rose, M., "A Convention for Defining Traps for use with the

            SNMP", RFC 1215, March 1991.



[RFC2932]   McCloghrie, K., Farinacci, D., and D. Thaler, "IPv4

            Multicast Routing MIB", RFC 2932, October 2000.



[RFC1573]   McCloghrie, K. and F. Kastenholz, "Evolution of the

            Interfaces Group of MIB-II", RFC 1573, January 1994.



[RFC3584]   Frye, R., Levi, D., Routhier, S. and B. Wijnen, "Coexistence

            between Version 1, Version 2, and Version 3 of the Internet-

            standard Network Management Framework", BCP 74, RFC 3584,

            August 2003.



[RFC2108]   de Graaf, K., Romascanu, D., McMaster, D. and K. McCloghrie,

            "Definitions of Managed Objects for IEEE 802.3 Repeater

            Devices using SMIv2", RFC 2108, February 1997.



[RFC3289]   Baker, F., Chan, K. and A. Smith, "Management Information

            Base for the Differentiated Services Architecture", RFC

            3289, May 2002.



[RFC1213]   McCloghrie, K. and M. Rose, "Management Information Base for

            Network Management of TCP/IP-based internets - MIB-II", STD

            17, RFC 1213, March 1991.



[RFC1595]   Brown, T. and K. Tesink, "Definitions of Managed Objects for

            the SONET/SDH Interface Type", RFC 1595, March 1994.



[RFC2558]   Tesink, K., "Definitions of Managed Objects for the

            SONET/SDH Interface Type", RFC 2558, March 1999.



[RFC3591]   Lam, H-K., Stewart, M. and A. Huynh, "Definitions of Managed

            Objects for the Optical Interface Type", RFC 3591, September

            2003.







OPS Area                    Expires June 2005                  [Page 40]



Internet-Draft        Guidelines for MIB Documents          January 2005





[RFC3621]   Berger, A. and D. Romascanu, "Power Ethernet MIB", RFC 3621,

            December 2003.



Editor's Address



   C. M. Heard

   158 South Madison Ave. #207

   Pasadena, CA 91101-2569

   USA



   Phone: +1 626 795 5311

   EMail: heard@pobox.com



Full Copyright Statement



   Copyright (C) The Internet Society (2005).



   This document is subject to the rights, licenses and restrictions

   contained in BCP 78, and except as set forth therein, the authors

   retain all their rights.



   This document and the information contained herein are provided on an

   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS

   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, AND THE INTERNET

   ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,

   INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE

   INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED

   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.



Intellectual Property



   The IETF takes no position regarding the validity or scope of any

   Intellectual Property Rights or other rights that might be claimed to

   pertain to the implementation or use of the technology described in

   this document or the extent to which any license under such rights

   might or might not be available;  nor does it represent that it has

   made any independent effort to identify any such rights.  Information

   on the procedures with respect to rights in RFC documents can be

   found in BCP 78 and BCP 79.



   Copies of IPR disclosures made to the IETF Secretariat and any

   assurances of licenses to be made available, or the result of an

   attempt made to obtain a general license or permission for the use of

   such proprietary rights by implementors or users of this

   specification can be obtained from the IETF on-line IPR repository at

   http://www.ietf.org/ipr.











OPS Area                    Expires June 2005                  [Page 41]



Internet-Draft        Guidelines for MIB Documents          January 2005





   The IETF invites any interested party to bring to its attention any

   copyrights, patents or patent applications, or other proprietary

   rights that may cover technology that may be required to implement

   this standard.  Please address the information to the IETF at ietf-

   ipr@ietf.org.



Acknowledgement



   Funding for the RFC Editor function is currently provided by the

   Internet Society.



















































































OPS Area                    Expires June 2005                  [Page 42]



Internet-Draft        Guidelines for MIB Documents          January 2005





Revision History



   NOTE TO RFC Editor:  this section is to be removed prior to

   publication as an RFC.



   The following changes were made to <draft-ietf-ops-mib-review-

   guidelines-00.txt> to produce <draft-ietf-ops-mib-review-

   guidelines-01.txt>:



      1.)  The Abstract, Section 1, and Section 3 were revised to

      clarify that the guidelines are targeted specifically at IETF

      standards-track documents containing MIB modules but may be used

      as a basis for reviews of other documents containing MIB modules.



      2.)  A note was added to Section 1 pointing out that some of the

      guidelines do not apply to MIB modules that have been converted to

      SMIv2 from SMIv1.



      3.)  A note was added to Section 2 clarifying that the term

      "standard", when it appears in quotes, is being used in the same

      way as in RFCs 2578/2579/2580.



      4.)  A typo (s/MIB modules/MIB module(s)/) was corrected in

      Section 3.3.



      5.)  The second paragraph of Section 3.5 was revised to include a

      requirement for a normative reference to the on-line version of an

      IANA-maintained MIB module that appears in an IMPORTS statement.



      6.)  Additional instructions to authors regarding the preparation

      of a Security Considerations section were incorporated into

      Section 3.6.



      7.)  A typo (s/defined/defines/) was corrected in the second

      paragraph of Section 3.7.



      8.)  In accordance with a recent IESG decision, the third

      paragraph of Section 3.7 was revised to state that the accepted

      procedure for the initial version of an IANA-maintained MIB module

      is to publish it in a non-normative section of the initial issue

      of the document that defines the corresponding name space, as was

      done in RFC 1573 for the IANAifType-MIB.



      9.)  An Editor's Note was added to Section 3.8 to alert authors

      and reviewers that a copyright notice will be required in the

      MODULE-IDENTITY invocation of IANA-maintained MIB modules with the

      exact form still to be determined.









OPS Area                    Expires June 2005                  [Page 43]



Internet-Draft        Guidelines for MIB Documents          January 2005





      10.) A pointer to the suggested naming conventions in Appendix E

      was added to Section 4.1.



      11.) In Section 4.2 the phrase "descriptors" was changed to

      "descriptors and TC names" to align with the usage in the SMIv2

      documents, and a pointer to the suggested naming conventions in

      Appendix E was added.



      12.) An editorial correction (s/"standard"/standards-track) was

      made to Section 4.4.



      13.) A typo (s/groups's/group's) was corrected in the first bullet

      in Section 4.5.



      14.) The third bullet in Section 4.5 was revised to clarify that

      IETF standards-track MIB modules are to be registered under the

      mgmt subtree and to say (based on experience reported by the RMON

      MIB working group chair) that IETF working groups SHOULD NOT

      assign top-level OIDs from subtrees delegated to them by IANA.



      15.) An editorial change (s/appropriate/acceptable/) was made to

      the paragraph of Section 4.6.1.1 that deals with Gauge32 index

      objects.



      16.) Section 4.6.1.2 was revised to state that (i) the DESCRIPTION

      clauses of Counter32/Counter64 objects MUST specify epochs of

      discontinuities (other than agent re-initialization) with enough

      precision to allow a manager to determine if data is valid and

      (ii) discontinuity indicators are the RECOMMENDED way to do this.



      17.) A note was added to Section 4.6.1.2 stating that the

      Counter64 type MUST be used for objects that would roll over in

      less than one hour if Counter32 was used instead and that the

      existing rule allowing Counter64 only under those circumstances is

      obsolete and should no longer be enforced.



      18.) The Utf8String and LongUtf8String TCs were added to the list

      of specialized OCTET STRING types mentioned in Section 4.6.1.4.



      19.) A typo (s/RowPointerTCs/RowPointer TCs/) was corrected in

      Section 4.6.1.5.



      20.) A wording change (s/MUST be contiguous/SHOULD be contiguous/)

      was made to Section 4.6.1.6 to make it agree with RFC 2578.



      21.) A note was added to Section 4.6.1.10 stating that when an

      object definition uses an imported TC that could later be extended

      (as is the case for some enumerated INTEGER and BITS TCs) then the







OPS Area                    Expires June 2005                  [Page 44]



Internet-Draft        Guidelines for MIB Documents          January 2005





      value set that must be supported SHOULD be documented if the

      object is writeable or is an index of a read-create table.



      22.) A typo was corrected in the nroff source that caused the

      second line in the second paragraph of Section 4.6.2 to be omitted

      from the formatted text.



      23.) A note was added to Section 4.6.2 stating that the

      DESCRIPTION clause of a read-write object SHOULD document what

      happens to the value after a reboot unless the object is a column

      in a read-create table with well-defined persistence properties.



      24.) A bullet was added to the first list in Section 4.6.3 stating

      that IMPLIED SHOULD NOT be used on index objects that might appear

      in expansion tables and providing some reasons why using IMPLIED

      often does not have the expected benefits.



      25.) An editorial change (s/row object/row object (table entry)/)

      was made to the second bullet of the second list in Section 4.6.3.



      26.) A note was added to Section 4.6.4 explicitly stating that

      object definitions SHOULD NOT be registered beneath conformance

      group definitions, MODULE-COMPLIANCE definitions, or AGENT-

      CAPABILITIES definitions (or vice-versa).



      27.) A typo (s/128 OID limitation/128 sub-identifier) was

      corrected in the first paragraph of Section 4.6.5.



      28.) The second paragraph of Section 4.6.5 was revised to state

      that size limitations on index variables that need to be observed

      by management software SHOULD be spelled out.



      29.) The phrase "second technique" was changed to "fixed time

      interval technique" in the last sentence of the of the paragraph

      of Section 4.7 that discusses notification throttling.



      30.) The phrase "in situations where it is appropriate" was

      changed to "when it is applicable" at the end of the bullet in

      Section 4.8 that discusses when to write full compliance and read-

      only compliance statements.



      31.) A paragraph was added to Section 4.8 (just before the

      endnote) stating that prerequisite modules and in some cases

      specific groups from such modules SHOULD be mentioned in the

      compliance statements.



      32.) Two typos (s/implemantations/implementations/ and

      s/descriptions/descriptors/) were corrected in the fourth







OPS Area                    Expires June 2005                  [Page 45]



Internet-Draft        Guidelines for MIB Documents          January 2005





      paragraph of Section 4.9.



      33.) A typo (s/boilerplace/boilerplate/) was fixed in checklist

      item #5 of Appendix A.



      34.) An item was added to the checklist in Appendix A requiring

      reviewers to check for things in http://www.ietf.org/ID-nits.html

      that are not covered elsewhere.  This became item #10;  the

      existing technical content review became item #11.



      35.) The default smilint switches in Appendix B were changed from

      "-m -s -l 9 -i namelength-32" to "-m -s -l 6 -i namelength-32" at

      the request of the authors of the program (currently there are no

      level 7, 8, or 9 diagnostics, and it is desired to reserve those

      levels for things that are of no concern in an IETF MIB review).



      36.) A note was added to Appendix D stating that the DisplayString

      TC is no longer permitted for objects that are intended for human

      consumption, and the Utf8String and LongUtf8String TCs from

      SYSAPPL-MIB were added to the list of standard TCs.



      37.) Suggested naming conventions were documented in Appendix E.



      38.) Normative references to RFCs 2277 and 2287 were added.



      39.) Informative references to RFC 1573 and OPT-IF-MIB were added.



      40.) The "Acknowledgements" section was updated.



   The following changes were made to <draft-ietf-ops-mib-review-

   guidelines-01.txt> to produce <draft-ietf-ops-mib-review-

   guidelines-02.txt>:



      1.)  The following changes were made to avoid the implication that

      reviews are required only for OPS Area MIB documents:

      Section 1:    s/OPS area review/expert review/

      Section 4.2:  s/OPS Area MIB reviewers/MIB reviewers/

      Section 4.8:  s/OPS Area MIB reviewers/MIB reviewers/



      2.)  Imperatives from RFC 2119 were capitalized in the following

      places:  Section 3.2 (last paragraph), Section 3.8 (first

      paragraph), Section 4.9 (first bullet in first paragraph), and

      Appendix A (checklist item #7).



      3.)  The EDITOR'S NOTE in Section 3.8 was replaced with text

      describing the actual form of the copyright notice that is now

      required for IANA-maintained MIB modules.









OPS Area                    Expires June 2005                  [Page 46]



Internet-Draft        Guidelines for MIB Documents          January 2005





      4.)  In Sections 4.1 & 4.2:  s/Appendix E/Appendix C/ (appendices

      were renumbered owing to the elimination of -01 appendices B & C).



      5.)  Two typographical errors (s/the the/the/,

      s/ifCounterDisconuityTime/ifCounterDiscontinuityTime/) were

      corrected in the first bullet of Section 4.6.1.2.



      6.)  In Section 4.6.1.10 a pointer was added to the "Common TCs"

      page (http://www.ops.ietf.org/mib-common-tcs.html) on the OPS Area

      web site.



      7.)  A "DISPLAY-HINT Clause" section was added;  it is Section

      4.6.3 in the -02 draft.  The following section numbers have

      changed as a result of this addition:



      -01 section number      -02 section number

            4.6.3                   4.6.4

            4.6.4                   4.6.5

            4.6.5                   4.6.6



      8.)  A typographical error (s/are can be/can be/) was corrected in

      Section 4.6.4 (formerly Section 4.6.3).



      9.)  In Sections 4.6.5 (formerly 4.6.4) and 4.7 a pointer to the

      new "Suggested OID Layout" appendix was added (it is Appendix D in

      the -02 draft, owing to the elimination of -01 appendices B & C).



      10.) In Section 4.7 the notification throttling text was

      wordsmithed.



      11.) A typographical error (s/following contains the/following/)

      was corrected in the third paragraph of Section 4.8.



      12.) The text of Section 4.9, third paragraph, first bullet and

      fifth paragraph, first bullet was revised to allow changes to BITS

      and enum labels in order to correct typographical errors.



      13.) The text of Section 4.9, third paragraph, second bullet was

      revised to allow redundant range or size constraints to be

      removed.



      14.) In the last paragraph of Section 4.9 the references to

      smidiff and -01 Appendix B were replaced by a pointer to the "MIB

      Review Tools" page (http://www.ops.ietf.org/mib-review-tools.html)

      on the OPS Area web site.



      15.) The text of Appendix A, checklist item #7 was corrected to

      reflect actual IESG policy on publication of initial versions of







OPS Area                    Expires June 2005                  [Page 47]



Internet-Draft        Guidelines for MIB Documents          January 2005





      IANA-maintained MIB modules in RFCs.  It is now consistent with

      Section 3.7.



      16.) In Appendix A draft -01 checklist items #9, #10, and #11 were

      consolidated into -02 checklist items #9 (which is equivalent to

      -01 checklist item #10) and #10 (which is equivalent to the union

      of -01 items #9 and #11).  The new item #10 consolidates the MIB

      compilation step into the technical review, and replaces mention

      of specific MIB compilation tools with a pointer to the "MIB

      Review Tools" page (http://www.ops.ietf.org/mib-review-tools.html)

      on the OPS Area web site.



      17.) Draft -01 appendices B and C have been eliminated.  They have

      been superseded by the "MIB Review Tools" page on the OPS Area web

      site (http://www.ops.ietf.org/mib-review-tools.html).  The

      following appendix names have changed as a result:



      -01 appendix name       -02 appendix name

          Appendix D              Appendix B

          Appendix E              Appendix C



      18.) A new "Suggested OID Layout" appendix was added.  It is

      Appendix D in the -02 draft, owing to the elimination of -01

      appendices B & C.



   The following changes were made to <draft-ietf-ops-mib-review-

   guidelines-02.txt> to produce <draft-ietf-ops-mib-review-

   guidelines-03.txt>:



      1.)  The title was changed to "Guidelines for Authors and

      Reviewers of MIB Documents".



      2.)  The I-D boilerplate on the front page was updated to conform

      to the requirements set forth in RFCs 3667 and 3668.



      3.)  Comments were redirected to <ietfmibs@ops.ietf.org>.



      4.)  All occurrences of http://www.ietf.org/ID-nits.html were

      changed to http://www.ietf.org/ID-Checklist.html.



      5.)  Section 3.2 was revised to require mention in the overview

      section when definitions are imported from other modules apart

      from the modules defined in the SMIv2 documents.



      6.)  The instructions for IPR notices in Section 3.4 (and also

      those in Appendix A) now refer to RFC 3668 instead of RFC 2026.











OPS Area                    Expires June 2005                  [Page 48]



Internet-Draft        Guidelines for MIB Documents          January 2005





      7.)  In Section 3.5 the [RFC2223bis] section number reference was

      updated to match <draft-rfc-editor-rfc2223bis-07.txt>, and text

      was added (a) to point out that RFC Editor policy prohibits

      uncited references and (b) to require citations in the narrative

      part of documents other than the SMIv2 RFCs that contain imported

      definitions.



      8.)  In Section 3.5 the pointer to [RFC2223bis] was removed and

      text was added to remind authors to consider privacy implications.



      9.)  The IANA Considerations instructions in Section 3.7 were

      changed to comply with the new IESG policy requiring an IANA

      Consideridations section in all Internet-Drafts.  Subsection

      headings were added to cover the three different cases.  The

      pointer to  [RFC2223bis] was removed.



      10.) The instructions for copyright notices in Section 3.8 were

      changed to refer to RFC 3667 instead of RFC 2026, and the pointer

      to [RFC2223bis] was removed.



      11.) A minor wording change was made to Section 4.1.



      12.) In Section 4.5 text was added admonishing authors NOT to use

      SMI numbers that have not been properly allocated by the IANA.



      13.) Sections 4.6.1.1 and 4.6.1.6 now mention that DEFVALS for

      enumerated INTEGER and BITS objects may, according to the SMI, be

      specified either by label or by value, but since some tools do not

      accept the numeric form, the label form is preferred.



      14.) Section 4.9 was clarified to state that adding an OBJECT

      clause specifying support for the original set of values of an

      enumerated INTEGER or BITS object is needed only when write access

      is required by the compliance statement.



      15.) Several TCs have been added to Appendix B.  These include the

      TCs that were recently added to the INET-ADDRESS-MIB, the

      PhysicalIndex and PhysicalIndexOrZero TCs from the recent update

      of the ENTITY-MIB, and all of the TCs from the HC-PerfHist-TC-MIB.



      16.) The reference to RFC 2026 was replaced by references to RFCs

      3667 and 3668, all references to I-Ds that have since been

      published have been changed to point to the RFCs, and the

      references to RFC 2737 and RFC 3291 were replaced by references to

      the I-Ds that update those documents.  Note that RFC2737bis and

      RFC3291bis are both normative references since Appendix B lists

      some TCs from those drafts that are available nowhere else.









OPS Area                    Expires June 2005                  [Page 49]



Internet-Draft        Guidelines for MIB Documents          January 2005





      17.) An IANA Considerations section (to be removed upon

      publication) was added, and the Open Issues section was removed.



   The following changes were made to <draft-ietf-ops-mib-review-

   guidelines-03.txt> to produce <draft-ietf-ops-mib-review-

   guidelines-04.txt>:



      1.)  The I-D boilerplate on the front page was updated to comply

      with http://www.ietf.org/ietf/1id-guidelines.txt.



      2.)  The introductory part of Section 3 has been wordsmithed to

      align it with http://www.ietf.org/ietf/1id-guidelines.txt,

      http://www.ietf.org/ID-Checklist.html, and RFC2223bis, and the

      sub-sections have been re-ordered to match the order recommended

      by RFC 2223bis for sections in an RFC.  As a result, the following

      section numbers have changed:



      -03 Section Number      -04 Section Number

              3.4                     3.8

              3.5                     3.6

              3.6                     3.4

              3.7                     3.5

              3.8                     3.7



      3.)  The instructions for copyright notices in Section 3.7 (and

      also those in Appendix A) refer to RFC 3907 instead of RFC 3667,

      and the wording for the abbreviated notice used in IANA-maintained

      was changed so that it agrees with RFC  3907.  In addition, the

      requirement to check for the presence of a copyright notice on the

      front page of a document has been deleted from Appendix A, since

      Internet-Drafts no longer require such a notice.



      4.)  The instructions for IPR notices in Section 3.8 (and also

      those in Appendix A) now refer to RFC 3908 instead of RFC 3668.

      In addition, these sections treat the notice as a SHOULD, since

      the IPR notice is no longer required in Internet-Drafts (although

      it is recommended)



      5.)  Text has been added to Section 4.6.1.2 to clarify that there

      is no longer a requirement to define a Counter32 counterpart for

      each Counter64 object.



      6.)  The Acknowledgments, Security Considerations, and IANA

      Considerations sections have been relocated before the appendices,

      as recommended by RFC 2223bis, and the Intellectual Property

      Section has been relocated to the end of the document, as required

      by RFC 2223bis (and in accordance with the practice in recent

      RFCs).







OPS Area                    Expires June 2005                  [Page 50]



Internet-Draft        Guidelines for MIB Documents          January 2005





      7.)  Several previously unacknowledged individuals who have

      provided helpful comments have been named in the Acknowledgments

      section.



      8.)  The IANA Considerations section is now non-null, and the

      editor's note requesting that it be removed prior to publication

      has been deleted.



      9.)  The checklist items in Appendix A have been re-ordered to

      match the order of presentation in Section 3.



      10.) Appendix B now correctly lists the SYNTAX of

      InetAddressPrefixLength as Unsigned32 (0..2040).



      11.) The references to RFCs 3667 and 3668 were replaced by

      references to RFCs 3907 and 3908, and the references to RFC

      2223bis, RFC 2737bis and RFC 3291bis were updated to point to the

      most current drafts.



      12.) Several typos and spelling errors were corrected.































































OPS Area                    Expires June 2005                  [Page 51]



Internet-Draft        Guidelines for MIB Documents          January 2005





      ************************************************************

      * NOTES TO RFC Editor (to be removed prior to publication) *

      *                                                          *

      * 1.) The normative reference [RFC2223bis] points to       *

      * a work in progress that is intended to replace RFC       *

      * 2223.  Please update that reference to point to the      *

      * forthcoming RFC that replaces RFC 2223, replace all      *

      * occurrences of "2223bis" with the number of that RFC,    *

      * and update section number references if needed.          *

      *                                                          *

      * 2.) The normative reference [RFC3291bis] points to       *

      * a work in progress that is intended to replace RFC       *

      * 3291.  Please update that reference to point to the      *

      * forthcoming RFC that replaces RFC 3291, replace all      *

      * occurrences of "3291bis" with the number of that RFC.    *

      *                                                          *

      * 3.) The normative reference [RFC2737bis] points to       *

      * a work in progress that is intended to replace RFC       *

      * 2737.  Please update that reference to point to the      *

      * forthcoming RFC that replaces RFC 2737, replace all      *

      * occurrences of "2737bis" with the number of that RFC.    *

      *                                                          *

      * 4.) The "Editor's Notes" and "Notes to RFC Editor" in    *

      * Sections 3.5, 3.7, and 4.5 are examples to authors and   *

      * are intended to appear in the final text.                *

      ************************************************************



















































OPS Area                    Expires June 2005                  [Page 52]