idnits 2.17.1 draft-ietf-netconf-yang-library-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 172 has weird spacing: '...-set-id str...' == Line 181 has weird spacing: '...evision uni...' == Line 186 has weird spacing: '...evision uni...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (April 27, 2016) is 2921 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) == Outdated reference: A later version (-14) exists of draft-ietf-netmod-rfc6020bis-11 Summary: 1 error (**), 0 flaws (~~), 6 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Bierman 3 Internet-Draft YumaWorks 4 Intended status: Standards Track M. Bjorklund 5 Expires: October 29, 2016 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 April 27, 2016 10 YANG Module Library 11 draft-ietf-netconf-yang-library-06 13 Abstract 15 This document describes a YANG library, which provides information 16 about all the YANG modules used by a network management server (e.g., 17 a Network Configuration Protocol (NETCONF) server). Simple caching 18 mechanisms are provided to allow clients to minimize retrieval of 19 this information. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on October 29, 2016. 38 Copyright Notice 40 Copyright (c) 2016 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.2. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 3 58 2. YANG Module Library . . . . . . . . . . . . . . . . . . . . . 4 59 2.1. modules-state . . . . . . . . . . . . . . . . . . . . . . 4 60 2.1.1. modules-state/module-set-id . . . . . . . . . . . . . 5 61 2.1.2. modules-state/module . . . . . . . . . . . . . . . . 5 62 2.2. YANG Library Module . . . . . . . . . . . . . . . . . . . 5 63 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 64 3.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 11 65 4. Security Considerations . . . . . . . . . . . . . . . . . . . 11 66 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 12 67 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 68 6.1. Normative References . . . . . . . . . . . . . . . . . . 12 69 6.2. Informative References . . . . . . . . . . . . . . . . . 13 70 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 13 71 A.1. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . 13 72 A.2. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . 14 73 A.3. v03 to v04 . . . . . . . . . . . . . . . . . . . . . . . 14 74 A.4. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . 14 75 A.5. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . 14 76 A.6. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 14 77 A.7. draft-ietf-netconf-restconf-03 to v00 . . . . . . . . . . 14 78 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 15 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 81 1. Introduction 83 There is a need for standard mechanisms to identify the YANG modules 84 and submodules that are in use by a server that implements YANG data 85 models. If a large number of YANG modules are utilized by the 86 server, then the YANG library contents needed can be relatively 87 large. This information changes very infrequently, so it is 88 important that clients be able to cache the YANG library contents and 89 easily identify whether their cache is out-of-date. 91 YANG library information can be different on every server, and can 92 change at run-time or across a server reboot. 94 If the server implements multiple protocols to access the YANG- 95 defined data, each such protocol has it's own conceptual 96 instantiation of the YANG library. 98 The following information is needed by a client application (for each 99 YANG module in the library) to fully utilize the YANG data modeling 100 language: 102 o name: The name of the YANG module. 104 o revision: Each YANG module and submodule within the library has a 105 revision. This is derived from the most recent revision statement 106 within the module or submodule. If no such revision statement 107 exists, the module's or submodule's revision is the zero-length 108 string. 110 o submodule list: The name and revision of each submodule used by 111 the module MUST be identified. 113 o feature list: The name of each YANG feature supported by the 114 server MUST be identified. 116 o deviation list: The name of each YANG module used for deviation 117 statements MUST be identified. 119 1.1. Terminology 121 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 122 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 123 "OPTIONAL" in this document are to be interpreted as described in BCP 124 14, [RFC2119]. 126 The following terms are defined in [RFC6241]: 128 o client 130 o server 132 The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: 134 o module 136 o submodule 138 The following terms are used within this document: 140 o YANG library: a collection of YANG modules and submodules used by 141 a server 143 1.2. Tree Diagrams 144 A simplified graphical representation of the data model is used in 145 this document. The meaning of the symbols in these diagrams is as 146 follows: 148 o Brackets "[" and "]" enclose list keys. 150 o Abbreviations before data node names: "rw" means configuration 151 data (read-write) and "ro" state data (read-only). 153 o Symbols after data node names: "?" means an optional node, "!" 154 means a presence container, and "*" denotes a list and leaf-list. 156 o Parentheses enclose choice and case nodes, and case nodes are also 157 marked with a colon (":"). 159 o Ellipsis ("...") stands for contents of subtrees that are not 160 shown. 162 2. YANG Module Library 164 The "ietf-yang-library" module provides information about the YANG 165 library used by a server. This module is defined using YANG version 166 1, but it supports the description of YANG modules written in any 167 revision of YANG. 169 YANG Tree Diagram for "ietf-yang-library" module: 171 +--ro modules-state 172 +--ro module-set-id string 173 +--ro module* [name revision] 174 +--ro name yang:yang-identifier 175 +--ro revision union 176 +--ro schema? inet:uri 177 +--ro namespace inet:uri 178 +--ro feature* yang:yang-identifier 179 +--ro deviation* [name revision] 180 | +--ro name yang:yang-identifier 181 | +--ro revision union 182 +--ro conformance-type enumeration 183 +--ro submodules 184 +--ro submodule* [name revision] 185 +--ro name yang:yang-identifier 186 +--ro revision union 187 +--ro schema? inet:uri 189 2.1. modules-state 190 This mandatory container holds the identifiers for the YANG data 191 model modules supported by the server. 193 2.1.1. modules-state/module-set-id 195 This mandatory leaf contains a unique implementation-specific 196 identifier representing the current set of modules and submodules on 197 a specific server. The value of this leaf MUST change whenever the 198 set of modules and submodules in the YANG library changes. There is 199 no requirement that the same set always results in the same module- 200 set-id value. 202 This leaf allows a client to fetch the module list once, cache it, 203 and only re-fetch it if the value of this leaf has been changed. 205 If the value of this leaf changes, the server also generates a 206 "yang-library-change" notification, with the new value of 207 "module-set-id". 209 Note that for a NETCONF server that implements YANG 1.1 210 [I-D.ietf-netmod-rfc6020bis], a change of the "module-set-id" value 211 results in a new value for the :yang-library capability defined in 212 [I-D.ietf-netmod-rfc6020bis]. Thus, if such a server implements 213 NETCONF notifications [RFC5277], and the notification 214 "netconf-capability-change" [RFC6470], a "netconf-capability-change" 215 notification is generated whenever the "module-set-id" changes. 217 2.1.2. modules-state/module 219 This mandatory list contains one entry for each YANG data model 220 module supported by the server. There MUST be an entry in this list 221 for each revision of each YANG module that is used by the server. It 222 is possible for multiple revisions of the same module to be imported, 223 in addition to an entry for the revision that is implemented by the 224 server. 226 2.2. YANG Library Module 228 The "ietf-yang-library" module defines monitoring information for the 229 YANG modules used by a server. 231 The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] 232 are used by this module for some type definitions. 234 RFC Ed.: update the date below with the date of RFC publication and 235 remove this note. 237 file "ietf-yang-library@2016-04-09.yang" 238 module ietf-yang-library { 239 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-library"; 240 prefix "yanglib"; 242 import ietf-yang-types { 243 prefix yang; 244 } 245 import ietf-inet-types { 246 prefix inet; 247 } 249 organization 250 "IETF NETCONF (Network Configuration) Working Group"; 252 contact 253 "WG Web: 254 WG List: 256 WG Chair: Mehmet Ersue 257 259 WG Chair: Mahesh Jethanandani 260 262 Editor: Andy Bierman 263 265 Editor: Martin Bjorklund 266 268 Editor: Kent Watsen 269 "; 271 description 272 "This module contains monitoring information about the YANG 273 modules and submodules that are used within a YANG-based 274 server. 276 Copyright (c) 2016 IETF Trust and the persons identified as 277 authors of the code. All rights reserved. 279 Redistribution and use in source and binary forms, with or 280 without modification, is permitted pursuant to, and subject 281 to the license terms contained in, the Simplified BSD License 282 set forth in Section 4.c of the IETF Trust's Legal Provisions 283 Relating to IETF Documents 284 (http://trustee.ietf.org/license-info). 285 This version of this YANG module is part of RFC XXXX; see 286 the RFC itself for full legal notices."; 288 // RFC Ed.: replace XXXX with actual RFC number and remove this 289 // note. 291 // RFC Ed.: remove this note 292 // Note: extracted from draft-ietf-netconf-yang-library-06.txt 294 // RFC Ed.: update the date below with the date of RFC publication 295 // and remove this note. 296 revision 2016-04-09 { 297 description 298 "Initial revision."; 299 reference 300 "RFC XXXX: YANG Module Library."; 301 } 303 /* 304 * Typedefs 305 */ 307 typedef revision-identifier { 308 type string { 309 pattern '\d{4}-\d{2}-\d{2}'; 310 } 311 description 312 "Represents a specific date in YYYY-MM-DD format."; 313 } 315 /* 316 * Groupings 317 */ 319 grouping module-list { 320 description 321 "The module data structure is represented as a grouping 322 so it can be reused in configuration or another monitoring 323 data structure."; 325 grouping common-leafs { 326 description 327 "Common parameters for YANG modules and submodules."; 329 leaf name { 330 type yang:yang-identifier; 331 description 332 "The YANG module or submodule name."; 334 } 335 leaf revision { 336 type union { 337 type revision-identifier; 338 type string { length 0; } 339 } 340 description 341 "The YANG module or submodule revision date. 342 A zero-length string is used if no revision statement 343 is present in the YANG module or submodule."; 344 } 345 } 347 grouping schema-leaf { 348 description 349 "Common schema leaf parameter for modules and submodules."; 351 leaf schema { 352 type inet:uri; 353 description 354 "Contains a URL that represents the YANG schema 355 resource for this module or submodule. 357 This leaf will only be present if there is a URL 358 available for retrieval of the schema for this entry."; 359 } 360 } 362 list module { 363 key "name revision"; 364 description 365 "Each entry represents one revision of one module 366 currently supported by the server."; 368 uses common-leafs; 369 uses schema-leaf; 371 leaf namespace { 372 type inet:uri; 373 mandatory true; 374 description 375 "The XML namespace identifier for this module."; 376 } 377 leaf-list feature { 378 type yang:yang-identifier; 379 description 380 "List of YANG feature names from this module that are 381 supported by the server, regardless whether they are 382 defined in the module or any included submodule."; 383 } 384 list deviation { 385 key "name revision"; 386 description 387 "List of YANG deviation module names and revisions 388 used by this server to modify the conformance of 389 the module associated with this entry. Note that 390 the same module can be used for deviations for 391 multiple modules, so the same entry MAY appear 392 within multiple 'module' entries. 394 The deviation module MUST be present in the 'module' 395 list, with the same name and revision values. 396 The 'conformance-type' value will be 'implement' for 397 the deviation module."; 398 uses common-leafs; 399 } 400 leaf conformance-type { 401 type enumeration { 402 enum implement { 403 description 404 "Indicates that the server implements one or more 405 protocol-accessible objects defined in the YANG module 406 identified in this entry. This includes deviation 407 statements defined in the module. 409 For YANG version 1.1 modules, there is at most one 410 module entry with conformance type 'implement' for a 411 particular module name, since YANG 1.1 requires that 412 at most one revision of a module is implemented. 414 For YANG version 1 modules, there SHOULD NOT be more 415 than one module entry for a particular module name."; 416 } 417 enum import { 418 description 419 "Indicates that the server imports reusable definitions 420 from the specified revision of the module, but does 421 not implement any protocol accessible objects from 422 this revision. 424 Multiple module entries for the same module name MAY 425 exist. This can occur if multiple modules import the 426 same module, but specify different revision-dates in 427 the import statements."; 428 } 429 } 430 mandatory true; 431 description 432 "Indicates the type of conformance the server is claiming 433 for the YANG module identified by this entry."; 434 } 435 container submodules { 436 description 437 "Contains information about all the submodules used 438 by the parent module entry"; 440 list submodule { 441 key "name revision"; 442 description 443 "Each entry represents one submodule within the 444 parent module."; 445 uses common-leafs; 446 uses schema-leaf; 447 } 448 } 449 } 450 } 452 /* 453 * Operational state data nodes 454 */ 456 container modules-state { 457 config false; 458 description 459 "Contains YANG module monitoring information."; 461 leaf module-set-id { 462 type string; 463 mandatory true; 464 description 465 "Contains a server-specific identifier representing 466 the current set of modules and submodules. The 467 server MUST change the value of this leaf if the 468 information represented by the 'module' list instances 469 has changed."; 470 } 472 uses module-list; 473 } 475 /* 476 * Notifications 477 */ 479 notification yang-library-change { 480 description 481 "Generated when the set of modules and submodules supported 482 by the server has changed."; 483 leaf module-set-id { 484 type leafref { 485 path "/yanglib:modules-state/yanglib:module-set-id"; 486 } 487 mandatory true; 488 description 489 "Contains the module-set-id value representing the 490 set of modules and submodules supported at the server at 491 the time the notification is generated."; 492 } 493 } 495 } 497 499 3. IANA Considerations 501 3.1. YANG Module Registry 503 This document registers one URI in the IETF XML registry [RFC3688]. 504 Following the format in RFC 3688, the following registration is 505 requested to be made. 507 URI: urn:ietf:params:xml:ns:yang:ietf-yang-library 508 Registrant Contact: The NETCONF WG of the IETF. 509 XML: N/A, the requested URI is an XML namespace. 511 This document registers one YANG module in the YANG Module Names 512 registry [RFC6020]. 514 name: ietf-yang-library 515 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library 516 prefix: yanglib 517 // RFC Ed.: replace XXXX with RFC number and remove this note 518 reference: RFC XXXX 520 4. Security Considerations 521 The YANG module defined in this memo is designed to be accessed via 522 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 523 secure transport layer and the mandatory-to-implement secure 524 transport is SSH [RFC6242]. Authorization for access to specific 525 portions of conceptual data and operations within this module is 526 provided by the NETCONF access control model (NACM) [RFC6536]. 528 Some of the readable data nodes in this YANG module may be considered 529 sensitive or vulnerable in some network environments. It is thus 530 important to control read access (e.g., via get, get-config, or 531 notification) to these data nodes. These are the subtrees and data 532 nodes and their sensitivity/vulnerability: 534 o /modules-state/module: The module list used in a server 535 implementation may help an attacker identify the server 536 capabilities and server implementations with known bugs. Although 537 some of this information may be available to all users via the 538 NETCONF message (or similar messages in other management 539 protocols), this YANG module potentially exposes additional 540 details that could be of some assistance to an attacker. Server 541 vulnerabilities may be specific to particular modules, module 542 revisions, module features, or even module deviations. This 543 information is included in each module entry. For example, if a 544 particular operation on a particular data node is known to cause a 545 server to crash or significantly degrade device performance, then 546 the module list information will help an attacker identify server 547 implementations with such a defect, in order to launch a denial of 548 service attack on the device. 550 5. Acknowledgements 552 Contributions to this material by Andy Bierman are based upon work 553 supported by the The Space & Terrestrial Communications Directorate 554 (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings 555 and conclusions or recommendations expressed in this material are 556 those of the author(s) and do not necessarily reflect the views of 557 The Space & Terrestrial Communications Directorate (S&TCD). 559 6. References 561 6.1. Normative References 563 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 564 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 565 RFC2119, March 1997, 566 . 568 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 569 DOI 10.17487/RFC3688, January 2004, 570 . 572 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 573 the Network Configuration Protocol (NETCONF)", RFC 6020, 574 DOI 10.17487/RFC6020, October 2010, 575 . 577 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 578 and A. Bierman, Ed., "Network Configuration Protocol 579 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 580 . 582 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 583 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 584 . 586 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 587 Protocol (NETCONF) Access Control Model", RFC 6536, DOI 588 10.17487/RFC6536, March 2012, 589 . 591 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 592 6991, DOI 10.17487/RFC6991, July 2013, 593 . 595 6.2. Informative References 597 [I-D.ietf-netmod-rfc6020bis] 598 Bjorklund, M., "The YANG 1.1 Data Modeling Language", 599 draft-ietf-netmod-rfc6020bis-11 (work in progress), 600 February 2016. 602 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 603 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 604 . 606 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 607 Base Notifications", RFC 6470, DOI 10.17487/RFC6470, 608 February 2012, . 610 Appendix A. Change Log 612 -- RFC Ed.: remove this section before publication. 614 A.1. v05 to v06 615 o correct IANA instructions for module 617 A.2. v04 to v05 619 o clarify security considerations per secdir review 621 o clarifications for AD review 623 A.3. v03 to v04 625 o editorial changes after WGLC 627 o one library instance per management protocol 629 o removed protocol definitions 631 o removed requirements on YANG 1.1 modules (text is moved to draft- 632 ietf-netmod-rfc6020bis) 634 o added notification yang-library-change 636 o changed top-level node name from "modules" to "modules-state" 638 o changed leaf "conformance" to "conformance-type" 640 A.4. v02 to v03 642 o added yang-protocol identity 644 o added identities for NETCONF and RESTCONF protocols 646 o added yang-protocol leaf-list to /modules 648 o added restricted-protocol leaf-list to /modules/module 650 A.5. v01 to v02 652 o clarify 'implement' conformance for YANG 1.1 modules 654 A.6. v00 to v01 656 o change conformance leaf to enumeration 658 o filled in security considerations section 660 A.7. draft-ietf-netconf-restconf-03 to v00 662 o moved ietf-yang-library from RESTCONF draft to new draft 664 Appendix B. Open Issues 666 -- RFC Ed.: remove this section before publication. 668 The YANG Library issue tracker can be found here: 670 https://github.com/netconf-wg/yang-library/issues 672 Authors' Addresses 674 Andy Bierman 675 YumaWorks 677 Email: andy@yumaworks.com 679 Martin Bjorklund 680 Tail-f Systems 682 Email: mbj@tail-f.com 684 Kent Watsen 685 Juniper Networks 687 Email: kwatsen@juniper.net