--- 1/draft-ietf-netmod-revised-datastores-03.txt 2017-08-24 08:13:52.948927576 -0700 +++ 2/draft-ietf-netmod-revised-datastores-04.txt 2017-08-24 08:13:53.080930734 -0700 @@ -1,24 +1,24 @@ Network Working Group M. Bjorklund Internet-Draft Tail-f Systems Intended status: Standards Track J. Schoenwaelder -Expires: January 4, 2018 Jacobs University +Expires: February 25, 2018 Jacobs University P. Shafer K. Watsen Juniper Networks R. Wilton Cisco Systems - July 3, 2017 + August 24, 2017 Network Management Datastore Architecture - draft-ietf-netmod-revised-datastores-03 + draft-ietf-netmod-revised-datastores-04 Abstract Datastores are a fundamental concept binding the data models written in the YANG data modeling language to network management protocols such as 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. @@ -30,21 +30,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on January 4, 2018. + This Internet-Draft will expire on February 25, 2018. Copyright Notice Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -52,50 +52,51 @@ 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. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Background . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 3.1. Original Model of Datastores . . . . . . . . . . . . . . 6 + 3.1. Original Model of Datastores . . . . . . . . . . . . . . 7 4. Architectural Model of Datastores . . . . . . . . . . . . . . 8 4.1. The Startup Configuration Datastore () . . . . . 9 4.2. The Candidate Configuration Datastore () . . . 10 4.3. The Running Configuration Datastore () . . . . . 10 4.4. The Intended Configuration Datastore () . . . . 10 4.5. Conventional Configuration Datastores . . . . . . . . . . 11 - 4.6. Dynamic Datastores . . . . . . . . . . . . . . . . . . . 11 + 4.6. Dynamic Configuration Datastores . . . . . . . . . . . . 11 4.7. The Operational State Datastore () . . . . . 11 - 4.7.1. Missing Resources . . . . . . . . . . . . . . . . . . 12 - 4.7.2. System-controlled Resources . . . . . . . . . . . . . 13 - 4.7.3. Origin Metadata Annotation . . . . . . . . . . . . . 13 - 5. Implications on YANG . . . . . . . . . . . . . . . . . . . . 14 - 5.1. XPath Context . . . . . . . . . . . . . . . . . . . . . . 14 - 6. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 15 + 4.7.1. Remnant Configuration . . . . . . . . . . . . . . . . 12 + 4.7.2. Missing Resources . . . . . . . . . . . . . . . . . . 13 + 4.7.3. System-controlled Resources . . . . . . . . . . . . . 13 + 4.7.4. Origin Metadata Annotation . . . . . . . . . . . . . 13 + 5. Implications on YANG . . . . . . . . . . . . . . . . . . . . 15 + 5.1. XPath Context . . . . . . . . . . . . . . . . . . . . . . 15 + 6. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 16 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 7.1. Updates to the IETF XML Registry . . . . . . . . . . . . 21 7.2. Updates to the YANG Module Names Registry . . . . . . . . 22 8. Security Considerations . . . . . . . . . . . . . . . . . . . 22 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 22 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 10.1. Normative References . . . . . . . . . . . . . . . . . . 23 10.2. Informative References . . . . . . . . . . . . . . . . . 23 Appendix A. Guidelines for Defining Datastores . . . . . . . . . 24 A.1. Define which YANG modules can be used in the datastore . 24 A.2. Define which subset of YANG-modeled data applies . . . . 25 A.3. Define how data is actualized . . . . . . . . . . . . . . 25 A.4. Define which protocols can be used . . . . . . . . . . . 25 A.5. Define YANG identities for the datastore . . . . . . . . 25 - Appendix B. Ephemeral Dynamic Datastore Example . . . . . . . . 25 + Appendix B. Ephemeral Dynamic Configuration Datastore Example . 26 Appendix C. Example Data . . . . . . . . . . . . . . . . . . . . 27 C.1. System Example . . . . . . . . . . . . . . . . . . . . . 27 C.2. BGP Example . . . . . . . . . . . . . . . . . . . . . . . 29 C.2.1. Datastores . . . . . . . . . . . . . . . . . . . . . 31 C.2.2. Adding a Peer . . . . . . . . . . . . . . . . . . . . 31 C.2.3. Removing a Peer . . . . . . . . . . . . . . . . . . . 32 C.3. Interface Example . . . . . . . . . . . . . . . . . . . . 33 C.3.1. Pre-provisioned Interfaces . . . . . . . . . . . . . 33 C.3.2. System-provided Interface . . . . . . . . . . . . . . 34 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 @@ -109,21 +110,27 @@ management data models to network management protocols. Agreement on a common architectural model of datastores ensures that data models can be written in a network management protocol agnostic way. 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. 2. Terminology - This document defines the following terms: + This document defines the following terminology. Some of the terms + are revised definitions of terms originally defined in [RFC6241] and + [RFC7950] (see also section Section 3). The revised definitions are + semantically equivalent with 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 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. @@ -159,31 +166,31 @@ o conventional configuration datastore: One of the following set of configuration datastores: , , , and . These datastores share a common 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 datastore: A datastore holding data 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 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 - datastore. + configuration datastore. o learned configuration: Configuration that has been learned via - protocol interactions with other systems that is not conventional - or dynamic configuration. + 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. @@ -313,21 +320,21 @@ configuration is made persistent. Note that implementations may also have additional datastores that can propagate changes to . NETCONF explicitly mentions so called named datastores. 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 operation returns the content of the + o The NETCONF operation returns the content of the running configuration datastore together with the operational state. It is therefore necessary that "config false" data is 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 ; this inactive data is only exposed to clients that indicate that they support the concept of inactive data; clients not indicating support for @@ -366,22 +373,22 @@ | // nodes, expansion of templates v +------------+ | | // subject to validation | (ct, ro) | +------------+ | // changes applied, subject to | // local factors, e.g., missing | // resources, delays | - | +-------- learned configuration - dynamic | +-------- system configuration + dynamic | +-------- learned configuration + configuration | +-------- system configuration datastores -----+ | +-------- default configuration | | | v v v +---------------+ | | <-- system state | (ct + cf, ro) | +---------------+ ct = config true; cf = config false rw = read-write; ro = read-only @@ -472,162 +479,191 @@ Other conventional configuration datastores may be defined in future documents. The flow of data between these datastores is depicted in section Section 4. The specific protocols may define explicit operations to copy between these datastores, e.g., NETCONF's operation. -4.6. Dynamic Datastores +4.6. Dynamic Configuration Datastores - The model recognizes the need for dynamic 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 - datastores interact with the rest of the system through - . + 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 . 4.7. The Operational State Datastore () The operational state datastore () is a read-only datastore that consists of all "config true" and "config false" nodes defined in the 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. contains system state and all configuration actually used by the system. This includes all applied configuration from - , system-provided configuration, and default values defined - by any supported data models. In addition, also - contains applied data from dynamic datastores. + , learned configuration, system-provided configuration, and + default values defined by any supported data models. In addition, + also contains applied configuration from dynamic + configuration datastores. Requests to retrieve nodes from 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 as 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 as being 'in use'. + Conversely, functionality that is neither enabled nor operational on + the system could be considered as not being 'in use', and hence may + be omitted from . + + 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", or due to remnant + configuration (described below). Note, that deviations are still + used when it is known in advance that a device does not fully conform + to the schema. + + Only semantic constraints may be violated, these are the YANG "when", + "must", "mandatory", "unique", "min-elements", and "max-elements" + statements. + + Syntactic constraints cannot be violated, including hierarchical + organization, identifiers, and type-based constraints. If a node in + does not meet the syntactic constraints then it cannot + be returned, and some other mechanism should be used to flag the + error. + does not persist across reboots. +4.7.1. Remnant Configuration + Changes to configuration may take time to percolate through to . During this period, 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). - As a result of remnant configuration, the semantic constraints - defined in the data model cannot be relied upon for , - 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. The constraints that may - not hold include "when", "must", "min-elements", and "max-elements". - Note that syntactic constraints cannot be violated, including - hierarchical organization, identifiers, and type-based constraints. + Remant configuration is a common example of where the semantic + constraints defined in the data model cannot be relied upon for + , 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. -4.7.1. Missing Resources +4.7.2. Missing Resources Configuration in can refer to resources that are not available or otherwise not physically present. In these situations, - these parts of the configuration are not applied. The - data appears in but does not appear in . + these parts of are not applied. The data appears in + but does not appear in . 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 but the interface configuration will not appear in . Note that configuration validity cannot depend on the current state of such resources, since that would imply the removing a resource might render the configuration invalid. This is unacceptable, especially given that rebooting such a device would fail to boot due to an invalid configuration. Instead we allow configuration for missing resources to exist in and , but it will not appear in . -4.7.2. System-controlled Resources +4.7.3. System-controlled Resources Sometimes resources are controlled by the device and the corresponding system controlled data appear in (and disappear from) dynamically. If a system controlled resource has matching configuration in when it appears, the system will try to apply the configuration, which causes the configuration to appear in eventually (if application of the configuration was successful). -4.7.3. Origin Metadata Annotation +4.7.4. Origin Metadata Annotation - As data flows into , it is conceptually marked with a - metadata annotation ([RFC7952]) that indicates its origin. The - origin applies to all data nodes except non-presence containers. The - "origin" metadata annotation is defined in Section 6. The values are - YANG identities. The following identities are defined: + As configuration flows into , 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 6. 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 data provided by . + o intended: represents configuration provided by . - o dynamic: represents data provided by a dynamic datastore. + o dynamic: represents configuration provided by a dynamic + configuration datastore. - o system: represents data provided by the system itself, including - both system configuration and system state. 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 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 protocols such as link-layer negotiations, routing protocols, DHCP, etc. - o default: represents data 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 data has not been provided by any - other source. + 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 data for which the system cannot identify the - origin. + 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 - datastore derived from "dynamic". + configuration datastores derived from "dynamic". - In all cases, the device should report the origin that most - accurately reflects the source of the data that is actively being - used by the system. + For all configuration data nodes in , the device should + report the origin that most accurately reflects the source of the + configuration that is actively being used by the system. 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, then 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 data node then it should use the origin "unknown". + particular configuration data node then it should use the origin + "unknown". 5. Implications on YANG 5.1. XPath Context 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 @@ -656,29 +692,29 @@ "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. YANG Modules - file "ietf-datastores@2017-04-26.yang" + file "ietf-datastores@2017-08-17.yang" module ietf-datastores { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-datastores"; prefix ds; organization - "IETF NETMOD (NETCONF Data Modeling Language) Working Group"; + "IETF Network Modeling (NETMOD) Working Group"; contact "WG Web: WG List: Author: Martin Bjorklund Author: Juergen Schoenwaelder @@ -689,37 +725,37 @@ Author: Kent Watsen Author: Rob Wilton "; description "This YANG module defines two sets of identities for datastores. The first identifies the datastores themselves, the second - identifies are for datastore protperties. + identifies datastore properties. Copyright (c) 2017 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 (http://trustee.ietf.org/license-info). This version of this YANG module is part of RFC XXXX (http://www.rfc-editor.org/info/rfcxxxx); see the RFC itself for full legal notices."; - revision 2017-04-26 { + revision 2017-08-17 { description "Initial revision."; reference "RFC XXXX: Network Management Datastore Architecture"; } /* * Identities */ @@ -744,105 +781,67 @@ base conventional; description "The candidate configuration datastore."; } identity startup { base conventional; description "The startup configuration datastore."; } - identity intended { base conventional; description "The intended configuration datastore."; } identity dynamic { base datastore; description - "Abstract base identity for dynamic datastores."; + "Abstract base identity for dynamic configuration datastores."; } identity operational { base datastore; description "The operational state datastore."; } - identity property { - description - "Abstract base identity for datastore identities."; - } - - identity writable { - base property; - description - "Used on the 'running' datastore to indicate that it can be - written to."; - - } - - identity auto-persist { - base property; - description - "Used on the 'running' datastore to indicate that writes to - it will be automatically persisted. - - If the 'startup' datastore is also supported, clients may - query its contents to ensure its synchronization. - - If the 'startup' datastore is not supported, and this - property is not set, then clients must use a mechanism - provided by the protocol to explicitly persist the - 'running' datastore's contents."; - } - - identity rollback-on-error { - base property; - description - "Used on either the 'running' or 'candidate' datastores to - indicate that clients may request atomic update behavior."; - } + /* + * Type definitions + */ - identity confirmed-commit { - base property; - description - "Used on the 'candidate' datastore to indicate that - clients may request confirmed-commit update behavior."; + typedef datastore-ref { + type identityref { + base datastore; } - - identity validate { - base property; description - "Used on the 'candidate' datastore to indicate that - clients may request datastore validation."; + "A datastore identity reference."; } } - file "ietf-origin@2017-04-26.yang" + file "ietf-origin@2017-08-17.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 NETMOD (NETCONF Data Modeling Language) Working Group"; + "IETF Network Modeling (NETMOD) Working Group"; contact "WG Web: WG List: Author: Martin Bjorklund Author: Juergen Schoenwaelder @@ -868,101 +867,116 @@ 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 (http://trustee.ietf.org/license-info). This version of this YANG module is part of RFC XXXX (http://www.rfc-editor.org/info/rfcxxxx); see the RFC itself for full legal notices."; - revision 2017-04-26 { + revision 2017-08-17 { description "Initial revision."; reference "RFC XXXX: Network Management Datastore Architecture"; } /* * Identities */ identity origin { description "Abstract base identity for the origin annotation."; } identity intended { base origin; description - "Denotes data from the intended configuration datastore"; + "Denotes configuration from the intended configuration + datastore"; } identity dynamic { base origin; description - "Denotes data from a dynamic datastore."; + "Denotes configuration from a dynamic configuration + datastore."; } identity system { base origin; description - "Denotes data originated by the system itself, including - both system configuration and system state. + "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."; } identity learned { base origin; description "Denotes configuration learned from protocol interactions with - other devices, instead of via the intended configuration - datastore or any dynamic datastore. + 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 data that does not have an 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."; + "Denotes configuration that does not have an 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 data for which the system cannot identify the + "Denotes configuration for which the system cannot identify the origin."; } /* - * Metadata annotations + * Type definitions */ - md:annotation origin { + typedef origin-ref { type identityref { base origin; } description - "The 'origin' annotation can be present on any node in a - datastore. It specifies from where the node originated."; + "An origin identity reference."; } + /* + * Metadata annotations + */ + + md:annotation origin { + type origin-ref; + description + "The 'origin' annotation can be present on any configuration + data node in the operational 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."; + } } 7. IANA Considerations 7.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 are @@ -991,20 +1005,24 @@ namespace: urn:ietf:params:xml:ns:yang:ietf-origin prefix: or reference: RFC XXXX 8. 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 meta-data, hence the "YANG module security + guidelines" do not apply. + 9. Acknowledgments This document grew out of many discussions that took place since 2010. Several Internet-Drafts ([I-D.bjorklund-netmod-operational], [I-D.wilton-netmod-opstate-yang], [I-D.ietf-netmod-opstate-reqs], [I-D.kwatsen-netmod-opstate], [I-D.openconfig-netmod-opstate]) and [RFC6244] touched on some of the problems of the original datastore model. The following people were authors to these Internet-Drafts or otherwise actively involved in the discussions that led to this document: @@ -1108,32 +1126,35 @@ 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 are - present, or "config false nodes" that also have a specific YANG - extension (e.g., "i2rs:ephemeral true") are present in the datastore. + present, 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 4 depicts dynamic + datastores. + + For example, the diagram in Section 4 depicts dynamic configuration datastores feeding into . How this interaction occurs - must be defined by any dynamic datastore. In some cases, it may - occur implicitly, as soon as the data is put into the dynamic - datastore while, in other cases, an explicit action (e.g., an RPC) - may be required to trigger the application of the datastore's data. + must 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., ForCES) or that a subset of all protocol operations or capabilities are available (e.g., no locking or no XPath-based filtering). A.5. Define YANG identities for the datastore @@ -1144,72 +1165,63 @@ protocol operations (e.g., ). The datastore may also be defined with an identity that uses the "or:origin" identity or one its derived identities as its base. This identity is needed if the datastore interacts with so that data originating from the datastore can be identified as such via the "origin" metadata attribute defined in Section 6. An example of these guidelines in use is provided in Appendix B. -Appendix B. Ephemeral Dynamic Datastore Example +Appendix B. Ephemeral Dynamic Configuration Datastore Example - The section defines documentation for an example dynamic datastore - using the guidelines provided in Appendix A. While this example is - very terse, it is expected to be that a standalone RFC would be - needed when fully expanded. + The section defines documentation for an example dynamic + configuration datastore using the guidelines provided in Appendix A. + While this example is very terse, it is expected to be that a + standalone RFC would be needed when fully expanded. - This example defines a dynamic datastore called "ephemeral", which is - loosely modeled after the work done in the I2RS working group. + This example defines a dynamic configuration datastore called + "ephemeral", which is loosely modeled after the work done in the I2RS + working group. 1. Name : ephemeral 2. YANG modules : all (default) - 3. YANG statements : config false + ephemeral true + 3. YANG data nodes : all "config true" data nodes 4. How applied : automatic 5. Protocols : NC/RC (default) 6. YANG Module : (see below) 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; } - // add datastore identity + // datastore identity identity ds-ephemeral { - base ds:datastore; + base ds:dynamic; description - "The 'ephemeral' datastore."; + "The ephemeral dynamic configuration datastore."; } - // add origin identity + // origin identity identity or-ephemeral { base or:dynamic; description - "Denotes data from the ephemeral dynamic datastore."; - } - - // define ephemeral extension - extension ephemeral { - argument "value"; - description - "This extension is mixed into config false YANG nodes to - indicate that they are writable nodes in the 'ephemeral' - datastore. This statement takes a single argument - representing a boolean having the values 'true' and - 'false'. The default value is 'false'."; + "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. @@ -1299,21 +1311,23 @@ 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 host name and an additional IP address for "eth0" over DHCP. In addition to a default value, a loopback interface is automatically added by the system, and the result of the "speed" auto-negotiation. All of - this is reflected in : + this is reflected in . Note how the origin metadata + attribute for several "config true" data nodes is inherited from + their parent data nodes. bar eth0 @@ -1336,21 +1350,21 @@
::1 128
C.2. BGP Example - Consider the following piece of a ersatz BGP module: + 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; @@ -1384,140 +1398,143 @@ } } } 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. The model also follows the pattern of fully integrating state ("config false") nodes with configuration ("config true") nodes. - There is not separate "bgp-state" hierarchy, with the accompanying + 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. - will hold the configuration provided by the user, for example a + will hold the configuration provided by the operator, for example a single BGP peer. will conceptually hold the data as validated, after the removal of data not intended for validation and - after any local template mechanisms are performed. - will show data from as well as any "config false" nodes. + after any local template mechanisms are performed. will + show data from 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 and . It may also appear in - , if the server supports the "candidate" feature. - Retrieving the peer will return only the user-specified values. + , 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 and . In this scenario, we've added the following to : - 64642 - 65000 + 64501 + 64502 10.1.2.3 C.2.2.1. - will contain the fully expanded peer data, including - "config false" nodes. In our example, this means the "state" node - will appear. + The operational datastore will contain the fully expanded peer data, + including "config false" nodes. In our example, this means the + "state" node will appear. In addition, 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 . 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 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 . If those values are not supplied, the system will select values. When the connection is established, 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. - - 64642 - 65000 - - 10.1.2.3 - 64642 - 65000 - 60794 - 179 + + 64501 + 64502 + + 10.1.2.3 + 64501 + 64502 + 60794 + 179 + established 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. 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 , with the "origin" attribute set to indicate the origin of the original data. - - 64642 - 65000 - - 10.1.2.3 - 64642 - 65000 - 60794 - 179 + + 64501 + 64502 + + 10.1.2.3 + 64501 + 64502 + 60794 + 179 + closing Once resources are released and the connection is closed, the peer's data is removed from . C.3. Interface Example - In this section, we'll use this simple interface data model: + 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 uint; + type uint16; } - leaf ipv4-address { - type inet:ipv4-address; + leaf-list ip-address { + type inet:ip-address; } } } 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 @@ -1531,63 +1548,64 @@ et-0/0/0 Test interface Since the interface does not exist, this data does not appear in . When a FRU containing this interface is inserted, the system will - detect it and process the associated configuration. The - will contain the data from , as well as the - "config false" nodes, such as the current value of the interface's - MTU. + detect it and process the associated configuration. + will contain the data from , as well as nodes added by the + system, such as the current value of the interface's MTU. - - - et-0/0/0 - Test interface - 1500 + + + et-0/0/0 + Test interface + 1500 If the FRU is removed, the interface data is removed from . C.3.2. System-provided Interface Imagine if the system provides a loopback interface (named "lo0") - with a default ipv4-address of "127.0.0.1". The system will only - provide configuration for this interface if there is no data for it - in . + with a default ip-address of "127.0.0.1" and a default ip-address of + "::1". The system will only provide configuration for this interface + if there is no data for it in . When no configuration for "lo0" appears in , then will show the system-provided data: - - - lo0 - 127.0.0.1 + + + lo0 + 127.0.0.1 + ::1 When configuration for "lo0" does appear in , then will show that data with the origin set to "intended". - If the "ipv4-address" is not provided, then the system-provided value + If the "ip-address" is not provided, then the system-provided value will appear as follows: - - - lo0 - loopback - 127.0.0.1 + + + lo0 + loopback + 127.0.0.1 + ::1 Authors' Addresses Martin Bjorklund Tail-f Systems Email: mbj@tail-f.com