--- 1/draft-ietf-netmod-yang-instance-file-format-11.txt 2020-04-14 06:13:06.145690937 -0700 +++ 2/draft-ietf-netmod-yang-instance-file-format-12.txt 2020-04-14 06:13:06.177691385 -0700 @@ -1,19 +1,19 @@ Netmod B. Lengyel Internet-Draft Ericsson Intended status: Standards Track B. Claise -Expires: October 10, 2020 Cisco Systems, Inc. - April 8, 2020 +Expires: October 16, 2020 Cisco Systems, Inc. + April 14, 2020 YANG Instance Data File Format - draft-ietf-netmod-yang-instance-file-format-11 + draft-ietf-netmod-yang-instance-file-format-12 Abstract There is a need to document data defined in YANG models when a live server is unavailable. Data is often needed at design or implementation time or needed when a live running server is unavailable. This document specifies a standard file format for YANG instance data, which follows the syntax and semantics of existing YANG models, and annotates it with metadata. @@ -25,21 +25,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on October 10, 2020. + This Internet-Draft will expire on October 16, 2020. Copyright Notice Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -55,34 +55,34 @@ 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Principles . . . . . . . . . . . . . . . . . . . . . . . 4 1.3. Delivery of Instance Data . . . . . . . . . . . . . . . . 4 1.4. Data Life cycle . . . . . . . . . . . . . . . . . . . . . 5 2. Instance Data File Format . . . . . . . . . . . . . . . . . . 5 2.1. Specifying the Content Schema . . . . . . . . . . . . . . 7 2.1.1. Inline Method . . . . . . . . . . . . . . . . . . . . 7 2.1.2. Simplified-Inline Method . . . . . . . . . . . . . . 8 2.1.3. URI Method . . . . . . . . . . . . . . . . . . . . . 8 2.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8 - 2.2.1. UC1, Documenting Server Capabilities . . . . . . . . 8 - 2.2.2. UC2, Preloading Default Configuration . . . . . . . . 10 - 2.2.3. UC5, Storing diagnostics data . . . . . . . . . . . . 11 + 2.2.1. Documentation of server capabilities . . . . . . . . 8 + 2.2.2. Preloading default configuration data . . . . . . . . 10 + 2.2.3. Storing diagnostics data . . . . . . . . . . . . . . 11 3. YANG Instance Data Model . . . . . . . . . . . . . . . . . . 12 3.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 12 3.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 13 4. Security Considerations . . . . . . . . . . . . . . . . . . . 19 - 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 + 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 5.1. URI Registration . . . . . . . . . . . . . . . . . . . . 20 5.2. YANG Module Name Registration . . . . . . . . . . . . . . 20 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 20 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 7.1. Normative References . . . . . . . . . . . . . . . . . . 20 - 7.2. Informative References . . . . . . . . . . . . . . . . . 21 + 7.2. Informative References . . . . . . . . . . . . . . . . . 22 Appendix A. Changes between revisions . . . . . . . . . . . . . 22 Appendix B. Backwards Compatibility . . . . . . . . . . . . . . 25 Appendix C. Detailed Use Cases . . . . . . . . . . . . . . . . . 25 C.1. Use Case 1: Early Documentation of Server Capabilities . 25 C.2. Use Case 2: Preloading Data . . . . . . . . . . . . . . . 26 C.3. Use Case 3: Documenting Factory Default Settings . . . . 27 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 1. Introduction @@ -238,68 +238,55 @@ if needed it MAY carry the complete configuration and state data for a server. Default values SHOULD NOT be included. Configuration ("config true") and operational state data ("config false") MAY be mixed in the instance data file. Instance data files MAY contain partial data sets. This means "mandatory", "min-elements", "require-instance true", "must" and "when" constrains MAY be violated. - The name of the instance data file SHOULD take one of the following - two forms: - - If "revision" information is present inside the data set: + The name of the instance data file SHOULD be of the form: - instance-data-set-name ['@' revision-date] '.filetype' + instance-data-set-name ['@' ( revision-date / timestamp ) ] + ( '.xml' / '.json' ) E.g., acme-router-modules@2018-01-25.xml - - If the leaf "name" is present in the instance data header, its - value SHOULD be used for the "instance-data-set-name". If the - "revision-date" is present in both the filename and in the - instance data header, the revision date in the file name MUST be - set to the latest revision date inside the instance data set. - - If timestamp information inside the data set is present - - instance-data-set-name ['@' timestamp] '.filetype' - E.g., acme-router-modules@2018-01-25T15_06_34_3+01_00.json - If the leaf "name" is present in the instance data header, its - value SHOULD be used for the "instance-data-set-name". If the - "timestamp" is present both in the filename and in the instance - data header, the timestamp in the file name SHOULD be set to the - timestamp inside the instance data set; the semicolons and the - decimal point, if present, shall be replaced by underscores. - - The revision date or timestamp is optional. ".filetype" SHOULD be - ".json" or ".xml" according to the format used. + If the leaf "name" is present in the instance data header, its value + SHOULD be used for the "instance-data-set-name". If the "revision- + date" is present in both the filename and in the instance data + header, the revision date in the file name MUST be set to the latest + revision date inside the instance data set. If the "timestamp" is + present both in the filename and in the instance data header, the + timestamp in the file name SHOULD be set to the timestamp inside the + instance data set; the colons and the decimal point, if present, + shall be replaced by underscores. Metadata, information about the data set itself SHOULD be included in the instance data set. Some metadata items are defined in the YANG module "ietf-yang-instance-data", but other items MAY be used. Metadata MUST include: - o Version of the YANG Instance Data format + * Version of the YANG Instance Data format Metadata SHOULD include: - o Name of the data set + * Name of the data set - o Content schema specification (i.e., the "content-schema" node) + * Content schema specification (i.e., the "content-schema" node) - o Description of the instance data set. The description SHOULD - contain information whether and how the data can change during the - lifetime of the server. + * Description of the instance data set. The description SHOULD + contain information whether and how the data can change during + the lifetime of the server. 2.1. Specifying the Content Schema To properly understand and use an instance data set, the user needs to know the content-schema. One of the following methods SHOULD be used: Inline method: Include the needed information as part of the instance data set. @@ -313,72 +300,76 @@ External Method: Do not include the "content-schema" node; the user needs to obtain the information through external documents. Additional methods e.g., a YANG-package based solution may be added later. Note, the specified content-schema only indicates the set of modules that were used to define this YANG instance data set. Sometimes instance data may be used for a server supporting a different YANG - module set. (e.g., for "UC2 Preloading Data" the instance data set - may not be updated every time the YANG modules on the server are - updated) Whether an instance data set originally defined using a - specific content-schema is usable with a different other schema - depends on many factors including the amount of differences and the - compatibility between the original and the other schema, considering - modules, revisions, features, deviations, the scope of the instance - data, etc. + module set (e.g., for the "Preloading default configuration data" + use-case, UC2 in Section 1, the instance data set may not be updated + every time the YANG modules on the server are updated). Whether an + instance data set originally defined using a specific content-schema + is usable with a different other schema depends on many factors + including the amount of differences and the compatibility between the + original and the other schema, considering modules, revisions, + features, deviations, the scope of the instance data, etc. 2.1.1. Inline Method One or more inline-module elements define YANG module(s) used to specify the content defining YANG modules. E.g., ietf-yang-library@2016-06-21 The anydata inline-schema carries instance data (conforming to the inline-modules) that actually specifies the content defining YANG modules including revision, supported features, deviations and any - relevant additional data (e.g., revision labels which can be used as - alternative to the revision - date[I-D.verdt-netmod-yang-module-versioning]). See Section 2.2. + relevant additional data (e.g., revision labels, described by + [I-D.ietf-netmod-yang-module-versioning]) as alternative to the + revision date). An example of the "inline" method is provided in + Figure 2. 2.1.2. Simplified-Inline Method The instance data set contains a list of content defining YANG modules including the revision date for each. Usage of this method implies that the modules are used without any deviations and with all - features supported. + features supported. An example of the "simplified-inline" method is + provided in Figure 3. 2.1.3. URI Method The "same-schema-as-file" leaf SHALL contain a URI that references another YANG instance data file. The current instance data file will use the same content schema as the referenced file. The referenced instance data file MAY have no content-data if it is used solely for specifying the content-schema. If a referenced instance data file is unavailable, content-schema is unknown. The URI method is advantageous when the user wants to avoid the overhead of specifying the content-schema in each instance data file: E.g., In UC6, when the system creates a diagnostic file every minute to document the state of the server. + An example of the "URI" method is provided in Figure 4. + 2.2. Examples -2.2.1. UC1, Documenting Server Capabilities +2.2.1. Documentation of server capabilities - The example illustrates UC1 Section 1. It provides a list of + The example reflects UC1 in Section 1. It provides a list of supported YANG modules and NETCONF capabilities for a server. It uses the "inline" method to specify the content-schema. The example uses artwork folding[I-D.ietf-netmod-artwork-folding]. ========== NOTE: '\' line wrapping per BCP XXX (RFC XXXX) =========== @@ -457,25 +447,25 @@ xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring"> \ urn:ietf:params:netconf:capability:validate:1.1\ - Figure 1: Documenting server capabilities + Figure 2 -2.2.2. UC2, Preloading Default Configuration +2.2.2. Preloading default configuration data - The example illustrates UC2 Section 1. It provides a default rule + The example reflects UC2 in Section 1. It provides a default rule set for a read-only operator role. It uses the "simplified-inline" method for specifying the content-schema. read-only-acm-rules ietf-netconf-acm@2018-02-14 @@ -496,25 +486,25 @@ read-all * read permit - Figure 2: Preloading access control data + Figure 3 -2.2.3. UC5, Storing diagnostics data +2.2.3. Storing diagnostics data - The example illustrates UC5 Section 1. An instance data set is + The example reflects UC5 in Section 1. An instance data set is produced by the server every 15 minutes that contains statistics about the NETCONF server. As a new set is produced periodically many times a day a revision-date would be useless; instead a timestamp is included. { "ietf-yang-instance-data:instance-data-set": { "name": "acme-router-netconf-diagnostics", "content-schema": { "same-schema-as-file": "file:///acme-diagnostics-schema.json" @@ -531,21 +521,21 @@ "in-rpcs ": "8711", "in-bad-rpcs ": "408", "out-rpc-errors ": "408", "out-notifications": "39007" } } } } } - Figure 3: Storing diagnostics data + Figure 4 3. YANG Instance Data Model 3.1. Tree Diagram The following tree diagram [RFC8340] provides an overview of the data model. module: ietf-yang-instance-data structure instance-data-set: @@ -567,21 +557,21 @@ +-- revision* [date] | +-- date string | +-- description? string +-- timestamp? yang:date-and-time +-- content-data? 3.2. YANG Model This YANG module imports typedefs from [RFC6991], identities from [RFC8342] and the "structure" extension from - [I-D.ietf-netmod-yang-data-ext]. + [I-D.ietf-netmod-yang-data-ext]. It also references [RFC8525]. file "ietf-yang-instance-data@2020-04-02.yang" module ietf-yang-instance-data { yang-version 1.1; namespace "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data"; prefix yid; import ietf-yang-structure-ext { prefix sx; reference @@ -638,39 +628,41 @@ revision 2020-04-02 { description "Initial revision."; reference "RFC XXXX: YANG Instance Data Format"; } feature inline-content-schema { description "This feature indicates that inline content-schema - option is supported."; + option is supported. Support for this feature might + be documented only via out-of-band documentation."; } typedef module-with-revision-date { type string { pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*' + '(@\d{4}-(1[0-2]|0[1-9])-(0[1-9]|[1|2][0-9]|3[0-1]))?'; pattern '.|..|[^xX].*|.[^mM].*|..[^lL].*'; } description "A type definining a module name and an optional revision date, e.g. ietf-yang-library@2016-06-21"; } sx:structure "instance-data-set" { description - "A data structure to define a format for - YANG instance data sets. Consists of meta-data about - the instance data set and the real content-data."; + "A data structure to define a format for YANG instance + data. The majority of the YANG nodes provide meta-data + about the instance data; the instance data itself is + is contained only in the 'content-data' node."; leaf name { type string; description "An arbitrary name for the YANG instance data set. This value is primarily used for descriptive purposes. However, when the instance data set is saved to a file, then the filename MUST encode the name's value, per Section 3 of RFC XXXX."; } leaf format-version { @@ -683,23 +675,23 @@ used to encode this 'instance-data-set'."; } container content-schema { description "The content schema used to create the instance data set. If not present the user needs to obtain the information through external documents."; choice content-schema-spec { description "Specification of the content-schema."; - case simplified-inline { leaf-list module { + min-elements 1; type module-with-revision-date; description "The list of content defining YANG modules. The value SHALL start with the module name. If the module contains a revision statement the revision date SHALL be included in the leaf-list entry. If other methods (e.g., revision-label) are defined to identify individual module revisions those MAY be used instead of using a revision date. @@ -742,21 +734,21 @@ different module-sets for different datastores. In this case the instance data set MUST contain the 'datastore' leaf and instance data for the ietf-yang-library MUST also contain information specifying the module-set for the relevant datastore. Subsequent items MAY specify YANG modules augmenting the first module with useful data (e.g., revision label)."; reference - "RFC 8525"; + "RFC 8525: YANG Library"; } anydata inline-schema { mandatory true; description "Instance data corresponding to the YANG modules specified in the inline-module nodes defining the set of content defining YANG modules for this instance-data-set."; } } @@ -793,21 +785,21 @@ type ds:datastore-ref; description "The identity of the datastore with which the instance data set is associated, e.g., the datastore from where the data was read or the datastore into which the data may be loaded or the datastore which is being documented. If a single specific datastore cannot be specified, the leaf MUST be absent. If this leaf is absent, then the datastore to which the - instance data belongs is undefined."; + instance data belongs is unspecified."; } list revision { key "date"; description "Instance data sets that are produced as a result of some sort of specification or design effort SHOULD have at least one revision entry. For every published editorial change, a new one SHOULD be added in front of the revisions sequence so that all revisions are in reverse chronological order. @@ -848,24 +840,24 @@ implementation specific manner."; } } } 4. Security Considerations The YANG module defined in this document only defines a wrapper structure specifying a format and a metadata header for YANG instance - data defined by the content-schema, so it does not follow the - security considerations template for YANG models. The instance data - is designed to be accessed as a stored file or over any file access - method or protocol. + data defined by the content-schema. Because of this the the security + considerations template for YANG models in section 3.7.1 in [RFC8407] + is not followed. The instance data is designed to be accessed as a + stored file or over any file access method or protocol. The document does not specify any method to influence the behavior of a server. Instance data files may contain sensitive data. The header part is not security sensitive. The security sensitivity of the instance data in the content part is completely dependent on the content schema. Depending on the nature @@ -980,56 +972,61 @@ Watsen, K., Auerswald, E., Farrel, A., and Q. WU, "Handling Long Lines in Inclusions in Internet-Drafts and RFCs", draft-ietf-netmod-artwork-folding-12 (work in progress), January 2020. [I-D.ietf-netmod-factory-default] WU, Q., Lengyel, B., and Y. Niu, "A YANG Data Model for Factory Default Settings", draft-ietf-netmod-factory- default-14 (work in progress), February 2020. - [I-D.verdt-netmod-yang-module-versioning] + [I-D.ietf-netmod-yang-module-versioning] Claise, B., Clarke, J., Rahman, R., Wilton, R., Lengyel, B., Sterne, J., and K. D'Souza, "Updated YANG Module - Revision Handling", draft-verdt-netmod-yang-module- - versioning-01 (work in progress), October 2019. + Revision Handling", draft-ietf-netmod-yang-module- + versioning-00 (work in progress), March 2020. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, DOI 10.17487/RFC3688, January 2004, . [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, DOI 10.17487/RFC6020, October 2010, . [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, . + [RFC8407] Bierman, A., "Guidelines for Authors and Reviewers of + Documents Containing YANG Data Models", BCP 216, RFC 8407, + DOI 10.17487/RFC8407, October 2018, + . + [RFC8632] Vallin, S. and M. Bjorklund, "A YANG Data Model for Alarm Management", RFC 8632, DOI 10.17487/RFC8632, September 2019, . [RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641, September 2019, . Appendix A. Changes between revisions Note to RFC Editor (To be removed by RFC Editor) - - v09 - v10 + v09 - v12 o Editorial updates v08 - v09 + o Removed reference to similar to get reply o Introduced artwork folding in the examples v07 - v08 o Moved compatibility into appendix o Renamed yid-version to format-version. Changed format to date of the YANG module @@ -1118,22 +1115,23 @@ o Updated examples o Moved detailed use case descriptions to appendix Appendix B. Backwards Compatibility The concept of backwards compatibility and what changes are backwards compatible are not defined for instance data sets as it is highly dependent on the specific use case and the content-schema. - For instance data that is the result of a design or specification - activity, some changes that may be good to avoid are listed below. + For "instance data sets" that are the result of design or + specification activity, some changes that may be good to avoid are + listed below. YANG uses the concept of managed entities identified by key values; if the connection between the represented entity and the key value is not preserved during an update, this may lead to the following problems. o If the key value of a list entry that represents the same managed entity as before is changed, the user may mistakenly identify the list entry as new.