YANG Schema MountTail-f Systemsmbj@tail-f.comCZ.NIClhotka@nic.cz
This document defines a mechanism to add the schema trees defined
by a set of YANG modules onto a mount point defined in the schema tree
in some YANG module.
Modularity and extensibility were among the leading design principles
of the YANG data modeling language. As a result, the same YANG module
can be combined with various sets of other modules and thus form a
data model that is tailored to meet the requirements of a specific use
case. Server implementors are only required to specify all YANG
modules comprising the data model (together with their revisions and
other optional choices) in the YANG library data (,
and Section 5.6.4 of )
implemented by the server. Such YANG modules appear in the data model
"side by side", i.e., top-level data nodes of each module - if there
are any - are also top-level nodes of the overall data model.
YANG has two mechanisms for contributing a schema
hierarchy defined elsewhere to the contents of an internal node of the
schema tree; these mechanisms are realized through the following YANG
statements:
The "uses" statement explicitly incorporates the contents of a
grouping defined in the same or another module. See Section 4.2.6
of for more details.
The "augment" statement explicitly adds contents to a target node
defined in the same or another module. See Section 4.2.8 of
for more details.
With both mechanisms, the YANG module with the "uses" or "augment"
statement explicitly defines the exact location in the schema tree
where the new nodes are placed.
In some cases these mechanisms are not sufficient; it is sometimes
necessary that an existing module (or a set of modules) is added to
the data model starting at locations other than the root. For example,
YANG modules such as "ietf‑interfaces" are defined so
as to be used in a data model of a physical device. Now suppose we
want to model a device that supports multiple logical devices
, each of which has its own instantiation of
"ietf‑interfaces", and possibly other modules, but, at the same time,
we want to be able to manage all these logical devices from the master
device. Hence, we would like to have a schema tree like this:
With the "uses" approach, the complete schema tree of
"ietf‑interfaces" would have to be wrapped in a grouping, and then
this grouping would have to be used at the top level (for the master
device) and then also in the "logical‑network‑element" list (for the
logical devices). This approach has several disadvantages:
It is not scalable because every time there is a new YANG module
that needs to be added to the logical device model, we have to
update the model for logical devices with another "uses" statement
pulling in contents of the new module.
Absolute references to nodes defined inside a grouping may break
if the grouping is used in different locations.
Nodes defined inside a grouping belong to the namespace of
the module where it is used, which makes references to such nodes
from other modules difficult or even impossible.
It would be difficult for vendors to add proprietary modules when
the "uses" statements are defined in a standard module.
With the "augment" approach, "ietf‑interfaces" would have to augment the
"logical‑network‑element" list with all its nodes, and at the same time define
all its nodes at the top level. The same hierarchy of nodes would thus
have to be defined twice, which is clearly not scalable either.
This document introduces a new mechanism, denoted as schema
mount, that allows for mounting one data model consisting of any
number of YANG modules at a specified location of another (parent)
schema. Unlike the "uses" and "augment" approaches discussed above,
the mounted modules needn't be specially prepared for mounting and,
consequently, existing modules such as "ietf‑interfaces" can be
mounted without any modifications.
The basic idea of schema mount is to label a data node in the parent
schema as the mount point, and then define a complete data model to be
attached to the mount point so that the labeled data node effectively
becomes the root node of the mounted data model.
In principle, the mounted schema can be specified at three different
phases of the data model life cycle:
Design-time: the mounted schema is defined along with the mount
point in the parent YANG module. In this case, the mounted schema has to
be the same for every implementation of the parent module.
Implementation-time: the mounted schema is defined by a server
implementor and is as stable as YANG library information of the
server.
Run-time: the mounted schema is defined by instance data that is
part of the mounted data model. If there are multiple instances of
the same mount point (e.g., in multiple entries of a list), the
mounted data model may be different for each instance.
The schema mount mechanism defined in this document provides support
only for the latter two cases. Design-time mounts are outside
the scope of this document, and could be possibly dealt with in a
future revision of the YANG data modeling language.
Schema mount applies to the data model, and specifically does not
assume anything about the source of instance data for the mounted
schemas. It may be implemented using the same instrumentation as the
rest of the system, or it may be implemented by querying some other
system. Future specifications may define mechanisms to control or
monitor the implementation of specific mount points.
How and when specific mount points are instantiated by the server is
out of scope for this document. Such mechanisms may be defined in
future specifications.
This document allows mounting of complete data models only. Other
specifications may extend this model by defining additional
mechanisms such as mounting sub-hierarchies of a module.
The YANG modules in this document conform to the Network Management
Datastore Architecture (NMDA) .
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.
The following terms are defined in and are not redefined
here:
action
container
data node
list
RPC operation
schema node
schema tree
The following terms are defined in and are not redefined
here:
client
notification
operational state
server
The following term is defined in and is not redefined
here:
system-controlled interface
The following term is defined in is
not redefined here:
YANG library checksum
The following additional terms are used within this document:
mount point: A container or a list node whose definition contains
the "mount‑point" extension statement. The argument of the
"mount‑point" statement defines a label for the mount point.
schema: A collection of schema trees with a common root.
top-level schema: A schema rooted at the root node.
mounted schema: A schema rooted at a mount point.
parent schema (of a mounted schema): A schema containing the mount
point.
schema mount: The mechanism to combine data models defined in this
document.
Tree diagrams used in this document follow the notation defined in
In this document, names of data nodes, YANG extensions, actions and
other data model objects are often used without a prefix, as long as
it is clear from the context in which YANG module each name is
defined. Otherwise, names are prefixed using the standard prefix
associated with the corresponding YANG module, as shown in
.
PrefixYANG moduleReferenceyangmntietf-yang-schema-mountinetietf-inet-typesyangietf-yang-typesyanglibietf-yang-library,
The schema mount mechanism defined in this document provides a new
extensibility mechanism for use with YANG 1.1. In contrast to the
existing mechanisms described in , schema mount defines the
relationship between the source and target YANG modules outside these
modules. The procedure consists of two separate steps that are
described in the following subsections.
A "container" or "list" node becomes a mount point if the
"mount‑point" extension (defined in the "ietf‑yang‑schema‑mount"
module) is used in its definition. This extension can appear only as a
substatement of "container" and "list" statements.
The argument of the "mount‑point" extension is a YANG identifier that
defines a label for the mount point. A module MAY contain multiple
"mount‑point" statements having the same argument.
It is therefore up to the designer of the parent schema to decide
about the placement of mount points. A mount point can also be made
conditional by placing "if‑feature" and/or "when" as substatements of
the "container" or "list" statement that represents the mount point.
The "mount‑point" statement MUST NOT be used in a YANG version 1
module . The reason for this is that otherwise it is not
possible to invoke mounted RPC operations, and receive mounted
notifications. See for details. Note, however, that modules
written in any YANG version, including version 1, can be mounted under
a mount point.
Note that the "mount‑point" statement does not define a new data node.
This document defines the YANG 1.1 module
"ietf‑yang‑schema‑mount", which has the following structure:
Mounted schemas for all mount points in the parent schema are
determined from state data in the "/schema‑mounts"
container.
Generally, the modules that are mounted under a mount point have no
relation to the modules in the parent schema; specifically, if a
module is mounted it may or may not be present in the parent schema
and, if present, its data will generally have no relationship to the
data of the parent. Exceptions are possible and such needs to be
defined in the model defining the exception. For example,
defines a mechanism to bind interfaces to
mounted logical network elements.
The "/schema‑mounts" container has the "mount‑point" list as one of its
children. Every entry of this list refers through its key to a mount
point and specifies the mounted schema.
If a mount point is defined in the parent schema but does not have an
entry in the "mount‑point" list, then the mounted schema is void,
i.e., instances of that mount point MUST NOT contain any data except
those that are defined in the parent schema.
If multiple mount points with the same name are defined in the same
module - either directly or because the mount point is defined in a
grouping and the grouping is used multiple times - then the
corresponding "mount‑point" entry applies equally to all such mount
points.
The "config" property of mounted schema nodes is overridden and all
nodes in the mounted schema are read-only ("config false") if at least
one of the following conditions is satisfied for a mount point:
the mount point is itself defined as "config false"
the "config" leaf in the corresponding entry of the "mount‑point"
list is set to "false".
An entry of the "mount‑point" list can specify the mounted schema in
two different ways, "inline" or "shared‑schema".
The mounted schema is determined at run time: every instance of the
mount point that exists in the operational state MUST contain a copy
of YANG library data that defines the mounted schema exactly as for a
top-level schema. A client is expected to retrieve this data from the
instance tree. In the "inline" case, instances of the same mount
point MAY use different mounted schemas, whereas in the
"shared‑schema" case, all instances MUST use the same mounted schema.
This means that in the "shared‑schema" case, all instances of the same
mount point MUST have the same YANG library checksum. In the "inline"
case, if two instances have the same YANG library checksum it is not
guaranteed that the YANG library contents are equal for these
instances.
YANG modules in a mounted schema MAY again contain mount points under
which other schemas can be mounted. Consequently, it is possible to
construct data models with an arbitrary number of mounted schemas. A
schema for a mount point contained in a mounted module can be
specified by implementing "ietf‑yang‑library" and
"ietf‑yang‑schema‑mount" modules in the mounted schema, and specifying
the schemas exactly as it is done in the top-level schema.
A fundamental design principle of schema mount is that the mounted
schema works exactly as a top-level schema, i.e., it is
confined to the "mount jail". This means that all paths in the mounted
schema (in leafrefs, instance-identifiers, XPath expressions, and
target nodes of augments) are interpreted with the mount point as the
root node. YANG modules of the mounted schema as well as corresponding
instance data thus cannot refer to schema nodes or instance data
outside the mount jail.
However, this restriction is sometimes too severe. A typical example
is network instances (NI) , where each NI has
its own routing engine but the list of interfaces is global and shared
by all NIs. If we want to model this organization with the NI schema
mounted using schema mount, the overall schema tree would look
schematically as follows:
Here, the "root" node is the mount point for the NI schema. Routing
configuration inside an NI often needs to refer to interfaces (at
least those that are assigned to the NI), which is impossible unless
such a reference can point to a node in the parent schema (interface
name).
Therefore, schema mount also allows for such references. For every
mount point in the "shared‑schema" case, it is possible to specify a
leaf-list named "parent‑reference" that contains zero or more XPath
1.0 expressions. Each expression is evaluated with the node in the
parent data tree where the mount point is defined as the context
node. The result of this evaluation MUST be a nodeset (see the
description of the "parent‑reference" node for a complete definition
of the evaluation context). For the purposes of evaluating XPath
expressions within the mounted data tree, the union of all such
nodesets is added to the accessible data tree.
It is worth emphasizing that the nodes specified in "parent‑reference"
leaf-list are available in the mounted schema only for XPath
evaluations. In particular, they cannot be accessed there via network
management protocols such as NETCONF or RESTCONF .
If a mounted YANG module defines an RPC operation, clients can invoke
this operation as if it were defined as an action for the
corresponding mount point, see Section 7.15 of . An example
of this is given in .
Similarly, if the server emits a notification defined at the top level
of any mounted module, it MUST be represented as if the
notification was connected to the mount point, see Section 7.16 of
.
Note, inline actions and notifications will not work when they are
contained within a list node without a "key" statement (see section 7.15
and 7.16 of ). Therefore, to be useful, mount points which
contain modules with RPCs, actions, and notifications SHOULD NOT have any
ancestor node that is a list node without a "key" statement. This
requirement applies to the definition of modules using the "mount‑point"
extension statement.
The schema mount solution presented in this document is designed to
work both with servers that implement the NMDA , and old
servers that don't implement the NMDA.
Note to RFC Editor: please update the date YYYY-MM-DD below with the
revision of the ietf-yang-library in the published version of
draft-ietf-netconf-rfc7895bis, and remove this note.
Specifically, a server that doesn't support the NMDA, MAY implement
revision 2016-06-21 of "ietf‑yang‑library" under a mount
point. A server that supports the NMDA, MUST implement at least
revision YYYY-MM-DD of "ietf‑yang‑library"
under the mount points.
If NACM is implemented on a server, it can be used to
control access to nodes defined by the mounted schema in the same way
as for nodes defined by the top-level schema.
For example, suppose the module "ietf‑interfaces" is mounted in the
"root" container in the "logical‑network‑element" list defined in
. Then the following NACM path can be used
to control access to the "interfaces" container (where the character
'\' is used where a line break has been inserted for formatting
reasons):
Network management of devices that use a data model with schema mount
can be implemented in different ways. However, the following
implementations options are envisioned as typical:
shared management: instance data of both parent and mounted schemas
are accessible within the same management session.
split management: one (master) management session has access to
instance data of both parent and mounted schemas but, in addition,
an extra session exists for every instance of the mount point,
having access only to the mounted data tree.
This module references .
<CODE BEGINS> file "ietf-yang-schema-mount@2018-08-07"<CODE ENDS>
This document registers a URI in the IETF XML registry
. Following the format in RFC 3688, the following
registration is requested to be made.
This document registers a YANG module in the YANG Module Names
registry .
YANG module "ietf‑yang‑schema‑mount" specified in this document
defines a schema for data that is designed to be accessed
via network management protocols such as NETCONF or RESTCONF
. The lowest NETCONF layer is the secure transport layer, and
the mandatory-to-implement secure transport is Secure Shell (SSH)
. The lowest RESTCONF layer is HTTPS, and the
mandatory-to-implement secure transport is TLS .
The network configuration access control model
provides the means to restrict
access for particular NETCONF or RESTCONF users to a preconfigured
subset of all available NETCONF or RESTCONF protocol operations and
content.
Some of the readable data nodes in this YANG module may be considered
sensitive or vulnerable in some network environments. It is thus
important to control read access (e.g., via get, get-config, or
notification) to these data nodes. These are the subtrees and data
nodes and their sensitivity/vulnerability:
/schema-mounts: The schema defined by this state data provides
detailed information about a server implementation may help an
attacker identify the server capabilities and server
implementations with known bugs. Server vulnerabilities may be
specific to particular modules included in the schema, module
revisions, module features, or even module deviations. For example,
if a particular operation on a particular data node is known to
cause a server to crash or significantly degrade device
performance, then the schema information will help an attacker
identify server implementations with such a defect, in order to
launch a denial-of-service attack on the device.
The idea of having some way to combine schemas from different YANG
modules into one has been proposed independently by several groups of
people: Alexander Clemm, Jan Medved, and Eric Voit
(); and Lou Berger and Christian Hopps:
Lou Berger, LabN Consulting, L.L.C., <lberger@labn.net>
Alexander Clemm, Huawei, <alexander.clemm@huawei.com>
Christian Hopps, Deutsche Telekom, <chopps@chopps.org>
Jan Medved, Cisco, <jmedved@cisco.com>
Eric Voit, Cisco, <evoit@cisco.com>
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.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.The Transport Layer Security (TLS) Protocol Version 1.2This document specifies Version 1.2 of the Transport Layer Security (TLS) protocol. The TLS protocol provides communications security over the Internet. The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery. [STANDARDS-TRACK]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]Common YANG Data TypesThis document introduces a collection of common data types to be used with the YANG data modeling language. This document obsoletes RFC 6021.YANG Module LibraryThis document describes a YANG library that provides information about all the YANG modules used by a network management server (e.g., a Network Configuration Protocol (NETCONF) server). Simple caching mechanisms are provided to allow clients to minimize retrieval of this information.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).Network Configuration Access Control ModelThe standardization of network configuration interfaces for use with the Network Configuration Protocol (NETCONF) or the RESTCONF protocol requires a structured and secure operating environment that promotes human usability and multi-vendor interoperability. There is a need for standard mechanisms to restrict NETCONF or RESTCONF protocol access for particular users to a preconfigured subset of all available NETCONF or RESTCONF protocol operations and content. This document defines such an access control model.This document obsoletes RFC 6536.Using the NETCONF Protocol over Secure Shell (SSH)This document describes a method for invoking and running the Network Configuration Protocol (NETCONF) within a Secure Shell (SSH) session as an SSH subsystem. This document obsoletes RFC 4742. [STANDARDS-TRACK]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.Network Management Datastore Architecture (NMDA)Datastores are a fundamental concept binding the data models written in the YANG data modeling language to network management protocols such as the Network Configuration Protocol (NETCONF) and RESTCONF. This document defines an architectural framework for datastores based on the experience gained with the initial simpler model, addressing requirements that were not well supported in the initial model. This document updates RFC 7950.YANG LibraryThis document describes a YANG library that provides information about the YANG modules, datastores, and datastore schemas used by a network management server. Simple caching mechanisms are provided to allow clients to minimize retrieval of this information. This version of the YANG library supports the Network Management Datastore Architecture by listing all datastores supported by a network management server and the schema that is used by each of these datastores. This document obsoletes RFC 7895.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]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 definitions for configuration and system state (status information and counters for the collection of statistics).The YANG data model in this document conforms to the Network Management Datastore Architecture (NMDA) defined in RFC 8342.This document obsoletes RFC 7223.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).YANG Tree DiagramsThis document captures the current syntax used in YANG module tree diagrams. The purpose of this document is to provide a single location for this definition. This syntax may be updated from time to time based on the evolution of the YANG language.Network Device YANG Logical OrganizationThis document presents an approach for organizing YANG models in a comprehensive logical structure that may be used to configure and operate network devices. The structure is itself represented as an example YANG model, with all of the related component models logically organized in a way that is operationally intuitive, but this model is not expected to be implemented. The identified component modules are expected to be defined and implemented on common network devices. This document is derived from work submitted to the IETF by members of the informal OpenConfig working group of network operators and is a product of the Routing Area YANG Architecture design team.YANG Model for Logical Network ElementsThis document defines a logical network element YANG module. This module can be used to manage the logical resource partitioning that may be present on a network device. Examples of common industry terms for logical resource partitioning are Logical Systems or Logical Routers. The YANG model in this document conforms to the Network Management Datastore Architecture as defined in RFCXXXX.YANG Model for Network InstancesThis document defines a network instance module. This module can be used to manage the virtual resource partitioning that may be present on a network device. Examples of common industry terms for virtual resource partitioning are Virtual Routing and Forwarding (VRF) instances and Virtual Switch Instances (VSIs). The YANG model in this document conforms to the Network Management Datastore Architecture defined in I-D.ietf-netmod-revised-datastores.YANG Data Model for IS-IS protocolThis document defines a YANG data model that can be used to configure and manage IS-IS protocol on network elements.Mounting YANG-Defined Information from Remote DatastoresThis document introduces capabilities that allow YANG datastores to reference and incorporate information from remote datastores. This is accomplished by extending YANG with the ability to define mount points that reference data nodes in another YANG subtree, by subsequently allowing those data nodes to be accessed by client applications as if part of an alternative data hierarchy, and by providing the necessary means to manage and administer those mount points. Two flavors are defined: Alias-Mount allows to mount local subtrees, while Peer-Mount allows subtrees to reside on and be authoritatively owned by a remote server. YANG-Mount facilitates the development of applications that need to access data that transcends individual network devices while improving network-wide object consistency, or that require an aliasing capability to be able to create overlay structures for YANG data.
This non-normative example demonstrates an implementation of the
device model as specified in Section 2 of
, using both logical network elements
(LNE) and network instances (NI).
In these examples, the character '\' is used where a line break has
been inserted for formatting reasons.
The data model for the physical device may be described by this YANG
library content, assuming the server supports the NMDA:
Each LNE can have a specific data model that is determined at run
time, so it is appropriate to mount it using the "inline" method,
hence the following "schema‑mounts" data:
An administrator of the host device has to configure an entry for each
LNE instance, for example,
and then also place necessary state data as the contents of the "root"
instance, which should include at least
YANG library data specifying the LNE's data model, for example,
assuming the server does not implement the NMDA:
state data for interfaces assigned to the LNE instance (that
effectively become system-controlled interfaces for the LNE), for
example:
Assuming that network instances share the same data model, it can be
mounted using the "shared‑schema" method as follows:
Note also that the "ietf‑interfaces" module appears in the
"parent‑reference" leaf-list for the mounted NI schema. This means
that references to LNE interfaces, such as "outgoing‑interface" in
static routes, are valid despite the fact that "ietf‑interfaces" isn't
part of the NI schema.
Assume that the mounted NI data model also implements the "ietf‑isis"
module . An RPC operation defined in this
module, such as "clear‑adjacency", can be invoked by a client session
of a LNE's RESTCONF server as an action tied to a the mount point of a
particular network instance using a request URI like this (all on one
line):