One document matched: draft-bierman-netmod-yang-conformance-04.xml
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt"?>
<!DOCTYPE rfc SYSTEM 'rfc2629.dtd'>
<?rfc toc="yes"?>
<?rfc compact="no"?>
<?rfc subcompact="no"?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes"?>
<?rfc iprnotified="no"?>
<?rfc strict="yes"?>
<rfc ipr="trust200902" category="std"
docName="draft-bierman-netmod-yang-conformance-04" >
<front>
<title abbrev="YANG Conformance">YANG Conformance Specification</title>
<author initials="A" surname="Bierman" fullname='Andy Bierman' >
<organization>YumaWorks</organization>
<address>
<email>andy@yumaworks.com</email>
</address>
</author>
<date/>
<abstract>
<t>
This document describes conformance specification
and advertisement mechanisms for NETCONF servers
implementing YANG data model modules.
</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>
There is a need for standard mechanisms to
allow YANG <xref target="RFC6020"/> data model designers to express more
precise and robust conformance levels for
server implementations of a particular YANG module,
or set of YANG modules.
</t>
<t>
There is also a need for standard mechanisms to
allow NETCONF <xref target="RFC6241"/> servers to precisely advertise the
conformance level of each YANG module it supports.
</t>
<t>
This document describes some problems with the current
conformance specifications mechanisms in YANG and
conformance advertisement mechanisms in NETCONF.
Solution proposals are also presented to address these problems.
</t>
<section title="Terminology">
<t>
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, <xref target="RFC2119"/>.
</t>
<section title="NETCONF">
<t>
The following terms are defined in <xref target="RFC6241"/>:
</t>
<t>
<list style="symbols">
<t>
capability
</t>
<t>
client
</t>
<t>
datastore
</t>
<t>
protocol operation
</t>
<t>
server
</t>
</list>
</t>
</section>
<section title="YANG">
<t>
The following terms are defined in <xref target="RFC6020"/>:
</t>
<t>
<list style="symbols">
<t>
data node
</t>
<t>
extension
</t>
<t>
feature
</t>
<t>
grouping
</t>
<t>
identity
</t>
<t>
module
</t>
<t>
notification
</t>
<t>
submodule
</t>
<t>
typedef
</t>
</list>
</t>
</section>
<section title="Terms">
<t>
The following terms are used within this document:
</t>
<t>
<list style="symbols">
<t>
base module: There is an implied "base" subset of a YANG module,
which includes all "rpc", "data‑def", and "notification" statements
which are not conditional. The base module may be empty,
a subset of all statements, or the entire module.
</t>
<t>
conditional node: An object that
has one or more "if‑feature" sub-statements associated with it.
Note that objects affected by "when" statements are not considered
conditional for conformance purposes.
</t>
<t>
import-by-revision: A YANG import statement that includes
a revision-date statement. This specifies the exact revision
of the YANG module to import, instead of the server picking
the revision to import.
</t>
<t>
include-by-revision: A YANG include statement that includes
a revision-date statement. This specifies the exact revision
of the YANG submodule to include, instead of the server picking
the revision to include.
</t>
<t>
object: a conceptual data structure represented by a
YANG data, rpc, or notification statement.
</t>
<t>
revision identifier: a YANG module revision is identified by
the revision date value of the most recent revision statement
in the module. If there are no revision statements then
the empty string is the revision identifier.
</t>
<t>
schema tree: The conceptual tree of all objects derived from
the set of all YANG modules supported by the server. This tree
only includes conditional nodes if all corresponding if-feature
statements are "true". Any deviation statements have also been
conceptually applied to the schema tree as well.
</t>
<t>
YANG dependency tree: A conceptual tree containing
the set of all revision identifiers
for all modules and submodules in the schema tree.
</t>
</list>
</t>
</section>
<section title="Tree Diagrams">
<t>
A simplified graphical representation of the data model is used in
this document. The meaning of the symbols in these
diagrams is as follows:
</t>
<t>
<list style="symbols">
<t>
Brackets "[" and "]" enclose list keys.
</t>
<t>
Abbreviations before data node names: "rw" means configuration
data (read-write) and "ro" state data (read-only).
</t>
<t>
Symbols after data node names: "?" means an optional node, "!" means
a presence container, and "*" denotes a list and leaf-list.
</t>
<t>
Parentheses enclose choice and case nodes, and case nodes are also
marked with a colon (":").
</t>
<t>
Ellipsis ("...") stands for contents of subtrees that are not shown.
</t>
</list>
</t>
</section>
</section>
</section>
<section title="Overview">
<t>
The YANG module represents a conceptual API contract between
the client and server for a management protocol that uses YANG.
There are two primary factors that directly impact interoperability.
</t>
<t>
<list style="symbols">
<t>
Client and Server Implementation Requirements
</t>
<t>
Actual Server Implementation Capabilities
</t>
</list>
</t>
<t>
The syntax and semantics of a given data model,
used within a specific protocol, must be
understood by the client and server developers to
achieve interoperability.
</t>
<t>
These implementation requirements need to stable, and not
change for a given revision of a module. Any changes to
the implementation requirements needs to be intentional,
and properly identified and understood by client and
server developers.
</t>
<section title="Server Implementation Capabilities">
<t>
The actual implemented portions of a given data model,
used within a specific protocol, must be
understood by the client. For YANG, a "YANG Module capability URI"
is advertised in the server capabilities, and understood by the client.
</t>
<t>
For improved interoperability,
the server must identify its conformance level for each
module, and identify and deviations from the advertised conformance
level.
</t>
</section>
</section>
<section title="Problems With YANG Conformance Mechanisms">
<t>
This section describes some perceived deficiencies with
the current YANG data model conformance specification and
NETCONF server conformance advertisement mechanisms.
</t>
<t>
The engineering trade-off that needs to be considered is the
complexity and effort required to specify conformance information
and the accuracy and specificity of the conformance information
that is defined.
</t>
<t>
The rest of this section discusses the advantages and
disadvantages of the two solution paths available in YANG
to identify conformance requirements.
</t>
<t>
Option 1: do not use import-by-revision or include-by-revision at all.
This approach requires some other mechanism besides the import
and include statements to fully identity the dependency tree.
</t>
<t>
Option 2: use import-by-revision and include-by-revision everywhere
so the YANG dependency tree is fully specified.
</t>
<section title="Incomplete Dependency Tree: Conformance Drift">
<t>
If the import-by-revision and include-by-revision mechanisms
are not used everywhere in the dependency tree, then the
application compiling the YANG modules must decide somehow
which revision to use for any module or submodule without a revision-date
statement.
</t>
<t>
When new modules are added which require the revision of a shared
module to be updated, the server will need to advertise the
updated module. There is ambiguity whether the server needs to
advertise all the revisions of all the YANG modules is uses,
and what that even means in some cases.
</t>
<t>
Conformance drift occurs when definition updates in an imported module
inadvertently change the syntax and/or semantics of statements
in the importing module. These changes occur without a change
in the revision date for the importing module, which makes them
hidden undocumented conformance updates.
</t>
<section title="Typedef Drift">
<t>
Typedef drift can occur if a leaf or leaf-list "type" statement
references a "typedef" statement from an external module.
The YANG syntax specified for a leaf or leaf-list will
depend on which revision of the external module is used.
If the newer revision is used, then the allowed value set will
be changed.
</t>
<t>
There are several ways this is allowed under the conditions
described in section 10 of <xref target="RFC6020"/>:
</t>
<t>
<list style="symbols">
<t>
an "enumeration" type can add new "enum" statements
</t>
<t>
a "bits" type can add new "bit" statements
</t>
<t>
a "range", "length", or "pattern" statement may expand the allowed
value space
</t>
</list>
</t>
<t>
Note that conformance for "identityref" types are discussed separately.
This data type is complex because the value
set is distributed, and actual allowed values of this type
are node and/or context-specific.
</t>
</section>
<section title="Grouping Drift">
<t>
Grouping drift can occur if a "uses" statement
references a "grouping" statement from an external module,
and the grouping contents change.
New data nodes can be added to a grouping in a new revision of
a module under certain conditions, described in section 10 of <xref target="RFC6020"/>:
</t>
<t>
The YANG data nodes that are copied from the grouping will
depend on which revision of the external module is used.
If the newer revision is used, then any new and/or modified objects
will be added to the schema tree.
</t>
<t>
It is not clear how multiple revisions of the same grouping can be
used reliably. It depends on the content of the grouping.
For example, a grouping may contain objects with "must" or "when"
XPath expressions. These expressions can reference objects inside
or outside the grouping in a manner that has the desired effect
when evaluated with the intended revision of the grouping, but
incorrect effect when evaluated against newer modules.
</t>
<t>
It is therefore unsafe for a server to support multiple revisions of
a grouping, in a generic manner.
</t>
</section>
<section title="Conformance Drift Example">
<t>
Consider the "first release" where the module set advertised by the server
consists of 2 modules:
</t>
<figure>
<artwork><![CDATA[
- module A, revision 2014-01-01
- module B, revision 2014-01-02
module A {
namespace "module-A";
prefix A;
revision "2014-01-01" {
description "First revision";
}
typedef knob-range {
type int32 { range "1 .. 100"; }
}
grouping knob-group {
leaf knobA {
type knob-range;
}
}
leaf which-leaf {
type knob-range;
}
}
module B {
namespace "module-B";
prefix B;
import A { prefix A; }
revision "2014-01-02" {
description "First revision";
}
leaf knob1 {
type A:knob-range;
}
container knobs {
uses A:knob-group;
}
}
]]></artwork>
</figure>
<t>
The server can clearly express the value range allowed for "knob1"
in revision "2014‑01‑02" of the "B" module. There is only 1 leaf
("knobA") in the "knobs" container. There is only 1 possible revision
of module "A" that can be advertised by a server, so the definition
of the "which‑leaf" leaf is clear.
</t>
<t>
Now consider the "second release" where the module set has been extended
to 3 modules, and module "A" has been updated but module "B" has not
been updated. The server advertises the latest revision of module "A"
instead of both revisions. This module was updated to support module "C".
</t>
<figure>
<artwork><![CDATA[
- module A, revision 2014-02-01 (updated)
- module B, revision 2014-01-02 (unchanged)
- module C, revision 2014-02-02 (new)
module A {
namespace "module-A";
prefix A;
revision "2014-02-01" {
description "Second revision";
}
revision "2014-01-01" {
description "First revision";
}
typedef knob-range { // range expanded and default added!
type int32 { range "1 .. 500"; }
default 500;
}
grouping knob-group {
leaf knobA {
type knob-range;
}
leaf knobB { // added 1 leaf to grouping!
type knob-range;
}
}
leaf which-leaf {
type knob-range; // type changed!
default 200; // added default!
}
}
module C {
namespace "module-C";
prefix C;
import A { prefix A; }
revision "2014-02-02" {
description "First revision";
}
leaf knob2 {
type A:knob-range;
}
}
]]></artwork>
</figure>
<t>
There are unadvertised changes in module "B":
</t>
<t>
<list style="symbols">
<t>
"knob1" leaf range expanded and default added
</t>
<t>
"knobB" leaf added to the "knobs" container
</t>
</list>
</t>
<t>
Problems can occur if the client understanding of the
dependency tree is not accurate. It might assume
the server has updated the instrumentation for the "knob1" leaf
so the increased range and new default are supported.
The "knob1" syntax used depends on which revision of module "A"
that is parsed.
</t>
<t>
Problems can occur if the server instrumentation understanding of the
dependency tree is not accurate. It might assume
the server validation code will only give it a
valid value for leaf "knob1" which fits in one byte.
Values from 256 to 500 in this example might cause
internal errors in the server.
</t>
<t>
If the server advertises the latest revisions of the YANG modules
then syntax of "knob1" and contents of the "knobs" container
will change, even though module "B" has not been updated.
This can cause the client to send invalid protocol requests
or misinterpret data received from the server.
</t>
</section>
</section>
<section title="Complete Dependency Tree: Multiple Concurrent Revisions">
<t>
If exact revision dates are used everywhere then they need
to be carefully examined each time any module in
the dependency tree is changed. Updating modules just
to change the revision date of an updated imported module
also changes the revision date of the importing module.
This ripple effect creates many revisions that do not
even import the particular module, and would add significant
complexity to module lifecycle management.
</t>
<t>
If some dependencies are updated but not others,
then the client and server will need to support
multiple revisions of the same module or submodule at the same time.
This is the most likely scenario to occur.
</t>
<t>
NETCONF and YANG do not specify how a server must support multiple revisions
of the same module at the same time. This causes interoperability
problems which need to be addressed.
</t>
<t>
Consider the previous example, except import-by-revision is used
everywhere to fix the conformance drift problem. The only changes
at all are the addition of revision dates in the import statements
in modules "B" and "C".
</t>
<section title="Conformance Ambiguity Example">
<t>
If import-by-revision is used everywhere, then the second release
in the previous example would contain the following modules
and revisions advertised by the server:
</t>
<figure>
<artwork><![CDATA[
- module A, revision 2014-01-01
- module A, revision 2014-02-01
- module B, revision 2014-01-02
- module C, revision 2014-02-02
]]></artwork>
</figure>
<t>
The conformance drift problems in module "B" are fixed.
Module "B" use the old definitions from the first
revision of module "A", and module "C" uses the new definitions
from the updated revision.
</t>
<t>
However, now that 2 revisions of module "A" are advertised
by the server, it is not clear what revision of leaf "which‑leaf"
from module "A" is implemented by the server.
</t>
<t>
This problem applies to all protocol accessible statements
(data nodes, "rpc", and "notification" statements). It may also
apply to any global reusable statements such as "extension" and
"feature". Advertising multiple revisions of any of these
statements causes ambiguity in the conformance definition.
</t>
</section>
<section title="Augmenting External Data Nodes">
<t>
The problem of ambiguous conformance affects data nodes
derived from external augmentation, i.e., several modules
(all using import-by-revision) augment multiple revisions
of the same data nodes. The augmenting nodes can change
over time, and they can themselves contain imported
definitions.
</t>
<t>
The YANG conformance rules do not support different revisions of the same
data node instance. The actual implementation matrix cannot
be an ad-hoc subset of all possible revision
combinations. The client needs to be able to identify
the exact revisions of data nodes that are supported by the
server.
</t>
</section>
<section title="Identityref Value Sets">
<t>
A server cannot advertise even the complete set of identities
that it supports. It actually advertises all of the
identities in all modules in the dependency tree. This is
a superset of all supported identities by the server.
</t>
<t>
It is not possible for a client to determine the
supported identity set at all. In addition, individual identityref
leafs may support different subsets of all possible identities
supported by the server. For example, simply importing the
"iana‑if‑types" YANG module does not mean the server supports
every possible interface type that has ever been defined.
</t>
<t>
YANG conformance requirements for "identityref" leafs are unclear
and need to be clarified. Discovery of agent capabilities
of actual supported identities is needed.
</t>
</section>
<section title="Leafref Value Sets">
<t>
YANG conformance requirements for "leafref" leafs are unclear
and need to be clarified. Support for discovery of agent capabilities
of actual supported identities is needed. The same issues that
apply to "identityref" types can occur with "leafref" types.
</t>
</section>
</section>
<section title="Module Capability Advertisement Issues">
<t>
NETCONF servers advertise the YANG modules they support
as <capability> URI strings in the <hello> message.
The complete list of modules used by the server needs to
be advertised in order for the client application to correctly parse the
YANG modules and reproduce the schema tree used by the server.
However the client does not really know which modules are advertised
for full conformance, and which are advertised for partial
conformance (such as importing
typedef and identity statements from the module).
The conformance information that is derived from the YANG module
advertisement needs to be clarified.
</t>
</section>
</section>
<section title="YANG Conformance Guidelines">
<t>
Conformance for the "ietf‑yang‑conformance" module capability
requires implementation of these conformance guidelines.
</t>
<section title="Conformance is Based on the Module Set, not One Module">
<t>
The reason conformance drift and
conformance ambiguity are currently problems is due
to the incorrect assumption that a YANG datastore is allowed
to be considered a collection of independent module implementations.
This is done in pursuit of module independence and the ability
to support off-line validation tools of YANG content.
</t>
<t>
The "individual module" approach does not work for YANG datastores.
Instead, the YANG conformance needs to be based on the
entire module set, identified by the collection of
YANG modules and submodules, features and deviations that
the server is using at the moment.
</t>
<t>
The revision date for a specific module or submodule only freezes
the definitions within that module or submodule. Any external
modules or submodules have their own revision date, that cannot
be frozen in the server implementation.
</t>
<t>
It is the responsibility of the YANG module writer to ensure that
a new or existing module is syntactically and semantically compatible
with the current revision of all external modules imported by that module.
It is the responsibility of the NETCONF server developer to ensure that
the supported module set is syntactically and semantically self-compatible.
</t>
</section>
<section title="Import has no Conformance Semantics">
<t>
Simply importing a module implies no conformance relationship
between the importing and imported module. There are many ways that
YANG can be used so an imported module is not even used. E.g.,
the only identifiers from the imported module have "if‑feature"
statements, but the server does not enable any of the features.
The "import" statement is only useful for resolving external
identifiers used in the current module.
</t>
</section>
<section title="Only the Most Recent Revision Allowed">
<t>
The server MUST implement the most recent revision of each module it
advertises. The vendor cannot upgrade a shared module without updating all the
modules that actually depend on the changes.
</t>
<t>
If any of the following statements in the most recent
advertised revision of the base module are not
supported by the server, then a YANG module containing the
appropriate "deviation" statements MUST be advertised for
that module.
</t>
<t>
<list style="symbols">
<t>
augment-stmt
</t>
<t>
data-def-stmt
</t>
<t>
notification-stmt
</t>
<t>
rpc-stmt
</t>
</list>
</t>
<t>
If a shared module needs to be updated, then the conformance
is implicitly updated for the modules that depend on the changes.
</t>
<section title="YANG Module Capability URIs">
<t>
There are existing NETCONF client applications that assume
that all the YANG modules used by the server
will be sent in the <hello> message. These applications
are likely to fail if an incomplete module set is advertised
by the server.
</t>
<t>
The server MUST advertise the most recent revision of all YANG
modules that it supports, including modules that do not contain any
data definitions.
</t>
<t>
If the server uses any modules with submodules, then the
"submodule" capability in <xref target="submodule-cap"/> SHOULD be advertised
for each submodule used. Only one revision of each submodule SHOULD
be advertised.
</t>
</section>
</section>
<section title="Import and Include By Revision Do Not Really Help">
<t>
The simplest solution for fixing the conformance drift
problem would be to use import and include by revision everywhere,
and make this usage mandatory.
Any new YANG statements would
cause duplication of the module or submodule name and revision
date information.
However, this solution is not workable because the ripple effect
will require constant updating of many YANG modules just to change the
revision-date clause.
</t>
<t>
Multiple concurrent revisions of YANG datastore contents
are not supported in a NETCONF server. The server behavior required
for import-by-revision has never been specified wrt/ multiple
revisions of the same module.
</t>
<t>
The "revision‑date" statement SHOULD NOT be used in "import" statements.
Conformance for external modules cannot be fixed to a specific revision
when used within a NETCONF server. If the "revision‑date" statement is used,
it SHOULD be interpreted as "the current revision of the imported module
when this module was published". The actual revision used
by the server will be advertised in the YANG module capability URI.
</t>
<t>
The hard-wired revision dates in "import" statements
are only useful for off-line validation.
of protocol requests. Even then, they must be used
everywhere to be deterministic.
Real NETCONF sessions require not only all the module
names and revision dates, but the enabled YANG features and
YANG conformance deviations.
</t>
</section>
<section title="Limit Protocol Accessible Objects in the Base Module">
<t>
YANG module designers SHOULD NOT specify "augment", "rpc",
"notification", or any data definition statements in the
base module of a YANG module, if it also contains any
"typedef", "grouping", "identity", "extension",
or "deviation" statements. This will prevent the need
for deviations advertisement by the server, just to utilize
the definitions designed for reusability.
</t>
<t>
Note that the "feature" statement is not included in this
list, otherwise if any optional protocol-accessible statements
were needed, then they would all need to be optional.
</t>
<t>
Reusable definitions can be placed in a separate module
with no protocol-accessible statements, or the protocol-accessible
statements can contain "if‑feature" statements to remove
them from the base module. Either practice is acceptable.
</t>
</section>
</section>
<section title="YANG Submodule Capability" anchor="submodule-cap">
<section title="Overview">
<t>
A new capability called "submodule" is defined to
identify the specific revisions of all submodules the server is using.
</t>
<t>
When a new session is started, the client can examine
the "submodule" <capability> URIs sent by the server
to determine the specific revision that the server is using
for each submodule.
</t>
<t>
Since submodule names share the same namespace as module names,
there is no need to add the parent module name and revision
to the advertisement. The server is required to support
the advertised revision, and only one revision can be advertised.
</t>
<section title=":submodule Capability Example">
<t>
The following example show just the "submodule" capability for
submodule "submod‑A" with revision date "2014‑09‑23",
and submodule "submod‑B" with revision date "2013‑10‑01",
The URIs are wrapped for display purposes only.
</t>
<figure>
<artwork><![CDATA[
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities>
<capability>
urn:ietf:params:netconf:capability:submodule:1.0?
name=submod-A&revision=2014-09-23
</capability>
<capability>
urn:ietf:params:netconf:capability:submodule:1.0?
name=submod-B&revision=2013-10-01
</capability>
// ... rest of <capability> elements
<capabilities>
<session-id>3</session-id>
</hello>
]]></artwork>
</figure>
</section>
</section>
<section title="Dependencies">
<t>
The :submodule capability is not dependent on any other capabilities.
</t>
</section>
<section title="Capability Identifier">
<t>
The :submodule capability is identified by the following
capability string:
</t>
<figure>
<artwork><![CDATA[
urn:ietf:params:netconf:capability:submodule:1.0
]]></artwork>
</figure>
<t>
The :submodule capability SHOULD be sent in every server <hello> message,
for each submodule used by the server.
The "submodule" parameter for the :submodule capability MUST be present,
and is set to the name of the submodule.
The "revision" parameter for the :submodule capability MUST be present,
and is set to the revision date of the submodule.
</t>
</section>
<section title="New Operations">
<t>
The :submodule capability does not introduce any
new protocol operations.
</t>
</section>
<section title="Modifications to Existing Operations">
<t>
The :submodule capability does not modify any existing
protocol operations.
</t>
</section>
<section title="Interactions with Other Capabilities">
<t>
The :submodule capability does not interact with any other
capabilities.
</t>
</section>
</section>
<section title="YANG Conformance Module">
<t>
The "ietf‑yang‑conformance" module in <xref target="module"/> defines 2 protocol
operations for retrieving allowed value sets from the server.
There is also an augmentation of the "schema" list in the
"ietf‑netconf‑monitoring" module defined in <xref target="RFC6022"/>.
</t>
<figure>
<artwork><![CDATA[
augment /ncm:netconf-state/ncm:schemas/ncm:schema:
+--ro conformance-type? enumeration
+--ro belongs-to-module? string
rpcs:
+---x get-allowed-identities {get-allowed}?
| +--ro input
| | +--ro target instance-identifier
| +--ro output
| +--ro (response)?
| | +--:(all)
| | | +--ro all? empty
| | +--:(identity)
| | +--ro identity* string
| +--ro support-all? empty
+---x get-allowed-leafrefs {get-allowed}?
+--ro input
| +--ro target instance-identifier
+--ro output
+--ro (response)?
| +--:(all)
| | +--ro all? empty
| +--:(value)
| +--ro value* string
+--ro support-all? empty
]]></artwork>
</figure>
<section title="Identityref Value Set Discovery">
<t>
A server is not required to support all advertised identity values.
The actual values required for a particular "identityref" leaf
or leaf-list MAY be specified in the YANG module. If not, then
the entire list of identities with a matching "base" definition
is used as the superset of all allowed values for the identityref.
</t>
<t>
A new protocol operation called "get‑allowed‑identities" is defined
to allow a client to discover the set of identities actually supported
at the moment for a specific leaf or leaf-list.
</t>
</section>
<section title="Leafref Value Set Discovery">
<t>
A server is not required to support all existing potential instances
for a leaf or leaf-list using the "leafref" data type.
The entire list of instances of the data node specified in the "path" statement
is used as the superset of all allowed values for the leafref type.
</t>
<t>
A new protocol operation called "get‑allowed‑leafrefs" is defined
to allow a client to discover the set of leafref values actually supported
at the moment for a specific leaf or leaf-list.
</t>
</section>
<section title="Schema Conformance Discovery">
<t>
The "schema" list in the "ietf‑netconf‑monitoring" module identifies
all the YANG modules available to the server. A new leaf called
"conformance‑type" is defined to augment this list.
</t>
<t>
Two conformance types are defined, called "base" and "reuse".
This information allows clients to understand how each module
is used, without parsing and and analyzing the "capability" URIs
from the "ietf‑netconf‑monitoring" module.
</t>
</section>
<section title="YANG module" anchor="module">
<t>
RFC Ed.: update the date below with the date of RFC publication and
remove this note.
</t>
<t><CODE BEGINS> file "ietf-yang-conformance@2014-09-24.yang"</t>
<figure>
<artwork><![CDATA[
module ietf-yang-conformance {
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-conformance";
prefix "yangconf";
import ietf-netconf-monitoring { prefix ncm; }
organization
"IETF NETMOD (NETCONF Data Modeling Language) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/netmod/>
WG List: <mailto:netmod@ietf.org>
WG Chair: Thomas Nadeau
<mailto:tnadeau@lucidvision.com>
WG Chair: Juergen Schoenwaelder
<mailto:j.schoenwaelder@jacobs-university.de>
Editor: Andy Bierman
<mailto:andy@yumaworks.com>";
description
"This module contains RPC statements to identify
the server capabilities for specific data nodes.
NETCONF Monitoring extensions are also provided
to report YANG conformance information.
Copyright (c) 2014 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; see
the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
// RFC Ed.: remove this note
// Note: extracted from draft-bierman-netmod-restconf-01.txt
// RFC Ed.: update the date below with the date of RFC publication
// and remove this note.
revision 2014-09-24 {
description
"Initial revision.";
reference
"RFC XXXX: YANG Conformance.";
}
feature netconf-monitoring {
description
"Indicates the ietf-netconf-monitoring extensions
defined in this module are supported.";
}
feature get-allowed {
description
"Indicates the 'get-allowed-identities' and
'get-allowed-leafrefs' protocol operations are supported.";
}
rpc get-allowed-identities {
if-feature get-allowed;
description
"Returns the set of identity values that are supported for
a specific data node instance. The server will indicate
if all instances of the specified data node accept the
same value set.
The server will return an error with an
'invalid-value' error-tag if the target parameter
referenced an invalid instance.
The server MAY support this operation for operational
data (i.e. config false). If not, then an error with an
'operation-not-supported' error-tag will be returned
by the server if the target parameter does not identify
a data node in the configuration datastore";
input {
leaf target {
type instance-identifier {
require-instance false;
}
mandatory true;
description
"Identifies an instance or possible instance of
a data node that uses the identityref data type.
The server will return information about the
accepted values for this data node.";
}
}
output {
choice response {
description
"Either the 'all' element is returned or one or more
'identity' elements are returned in the response.";
leaf all {
type empty;
description
"Indicates all advertised identities with a matching
base value are supported for the specified data node.";
}
leaf-list identity {
type string;
description
"This formatted string contains the value of an
acceptable identity for the specified identityref
data node. It has the following format:
<module-name>:<identity-name>
The module name is followed by the colon (':')
character, which is followed by the identity name.
No whitespace is allowed.";
}
}
leaf support-all {
type empty;
description
"Indicates all possible instances of the target data node
support the same identities.";
}
}
}
rpc get-allowed-leafrefs {
if-feature get-allowed;
description
"Returns the set of leafref values that are supported for
a specific data node instance. The server will indicate
if all instances of the specified data node accept the
same value set.
The server will return an error with an
'invalid-value' error-tag if the target parameter
referenced an invalid instance.
The server MAY support this operation for operational
data (i.e. config false). If not, then an error with an
'operation-not-supported' error-tag will be returned
by the server if the target parameter does not identify
a data node in the configuration datastore";
input {
leaf target {
type instance-identifier {
require-instance false;
}
mandatory true;
description
"Identifies an instance or possible instance of
a data node that uses the leafref data type.
The server will return information about the
accepted values for this data node.";
}
}
output {
choice response {
description
"Either the 'all' element is returned or one or more
'value' elements are returned in the response.";
leaf all {
type empty;
description
"Indicates all current instances of the data node
identified by the 'path' statement for the
target parameter are supported.";
}
leaf-list value {
type string;
description
"This string contains the value of an
acceptable leafref, encoded as a string.";
}
}
leaf support-all {
type empty;
description
"Indicates all possible instances of the target data
node support the same leaf values.";
}
}
}
augment /ncm:netconf-state/ncm:schemas/ncm:schema {
if-feature netconf-monitoring;
description
"Conformance information added to each 'schema' list entry.";
leaf conformance-type {
type enumeration {
enum base {
description
"Indicates the entire base module is supported within
the server. The server MAY also advertise YANG features
and YANG deviations for this module.";
}
enum reuse {
description
"Indicates that no data definition, augment, rpc,
or notification statements in the base module are
used from the module. Only reusable definitions are
used, which include the following statements:
- extension-stmt
- feature-stmt
- identity-stmt
- typedef-stmt
- grouping-stmt
";
}
}
config false;
description
"Indicates how the server is claiming conformance
for the module represented by this schema.";
}
leaf belongs-to-module {
type string;
config false;
description
"This leaf is only applicable if the schema identified
this entry represents a YANG submodule. If so, then this
string identifies the parent module name for the
submodule.";
}
}
}
]]></artwork>
</figure>
<t><CODE ENDS></t>
</section>
</section>
<section title="IANA Considerations" anchor="iana">
<section title="YANG Module Registry">
<t>
This document registers one URI in the IETF XML registry
<xref target="RFC3688"/>. Following the format in RFC 3688, the following
registration is requested to be made.
</t>
<figure>
<artwork><![CDATA[
URI: urn:ietf:params:xml:ns:yang:ietf-yang-conformance
Registrant Contact: The NETMOD WG of the IETF.
XML: N/A, the requested URI is an XML namespace.
]]></artwork>
</figure>
<t>
This document registers one YANG module in the YANG Module Names
registry <xref target="RFC6020"/>.
</t>
<figure>
<artwork><![CDATA[
name: ietf-yang-conformance
namespace: urn:ietf:params:xml:ns:yang:ietf-yang-conformance
prefix: yangconf
// RFC Ed.: replace XXXX with RFC number and remove this note
reference: RFC XXXX
]]></artwork>
</figure>
</section>
</section>
<section title="Security Considerations">
<t>
TBD.
</t>
<t>
Access control may need to be considered.
For example, a server may wish to prune
values returned from the "get‑allowed‑identities" or "get‑allowed‑leafrefs"
operations, based on the client user identity.
</t>
</section>
<section title="Open Issues">
<section title="YANG Module Advertisement">
<section title="Capability-ID vs. Module URI List">
<t>
Left out of this release:
</t>
<figure>
<artwork><![CDATA[
augment /ncm:netconf-state/ncm:capabilities {
if-feature netconf-monitoring;
leaf capability-set-id {
config false;
type string;
description
"Contains the capability set identifier for the
current set of capability URIs. The server MUST
update this value if any capability URIS are added,
modified, or deleted.
The server SHOULD select a previously unused value
each time the value is changed.
This object can enable caching of the capability URI
list by a client.";
}
}
]]></artwork>
</figure>
<t>
The "capability‑id" was first introduced
in "draft‑bierman‑netconf‑efficiency‑extensions‑00.txt"
in October 2013. Switching from <hello> based module set discovery to
retrieval-based module set discovery requires a "flag day" upgrade,
and the data that is replacing the removed <capability> URIs needs to
be mandatory-to-implement.
</t>
<t>
If the <hello> is really too large, then a single <capability‑set‑id> URI could
be used instead, so the client could cache the data and reduce bandwidth
(at the cost of maintaining a cache). It is not clear that the <hello> message
is really too large relative to SSH setup and other data.
</t>
</section>
<section title="Full vs. Partial <capability> List">
<t>
If only supported modules are advertised in the <hello> then the client
has an incomplete list and must retrieve the revision dates of all the modules
that are just imported. If the client has to retrieve any information at all
to complete the module set, then it might as well retrieve all of it.
</t>
</section>
</section>
<section title="YANG 1.1 Support">
<t>
The YANG 1.1 plan for server capability discovery
is to only advertise YANG 1.0 modules, and
not advertise any YANG 1.1 modules. Instead,
a hash or instance-identifier will be used for client caching,
and the client will retrieve the module information instead.
It is not known if any new mechanisms will be needed in this document.
</t>
</section>
<section title="Protocol Independence">
<t>
<list style="symbols">
<t>
Should this document be written so it is specific to
the NETCONF and RESTCONF protocols?
</t>
<t>
If protocol independence is required, then what parts
of the draft need to be changed? What parts need to be moved
to a different document?
</t>
</list>
</t>
</section>
</section>
<section title="Change Log">
<figure>
<artwork><![CDATA[
-- RFC Ed.: remove this section before publication.
]]></artwork>
</figure>
<section title="03-04">
<t>
<list style="symbols">
<t>
Massive rewrite to address just the issues of conformance drift and conformance ambiguity
within a single YANG module.
</t>
<t>
Removed package definitions and service profile definitions. Deferred for future work.
</t>
<t>
Added ietf-yang-conformance YANG module
</t>
<t>
changed term "module base" to "base module"
</t>
<t>
Removed term "YANG feature set"
</t>
<t>
Added terms "import‑by‑revision", "include‑by‑revision", "revision‑identifier"
</t>
<t>
Added :submodule capability
</t>
</list>
</t>
</section>
<section title="02-03">
<t>
<list style="symbols">
<t>
updated routing example
</t>
</list>
</t>
</section>
<section title="01-02">
<t>
<list style="symbols">
<t>
removed 'min‑revision' and 'max‑revision' statements.
</t>
<t>
added mandatory revision-stmt for profiles and require-package
statements.
</t>
<t>
changed package capability to allow the server to
advertise multiple profiles for a YANG package instead of 1.
</t>
<t>
changed required package contents from 0 to 1.
</t>
<t>
removed 'category' statement.
</t>
<t>
add 'require‑parameter' statement to require-capability-stmt.
</t>
<t>
add 'require‑value' statement to require-parameter-stmt.
</t>
<t>
removed 'prefix‑stmt' from YANG package.
</t>
<t>
removed 'header‑stmts' from ABNF so prefix-stmt would be removed.
</t>
<t>
added 'yangconf‑version‑stmt' to ABNF, cloned from RFC 6020
</t>
<t>
added 'namespace‑stmt' to ABNF, cloned from RFC 6020
</t>
<t>
remove conformance profile 'ip' from example, since this is now
achieved by advertising multiple names in the 'profiles' parameter
in the 'package' capability URI.
</t>
</list>
</t>
</section>
<section title="00-01">
<t>
<list style="symbols">
<t>
fixed typos in text and examples
</t>
<t>
updated ietf-routing-pkg example
</t>
<t>
added 'require parameters for capabilities' as an open issue
</t>
</list>
</t>
</section>
</section>
</middle>
<back>
<references title="Normative References">
<reference anchor="RFC2119">
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials="S." surname="Bradner" fullname="S. Bradner">
<organization>Harvard University</organization>
</author>
<date month="March" year="1997"/>
<abstract>
<t>In 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.</t>
</abstract>
</front>
<seriesInfo name="BCP" value="14"/>
<seriesInfo name="RFC" value="2119"/>
<format type="TXT" octets="4723" target="ftp://ftp.isi.edu/in-notes/rfc2119.txt"/>
</reference>
<reference anchor='RFC6241'>
<front>
<title>Network Configuration Protocol (NETCONF)</title>
<author initials='R.' surname='Enns' fullname='R. Enns' role="editor">
<organization/>
</author>
<author initials='M.' surname='Bjorklund' fullname='M. Bjorklund' role="editor">
<organization/>
</author>
<author initials='J.' surname='Schoenwaelder' fullname='J. Schoenwaelder' role="editor">
<organization/>
</author>
<author initials='A.' surname='Bierman' fullname='A. Bierman' role="editor">
<organization/>
</author>
<date year='2011' month='June'/>
</front>
<seriesInfo name='RFC' value='6241'/>
</reference>
<reference anchor="RFC6020">
<front>
<title>YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)</title>
<author initials="M." surname="Bjorklund" fullname="M. Bjorklund">
<organization/>
</author>
<date year="2010" month="October"/>
<abstract>
<t>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]</t>
</abstract>
</front>
<seriesInfo name="RFC" value="6020"/>
<format type="TXT" octets="324178" target="http://www.rfc-editor.org/rfc/rfc6020.txt"/>
</reference>
<!--
<reference anchor='RFC6021'>
<front>
<title>Common YANG Data Types</title>
<author initials='J.' surname='Schoenwaelder' fullname='J. Schoenwaelder'>
<organization/>
</author>
<date year='2010' month='October'/>
</front>
<seriesInfo name='RFC' value='6021'/>
</reference>
-->
<reference anchor="RFC6022">
<front>
<title>YANG Module for NETCONF Monitoring</title>
<author initials="M." surname="Scott" fullname="M. Scott">
<organization/>
</author>
<author initials="M." surname="Bjorklund" fullname="M. Bjorklund">
<organization/>
</author>
<date year="2010" month="October"/>
<abstract>
<t>
This document defines a Network Configuration Protocol (NETCONF) data model to be used to monitor the NETCONF protocol. The monitoring data model includes information about NETCONF datastores, sessions, locks, and statistics. This data facilitates the management of a NETCONF server. This document also defines methods for NETCONF clients to discover data models supported by a NETCONF server and defines a new NETCONF <get-schema> operation to retrieve them. [STANDARDS-TRACK]
</t>
</abstract>
</front>
<seriesInfo name="RFC" value="6022"/>
<format type="TXT" octets="46988" target="http://www.rfc-editor.org/rfc/rfc6022.txt"/>
</reference>
<!--
<reference anchor="RFC6536">
<front>
<title>Network Configuration Protocol (NETCONF) Access Control Model</title>
<author initials="A." surname="Bierman" fullname="A. Bierman">
<organization/></author>
<author initials="M." surname="Bjorklund" fullname="M. Bjorklund">
<organization/></author>
<date year="2012" month="March"/>
<abstract>
<t>The 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]</t></abstract></front>
<seriesInfo name="RFC" value="6536"/>
<format type="TXT" octets="90803" target="http://www.rfc-editor.org/rfc/rfc6536.txt"/>
</reference>
-->
</references>
<references title="Informative References">
<reference anchor='RFC3688'>
<front>
<title>The IETF XML Registry</title>
<author initials='M.' surname='Mealling' fullname='M. Mealling'>
<organization /></author>
<date year='2004' month='January' />
<abstract>
<t>This 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.</t></abstract></front>
<seriesInfo name='BCP' value='81' />
<seriesInfo name='RFC' value='3688' />
<format type='TXT' octets='17325' target='http://www.rfc-editor.org/rfc/rfc3688.txt' />
</reference>
</references>
</back></rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 04:20:40 |