[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: comments/review <draft-ietf-ops-mib-review-guidelines-00.txt>
On Fri, 7 Feb 2003, Wijnen, Bert (Bert) wrote:
> Sorry that this took a while (well more than a day).
I consider that pretty speedy; the replies have
taken me quite a lot longer. As folks have probably
noted, many of these comments have already been
addressed in separate "issue threads"; the ones
not so addressed are answered in-line below.
> - you talk about "standard" MIB quite a few times.
> maybe better to use "standards track" MIB, cause it is
> true for all 3 levels on the stds track
See thread entitled ``clarifying the term "standard"''
> - Sect 3 talks about need for IPR section.
> I believe such is only required for stds track and bcp docs
> It is allowed in other docs, but not required I think.
See thread entitled ``clarify that MIB review requirements
are targeted at standards-track documents''
> - sect 3.2
> I have often asked people to IMPORT object groups from
> other MIB modules if they require them to be implemnted
> and then to add such groups to the MODULE-COMPLIANCE.
> Would that not be better than narrative text to express it.
See thread on mibs@ops.ietf.org list entitled ``section 3.2 of
draft-ietf-ops-mib-review-guidelines-00.txt''. I think we
have agreement in principle, but I still owe you some proposed
text ... look for it on the mibs list, if possible I will post
it before the end of the week.
> - sect 3.3 1st sentence
> s/MIB modules/MIB module(s)/ ??
Fixed.
> - sect 3.7
> I personally have no problem [if a to-be] IANA-maintained
> MIB module stays in an RFC where it gets first published
> and handed to the RFC-Editor. As long as it makes clear
> that current versions should be picked up from the iana
> web pages, and that furture revisions will NOT include
> the current or updated revisions.
> RFC1573 is an example of that for IANA ifTypes.
See thread entitled ``guidelines section 3.7 (disposition of
IANA MIB modules)''
> - sect 4.3
> as an aside, does that now mean that we as MIB doctors
> agree that it is OK for draft-ietf-ops-rfc2786std-00.txt
> to stay under experimental if that is what they want,
> even when the doc gets published as stds track doc?
In this case, yes, but make it clear that this document is
being granted a waiver (or a variance, if you prefer that
term) and that this won't be a general practice.
> - sect 4.5
> last sentence of 3rd bullet....
> are we sure we agree? I have seen trouble with that, even
> for the RMON MIB space... I cought it in time before
> we published an RFC, but...
> Should we at least ask that such registrations are
> administered by IANA. SO the WG can make them but should
> get them recorded and documented in the IANA registry.
> That way... when say 10 years from now, someone wants to
> add something, they have a central place to check as to
> what actually has been assigned and what numbers are still
> available.
See thread entitled ``guidelines section 4.5 (WG-assigned OIDs
vs IANA-assigned OIDs)''
> - sect 4.6.1.1
> You may want to indent the para that starts with
> "Note that RFC 2578....
> 2 positions to the right. Or so I think
The typography is as I intended it to be, and unless there are
strong objections I'd really prefer to leave it the way it is.
> - sect 4.6.1.4, end of page 14
> Mmm... the DisplayString is still current, although we
> rarely want to allow people to use it anymore. We prefer
> UTF-8 based TCs like SnmpAdminString.
> Do we want to make a note of that? I think it would be
> good. It is a thing that I see still far too often.
See thread entitled ``DisplayString in guidelines 4.6.1.4
and Appendix D''
> - sect 4.6.1.5 one but last para
> s/RowPointerTC/RowPointer TC/ ??
Fixed.
> - sect 4.6.3 page 18
> You talks about the "status" column. Is it not better
> to call it the "row-status" column ? Some MIB modules
> use a additional status to indicate enabled/disabled
> or inuse/out-of-order and what have you.
The term and its definition are copied (almost verbatim)
from RFC 2578. I'd prefer to leave the usage aligned
with RFC 2578, unless there are strong objections.
> - Same section,
> would it be good to add (tableEntry) in parentheses
> at the first mention of "row object"
Done.
> - Same section
> For table that are not read-create, but that have read-write
> objects, I think we also want some words about persistence
> or a StorageType object.
See thread entitled ``guidelines 4.6.2/4.6.3 (persistence of values
of read-write objects)''
> - sect 4.7
> I wonder if we should say something about what I often
> mention when reviewing, and that is that for many MIB
> modules, it makes sense to not do:
>
> xxxMibNotifications OBJECT IDENTIFIER ::= { xxxMib 2 }
> xxxMibNotificationPrefix
> OBJECT IDENTIFIER ::= { xxxMibNotifications 0 }
>
> but instead use
>
> xxxMibNotifications OBJECT IDENTIFIER ::= { xxxMib 0 }
>
> It is not always the best solution, but in many case sit is
> and it shortens the OID by one subID.
> (details details, right?)
>
> Juergen actually had a good few paragraphs about it at
> some time as to when to use which approach... but I can't
> find it quickly.
I think that the xxxMibNotificationPrefix method is better known.
It's mentioned in RFC 2578, and I've seen it used in a lot of
places. That said, I suggested both alternatives to Avi Berger
when he was getting compile errors on the POWER-ETHERNET-MIB,
and he chose the method you seem to prefer. I actually thought
I would get criticized for suggesting something unconventional :)
As for putting specific advice to this effect in the guidelines: I
am reluctant to do so simply because the document is getting bigger
than we want. I'm happy if I can just get people to follow the
"next-to-last OID must be zero" rule so I don't have to pester them
about compile warnings in MIB reviews (this one seems to come up all
the time).
If you are not satisfied with this answer, let's start
a thread specific to this topic and get other opinions.
> - sect 4.8 3rd bullet
> would we not recommend to do it in the same MIB module?
That's the normal practice. On the other hand, we don't want
to say that making a compliance statement in a companion
module is NOT RECOMMENDED -- we would be in danger of making
up a CLR (remember the "Gauge32 as Index" brouhaha). Let me
just mention a couple of examples of compliance statements
living elsewhere:
(1) The ifStackGroup2 is not mentioned in the current
compliance statement ifCompliance3 of IF-MIB (RFC 2863),
but it is mentioned in ifInvCompliance of
IF-INVERTED-STACK-MIB (RFC 2864). These modules were
packaged separately so that IF-MIB could advance to
Draft Standard while IF-INVERTED-STACK-MIB was
introduced at Proposed Standard. The ifStack compliance
stuff needed to go in the latter so that the PS doc
would reference the DS doc and not the other way around.
(2) The ETHER-WIS MIB <draft-ietf-hubmib-wis-mib-06.txt>
has a complete SONET-MIB compliance statement built in
instead of incorporating the one in SONET-MIB by
reference because it needed to express requirements that
are tighter than those of the generic SONET-MIB compliance
statement.
My preference is to leave this as is. If you are
not satisfied with this answer, let's start a thread
specific to this topic and get other opinions.
> - last bullet on page 21
> I'd actually remove the last few words. SO I would change
>
> example is provided by the DIFFSERV-MIB [RFC3289]. Authors SHOULD
> consider using this technique in situations where it is
> appropriate.
>
> into
>
> example is provided by the DIFFSERV-MIB [RFC3289]. Authors SHOULD
> consider using this technique.
>
> Or maybe the last sentence:
>
> It is strongly RECOMMENDED to use this technique.
>
> because I think it makes it MUCH easier for an agent to express
> what it complies with, and so it potentially makes things easier
> on the manager (assuming everyone implements correctly and makes
> correct claims).
See thread entitled ``guidelines 4.8 (read-only + full compliances)''
> - page 22
> Is that a footnote that I see? I though RFC-Editor does not
> allow for that
No, it's an endnote, which is allowed (I checked!). Here is what it
says in Section 3.1 (page 16)
(8) Footnotes
Do not use footnotes. If such notes are necessary, put them
at the end of a section, or at the end of the document.
and in Appendix B (page 31)
7. No footnotes (end notes OK) | 3.1(8)
so I think I am OK.
> - Page 22 says towards bottom (just before footnote)
> 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).
>
> I wonder if we could recommend that they also just do the spec
> in the form of comments for such index columns. So
>
> -- OBJECT xxxIndex
> -- SYNTAX InetAddressType { ipv4(1), ipv6(2) }
> -- DESCRIPTION "Only ipv4 and ipv6 support is required"
>
> That way it reads easier I think Of course it also is good to
> have it in a real DESCRIPTION clause.
This looks nice but it duplicates information in the DESCRIPTION
clause. I tend to dislike having a lot of stuff like this in
comments because comments tend not to get updated (sometimed not
even from one spin of a draft to the next), and for that reason
(as anyone who has worked in a software team can tell you) cannot
really be trusted. I would not mind if an author decided to do
this (then he or she would probably not need me to do a review :),
but I don't want to be responsible for trying to nag reluctant authors
into doing something like this. I will be happy if they just put
the right stuff in the DESCRIPTION clauses without too much hassling.
Again, if you are not satisfied with this answer, let's start
a thread specific to this topic and get other opinions.
> - Sections 4.8 and 4.9 are pretty long.
> Would it be possible to add some sub-numbers or labels
> so that when we review a MIB and we find it violates some
> piece of these sections that we can easily say
> see RFCxxxx section 4.9 bullet A sub 3 or some such?
> Just thinking aloud here
I know that these sections are not so good, but I've had to
struggle a lot with them already ... you know how long it
took ... let me take this under advisement, and once we get the
content worked out we can re-open the issue. Will that be OK?
> - page 25 2nd bullet
> I actually wonder if it would not be better if people did
> list all the enumerations at the first revision of a MIB
> and the compliance statements. That way... it is clear
> from the beginning what it is that one can expect.
>
> Of course some enumerations do not need that, because they
> are [not] intended to be extended, and that is OK.
I think RFC 2580 already says that. Do we need to repeat it
here? The document is already pretty long, and it's not getting
any shorter.
> - Appendix A
> - add a bullet to do a general/overall check on ID-NITs
> with ptr to it of course
OK. How about the following:
10.) Other issues -- check for any issues mentioned in
http://www.ietf.org/ID-nits.html that are not covered above.
The technical content bullet would then become #11.
While I have your attention: one of the promised fixes
to http://www.ietf.org/ID-nits.html is incompletely
implemented. It now says:
* All MIBs must compile cleanly using "smilint -m -s -l 9 -i
namelength-32"
and this is still not quite right: ``must'' needs to
be changed to ``should'', otherwise ID-nits and the
guidelines doc will be out-of-sync. I'd like to
suggest a formatting change too, so that it would read:
* All MIBs should compile cleanly using
"smilint -m -s -l 9 -i namelength-32"
The other fix (regarding the IANA considerations section) is
also formatted rather poorly, and I request that
* Required if the document requires IANA to assign or update values
in an IANA registry before RFC publication. Note that for the
assignment of just an OID for a MIB or PIB Module, no IANA
Considerations section is required; it is sufficient to request
such via a MIB/SMI or PIB/SPPI comment line, aka: ::= { mib-2 xxx
} -- xxx to be assigned by IANA
be changed to
* Required if the document requires IANA to assign or update values
in an IANA registry before RFC publication. Note that for the
assignment of just an OID for a MIB or PIB Module, no IANA
Considerations section is required; it is sufficient to request
such via a MIB/SMI or PIB/SPPI comment line, aka:
::= { mib-2 xxx } -- xxx to be assigned by IANA
(Note that only the layout is requested to be changed in the above)
> - I will check the appendix C.. Mike did send me some stuff
> to work out... still to be done.
> Thing is I'd like to refer to 2578/79/80 instead of
> 1902/3/4
Pending that investigation, the only comment I have is that
rfc1902.inc, rfc1903.inc, and rfc1904.inc are filenames, not
formal references to RFCs, and they match the stuff that's
available for download from the snmpinfo web site.
> - Appendix D
> - Make a note that DisplayString should not be used anymore
> but some UTF-8 based TC instead
> - We probably should add some more common TCs here.
> In fact we should start that project to collect all
> common TCs into one place one way or another, so that
> they are easy to find.
The note you requested was proposed in the thread entitled
``DisplayString in guidelines 4.6.1.4 and Appendix D''
As for the scope of this appendix ... while it would be a
worthwhile project to make a comprehensive list of all TCs
in standards-track documents, my ambitions here were much
more modest. I was trying just to make sure that I mentioned
all the TCs that:
(a) are mentioned by name elsewhere in the document,
OR
(b) are so basic that every MIB author needs to be aware of them.
If I've left anything out in either of these categories then
by all means let me know and I will add them (I think I already
proposed adding Utf8String and LongUtf8String). But we don't
want to try to put down everything here; even if we did, it
would get stale all too soon. A comprehensive list of TCs is
something that really ought to go into an on-line registry
that is continually updated, and not in a semi-permanent
archival document.
> Thanks again Mike. Great job.
> Bert
Thanks for the kind words, and sorry it took so long.
Mike