Internet Engineering Task Force D. Harrington, Ed.
Internet-Draft Huawei Technologies (USA)
Intended status: Best Current January 8, 2007
Practice
Expires: July 12, 2007
A Template for Documents Containing a MIB Module
draft-harrington-text-mib-doc-template-02
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 July 12, 2007.
Copyright Notice
Copyright (C) The IETF Trust (2007).
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].
[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,
Harrington Expires July 12, 2007 [Page 1]
Internet-Draft MIB Module Document Text Template January 2007
or a particular goal of the module. But keep it brief.
Note: Forward to RFC Editor
Note to RFC Editor - throughout this template, there are numerouse
sample "Note to RFC Editor" that should NOT be removed from this
template before publication of the template. These need to retain
the "Note to RFC Editor" format to match the boilerplate included in
the template.
For simplicity, there are NO notes to the RFC Editor in this document
that should be removed, except THIS section - the complete section
entitled "Note: Foreward to RFC Editor".
Note: Foreword to template users
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.
Throughout this template, the marker "[TODO]" is used as a reminder
to the template user to indicate an element or text that requires
replacement or removal by the template user before submission to the
internet draft editor. All [TODO] markers should be resolved and
removed before you submit your document to the internet-draft editor.
[TODO] THIS section, the complete section entitled "Note: Foreward to
template users" should be removed by the template user from their
document before submission.
[TODO] Remove all page headings from the template document, and
replace them with the appropriate headings for your document.
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
Harrington Expires July 12, 2007 [Page 2]
Internet-Draft MIB Module Document Text Template January 2007
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 July 12, 2007 [Page 3]
Internet-Draft MIB Module Document Text Template January 2007
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
2. The Internet-Standard Management Framework . . . . . . . . . . 5
3. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 5
4. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5. Structure of the MIB Module . . . . . . . . . . . . . . . . . 5
5.1. Textual Conventions . . . . . . . . . . . . . . . . . . . 5
5.2. The [TODO] Subtree . . . . . . . . . . . . . . . . . . . . 5
5.3. The Notifications Subtree . . . . . . . . . . . . . . . . 6
6. Relationship to Other MIB Modules . . . . . . . . . . . . . . 6
6.1. Relationship to the SNMPv2-MIB . . . . . . . . . . . . . . 6
6.2. Relationship to the IF-MIB . . . . . . . . . . . . . . . . 6
6.3. MIB modules required for IMPORTS . . . . . . . . . . . . . 7
7. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 7
8. Security Considerations . . . . . . . . . . . . . . . . . . . 7
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
10. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 10
11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 10
12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10
12.1. Normative References . . . . . . . . . . . . . . . . . . . 10
12.2. Informative References . . . . . . . . . . . . . . . . . . 11
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 11
Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . . 11
Harrington Expires July 12, 2007 [Page 4]
Internet-Draft MIB Module Document Text Template January 2007
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
[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
5. 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.
5.1. Textual Conventions
5.2. The [TODO] Subtree
[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.
Harrington Expires July 12, 2007 [Page 5]
Internet-Draft MIB Module Document Text Template January 2007
5.3. The Notifications Subtree
[TODO] describe the notifications defined in the MIB module, and
their purpose.
6. 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.
[TODO] If the MIB modules defined by the specification import
definitions from other MIB modules 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.
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].
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
[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.
The Interface MIB [RFC2863] requires that any MIB module which is an
Harrington Expires July 12, 2007 [Page 6]
Internet-Draft MIB Module Document Text Template January 2007
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
[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.
The following MIB module IMPORTS objects from SNMPv2-SMI [RFC2578],
SNMPv2-TC [RFC2579], SNMPv2-CONF [RFC2580], and IF-MIB [RFC2863]
7. Definitions
[TODO]: put your valid MIB module here. A list of MIB verification
tools is available at http://tools.ietf.org/
8. Security Considerations
[TODO] 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.
[TODO] if you have any read-write and/or read-create objects, please
include the following boilerplate paragraph.
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
Harrington Expires July 12, 2007 [Page 7]
Internet-Draft MIB Module Document Text Template January 2007
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] 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.
[TODO] else if there are no read-write objects in your MIB module,
use the following boilerplate paragraph.
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.
[TODO] if you have any sensitive readable objects, please include the
following boilerplate paragraph.
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] 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)
o [TODO] list the tables and objects and state why they are
sensitive.
[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.
Harrington Expires July 12, 2007 [Page 8]
Internet-Draft MIB Module Document Text Template January 2007
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] 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.
[TODO} select an option and provide the necessary details.
Option #1:
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"
Harrington Expires July 12, 2007 [Page 9]
Internet-Draft MIB Module Document Text Template January 2007
(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.
[TODO]This acknowledgement can be removed from your MIB module
document.
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,
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.
Harrington Expires July 12, 2007 [Page 10]
Internet-Draft MIB Module Document Text Template January 2007
[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 draft-xxx-xxx-xxx-12 .
[TODO] replace this list with your own list
1. Updated the introductry 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
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 July 12, 2007 [Page 11]
Internet-Draft MIB Module Document Text Template January 2007
Full Copyright Statement
Copyright (C) The IETF Trust (2007).
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, THE IETF TRUST 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 July 12, 2007 [Page 12]
