Internet DRAFT - draft-harrington-xml2rfc-mib-doc-template

draft-harrington-xml2rfc-mib-doc-template







Internet Engineering Task Force                       D. Harrington, Ed.
Internet-Draft                                 Huawei Technologies (USA)
Intended status: Best Current                              June 15, 2006
Practice
Expires: December 17, 2006


       An XML2RFC Template for Documents Containing a MIB Module
            draft-harrington-xml2rfc-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

   For updated information on MIB module guidelines and templates, see



Harrington              Expires December 17, 2006               [Page 1]

Internet-Draft        MIB Module Document Template             June 2006


   [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.

   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.

   You don't need to have any other tools than a 'notepad' or your
   favourite editor to write xml2rfc drafts.  You can use the web
   interface at http://xml.resource.org for processing.  The benefit of
   using xml editors is mostly catching those missing tags which the
   processor will warn you about, but you don't need to worry about the
   editors when getting started.

   This xml2rfc template is not meant to be a conclusive list of
   everything, but 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, including the appropriate
   boilerplate text, to facilitate the development of tools to automate
   the checking of MIB module documents, to speed the WG and IESG review
   processes.

   [TODO]: please remove this Note prior to publication.


















Harrington              Expires December 17, 2006               [Page 2]

Internet-Draft        MIB Module Document 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 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 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 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 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 xml2rfc template is based on an xml2rfc template prepared by
   Pekka Savola, and 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 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 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 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]