doc: Add RFC documents

1 files changed, 1459 insertions, 0 deletions

diff --git a/doc/rfc/rfc6087.txt b/doc/rfc/rfc6087.txt
new file mode 100644
index 0000000..f24d909
--- /dev/null
+++ b/doc/rfc/rfc6087.txt
@@ -0,0 +1,1459 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF)                        A. Bierman
+Request for Comments: 6087                                       Brocade
+Category: Informational                                     January 2011
+ISSN: 2070-1721
+
+
+   Guidelines for Authors and Reviewers of YANG Data Model Documents
+
+Abstract
+
+   This memo provides guidelines for authors and reviewers of Standards
+   Track specifications containing YANG data model modules.  Applicable
+   portions may be used as a basis for reviews of other YANG data model
+   documents.  Recommendations and procedures are defined, which are
+   intended to increase interoperability and usability of Network
+   Configuration Protocol (NETCONF) implementations that utilize YANG
+   data model modules.
+
+Status of This Memo
+
+   This document is not an Internet Standards Track specification; it is
+   published for informational purposes.
+
+   This document is a product of the Internet Engineering Task Force
+   (IETF).  It represents the consensus of the IETF community.  It has
+   received public review and has been approved for publication by the
+   Internet Engineering Steering Group (IESG).  Not all documents
+   approved by the IESG are a candidate for any level of Internet
+   Standard; see Section 2 of RFC 5741.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   http://www.rfc-editor.org/info/rfc6087.
+
+Copyright Notice
+
+   Copyright (c) 2011 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   This document is subject to BCP 78 and the IETF Trust's Legal
+   Provisions Relating to IETF Documents
+   (http://trustee.ietf.org/license-info) in effect on the date of
+   publication of this document.  Please review these documents
+   carefully, as they describe your rights and restrictions with respect
+   to this document.  Code Components extracted from this document must
+   include Simplified BSD License text as described in Section 4.e of
+   the Trust Legal Provisions and are provided without warranty as
+   described in the Simplified BSD License.
+
+
+
+Bierman                       Informational                     [Page 1]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+Table of Contents
+
+   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
+   2.  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  3
+     2.1.  Requirements Notation  . . . . . . . . . . . . . . . . . .  3
+     2.2.  NETCONF Terms  . . . . . . . . . . . . . . . . . . . . . .  4
+     2.3.  YANG Terms . . . . . . . . . . . . . . . . . . . . . . . .  4
+     2.4.  Terms  . . . . . . . . . . . . . . . . . . . . . . . . . .  4
+   3.  General Documentation Guidelines . . . . . . . . . . . . . . .  5
+     3.1.  Module Copyright . . . . . . . . . . . . . . . . . . . . .  5
+     3.2.  Narrative Sections . . . . . . . . . . . . . . . . . . . .  6
+     3.3.  Definitions Section  . . . . . . . . . . . . . . . . . . .  6
+     3.4.  Security Considerations Section  . . . . . . . . . . . . .  6
+     3.5.  IANA Considerations Section  . . . . . . . . . . . . . . .  7
+       3.5.1.  Documents that Create a New Namespace  . . . . . . . .  7
+       3.5.2.  Documents that Extend an Existing Namespace  . . . . .  8
+     3.6.  Reference Sections . . . . . . . . . . . . . . . . . . . .  8
+   4.  YANG Usage Guidelines  . . . . . . . . . . . . . . . . . . . .  8
+     4.1.  Module Naming Conventions  . . . . . . . . . . . . . . . .  8
+     4.2.  Identifiers  . . . . . . . . . . . . . . . . . . . . . . .  9
+     4.3.  Defaults . . . . . . . . . . . . . . . . . . . . . . . . .  9
+     4.4.  Conditional Statements . . . . . . . . . . . . . . . . . . 10
+     4.5.  XPath Usage  . . . . . . . . . . . . . . . . . . . . . . . 10
+     4.6.  Lifecycle Management . . . . . . . . . . . . . . . . . . . 11
+     4.7.  Module Header, Meta, and Revision Statements . . . . . . . 12
+     4.8.  Namespace Assignments  . . . . . . . . . . . . . . . . . . 13
+     4.9.  Top-Level Data Definitions . . . . . . . . . . . . . . . . 14
+     4.10. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 14
+     4.11. Reusable Type Definitions  . . . . . . . . . . . . . . . . 15
+     4.12. Data Definitions . . . . . . . . . . . . . . . . . . . . . 15
+     4.13. Operation Definitions  . . . . . . . . . . . . . . . . . . 17
+     4.14. Notification Definitions . . . . . . . . . . . . . . . . . 17
+   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 17
+   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 18
+     6.1.  Security Considerations Section Template . . . . . . . . . 19
+   7.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 20
+   8.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 20
+     8.1.  Normative References . . . . . . . . . . . . . . . . . . . 20
+     8.2.  Informative References . . . . . . . . . . . . . . . . . . 21
+   Appendix A.  Module Review Checklist . . . . . . . . . . . . . . . 22
+   Appendix B.  YANG Module Template  . . . . . . . . . . . . . . . . 24
+
+
+
+
+
+
+
+
+
+
+Bierman                       Informational                     [Page 2]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+1.  Introduction
+
+   The standardization of network configuration interfaces for use with
+   the Network Configuration Protocol (NETCONF) [RFC4741] requires a
+   modular set of data models, which can be reused and extended over
+   time.
+
+   This document defines a set of usage guidelines for Standards Track
+   documents containing YANG [RFC6020] data models.  YANG is used to
+   define the data structures, protocol operations, and notification
+   content used within a NETCONF server.  A server that supports a
+   particular YANG module will support client NETCONF operation
+   requests, as indicated by the specific content defined in the YANG
+   module.
+
+   This document is similar to the Structure of Management Information
+   version 2 (SMIv2) usage guidelines specification [RFC4181] in intent
+   and structure.  However, since that document was written a decade
+   after SMIv2 modules had been in use, it was published as a 'Best
+   Current Practice' (BCP).  This document is not a BCP, but rather an
+   informational reference, intended to promote consistency in documents
+   containing YANG modules.
+
+   Many YANG constructs are defined as optional to use, such as the
+   description statement.  However, in order to maximize
+   interoperability of NETCONF implementations utilizing YANG data
+   models, it is desirable to define a set of usage guidelines that may
+   require a higher level of compliance than the minimum level defined
+   in the YANG specification.
+
+   In addition, YANG allows constructs such as infinite length
+   identifiers and string values, or top-level mandatory nodes, that a
+   compliant server is not required to support.  Only constructs that
+   all servers are required to support can be used in IETF YANG modules.
+
+   This document defines usage guidelines related to the NETCONF
+   operations layer and NETCONF content layer, as defined in [RFC4741].
+   These guidelines are intended to be used by authors and reviewers to
+   improve the readability and interoperability of published YANG data
+   models.
+
+2.  Terminology
+
+2.1.  Requirements Notation
+
+   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 [RFC2119].
+
+
+
+Bierman                       Informational                     [Page 3]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+   RFC 2119 language is used here to express the views of the NETMOD
+   working group regarding content for YANG modules.  YANG modules
+   complying with this document will treat the RFC 2119 terminology as
+   if it were describing best current practices.
+
+2.2.  NETCONF Terms
+
+   The following terms are defined in [RFC4741] and are not redefined
+   here:
+
+   o  capabilities
+
+   o  client
+
+   o  operation
+
+   o  server
+
+2.3.  YANG Terms
+
+   The following terms are defined in [RFC6020] and are not redefined
+   here:
+
+   o  data node
+
+   o  module
+
+   o  namespace
+
+   o  submodule
+
+   o  version
+
+   o  YANG
+
+   o  YIN
+
+   Note that the term 'module' may be used as a generic term for a YANG
+   module or submodule.  When describing properties that are specific to
+   submodules, the term 'submodule' is used instead.
+
+2.4.  Terms
+
+   The following terms are used throughout this document:
+
+   published:  A stable release of a module or submodule, usually
+      contained in an RFC.
+
+
+
+
+Bierman                       Informational                     [Page 4]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+   unpublished:  An unstable release of a module or submodule, usually
+      contained in an Internet-Draft.
+
+3.  General Documentation Guidelines
+
+   YANG data model modules under review are likely to be contained in
+   Internet-Drafts.  All guidelines for Internet-Draft authors MUST be
+   followed.  The RFC Editor provides guidelines for authors of RFCs,
+   which are first published as Internet-Drafts.  These guidelines
+   should be followed and are defined in [RFC2223] and updated in
+   [RFC5741] and "RFC Document Style" [RFC-STYLE].
+
+   The following sections MUST be present in an Internet-Draft
+   containing a module:
+
+   o  Narrative sections
+
+   o  Definitions section
+
+   o  Security Considerations section
+
+   o  IANA Considerations section
+
+   o  References section
+
+3.1.  Module Copyright
+
+   The module description statement MUST contain a reference to the
+   latest approved IETF Trust Copyright statement, which is available
+   online at:
+
+   http://trustee.ietf.org/license-info/
+
+   Each YANG module or submodule contained within an Internet-Draft or
+   RFC is considered to be a code component.  The strings '<CODE
+   BEGINS>' and '<CODE ENDS>' MUST be used to identify each code
+   component.
+
+   The '<CODE BEGINS>' tag SHOULD be followed by a string identifying
+   the file name specified in Section 5.2 of [RFC6020].  The following
+   example is for the '2010-01-18' revision of the 'ietf-foo' module:
+
+
+
+
+
+
+
+
+
+
+Bierman                       Informational                     [Page 5]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+   <CODE BEGINS> file "ietf-foo@2010-01-18.yang"
+   module ietf-foo {
+       // ...
+      revision 2010-01-18 {
+         description "Latest revision";
+         reference "RFC XXXX";
+      }
+      // ...
+   }
+   <CODE ENDS>
+
+3.2.  Narrative Sections
+
+   The narrative part MUST include an overview section that describes
+   the scope and field of application of the module(s) defined by the
+   specification and that specifies the relationship (if any) of these
+   modules to other standards, particularly to standards containing
+   other YANG modules.  The narrative part SHOULD include one or more
+   sections to briefly describe the structure of the modules defined in
+   the specification.
+
+   If the module(s) defined by the specification imports definitions
+   from other modules (except for those defined in the YANG [RFC6020] or
+   YANG Types [RFC6021] documents), or are always implemented in
+   conjunction with other modules, then those facts MUST be noted in the
+   overview section, as MUST be noted any special interpretations of
+   definitions in other modules.
+
+3.3.  Definitions Section
+
+   This section contains the module(s) defined by the specification.
+   These modules MUST be written using the YANG syntax defined in
+   [RFC6020].  A YIN syntax version of the module MAY also be present in
+   the document.  There MAY also be other types of modules present in
+   the document, such as SMIv2, which are not affected by these
+   guidelines.
+
+   See Section 4 for guidelines on YANG usage.
+
+3.4.  Security Considerations Section
+
+   Each specification that defines one or more 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/netconf/yang-security-considerations.txt).
+
+
+
+Bierman                       Informational                     [Page 6]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+   Section 6.1 contains the security considerations template dated
+   2010-06-16.  Authors MUST check the webpage at the URL listed above
+   in case there is a more recent version available.
+
+   In particular:
+
+   o  Writable data nodes that could be especially disruptive if abused
+      MUST be explicitly listed by name and the associated security
+      risks MUST be explained.
+
+   o  Readable data nodes that contain especially sensitive information
+      or that raise significant privacy concerns MUST be explicitly
+      listed by name and the reasons for the sensitivity/privacy
+      concerns MUST be explained.
+
+   o  Operations (i.e., YANG 'rpc' statements) that are potentially
+      harmful to system behavior or that raise significant privacy
+      concerns MUST be explicitly listed by name and the reasons for the
+      sensitivity/privacy concerns MUST be explained.
+
+3.5.  IANA Considerations Section
+
+   In order to comply with IESG policy as set forth in
+   http://www.ietf.org/id-info/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 on what actions are required of the IANA.  If there are no
+   IANA considerations applicable to the document, then the IANA
+   Considerations section stating that there are no actions is removed
+   by the RFC Editor before publication.  Refer to the guidelines in
+   [RFC5226] for more details.
+
+3.5.1.  Documents that Create a New Namespace
+
+   If an Internet-Draft defines a new namespace that is to be
+   administered by the IANA, then the document MUST include an IANA
+   Considerations section that specifies how the namespace is to be
+   administered.
+
+   Specifically, if any YANG module namespace statement value contained
+   in the document is not already registered with IANA, then a new YANG
+   Namespace registry entry MUST be requested from the IANA.  The YANG
+   [RFC6020] specification includes the procedure for this purpose in
+   its IANA Considerations section.
+
+
+
+
+
+
+
+Bierman                       Informational                     [Page 7]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+3.5.2.  Documents that Extend an Existing Namespace
+
+   It is possible to extend an existing namespace using a YANG submodule
+   that belongs to an existing module already administered by IANA.  In
+   this case, the document containing the main module MUST be updated to
+   use the latest revision of the submodule.
+
+3.6.  Reference Sections
+
+   For every import or include statement that appears in a module
+   contained in the specification, which identifies a module in a
+   separate document, a corresponding normative reference to that
+   document MUST appear in the Normative References section.  The
+   reference MUST correspond to the specific module version actually
+   used within the specification.
+
+   For every normative reference statement that appears in a module
+   contained in the specification, which identifies a separate document,
+   a corresponding normative reference to that document SHOULD appear in
+   the Normative References section.  The reference SHOULD correspond to
+   the specific document version actually used within the specification.
+   If the reference statement identifies an informative reference, which
+   identifies a separate document, a corresponding informative reference
+   to that document MAY appear in the Informative References section.
+
+4.  YANG Usage Guidelines
+
+   In general, modules in IETF Standards Track specifications MUST
+   comply with all syntactic and semantic requirements of YANG
+   [RFC6020].  The guidelines in this section are intended to supplement
+   the YANG specification, which is intended to define a minimum set of
+   conformance requirements.
+
+   In order to promote interoperability and establish a set of practices
+   based on previous experience, the following sections establish usage
+   guidelines for specific YANG constructs.
+
+   Only guidelines that clarify or restrict the minimum conformance
+   requirements are included here.
+
+4.1.  Module Naming Conventions
+
+   Modules contained in Standards Track documents SHOULD be named
+   according to the guidelines in the IANA Considerations section of
+   [RFC6020].
+
+
+
+
+
+
+Bierman                       Informational                     [Page 8]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+   A distinctive word or acronym (e.g., protocol name or working group
+   acronym) SHOULD be used in the module name.  If new definitions are
+   being defined to extend one or more existing modules, then the same
+   word or acronym should be reused, instead of creating a new one.
+
+   All published module names MUST be unique.  For a YANG module
+   published in an RFC, this uniqueness is guaranteed by IANA.  For
+   unpublished modules, the authors need to check that no other work in
+   progress is using the same module name.
+
+   Once a module name is published, it MUST NOT be reused, even if the
+   RFC containing the module is reclassified to 'Historic' status.
+
+4.2.  Identifiers
+
+   Identifiers for all YANG identifiers in published modules MUST be
+   between 1 and 64 characters in length.  These include any construct
+   specified as an 'identifier-arg-str' token in the ABNF in Section 12
+   of [RFC6020].
+
+4.3.  Defaults
+
+   In general, it is suggested that substatements containing very common
+   default values SHOULD NOT be present.  The following substatements
+   are commonly used with the default value, which would make the module
+   difficult to read if used everywhere they are allowed.
+
+                     +---------------+---------------+
+                     | Statement     | Default Value |
+                     +---------------+---------------+
+                     | config        | true          |
+                     |               |               |
+                     | mandatory     | false         |
+                     |               |               |
+                     | max-elements  | unbounded     |
+                     |               |               |
+                     | min-elements  | 0             |
+                     |               |               |
+                     | ordered-by    | system        |
+                     |               |               |
+                     | status        | current       |
+                     |               |               |
+                     | yin-element   | false         |
+                     +---------------+---------------+
+
+
+
+
+
+
+
+Bierman                       Informational                     [Page 9]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+4.4.  Conditional Statements
+
+   A module may be conceptually partitioned in several ways, using the
+   'if-feature' and/or 'when' statements.
+
+   Data model designers need to carefully consider all modularity
+   aspects, including the use of YANG conditional statements.
+
+   If a data definition is optional, depending on server support for a
+   NETCONF protocol capability, then a YANG 'feature' statement SHOULD
+   be defined to indicate that the NETCONF capability is supported
+   within the data model.
+
+   If any notification data, or any data definition, for a non-
+   configuration data node is not mandatory, then the server may or may
+   not be required to return an instance of this data node.  If any
+   conditional requirements exist for returning the data node in a
+   notification payload or retrieval request, they MUST be documented
+   somewhere.  For example, a 'when' or 'if-feature' statement could
+   apply to the data node, or the conditional requirements could be
+   explained in a 'description' statement within the data node or one of
+   its ancestors (if any).
+
+4.5.  XPath Usage
+
+   This section describes guidelines for using the XML Path Language
+   [W3C.REC-xpath-19991116] (XPath) within YANG modules.
+
+   The 'attribute' and 'namespace' axes are not supported in YANG, and
+   MAY be empty in a NETCONF server implementation.
+
+   The 'position' and 'last' functions SHOULD NOT be used.  This applies
+   to implicit use of the 'position' function as well (e.g.,
+   '//chapter[42]').  A server is only required to maintain the relative
+   XML document order of all instances of a particular user-ordered list
+   or leaf-list.  The 'position' and 'last' functions MAY be used if
+   they are evaluated in a context where the context node is a user-
+   ordered 'list' or 'leaf-list'.
+
+   The 'preceding', and 'following' axes SHOULD NOT be used.  These
+   constructs rely on XML document order within a NETCONF server
+   configuration database, which may not be supported consistently or
+   produce reliable results across implementations.  Predicate
+   expressions based on static node properties (e.g., element name or
+   value, 'ancestor' or 'descendant' axes) SHOULD be used instead.  The
+   'preceding' and 'following' axes MAY be used if document order is not
+   relevant to the outcome of the expression (e.g., check for global
+   uniqueness of a parameter value).
+
+
+
+Bierman                       Informational                    [Page 10]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+   The 'preceding-sibling' and 'following-sibling' axes SHOULD NOT used.
+   A server is only required to maintain the relative XML document order
+   of all instances of a particular user-ordered list or leaf-list.  The
+   'preceding-sibling' and 'following-sibling' axes MAY be used if they
+   are evaluated in a context where the context node is a user-ordered
+   'list' or 'leaf-list'.
+
+   Data nodes that use the 'int64' and 'uint64' built-in type SHOULD NOT
+   be used within numeric expressions.  There are boundary conditions in
+   which the translation from the YANG 64-bit type to an XPath number
+   can cause incorrect results.  Specifically, an XPath 'double'
+   precision floating point number cannot represent very large positive
+   or negative 64-bit numbers because it only provides a total precision
+   of 53 bits.  The 'int64' and 'uint64' data types MAY be used in
+   numeric expressions if the value can be represented with no more than
+   53 bits of precision.
+
+   Data modelers need to be careful not to confuse the YANG value space
+   and the XPath value space.  The data types are not the same in both,
+   and conversion between YANG and XPath data types SHOULD be considered
+   carefully.
+
+   Explicit XPath data type conversions MAY be used (e.g., 'string',
+   'boolean', or 'number' functions), instead of implicit XPath data
+   type conversions.
+
+4.6.  Lifecycle Management
+
+   The status statement MUST be present if its value is 'deprecated' or
+   'obsolete'.
+
+   The module or submodule name MUST NOT be changed, once the document
+   containing the module or submodule is published.
+
+   The module namespace URI value MUST NOT be changed, once the document
+   containing the module is published.
+
+   The revision-date substatement within the imports statement SHOULD be
+   present if any groupings are used from the external module.
+
+   The revision-date substatement within the include statement SHOULD be
+   present if any groupings are used from the external submodule.
+
+   If submodules are used, then the document containing the main module
+   MUST be updated so that the main module revision date is equal or
+   more recent than the revision date of any submodule that is (directly
+   or indirectly) included by the main module.
+
+
+
+
+Bierman                       Informational                    [Page 11]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+4.7.  Module Header, Meta, and Revision Statements
+
+   For published modules, the namespace MUST be a globally unique URI,
+   as defined in [RFC3986].  This value is usually assigned by the IANA.
+
+   The organization statement MUST be present.  If the module is
+   contained in a document intended for Standards Track status, then the
+   organization SHOULD be the IETF working group chartered to write the
+   document.
+
+   The contact statement MUST be present.  If the module is contained in
+   a document intended for Standards Track status, then the working
+   group web and mailing information MUST be present, and the main
+   document author or editor contact information SHOULD be present.  If
+   additional authors or editors exist, their contact information MAY be
+   present.  In addition, the Area Director and other contact
+   information MAY be present.
+
+   The description statement MUST be present.  The appropriate IETF
+   Trust Copyright text MUST be present, as described in Section 3.1.
+
+   If the module relies on information contained in other documents,
+   which are not the same documents implied by the import statements
+   present in the module, then these documents MUST be identified in the
+   reference statement.
+
+   A revision statement MUST be present for each published version of
+   the module.  The revision statement MUST have a reference
+   substatement.  It MUST identify the published document that contains
+   the module.  Modules are often extracted from their original
+   documents, and it is useful for developers and operators to know how
+   to find the original source document in a consistent manner.  The
+   revision statement MAY have a description substatement.
+
+   Each new revision MUST include a revision date that is higher than
+   any other revision date in the module.  The revision date does not
+   need to be updated if the module contents do not change in the new
+   document revision.
+
+   It is acceptable to reuse the same revision statement within
+   unpublished versions (i.e., Internet-Drafts), but the revision date
+   MUST be updated to a higher value each time the Internet-Draft is re-
+   posted.
+
+
+
+
+
+
+
+
+Bierman                       Informational                    [Page 12]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+4.8.  Namespace Assignments
+
+   It is RECOMMENDED that only valid YANG modules be included in
+   documents, whether or not they are published yet.  This allows:
+
+   o  the module to compile correctly instead of generating disruptive
+      fatal errors.
+
+   o  early implementors to use the modules without picking a random
+      value for the XML namespace.
+
+   o  early interoperability testing since independent implementations
+      will use the same XML namespace value.
+
+   Until a URI is assigned by the IANA, a proposed namespace URI MUST be
+   provided for the namespace statement in a YANG module.  A value
+   SHOULD be selected that is not likely to collide with other YANG
+   namespaces.  Standard module names, prefixes, and URI strings already
+   listed in the YANG Module Registry MUST NOT be used.
+
+   A standard namespace statement value SHOULD have the following form:
+
+   <URN prefix string>:<module-name>
+
+   The following URN prefix string SHOULD be used for published and
+   unpublished YANG modules:
+
+   urn:ietf:params:xml:ns:yang:
+
+   The following example URNs would be valid temporary namespace
+   statement values for Standards Track modules:
+
+      urn:ietf:params:xml:ns:yang:ietf-netconf-partial-lock
+
+      urn:ietf:params:xml:ns:yang:ietf-netconf-state
+
+      urn:ietf:params:xml:ns:yang:ietf-netconf
+
+   Note that a different URN prefix string SHOULD be used for non-
+   Standards-Track modules.  The string SHOULD be selected according to
+   the guidelines in [RFC6020].
+
+   The following examples of non-Standards-Track modules are only
+   suggestions.  There are no guidelines for this type of URN in this
+   document:
+
+
+
+
+
+
+Bierman                       Informational                    [Page 13]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+      http://example.com/ns/example-interfaces
+
+      http://example.com/ns/example-system
+
+4.9.  Top-Level Data Definitions
+
+   There SHOULD only be one top-level data node defined in each YANG
+   module, if any data nodes are defined at all.
+
+   The top-level data organization SHOULD be considered carefully, in
+   advance.  Data model designers need to consider how the functionality
+   for a given protocol or protocol family will grow over time.
+
+   The names and data organization SHOULD reflect persistent
+   information, such as the name of a protocol.  The name of the working
+   group SHOULD NOT be used because this may change over time.
+
+   A mandatory database data definition is defined as a node that a
+   client must provide for the database to be valid.  The server is not
+   required to provide a value.
+
+   Top-level database data definitions MUST NOT be mandatory.  If a
+   mandatory node appears at the top level, it will immediately cause
+   the database to be invalid.  This can occur when the server boots or
+   when a module is loaded dynamically at runtime.
+
+4.10.  Data Types
+
+   Selection of an appropriate data type (i.e., built-in type, existing
+   derived type, or new derived type) is very subjective, and therefore
+   few requirements can be specified on that subject.
+
+   Data model designers SHOULD use the most appropriate built-in data
+   type for the particular application.
+
+   If extensibility of enumerated values is required, then the
+   'identityref' data type SHOULD be used instead of an enumeration or
+   other built-in type.
+
+   For string data types, if a machine-readable pattern can be defined
+   for the desired semantics, then one or more pattern statements SHOULD
+   be present.
+
+   For string data types, if the length of the string is required to be
+   bounded in all implementations, then a length statement MUST be
+   present.
+
+
+
+
+
+Bierman                       Informational                    [Page 14]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+   For numeric data types, if the values allowed by the intended
+   semantics are different than those allowed by the unbounded intrinsic
+   data type (e.g., 'int32'), then a range statement SHOULD be present.
+
+   The signed numeric data types (i.e., 'int8', 'int16', 'int32', and
+   'int64') SHOULD NOT be used unless negative values are allowed for
+   the desired semantics.
+
+   For 'enumeration' or 'bits' data types, the semantics for each 'enum'
+   or 'bit' SHOULD be documented.  A separate description statement
+   (within each 'enum' or 'bit' statement) SHOULD be present.
+
+4.11.  Reusable Type Definitions
+
+   If an appropriate derived type exists in any standard module, such as
+   [RFC6021], then it SHOULD be used instead of defining a new derived
+   type.
+
+   If an appropriate units identifier can be associated with the desired
+   semantics, then a units statement SHOULD be present.
+
+   If an appropriate default value can be associated with the desired
+   semantics, then a default statement SHOULD be present.
+
+   If a significant number of derived types are defined, and it is
+   anticipated that these data types will be reused by multiple modules,
+   then these derived types SHOULD be contained in a separate module or
+   submodule, to allow easier reuse without unnecessary coupling.
+
+   The description statement MUST be present.
+
+   If the type definition semantics are defined in an external document
+   (other than another YANG module indicated by an import statement),
+   then the reference statement MUST be present.
+
+4.12.  Data Definitions
+
+   The description statement MUST be present in the following YANG
+   statements:
+
+   o  anyxml
+
+   o  augment
+
+   o  choice
+
+   o  container
+
+
+
+
+Bierman                       Informational                    [Page 15]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+   o  extension
+
+   o  feature
+
+   o  grouping
+
+   o  identity
+
+   o  leaf
+
+   o  leaf-list
+
+   o  list
+
+   o  notification
+
+   o  rpc
+
+   o  typedef
+
+   If the data definition semantics are defined in an external document,
+   (other than another YANG module indicated by an import statement),
+   then a reference statement MUST be present.
+
+   The 'anyxml' construct may be useful to represent an HTML banner
+   containing markup elements, such as '<b>' and '</b>', and MAY be used
+   in such cases.  However, this construct SHOULD NOT be used if other
+   YANG data node types can be used instead to represent the desired
+   syntax and semantics.
+
+   If there are referential integrity constraints associated with the
+   desired semantics that can be represented with XPath, then one or
+   more 'must' statements SHOULD be present.
+
+   For list and leaf-list data definitions, if the number of possible
+   instances is required to be bounded for all implementations, then the
+   max-elements statements SHOULD be present.
+
+   If any 'must' or 'when' statements are used within the data
+   definition, then the data definition description statement SHOULD
+   describe the purpose of each one.
+
+
+
+
+
+
+
+
+
+
+Bierman                       Informational                    [Page 16]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+4.13.  Operation Definitions
+
+   If the operation semantics are defined in an external document (other
+   than another YANG module indicated by an import statement), then a
+   reference statement MUST be present.
+
+   If the operation impacts system behavior in some way, it SHOULD be
+   mentioned in the description statement.
+
+   If the operation is potentially harmful to system behavior in some
+   way, it MUST be mentioned in the Security Considerations section of
+   the document.
+
+4.14.  Notification Definitions
+
+   The description statement MUST be present.
+
+   If the notification semantics are defined in an external document
+   (other than another YANG module indicated by an import statement),
+   then a reference statement MUST be present.
+
+5.  IANA Considerations
+
+   This document registers one URI in the IETF XML registry [RFC3688].
+   The following registration has been made:
+
+   URI: urn:ietf:params:xml:ns:yang:ietf-template
+
+   Registrant Contact: The NETMOD WG of the IETF.
+
+   XML: N/A, the requested URI is an XML namespace.
+
+   Per this document, the following assignment has been made in the YANG
+   Module Names Registry for the YANG module template in Appendix B.
+
+       +---------------+-------------------------------------------+
+       | Field         | Value                                     |
+       +---------------+-------------------------------------------+
+       | Name          | ietf-template                             |
+       |               |                                           |
+       | Namespace     | urn:ietf:params:xml:ns:yang:ietf-template |
+       |               |                                           |
+       | Prefix        | temp                                      |
+       |               |                                           |
+       | Reference     | RFC 6087                                  |
+       +---------------+-------------------------------------------+
+
+
+
+
+
+Bierman                       Informational                    [Page 17]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+6.  Security Considerations
+
+   This document defines documentation guidelines for NETCONF content
+   defined with the YANG data modeling language.  The guidelines for how
+   to write a Security Considerations section for a YANG module are
+   defined in the online document
+
+   http://www.ops.ietf.org/netconf/yang-security-considerations.txt
+
+   This document does not introduce any new or increased security risks
+   into the management system.
+
+   The following section contains the security considerations template
+   dated 2010-06-16.  Be sure to check the webpage at the URL listed
+   above in case there is a more recent version available.
+
+   Each specification that defines one or more YANG 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/netconf/yang-security-considerations.txt).
+
+   In particular, writable data nodes that could be especially
+   disruptive if abused MUST be explicitly listed by name and the
+   associated security risks MUST be spelled out.
+
+   Similarly, readable data nodes that contain especially sensitive
+   information or that raise significant privacy concerns MUST be
+   explicitly listed by name and the reasons for the sensitivity/privacy
+   concerns MUST be explained.
+
+   Further, if new RPC operations have been defined, then the security
+   considerations of each new RPC operation MUST be explained.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bierman                       Informational                    [Page 18]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+6.1.  Security Considerations Section Template
+
+   X.  Security Considerations
+
+   The YANG module defined in this memo is designed to be accessed
+   via the NETCONF protocol [RFC4741].  The lowest NETCONF layer is
+   the secure transport layer and the mandatory-to-implement secure
+   transport is SSH [RFC4742].
+
+   -- if you have any writable data nodes (those are all the
+   -- "config true" nodes, and remember, that is the default)
+   -- describe their specific sensitivity or vulnerability.
+
+   There are a number of data nodes defined in this YANG module
+   which are writable/creatable/deletable (i.e., config true, which
+   is the default).  These data nodes may be considered sensitive
+   or vulnerable in some network environments.  Write operations
+   (e.g., edit-config) to these data nodes without proper protection
+   can have a negative effect on network operations.  These are
+   the subtrees and data nodes and their sensitivity/vulnerability:
+
+    <list subtrees and data nodes and state why they are sensitive>
+
+   -- for all YANG modules you must evaluate whether any readable data
+   -- nodes (those are all the "config false" nodes, but also all other
+   -- nodes, because they can also be read via operations like get or
+   -- get-config) are sensitive or vulnerable (for instance, if they
+   -- might reveal customer information or violate personal privacy
+   -- laws such as those of the European Union if exposed to
+   -- unauthorized parties)
+
+   Some of the readable data nodes in this YANG module may be
+   considered sensitive or vulnerable in some network environments.
+   It is thus important to control read access (e.g., via get,
+   get-config, or notification) to these data nodes.  These are the
+   subtrees and data nodes and their sensitivity/vulnerability:
+
+    <list subtrees and data nodes and state why they are sensitive>
+
+   -- if your YANG module has defined any rpc operations
+   -- describe their specific sensitivity or vulnerability.
+
+   Some of the RPC operations in this YANG module may be considered
+   sensitive or vulnerable in some network environments.  It is thus
+   important to control access to these operations.  These are the
+   operations and their sensitivity/vulnerability:
+
+    <list RPC operations and state why they are sensitive>
+
+
+
+Bierman                       Informational                    [Page 19]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+7.  Acknowledgments
+
+   The structure and contents of this document are adapted from
+   Guidelines for MIB Documents [RFC4181], by C. M. Heard.
+
+   The working group thanks Martin Bjorklund and Juergen Schoenwaelder
+   for their extensive reviews and contributions to this document.
+
+8.  References
+
+8.1.  Normative References
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+   [RFC2223]  Postel, J. and J. Reynolds, "Instructions to RFC Authors",
+              RFC 2223, October 1997.
+
+   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
+              January 2004.
+
+   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
+              Resource Identifier (URI): Generic Syntax", STD 66,
+              RFC 3986, January 2005.
+
+   [RFC4741]  Enns, R., "NETCONF Configuration Protocol", RFC 4741,
+              December 2006.
+
+   [RFC5378]  Bradner, S. and J. Contreras, "Rights Contributors Provide
+              to the IETF Trust", BCP 78, RFC 5378, November 2008.
+
+   [RFC5741]  Daigle, L., Kolkman, O., and IAB, "RFC Streams, Headers,
+              and Boilerplates", RFC 5741, December 2009.
+
+   [W3C.REC-xpath-19991116]
+              DeRose, S. and J. Clark, "XML Path Language (XPath)
+              Version 1.0", World Wide Web Consortium
+              Recommendation REC-xpath-19991116, November 1999,
+              <http://www.w3.org/TR/1999/REC-xpath-19991116>.
+
+   [RFC6020]  Bjorklund, M., "YANG - A Data Modeling Language for the
+              Network Configuration Protocol (NETCONF)", RFC 6020,
+              October 2010.
+
+   [RFC6021]  Schoenwaelder, J., "Common YANG Data Types", RFC 6021,
+              October 2010.
+
+
+
+
+
+Bierman                       Informational                    [Page 20]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+8.2.  Informative References
+
+   [RFC4181]  Heard, C., "Guidelines for Authors and Reviewers of MIB
+              Documents", BCP 111, RFC 4181, September 2005.
+
+   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
+              IANA Considerations Section in RFCs", BCP 26, RFC 5226,
+              May 2008.
+
+   [RFC-STYLE]
+              Braden, R., Ginoza, S., and A. Hagens, "RFC Document
+              Style", September 2009,
+              <http://www.rfc-editor.org/rfc-style-guide/rfc-style>.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bierman                       Informational                    [Page 21]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+Appendix A.  Module Review Checklist
+
+   This section is adapted from RFC 4181.
+
+   The purpose of a YANG module review is to review the YANG module both
+   for technical correctness and for adherence to IETF documentation
+   requirements.  The following checklist may be helpful when reviewing
+   an Internet-Draft:
+
+   1.  I-D Boilerplate -- verify that the draft contains the required
+       Internet-Draft boilerplate (see
+       http://www.ietf.org/id-info/guidelines.html), including the
+       appropriate statement to permit publication as an RFC, and that
+       I-D boilerplate does not contain references or section numbers.
+
+   2.  Abstract -- verify that the abstract does not contain references,
+       that it does not have a section number, and that its content
+       follows the guidelines in
+       http://www.ietf.org/id-info/guidelines.html.
+
+   3.  Copyright Notice -- verify that the draft has the appropriate
+       text regarding the rights that document contributers provide to
+       the IETF Trust [RFC5378].  Verify that it contains the full IETF
+       Trust copyright notice at the beginning of the document.  The
+       IETF Trust Legal Provisions (TLP) can be found at:
+
+       http://trustee.ietf.org/license-info/
+
+   4.  Security Considerations section -- verify that the draft uses the
+       latest approved template from the OPS area website (http://
+       www.ops.ietf.org/netconf/yang-security-considerations.txt) and
+       that the guidelines therein have been followed.
+
+   5.  IANA Considerations section -- this section must always be
+       present.  For each module within the document, ensure that the
+       IANA Considerations section contains entries for the following
+       IANA registries:
+
+       XML Namespace Registry:  Register the YANG module namespace.
+
+       YANG Module Registry:  Register the YANG module name, prefix,
+          namespace, and RFC number, according to the rules specified in
+          [RFC6020].
+
+   6.  References -- verify that the references are properly divided
+       between normative and informative references, that RFC 2119 is
+       included as a normative reference if the terminology defined
+       therein is used in the document, that all references required by
+
+
+
+Bierman                       Informational                    [Page 22]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+       the boilerplate are present, that all YANG modules containing
+       imported items are cited as normative references, and that all
+       citations point to the most current RFCs unless there is a valid
+       reason to do otherwise (for example, it is OK to include an
+       informative reference to a previous version of a specification to
+       help explain a feature included for backward compatibility).  Be
+       sure citations for all imported modules are present somewhere in
+       the document text (outside the YANG module).
+
+   7.  License -- verify that the draft contains the Simplified BSD
+       License in each YANG module or submodule.  Some guidelines
+       related to this requirement are described in Section 3.1.  Make
+       sure that the correct year is used in all copyright dates.  Use
+       the approved text from the latest Trust Legal Provisions (TLP)
+       document, which can be found at:
+
+       http://trustee.ietf.org/license-info/
+
+   8.  Other Issues -- check for any issues mentioned in
+       http://www.ietf.org/id-info/checklist.html that are not covered
+       elsewhere.
+
+   9.  Technical Content -- review the actual technical content for
+       compliance with the guidelines in this document.  The use of a
+       YANG module compiler is recommended when checking for syntax
+       errors.  A list of freely available tools and other information
+       can be found at:
+
+       http://trac.tools.ietf.org/wg/netconf/trac/wiki
+
+       Checking for correct syntax, however, is only part of the job.
+       It is just as important to actually read the YANG module document
+       from the point of view of a potential implementor.  It is
+       particularly important to check that description statements are
+       sufficiently clear and unambiguous to allow interoperable
+       implementations to be created.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bierman                       Informational                    [Page 23]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+Appendix B.  YANG Module Template
+
+<CODE BEGINS> file "ietf-template@2010-05-18.yang"
+
+module ietf-template {
+
+    // replace this string with a unique namespace URN value
+    namespace
+      "urn:ietf:params:xml:ns:yang:ietf-template";
+
+    // replace this string, and try to pick a unique prefix
+    prefix "temp";
+
+
+    // import statements here: e.g.,
+    // import ietf-yang-types { prefix yang; }
+    // import ietf-inet-types { prefix inet; }
+
+    // identify the IETF working group if applicable
+    organization
+       "IETF NETMOD (NETCONF Data Modeling Language) Working Group";
+
+    // update this contact statement with your info
+    contact
+       "WG Web:   <http://tools.ietf.org/wg/your-wg-name/>
+        WG List:  <mailto:your-wg-name@ietf.org>
+
+        WG Chair: your-WG-chair
+                  <mailto:your-WG-chair@example.com>
+
+        Editor:   your-name
+                  <mailto:your-email@example.com>";
+
+
+    // replace the first sentence in this description statement.
+    // replace the copyright notice with the most recent
+    // version, if it has been updated since the publication
+    // of this document
+    description
+     "This module defines a template for other YANG modules.
+
+      Copyright (c) <insert year> IETF Trust and the persons
+      identified as authors of the code.  All rights reserved.
+
+      Redistribution and use in source and binary forms, with or
+      without modification, is permitted pursuant to, and subject
+      to the license terms contained in, the Simplified BSD License
+      set forth in Section 4.c of the IETF Trust's Legal Provisions
+
+
+
+Bierman                       Informational                    [Page 24]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+      Relating to IETF Documents
+      (http://trustee.ietf.org/license-info).
+
+      This version of this YANG module is part of RFC XXXX; see
+      the RFC itself for full legal notices.";
+
+    // RFC Ed.: replace XXXX with actual RFC number and remove this note
+
+    reference "RFC XXXX";
+
+    // RFC Ed.: remove this note
+    // Note: extracted from RFC 6087
+
+
+    // replace '2010-05-18' with the module publication date
+    // The format is (year-month-day)
+    revision "2010-05-18" {
+      description
+        "Initial version";
+    }
+
+    // extension statements
+
+    // feature statements
+
+    // identity statements
+
+    // typedef statements
+
+    // grouping statements
+
+    // data definition statements
+
+    // augment statements
+
+    // rpc statements
+
+    // notification statements
+
+    // DO NOT put deviation statements in a published module
+
+}
+
+<CODE ENDS>
+
+
+
+
+
+
+
+Bierman                       Informational                    [Page 25]
+
+RFC 6087              Guidelines for YANG Documents         January 2011
+
+
+Author's Address
+
+   Andy Bierman
+   Brocade
+
+   EMail: andy.bierman@brocade.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bierman                       Informational                    [Page 26]
+