Internet DRAFT - draft-bierman-netmod-yang-conformance
draft-bierman-netmod-yang-conformance
Network Working Group A. Bierman
Internet-Draft YumaWorks
Intended status: Standards Track September 24, 2014
Expires: March 28, 2015
YANG Conformance Specification
draft-bierman-netmod-yang-conformance-04
Abstract
This document describes conformance specification and advertisement
mechanisms for NETCONF servers implementing YANG data model modules.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on March 28, 2015.
Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Bierman Expires March 28, 2015 [Page 1]
Internet-Draft YANG Conformance September 2014
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.2. YANG . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.3. Terms . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1.4. Tree Diagrams . . . . . . . . . . . . . . . . . . . . 6
2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.1. Server Implementation Capabilities . . . . . . . . . . . . 7
3. Problems With YANG Conformance Mechanisms . . . . . . . . . . 8
3.1. Incomplete Dependency Tree: Conformance Drift . . . . . . 8
3.1.1. Typedef Drift . . . . . . . . . . . . . . . . . . . . 8
3.1.2. Grouping Drift . . . . . . . . . . . . . . . . . . . . 9
3.1.3. Conformance Drift Example . . . . . . . . . . . . . . 9
3.2. Complete Dependency Tree: Multiple Concurrent Revisions . 13
3.2.1. Conformance Ambiguity Example . . . . . . . . . . . . 14
3.2.2. Augmenting External Data Nodes . . . . . . . . . . . . 14
3.2.3. Identityref Value Sets . . . . . . . . . . . . . . . . 14
3.2.4. Leafref Value Sets . . . . . . . . . . . . . . . . . . 15
3.3. Module Capability Advertisement Issues . . . . . . . . . . 15
4. YANG Conformance Guidelines . . . . . . . . . . . . . . . . . 16
4.1. Conformance is Based on the Module Set, not One Module . . 16
4.2. Import has no Conformance Semantics . . . . . . . . . . . 16
4.3. Only the Most Recent Revision Allowed . . . . . . . . . . 16
4.3.1. YANG Module Capability URIs . . . . . . . . . . . . . 17
4.4. Import and Include By Revision Do Not Really Help . . . . 17
4.5. Limit Protocol Accessible Objects in the Base Module . . . 18
5. YANG Submodule Capability . . . . . . . . . . . . . . . . . . 19
5.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.1.1. :submodule Capability Example . . . . . . . . . . . . 19
5.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 19
5.3. Capability Identifier . . . . . . . . . . . . . . . . . . 19
5.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 20
5.5. Modifications to Existing Operations . . . . . . . . . . . 20
5.6. Interactions with Other Capabilities . . . . . . . . . . . 20
6. YANG Conformance Module . . . . . . . . . . . . . . . . . . . 21
6.1. Identityref Value Set Discovery . . . . . . . . . . . . . 21
6.2. Leafref Value Set Discovery . . . . . . . . . . . . . . . 21
6.3. Schema Conformance Discovery . . . . . . . . . . . . . . . 22
6.4. YANG module . . . . . . . . . . . . . . . . . . . . . . . 22
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28
7.1. YANG Module Registry . . . . . . . . . . . . . . . . . . . 28
8. Security Considerations . . . . . . . . . . . . . . . . . . . 29
9. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 30
9.1. YANG Module Advertisement . . . . . . . . . . . . . . . . 30
9.1.1. Capability-ID vs. Module URI List . . . . . . . . . . 30
9.1.2. Full vs. Partial <capability> List . . . . . . . . . . 30
Bierman Expires March 28, 2015 [Page 2]
Internet-Draft YANG Conformance September 2014
9.2. YANG 1.1 Support . . . . . . . . . . . . . . . . . . . . . 31
9.3. Protocol Independence . . . . . . . . . . . . . . . . . . 31
10. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 32
10.1. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 32
10.2. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 32
10.3. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 32
10.4. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 33
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34
11.1. Normative References . . . . . . . . . . . . . . . . . . . 34
11.2. Informative References . . . . . . . . . . . . . . . . . . 34
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 35
Bierman Expires March 28, 2015 [Page 3]
Internet-Draft YANG Conformance September 2014
1. Introduction
There is a need for standard mechanisms to allow YANG [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.
There is also a need for standard mechanisms to allow NETCONF
[RFC6241] servers to precisely advertise the conformance level of
each YANG module it supports.
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.
1.1. Terminology
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, [RFC2119].
1.1.1. NETCONF
The following terms are defined in [RFC6241]:
o capability
o client
o datastore
o protocol operation
o server
1.1.2. YANG
The following terms are defined in [RFC6020]:
o data node
o extension
o feature
Bierman Expires March 28, 2015 [Page 4]
Internet-Draft YANG Conformance September 2014
o grouping
o identity
o module
o notification
o submodule
o typedef
1.1.3. Terms
The following terms are used within this document:
o 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.
o 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.
o 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.
o 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.
o object: a conceptual data structure represented by a YANG data,
rpc, or notification statement.
o 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.
o 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
Bierman Expires March 28, 2015 [Page 5]
Internet-Draft YANG Conformance September 2014
conceptually applied to the schema tree as well.
o YANG dependency tree: A conceptual tree containing the set of all
revision identifiers for all modules and submodules in the schema
tree.
1.1.4. Tree Diagrams
A simplified graphical representation of the data model is used in
this document. The meaning of the symbols in these diagrams is as
follows:
o Brackets "[" and "]" enclose list keys.
o Abbreviations before data node names: "rw" means configuration
data (read-write) and "ro" state data (read-only).
o Symbols after data node names: "?" means an optional node, "!"
means a presence container, and "*" denotes a list and leaf-list.
o Parentheses enclose choice and case nodes, and case nodes are also
marked with a colon (":").
o Ellipsis ("...") stands for contents of subtrees that are not
shown.
Bierman Expires March 28, 2015 [Page 6]
Internet-Draft YANG Conformance September 2014
2. Overview
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.
o Client and Server Implementation Requirements
o Actual Server Implementation Capabilities
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.
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.
2.1. Server Implementation Capabilities
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.
For improved interoperability, the server must identify its
conformance level for each module, and identify and deviations from
the advertised conformance level.
Bierman Expires March 28, 2015 [Page 7]
Internet-Draft YANG Conformance September 2014
3. Problems With YANG Conformance Mechanisms
This section describes some perceived deficiencies with the current
YANG data model conformance specification and NETCONF server
conformance advertisement mechanisms.
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.
The rest of this section discusses the advantages and disadvantages
of the two solution paths available in YANG to identify conformance
requirements.
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.
Option 2: use import-by-revision and include-by-revision everywhere
so the YANG dependency tree is fully specified.
3.1. Incomplete Dependency Tree: Conformance Drift
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.
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.
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.
3.1.1. Typedef Drift
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.
Bierman Expires March 28, 2015 [Page 8]
Internet-Draft YANG Conformance September 2014
There are several ways this is allowed under the conditions described
in section 10 of [RFC6020]:
o an "enumeration" type can add new "enum" statements
o a "bits" type can add new "bit" statements
o a "range", "length", or "pattern" statement may expand the allowed
value space
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.
3.1.2. Grouping Drift
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 [RFC6020]:
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.
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.
It is therefore unsafe for a server to support multiple revisions of
a grouping, in a generic manner.
3.1.3. Conformance Drift Example
Consider the "first release" where the module set advertised by the
server consists of 2 modules:
Bierman Expires March 28, 2015 [Page 9]
Internet-Draft YANG Conformance September 2014
- 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;
}
}
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.
Bierman Expires March 28, 2015 [Page 10]
Internet-Draft YANG Conformance September 2014
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".
Bierman Expires March 28, 2015 [Page 11]
Internet-Draft YANG Conformance September 2014
- 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;
}
}
Bierman Expires March 28, 2015 [Page 12]
Internet-Draft YANG Conformance September 2014
There are unadvertised changes in module "B":
o "knob1" leaf range expanded and default added
o "knobB" leaf added to the "knobs" container
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.
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.
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.
3.2. Complete Dependency Tree: Multiple Concurrent Revisions
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.
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.
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.
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".
Bierman Expires March 28, 2015 [Page 13]
Internet-Draft YANG Conformance September 2014
3.2.1. Conformance Ambiguity Example
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:
- module A, revision 2014-01-01
- module A, revision 2014-02-01
- module B, revision 2014-01-02
- module C, revision 2014-02-02
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.
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.
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.
3.2.2. Augmenting External Data Nodes
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.
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.
3.2.3. Identityref Value Sets
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.
It is not possible for a client to determine the supported identity
set at all. In addition, individual identityref leafs may support
Bierman Expires March 28, 2015 [Page 14]
Internet-Draft YANG Conformance September 2014
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.
YANG conformance requirements for "identityref" leafs are unclear and
need to be clarified. Discovery of agent capabilities of actual
supported identities is needed.
3.2.4. Leafref Value Sets
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.
3.3. Module Capability Advertisement Issues
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.
Bierman Expires March 28, 2015 [Page 15]
Internet-Draft YANG Conformance September 2014
4. YANG Conformance Guidelines
Conformance for the "ietf-yang-conformance" module capability
requires implementation of these conformance guidelines.
4.1. Conformance is Based on the Module Set, not One Module
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.
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.
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.
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.
4.2. Import has no Conformance Semantics
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.
4.3. Only the Most Recent Revision Allowed
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.
If any of the following statements in the most recent advertised
revision of the base module are not supported by the server, then a
Bierman Expires March 28, 2015 [Page 16]
Internet-Draft YANG Conformance September 2014
YANG module containing the appropriate "deviation" statements MUST be
advertised for that module.
o augment-stmt
o data-def-stmt
o notification-stmt
o rpc-stmt
If a shared module needs to be updated, then the conformance is
implicitly updated for the modules that depend on the changes.
4.3.1. YANG Module Capability URIs
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.
The server MUST advertise the most recent revision of all YANG
modules that it supports, including modules that do not contain any
data definitions.
If the server uses any modules with submodules, then the "submodule"
capability in Section 5 SHOULD be advertised for each submodule used.
Only one revision of each submodule SHOULD be advertised.
4.4. Import and Include By Revision Do Not Really Help
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.
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.
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
Bierman Expires March 28, 2015 [Page 17]
Internet-Draft YANG Conformance September 2014
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.
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.
4.5. Limit Protocol Accessible Objects in the Base Module
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.
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.
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.
Bierman Expires March 28, 2015 [Page 18]
Internet-Draft YANG Conformance September 2014
5. YANG Submodule Capability
5.1. Overview
A new capability called "submodule" is defined to identify the
specific revisions of all submodules the server is using.
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.
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.
5.1.1. :submodule Capability Example
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.
<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>
5.2. Dependencies
The :submodule capability is not dependent on any other capabilities.
5.3. Capability Identifier
The :submodule capability is identified by the following capability
string:
urn:ietf:params:netconf:capability:submodule:1.0
Bierman Expires March 28, 2015 [Page 19]
Internet-Draft YANG Conformance September 2014
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.
5.4. New Operations
The :submodule capability does not introduce any new protocol
operations.
5.5. Modifications to Existing Operations
The :submodule capability does not modify any existing protocol
operations.
5.6. Interactions with Other Capabilities
The :submodule capability does not interact with any other
capabilities.
Bierman Expires March 28, 2015 [Page 20]
Internet-Draft YANG Conformance September 2014
6. YANG Conformance Module
The "ietf-yang-conformance" module in Section 6.4 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 [RFC6022].
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
6.1. Identityref Value Set Discovery
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.
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.
6.2. Leafref Value Set Discovery
A server is not required to support all existing potential instances
for a leaf or leaf-list using the "leafref" data type. The entire
Bierman Expires March 28, 2015 [Page 21]
Internet-Draft YANG Conformance September 2014
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.
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.
6.3. Schema Conformance Discovery
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.
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.
6.4. YANG module
RFC Ed.: update the date below with the date of RFC publication and
remove this note.
<CODE BEGINS> file "ietf-yang-conformance@2014-09-24.yang"
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
Bierman Expires March 28, 2015 [Page 22]
Internet-Draft YANG Conformance September 2014
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
Bierman Expires March 28, 2015 [Page 23]
Internet-Draft YANG Conformance September 2014
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>
Bierman Expires March 28, 2015 [Page 24]
Internet-Draft YANG Conformance September 2014
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
Bierman Expires March 28, 2015 [Page 25]
Internet-Draft YANG Conformance September 2014
"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
Bierman Expires March 28, 2015 [Page 26]
Internet-Draft YANG Conformance September 2014
- 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.";
}
}
}
<CODE ENDS>
Bierman Expires March 28, 2015 [Page 27]
Internet-Draft YANG Conformance September 2014
7. IANA Considerations
7.1. YANG Module Registry
This document registers one URI in the IETF XML registry [RFC3688].
Following the format in RFC 3688, the following registration is
requested to be made.
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.
This document registers one YANG module in the YANG Module Names
registry [RFC6020].
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
Bierman Expires March 28, 2015 [Page 28]
Internet-Draft YANG Conformance September 2014
8. Security Considerations
TBD.
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.
Bierman Expires March 28, 2015 [Page 29]
Internet-Draft YANG Conformance September 2014
9. Open Issues
9.1. YANG Module Advertisement
9.1.1. Capability-ID vs. Module URI List
Left out of this release:
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.";
}
}
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.
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.
9.1.2. Full vs. Partial <capability> List
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.
Bierman Expires March 28, 2015 [Page 30]
Internet-Draft YANG Conformance September 2014
9.2. YANG 1.1 Support
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.
9.3. Protocol Independence
o Should this document be written so it is specific to the NETCONF
and RESTCONF protocols?
o 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?
Bierman Expires March 28, 2015 [Page 31]
Internet-Draft YANG Conformance September 2014
10. Change Log
-- RFC Ed.: remove this section before publication.
10.1. 03-04
o Massive rewrite to address just the issues of conformance drift
and conformance ambiguity within a single YANG module.
o Removed package definitions and service profile definitions.
Deferred for future work.
o Added ietf-yang-conformance YANG module
o changed term "module base" to "base module"
o Removed term "YANG feature set"
o Added terms "import-by-revision", "include-by-revision",
"revision-identifier"
o Added :submodule capability
10.2. 02-03
o updated routing example
10.3. 01-02
o removed 'min-revision' and 'max-revision' statements.
o added mandatory revision-stmt for profiles and require-package
statements.
o changed package capability to allow the server to advertise
multiple profiles for a YANG package instead of 1.
o changed required package contents from 0 to 1.
o removed 'category' statement.
o add 'require-parameter' statement to require-capability-stmt.
o add 'require-value' statement to require-parameter-stmt.
o removed 'prefix-stmt' from YANG package.
Bierman Expires March 28, 2015 [Page 32]
Internet-Draft YANG Conformance September 2014
o removed 'header-stmts' from ABNF so prefix-stmt would be removed.
o added 'yangconf-version-stmt' to ABNF, cloned from RFC 6020
o added 'namespace-stmt' to ABNF, cloned from RFC 6020
o remove conformance profile 'ip' from example, since this is now
achieved by advertising multiple names in the 'profiles' parameter
in the 'package' capability URI.
10.4. 00-01
o fixed typos in text and examples
o updated ietf-routing-pkg example
o added 'require parameters for capabilities' as an open issue
Bierman Expires March 28, 2015 [Page 33]
Internet-Draft YANG Conformance September 2014
11. References
11.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the
Network Configuration Protocol (NETCONF)", RFC 6020,
October 2010.
[RFC6022] Scott, M. and M. Bjorklund, "YANG Module for NETCONF
Monitoring", RFC 6022, October 2010.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, June 2011.
11.2. Informative References
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
January 2004.
Bierman Expires March 28, 2015 [Page 34]
Internet-Draft YANG Conformance September 2014
Author's Address
Andy Bierman
YumaWorks
Email: andy@yumaworks.com
Bierman Expires March 28, 2015 [Page 35]
