summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc7895.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc7895.txt')
-rw-r--r--doc/rfc/rfc7895.txt731
1 files changed, 731 insertions, 0 deletions
diff --git a/doc/rfc/rfc7895.txt b/doc/rfc/rfc7895.txt
new file mode 100644
index 0000000..9ff5eb9
--- /dev/null
+++ b/doc/rfc/rfc7895.txt
@@ -0,0 +1,731 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) A. Bierman
+Request for Comments: 7895 YumaWorks
+Category: Standards Track M. Bjorklund
+ISSN: 2070-1721 Tail-f Systems
+ K. Watsen
+ Juniper Networks
+ June 2016
+
+
+ YANG Module Library
+
+Abstract
+
+ This document describes a YANG library that provides information
+ about all the YANG modules used by a network management server (e.g.,
+ a Network Configuration Protocol (NETCONF) server). Simple caching
+ mechanisms are provided to allow clients to minimize retrieval of
+ this information.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 7841.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc7895.
+
+Copyright Notice
+
+ Copyright (c) 2016 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, et al. Standards Track [Page 1]
+
+RFC 7895 YANG Library June 2016
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
+ 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3
+ 2. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 4
+ 2.1. modules-state . . . . . . . . . . . . . . . . . . . . . . 4
+ 2.1.1. modules-state/module-set-id . . . . . . . . . . . . . 4
+ 2.1.2. modules-state/module . . . . . . . . . . . . . . . . 5
+ 2.2. YANG Library Module . . . . . . . . . . . . . . . . . . . 5
+ 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
+ 3.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 11
+ 4. Security Considerations . . . . . . . . . . . . . . . . . . . 11
+ 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
+ 5.1. Normative References . . . . . . . . . . . . . . . . . . 12
+ 5.2. Informative References . . . . . . . . . . . . . . . . . 12
+ Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 13
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13
+
+1. Introduction
+
+ There is a need for standard mechanisms to identify the YANG modules
+ and submodules that are in use by a server that implements YANG data
+ models. If a large number of YANG modules are utilized by the
+ server, then the YANG library contents needed can be relatively
+ large. This information changes very infrequently, so it is
+ important that clients be able to cache the YANG library contents and
+ easily identify whether their cache is out of date.
+
+ YANG library information can be different on every server and can
+ change at runtime or across a server reboot.
+
+ If the server implements multiple protocols to access the YANG-
+ defined data, each such protocol has its own conceptual instantiation
+ of the YANG library.
+
+ The following information is needed by a client application (for each
+ YANG module in the library) to fully utilize the YANG data modeling
+ language:
+
+ o name: The name of the YANG module.
+
+ o revision: Each YANG module and submodule within the library has a
+ revision. This is derived from the most recent revision statement
+ within the module or submodule. If no such revision statement
+ exists, the module's or submodule's revision is the zero-length
+ string.
+
+
+
+
+Bierman, et al. Standards Track [Page 2]
+
+RFC 7895 YANG Library June 2016
+
+
+ o submodule list: The name and revision of each submodule used by
+ the module MUST be identified.
+
+ o feature list: The name of each YANG feature supported by the
+ server MUST be identified.
+
+ o deviation list: The name of each YANG module used for deviation
+ statements MUST be identified.
+
+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].
+
+ The following terms are defined in [RFC6241]:
+
+ o client
+
+ o server
+
+ The following terms are defined in [YANG1.1]:
+
+ o module
+
+ o submodule
+
+ The following terms are used within this document:
+
+ o YANG library: A collection of YANG modules and submodules used by
+ a server.
+
+1.2. 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.
+
+
+
+
+
+Bierman, et al. Standards Track [Page 3]
+
+RFC 7895 YANG Library June 2016
+
+
+ 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.
+
+2. YANG Module Library
+
+ The "ietf-yang-library" module provides information about the YANG
+ library used by a server. This module is defined using YANG version
+ 1, but it supports the description of YANG modules written in any
+ revision of YANG.
+
+ Following is the YANG Tree Diagram for the "ietf-yang-library"
+ module:
+
+ +--ro modules-state
+ +--ro module-set-id string
+ +--ro module* [name revision]
+ +--ro name yang:yang-identifier
+ +--ro revision union
+ +--ro schema? inet:uri
+ +--ro namespace inet:uri
+ +--ro feature* yang:yang-identifier
+ +--ro deviation* [name revision]
+ | +--ro name yang:yang-identifier
+ | +--ro revision union
+ +--ro conformance-type enumeration
+ +--ro submodule* [name revision]
+ +--ro name yang:yang-identifier
+ +--ro revision union
+ +--ro schema? inet:uri
+
+2.1. modules-state
+
+ This mandatory container holds the identifiers for the YANG data
+ model modules supported by the server.
+
+2.1.1. modules-state/module-set-id
+
+ This mandatory leaf contains a unique implementation-specific
+ identifier representing the current set of modules and submodules on
+ a specific server. The value of this leaf MUST change whenever the
+ set of modules and submodules in the YANG library changes. There is
+ no requirement that the same set always results in the same "module-
+ set-id" value.
+
+
+
+
+
+Bierman, et al. Standards Track [Page 4]
+
+RFC 7895 YANG Library June 2016
+
+
+ This leaf allows a client to fetch the module list once, cache it,
+ and only refetch it if the value of this leaf has been changed.
+
+ If the value of this leaf changes, the server also generates a
+ "yang-library-change" notification, with the new value of
+ "module-set-id".
+
+ Note that for a NETCONF server that implements YANG 1.1 [YANG1.1], a
+ change of the "module-set-id" value results in a new value for the
+ :yang-library capability defined in [YANG1.1]. Thus, if such a
+ server implements NETCONF notifications [RFC5277], and the
+ notification "netconf-capability-change" [RFC6470], a
+ "netconf-capability-change" notification is generated whenever the
+ "module-set-id" changes.
+
+2.1.2. modules-state/module
+
+ This mandatory list contains one entry for each YANG data model
+ module supported by the server. There MUST be an entry in this list
+ for each revision of each YANG module that is used by the server. It
+ is possible for multiple revisions of the same module to be imported,
+ in addition to an entry for the revision that is implemented by the
+ server.
+
+2.2. YANG Library Module
+
+ The "ietf-yang-library" module defines monitoring information for the
+ YANG modules used by a server.
+
+ The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991]
+ are used by this module for some type definitions.
+
+ <CODE BEGINS> file "ietf-yang-library@2016-06-21.yang"
+
+ module ietf-yang-library {
+ namespace "urn:ietf:params:xml:ns:yang:ietf-yang-library";
+ prefix "yanglib";
+
+ import ietf-yang-types {
+ prefix yang;
+ }
+ import ietf-inet-types {
+ prefix inet;
+ }
+
+
+
+
+
+
+
+Bierman, et al. Standards Track [Page 5]
+
+RFC 7895 YANG Library June 2016
+
+
+ organization
+ "IETF NETCONF (Network Configuration) Working Group";
+
+ contact
+ "WG Web: <https://datatracker.ietf.org/wg/netconf/>
+ WG List: <mailto:netconf@ietf.org>
+
+ WG Chair: Mehmet Ersue
+ <mailto:mehmet.ersue@nsn.com>
+
+ WG Chair: Mahesh Jethanandani
+ <mailto:mjethanandani@gmail.com>
+
+ Editor: Andy Bierman
+ <mailto:andy@yumaworks.com>
+
+ Editor: Martin Bjorklund
+ <mailto:mbj@tail-f.com>
+
+ Editor: Kent Watsen
+ <mailto:kwatsen@juniper.net>";
+
+ description
+ "This module contains monitoring information about the YANG
+ modules and submodules that are used within a YANG-based
+ server.
+
+ Copyright (c) 2016 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 7895; see
+ the RFC itself for full legal notices.";
+
+ revision 2016-06-21 {
+ description
+ "Initial revision.";
+ reference
+ "RFC 7895: YANG Module Library.";
+ }
+
+
+
+
+
+Bierman, et al. Standards Track [Page 6]
+
+RFC 7895 YANG Library June 2016
+
+
+ /*
+ * Typedefs
+ */
+
+ typedef revision-identifier {
+ type string {
+ pattern '\d{4}-\d{2}-\d{2}';
+ }
+ description
+ "Represents a specific date in YYYY-MM-DD format.";
+ }
+
+ /*
+ * Groupings
+ */
+
+ grouping module-list {
+ description
+ "The module data structure is represented as a grouping
+ so it can be reused in configuration or another monitoring
+ data structure.";
+
+ grouping common-leafs {
+ description
+ "Common parameters for YANG modules and submodules.";
+
+ leaf name {
+ type yang:yang-identifier;
+ description
+ "The YANG module or submodule name.";
+ }
+ leaf revision {
+ type union {
+ type revision-identifier;
+ type string { length 0; }
+ }
+ description
+ "The YANG module or submodule revision date.
+ A zero-length string is used if no revision statement
+ is present in the YANG module or submodule.";
+ }
+ }
+
+ grouping schema-leaf {
+ description
+ "Common schema leaf parameter for modules and submodules.";
+
+
+
+
+
+Bierman, et al. Standards Track [Page 7]
+
+RFC 7895 YANG Library June 2016
+
+
+ leaf schema {
+ type inet:uri;
+ description
+ "Contains a URL that represents the YANG schema
+ resource for this module or submodule.
+
+ This leaf will only be present if there is a URL
+ available for retrieval of the schema for this entry.";
+ }
+ }
+
+ list module {
+ key "name revision";
+ description
+ "Each entry represents one revision of one module
+ currently supported by the server.";
+
+ uses common-leafs;
+ uses schema-leaf;
+
+ leaf namespace {
+ type inet:uri;
+ mandatory true;
+ description
+ "The XML namespace identifier for this module.";
+ }
+ leaf-list feature {
+ type yang:yang-identifier;
+ description
+ "List of YANG feature names from this module that are
+ supported by the server, regardless of whether they are
+ defined in the module or any included submodule.";
+ }
+ list deviation {
+ key "name revision";
+ description
+ "List of YANG deviation module names and revisions
+ used by this server to modify the conformance of
+ the module associated with this entry. Note that
+ the same module can be used for deviations for
+ multiple modules, so the same entry MAY appear
+ within multiple 'module' entries.
+
+ The deviation module MUST be present in the 'module'
+ list, with the same name and revision values.
+ The 'conformance-type' value will be 'implement' for
+ the deviation module.";
+ uses common-leafs;
+
+
+
+Bierman, et al. Standards Track [Page 8]
+
+RFC 7895 YANG Library June 2016
+
+
+ }
+ leaf conformance-type {
+ type enumeration {
+ enum implement {
+ description
+ "Indicates that the server implements one or more
+ protocol-accessible objects defined in the YANG module
+ identified in this entry. This includes deviation
+ statements defined in the module.
+
+ For YANG version 1.1 modules, there is at most one
+ module entry with conformance type 'implement' for a
+ particular module name, since YANG 1.1 requires that,
+ at most, one revision of a module is implemented.
+
+ For YANG version 1 modules, there SHOULD NOT be more
+ than one module entry for a particular module name.";
+ }
+ enum import {
+ description
+ "Indicates that the server imports reusable definitions
+ from the specified revision of the module but does
+ not implement any protocol-accessible objects from
+ this revision.
+
+ Multiple module entries for the same module name MAY
+ exist. This can occur if multiple modules import the
+ same module but specify different revision dates in
+ the import statements.";
+ }
+ }
+ mandatory true;
+ description
+ "Indicates the type of conformance the server is claiming
+ for the YANG module identified by this entry.";
+ }
+ list submodule {
+ key "name revision";
+ description
+ "Each entry represents one submodule within the
+ parent module.";
+ uses common-leafs;
+ uses schema-leaf;
+ }
+ }
+ }
+
+
+
+
+
+Bierman, et al. Standards Track [Page 9]
+
+RFC 7895 YANG Library June 2016
+
+
+ /*
+ * Operational state data nodes
+ */
+
+ container modules-state {
+ config false;
+ description
+ "Contains YANG module monitoring information.";
+
+ leaf module-set-id {
+ type string;
+ mandatory true;
+ description
+ "Contains a server-specific identifier representing
+ the current set of modules and submodules. The
+ server MUST change the value of this leaf if the
+ information represented by the 'module' list instances
+ has changed.";
+ }
+
+ uses module-list;
+ }
+
+ /*
+ * Notifications
+ */
+
+ notification yang-library-change {
+ description
+ "Generated when the set of modules and submodules supported
+ by the server has changed.";
+ leaf module-set-id {
+ type leafref {
+ path "/yanglib:modules-state/yanglib:module-set-id";
+ }
+ mandatory true;
+ description
+ "Contains the module-set-id value representing the
+ set of modules and submodules supported at the server at
+ the time the notification is generated.";
+ }
+ }
+
+ }
+
+ <CODE ENDS>
+
+
+
+
+
+Bierman, et al. Standards Track [Page 10]
+
+RFC 7895 YANG Library June 2016
+
+
+3. IANA Considerations
+
+3.1. YANG Module Registry
+
+ This document registers one URI in the "IETF XML Registry" [RFC3688].
+ Following the format in RFC 3688, the following registration has been
+ made.
+
+ URI: urn:ietf:params:xml:ns:yang:ietf-yang-library
+ Registrant Contact: The NETCONF 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-library
+ namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library
+ prefix: yanglib
+ reference: RFC 7895
+
+4. Security Considerations
+
+ The YANG module defined in this memo is designed to be accessed via
+ the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the
+ secure transport layer and the mandatory-to-implement secure
+ transport is SSH [RFC6242]. The NETCONF access control model
+ [RFC6536] provides the means to restrict access for particular
+ NETCONF users to a pre-configured subset of all available NETCONF
+ protocol operations and content.
+
+ Some of the readable data nodes in this YANG module may be considered
+ sensitive or vulnerable in some network environments. It is thus
+ important to control read access (e.g., via get, get-config, or
+ notification) to these data nodes. These are the subtrees and data
+ nodes and their sensitivity/vulnerability:
+
+ o /modules-state/module: The module list used in a server
+ implementation may help an attacker identify the server
+ capabilities and server implementations with known bugs. Although
+ some of this information may be available to all users via the
+ NETCONF <hello> message (or similar messages in other management
+ protocols), this YANG module potentially exposes additional
+ details that could be of some assistance to an attacker. Server
+ vulnerabilities may be specific to particular modules, module
+ revisions, module features, or even module deviations. This
+ information is included in each module entry. For example, if a
+ particular operation on a particular data node is known to cause a
+ server to crash or significantly degrade device performance, then
+
+
+
+Bierman, et al. Standards Track [Page 11]
+
+RFC 7895 YANG Library June 2016
+
+
+ the module list information will help an attacker identify server
+ implementations with such a defect, in order to launch a denial-
+ of-service attack on the device.
+
+5. References
+
+5.1. Normative References
+
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119,
+ DOI 10.17487/RFC2119, March 1997,
+ <http://www.rfc-editor.org/info/rfc2119>.
+
+ [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
+ DOI 10.17487/RFC3688, January 2004,
+ <http://www.rfc-editor.org/info/rfc3688>.
+
+ [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
+ the Network Configuration Protocol (NETCONF)", RFC 6020,
+ DOI 10.17487/RFC6020, October 2010,
+ <http://www.rfc-editor.org/info/rfc6020>.
+
+ [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
+ and A. Bierman, Ed., "Network Configuration Protocol
+ (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
+ <http://www.rfc-editor.org/info/rfc6241>.
+
+ [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
+ Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
+ <http://www.rfc-editor.org/info/rfc6242>.
+
+ [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
+ Protocol (NETCONF) Access Control Model", RFC 6536,
+ DOI 10.17487/RFC6536, March 2012,
+ <http://www.rfc-editor.org/info/rfc6536>.
+
+ [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
+ RFC 6991, DOI 10.17487/RFC6991, July 2013,
+ <http://www.rfc-editor.org/info/rfc6991>.
+
+5.2. Informative References
+
+ [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
+ Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
+ <http://www.rfc-editor.org/info/rfc5277>.
+
+
+
+
+
+
+Bierman, et al. Standards Track [Page 12]
+
+RFC 7895 YANG Library June 2016
+
+
+ [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF)
+ Base Notifications", RFC 6470, DOI 10.17487/RFC6470,
+ February 2012, <http://www.rfc-editor.org/info/rfc6470>.
+
+ [YANG1.1] Bjorklund, M., "The YANG 1.1 Data Modeling Language", Work
+ in Progress, draft-ietf-netmod-rfc6020bis-12, April 2016.
+
+Acknowledgements
+
+ Contributions to this material by Andy Bierman are based upon work
+ supported by the Space & Terrestrial Communications Directorate
+ (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings,
+ conclusions, or recommendations expressed in this material are those
+ of the author(s) and do not necessarily reflect the views of the
+ Space & Terrestrial Communications Directorate (S&TCD).
+
+Authors' Addresses
+
+ Andy Bierman
+ YumaWorks
+
+ Email: andy@yumaworks.com
+
+
+ Martin Bjorklund
+ Tail-f Systems
+
+ Email: mbj@tail-f.com
+
+
+ Kent Watsen
+ Juniper Networks
+
+ Email: kwatsen@juniper.net
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bierman, et al. Standards Track [Page 13]
+