idnits 2.17.1 draft-ietf-netmod-yang-instance-file-format-02.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 == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (February 26, 2019) is 1879 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-netmod-yang-data-ext' is defined on line 805, but no explicit reference was found in the text == Outdated reference: A later version (-05) exists of draft-ietf-netmod-yang-data-ext-01 == Outdated reference: A later version (-09) exists of draft-ietf-ccamp-alarm-module-07 == Outdated reference: A later version (-25) exists of draft-ietf-netconf-yang-push-22 Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Netmod B. Lengyel 3 Internet-Draft Ericsson 4 Intended status: Standards Track B. Claise 5 Expires: August 30, 2019 Cisco Systems, Inc. 6 February 26, 2019 8 YANG Instance Data File Format 9 draft-ietf-netmod-yang-instance-file-format-02 11 Abstract 13 There is a need to document data defined in YANG models when a live 14 YANG server is not available. Data is often needed already at design 15 or implementation time or needed by groups that do not have a live 16 running YANG server available. This document specifies a standard 17 file format for YANG instance data (which follows the syntax and 18 semantic from existing YANG models, re-using the same format as the 19 reply to a operation/request) and decorates it with metadata. 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 https://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 August 30, 2019. 38 Copyright Notice 40 Copyright (c) 2019 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 (https://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. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2.1. High Level Principles . . . . . . . . . . . . . . . . . . 4 58 3. Instance Data File Format . . . . . . . . . . . . . . . . . . 4 59 3.1. Specifying the Target YANG Modules: target-ptr . . . . . 6 60 3.1.1. INLINE Method . . . . . . . . . . . . . . . . . . . . 7 61 3.1.2. URI Method . . . . . . . . . . . . . . . . . . . . . 8 62 3.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8 63 4. Data Life cycle . . . . . . . . . . . . . . . . . . . . . . . 12 64 5. Delivery of Instance Data . . . . . . . . . . . . . . . . . . 13 65 6. Backwards Compatibility . . . . . . . . . . . . . . . . . . . 13 66 7. YANG Model . . . . . . . . . . . . . . . . . . . . . . . . . 13 67 8. Security Considerations . . . . . . . . . . . . . . . . . . . 17 68 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 69 9.1. URI Registration . . . . . . . . . . . . . . . . . . . . 17 70 9.2. YANG Module Name Registration . . . . . . . . . . . . . . 17 71 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17 72 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 73 11.1. Normative References . . . . . . . . . . . . . . . . . . 18 74 11.2. Informative References . . . . . . . . . . . . . . . . . 19 75 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 19 76 Appendix B. Changes between revisions . . . . . . . . . . . . . 19 77 Appendix C. Detailed Use Cases - Non-Normative . . . . . . . . . 21 78 C.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 21 79 C.1.1. Use Case 1: Early Documentation of Server 80 Capabilities . . . . . . . . . . . . . . . . . . . . 22 81 C.1.2. Use Case 2: Preloading Data . . . . . . . . . . . . . 23 82 C.1.3. Use Case 3: Documenting Factory Default Settings . . 23 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 23 85 1. Terminology 87 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 88 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 89 "OPTIONAL" in this document are to be interpreted as described in BCP 90 14 RFC 2119 [RFC2119] RFC 8174 [RFC8174] when, and only when, they 91 appear in all capitals, as shown here. 93 Instance Data Set: A named set of data items decorated with metadata 94 that can be used as instance data in a YANG data tree. 96 Instance Data File: A file containing an instance data set formatted 97 according to the rules described in this document. 99 Target YANG Module: A YANG module for which the instance data set 100 contains instance data, like ietf-yang-library in the examples. 102 YANG Instance Data, or just instance data for short, is data that 103 could be stored in a datastore and whose syntax and semantics is 104 defined by YANG models. 106 2. Introduction 108 There is a need to document data defined in YANG models when a live 109 YANG server is not available. Data is often needed already at design 110 or implementation time or needed by groups that do not have a live 111 running YANG server available. To facilitate this off-line delivery 112 of data this document specifies a standard format for YANG instance 113 data sets and YANG instance data files. 115 The following is a list of already implemented and potential use 116 cases. 118 UC1 Documentation of server capabilities 120 UC2 Preloading default configuration data 122 UC3 Documenting Factory Default Settings 124 UC4 Instance data used as backup 126 UC5 Storing the configuration of a device, e.g. for archive or audit 127 purposes 129 UC6 Storing diagnostics data 131 UC7 Allowing YANG instance data to potentially be carried within 132 other IPC message formats 134 UC8 Default instance data used as part of a templating solution 136 UC9 Providing data examples in RFCs or internet drafts 138 In Appendix C we describe the first three use cases in detail. 140 There are already many and varied use cases where YANG instance data 141 could be used. We do not want to limit future uses of instance data 142 sets, so specifying how and when to use Yang instance data is out of 143 scope for this document. It is anticipated that other documents 144 outside the instance data set itself will define specific use cases. 145 Use cases are listed here only to indicate the need for this work. 147 2.1. High Level Principles 149 The following is a list of the basic principles of the instance data 150 format: 152 P1 Two standard formats are based on the XML and the JSON encoding 154 P2 Re-use existing formats similar to the operation/request 156 P3 Add metadata about the instance data set 158 P4 A YANG instance data file shall contain only a single YANG 159 instance data set 161 P5 A YANG instance data set may contain data for many target YANG 162 modules 164 P6 Instance data may include configuration data, state data or a mix 165 of the two 167 P7 Partial data sets are allowed 169 P8 YANG instance data format may be used for any data for which 170 target YANG module(s) are defined and available to the reader, 171 independent of whether the module is actually implemented by a 172 YANG server 174 3. Instance Data File Format 176 A YANG instance data file MUST contain a single instance data set and 177 no additional data. 179 The instance data set is placed in a top level auxiliary container 180 named "instance-data-set". An instance data set is made up of a 181 header part and content-data. The initial header part carries 182 metadata for the instance data set. It is defined by the ietf-yang- 183 instance-data YANG module. The content-data is all data inside the 184 anydata datanode, this carries the "real data" that we want to 185 document/provide. The syntax and semantics of content-data is 186 defined by the target YANG modules. 188 Two formats are specified that can be used to represent YANG instance 189 data based on the XML and JSON encoding. Later as other YANG 190 encodings (e.g. CBOR) are defined further instance data formats may 191 be specified. 193 The content-data part of the XML format SHALL follow the encoding 194 rules defined in [RFC7950] for XML and [RFC7951] for JSON and MUST 195 use UTF-8 character encoding. 197 It MAY include metadata as defined by [RFC7952]. 199 It MAY include entity-tags and timestamps as defined in [RFC8040] 201 It MAY include an explicit tag for default values as defined in 202 [RFC6243] and [RFC8040] 204 It MAY include the origin metadata as specified in 205 [I-D.ietf-netconf-nmda-netconf] and 206 [I-D.ietf-netconf-nmda-restconf] 208 It MAY include implementation specific metadata. Unknown metadata 209 MUST be ignored by users of YANG instance data, allowing it to be 210 used later for other purposes. 212 It MAY include implementation specific XML attributes. Unknown 213 attributes MUST be ignored by users of YANG instance data, 214 allowing them to be used later for other purposes. 216 The content-data part will be very similar to the result returned for 217 a NETCONF or for a RESTCONF get operation. 219 The content-data part MUST conform to the corresponding target YANG 220 Modules. A single instance data set MAY contain data for any number 221 of target YANG modules; if needed it MAY carry the complete 222 configuration and state data set for a YANG server. Default values 223 SHOULD NOT be included. 225 Config=true and config=false data MAY be mixed in the instance data 226 file. 228 Instance data files MAY contain partial data sets. This means 229 mandatory, min-elements or require-instance=true constrains MAY be 230 violated. 232 The name of the file SHALL be of the form: 234 instance-data-set-name ['@' revision-date] '.filetype' 236 E.g. acme-router-modules@2018-01-25.xml 238 The revision date is optional. ".filetype" SHALL be ".json" or ".xml" 239 according to the format used. 241 Metadata, information about the data set itself SHALL be included in 242 the instance data set. This data will be children of the top level 243 instance-data-set container as defined in the ietf-instance-data YANG 244 module. Metadata MUST include: 246 o name of the instance data set 248 Metadata SHOULD include: 250 o target-ptr: A pointer to the list of target YANG modules their 251 revision, supported features and deviations. 253 o An inline definition of target-modules, when the INLINE method is 254 used for the target-ptr 256 o Description of the instance data set. The description SHOULD 257 contain information whether and how the data can change during the 258 lifetime of the YANG server. 260 Metadata MAY include: 262 o Organization responsible for the instance data set 264 o Contact information 266 o Information about the datastore associated with the instance data 267 set e.g. the datastore from where the data was read or the 268 datastore where the data could be loaded or the datastore which is 269 being documented. This information is optional, as often a single 270 datastore can not be specified. 272 o Revision date of the instance data set. If both this date and and 273 the date in the instance data file name are present they MUST have 274 the same value. 276 o Timestamp: The date and time when the instance data set was last 277 modified. 279 o It is anticipated that different organizations will have the need 280 to augment the metadata with various other data nodes. 282 3.1. Specifying the Target YANG Modules: target-ptr 284 To properly understand and use an instance data set the user needs to 285 know the list of target YANG modules their revision, supported 286 features and deviations. The metadata "target-ptr" is used to 287 specify the YANG target module list. One of the following options 288 SHOULD be used: 290 INLINE method: Include the needed information as part of instance 291 data set as defined by e.g. ietf-yang-library 293 URI method: Include a URI that points to the target module set. 294 (if you don't want to repeat the info again and again) 296 EXTERNAL Method: Do not include the target-ptr as the target YANG 297 module set is already known, or the information is available 298 through external documents. 300 Additional methods e.g. a YANG-package based solution may be added 301 later. 303 Note, the specified target YANG modules only indicate the set of 304 modules that were used to define this YANG instance data set. 305 Sometimes instance data may be used for a YANG server supporting a 306 different YANG module set e.g. for "UC2 Preloading Data" the instance 307 data set may not be updated every time the YANG modules on the YANG 308 server are updated, an unchanged instance data set may still be 309 usable. Whether the instance data set is usable for a possibly 310 different real-life target YANG module set depends on many factors 311 including the compatibility between the specified target and the 312 real-life target YANG module set (considering modules, revisions, 313 features, deviations), the scope of the instance data, etc. 315 3.1.1. INLINE Method 317 One or more inline-target-spec elements SHALL be specified. The 318 first one specifies ietf-yang-library or a similar YANG module 319 listing target YANG modules with their name, revision-date, 320 supported-features and deviations. Deviations or unsupported 321 features MUST NOT remove any of the above data from the module. 322 Using ietf-yang-library MUST be supported. 324 E.g. ietf-yang-library@2016-06-21.yang 326 As some versions of ietf-yang-library MAY contain different module- 327 sets for different datastores, if multiple module-sets are defined, 328 the instance data set's meta-data MUST contain the datastore 329 information and instance data for the ietf-yang library MUST also 330 contain information specifying the module-set for the relevant 331 datastore. 333 Subsequent inline-target-spec elements MAY specify YANG modules 334 augmenting the first module with useful data (e.g. a semantic 335 version). 337 When using the inline method a 'target-modules' element MUST be 338 present. This SHALL contain instance data corresponding to the YANG 339 modules specified in the inline-target-spec elements specifying the 340 set of target YANG modules for this instance-data-set. 342 3.1.2. URI Method 344 A target-uri element SHALL contain a URI that references another YANG 345 instance data file. The current instance data file will use the same 346 set of target YANG modules, revisions, supported features and 347 deviations as the referenced YANG instance data file. 349 The referenced instance data file will usually contain data only for 350 ietf-yang-library to specify the target YANG modules for the original 351 instance data file. 353 The URI method is advantageous when the user wants to avoid the 354 overhead of specifying the target YANG modules in the instance data 355 file: E.g. In Use Case 6, when the system creates a diagnostic file 356 every 10 minutes to document the state of the YANG server. 358 The referenced YANG instance data file might use the in-line method 359 or might use the URI method to reference further instance data 360 file(s). However at the end of this reference chain there MUST be an 361 instance data file using the in-line method. 363 If a referenced instance data file is not available the revision 364 data, supported features and deviations for the target YANG modules 365 are unknown. 367 3.2. Examples 369 The following example is based on "UC1, Documenting Server 370 Capabilities". It provides (a shortened) list of supported YANG 371 modules and Netconf capabilities for a YANG server. It uses the 372 inline method for the target-ptr. 374 375 377 acme-router-modules 378 379 ietf-yang-library@2016-06-21.yang 380 381 382 383 384 ietf-yang-library 385 2016-06-21 386 387 388 ietf-netconf-monitoring 389 2010-10-04 390 391 392 393 394 2108-01-25 395 Initial version 396 397 Defines the minimal set of modules that any acme-router 398 will contain. 399 info@acme.com 400 401 404 405 406 ietf-yang-library 407 2016-06-21 408 409 urn:ietf:params:xml:ns:yang:ietf-yang-library 410 411 implement 412 413 414 ietf-system 415 2014-08-06 416 urn:ietf:params:xml:ns:yang:ietf-system 417 sys:authentication 418 sys:local-users 419 420 acme-system-ext 421 2018-08-06 422 423 implement 424 425 426 ietf-yang-types 427 2013-07-15 428 urn:ietf:params:xml:ns:yang:ietf-yang-types 429 430 import 431 432 433 acme-system-ext 434 2018-08-06 435 urn:rdns:acme.com:oammodel:acme-system-ext 436 437 implement 438 439 440 441 442 443 urn:ietf:params:netconf:capability:validate:1.1 444 445 446 447 448 450 Figure 1: XML Instance Data Set - Use case 1, Documenting server 451 capabilities 453 The following example is based on "UC2, Preloading Default 454 Configuration". It provides a (shortened) default rule set for a 455 read-only operator role. It uses the inline method for the target- 456 ptr. 458 459 461 read-only-acm-rules 462 ietf-yang-library@2016-06-21.yang 463 464 465 466 467 ietf-netconf-acm 468 2012-02-22 469 470 471 472 473 2018-01-25 474 Initial version 475 476 Access control rules for a read-only role. 477 info@acme.com 478 479 480 true 481 deny 482 deny 483 484 read-only-role 485 read-only-group 486 487 read-all 488 * 489 read 490 permit 491 492 493 494 495 497 Figure 2: XML Instance Data Set - Use case 2, Preloading access 498 control data 500 The following example is based on UC6 Storing diagnostics data. An 501 instance data set is produced by the YANG server every 15 minutes 502 that contains statistics about NETCONF. As a new set is produced 503 periodically multiple times a day a revision-date would be useless; 504 instead a timestamp is included. 506 { 507 "ietf-yang-instance-data:instance-data-set": { 508 "name": "acme-router-netconf-diagnostics", 509 "target-uri": "file:///acme-netconf-diagnostics-yanglib.json", 510 "timestamp": "2018-01-25T17:00:38Z", 511 "description": 512 "Netconf statistics", 513 "content-data": { 514 "ietf-netconf-monitoring:netconf-state": { 515 "statistics": { 516 "netconf-start-time ": "2018-12-05T17:45:00Z", 517 "in-bad-hellos ": "32", 518 "in-sessions ": "397", 519 "dropped-sessions ": "87", 520 "in-rpcs ": "8711", 521 "in-bad-rpcs ": "408", 522 "out-rpc-errors ": "408", 523 "out-notifications": "39007" 524 } 525 } 526 } 527 } 528 } 530 Figure 3: JSON Instance Data File example - UC6 Storing diagnostics 531 data 533 4. Data Life cycle 535 Data defined or documented in YANG instance data sets may be used for 536 preloading a YANG server with this data, but the server may populate 537 the data without using the actual file in which case the instance 538 data file is only used as documentation. 540 While such data will usually not change, data documented by instance 541 data sets MAY be changed by the YANG server itself or by management 542 operations. It is out of scope for this document to specify a method 543 to prevent this. Whether such data changes and if so, when and how, 544 SHOULD be described either in the instance data set's description 545 statement or in some other implementation specific manner. 547 YANG instance data is a snap-shot of information at a specific point 548 of time. If the data changes afterwards this is not represented in 549 the instance data set anymore, the valid values can be retrieved in 550 run-time via NETCONF/RESTCONF. 552 Notifications about the change of data documented by instance data 553 sets may be supplied by e.g. the Yang-Push mechanism, but it is out 554 of scope for this document. 556 5. Delivery of Instance Data 558 Instance data sets that are produced as a result of some sort of 559 specification or design effort SHOULD be available without the need 560 for a live YANG server e.g. via download from the vendor's website, 561 or in any other way product documentation is distributed. 563 Other instance data sets may be read from or produced by the YANG 564 server itself e.g. UC6 documenting diagnostic data. 566 6. Backwards Compatibility 568 The concept of backwards compatibility and what changes are backwards 569 compatible are not defined for instance data sets as it is highly 570 dependent on the specific use case and the target YANG model. 571 However as instance data does use the concept of managed entities 572 identified by key values the following guidelines are provided: 574 o For list entries representing the same managed entity as 575 previously key values SHOULD NOT be changed. 577 o The meaning of list entries, representing the same managed entity 578 as previously, SHOULD NOT be changed e.g. redefining an alarm-type 579 but not changing its alarm-type-id should be avoided. 581 o Keys for previously removed list entries SHOULD NOT be reused if 582 they represent a different meaning. 584 7. YANG Model 586 file "ietf-yang-instance-data.yang" 587 module ietf-yang-instance-data { 588 yang-version 1.1; 589 namespace 590 "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data"; 591 prefix yid ; 593 import ietf-yang-data-ext { prefix yd; } 594 import ietf-datastores { prefix ds; } 595 import ietf-inet-types { prefix inet; } 596 import ietf-yang-types { prefix yang; } 598 organization "IETF NETMOD Working Group"; 599 contact 600 "WG Web: 601 WG List: 603 Author: Balazs Lengyel 604 "; 606 description "The module defines the structure and content of YANG 607 instance data sets."; 609 revision 2019-02-20 { 610 description "Initial revision."; 611 reference "RFC XXXX: YANG Instance Data Format"; 612 } 614 yd:yang-data instance-data-format { 615 container instance-data-set { 616 description "Auxiliary container to carry meta-data for 617 the complete instance data set."; 619 leaf name { 620 type string; 621 mandatory true; 622 description "Name of the YANG instance data set."; 623 } 625 choice target-ptr { 626 description "A pointer to the list of target YANG modules 627 their revisions, supported features and deviations."; 629 case inline { 630 leaf-list inline-target-spec { 631 type string { 632 pattern '.+@\d{4}-\d{2}-\d{2}\.yang'; 633 } 634 min-elements 1; 635 ordered-by user; 636 description 637 "Indicates that target modules are specified inline. 638 Each value MUST be a YANG Module name including the 639 revision-date as defined for YANG file names in RFC7950. 641 E.g. ietf-yang-library@2016-06-21.yang 643 The first item is either ietf-yang-library or some other 644 YANG module that contains a list of YANG modules with 645 their name, revision-date, supported-features and 646 deviations. 647 As some versions of ietf-yang-library MAY contain 648 different module-sets for different datastores, if 649 multiple module-sets are defined, the instance data set's 650 meta-data MUST contain the datastore information and 651 instance data for the ietf-yang-library MUST also contain 652 information specifying the module-set for the relevant 653 datastore. 655 Subsequent items MAY specify YANG modules augmenting the 656 first module with useful data (e.g. a semantic version)."; 657 } 658 anydata target-modules { 659 mandatory true; 660 description "Instance data corresponding to the YANG modules 661 specified in the inline-target-spec nodes defining the set 662 of target YANG modules for this instance-data-set."; 663 } 664 } 666 case uri { 667 leaf target-uri { 668 type inet:uri; 669 description 670 "A reference to another YANG instance data file. 671 This instance data file will use the same set of target 672 YANG modules, revisions, supported features and deviations 673 as the referenced YANG instance data file."; 674 } 675 } 676 } 678 leaf description { type string; } 680 leaf contact { 681 type string; 682 description "Contact information for the person or 683 organization to whom queries concerning this 684 instance data set should be sent."; 685 } 687 leaf organization { 688 type string; 689 description "Organization responsible for the instance 690 data set."; 691 } 693 leaf datastore { 694 type ds:datastore-ref; 695 description "The identity of the datastore with which the 696 instance data set is associated. If a single specific 697 datastore can not be specified, the leaf MUST be absent. 699 If this leaf is absent, then the datastore to which the 700 instance data belongs is undefined."; 701 } 703 list revision { 704 key date; 705 description "Instance data sets that are produced as 706 a result of some sort of specification or design effort 707 SHOULD have at least one revision entry. For every 708 published editorial change, a new one SHOULD be added 709 in front of the revisions sequence so that all 710 revisions are in reverse chronological order. 712 For instance data sets that are read from 713 or produced by the YANG server or otherwise 714 subject to frequent updates or changes, revision 715 SHOULD NOT be present"; 717 leaf date { 718 type string { 719 pattern '\d{4}-\d{2}-\d{2}'; 720 } 721 description "Specifies the date the instance data set 722 was last modified. Formatted as YYYY-MM-DD"; 723 } 725 leaf description { type string; } 726 } 728 leaf timestamp { 729 type yang:date-and-time; 730 description "The date and time when the instance data set 731 was last modified. 733 For instance data sets that are read from or produced 734 by the YANG server or otherwise subject to frequent 735 updates or changes, timestamp SHOULD be present"; 736 } 738 anydata content-data { 739 mandatory true; 740 description "Contains the real instance data. 741 The data MUST conform to the relevant YANG Modules."; 742 } 743 } 745 } 746 } 747 749 8. Security Considerations 751 Depending on the nature of the instance data, instance data files MAY 752 need to be handled in a secure way. The same type of handling should 753 be applied, that would be needed for the result of a operation 754 returning the same data. 756 9. IANA Considerations 758 This document registers one URI and one YANG module. 760 9.1. URI Registration 762 This document registers one URI in the IETF XML registry [RFC3688]. 763 Following the format in RFC 3688, the following registration is 764 requested to be made: 766 URI: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data 768 Registrant Contact: The IESG. 770 XML: N/A, the requested URI is an XML namespace. 772 9.2. YANG Module Name Registration 774 This document registers one YANG module in the YANG Module Names 775 registry [RFC6020]. 777 name: ietf-yang-instance-data 778 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data 779 prefix: yid 780 reference: RFC XXXX 782 10. Acknowledgments 784 For their valuable comments, discussions, and feedback, we wish to 785 acknowledge Andy Bierman, Juergen Schoenwaelder, Rob Wilton, Joe 786 Clark, Martin Bjorklund, Ladislav Lhotka, Qin Wu and other members of 787 the Netmod WG. 789 11. References 791 11.1. Normative References 793 [I-D.ietf-netconf-nmda-netconf] 794 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 795 and R. Wilton, "NETCONF Extensions to Support the Network 796 Management Datastore Architecture", draft-ietf-netconf- 797 nmda-netconf-08 (work in progress), October 2018. 799 [I-D.ietf-netconf-nmda-restconf] 800 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 801 and R. Wilton, "RESTCONF Extensions to Support the Network 802 Management Datastore Architecture", draft-ietf-netconf- 803 nmda-restconf-05 (work in progress), October 2018. 805 [I-D.ietf-netmod-yang-data-ext] 806 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data 807 Extensions", draft-ietf-netmod-yang-data-ext-01 (work in 808 progress), March 2018. 810 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 811 DOI 10.17487/RFC3688, January 2004, 812 . 814 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 815 the Network Configuration Protocol (NETCONF)", RFC 6020, 816 DOI 10.17487/RFC6020, October 2010, 817 . 819 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 820 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 821 . 823 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 824 RFC 7950, DOI 10.17487/RFC7950, August 2016, 825 . 827 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 828 RFC 7951, DOI 10.17487/RFC7951, August 2016, 829 . 831 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 832 RFC 7952, DOI 10.17487/RFC7952, August 2016, 833 . 835 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 836 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 837 . 839 11.2. Informative References 841 [I-D.ietf-ccamp-alarm-module] 842 Vallin, S. and M. Bjorklund, "YANG Alarm Module", draft- 843 ietf-ccamp-alarm-module-07 (work in progress), January 844 2019. 846 [I-D.ietf-netconf-rfc7895bis] 847 Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 848 and R. Wilton, "YANG Library", draft-ietf-netconf- 849 rfc7895bis-07 (work in progress), October 2018. 851 [I-D.ietf-netconf-yang-push] 852 Clemm, A., Voit, E., Prieto, A., Tripathy, A., Nilsen- 853 Nygaard, E., Bierman, A., and B. Lengyel, "Subscription to 854 YANG Datastores", draft-ietf-netconf-yang-push-22 (work in 855 progress), February 2019. 857 [I-D.wu-netconf-restconf-factory-restore] 858 Wu, Q., Lengyel, B., and Y. Niu, "Factory default 859 Setting", draft-wu-netconf-restconf-factory-restore-03 860 (work in progress), October 2018. 862 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 863 Requirement Levels", BCP 14, RFC 2119, 864 DOI 10.17487/RFC2119, March 1997, 865 . 867 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 868 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 869 May 2017, . 871 Appendix A. Open Issues 873 o Augmenting metadata must be possible. As of now it looks like 874 yang-data-ext will solve that. If not, define instance data as 875 regular YANG instead of yd:yang-data. 877 Appendix B. Changes between revisions 879 v01 - v02 881 o Removed design time from terminology 882 o Defined the format of the content-data part by referencing various 883 RFCs and drafts instead of the result of the get-data and get 884 operations. 886 o Changed target-ptr to a choice 888 o Inline target-ptr may include augmenting modules and alternatives 889 to ietf-yang-library 891 o Moved list of target modules into a separate 892 element. 894 o Added backwards compatibility considerations 896 v00 - v01 898 o Added the target-ptr metadata with 3 methods 900 o Added timestamp metadata 902 o Removed usage of dedicated .yid file extension 904 o Added list of use cases 906 o Added list of principles 908 o Updated examples 910 o Moved detailed use case descriptions to appendix 912 v05 - v00-netmod 914 o New name for the draft following Netmod workgroup adoption. No 915 other changes 917 v04 - v05 919 o Changed title and introduction to clarify that this draft is only 920 about the file format and documenting server capabilities is just 921 a use case. 923 o Added reference to draft-wu-netconf-restconf-factory-restore 925 o Added new open issues. 927 v03 - v04 929 o Updated changelog for v02-v03 930 v02 - v03 932 o Updated the document according to comments received at IETF102 934 o Added parameter to specify datastore 936 o Rearranged chapters 938 o Added new use case: Documenting Factory Default Settings 940 o Added "Target YANG Module" to terminology 942 o Clarified that instance data is a snapshot valid at the time of 943 creation, so it does not contain any later changes. 945 o Removed topics from Open Issues according to comments received at 946 IETF102 948 v01 - v02 950 o The recommendation to document server capabilities was changed to 951 be just the primary use-case. (Merged chapter 4 into the use case 952 chapter.) 954 o Stated that RFC7950/7951 encoding must be followed which also 955 defines (dis)allowed whitespace rules. 957 o Added UTF-8 encoding as it is not specified in t950 for instance 958 data 960 o added XML declaration 962 v00 - v01 964 o Redefined using yang-data-ext 966 o Moved metadata into ordinary leafs/leaf-lists 968 Appendix C. Detailed Use Cases - Non-Normative 970 C.1. Use Cases 972 We present a number of use cases were YANG instance data is needed. 974 C.1.1. Use Case 1: Early Documentation of Server Capabilities 976 A YANG server has a number of server-capabilities that are defined in 977 YANG modules and can be retrieved from the server using protocols 978 like NETCONF or RESTCONF. YANG server capabilities include 980 o data defined in ietf-yang-library: YANG modules, submodules, 981 features, deviations, schema-mounts, datastores supported 982 ([I-D.ietf-netconf-rfc7895bis]) 984 o alarms supported ([I-D.ietf-ccamp-alarm-module]) 986 o data nodes, subtrees that support or do not support on-change 987 notifications ([I-D.ietf-netconf-yang-push]) 989 o netconf-capabilities in ietf-netconf-monitoring 991 While it is good practice to allow a client to query these 992 capabilities from the live YANG server, that is often not possible. 994 Often when a network node is released an associated NMS (network 995 management system) is also released with it. The NMS depends on the 996 capabilities of the YANG server. During NMS implementation 997 information about server capabilities is needed. If the information 998 is not available early in some off-line document, but only as 999 instance data from the live network node, the NMS implementation will 1000 be delayed, because it has to wait for the network node to be ready. 1001 Also assuming that all NMS implementors will have a correctly 1002 configured network node available to retrieve data from, is a very 1003 expensive proposition. (An NMS may handle dozens of node types.) 1005 Network operators often build their own home-grown NMS systems that 1006 needs to be integrated with a vendor's network node. The operator 1007 needs to know the network node's server capabilities in order to do 1008 this. Moreover the network operator's decision to buy a vendor's 1009 product may even be influenced by the network node's OAM feature set 1010 documented as the Yang server's capabilities. 1012 Beside NMS implementors, system integrators and many others also need 1013 the same information early. Examples could be model driven testing, 1014 generating documentation, etc. 1016 Most server-capabilities are relatively stable and change only during 1017 upgrade or due to licensing or addition or removal of HW. They are 1018 usually defined by a vendor at design time, before the product is 1019 released. It feasible and advantageous to define/document them early 1020 e.g. in a YANG instance data File. 1022 It is anticipated that a separate IETF document will define in detail 1023 how and which set of server capabilities should be documented. 1025 C.1.2. Use Case 2: Preloading Data 1027 There are parts of the configuration that must be fully configurable 1028 by the operator, however for which often a simple default 1029 configuration will be sufficient. 1031 One example is access control groups/roles and related rules. While 1032 a sophisticated operator may define dozens of different groups often 1033 a basic (read-only operator, read-write system administrator, 1034 security-administrator) triplet will be enough. Vendors will often 1035 provide such default configuration data to make device configuration 1036 easier for an operator. 1038 Defining Access control data is a complex task. To help the device 1039 vendor pre-defines a set of default groups (/nacm:nacm/groups) and 1040 rules for these groups to access specific parts of common models 1041 (/nacm:nacm/rule-list/rule). 1043 YANG instance data files are used to document and/or preload the 1044 default configuration. 1046 C.1.3. Use Case 3: Documenting Factory Default Settings 1048 Nearly every YANG server has a factory default configuration. If the 1049 system is really badly misconfigured or if the current configuration 1050 is to be abandoned the system can be reset to this default. 1052 In Netconf the operation can already be used to reset 1053 the startup datastore. There are ongoing efforts to introduce a new, 1054 more generic reset-datastore operation for the same purpose 1055 [I-D.wu-netconf-restconf-factory-restore] 1057 The operator currently has no way to know what the default 1058 configuration actually contains. YANG instance data can be used to 1059 document the factory default configuration. 1061 Authors' Addresses 1062 Balazs Lengyel 1063 Ericsson 1064 Magyar Tudosok korutja 11 1065 1117 Budapest 1066 Hungary 1068 Phone: +36-70-330-7909 1069 Email: balazs.lengyel@ericsson.com 1071 Benoit Claise 1072 Cisco Systems, Inc. 1073 De Kleetlaan 6a b1 1074 1831 Diegem 1075 Belgium 1077 Phone: +32 2 704 5622 1078 Email: bclaise@cisco.com