Re: FW: I-D ACTION:draft-ietf-ops-mib-review-guidelines-00.txt

["C. M. Heard" <heard@pobox.com>]

On Fri, 7 Feb 2003, Harrie Hazewinkel wrote:
> I read the document and have a few comments.
> '> ' indicates text from the draft itself (sorry it I cut/paste to 
> much).

Not at all, the clarity is appreciated.

>  >3.2.  Narrative Sections
>  >
>  >
>  >   If the MIB modules defined by the specification are always
>  >   implemented in conjunction with other MIB modules, then that fact
>  >   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.
> 
> Also the definition section should express this in its compliance
> statements. (There is later a lot of info for this compliance 
> statements.)

We've been discussing this in the thread entitled ``section 3.2 of
draft-ietf-ops-mib-review-guidelines-00.txt''.  I still owe you
some text.  It's coming, hopefully before the end of this week.

>  >4.5.  MODULE-IDENTITY Invocation
>  >
>  >
>  >   - 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 groups's web page.
> 
> Is this the IETF maintained web page?? If a WG has concluded the URL 
> changes.  For example,
> http://www.ietf.org/html.charters/adslmib-charter.html
> http://www.ietf.org/html.charters/OLD/applmib-charter.html
> 
> and note the extra 'OLD' in the URL.

That is true, and it's the reason why Bert has insisted on including
the mailing list information as well (mailing lists usually survive
for a while after the WG concludes).  On the other hand, mailing lists
are sometimes rehosted while the WG is still active, and in those cases
having a pointer to the charter page (which has the mailing list
information, and well as other useful stuff) can be helpful to those
seeking answers to questions.

>  >      <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.
> 
> Add extra note that it is NOT advised to use this number when a product
> of it is shipped. Although, this is not for reviewers, more for
> implementors.

If you don't mind too much, I'd rather not add that.  The document
is already too big, so I really don't want to stray off topic.

>  >4.6.1.4.  OCTET STRING
>  >
>  >   There exist a number of standard TCs that cater to some of the more
>  >   common requirements for specialized OCTET STRING types.  In
>  >   particular, ..
> 
> Maybe it is useful to mention specifically a UTF-8 octet string as
> well. Various people add this to their draft and already multiple
> exist.

You will notice that I do mention SnmpAdminString, which is the
"standard" UTF-8 replacement for DisplayString.

In separate comments, Bert Wijnen has asked me to remove mention here
of DisplayString and to point out in Appendix D that it is not to be
used in new MIB modules because it does not support i18n.  When I
put those changes into Appendix D I will state that SnmpAdminString
is the "approved" replacement because it supports UTF-8.

Will that take care of these concerns?

>  >4.6.4.  OID Values Assigned to Objects
>  >
>  >   - 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.
> 
> Do we also want to mention the SEQUENCE and the order of the SEQUENCE
> and column should be equal??  Mostly this will be picked up by MIB 
> compilers, but so are some other advises in this draft.

I don't think this is actually a requirement of RFC 2578.  Anyway, I cite
the appropriate sections of RFC 2578 in 4.6.3 and 4.6.4, and people are
expected to read the SMI documents.

As an aside, if you see some advice in this document that covers
some obvious thing that even the most crude MIB compiler will catch,
and you think it is a waste of space, then please point it out.  
The document is getting longer than it really should be, and I would
like to remove stuff that's not essential.

>  >4.7.  Notification Definitions
>  >
>  > One mechanism that has been widely used is to require
>  >   the notification generator to use throttling -- that is, to ensure
>  >   that no more than one notification is generated for each event source
>  >   in any given time interval of duration T.  The throttling period T
>  >   MAY be configurable, in which case it would be specified in a MIB
>  >   object, or it MAY be fixed, in which case it would be specified in
>  >   the notification definition.  Examples of the second technique can be
>  >   found in the SNMP-REPEATER-MIB [RFC2108] and in the ENTITY-MIB
>  >   [RFC2737].
> 
> 
> Why mentioning the first and referring to the second?? Does the
> SNMP-REPEATER-MIB not use the time interval and thus the first
> approach??

No, the SNMP-REPEATER-MIB is an example of the second approach, because
the interval is fixed (not configurable).  Each notification definition
in 2108 specifies that the throttling period must be at least five
seconds, and there is no MIB object to control it.  An example of the
first technique (using a configurable throttling interval) can be found
in <draft-ietf-atommib-atm2-18.txt>.  I didn't want to cite an I-D,
however, because there is an outside change that the methodology used
to throttle trap generation could change before it is published as an RFC.

If you find the text confusing and would like for it to be cleaned up, it
would be helpful to me if you could propose specific changes to the text.

>  >   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
>  >   boilerplace are present, that all MIB modules containing imported
> 
> typo: boilerplace -> boilerplate

Fixed.  It's so hard to see those things until they are pointed out :-(

Thanks again for your comments.

Mike Heard