idnits 2.17.1 draft-ietf-netconf-rfc7895bis-07.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 271 has weird spacing: '...mespace ine...' == Line 282 has weird spacing: '...mespace ine...' == Line 294 has weird spacing: '...tent-id str...' -- The document date (October 17, 2018) is 2015 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) == Unused Reference: 'I-D.ietf-netconf-nmda-restconf' is defined on line 1070, but no explicit reference was found in the text == Outdated reference: A later version (-08) exists of draft-ietf-netconf-nmda-netconf-07 == Outdated reference: A later version (-12) exists of draft-ietf-netmod-schema-mount-11 -- Obsolete informational reference (is this intentional?): RFC 7895 (Obsoleted by RFC 8525) Summary: 0 errors (**), 0 flaws (~~), 7 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: April 20, 2019 J. Schoenwaelder 7 Jacobs University 8 K. Watsen 9 Juniper Networks 10 R. Wilton 11 Cisco Systems 12 October 17, 2018 14 YANG Library 15 draft-ietf-netconf-rfc7895bis-07 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 April 20, 2019. 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 . . . . . . . . . . . . . . . . . . . 5 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 configuration datastores and for which config false data nodes are 107 returned via a 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 1.1. Terminology 123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 125 "OPTIONAL" in this document are to be interpreted as described in BCP 126 14 [RFC2119] [RFC8174] when, and only when, they appear in all 127 capitals, as shown here. 129 The following terms are defined in [RFC7950]: 131 o module 133 o submodule 135 o data node 137 This document uses the phrase "implementing a module" as defined in 138 [RFC7950] Section 5.6.5. 140 The following terms are defined in [RFC8342]: 142 o datastore 144 o datastore schema 146 o configuration 148 o configuration datastore 150 o conventional configuration 152 o conventional configuration datastore 154 o operational state 156 o operational state datastore 158 o dynamic configuration datastore 160 o client and server 162 The following terms are used within this document: 164 o YANG library: A collection of YANG modules, submodules, 165 datastores, and datastore schemas used by a server. 167 o YANG library content identifier: A server-generated identifier of 168 the contents of the YANG library. 170 Tree diagrams used in this document use the notation defined in 171 [RFC8340]. 173 2. Objectives 175 The following information is needed by a client application (for each 176 YANG module in the library) to fully utilize the YANG data modeling 177 language: 179 o name: The name of the YANG module. 181 o revision: If defined in the YANG module or submodule, the revision 182 is derived from the most recent revision statement within the 183 module or submodule. 185 o submodule list: The name, and if defined, revision of each 186 submodule used by the module must be identified. 188 o feature list: The name of each YANG feature supported by the 189 server, in a given datastore schema, must be identified. 191 o deviation list: The name of each YANG module with deviation 192 statements affecting a given YANG module, in a given datastore 193 schema, must be identified. 195 In addition, the following information is needed by a client 196 application for each datastore supported by a server: 198 o identity: The YANG identity for the datastore. 200 o schema: The schema (i.e., the set of modules) implemented by the 201 datastore. 203 In order to select one out of several possible data model designs, 204 the following criteria were used: 206 1. The information must be efficient for a client to consume. Since 207 the size of the YANG library can be quite large, it should be 208 possible for clients to cache the YANG library information. 210 2. A dynamic configuration datastore must be able to implement a 211 module or feature that is not implemented in the conventional 212 configuration datastores. 214 3. It must be possible to not implement a module or feature in 215 , even if it is implemented in some other datastore. 216 This is required for transition purposes; a server that wants to 217 implement should not have to implement all modules 218 at once. 220 4. A given module can only be implemented in one revision in all 221 datastores. If a module is implemented in more than one 222 datastore, the same revision is implemented in all these 223 datastores. 225 5. Multiple revisions can be used for import, if import-by revision 226 is used. 228 6. It must be possible to use the YANG library by schema mount 229 [I-D.ietf-netmod-schema-mount]. 231 3. YANG Library Data Model 233 The "ietf-yang-library" YANG module provides information about the 234 modules, submodules, datastores, and datastore schemas supported by a 235 server. All data nodes in "ietf-yang-library" are "config false", 236 and thus only accessible in the operational state datastore. 238 +-----------+ 239 | datastore | 240 +-----------+ 241 | 242 | has a 243 V 244 +-----------+ +--------+ +------------+ 245 | datastore | union of | module | consists of | modules + | 246 | schema |----------->| set |--------------->| submodules | 247 +-----------+ +--------+ +------------+ 249 Figure 1 251 The conceptual model of the YANG library is depicted in Figure 1. 252 Following the NMDA, every datastore has an associated datastore 253 schema. A datastore schema is a union of module sets and every 254 module set is a collection of modules and submodules, including the 255 modules and submodules used for imports. Note that multiple 256 datastores may refer to the same datastore schema. Furthermore, it 257 is possible that individual datastore schemas share module sets. A 258 common use case is the operational state datastore schema which is a 259 superset of the schema used by conventional configuration datastores. 261 Below is the YANG Tree Diagram for the "ietf-yang-library" module, 262 excluding the deprecated "modules-state" tree: 264 module: ietf-yang-library 265 +--ro yang-library 266 +--ro module-set* [name] 267 | +--ro name string 268 | +--ro module* [name] 269 | | +--ro name yang:yang-identifier 270 | | +--ro revision? revision-identifier 271 | | +--ro namespace inet:uri 272 | | +--ro location* inet:uri 273 | | +--ro submodule* [name] 274 | | | +--ro name yang:yang-identifier 275 | | | +--ro revision? revision-identifier 276 | | | +--ro location* inet:uri 277 | | +--ro feature* yang:yang-identifier 278 | | +--ro deviation* -> ../../module/name 279 | +--ro import-only-module* [name revision] 280 | +--ro name yang:yang-identifier 281 | +--ro revision union 282 | +--ro namespace inet:uri 283 | +--ro location* inet:uri 284 | +--ro submodule* [name] 285 | +--ro name yang:yang-identifier 286 | +--ro revision? revision-identifier 287 | +--ro location* inet:uri 288 +--ro schema* [name] 289 | +--ro name string 290 | +--ro module-set* -> ../../module-set/name 291 +--ro datastore* [name] 292 | +--ro name ds:datastore-ref 293 | +--ro schema -> ../../schema/name 294 +--ro content-id string 296 notifications: 297 +---n yang-library-update 298 +--ro content-id -> /yang-library/content-id 300 The "/yang-library" container holds the entire YANG library. The 301 container has the following child nodes: 303 o The "/yang-library/module-set" contains entries representing 304 module sets. The list "/yang-library/module-set/module" 305 enumerates the modules that belong to the module set. A module is 306 listed together with its submodules (if any), a set of features, 307 and any deviation modules. The list "/yang-library/module-set/ 308 import-only-module" lists all modules (and their submodules) used 309 only for imports. The assignment of a module to a module-set is 310 at the server's discretion. This revision of the YANG library 311 attaches no semantics as to which module-set a module is listed 312 in. 314 o The "/yang-library/schema" list contains an entry for each 315 datastore schema supported by the server. All conventional 316 configuration datastores use the same "schema" list entry. A 317 dynamic configuration datastore may use a different datastore 318 schema from the conventional configuration datastores, and hence 319 may require a separate "schema" entry. A "schema" entry has a 320 leaf-list of references to entries in the "module-set" list. The 321 schema consists of the union of all modules in all referenced 322 module sets. 324 o The "/yang-library/datastore" list contains one entry for each 325 datastore supported by the server, and it identifies the datastore 326 schema associated with a datastore via a reference to an entry in 327 the "schema" list. Each supported conventional configuration 328 datastore has a separate entry, pointing to the same "schema" list 329 element. 331 o The "/yang-library/content-id" leaf contains the YANG library 332 content identifier, which is an implementation-specific identifier 333 representing the current information in the YANG library on a 334 specific server. The value of this leaf MUST change whenever the 335 information in the YANG library changes. There is no requirement 336 that the same information always results in the same "content-id" 337 value. This leaf allows a client to fetch all schema information 338 once, cache it, and only refetch it if the value of this leaf has 339 been changed. If the value of this leaf changes, the server also 340 generates a "yang-library-update" notification. 342 Note that for a NETCONF server implementing the NETCONF extensions to 343 support the NMDA [I-D.ietf-netconf-nmda-netconf], a change of the 344 YANG library content identifier results in a new value for the :yang- 345 library:1.1 capability defined in [I-D.ietf-netconf-nmda-netconf]. 346 Thus, if such a server implements NETCONF notifications [RFC5277], 347 and the notification "netconf-capability-change" [RFC6470], a 348 "netconf-capability-change" notification is generated whenever the 349 YANG library content identifier changes. 351 4. YANG Library YANG Module 353 The "ietf-yang-library" YANG module imports definitions from 354 "ietf-yang-types" and "ietf-inet-types" defined in [RFC6991] and from 355 "ietf-datastores" defined in [RFC8342]. While the YANG module is 356 defined using YANG version 1.1, the YANG library supports the YANG 357 modules written in any version of YANG. 359 RFC Ed.: update the date below with the date of RFC publication and 360 remove this note. 362 file "ietf-yang-library@2018-10-16.yang" 364 module ietf-yang-library { 365 yang-version 1.1; 366 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-library"; 367 prefix "yanglib"; 369 import ietf-yang-types { 370 prefix yang; 371 reference "RFC 6991: Common YANG Data Types."; 372 } 373 import ietf-inet-types { 374 prefix inet; 375 reference "RFC 6991: Common YANG Data Types."; 376 } 377 import ietf-datastores { 378 prefix ds; 379 reference "RFC 8342: Network Management Datastore Architecture."; 380 } 382 organization 383 "IETF NETCONF (Network Configuration) Working Group"; 385 contact 386 "WG Web: 387 WG List: 389 Author: Andy Bierman 390 392 Author: Martin Bjorklund 393 395 Author: Juergen Schoenwaelder 396 398 Author: Kent Watsen 399 401 Author: Rob Wilton 402 "; 404 description 405 "This module provides information about the YANG modules, 406 datastores, and datastore schemas used by a network 407 management server. 409 Copyright (c) 2018 IETF Trust and the persons identified as 410 authors of the code. All rights reserved. 412 Redistribution and use in source and binary forms, with or 413 without modification, is permitted pursuant to, and subject 414 to the license terms contained in, the Simplified BSD License 415 set forth in Section 4.c of the IETF Trust's Legal Provisions 416 Relating to IETF Documents 417 (http://trustee.ietf.org/license-info). 419 This version of this YANG module is part of RFC XXXX; see 420 the RFC itself for full legal notices."; 422 // RFC Ed.: update the date below with the date of RFC publication 423 // and remove this note. 424 // RFC Ed.: replace XXXX with actual RFC number and remove this 425 // note. 426 revision 2018-10-16 { 427 description 428 "Added support for multiple datastores according to the 429 Network Management Datastore Architecture (NMDA)."; 430 reference 431 "RFC XXXX: YANG Library."; 432 } 433 revision 2016-04-09 { 434 description 435 "Initial revision."; 436 reference 437 "RFC 7895: YANG Module Library."; 438 } 440 /* 441 * Typedefs 442 */ 444 typedef revision-identifier { 445 type string { 446 pattern '\d{4}-\d{2}-\d{2}'; 447 } 448 description 449 "Represents a specific date in YYYY-MM-DD format."; 450 } 452 /* 453 * Groupings 454 */ 456 grouping module-identification-leafs { 457 description 458 "Parameters for identifying YANG modules and submodules."; 460 leaf name { 461 type yang:yang-identifier; 462 mandatory true; 463 description 464 "The YANG module or submodule name."; 465 } 466 leaf revision { 467 type revision-identifier; 468 description 469 "The YANG module or submodule revision date. If no revision 470 statement is present in the YANG module or submodule, this 471 leaf is not instantiated."; 472 } 473 } 475 grouping location-leaf-list { 476 description 477 "Common location leaf list parameter for modules and 478 submodules."; 480 leaf-list location { 481 type inet:uri; 482 description 483 "Contains a URL that represents the YANG schema 484 resource for this module or submodule. 486 This leaf will only be present if there is a URL 487 available for retrieval of the schema for this entry."; 488 } 489 } 491 grouping module-implementation-parameters { 492 description 493 "Parameters for describing the implementation of a module."; 495 leaf-list feature { 496 type yang:yang-identifier; 497 description 498 "List of all YANG feature names from this module that are 499 supported by the server, regardless whether they are defined 500 in the module or any included submodule."; 501 } 502 leaf-list deviation { 503 type leafref { 504 path "../../module/name"; 505 } 506 description 507 "List of all YANG deviation modules used by this server to 508 modify the conformance of the module associated with this 509 entry. Note that the same module can be used for deviations 510 for multiple modules, so the same entry MAY appear within 511 multiple 'module' entries. 513 This reference MUST NOT (directly or indirectly) 514 refer to the module being deviated. 516 Robust clients may want to make sure that they handle a 517 situation where a module deviates itself (directly or 518 indirectly) gracefully."; 519 } 520 } 522 grouping module-set-parameters { 523 description 524 "A set of parameters that describe a module set."; 526 leaf name { 527 type string; 528 description 529 "An arbitrary name of the module set."; 530 } 531 list module { 532 key "name"; 533 description 534 "An entry in this list represents a module implemented by the 535 server, as per RFC 7950 section 5.6.5, with a particular set 536 of supported features and deviations."; 537 reference 538 "RFC 7950: The YANG 1.1 Data Modeling Language."; 540 uses module-identification-leafs; 542 leaf namespace { 543 type inet:uri; 544 mandatory true; 545 description 546 "The XML namespace identifier for this module."; 547 } 549 uses location-leaf-list; 551 list submodule { 552 key "name"; 553 description 554 "Each entry represents one submodule within the 555 parent module."; 556 uses module-identification-leafs; 557 uses location-leaf-list; 558 } 560 uses module-implementation-parameters; 561 } 562 list import-only-module { 563 key "name revision"; 564 description 565 "An entry in this list indicates that the server imports 566 reusable definitions from the specified revision of the 567 module, but does not implement any protocol accessible 568 objects from this revision. 570 Multiple entries for the same module name MAY exist. This 571 can occur if multiple modules import the same module, but 572 specify different revision-dates in the import statements."; 574 leaf name { 575 type yang:yang-identifier; 576 description 577 "The YANG module name."; 578 } 579 leaf revision { 580 type union { 581 type revision-identifier; 582 type string { 583 length 0; 584 } 585 } 586 description 587 "The YANG module revision date. 588 A zero-length string is used if no revision statement 589 is present in the YANG module."; 590 } 591 leaf namespace { 592 type inet:uri; 593 mandatory true; 594 description 595 "The XML namespace identifier for this module."; 596 } 598 uses location-leaf-list; 599 list submodule { 600 key "name"; 601 description 602 "Each entry represents one submodule within the 603 parent module."; 605 uses module-identification-leafs; 606 uses location-leaf-list; 607 } 608 } 609 } 611 grouping yang-library-parameters { 612 description 613 "The YANG library data structure is represented as a grouping 614 so it can be reused in configuration or another monitoring 615 data structure."; 617 list module-set { 618 key name; 619 description 620 "A set of modules that may be used by one or more schemas. 622 A module set does not have to be referentially complete, 623 i.e., it may define modules that contain import statements 624 for other modules not included in the module set."; 626 uses module-set-parameters; 627 } 629 list schema { 630 key "name"; 631 description 632 "A datastore schema that may be used by one or more 633 datastores. 635 The schema must be valid and referentially complete, i.e., 636 it must contain modules to satisfy all used import 637 statements for all modules specified in the schema."; 639 leaf name { 640 type string; 641 description 642 "An arbitrary name of the schema."; 643 } 644 leaf-list module-set { 645 type leafref { 646 path "../../module-set/name"; 648 } 649 description 650 "A set of module-sets that are included in this schema. 651 If a non import-only module appears in multiple module 652 sets, then the module revision and the associated features 653 and deviations must be identical."; 654 } 655 } 657 list datastore { 658 key "name"; 659 description 660 "A datastore supported by this server. 662 Each datastore indicates which schema it supports. 664 The server MUST instantiate one entry in this list per 665 specific datastore it supports. 667 Each datstore entry with the same datastore schema SHOULD 668 reference the same schema."; 670 leaf name { 671 type ds:datastore-ref; 672 description 673 "The identity of the datastore."; 674 } 675 leaf schema { 676 type leafref { 677 path "../../schema/name"; 678 } 679 mandatory true; 680 description 681 "A reference to the schema supported by this datastore. 682 All non import-only modules of the schema are implemented 683 with their associated features and deviations."; 684 } 685 } 686 } 688 /* 689 * Top-level container 690 */ 692 container yang-library { 693 config false; 694 description 695 "Container holding the entire YANG library of this server."; 697 uses yang-library-parameters; 699 leaf content-id { 700 type string; 701 mandatory true; 702 description 703 "A server-generated identifier of the contents of the 704 'yang-library' tree. The server MUST change the value of 705 this leaf if the information represented by the 706 'yang-library' tree, except 'yang-library/content-id', has 707 changed."; 708 } 709 } 711 /* 712 * Notifications 713 */ 715 notification yang-library-update { 716 description 717 "Generated when any YANG library information on the 718 server has changed."; 720 leaf content-id { 721 type leafref { 722 path "/yanglib:yang-library/yanglib:content-id"; 723 } 724 mandatory true; 725 description 726 "Contains the YANG library content identifier for the updated 727 YANG library at the time the notification is generated."; 728 } 729 } 731 /* 732 * Legacy groupings 733 */ 735 grouping module-list { 736 status deprecated; 737 description 738 "The module data structure is represented as a grouping 739 so it can be reused in configuration or another monitoring 740 data structure."; 742 grouping common-leafs { 743 status deprecated; 744 description 745 "Common parameters for YANG modules and submodules."; 747 leaf name { 748 type yang:yang-identifier; 749 status deprecated; 750 description 751 "The YANG module or submodule name."; 752 } 753 leaf revision { 754 type union { 755 type revision-identifier; 756 type string { 757 length 0; 758 } 759 } 760 status deprecated; 761 description 762 "The YANG module or submodule revision date. 763 A zero-length string is used if no revision statement 764 is present in the YANG module or submodule."; 765 } 766 } 767 grouping schema-leaf { 768 status deprecated; 769 description 770 "Common schema leaf parameter for modules and submodules."; 771 leaf schema { 772 type inet:uri; 773 description 774 "Contains a URL that represents the YANG schema 775 resource for this module or submodule. 777 This leaf will only be present if there is a URL 778 available for retrieval of the schema for this entry."; 779 } 780 } 782 list module { 783 key "name revision"; 784 status deprecated; 785 description 786 "Each entry represents one revision of one module 787 currently supported by the server."; 789 uses common-leafs { 790 status deprecated; 791 } 792 uses schema-leaf { 793 status deprecated; 794 } 796 leaf namespace { 797 type inet:uri; 798 mandatory true; 799 status deprecated; 800 description 801 "The XML namespace identifier for this module."; 802 } 803 leaf-list feature { 804 type yang:yang-identifier; 805 status deprecated; 806 description 807 "List of YANG feature names from this module that are 808 supported by the server, regardless whether they are 809 defined in the module or any included submodule."; 810 } 811 list deviation { 812 key "name revision"; 813 status deprecated; 814 description 815 "List of YANG deviation module names and revisions 816 used by this server to modify the conformance of 817 the module associated with this entry. Note that 818 the same module can be used for deviations for 819 multiple modules, so the same entry MAY appear 820 within multiple 'module' entries. 822 The deviation module MUST be present in the 'module' 823 list, with the same name and revision values. 824 The 'conformance-type' value will be 'implement' for 825 the deviation module."; 826 uses common-leafs { 827 status deprecated; 828 } 829 } 830 leaf conformance-type { 831 type enumeration { 832 enum implement { 833 description 834 "Indicates that the server implements one or more 835 protocol-accessible objects defined in the YANG module 836 identified in this entry. This includes deviation 837 statements defined in the module. 839 For YANG version 1.1 modules, there is at most one 840 module entry with conformance type 'implement' for a 841 particular module name, since YANG 1.1 requires that 842 at most one revision of a module is implemented. 844 For YANG version 1 modules, there SHOULD NOT be more 845 than one module entry for a particular module name."; 846 } 847 enum import { 848 description 849 "Indicates that the server imports reusable definitions 850 from the specified revision of the module, but does 851 not implement any protocol accessible objects from 852 this revision. 854 Multiple module entries for the same module name MAY 855 exist. This can occur if multiple modules import the 856 same module, but specify different revision-dates in 857 the import statements."; 858 } 859 } 860 mandatory true; 861 status deprecated; 862 description 863 "Indicates the type of conformance the server is claiming 864 for the YANG module identified by this entry."; 865 } 866 list submodule { 867 key "name revision"; 868 status deprecated; 869 description 870 "Each entry represents one submodule within the 871 parent module."; 872 uses common-leafs { 873 status deprecated; 874 } 875 uses schema-leaf { 876 status deprecated; 877 } 878 } 879 } 880 } 882 /* 883 * Legacy operational state data nodes 884 */ 886 container modules-state { 887 config false; 888 status deprecated; 889 description 890 "Contains YANG module monitoring information."; 892 leaf module-set-id { 893 type string; 894 mandatory true; 895 status deprecated; 896 description 897 "Contains a server-specific identifier representing 898 the current set of modules and submodules. The 899 server MUST change the value of this leaf if the 900 information represented by the 'module' list instances 901 has changed."; 902 } 904 uses module-list { 905 status deprecated; 906 } 907 } 909 /* 910 * Legacy notifications 911 */ 913 notification yang-library-change { 914 status deprecated; 915 description 916 "Generated when the set of modules and submodules supported 917 by the server has changed."; 918 leaf module-set-id { 919 type leafref { 920 path "/yanglib:modules-state/yanglib:module-set-id"; 921 } 922 mandatory true; 923 status deprecated; 924 description 925 "Contains the module-set-id value representing the 926 set of modules and submodules supported at the server 927 at the time the notification is generated."; 928 } 929 } 931 } 933 935 5. IANA Considerations 937 RFC 7895 previously registered one URI in the IETF XML registry 938 [RFC3688]. This document takes over this registration entry made by 939 RFC 7895 and changes the Registrant to the IESG according to 940 Section 4 in [RFC3688]. 942 URI: urn:ietf:params:xml:ns:yang:ietf-yang-library 944 Registrant Contact: The IESG. 946 XML: N/A, the requested URI is an XML namespace. 948 RFC 7895 previously registered one YANG module in the "YANG Module 949 Names" registry [RFC6020] as follows: 951 name: ietf-yang-library 952 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library 953 prefix: yanglib 954 reference: RFC 7895 956 This document takes over this registration entry made by RFC 7895. 958 6. Security Considerations 960 The YANG module specified in this document defines a schema for data 961 that is accessed by network management protocols such as NETCONF 962 [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the 963 secure transport layer, and the mandatory-to-implement secure 964 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer 965 is HTTPS, and the mandatory-to-implement secure transport is TLS 966 [RFC8446]. 968 The NETCONF access control model [RFC8341] provides the means to 969 restrict access for particular NETCONF or RESTCONF users to a 970 preconfigured subset of all available NETCONF or RESTCONF protocol 971 operations and content. 973 Some of the readable data nodes in this YANG module may be considered 974 sensitive or vulnerable in some network environments. It is thus 975 important to control read access (e.g., via get, get-config, or 976 notification) to these data nodes. These are the subtrees and data 977 nodes and their sensitivity/vulnerability: 979 The "/yang-library" subtree of the YANG library may help an attacker 980 identify the server capabilities and server implementations with 981 known bugs since the set of YANG modules supported by a server may 982 reveal the kind of device and the manufacturer of the device. 984 Although some of this information may be available to all NETCONF 985 users via the NETCONF message (or similar messages in other 986 management protocols), this YANG module potentially exposes 987 additional details that could be of some assistance to an attacker. 988 Server vulnerabilities may be specific to particular modules, module 989 revisions, module features, or even module deviations. For example, 990 if a particular operation on a particular data node is known to cause 991 a server to crash or significantly degrade device performance, then 992 the module list information will help an attacker identify server 993 implementations with such a defect, in order to launch a denial-of- 994 service attack on the device. 996 7. Acknowledgments 998 Contributions to this material by Andy Bierman are based upon work 999 supported by the The Space & Terrestrial Communications Directorate 1000 (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings 1001 and conclusions or recommendations expressed in this material are 1002 those of the author(s) and do not necessarily reflect the views of 1003 The Space & Terrestrial Communications Directorate (S&TCD). 1005 8. References 1007 8.1. Normative References 1009 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1010 Requirement Levels", BCP 14, RFC 2119, 1011 DOI 10.17487/RFC2119, March 1997, . 1014 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1015 DOI 10.17487/RFC3688, January 2004, . 1018 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1019 the Network Configuration Protocol (NETCONF)", RFC 6020, 1020 DOI 10.17487/RFC6020, October 2010, . 1023 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1024 and A. Bierman, Ed., "Network Configuration Protocol 1025 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1026 . 1028 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1029 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 1030 . 1032 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1033 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1034 . 1036 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1037 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1038 . 1040 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1041 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 1042 . 1044 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1045 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1046 May 2017, . 1048 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration 1049 Access Control Model", STD 91, RFC 8341, 1050 DOI 10.17487/RFC8341, March 2018, . 1053 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1054 and R. Wilton, "Network Management Datastore Architecture 1055 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1056 . 1058 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1059 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1060 . 1062 8.2. Informative References 1064 [I-D.ietf-netconf-nmda-netconf] 1065 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1066 and R. Wilton, "NETCONF Extensions to Support the Network 1067 Management Datastore Architecture", draft-ietf-netconf- 1068 nmda-netconf-07 (work in progress), October 2018. 1070 [I-D.ietf-netconf-nmda-restconf] 1071 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1072 and R. Wilton, "RESTCONF Extensions to Support the Network 1073 Management Datastore Architecture", draft-ietf-netconf- 1074 nmda-restconf-05 (work in progress), October 2018. 1076 [I-D.ietf-netmod-schema-mount] 1077 Bjorklund, M. and L. Lhotka, "YANG Schema Mount", draft- 1078 ietf-netmod-schema-mount-11 (work in progress), August 1079 2018. 1081 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1082 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1083 . 1085 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 1086 Base Notifications", RFC 6470, DOI 10.17487/RFC6470, 1087 February 2012, . 1089 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 1090 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 1091 . 1093 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1094 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1095 . 1097 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 1098 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 1099 . 1101 [RFC8344] Bjorklund, M., "A YANG Data Model for IP Management", 1102 RFC 8344, DOI 10.17487/RFC8344, March 2018, 1103 . 1105 [RFC8345] Clemm, A., Medved, J., Varga, R., Bahadur, N., 1106 Ananthakrishnan, H., and X. Liu, "A YANG Data Model for 1107 Network Topologies", RFC 8345, DOI 10.17487/RFC8345, March 1108 2018, . 1110 [RFC8348] Bierman, A., Bjorklund, M., Dong, J., and D. Romascanu, "A 1111 YANG Data Model for Hardware Management", RFC 8348, 1112 DOI 10.17487/RFC8348, March 2018, . 1115 [RFC8349] Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for 1116 Routing Management (NMDA Version)", RFC 8349, 1117 DOI 10.17487/RFC8349, March 2018, . 1120 Appendix A. Summary of Changes from RFC 7895 1122 This document updates [RFC7895] in the following ways: 1124 o Renamed document title from "YANG Module Library" to "YANG 1125 Library". 1127 o Added a new top-level "/yang-library" container to hold the entire 1128 YANG library providing information about module sets, schemas, and 1129 datastores. 1131 o Refactored the "/modules-state" container into a new 1132 "/yang-library/module-set" list. 1134 o Added a new "/yang-library/schema" list and a new "/yang-library/ 1135 datastore" list. 1137 o Added a set of new groupings as replacements for the deprecated 1138 groupings. 1140 o Added a "yang-library-update" notification as a replacement for 1141 the deprecated "yang-library-change" notification. 1143 o Deprecated the "/modules-state" tree. 1145 o Deprecated the "/module-list" grouping. 1147 o Deprecated the "/yang-library-change" notification. 1149 Appendix B. Example YANG Library Instance for a Basic Server 1151 The following example shows the YANG Library of a basic server 1152 implementing the "ietf-interfaces" [RFC8343] and "ietf-ip" [RFC8344] 1153 modules in the , , and datastores and 1154 the "ietf-hardware" [RFC8348] module in the datastore. 1156 Newlines in leaf values are added for formatting reasons. 1158 1162 1163 config-modules 1164 1165 ietf-interfaces 1166 2018-01-09 1167 1168 urn:ietf:params:xml:ns:yang:ietf-interfaces 1169 1170 1171 1172 ietf-ip 1173 2018-01-09 1174 1175 urn:ietf:params:xml:ns:yang:ietf-ip 1176 1177 1178 1179 ietf-yang-types 1180 2013-07-15 1181 1182 urn:ietf:params:xml:ns:yang:ietf-yang-types 1183 1184 1185 1186 ietf-inet-types 1187 2013-07-15 1188 1189 urn:ietf:params:xml:ns:yang:ietf-inet-types 1190 1191 1192 1194 1195 state-modules 1196 1197 ietf-hardware 1198 2018-12-18 1199 1200 urn:ietf:params:xml:ns:yang:ietf-hardware 1201 1202 1203 1204 ietf-inet-types 1205 2013-07-15 1206 1207 urn:ietf:params:xml:ns:yang:ietf-inet-types 1208 1209 1210 1211 ietf-yang-types 1212 2013-07-15 1213 1214 urn:ietf:params:xml:ns:yang:ietf-yang-types 1215 1216 1217 1218 iana-hardware 1219 2017-12-18 1220 1221 urn:ietf:params:xml:ns:yang:iana-hardware 1222 1224 1225 1227 1228 config-schema 1229 config-modules 1230 1231 1232 state-schema 1233 config-modules 1234 state-modules 1235 1237 1238 ds:startup 1239 config-schema 1240 1241 1242 ds:running 1243 config-schema 1244 1245 1246 ds:operational 1247 state-schema 1248 1250 75a43df9bd56b92aacc156a2958fbe12312fb285 1251 1253 Appendix C. Example YANG Library Instance for an Advanced Server 1255 The following example extends the preceding Basic Server YANG Library 1256 example, by using modules from [RFC8345] and [RFC8349], to illustrate 1257 a slightly more advanced server that: 1259 o Has a module with features only enabled in ; the 1260 "ietf-routing module" is supported in , , and 1261 , but the "multiple-ribs" and "router-id" features 1262 are only enabled in . Hence the "router-id" leaf may 1263 be read but not configured. 1265 o Supports a dynamic configuration datastore "example-ds-ephemeral", 1266 with only the "ietf-network" and "ietf-network-topology" modules 1267 configurable via a notional dynamic configuration protocol. 1269 o Shows an example of datastore specific deviations. The module 1270 "example-vendor-hardware-deviations" is included in the schema for 1271 to remove data nodes that cannot be supported by the 1272 server. 1274 o Shows how module-sets can be used to organize related modules 1275 together. 1277 1282 1283 config-state-modules 1284 1285 ietf-interfaces 1286 2018-01-09 1287 1288 urn:ietf:params:xml:ns:yang:ietf-interfaces 1289 1290 1291 1292 ietf-ip 1293 2018-01-09 1294 1295 urn:ietf:params:xml:ns:yang:ietf-ip 1296 1297 1298 1299 ietf-routing 1300 2018-01-25 1301 1302 urn:ietf:params:xml:ns:yang:ietf-routing 1303 1304 1305 1306 ietf-yang-types 1307 2013-07-15 1308 1309 urn:ietf:params:xml:ns:yang:ietf-yang-types 1310 1311 1312 1313 ietf-inet-types 1314 2013-07-15 1315 1316 urn:ietf:params:xml:ns:yang:ietf-inet-types 1317 1318 1320 1322 1323 config-only-modules 1324 1325 ietf-routing 1326 2018-01-25 1327 1328 urn:ietf:params:xml:ns:yang:ietf-routing 1329 1330 1331 1333 1334 dynamic-config-state-modules 1335 1336 ietf-network 1337 2017-12-18 1338 1339 urn:ietf:params:xml:ns:yang:ietf-network 1340 1341 1342 1343 ietf-network-topology 1344 2017-12-18 1345 1346 urn:ietf:params:xml:ns:yang:ietf-network-topology 1347 1348 1349 1350 ietf-inet-types 1351 2013-07-15 1352 1353 urn:ietf:params:xml:ns:yang:ietf-inet-types 1354 1355 1356 1358 1359 state-only-modules 1360 1361 ietf-hardware 1362 2018-12-18 1363 1364 urn:ietf:params:xml:ns:yang:ietf-hardware 1365 1366 example-vendor-hardware-deviations 1367 1368 1369 ietf-routing 1370 2018-01-25 1371 1372 urn:ietf:params:xml:ns:yang:ietf-routing 1373 1374 multiple-ribs 1375 router-id 1376 1377 1378 example-vendor-hardware-deviations 1379 2018-01-31 1380 1381 urn:example:example-vendor-hardware-deviations 1382 1383 1384 1385 ietf-inet-types 1386 2013-07-15 1387 1388 urn:ietf:params:xml:ns:yang:ietf-inet-types 1389 1390 1391 1392 ietf-yang-types 1393 2013-07-15 1394 1395 urn:ietf:params:xml:ns:yang:ietf-yang-types 1396 1397 1398 1399 iana-hardware 1400 2017-12-18 1401 1402 urn:ietf:params:xml:ns:yang:iana-hardware 1403 1404 1405 1407 1408 config-schema 1409 config-state-modules 1410 config-only-modules 1411 1412 1413 dynamic-config-schema 1414 dynamic-config-state-modules 1415 1416 1417 state-schema 1418 config-state-modules 1419 dynamic-config-state-modules 1420 state-only-modules 1421 1423 1424 ds:startup 1425 config-schema 1426 1427 1428 ds:running 1429 config-schema 1430 1431 1432 ex-ds-eph:ds-ephemeral 1433 dynamic-config-schema 1434 1435 1436 ds:operational 1437 state-schema 1438 1440 14782ab9bd56b92aacc156a2958fbe12312fb285 1441 1443 Authors' Addresses 1445 Andy Bierman 1446 YumaWorks 1448 Email: andy@yumaworks.com 1450 Martin Bjorklund 1451 Tail-f Systems 1453 Email: mbj@tail-f.com 1455 Juergen Schoenwaelder 1456 Jacobs University 1458 Email: j.schoenwaelder@jacobs-university.de 1459 Kent Watsen 1460 Juniper Networks 1462 Email: kwatsen@juniper.net 1464 Robert Wilton 1465 Cisco Systems 1467 Email: rwilton@cisco.com