| Network Working Group | A. Bierman |
| Internet-Draft | YumaWorks |
| Intended status: Standards Track | July 6, 2015 |
| Expires: January 7, 2016 |
The YANG Package Statement
draft-bierman-netmod-yang-package-00
This document describes mechanisms for defining a conceptual collection of YANG modules and protocol capability URIs, called a YANG package. Typically, modules with high cohesion that are designed to be used together to manage a service or product feature are included in a YANG package. The purpose of the package is not constrained by this document. For example, a YANG package may describe conformance requirements or simply describe the modules and protocol capabilities implemented in a specific platform.
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 January 7, 2016.
Copyright (c) 2015 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.
The YANG data modelling language [I-D.ietf-netmod-rfc6020bis] is used to manage conceptual hierarchical data in a modular fashion. It is highly extensible, and modules from any organization can be defined to work together. Unfortunately, YANG has no way to describe any functionality or service which is defined in multiple YANG modules. As described in [I-D.bogdanovic-netmod-yang-model-classification], vendor-specific YANG modules are expected to co-exist with standard modules from multiple standards organizations. Operators and developers need a higher layer of data organization than a list of individual YANG modules, in order to more easily manage networks with YANG data models.
There is a need for standard mechanisms to describe a set of YANG modules, grouped together for a specific purpose. The exact purpose of such a mechanism may vary by use-case, and is not restricted by this document.
Often YANG modules are designed such that a framework module (e.g., ietf-interfaces module in [RFC7223]) is designed to be augmented by many other modules. There are no machine-readable statements in YANG to describe which modules are needed for the implementation of a service or product feature.
YANG features are used to specify a set of optional related statements, such as data definition statements. There are no machine-readable statements in YANG to describe which features are needed for the implementation of a service or product feature.
Capability URIs are used in protocols such as NETCONF [RFC6241] and RESTCONF [I-D.ietf-netconf-restconf] to identify an optional protocol feature. such as the ":confirmed‑commit" capability in NETCONF. There are no machine-readable statements in YANG to describe which protocol capabilities are needed for the implementation of a service or product feature.
Constrained devices may have limited host and network resources. Retrieval of a large list of YANG modules, or sending of a large NETCONF <hello> message could significantly impact network performance. It is important to minimize all network management traffic in this type of environment. Advertisement of YANG packages instead of a complete list of YANG modules (with revision, features, and deviation parameters) could save a significant amount of host and network resources.
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].
The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: q
The following terms are used within this document:
The solution in this document attempts to achieve the following objectives:
A YANG package is a conceptual set of YANG modules describing some service or product feature. Typically, modules with high cohesion that are designed to be used together to manage a service or device feature are included in a YANG package. The purpose of the package is not constrained by this document. A YANG package may describe conformance requirements or simply describe the modules implemented in a specific platform.
YANG packages are specified using a text file similar to YANG modules, however they are separate from YANG modules, since the purpose of a YANG package is to describe a set of YANG modules. Unlike YANG modules, YANG package definitions cannot represent YANG data nodes that would appear in a protocol message.
A YANG package is identified with a module-qualified name similar to a YANG module. YANG modules and YANG packages share the same YANG identifier namespace, so the same naming conventions apply to YANG packages as YANG modules.
A YANG package file consists of UTF-8 characters. The syntax is exactly the same as for YANG modules. Several YANG statements are "imported" from the YANG ABNF, and some new statements are defined. Specifically, YANG package syntax is the same as [I-D.ietf-netmod-rfc6020bis], sections 6, 6.1, 6.2, and 6.3.
At least one revision statement MUST be present in a YANG package file. A new revision MUST be added each time the YANG package file is published. This requirement is more strict than RFC 6020 to ensure that package revisions can be properly identified without ambiguity.
A YANG package has a lifecycle status, based on the YANG "status" statement.
In this example, a package named "example‑routing‑pkg" is defined to describe the routing modules supported by a particular vendor name Example, Inc.
package example-routing-pkg {
organization "Example, Inc.";
contact "support at example.com";
description
"This package describes the routing modules required to
support Example, Inc. base routing service.";
revision 2015-07-01 {
description "First revision";
reference "TBD";
}
imports-module ietf-inet-types {
uses-revision 2013-07-15;
}
imports-module ietf-yang-types {
uses-revision 2013-07-15;
}
uses-module ietf-routing {
uses-revision 2015-05-25;
uses-feature multiple-ribs;
uses-feature router-id;
}
uses-module ietf-interfaces {
uses-revision 2014-05-08;
uses-feature pre-provisioning;
}
uses-module ietf-ipv4-unicast-routing {
uses-revision 2014-05-25;
}
uses-module ietf-ipv6-unicast-routing {
uses-revision 2014-05-25;
}
uses-module example-routing-extensions {
uses-revision 2015-06-24;
}
}
In this example, a package named "example‑routing‑bgp‑pkg" is defined to describe the BGP modules supported by a particular vendor name Example, Inc.
package example-routing-bgp-pkg {
organization "Example, Inc.";
contact "support at example.com";
description
"This package describes the routing modules required to
support Example, Inc. BGP routing service.";
revision 2015-07-01 {
description "First revision";
reference "TBD";
}
uses-package example-routing-pkg {
uses-revision 2015-07-01;
}
uses-module example-routing-bgp {
uses-revision 2014-04-17;
}
}
In this example, the YANG package described the NETCONF server features that the Example, Inc NMS platform requires to function.
package example-netconf-pkg {
organization "Example, Inc.";
contact "support at example.com";
description
"This package describes the NETCONF functionality required to
support Example, Inc. NMS platforms.";
revision 2015-07-01 {
description "First revision";
}
imports-module ietf-inet-types {
uses-revision 2013-07-15;
}
imports-module ietf-yang-types {
uses-revision 2013-07-15;
}
uses-module ietf-netconf {
uses-revision 2011-06-01;
uses-feature candidate;
uses-feature confirmed-commit;
}
uses-capability
"urn:ietf:params:netconf:capability:notification:1.0" {
description
"Notification delivery support is required.";
reference "RFC 5277, section 3.1";
}
uses-capability
"urn:ietf:params:netconf:capability:interleave:1.0" {
description
"Interleave of commands is required while notification
delivery is active .";
reference "RFC 5277, section 6";
}
uses-module ietf-netconf-with-defaults {
uses-revision 2011-06-01;
description
"Support for <with-defaults> RPC parameter is required.";
reference "RFC 6243, section 5";
}
uses-module ietf-netconf-acm {
uses-revision 2012-02-22;
description
"Base module implementation of NACM is required.";
reference "RFC 6536, section 3.5.2";
}
uses-module ietf-netconf-monitoring {
uses-revision 2010-10-04;
description
"Implementation of NETCONF monitoring is required.";
reference "RFC 6022, section 5";
}
uses-module ietf-netconf-notifications {
uses-revision 2012-02-06;
reference "RFC 6470, section 2.2";
}
}
The "package" statement defines the YANG package's name, and contains all YANG package statements. The "package" statement's argument is the name of the YANG package, followed by a block of substatements that hold detailed package information. The package name follows the rules for identifiers in RFC 6020bis, section 6.2.
A YANG package name is defined in the same conceptual namespace as YANG module names. The same rules for selecting non-conflicting names apply as defined in RFC 6020bis, section 7.1.
If standard YANG packages are defined by the IETF, then an IANA registry for YANG package names will be needed, similar to mechanism described in RFC 6020bis, section 15.
A YANG package includes a status statement to indicate the package lifecycle status. The YANG "status" statement is used for this purpose. The default status is "current". A current YANG package SHOULD NOT use any package, module, feature, or capability that is deprecated. A current YANG package MUST NOT use any package, module, feature, or capability that is obsolete.
Only current YANG packages SHOULD be used in a server. A deprecated package MAY be used with the understanding that support for the package may be removed at any time in the future. An obsolete package MUST NOT be used.
| Substatement | Reference | Cardinality |
|---|---|---|
| contact | RFC 6020bis, 7.1.8 | 0..1 |
| description | RFC 6020bis, 7.19.3 | 0..1 |
| imports-module | 2.5 | 0..n |
| organization | RFC 6020bis, 7.1.7 | 0..1 |
| reference | RFC 6020bis, 7.19.4 | 0..1 |
| revision | RFC 6020bis, 7.1.9 | 1..n |
| status | RFC 6020bis, 7.19.2 | 0..1 |
| uses-capability | 2.8 | 0..n |
| uses-module | 2.6 | 0..n |
| uses-package | 2.3 | 0..n |
| yang-package-version | 2.2 | 0..1 |
The optional "yang‑package‑version" statement specifies which version of the YANG Package specification language was used in developing the module. The statement's argument is a string. If present, it MUST contain the value "1", which is the current YANG Package language version and the default value.
Handling of the "yang‑package‑version" statement for versions other than "1" (the version defined here) is out of scope for this specification. Any document that defines a higher version will need to define the backward compatibility of such a higher version.
The "uses‑package" statement is used to indicate that support for an another YANG package. It takes as an argument the name of the YANG package to use, followed by a block of substatements that hold detailed server support requirements.
A "uses‑package" statement MUST NOT specify any YANG package name that would create a dependency loop, such that the package containing the "uses‑package" statement would be required to use itself.
The "uses‑revision" sub-statement is required, and identifies the revision of the package used.
| Substatement | Reference | Cardinality |
|---|---|---|
| description | RFC 6020bis, 7.19.3 | 0..1 |
| reference | RFC 6020bis, 7.19.4 | 0..1 |
| uses-revision | 2.4 | 1 |
The "uses‑revision" statement is a mandatory statement used to identify the revision date for the parent package or module statement uses in the YANG package. It takes as argument a date string in the form "YYYY‑MM‑DD" where "YYYY" is the year, "MM" is the month, and "DD" is the day. The "uses‑revision" statement has no substatements.
The "imports‑module" statement is used to indicate that the macro-data from the specified module is used. It takes as an argument the name of the module to import, followed by a block of substatements that describe detailed module import usage information.
The "uses‑revision" sub-statement is required, and identifies at least one revision of the module imported. YANG permits the macro-data from more than one revision of a module to be used within a server (i.e., import using a revision-date), so multiple "uses‑revision" statements are permitted.
| Substatement | Reference | Cardinality |
|---|---|---|
| description | RFC 6020bis, 7.19.3 | 0..1 |
| reference | RFC 6020bis, 7.19.4 | 0..1 |
| uses-revision | 2.4 | 1..n |
The "uses‑module" statement is used to indicate support for the protocol accessible objects in the specified base module. It takes as an argument the name of the module to use, followed by a block of substatements that describe detailed module usage information.
The "uses‑revision" sub-statement is required, and identifies the revision of the module used.
| Substatement | Reference | Cardinality |
|---|---|---|
| description | RFC 6020bis, 7.19.3 | 0..1 |
| reference | RFC 6020bis, 7.19.4 | 0..1 |
| uses-revision | 2.4 | 1 |
| uses-feature | 2.7 | 0..n |
The "uses‑feature" statement is used to indicate that the specified YANG feature is used in the YANG package. It takes as argument the name of the YANG feature that is required, and is followed by a block of substatements that describe the YANG feature usage within the YANG package.
| Substatement | Reference | Cardinality |
|---|---|---|
| description | RFC 6020bis, 7.19.3 | 0..1 |
| reference | RFC 6020bis, 7.19.4 | 0..1 |
The "uses‑capability" statement is used to indicate that the specified protocol capability URI is used in the YANG package. It takes as argument a URI string identifying the protocol capability that is used, and is followed by a block of substatements that describe the protocol capability usage within the YANG package.
| Substatement | Reference | Cardinality |
|---|---|---|
| description | RFC 6020bis, 7.19.3 | 0..1 |
| reference | RFC 6020bis, 7.19.4 | 0..1 |
| uses-parameter | 2.9 | 0..n |
The "uses‑parameter" statement is used to indicate that the specified URI parameter for the parent "uses‑capability" statement is used in the YANG package.
It takes as argument a string identifying the parameter name that is used, and MAY be followed by a block of substatements that describe the protocol parameter usage within the YANG package.
If this parameter appears more than once within a "uses‑capability" statement then all the specified parameters are used in the YANG package.
| Substatement | Reference | Cardinality |
|---|---|---|
| description | RFC 6020bis, 7.19.3 | 0..1 |
| reference | RFC 6020bis, 7.19.4 | 0..1 |
| uses-value | 2.10 | 0..n |
Usage Example:
package example-url {
description
"A package for requiring that the scheme parameter
be present in the :url capability. Any value is
allowed.";
uses-capability
"urn:ietf:params:netconf:capability:url:1.0" {
description
"Support for the :url capability is required.";
reference "RFC 6241, section 8.8";
uses-parameter scheme {
description
"Support for the scheme parameter is required.";
reference "RFC 6241, section 8.8.3";
}
}
}
The "uses‑value" statement is used to indicate a parameter value used in the parent "uses‑capability" statement.
It takes as argument a string identifying a parameter value that is used, and MAY be followed by a block of substatements that describe the protocol parameter value usage within the YANG package.
| Substatement | Reference | Cardinality |
|---|---|---|
| description | RFC 6020bis, 7.19.3 | 0..1 |
| reference | RFC 6020bis, 7.19.4 | 0..1 |
Usage Example
package example-url-ftp {
description
"A profile for requiring FTP support for the 'url'
capability.";
uses-capability
"urn:ietf:params:netconf:capability:url:1.0" {
description
"Support for the :url capability is required.";
reference "RFC 6241, section 8.8";
uses-parameter scheme {
description
"Support for the 'scheme' parameter is required.";
reference "RFC 6241, section 8.8.3";
uses-value ftp {
description
"Support for 'ftp' transfer is required.";
}
}
}
}
If a YANG package is modified then a new "revision" statement MUST be added identifying the new revision date. There are no other YANG package update restrictions.
The YANG Package Identifier is a URI, used to identify a YANG package within a protocol capability URI. This document does not specify any protocol procedures for advertisement of a YANG Package Identifier.
The YANG Package Identifier MUST match the rule for a "pkg‑uri":
pkg-uri = yang-pkg-uri parameter-list parameter-list = "?" pkg-parameter "&" rev-parameter pkg-parameter = "name=" package-name rev-parameter = "rev=" revision-date
Where:
Both parameters MUST be present in the YANG Package Identifier.
Example: (wrapped for display purposes only)
urn:ietf:params:xml:ns:yang:pkg?name=example-routing-pkg
&rev=2015-07-01
The following ABNF grammar is defined in accordance with [RFC5234] and [RFC7405].
Within the ABNF grammar, unordered statements are marked with comments.
This grammar assumes that the scanner replaces YANG comments with a single space character.
<CODE BEGINS> file "yang-package.abnf"
package-stmt = optsep package-keyword sep identifier-arg-str
optsep
"{" stmtsep
[yang-package-version-stmt]
meta-stmts
[status-stmt stmtsep]
req-revision-stmts
package-body-stmts
"}" optsep
yang-package-version-stmt = yang-package-version-keyword sep
yang-package-version-arg-str
optsep stmtend
yang-package-version-arg-str = < a string that matches the rule
yang-package-version-arg >
yang-package-version-arg = "1"
req-revision-stmts = 1*(revision-stmt stmtsep)
uses-revision-stmt = revision-keyword sep date-arg-str stmtend
package-body-stmts = *((uses-package-stmt /
uses-module-stmt /
imports-module-stmt /
uses-capability-stmt) stmtsep)
uses-package-stmt = uses-package-keyword sep
identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
uses-revision-stmt stmtsep
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}")
uses-module-stmt = uses-module-keyword sep
identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
uses-revision-stmt stmtsep
[description-stmt stmtsep]
[reference-stmt stmtsep]
*(uses-feature-stmt stmtsep)
"}")
uses-feature-stmt = uses-feature-keyword sep
identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}")
imports-module-stmt = imports-module-keyword sep
identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
uses-revision-stmt stmtsep
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}")
uses-capability-stmt = uses-capability-keyword sep
uri-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[description-stmt stmtsep]
[reference-stmt stmtsep]
*(uses-parameter-stmt stmtsep)
"}")
uses-parameter-stmt = uses-parameter-keyword sep
identifier-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[description-stmt stmtsep]
[reference-stmt stmtsep]
*(uses-value-stmt stmtsep)
"}")
uses-value-stmt = uses-value-keyword sep
value-arg-str optsep
(";" /
"{" stmtsep
;; these stmts can appear in any order
[description-stmt stmtsep]
[reference-stmt stmtsep]
"}")
value-arg-str = <string containing parameter value>
;; new keywords
imports-module-keyword = 'imports-module'
package-keyword = 'package'
uses-revision-keyword = 'uses-revision'
uses-capability-keyword = 'uses-capability'
uses-feature-keyword = 'uses-feature'
uses-module-keyword = 'uses-module'
uses-parameter-keyword = 'uses-parameter'
uses-package-keyword = 'uses-package'
uses-value-keyword = 'uses-value'
yang-package-version-keyword = 'yang-package-version'
;; the following rules are defined in RFC 6020bis, section 12
description-stmt
identifier-arg-str
meta-stmts
opt-set
reference-stmt
revision-keyword
revision-stmt
status-stmt
stmtsep
uri-str
<CODE ENDS>
TODO: The YANG Package Identifier URI needs to be registered
No security threats are introduced by this document. This document describes mechanisms for specifying collections of YANG modules and protocol capabilities. It does not describe any protocol interactions or conceptual interface, such as a YANG module.
However, if the YANG package list supported by a device is advertised by a server, it may help an attacker identify the server capabilities and server implementations with known bugs. Server vulnerabilities may be specific to particular modules, module revisions, or module features. This information may be included in a YANG package instance document.
| [I-D.ietf-netmod-rfc6020bis] | Bjorklund, M., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", Internet-Draft draft-ietf-netmod-rfc6020bis-06, July 2015. |
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |
| [RFC5234] | Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008. |
| [RFC7405] | Kyzivat, P., "Case-Sensitive String Support in ABNF", RFC 7405, December 2014. |
| [I-D.bogdanovic-netmod-yang-model-classification] | Bogdanovic, D., Claise, B. and C. Moberg, "YANG model classification", Internet-Draft draft-bogdanovic-netmod-yang-model-classification-03, June 2015. |
| [I-D.ietf-netconf-restconf] | Bierman, A., Bjorklund, M. and K. Watsen, "RESTCONF Protocol", Internet-Draft draft-ietf-netconf-restconf-06, June 2015. |
| [RFC6241] | Enns, R., Bjorklund, M., Schoenwaelder, J. and A. Bierman, "Network Configuration Protocol (NETCONF)", RFC 6241, June 2011. |
| [RFC7223] | Bjorklund, M., "A YANG Data Model for Interface Management", RFC 7223, May 2014. |
-- RFC Ed.: remove this section before publication.