--- 1/draft-ietf-netmod-rfc6087bis-15.txt 2018-01-18 14:13:33.840185443 -0800 +++ 2/draft-ietf-netmod-rfc6087bis-16.txt 2018-01-18 14:13:33.956188214 -0800 @@ -1,19 +1,19 @@ Network Working Group A. Bierman Internet-Draft YumaWorks -Obsoletes: 6087 (if approved) December 18, 2017 +Obsoletes: 6087 (if approved) January 18, 2018 Intended status: BCP -Expires: June 21, 2018 +Expires: July 22, 2018 Guidelines for Authors and Reviewers of YANG Data Model Documents - draft-ietf-netmod-rfc6087bis-15 + draft-ietf-netmod-rfc6087bis-16 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) and RESTCONF protocol implementations that utilize YANG data model modules. This document @@ -27,201 +27,249 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. 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." - This Internet-Draft will expire on June 21, 2018. + This Internet-Draft will expire on July 22, 2018. Copyright Notice - Copyright (c) 2017 IETF Trust and the persons identified as the + Copyright (c) 2018 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 - 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 6 - 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 6 - 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 6 - 2.4. NMDA Terms . . . . . . . . . . . . . . . . . . . . . . . . 7 - 2.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 7 - 2.5.1. YANG Tree Diagrams . . . . . . . . . . . . . . . . . . 7 - 3. General Documentation Guidelines . . . . . . . . . . . . . . . 8 - 3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 8 - 3.2. Code Components . . . . . . . . . . . . . . . . . . . . . 8 - 3.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 9 - 3.3. Terminology Section . . . . . . . . . . . . . . . . . . . 9 - 3.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 10 - 3.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 10 - 3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 10 - 3.7. Security Considerations Section . . . . . . . . . . . . . 11 - 3.8. IANA Considerations Section . . . . . . . . . . . . . . . 11 - 3.8.1. Documents that Create a New Namespace . . . . . . . . 12 - 3.8.2. Documents that Extend an Existing Namespace . . . . . 12 - 3.9. Reference Sections . . . . . . . . . . . . . . . . . . . . 12 - 3.10. Validation Tools . . . . . . . . . . . . . . . . . . . . . 13 - 3.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 13 - 3.12. Module Usage Examples . . . . . . . . . . . . . . . . . . 13 - 4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 14 - 4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 14 - 4.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 15 - 4.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 16 - 4.3.1. Identifier Naming Conventions . . . . . . . . . . . . 16 - 4.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 17 - 4.5. Conditional Statements . . . . . . . . . . . . . . . . . . 17 - 4.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 18 - 4.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 18 - 4.6.2. Function Library . . . . . . . . . . . . . . . . . . . 19 - 4.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 20 - 4.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 20 - 4.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 21 - 4.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 21 - 4.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 22 - 4.8. Module Header, Meta, and Revision Statements . . . . . . . 23 - 4.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 24 - 4.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 25 - 4.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 26 - 4.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 26 - 4.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 27 - 4.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 28 - 4.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 29 - 4.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . . 30 - 4.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 31 - 4.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 32 - 4.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 32 - 4.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 34 - 4.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 34 - 4.15. Operation Definitions . . . . . . . . . . . . . . . . . . 35 - 4.16. Notification Definitions . . . . . . . . . . . . . . . . . 35 - 4.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 36 - 4.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 36 - 4.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 36 - 4.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 37 - 4.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 37 - 4.19.1. Conditional Augment Statements . . . . . . . . . . . . 37 - 4.19.2. Conditionally Mandatory Data Definition Statements . . 38 - 4.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 39 - 4.21. Extension Statements . . . . . . . . . . . . . . . . . . . 40 - 4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 41 - 4.22.1. Use of Leafref for Key Correlation . . . . . . . . . . 42 - 4.23. Operational State . . . . . . . . . . . . . . . . . . . . 43 - 4.23.1. Combining Operational State and Configuration Data . . 43 + 1.1. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . 5 + 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 8 + 2.1. Requirements Notation . . . . . . . . . . . . . . . . . . 8 + 2.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . . . 8 + 2.3. YANG Terms . . . . . . . . . . . . . . . . . . . . . . . . 8 + 2.4. NMDA Terms . . . . . . . . . . . . . . . . . . . . . . . . 9 + 2.5. Terms . . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 3. General Documentation Guidelines . . . . . . . . . . . . . . . 10 + 3.1. Module Copyright . . . . . . . . . . . . . . . . . . . . . 10 + 3.2. Code Components . . . . . . . . . . . . . . . . . . . . . 10 + 3.2.1. Example Modules . . . . . . . . . . . . . . . . . . . 11 + 3.3. Terminology Section . . . . . . . . . . . . . . . . . . . 11 + 3.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 11 + 3.5. Narrative Sections . . . . . . . . . . . . . . . . . . . . 12 + 3.6. Definitions Section . . . . . . . . . . . . . . . . . . . 12 + 3.7. Security Considerations Section . . . . . . . . . . . . . 13 + 3.7.1. Security Considerations Section Template . . . . . . . 13 + 3.8. IANA Considerations Section . . . . . . . . . . . . . . . 14 + 3.8.1. Documents that Create a New Namespace . . . . . . . . 15 + 3.8.2. Documents that Extend an Existing Namespace . . . . . 15 + 3.9. Reference Sections . . . . . . . . . . . . . . . . . . . . 15 + 3.10. Validation Tools . . . . . . . . . . . . . . . . . . . . . 16 + 3.11. Module Extraction Tools . . . . . . . . . . . . . . . . . 16 + 3.12. Module Usage Examples . . . . . . . . . . . . . . . . . . 16 + 4. YANG Usage Guidelines . . . . . . . . . . . . . . . . . . . . 17 + 4.1. Module Naming Conventions . . . . . . . . . . . . . . . . 17 + 4.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . 18 + 4.3. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 19 + 4.3.1. Identifier Naming Conventions . . . . . . . . . . . . 19 + 4.4. Defaults . . . . . . . . . . . . . . . . . . . . . . . . . 20 + 4.5. Conditional Statements . . . . . . . . . . . . . . . . . . 20 + 4.6. XPath Usage . . . . . . . . . . . . . . . . . . . . . . . 21 + 4.6.1. XPath Evaluation Contexts . . . . . . . . . . . . . . 21 + 4.6.2. Function Library . . . . . . . . . . . . . . . . . . . 22 + 4.6.3. Axes . . . . . . . . . . . . . . . . . . . . . . . . . 23 + 4.6.4. Types . . . . . . . . . . . . . . . . . . . . . . . . 23 + 4.6.5. Wildcards . . . . . . . . . . . . . . . . . . . . . . 24 + 4.6.6. Boolean Expressions . . . . . . . . . . . . . . . . . 24 + 4.7. Lifecycle Management . . . . . . . . . . . . . . . . . . . 25 + 4.8. Module Header, Meta, and Revision Statements . . . . . . . 26 + 4.9. Namespace Assignments . . . . . . . . . . . . . . . . . . 27 + 4.10. Top-Level Data Definitions . . . . . . . . . . . . . . . . 28 + 4.11. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 29 + 4.11.1. Fixed Value Extensibility . . . . . . . . . . . . . . 29 + 4.11.2. Patterns and Ranges . . . . . . . . . . . . . . . . . 30 + 4.11.3. Enumerations and Bits . . . . . . . . . . . . . . . . 31 + 4.11.4. Union Types . . . . . . . . . . . . . . . . . . . . . 32 + 4.11.5. Empty and Boolean . . . . . . . . . . . . . . . . . . 33 + 4.12. Reusable Type Definitions . . . . . . . . . . . . . . . . 34 + 4.13. Reusable Groupings . . . . . . . . . . . . . . . . . . . . 35 + 4.14. Data Definitions . . . . . . . . . . . . . . . . . . . . . 35 + 4.14.1. Non-Presence Containers . . . . . . . . . . . . . . . 37 + 4.14.2. Top-Level Data Nodes . . . . . . . . . . . . . . . . . 37 + 4.15. Operation Definitions . . . . . . . . . . . . . . . . . . 38 + 4.16. Notification Definitions . . . . . . . . . . . . . . . . . 38 + 4.17. Feature Definitions . . . . . . . . . . . . . . . . . . . 39 + 4.18. YANG Data Node Constraints . . . . . . . . . . . . . . . . 39 + 4.18.1. Controlling Quantity . . . . . . . . . . . . . . . . . 39 + 4.18.2. must vs. when . . . . . . . . . . . . . . . . . . . . 40 + 4.19. Augment Statements . . . . . . . . . . . . . . . . . . . . 40 + 4.19.1. Conditional Augment Statements . . . . . . . . . . . . 40 + 4.19.2. Conditionally Mandatory Data Definition Statements . . 41 + 4.20. Deviation Statements . . . . . . . . . . . . . . . . . . . 42 + 4.21. Extension Statements . . . . . . . . . . . . . . . . . . . 43 + 4.22. Data Correlation . . . . . . . . . . . . . . . . . . . . . 44 + 4.22.1. Use of Leafref for Key Correlation . . . . . . . . . . 45 + 4.23. Operational State . . . . . . . . . . . . . . . . . . . . 46 + 4.23.1. Combining Operational State and Configuration Data . . 46 4.23.2. Representing Operational Values of Configuration - Data . . . . . . . . . . . . . . . . . . . . . . . . . 44 - 4.23.3. NMDA Transition Guidelines . . . . . . . . . . . . . . 44 - 4.24. Performance Considerations . . . . . . . . . . . . . . . . 48 - 4.25. Open Systems Considerations . . . . . . . . . . . . . . . 48 - 4.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 49 - 4.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 49 - 4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 49 - 4.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 49 - 4.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 49 - 4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 50 - 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 52 - 6. Security Considerations . . . . . . . . . . . . . . . . . . . 53 - 6.1. Security Considerations Section Template . . . . . . . . . 53 - 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 55 - 8. Changes Since RFC 6087 . . . . . . . . . . . . . . . . . . . . 56 - 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 58 - 9.1. Normative References . . . . . . . . . . . . . . . . . . . 58 - 9.2. Informative References . . . . . . . . . . . . . . . . . . 58 + Data . . . . . . . . . . . . . . . . . . . . . . . . . 47 + 4.23.3. NMDA Transition Guidelines . . . . . . . . . . . . . . 47 + 4.24. Performance Considerations . . . . . . . . . . . . . . . . 51 + 4.25. Open Systems Considerations . . . . . . . . . . . . . . . 51 + 4.26. YANG 1.1 Guidelines . . . . . . . . . . . . . . . . . . . 52 + 4.26.1. Importing Multiple Revisions . . . . . . . . . . . . . 52 + 4.26.2. Using Feature Logic . . . . . . . . . . . . . . . . . 52 + 4.26.3. anyxml vs. anydata . . . . . . . . . . . . . . . . . . 52 + 4.26.4. action vs. rpc . . . . . . . . . . . . . . . . . . . . 52 + 4.27. Updating YANG Modules (Published vs. Unpublished) . . . . 53 + 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 56 + 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 57 + 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 58 + 8.1. Normative References . . . . . . . . . . . . . . . . . . . 58 + 8.2. Informative References . . . . . . . . . . . . . . . . . . 58 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 61 - A.1. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . . 61 - A.2. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 61 - A.3. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 61 - A.4. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 61 - A.5. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 62 - A.6. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 62 - A.7. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 62 - A.8. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 62 - A.9. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 62 - A.10. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 63 - A.11. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 63 - A.12. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 64 - A.13. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 64 - A.14. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 64 - A.15. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 64 + A.1. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . . 61 + A.2. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . . 61 + A.3. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . . 61 + A.4. v12 to v13 . . . . . . . . . . . . . . . . . . . . . . . . 61 + A.5. v11 to v12 . . . . . . . . . . . . . . . . . . . . . . . . 62 + A.6. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . . 62 + A.7. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . . 62 + A.8. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . . 62 + A.9. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . . 62 + A.10. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . . 63 + A.11. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . . 63 + A.12. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . . 63 + A.13. v03 ot v04 . . . . . . . . . . . . . . . . . . . . . . . . 64 + A.14. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . . 64 + A.15. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . . 64 + A.16. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . . 64 Appendix B. Module Review Checklist . . . . . . . . . . . . . . . 66 Appendix C. YANG Module Template . . . . . . . . . . . . . . . . 68 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 70 1. Introduction The standardization of network configuration interfaces for use with - the Network Configuration Protocol [RFC6241] and RESTCONF [RFC8040] - requires a modular set of data models, which can be reused and - extended over time. + network configuration management protocols, such as the Network + Configuration Protocol [RFC6241] and RESTCONF [RFC8040], 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 [RFC7950] data models. YANG is used to define the data structures, protocol operations, and notification content - used within a NETCONF and/or RESTCONF server. A server that supports - a particular YANG module will support client NETCONF and/or RESTCONF - 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. + used within a NETCONF and/or RESTCONF server. A NETCONF or RESTCONF + server that supports a particular YANG module will support client + NETCONF and/or RESTCONF operation requests, as indicated by the + specific content defined in the YANG module. Many YANG constructs are defined as optional to use, such as the - description statement. However, in order to maximize - interoperability of NETCONF and RESTCONF 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. + description statement. However, in order to make YANG modules more + useful, it is desirable to define a set of usage guidelines that + entails 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 [RFC6241], and the RESTCONF methods and RESTCONF resources, as defined in [RFC8040], These guidelines are intended to be used by authors and reviewers to improve the readability and interoperability of published YANG data models. Note that this document is not a YANG tutorial and the reader is expected to know the YANG data modeling language before using this document. +1.1. Changes Since RFC 6087 + + The following changes have been made to the guidelines published in + [RFC6087]: + + o Updated NETCONF reference from RFC 4741 to RFC 6241 + o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 + + o Updated YANG Types reference from RFC 6021 to RFC 6991 + + o Updated obsolete URLs for IETF resources + + o Changed top-level data node guideline + + o Clarified XPath usage for a literal value representing a YANG + identity + + o Clarified XPath usage for a when-stmt + + o Clarified XPath usage for 'proceeding-sibling' and + 'following-sibling' axes + + o Added terminology guidelines + + o Added YANG tree diagram guidelines + + o Updated XPath guidelines for type conversions and function library + usage. + + o Updated data types section + + o Updated notifications section + + o Clarified conditional key leaf nodes + + o Clarify usage of 'uint64' and 'int64' data types + + o Added text on YANG feature usage + + o Added Identifier Naming Conventions + + o Clarified use of mandatory nodes with conditional augmentations + + o Clarified namespace and domain conventions for example modules + + o Clarified conventions for identifying code components + + o Added YANG 1.1 guidelines + + o Added Data Model Constraints section + + o Added mention of RESTCONF protocol + o Added guidelines for NMDA Revised Datastores + 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]. + document are to be interpreted as described in BCP 14 [RFC2119] + [RFC8174] when, and only when, they appear in all capitals, as shown + here. 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 [RFC6241] and are not redefined here: @@ -286,26 +334,20 @@ is considered an unstable publication that is a work-in-progress, subject to change at any time. o YANG fragment: A set of YANG statements that are not intended to represent a complete YANG module or submodule. These statements are not intended for actual use, except to provide an example of YANG statement usage. The invalid syntax "..." is sometimes used to indicate that additional YANG statements would be present in a real YANG module. -2.5.1. YANG Tree Diagrams - - A simplified graphical representation of the data model is used in - this document. The meaning of the symbols in these diagrams is - defined in [I-D.ietf-netmod-yang-tree-diagrams]. - 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 [RFC7322] and updated in [RFC7841] and "RFC Document Style" [RFC-STYLE]. The following sections MUST be present in an Internet-Draft @@ -377,36 +419,33 @@ convention MUST NOT be used for example modules. An example module SHOULD be named using the term "example", followed by a hyphen, followed by a descriptive name, e.g., "example-toaster". 3.3. Terminology Section A terminology section MUST be present if any terms are defined in the document or if any terms are imported from other documents. - If YANG tree diagrams are used, then a sub-section explaining the - YANG tree diagram syntax MUST be present, containing the following - text: - - A simplified graphical representation of the data model is used in - this document. The meaning of the symbols in these diagrams is - defined in [I-D.ietf-netmod-yang-tree-diagrams]. + If YANG tree diagrams are used, then a normative reference to the + YANG tree diagrams specification MUST be provided for each diagram. + (Refer to the example in the next section.) 3.4. Tree Diagrams YANG tree diagrams provide a concise representation of a YANG module, and SHOULD be included to help readers understand YANG module structure. Guidelines on tree diagrams can be found in Section 3 of [I-D.ietf-netmod-yang-tree-diagrams]. - The following example shows a simple YANG tree diagram: + The following example shows a simple YANG tree diagram + [I-D.ietf-netmod-yang-tree-diagrams]: +--rw top-level-config-container | +--rw config-list* [key-name] | +--rw key-name string | +--rw optional-parm? string | +--rw mandatory-parm identityref | +--ro read-only-leaf string +--ro top-level-nonconfig-container +--ro nonconfig-list* [name] +--ro name string @@ -452,41 +491,98 @@ See Section 4 for guidelines on YANG usage. 3.7. 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://trac.tools.ietf.org/area/ops/trac/wiki/ - yang-security-guidelines). Section 6.1 contains the security - considerations template dated 2013-05-08. Authors MUST check the WEB - page at the URL listed above in case there is a more recent version - available. + yang-security-guidelines). Section 3.7.1 contains the security + considerations template dated 2013-05-08 and last updated 2017-12-21. + Authors MUST check the WEB page 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.7.1. Security Considerations Section Template + + X. Security Considerations + + The YANG module specified in this document defines a schema for data + that is designed to be accessed via network management protocols such + as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer + is the secure transport layer, and the mandatory-to-implement secure + transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer + is HTTPS, and the mandatory-to-implement secure transport is TLS + [RFC5246]. + + The NETCONF access control model [RFC6536] provides the means to + restrict access for particular NETCONF or RESTCONF users to a + preconfigured subset of all available NETCONF or RESTCONF protocol + operations and content. + + -- if you have any writeable 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 that 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: + + + + -- 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: + + + + -- 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: + + + 3.8. 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 @@ -2332,212 +2428,85 @@ | Namespace | urn:ietf:params:xml:ns:yang:ietf-template | | Prefix | temp | | Reference | RFC XXXX | +-----------+-------------------------------------------+ YANG Registry Assignment 6. Security Considerations This document defines documentation guidelines for NETCONF or - RESTCONF 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://trac.tools.ietf.org/area/ops/trac/wiki/ - yang-security-guidelines - - 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. - -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 [RFC6241]. The lowest NETCONF layer is the - secure transport layer and the mandatory-to-implement secure - transport is SSH [RFC6242]. - - -- 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: - - - - -- 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: - - - - -- 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: - - + RESTCONF content defined with the YANG data modeling language, and + therefore does not introduce any new or increased security risks into + the management system. 7. Acknowledgments The structure and contents of this document are adapted from [RFC4181], guidelines for MIB Documents, by C. M. Heard. The working group thanks Martin Bjorklund, Juergen Schoenwaelder, Ladislav Lhotka, Jernej Tuljak, and Lou Berger for their extensive reviews and contributions to this document. -8. Changes Since RFC 6087 - - The following changes have been made to the guidelines published in - [RFC6087]: - - o Updated NETCONF reference from RFC 4741 to RFC 6241 - - o Updated NETCONF over SSH citation from RFC 4742 to RFC 6242 - - o Updated YANG Types reference from RFC 6021 to RFC 6991 - - o Updated obsolete URLs for IETF resources - - o Changed top-level data node guideline - - o Clarified XPath usage for a literal value representing a YANG - identity - - o Clarified XPath usage for a when-stmt - - o Clarified XPath usage for 'proceeding-sibling' and - 'following-sibling' axes - - o Added terminology guidelines - - o Added YANG tree diagram definition and guideline - - o Updated XPath guidelines for type conversions and function library - usage. - - o Updated data types section - - o Updated notifications section - - o Clarified conditional key leaf nodes - - o Clarify usage of 'uint64' and 'int64' data types - - o Added text on YANG feature usage - - o Added Identifier Naming Conventions - - o Clarified use of mandatory nodes with conditional augmentations - - o Clarified namespace and domain conventions for example modules - - o Clarified conventions for identifying code components - o Added YANG 1.1 guidelines - - o Added Data Model Constraints section - - o Added mention of RESTCONF protocol - - o Added guidelines for NMDA Revised Datastores - -9. References +8. References -9.1. Normative References +8.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 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. + [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ + RFC5246, August 2008, + . + [RFC5378] Bradner, S. and J. Contreras, "Rights Contributors Provide to the IETF Trust", BCP 78, RFC 5378, November 2008. [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, October 2010. - [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, - July 2013. - [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016, . + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + [W3C.REC-xpath-19991116] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", World Wide Web Consortium Recommendation REC-xpath-19991116, November 1999, . -9.2. Informative References +8.2. Informative References [I-D.ietf-netmod-revised-datastores] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "Network Management Datastore - Architecture", draft-ietf-netmod-revised-datastores-07 - (work in progress), November 2017. + Architecture", draft-ietf-netmod-revised-datastores-10 + (work in progress), January 2018. [I-D.ietf-netmod-yang-tree-diagrams] Bjorklund, M. and L. Berger, "YANG Tree Diagrams", - draft-ietf-netmod-yang-tree-diagrams-02 (work in - progress), October 2017. + draft-ietf-netmod-yang-tree-diagrams-04 (work in + progress), December 2017. [RFC-STYLE] Braden, R., Ginoza, S., and A. Hagens, "RFC Document Style", September 2009, . [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, . @@ -2556,20 +2525,23 @@ (NETCONF)", RFC 6241, June 2011. [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, . [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration Protocol (NETCONF) Access Control Model", RFC 6536, March 2012. + [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, + July 2013. + [RFC7223] Bjorklund, M., "A YANG Data Model for Interface Management", RFC 7223, May 2014. [RFC7322] Flanagan, H. and S. Ginoza, "RFC Style Guide", RFC 7322, DOI 10.17487/RFC7322, September 2014, . [RFC7841] Halpern, J., Ed., Daigle, L., Ed., and O. Kolkman, Ed., "RFC Streams, Headers, and Boilerplates", RFC 7841, DOI 10.17487/RFC7841, May 2016, @@ -2581,110 +2553,117 @@ [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, June 2017, . Appendix A. Change Log -- RFC Ed.: remove this section before publication. -A.1. v14 to v15 +A.1. v15 to v16 + + o address document shephard comments posted 2018-01-15 + + o add yang-version to template module + +A.2. v14 to v15 o changed Intended status from Informational to BCP o update tree diagram guidelines section o Change IANA template to list IESG instead of NETMOD WG as the Registrant o Update some references -A.2. v13 to v14 +A.3. v13 to v14 o Replaced sec. 4.23 Operational Data with Operational Data from NMDA text by Lou Berger and Kent Watsen o Added NMDA Terms section o Changed term operational data to operational state o Clarified that reference-stmt SHOULD be present in import-stmt -A.3. v12 to v13 +A.4. v12 to v13 o Clarify that the revision-date SHOULD be used in a CODE BEGINS YANG file extraction macro. o Clarify the IANA requirements section wrt/ XML namespace and YANG module name registries. o Clarify YANG Usage section wrt/ XML and/or JSON encoding format. o Update Operation Data section to consider revised datastores. o Add reference to YANG Tree Diagrams and update 2 sections that use this reference. o Add reference to Revised Datastores and guidelines drafts -A.4. v11 to v12 +A.5. v11 to v12 o fix incorrect location of new Module Usage Examples section -A.5. v10 to v11 +A.6. v10 to v11 o updated YANG tree diagram syntax to align with pyang 1.7.1 o added general guideline to include module usage examples -A.6. v09 to v10 +A.7. v09 to v10 o clarified is only for normative modules o clarified example module namespace URI conventions o clarified pyang usage for normative and example modules o updated YANG tree diagrams section with text from RFC 8022 -A.7. v08 to v09 +A.8. v08 to v09 o fixed references o added mention of RESTCONF to abstract and intro o created separate section for code components o fixed document status -A.8. v07 to v08 +A.9. v07 to v08 o changed CODE BEGINS guideline for example modules o updated tree diagram guidelines o clarified published and unpublished terms o added section on Empty and Boolean data types o clarified how to update the revision statement o updated operational state guidelines o added 'YANG fragment' to terminology section -A.9. v06 to v07 +A.10. v06 to v07 o update contact statement guideline o update example modules guidelines + o add guidelines on top-level data nodes o add guideline on use of NP containers o added guidelines on union types o add guideline on deviations o added section on open systems considerations @@ -2683,41 +2662,41 @@ o add guideline on use of NP containers o added guidelines on union types o add guideline on deviations o added section on open systems considerations o added guideline about definitions reserved for future use -A.10. v05 to v06 +A.11. v05 to v06 o Changed example 'my-module' to 'example-module' o Added section Updating YANG Modules (Published vs. Unpublished) o Added Example Modules section o Added "" convention for full example modules o Added section on using action vs. rpc o Changed term "operational state" to "operational data" o Added section on YANG Data Node Constraints o Added guidelines on using must vs. when statements o Made ietf-foo module validate for I-D submission -A.11. v04 to v05 +A.12. v04 to v05 o Clarified that YANG 1.1 SHOULD be used but YANG 1.0 MAY be used if no YANG 1.1 features needed o Changed SHOULD follow YANG naming conventions to MUST follow (for standards track documents only) o Clarified module naming conventions for normative modules, example modules, and modules from other SDOs. @@ -2717,53 +2696,54 @@ o Changed SHOULD follow YANG naming conventions to MUST follow (for standards track documents only) o Clarified module naming conventions for normative modules, example modules, and modules from other SDOs. o Added prefix value selection guidelines o Added new section on guidelines for reusable groupings + o Made header guidelines less IETF-specific o Added new section on guidelines for extension statements o Added guidelines for nested "choice" statement within a "case" statement -A.12. v03 ot v04 +A.13. v03 ot v04 o Added sections for deviation statements and performance considerations o Added YANG 1.1 section o Updated YANG reference from 1.0 to 1.1 -A.13. v02 to v03 +A.14. v02 to v03 o Updated draft based on github data tracker issues added by Benoit Clause (Issues 12 - 18) -A.14. v01 to v02 +A.15. v01 to v02 o Updated draft based on mailing list comments. -A.15. v00 to v01 +A.16. v00 to v01 All issues from the issue tracker have been addressed. https://github.com/netmod-wg/rfc6087bis/issues - o Issue 1: Tree Diagrams: Added Section 2.5.1 so RFCs with YANG - modules can use an Informative reference to this RFC for tree + o Issue 1: Tree Diagrams: Added 'tree-diagrams' section so RFCs with + YANG modules can use an Informative reference to this RFC for tree diagrams. Updated guidelines to reference this RFC when tree diagrams are used o Issue 2: XPath function restrictions: Added paragraphs in XPath usage section for 'id', 'namespace-uri', 'name', and 'lang' functions o Issue 3: XPath function document order issues: Added paragraph in XPath usage section about node-set ordering for 'local-name', 'namespace-uri', 'name', 'string' and 'number' functions. Also @@ -2877,20 +2857,22 @@ particularly important to check that description statements are sufficiently clear and unambiguous to allow interoperable implementations to be created. Appendix C. YANG Module Template file "ietf-template@2016-03-20.yang" module ietf-template { + yang-version 1.1; + // 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; }