idnits 2.17.1 draft-nmdsdt-netconf-rfc7895bis-01.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 : ---------------------------------------------------------------------------- ** There is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. == The 'Obsoletes: ' line in the draft header should list only the _numbers_ of the RFCs which will be obsoleted by this document (if approved); it should not include the word 'RFC' in the list. == The 'Updates: ' line in the draft header should list only the _numbers_ of the RFCs which will be updated by this document (if approved); it should not include the word 'RFC' in the list. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 304 has weird spacing: '...evision uni...' == Line 305 has weird spacing: '...ce-type enu...' == Line 308 has weird spacing: '...evision uni...' == Line 321 has weird spacing: '...-set-id str...' == Line 330 has weird spacing: '...evision uni...' == (2 more instances...) == 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 (July 3, 2017) is 2488 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) == Outdated reference: A later version (-10) exists of draft-ietf-netmod-revised-datastores-03 ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) ** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525) Summary: 3 errors (**), 0 flaws (~~), 11 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 Obsoletes: rfc7895 (if approved) M. Bjorklund 5 Updates: rfc7950, rfc8040 (if approved) Tail-f Systems 6 Intended status: Standards Track K. Watsen 7 Expires: January 4, 2018 Juniper Networks 8 July 3, 2017 10 YANG Library 11 draft-nmdsdt-netconf-rfc7895bis-01 13 Abstract 15 This document describes a YANG library that 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 January 4, 2018. 38 Copyright Notice 40 Copyright (c) 2017 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 . . . . . . . . . . . . . . . . . . . . . . 4 58 1.3. Motivation for rfc7895bis . . . . . . . . . . . . . . . . 4 59 1.4. Summary of Changes from RFC 7895 . . . . . . . . . . . . 5 60 1.5. Summary of Updates to RFC 7950 . . . . . . . . . . . . . 6 61 1.6. Summary of Updates to RFC 8040 . . . . . . . . . . . . . 6 62 1.7. Open Issues . . . . . . . . . . . . . . . . . . . . . . . 6 63 2. YANG Library . . . . . . . . . . . . . . . . . . . . . . . . 7 64 2.1. yang-library . . . . . . . . . . . . . . . . . . . . . . 9 65 2.1.1. yang-library/modules/module . . . . . . . . . . . . . 9 66 2.1.2. yang-library/module-sets/module-set . . . . . . . . . 9 67 2.1.3. yang-library/datastores/datastore . . . . . . . . . . 9 68 2.2. modules-state . . . . . . . . . . . . . . . . . . . . . . 9 69 2.2.1. modules-state/module-set-id . . . . . . . . . . . . . 9 70 2.2.2. modules-state/module . . . . . . . . . . . . . . . . 10 71 2.3. YANG Library Module . . . . . . . . . . . . . . . . . . . 10 72 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 73 3.1. YANG Module Registry . . . . . . . . . . . . . . . . . . 20 74 4. Security Considerations . . . . . . . . . . . . . . . . . . . 21 75 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 21 76 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 77 6.1. Normative References . . . . . . . . . . . . . . . . . . 21 78 6.2. Informative References . . . . . . . . . . . . . . . . . 23 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 81 1. Introduction 83 There is a need for standard mechanisms to provide the operational 84 state of the server. This includes, for instance, identifying the 85 YANG modules and datastores that are in use by a server and how they 86 relate to each other. 88 If a large number of YANG modules are utilized by the server, then 89 the YANG library contents needed can be relatively large. This 90 information changes very infrequently, so it is important that 91 clients be able to cache the YANG library contents and easily 92 identify whether their cache is out of date. 94 YANG library information can be different on every server and can 95 change at runtime or across a server reboot. 97 If the server implements multiple protocols to access the YANG- 98 defined data, each such protocol has its own conceptual instantiation 99 of the YANG library. 101 The following information is needed by a client application (for each 102 YANG module in the library) to fully utilize the YANG data modeling 103 language: 105 o identifier: a unique identifier for the module that includes the 106 module's name, revision, features, and deviations. 108 o name: The name of the YANG module. 110 o revision: Each YANG module and submodule within the library has a 111 revision. This is derived from the most recent revision statement 112 within the module or submodule. If no such revision statement 113 exists, the module's or submodule's revision is the zero-length 114 string. 116 o submodule list: The name and revision of each submodule used by 117 the module MUST be identified. 119 o feature list: The name of each YANG feature supported by the 120 server, in a given context, MUST be identified. 122 o deviation list: The name of each YANG module used for deviation 123 statements, in a given context, MUST be identified. 125 The following information is needed by a client application (for each 126 datastore supported by the server) to fully access all the YANG- 127 modelled data available on the server: 129 o identity: the YANG identity for the datastore. 131 o properties: properties supported by the datastore. 133 o modules: modules supported by the datastore, including any 134 features and deviations. 136 1.1. Terminology 138 The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 140 "OPTIONAL" in this document are to be interpreted as described in BCP 141 14, [RFC2119]. 143 The following terms are defined in [RFC6241]: 145 o client 147 o server 149 The following terms are defined in [RFC7950]: 151 o module 153 o submodule 155 The following terms are used within this document: 157 o YANG library: A collection of metadata describing the server's 158 operational state. 160 1.2. Tree Diagrams 162 A simplified graphical representation of the data model is used in 163 this document. The meaning of the symbols in these diagrams is as 164 follows: 166 o Brackets "[" and "]" enclose list keys. 168 o Abbreviations before data node names: "rw" means configuration 169 data (read-write) and "ro" state data (read-only). 171 o Symbols after data node names: "?" means an optional node, "!" 172 means a presence container, and "*" denotes a list and leaf-list. 174 o Parentheses enclose choice and case nodes, and case nodes are also 175 marked with a colon (":"). 177 o Ellipsis ("...") stands for contents of subtrees that are not 178 shown. 180 1.3. Motivation for rfc7895bis 182 RFC Ed.: delete this section, including this note, at time of 183 publication. 185 All NETCONF servers supporting YANG 1.1 [RFC7950] MUST support YANG 186 Library (see Section 5.6.4 of RFC 7950). Similarly, all RESTCONF 187 servers MUST support YANG Library (see Section 10 of RFC 8040). 188 These requirements are independent of if the server supports NMDA or 189 not. 191 RFC 7895 has a mandatory to implement 'modules-state' tree that a 192 server uses to advertise all the modules it supports. However, this 193 module was designed assuming the all modules would be in all 194 datastores, and with the same number of features and deviations. 195 However, this is not the case with NMDA-compatible servers that may 196 have some modules that only appear in (e.g., ietf- 197 network-topo) or only also appear in a dynamic datastore (e.g., i2rs- 198 ephemeral-rib). It is also possible that a server only implements a 199 module in , at it hasn't yet coded support for returning the 200 module's opstate yet. Presumably, an NMDA-supporting server would 201 return all modules implemented in every datastore, but this would be 202 misleading to existing clients and unhelpful to NMDA-aware clients. 204 In the end, it appears that the 'modules-state' node should be for 205 non-NMDA aware clients. For backwards compatability, an NMDA- 206 supporting server SHOULD populate 'modules-state' in a backwards- 207 compatible manner. The new 'yang-library' node would be ignored by 208 legacy clients, while providing all the data needed for NMDA-aware 209 clients, which would themselves ignore the 'modules-state' tree. 211 In addition to resolving the 'modules-state' node NMDA- 212 incompatibility issue described above, the solution presented in this 213 document is further motivated by the following desires: 215 o leverage Section 5.6.4 of RFC 7950 and Section 10 of RFC 8040. 217 o indicate which modules are supported by each datastore 219 o enable the features and deviations to vary by datastore 221 o structure extensible to support schema-mount 223 o provide a top-level container for all server metadata 225 1.4. Summary of Changes from RFC 7895 227 This document updates [RFC7895] in the following ways: 229 o Renames document title from "YANG Module Library" to "YANG 230 Library". 232 o Adds new top-level "yang-library" container to hold many types of 233 server metadata: modules supported, datastores supported, 234 relationships between datastores and modules, etc. 236 o Deprecates the modules-state tree. 238 1.5. Summary of Updates to RFC 7950 240 This document updates [RFC7950] in the following ways: 242 1. Section 5.6.4 says: 244 A NETCONF server MUST announce the modules it implements (see 245 Section 5.6.5) by implementing the YANG module "ietf-yang-library" 246 defined in [RFC7895] and listing all implemented modules in the 247 "/modules-state/module" list. 249 This should be updated to allow for also listing all implemented 250 modules in the "/yang-library/modules/module" list or, more 251 generally, use the entire YANG Library. 253 2. Section 5.6.4 also says: 255 The parameter "module-set-id" has the same value as the leaf 256 "/modules-state/module-set-id" from "ietf-yang-library". This 257 parameter MUST be present. 259 This should be updated to say that, for NMDA-capable servers, this 260 parameter has the same value as the leaf 261 "/yang-library/module-sets/module-set/id", for the module-set that is 262 used by . 264 1.6. Summary of Updates to RFC 8040 266 This document updates [RFC8040] in the following ways: 268 1. Section 10.1 says that the "modules-state/module" list is 269 mandatory. This should be updated to allow for also listing all 270 supported modules in the "/yang-library/modules/module" list or, more 271 generally, use the entire YANG Library. 273 1.7. Open Issues 275 o The per-datastore 'properties' idea is still being discussed. 276 It's included here so as to provide something to point at. 278 o There's debate if there should be a list of module-sets or if 279 instead each 'module-set' should be embeded into the datastore 280 definition. This discussion goes into if a datastore can 281 reference more than one module-set. 283 2. YANG Library 285 The "ietf-yang-library" module provides information about the modules 286 used by a server. This module is defined using YANG version 1, but 287 it supports the description of YANG modules written in any revision 288 of YANG. 290 Following is the YANG Tree Diagram for the "ietf-yang-library" 291 module, including the deprecated 'modules-state' tree: 293 +--ro yang-library 294 | +--ro modules 295 | | +--ro module* [id] 296 | | +--ro id string 297 | | +--ro name? yang:yang-identifier 298 | | +--ro revision? union 299 | | +--ro schema? inet:uri 300 | | +--ro namespace inet:uri 301 | | +--ro feature* yang:yang-identifier 302 | | +--ro deviation* [name revision] 303 | | | +--ro name yang:yang-identifier 304 | | | +--ro revision union 305 | | +--ro conformance-type enumeration 306 | | +--ro submodule* [name revision] 307 | | +--ro name yang:yang-identifier 308 | | +--ro revision union 309 | | +--ro schema? inet:uri 310 | +--ro module-sets 311 | | +--ro module-set* 312 | | +--ro id? string 313 | | +--ro module* -> /yang-library/modules/module/id 314 | +--ro datastores 315 | +--ro datastore* [name] 316 | +--ro name identityref 317 | +--ro properties 318 | | +--ro property* identityref 319 | +--ro module-set? -> /yang-library/module-sets/module-set/id 320 x--ro modules-state 321 +--ro module-set-id string 322 +--ro module* [name revision] 323 +--ro name yang:yang-identifier 324 +--ro revision union 325 +--ro schema? inet:uri 326 +--ro namespace inet:uri 327 +--ro feature* yang:yang-identifier 328 +--ro deviation* [name revision] 329 | +--ro name yang:yang-identifier 330 | +--ro revision union 331 +--ro conformance-type enumeration 332 +--ro submodule* [name revision] 333 +--ro name yang:yang-identifier 334 +--ro revision union 335 +--ro schema? inet:uri 337 2.1. yang-library 339 This mandatory container holds all of the server's metadata. 341 2.1.1. yang-library/modules/module 343 This mandatory list contains one entry for each unique instance of a 344 module in use by the server. Each entry is distiguished by the 345 module's name, revisions, features, and deviations. 347 2.1.2. yang-library/module-sets/module-set 349 This mandatory list contains one entry for each module-set in use by 350 the server (e.g., presented by a datastore). 352 2.1.3. yang-library/datastores/datastore 354 This mandatory list contains one entry for each datastore supported 355 by the server. Each datastore entry both identifies any special 356 propoerties it has and any module-sets it uses. 358 2.2. modules-state 360 This mandatory container holds the identifiers for the YANG data 361 model modules supported by the server. 363 2.2.1. modules-state/module-set-id 365 This mandatory leaf contains a unique implementation-specific 366 identifier representing the current set of modules and submodules on 367 a specific server. The value of this leaf MUST change whenever the 368 set of modules and submodules in the YANG library changes. There is 369 no requirement that the same set always results in the same 370 "module-set-id" value. 372 This leaf allows a client to fetch the module list once, cache it, 373 and only refetch it if the value of this leaf has been changed. 375 If the value of this leaf changes, the server also generates a 376 "yang-library-change" notification, with the new value of 377 "module-set-id". 379 Note that for a NETCONF server that implements YANG 1.1 [RFC7950], a 380 change of the "module-set-id" value results in a new value for the 381 :yang-library capability defined in [RFC7950]. Thus, if such a 382 server implements NETCONF notifications [RFC5277], and the 383 notification "netconf-capability-change" [RFC6470], a 384 "netconf-capability-change" notification is generated whenever the 385 "module-set-id" changes. 387 2.2.2. modules-state/module 389 This mandatory list contains one entry for each YANG data model 390 module supported by the server. There MUST be an entry in this list 391 for each revision of each YANG module that is used by the server. It 392 is possible for multiple revisions of the same module to be imported, 393 in addition to an entry for the revision that is implemented by the 394 server. 396 2.3. YANG Library Module 398 The "ietf-yang-library" module defines monitoring information for the 399 YANG modules used by a server. 401 The modules "ietf-yang-types" and "ietf-inet-types" from [RFC6991] 402 and the module "ietf-datastores" from 403 [I-D.ietf-netmod-revised-datastores] are used by this module for some 404 type definitions. 406 RFC Ed.: update the date below with the date of RFC publication and 407 remove this note. 409 file "ietf-yang-library@2017-07-03.yang" 411 module ietf-yang-library { 412 yang-version 1.1; 413 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-library"; 414 prefix "yanglib"; 416 import ietf-yang-types { 417 prefix yang; 418 reference "RFC 6991: Common YANG Data Types."; 419 } 420 import ietf-inet-types { 421 prefix inet; 422 reference "RFC 6991: Common YANG Data Types."; 423 } 424 import ietf-datastores { 425 prefix ds; 426 reference "I-D.ietf-revised-datastoes: 427 Network Management Datastore Architecture."; 428 } 430 organization 431 "IETF NETCONF (Network Configuration) Working Group"; 433 contact 434 "WG Web: 435 WG List: 437 Author: Andy Bierman 438 440 Author: Martin Bjorklund 441 443 Author: Kent Watsen 444 "; 446 description 447 "This module contains monitoring information about the YANG 448 modules and submodules that are used within a YANG-based 449 server. 451 Copyright (c) 2016 IETF Trust and the persons identified as 452 authors of the code. All rights reserved. 454 Redistribution and use in source and binary forms, with or 455 without modification, is permitted pursuant to, and subject 456 to the license terms contained in, the Simplified BSD License 457 set forth in Section 4.c of the IETF Trust's Legal Provisions 458 Relating to IETF Documents 459 (http://trustee.ietf.org/license-info). 461 This version of this YANG module is part of RFC XXXX; see 462 the RFC itself for full legal notices."; 464 // RFC Ed.: update the date below with the date of RFC publication 465 // and remove this note. 466 // RFC Ed.: replace XXXX with actual RFC number and remove this 467 // note. 468 revision 2017-07-03 { 469 description 470 "Updated revision."; 471 reference 472 "RFC XXXX: YANG Library."; 473 } 474 revision 2016-04-09 { 475 description 476 "Initial revision."; 477 reference 478 "RFC 7895: YANG Module Library."; 479 } 480 /* 481 * Typedefs 482 */ 484 typedef revision-identifier { 485 type string { 486 pattern '\d{4}-\d{2}-\d{2}'; 487 } 488 description 489 "Represents a specific date in YYYY-MM-DD format."; 490 } 492 /* 493 * Groupings 494 */ 495 grouping common-leafs2 { 496 description 497 "Common parameters for YANG modules and submodules."; 499 leaf name { 500 type yang:yang-identifier; 501 description 502 "The YANG module or submodule name."; 503 } 504 leaf revision { 505 type union { 506 type revision-identifier; 507 type string { length 0; } 508 } 509 description 510 "The YANG module or submodule revision date. 511 A zero-length string is used if no revision statement 512 is present in the YANG module or submodule."; 513 } 514 } 516 grouping schema-leaf2 { 517 description 518 "Common schema leaf parameter for modules and submodules."; 520 leaf schema { 521 type inet:uri; 522 description 523 "Contains a URL that represents the YANG schema 524 resource for this module or submodule. 526 This leaf will only be present if there is a URL 527 available for retrieval of the schema for this entry."; 528 } 529 } 531 /* 532 * Top-level container 533 */ 534 container yang-library { 535 config false; 536 description 537 "Top-level resource providing all the meta information the 538 server possesses."; 540 container modules { 541 description 542 "A container holding a list of modules. Note, modules being 543 listed here does not mean that they are supported by any 544 particular datastore."; 546 list module { 547 key "id"; 549 description 550 "Each entry represents one revision of one module 551 currently supported by the server."; 553 leaf id { 554 type string; 555 description 556 "A system-generated value that uniquely represents the 557 module listing, including its name, revision, features, 558 and deviations."; 559 } 561 uses common-leafs2; 562 uses schema-leaf2; 564 leaf namespace { 565 type inet:uri; 566 mandatory true; 567 description 568 "The XML namespace identifier for this module."; 569 } 570 leaf-list feature { 571 type yang:yang-identifier; 572 description 573 "List of YANG feature names from this module that are 574 supported by the server, regardless whether they are 575 defined in the module or any included submodule."; 576 } 577 list deviation { 578 key "name revision"; 579 description 580 "List of YANG deviation module names and revisions 581 used by this server to modify the conformance of 582 the module associated with this entry. Note that 583 the same module can be used for deviations for 584 multiple modules, so the same entry MAY appear 585 within multiple 'module' entries. 587 The deviation module MUST be present in the 'module' 588 list, with the same name and revision values. 589 The 'conformance-type' value will be 'implement' for 590 the deviation module."; 591 uses common-leafs2; 592 } 593 leaf conformance-type { 594 type enumeration { 595 enum implement { 596 description 597 "Indicates that the server implements one or more 598 protocol-accessible objects defined in the YANG module 599 identified in this entry. This includes deviation 600 statements defined in the module. 602 For YANG version 1.1 modules, there is at most one 603 module entry with conformance type 'implement' for a 604 particular module name, since YANG 1.1 requires that 605 at most one revision of a module is implemented. 607 For YANG version 1 modules, there SHOULD NOT be more 608 than one module entry for a particular module name."; 609 } 610 enum import { 611 description 612 "Indicates that the server imports reusable definitions 613 from the specified revision of the module, but does 614 not implement any protocol accessible objects from 615 this revision. 617 Multiple module entries for the same module name MAY 618 exist. This can occur if multiple modules import the 619 same module, but specify different revision-dates in 620 the import statements."; 621 } 623 } 624 mandatory true; 625 description 626 "Indicates the type of conformance the server is claiming 627 for the YANG module identified by this entry."; 628 } 629 list submodule { 630 key "name revision"; 631 description 632 "Each entry represents one submodule within the 633 parent module."; 634 uses common-leafs2; 635 uses schema-leaf2; 636 } 637 } 638 } 640 container module-sets { 641 description 642 "A container for a list of module-sets. Module-sets being 643 listed here does not mean that they are used by any 644 particular datastore."; 645 list module-set { 646 description 647 "An arbitrary module-set definition provided by the server."; 649 leaf id { 650 type string; 651 description 652 "A server-supplied identifier for this set of modules."; 653 } 654 leaf-list module { 655 type leafref { 656 path "/yang-library/modules/module/id"; 657 } 658 description 659 "A module-instance supported by the server, including its 660 features and deviations."; 661 } 662 } 663 } 665 container datastores { 666 description 667 "A container for a list of datastores supported by the server. 668 Each datastore indicates which module-sets it supports."; 670 list datastore { 671 key name; 672 leaf name { 673 type identityref { 674 base ds:datastore; 675 } 676 description 677 "The identity of the datastore."; 678 } 679 container properties { 680 leaf-list property { 681 type identityref { 682 base ds:property; 683 } 684 description 685 "A property of the datastore."; 686 } 687 description 688 "A list of properties supported by this datastore."; 689 } 690 leaf module-set { 691 type leafref { 692 path "/yang-library/module-sets/module-set/id"; 693 } 694 description 695 "A reference to a module-set supported by this datastore"; 696 } 697 description 698 "A datastore supported by this server."; 699 } 700 } // end 'datastores' 702 } // end 'yang-library' 704 /* 705 * Legacy groupings 706 */ 708 grouping module-list { 709 description 710 "The module data structure is represented as a grouping 711 so it can be reused in configuration or another monitoring 712 data structure."; 714 grouping common-leafs { 715 description 716 "Common parameters for YANG modules and submodules."; 718 leaf name { 719 type yang:yang-identifier; 720 description 721 "The YANG module or submodule name."; 722 } 723 leaf revision { 724 type union { 725 type revision-identifier; 726 type string { length 0; } 727 } 728 description 729 "The YANG module or submodule revision date. 730 A zero-length string is used if no revision statement 731 is present in the YANG module or submodule."; 732 } 733 } 735 grouping schema-leaf { 736 description 737 "Common schema leaf parameter for modules and submodules."; 739 leaf schema { 740 type inet:uri; 741 description 742 "Contains a URL that represents the YANG schema 743 resource for this module or submodule. 745 This leaf will only be present if there is a URL 746 available for retrieval of the schema for this entry."; 747 } 748 } 750 list module { 751 key "name revision"; 752 description 753 "Each entry represents one revision of one module 754 currently supported by the server."; 756 uses common-leafs; 757 uses schema-leaf; 759 leaf namespace { 760 type inet:uri; 761 mandatory true; 762 description 763 "The XML namespace identifier for this module."; 764 } 765 leaf-list feature { 766 type yang:yang-identifier; 767 description 768 "List of YANG feature names from this module that are 769 supported by the server, regardless whether they are 770 defined in the module or any included submodule."; 771 } 772 list deviation { 773 key "name revision"; 774 description 775 "List of YANG deviation module names and revisions 776 used by this server to modify the conformance of 777 the module associated with this entry. Note that 778 the same module can be used for deviations for 779 multiple modules, so the same entry MAY appear 780 within multiple 'module' entries. 782 The deviation module MUST be present in the 'module' 783 list, with the same name and revision values. 784 The 'conformance-type' value will be 'implement' for 785 the deviation module."; 786 uses common-leafs; 787 } 788 leaf conformance-type { 789 type enumeration { 790 enum implement { 791 description 792 "Indicates that the server implements one or more 793 protocol-accessible objects defined in the YANG module 794 identified in this entry. This includes deviation 795 statements defined in the module. 797 For YANG version 1.1 modules, there is at most one 798 module entry with conformance type 'implement' for a 799 particular module name, since YANG 1.1 requires that 800 at most one revision of a module is implemented. 802 For YANG version 1 modules, there SHOULD NOT be more 803 than one module entry for a particular module name."; 804 } 805 enum import { 806 description 807 "Indicates that the server imports reusable definitions 808 from the specified revision of the module, but does 809 not implement any protocol accessible objects from 810 this revision. 812 Multiple module entries for the same module name MAY 813 exist. This can occur if multiple modules import the 814 same module, but specify different revision-dates in 815 the import statements."; 816 } 817 } 818 mandatory true; 819 description 820 "Indicates the type of conformance the server is claiming 821 for the YANG module identified by this entry."; 822 } 823 list submodule { 824 key "name revision"; 825 description 826 "Each entry represents one submodule within the 827 parent module."; 828 uses common-leafs; 829 uses schema-leaf; 830 } 831 } 832 } 834 /* 835 * Legacy operational state data nodes 836 */ 838 container modules-state { 839 config false; 840 status deprecated; 841 description 842 "Contains YANG module monitoring information."; 844 leaf module-set-id { 845 type string; 846 mandatory true; 847 description 848 "Contains a server-specific identifier representing 849 the current set of modules and submodules. The 850 server MUST change the value of this leaf if the 851 information represented by the 'module' list instances 852 has changed."; 853 } 855 uses module-list; 856 } 858 /* 859 * Notifications 860 */ 862 notification yang-library-change { 863 description 864 "Generated when the set of modules and submodules supported 865 by the server has changed."; 866 leaf module-set-id { 867 type leafref { 868 path "/yanglib:modules-state/yanglib:module-set-id"; 869 } 870 mandatory true; 871 description 872 "Contains the module-set-id value representing the 873 set of modules and submodules supported at the server at 874 the time the notification is generated."; 875 } 876 } 878 } 880 882 3. IANA Considerations 884 3.1. YANG Module Registry 886 RFC 7895 previously registered one URI in the IETF XML registry 887 [RFC3688]. Following the format in RFC 3688, the following 888 registration was made: 890 URI: urn:ietf:params:xml:ns:yang:ietf-yang-library 891 Registrant Contact: The NETCONF WG of the IETF. 892 XML: N/A, the requested URI is an XML namespace. 894 This document takes over this registration entry made by RFC 7895. 896 RFC 7895 previously registered one YANG module in the "YANG Module 897 Names" registry [RFC6020] as follows: 899 name: ietf-yang-library 900 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-library 901 prefix: yanglib 902 reference: RFC 7895 904 This document takes over this registration entry made by RFC 7895. 906 4. Security Considerations 908 The YANG module defined in this memo is designed to be accessed via 909 the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the 910 secure transport layer and the mandatory-to-implement secure 911 transport is SSH [RFC6242]. The NETCONF access control model 912 [RFC6536] provides the means to restrict access for particular 913 NETCONF users to a pre-configured subset of all available NETCONF 914 protocol operations and content. 916 Some of the readable data nodes in this YANG module may be considered 917 sensitive or vulnerable in some network environments. It is thus 918 important to control read access (e.g., via get, get-config, or 919 notification) to these data nodes. These are the subtrees and data 920 nodes and their sensitivity/vulnerability: 922 o /modules-state/module: The module list used in a server 923 implementation may help an attacker identify the server 924 capabilities and server implementations with known bugs. Although 925 some of this information may be available to all users via the 926 NETCONF message (or similar messages in other management 927 protocols), this YANG module potentially exposes additional 928 details that could be of some assistance to an attacker. Server 929 vulnerabilities may be specific to particular modules, module 930 revisions, module features, or even module deviations. This 931 information is included in each module entry. For example, if a 932 particular operation on a particular data node is known to cause a 933 server to crash or significantly degrade device performance, then 934 the module list information will help an attacker identify server 935 implementations with such a defect, in order to launch a denial- 936 of-service attack on the device. 938 5. Acknowledgements 940 Contributions to this material by Andy Bierman are based upon work 941 supported by the The Space & Terrestrial Communications Directorate 942 (S&TCD) under Contract No. W15P7T-13-C-A616. Any opinions, findings 943 and conclusions or recommendations expressed in this material are 944 those of the author(s) and do not necessarily reflect the views of 945 The Space & Terrestrial Communications Directorate (S&TCD). 947 6. References 949 6.1. Normative References 951 [I-D.ietf-netmod-revised-datastores] 952 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 953 and R. Wilton, "Network Management Datastore 954 Architecture", draft-ietf-netmod-revised-datastores-03 955 (work in progress), July 2017. 957 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 958 Requirement Levels", BCP 14, RFC 2119, 959 DOI 10.17487/RFC2119, March 1997, 960 . 962 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 963 DOI 10.17487/RFC3688, January 2004, 964 . 966 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 967 the Network Configuration Protocol (NETCONF)", RFC 6020, 968 DOI 10.17487/RFC6020, October 2010, 969 . 971 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 972 and A. Bierman, Ed., "Network Configuration Protocol 973 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 974 . 976 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 977 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 978 . 980 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 981 Protocol (NETCONF) Access Control Model", RFC 6536, 982 DOI 10.17487/RFC6536, March 2012, 983 . 985 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 986 RFC 6991, DOI 10.17487/RFC6991, July 2013, 987 . 989 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module 990 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016, 991 . 993 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 994 RFC 7950, DOI 10.17487/RFC7950, August 2016, 995 . 997 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 998 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 999 . 1001 6.2. Informative References 1003 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1004 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1005 . 1007 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF) 1008 Base Notifications", RFC 6470, DOI 10.17487/RFC6470, 1009 February 2012, . 1011 Authors' Addresses 1013 Andy Bierman 1014 YumaWorks 1016 Email: andy@yumaworks.com 1018 Martin Bjorklund 1019 Tail-f Systems 1021 Email: mbj@tail-f.com 1023 Kent Watsen 1024 Juniper Networks 1026 Email: kwatsen@juniper.net