idnits 2.17.1 draft-ietf-netconf-yang-library-05.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 171 has weird spacing: '...-set-id str...' == Line 180 has weird spacing: '...evision uni...' == Line 185 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 9, 2016) is 2938 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-10 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 11, 2016 Tail-f Systems 6 K. Watsen 7 Juniper Networks 8 April 9, 2016 10 YANG Module Library 11 draft-ietf-netconf-yang-library-05 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 11, 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. v04 to v05 . . . . . . . . . . . . . . . . . . . . . . . 13 72 A.2. v03 to v04 . . . . . . . . . . . . . . . . . . . . . . . 14 73 A.3. v02 to v03 . . . . . . . . . . . . . . . . . . . . . . . 14 74 A.4. v01 to v02 . . . . . . . . . . . . . . . . . . . . . . . 14 75 A.5. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 14 76 A.6. draft-ietf-netconf-restconf-03 to v00 . . . . . . . . . . 14 77 Appendix B. Open Issues . . . . . . . . . . . . . . . . . . . . 14 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 80 1. Introduction 82 There is a need for standard mechanisms to identify the YANG modules 83 and submodules that are in use by a server that implements YANG data 84 models. If a large number of YANG modules are utilized by the 85 server, then the YANG library contents needed can be relatively 86 large. This information changes very infrequently, so it is 87 important that clients be able to cache the YANG library contents and 88 easily identify whether their cache is out-of-date. 90 YANG library information can be different on every server, and can 91 change at run-time or across a server reboot. 93 If the server implements multiple protocols to access the YANG- 94 defined data, each such protocol has it's own conceptual 95 instantiation of the YANG library. 97 The following information is needed by a client application (for each 98 YANG module in the library) to fully utilize the YANG data modeling 99 language: 101 o name: The name of the YANG module. 103 o revision: Each YANG module and submodule within the library has a 104 revision. This is derived from the most recent revision statement 105 within the module or submodule. If no such revision statement 106 exists, the module's or submodule's revision is the zero-length 107 string. 109 o submodule list: The name and revision of each submodule used by 110 the module MUST be identified. 112 o feature list: The name of each YANG feature supported by the 113 server MUST be identified. 115 o deviation list: The name of each YANG module used for deviation 116 statements MUST be identified. 118 1.1. Terminology 120 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 121 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 122 "OPTIONAL" in this document are to be interpreted as described in BCP 123 14, [RFC2119]. 125 The following terms are defined in [RFC6241]: 127 o client 129 o server 131 The following terms are defined in [I-D.ietf-netmod-rfc6020bis]: 133 o module 135 o submodule 137 The following terms are used within this document: 139 o YANG library: a collection of YANG modules and submodules used by 140 a server 142 1.2. Tree Diagrams 143 A simplified graphical representation of the data model is used in 144 this document. The meaning of the symbols in these diagrams is as 145 follows: 147 o Brackets "[" and "]" enclose list keys. 149 o Abbreviations before data node names: "rw" means configuration 150 data (read-write) and "ro" state data (read-only). 152 o Symbols after data node names: "?" means an optional node, "!" 153 means a presence container, and "*" denotes a list and leaf-list. 155 o Parentheses enclose choice and case nodes, and case nodes are also 156 marked with a colon (":"). 158 o Ellipsis ("...") stands for contents of subtrees that are not 159 shown. 161 2. YANG Module Library 163 The "ietf-yang-library" module provides information about the YANG 164 library used by a server. This module is defined using YANG version 165 1, but it supports the description of YANG modules written in any 166 revision of YANG. 168 YANG Tree Diagram for "ietf-yang-library" module: 170 +--ro modules-state 171 +--ro module-set-id string 172 +--ro module* [name revision] 173 +--ro name yang:yang-identifier 174 +--ro revision union 175 +--ro schema? inet:uri 176 +--ro namespace inet:uri 177 +--ro feature* yang:yang-identifier 178 +--ro deviation* [name revision] 179 | +--ro name yang:yang-identifier 180 | +--ro revision union 181 +--ro conformance-type enumeration 182 +--ro submodules 183 +--ro submodule* [name revision] 184 +--ro name yang:yang-identifier 185 +--ro revision union 186 +--ro schema? inet:uri 188 2.1. modules-state 189 This mandatory container holds the identifiers for the YANG data 190 model modules supported by the server. 192 2.1.1. modules-state/module-set-id 194 This mandatory leaf contains a unique implementation-specific 195 identifier representing the current set of modules and submodules on 196 a specific server. The value of this leaf MUST change whenever the 197 set of modules and submodules in the YANG library changes. There is 198 no requirement that the same set always results in the same module- 199 set-id value. 201 This leaf allows a client to fetch the module list once, cache it, 202 and only re-fetch it if the value of this leaf has been changed. 204 If the value of this leaf changes, the server also generates a 205 "yang-library-change" notification, with the new value of 206 "module-set-id". 208 Note that for a NETCONF server that implements YANG 1.1 209 [I-D.ietf-netmod-rfc6020bis], a change of the "module-set-id" value 210 results in a new value for the :yang-library capability defined in 211 [I-D.ietf-netmod-rfc6020bis]. Thus, if such a server implements 212 NETCONF notifications [RFC5277], and the notification 213 "netconf-capability-change" [RFC6470], a "netconf-capability-change" 214 notification is generated whenever the "module-set-id" changes. 216 2.1.2. modules-state/module 218 This mandatory list contains one entry for each YANG data model 219 module supported by the server. There MUST be an entry in this list 220 for each revision of each YANG module that is used by the server. It 221 is possible for multiple revisions of the same module to be imported, 222 in addition to an entry for the revision that is implemented by the 223 server. 225 2.2. YANG Library Module 227 The "ietf-yang-library" module defines monitoring information for the 228 YANG modules used by a server. 230 The "ietf-yang-types" and "ietf-inet-types" modules from [RFC6991] 231 are used by this module for some type definitions. 233 RFC Ed.: update the date below with the date of RFC publication and 234 remove this note. 236 file "ietf-yang-library@2016-04-09.yang" 237 module ietf-yang-library { 238 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-library"; 239 prefix "yanglib"; 241 import ietf-yang-types { 242 prefix yang; 243 } 244 import ietf-inet-types { 245 prefix inet; 246 } 248 organization 249 "IETF NETCONF (Network Configuration) Working Group"; 251 contact 252 "WG Web: 253 WG List: 255 WG Chair: Mehmet Ersue 256 258 WG Chair: Mahesh Jethanandani 259 261 Editor: Andy Bierman 262 264 Editor: Martin Bjorklund 265 267 Editor: Kent Watsen 268 "; 270 description 271 "This module contains monitoring information about the YANG 272 modules and submodules that are used within a YANG-based 273 server. 275 Copyright (c) 2016 IETF Trust and the persons identified as 276 authors of the code. All rights reserved. 278 Redistribution and use in source and binary forms, with or 279 without modification, is permitted pursuant to, and subject 280 to the license terms contained in, the Simplified BSD License 281 set forth in Section 4.c of the IETF Trust's Legal Provisions 282 Relating to IETF Documents 283 (http://trustee.ietf.org/license-info). 284 This version of this YANG module is part of RFC XXXX; see 285 the RFC itself for full legal notices."; 287 // RFC Ed.: replace XXXX with actual RFC number and remove this 288 // note. 290 // RFC Ed.: remove this note 291 // Note: extracted from draft-ietf-netconf-yang-library-05.txt 293 // RFC Ed.: update the date below with the date of RFC publication 294 // and remove this note. 295 revision 2016-04-09 { 296 description 297 "Initial revision."; 298 reference 299 "RFC XXXX: YANG Module Library."; 300 } 302 /* 303 * Typedefs 304 */ 306 typedef revision-identifier { 307 type string { 308 pattern '\d{4}-\d{2}-\d{2}'; 309 } 310 description 311 "Represents a specific date in YYYY-MM-DD format."; 312 } 314 /* 315 * Groupings 316 */ 318 grouping module-list { 319 description 320 "The module data structure is represented as a grouping 321 so it can be reused in configuration or another monitoring 322 data structure."; 324 grouping common-leafs { 325 description 326 "Common parameters for YANG modules and submodules."; 328 leaf name { 329 type yang:yang-identifier; 330 description 331 "The YANG module or submodule name."; 333 } 334 leaf revision { 335 type union { 336 type revision-identifier; 337 type string { length 0; } 338 } 339 description 340 "The YANG module or submodule revision date. 341 A zero-length string is used if no revision statement 342 is present in the YANG module or submodule."; 343 } 344 } 346 grouping schema-leaf { 347 description 348 "Common schema leaf parameter for modules and submodules."; 350 leaf schema { 351 type inet:uri; 352 description 353 "Contains a URL that represents the YANG schema 354 resource for this module or submodule. 356 This leaf will only be present if there is a URL 357 available for retrieval of the schema for this entry."; 358 } 359 } 361 list module { 362 key "name revision"; 363 description 364 "Each entry represents one revision of one module 365 currently supported by the server."; 367 uses common-leafs; 368 uses schema-leaf; 370 leaf namespace { 371 type inet:uri; 372 mandatory true; 373 description 374 "The XML namespace identifier for this module."; 375 } 376 leaf-list feature { 377 type yang:yang-identifier; 378 description 379 "List of YANG feature names from this module that are 380 supported by the server, regardless whether they are 381 defined in the module or any included submodule."; 382 } 383 list deviation { 384 key "name revision"; 385 description 386 "List of YANG deviation module names and revisions 387 used by this server to modify the conformance of 388 the module associated with this entry. Note that 389 the same module can be used for deviations for 390 multiple modules, so the same entry MAY appear 391 within multiple 'module' entries. 393 The deviation module MUST be present in the 'module' 394 list, with the same name and revision values. 395 The 'conformance-type' value will be 'implement' for 396 the deviation module."; 397 uses common-leafs; 398 } 399 leaf conformance-type { 400 type enumeration { 401 enum implement { 402 description 403 "Indicates that the server implements one or more 404 protocol-accessible objects defined in the YANG module 405 identified in this entry. This includes deviation 406 statements defined in the module. 408 For YANG version 1.1 modules, there is at most one 409 module entry with conformance type 'implement' for a 410 particular module name, since YANG 1.1 requires that 411 at most one revision of a module is implemented. 413 For YANG version 1 modules, there SHOULD NOT be more 414 than one module entry for a particular module name."; 415 } 416 enum import { 417 description 418 "Indicates that the server imports reusable definitions 419 from the specified revision of the module, but does 420 not implement any protocol accessible objects from 421 this revision. 423 Multiple module entries for the same module name MAY 424 exist. This can occur if multiple modules import the 425 same module, but specify different revision-dates in 426 the import statements."; 427 } 428 } 429 mandatory true; 430 description 431 "Indicates the type of conformance the server is claiming 432 for the YANG module identified by this entry."; 433 } 434 container submodules { 435 description 436 "Contains information about all the submodules used 437 by the parent module entry"; 439 list submodule { 440 key "name revision"; 441 description 442 "Each entry represents one submodule within the 443 parent module."; 444 uses common-leafs; 445 uses schema-leaf; 446 } 447 } 448 } 449 } 451 /* 452 * Operational state data nodes 453 */ 455 container modules-state { 456 config false; 457 description 458 "Contains YANG module monitoring information."; 460 leaf module-set-id { 461 type string; 462 mandatory true; 463 description 464 "Contains a server-specific identifier representing 465 the current set of modules and submodules. The 466 server MUST change the value of this leaf if the 467 information represented by the 'module' list instances 468 has changed."; 469 } 471 uses module-list; 472 } 474 /* 475 * Notifications 476 */ 478 notification yang-library-change { 479 description 480 "Generated when the set of modules and submodules supported 481 by the server has changed."; 482 leaf module-set-id { 483 type leafref { 484 path "/yanglib:modules-state/yanglib:module-set-id"; 485 } 486 mandatory true; 487 description 488 "Contains the module-set-id value representing the 489 set of modules and submodules supported at the server at 490 the time the notification is generated."; 491 } 492 } 494 } 496 498 3. IANA Considerations 500 3.1. YANG Module Registry 502 This document registers one URI in the IETF XML registry [RFC3688]. 503 Following the format in RFC 3688, the following registration is 504 requested to be made. 506 URI: urn:ietf:params:xml:ns:yang:ietf-yang-library 507 Registrant Contact: The NETMOD WG of the IETF. 508 XML: N/A, the requested URI is an XML namespace. 510 This document registers one YANG module in the YANG Module Names 511 registry [RFC6020]. 513 name: ietf-yang-library 514 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library 515 prefix: yanglib 516 // RFC Ed.: replace XXXX with RFC number and remove this note 517 reference: RFC XXXX 519 4. Security Considerations 520 The YANG module defined in this memo is designed to be accessed via 521 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 522 secure transport layer and the mandatory-to-implement secure 523 transport is SSH [RFC6242]. Authorization for access to specific 524 portions of conceptual data and operations within this module is 525 provided by the NETCONF access control model (NACM) [RFC6536]. 527 Some of the readable data nodes in this YANG module may be considered 528 sensitive or vulnerable in some network environments. It is thus 529 important to control read access (e.g., via get, get-config, or 530 notification) to these data nodes. These are the subtrees and data 531 nodes and their sensitivity/vulnerability: 533 o /modules-state/module: The module list used in a server 534 implementation may help an attacker identify the server 535 capabilities and server implementations with known bugs. Although 536 some of this information may be available to all users via the 537 NETCONF message (or similar messages in other management 538 protocols), this YANG module potentially exposes additional 539 details that could be of some assistance to an attacker. Server 540 vulnerabilities may be specific to particular modules, module 541 revisions, module features, or even module deviations. This 542 information is included in each module entry. For example, if a 543 particular operation on a particular data node is known to cause a 544 server to crash or significantly degrade device performance, then 545 the module list information will help an attacker identify server 546 implementations with such a defect, in order to launch a denial of 547 service attack on the device. 549 5. Acknowledgements 551 Contributions to this material by Andy Bierman are based upon work 552 supported by the The Space & Terrestrial Communications Directorate 553 (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings 554 and conclusions or recommendations expressed in this material are 555 those of the author(s) and do not necessarily reflect the views of 556 The Space & Terrestrial Communications Directorate (S&TCD). 558 6. References 560 6.1. Normative References 562 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 563 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 564 RFC2119, March 1997, 565 . 567 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 568 DOI 10.17487/RFC3688, January 2004, 569 . 571 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 572 the Network Configuration Protocol (NETCONF)", RFC 6020, 573 DOI 10.17487/RFC6020, October 2010, 574 . 576 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 577 and A. Bierman, Ed., "Network Configuration Protocol 578 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 579 . 581 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 582 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 583 . 585 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 586 Protocol (NETCONF) Access Control Model", RFC 6536, DOI 587 10.17487/RFC6536, March 2012, 588 . 590 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 591 6991, DOI 10.17487/RFC6991, July 2013, 592 . 594 6.2. Informative References 596 [I-D.ietf-netmod-rfc6020bis] 597 Bjorklund, M., "The YANG 1.1 Data Modeling Language", 598 draft-ietf-netmod-rfc6020bis-10 (work in progress), 599 February 2016. 601 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 602 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 603 . 605 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 606 Base Notifications", RFC 6470, DOI 10.17487/RFC6470, 607 February 2012, . 609 Appendix A. Change Log 611 -- RFC Ed.: remove this section before publication. 613 A.1. v04 to v05 614 o clarify security considerations per secdir review 616 o clarifications for AD review 618 A.2. v03 to v04 620 o editorial changes after WGLC 622 o one library instance per management protocol 624 o removed protocol definitions 626 o removed requirements on YANG 1.1 modules (text is moved to draft- 627 ietf-netmod-rfc6020bis) 629 o added notification yang-library-change 631 o changed top-level node name from "modules" to "modules-state" 633 o changed leaf "conformance" to "conformance-type" 635 A.3. v02 to v03 637 o added yang-protocol identity 639 o added identities for NETCONF and RESTCONF protocols 641 o added yang-protocol leaf-list to /modules 643 o added restricted-protocol leaf-list to /modules/module 645 A.4. v01 to v02 647 o clarify 'implement' conformance for YANG 1.1 modules 649 A.5. v00 to v01 651 o change conformance leaf to enumeration 653 o filled in security considerations section 655 A.6. draft-ietf-netconf-restconf-03 to v00 657 o moved ietf-yang-library from RESTCONF draft to new draft 659 Appendix B. Open Issues 661 -- RFC Ed.: remove this section before publication. 663 The YANG Library issue tracker can be found here: 665 https://github.com/netconf-wg/yang-library/issues 667 Authors' Addresses 669 Andy Bierman 670 YumaWorks 672 Email: andy@yumaworks.com 674 Martin Bjorklund 675 Tail-f Systems 677 Email: mbj@tail-f.com 679 Kent Watsen 680 Juniper Networks 682 Email: kwatsen@juniper.net