summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc8342.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc8342.txt')
-rw-r--r--doc/rfc/rfc8342.txt2467
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]
+