YANG LibraryYumaWorksandy@yumaworks.comTail-f Systemsmbj@tail-f.comJuniper Networkskwatsen@juniper.net
This document describes a YANG library that provides information about
all the YANG modules and datastores 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.
There is a need for standard mechanisms to provide the operational
state of a network management server. This includes, for instance,
identifying the YANG modules and datastores that are in use by a
server and how they relate to each other.
This document defines a YANG module that can be used to provide this
informaton, in a way that is compatible with the NMDA
, but that is also backwards
compatible with the "YANG Module Library" YANG module defined in
.
If a large number of YANG modules are utilized by the server,
then the YANG library contents needed can be relatively large. This
information changes very infrequently, so it is important that clients
be able to cache the YANG library contents and easily identify whether
their cache is out of date.
YANG library information can be different on every server
and can change at runtime or across a server reboot.
If the server implements multiple protocols to access the
YANG-defined data, each such protocol has its own conceptual
instantiation of the YANG library.
The following information is needed by a client application
(for each YANG module in the library)
to fully utilize the YANG data modeling language:
identifier: a unique identifier for the module that includes
the module's name, revision, submodules, features, and deviations.
name: The name of the YANG module.
revision: Each YANG module and submodule within the library SHOULD
have a revision. This 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, in a given datastore schema, MUST be identified.
deviation list: The name of each YANG module used for deviation
statements, in a given datastore schema, MUST be identified.
The following information is needed by a client application
(for each datastore supported by the server) to fully access
all the YANG-modelled data available on the server:
identity: the YANG identity for the datastore.
modules: modules supported by the datastore, including any features
and deviations.
The keywords "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, .
The following terms are defined in :
client
server
The following terms are defined in :
module
submodule
The following terms are defined in ^NMDA":
conventional configuration datastore
operational datastore
datastore schema
The following terms are used within this document:
YANG library: A collection of metadata describing the server's
operational state.
A simplified graphical representation of the data model is used in
this document. The meaning of the symbols in these
diagrams is as follows:
Brackets "[" and "]" enclose list keys.
Abbreviations before data node names: "rw" means configuration
data (read-write) and "ro" state data (read-only).
Symbols after data node names: "?" means an optional node, "!" means
a presence container, and "*" denotes a list and leaf-list.
Parentheses enclose choice and case nodes, and case nodes are also
marked with a colon (":").
Ellipsis ("...") stands for contents of subtrees that are not shown.
RFC Ed.: delete this section, including this note, at time of publication.
All NETCONF servers supporting YANG 1.1 MUST support YANG Library
(see Section 5.6.4 of RFC 7950). Similarly, all RESTCONF servers MUST
support YANG Library (see Section 10 of RFC 8040). These requirements
are independent of if the server supports NMDA or not.
RFC 7895 has a mandatory to implement 'modules‑state' tree that a server
uses to advertise all the modules it supports. However, this module was
designed assuming the all modules would be in all datastores, and with the
same number of features and deviations. However, this is not the case
with NMDA-compatible servers that may have some modules that only appear
in <operational> (e.g., ietf-network-topo) or only also appear in a dynamic
datastore (e.g., i2rs-ephemeral-rib). It is also possible that a server
only implements a module in <running>, as it hasn't yet coded support for
returning the module's opstate yet. Presumably, an NMDA-supporting server
would return all modules implemented in every datastore, but this would be
misleading to existing clients and unhelpful to NMDA-aware clients.
In the end, it appears that the 'modules‑state' node should be for non-NMDA
aware clients. For backwards compatability, an NMDA-supporting server SHOULD
populate 'modules‑state' in a backwards-compatible manner. The new
'yang‑library' node would be ignored by legacy clients, while providing
all the data needed for NMDA-aware clients, which would themselves ignore
the 'modules‑state' tree.
The solution presented in this document is further motivated
by the following desires:
leverage Section 5.6.4 of RFC 7950 and Section 10 of RFC 8040.
indicate which modules are supported by each datastore
enable the features and deviations to vary by datastore
structure extensible to support schema-mount
provide a top-level container for all server metadata
This document updates in the following ways:
Renames document title from "YANG Module Library" to "YANG Library".
Adds a new top-level "yang‑library" container to hold many types of
server metadata: modules supported, datastores supported, relationships
between datastores and modules, etc.
Adds a set of new groupings as replacements for the deprecated
"module‑list" grouping.
Adds a "yang‑library‑update" notification as a replacement for the
deprecated "yang‑library‑change" notification.
Deprecates the "modules‑state" tree.
Deprecates the "module‑list" grouping.
Deprecates the "yang‑library‑change" notification.
The "ietf‑yang‑library" module provides information about the modules
and datastores supported by a server. This module is defined using
YANG version 1.1, but it supports the description of YANG modules
written in any revision of YANG.
Following is the YANG Tree Diagram for the "ietf‑yang‑library" module,
excluding the deprecated 'modules‑state' tree:
This container holds all of the server's metadata.
This list contains one entry for each unique instance
of a module in use by the server. Each entry is distinguished
by the module's name, revisions, features, and deviations.
A server cannot implement different revisions of the same module in
different datastores, so there MUST only be a single revision of a
given module in the "module" list that has a "conformance‑type" leaf of
"implement".
Although the server is at liberty to choose the unique "id" for each
entry in the "module" list, it is suggested to use an "id" that would
be meaningful to clients. For example, "ietf‑interfaces@2017‑08‑17"
could be used as the "id" for a particular revision of the IETF
interfaces YANG module. For a module that holds deviations or
features specific to a datastore perhaps an "id" that also contains
the datastore name, like
"ietf‑interfaces‑deviations@2017‑08‑17/operational" could be used.
A "module‑set" represents the datastore schema that is used by one or
more datastores.
This list contains one entry for each module set in use by the server
(e.g., presented by a datastore).
All conventional configuration datastores use the same datastore
schema, which can normally be modelled using a single module set.
A dynamic configuration datastore may use a different datastore schema
from the conventional configuration datastores, and hence may require
a separate module set definition.
The datastore schema for the operational datastore is the superset of
the datastore schema of all the configuration datastores, but can have
unsupported nodes removed via datastore specific deviations or by
omitting one or more modules from the module set associated with the
operational datastore.
However, where possible, the same module set used for conventional
configuration datatstores should also be used for the operational
datastore. For example, deviations that are specific to "config
false" nodes could still be applied to a common module instance that
is also included in the module set used for the conventional
datastores.
Although the server is at liberty to choose the unique "id" for the
"module‑set" list entry, it is suggested to choose an "id" that would be
meaningful to clients, perhaps including the datastore name if the
module set is only relevant to a single datastore.
This list contains one entry for each datastore supported by
the server, and identifes the datastore schema associated with a
datastore via a reference to a module-set. Each supported
conventional configuration datastore has a separate entry.
The "ietf‑yang‑library" module defines monitoring
information for the YANG modules used by a server.
The modules "ietf‑yang‑types" and "ietf‑inet‑types" from
and the module "ietf‑datastores" from
are used by this module for some type definitions.
RFC Ed.: update the date below with the date of RFC publication and
remove this note.
<CODE BEGINS> file "ietf-yang-library@2017-10-30.yang"<CODE ENDS>
RFC 7895 previously registered one URI in the IETF XML registry
. Following the format in RFC 3688, the following
registration was made:
This document takes over this registration entry made by RFC 7895.
RFC 7895 previously registered one YANG module in the
"YANG Module Names" registry as follows:
This document takes over this registration entry made by RFC 7895.
The YANG module defined in this memo is designed to be accessed
via the NETCONF protocol . The lowest NETCONF layer is
the secure transport layer and the mandatory-to-implement secure
transport is SSH . The NETCONF access control model
provides the means to restrict access for particular
NETCONF users to a pre-configured subset of all available NETCONF
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:
/modules-state/module: The module list used in a server
implementation may help an attacker identify the server capabilities
and server implementations with known bugs.
Although some of this information may
be available to all 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. This information is included in each module entry.
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.
Contributions to this material by Andy Bierman are based upon work
supported by the The Space & Terrestrial Communications Directorate
(S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings
and conclusions or recommendations expressed in this material are
those of the author(s) and do not necessarily reflect the views of
The Space & Terrestrial Communications Directorate (S&TCD).
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.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.Network Configuration Protocol (NETCONF) Access Control ModelThe standardization of network configuration interfaces for use with the Network Configuration Protocol (NETCONF) 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 protocol access for particular users to a pre-configured subset of all available NETCONF protocol operations and content. This document defines such an access control model. [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.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).Network Management Datastore ArchitectureDatastores 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.NETCONF 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]