[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
A Template for Documents Containing a MIB Module
Hi,
I have updated the MIB module document template. I think I have
addressed most comments I received.
I would like to make this available in two forms.
The (xml2rfc-output) text template can be used in any editor as a
starting point for an internet-draft. I have submitted this to be
published.
The second form is the same template, written in XML, ready for
xml2rfc. If you run this template as is, it will generate the text
template. The XML is heavily commented with how to modify the XML to
fill in the fields with content relative to the desired MIB module. In
XXE, this is pretty user-friendly because the comments are shown with
a colored background, while the text to be modified (and the
boilerplate) is shown on a white background. So a person can read the
suggestions (mostly from RFC4181) about how to fill in the sections.
Once they fill in the sections, they can generate their own MIB module
from the modified XML source using xml2rfc. I hope to publish a draft
of the xml template in the next few days.
The major change from the last version I showed to this list is that I
removed the sample MIB entirely.
In discussions with the rfc-editor, that is the preferred way since
they need to extract the module and validate it anyway. Now, the
template is only about providing guidance to writing the surrounding
text. Then you paste your valid MIB module into the document within a
figure tag. So this helps get the fixed boilerplate right, defines the
common sections we want to see, and provides RFC4181-compatible
guidance about filling in the various sections.
Others here have expressed an interest in writing tools to generate
MIB modules from user-friendly web interfaces and so on. My template
has left that part of the job to you.
Comments welcome.
David Harrington
dharrington@huawei.com
dbharrington@comcast.net
ietfdbh@comcast.net
<?xml version="1.0" encoding="US-ASCII"?>
<!--
XML2RFC offers an include feature described in the XML2RFC README
file. That syntax, however, contradicts the DTD requirements to
have <reference> elements within the <references> element, so an
XML parser is likely to find your XML file invalid. It may be
possible that XML2RFC will change their DTD so that the XML file
remains valid when their style of include is used.
In the meantime therefore, we use an alternative valid-XML approach
to includes, which unfortunately require that define your includes
at the beginning of the file. Since the biggest benefit of includes
is for references, this requires that your references be defined in
ENTITY clauses here before being "included" and cited elsewhere in
the file.
-->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY rfc2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml";>
<!ENTITY rfc2863 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2863.xml";>
<!ENTITY rfc3418 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3418.xml";>
<!ENTITY rfc4181 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4181.xml";>
<!ENTITY rfc2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml";>
<!ENTITY rfc2578 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2578.xml";>
<!ENTITY rfc2579 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2579.xml";>
<!ENTITY rfc2580 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2580.xml";>
<!ENTITY rfc3410 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3410.xml";>
]>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc strict="no"?>
<?rfc rfcedstyle="yes"?>
<!--
This template is for authors of IETF specifications containing MIB
modules. This template can be used as a starting point to produce
specifications that comply with the Operations & Management Area
guidelines for MIB module documents.
-->
<!--
Throughout this template, the marker "[TODO]" is used to indicate an
element or text that requires replacement or removal.
-->
<!-- Intellectual Property section -->
<!--
The Intellectual Property section will be generated automatically by
XML2RFC, based on the ipr attribute in the rfc element.
-->
<!--
[TODO] specify the name of the output document. This is optional;
the default is to use the base portion of the XML filename.
[TODO]For Internet-drafts, indicate which intellectual property notice
to use per the rules of RFC3978.
Specify this in the ipr attribute. The value can be:
full3978 -
noModification3978 -
noDerivatives3978 -
[TODO] Specify the category attribute per RFC2026
options are info, std, bcp, or exp.
[TODO] if this document updates an RFC, specify the RFC in the
"updates" attribute
-->
<rfc category="bcp" docName="draft-harrington-text-mib-doc-template-00.txt"
ipr="full3978">
<front>
<!--
Throughout this template, the marker "[TODO]" is used to indicate an
element or text that requires replacement or removal.
-->
<!--
[TODO] Enter the full document title and an abbreviated version
to use in the page header.
-->
<title abbrev="MIB Module Document Text Template">A Template for Documents
Containing a MIB Module</title>
<!-- [TODO] copy the author block as many times as needed, one for each author.-->
<!-- If the author is acting as editor, use the <role=editor> attribute-->
<!-- see RFC2223 for guidelines regarding author names -->
<author fullname="David Harrington" initials="D" role="editor"
surname="Harrington">
<organization>Huawei Technologies (USA)</organization>
<address>
<postal>
<street>1700 Alma Drive, Suite 100</street>
<city>Plano, TX 75075</city>
<country>USA</country>
</postal>
<phone>+1 603 436 8634</phone>
<email>dharrington@huawei.com</email>
</address>
</author>
<!-- [TODO]: month and day will be generated automatically by XML2RFC;
be sure the year is current.-->
<date year="2006" />
<!--[TODO] IETF area is optional -->
<area>Operations & Management Area</area>
<!--[TODO] WG name at the upperleft corner of the doc,
IETF is fine for non-WG submissions -->
<workgroup>Internet Engineering Task Force</workgroup>
<keyword>Network Management</keyword>
<keyword>Management Information base</keyword>
<keyword>MIB</keyword>
<keyword>SMIv2</keyword>
<!--[TODO] add additional keywords here for IETF website search engine -->
<abstract>
<t>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].</t>
<!--[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.-->
<!--Remember, don't put any citations in the abstract, and expand your acronyms. -->
</abstract>
<note title="Foreword to template users">
<t>This template helps authors write the surrounding text needed in a
MIB module document, but does not provide a template for writing the MIB
module itself.</t>
<t>For updated information on MIB module guidelines and templates, see
<xref target="RFC4181"></xref> and http://www.ops.ietf.org/.</t>
<t>For information on writing internet drafts or RFCs, see
http://www.ietf.org/ietf/1id-guidelines.txt and RFC2223(bis), and look
at http://www.ietf.org/ID-Checklist.html for issues to note when writing
drafts.</t>
<t>This template is not meant to be a conclusive list of everything
needed to write MIB module documents, but to summarize the often-needed
basic features to get a document containing a MIB module started. An
important purpose of the template is to aid authors in developing a
document that is laid out in a manner consistent with other documents
containing MIB modules. Documents submitted for advancement to the
standards track typically require review by a MIB Doctor. This template
standardizes the layout and naming of sections, includes the appropriate
boilerplate text, and facilitates the development of tools to automate
the checking of MIB module documents, to speed the WG and IESG review
processes.</t>
<t>An XML template is also available. For information on XML2RFC, see
RFC2629 <xref target="RFC2629"></xref>,
http://xml.resource.org/public/rfc/html/rfc2629.html and "bis":
http://xml.resource.org/authoring/draft-mrose-writing-rfcs.html. Also
see http://xml.resource.org/authoring/README.html for 'rfc' option
strings. The benefit of using the XML version of the template is that
comments in the XML describe how to fill in each section of the
template, and then XML2RFC will generate the actual internet-draft with
your information. XML2RFC automatically handles much of the boilerplate,
references, and idnits issues for you.</t>
<t>[TODO]: please remove this Note prior to publication.</t>
</note>
</front>
<middle>
<section title="Introduction">
<!-- It is good practice to echo the abstract in the Introduction,
providing citations here. -->
<t>This memo defines a portion of the Management Information Base (MIB)
for use with network management protocols. In particular it defines
objects for managing the [TODO]</t>
</section>
<section title="The Internet-Standard Management Framework">
<t><!-- The title and text for this section has been copied from the
official boilerplate, and should not be modified unless the boilerplate text at http;//ops.ietf.org/mib-boilerplate.html has changed. See RFC4818
section 3.1 for a discussion of the boilerplate section.-->For a detailed
overview of the documents that describe the current Internet-Standard
Management Framework, please refer to section 7 of RFC 3410 <xref
target="RFC3410"></xref>.</t>
<t>Managed objects are accessed via a virtual information store, termed
the Management Information Base or MIB. MIB objects are generally
accessed through the Simple Network Management Protocol (SNMP). Objects
in the MIB are defined using the mechanisms defined in the Structure of
Management Information (SMI). This memo specifies a MIB module that is
compliant to the SMIv2, which is described in STD 58, RFC 2578 <xref
target="RFC2578"></xref>, STD 58, RFC 2579 <xref
target="RFC2579"></xref> and STD 58, RFC 2580 <xref
target="RFC2580"></xref>.</t>
</section>
<section title="Conventions">
<!--[TODO] This boilerplate should be used if the RFC2119 key words
are used in the document. -->
<t><!-- The text in this section has been copied from the official boilerplate,
and should not be modified.-->The key words "MUST", "MUST
NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in RFC 2119 <xref target="RFC2119"></xref>.</t>
</section>
<!-- ********************************************* -->
<section title="Overview">
<!--[TODO] The narrative part MUST include an overview section that describes
the scope and field of application of the MIB modules defined by the
specification.
See RFC4181 section 3.2 for a discussion of the Narrative section-->
<t></t>
</section>
<!-- Design Principles -->
<!--
<t>This section is here to remind authors of the Design Principles
for MIB modules.</t>
<t>To be consistent with IAB directives and good engineering
practice, an explicit attempt should be made to keep this MIB module
as simple as possible. This can be accomplished by applying the
following criteria to objects proposed for inclusion:</t>
</t>
<t>
<list style="symbols">
<t>
Start with a small set of essential objects and add only
as objects are needed.
</t>
<t>
Require objects be essential for either fault or
performance or configuration management.
</t>
<t>
Consider evidence of current use and/or utility.
</t>
<t>
Limit the total number of objects.
</t>
<t>
Exclude objects which are simply derivable from others in
this or other MIB modules. The complexity of deriving values
should be done by the managament station, not the agent.
</t>
<t>
Avoid causing critical sections to be heavily
instrumented. The guideline that has been followed in previous
MIB modules is one counter per critical section per layer.
</t>
<t>
Consider the requirements of a small footprint system, such
as a set-top box as well as the expanded functionality beneficial
to a large foootprint system. To the degree possible, costs
associated with advanced functionality should be borne only
by the systems implementing such functionality, and the overhead
of advanced functionality should minimally impact systems which
do not implement the advanced functionality.</t>
</list>
</t>
</section>
-->
<section title="Structure of the MIB Module">
<!--[TODO] The narrative part SHOULD include one or more
sections to briefly describe the structure of the MIB modules defined
in the specification. -->
<section title="Textual Conventions">
<!--Generic and Common Textual Conventions can be found summarized at
http://www.ops.ietf.org/mib-common-tcs.html-->
<t></t>
</section>
<section title="The [TODO] Subtree">
<t><!--[TODO] copy this section for each subtree in the MIB module,
and describe the purpose of the subtree.
For example, the fooStats subtree provides information for
identifying fault conditions and performance degradation of
the foo functionality.--></t>
</section>
<section title="The Notifications Subtree">
<t><!--[TODO] describe the notifications defined in the MIB module,
and their purpose.--></t>
</section>
</section>
<section title="Relationship to Other MIB Modules">
<!-- [TODO]: The narrative part MUST include a section that specifies
the relationship (if any) of the MIB modules contained in this document
to other standards, particularly to standards containing other MIB modules.
If the MIB modules defined by the specification import definitions
from other MIB modules (except for those defined in the SMIv2
documents [RFC2578] [RFC2579] [RFC2580]) or are always implemented in
conjunction with other MIB modules, then those facts must be noted in
the narrataive section, as must any special interpretations of objects
in other MIB modules. Note that citations may NOT be put into the MIB
module portions of the document, but documents used for Imported items are
Normative references, so the citations must exist in the narrative section
of the document. For example, some 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.
-->
<t>Some management objects defined in other MIB modules are applicable
to an entity implementing this MIB. In particular, it is assumed that an
entity implementing the SAMPLE-MIB module will also implement the
'system' group of the SNMPv2-MIB <xref target="RFC3418"></xref> and the
'interfaces' group of the IF-MIB <xref target="RFC2863"></xref>.</t>
<section title="Relationship to the SNMPv2-MIB">
<t>The 'system' group in the SNMPv2-MIB <xref target="RFC3418"></xref>
is defined as being mandatory for all systems, and the objects apply
to the entity as a whole. The 'system' group provides identification
of the management entity and certain other system-wide data. The
SAMPLE-MIB does not duplicate those objects.</t>
</section>
<section title="Relationship to the IF-MIB">
<!--[TODO] This section is included as an example; If the
MIB module is not an adjunct of the Interface MIB, then this section
should be removed.-->
<t>The Interface MIB <xref target="RFC2863"></xref> requires that any
MIB module which is an adjunct of the Interface MIB clarify specific
areas within the Interface MIB. These areas were intentionally left
vague in the Interface MIB to avoid over constraining the MIB, thereby
precluding management of certain media-types.</t>
<t>Section 4 of <xref target="RFC2863"></xref> enumerates several
areas which a media-specific MIB must clarify. The implementor is
referred to <xref target="RFC2863"></xref> in order to understand the
general intent of these areas.</t>
</section>
<section title="MIB modules required for IMPORTS">
<!-- [TODO]: Citations are not permitted within a MIB module,
but any module mentioned in an IMPORTS clause or document mentioned
in a REFERENCE clause is a Normative reference, and must be cited someplace
within the narrative sections. If there are imported items in the MIB module,
such as Textual Conventions, that are not already cited, they can be cited
in text here. Since relationships to other MIB modules should be described
in the narrative text, this section is typically used to cite modules from which
Textual Conventions are imported. -->
<t>The following MIB module IMPORTS objects from SNMPv2-SMI <xref
target="RFC2578"></xref>, SNMPv2-TC <xref target="RFC2579"></xref>,
SNMPv2-CONF <xref target="RFC2580"></xref>, and IF-MIB <xref
target="RFC2863"></xref></t>
</section>
</section>
<!-- Definitions section -->
<!-- This section contains the MIB module(s) defined by the specification.
These MIB modules MUST be written in SMIv2 [RFC2578] [RFC2579]
[RFC2580].
See Section 4 of RFC 4181 for guidelines on SMIv2 usage.
See Appendix C of RFC 4181 for suggested naming conventions
A list of tools that can help automate the process of checking mib definitions can
be found at http://www.ops.ietf.org/mib-review-tools.html
-->
<section title="Definitions">
<t></t>
<figure>
<artwork>
<!-- [TODO]: put your valid MIB module here. A list of MIB verification
tools is available at http://tools.ietf.org/-->
</artwork>
</figure>
</section>
<section title="Security Considerations">
<!--[TODO] Remember to consider security from the start. -->
<!-- Each specification that defines one or more MIB modules MUST
contain a section that discusses security considerations relevant to those
modules. This section MUST be patterned after the latest approved
template (available at http://www.ops.ietf.org/mib-security.html).
Remember that the objective is not to blindly copy text from the template,
but rather to think and evaluate the risks/vulnerabilities and then
state/document the result of this evaluation.
-->
<t></t>
<!--[TODO] if you have any read-write and/or read-create objects,
please include this boilerplate paragraph. -->
<t>There are a number of management objects defined in this MIB module
with a MAX-ACCESS clause of read-write and/or read-create. Such objects
may be considered sensitive or vulnerable in some network environments.
The support for SET operations in a non-secure environment without
proper protection can have a negative effect on network operations.
These are the tables and objects and their
sensitivity/vulnerability:</t>
<t><list style="symbols">
<t><!--[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.-->[TODO] list the writable
tables and objects and state why they are sensitive.</t>
</list></t>
<!--[TODO] else if there are no read-write objects in your MIB module, use this boilerplate paragraph. -->
<t>There are no management objects defined in this MIB module that have
a MAX-ACCESS clause of read-write and/or read-create. So, if this MIB
module is implemented correctly, then there is no risk that an intruder
can alter or create any management objects of this MIB module via direct
SNMP SET operations.</t>
<!--[TODO] if you have any sensitive readable objects, please include this boilerplate paragraph.-->
<t>Some of the readable objects in this MIB module (i.e., objects with a
MAX-ACCESS other than not-accessible) may be considered sensitive or
vulnerable in some network environments. It is thus important to control
even GET and/or NOTIFY access to these objects and possibly to even
encrypt the values of these objects when sending them over the network
via SNMP. These are the tables and objects and their
sensitivity/vulnerability: <list style="symbols">
<t><!--[TODO] you must explicitly list by name any readable
objects that are sensitive or vulnerable and the associated security risks
MUST be spelled out (for instance, if they might reveal customer information
or violate personal privacy laws such as those of the European Union if
exposed to unathorized parties) -->[TODO] list the tables and objects and
state why they are sensitive.</t>
</list></t>
<!--[TODO] discuss what security the protocol used to carry the
information should have. The following three boilerplate paragraphs should
not be changed without very good reason. Changes will almost certainly
require justification during IESG review.-->
<t>SNMP versions prior to SNMPv3 did not include adequate security. Even
if the network itself is secure (for example by using IPSec), even then,
there is no control as to who on the secure network is allowed to access
and GET/SET (read/change/create/delete) the objects in this MIB
module.</t>
<t>It is RECOMMENDED that implementers consider the security features as
provided by the SNMPv3 framework (see <xref target="RFC3410"></xref>,
section 8), including full support for the SNMPv3 cryptographic
mechanisms (for authentication and privacy).</t>
<t>Further, deployment of SNMP versions prior to SNMPv3 is NOT
RECOMMENDED. Instead, it is RECOMMENDED to deploy SNMPv3 and to enable
cryptographic security. It is then a customer/operator responsibility to
ensure that the SNMP entity giving access to an instance of this MIB
module is properly configured to give access to the objects only to
those principals (users) that have legitimate rights to indeed GET or
SET (change/create/delete) them.</t>
</section>
<section title="IANA Considerations">
<!-- In order to comply with IESG policy as set forth in
http://www.ietf.org/ID-Checklist.html, every Internet-Draft that is
submitted to the IESG for publication MUST contain an IANA
Considerations section. The requirements for this section vary
depending what actions are required of the IANA.
see RFC4181 section 3.5 for more information on writing an IANA clause
for a MIB module document.-->
<t>[TODO} select an option and provide the necessary details.</t>
<t>Option #1:</t>
<figure>
<preamble></preamble>
<artwork><![CDATA[
The MIB module in this document uses the following IANA-assigned
OBJECT IDENTIFIER values recorded in the SMI Numbers registry:
Descriptor OBJECT IDENTIFIER value
---------- -----------------------
sampleMIB { mib-2 XXX }
]]></artwork>
<postamble></postamble>
</figure>
<t></t>
<t>Option #2:</t>
<t>Editor's Note (to be removed prior to publication): the IANA is
requested to assign a value for "XXX" under the 'mib-2' subtree and to
record the assignment in the SMI Numbers registry. When the assignment
has been made, the RFC Editor is asked to replace "XXX" (here and in the
MIB module) with the assigned value and to remove this note.</t>
<t>Note well: prior to official assignment by the IANA, a draft document
MUST use placeholders (such as "XXX" above) rather than actual numbers.
See RFC4181 Section 4.5 for an example of how this is done in a draft
MIB module.</t>
<t>Option #3:</t>
<!-- If no IANA work is required, an explicit note must be included.-->
<t>This memo includes no request to IANA.</t>
</section>
<!-- The Author's Addresses section will be generated automatically by XML2RFC from the front information -->
<section title="Contributors">
<t>This template is based on contributions from the MIb Doctors,
especially Juergen Schoenwaelder, Dave Perkins, C.M.Heard and Randy
Presuhn.</t>
<t><!--[TODO] Change this section to mention contributors to your MIB module document.--></t>
</section>
<section title="Acknowledgements">
<t>Thanks to Marshall Rose for developing the XML2RFC format.</t>
<t><!--This acknowledgement can be removed from your MIB module document.--></t>
</section>
</middle>
<back>
<!-- References Section -->
<!-- Section 4.7f of [RFC2223bis] specifies the requirements for the
references sections. In particular, there MUST be separate lists of
normative and informative references, each in a separate section.
The style SHOULD follow that of recently published RFCs.
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-maintained 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
mentioned in the MIB boilerplate) are required to be mentioned (cf.
Section 3.2).
In general, each normative reference SHOULD point to the most recent
version of the specification in question.
-->
<references title="Normative References">
<!-- start of normative references that are required only to support
this template, and which can be removed from the final document, if not
used for other purposes. -->
&rfc2629;
&rfc2863;
&rfc3418;
&rfc4181;
<!-- end of normative references that are required only to support this template;
Remove from the final document. -->
<!-- start of normative references that are required to support MIB module boilerplate text. -->
&rfc2119;
&rfc2578;
&rfc2579;
&rfc2580;
<!-- end of references that are required to support the boilerplate text. -->
<!-- [TODO]: start of normative references samples. Replace with your own. -->
<!-- end of normative references samples. -->
</references>
<references title="Informative References">
<!-- start of informative references that are required to support the boilerplate text. -->
&rfc3410;
<!-- end of informative references that are required to support the boilerplate text. -->
</references>
<!--
<section anchor="appendix" title="Appendix A">
<t>You can add appendices just as regular sections, the only
difference is that they go under "back" element, and get letters
instead of numbers</t>
</section>
-->
<section title="Change Log ">
<t>The following changes have been made from RFC BBBB.</t>
<t>[TODO] replace this list with your own list</t>
<t><list style="numbers">
<t>Updated the introductionary boilerplate text, the security
considerations section and the references to comply with the current
IETF standards and guidelines.</t>
<t>Additions and clarifications in various description clauses.</t>
</list></t>
</section>
<section title="Open Issues">
<t>[TODO] This list of open issues should be cleared and removed before
this document hits the IESG.</t>
<t><list style="numbers">
<t>Contributor addresses need to be updated</t>
</list></t>
</section>
<!--
$Log: draft-harrington-xml2rfc-mib-template.xml,v $
Revision 1.10 2006/06/15 13:11:34 H73653
-00- internet-draft
made it a mib-doc-template rather than a mib-template
Revision 1.9 2006/06/14 17:32:11 H73653
saved from XXE, and reflects XXE automatic changes to formatting.
Revision 1.8 2006/04/24 23:37:55 H73653
changed from cvs header to cvs id to eliminate directory differences
Revision 1.7 2006/04/24 15:52:16 H73653
started -02- revision
Revision 1.6 2006/04/01 04:14:49 dbh
misc fixes
Revision 1.5 2005/12/24 05:35:21 dbh
pretty printed the XML
Revision 1.4 2005/12/20 00:09:39 dbh
submitted to mreview for Last Call. Runs cleanly through Bill's validator, and the production and dev versions of xml2rfc. Also aubmitted the output file produced by the web service from this source file. Note that the rfcedstyle is disabled because the directive is only available in the "bleeding edge" version.
place for source control log here
-->
</back>
</rfc>
Internet Engineering Task Force D. Harrington, Ed.
Internet-Draft Huawei Technologies (USA)
Intended status: Best Current June 15, 2006
Practice
Expires: December 17, 2006
A Template for Documents Containing a MIB Module
draft-harrington-text-mib-doc-template-00.txt
Status of This Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on December 17, 2006.
Copyright Notice
Copyright (C) The Internet Society (2006).
Abstract
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].
Foreword to template users
This template helps authors write the surrounding text needed in a
Harrington Expires December 17, 2006 [Page 1]
Internet-Draft MIB Module Document Text Template June 2006
MIB module document, but does not provide a template for writing the
MIB module itself.
The [TODO] markers throughuot the text are for the authors to fill in.
For updated information on MIB module guidelines and templates, see
[RFC4181] and http://www.ops.ietf.org/.
For information on writing internet drafts or RFCs, see
http://www.ietf.org/ietf/1id-guidelines.txt and RFC2223(bis), and
look at http://www.ietf.org/ID-Checklist.html for issues to note when
writing drafts.
This template is not meant to be a conclusive list of everything
needed to write MIB module documents, but to summarize the often-
needed basic features to get a document containing a MIB module
started. An important purpose of the template is to aid authors in
developing a document that is laid out in a manner consistent with
other documents containing MIB modules. Documents submitted for
advancement to the standards track typically require review by a MIB
Doctor. This template standardizes the layout and naming of
sections, includes the appropriate boilerplate text, and facilitates
the development of tools to automate the checking of MIB module
documents, to speed the WG and IESG review processes.
An XML template is also available. For information on XML2RFC, see
RFC2629 [RFC2629],
http://xml.resource.org/public/rfc/html/rfc2629.html and "bis":
http://xml.resource.org/authoring/draft-mrose-writing-rfcs.html.
Also see http://xml.resource.org/authoring/README.html for 'rfc'
option strings. The benefit of using the XML version of the template
is that comments in the XML describe how to fill in each section of
the template, and then XML2RFC will generate the actual internet-
draft with your information. XML2RFC automatically handles much of
the boilerplate, references, and idnits issues for you.
[TODO]: please remove this Note prior to publication.
Harrington Expires December 17, 2006 [Page 2]
Internet-Draft MIB Module Document Text Template June 2006
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. The Internet-Standard Management Framework . . . . . . . . . . 4
3. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
5. Structure of the MIB Module . . . . . . . . . . . . . . . . . . 4
5.1. Textual Conventions . . . . . . . . . . . . . . . . . . . . 4
5.2. The [TODO] Subtree . . . . . . . . . . . . . . . . . . . . 4
5.3. The Notifications Subtree . . . . . . . . . . . . . . . . . 4
6. Relationship to Other MIB Modules . . . . . . . . . . . . . . . 4
6.1. Relationship to the SNMPv2-MIB . . . . . . . . . . . . . . 5
6.2. Relationship to the IF-MIB . . . . . . . . . . . . . . . . 5
6.3. MIB modules required for IMPORTS . . . . . . . . . . . . . 5
7. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . 5
8. Security Considerations . . . . . . . . . . . . . . . . . . . . 5
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 6
10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 7
11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 7
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7
12.1. Normative References . . . . . . . . . . . . . . . . . . . 7
12.2. Informative References . . . . . . . . . . . . . . . . . . 8
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . . 8
Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . . 8
Harrington Expires December 17, 2006 [Page 3]
Internet-Draft MIB Module Document Text Template June 2006
1. Introduction
This memo defines a portion of the Management Information Base (MIB)
for use with network management protocols. In particular it defines
objects for managing the [TODO]
2. The Internet-Standard Management Framework
For a detailed overview of the documents that describe the current
Internet-Standard Management Framework, please refer to section 7 of
RFC 3410 [RFC3410].
Managed objects are accessed via a virtual information store, termed
the Management Information Base or MIB. MIB objects are generally
accessed through the Simple Network Management Protocol (SNMP).
Objects in the MIB are defined using the mechanisms defined in the
Structure of Management Information (SMI). This memo specifies a MIB
module that is compliant to the SMIv2, which is described in STD 58,
RFC 2578 [RFC2578], STD 58, RFC 2579 [RFC2579] and STD 58, RFC 2580
[RFC2580].
3. Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119].
4. Overview
5. Structure of the MIB Module
5.1. Textual Conventions
5.2. The [TODO] Subtree
5.3. The Notifications Subtree
6. Relationship to Other MIB Modules
Some management objects defined in other MIB modules are applicable
to an entity implementing this MIB. In particular, it is assumed
that an entity implementing the SAMPLE-MIB module will also implement
the 'system' group of the SNMPv2-MIB [RFC3418] and the 'interfaces'
group of the IF-MIB [RFC2863].
Harrington Expires December 17, 2006 [Page 4]
Internet-Draft MIB Module Document Text Template June 2006
6.1. Relationship to the SNMPv2-MIB
The 'system' group in the SNMPv2-MIB [RFC3418] is defined as being
mandatory for all systems, and the objects apply to the entity as a
whole. The 'system' group provides identification of the management
entity and certain other system-wide data. The SAMPLE-MIB does not
duplicate those objects.
6.2. Relationship to the IF-MIB
The Interface MIB [RFC2863] requires that any MIB module which is an
adjunct of the Interface MIB clarify specific areas within the
Interface MIB. These areas were intentionally left vague in the
Interface MIB to avoid over constraining the MIB, thereby precluding
management of certain media-types.
Section 4 of [RFC2863] enumerates several areas which a media-
specific MIB must clarify. The implementor is referred to [RFC2863]
in order to understand the general intent of these areas.
6.3. MIB modules required for IMPORTS
The following MIB module IMPORTS objects from SNMPv2-SMI [RFC2578],
SNMPv2-TC [RFC2579], SNMPv2-CONF [RFC2580], and IF-MIB [RFC2863]
7. Definitions
8. Security Considerations
There are a number of management objects defined in this MIB module
with a MAX-ACCESS clause of read-write and/or read-create. Such
objects may be considered sensitive or vulnerable in some network
environments. The support for SET operations in a non-secure
environment without proper protection can have a negative effect on
network operations. These are the tables and objects and their
sensitivity/vulnerability:
o [TODO] list the writable tables and objects and state why they are
sensitive.
There are no management objects defined in this MIB module that have
a MAX-ACCESS clause of read-write and/or read-create. So, if this
MIB module is implemented correctly, then there is no risk that an
intruder can alter or create any management objects of this MIB
Harrington Expires December 17, 2006 [Page 5]
Internet-Draft MIB Module Document Text Template June 2006
module via direct SNMP SET operations.
Some of the readable objects in this MIB module (i.e., objects with a
MAX-ACCESS other than not-accessible) may be considered sensitive or
vulnerable in some network environments. It is thus important to
control even GET and/or NOTIFY access to these objects and possibly
to even encrypt the values of these objects when sending them over
the network via SNMP. These are the tables and objects and their
sensitivity/vulnerability:
o [TODO] list the tables and objects and state why they are
sensitive.
SNMP versions prior to SNMPv3 did not include adequate security.
Even if the network itself is secure (for example by using IPSec),
even then, there is no control as to who on the secure network is
allowed to access and GET/SET (read/change/create/delete) the objects
in this MIB module.
It is RECOMMENDED that implementers consider the security features as
provided by the SNMPv3 framework (see [RFC3410], section 8),
including full support for the SNMPv3 cryptographic mechanisms (for
authentication and privacy).
Further, deployment of SNMP versions prior to SNMPv3 is NOT
RECOMMENDED. Instead, it is RECOMMENDED to deploy SNMPv3 and to
enable cryptographic security. It is then a customer/operator
responsibility to ensure that the SNMP entity giving access to an
instance of this MIB module is properly configured to give access to
the objects only to those principals (users) that have legitimate
rights to indeed GET or SET (change/create/delete) them.
9. IANA Considerations
[TODO} select an option and provide the necessary details.
Option #1:
Harrington Expires December 17, 2006 [Page 6]
Internet-Draft MIB Module Document Text Template June 2006
The MIB module in this document uses the following IANA-assigned
OBJECT IDENTIFIER values recorded in the SMI Numbers registry:
Descriptor OBJECT IDENTIFIER value
---------- -----------------------
sampleMIB { mib-2 XXX }
Option #2:
Editor's Note (to be removed prior to publication): the IANA is
requested to assign a value for "XXX" under the 'mib-2' subtree and
to record the assignment in the SMI Numbers registry. When the
assignment has been made, the RFC Editor is asked to replace "XXX"
(here and in the MIB module) with the assigned value and to remove
this note.
Note well: prior to official assignment by the IANA, a draft document
MUST use placeholders (such as "XXX" above) rather than actual
numbers. See RFC4181 Section 4.5 for an example of how this is done
in a draft MIB module.
Option #3:
This memo includes no request to IANA.
10. Contributors
This template is based on contributions from the MIb Doctors,
especially Juergen Schoenwaelder, Dave Perkins, C.M.Heard and Randy
Presuhn.
11. Acknowledgements
Thanks to Marshall Rose for developing the XML2RFC format.
12. References
12.1. Normative References
[RFC2629] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629,
June 1999.
[RFC2863] McCloghrie, K. and F. Kastenholz, "The Interfaces Group
MIB", RFC 2863, June 2000.
[RFC3418] Presuhn, R., "Management Information Base (MIB) for the
Simple Network Management Protocol (SNMP)", STD 62,
Harrington Expires December 17, 2006 [Page 7]
Internet-Draft MIB Module Document Text Template June 2006
RFC 3418, December 2002.
[RFC4181] Heard, C., "Guidelines for Authors and Reviewers of MIB
Documents", BCP 111, RFC 4181, September 2005.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J.
Schoenwaelder, Ed., "Structure of Management Information
Version 2 (SMIv2)", STD 58, RFC 2578, April 1999.
[RFC2579] McCloghrie, K., Ed., Perkins, D., Ed., and J.
Schoenwaelder, Ed., "Textual Conventions for SMIv2",
STD 58, RFC 2579, April 1999.
[RFC2580] McCloghrie, K., Perkins, D., and J. Schoenwaelder,
"Conformance Statements for SMIv2", STD 58, RFC 2580,
April 1999.
12.2. Informative References
[RFC3410] Case, J., Mundy, R., Partain, D., and B. Stewart,
"Introduction and Applicability Statements for Internet-
Standard Management Framework", RFC 3410, December 2002.
Appendix A. Change Log
The following changes have been made from RFC BBBB.
[TODO] replace this list with your own list
1. Updated the introductionary boilerplate text, the security
considerations section and the references to comply with the
current IETF standards and guidelines.
2. Additions and clarifications in various description clauses.
Appendix B. Open Issues
[TODO] This list of open issues should be cleared and removed before
this document hits the IESG.
1. Contributor addresses need to be updated
Harrington Expires December 17, 2006 [Page 8]
Internet-Draft MIB Module Document Text Template June 2006
Author's Address
David Harrington (editor)
Huawei Technologies (USA)
1700 Alma Drive, Suite 100
Plano, TX 75075
USA
Phone: +1 603 436 8634
EMail: dharrington@huawei.com
Harrington Expires December 17, 2006 [Page 9]
Internet-Draft MIB Module Document Text Template June 2006
Full Copyright Statement
Copyright (C) The Internet Society (2006).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Acknowledgement
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
Harrington Expires December 17, 2006 [Page 10]