idnits 2.17.1 draft-ietf-netmod-yang-instance-file-format-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == 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 (December 3, 2019) is 1605 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 920, but no explicit reference was found in the text == Outdated reference: A later version (-05) exists of draft-ietf-netmod-yang-data-ext-04 == Outdated reference: A later version (-15) exists of draft-ietf-netmod-factory-default-07 Summary: 0 errors (**), 0 flaws (~~), 5 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: June 5, 2020 Cisco Systems, Inc. 6 December 3, 2019 8 YANG Instance Data File Format 9 draft-ietf-netmod-yang-instance-file-format-06 11 Abstract 13 There is a need to document data defined in YANG models when a live 14 server is not available. Data is often needed already at design or 15 implementation time or needed by groups that do not have a live 16 running server available. This document specifies a standard file 17 format for YANG instance data (which follows the syntax and semantic 18 from existing YANG models, re-using the same format as the reply to a 19 operation/request) and annotates 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 June 5, 2020. 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. Principles . . . . . . . . . . . . . . . . . . . . . . . 4 58 3. Instance Data File Format . . . . . . . . . . . . . . . . . . 4 59 3.1. Specifying the Content Schema . . . . . . . . . . . . . . 6 60 3.1.1. Inline Method . . . . . . . . . . . . . . . . . . . . 7 61 3.1.2. Simplified-Inline Method . . . . . . . . . . . . . . 7 62 3.1.3. URI Method . . . . . . . . . . . . . . . . . . . . . 8 63 3.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8 64 4. Data Life cycle . . . . . . . . . . . . . . . . . . . . . . . 12 65 5. Delivery of Instance Data . . . . . . . . . . . . . . . . . . 13 66 6. Backwards Compatibility . . . . . . . . . . . . . . . . . . . 13 67 7. YANG Instance Data Model . . . . . . . . . . . . . . . . . . 13 68 7.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 13 69 7.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 14 70 8. Security Considerations . . . . . . . . . . . . . . . . . . . 19 71 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 72 9.1. URI Registration . . . . . . . . . . . . . . . . . . . . 20 73 9.2. YANG Module Name Registration . . . . . . . . . . . . . . 20 74 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 20 75 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 76 11.1. Normative References . . . . . . . . . . . . . . . . . . 20 77 11.2. Informative References . . . . . . . . . . . . . . . . . 22 78 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 22 79 Appendix B. Changes between revisions . . . . . . . . . . . . . 22 80 Appendix C. Detailed Use Cases - Non-Normative . . . . . . . . . 24 81 C.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 24 82 C.1.1. Use Case 1: Early Documentation of Server 83 Capabilities . . . . . . . . . . . . . . . . . . . . 24 84 C.1.2. Use Case 2: Preloading Data . . . . . . . . . . . . . 25 85 C.1.3. Use Case 3: Documenting Factory Default Settings . . 26 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 88 1. Terminology 90 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 91 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 92 "OPTIONAL" in this document are to be interpreted as described in BCP 93 14 RFC 2119 [RFC2119] RFC 8174 [RFC8174] when, and only when, they 94 appear in all capitals, as shown here. 96 Instance Data Set: A named set of data items annotated with metadata 97 that can be used as instance data in a YANG data tree. 99 Instance Data File: A file containing an instance data set formatted 100 according to the rules described in this document. 102 Content-schema: A set of YANG modules with their revision, supported 103 features, and deviations for which the instance data set contains 104 instance data 106 Content defining YANG module(s): YANG module(s) that make up the 107 content-schema 109 YANG Instance Data, or just instance data for short, is data that 110 could be stored in a datastore and whose syntax and semantics is 111 defined by YANG models. 113 The term Server is used as defined in [RFC8342] 115 2. Introduction 117 There is a need to document data defined in YANG models when a live 118 server is not available. Data is often needed already at design or 119 implementation time or needed by groups that do not have a live 120 running server available. To facilitate this offline delivery of 121 data, this document specifies a standard format for YANG instance 122 data sets and YANG instance data files. 124 The following is a list of already implemented and potential use 125 cases. 127 UC1 Documentation of server capabilities 129 UC2 Preloading default configuration data 131 UC3 Documenting Factory Default Settings 133 UC4 Instance data used as backup 135 UC5 Storing the configuration of a device, e.g., for archive or 136 audit purposes 138 UC6 Storing diagnostics data 140 UC7 Allowing YANG instance data to potentially be carried within 141 other IPC message formats 143 UC8 Default instance data used as part of a templating solution 144 UC9 Providing data examples in RFCs or internet drafts 146 In Appendix C we describe the first three use cases in detail. 148 There are many and varied use cases where YANG instance data could be 149 used. We do not want to limit future uses of instance data sets, so 150 specifying how and when to use YANG instance data is out of scope for 151 this document. It is anticipated that other documents will define 152 specific use cases. Use cases are listed here only to indicate the 153 need for this work. 155 2.1. Principles 157 The following is a list of the basic principles of the instance data 158 format: 160 P1 Two standard formats shall be defined based on the XML and JSON 161 encodings. 163 P2 Instance data shall reuse existing formats similar to the 164 response to a operation/request. 166 P3 Metadata about the instance data set (Section 3, Paragraph 9) 167 shall be defined. 169 P4 A YANG instance data set shall be allowed to contain data for 170 many YANG modules. 172 P5 Instance data shall be allowed to contain configuration data, 173 state data, or a mix of the two. 175 P6 Partial data sets shall be allowed. 177 P7 The YANG instance data format shall be usable for any data for 178 which YANG module(s) are defined and available to the reader, 179 independent of whether the module is actually implemented by a 180 server. 182 3. Instance Data File Format 184 A YANG instance data file MUST contain a single instance data set and 185 no additional data. 187 The format of the instance data set is defined by the ietf-yang- 188 instance-data YANG module. It is made up of a header part and 189 content-data. The header part carries metadata for the instance data 190 set. The content-data, defined as an anydata data node, carries the 191 "real data" that we want to document/provide. The syntax and 192 semantics of content-data is defined by the content-schema. 194 Two formats are specified based on the XML and JSON YANG encodings. 195 Later as other YANG encodings (e.g., CBOR) are defined, further 196 instance data formats may be specified. 198 The content-data part SHALL follow the encoding rules defined in 199 [RFC7950] for XML and [RFC7951] for JSON and MUST use UTF-8 character 200 encoding. Content-data MAY include: 202 metadata as defined by [RFC7952]. 204 a default attribute as defined in [RFC6243] section 6. and in 205 [RFC8040] section 4.8.9. 207 origin metadata as specified in [RFC8526] and [RFC8527] 209 implementation specific metadata. Unknown metadata MUST be 210 ignored by users of YANG instance data, allowing it to be used 211 later for other purposes. 213 in the XML format implementation specific XML attributes, unknown 214 attributes MUST be ignored by users of YANG instance data, 215 allowing them to be used later for other purposes. 217 The content-data part will be very similar to the result returned for 218 a NETCONF or for a RESTCONF get operation. 220 The content-data part MUST conform to the content-schema. An 221 instance data set MAY contain data for any number of YANG modules; if 222 needed it MAY carry the complete configuration and state data set for 223 a server. Default values 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, require-instance=true, must and when 230 constrains MAY be violated. 232 The name of the instance data file SHOULD take one of the following 233 two forms: 235 If revision information inside the data set is present 237 * instance-data-set-name ['@' revision-date] '.filetype' 238 * E.g., acme-router-modules@2018-01-25.xml 240 If the leaf "name" is present in the instance data header, this 241 MUST be used. If the "revision-date" is present in both the 242 filename and in the instance data header, the revision date in the 243 file name MUST be set to the latest revision date inside the 244 instance data set. 246 If timestamp information inside the data set is present 248 * instance-data-set-name ['@' timestamp] '.filetype' 250 * E.g., acme-router-modules@2018-01-25T15_06_34_3+01_00.json 252 If the leaf "name" is present in the instance data header, this 253 MUST be used. If the "timestamp" is present both in the filename 254 and in the instance data header, the timestamp in the file name 255 MUST be set to the timestamp inside the instance data set; the 256 semicolons and the decimal point, if present, shall be replaced by 257 underscores. 259 The revision date or timestamp is optional. ".filetype" SHALL be 260 ".json" or ".xml" according to the format used. 262 Metadata, information about the data set itself SHOULD be included in 263 the instance data set. Some metadata items are defined in the YANG 264 module ietf-yang-instance-data, but other items MAY also be used. 265 Metadata MUST include: 267 Version of the YANG Instance Data format 269 Metadata SHOULD include: 271 o Name of the data set 273 o Content schema specification 275 o Description of the instance data set. The description SHOULD 276 contain information whether and how the data can change during the 277 lifetime of the server. 279 3.1. Specifying the Content Schema 281 To properly understand and use an instance data set, the user needs 282 to know the content-schema. One of the following methods SHOULD be 283 used: 285 Inline method: Include the needed information as part of the 286 instance data set. 288 Simplified-Inline method: Include the needed information as part 289 of the instance data set; short specification. 291 URI method: Include a URI that references another YANG instance 292 data file. This instance data file will use the same content- 293 schema as the referenced YANG instance data file. (if you don't 294 want to repeat the info again and again) 296 EXTERNAL Method: Do not include the content-schema as it is 297 already known, or the information is available through external 298 documents. 300 Additional methods e.g., a YANG-package based solution may be added 301 later. 303 Note, the specified content-schema only indicates the set of modules 304 that were used to define this YANG instance data set. Sometimes 305 instance data may be used for a server supporting a different YANG 306 module set. (e.g., for "UC2 Preloading Data" the instance data set 307 may not be updated every time the YANG modules on the server are 308 updated) Whether the instance data set is usable for a possibly 309 different real-life YANG module set depends on many factors including 310 the compatibility between the specified and the real-life YANG module 311 set, considering modules, revisions, features, deviations, the scope 312 of the instance data, etc. 314 3.1.1. Inline Method 316 One or more inline-module elements define YANG module(s) used to 317 specify the content defining YANG modules. 319 E.g., ietf-yang-library@2016-06-21 321 The anydata inline-schema carries instance data (conforming to the 322 inline-modules) that actually specifies the content defining YANG 323 modules including revision, supported features, deviations and any 324 relevant additional data (e.g., version labels) 326 3.1.2. Simplified-Inline Method 328 The instance data set contains a list of content defining YANG 329 modules including the revision date for each. Usage of this method 330 implies that the modules are used without any deviations and with all 331 features supported. 333 3.1.3. URI Method 335 The same-schema-as-file leaf SHALL contain a URI that references 336 another YANG instance data file. The current instance data file will 337 use the same content schema as the referenced file. 339 The referenced instance data file MAY have no content-data if it is 340 used solely for specifying the content-schema. 342 If a referenced instance data file is not available, content-schema 343 is unknown. 345 The URI method is advantageous when the user wants to avoid the 346 overhead of specifying the content-schema in each instance data file: 347 E.g., In Use Case 6, when the system creates a diagnostic file every 348 minute to document the state of the server. 350 3.2. Examples 352 The following example is based on "UC1, Documenting Server 353 Capabilities". It provides (a shortened) list of supported YANG 354 modules and NETCONF capabilities for a server. It uses the inline 355 method to specify the content-schema. 357 358 360 acme-router-modules 361 1 362 363 364 ietf-yang-library@2016-06-21 365 366 367 369 370 ietf-yang-library 371 2016-06-21 372 373 374 ietf-netconf-monitoring 375 2010-10-04 376 377 378 379 380 381 1956-10-23 382 Initial version 383 384 Defines the minimal set of modules that any acme-router 385 will contain. 386 info@acme.com 387 388 391 392 393 ietf-yang-library 394 2016-06-21 395 396 urn:ietf:params:xml:ns:yang:ietf-yang-library 397 398 implement 399 400 401 ietf-system 402 2014-08-06 403 urn:ietf:params:xml:ns:yang:ietf-system 404 sys:authentication 405 sys:local-users 406 407 acme-system-ext 408 2018-08-06 409 410 implement 411 412 413 ietf-yang-types 414 2013-07-15 415 urn:ietf:params:xml:ns:yang:ietf-yang-types 416 417 import 418 419 420 acme-system-ext 421 2018-08-06 422 urn:rdns:acme.com:oammodel:acme-system-ext 423 424 implement 425 426 427 430 431 432 urn:ietf:params:netconf:capability:validate:1.1 433 434 435 436 437 439 Figure 1: XML Instance Data Set - Use case 1, Documenting server 440 capabilities 442 The following example is based on "UC2, Preloading Default 443 Configuration". It provides a (shortened) default rule set for a 444 read-only operator role. It uses the inline method for specifying 445 the content-schema. 447 448 450 read-only-acm-rules 451 1 452 453 ietf-yang-library@2019-01-04 454 455 457 458 all 459 460 ietf-netconf-acm 461 2012-02-22 462 463 464 465 466 467 468 1776-07-04 469 Initial version 470 471 Access control rules for a read-only role. 472 473 474 true 475 deny 476 deny 477 478 read-only-role 479 read-only-group 480 481 read-all 482 * 483 read 484 permit 485 486 487 488 489 491 Figure 2: XML Instance Data Set - Use case 2, Preloading access 492 control data 494 The following example is based on UC6 Storing diagnostics data. An 495 instance data set is produced by the server every 15 minutes that 496 contains statistics about NETCONF. As a new set is produced 497 periodically many times a day a revision-date would be useless; 498 instead a timestamp is included. 500 { 501 "ietf-yang-instance-data:instance-data-set": { 502 "name": "acme-router-netconf-diagnostics", 503 "yid-version": "1", 504 "content-schema": { 505 "same-schema-as-file": "file:///acme-diagnostics-schema.json", 506 }, 507 "timestamp": "2018-01-25T17:00:38Z", 508 "description": 509 "NETCONF statistics", 510 "content-data": { 511 "ietf-netconf-monitoring:netconf-state": { 512 "statistics": { 513 "netconf-start-time ": "2018-12-05T17:45:00Z", 514 "in-bad-hellos ": "32", 515 "in-sessions ": "397", 516 "dropped-sessions ": "87", 517 "in-rpcs ": "8711", 518 "in-bad-rpcs ": "408", 519 "out-rpc-errors ": "408", 520 "out-notifications": "39007" 521 } 522 } 523 } 524 } 525 } 527 Figure 3: JSON Instance Data File example - UC6 Storing diagnostics 528 data 530 4. Data Life cycle 532 In UC2 "Preloading default configuration data", the loaded data may 533 be changed later e.g., by management operations. In UC6 "Storing 534 Diagnostics data", the diagnostics values may change on device every 535 second. 537 YANG instance data is a snapshot of information at a specific point 538 of time. If the data changes afterwards, this is not represented in 539 the instance data set anymore. The valid values can be retrieved at 540 run-time via NETCONF/RESTCONF or received e.g., in YANG-Push 541 notifications. 543 Whether the instance data changes and if so, when and how, SHOULD be 544 described either in the instance data set's description statement or 545 in some other implementation specific manner. 547 5. Delivery of Instance Data 549 Instance data sets that are produced as a result of some sort of 550 specification or design effort SHOULD be available without the need 551 for a live server e.g., via download from the vendor's website, or in 552 any other way that product documentation is distributed. 554 Other instance data sets may be read from or produced by the YANG 555 server itself e.g., UC6 documenting diagnostic data. 557 6. Backwards Compatibility 559 The concept of backwards compatibility and what changes are backwards 560 compatible are not defined for instance data sets as it is highly 561 dependent on the specific use case and the content-schema. 563 For instance data that is the result of a design or specification 564 activity, some changes that may be good to avoid are listed. YANG 565 uses the concept of managed entities identified by key values; if the 566 connection between the represented entity and the key value is not 567 preserved during an update, this may lead to problems. 569 o If the key value of a list entry that represents the same managed 570 entity as before is changed, the user may mistakenly identify the 571 list entry as new. 573 o If the meaning of a list entry is changed, but the key values are 574 not (e.g., redefining an alarm-type but not changing its alarm- 575 type-id) the change may not be noticed. 577 o If the key value of a previously removed list entry is reused for 578 a different entity, the change may be misinterpreted as 579 reintroducing the previous entity. 581 7. YANG Instance Data Model 583 7.1. Tree Diagram 585 The following tree diagram [RFC8340] provides an overview of the data 586 model. 588 module: ietf-yang-instance-data 589 structure instance-data-set: 590 +--rw name? string 591 +--rw yid-version uint8 592 +--rw content-schema 593 | +--rw (content-schema-spec)? 594 | +--:(simplified-inline) 595 | | +--rw module* string 596 | +--:(inline) {inline-content-schema}? 597 | | +--rw inline-module* string 598 | | +--rw inline-schema 599 | +--:(uri) 600 | +--rw same-schema-as-file? inet:uri 601 +--rw description? string 602 +--rw contact? string 603 +--rw organization? string 604 +--rw datastore? ds:datastore-ref 605 +--rw revision* [date] 606 | +--rw date string 607 | +--rw description? string 608 +--rw timestamp? yang:date-and-time 609 +--rw content-data? 611 7.2. YANG Model 613 file "ietf-yang-instance-data@2019-11-17.yang" 614 module ietf-yang-instance-data { 615 yang-version 1.1; 616 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data"; 617 prefix yid; 619 import ietf-yang-structure-ext { 620 prefix sx; 621 } 622 import ietf-datastores { 623 prefix ds; 624 } 625 import ietf-inet-types { 626 prefix inet; 627 } 628 import ietf-yang-types { 629 prefix yang; 630 } 632 organization 633 "IETF NETMOD Working Group"; 634 contact 635 "WG Web: 636 WG List: 638 Author: Balazs Lengyel 639 "; 640 description 641 "The module defines the structure and content of YANG 642 instance data sets. 644 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 645 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 646 'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document 647 are to be interpreted as described in BCP 14 (RFC 2119) 648 (RFC 8174) when, and only when, they appear in all 649 capitals, as shown here. 651 Copyright (c) 2019 IETF Trust and the persons identified as 652 authors of the code. All rights reserved. 654 Redistribution and use in source and binary forms, with or 655 without modification, is permitted pursuant to, and subject 656 to the license terms contained in, the Simplified BSD License 657 set forth in Section 4.c of the IETF Trust's Legal Provisions 658 Relating to IETF Documents 659 (http://trustee.ietf.org/license-info). 661 This version of this YANG module is part of RFC XXXX; see 662 the RFC itself for full legal notices."; 664 revision 2019-11-17 { 665 description 666 "Initial revision."; 667 reference 668 "RFC XXXX: YANG Instance Data Format"; 669 } 671 feature inline-content-schema { 672 description 673 "This feature indicates that inline content-schema 674 option is supported."; 675 } 677 sx:structure "instance-data-set" { 678 description 679 "A data structure to define a format for 680 YANG instance data sets. Consists of meta-data about 681 the instance data set and the real content-data."; 682 leaf name { 683 type string; 684 description 685 "Name of the YANG instance data set."; 686 } 687 leaf yid-version { 688 type uint8; 689 mandatory true; 690 description 691 "Version number of the 'YANG Instance Data format'. 692 It MUST contain the value '1' for instance data 693 based on this specification."; 694 } 695 container content-schema { 696 description 697 "The content schema used to create the instance data set"; 698 choice content-schema-spec { 699 description 700 "Specification of the content-schema"; 701 case simplified-inline { 702 leaf-list module { 703 type string ; 704 description 705 "The list of content defining YANG modules. 706 The value SHALL start with the module name. 707 If the module contains a revision statement the 708 revision date SHALL be included in the leaf-list 709 entry. 710 If other methods (e.g., revision-label) are 711 defined to identify individual module revisions 712 those MAY be used instead of using a revision date. 714 E.g., ietf-yang-library@2016-06-21 716 Usage of this leaf-list implies the modules are 717 used without any deviations and with all features 718 supported. Multiple revisions of the same module 719 MUST NOT be specified."; 720 } 721 } 722 case inline { 723 if-feature inline-content-schema; 724 leaf-list inline-module { 725 type string ; 726 min-elements 1; 727 ordered-by user; 728 description 729 "Indicates that content defining YANG modules 730 are specified inline. 731 The value SHALL start with the module name. 733 If the module contains a revision statement the 734 revision date SHALL be included in the leaf-list 735 entry. 736 If other methods (e.g., revision-label) are 737 defined to identify individual module revisions 738 those MAY be used instead of using a revision date. 740 E.g., ietf-yang-library@2016-06-21 742 The first item is either ietf-yang-library or some other 743 YANG module that contains a list of YANG modules with 744 their name, revision-date, supported-features, and 745 deviations. 746 As some versions of ietf-yang-library MAY contain 747 different module-sets for different datastores, if 748 multiple module-sets are included, the instance data 749 set's meta-data MUST contain the datastore information 750 and instance data for the ietf-yang-library MUST also 751 contain information specifying the module-set for the 752 relevant datastore. 754 Subsequent items MAY specify YANG modules augmenting the 755 first module with useful data (e.g., a version label)."; 756 } 757 anydata inline-schema { 758 mandatory true; 759 description 760 "Instance data corresponding to the YANG modules 761 specified in the inline-module nodes defining the set 762 of content defining YANG modules for this 763 instance-data-set."; 764 } 765 } 766 case uri { 767 leaf same-schema-as-file { 768 type inet:uri; 769 description 770 "A reference to another YANG instance data file. 771 This instance data file uses the same 772 content schema as the referenced file."; 773 } 774 } 775 } 776 } 777 leaf-list description { 778 type string; 779 description 780 "Description of the instance data set."; 782 } 783 leaf contact { 784 type string; 785 description 786 "Contact information for the person or 787 organization to whom queries concerning this 788 instance data set should be sent."; 789 } 790 leaf organization { 791 type string; 792 description 793 "Organization responsible for the instance 794 data set."; 795 } 796 leaf datastore { 797 type ds:datastore-ref; 798 description 799 "The identity of the datastore with which the 800 instance data set is associated, e.g., the datastore from 801 where the data was read or the datastore into which the data 802 may be loaded or the datastore which is being documented. 803 If a single specific datastore cannot be specified, the 804 leaf MUST be absent. 806 If this leaf is absent, then the datastore to which the 807 instance data belongs is undefined."; 808 } 809 list revision { 810 key "date"; 811 description 812 "Instance data sets that are produced as 813 a result of some sort of specification or design effort 814 SHOULD have at least one revision entry. For every 815 published editorial change, a new one SHOULD be added 816 in front of the revisions sequence so that all 817 revisions are in reverse chronological order. 819 For instance data sets that are read from 820 or produced by a server or otherwise 821 subject to frequent updates or changes, revision 822 SHOULD NOT be present"; 823 leaf date { 824 type string { 825 pattern '\d{4}-\d{2}-\d{2}'; 826 } 827 description 828 "Specifies the date the instance data set 829 was last modified. Formatted as YYYY-MM-DD"; 831 } 832 leaf description { 833 type string; 834 description 835 "Description of this revision of the instance data set."; 836 } 837 } 838 leaf timestamp { 839 type yang:date-and-time; 840 description 841 "The date and time when the instance data set 842 was last modified. 844 For instance data sets that are read from or produced 845 by a server or otherwise subject to frequent 846 updates or changes, timestamp SHOULD be present"; 847 } 848 anydata content-data { 849 description 850 "Contains the real instance data. 851 The data MUST conform to the relevant YANG Modules specified 852 either in the content-schema-spec or in some other 853 implementation specific manner."; 854 } 855 } 856 } 857 859 8. Security Considerations 861 The YANG module defined in this document is designed as a wrapper 862 specifying a format and a metadata header for YANG instance data 863 defined by the content-schema. The data is designed to be accessed 864 as a stored file or over any file access method or protocol. 866 The document does not specify any method to influence the behavior of 867 a server. 869 Instance data files may contain sensitive data. 871 The header part is not security sensitive. 873 The security sensitivity of the instance data in the content part is 874 completely dependent on the content schema. Depending on the nature 875 of the instance data, instance data files MAY need to be handled in a 876 secure way. The same kind of handling should be applied, that would 877 be needed for the result of a operation returning the same 878 data. 880 Instance data files should be protected against modification or 881 unauthorized access using normal file handling mechanisms. 883 9. IANA Considerations 885 This document registers one URI and one YANG module. 887 9.1. URI Registration 889 This document registers one URI in the IETF XML registry [RFC3688]. 890 Following the format in RFC 3688, the following registration is 891 requested to be made: 893 URI: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data 895 Registrant Contact: The IESG. 897 XML: N/A, the requested URI is an XML namespace. 899 9.2. YANG Module Name Registration 901 This document registers one YANG module in the YANG Module Names 902 registry [RFC6020]. 904 name: ietf-yang-instance-data 905 namespace: urn:ietf:params:xml:ns:yang:ietf-yang-instance-data 906 prefix: yid 907 reference: RFC XXXX 909 10. Acknowledgments 911 For their valuable comments, discussions, and feedback, we wish to 912 acknowledge Andy Bierman, Juergen Schoenwaelder, Rob Wilton, Joe 913 Clarke, Kent Watsen Martin Bjorklund, Ladislav Lhotka, Qin Wu and 914 other members of the Netmod WG. 916 11. References 918 11.1. Normative References 920 [I-D.ietf-netmod-yang-data-ext] 921 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Data 922 Structure Extensions", draft-ietf-netmod-yang-data-ext-04 923 (work in progress), July 2019. 925 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 926 DOI 10.17487/RFC3688, January 2004, 927 . 929 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 930 the Network Configuration Protocol (NETCONF)", RFC 6020, 931 DOI 10.17487/RFC6020, October 2010, 932 . 934 [RFC6243] Bierman, A. and B. Lengyel, "With-defaults Capability for 935 NETCONF", RFC 6243, DOI 10.17487/RFC6243, June 2011, 936 . 938 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 939 RFC 7950, DOI 10.17487/RFC7950, August 2016, 940 . 942 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", 943 RFC 7951, DOI 10.17487/RFC7951, August 2016, 944 . 946 [RFC7952] Lhotka, L., "Defining and Using Metadata with YANG", 947 RFC 7952, DOI 10.17487/RFC7952, August 2016, 948 . 950 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 951 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 952 . 954 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 955 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 956 . 958 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 959 and R. Wilton, "Network Management Datastore Architecture 960 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 961 . 963 [RFC8526] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 964 and R. Wilton, "NETCONF Extensions to Support the Network 965 Management Datastore Architecture", RFC 8526, 966 DOI 10.17487/RFC8526, March 2019, 967 . 969 [RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 970 and R. Wilton, "RESTCONF Extensions to Support the Network 971 Management Datastore Architecture", RFC 8527, 972 DOI 10.17487/RFC8527, March 2019, 973 . 975 11.2. Informative References 977 [I-D.ietf-netmod-factory-default] 978 WU, Q., Lengyel, B., and Y. Niu, "Factory Default 979 Setting", draft-ietf-netmod-factory-default-07 (work in 980 progress), November 2019. 982 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 983 Requirement Levels", BCP 14, RFC 2119, 984 DOI 10.17487/RFC2119, March 1997, 985 . 987 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 988 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 989 May 2017, . 991 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K., 992 and R. Wilton, "YANG Library", RFC 8525, 993 DOI 10.17487/RFC8525, March 2019, 994 . 996 [RFC8632] Vallin, S. and M. Bjorklund, "A YANG Data Model for Alarm 997 Management", RFC 8632, DOI 10.17487/RFC8632, September 998 2019, . 1000 [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications 1001 for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, 1002 September 2019, . 1004 Appendix A. Open Issues 1006 o - 1008 Appendix B. Changes between revisions 1010 v05 - v06 1012 o Modified module name format, removed .yin or .yang extension 1014 o Removed pattern for module and inline-module. We want to allow 1015 the usage of revision-label later 1017 v04 - v05 1019 o Updated according to YANG-Doctor review 1021 o Updated security considerations 1022 o Added a wrapping container for the schema, and renamed the data 1023 nodes in the inline and uri cases. 1025 o Allowed .yin for simplified-inline schema naming. Made date 1026 optional if it is not available in the YANG module. 1028 o Added a mandatory yid-version to the header metadata to allow 1029 later updates of the module. 1031 v03 - v04 1033 o removed entity-tag and last-modified timestamp 1035 o Added simplified-inline method of content-schema specification 1037 v02 - v03 1039 o target renamed to "content-schema" and "content defining YANG 1040 module(s)" 1042 o Made name of instance data set optional 1044 o Updated according to draft-ietf-netmod-yang-data-ext-03 1046 o Clarified that entity-tag and last-modified timestamp are encoded 1047 as metadata. While they contain useful data, the HTTP-header 1048 based encoding from Restconf is not suitable. 1050 v01 - v02 1052 o Removed design time from terminology 1054 o Defined the format of the content-data part by referencing various 1055 RFCs and drafts instead of the result of the get-data and get 1056 operations. 1058 o Changed target-ptr to a choice 1060 o Inline target-ptr may include augmenting modules and alternatives 1061 to ietf-yang-library 1063 o Moved list of target modules into a separate 1064 element. 1066 o Added backwards compatibility considerations 1068 v00 - v01 1069 o Added the target-ptr metadata with 3 methods 1071 o Added timestamp metadata 1073 o Removed usage of dedicated .yid file extension 1075 o Added list of use cases 1077 o Added list of principles 1079 o Updated examples 1081 o Moved detailed use case descriptions to appendix 1083 Appendix C. Detailed Use Cases - Non-Normative 1085 C.1. Use Cases 1087 We present a number of use cases were YANG instance data is needed. 1089 C.1.1. Use Case 1: Early Documentation of Server Capabilities 1091 A server has a number of server-capabilities that are defined in YANG 1092 modules and can be retrieved from the server using protocols like 1093 NETCONF or RESTCONF. Server capabilities include: 1095 o data defined in ietf-yang-library: YANG modules, submodules, 1096 features, deviations, schema-mounts, and datastores supported 1097 ([RFC8525]) 1099 o alarms supported ([RFC8632]) 1101 o data nodes and subtrees that support or do not support on-change 1102 notifications ([RFC8641]) 1104 o netconf-capabilities in ietf-netconf-monitoring 1106 While it is good practice to allow a client to query these 1107 capabilities from the live server, that is often not possible. 1109 Often when a network node is released, an associated NMS (network 1110 management system) is also released with it. The NMS depends on the 1111 capabilities of the server. During NMS implementation, information 1112 about server capabilities is needed. If the information is not 1113 available early in some offline document, but only as instance data 1114 from the live network node, the NMS implementation will be delayed, 1115 because it has to wait until the network node is ready. Also 1116 assuming that all NMS implementors will have a correctly configured 1117 network nodes from which data can be retrieved, is a very expensive 1118 proposition. (An NMS may handle dozens of node types.) 1120 Network operators often build their own home-grown NMS systems that 1121 need to be integrated with a vendor's network node. The operator 1122 needs to know the network node's server capabilities in order to do 1123 this. Moreover, the network operator's decision to buy a vendor's 1124 product may even be influenced by the network node's OAM feature set 1125 documented as the server's capabilities. 1127 Beside NMS implementors, system integrators and many others also need 1128 the same information early. Examples could be model driven testing, 1129 generating documentation, etc. 1131 Most server-capabilities are relatively stable and change only during 1132 upgrade or due to licensing or the addition or removal of hardware. 1133 They are usually defined by a vendor at design time, before the 1134 product is released. It is feasible and advantageous to define/ 1135 document them early e.g., in a YANG instance data File. 1137 It is anticipated that a separate IETF document will define in detail 1138 how and which set of server capabilities should be documented. 1140 C.1.2. Use Case 2: Preloading Data 1142 There are parts of the configuration that must be fully configurable 1143 by the operator. However, often a simple default configuration will 1144 be sufficient. 1146 One example is access control groups/roles and related rules. While 1147 a sophisticated operator may define dozens of different groups, often 1148 a basic (read-only operator, read-write system administrator, 1149 security-administrator) triplet will be enough. Vendors will often 1150 provide such default configuration data to make device configuration 1151 easier for an operator. 1153 Defining access control data is a complex task. To help, the device 1154 vendor predefines a set of default groups (/nacm:nacm/groups) and 1155 rules for these groups to access specific parts of common models 1156 (/nacm:nacm/rule-list/rule). 1158 YANG instance data files are used to document and/or preload the 1159 default configuration. 1161 C.1.3. Use Case 3: Documenting Factory Default Settings 1163 Nearly every server has a factory default configuration. If the 1164 system is really badly misconfigured or if the current configuration 1165 is to be abandoned, the system can be reset the default factory 1166 configuration. 1168 In NETCONF, the operation can already be used to 1169 reset the startup datastore. There are ongoing efforts to introduce 1170 a new, more generic factory-reset operation for the same purpose 1171 [I-D.ietf-netmod-factory-default] 1173 The operator currently has no way to know what the default 1174 configuration actually contains. YANG instance data can also be used 1175 to document the factory default configuration. 1177 Authors' Addresses 1179 Balazs Lengyel 1180 Ericsson 1181 Magyar Tudosok korutja 11 1182 1117 Budapest 1183 Hungary 1185 Phone: +36-70-330-7909 1186 Email: balazs.lengyel@ericsson.com 1188 Benoit Claise 1189 Cisco Systems, Inc. 1190 De Kleetlaan 6a b1 1191 1831 Diegem 1192 Belgium 1194 Phone: +32 2 704 5622 1195 Email: bclaise@cisco.com