Network Management Datastore ArchitectureTail-f Systemsmbj@tail-f.comJacobs Universityj.schoenwaelder@jacobs-university.deJuniper Networksphil@juniper.netJuniper Networkskwatsen@juniper.netCisco Systemsrwilton@cisco.com
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 document provides an architectural framework for
datastores as they are used by network management protocols such as
NETCONF , RESTCONF and the YANG
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 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 () and the IP data model () 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 and
(see also section ). The revised definitions are
semantically equivalent with the definitions found in and
. It is expected that the revised definitions provided in
this section will replace the definitions in and
when these documents are revised.
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.
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.
configuration datastore: A datastore holding configuration.
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>".
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>".
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>".
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.
intended configuration datastore: A configuration datastore holding
the complete intended configuration of the device. This datastore
is referred to as "<intended>".
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.
conventional configuration datastore: One of the following set of
configuration datastores: <running>, <startup>, <candidate>, and
<intended>. 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.
conventional configuration: Configuration that is stored
in any of the conventional configuration datastores.
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.
dynamic configuration: Configuration obtained via a dynamic
configuration datastore.
learned configuration: Configuration that has been learned via
protocol interactions with other systems and that is neither
conventional nor dynamic configuration.
system configuration: Configuration that is supplied by
the device itself.
default configuration: Configuration that is not explicitly provided
but for which a value defined in the data model is used.
applied configuration: Configuration that is actively in use by a
device. Applied configuration originates from conventional,
dynamic, learned, system and default configuration.
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.
operational state: The combination of applied configuration and
system state.
operational state datastore: A datastore holding the
complete operational state of the device. This datastore
is referred to as "<operational>".
origin: A metadata annotation indicating the origin of a data item.
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 commonly
used and thus defined here as well:
client: An entity that can access YANG-defined data on a server,
over some network management protocol.
server: An entity that provides access to YANG-defined data to a
client, over some network management protocol.
notification: A server-initiated message indicating that a certain
event has been recognized by the server.
remote procedure call: An operation that can be invoked by a client
on a server.
NETCONF provides the following definitions:
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.
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 provides the following
refinements when NETCONF is used with YANG (which is the usual case
but note that NETCONF was defined before YANG existed):
datastore: When modeled with YANG, a datastore is realized as an
instantiated data tree.
configuration datastore: When modeled with YANG, a configuration
datastore is realized as an instantiated data tree with
configuration.
defined operational state data as follows:
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 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
,
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 :
| | |
| (ct, rw) |<---+ +--->| (ct, rw) |
+-------------+ | | +-----------+
| | | |
| +-----------+ |
+-------->| |<--------+
| (ct, rw) |
+-----------+
|
v
operational state <--- control plane
(cf, ro)
]]>
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:
Operational state has not been defined as a datastore although there
were proposals in the past to introduce an operational state
datastore.
The NETCONF <get> operation returns the contents of <running>
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.
Several implementations have proprietary mechanisms that allow
clients to store inactive data in <running>. Inactive data is
conceptually removed before validation.
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.
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.
Below is a new conceptual model of datastores extending the original
model in order to reflect the experience gained with the original
model.
| | |
| (ct, rw) |<---+ +--->| (ct, rw) |
+-------------+ | | +-----------+
| | | |
| +-----------+ |
+-------->| |<--------+
| (ct, rw) |
+-----------+
|
| // configuration transformations,
| // e.g., removal of "inactive"
| // nodes, expansion of templates
v
+------------+
| | // 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
+---------------+
| | <-- system state
| (ct + cf, ro) |
+---------------+
]]>
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:
<running>
<candidate>
<startup>
<intended>
Other conventional configuration datastores may be defined in future
documents.
The flow of data between these datastores is depicted in
.
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
.
<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 .
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 ). 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 () that indicates its origin. The
origin applies to all configuration nodes except non-presence
containers. The "origin" metadata annotation is defined in
. The values are YANG identities. The following
identities are defined:
origin: abstract base identity from which the other origin
identities are derived.
intended: represents configuration provided by <intended>.
dynamic: represents configuration provided by a dynamic
configuration datastore.
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.
learned: represents configuration that has been learned via protocol
interactions with other systems, including protocols such as
link-layer negotiations, routing protocols, DHCP, etc.
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.
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.
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:
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.
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.
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.
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.
<CODE BEGINS> file "ietf-datastores@2017-08-17.yang"
WG List:
Author: Martin Bjorklund
Author: Juergen Schoenwaelder
Author: Phil Shafer
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 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"
WG List:
Author: Martin Bjorklund
Author: Juergen Schoenwaelder
Author: Phil Shafer
Author: Kent Watsen
Author: Rob Wilton
";
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 . Following
the format in , the following registrations are requested:
This document registers two YANG modules in the YANG Module Names registry
. Following the format in , the the following registrations
are requested:
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 (,
, ,
, ) and
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:
Lou Berger, LabN Consulting, L.L.C., <lberger@labn.net>
Andy Bierman, YumaWorks, <andy@yumaworks.com>
Marcus Hines, Google, <hines@google.com>
Christian Hopps, Deutsche Telekom, <chopps@chopps.org>
Balazs Lengyel, Ericsson, <balazs.lengyel@ericsson.com>
Acee Lindem, Cisco Systems, <acee@cisco.com>
Ladislav Lhotka, CZ.NIC, <lhotka@nic.cz>
Thomas Nadeau, Brocade Networks, <tnadeau@lucidvision.com>
Tom Petch, Engineering Networks Ltd, <ietfc@btconnect.com>
Anees Shaikh, Google, <aashaikh@google.com>
Rob Shakir, Google, <robjs@google.com>
Jason Sterne, Nokia, <jason.sterne@nokia.co>
Juergen Schoenwaelder was partly funded by Flamingo, a Network of
Excellence project (ICT-318488) supported by the European Commission
under its Seventh Framework Programme.
Key words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.Network Configuration Protocol (NETCONF)The Network Configuration Protocol (NETCONF) defined in this document provides mechanisms to install, manipulate, and delete the configuration of network devices. It uses an Extensible Markup Language (XML)-based data encoding for the configuration data as well as the protocol messages. The NETCONF protocol operations are realized as remote procedure calls (RPCs). This document obsoletes RFC 4741. [STANDARDS-TRACK]Defining and Using Metadata with YANGThis document defines a YANG extension that allows for defining metadata annotations in YANG modules. The document also specifies XML and JSON encoding of annotations and other rules for annotating instances of YANG data nodes.The YANG 1.1 Data Modeling LanguageYANG is a data modeling language used to model configuration data, state data, Remote Procedure Calls, and notifications for network management protocols. This document describes the syntax and semantics of version 1.1 of the YANG language. YANG version 1.1 is a maintenance release of the YANG language, addressing ambiguities and defects in the original specification. There are a small number of backward incompatibilities from YANG version 1. This document also specifies the YANG mappings to the Network Configuration Protocol (NETCONF).RESTCONF ProtocolThis document describes an HTTP-based protocol that provides a programmatic interface for accessing data defined in YANG, using the datastore concepts defined in the Network Configuration Protocol (NETCONF).Ambiguity of Uppercase vs Lowercase in RFC 2119 Key WordsRFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.The IETF XML RegistryThis document describes an IANA maintained registry for IETF standards which use Extensible Markup Language (XML) related items such as Namespaces, Document Type Declarations (DTDs), Schemas, and Resource Description Framework (RDF) Schemas.YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)YANG is a data modeling language used to model configuration and state data manipulated by the Network Configuration Protocol (NETCONF), NETCONF remote procedure calls, and NETCONF notifications. [STANDARDS-TRACK]An Architecture for Network Management Using NETCONF and YANGThe Network Configuration Protocol (NETCONF) gives access to native capabilities of the devices within a network, defining methods for manipulating configuration databases, retrieving operational data, and invoking specific operations. YANG provides the means to define the content carried via NETCONF, both data and operations. Using both technologies, standard modules can be defined to give interoperability and commonality to devices, while still allowing devices to express their unique capabilities.This document describes how NETCONF and YANG help build network management applications that meet the needs of network operators. This document is not an Internet Standards Track specification; it is published for informational purposes.A YANG Data Model for Interface ManagementThis document defines a YANG data model for the management of network interfaces. It is expected that interface-type-specific data models augment the generic interfaces data model defined in this document. The data model includes configuration data and state data (status information and counters for the collection of statistics).A YANG Data Model for IP ManagementThis document defines a YANG data model for management of IP implementations. The data model includes configuration data and state data.Terminology and Requirements for Enhanced Handling of Operational StateThis document primarily regards the difference between the intended configuration and the applied configuration of a device and how intended and applied configuration relate to the operational state of a device. This document defines requirements for the applied configuration's data model and its values, as well as for enabling a client to know when a configuration has been fully applied or not, how to access operational state, and how to relate intended configuration nodes to applied configuration and derived state nodes.Operational Data in NETCONF and YANGThis document defines the concept of operational state data in the context of YANG and the Network Configuration Protocol (NETCONF). It updates RFC 6020 with rules for how to model the operational state, and defines NETCONF operations to retrieve and modify the operational state.Operational State Enhancements for YANG, NETCONF, and RESTCONFThis document presents enhancements to YANG, NETCONF, and RESTCONF satisfying the requirements set forth in Terminology and Requirements for Enhanced Handling of Operational State.Consistent Modeling of Operational State Data in YANGThis document proposes an approach for modeling configuration and operational state data in YANG [RFC6020] that is geared toward network management systems that require capabilities beyond those typically envisioned in a NETCONF-based management system. The document presents the requirements of such systems and proposes a modeling approach to meet these requirements, along with implications and design patterns for modeling operational state in YANG."With-config-state" Capability for NETCONF/RESTCONFThis document proposes a possible alternative solution for handling applied configuration state in YANG as described in draft-openconfig- netmod-opstate-01. The proposed solution, roughly modelled on the with-defaults NETCONF/RESTCONF capability, aims to meet the key requirements set out in draft-ietf-netmod-opstate-reqs-01 without the need for YANG module authors to explicitly duplicate configuration nodes in both configuration and operational containers. This draft does not address the issue of co-location of configuration and operational state for interfaces, nor does it provide a NETCONF mechanism to retrieve operational data separately from configuration data.
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 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 .
An example of these guidelines in use is provided in
.
The section defines documentation for an example dynamic configuration
datastore using the guidelines provided in . 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.
NameValueNameephemeralYANG modulesall (default)YANG nodesall "config true" data nodesHow appliedchanges automatically propagated to <operational>ProtocolsNC/RC (default)YANG Module(see below)
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:
The operator has configured the host name and two interfaces, so the
contents of <intended> are:
fooeth010002001:db8::1064eth12001:db8::2064
]]>
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.
bareth0true10001002001:db8::10642001:db8::1:10064lo0::1128
]]>
Consider the following fragment of a fictional BGP module:
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>:
645016450210.1.2.3
]]>
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.
645016450210.1.2.3645016450260794179established
]]>
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.
645016450210.1.2.3645016450260794179closing
]]>
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:
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:
et-0/0/0Test interface
]]>
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.
et-0/0/0Test interface1500
]]>
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:
lo0127.0.0.1::1
]]>
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:
lo0loopback127.0.0.1::1
]]>