YANG LibraryYumaWorksandy@yumaworks.comTail-f Systemsmbj@tail-f.comJacobs Universityj.schoenwaelder@jacobs-university.deJuniper Networkskwatsen@juniper.netCisco Systemsrwilton@cisco.com
This 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 (NMDA) 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.
Introduction
There is a need for a standard mechanism to expose which YANG modules
, datastores , and datastore schemas
are in use by a network
management server.
This document defines the YANG module "ietf‑yang‑library" that
provides this information. This version of the YANG library is
compatible with the Network Management Datastore Architecture (NMDA)
. The previous version of the YANG
library, defined in , is not compatible with the NMDA since
it assumes that all datastores have exactly the same schema. This is
not necessarily true in the NMDA since dynamic configuration datastores
may have their own datastore schema. Furthermore, the operational
state datastore may support non-configurable YANG modules in addition
to the YANG modules supported by conventional configuration
datastores.
The old YANG library definitions have been retained (for
backwards-compatibility reasons), but the definitions have been marked as
deprecated. For backwards compatibility, an NMDA-supporting server
SHOULD populate the deprecated "/modules‑state" tree in a
backwards-compatible manner. The new "/yang‑library" tree will be
ignored by legacy clients but will provide all the data needed for
NMDA-aware clients (which will ignore the "/modules‑state"
tree).
The recommended approach to populate "/modules-state" is to report
the YANG modules with "config true" data nodes that are
configurable via conventional configuration datastores and the
YANG modules with "config false" data nodes that are returned via a
Network Configuration Protocol (NETCONF) <get>
operation or equivalent.
The YANG library information can be different on every server, and it
can change at runtime or across a server reboot. If a server
implements multiple network management protocols to access the
server's datastores, then each such protocol may have its own
conceptual instantiation of the YANG library.
If a large number of YANG modules are utilized by a server, then the
YANG library contents can be relatively large. Since the YANG library
contents change very infrequently, it is important that clients be
able to cache the YANG library contents and easily identify whether
their cache is out of date.
Terminology
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 :
module
submodule
data node
This document uses the phrase "implement a module" as defined in
Section 5.6.5 of .
The following terms are defined in :
datastore
datastore schema
configuration
conventional configuration datastore
operational state
operational state datastore
dynamic configuration datastore
client
server
The following terms are used within this document:
YANG library: A collection of YANG modules, submodules, datastores,
and datastore schemas used by a server.
YANG library content identifier: A server-generated identifier of
the contents of the YANG library.
Tree diagrams in this document use the notation defined in
.
Objectives
The following information is needed by a client application (for each
YANG module in the library) to fully utilize the YANG data modeling
language:
name: The name of the YANG module.
revision: If defined in the YANG module or submodule, the revision
is derived from the most recent revision statement within the module
or submodule.
submodule list: The name and (if defined) revision of each submodule
used by the module must be identified.
feature list: The name of each YANG feature supported by the
server must be identified.
deviation list: The name of each YANG module with deviation
statements affecting a given YANG module must be identified.
In addition, the following information is needed by a client
application for each datastore supported by a server:
identity: The YANG identity for the datastore.
schema: The schema (i.e., the set of modules) implemented by the
datastore.
In order to select one out of several possible designs for the YANG
library data model, the following criteria were used:
The information must be efficient for a client to consume.
Since the size of the YANG library can be quite large, it should
be possible for clients to cache the YANG library information.
A dynamic configuration datastore must be able to implement a module
or feature that is not implemented in the conventional configuration
datastores.
It must be possible to not implement a module or feature in
<operational>, even if it is implemented in some other datastore.
This is required for transition purposes; a server that wants to
implement <operational> should not have to implement all modules at
once.
A given module can only be implemented in one revision in all
datastores. If a module is implemented in more than one
datastore, the same revision is implemented in all these
datastores.
Multiple revisions can be used for import, if import-by revision
is used.
It must be possible to use the YANG library by schema mount
.
YANG Library Data Model
The "ietf‑yang‑library" YANG module provides information about the
modules, submodules, datastores, and datastore schemas supported by a
server. All data nodes in the "ietf‑yang‑library" module are
"config false" and
thus only accessible in the operational state datastore.
The conceptual model of the YANG library is depicted in
Figure 1. Following the NMDA, every datastore has an associated datastore
schema. A datastore schema is a union of module sets, and every module
set is a collection of modules and submodules, including the modules
and submodules used for imports. Note that multiple datastores may
refer to the same datastore schema. Furthermore, it is possible for
individual datastore schemas to share module sets. A common use case is the
operational state datastore schema, which is a superset of the schema
used by conventional configuration datastores.
Below is the YANG tree diagram for the "ietf‑yang‑library" module,
excluding the deprecated "/modules‑state" tree:
../../module/name
| +--ro import-only-module* [name revision]
| +--ro name yang:yang-identifier
| +--ro revision union
| +--ro namespace inet:uri
| +--ro location* inet:uri
| +--ro submodule* [name]
| +--ro name yang:yang-identifier
| +--ro revision? revision-identifier
| +--ro location* inet:uri
+--ro schema* [name]
| +--ro name string
| +--ro module-set* -> ../../module-set/name
+--ro datastore* [name]
| +--ro name ds:datastore-ref
| +--ro schema -> ../../schema/name
+--ro content-id string
notifications:
+---n yang-library-update
+--ro content-id -> /yang-library/content-id
]]>
The "/yang‑library" container holds the entire YANG library. The
container has the following child nodes:
The "/yang‑library/module‑set" contains entries representing module
sets. The list "/yang‑library/module‑set/module" enumerates the
modules that belong to the module set. A module is listed together
with its submodules (if any), a set of features, and any deviation
modules. The list "/yang‑library/module‑set/import‑only‑module"
lists all modules (and their submodules) used only for imports. The
assignment of a module to a module set is at the server's
discretion. This revision of the YANG library attaches no semantics
as to which module set a module is listed in.
The "/yang‑library/schema" list contains an entry for each datastore
schema supported by the server. All conventional configuration
datastores use the same "schema" list entry. A dynamic configuration
datastore may use a different datastore schema from the conventional
configuration datastores and hence may require a separate "schema"
entry. A "schema" entry has a leaf-list of references to entries in
the "module‑set" list. The schema consists of the union of all
modules in all referenced module sets.
The "/yang‑library/datastore" list contains one entry for each
datastore supported by the server, and it identifies the datastore
schema associated with a datastore via a reference to an entry in
the "schema" list. Each supported conventional configuration
datastore has a separate entry, pointing to the same "schema" list
element.
The "/yang‑library/content‑id" leaf contains the YANG library
content identifier, which is an implementation-specific identifier
representing the current information in the YANG library on a
specific server. The value of this leaf MUST change whenever the
information in the YANG library changes. There is no requirement
that the same information always result in the same "content‑id"
value. This leaf allows a client to fetch all schema information
once, cache it, and only refetch it if the value of this leaf has
been changed. If the value of this leaf changes, the server also
generates a "yang‑library‑update" notification.
Note that for a NETCONF server implementing the NETCONF extensions to
support the NMDA , a change of the YANG
library content identifier results in a new value for the
:yang-library:1.1 capability defined in
. Thus, if such a server implements
NETCONF notifications and the
"netconf‑capability‑change" notification , a
"netconf‑capability‑change"
notification is generated whenever the YANG library content identifier
changes.
YANG Library YANG Module
The "ietf‑yang‑library" YANG module imports definitions from
the "ietf‑yang‑types" and
"ietf‑inet‑types" modules defined in and
from the
"ietf‑datastores" module defined in .
While
the YANG module is defined using YANG version 1.1, the YANG library
supports YANG modules written in any version of YANG.
Adding SVG diagram for testing purposes.<CODE BEGINS> file "ietf-yang-library@2019-01-04.yang"<CODE ENDS>IANA Considerations
RFC 7895 previously registered one URI in the "IETF XML Registry"
. This document takes over this registration entry made by
RFC 7895 and changes the Registrant Contact to the IESG according to Section 4
of .
This document registers a YANG module in the "YANG Module
Names" registry :
This document takes over this registration entry made by RFC 7895.
Security Considerations
The YANG module 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 (NACM)
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:
The "/yang‑library" subtree of the YANG library may help an attacker
identify the server capabilities and server implementations with known
bugs since the set of YANG modules supported by a server may reveal
the kind of device and the manufacturer of the device. Although some
of this information may be available to all NETCONF users via the
NETCONF <hello> message (or similar messages in other management
protocols), this YANG module potentially exposes additional details
that could be of some assistance to an attacker. Server
vulnerabilities may be specific to particular modules, 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
"module" list information will help an attacker identify server
implementations with such a defect, in order to launch a
denial-of-service attack on the device.
ReferencesNormative ReferencesKey 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.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]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]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]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.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.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.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.The Transport Layer Security (TLS) Protocol Version 1.3This document specifies version 1.3 of the Transport Layer Security (TLS) protocol. TLS allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery.This document updates RFCs 5705 and 6066, and obsoletes RFCs 5077, 5246, and 6961. This document also specifies new requirements for TLS 1.2 implementations.Informative ReferencesNETCONF Event NotificationsThis document defines mechanisms that provide an asynchronous message notification delivery service for the Network Configuration protocol (NETCONF). This is an optional capability built on top of the base NETCONF definition. This document defines the capabilities and operations necessary to support this service. [STANDARDS-TRACK]Network Configuration Protocol (NETCONF) Base NotificationsThe Network Configuration Protocol (NETCONF) provides mechanisms to manipulate configuration datastores. However, client applications often need to be aware of common events, such as a change in NETCONF server capabilities, that may impact management applications. Standard mechanisms are needed to support the monitoring of the base system events within the NETCONF server. This document defines a YANG module that allows a NETCONF client to receive notifications for some common system events. [STANDARDS-TRACK]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.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.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.A YANG Data Model for IP ManagementThis document defines a YANG data model for management of IP implementations. The data model includes configuration and system state.The YANG data model in this document conforms to the Network Management Datastore Architecture defined in RFC 8342.This document obsoletes RFC 7277.A YANG Data Model for Network TopologiesThis document defines an abstract (generic, or base) YANG data model for network/service topologies and inventories. The data model serves as a base model that is augmented with technology-specific details in other, more specific topology and inventory data models.A YANG Data Model for Hardware ManagementThis document defines a YANG data model for the management of hardware on a single server.A YANG Data Model for Routing Management (NMDA Version)This document specifies three YANG modules and one submodule. Together, they form the core routing data model that serves as a framework for configuring and managing a routing subsystem. It is expected that these modules will be augmented by additional YANG modules defining data models for control-plane protocols, route filters, and other functions. The core routing data model provides common building blocks for such extensions -- routes, Routing Information Bases (RIBs), and control-plane protocols.The YANG modules in this document conform to the Network Management Datastore Architecture (NMDA). This document obsoletes RFC 8022.NETCONF Extensions to Support the Network Management Datastore ArchitectureYANG Schema MountSummary of Changes from RFC 7895
This document changes in the following ways:
Renamed document title from "YANG Module Library" to "YANG Library".
Added a new top-level "/yang‑library" container to hold the entire
YANG library providing information about module sets, schemas, and
datastores.
Refactored the "/modules‑state" container into a new
"/yang‑library/module‑set" list.
Added a new "/yang‑library/schema" list and a new
"/yang‑library/datastore" list.
Added a set of new groupings as replacements for the deprecated
groupings.
Added a "yang‑library‑update" notification as a replacement for the
deprecated "yang‑library‑change" notification.
Deprecated the "/modules‑state" tree.
Deprecated the "/module‑list" grouping.
Deprecated the "/yang‑library‑change" notification.
Example YANG Library Instance for a Basic Server
The following example shows the YANG library of a basic server
implementing the "ietf‑interfaces" and
"ietf‑ip" modules in the <running>,
<startup>, and <operational> datastores and the "ietf‑hardware"
module in the <operational> datastore.
Newline characters in leaf values are added for formatting reasons.
config-modulesietf-interfaces2018-02-20
urn:ietf:params:xml:ns:yang:ietf-interfaces
ietf-ip2018-02-22
urn:ietf:params:xml:ns:yang:ietf-ip
ietf-yang-types2013-07-15
urn:ietf:params:xml:ns:yang:ietf-yang-types
ietf-inet-types2013-07-15
urn:ietf:params:xml:ns:yang:ietf-inet-types
state-modulesietf-hardware2018-03-13
urn:ietf:params:xml:ns:yang:ietf-hardware
ietf-inet-types2013-07-15
urn:ietf:params:xml:ns:yang:ietf-inet-types
ietf-yang-types2013-07-15
urn:ietf:params:xml:ns:yang:ietf-yang-types
iana-hardware2018-03-13
urn:ietf:params:xml:ns:yang:iana-hardware
config-schemaconfig-modulesstate-schemaconfig-modulesstate-modulesds:startupconfig-schemads:runningconfig-schemads:operationalstate-schema75a43df9bd56b92aacc156a2958fbe12312fb285
]]>Example YANG Library Instance for an Advanced Server
The following example extends the example in
by using modules from and to illustrate
a slightly more advanced server that:
Has a module with features only enabled in <operational>; the
"ietf-routing" module is supported in <running>, <startup>, and
<operational>, but the "multiple‑ribs" and "router‑id" features are
only enabled in <operational>. Hence, the "router‑id" leaf may be
read but not configured.
Supports a dynamic configuration datastore
"example‑ds‑ephemeral", with only the "ietf‑network" and
"ietf‑network‑topology" modules configurable via a notional dynamic
configuration protocol.
Shows an example of datastore-specific deviations. The
"example‑vendor‑hardware‑deviations" module is included in
the schema for <operational> to remove data nodes that cannot be
supported by the server.
Shows how module-sets can be used to organize related modules together.