[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Proposed changes to Section 3 of draft-ietf-ops-mib-review-guidelines
Hi,
As the MIB Doctor for IEEE 802.1 WG, I find it can be difficult to
convince other SDOs to apply these guidelines because the guidelines
are not just about writing MIBs, they are also about getting a MIB
document published and approved in the IETF publication and approval
system. IETF approval and publication requirements are mixed in with
the requirements for SMIv2 interoperability and SNMP interoperability.
It makes it much more difficult to argue that "this section of the
guidelines" can be ignored or taken with a grain of salt, but "that
section of the guidelines" must be taken as written, even though
sections both are couched in "MUST" language.
As a MIB Doctor in the IETF, I make the same observation Keith once
made - the difficult portion of getting a MIB document published is
getting through the MIB Doctor review. I suggest we develop tools to
help automate this process, to allow authors to check their own
documents more easily, and to free MIB Doctors from non-expert-review
burdens so we can focus their expertise on providing better advice on
how to design a good MIB module.
I have some suggestions:
----------------------------------------------------------------------
----------------------------------------------------------------------
----
Overview:
These guidelines would benefit from being written so they can be
applied by other organizations, including other SDOs and vendors that
develop their own MIB modules. These guidelines would benefit from
recognizing that 1) not all organizations developing MIB modules will
try to publish using, and seek approval from, the IETF, 2) some of the
guidelines exist to ensure SMIv2 interoperability, and are extremely
important for interoperability, 3) some guidelines are focused on SNMP
rather than SMIv2 interoperability, but not all solutions will use
SNMP as the only transport for MIB information, so we should clearly
identify which guidelines are SNMP-centric rather than SMIv2-centric,
4) other organizations and IETF working groups that are not composed
of SMI/SNMP experts would really benefit from more guidelines that
explain how to design a "good" MIB module.
There are tools available that can help MIB document authors apply the
guidelines. These guidelines would benefit from separating those
elements of checking that can be automated from those that cannot, and
to eliminate the guidelines that are not about MIB document authoring.
But in the meantime, I suggest the document should clearly identify
(and preferablt separate) 1) IETF publication requirements, most of
which can be checked automaticaly usung tools like the id-nits tool,
2) SMIv2 syntax compatibility, much of which can be checked using a
good mib compiler, and 3) recommended practices that are not easily
checked using automation.
I recommend we:
1) Provide templates on the O&M web site as a starting point for MIB
document authors, with all the current boilerplates required for IETF
publication already in place, and other section headers in place
accompanied by instructions from this document or references to
specific sections of this doucment. Sections that SHOULD be modified
by the authors, such as secuirity consdierations, should have markers
that get removed by the wuthor when the modification is provided.
I have submitted a proposed xml2rfc template to Bert for review, and
xml2rfc should be able to generate the corresponding nroff template.
XML2RFC can apparently "include" text from a URI, so keeping the
boilerplates current might be simplified.
2) provide advice to other organizations about how to develop their
own mib module template, and things to watch for in so doing. For
organization that might be able to use XML2RFC, such as vendors, the
include capability might make it easier for those organizations to
substitute their own boilerplates, while maintaining overall
compatibility with the O&M template.
3) In the guidelines document, separate the publication processing
sections from the SMIv2 sections from the SNMP sections from the
design sections. This has already been done to a large degree, and I
will check further.
4) In the guidelines document, separate the automatable rules from
non-automatable rules.
5) Expand the tools available to automate checking (and with
standardized templates available, it might be easier to develop such
tools)
----------------------------------------------------------------------
----------------------------------------------------------------------
----
Editing suggestions for this document:
1) At the beginning of the sections focused on IETF publication
requirements, start out with a pointer to the tools that automate the
checking of these guidelines, i.e. point to the rfc-editor and id-nits
pages of the RFC editor. Separate out any IETF-publication guidelines
not currently covered by these tools.
2) At the beginning of the sections on SMIv2 requirements, start out
with a pointer to the tools that automate the checking of the SMIv2
guidelines, i.e., point to the O&M web page that discusses available
tools and the appropriate settings to use. Separate out those rules
that are not covered by these tools.
3) Section 3 claims to be "General Documentation Guideleines", but is
very explicitly IETF documentation. For example, Section 3 says "The
'body of memo' is always required, and in a MIB document MUST include
the following: ....". This is true for an IETF-published document, but
is not always required in a non-IETF document. It might be a good idea
to take the introductory portion of section 3, make it section 3.1 and
divide it into 3.1.1. "general guidelines for IETF MIB documents" and
3.1.2 "General Guidelines for non-IETF documents". Then we can use
MUST for the IETF documents and RECOMMENDED sections for other
organizations.
--- suggested text ---
3. General Documentation Guidelines
+ 3.1 IETF Documentation Guidelines
+ There are guidelines and tools available that can help an author
+ check against the Section 3 guidelines for IETF documents. See
+ http://www.ietf.org/ID-Checklist.html which discusses current
+ guidelines for internet drafts, and includes pointers to tools
that
+ help automate the process of checking.
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.2 Non-IETF Documentation Guidelines
Many organizations have documentation publication guidelines of
their own.
It is RECOMMENDED that non-IETF documents containing MIB modules
include
sections similar to those in an IETF MIB document, with some
differences.
o MIB boilerplate section
o Narrative sections
o Definitions section
o Security Considerations section
o Naming Authority Considerations section
o References section.
3.2.1. MIB module format
The MIB module portions of a MIB document should always be made
available in US-ASCII format so the module(s) can be imported into
management applications easily. If an organization supports a
documentation
format without cut-and-paste capabilities, such as PDF format, it
is
RECOMMENED that, at least, the MIB module portion (the Definitions
sections)
be made separately available in US-ASCII format.
3.2.2. MIB module availability
Many standards organizations charge for copies of specifications of
standards.
The purpose of a MIB module is to standardize the interface to
management
information to allow the management of devices which implement a
managed technology.
It is RECOMMENDED that at least the MIB module portion (the
Definitions sections)
be made publicly accessible and freely available to encourage
implementation,
even if an organization's policy is to charge for the complete
standard
specification. This will permit application developers to support
managing
using the MIB module, even though the application may not need to
implement
the managed technology itself. For example, an application could
enable monitoring
Ethernet, though the application does not itself implement the
Ethernet protocol.
3.2.3, Naming Authority
IANA is the naming authority used by the IETF. A section detailing
what naming is needed for the document is required for all IETF MIB
documents.
MIB module naming registrations are made by IANA after an IETF MIB
document
has been approved, to reduce problems of interoparbility between
implemented revisions which have not yet been approved and
implemented
revisions which have been approved. It is RECOMMENDED that naming
done by other
naming authorities also be done only after the document has been
approved.
Other organizations MAY choose to include a document section that
details
the naming that needs to be provided by their naming authority.
--- end suggested text ---
Proposed text for the current Section 3.1:
--- proposed text ---
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.
For non-IETF documents, it is RECOMMENDED that a verbation copy
of the latest approved Internet-Standard Management Framework
boilerplate
be used.
The approved boilerplate makes a distinction between the SMI used
to
write MIB modules, and SNMP, the protocol most frequently used to
transport MIB module data. Some organizations MAY choose to also
utilize
non-SNMP protocols to carry MIB module data.
RFC 3410 describes the Internet-Standard Management Framework,
which explains
the relationahip between the SMI data modeling language, MIB
modules, and the
SNMP protocol, and discusses the applicability of SNMP versions.
For
organizations that choose to use a different protocol, RFC3410
provides
some background into the issues to consider, especially security.
--- end proposed text ---
Section 3.3
"These MIB modules" s/b "IETF MIB modules"
Non-IETF MIB modules SHOULD be written using SMIv2.
---
Section 3.4
I have a concern that we are requiring people to describe the security
considerations on a per-object basis in a section of the document
That frequently is stripped from the mib module. I think we should be
encouraging people to put the per-object security considerations in
the
Object description, and the per-table security considerations in the
table descriptions. This way the information will still be accessible
In the stripped module.
I think we should encourage people to use the security considerations
section to point to the objects that contain the descriptions of the
zsecurity risks.
---
Section 3.5 might be better titled "Naming Authority Considerations
Section", and have a subsection 3.5.1 that is the current "IANA
Considerations Section" (all the existing text indented one level.
A new Section 3.5.2 might advise other organizations to consider name
space issues comparable to those described under IANA Consideraions
Section.
---
Section 3.7 deals with copyright notices.
RFC 3907 is referenced, but does not appear to exist yet.
For non-IETF documents, it would be good to advise other organizations
to consider
the importance of allowing organizations to make copies, with
restrictions, for management purposes.
I suspect that is what is discussed in RFC 3907.
Section 3.8 deals with intellectual property issues. For non-IETF
documents, it woul dbe good if we provided some guidelines about
crafting their IP notices for MIB modules to ensure thay can be used
for management purposes. This is somewhat similar to the proposed text
about making MIB modules freely available.
David Harrington
dbharrington@comcast.net
> -----Original Message-----
> From: owner-mreview@ops.ietf.org
> [mailto:owner-mreview@ops.ietf.org] On Behalf Of Romascanu, Dan
(Dan)
> Sent: Monday, January 03, 2005 5:57 AM
> To: C. M. Heard; Mreview (E-mail)
> Subject: RE: Proposed "Last Call" version of
> draft-ietf-ops-mib-review-guidelines [ Corrected, for the 2nd time ]
>
> Mike,
>
> At IETF61 in the Bridge MIB WG meeting the issue was raised
> about the usage of the guidelines document for reviewing and
> as a guidelines for editors of documents defining MIB modules
> from outside of the IETF (see
> http://www1.ietf.org/proceedings_new/04nov/minutes/bridge.html
> ). One of the options I had in mind was a possible section
> that mentions the non-IETF specifics and possible relaxation
> of some of the rules that would allow for the guidelines to
> be used in a more convenient manner by non-IETF
> consistencies. I apologize for raising this in a thread that
> tries to get this extremely useful work closer to completion,
> but is it too late to discuss this issue?
>
> Thanks and Regards,
>
> Dan
>
>
>
> > -----Original Message-----
> > From: owner-mreview@ops.ietf.org
> > [mailto:owner-mreview@ops.ietf.org]On Behalf Of C. M. Heard
> > Sent: 02 January, 2005 8:38 AM
> > To: Mreview (E-mail)
> > Subject: Proposed "Last Call" version of
> > draft-ietf-ops-mib-review-guidelines [ Corrected, for the 2nd time
]
> >
> >
> > [ re-sent, again, to fixdouble line-break problem in attachments ]
> >
> > 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
> >
>
>