| Network Working Group | M. Bjorklund |
| Internet-Draft | Tail-f Systems |
| Updates: 7950 (if approved) | J. Schoenwaelder |
| Intended status: Standards Track | Jacobs University |
| Expires: April 23, 2018 | P. Shafer |
| K. Watsen | |
| Juniper Networks | |
| R. Wilton | |
| Cisco Systems | |
| October 20, 2017 |
Network Management Datastore Architecture
draft-ietf-netmod-revised-datastores-05
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.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
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 https://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 April 23, 2018.
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 (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.
This document provides an architectural framework for datastores as they are used by network management protocols such as NETCONF [RFC6241], RESTCONF [RFC8040] and the YANG [RFC7950] data modeling language. 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 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.
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.
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 ([RFC7223]) and the IP data model ([RFC7277]) was using 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 leads 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 two different datastores, one for configured values and one for operational state values. 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.
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 4). 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.
The following additional terms are not datastore specific but commonly used and thus defined here as well:
NETCONF [RFC6241] provides the following definitions:
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):
[RFC6244] defined operational state data as follows:
Section 4.3.3 of [RFC6244] discusses operational state and among other things mentions the option to consider operational state as being stored in another datastore. Section 4.4 of this document then concludes that at the time of the writing, modeling state as distinct leafs and distinct branches is the recommended approach.
Implementation experience and requests from operators [I-D.ietf-netmod-opstate-reqs], [I-D.openconfig-netmod-opstate] 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.
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
Note that this diagram simplifies the model: read-only (ro) and read-write (rw) is to be understood 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> or 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.
Some observations:
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 "inactive"
| // nodes, 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
The conventional configuration datastores are a set of configuration datastores that share exactly the same schema, allowing data to be copied between them. The term is meant as a generic umbrella description of these datastores. The set of datastores include:
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.
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>, either via implicit or explicit protocol operations.
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>.
The running configuration datastore (<running>) is a configuration datastore that holds the complete current configuration on 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.
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>, then <intended> MUST also be immediately updated by performing all necessary configuration transformations to the contents of <running> and then <intended> is validated.
<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].
For simple implementations, <running> and <intended> are identical.
The contents of <intended> are also related to the "config true" subset of <operational>, and hence a client can determine to what extent the intended configuration is currently in use by checking 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>.
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 operational state datastore (<operational>) 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.
<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.
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 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 is considered as not being "in use", and hence 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 due to remnant configuration (see Section 5.3.1). 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.
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.
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>.
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, which causes the configuration to appear in <operational> eventually (if application of the configuration was successful).
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:
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.
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 configuration data node then it SHOULD use the origin "unknown".
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:
<CODE BEGINS> 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 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 two sets of identities for datastores.
The first identifies the datastores themselves, the second
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-08-17 {
description
"Initial revision.";
reference
"RFC XXXX: Network Management Datastore Architecture";
}
/*
* 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.";
}
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>
<CODE BEGINS> 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 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) 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-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 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.";
}
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 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 configuration for which the system cannot identify the
origin.";
}
/*
* Type definitions
*/
typedef origin-ref {
type identityref {
base origin;
}
description
"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.";
}
}
<CODE ENDS>
This document registers two URIs in the IETF XML registry [RFC3688]. Following the format in [RFC3688], the following registrations are requested:
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.
This document registers two YANG modules in the YANG Module Names registry [RFC6020]. Following the format in [RFC6020], the the following registrations are requested:
name: ietf-datastores namespace: urn:ietf:params:xml:ns:yang:ietf-datastores prefix: ds reference: RFC XXXX name: ietf-origin namespace: urn:ietf:params:xml:ns:yang:ietf-origin prefix: or reference: RFC XXXX
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.
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:
Juergen Schoenwaelder was partly funded by Flamingo, a Network of Excellence project (ICT-318488) supported by the European Commission under its Seventh Framework Programme.
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC6241] | Enns, R., Bjorklund, M., Schoenwaelder, J. and A. Bierman, "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011. |
| [RFC7950] | Bjorklund, M., "The YANG 1.1 Data Modeling Language", RFC 7950, DOI 10.17487/RFC7950, August 2016. |
| [RFC7952] | Lhotka, L., "Defining and Using Metadata with YANG", RFC 7952, DOI 10.17487/RFC7952, August 2016. |
| [RFC8040] | Bierman, A., Bjorklund, M. and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017. |
| [RFC8174] | Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017. |
| [I-D.bjorklund-netmod-operational] | Bjorklund, M. and L. Lhotka, "Operational Data in NETCONF and YANG", Internet-Draft draft-bjorklund-netmod-operational-00, October 2012. |
| [I-D.ietf-netmod-opstate-reqs] | Watsen, K. and T. Nadeau, "Terminology and Requirements for Enhanced Handling of Operational State", Internet-Draft draft-ietf-netmod-opstate-reqs-04, January 2016. |
| [I-D.kwatsen-netmod-opstate] | Watsen, K., Bierman, A., Bjorklund, M. and J. Schoenwaelder, "Operational State Enhancements for YANG, NETCONF, and RESTCONF", Internet-Draft draft-kwatsen-netmod-opstate-02, February 2016. |
| [I-D.openconfig-netmod-opstate] | Shakir, R., Shaikh, A. and M. Hines, "Consistent Modeling of Operational State Data in YANG", Internet-Draft draft-openconfig-netmod-opstate-01, July 2015. |
| [I-D.wilton-netmod-opstate-yang] | Wilton, R., ""With-config-state" Capability for NETCONF/RESTCONF", Internet-Draft draft-wilton-netmod-opstate-yang-02, December 2015. |
| [RFC3688] | Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004. |
| [RFC6020] | Bjorklund, M., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010. |
| [RFC6244] | Shafer, P., "An Architecture for Network Management Using NETCONF and YANG", RFC 6244, DOI 10.17487/RFC6244, June 2011. |
| [RFC7223] | Bjorklund, M., "A YANG Data Model for Interface Management", RFC 7223, DOI 10.17487/RFC7223, May 2014. |
| [RFC7277] | Bjorklund, M., "A YANG Data Model for IP Management", RFC 7277, DOI 10.17487/RFC7277, June 2014. |
The definition of a new datastore in this architecture should be provided in a document (e.g., an RFC) purposed to the definition of 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 sections below.
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.
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.
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.
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).
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 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.
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 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 | NC/RC (default) |
| 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;
}
// 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.";
}
}
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.
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.";
}
list address {
key ip;
leaf ip {
type inet:ip-address;
}
leaf prefix-length {
type uint8;
}
}
}
}
}
The operator has configured the host name and two interfaces, so the contents of <intended> are:
<system xmlns="urn:example:system">
<hostname>foo</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 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 <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:dynamic">bar</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:dynamic">
<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>
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 ipaddress;
}
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.
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.
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.
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>10.1.2.3</name>
</peer>
</bgp>
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, <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 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 or:origin="or:intended">
<local-as>64501</local-as>
<peer-as>64502</peer-as>
<peer>
<name>10.1.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>
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.
<bgp or:origin="or:intended">
<local-as>64501</local-as>
<peer-as>64502</peer-as>
<peer>
<name>10.1.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>.
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;
}
}
}
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 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>.
Imagine if the system provides a loopback interface (named "lo0") 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 <intended>.
When no configuration for "lo0" appears in <intended>, then <operational> will show the system-provided data:
<interfaces 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>, then <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 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>