idnits 2.17.1 draft-ietf-netconf-rfc7895bis-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 280 has weird spacing: '...mespace ine...' == Line 291 has weird spacing: '...mespace ine...' -- The document date (April 9, 2018) is 2209 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 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) == Outdated reference: A later version (-08) exists of draft-ietf-netconf-nmda-netconf-04 == Outdated reference: A later version (-05) exists of draft-ietf-netconf-nmda-restconf-03 == Outdated reference: A later version (-12) exists of draft-ietf-netmod-schema-mount-09 -- Obsolete informational reference (is this intentional?): RFC 7895 (Obsoleted by RFC 8525) Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 2 comments (--). 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 Obsoletes: 7895 (if approved) M. Bjorklund 5 Intended status: Standards Track Tail-f Systems 6 Expires: October 11, 2018 J. Schoenwaelder 7 Jacobs University 8 K. Watsen 9 Juniper Networks 10 R. Wilton 11 Cisco Systems 12 April 9, 2018 14 YANG Library 15 draft-ietf-netconf-rfc7895bis-06 17 Abstract 19 This document describes a YANG library that provides information 20 about the YANG modules, datastores, and datastore schemas used by a 21 network management server. Simple caching mechanisms are provided to 22 allow clients to minimize retrieval of this information. This 23 version of the YANG library supports the Network Management Datastore 24 Architecture by listing all datastores supported by a network 25 management server and the schema that is used by each of these 26 datastores. 28 This document obsoletes RFC 7895. 30 Status of This Memo 32 This Internet-Draft is submitted in full conformance with the 33 provisions of BCP 78 and BCP 79. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on October 11, 2018. 47 Copyright Notice 49 Copyright (c) 2018 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 65 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Objectives . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 3. YANG Library Data Model . . . . . . . . . . . . . . . . . . . 6 68 4. YANG Library YANG Module . . . . . . . . . . . . . . . . . . 8 69 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 70 6. Security Considerations . . . . . . . . . . . . . . . . . . . 21 71 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 22 72 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 22 73 8.1. Normative References . . . . . . . . . . . . . . . . . . 22 74 8.2. Informative References . . . . . . . . . . . . . . . . . 23 75 Appendix A. Summary of Changes from RFC 7895 . . . . . . . . . . 24 76 Appendix B. Example YANG Library Instance for a Basic Server . . 25 77 Appendix C. Example YANG Library Instance for an Advanced Server 27 78 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 31 80 1. Introduction 82 There is a need for a standard mechanism to expose which YANG modules 83 [RFC7950], datastores and datastore schemas [RFC8342] are in use by a 84 network management server. 86 This document defines the YANG module "ietf-yang-library" that 87 provides this information. This version of the YANG library is 88 compatible with the Network Management Datastore Architecture (NMDA) 89 [RFC8342]. The previous version of the YANG library, defined in 90 [RFC7895], is not compatible with the NMDA since it assumes that all 91 datastores have exactly the same schema. This is not necessarily 92 true in the NMDA since dynamic configuration datastores may have 93 their own datastore schema. Furthermore, the operational state 94 datastore may support non-configurable YANG modules in addition to 95 the YANG modules supported by conventional configuration datastores. 97 The old YANG library definitions have been retained (for backwards 98 compatibility reasons) but the definitions have been marked as 99 deprecated. For backwards compatibility, an NMDA-supporting server 100 SHOULD populate the deprecated "/modules-state" tree in a backwards- 101 compatible manner. The new "/yang-library" tree would be ignored by 102 legacy clients, while providing all the data needed for NMDA-aware 103 clients, which would themselves ignore the "/modules-state" tree. 104 The recommended approach to populate "/modules-state" is to report 105 the schema for YANG modules that are configurable via conventional 106 datastores and for which config false data nodes are returned via a 107 NETCONF operation, or equivalent. 109 The YANG library information can be different on every server and it 110 can change at runtime or across a server reboot. If a server 111 implements multiple network management protocols to access the 112 server's datastores, then each such protocol may have its own 113 conceptual instantiation of the YANG library. 115 If a large number of YANG modules are utilized by a server, then the 116 YANG library contents can be relatively large. Since the YANG 117 library contents changes very infrequently, it is important that 118 clients be able to cache the YANG library contents and easily 119 identify whether their cache is out of date. 121 All NETCONF servers supporting YANG 1.1 [RFC7950] are required to 122 support YANG Library (see Section 5.6.4 of RFC 7950). NETCONF 123 servers implementing the NETCONF extensions to support the NMDA 124 [I-D.ietf-netconf-nmda-netconf] MUST implement at least the version 125 of the YANG library defined in this document. Similarly, all 126 RESTCONF servers are required to support YANG Library (see Section 10 127 of RFC 8040). RESTCONF servers implementing the RESTCONF extensions 128 to support the NMDA [I-D.ietf-netconf-nmda-restconf] MUST implement 129 at least the version of the YANG library defined in this document. 131 1.1. Terminology 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 135 "OPTIONAL" in this document are to be interpreted as described in BCP 136 14 [RFC2119] [RFC8174] when, and only when, they appear in all 137 capitals, as shown here. 139 The following terms are defined in [RFC7950]: 141 o module 142 o submodule 144 o data node 146 This document uses the phrase "implementing a module" as defined in 147 [RFC7950] Section 5.6.5. 149 The following terms are defined in [RFC8342]: 151 o datastore 153 o datastore schema 155 o configuration 157 o configuration datastore 159 o conventional configuration 161 o conventional configuration datastore 163 o operational state 165 o operational state datastore 167 o dynamic configuration datastore 169 o client and server 171 The following terms are used within this document: 173 o YANG library: A collection of YANG modules, submodules, 174 datastores, and datastore schemas used by a server. 176 o YANG library checksum: A server-generated checksum of the contents 177 of the YANG library. 179 Tree diagrams used in this document use the notation defined in 180 [RFC8340]. 182 2. Objectives 184 The following information is needed by a client application (for each 185 YANG module in the library) to fully utilize the YANG data modeling 186 language: 188 o name: The name of the YANG module. 190 o revision: Each YANG module and submodule within the library SHOULD 191 have a revision. This is derived from the most recent revision 192 statement within the module or submodule. 194 o submodule list: The name, and if defined, revision of each 195 submodule used by the module must be identified. 197 o feature list: The name of each YANG feature supported by the 198 server, in a given datastore schema, must be identified. 200 o deviation list: The name of each YANG module with deviation 201 statements affecting a given YANG module, in a given datastore 202 schema, must be identified. 204 In addition, the following information is needed by a client 205 application for each datastore supported by a server: 207 o identity: The YANG identity for the datastore. 209 o schema: The schema (i.e., the set of modules) implemented by the 210 datastore. 212 In order to select one out of several possible data model designs, 213 the following criteria were used: 215 1. Efficient for a client to consume. Since the size of the YANG 216 library can be quite large, it should be possible for clients to 217 cache the YANG library information. 219 2. A dynamic configuration datastore must be able to implement a 220 module or feature that is not implemented in the conventional 221 configuration datastores. 223 3. It must be possible to NOT implement a module or feature in 224 , even if it is implemented in some other datastore. 225 This is required for transition purposes; a server that wants to 226 implement should not have to implement all modules 227 at once. 229 4. A given module can only be implemented in one revision in all 230 datastores. If a module is implemented in more than one 231 datastores, the same revision is implemented in all these 232 datastores. 234 5. Multiple revisions can be used for import, if import-by revision 235 is used. 237 6. Make it possible to use the YANG library by schema mount 238 [I-D.ietf-netmod-schema-mount]. 240 3. YANG Library Data Model 242 The "ietf-yang-library" YANG module provides information about the 243 modules, submodules, datastores, and datastore schemas supported by a 244 server. All data nodes in "ietf-yang-library" are "config false", 245 and thus only accessible in the operational state datastore. 247 +-----------+ 248 | datastore | 249 +-----------+ 250 | 251 | has a 252 V 253 +-----------+ +--------+ +------------+ 254 | datastore | union of | module | consists of | modules + | 255 | schema |----------->| set |--------------->| submodules | 256 +-----------+ +--------+ +------------+ 258 Figure 1 260 The conceptual model of the YANG library is depicted in Figure 1. 261 Following the NMDA, every datastore has an associated datastore 262 schema. A datastore schema is a union of module sets and every 263 module set is a collection of modules and submodules, including the 264 modules and submodules used for imports. Note that multiple 265 datastores may refer to the same datastore schema. Furthermore, it 266 is possible that individual datastore schemas share module sets. A 267 common use case is the operational state datastore schema which is a 268 superset of the schema used by conventional configuration datastores. 270 Below is the YANG Tree Diagram for the "ietf-yang-library" module, 271 excluding the deprecated "modules-state" tree: 273 module: ietf-yang-library 274 +--ro yang-library 275 +--ro module-set* [name] 276 | +--ro name string 277 | +--ro module* [name] 278 | | +--ro name yang:yang-identifier 279 | | +--ro revision? revision-identifier 280 | | +--ro namespace inet:uri 281 | | +--ro location* inet:uri 282 | | +--ro submodule* [name] 283 | | | +--ro name yang:yang-identifier 284 | | | +--ro revision? revision-identifier 285 | | | +--ro location* inet:uri 286 | | +--ro feature* yang:yang-identifier 287 | | +--ro deviation* -> ../../module/name 288 | +--ro import-only-module* [name revision] 289 | +--ro name yang:yang-identifier 290 | +--ro revision union 291 | +--ro namespace inet:uri 292 | +--ro location* inet:uri 293 | +--ro submodule* [name] 294 | +--ro name yang:yang-identifier 295 | +--ro revision? revision-identifier 296 | +--ro location* inet:uri 297 +--ro schema* [name] 298 | +--ro name string 299 | +--ro module-set* -> ../../module-set/name 300 +--ro datastore* [name] 301 | +--ro name ds:datastore-ref 302 | +--ro schema -> ../../schema/name 303 +--ro checksum string 305 notifications: 306 +---n yang-library-update 307 +--ro checksum -> /yang-library/checksum 309 The "/yang-library" container holds the entire YANG library. The 310 container has the following child nodes: 312 o The "/yang-library/module-set" contains entries representing 313 module sets. The list "/yang-library/module-set/module" 314 enumerates the modules that belong to the module set. A module is 315 listed together with its submodules (if any), a set of features, 316 and any deviation modules. The list "/yang-library/module-set/ 317 import-only-module" lists all modules (and their submodules) used 318 only for imports. 320 o The "/yang-library/schema" list contains an entry for each 321 datastore schema supported by the server. All conventional 322 configuration datastores use the same "schema" list entry. A 323 dynamic configuration datastore may use a different datastore 324 schema from the conventional configuration datastores, and hence 325 may require a separate "schema" entry. A "schema" entry has a 326 leaf-list of references to entries in the "module-set" list. The 327 schema consists of the union of all modules in all referenced 328 module sets. 330 o The "/yang-library/datastore" list contains one entry for each 331 datastore supported by the server, and it identifies the datastore 332 schema associated with a datastore via a reference to an entry in 333 the "schema" list. Each supported conventional configuration 334 datastore has a separate entry, pointing to the same "schema" list 335 element. 337 o The "/yang-library/checksum" leaf contains the YANG library 338 checksum, which is a unique implementation-specific identifier 339 representing the current information in the YANG library on a 340 specific server. The value of this leaf MUST change whenever the 341 information in the YANG library changes. There is no requirement 342 that the same information always results in the same "checksum" 343 value. This leaf allows a client to fetch all schema information 344 once, cache it, and only refetch it if the value of this leaf has 345 been changed. If the value of this leaf changes, the server also 346 generates a "yang-library-update" notification. 348 Note that for a NETCONF server implementing the NETCONF extensions to 349 support the NMDA [I-D.ietf-netconf-nmda-netconf], a change of the 350 YANG library checksum results in a new value for the :yang- 351 library:1.1 capability defined in [I-D.ietf-netconf-nmda-netconf]. 352 Thus, if such a server implements NETCONF notifications [RFC5277], 353 and the notification "netconf-capability-change" [RFC6470], a 354 "netconf-capability-change" notification is generated whenever the 355 YANG library checksum changes. 357 4. YANG Library YANG Module 359 The "ietf-yang-library" YANG module imports definitions from 360 "ietf-yang-types" and "ietf-inet-types" defined in [RFC6991] and from 361 "ietf-datastores" defined in [RFC8342]. While the YANG module is 362 defined using YANG version 1.1, the YANG library supports the YANG 363 modules written in any version of YANG. 365 RFC Ed.: update the date below with the date of RFC publication and 366 remove this note. 368 file "ietf-yang-library@2018-02-21.yang" 370 module ietf-yang-library { 371 yang-version 1.1; 372 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-library"; 373 prefix "yanglib"; 375 import ietf-yang-types { 376 prefix yang; 377 reference "RFC 6991: Common YANG Data Types."; 378 } 379 import ietf-inet-types { 380 prefix inet; 381 reference "RFC 6991: Common YANG Data Types."; 382 } 383 import ietf-datastores { 384 prefix ds; 385 // RFC Ed.: update the reference below with the actual RFC number 386 reference "RFC XXXX: Network Management Datastore Architecture."; 387 } 389 organization 390 "IETF NETCONF (Network Configuration) Working Group"; 392 contact 393 "WG Web: 394 WG List: 396 Author: Andy Bierman 397 399 Author: Martin Bjorklund 400 402 Author: Juergen Schoenwaelder 403 405 Author: Kent Watsen 406 408 Author: Rob Wilton 409 "; 411 description 412 "This module provides information about the YANG modules, 413 datastores, and datastore schemas used by a network 414 management server. 416 Copyright (c) 2018 IETF Trust and the persons identified as 417 authors of the code. All rights reserved. 419 Redistribution and use in source and binary forms, with or 420 without modification, is permitted pursuant to, and subject 421 to the license terms contained in, the Simplified BSD License 422 set forth in Section 4.c of the IETF Trust's Legal Provisions 423 Relating to IETF Documents 424 (http://trustee.ietf.org/license-info). 426 This version of this YANG module is part of RFC XXXX; see 427 the RFC itself for full legal notices."; 429 // RFC Ed.: update the date below with the date of RFC publication 430 // and remove this note. 431 // RFC Ed.: replace XXXX with actual RFC number and remove this 432 // note. 433 revision 2018-02-21 { 434 description 435 "Added support for multiple datastores according to the 436 Network Management Datastore Architecture (NMDA)."; 437 reference 438 "RFC XXXX: YANG Library."; 439 } 440 revision 2016-04-09 { 441 description 442 "Initial revision."; 443 reference 444 "RFC 7895: YANG Module Library."; 445 } 447 /* 448 * Typedefs 449 */ 451 typedef revision-identifier { 452 type string { 453 pattern '\d{4}-\d{2}-\d{2}'; 454 } 455 description 456 "Represents a specific date in YYYY-MM-DD format."; 457 } 459 /* 460 * Groupings 461 */ 463 grouping module-identification-leafs { 464 description 465 "Parameters for identifying YANG modules and submodules."; 467 leaf name { 468 type yang:yang-identifier; 469 mandatory true; 470 description 471 "The YANG module or submodule name."; 472 } 473 leaf revision { 474 type revision-identifier; 475 description 476 "The YANG module or submodule revision date. If no revision 477 statement is present in the YANG module or submodule, this 478 leaf is not instantiated."; 479 } 480 } 482 grouping location-leaf-list { 483 description 484 "Common location leaf list parameter for modules and 485 submodules."; 487 leaf-list location { 488 type inet:uri; 489 description 490 "Contains a URL that represents the YANG schema 491 resource for this module or submodule. 493 This leaf will only be present if there is a URL 494 available for retrieval of the schema for this entry."; 495 } 496 } 498 grouping implementation-parameters { 499 description 500 "Parameters for describing the implementation of a module."; 502 leaf-list feature { 503 type yang:yang-identifier; 504 description 505 "List of all YANG feature names from this module that are 506 supported by the server, regardless whether they are defined 507 in the module or any included submodule."; 508 } 509 leaf-list deviation { 510 type leafref { 511 path "../../module/name"; 513 } 514 description 515 "List of all YANG deviation modules used by this server to 516 modify the conformance of the module associated with this 517 entry. Note that the same module can be used for deviations 518 for multiple modules, so the same entry MAY appear within 519 multiple 'module' entries. 521 This reference MUST NOT (directly or indirectly) 522 refer to the module being deviated. 524 Robust clients may want to make sure that they handle a 525 situation where a module deviates itself (directly or 526 indirectly) gracefully."; 527 } 528 } 530 grouping module-set-parameters { 531 description 532 "A set of parameters that describe a module set."; 534 leaf name { 535 type string; 536 description 537 "An arbitrary name of the module set."; 538 } 539 list module { 540 key "name"; 541 description 542 "An entry in this list represents a module implemented by the 543 server, as per RFC 7950 section 5.6.5, with a particular set 544 of supported features and deviations."; 545 reference 546 "RFC 7950: The YANG 1.1 Data Modeling Language."; 548 uses module-identification-leafs; 550 leaf namespace { 551 type inet:uri; 552 mandatory true; 553 description 554 "The XML namespace identifier for this module."; 555 } 557 uses location-leaf-list; 559 list submodule { 560 key "name"; 561 description 562 "Each entry represents one submodule within the 563 parent module."; 564 uses module-identification-leafs; 565 uses location-leaf-list; 566 } 568 uses implementation-parameters; 569 } 570 list import-only-module { 571 key "name revision"; 572 description 573 "An entry in this list indicates that the server imports 574 reusable definitions from the specified revision of the 575 module, but does not implement any protocol accessible 576 objects from this revision. 578 Multiple entries for the same module name MAY exist. This 579 can occur if multiple modules import the same module, but 580 specify different revision-dates in the import statements."; 582 leaf name { 583 type yang:yang-identifier; 584 description 585 "The YANG module name."; 586 } 587 leaf revision { 588 type union { 589 type revision-identifier; 590 type string { 591 length 0; 592 } 593 } 594 description 595 "The YANG module revision date. 596 A zero-length string is used if no revision statement 597 is present in the YANG module."; 598 } 599 leaf namespace { 600 type inet:uri; 601 mandatory true; 602 description 603 "The XML namespace identifier for this module."; 604 } 606 uses location-leaf-list; 608 list submodule { 609 key "name"; 610 description 611 "Each entry represents one submodule within the 612 parent module."; 614 uses module-identification-leafs; 615 uses location-leaf-list; 616 } 617 } 618 } 620 grouping yang-library-parameters { 621 description 622 "The YANG library data structure is represented as a grouping 623 so it can be reused in configuration or another monitoring 624 data structure."; 626 list module-set { 627 key name; 628 description 629 "A set of modules that may be used by one or more schemas. 631 A module set does not have to be referentially complete, 632 i.e., it may define modules that contain import statements 633 for other modules not included in the module set."; 635 uses module-set-parameters; 636 } 638 list schema { 639 key "name"; 640 description 641 "A datastore schema that may be used by one or more 642 datastores. 644 The schema must be valid and referentially complete, i.e., 645 it must contain modules to satisfy all used import 646 statements for all modules specified in the schema."; 648 leaf name { 649 type string; 650 description 651 "An arbitrary name of the schema."; 652 } 653 leaf-list module-set { 654 type leafref { 655 path "../../module-set/name"; 656 } 657 description 658 "A set of module-sets that are included in this schema. 659 If a non import-only module appears in multiple module 660 sets, then the module revision and the associated features 661 and deviations must be identical."; 662 } 663 } 665 list datastore { 666 key "name"; 667 description 668 "A datastore supported by this server. 670 Each datastore indicates which schema it supports. 672 The server MUST instantiate one entry in this list per 673 specific datastore it supports. 675 Each datstore entry with the same datastore schema SHOULD 676 reference the same schema."; 678 leaf name { 679 type ds:datastore-ref; 680 description 681 "The identity of the datastore."; 682 } 683 leaf schema { 684 type leafref { 685 path "../../schema/name"; 686 } 687 mandatory true; 688 description 689 "A reference to the schema supported by this datastore. 690 All non import-only modules of the schema are implemented 691 with their associated features and deviations."; 692 } 693 } 694 } 696 /* 697 * Top-level container 698 */ 700 container yang-library { 701 config false; 702 description 703 "Container holding the entire YANG library of this server."; 705 uses yang-library-parameters; 707 leaf checksum { 708 type string; 709 mandatory true; 710 description 711 "A server-generated checksum of the contents of the 712 'yang-library' tree. The server MUST change the value of 713 this leaf if the information represented by the 714 'yang-library' tree, except 'yang-library/checksum', has 715 changed."; 716 } 717 } 719 /* 720 * Notifications 721 */ 723 notification yang-library-update { 724 description 725 "Generated when any YANG library information on the 726 server has changed."; 728 leaf checksum { 729 type leafref { 730 path "/yanglib:yang-library/yanglib:checksum"; 731 } 732 mandatory true; 733 description 734 "Contains the YANG library checksum for the updated YANG 735 library at the time the notification is generated."; 736 } 737 } 739 /* 740 * Legacy groupings 741 */ 743 grouping module-list { 744 status deprecated; 745 description 746 "The module data structure is represented as a grouping 747 so it can be reused in configuration or another monitoring 748 data structure."; 750 grouping common-leafs { 751 status deprecated; 752 description 753 "Common parameters for YANG modules and submodules."; 755 leaf name { 756 type yang:yang-identifier; 757 status deprecated; 758 description 759 "The YANG module or submodule name."; 760 } 761 leaf revision { 762 type union { 763 type revision-identifier; 764 type string { 765 length 0; 766 } 767 } 768 status deprecated; 769 description 770 "The YANG module or submodule revision date. 771 A zero-length string is used if no revision statement 772 is present in the YANG module or submodule."; 773 } 774 } 775 grouping schema-leaf { 776 status deprecated; 777 description 778 "Common schema leaf parameter for modules and submodules."; 779 leaf schema { 780 type inet:uri; 781 description 782 "Contains a URL that represents the YANG schema 783 resource for this module or submodule. 785 This leaf will only be present if there is a URL 786 available for retrieval of the schema for this entry."; 787 } 788 } 790 list module { 791 key "name revision"; 792 status deprecated; 793 description 794 "Each entry represents one revision of one module 795 currently supported by the server."; 797 uses common-leafs { 798 status deprecated; 799 } 800 uses schema-leaf { 801 status deprecated; 802 } 804 leaf namespace { 805 type inet:uri; 806 mandatory true; 807 status deprecated; 808 description 809 "The XML namespace identifier for this module."; 810 } 811 leaf-list feature { 812 type yang:yang-identifier; 813 status deprecated; 814 description 815 "List of YANG feature names from this module that are 816 supported by the server, regardless whether they are 817 defined in the module or any included submodule."; 818 } 819 list deviation { 820 key "name revision"; 821 status deprecated; 822 description 823 "List of YANG deviation module names and revisions 824 used by this server to modify the conformance of 825 the module associated with this entry. Note that 826 the same module can be used for deviations for 827 multiple modules, so the same entry MAY appear 828 within multiple 'module' entries. 830 The deviation module MUST be present in the 'module' 831 list, with the same name and revision values. 832 The 'conformance-type' value will be 'implement' for 833 the deviation module."; 834 uses common-leafs { 835 status deprecated; 836 } 837 } 838 leaf conformance-type { 839 type enumeration { 840 enum implement { 841 description 842 "Indicates that the server implements one or more 843 protocol-accessible objects defined in the YANG module 844 identified in this entry. This includes deviation 845 statements defined in the module. 847 For YANG version 1.1 modules, there is at most one 848 module entry with conformance type 'implement' for a 849 particular module name, since YANG 1.1 requires that 850 at most one revision of a module is implemented. 852 For YANG version 1 modules, there SHOULD NOT be more 853 than one module entry for a particular module name."; 854 } 855 enum import { 856 description 857 "Indicates that the server imports reusable definitions 858 from the specified revision of the module, but does 859 not implement any protocol accessible objects from 860 this revision. 862 Multiple module entries for the same module name MAY 863 exist. This can occur if multiple modules import the 864 same module, but specify different revision-dates in 865 the import statements."; 866 } 867 } 868 mandatory true; 869 status deprecated; 870 description 871 "Indicates the type of conformance the server is claiming 872 for the YANG module identified by this entry."; 873 } 874 list submodule { 875 key "name revision"; 876 status deprecated; 877 description 878 "Each entry represents one submodule within the 879 parent module."; 880 uses common-leafs { 881 status deprecated; 882 } 883 uses schema-leaf { 884 status deprecated; 885 } 886 } 887 } 888 } 890 /* 891 * Legacy operational state data nodes 892 */ 894 container modules-state { 895 config false; 896 status deprecated; 897 description 898 "Contains YANG module monitoring information."; 900 leaf module-set-id { 901 type string; 902 mandatory true; 903 status deprecated; 904 description 905 "Contains a server-specific identifier representing 906 the current set of modules and submodules. The 907 server MUST change the value of this leaf if the 908 information represented by the 'module' list instances 909 has changed."; 910 } 912 uses module-list { 913 status deprecated; 914 } 915 } 917 /* 918 * Legacy notifications 919 */ 921 notification yang-library-change { 922 status deprecated; 923 description 924 "Generated when the set of modules and submodules supported 925 by the server has changed."; 926 leaf module-set-id { 927 type leafref { 928 path "/yanglib:modules-state/yanglib:module-set-id"; 929 } 930 mandatory true; 931 status deprecated; 932 description 933 "Contains the module-set-id value representing the 934 set of modules and submodules supported at the server 935 at the time the notification is generated."; 936 } 937 } 939 } 941 943 5. IANA Considerations 945 RFC 7895 previously registered one URI in the IETF XML registry 946 [RFC3688]. This document takes over this registration entry made by 947 RFC 7895 and changes the Registrant to the IESG according to 948 Section 4 in [RFC3688]. 950 URI: urn:ietf:params:xml:ns:yang:ietf-yang-library 952 Registrant Contact: The IESG. 954 XML: N/A, the requested URI is an XML namespace. 956 RFC 7895 previously registered one YANG module in the "YANG Module 957 Names" registry [RFC6020] as follows: 959 name: ietf-yang-library 960 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library 961 prefix: yanglib 962 reference: RFC 7895 964 This document takes over this registration entry made by RFC 7895. 966 6. Security Considerations 968 The YANG module specified in this document defines a schema for data 969 that is accessed by network management protocols such as NETCONF 970 [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the 971 secure transport layer, and the mandatory-to-implement secure 972 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 973 is HTTPS, and the mandatory-to-implement secure transport is TLS 974 [RFC5246]. 976 The NETCONF access control model [RFC6536] provides the means to 977 restrict access for particular NETCONF or RESTCONF users to a 978 preconfigured subset of all available NETCONF or RESTCONF protocol 979 operations and content. 981 Some of the readable data nodes in this YANG module may be considered 982 sensitive or vulnerable in some network environments. It is thus 983 important to control read access (e.g., via get, get-config, or 984 notification) to these data nodes. These are the subtrees and data 985 nodes and their sensitivity/vulnerability: 987 The "/yang-library" subtree of the YANG library may help an attacker 988 identify the server capabilities and server implementations with 989 known bugs since the set of YANG modules supported by a server may 990 reveal the kind of device and the manufacturer of the device. 992 Although some of this information may be available to all NETCONF 993 users via the NETCONF message (or similar messages in other 994 management protocols), this YANG module potentially exposes 995 additional details that could be of some assistance to an attacker. 996 Server vulnerabilities may be specific to particular modules, module 997 revisions, module features, or even module deviations. For example, 998 if a particular operation on a particular data node is known to cause 999 a server to crash or significantly degrade device performance, then 1000 the module list information will help an attacker identify server 1001 implementations with such a defect, in order to launch a denial-of- 1002 service attack on the device. 1004 7. Acknowledgments 1006 Contributions to this material by Andy Bierman are based upon work 1007 supported by the The Space & Terrestrial Communications Directorate 1008 (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings 1009 and conclusions or recommendations expressed in this material are 1010 those of the author(s) and do not necessarily reflect the views of 1011 The Space & Terrestrial Communications Directorate (S&TCD). 1013 8. References 1015 8.1. Normative References 1017 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1018 Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/ 1019 RFC2119, March 1997, . 1022 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1023 DOI 10.17487/RFC3688, January 2004, . 1026 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1027 (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ 1028 RFC5246, August 2008, . 1031 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1032 the Network Configuration Protocol (NETCONF)", RFC 6020, 1033 DOI 10.17487/RFC6020, October 2010, . 1036 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1037 and A. Bierman, Ed., "Network Configuration Protocol 1038 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1039 . 1041 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1042 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1043 . 1045 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1046 Protocol (NETCONF) Access Control Model", RFC 6536, DOI 1047 10.17487/RFC6536, March 2012, . 1050 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 1051 6991, DOI 10.17487/RFC6991, July 2013, . 1054 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1055 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1056 . 1058 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1059 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1060 . 1062 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1063 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1064 May 2017, . 1066 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1067 and R. Wilton, "Network Management Datastore Architecture 1068 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1069 . 1071 8.2. Informative References 1073 [I-D.ietf-netconf-nmda-netconf] 1074 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1075 and R. Wilton, "NETCONF Extensions to Support the Network 1076 Management Datastore Architecture", draft-ietf-netconf- 1077 nmda-netconf-04 (work in progress), March 2018. 1079 [I-D.ietf-netconf-nmda-restconf] 1080 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1081 and R. Wilton, "RESTCONF Extensions to Support the Network 1082 Management Datastore Architecture", draft-ietf-netconf- 1083 nmda-restconf-03 (work in progress), March 2018. 1085 [I-D.ietf-netmod-schema-mount] 1086 Bjorklund, M. and L. Lhotka, "YANG Schema Mount", draft- 1087 ietf-netmod-schema-mount-09 (work in progress), March 1088 2018. 1090 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1091 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1092 . 1094 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 1095 Base Notifications", RFC 6470, DOI 10.17487/RFC6470, 1096 February 2012, . 1098 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 1099 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 1100 . 1102 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1103 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1104 . 1106 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 1107 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 1108 . 1110 [RFC8344] Bjorklund, M., "A YANG Data Model for IP Management", RFC 1111 8344, DOI 10.17487/RFC8344, March 2018, . 1114 [RFC8345] Clemm, A., Medved, J., Varga, R., Bahadur, N., 1115 Ananthakrishnan, H., and X. Liu, "A YANG Data Model for 1116 Network Topologies", RFC 8345, DOI 10.17487/RFC8345, March 1117 2018, . 1119 [RFC8348] Bierman, A., Bjorklund, M., Dong, J., and D. Romascanu, "A 1120 YANG Data Model for Hardware Management", RFC 8348, DOI 1121 10.17487/RFC8348, March 2018, . 1124 [RFC8349] Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for 1125 Routing Management (NMDA Version)", RFC 8349, DOI 1126 10.17487/RFC8349, March 2018, . 1129 Appendix A. Summary of Changes from RFC 7895 1131 This document updates [RFC7895] in the following ways: 1133 o Renamed document title from "YANG Module Library" to "YANG 1134 Library". 1136 o Added a new top-level "/yang-library" container to hold the entire 1137 YANG library providing information about module sets, schemas, and 1138 datastores. 1140 o Refactored the "/modules-state" container into a new 1141 "/yang-library/module-set" list. 1143 o Added a new "/yang-library/schema" list and a new "/yang-library/ 1144 datastore" list. 1146 o Added a set of new groupings as replacements for the deprecated 1147 groupings. 1149 o Added a "yang-library-update" notification as a replacement for 1150 the deprecated "yang-library-change" notification. 1152 o Deprecated the "/modules-state" tree. 1154 o Deprecated the "/module-list" grouping. 1156 o Deprecated the "/yang-library-change" notification. 1158 Appendix B. Example YANG Library Instance for a Basic Server 1160 The following example shows the YANG Library of a basic server 1161 implementing the "ietf-interfaces" [RFC8343] and "ietf-ip" [RFC8344] 1162 modules in the , , and datastores and 1163 the "ietf-hardware" [RFC8348] module in the datastore. 1165 Newlines in leaf values are added for formatting reasons. 1167 1171 1172 config-modules 1173 1174 ietf-interfaces 1175 2018-01-09 1176 1177 urn:ietf:params:xml:ns:yang:ietf-interfaces 1178 1179 1180 1181 ietf-ip 1182 2018-01-09 1183 1184 urn:ietf:params:xml:ns:yang:ietf-ip 1185 1186 1187 1188 ietf-yang-types 1189 2013-07-15 1190 1191 urn:ietf:params:xml:ns:yang:ietf-yang-types 1192 1193 1194 1195 ietf-inet-types 1196 2013-07-15 1197 1198 urn:ietf:params:xml:ns:yang:ietf-inet-types 1199 1200 1201 1203 1204 state-modules 1205 1206 ietf-hardware 1207 2018-12-18 1208 1209 urn:ietf:params:xml:ns:yang:ietf-hardware 1210 1211 1212 1213 ietf-inet-types 1214 2013-07-15 1215 1216 urn:ietf:params:xml:ns:yang:ietf-inet-types 1217 1218 1219 1220 ietf-yang-types 1221 2013-07-15 1222 1223 urn:ietf:params:xml:ns:yang:ietf-yang-types 1224 1225 1226 1227 iana-hardware 1228 2017-12-18 1229 1230 urn:ietf:params:xml:ns:yang:iana-hardware 1231 1233 1234 1236 1237 config-schema 1238 config-modules 1239 1240 1241 state-schema 1242 config-modules 1243 state-modules 1244 1246 1247 ds:startup 1248 config-schema 1249 1250 1251 ds:running 1252 config-schema 1253 1254 1255 ds:operational 1256 state-schema 1257 1259 75a43df9bd56b92aacc156a2958fbe12312fb285 1260 1262 Appendix C. Example YANG Library Instance for an Advanced Server 1264 The following example extends the preceding Basic Server YANG Library 1265 example, by using modules from [RFC8345] and [RFC8349], to illustrate 1266 a slightly more advanced server that: 1268 o Has a module with features only enabled in ; the 1269 "ietf-routing module" is supported in , , and 1270 , but the "multiple-ribs" and "router-id" features 1271 are only enabled in . Hence the "router-id" leaf may 1272 be read but not configured. 1274 o Supports a dynamic configuration datastore "example-ds-ephemeral", 1275 with only the "ietf-network" and "ietf-network-topology" modules 1276 configurable via a notional dynamic configuration protocol. 1278 o Shows an example of datastore specific deviations. The module 1279 "example-vendor-hardware-deviations" is included in the schema for 1280 to remove data nodes that cannot be supported by the 1281 server. 1283 o Shows how module-sets can be used to organize related modules 1284 together. 1286 1291 1292 config-state-modules 1293 1294 ietf-interfaces 1295 2018-01-09 1296 1297 urn:ietf:params:xml:ns:yang:ietf-interfaces 1298 1299 1300 1301 ietf-ip 1302 2018-01-09 1303 1304 urn:ietf:params:xml:ns:yang:ietf-ip 1305 1306 1307 1308 ietf-routing 1309 2018-01-25 1310 1311 urn:ietf:params:xml:ns:yang:ietf-routing 1312 1313 1314 1315 ietf-yang-types 1316 2013-07-15 1317 1318 urn:ietf:params:xml:ns:yang:ietf-yang-types 1319 1320 1321 1322 ietf-inet-types 1323 2013-07-15 1324 1325 urn:ietf:params:xml:ns:yang:ietf-inet-types 1326 1327 1329 1331 1332 config-only-modules 1333 1334 ietf-routing 1335 2018-01-25 1336 1337 urn:ietf:params:xml:ns:yang:ietf-routing 1338 1339 1340 1342 1343 dynamic-config-state-modules 1344 1345 ietf-network 1346 2017-12-18 1347 1348 urn:ietf:params:xml:ns:yang:ietf-network 1349 1350 1351 1352 ietf-network-topology 1353 2017-12-18 1354 1355 urn:ietf:params:xml:ns:yang:ietf-network-topology 1356 1357 1358 1359 ietf-inet-types 1360 2013-07-15 1361 1362 urn:ietf:params:xml:ns:yang:ietf-inet-types 1363 1364 1365 1367 1368 state-only-modules 1369 1370 ietf-hardware 1371 2018-12-18 1372 1373 urn:ietf:params:xml:ns:yang:ietf-hardware 1374 1375 example-vendor-hardware-deviations 1376 1377 1378 ietf-routing 1379 2018-01-25 1380 1381 urn:ietf:params:xml:ns:yang:ietf-routing 1382 1383 multiple-ribs 1384 router-id 1385 1386 1387 example-vendor-hardware-deviations 1388 2018-01-31 1389 1390 urn:example:example-vendor-hardware-deviations 1391 1392 1393 1394 ietf-inet-types 1395 2013-07-15 1396 1397 urn:ietf:params:xml:ns:yang:ietf-inet-types 1398 1399 1400 1401 ietf-yang-types 1402 2013-07-15 1403 1404 urn:ietf:params:xml:ns:yang:ietf-yang-types 1405 1406 1407 1408 iana-hardware 1409 2017-12-18 1410 1411 urn:ietf:params:xml:ns:yang:iana-hardware 1412 1413 1414 1416 1417 config-schema 1418 config-state-modules 1419 config-only-modules 1420 1421 1422 dynamic-config-schema 1423 dynamic-config-state-modules 1424 1425 1426 state-schema 1427 config-state-modules 1428 dynamic-config-state-modules 1429 state-only-modules 1430 1432 1433 ds:startup 1434 config-schema 1435 1436 1437 ds:running 1438 config-schema 1439 1440 1441 ex-ds-eph:ds-ephemeral 1442 dynamic-config-schema 1443 1444 1445 ds:operational 1446 state-schema 1447 1449 14782ab9bd56b92aacc156a2958fbe12312fb285 1450 1452 Authors' Addresses 1454 Andy Bierman 1455 YumaWorks 1457 Email: andy@yumaworks.com 1459 Martin Bjorklund 1460 Tail-f Systems 1462 Email: mbj@tail-f.com 1464 Juergen Schoenwaelder 1465 Jacobs University 1467 Email: j.schoenwaelder@jacobs-university.de 1468 Kent Watsen 1469 Juniper Networks 1471 Email: kwatsen@juniper.net 1473 Robert Wilton 1474 Cisco Systems 1476 Email: rwilton@cisco.com