doc: Add RFC documents

1 files changed, 619 insertions, 0 deletions

diff --git a/doc/rfc/rfc8199.txt b/doc/rfc/rfc8199.txt
new file mode 100644
index 0000000..8ee18b8
--- /dev/null
+++ b/doc/rfc/rfc8199.txt
@@ -0,0 +1,619 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF)                     D. Bogdanovic
+Request for Comments: 8199                          Volta Networks, Inc.
+Category: Informational                                        B. Claise
+ISSN: 2070-1721                                                C. Moberg
+                                                     Cisco Systems, Inc.
+                                                               July 2017
+
+
+                       YANG Module Classification
+
+Abstract
+
+   The YANG data modeling language is currently being considered for a
+   wide variety of applications throughout the networking industry at
+   large.  Many standards development organizations (SDOs), open-source
+   software projects, vendors, and users are using YANG to develop and
+   publish YANG modules for a wide variety of applications.  At the same
+   time, there is currently no well-known terminology to categorize
+   various types of YANG modules.
+
+   A consistent terminology would help with the categorization of YANG
+   modules, assist in the analysis of the YANG data modeling efforts in
+   the IETF and other organizations, and bring clarity to the YANG-
+   related discussions between the different groups.
+
+   This document describes a set of concepts and associated terms to
+   support consistent classification of YANG 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 7841.
+
+   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/rfc8199.
+
+
+
+
+
+
+
+
+Bogdanovic, et al.            Informational                     [Page 1]
+
+RFC 8199               YANG Module Classification              July 2017
+
+
+Copyright Notice
+
+   Copyright (c) 2017 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  . . . . . . . . . . . . . . . . . . . . . . . .   2
+     1.1.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   4
+   2.  First Dimension: YANG Module Abstraction Layers . . . . . . .   4
+     2.1.  Network Service YANG Modules  . . . . . . . . . . . . . .   6
+     2.2.  Network Element YANG Modules  . . . . . . . . . . . . . .   7
+   3.  Second Dimension: YANG Module Origin Types  . . . . . . . . .   7
+     3.1.  Standard YANG Modules . . . . . . . . . . . . . . . . . .   8
+     3.2.  Vendor-Specific YANG Modules and Extensions . . . . . . .   8
+     3.3.  User-Specific YANG Modules and Extensions . . . . . . . .   9
+   4.  Security Considerations . . . . . . . . . . . . . . . . . . .   9
+   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   9
+   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  10
+     6.1.  Normative References  . . . . . . . . . . . . . . . . . .  10
+     6.2.  Informative References  . . . . . . . . . . . . . . . . .  10
+   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  11
+   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  11
+
+1.  Introduction
+
+   The Internet Engineering Steering Group (IESG) has been actively
+   encouraging IETF working groups to use the YANG data modeling
+   language [RFC7950] and the Network Configuration Protocol (NETCONF)
+   [RFC6241] for configuration management purposes, especially in new
+   working group charters [IESG-Statement].
+
+   YANG is also gaining wide acceptance as the de facto standard data
+   modeling language in the broader industry.  This extends beyond the
+   IETF to include many SDOs, industry consortia, ad hoc groups, open-
+   source projects, vendors, and end users.
+
+
+
+
+
+Bogdanovic, et al.            Informational                     [Page 2]
+
+RFC 8199               YANG Module Classification              July 2017
+
+
+   There are currently no clear guidelines on how to classify the
+   layering of YANG modules according to abstraction or how to classify
+   modules along the continuum spanning formal standards publications,
+   vendor-specific modules, and modules provided by end users.
+
+   This document presents a set of concepts and terms to form a useful
+   taxonomy for consistent classification of YANG modules in two
+   dimensions:
+
+   o  The layering of modules based on their abstraction levels
+
+   o  The module origin type based on the nature and intent of the
+      content
+
+   The intent of this document is to provide a taxonomy to simplify
+   human communication around YANG modules.  While the classification
+   boundaries are at times blurry, this document should provide a robust
+   starting point as the YANG community gains further experience with
+   designing and deploying modules.  To be more explicit, it is expected
+   that the classification criteria will change over time.
+
+   A number of modules, for example, modules concerned with topologies,
+   created substantial discussion during the development of this
+   document.  Topology modules are useful both on the network element
+   level (e.g., link-state database content) and on the network service
+   level (e.g., network-wide, configured topologies).  In the end, it is
+   the module developer that classifies the module according to the
+   initial intent of the module content.
+
+   This document should provide benefits to multiple audiences:
+
+   o  First, a common taxonomy helps with discussions among SDOs and
+      industry consortia; the goals of such discussions are determined
+      by the respective areas of work.
+
+   o  Second, operators might look at the YANG module abstraction layers
+      to understand which Network Service YANG Modules and Network
+      Element YANG Modules are available for their service composition.
+      It is difficult to determine the module type without inspecting
+      the YANG module itself.  The YANG module name might provide some
+      useful information but is not a definite answer.  For example, a
+      Layer 2 Virtual Private Network (L2VPN) YANG module might be a
+      Network Service YANG Module, ready to be used as a service model
+      by a network operator.  Alternatively, it might be a Network
+      Element YANG Module that contains the L2VPN data definitions
+      required to be configured on a single device.
+
+
+
+
+
+Bogdanovic, et al.            Informational                     [Page 3]
+
+RFC 8199               YANG Module Classification              July 2017
+
+
+   o  Third, this taxonomy will help equipment vendors (whether physical
+      or virtual), controller vendors, and orchestrator vendors to
+      explain to their customers the relationship between the different
+      YANG modules they support in their products.
+
+1.1.  Terminology
+
+   [RFC7950] specifies:
+
+   o  data model: A data model describes how data is represented and
+      accessed.
+
+   o  module: A YANG module defines hierarchies of schema nodes.  With
+      its definitions and the definitions it imports or includes from
+      elsewhere, a module is self-contained and "compilable".
+
+2.  First Dimension: YANG Module Abstraction Layers
+
+   Module developers have taken two approaches to developing YANG
+   modules: top-down and bottom-up.  The top-down approach starts with
+   high-level abstractions modeling business or customer requirements
+   and maps them to specific networking technologies.  The bottom-up
+   approach starts with fundamental networking technologies and maps
+   them into more abstract constructs.
+
+   There are currently no specific requirements or well-defined best
+   practices for the development of YANG modules.  This document
+   considers both bottom-up and top-down approaches as they are both
+   used and they each provide benefits that appeal to different groups.
+
+   For layering purposes, this document suggests the classification of
+   YANG modules into two distinct abstraction layers:
+
+   o  Network Element YANG Modules describe the configuration, state
+      data, operations, and notifications of specific device-centric
+      technologies or features.
+
+   o  Network Service YANG Modules describe the configuration, state
+      data, operations, and notifications of abstract representations of
+      services implemented on one or multiple network elements.
+
+
+
+
+
+
+
+
+
+
+
+Bogdanovic, et al.            Informational                     [Page 4]
+
+RFC 8199               YANG Module Classification              July 2017
+
+
+                        +--------------------------+
+                        |  Operations and Business |
+                        |      Support Systems     |
+                        |      (OSSs and BSSs)     |
+                        +--------------------------+
+
+        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+        Network Service YANG Modules
+
+             +------------+      +-------------+      +-------------+
+             |            |      |             |      |             |
+             |  - L2VPN   |      |   - L2VPN   |      |    L3VPN    |
+             |  - VPWS    |      |   - VPLS    |      |             |
+             |            |      |             |      |             |
+             +------------+      +-------------+      +-------------+
+
+        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+        Network Element YANG Modules
+
+        +------------+  +------------+  +-------------+  +------------+
+        |            |  |            |  |             |  |            |
+        |    MPLS    |  |    BGP     |  | IPv4 / IPv6 |  |  Ethernet  |
+        |            |  |            |  |             |  |            |
+        +------------+  +------------+  +-------------+  +------------+
+
+          L2VPN: Layer 2 Virtual Private Network
+          L3VPN: Layer 3 Virtual Private Network
+          VPWS: Virtual Private Wire Service
+          VPLS: Virtual Private LAN Service
+
+                 Figure 1: YANG Module Abstraction Layers
+
+   Figure 1 illustrates the application of YANG modules at different
+   layers of abstraction.  Layering of modules allows for reusability of
+   existing lower-layer modules by higher-level modules while limiting
+   duplication of features across layers.
+
+   For module developers, per-layer modeling allows for separation of
+   concern across editing teams focusing on specific areas.
+
+   As an example, experience from the IETF shows that creating useful
+   Network Element YANG Modules (e.g., for routing or switching
+   protocols) requires teams that include developers with experience
+   implementing those protocols.
+
+
+
+
+
+
+
+Bogdanovic, et al.            Informational                     [Page 5]
+
+RFC 8199               YANG Module Classification              July 2017
+
+
+   On the other hand, Network Service YANG Modules are best developed by
+   network operators experienced in defining network services for
+   consumption by programmers, e.g., those developing flow-through
+   provisioning systems or self-service portals.
+
+2.1.  Network Service YANG Modules
+
+   Network Service YANG Modules describe the characteristics of a
+   service, as agreed upon with consumers of that service.  That is, a
+   service module does not expose the detailed configuration parameters
+   of all participating network elements and features but describes an
+   abstract model that allows instances of the service to be decomposed
+   into instance data according to the Network Element YANG Modules of
+   the participating network elements.  The service-to-element
+   decomposition is a separate process; the details depend on how the
+   network operator chooses to realize the service.  For the purpose of
+   this document, the term "orchestrator" is used to describe a system
+   implementing such a process.
+
+   External systems can be provisioning systems, service orchestrators,
+   Operations Support Systems, Business Support Systems, and
+   applications exposed to network service consumers (either internal
+   network operations people or external customers).  These modules are
+   commonly designed, developed, and deployed by network infrastructure
+   teams.
+
+   YANG allows for different design patterns to describe network
+   services, ranging from monolithic to component-based approaches.
+
+   The monolithic approach captures the entire service in a single
+   module and does not put focus on reusability of internal data
+   definitions and groupings.  The monolithic approach has the
+   advantages of single-purpose development, including development speed
+   at the expense of reusability.
+
+   The component-based approach captures device-centric features (e.g.,
+   VPN Routing and Forwarding (VRF), routing protocols, or packet
+   filtering) in a vendor-independent manner.  The components are
+   designed for reuse across many service modules.  The set of
+   components required for a specific service is then composed into the
+   higher-level service.  The component-based approach has the
+   advantages of modular development, including a higher degree of
+   reusability at the expense of initial development speed.
+
+   As an example, an L2VPN service can be built on many different types
+   of transport network technologies, including, e.g., MPLS or Carrier
+   Ethernet.  A component-based approach would allow for reuse of User-
+   Network Interface (UNI) definitions, such as the MEF UNI interface or
+
+
+
+Bogdanovic, et al.            Informational                     [Page 6]
+
+RFC 8199               YANG Module Classification              July 2017
+
+
+   MPLS interface, independent of the underlying transport network.  The
+   monolithic approach would assume a specific set of transport
+   technologies and interface definitions.
+
+   An example of a Network Service YANG Module is in [RFC8049].  It
+   provides an abstract model for Layer 3 IP VPN service configuration.
+   This module includes the concept of a 'site-network-access' to
+   represent bearer and connection parameters.  An orchestrator receives
+   operations on service instances according to the service module and
+   decomposes the data into configuration data according to specific
+   Network Element YANG Modules to configure the participating network
+   elements to the service.  In the case of the L3VPN module, this would
+   include translating the 'site-network-access' parameters to the
+   appropriate parameters in the Network Element YANG Module implemented
+   on the constituent elements.
+
+2.2.  Network Element YANG Modules
+
+   Network Element YANG Modules describe the characteristics of a
+   network device as defined by the vendor of that device.  The modules
+   are commonly structured around features of the device, e.g.,
+   interface configuration [RFC7223], OSPF configuration [OSPF-YANG],
+   and access control list (ACL) configuration [ACL-YANG].
+
+   The Network Element YANG Module provides a coherent data model
+   representation of the software environment consisting of the
+   operating system and applications running on the device.  The
+   decomposition, ordering, and execution of changes to the operating
+   system and application configuration is the task of the agent that
+   implements the module.
+
+3.  Second Dimension: YANG Module Origin Types
+
+   This document suggests classifying YANG module origin types as
+   Standard YANG Modules, Vendor-Specific YANG Modules and Extensions,
+   or User-Specific YANG Modules and Extensions.
+
+   The suggested classification applies to both Network Element YANG
+   Modules and Network Service YANG Modules.
+
+   It is to be expected that real-world implementations of both Network
+   Service YANG Modules and Network Element YANG Modules will include a
+   mix of all three module origin types.
+
+
+
+
+
+
+
+
+Bogdanovic, et al.            Informational                     [Page 7]
+
+RFC 8199               YANG Module Classification              July 2017
+
+
+   Figure 2 illustrates the relationship between the three types of
+   modules.
+
+  +--------------+
+  |     User     |
+  |   Extensions |
+  +------+-------+
+      Augments
+  +------+-------+  +--------------+  +--------------+
+  |   Vendor     |  |     User     |  |     User     |
+  |  Extensions  |  |  Extensions  |  |  Extensions  |
+  +------+-------+  +------+-------+  +------+-------+
+      Augments          Augments          Augments
+  +------+-----------------+-------+  +------+-------+  +--------------+
+  |            Standard            |  |    Vendor    |  |    User      |
+  |            Modules             |  |    Modules   |  |   Modules    |
+  +--------------------------------+  +--------------+  +--------------+
+
+                    Figure 2: YANG Module Origin Types
+
+3.1.  Standard YANG Modules
+
+   Standard YANG Modules are published by SDOs.  Most SDOs create
+   specifications according to a formal process in order to produce a
+   standard that is useful for their constituencies.
+
+   The lifecycles of these modules are driven by the editing cycles of
+   the specifications and not tied to a specific implementation.
+
+   Examples of SDOs in the networking industry are the IETF and the
+   IEEE.
+
+3.2.  Vendor-Specific YANG Modules and Extensions
+
+   Vendor-Specific YANG Modules are developed by organizations with the
+   intent to support a specific set of implementations under control of
+   that organization, for example, vendors of virtual or physical
+   equipment, industry consortia, and open-source projects.  The intent
+   of these modules ranges from providing openly published YANG modules
+   that may eventually be contributed back to or adopted by an SDO to
+   strictly internal YANG modules not intended for external consumption.
+
+   The lifecycles of these modules are generally aligned with the
+   release cycles of the product or open-source software project
+   deliverables.
+
+
+
+
+
+
+Bogdanovic, et al.            Informational                     [Page 8]
+
+RFC 8199               YANG Module Classification              July 2017
+
+
+   It is worth noting that there is an increasing amount of interaction
+   between open-source projects and SDOs in the networking industry.
+   This includes open-source projects implementing published standards
+   as well as open-source projects contributing content to SDO
+   processes.
+
+   Vendors also develop vendor-specific extensions to standard modules
+   using YANG constructs for extending data definitions of previously
+   published modules.  This is done using the 'augment' statement that
+   allows locally defined data trees to be added into locations in
+   externally defined data trees.
+
+   Vendors use this to extend standard modules to cover the full scope
+   of features in implementations, which commonly is broader than that
+   covered by the standard module.
+
+3.3.  User-Specific YANG Modules and Extensions
+
+   User-Specific YANG Modules are developed by organizations that
+   operate YANG-based infrastructure including devices and
+   orchestrators, for example, network administrators in enterprises or
+   at service providers.  The intent of these modules is to express the
+   specific needs for a certain implementation, above and beyond what is
+   provided by vendors.
+
+   This module type obviously requires the infrastructure to support the
+   introduction of user-provided modules and extensions.  This would
+   include the ability to describe the service-to-network decomposition
+   in orchestrators and the module-to-configuration decomposition in
+   devices.
+
+   The lifecycles of these modules are generally aligned with the change
+   cadence of the infrastructure.
+
+4.  Security Considerations
+
+   This document doesn't have any Security Considerations.
+
+5.  IANA Considerations
+
+   This document does not require any IANA actions.
+
+
+
+
+
+
+
+
+
+
+Bogdanovic, et al.            Informational                     [Page 9]
+
+RFC 8199               YANG Module Classification              July 2017
+
+
+6.  References
+
+6.1.  Normative References
+
+   [RFC6241]  Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
+              and A. Bierman, Ed., "Network Configuration Protocol
+              (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
+              <http://www.rfc-editor.org/info/rfc6241>.
+
+   [RFC7223]  Bjorklund, M., "A YANG Data Model for Interface
+              Management", RFC 7223, DOI 10.17487/RFC7223, May 2014,
+              <http://www.rfc-editor.org/info/rfc7223>.
+
+   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
+              RFC 7950, DOI 10.17487/RFC7950, August 2016,
+              <http://www.rfc-editor.org/info/rfc7950>.
+
+   [RFC8049]  Litkowski, S., Tomotaki, L., and K. Ogaki, "YANG Data
+              Model for L3VPN Service Delivery", RFC 8049,
+              DOI 10.17487/RFC8049, February 2017,
+              <http://www.rfc-editor.org/info/rfc8049>.
+
+6.2.  Informative References
+
+   [ACL-YANG]
+              Bogdanovic, D., Jethanandani, M., Huang, L., Agarwal, S.,
+              and D. Blair, "Network Access Control List (ACL) YANG Data
+              Model", Work in Progress, draft-ietf-netmod-acl-model-11,
+              June 2017.
+
+   [IESG-Statement]
+              "Writable MIB Module IESG Statement",
+              <https://www.ietf.org/iesg/statement/
+              writable-mib-module.html>.
+
+   [OSPF-YANG]
+              Yeung, D., Qu, Y., Zhang, Z., Chen, I., and A. Lindem,
+              "Yang Data Model for OSPF Protocol", Work in Progress,
+              draft-ietf-ospf-yang-08, July 2017.
+
+
+
+
+
+
+
+
+
+
+
+
+Bogdanovic, et al.            Informational                    [Page 10]
+
+RFC 8199               YANG Module Classification              July 2017
+
+
+Acknowledgements
+
+   Thanks to David Ball and Jonathan Hansford for feedback and
+   suggestions.
+
+Authors' Addresses
+
+   Dean Bogdanovic
+   Volta Networks, Inc.
+
+   Email: dean@voltanet.io
+
+
+   Benoit Claise
+   Cisco Systems, Inc.
+   De Kleetlaan 6a b1
+   1831 Diegem
+   Belgium
+
+   Phone: +32 2 704 5622
+   Email: bclaise@cisco.com
+
+
+   Carl Moberg
+   Cisco Systems, Inc.
+
+   Email: camoberg@cisco.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bogdanovic, et al.            Informational                    [Page 11]
+