draft-ietf-netmod-yang-instance-file-format-04.txt   draft-ietf-netmod-yang-instance-file-format-05.txt 
Netmod B. Lengyel Netmod B. Lengyel
Internet-Draft Ericsson Internet-Draft Ericsson
Intended status: Standards Track B. Claise Intended status: Standards Track B. Claise
Expires: February 13, 2020 Cisco Systems, Inc. Expires: May 20, 2020 Cisco Systems, Inc.
August 12, 2019 November 17, 2019
YANG Instance Data File Format YANG Instance Data File Format
draft-ietf-netmod-yang-instance-file-format-04 draft-ietf-netmod-yang-instance-file-format-05
Abstract Abstract
There is a need to document data defined in YANG models when a live There is a need to document data defined in YANG models when a live
server is not available. Data is often needed already at design or server is not available. Data is often needed already at design or
implementation time or needed by groups that do not have a live implementation time or needed by groups that do not have a live
running server available. This document specifies a standard file running server available. This document specifies a standard file
format for YANG instance data (which follows the syntax and semantic format for YANG instance data (which follows the syntax and semantic
from existing YANG models, re-using the same format as the reply to a from existing YANG models, re-using the same format as the reply to a
<get> operation/request) and decorates it with metadata. <get> operation/request) and annotates it with metadata.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on February 13, 2020. This Internet-Draft will expire on May 20, 2020.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 17 skipping to change at page 2, line 17
Table of Contents Table of Contents
1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Principles . . . . . . . . . . . . . . . . . . . . . . . 4 2.1. Principles . . . . . . . . . . . . . . . . . . . . . . . 4
3. Instance Data File Format . . . . . . . . . . . . . . . . . . 4 3. Instance Data File Format . . . . . . . . . . . . . . . . . . 4
3.1. Specifying the Content Schema . . . . . . . . . . . . . . 6 3.1. Specifying the Content Schema . . . . . . . . . . . . . . 6
3.1.1. Inline Method . . . . . . . . . . . . . . . . . . . . 7 3.1.1. Inline Method . . . . . . . . . . . . . . . . . . . . 7
3.1.2. Simplified-Inline Method . . . . . . . . . . . . . . 7 3.1.2. Simplified-Inline Method . . . . . . . . . . . . . . 7
3.1.3. URI Method . . . . . . . . . . . . . . . . . . . . . 7 3.1.3. URI Method . . . . . . . . . . . . . . . . . . . . . 8
3.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8 3.2. Examples . . . . . . . . . . . . . . . . . . . . . . . . 8
4. Data Life cycle . . . . . . . . . . . . . . . . . . . . . . . 12 4. Data Life cycle . . . . . . . . . . . . . . . . . . . . . . . 12
5. Delivery of Instance Data . . . . . . . . . . . . . . . . . . 13 5. Delivery of Instance Data . . . . . . . . . . . . . . . . . . 13
6. Backwards Compatibility . . . . . . . . . . . . . . . . . . . 13 6. Backwards Compatibility . . . . . . . . . . . . . . . . . . . 13
7. Yang Instance Data Model . . . . . . . . . . . . . . . . . . 13 7. YANG Instance Data Model . . . . . . . . . . . . . . . . . . 13
7.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 13 7.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 13
7.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 14 7.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 14
8. Security Considerations . . . . . . . . . . . . . . . . . . . 18 8. Security Considerations . . . . . . . . . . . . . . . . . . . 19
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
9.1. URI Registration . . . . . . . . . . . . . . . . . . . . 19 9.1. URI Registration . . . . . . . . . . . . . . . . . . . . 20
9.2. YANG Module Name Registration . . . . . . . . . . . . . . 19 9.2. YANG Module Name Registration . . . . . . . . . . . . . . 20
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 19 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 20
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 20
11.1. Normative References . . . . . . . . . . . . . . . . . . 19 11.1. Normative References . . . . . . . . . . . . . . . . . . 20
11.2. Informative References . . . . . . . . . . . . . . . . . 20 11.2. Informative References . . . . . . . . . . . . . . . . . 22
Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 21 Appendix A. Open Issues . . . . . . . . . . . . . . . . . . . . 22
Appendix B. Changes between revisions . . . . . . . . . . . . . 21 Appendix B. Changes between revisions . . . . . . . . . . . . . 22
Appendix C. Detailed Use Cases - Non-Normative . . . . . . . . . 22 Appendix C. Detailed Use Cases - Non-Normative . . . . . . . . . 24
C.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 22 C.1. Use Cases . . . . . . . . . . . . . . . . . . . . . . . . 24
C.1.1. Use Case 1: Early Documentation of Server C.1.1. Use Case 1: Early Documentation of Server
Capabilities . . . . . . . . . . . . . . . . . . . . 22 Capabilities . . . . . . . . . . . . . . . . . . . . 24
C.1.2. Use Case 2: Preloading Data . . . . . . . . . . . . . 24 C.1.2. Use Case 2: Preloading Data . . . . . . . . . . . . . 25
C.1.3. Use Case 3: Documenting Factory Default Settings . . 24 C.1.3. Use Case 3: Documenting Factory Default Settings . . 25
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26
1. Terminology 1. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 RFC 2119 [RFC2119] RFC 8174 [RFC8174] when, and only when, they 14 RFC 2119 [RFC2119] RFC 8174 [RFC8174] when, and only when, they
appear in all capitals, as shown here. appear in all capitals, as shown here.
Instance Data Set: A named set of data items decorated with metadata Instance Data Set: A named set of data items annotated with metadata
that can be used as instance data in a YANG data tree. that can be used as instance data in a YANG data tree.
Instance Data File: A file containing an instance data set formatted Instance Data File: A file containing an instance data set formatted
according to the rules described in this document. according to the rules described in this document.
Content-schema: A set of YANG modules with their revision,suupported Content-schema: A set of YANG modules with their revision, supported
features and deviations for which the instance data set contains features, and deviations for which the instance data set contains
instance data instance data
Content defining Yang module(s): YANG module(s) that make up the Content defining YANG module(s): YANG module(s) that make up the
content-schema content-schema
YANG Instance Data, or just instance data for short, is data that YANG Instance Data, or just instance data for short, is data that
could be stored in a datastore and whose syntax and semantics is could be stored in a datastore and whose syntax and semantics is
defined by YANG models. defined by YANG models.
The term Server is used as defined in [RFC8342] The term Server is used as defined in [RFC8342]
2. Introduction 2. Introduction
There is a need to document data defined in YANG models when a live There is a need to document data defined in YANG models when a live
server is not available. Data is often needed already at design or server is not available. Data is often needed already at design or
implementation time or needed by groups that do not have a live implementation time or needed by groups that do not have a live
running server available. To facilitate this off-line delivery of running server available. To facilitate this offline delivery of
data this document specifies a standard format for YANG instance data data, this document specifies a standard format for YANG instance
sets and YANG instance data files. data sets and YANG instance data files.
The following is a list of already implemented and potential use The following is a list of already implemented and potential use
cases. cases.
UC1 Documentation of server capabilities UC1 Documentation of server capabilities
UC2 Preloading default configuration data UC2 Preloading default configuration data
UC3 Documenting Factory Default Settings UC3 Documenting Factory Default Settings
UC4 Instance data used as backup UC4 Instance data used as backup
UC5 Storing the configuration of a device, e.g. for archive or audit UC5 Storing the configuration of a device, e.g., for archive or
purposes audit purposes
UC6 Storing diagnostics data UC6 Storing diagnostics data
UC7 Allowing YANG instance data to potentially be carried within UC7 Allowing YANG instance data to potentially be carried within
other IPC message formats other IPC message formats
UC8 Default instance data used as part of a templating solution UC8 Default instance data used as part of a templating solution
UC9 Providing data examples in RFCs or internet drafts UC9 Providing data examples in RFCs or internet drafts
In Appendix C we describe the first three use cases in detail. In Appendix C we describe the first three use cases in detail.
There are many and varied use cases where YANG instance data could be There are many and varied use cases where YANG instance data could be
used. We do not want to limit future uses of instance data sets, so used. We do not want to limit future uses of instance data sets, so
specifying how and when to use Yang instance data is out of scope for specifying how and when to use YANG instance data is out of scope for
this document. It is anticipated that other documents will define this document. It is anticipated that other documents will define
specific use cases. Use cases are listed here only to indicate the specific use cases. Use cases are listed here only to indicate the
need for this work. need for this work.
2.1. Principles 2.1. Principles
The following is a list of the basic principles of the instance data The following is a list of the basic principles of the instance data
format: format:
P1 Two standard formats are based on the XML and the JSON encoding P1 Two standard formats shall be defined based on the XML and JSON
encodings.
P2 Re-use existing formats similar to the response to a <get> P2 Instance data shall reuse existing formats similar to the
operation/request response to a <get> operation/request.
P3 Add metadata about the instance data set (Section 3, Paragraph 9) P3 Metadata about the instance data set (Section 3, Paragraph 9)
shall be defined.
P4 A YANG instance data set may contain data for many YANG modules P4 A YANG instance data set shall be allowed to contain data for
many YANG modules.
P5 Instance data may include configuration data, state data or a mix P5 Instance data shall be allowed to contain configuration data,
of the two state data, or a mix of the two.
P6 Partial data sets are allowed P6 Partial data sets shall be allowed.
P7 YANG instance data format may be used for any data for which YANG P7 The YANG instance data format shall be usable for any data for
module(s) are defined and available to the reader, independent of which YANG module(s) are defined and available to the reader,
whether the module is actually implemented by a server independent of whether the module is actually implemented by a
server.
3. Instance Data File Format 3. Instance Data File Format
A YANG instance data file MUST contain a single instance data set and A YANG instance data file MUST contain a single instance data set and
no additional data. no additional data.
The format of the instance data set is defined by the ietf-yang- The format of the instance data set is defined by the ietf-yang-
instance-data YANG module. It is made up of a header part and instance-data YANG module. It is made up of a header part and
content-data. The header part carries metadata for the instance data content-data. The header part carries metadata for the instance data
set. The content-data, defined as an anydata data node, carries the set. The content-data, defined as an anydata data node, carries the
"real data" that we want to document/provide. The syntax and "real data" that we want to document/provide. The syntax and
semantics of content-data is defined by the content-schema. semantics of content-data is defined by the content-schema.
Two formats are specified based on the XML and JSON YANG encodings. Two formats are specified based on the XML and JSON YANG encodings.
Later as other YANG encodings (e.g. CBOR) are defined further Later as other YANG encodings (e.g., CBOR) are defined, further
instance data formats may be specified. instance data formats may be specified.
The content-data part SHALL follow the encoding rules defined in The content-data part SHALL follow the encoding rules defined in
[RFC7950] for XML and [RFC7951] for JSON and MUST use UTF-8 character [RFC7950] for XML and [RFC7951] for JSON and MUST use UTF-8 character
encoding. Content-data MAY include: encoding. Content-data MAY include:
metadata as defined by [RFC7952]. metadata as defined by [RFC7952].
a default attribute as defined in [RFC6243] section 6. and in a default attribute as defined in [RFC6243] section 6. and in
[RFC8040] section 4.8.9. [RFC8040] section 4.8.9.
origin metadata as specified in [RFC8526] and [RFC8527] origin metadata as specified in [RFC8526] and [RFC8527]
implementation specific metadata. Unknown metadata MUST be implementation specific metadata. Unknown metadata MUST be
ignored by users of YANG instance data, allowing it to be used ignored by users of YANG instance data, allowing it to be used
later for other purposes. later for other purposes.
in the XML format implementation specific XML attributes. Unknown in the XML format implementation specific XML attributes, unknown
attributes MUST be ignored by users of YANG instance data, attributes MUST be ignored by users of YANG instance data,
allowing them to be used later for other purposes. allowing them to be used later for other purposes.
The content-data part will be very similar to the result returned for The content-data part will be very similar to the result returned for
a NETCONF <get-data> or for a RESTCONF get operation. a NETCONF <get-data> or for a RESTCONF get operation.
The content-data part MUST conform to the content-schema. An The content-data part MUST conform to the content-schema. An
instance data set MAY contain data for any number of YANG modules; if instance data set MAY contain data for any number of YANG modules; if
needed it MAY carry the complete configuration and state data set for needed it MAY carry the complete configuration and state data set for
a server. Default values SHOULD NOT be included. a server. Default values SHOULD NOT be included.
skipping to change at page 5, line 49 skipping to change at page 6, line 4
Instance data files MAY contain partial data sets. This means Instance data files MAY contain partial data sets. This means
mandatory, min-elements, require-instance=true, must and when mandatory, min-elements, require-instance=true, must and when
constrains MAY be violated. constrains MAY be violated.
The name of the instance data file SHOULD take one of the following The name of the instance data file SHOULD take one of the following
two forms: two forms:
If revision information inside the data set is present If revision information inside the data set is present
* instance-data-set-name ['@' revision-date] '.filetype' * instance-data-set-name ['@' revision-date] '.filetype'
* E.g., acme-router-modules@2018-01-25.xml
* E.g. acme-router-modules@2018-01-25.xml If the leaf name is present in the instance data header, this MUST
If the leaf name is present in the instance data header this MUST be used. If the revision-date is present in both the filename and
be used. Revision-date MUST be set to the latest revision date in the instance data header, the revision date in the file name
inside the instance data set. MUST be set to the latest revision date inside the instance data
set.
If timestamp information inside the data set is present If timestamp information inside the data set is present
* instance-data-set-name ['@' timestamp] '.filetype' * instance-data-set-name ['@' timestamp] '.filetype'
* E.g. acme-router-modules@2018-01-25T15_06_34_3+01_00.json * 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 this MUST If the leaf name is present in the instance data header, this MUST
be used. If the leaf timestamp is present in the instance data be used. If the timestamp is present both in the filename and in
header this MUST be used; the semicolons and the decimal point if the instance data header, the timestamp in the file name MUST be
present shall be replaced by underscores. 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" SHALL be The revision date or timestamp is optional. ".filetype" SHALL be
".json" or ".xml" according to the format used. ".json" or ".xml" according to the format used.
Metadata, information about the data set itself SHOULD be included in Metadata, information about the data set itself SHOULD be included in
the instance data set. Some metadata items are defined in the YANG the instance data set. Some metadata items are defined in the YANG
module ietf-yang-instance-data, but other items MAY also be used. module ietf-yang-instance-data, but other items MAY also be used.
Metadata MUST include:
Version of the YANG Instance Data format
Metadata SHOULD include: Metadata SHOULD include:
o Name of the data set o Name of the data set
o Content schema specification o Content schema specification
o Description of the instance data set. The description SHOULD o Description of the instance data set. The description SHOULD
contain information whether and how the data can change during the contain information whether and how the data can change during the
lifetime of the server. lifetime of the server.
3.1. Specifying the Content Schema 3.1. Specifying the Content Schema
To properly understand and use an instance data set the user needs to To properly understand and use an instance data set, the user needs
know the content-schema. One of the following methods SHOULD be to know the content-schema. One of the following methods SHOULD be
used: used:
Inline method: Include the needed information as part of the Inline method: Include the needed information as part of the
instance data set. instance data set.
Simplified-Inline method: Include the needed information as part Simplified-Inline method: Include the needed information as part
of the instance data set; short specification. of the instance data set; short specification.
URI method: Include a URI that references another YANG instance URI method: Include a URI that references another YANG instance
data file. This instance data file will use the same content- data file. This instance data file will use the same content-
skipping to change at page 7, line 4 skipping to change at page 7, line 15
Inline method: Include the needed information as part of the Inline method: Include the needed information as part of the
instance data set. instance data set.
Simplified-Inline method: Include the needed information as part Simplified-Inline method: Include the needed information as part
of the instance data set; short specification. of the instance data set; short specification.
URI method: Include a URI that references another YANG instance URI method: Include a URI that references another YANG instance
data file. This instance data file will use the same content- data file. This instance data file will use the same content-
schema as the referenced YANG instance data file. (if you don't schema as the referenced YANG instance data file. (if you don't
want to repeat the info again and again) want to repeat the info again and again)
EXTERNAL Method: Do not include the content-schema as it is EXTERNAL Method: Do not include the content-schema as it is
already known, or the information is available through external already known, or the information is available through external
documents. documents.
Additional methods e.g. a YANG-package based solution may be added Additional methods e.g., a YANG-package based solution may be added
later. later.
Note, the specified content-schema only indicates the set of modules Note, the specified content-schema only indicates the set of modules
that were used to define this YANG instance data set. Sometimes that were used to define this YANG instance data set. Sometimes
instance data may be used for a server supporting a different YANG 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 module set. (e.g., for "UC2 Preloading Data" the instance data set
not be updated every time the YANG modules on the server are updated) may not be updated every time the YANG modules on the server are
Whether the instance data set is usable for a possibly different updated) Whether the instance data set is usable for a possibly
real-life YANG module set depends on many factors including the different real-life YANG module set depends on many factors including
compatibility between the specified and the real-life YANG module set the compatibility between the specified and the real-life YANG module
(considering modules, revisions, features, deviations), the scope of set, considering modules, revisions, features, deviations, the scope
the instance data, etc. of the instance data, etc.
3.1.1. Inline Method 3.1.1. Inline Method
One or more inline-target-spec elements define YANG module(s) used to One or more inline-module elements define YANG module(s) used to
specify the content defining YANG modules. specify the content defining YANG modules.
E.g. ietf-yang-library@2016-06-21.yang E.g., ietf-yang-library@2016-06-21.yang
The anydata inline-content-schema carries instance data (conforming The anydata inline-schema carries instance data (conforming to the
to the inline-target-spec modules) that actually specifies the inline-modules) that actually specifies the content defining YANG
content defining YANG modules including revision, supported features, modules including revision, supported features, deviations and any
deviations and any relevant additional data (e.g. version labels) relevant additional data (e.g., version labels)
3.1.2. Simplified-Inline Method 3.1.2. Simplified-Inline Method
The instance data set contains a list of content defining YANG The instance data set contains a list of content defining YANG
modules including the revision date for each. Usage of this method modules including the revision date for each. Usage of this method
implies that the modules are used without any deviations and with all implies that the modules are used without any deviations and with all
features supported. features supported.
3.1.3. URI Method 3.1.3. URI Method
A schema-uri leaf SHALL contain a URI that references another YANG The same-schema-as-file leaf SHALL contain a URI that references
instance data file. The current instance data file will use the same another YANG instance data file. The current instance data file will
content schema as the referenced file. use the same content schema as the referenced file.
The referenced instance data file MAY have no content-data if it is The referenced instance data file MAY have no content-data if it is
used solely for specifying the content-schema. The referenced YANG used solely for specifying the content-schema.
instance data file might use the INLINE method or might use the URI
method to reference further instance data file(s). However at the
end of this reference chain there MUST be an instance data file using
the INLINE method.
If a referenced instance data file is not available the revision If a referenced instance data file is not available, content-schema
data, supported features and deviations for the target YANG modules is unknown.
are unknown.
The URI method is advantageous when the user wants to avoid the The URI method is advantageous when the user wants to avoid the
overhead of specifying the content-schema in each instance data file: overhead of specifying the content-schema in each instance data file:
E.g. In Use Case 6, when the system creates a diagnostic file every E.g., In Use Case 6, when the system creates a diagnostic file every
minute to document the state of the server. minute to document the state of the server.
3.2. Examples 3.2. Examples
The following example is based on "UC1, Documenting Server The following example is based on "UC1, Documenting Server
Capabilities". It provides (a shortened) list of supported YANG Capabilities". It provides (a shortened) list of supported YANG
modules and Netconf capabilities for a server. It uses the inline modules and NETCONF capabilities for a server. It uses the inline
method to specify the content-schema. method to specify the content-schema.
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<instance-data-set xmlns= <instance-data-set xmlns=
"urn:ietf:params:xml:ns:yang:ietf-yang-instance-data"> "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data">
<name>acme-router-modules</name> <name>acme-router-modules</name>
<inline-spec> <yid-version>1</yid-version>
ietf-yang-library@2016-06-21.yang <content-schema>
</inline-spec> <inline-module>
<inline-content-schema> ietf-yang-library@2016-06-21.yang
<module-state xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"> </inline-module>
<module> <inline-schema>
<name>ietf-yang-library</name> <module-state
<revision>2016-06-21</revision> xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
</module> <module>
<module> <name>ietf-yang-library</name>
<name>ietf-netconf-monitoring</name> <revision>2016-06-21</revision>
<revision>2010-10-04</revision> </module>
</module> <module>
</module-state> <name>ietf-netconf-monitoring</name>
</inline-content-schema> <revision>2010-10-04</revision>
</module>
</module-state>
</inline-schema>
<content-schema>
<revision> <revision>
<date>1956-10-23</date> <date>1956-10-23</date>
<description>Initial version</description> <description>Initial version</description>
</revision> </revision>
<description>Defines the minimal set of modules that any acme-router <description>Defines the minimal set of modules that any acme-router
will contain.</description> will contain.</description>
<contact>info@acme.com</contact> <contact>info@acme.com</contact>
<content-data> <content-data>
<!-- The example lists only 4 modules, but it could list the <!-- The example lists only 4 modules, but it could list the
full set of supported modules for a server, potentially many full set of supported modules for a server, potentially many
skipping to change at page 9, line 41 skipping to change at page 9, line 50
<conformance-type>import</conformance-type> <conformance-type>import</conformance-type>
</module> </module>
<module> <module>
<name>acme-system-ext</name> <name>acme-system-ext</name>
<revision>2018-08-06</revision> <revision>2018-08-06</revision>
<namespace>urn:rdns:acme.com:oammodel:acme-system-ext <namespace>urn:rdns:acme.com:oammodel:acme-system-ext
</namespace> </namespace>
<conformance-type>implement</conformance-type> <conformance-type>implement</conformance-type>
</module> </module>
</module-state> </module-state>
<netconf-state> <netconf-state
xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
<capabilities> <capabilities>
<capability> <capability>
urn:ietf:params:netconf:capability:validate:1.1 urn:ietf:params:netconf:capability:validate:1.1
</capability> </capability>
</capabilities> </capabilities>
</netconf-state> </netconf-state>
</content-data> </content-data>
</instance-data-set> </instance-data-set>
Figure 1: XML Instance Data Set - Use case 1, Documenting server Figure 1: XML Instance Data Set - Use case 1, Documenting server
capabilities capabilities
The following example is based on "UC2, Preloading Default The following example is based on "UC2, Preloading Default
Configuration". It provides a (shortened) default rule set for a Configuration". It provides a (shortened) default rule set for a
read-only operator role. It uses the inline method for specifying read-only operator role. It uses the inline method for specifying
the content-schema. the content-schema.
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<instance-data-set xmlns= <instance-data-set xmlns=
"urn:ietf:params:xml:ns:yang:ietf-yang-instance-data"> "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data">
<name>read-only-acm-rules</name> <name>read-only-acm-rules</name>
<inline-spec>ietf-yang-library@2019-01-04.yang</inline-spec> <yid-version>1</yid-version>
<inline-content-schema> <content-schema>
<yang-library xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"> <inline-module>ietf-yang-library@2019-01-04.yang</inline-module>
<module-set> <inline-schema>
<name>all</name> <yang-library
<module> xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
<name>ietf-netconf-acm</name> <module-set>
<revision>2012-02-22</revision> <name>all</name>
</module> <module>
</module-set> <name>ietf-netconf-acm</name>
</yang-library> <revision>2012-02-22</revision>
</inline-content-schema> </module>
<revision> </module-set>
<date>1776-07-04</date> </yang-library>
<description>Initial version</description> </inline-schema>
</revision> </content-schema>
<description>Access control rules for a read-only role.</description> <revision>
<content-data> <date>1776-07-04</date>
<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"> <description>Initial version</description>
<enable-nacm>true</enable-nacm> </revision>
<read-default>deny</read-default> <description>Access control rules for a read-only role.</description>
<exec-default>deny</exec-default> <content-data>
<rule-list> <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
<name>read-only-role</name> <enable-nacm>true</enable-nacm>
<group>read-only-group</group> <read-default>deny</read-default>
<rule> <exec-default>deny</exec-default>
<name>read-all</name> <rule-list>
<module-name>*</module-name> <name>read-only-role</name>
<access-operation>read</access-operation> <group>read-only-group</group>
<action>permit</action> <rule>
</rule> <name>read-all</name>
</rule-list> <module-name>*</module-name>
</nacm> <access-operation>read</access-operation>
</content-data> <action>permit</action>
</instance-data-set> </rule>
</rule-list>
</nacm>
</content-data>
</instance-data-set>
Figure 2: XML Instance Data Set - Use case 2, Preloading access Figure 2: XML Instance Data Set - Use case 2, Preloading access
control data control data
The following example is based on UC6 Storing diagnostics data. An The following example is based on UC6 Storing diagnostics data. An
instance data set is produced by the server every 15 minutes that instance data set is produced by the server every 15 minutes that
contains statistics about NETCONF. As a new set is produced contains statistics about NETCONF. As a new set is produced
periodically many times a day a revision-date would be useless; periodically many times a day a revision-date would be useless;
instead a timestamp is included. instead a timestamp is included.
{ {
"ietf-yang-instance-data:instance-data-set": { "ietf-yang-instance-data:instance-data-set": {
"name": "acme-router-netconf-diagnostics", "name": "acme-router-netconf-diagnostics",
"schema-uri": "file:///acme-netconf-diagnostics-yanglib.json", "yid-version": "1",
"content-schema": {
"same-schema-as-file": "file:///acme-diagnostics-schema.json",
},
"timestamp": "2018-01-25T17:00:38Z", "timestamp": "2018-01-25T17:00:38Z",
"description": "description":
"Netconf statistics", "NETCONF statistics",
"content-data": { "content-data": {
"ietf-netconf-monitoring:netconf-state": { "ietf-netconf-monitoring:netconf-state": {
"statistics": { "statistics": {
"netconf-start-time ": "2018-12-05T17:45:00Z", "netconf-start-time ": "2018-12-05T17:45:00Z",
"in-bad-hellos ": "32", "in-bad-hellos ": "32",
"in-sessions ": "397", "in-sessions ": "397",
"dropped-sessions ": "87", "dropped-sessions ": "87",
"in-rpcs ": "8711", "in-rpcs ": "8711",
"in-bad-rpcs ": "408", "in-bad-rpcs ": "408",
"out-rpc-errors ": "408", "out-rpc-errors ": "408",
skipping to change at page 12, line 34 skipping to change at page 12, line 43
} }
} }
} }
} }
Figure 3: JSON Instance Data File example - UC6 Storing diagnostics Figure 3: JSON Instance Data File example - UC6 Storing diagnostics
data data
4. Data Life cycle 4. Data Life cycle
In UC2 "Preloading default configuration data" the loaded data may be In UC2 "Preloading default configuration data", the loaded data may
changed later e.g. by management operations. In UC6 "Storing be changed later e.g., by management operations. In UC6 "Storing
Diagnostics data" the diagnostics values may change on device every Diagnostics data", the diagnostics values may change on device every
second. second.
YANG instance data is a snap-shot of information at a specific point YANG instance data is a snapshot of information at a specific point
of time. If the data changes afterwards this is not represented in of time. If the data changes afterwards, this is not represented in
the instance data set anymore. The valid values can be retrieved in the instance data set anymore. The valid values can be retrieved at
run-time via NETCONF/RESTCONF or received e.g. in Yang-Push run-time via NETCONF/RESTCONF or received e.g., in YANG-Push
notifications. notifications.
Whether the instance data changes and if so, when and how, SHOULD be Whether the instance data changes and if so, when and how, SHOULD be
described either in the instance data set's description statement or described either in the instance data set's description statement or
in some other implementation specific manner. in some other implementation specific manner.
5. Delivery of Instance Data 5. Delivery of Instance Data
Instance data sets that are produced as a result of some sort of Instance data sets that are produced as a result of some sort of
specification or design effort SHOULD be available without the need specification or design effort SHOULD be available without the need
for a live server e.g. via download from the vendor's website, or in for a live server e.g., via download from the vendor's website, or in
any other way product documentation is distributed. any other way that product documentation is distributed.
Other instance data sets may be read from or produced by the YANG Other instance data sets may be read from or produced by the YANG
server itself e.g. UC6 documenting diagnostic data. server itself e.g., UC6 documenting diagnostic data.
6. Backwards Compatibility 6. Backwards Compatibility
The concept of backwards compatibility and what changes are backwards The concept of backwards compatibility and what changes are backwards
compatible are not defined for instance data sets as it is highly compatible are not defined for instance data sets as it is highly
dependent on the specific use case and the content-schema. dependent on the specific use case and the content-schema.
For instance data that is the result of a design or specification For instance data that is the result of a design or specification
activity some changes that may be good to avoid are listed. YANG activity, some changes that may be good to avoid are listed. YANG
uses the concept of managed entities identified by key values; if the uses the concept of managed entities identified by key values; if the
connection between the represented entity and the key value is not connection between the represented entity and the key value is not
preserved during an update this may lead to problems. preserved during an update, this may lead to problems.
o If the key value of a list entry that represents the same managed 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 entity as before is changed, the user may mistakenly identify the
list entry as new. list entry as new.
o If the meaning of a list entry is changed, but the key values are o If the meaning of a list entry is changed, but the key values are
not (e.g. redefining an alarm-type but not changing its alarm- not (e.g., redefining an alarm-type but not changing its alarm-
type-id) the change may not be noticed. type-id) the change may not be noticed.
o If the key value of a previously removed list entry is reused for o If the key value of a previously removed list entry is reused for
a different entity, the change may be mis-interpreted as a different entity, the change may be misinterpreted as
reintroducing the previous entity. reintroducing the previous entity.
7. Yang Instance Data Model 7. YANG Instance Data Model
7.1. Tree Diagram 7.1. Tree Diagram
The following tree diagram [RFC8340] provides an overview of the data The following tree diagram [RFC8340] provides an overview of the data
model. model.
module: ietf-yang-instance-data module: ietf-yang-instance-data
structure instance-data-set: structure instance-data-set:
+--rw name? string +--rw name? string
+--rw (content-schema-spec)? +--rw yid-version uint8
| +--:(simplified-inline) +--rw content-schema
| +--rw module* string | +--rw (content-schema-spec)?
| +--:(inline) | +--:(simplified-inline)
| | +--rw inline-spec* string | | +--rw module* string
| | +--rw inline-content-schema <anydata> | +--:(inline) {inline-content-schema}?
| +--:(uri) | | +--rw inline-module* string
| +--rw schema-uri? inet:uri | | +--rw inline-schema <anydata>
| +--:(uri)
| +--rw same-schema-as-file? inet:uri
+--rw description? string +--rw description? string
+--rw contact? string +--rw contact? string
+--rw organization? string +--rw organization? string
+--rw datastore? ds:datastore-ref +--rw datastore? ds:datastore-ref
+--rw revision* [date] +--rw revision* [date]
| +--rw date string | +--rw date string
| +--rw description? string | +--rw description? string
+--rw timestamp? yang:date-and-time +--rw timestamp? yang:date-and-time
+--rw content-data? <anydata> +--rw content-data? <anydata>
7.2. YANG Model 7.2. YANG Model
<CODE BEGINS> file "ietf-yang-instance-data@2019-07-04.yang" <CODE BEGINS> file "ietf-yang-instance-data@2019-11-17.yang"
module ietf-yang-instance-data { module ietf-yang-instance-data {
yang-version 1.1; yang-version 1.1;
namespace namespace "urn:ietf:params:xml:ns:yang:ietf-yang-instance-data";
"urn:ietf:params:xml:ns:yang:ietf-yang-instance-data"; prefix yid;
prefix yid ;
import ietf-yang-structure-ext { prefix sx; } import ietf-yang-structure-ext {
import ietf-datastores { prefix ds; } prefix sx;
import ietf-inet-types { prefix inet; } }
import ietf-yang-types { prefix yang; } import ietf-datastores {
import ietf-yang-metadata { prefix "md"; } prefix ds;
}
import ietf-inet-types {
prefix inet;
}
import ietf-yang-types {
prefix yang;
}
organization "IETF NETMOD Working Group"; organization
contact "IETF NETMOD Working Group";
contact
"WG Web: <https://datatracker.ietf.org/wg/netmodf/> "WG Web: <https://datatracker.ietf.org/wg/netmodf/>
WG List: <mailto:netmod@ietf.org> WG List: <mailto:netmod@ietf.org>
Author: Balazs Lengyel Author: Balazs Lengyel
<mailto:balazs.lengyel@ericsson.com>"; <mailto:balazs.lengyel@ericsson.com>";
description
"The module defines the structure and content of YANG
instance data sets.
description "The module defines the structure and content of YANG The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL',
instance data sets. 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED',
'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
are to be interpreted as described in BCP 14 (RFC 2119)
(RFC 8174) when, and only when, they appear in all
capitals, as shown here.
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', Copyright (c) 2019 IETF Trust and the persons identified as
'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', authors of the code. All rights reserved.
'NOT RECOMMENDED', 'MAY', and 'OPTIONAL' in this document
are to be interpreted as described in BCP 14 (RFC 2119)
(RFC 8174) when, and only when, they appear in all
capitals, as shown here.
Copyright (c) 2019 IETF Trust and the persons identified as Redistribution and use in source and binary forms, with or
authors of the code. All rights reserved. without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
Redistribution and use in source and binary forms, with or This version of this YANG module is part of RFC XXXX; see
without modification, is permitted pursuant to, and subject the RFC itself for full legal notices.";
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see revision 2019-11-17 {
the RFC itself for full legal notices."; description
"Initial revision.";
reference
"RFC XXXX: YANG Instance Data Format";
}
revision 2019-07-04 { feature inline-content-schema {
description "Initial revision."; description
reference "RFC XXXX: YANG Instance Data Format"; "This feature indicates that inline content-schema
} option is supported.";
}
sx:structure instance-data-set { sx:structure "instance-data-set" {
description "A data structure to define a format for a description
YANG instance data set.Consists of meta-data about "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."; the instance data set and the real content-data.";
leaf name {
leaf name { type string;
type string; description
description "Name of the YANG instance data set."; "Name of the YANG instance data set.";
} }
leaf yid-version {
choice content-schema-spec { type uint8;
description "Specification of the content-schema"; mandatory true;
description
case simplified-inline { "Version number of the 'YANG Instance Data format'.
leaf-list module { It MUST contain the value '1' for instance data
type string { based on this specification.";
pattern '.+@\d{4}-\d{2}-\d{2}\.yang'; }
container content-schema {
description
"The content schema used to create the instance data set";
choice content-schema-spec {
description
"Specification of the content-schema";
case simplified-inline {
leaf-list module {
type string {
pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*' +
'(@\d{4}-\d{2}-\d{2})?\.((yang)|(yin))';
} }
description "The list of content defining YANG description
modules including the revision date for each. "The list of content defining YANG modules.
Usage of this leaf-list implies the modules are If the module contains a revision statement the
used without any deviations and with all features revision date SHALL be included in the leaf-list
supported."; entry.
}
}
case inline {
leaf-list inline-spec {
type string {
pattern '.+@\d{4}-\d{2}-\d{2}\.yang';
}
min-elements 1;
ordered-by user;
description
"Indicates that content defining Yang modules
are specified inline.
Each value MUST be a YANG Module name including the
revision-date as defined for YANG file names in RFC7950.
E.g. ietf-yang-library@2016-06-21.yang
The first item is either ietf-yang-library or some other E.g., ietf-yang-library@2016-06-21.yang
YANG module that contains a list of YANG modules with
their name, revision-date, supported-features and
deviations.
As some versions of ietf-yang-library MAY contain
different module-sets for different datastores, if
multiple module-sets are included, the instance data set's
meta-data MUST contain the datastore information 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 Usage of this leaf-list implies the modules are
first module with useful data (e.g. a version label)."; used without any deviations and with all features
} supported.";
anydata inline-content-schema { }
mandatory true; }
description "Instance data corresponding to the YANG modules case inline {
specified in the inline-spec nodes defining the set if-feature inline-content-schema;
of content defining Yang YANG modules for this leaf-list inline-module {
instance-data-set."; type string {
} pattern '[a-zA-Z_][a-zA-Z0-9\-_.]*' +
} '(@\d{4}-\d{2}-\d{2})?\.((yang)|(yin))';
}
min-elements 1;
ordered-by user;
description
"Indicates that content defining YANG modules
are specified inline.
case uri { If the module contains a revision statement the
leaf schema-uri { revision date SHALL be included in the leaf-list
type inet:uri; entry.
description
"A reference to another YANG instance data file.
This instance data file will use the same set of target
YANG modules, revisions, supported features and deviations
as the referenced YANG instance data file.";
} E.g., ietf-yang-library@2016-06-21.yang
}
}
leaf-list description { The first item is either ietf-yang-library or some other
type string; YANG module that contains a list of YANG modules with
description "Description of the instance data set."; their name, revision-date, supported-features, and
} deviations.
As some versions of ietf-yang-library MAY contain
different module-sets for different datastores, if
multiple module-sets are included, the instance data
set's meta-data MUST contain the datastore information
and instance data for the ietf-yang-library MUST also
contain information specifying the module-set for the
relevant datastore.
leaf contact { Subsequent items MAY specify YANG modules augmenting the
type string; first module with useful data (e.g., a version label).";
description "Contact information for the person or }
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.";
}
}
case uri {
leaf same-schema-as-file {
type inet:uri;
description
"A reference to another YANG instance data file.
This instance data file uses the same
content schema as the referenced file.";
}
}
}
}
leaf-list description {
type string;
description
"Description of the instance data set.";
}
leaf contact {
type string;
description
"Contact information for the person or
organization to whom queries concerning this organization to whom queries concerning this
instance data set should be sent."; instance data set should be sent.";
} }
leaf organization {
leaf organization { type string;
type string; description
description "Organization responsible for the instance "Organization responsible for the instance
data set."; data set.";
} }
leaf datastore {
leaf datastore { type ds:datastore-ref;
type ds:datastore-ref; description
description "The identity of the datastore with which the "The identity of the datastore with which the
instance data set is associated e.g. the datastore from instance data set is associated, e.g., the datastore from
where the data was read or the datastore where the data where the data was read or the datastore into which the data
could be loaded or the datastore which is being documented. may be loaded or the datastore which is being documented.
If a single specific datastore can not be specified, the If a single specific datastore cannot be specified, the
leaf MUST be absent. leaf MUST be absent.
If this leaf is absent, then the datastore to which the If this leaf is absent, then the datastore to which the
instance data belongs is undefined."; instance data belongs is undefined.";
} }
list revision {
list revision { key "date";
key date; description
description "Instance data sets that are produced as "Instance data sets that are produced as
a result of some sort of specification or design effort a result of some sort of specification or design effort
SHOULD have at least one revision entry. For every SHOULD have at least one revision entry. For every
published editorial change, a new one SHOULD be added published editorial change, a new one SHOULD be added
in front of the revisions sequence so that all in front of the revisions sequence so that all
revisions are in reverse chronological order. revisions are in reverse chronological order.
For instance data sets that are read from For instance data sets that are read from
or produced by a server or otherwise or produced by a server or otherwise
subject to frequent updates or changes, revision subject to frequent updates or changes, revision
SHOULD NOT be present"; SHOULD NOT be present";
leaf date {
leaf date { type string {
type string { pattern '\d{4}-\d{2}-\d{2}';
pattern '\d{4}-\d{2}-\d{2}'; }
} description
description "Specifies the date the instance data set "Specifies the date the instance data set
was last modified. Formatted as YYYY-MM-DD"; was last modified. Formatted as YYYY-MM-DD";
} }
leaf description {
leaf description { type string;
type string; description
description "Description of this revision of the instance data set.";
"Description of this revision of the instance data set."; }
} }
} leaf timestamp {
type yang:date-and-time;
leaf timestamp { description
type yang:date-and-time; "The date and time when the instance data set
description "The date and time when the instance data set
was last modified. was last modified.
For instance data sets that are read from or produced For instance data sets that are read from or produced
by a server or otherwise subject to frequent by a server or otherwise subject to frequent
updates or changes, timestamp SHOULD be present"; updates or changes, timestamp SHOULD be present";
} }
anydata content-data {
anydata content-data { description
description "Contains the real instance data. "Contains the real instance data.
The data MUST conform to the relevant YANG Modules specified The data MUST conform to the relevant YANG Modules specified
either in the content-schema-spec or in some other either in the content-schema-spec or in some other
implementation specific manner."; implementation specific manner.";
} }
} }
} }
<CODE ENDS> <CODE ENDS>
8. Security Considerations 8. Security Considerations
Depending on the nature of the instance data, instance data files MAY The YANG module defined in this document is designed as a wrapper
need to be handled in a secure way. The same type of handling should specifying a format and a metadata header for YANG instance data
be applied, that would be needed for the result of a <get> operation defined by the content-schema. The data is designed to be accessed
returning the same data. 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
of the instance data, instance data files MAY need to be handled in a
secure way. The same kind of handling should be applied, that would
be needed for the result of a <get> operation returning the same
data.
Instance data files should be protected against modification or
unauthorized access using normal file handling mechanisms.
9. IANA Considerations 9. IANA Considerations
This document registers one URI and one YANG module. This document registers one URI and one YANG module.
9.1. URI Registration 9.1. URI Registration
This document registers one URI in the IETF XML registry [RFC3688]. This document registers one URI in the IETF XML registry [RFC3688].
Following the format in RFC 3688, the following registration is Following the format in RFC 3688, the following registration is
requested to be made: requested to be made:
skipping to change at page 20, line 48 skipping to change at page 22, line 7
<https://www.rfc-editor.org/info/rfc8526>. <https://www.rfc-editor.org/info/rfc8526>.
[RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., [RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
and R. Wilton, "RESTCONF Extensions to Support the Network and R. Wilton, "RESTCONF Extensions to Support the Network
Management Datastore Architecture", RFC 8527, Management Datastore Architecture", RFC 8527,
DOI 10.17487/RFC8527, March 2019, DOI 10.17487/RFC8527, March 2019,
<https://www.rfc-editor.org/info/rfc8527>. <https://www.rfc-editor.org/info/rfc8527>.
11.2. Informative References 11.2. Informative References
[I-D.ietf-ccamp-alarm-module] [I-D.ietf-netmod-factory-default]
Vallin, S. and M. Bjorklund, "YANG Alarm Module", draft- WU, Q., Lengyel, B., and Y. Niu, "Factory Default
ietf-ccamp-alarm-module-09 (work in progress), April 2019. Setting", draft-ietf-netmod-factory-default-05 (work in
progress), October 2019.
[I-D.ietf-netconf-rfc7895bis]
Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
and R. Wilton, "YANG Library", draft-ietf-netconf-
rfc7895bis-07 (work in progress), October 2018.
[I-D.ietf-netconf-yang-push]
Clemm, A. and E. Voit, "Subscription to YANG Datastores",
draft-ietf-netconf-yang-push-25 (work in progress), May
2019.
[I-D.wu-netconf-restconf-factory-restore]
Wu, Q., Lengyel, B., and Y. Niu, "Factory default
Setting", draft-wu-netconf-restconf-factory-restore-03
(work in progress), October 2018.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
and R. Wilton, "YANG Library", RFC 8525,
DOI 10.17487/RFC8525, March 2019,
<https://www.rfc-editor.org/info/rfc8525>.
[RFC8632] Vallin, S. and M. Bjorklund, "A YANG Data Model for Alarm
Management", RFC 8632, DOI 10.17487/RFC8632, September
2019, <https://www.rfc-editor.org/info/rfc8632>.
[RFC8641] Clemm, A. and E. Voit, "Subscription to YANG Notifications
for Datastore Updates", RFC 8641, DOI 10.17487/RFC8641,
September 2019, <https://www.rfc-editor.org/info/rfc8641>.
Appendix A. Open Issues Appendix A. Open Issues
o - o -
Appendix B. Changes between revisions Appendix B. Changes between revisions
v04 - v05
o Updated according to YANG-Doctor revied
o Updated security considerations
o Added a wrapping container for the schema, and renamed the data
nodes in the inline and uri cases.
o Allowed .yin for simplified-inline schema naming. Made date
optional if it is not available in the YANG module.
o Added a mandatory yid-version to the header metadata to allow
later updates of the module.
v03 - v04 v03 - v04
o removed entity-tag and last-modified timestamp o removed entity-tag and last-modified timestamp
o Added simplified-inline method of content-schema specification o Added simplified-inline method of content-schema specification
v02 - v03 v02 - v03
o target renamed to "content-schema" and "content defining Yang o target renamed to "content-schema" and "content defining YANG
module(s)" module(s)"
o Made name of instance data set optional o Made name of instance data set optional
o Updated according to draft-ietf-netmod-yang-data-ext-03 o Updated according to draft-ietf-netmod-yang-data-ext-03
o Clarified that entity-tag and last-modified timestamp are encoded o Clarified that entity-tag and last-modified timestamp are encoded
as metadata. While they contain useful data, the HTTP-header as metadata. While they contain useful data, the HTTP-header
based encoding from Restconf is not suitable. based encoding from Restconf is not suitable.
skipping to change at page 22, line 49 skipping to change at page 24, line 22
Appendix C. Detailed Use Cases - Non-Normative Appendix C. Detailed Use Cases - Non-Normative
C.1. Use Cases C.1. Use Cases
We present a number of use cases were YANG instance data is needed. We present a number of use cases were YANG instance data is needed.
C.1.1. Use Case 1: Early Documentation of Server Capabilities C.1.1. Use Case 1: Early Documentation of Server Capabilities
A server has a number of server-capabilities that are defined in YANG A server has a number of server-capabilities that are defined in YANG
modules and can be retrieved from the server using protocols like modules and can be retrieved from the server using protocols like
NETCONF or RESTCONF. server capabilities include NETCONF or RESTCONF. Server capabilities include:
o data defined in ietf-yang-library: YANG modules, submodules, o data defined in ietf-yang-library: YANG modules, submodules,
features, deviations, schema-mounts, datastores supported features, deviations, schema-mounts, and datastores supported
([I-D.ietf-netconf-rfc7895bis]) ([RFC8525])
o alarms supported ([I-D.ietf-ccamp-alarm-module]) o alarms supported ([RFC8632])
o data nodes, subtrees that support or do not support on-change o data nodes and subtrees that support or do not support on-change
notifications ([I-D.ietf-netconf-yang-push]) notifications ([RFC8641])
o netconf-capabilities in ietf-netconf-monitoring o netconf-capabilities in ietf-netconf-monitoring
While it is good practice to allow a client to query these While it is good practice to allow a client to query these
capabilities from the live server, that is often not possible. capabilities from the live server, that is often not possible.
Often when a network node is released an associated NMS (network Often when a network node is released, an associated NMS (network
management system) is also released with it. The NMS depends on the management system) is also released with it. The NMS depends on the
capabilities of the server. During NMS implementation information capabilities of the server. During NMS implementation, information
about server capabilities is needed. If the information is not about server capabilities is needed. If the information is not
available early in some off-line document, but only as instance data available early in some offline document, but only as instance data
from the live network node, the NMS implementation will be delayed, from the live network node, the NMS implementation will be delayed,
because it has to wait for the network node to be ready. Also because it has to wait until the network node is ready. Also
assuming that all NMS implementors will have a correctly configured assuming that all NMS implementors will have a correctly configured
network node available to retrieve data from, is a very expensive network nodes from which data can be retrieved, is a very expensive
proposition. (An NMS may handle dozens of node types.) proposition. (An NMS may handle dozens of node types.)
Network operators often build their own home-grown NMS systems that Network operators often build their own home-grown NMS systems that
needs to be integrated with a vendor's network node. The operator need to be integrated with a vendor's network node. The operator
needs to know the network node's server capabilities in order to do needs to know the network node's server capabilities in order to do
this. Moreover the network operator's decision to buy a vendor's this. Moreover, the network operator's decision to buy a vendor's
product may even be influenced by the network node's OAM feature set product may even be influenced by the network node's OAM feature set
documented as the Server's capabilities. documented as the server's capabilities.
Beside NMS implementors, system integrators and many others also need Beside NMS implementors, system integrators and many others also need
the same information early. Examples could be model driven testing, the same information early. Examples could be model driven testing,
generating documentation, etc. generating documentation, etc.
Most server-capabilities are relatively stable and change only during Most server-capabilities are relatively stable and change only during
upgrade or due to licensing or addition or removal of HW. They are upgrade or due to licensing or the addition or removal of hardware.
usually defined by a vendor at design time, before the product is They are usually defined by a vendor at design time, before the
released. It feasible and advantageous to define/document them early product is released. It is feasible and advantageous to define/
e.g. in a YANG instance data File. document them early e.g., in a YANG instance data File.
It is anticipated that a separate IETF document will define in detail It is anticipated that a separate IETF document will define in detail
how and which set of server capabilities should be documented. how and which set of server capabilities should be documented.
C.1.2. Use Case 2: Preloading Data C.1.2. Use Case 2: Preloading Data
There are parts of the configuration that must be fully configurable There are parts of the configuration that must be fully configurable
by the operator, however for which often a simple default by the operator. However, often a simple default configuration will
configuration will be sufficient. be sufficient.
One example is access control groups/roles and related rules. While One example is access control groups/roles and related rules. While
a sophisticated operator may define dozens of different groups often a sophisticated operator may define dozens of different groups, often
a basic (read-only operator, read-write system administrator, a basic (read-only operator, read-write system administrator,
security-administrator) triplet will be enough. Vendors will often security-administrator) triplet will be enough. Vendors will often
provide such default configuration data to make device configuration provide such default configuration data to make device configuration
easier for an operator. easier for an operator.
Defining Access control data is a complex task. To help the device Defining access control data is a complex task. To help, the device
vendor pre-defines a set of default groups (/nacm:nacm/groups) and vendor predefines a set of default groups (/nacm:nacm/groups) and
rules for these groups to access specific parts of common models rules for these groups to access specific parts of common models
(/nacm:nacm/rule-list/rule). (/nacm:nacm/rule-list/rule).
YANG instance data files are used to document and/or preload the YANG instance data files are used to document and/or preload the
default configuration. default configuration.
C.1.3. Use Case 3: Documenting Factory Default Settings C.1.3. Use Case 3: Documenting Factory Default Settings
Nearly every server has a factory default configuration. If the Nearly every server has a factory default configuration. If the
system is really badly misconfigured or if the current configuration system is really badly misconfigured or if the current configuration
is to be abandoned the system can be reset to this default. is to be abandoned, the system can be reset the default factory
configuration.
In Netconf the <delete-config> operation can already be used to reset In NETCONF, the <delete-config> operation can already be used to
the startup datastore. There are ongoing efforts to introduce a new, reset the startup datastore. There are ongoing efforts to introduce
more generic reset-datastore operation for the same purpose a new, more generic factory-reset operation for the same purpose
[I-D.wu-netconf-restconf-factory-restore] [I-D.ietf-netmod-factory-default]
The operator currently has no way to know what the default The operator currently has no way to know what the default
configuration actually contains. YANG instance data can be used to configuration actually contains. YANG instance data can also be used
document the factory default configuration. to document the factory default configuration.
Authors' Addresses Authors' Addresses
Balazs Lengyel Balazs Lengyel
Ericsson Ericsson
Magyar Tudosok korutja 11 Magyar Tudosok korutja 11
1117 Budapest 1117 Budapest
Hungary Hungary
Phone: +36-70-330-7909 Phone: +36-70-330-7909
 End of changes. 107 change blocks. 
377 lines changed or deleted 468 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/