doc: Add RFC documents

1 files changed, 2467 insertions, 0 deletions

diff --git a/doc/rfc/rfc8342.txt b/doc/rfc/rfc8342.txt
new file mode 100644
index 0000000..b23ded4
--- /dev/null
+++ b/doc/rfc/rfc8342.txt
@@ -0,0 +1,2467 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF)                      M. Bjorklund
+Request for Comments: 8342                                Tail-f Systems
+Updates: 7950                                           J. Schoenwaelder
+Category: Standards Track                              Jacobs University
+ISSN: 2070-1721                                                P. Shafer
+                                                               K. Watsen
+                                                        Juniper Networks
+                                                               R. Wilton
+                                                           Cisco Systems
+                                                              March 2018
+
+
+            Network Management Datastore Architecture (NMDA)
+
+Abstract
+
+   Datastores are a fundamental concept binding the data models written
+   in the YANG data modeling language to network management protocols
+   such as the Network Configuration Protocol (NETCONF) and RESTCONF.
+   This document defines an architectural framework for datastores based
+   on the experience gained with the initial simpler model, addressing
+   requirements that were not well supported in the initial model.  This
+   document updates RFC 7950.
+
+Status of This Memo
+
+   This is an Internet Standards Track document.
+
+   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).  Further information on
+   Internet Standards is available in 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
+   https://www.rfc-editor.org/info/rfc8342.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                    [Page 1]
+
+RFC 8342                          NMDA                        March 2018
+
+
+Copyright Notice
+
+   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
+   (https://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 ....................................................3
+   2. Objectives ......................................................4
+   3. Terminology .....................................................5
+   4. Background ......................................................8
+      4.1. Original Model of Datastores ...............................9
+   5. Architectural Model of Datastores ..............................11
+      5.1. Conventional Configuration Datastores .....................12
+           5.1.1. The Startup Configuration Datastore (<startup>) ....12
+           5.1.2. The Candidate Configuration Datastore
+                  (<candidate>) ......................................13
+           5.1.3. The Running Configuration Datastore (<running>) ....13
+           5.1.4. The Intended Configuration Datastore (<intended>) ..13
+      5.2. Dynamic Configuration Datastores ..........................14
+      5.3. The Operational State Datastore (<operational>) ...........14
+           5.3.1. Remnant Configuration ..............................16
+           5.3.2. Missing Resources ..................................16
+           5.3.3. System-Controlled Resources ........................16
+           5.3.4. Origin Metadata Annotation .........................17
+   6. Implications on YANG ...........................................18
+      6.1. XPath Context .............................................18
+      6.2. Invocation of Actions and RPCs ............................19
+   7. YANG Modules ...................................................20
+   8. IANA Considerations ............................................26
+      8.1. Updates to the IETF XML Registry ..........................26
+      8.2. Updates to the YANG Module Names Registry .................27
+   9. Security Considerations ........................................27
+   10. References ....................................................28
+      10.1. Normative References .....................................28
+      10.2. Informative References ...................................29
+
+
+
+
+
+Bjorklund, et al.            Standards Track                    [Page 2]
+
+RFC 8342                          NMDA                        March 2018
+
+
+   Appendix A. Guidelines for Defining Datastores ....................31
+     A.1. Define Which YANG Modules Can Be Used in the Datastore .....31
+     A.2. Define Which Subset of YANG-Modeled Data Applies ...........31
+     A.3. Define How Data Is Actualized ..............................31
+     A.4. Define Which Protocols Can Be Used .........................31
+     A.5. Define YANG Identities for the Datastore ...................32
+   Appendix B. Example of an Ephemeral Dynamic Configuration
+               Datastore .............................................32
+   Appendix C. Example Data ..........................................33
+     C.1. System Example .............................................34
+     C.2. BGP Example ................................................37
+       C.2.1. Datastores .............................................38
+       C.2.2. Adding a Peer ..........................................38
+       C.2.3. Removing a Peer ........................................39
+     C.3. Interface Example ..........................................40
+       C.3.1. Pre-provisioned Interfaces .............................41
+       C.3.2. System-Provided Interface ..............................42
+   Acknowledgments ...................................................43
+   Authors' Addresses ................................................44
+
+1.  Introduction
+
+   This document provides an architectural framework for datastores as
+   they are used by network management protocols such as the Network
+   Configuration Protocol (NETCONF) [RFC6241], RESTCONF [RFC8040], and
+   the YANG data modeling language [RFC7950].  Datastores are a
+   fundamental concept binding network management data models to network
+   management protocols.  Agreement on a common architectural model of
+   datastores ensures that data models can be written in a way that is
+   network management protocol agnostic.  This architectural framework
+   identifies a set of conceptual datastores, but it does not mandate
+   that all network management protocols expose all these conceptual
+   datastores.  This architecture is agnostic with regard to the
+   encoding used by network management protocols.
+
+   This document updates RFC 7950 by refining the definition of the
+   accessible tree for some XML Path Language (XPath) context (see
+   Section 6.1) and the invocation context of operations (see
+   Section 6.2).
+
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+   "OPTIONAL" in this document are to be interpreted as described in
+   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
+   capitals, as shown here.
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                    [Page 3]
+
+RFC 8342                          NMDA                        March 2018
+
+
+2.  Objectives
+
+   Network management data objects can often take two different values:
+   the value configured by the user or an application (configuration)
+   and the value that the device is actually using (operational state).
+   These two values may be different for a number of reasons, e.g.,
+   system internal interactions with hardware, interaction with
+   protocols or other devices, or simply the time it takes to propagate
+   a configuration change to the software and hardware components of a
+   system.  Furthermore, configuration and operational state data
+   objects may have different lifetimes.
+
+   The original model of datastores required these data objects to be
+   modeled twice in the YANG schema -- as "config true" objects and as
+   "config false" objects.  The convention adopted by the interfaces
+   data model [RFC8343] and the IP data model [RFC8344] was to use two
+   separate branches rooted at the root of the data tree: one branch for
+   configuration data objects and one branch for operational state data
+   objects.
+
+   The duplication of definitions and the ad hoc separation of
+   operational state data from configuration data lead to a number of
+   problems.  Having configuration and operational state data in
+   separate branches in the data model is operationally complicated and
+   impacts the readability of module definitions.  Furthermore, the
+   relationship between the branches is not machine readable, and filter
+   expressions operating on configuration and on related operational
+   state are different.
+
+   With the revised architectural model of datastores defined in this
+   document, the data objects are defined only once in the YANG schema
+   but independent instantiations can appear in different datastores,
+   e.g., one for a configured value and another for an operationally
+   used value.  This provides a more elegant and simpler solution to the
+   problem.
+
+   The revised architectural model of datastores supports additional
+   datastores for systems that support more advanced processing chains
+   converting configuration to operational state.  For example, some
+   systems support configuration that is not currently used (so-called
+   "inactive configuration") or they support configuration templates
+   that are used to expand configuration data via a common template.
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                    [Page 4]
+
+RFC 8342                          NMDA                        March 2018
+
+
+3.  Terminology
+
+   This document defines the following terminology.  Some of the terms
+   are revised definitions of terms originally defined in [RFC6241] and
+   [RFC7950] (see also Section 4).  The revised definitions are
+   semantically equivalent to the definitions found in [RFC6241] and
+   [RFC7950].  It is expected that the revised definitions provided in
+   this section will replace the definitions in [RFC6241] and [RFC7950]
+   when these documents are revised.
+
+   o  datastore: A conceptual place to store and access information.  A
+      datastore might be implemented, for example, using files, a
+      database, flash memory locations, or combinations thereof.  A
+      datastore maps to an instantiated YANG data tree.
+
+   o  schema node: A node in the schema tree.  The formal definition is
+      provided in RFC 7950.
+
+   o  datastore schema: The combined set of schema nodes for all modules
+      supported by a particular datastore, taking into consideration any
+      deviations and enabled features for that datastore.
+
+   o  configuration: Data that is required to get a device from its
+      initial default state into a desired operational state.  This data
+      is modeled in YANG using "config true" nodes.  Configuration can
+      originate from different sources.
+
+   o  configuration datastore: A datastore holding configuration.
+
+   o  running configuration datastore: A configuration datastore holding
+      the current configuration of the device.  It may include
+      configuration that requires further transformations before it can
+      be applied.  This datastore is referred to as "<running>".
+
+   o  candidate configuration datastore: A configuration datastore that
+      can be manipulated without impacting the device's running
+      configuration datastore and that can be committed to the running
+      configuration datastore.  This datastore is referred to as
+      "<candidate>".
+
+   o  startup configuration datastore: A configuration datastore holding
+      the configuration loaded by the device into the running
+      configuration datastore when it boots.  This datastore is referred
+      to as "<startup>".
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                    [Page 5]
+
+RFC 8342                          NMDA                        March 2018
+
+
+   o  intended configuration: Configuration that is intended to be used
+      by the device.  It represents the configuration after all
+      configuration transformations to <running> have been performed and
+      is the configuration that the system attempts to apply.
+
+   o  intended configuration datastore: A configuration datastore
+      holding the complete intended configuration of the device.  This
+      datastore is referred to as "<intended>".
+
+   o  configuration transformation: The addition, modification, or
+      removal of configuration between the <running> and <intended>
+      datastores.  Examples of configuration transformations include the
+      removal of inactive configuration and the configuration produced
+      through the expansion of templates.
+
+   o  conventional configuration datastore: One of the following set of
+      configuration datastores: <running>, <startup>, <candidate>, and
+      <intended>.  These datastores share a common datastore schema, and
+      protocol operations allow copying data between these datastores.
+      The term "conventional" is chosen as a generic umbrella term for
+      these datastores.
+
+   o  conventional configuration: Configuration that is stored in any of
+      the conventional configuration datastores.
+
+   o  dynamic configuration datastore: A configuration datastore holding
+      configuration obtained dynamically during the operation of a
+      device through interaction with other systems, rather than through
+      one of the conventional configuration datastores.
+
+   o  dynamic configuration: Configuration obtained via a dynamic
+      configuration datastore.
+
+   o  learned configuration: Configuration that has been learned via
+      protocol interactions with other systems and that is neither
+      conventional nor dynamic configuration.
+
+   o  system configuration: Configuration that is supplied by the device
+      itself.
+
+   o  default configuration: Configuration that is not explicitly
+      provided but for which a value defined in the data model is used.
+
+   o  applied configuration: Configuration that is actively in use by a
+      device.  Applied configuration originates from conventional,
+      dynamic, learned, system, and default configuration.
+
+
+
+
+
+Bjorklund, et al.            Standards Track                    [Page 6]
+
+RFC 8342                          NMDA                        March 2018
+
+
+   o  system state: The additional data on a system that is not
+      configuration, such as read-only status information and collected
+      statistics.  System state is transient and modified by
+      interactions with internal components or other systems.  System
+      state is modeled in YANG using "config false" nodes.
+
+   o  operational state: The combination of applied configuration and
+      system state.
+
+   o  operational state datastore: A datastore holding the complete
+      operational state of the device.  This datastore is referred to as
+      "<operational>".
+
+   o  origin: A metadata annotation indicating the origin of a
+      data item.
+
+   o  remnant configuration: Configuration that remains part of the
+      applied configuration for a period of time after it has been
+      removed from the intended configuration or dynamic configuration.
+      The time period may be minimal or may last until all resources
+      used by the newly deleted configuration (e.g., network
+      connections, memory allocations, file handles) have been
+      deallocated.
+
+   The following additional terms are not datastore specific, but they
+   are commonly used and are thus defined here as well:
+
+   o  client: An entity that can access YANG-defined data on a server,
+      over some network management protocol.
+
+   o  server: An entity that provides access to YANG-defined data to a
+      client, over some network management protocol.
+
+   o  notification: A server-initiated message indicating that a certain
+      event has been recognized by the server.
+
+   o  remote procedure call: An operation that can be invoked by a
+      client on a server.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                    [Page 7]
+
+RFC 8342                          NMDA                        March 2018
+
+
+4.  Background
+
+   NETCONF [RFC6241] provides the following definitions:
+
+   o  datastore: A conceptual place to store and access information.  A
+      datastore might be implemented, for example, using files, a
+      database, flash memory locations, or combinations thereof.
+
+   o  configuration datastore: The datastore holding the complete set of
+      configuration that is required to get a device from its initial
+      default state into a desired operational state.
+
+   YANG 1.1 [RFC7950] provides the following refinements when NETCONF is
+   used with YANG (which is the usual case, but note that NETCONF was
+   defined before YANG existed):
+
+   o  datastore: When modeled with YANG, a datastore is realized as an
+      instantiated data tree.
+
+   o  configuration datastore: When modeled with YANG, a configuration
+      datastore is realized as an instantiated data tree with
+      configuration.
+
+   [RFC6244] defined operational state data as follows:
+
+   o  Operational state data is a set of data that has been obtained by
+      the system at runtime and influences the system's behavior similar
+      to configuration data.  In contrast to configuration data,
+      operational state is transient and modified by interactions with
+      internal components or other systems via specialized protocols.
+
+   Section 4.3.3 of [RFC6244] discusses operational state and mentions,
+   among other things, the option to consider operational state as being
+   stored in another datastore.  Section 4.4 of [RFC6244] then concludes
+   that, at the time of its writing, modeling state as distinct leafs
+   and distinct branches is the recommended approach.
+
+   Implementation experience and requests from operators [OpState-Reqs]
+   [OpState-Modeling] indicate that the datastore model initially
+   designed for NETCONF and refined by YANG needs to be extended.  In
+   particular, the notion of intended configuration and applied
+   configuration has developed.
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                    [Page 8]
+
+RFC 8342                          NMDA                        March 2018
+
+
+4.1.  Original Model of Datastores
+
+   The following drawing shows the original model of datastores as it is
+   currently used by NETCONF [RFC6241]:
+
+          +-------------+                 +-----------+
+          | <candidate> |                 | <startup> |
+          |  (ct, rw)   |<---+       +--->| (ct, rw)  |
+          +-------------+    |       |    +-----------+
+                 |           |       |           |
+                 |         +-----------+         |
+                 +-------->| <running> |<--------+
+                           | (ct, rw)  |
+                           +-----------+
+                                 |
+                                 v
+                          operational state  <--- control plane
+                              (cf, ro)
+
+          ct = config true; cf = config false
+          rw = read-write; ro = read-only
+          boxes denote datastores
+
+                                 Figure 1
+
+   Note that this diagram simplifies the model: "read-only" (ro) and
+   "read-write" (rw) are to be understood from the client's perspective,
+   at a conceptual level.  In NETCONF, for example, support for
+   <candidate> and <startup> is optional, and <running> does not have to
+   be writable.  Furthermore, <startup> can only be modified by copying
+   <running> to <startup> in the standardized NETCONF datastore editing
+   model.  The RESTCONF protocol does not expose these differences and
+   instead provides only a writable unified datastore, which hides
+   whether edits are done through <candidate>, by directly modifying
+   <running>, or via some other implementation-specific mechanism.
+   RESTCONF also hides how configuration is made persistent.  Note that
+   implementations may also have additional datastores that can
+   propagate changes to <running>.  NETCONF explicitly mentions
+   so-called "named datastores".
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                    [Page 9]
+
+RFC 8342                          NMDA                        March 2018
+
+
+   Some observations:
+
+   o  Operational state has not been defined as a datastore, although
+      there were proposals in the past to introduce an operational state
+      datastore.
+
+   o  The NETCONF <get> operation returns the contents of <running>
+      together with the operational state.  It is therefore necessary
+      that "config false" data be in a different branch than the
+      "config true" data if the operational state can have a different
+      lifetime compared to configuration or if configuration is not
+      immediately or successfully applied.
+
+   o  Several implementations have proprietary mechanisms that allow
+      clients to store inactive data in <running>.  Inactive data is
+      conceptually removed before validation.
+
+   o  Some implementations have proprietary mechanisms that allow
+      clients to define configuration templates in <running>.  These
+      templates are expanded automatically by the system, and the
+      resulting configuration is applied internally.
+
+   o  Some operators have reported that it is essential for them to be
+      able to retrieve the configuration that has actually been
+      successfully applied, which may be a subset or a superset of the
+      <running> configuration.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 10]
+
+RFC 8342                          NMDA                        March 2018
+
+
+5.  Architectural Model of Datastores
+
+   Below is a new conceptual model of datastores, extending the original
+   model in order to reflect the experience gained with the original
+   model.
+
+     +-------------+                 +-----------+
+     | <candidate> |                 | <startup> |
+     |  (ct, rw)   |<---+       +--->| (ct, rw)  |
+     +-------------+    |       |    +-----------+
+            |           |       |           |
+            |         +-----------+         |
+            +-------->| <running> |<--------+
+                      | (ct, rw)  |
+                      +-----------+
+                            |
+                            |        // configuration transformations,
+                            |        // e.g., removal of nodes marked as
+                            |        // "inactive", expansion of
+                            |        // templates
+                            v
+                      +------------+
+                      | <intended> | // subject to validation
+                      | (ct, ro)   |
+                      +------------+
+                            |        // changes applied, subject to
+                            |        // local factors, e.g., missing
+                            |        // resources, delays
+                            |
+       dynamic              |   +-------- learned configuration
+       configuration        |   +-------- system configuration
+       datastores -----+    |   +-------- default configuration
+                       |    |   |
+                       v    v   v
+                    +---------------+
+                    | <operational> | <-- system state
+                    | (ct + cf, ro) |
+                    +---------------+
+
+     ct = config true; cf = config false
+     rw = read-write; ro = read-only
+     boxes denote named datastores
+
+                                 Figure 2
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 11]
+
+RFC 8342                          NMDA                        March 2018
+
+
+5.1.  Conventional Configuration Datastores
+
+   The conventional configuration datastores are a set of configuration
+   datastores that share exactly the same datastore schema, allowing
+   data to be copied between them.  The term is meant as a generic
+   umbrella description of these datastores.  If a module does not
+   contain any configuration data nodes and it is not needed to satisfy
+   any imports, then it MAY be omitted from the datastore schema for the
+   conventional configuration datastores.  The set of datastores
+   include:
+
+   o  <running>
+
+   o  <candidate>
+
+   o  <startup>
+
+   o  <intended>
+
+   Other conventional configuration datastores may be defined in future
+   documents.
+
+   The flow of data between these datastores is depicted in Section 5.
+
+   The specific protocols may define explicit operations to copy between
+   these datastores, e.g., NETCONF defines the <copy-config> operation.
+
+5.1.1.  The Startup Configuration Datastore (<startup>)
+
+   The startup configuration datastore (<startup>) is a configuration
+   datastore holding the configuration loaded by the device when it
+   boots.  <startup> is only present on devices that separate the
+   startup configuration from the running configuration datastore.
+
+   The startup configuration datastore may not be supported by all
+   protocols or implementations.
+
+   On devices that support non-volatile storage, the contents of
+   <startup> will typically persist across reboots via that storage.  At
+   boot time, the device loads the saved startup configuration into
+   <running>.  To save a new startup configuration, data is copied to
+   <startup> via either implicit or explicit protocol operations.
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 12]
+
+RFC 8342                          NMDA                        March 2018
+
+
+5.1.2.  The Candidate Configuration Datastore (<candidate>)
+
+   The candidate configuration datastore (<candidate>) is a
+   configuration datastore that can be manipulated without impacting the
+   device's current configuration and that can be committed to
+   <running>.
+
+   The candidate configuration datastore may not be supported by all
+   protocols or implementations.
+
+   <candidate> does not typically persist across reboots, even in the
+   presence of non-volatile storage.  If <candidate> is stored using
+   non-volatile storage, it is reset at boot time to the contents of
+   <running>.
+
+5.1.3.  The Running Configuration Datastore (<running>)
+
+   The running configuration datastore (<running>) is a configuration
+   datastore that holds the current configuration of the device.  It MAY
+   include configuration that requires further transformation before it
+   can be applied, e.g., inactive configuration, or template-mechanism-
+   oriented configuration that needs further expansion.  However,
+   <running> MUST always be a valid configuration data tree, as defined
+   in Section 8.1 of [RFC7950].
+
+   <running> MUST be supported if the device can be configured via
+   conventional configuration datastores.
+
+   If a device does not have a distinct <startup> and non-volatile
+   storage is available, the device will typically use that non-volatile
+   storage to allow <running> to persist across reboots.
+
+5.1.4.  The Intended Configuration Datastore (<intended>)
+
+   The intended configuration datastore (<intended>) is a read-only
+   configuration datastore.  It represents the configuration after all
+   configuration transformations to <running> are performed (e.g.,
+   template expansion, removal of inactive configuration) and is the
+   configuration that the system attempts to apply.
+
+   <intended> is tightly coupled to <running>.  Whenever data is written
+   to <running>, the server MUST also immediately update and validate
+   <intended>.
+
+   <intended> MAY also be updated independently of <running> if the
+   effect of a configuration transformation changes, but <intended> MUST
+   always be a valid configuration data tree, as defined in Section 8.1
+   of [RFC7950].
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 13]
+
+RFC 8342                          NMDA                        March 2018
+
+
+   For simple implementations, <running> and <intended> are identical.
+
+   The contents of <intended> are also related to the "config true"
+   subset of <operational>; hence, a client can determine to what extent
+   the intended configuration is currently in use by checking to see
+   whether the contents of <intended> also appear in <operational>.
+
+   <intended> does not persist across reboots; its relationship with
+   <running> makes that unnecessary.
+
+   Currently, there are no standard mechanisms defined that affect
+   <intended> so that it would have different content than <running>,
+   but this architecture allows for such mechanisms to be defined.
+
+   One example of such a mechanism is support for marking nodes as
+   inactive in <running>.  Inactive nodes are not copied to <intended>.
+   A second example is support for templates, which can perform
+   transformations on the configuration from <running> to the
+   configuration written to <intended>.
+
+5.2.  Dynamic Configuration Datastores
+
+   The model recognizes the need for dynamic configuration datastores
+   that are, by definition, not part of the persistent configuration of
+   a device.  In some contexts, these have been termed "ephemeral
+   datastores", since the information is ephemeral, i.e., lost upon
+   reboot.  The dynamic configuration datastores interact with the rest
+   of the system through <operational>.
+
+   The datastore schema for a dynamic configuration datastore MAY differ
+   from the datastore schema used for conventional configuration
+   datastores.  If a module does not contain any configuration data
+   nodes and it is not needed to satisfy any imports, then it MAY be
+   omitted from the datastore schema for the dynamic configuration
+   datastore.
+
+5.3.  The Operational State Datastore (<operational>)
+
+   The operational state datastore (<operational>) is a read-only
+   datastore that consists of all "config true" and "config false" nodes
+   defined in the datastore's schema.  In the original NETCONF model,
+   the operational state only had "config false" nodes.  The reason for
+   incorporating "config true" nodes here is to be able to expose all
+   operational settings without having to replicate definitions in the
+   data models.
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 14]
+
+RFC 8342                          NMDA                        March 2018
+
+
+   <operational> contains system state and all configuration actually
+   used by the system.  This includes all applied configuration from
+   <intended>, learned configuration, system-provided configuration, and
+   default values defined by any supported data models.  In addition,
+   <operational> also contains applied configuration from dynamic
+   configuration datastores.
+
+   The datastore schema for <operational> MUST be a superset of the
+   combined datastore schema used in all configuration datastores,
+   except that configuration data nodes supported in a configuration
+   datastore MAY be omitted from <operational> if a server is not able
+   to accurately report them.
+
+   Requests to retrieve nodes from <operational> always return the value
+   in use if the node exists, regardless of any default value specified
+   in the YANG module.  If no value is returned for a given node, then
+   this implies that the node is not used by the device.
+
+   The interpretation of what constitutes being "in use" by the system
+   is dependent on both the schema definition and the device
+   implementation.  Generally, functionality that is enabled and
+   operational on the system would be considered to be "in use".
+   Conversely, functionality that is neither enabled nor operational on
+   the system is considered not to be "in use"; hence, it SHOULD be
+   omitted from <operational>.
+
+   <operational> SHOULD conform to any constraints specified in the data
+   model, but given the principal aim of returning "in use" values, it
+   is possible that constraints MAY be violated under some circumstances
+   (e.g., an abnormal value is "in use", the structure of a list is
+   being modified, or remnant configuration (see Section 5.3.1) still
+   exists).  Note that deviations SHOULD be used when it is known in
+   advance that a device does not fully conform to the <operational>
+   schema.
+
+   Only semantic constraints MAY be violated.  These are the YANG
+   "when", "must", "mandatory", "unique", "min-elements", and
+   "max-elements" statements; and the uniqueness of key values.
+
+   Syntactic constraints MUST NOT be violated, including hierarchical
+   organization, identifiers, and type-based constraints.  If a node in
+   <operational> does not meet the syntactic constraints, then it
+   MUST NOT be returned, and some other mechanism should be used to flag
+   the error.
+
+   <operational> does not persist across reboots.
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 15]
+
+RFC 8342                          NMDA                        March 2018
+
+
+5.3.1.  Remnant Configuration
+
+   Changes to configuration may take time to percolate through to
+   <operational>.  During this period, <operational> may contain nodes
+   for both the previous and current configuration, as closely as
+   possible tracking the current operation of the device.  Such remnant
+   configuration from the previous configuration persists until the
+   system has released resources used by the newly deleted configuration
+   (e.g., network connections, memory allocations, file handles).
+
+   Remnant configuration is a common example of where the semantic
+   constraints defined in the data model cannot be relied upon for
+   <operational>, since the system may have remnant configuration whose
+   constraints were valid with the previous configuration and that are
+   not valid with the current configuration.  Since constraints on
+   "config false" nodes may refer to "config true" nodes, remnant
+   configuration may force the violation of those constraints.
+
+5.3.2.  Missing Resources
+
+   Configuration in <intended> can refer to resources that are not
+   available or otherwise not physically present.  In these situations,
+   these parts of <intended> are not applied.  The data appears in
+   <intended> but does not appear in <operational>.
+
+   A typical example is an interface configuration that refers to an
+   interface that is not currently present.  In such a situation, the
+   interface configuration remains in <intended> but the interface
+   configuration will not appear in <operational>.
+
+   Note that configuration validity cannot depend on the current state
+   of such resources, since that would imply that removing a resource
+   might render the configuration invalid.  This is unacceptable,
+   especially given that rebooting such a device would cause it to
+   restart with an invalid configuration.  Instead, we allow
+   configuration for missing resources to exist in <running> and
+   <intended>, but it will not appear in <operational>.
+
+5.3.3.  System-Controlled Resources
+
+   Sometimes, resources are controlled by the device and the
+   corresponding system-controlled data appears in (and disappears from)
+   <operational> dynamically.  If a system-controlled resource has
+   matching configuration in <intended> when it appears, the system will
+   try to apply the configuration; this causes the configuration to
+   appear in <operational> eventually (if application of the
+   configuration was successful).
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 16]
+
+RFC 8342                          NMDA                        March 2018
+
+
+5.3.4.  Origin Metadata Annotation
+
+   As configuration flows into <operational>, it is conceptually marked
+   with a metadata annotation [RFC7952] that indicates its origin.  The
+   origin applies to all configuration nodes except non-presence
+   containers.  The "origin" metadata annotation is defined in
+   Section 7.  The values are YANG identities.  The following identities
+   are defined:
+
+   o  origin: abstract base identity from which the other origin
+      identities are derived.
+
+   o  intended: represents configuration provided by <intended>.
+
+   o  dynamic: represents configuration provided by a dynamic
+      configuration datastore.
+
+   o  system: represents configuration provided by the system itself.
+      Examples of system configuration include applied configuration for
+      an always-existing loopback interface, or interface configuration
+      that is auto-created due to the hardware currently present in the
+      device.
+
+   o  learned: represents configuration that has been learned via
+      protocol interactions with other systems, including such protocols
+      as link-layer negotiations, routing protocols, and DHCP.
+
+   o  default: represents configuration using a default value specified
+      in the data model, using either values in the "default" statement
+      or any values described in the "description" statement.  The
+      default origin is only used when the configuration has not been
+      provided by any other source.
+
+   o  unknown: represents configuration for which the system cannot
+      identify the origin.
+
+   These identities can be further refined, e.g., there could be
+   separate identities for particular types or instances of dynamic
+   configuration datastores derived from "dynamic".
+
+   For all configuration data nodes in <operational>, the device SHOULD
+   report the origin that most accurately reflects the source of the
+   configuration that is in use by the system.
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 17]
+
+RFC 8342                          NMDA                        March 2018
+
+
+   In cases where it could be ambiguous as to which origin should be
+   used, i.e., where the same data node value has originated from
+   multiple sources, the "description" statement in the YANG module
+   SHOULD be used as guidance for choosing the appropriate origin.  For
+   example:
+
+   If, for a particular configuration node, the associated YANG
+   "description" statement indicates that a protocol-negotiated value
+   overrides any configured value, then the origin would be reported as
+   "learned", even when a learned value is the same as the configured
+   value.
+
+   Conversely, if, for a particular configuration node, the associated
+   YANG "description" statement indicates that a protocol-negotiated
+   value does not override an explicitly configured value, then the
+   origin would be reported as "intended", even when a learned value is
+   the same as the configured value.
+
+   In the case that a device cannot provide an accurate origin for a
+   particular configuration data node, it SHOULD use the origin
+   "unknown".
+
+6.  Implications on YANG
+
+6.1.  XPath Context
+
+   This section updates Section 6.4.1 of RFC 7950.
+
+   If a server implements the architecture defined in this document, the
+   accessible trees for some XPath contexts are refined as follows:
+
+   o  If the XPath expression is defined in a substatement to a data
+      node that represents system state, the accessible tree is all
+      operational state in the server.  The root node has all top-level
+      data nodes in all modules as children.
+
+   o  If the XPath expression is defined in a substatement to a
+      "notification" statement, the accessible tree is the notification
+      instance and all operational state in the server.  If the
+      notification is defined on the top level in a module, then the
+      root node has the node representing the notification being defined
+      and all top-level data nodes in all modules as children.
+      Otherwise, the root node has all top-level data nodes in all
+      modules as children.
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 18]
+
+RFC 8342                          NMDA                        March 2018
+
+
+   o  If the XPath expression is defined in a substatement to an "input"
+      statement in an "rpc" or "action" statement, the accessible tree
+      is the RPC or action operation instance and all operational state
+      in the server.  The root node has top-level data nodes in all
+      modules as children.  Additionally, for an RPC, the root node also
+      has the node representing the RPC operation being defined as a
+      child.  The node representing the operation being defined has the
+      operation's input parameters as children.
+
+   o  If the XPath expression is defined in a substatement to an
+      "output" statement in an "rpc" or "action" statement, the
+      accessible tree is the RPC or action operation instance and all
+      operational state in the server.  The root node has top-level data
+      nodes in all modules as children.  Additionally, for an RPC, the
+      root node also has the node representing the RPC operation being
+      defined as a child.  The node representing the operation being
+      defined has the operation's output parameters as children.
+
+6.2.  Invocation of Actions and RPCs
+
+   This section updates Section 7.15 of RFC 7950.
+
+   Actions are always invoked in the context of the operational state
+   datastore.  The node for which the action is invoked MUST exist in
+   the operational state datastore.
+
+   Note that this document does not constrain the result of invoking an
+   RPC or action in any way.  For example, an RPC might be defined to
+   modify the contents of some datastore.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 19]
+
+RFC 8342                          NMDA                        March 2018
+
+
+7.  YANG Modules
+
+   <CODE BEGINS> file "ietf-datastores@2018-02-14.yang"
+
+   module ietf-datastores {
+     yang-version 1.1;
+     namespace "urn:ietf:params:xml:ns:yang:ietf-datastores";
+     prefix ds;
+
+     organization
+       "IETF Network Modeling (NETMOD) Working Group";
+
+     contact
+       "WG Web:   <https://datatracker.ietf.org/wg/netmod/>
+
+        WG List:  <mailto:netmod@ietf.org>
+
+        Author:   Martin Bjorklund
+                  <mailto:mbj@tail-f.com>
+
+        Author:   Juergen Schoenwaelder
+                  <mailto:j.schoenwaelder@jacobs-university.de>
+
+        Author:   Phil Shafer
+                  <mailto:phil@juniper.net>
+
+        Author:   Kent Watsen
+                  <mailto:kwatsen@juniper.net>
+
+        Author:   Rob Wilton
+                  <rwilton@cisco.com>";
+
+     description
+       "This YANG module defines a set of identities for identifying
+        datastores.
+
+        Copyright (c) 2018 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
+        Relating to IETF Documents
+        (https://trustee.ietf.org/license-info).
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 20]
+
+RFC 8342                          NMDA                        March 2018
+
+
+        This version of this YANG module is part of RFC 8342
+        (https://www.rfc-editor.org/info/rfc8342); see the RFC itself
+        for full legal notices.";
+
+     revision 2018-02-14 {
+       description
+         "Initial revision.";
+       reference
+         "RFC 8342: Network Management Datastore Architecture (NMDA)";
+     }
+
+     /*
+      * Identities
+      */
+
+     identity datastore {
+       description
+         "Abstract base identity for datastore identities.";
+     }
+
+     identity conventional {
+       base datastore;
+       description
+         "Abstract base identity for conventional configuration
+          datastores.";
+     }
+
+     identity running {
+       base conventional;
+       description
+         "The running configuration datastore.";
+     }
+
+     identity candidate {
+       base conventional;
+       description
+         "The candidate configuration datastore.";
+     }
+
+     identity startup {
+       base conventional;
+       description
+         "The startup configuration datastore.";
+     }
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 21]
+
+RFC 8342                          NMDA                        March 2018
+
+
+     identity intended {
+       base conventional;
+       description
+         "The intended configuration datastore.";
+     }
+
+     identity dynamic {
+       base datastore;
+       description
+         "Abstract base identity for dynamic configuration datastores.";
+     }
+
+     identity operational {
+       base datastore;
+       description
+         "The operational state datastore.";
+     }
+
+     /*
+      * Type definitions
+      */
+
+     typedef datastore-ref {
+       type identityref {
+         base datastore;
+       }
+       description
+         "A datastore identity reference.";
+     }
+   }
+
+   <CODE ENDS>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 22]
+
+RFC 8342                          NMDA                        March 2018
+
+
+   <CODE BEGINS> file "ietf-origin@2018-02-14.yang"
+
+   module ietf-origin {
+     yang-version 1.1;
+     namespace "urn:ietf:params:xml:ns:yang:ietf-origin";
+     prefix or;
+
+     import ietf-yang-metadata {
+       prefix md;
+     }
+
+     organization
+       "IETF Network Modeling (NETMOD) Working Group";
+
+     contact
+       "WG Web:   <https://datatracker.ietf.org/wg/netmod/>
+
+        WG List:  <mailto:netmod@ietf.org>
+
+        Author:   Martin Bjorklund
+                  <mailto:mbj@tail-f.com>
+
+        Author:   Juergen Schoenwaelder
+                  <mailto:j.schoenwaelder@jacobs-university.de>
+
+        Author:   Phil Shafer
+                  <mailto:phil@juniper.net>
+
+        Author:   Kent Watsen
+                  <mailto:kwatsen@juniper.net>
+
+        Author:   Rob Wilton
+                  <rwilton@cisco.com>";
+
+     description
+       "This YANG module defines an 'origin' metadata annotation and a
+        set of identities for the origin value.
+
+        Copyright (c) 2018 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
+        Relating to IETF Documents
+        (https://trustee.ietf.org/license-info).
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 23]
+
+RFC 8342                          NMDA                        March 2018
+
+
+        This version of this YANG module is part of RFC 8342
+        (https://www.rfc-editor.org/info/rfc8342); see the RFC itself
+        for full legal notices.";
+
+     revision 2018-02-14 {
+       description
+         "Initial revision.";
+       reference
+         "RFC 8342: Network Management Datastore Architecture (NMDA)";
+     }
+
+     /*
+      * Identities
+      */
+
+     identity origin {
+       description
+         "Abstract base identity for the origin annotation.";
+     }
+
+     identity intended {
+       base origin;
+       description
+         "Denotes configuration from the intended configuration
+          datastore.";
+     }
+
+     identity dynamic {
+       base origin;
+       description
+         "Denotes configuration from a dynamic configuration
+          datastore.";
+     }
+
+     identity system {
+       base origin;
+       description
+         "Denotes configuration originated by the system itself.
+
+          Examples of system configuration include applied configuration
+          for an always-existing loopback interface, or interface
+          configuration that is auto-created due to the hardware
+          currently present in the device.";
+     }
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 24]
+
+RFC 8342                          NMDA                        March 2018
+
+
+     identity learned {
+       base origin;
+       description
+         "Denotes configuration learned from protocol interactions with
+          other devices, instead of via either the intended
+          configuration datastore or any dynamic configuration
+          datastore.
+
+          Examples of protocols that provide learned configuration
+          include link-layer negotiations, routing protocols, and
+          DHCP.";
+     }
+
+     identity default {
+       base origin;
+       description
+         "Denotes configuration that does not have a configured or
+          learned value but has a default value in use.  Covers both
+          values defined in a 'default' statement and values defined
+          via an explanation in a 'description' statement.";
+     }
+
+     identity unknown {
+       base origin;
+       description
+         "Denotes configuration for which the system cannot identify the
+          origin.";
+     }
+
+     /*
+      * Type definitions
+      */
+
+     typedef origin-ref {
+       type identityref {
+         base origin;
+       }
+       description
+         "An origin identity reference.";
+     }
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 25]
+
+RFC 8342                          NMDA                        March 2018
+
+
+     /*
+      * Metadata annotations
+      */
+
+     md:annotation origin {
+       type origin-ref;
+       description
+         "The 'origin' annotation can be present on any configuration
+          data node in the operational state datastore.  It specifies
+          from where the node originated.  If not specified for a given
+          configuration data node, then the origin is the same as the
+          origin of its parent node in the data tree.  The origin for
+          any top-level configuration data nodes must be specified.";
+     }
+   }
+
+   <CODE ENDS>
+
+8.  IANA Considerations
+
+8.1.  Updates to the IETF XML Registry
+
+   This document registers two URIs in the "IETF XML Registry"
+   [RFC3688].  Following the format in [RFC3688], the following
+   registrations have been made:
+
+      URI: urn:ietf:params:xml:ns:yang:ietf-datastores
+      Registrant Contact: The IESG.
+      XML: N/A; the requested URI is an XML namespace.
+
+      URI: urn:ietf:params:xml:ns:yang:ietf-origin
+      Registrant Contact: The IESG.
+      XML: N/A; the requested URI is an XML namespace.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 26]
+
+RFC 8342                          NMDA                        March 2018
+
+
+8.2.  Updates to the YANG Module Names Registry
+
+   This document registers two YANG modules in the "YANG Module Names"
+   registry [RFC6020].  Following the format in [RFC6020], the following
+   registrations have been made:
+
+      name:         ietf-datastores
+      namespace:    urn:ietf:params:xml:ns:yang:ietf-datastores
+      prefix:       ds
+      reference:    RFC 8342
+
+      name:         ietf-origin
+      namespace:    urn:ietf:params:xml:ns:yang:ietf-origin
+      prefix:       or
+      reference:    RFC 8342
+
+9.  Security Considerations
+
+   This document discusses an architectural model of datastores for
+   network management using NETCONF/RESTCONF and YANG.  It has no
+   security impact on the Internet.
+
+   Although this document specifies several YANG modules, these modules
+   only define identities and a metadata annotation; hence, the "YANG
+   module security guidelines" [YANG-SEC] do not apply.
+
+   The origin metadata annotation exposes the origin of values in the
+   applied configuration.  Origin information may provide hints that
+   certain control-plane protocols are active on a device.  Since origin
+   information is tied to applied configuration values, it is only
+   accessible to clients that have the permissions to read the applied
+   configuration values.  Security administrators should consider the
+   sensitivity of origin information while defining access control
+   rules.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 27]
+
+RFC 8342                          NMDA                        March 2018
+
+
+10.  References
+
+10.1.  Normative References
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119,
+              DOI 10.17487/RFC2119, March 1997,
+              <https://www.rfc-editor.org/info/rfc2119>.
+
+   [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,
+              <https://www.rfc-editor.org/info/rfc6241>.
+
+   [RFC7950]  Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
+              RFC 7950, DOI 10.17487/RFC7950, August 2016,
+              <https://www.rfc-editor.org/info/rfc7950>.
+
+   [RFC7952]  Lhotka, L., "Defining and Using Metadata with YANG",
+              RFC 7952, DOI 10.17487/RFC7952, August 2016,
+              <https://www.rfc-editor.org/info/rfc7952>.
+
+   [RFC8040]  Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
+              Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
+              <https://www.rfc-editor.org/info/rfc8040>.
+
+   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in
+              RFC 2119 Key Words", BCP 14, RFC 8174,
+              DOI 10.17487/RFC8174, May 2017,
+              <https://www.rfc-editor.org/info/rfc8174>.
+
+   [W3C.REC-xml-20081126]
+              Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and
+              F. Yergeau, "Extensible Markup Language (XML) 1.0
+              (Fifth Edition)", World Wide Web Consortium Recommendation
+              REC-xml-20081126, November 2008,
+              <https://www.w3.org/TR/2008/REC-xml-20081126>.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 28]
+
+RFC 8342                          NMDA                        March 2018
+
+
+10.2.  Informative References
+
+   [NETMOD-Operational]
+              Bjorklund, M. and L. Lhotka, "Operational Data in NETCONF
+              and YANG", Work in Progress, draft-bjorklund-netmod-
+              operational-00, October 2012.
+
+   [OpState-Enhance]
+              Watsen, K., Bierman, A., Bjorklund, M., and J.
+              Schoenwaelder, "Operational State Enhancements for YANG,
+              NETCONF, and RESTCONF", Work in Progress, draft-kwatsen-
+              netmod-opstate-02, February 2016.
+
+   [OpState-Modeling]
+              Shakir, R., Shaikh, A., and M. Hines, "Consistent Modeling
+              of Operational State Data in YANG", Work in Progress,
+              draft-openconfig-netmod-opstate-01, July 2015.
+
+   [OpState-Reqs]
+              Watsen, K. and T. Nadeau, "Terminology and Requirements
+              for Enhanced Handling of Operational State", Work in
+              Progress, draft-ietf-netmod-opstate-reqs-04, January 2016.
+
+   [RFC3688]  Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
+              DOI 10.17487/RFC3688, January 2004,
+              <https://www.rfc-editor.org/info/rfc3688>.
+
+   [RFC6020]  Bjorklund, M., Ed., "YANG - A Data Modeling Language for
+              the Network Configuration Protocol (NETCONF)", RFC 6020,
+              DOI 10.17487/RFC6020, October 2010,
+              <https://www.rfc-editor.org/info/rfc6020>.
+
+   [RFC6244]  Shafer, P., "An Architecture for Network Management Using
+              NETCONF and YANG", RFC 6244, DOI 10.17487/RFC6244,
+              June 2011, <https://www.rfc-editor.org/info/rfc6244>.
+
+   [RFC8343]  Bjorklund, M., "A YANG Data Model for Interface
+              Management", RFC 8343, DOI 10.17487/RFC8343, March 2018,
+              <https://www.rfc-editor.org/info/rfc8343>.
+
+   [RFC8344]  Bjorklund, M., "A YANG Data Model for IP Management",
+              RFC 8344, DOI 10.17487/RFC8344, March 2018,
+              <https://www.rfc-editor.org/info/rfc8344>.
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 29]
+
+RFC 8342                          NMDA                        March 2018
+
+
+   [With-config-state]
+              Wilton, R., ""With-config-state" Capability for
+              NETCONF/RESTCONF", Work in Progress, draft-wilton-netmod-
+              opstate-yang-02, December 2015.
+
+   [YANG-SEC] IETF, "YANG Security Guidelines", <https://trac.ietf.org/
+              trac/ops/wiki/yang-security-guidelines>.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 30]
+
+RFC 8342                          NMDA                        March 2018
+
+
+Appendix A.  Guidelines for Defining Datastores
+
+   The definition of a new datastore in this architecture should be
+   provided in a document (e.g., an RFC) purposed for defining the
+   datastore.  When it makes sense, more than one datastore may be
+   defined in the same document (e.g., when the datastores are logically
+   connected).  Each datastore's definition should address the points
+   specified in the subsections below.
+
+A.1.  Define Which YANG Modules Can Be Used in the Datastore
+
+   Not all YANG modules may be used in all datastores.  Some datastores
+   may constrain which data models can be used in them.  If it is
+   desirable that a subset of all modules can be targeted to the
+   datastore, then the documentation defining the datastore must
+   indicate this.
+
+A.2.  Define Which Subset of YANG-Modeled Data Applies
+
+   By default, the data in a datastore is modeled by all YANG statements
+   in the available YANG modules.  However, it is possible to specify
+   criteria that YANG statements must satisfy in order to be present in
+   a datastore.  For instance, maybe only "config true" nodes, or
+   "config false" nodes that also have a specific YANG extension, are
+   present in the datastore.
+
+A.3.  Define How Data Is Actualized
+
+   The new datastore must specify how it interacts with other
+   datastores.
+
+   For example, the diagram in Section 5 depicts dynamic configuration
+   datastores feeding into <operational>.  How this interaction occurs
+   has to be defined by the particular dynamic configuration datastores.
+   In some cases, it may occur implicitly, as soon as the data is put
+   into the dynamic configuration datastore, while in other cases an
+   explicit action (e.g., an RPC) may be required to trigger the
+   application of the datastore's data.
+
+A.4.  Define Which Protocols Can Be Used
+
+   By default, it is assumed that both the NETCONF and RESTCONF
+   protocols can be used to interact with a datastore.  However, it may
+   be that only a specific protocol can be used (e.g., Forwarding and
+   Control Element Separation (ForCES)) or that a subset of all protocol
+   operations or capabilities are available (e.g., no locking or no
+   XPath-based filtering).
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 31]
+
+RFC 8342                          NMDA                        March 2018
+
+
+A.5.  Define YANG Identities for the Datastore
+
+   The datastore must be defined with a YANG identity that uses the
+   "ds:datastore" identity, or one of its derived identities, as its
+   base.  This identity is necessary, so that the datastore can be
+   referenced in protocol operations (e.g., <get-data>).
+
+   The datastore may also be defined with an identity that uses the
+   "or:origin" identity, or one of its derived identities, as its base.
+   This identity is needed if the datastore interacts with
+   <operational>, so that data originating from the datastore can be
+   identified as such via the "origin" metadata attribute defined in
+   Section 7.
+
+   An example of these guidelines in use is provided in Appendix B.
+
+Appendix B.  Example of an Ephemeral Dynamic Configuration Datastore
+
+   This section defines documentation for an example dynamic
+   configuration datastore using the guidelines provided in Appendix A.
+   For brevity, only a terse example is provided; it is expected that a
+   standalone RFC would be written when this type of scenario is fully
+   considered.
+
+   This example defines a dynamic configuration datastore called
+   "ephemeral", which is loosely modeled after the work done in the I2RS
+   Working Group.
+
+   +--------------------+----------------------------------------------+
+   | Name               | Value                                        |
+   +--------------------+----------------------------------------------+
+   | Name               | ephemeral                                    |
+   |                    |                                              |
+   | YANG modules       | all (default)                                |
+   |                    |                                              |
+   | YANG nodes         | all "config true" data nodes                 |
+   |                    |                                              |
+   | How applied        | changes automatically propagated to          |
+   |                    | <operational>                                |
+   |                    |                                              |
+   | Protocols          | NETCONF/RESTCONF (default)                   |
+   |                    |                                              |
+   | Defining YANG      | "example-ds-ephemeral"                       |
+   | module             |                                              |
+   +--------------------+----------------------------------------------+
+
+              Properties of the Example "ephemeral" Datastore
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 32]
+
+RFC 8342                          NMDA                        March 2018
+
+
+   module example-ds-ephemeral {
+     yang-version 1.1;
+     namespace "urn:example:ds-ephemeral";
+     prefix eph;
+
+     import ietf-datastores {
+       prefix ds;
+     }
+     import ietf-origin {
+       prefix or;
+     }
+
+     // datastore identity
+     identity ds-ephemeral {
+       base ds:dynamic;
+       description
+         "The ephemeral dynamic configuration datastore.";
+     }
+
+     // origin identity
+     identity or-ephemeral {
+       base or:dynamic;
+       description
+         "Denotes data from the ephemeral dynamic configuration
+          datastore.";
+     }
+   }
+
+Appendix C.  Example Data
+
+   The use of datastores is complex, and many of the subtle effects are
+   more easily presented using examples.  This section presents a series
+   of example data models with some sample contents of the various
+   datastores.
+
+   The XML [W3C.REC-xml-20081126] snippets that follow are provided as
+   examples only.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 33]
+
+RFC 8342                          NMDA                        March 2018
+
+
+C.1.  System Example
+
+   In this example, the following fictional module is used:
+
+   module example-system {
+     yang-version 1.1;
+     namespace urn:example:system;
+     prefix sys;
+
+     import ietf-inet-types {
+       prefix inet;
+     }
+
+     container system {
+       leaf hostname {
+         type string;
+       }
+
+       list interface {
+         key name;
+
+         leaf name {
+           type string;
+         }
+
+         container auto-negotiation {
+           leaf enabled {
+             type boolean;
+             default true;
+           }
+           leaf speed {
+             type uint32;
+             units mbps;
+             description
+               "The advertised speed, in Mbps.";
+           }
+         }
+
+         leaf speed {
+           type uint32;
+           units mbps;
+           config false;
+           description
+             "The speed of the interface, in Mbps.";
+         }
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 34]
+
+RFC 8342                          NMDA                        March 2018
+
+
+         list address {
+           key ip;
+
+           leaf ip {
+             type inet:ip-address;
+           }
+           leaf prefix-length {
+             type uint8;
+           }
+         }
+       }
+     }
+   }
+
+   The operator has configured the hostname and two interfaces, so the
+   contents of <intended> are:
+
+   <system xmlns="urn:example:system">
+
+     <hostname>foo.example.com</hostname>
+
+     <interface>
+       <name>eth0</name>
+       <auto-negotiation>
+         <speed>1000</speed>
+       </auto-negotiation>
+       <address>
+         <ip>2001:db8::10</ip>
+         <prefix-length>64</prefix-length>
+       </address>
+     </interface>
+
+     <interface>
+       <name>eth1</name>
+       <address>
+         <ip>2001:db8::20</ip>
+         <prefix-length>64</prefix-length>
+       </address>
+     </interface>
+
+   </system>
+
+   The system has detected that the hardware for one of the configured
+   interfaces ("eth1") is not yet present, so the configuration for that
+   interface is not applied.  Further, the system has received a
+   hostname and an additional IP address for "eth0" over DHCP.  In
+   addition to filling in the default value for the auto-negotiation
+   enabled leaf, a loopback interface entry is also automatically
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 35]
+
+RFC 8342                          NMDA                        March 2018
+
+
+   instantiated by the system.  All of this is reflected in
+   <operational>.  Note how the "origin" metadata attribute for several
+   "config true" data nodes is inherited from their parent data nodes.
+
+   <system
+       xmlns="urn:example:system"
+       xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin">
+
+     <hostname or:origin="or:learned">bar.example.com</hostname>
+
+     <interface or:origin="or:intended">
+       <name>eth0</name>
+       <auto-negotiation>
+         <enabled or:origin="or:default">true</enabled>
+         <speed>1000</speed>
+       </auto-negotiation>
+       <speed>100</speed>
+       <address>
+         <ip>2001:db8::10</ip>
+         <prefix-length>64</prefix-length>
+       </address>
+       <address or:origin="or:learned">
+         <ip>2001:db8::1:100</ip>
+         <prefix-length>64</prefix-length>
+       </address>
+     </interface>
+
+     <interface or:origin="or:system">
+       <name>lo0</name>
+       <address>
+         <ip>::1</ip>
+         <prefix-length>128</prefix-length>
+       </address>
+     </interface>
+
+   </system>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 36]
+
+RFC 8342                          NMDA                        March 2018
+
+
+C.2.  BGP Example
+
+   Consider the following fragment of a fictional BGP module:
+
+       container bgp {
+         leaf local-as {
+           type uint32;
+         }
+         leaf peer-as {
+           type uint32;
+         }
+         list peer {
+           key name;
+           leaf name {
+             type inet:ip-address;
+           }
+           leaf local-as {
+             type uint32;
+             description
+               "... Defaults to ../local-as.";
+           }
+           leaf peer-as {
+             type uint32;
+             description
+               "... Defaults to ../peer-as.";
+           }
+           leaf local-port {
+             type inet:port;
+           }
+           leaf remote-port {
+             type inet:port;
+             default 179;
+           }
+           leaf state {
+             config false;
+             type enumeration {
+               enum init;
+               enum established;
+               enum closing;
+             }
+           }
+         }
+       }
+
+   In this example model, both bgp/peer/local-as and bgp/peer/peer-as
+   have complex hierarchical values, allowing the user to specify
+   default values for all peers in a single location.
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 37]
+
+RFC 8342                          NMDA                        March 2018
+
+
+   The model also follows the pattern of fully integrating state
+   ("config false") nodes with configuration ("config true") nodes.
+   There is no separate "bgp-state" hierarchy, with the accompanying
+   repetition of containment and naming nodes.  This makes the model
+   simpler and more readable.
+
+C.2.1.  Datastores
+
+   Each datastore represents differing views of these nodes.  <running>
+   will hold the configuration provided by the operator -- for example,
+   a single BGP peer.  <intended> will conceptually hold the data as
+   validated, after the removal of data not intended for validation and
+   after any local template mechanisms are performed.  <operational>
+   will show data from <intended> as well as any "config false" nodes.
+
+C.2.2.  Adding a Peer
+
+   If the user configures a single BGP peer, then that peer will be
+   visible in both <running> and <intended>.  It may also appear in
+   <candidate> if the server supports the candidate configuration
+   datastore.  Retrieving the peer will return only the user-specified
+   values.
+
+   No time delay should exist between the appearance of the peer in
+   <running> and <intended>.
+
+   In this scenario, we've added the following to <running>:
+
+     <bgp>
+       <local-as>64501</local-as>
+       <peer-as>64502</peer-as>
+       <peer>
+         <name>2001:db8::2:3</name>
+       </peer>
+     </bgp>
+
+C.2.2.1.  <operational>
+
+   The operational datastore will contain the fully expanded peer data,
+   including "config false" nodes.  In our example, this means that the
+   "state" node will appear.
+
+   In addition, <operational> will contain the "currently in use" values
+   for all nodes.  This means that local-as and peer-as will be
+   populated even if they are not given values in <intended>.  The value
+   of bgp/local-as will be used if bgp/peer/local-as is not provided;
+   bgp/peer-as and bgp/peer/peer-as will have the same relationship.  In
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 38]
+
+RFC 8342                          NMDA                        March 2018
+
+
+   the operational view, this means that every peer will have values for
+   their local-as and peer-as, even if those values are not explicitly
+   configured but are provided by bgp/local-as and bgp/peer-as.
+
+   Each BGP peer has a TCP connection associated with it, using the
+   values of local-port and remote-port from <intended>.  If those
+   values are not supplied, the system will select values.  When the
+   connection is established, <operational> will contain the current
+   values for the local-port and remote-port nodes regardless of the
+   origin.  If the system has chosen the values, the "origin" attribute
+   will be set to "system".  Before the connection is established, one
+   or both of the nodes may not appear, since the system may not yet
+   have their values.
+
+     <bgp xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin"
+          or:origin="or:intended">
+       <local-as>64501</local-as>
+       <peer-as>64502</peer-as>
+       <peer>
+         <name>2001:db8::2:3</name>
+         <local-as or:origin="or:default">64501</local-as>
+         <peer-as or:origin="or:default">64502</peer-as>
+         <local-port or:origin="or:system">60794</local-port>
+         <remote-port or:origin="or:default">179</remote-port>
+         <state>established</state>
+       </peer>
+     </bgp>
+
+C.2.3.  Removing a Peer
+
+   Changes to configuration may take time to percolate through the
+   various software components involved.  During this period, it is
+   imperative to continue to give an accurate view of the working of the
+   device.  <operational> will contain nodes for both the previous and
+   current configuration, as closely as possible tracking the current
+   operation of the device.
+
+   Consider the scenario where a client removes a BGP peer.  When a peer
+   is removed, the operational state will continue to reflect the
+   existence of that peer until the peer's resources are released,
+   including closing the peer's connection.  During this period, the
+   current data values will continue to be visible in <operational>,
+   with the "origin" attribute set to indicate the origin of the
+   original data.
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 39]
+
+RFC 8342                          NMDA                        March 2018
+
+
+     <bgp xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin"
+          or:origin="or:intended">
+       <local-as>64501</local-as>
+       <peer-as>64502</peer-as>
+       <peer>
+         <name>2001:db8::2:3</name>
+         <local-as or:origin="or:default">64501</local-as>
+         <peer-as or:origin="or:default">64502</peer-as>
+         <local-port or:origin="or:system">60794</local-port>
+         <remote-port or:origin="or:default">179</remote-port>
+         <state>closing</state>
+       </peer>
+     </bgp>
+
+   Once resources are released and the connection is closed, the peer's
+   data is removed from <operational>.
+
+C.3.  Interface Example
+
+   In this section, we will use this simple interface data model:
+
+     container interfaces {
+       list interface {
+         key name;
+         leaf name {
+           type string;
+         }
+         leaf description {
+           type string;
+         }
+         leaf mtu {
+           type uint16;
+         }
+         leaf-list ip-address {
+           type inet:ip-address;
+         }
+       }
+     }
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 40]
+
+RFC 8342                          NMDA                        March 2018
+
+
+C.3.1.  Pre-provisioned Interfaces
+
+   One common issue in networking devices is the support of Field
+   Replaceable Units (FRUs) that can be inserted and removed from the
+   device without requiring a reboot or interfering with normal
+   operation.  These FRUs are typically interface cards, and the devices
+   support pre-provisioning of these interfaces.
+
+   If a client creates an interface "et-0/0/0" but the interface does
+   not physically exist at this point, then <intended> might contain the
+   following:
+
+     <interfaces>
+       <interface>
+         <name>et-0/0/0</name>
+         <description>Test interface</description>
+       </interface>
+     </interfaces>
+
+   Since the interface does not exist, this data does not appear in
+   <operational>.
+
+   When a FRU containing this interface is inserted, the system will
+   detect it and process the associated configuration.  <operational>
+   will contain the data from <intended>, as well as nodes added by the
+   system, such as the current value of the interface's MTU.
+
+     <interfaces xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin"
+                 or:origin="or:intended">
+       <interface>
+         <name>et-0/0/0</name>
+         <description>Test interface</description>
+         <mtu or:origin="or:system">1500</mtu>
+       </interface>
+     </interfaces>
+
+   If the FRU is removed, the interface data is removed from
+   <operational>.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 41]
+
+RFC 8342                          NMDA                        March 2018
+
+
+C.3.2.  System-Provided Interface
+
+   Imagine that the system provides a loopback interface (named "lo0")
+   with a default IPv4 address of "127.0.0.1" and a default IPv6 address
+   of "::1".  The system will only provide configuration for this
+   interface if there is no data for it in <intended>.
+
+   When no configuration for "lo0" appears in <intended>, <operational>
+   will show the system-provided data:
+
+     <interfaces xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin"
+                 or:origin="or:intended">
+       <interface or:origin="or:system">
+         <name>lo0</name>
+         <ip-address>127.0.0.1</ip-address>
+         <ip-address>::1</ip-address>
+       </interface>
+     </interfaces>
+
+   When configuration for "lo0" does appear in <intended>, <operational>
+   will show that data with the origin set to "intended".  If the
+   "ip-address" is not provided, then the system-provided value will
+   appear as follows:
+
+     <interfaces xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin"
+                 or:origin="or:intended">
+       <interface>
+         <name>lo0</name>
+         <description>loopback</description>
+         <ip-address or:origin="or:system">127.0.0.1</ip-address>
+         <ip-address>::1</ip-address>
+       </interface>
+     </interfaces>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 42]
+
+RFC 8342                          NMDA                        March 2018
+
+
+Acknowledgments
+
+   This document grew out of many discussions that took place since
+   2010.  Several documents ([NETMOD-Operational] [With-config-state]
+   [OpState-Reqs] [OpState-Enhance] [OpState-Modeling], as well as
+   [RFC6244]), touched on some of the problems of the original datastore
+   model.  The following people were authors of these works in progress
+   or were otherwise actively involved in the discussions that led to
+   this document:
+
+   o  Lou Berger, LabN Consulting, L.L.C., <lberger@labn.net>
+
+   o  Andy Bierman, YumaWorks, <andy@yumaworks.com>
+
+   o  Marcus Hines, Google, <hines@google.com>
+
+   o  Christian Hopps, Deutsche Telekom, <chopps@chopps.org>
+
+   o  Balazs Lengyel, Ericsson, <balazs.lengyel@ericsson.com>
+
+   o  Ladislav Lhotka, CZ.NIC, <lhotka@nic.cz>
+
+   o  Acee Lindem, Cisco Systems, <acee@cisco.com>
+
+   o  Thomas Nadeau, Brocade Networks, <tnadeau@lucidvision.com>
+
+   o  Tom Petch, Engineering Networks Ltd, <ietfc@btconnect.com>
+
+   o  Anees Shaikh, Google, <aashaikh@google.com>
+
+   o  Rob Shakir, Google, <robjs@google.com>
+
+   o  Jason Sterne, Nokia, <jason.sterne@nokia.com>
+
+   Juergen Schoenwaelder was partly funded by Flamingo, a Network of
+   Excellence project (ICT-318488) supported by the European Commission
+   under its Seventh Framework Programme.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 43]
+
+RFC 8342                          NMDA                        March 2018
+
+
+Authors' Addresses
+
+   Martin Bjorklund
+   Tail-f Systems
+
+   Email: mbj@tail-f.com
+
+
+   Juergen Schoenwaelder
+   Jacobs University
+
+   Email: j.schoenwaelder@jacobs-university.de
+
+
+   Phil Shafer
+   Juniper Networks
+
+   Email: phil@juniper.net
+
+
+   Kent Watsen
+   Juniper Networks
+
+   Email: kwatsen@juniper.net
+
+
+   Robert Wilton
+   Cisco Systems
+
+   Email: rwilton@cisco.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bjorklund, et al.            Standards Track                   [Page 44]
+