Internet Engineering Task Force (IETF) M. Bjorklund
Request for Comments: 8527 Tail-f Systems
Updates: 8040 J. Schoenwaelder
Category: Standards Track Jacobs University
ISSN: 2070-1721 P. Shafer
Juniper Networks
K. Watsen
Watsen Networks
R. Wilton
Cisco Systems
March 2019
Internet Engineering Task Force (IETF) M. Bjorklund
Request for Comments: 8527 Tail-f Systems
Updates: 8040 J. Schoenwaelder
Category: Standards Track Jacobs University
ISSN: 2070-1721 P. Shafer
Juniper Networks
K. Watsen
Watsen Networks
R. Wilton
Cisco Systems
March 2019
RESTCONF Extensions to Support the Network Management Datastore Architecture
支持网络管理数据存储体系结构的RESTCONF扩展
Abstract
摘要
This document extends the RESTCONF protocol defined in RFC 8040 in order to support the Network Management Datastore Architecture (NMDA) defined in RFC 8342.
本文档扩展了RFC 8040中定义的RESTCONF协议，以支持RFC 8342中定义的网络管理数据存储体系结构（NMDA）。
This document updates RFC 8040 by introducing new datastore resources, adding a new query parameter, and requiring the usage of the YANG library (described in RFC 8525) by RESTCONF servers implementing the NMDA.
本文档通过引入新的数据存储资源、添加新的查询参数以及要求实现NMDA的RESTCONF服务器使用YANG库（如RFC 8525所述）来更新RFC 8040。
Status of This Memo
关于下段备忘
This is an Internet Standards Track document.
这是一份互联网标准跟踪文件。
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.
本文件是互联网工程任务组（IETF）的产品。它代表了IETF社区的共识。它已经接受了公众审查，并已被互联网工程指导小组（IESG）批准出版。有关互联网标准的更多信息，请参见RFC 7841第2节。
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc8527.
有关本文件当前状态、任何勘误表以及如何提供反馈的信息，请访问https://www.rfc-editor.org/info/rfc8527.
Copyright Notice
版权公告
Copyright (c) 2019 IETF Trust and the persons identified as the document authors. All rights reserved.
版权（c）2019 IETF信托基金和被确定为文件作者的人员。版权所有。
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 carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
本文件受BCP 78和IETF信托有关IETF文件的法律规定的约束(https://trustee.ietf.org/license-info)自本文件出版之日起生效。请仔细阅读这些文件，因为它们描述了您对本文件的权利和限制。从本文件中提取的代码组件必须包括信托法律条款第4.e节中所述的简化BSD许可证文本，并提供简化BSD许可证中所述的无担保。
Table of Contents
目录
1. Introduction ....................................................3
1.1. Terminology ................................................3
2. Datastore and YANG Library Requirements .........................3
3. RESTCONF Extensions .............................................4
3.1. New Datastore Resources ....................................4
3.2. Protocol Operations ........................................5
3.2.1. The "with-defaults" Query Parameter on the
Operational State Datastore .........................5
3.2.2. New "with-origin" Query Parameter ...................6
4. IANA Considerations .............................................7
5. Security Considerations .........................................7
6. Normative References ............................................7
Authors' Addresses .................................................9
1. Introduction ....................................................3
1.1. Terminology ................................................3
2. Datastore and YANG Library Requirements .........................3
3. RESTCONF Extensions .............................................4
3.1. New Datastore Resources ....................................4
3.2. Protocol Operations ........................................5
3.2.1. The "with-defaults" Query Parameter on the
Operational State Datastore .........................5
3.2.2. New "with-origin" Query Parameter ...................6
4. IANA Considerations .............................................7
5. Security Considerations .........................................7
6. Normative References ............................................7
Authors' Addresses .................................................9
This document extends the RESTCONF protocol defined in [RFC8040] in order to support the Network Management Datastore Architecture (NMDA) defined in [RFC8342].
本文档扩展了[RFC8040]中定义的RESTCONF协议，以支持[RFC8342]中定义的网络管理数据存储体系结构（NMDA）。
This document updates [RFC8040] in order to enable RESTCONF clients to discover which datastores are supported by the RESTCONF server, determine which modules are supported in each datastore, and interact with all the datastores supported by the NMDA. Specifically, the update introduces new datastore resources, adds a new query parameter, and requires the usage of the YANG library [RFC8525] by RESTCONF servers implementing the NMDA.
本文档更新了[RFC8040]，以使RESTCONF客户端能够发现RESTCONF服务器支持哪些数据存储，确定每个数据存储中支持哪些模块，并与NMDA支持的所有数据存储交互。具体来说，更新引入了新的数据存储资源，添加了新的查询参数，并要求实现NMDA的RESTCONF服务器使用YANG库[RFC8525]。
The solution presented in this document is backwards compatible with [RFC8040]. This is achieved by only adding new resources and leaving the semantics of the existing resources unchanged.
本文档中提供的解决方案与[RFC8040]向后兼容。这是通过只添加新资源并保持现有资源的语义不变来实现的。
This document uses the terminology defined by the NMDA [RFC8342].
本文件使用NMDA[RFC8342]定义的术语。
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
本文件中的关键词“必须”、“不得”、“必需”、“应”、“不应”、“建议”、“不建议”、“可”和“可选”在所有大写字母出现时（如图所示）应按照BCP 14[RFC2119][RFC8174]所述进行解释。
An NMDA-compliant RESTCONF server MUST support the operational state datastore and MUST implement at least revision 2019-01-04 of the "ietf-yang-library" module defined in [RFC8525].
符合NMDA标准的RESTCONF服务器必须支持运行状态数据存储，并且必须至少实现[RFC8525]中定义的“ietf yang library”模块2019-01-04版。
Such a server identifies that it supports the NMDA both by implementing the {+restconf}/ds/ietf-datastores:operational resource and by implementing at least revision 2019-01-04 of the "ietf-yang-library" module.
这种服务器通过实施{+restconf}/ds/ietf datastores:operation resource和实施至少2019-01-04版的“ietf-yang-library”模块来确定其支持NMDA。
A RESTCONF client can test if a server supports the NMDA by using either the HEAD or GET methods on {+restconf}/ds/ietf-datastores:operational.
RESTCONF客户端可以使用{+RESTCONF}/ds/ietf datastores:operational上的HEAD或GET方法测试服务器是否支持NMDA。
A RESTCONF client can discover which datastores and YANG modules the server supports by reading the YANG library information from the operational state datastore.
RESTCONF客户端可以通过从操作状态数据存储中读取YANG库信息来发现服务器支持哪些数据存储和YANG模块。
This section describes the RESTCONF extensions needed to support the NMDA.
本节介绍支持NMDA所需的RESTCONF扩展。
This document defines a set of new resources representing datastores as defined in [RFC8342]. These resources are available using the following resource path template:
本文档定义了一组表示[RFC8342]中定义的数据存储的新资源。使用以下资源路径模板可以使用这些资源：
{+restconf}/ds/<datastore>
{+restconf}/ds/<datastore>
The <datastore> path component is encoded as an "identityref" according to the JSON encoding rules for identities, defined in Section 6.8 of [RFC7951]. The namespace-qualified form MUST be used. Such an identity MUST be derived from the "datastore" identity defined in the "ietf-datastores" YANG module [RFC8342].
根据[RFC7951]第6.8节中定义的标识JSON编码规则，<datastore>path组件被编码为“identityref”。必须使用命名空间限定形式。此类标识必须源自“ietf数据存储”模块[RFC8342]中定义的“数据存储”标识。
Specifically:
明确地：
o The resource {+restconf}/ds/ietf-datastores:operational refers to the operational state datastore.
o 资源{+restconf}/ds/ietf datastores:operational指的是操作状态数据存储。
o The resource {+restconf}/ds/ietf-datastores:running refers to the running configuration datastore.
o 资源{+restconf}/ds/ietf datastores:running指的是正在运行的配置数据存储。
o The resource {+restconf}/ds/ietf-datastores:intended refers to the intended configuration datastore.
o 资源{+restconf}/ds/ietf datastores:designed指的是预期的配置数据存储。
An NMDA-compliant server MUST implement {+restconf}/ds/ietf-datastores:operational. Other datastore resources MAY be implemented.
符合NMDA的服务器必须实现{+restconf}/ds/ietf数据存储：可操作。可以实现其他数据存储资源。
YANG actions can only be invoked in {+restconf}/ds/ietf-datastores:operational.
YANG操作只能在{+restconf}/ds/ietf数据存储中调用：操作。
As an example, if a server implements a datastore called "ds-ephemeral", defined in a module called "example-ds-ephemeral", then the server would implement the resource {+restconf}/ds/example-ds-ephemeral:ds-ephemeral.
例如，如果服务器实现名为“ds ephemeral”的数据存储（在名为“example ds ephemeral”的模块中定义），那么服务器将实现资源{+restconf}/ds/example ds ephemeral:ds ephemeral。
The protocol operations available for the new datastore resources (see Section 3.1) are the same as the protocol operations defined in [RFC8040] for the {+restconf}/data resource with the following exceptions:
新数据存储资源可用的协议操作（见第3.1节）与[RFC8040]中为{+restconf}/数据资源定义的协议操作相同，但以下例外：
o Dynamic configuration datastores are excluded, as each dynamic configuration datastore definition needs to be reviewed for what protocol operations it supports.
o 动态配置数据存储被排除在外，因为每个动态配置数据存储定义都需要检查其支持的协议操作。
o Some datastores are read-only by nature (e.g., <intended>); hence, any attempt to modify these datastores will fail. A server MUST return a response with a "405 Method Not Allowed" status-line and an error-tag value of "operation-not-supported".
o 某些数据存储本质上是只读的（例如，<designed>）；因此，任何修改这些数据存储的尝试都将失败。服务器必须返回具有“405方法不允许”状态行和错误标记值“操作不受支持”的响应。
o The semantics of the "with-defaults" query parameter (Section 4.8.9 of [RFC8040]) differ when interacting with the operational state datastore. The semantics are described in Section 3.2.1.
o 与操作状态数据存储交互时，“with defaults”查询参数（RFC8040的第4.8.9节）的语义不同。语义如第3.2.1节所述。
o [RFC8040], Section 3.5.4, paragraph 3 does not apply when interacting with any resource under {+restconf}/ds.
o [RFC8040]，第3.5.4节第3段在与{+restconf}/ds下的任何资源交互时不适用。
3.2.1. The "with-defaults" Query Parameter on the Operational State Datastore
3.2.1. 操作状态数据存储上的“带默认值”查询参数
Support for the "with-defaults" query parameter (Section 4.8.9 of [RFC8040]) is OPTIONAL when interacting with {+restconf}/ds/ietf-datastores:operational. The associated capability to indicate a server's support is identified with the URI:
当与{+restconf}/ds/ietf数据存储交互时，对“with defaults”查询参数（RFC8040的第4.8.9节）的支持是可选的：可操作的。指示服务器支持的相关功能由URI标识：
urn:ietf:params:restconf:capability:with-operational-defaults:1.0
urn:ietf:params:restconf:capability:with-operational-defaults:1.0
For servers that support it, the behavior of the "with-defaults" query parameter on the operational state datastore is defined as follows:
对于支持它的服务器，操作状态数据存储上“with defaults”查询参数的行为定义如下：
o If no "with-defaults" query parameter is specified, or if it is set to "explicit", "report-all", or "report-all-tagged", then the "in use" values, as defined in Section 5.3 of [RFC8342], are returned from the operational state datastore, even if a node happens to have a default statement in the YANG module and this default value is being used by the server. If the "with-defaults" parameter is set to "report-all-tagged", any values that match the schema default are tagged with additional metadata, as described in Section 4.8.9 of [RFC8040].
o 如果未指定“带默认值”查询参数，或者如果将其设置为“显式”、“全部报告”或“标记全部报告”，则从运行状态数据存储中返回[RFC8342]第5.3节中定义的“使用中”值，即使节点在模块中碰巧有一个默认语句，并且服务器正在使用该默认值。如果“with defaults”参数设置为“report all taged”，则任何与模式默认值匹配的值都将使用附加元数据进行标记，如[RFC8040]第4.8.9节所述。
o If the "with-defaults" query parameter is set to "trim", all "in use" values are returned, except that the output is filtered to exclude any values that match the default defined in the YANG schema.
o 如果“with defaults”查询参数设置为“trim”，则返回所有“in use”值，但过滤输出以排除与模式中定义的默认值匹配的任何值。
Servers are not required to support all values in the "with-defaults" query parameter on the operational state datastore. If a request is made using a value that is not supported, then the error handling behavior is as described in Section 4.8.9 of [RFC8040].
服务器不需要支持操作状态数据存储上“with defaults”查询参数中的所有值。如果使用不受支持的值发出请求，则错误处理行为如[RFC8040]第4.8.9节所述。
A new query parameter named "with-origin" is added to the GET operation. If present, it requests that the server includes "origin" metadata annotations in its response, as detailed in the NMDA. This parameter is only valid when querying {+restconf}/ds/ietf-datastores:operational or any datastores with identities derived from the "operational" identity. Otherwise, if an invalid datastore is specified, then the server MUST return a response with a "400 Bad Request" status-line, using an error-tag value of "invalid-value". "origin" metadata annotations are not included unless a client explicitly requests them.
将名为“with origin”的新查询参数添加到GET操作中。如果存在，它会请求服务器在其响应中包含“源”元数据注释，如NMDA中所述。此参数仅在查询{+restconf}/ds/ietf datastores:operational或具有从“operational”标识派生的标识的任何数据存储时有效。否则，如果指定了无效的数据存储，则服务器必须返回一个带有“400错误请求”状态行的响应，并使用错误标记值“invalid value”。除非客户端明确请求，否则不包括“源”元数据注释。
Data in the operational state datatstore can come from multiple sources. The server should return the "origin" metadata annotation value that most accurately indicates the source of the operational value, as specified in Section 5.3.4 of [RFC8342].
运行状态datatstore中的数据可以来自多个源。按照[RFC8342]第5.3.4节的规定，服务器应返回最准确地指示操作值来源的“源”元数据注释值。
When encoding the "origin" metadata annotation for a hierarchy of returned nodes, the annotation can be omitted for a child node when the value matches that of the parent node, as described in the "ietf-origin" YANG module [RFC8342].
当为返回节点的层次结构编码“源”元数据注释时，如“ietf源”模块[RFC8342]中所述，当值与父节点的值匹配时，可以省略子节点的注释。
Support for the "with-origin" query parameter is OPTIONAL. It is identified with the URI:
支持“with origin”查询参数是可选的。它由URI标识：
urn:ietf:params:restconf:capability:with-origin:1.0
urn:ietf:params:restconf:capability:with-origin:1.0
This document defines two capability identifier URNs in the "RESTCONF Capability URNs" registry defined in [RFC8040]:
本文档在[RFC8040]中定义的“RESTCONF capability URNs”注册表中定义了两个功能标识符urn：
Index
Capability Identifier
---------------------
Index
Capability Identifier
---------------------
:with-origin
urn:ietf:params:restconf:capability:with-origin:1.0
:with-origin
urn:ietf:params:restconf:capability:with-origin:1.0
:with-operational-defaults
urn:ietf:params:restconf:capability:with-operational-defaults:1.0
:with-operational-defaults
urn:ietf:params:restconf:capability:with-operational-defaults:1.0
This document extends the RESTCONF protocol by introducing new datastore resources. The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport is TLS [RFC8446]. The RESTCONF protocol uses the network configuration access control model [RFC8341], which provides the means to restrict access for particular RESTCONF users to a preconfigured subset of all available RESTCONF protocol operations and content.
本文档通过引入新的数据存储资源来扩展RESTCONF协议。最低的RESTCONF层是HTTPS，实现安全传输的强制层是TLS[RFC8446]。RESTCONF协议使用网络配置访问控制模型[RFC8341]，该模型提供了将特定RESTCONF用户的访问限制为所有可用RESTCONF协议操作和内容的预配置子集的方法。
The security constraints for the base RESTCONF protocol (see Section 12 of [RFC8040]) apply to the new RESTCONF datastore resources defined in this document.
基本RESTCONF协议的安全约束（参见[RFC8040]第12节）适用于本文档中定义的新RESTCONF数据存储资源。
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.
[RFC2119]Bradner，S.，“RFC中用于表示需求水平的关键词”，BCP 14，RFC 2119，DOI 10.17487/RFC2119，1997年3月<https://www.rfc-editor.org/info/rfc2119>.
[RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", RFC 7951, DOI 10.17487/RFC7951, August 2016, <https://www.rfc-editor.org/info/rfc7951>.
[RFC7951]Lhotka，L.，“用YANG建模的数据的JSON编码”，RFC 7951，DOI 10.17487/RFC7951，2016年8月<https://www.rfc-editor.org/info/rfc7951>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, <https://www.rfc-editor.org/info/rfc8040>.
[RFC8040]Bierman，A.，Bjorklund，M.，和K.Watsen，“RESTCONF协议”，RFC 8040，DOI 10.17487/RFC8040，2017年1月<https://www.rfc-editor.org/info/rfc8040>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8174]Leiba，B.，“RFC 2119关键词中大写与小写的歧义”，BCP 14，RFC 8174，DOI 10.17487/RFC8174，2017年5月<https://www.rfc-editor.org/info/rfc8174>.
[RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration Access Control Model", STD 91, RFC 8341, DOI 10.17487/RFC8341, March 2018, <https://www.rfc-editor.org/info/rfc8341>.
[RFC8341]Bierman，A.和M.Bjorklund，“网络配置访问控制模型”，STD 91，RFC 8341，DOI 10.17487/RFC8341，2018年3月<https://www.rfc-editor.org/info/rfc8341>.
[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., and R. Wilton, "Network Management Datastore Architecture (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, <https://www.rfc-editor.org/info/rfc8342>.
[RFC8342]Bjorklund，M.，Schoenwaeld，J.，Shafer，P.，Watsen，K.，和R.Wilton，“网络管理数据存储体系结构（NMDA）”，RFC 8342，DOI 10.17487/RFC8342，2018年3月<https://www.rfc-editor.org/info/rfc8342>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, <https://www.rfc-editor.org/info/rfc8446>.
[RFC8446]Rescorla，E.“传输层安全（TLS）协议版本1.3”，RFC 8446，DOI 10.17487/RFC8446，2018年8月<https://www.rfc-editor.org/info/rfc8446>.
[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>.
[RFC8525]Bierman，A.，Bjorklund，M.，Schoenwaeld，J.，Watsen，K.，和R.Wilton，“杨图书馆”，RFC 8525，DOI 10.17487/RFC85252019年3月<https://www.rfc-editor.org/info/rfc8525>.
Authors' Addresses
作者地址
Martin Bjorklund Tail-f Systems
Martin Bjorklund Tail-f系统
Email: mbj@tail-f.com
Email: mbj@tail-f.com
Juergen Schoenwaelder Jacobs University
尤尔根·舍恩瓦埃尔德·雅各布斯大学
Email: j.schoenwaelder@jacobs-university.de
Email: j.schoenwaelder@jacobs-university.de
Phil Shafer Juniper Networks
Phil Shafer Juniper网络公司
Email: phil@juniper.net
Email: phil@juniper.net
Kent Watsen Watsen Networks
肯特沃特森网络公司
Email: kent+ietf@watsen.net
Email: kent+ietf@watsen.net
Robert Wilton Cisco Systems
罗伯特·威尔顿思科系统公司
Email: rwilton@cisco.com
Email: rwilton@cisco.com