> The IESG has received a request from an individual submitter to consider
> the following document:
>
> - 'A Template for Documents Containing a MIB Module '
> <draft-harrington-text-mib-doc-template-02.txt> as a BCP
>
> The IESG plans to make a decision in the next few weeks, and solicits
> final comments on this action. Please send substantive comments to the
> ietf@xxxxxxxx mailing lists by 2007-02-07. Exceptionally,
> comments may be sent to iesg@xxxxxxxx instead. In either case, please
> retain the beginning of the Subject line to allow automated sorting.
Here are some comments:
1. Is the title correct ?? That is, is this a document which applies
to "Documents" or does it only apply to I-Ds ?? (Note that checking
the Abstract doesn't answer this question, see example in #2 below.)
If this document applies to RFCs as well as I-Ds, then text is needed
to state that Appendix A and Appendix B apply only to documents which
are I-Ds.
It would also be helpful to be clear in advance whether this document
is intended as a guide to folks who are new to writing I-Ds containing
MIB modules, or as a rule book to be rigidly applied by the MIB Doctors.
The use of "Template" suggests the former, but it has many MUSTs.
2. For beginners, I think this document is quite confusing, because of
the method it uses to include I-D boilerplate for two different
purposes: i) for itself as an I-D, and ii) in the template that it is
describing for other I-Ds/documents. The document repeatedly tries to
use a single section for both purposes, and sometimes it fails and
that's what creates the confusion. Here are two examples:
a) the Abstract says:
This memo defines a portion of the Management Information Base (MIB)
for use with network management protocols. In particular it defines
objects for managing [TODO].
[TODO]: describe what functionality will be managed using this MIB
module. It can be good to mention the protocol being managed, and
whether there is a particular aspect of the protocol to be managed,
or a particular goal of the module. But keep it brief.
none of this text is an Abstract for *this* I-D -- it applies only as
part of the template for use in other documents.
b) the "Note: Foreword to template users" says:
[TODO]: please remove this Note prior to publication.
It's not clear which "publication" this is referring to.
So, I think it would be less confusing to re-organize this document
to have the template embedded inside it (not superimposed on it), such
that each boilerplate section is either: of this document, or within the
template, i.e., have no one boilerplate section used for both purposes.
For example, the template could have additional indentation as the means
for the reader to know which is which.
2. There are a couple of references to "SAMPLE-MIB" and the reader is
left to guess what that means.
3. Section 5.2 suggests having a "section for each subtree in the MIB
module". The granularity of such sections is situation-dependent,
i.e., having sections on a per-subtree basis might be appropriate in
some cases, but there are many other cases where having sections on a
per-MIB-conformance-group basis is more appropriate.
4. Section 6.1 doesn't belong in a MIB document template:
- saying "The SAMPLE-MIB does not duplicate those objects." needs to be
true for all objects, not just the 'system' group -- it should also
be true for all other MIBs, not just for some "SAMPLE-MIB".
- if "does not duplicate" is a "Relationship", then all other MIBs in
the world would need to be listed here, which is obviously impossible.
- if someone feels strongly that this needs to be said, put it in (an
update to) RFC 4181.
- it's possible that some MIB modules will have a real "Relationship"
with the 'system' group, and if so, then a modified version of this
section would be needed, which is currently precluded because this
section doesn't have a "[TODO]" marker.
5. Section 8 says:
o [TODO] 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; RFC 2669 has a very good
example.
I agree that RFC 2669 is a good example, but not all "writeable MIB
objects ... [are] explicitly listed by name" in 2669. In some cases,
2669 lists objects like this:
... manipulation of the docsDevNmAccessTable, docsDevFilterLLCTable,
docsDevFilterIpTable and the elements of the docsDevCpe group may
allow an end-user to ...
without explicitly listing all of the writeable MIB in those tables/that
group. So, I suggest that these two:
o [TODO] 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; RFC 2669 has a very good
example.
o [TODO] list the writable tables and objects and state why they are
sensitive.
should be clarified as alternatives, together with a third alternative
of listing objects contained in a group (as used in RFC 2669, see above).
Similarly, for readable objects, tables and groups.
6. Even when Appendix A and Appendix B are applicable, I suggest that
they don't need to be Appendix A and Appendix B. For example, if the
I-D has other Appendicies, then the Change Log could be Appendix C.
Indeed, I now put the Change Log near the front of my I-Ds, rather than
as an Appendix, because I think that has some advantages, but I'm not
suggesting that you require everyone else to use my preference.
Keith.
_______________________________________________
Ietf@xxxxxxxx
https://www1.ietf.org/mailman/listinfo/ietf