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

References in MIB documents for IMPORTed items

MIB doctors:

A while ago Bert forwarded some correspondence to me from the RFC
Editor regarding a situation where certain MIB modules were
contained in an IMPORTS list but were omitted from the normative
reference list.  This has happened enough times that we need to have
some checks and balances to help prevent it, and the RFC Editor
wants to make sure that all all cited text has a corresponding
reference and vice versa.

Of the two solutions that were discussed by Bert and the RFC Editor,
I have a strong preference for having some text outside the MIB
module that documents the dependencies, so I propose the following
changes to Sections 3.2 and Section 3.5 of the MIB review
guidelines:

OLD:
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
   MIB modules to other standards, particularly to standards containing
   other MIB modules.  The narrative part SHOULD include one or more
   sections that briefly describes the structure of the MIB modules
   defined in the specification.

   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.

NEW:
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
   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)
   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.

In Section 3.5:

OLD:
   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-mainained MIB module the corresponding normative reference SHALL
   point to the on-line version of that MIB module.

NEW:
   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-mainained 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 text;  such
   citations MUST appear in the overview section where documents
   containing imported definitions (other those already cited in the
   MIB boilerplate) are required to be mentioned (see Section 3.2).

Please let me know whether or not the proposed changes are
satisfactory.  A copy of the discussion between Bert and the RFC
Editor illustrating the alternatives is attached below.

Thanks,

Mike Heard

On Mon, Feb 23, 2004 at 06:12:03PM +0100, Wijnen, Bert (Bert) wrote:
> > 
> > Bert,
> > 
> > We have a question for you regarding the references in MIBs.  We have
> > been trying to ensure that all cited text has a corresponding
> > reference, and vice versa.  
> > 
> Understood
> 
> > Would you be strongly against a request for a line of text, outside of
> > the MIB, that says something like the following:
> > 
> > This MIB imports from [RFCXXXX] and [RFCXXXX].
> > 
> That would be OK with me.
> 
> I have also (in the past) indicated that something aka:
> 
> OLD:
>     IMPORTS
> 
>     MODULE-IDENTITY,
>     OBJECT-TYPE,
>     Gauge32,
>     Integer32,
>     Unsigned32,
>     NOTIFICATION-TYPE,
>     transmission                    FROM SNMPv2-SMI
>     ZeroBasedCounter64              FROM HCNUM-TC
>     TEXTUAL-CONVENTION,
>     RowStatus,
>     TruthValue                      FROM SNMPv2-TC
>     HCPerfValidIntervals,
>     HCPerfInvalidIntervals,
>     HCPerfTimeElapsed,
>     HCPerfIntervalThreshold,
>     HCPerfCurrentCount,
>     HCPerfIntervalCount             FROM HC-PerfHist-TC-MIB
>     MODULE-COMPLIANCE,
>     OBJECT-GROUP,
>     NOTIFICATION-GROUP              FROM SNMPv2-CONF
>     ifIndex                         FROM IF-MIB
>     SnmpAdminString                 FROM SNMP-FRAMEWORK-MIB;
> 
> NEW:
> 
>     IMPORTS
> 
>     MODULE-IDENTITY,
>     OBJECT-TYPE,
>     Gauge32,
>     Integer32,
>     Unsigned32,
>     NOTIFICATION-TYPE,
>     transmission                    FROM SNMPv2-SMI          -- [RFC2578]
>     ZeroBasedCounter64              FROM HCNUM-TC            -- [RFC2856]
>     TEXTUAL-CONVENTION,
>     RowStatus,
>     TruthValue                      FROM SNMPv2-TC           -- [RFC2579]
>     HCPerfValidIntervals,
>     HCPerfInvalidIntervals,
>     HCPerfTimeElapsed,
>     HCPerfIntervalThreshold,
>     HCPerfCurrentCount,
>     HCPerfIntervalCount             FROM HC-PerfHist-TC-MIB  -- [RFC3705]
>     MODULE-COMPLIANCE,
>     OBJECT-GROUP,
>     NOTIFICATION-GROUP              FROM SNMPv2-CONF         -- [RFC2580]
>     ifIndex                         FROM IF-MIB              -- [RFC2863]
>     SnmpAdminString                 FROM SNMP-FRAMEWORK-MIB; -- [RFC3411]
> 
> Would be acceptable to me too.
> It also will look strange in an "extracted MIB module" where the references
> are no longer present, but certainly with the RFC numbers it should be clear 
> enough what is meant.