Internet Engineering Task Force (IETF) E. Voit
Request for Comments: 8640 Cisco Systems
Category: Standards Track A. Clemm
ISSN: 2070-1721 Futurewei
A. Gonzalez Prieto
Microsoft
E. Nilsen-Nygaard
A. Tripathy
Cisco Systems
September 2019
Internet Engineering Task Force (IETF) E. Voit
Request for Comments: 8640 Cisco Systems
Category: Standards Track A. Clemm
ISSN: 2070-1721 Futurewei
A. Gonzalez Prieto
Microsoft
E. Nilsen-Nygaard
A. Tripathy
Cisco Systems
September 2019
Dynamic Subscription to YANG Events and Datastores over NETCONF
通过NETCONF动态订阅事件和数据存储
Abstract
摘要
This document provides a Network Configuration Protocol (NETCONF) binding to the dynamic subscription capability of both subscribed notifications and YANG-Push.
本文档提供了一个网络配置协议（NETCONF），该协议绑定到订阅通知和推送的动态订阅功能。
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/rfc8640.
有关本文件当前状态、任何勘误表以及如何提供反馈的信息，请访问https://www.rfc-editor.org/info/rfc8640.
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许可证中所述的无担保。
This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English.
本文件可能包含2008年11月10日之前发布或公开的IETF文件或IETF贡献中的材料。控制某些材料版权的人员可能未授予IETF信托允许在IETF标准流程之外修改此类材料的权利。在未从控制此类材料版权的人员处获得充分许可的情况下，不得在IETF标准流程之外修改本文件，也不得在IETF标准流程之外创建其衍生作品，除了将其格式化以RFC形式发布或将其翻译成英语以外的其他语言。
Table of Contents
目录
1. Introduction ....................................................3
2. Terminology .....................................................3
3. Compatibility with <create-subscription> as Defined in
RFC 5277 ........................................................4
4. Mandatory XML, Event Stream, and Datastore Support ..............4
5. NETCONF Connectivity and Dynamic Subscriptions ..................4
6. Notification Messages ...........................................5
7. Dynamic Subscriptions and RPC Error Responses ...................5
8. Security Considerations .........................................7
9. IANA Considerations .............................................7
10. References .....................................................7
10.1. Normative References ......................................7
10.2. Informative References ....................................8
Appendix A. Examples ...............................................9
A.1. Event Stream Discovery ......................................9
A.2. Dynamic Subscriptions ......................................10
A.3. Subscription State Notifications ...........................15
A.4. Filter Examples ............................................17
Acknowledgments ...................................................19
Authors' Addresses ................................................19
1. Introduction ....................................................3
2. Terminology .....................................................3
3. Compatibility with <create-subscription> as Defined in
RFC 5277 ........................................................4
4. Mandatory XML, Event Stream, and Datastore Support ..............4
5. NETCONF Connectivity and Dynamic Subscriptions ..................4
6. Notification Messages ...........................................5
7. Dynamic Subscriptions and RPC Error Responses ...................5
8. Security Considerations .........................................7
9. IANA Considerations .............................................7
10. References .....................................................7
10.1. Normative References ......................................7
10.2. Informative References ....................................8
Appendix A. Examples ...............................................9
A.1. Event Stream Discovery ......................................9
A.2. Dynamic Subscriptions ......................................10
A.3. Subscription State Notifications ...........................15
A.4. Filter Examples ............................................17
Acknowledgments ...................................................19
Authors' Addresses ................................................19
This document specifies the binding of a stream of events that form part of a dynamic subscription to the Network Configuration Protocol (NETCONF) [RFC6241]. Dynamic subscriptions are defined in [RFC8639]. In addition, as [RFC8641] is itself built upon [RFC8639], this document enables a NETCONF client to request via a dynamic subscription, and receive, updates from a YANG datastore located on a NETCONF server.
本文档指定了构成网络配置协议（NETCONF）[RFC6241]动态订阅一部分的事件流的绑定。[RFC8639]中定义了动态订阅。此外，由于[RFC8641]本身是建立在[RFC8639]之上的，因此本文档使NETCONF客户端能够通过动态订阅请求并接收来自NETCONF服务器上的数据存储的更新。
This document assumes that the reader is familiar with the terminology and concepts defined in [RFC8639].
本文件假设读者熟悉[RFC8639]中定义的术语和概念。
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]所述进行解释。
The following terms are defined in [RFC8639]: dynamic subscription, event stream, notification message, publisher, receiver, subscriber, and subscription. This document does not define any additional terms.
[RFC8639]中定义了以下术语：动态订阅、事件流、通知消息、发布者、接收者、订阅者和订阅。本文件未定义任何其他术语。
A publisher is allowed to concurrently support dynamic subscription RPCs as defined in [RFC8639] at the same time as the <create-subscription> RPC defined in [RFC5277]. However, a single NETCONF transport session MUST NOT support both this specification and a subscription established by the <create-subscription> RPC defined in [RFC5277]. To protect against any attempts to use a single NETCONF transport session in this way:
允许发布服务器同时支持[RFC8639]中定义的动态订阅RPC和[RFC5277]中定义的<create subscription>RPC。但是，单个NETCONF传输会话不能同时支持此规范和[RFC5277]中定义的<create subscription>RPC建立的订阅。要防止以这种方式使用单个NETCONF传输会话的任何尝试，请执行以下操作：
o A solution MUST reply with the <rpc-error> element [RFC6241] containing the "error-tag" value of "operation-not-supported" if a <create-subscription> RPC is received on a NETCONF session where an established subscription per [RFC8639] exists.
o 如果在NETCONF会话上收到<create subscription>rpc，并且存在根据[RFC8639]建立的订阅，则解决方案必须使用包含“操作不受支持”的“错误标记”值的<rpc error>元素[RFC6241]进行回复。
o A solution MUST reply with the <rpc-error> element [RFC6241] containing the "error-tag" value of "operation-not-supported" if an "establish-subscription" request has been received on a NETCONF session where the <create-subscription> RPC [RFC5277] has successfully created a subscription.
o 如果在<create subscription>rpc[RFC5277]已成功创建订阅的NETCONF会话上收到“建立订阅”请求，则解决方案必须使用包含“操作不受支持”的“错误标记”值的<rpc error>元素[RFC6241]进行回复。
If a publisher supports this specification but not subscriptions via [RFC5277], the publisher MUST NOT advertise "urn:ietf:params:netconf:capability:notification:1.0".
如果发布服务器支持此规范，但不支持通过[RFC5277]进行订阅，则发布服务器不得播发“urn:ietf:params:netconf:capability:notification:1.0”。
The "encode-xml" feature of [RFC8639] MUST be supported. This indicates that XML is a valid encoding for RPCs, state change notifications, and subscribed content.
必须支持[RFC8639]的“编码xml”功能。这表明XML是RPC、状态更改通知和订阅内容的有效编码。
A NETCONF publisher supporting event stream subscription via [RFC8639] MUST support the "NETCONF" event stream identified in that document.
通过[RFC8639]支持事件流订阅的NETCONF发布服务器必须支持该文档中标识的“NETCONF”事件流。
Management of dynamic subscriptions occurs via RPCs as defined in [RFC8641] and [RFC8639]. For a dynamic subscription, if the NETCONF session involved with the "establish-subscription" terminates, the subscription MUST be terminated.
通过[RFC8641]和[RFC8639]中定义的RPC管理动态订阅。对于动态订阅，如果与“建立订阅”相关的NETCONF会话终止，则必须终止订阅。
For a dynamic subscription, any "modify-subscription", "delete-subscription", or "resync-subscription" RPCs MUST be sent using the same NETCONF session upon which the referenced subscription was established.
对于动态订阅，任何“修改订阅”、“删除订阅”或“重新同步订阅”RPC必须使用建立引用订阅的同一NETCONF会话发送。
Notification messages transported over NETCONF MUST be encoded in a <notification> message as defined in [RFC5277], Section 4. And per the <eventTime> object definition provided in [RFC5277], <eventTime> is populated with the event occurrence time.
通过NETCONF传输的通知消息必须按照[RFC5277]第4节中的定义编码在<Notification>消息中。根据[RFC5277]中提供的<eventTime>对象定义，<eventTime>填充事件发生时间。
For dynamic subscriptions, all notification messages MUST use the NETCONF transport session used by the "establish-subscription" RPC.
对于动态订阅，所有通知消息都必须使用“建立订阅”RPC使用的NETCONF传输会话。
When an RPC error occurs as defined in [RFC8639], Section 2.4.6 and [RFC8641], Appendix A, the NETCONF RPC reply MUST include an <rpc-error> element per [RFC6241] with the error information populated as follows:
当发生[RFC8639]第2.4.6节和[RFC8641]附录A中定义的RPC错误时，NETCONF RPC回复必须包括每个[RFC6241]的<RPC错误>元素，错误信息填充如下：
o An "error-type" node of "application".
o “应用程序”的“错误类型”节点。
o An "error-tag" node, where the value is a string that corresponds to an identity associated with the error. For the mechanisms specified in this document, this "error-tag" will correspond to the error identities in either (1) [RFC8639], Section 2.4.6, for general subscription errors:
o “错误标记”节点，其中的值是与错误关联的标识相对应的字符串。对于本文件中规定的机制，该“错误标签”将对应于第2.4.6节第（1）[RFC8639]节中关于一般订阅错误的错误标识：
error identity uses error-tag
---------------------- -----------------------
dscp-unavailable invalid-value
encoding-unsupported invalid-value
filter-unsupported invalid-value
insufficient-resources resource-denied
no-such-subscription invalid-value
replay-unsupported operation-not-supported
error identity uses error-tag
---------------------- -----------------------
dscp-unavailable invalid-value
encoding-unsupported invalid-value
filter-unsupported invalid-value
insufficient-resources resource-denied
no-such-subscription invalid-value
replay-unsupported operation-not-supported
or (2) [RFC8641], Appendix A.1, for subscription errors specific to YANG datastores:
或（2）[RFC8641]，附录A.1，针对特定于YANG数据存储的订阅错误：
error identity uses error-tag
--------------------------- -----------------------
cant-exclude operation-not-supported
datastore-not-subscribable invalid-value
no-such-subscription-resync invalid-value
on-change-unsupported operation-not-supported
on-change-sync-unsupported operation-not-supported
period-unsupported invalid-value
update-too-big too-big
sync-too-big too-big
unchanging-selection operation-failed
error identity uses error-tag
--------------------------- -----------------------
cant-exclude operation-not-supported
datastore-not-subscribable invalid-value
no-such-subscription-resync invalid-value
on-change-unsupported operation-not-supported
on-change-sync-unsupported operation-not-supported
period-unsupported invalid-value
update-too-big too-big
sync-too-big too-big
unchanging-selection operation-failed
o An "error-severity" of "error" (this MAY be included).
o “错误”的“错误严重性”（可能包括在内）。
o An "error-app-tag" node, where the value is a string that corresponds to an identity associated with the error, as defined in [RFC8639], Section 2.4.6 for general subscriptions and [RFC8641], Appendix A.1 for datastore subscriptions. The specific identity to use depends on the RPC for which the error occurred. Each error identity will be inserted as the "error-app-tag" following the form <modulename>:<identityname>. An example of such a valid encoding would be "ietf-subscribed-notifications:no-such-subscription". Viable errors for different RPCs are as follows:
o “错误应用程序标记”节点，其中的值是一个字符串，对应于与错误相关联的标识，如[RFC8639]第2.4.6节（适用于一般订阅）和[RFC8641]附录a.1（适用于数据存储订阅）中的定义。要使用的特定标识取决于发生错误的RPC。每个错误标识都将作为“错误应用程序标记”插入到<modulename>：<identityname>表单后面。这种有效编码的一个例子是“ietf订阅通知：无此类订阅”。不同RPC的可行错误如下所示：
RPC has base identity
---------------------- ----------------------------
establish-subscription establish-subscription-error
modify-subscription modify-subscription-error
delete-subscription delete-subscription-error
kill-subscription delete-subscription-error
resync-subscription resync-subscription-error
RPC has base identity
---------------------- ----------------------------
establish-subscription establish-subscription-error
modify-subscription modify-subscription-error
delete-subscription delete-subscription-error
kill-subscription delete-subscription-error
resync-subscription resync-subscription-error
o In the case of error responses to an "establish-subscription" or "modify-subscription" request, there is the option of including an "error-info" node. This node may contain XML-encoded data with hints for parameter settings that might lead to successful RPC requests in the future. The yang-data structures from [RFC8639] and [RFC8641] that may be returned are as follows:
o 对于“建立订阅”或“修改订阅”请求的错误响应，可以选择包括“错误信息”节点。此节点可能包含XML编码的数据，其中包含可能导致将来成功RPC请求的参数设置提示。[RFC8639]和[RFC8641]中可能返回的数据结构如下：
establish-subscription returns hints in yang-data structure
---------------------- -------------------------------------------
target: event stream establish-subscription-stream-error-info
target: datastore establish-subscription-datastore-error-info
establish-subscription returns hints in yang-data structure
---------------------- -------------------------------------------
target: event stream establish-subscription-stream-error-info
target: datastore establish-subscription-datastore-error-info
modify-subscription returns hints in yang-data structure
---------------------- ----------------------------------------
target: event stream modify-subscription-stream-error-info
target: datastore modify-subscription-datastore-error-info
modify-subscription returns hints in yang-data structure
---------------------- ----------------------------------------
target: event stream modify-subscription-stream-error-info
target: datastore modify-subscription-datastore-error-info
The yang-data included in "error-info" SHOULD NOT include the optional leaf "reason", as such a leaf would be redundant with information that is already placed in the "error-app-tag".
“错误信息”中包含的数据不应包括可选的叶“原因”，因为这样的叶将与已经放置在“错误应用程序标记”中的信息冗余。
In the case of an RPC error resulting from a "delete-subscription", "kill-subscription", or "resync-subscription" request, no "error-info" needs to be included, as the "subscription-id" is the only RPC input parameter and no hints regarding this RPC input parameter need to be provided.
在“删除订阅”、“终止订阅”或“重新同步订阅”请求导致RPC错误的情况下，不需要包含“错误信息”，因为“订阅id”是唯一的RPC输入参数，不需要提供有关此RPC输入参数的提示。
This document does not introduce additional security considerations for dynamic subscriptions beyond those discussed in [RFC8639]. But there is one consideration worthy of more refinement based on the connection-oriented nature of NETCONF. Specifically, if a buggy or compromised NETCONF subscriber sends a number of "establish-subscription" requests, then these subscriptions accumulate and may use up system resources. In such a situation, subscriptions MAY be terminated by terminating the underlying NETCONF session. The publisher MAY also suspend or terminate a subset of the active subscriptions on that NETCONF session in order to reclaim resources and preserve normal operation for the other subscriptions.
除了[RFC8639]中讨论的内容外，本文档没有为动态订阅引入其他安全注意事项。但是，基于NETCONF面向连接的特性，有一个值得进一步改进的考虑因素。具体地说，如果一个有缺陷或受损的NETCONF订户发送了大量“建立订阅”请求，那么这些订阅将累积并可能耗尽系统资源。在这种情况下，可以通过终止底层NETCONF会话来终止订阅。发布者还可以挂起或终止该NETCONF会话上活动订阅的子集，以回收资源并保留其他订阅的正常操作。
This document has no IANA actions.
本文档没有IANA操作。
[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>.
[RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, <https://www.rfc-editor.org/info/rfc5277>.
[RFC5277]Chisholm，S.和H.Trevino，“NETCONF事件通知”，RFC 5277，DOI 10.17487/RFC5277，2008年7月<https://www.rfc-editor.org/info/rfc5277>.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., and A. Bierman, Ed., "Network Configuration Protocol (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, <https://www.rfc-editor.org/info/rfc6241>.
[RFC6241]Enns，R.，Ed.，Bjorklund，M.，Ed.，Schoenwaeld，J.，Ed.，和A.Bierman，Ed.，“网络配置协议（NETCONF）”，RFC 6241，DOI 10.17487/RFC6241，2011年6月<https://www.rfc-editor.org/info/rfc6241>.
[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>.
[RFC8639] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, E., and A. Tripathy, "Subscription to YANG Notifications", RFC 8639, DOI 10.17487/RFC8639, September 2019, <https://www.rfc-editor.org/info/rfc8639>.
[RFC8639]Voit，E.，Clemm，A.，Gonzalez-Prieto，A.，Nilsen-Nygaard，E.，和A.Tripathy，“YANG通知订阅”，RFC 8639，DOI 10.17487/RFC8639，2019年9月<https://www.rfc-editor.org/info/rfc8639>.
[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>.
[RFC8641]Clemm，A.和E.Voit，“数据存储更新的YANG通知订阅”，RFC 8641，DOI 10.17487/RFC8641，2019年9月<https://www.rfc-editor.org/info/rfc8641>.
[W3C.REC-xml-20081126] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC-xml-20081126, November 2008, <https://www.w3.org/TR/2008/REC-xml-20081126>.
[W3C.REC-xml-20081126]Bray，T.，Paoli，J.，Sperberg McQueen，M.，Maler，E.，和F.Yergeau，“可扩展标记语言（xml）1.0（第五版）”，万维网联盟建议REC-xml-20081126，2008年11月<https://www.w3.org/TR/2008/REC-xml-20081126>.
[RFC8347] Liu, X., Ed., Kyparlis, A., Parikh, R., Lindem, A., and M. Zhang, "A YANG Data Model for the Virtual Router Redundancy Protocol (VRRP)", RFC 8347, DOI 10.17487/RFC8347, March 2018, <https://www.rfc-editor.org/info/rfc8347>.
[RFC8347]Liu，X.，Ed.，Kyparlis，A.，Parikh，R.，Lindem，A.，和M.Zhang，“虚拟路由器冗余协议（VRRP）的YANG数据模型”，RFC 8347，DOI 10.17487/RFC8347，2018年3月<https://www.rfc-editor.org/info/rfc8347>.
[XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", November 1999, <https://www.w3.org/TR/1999/REC-xpath-19991116>.
[XPATH]Clark，J.和S.DeRose，“XML路径语言（XPATH）1.0版”，1999年11月<https://www.w3.org/TR/1999/REC-xpath-19991116>.
This appendix is non-normative. Additionally, the subscription "id" values of 22, 23, 39, and 99 used below are just examples. In production, the actual values of "id" might not be small integers.
本附录为非规范性附录。此外，下面使用的订阅“id”值22、23、39和99只是示例。在生产中，“id”的实际值可能不是小整数。
As defined in [RFC8639], an event stream exposes a continuous set of events available for subscription. A NETCONF client can retrieve the list of available event streams from a NETCONF publisher using the <get> operation against the top-level "streams" container defined in [RFC8639], Section 3.1.
如[RFC8639]中所定义，事件流公开可供订阅的连续事件集。NETCONF客户端可以使用[RFC8639]第3.1节中定义的顶级“streams”容器中的<get>操作从NETCONF发布服务器检索可用事件流列表。
The following XML example [W3C.REC-xml-20081126] illustrates the retrieval of the list of available event streams:
以下XML示例[W3C.REC-XML-20081126]说明了可用事件流列表的检索：
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<streams
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"/>
</filter>
</get>
</rpc>
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<streams
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"/>
</filter>
</get>
</rpc>
Figure 1: <get> Request for Retrieval of Event Streams
Figure 1: <get> Request for Retrieval of Event Streams
After such a request, the NETCONF publisher returns a list of available event streams as well as additional information that might exist in the container.
在发出这样的请求后，NETCONF发布程序将返回可用事件流的列表以及容器中可能存在的其他信息。
Figure 2 shows two successful "establish-subscription" RPC requests as per [RFC8639]. The first request is given a subscription "id" of 22, and the second is given an "id" of 23.
图2显示了根据[RFC8639]的两个成功的“建立订阅”RPC请求。第一个请求的订阅“id”为22，第二个请求的订阅“id”为23。
+------------+ +-----------+
| Subscriber | | Publisher |
+------------+ +-----------+
| |
| Capability Exchange |
|<---------------------------->|
| |
| |
| establish-subscription |
|----------------------------->| (a)
| RPC Reply: OK, id = 22 |
|<-----------------------------| (b)
| |
| notification message (for 22)|
|<-----------------------------|
| |
| |
| establish-subscription |
|----------------------------->|
| notification message (for 22)|
|<-----------------------------|
| RPC Reply: OK, id = 23 |
|<-----------------------------|
| |
| |
| notification message (for 22)|
|<-----------------------------|
| notification message (for 23)|
|<-----------------------------|
| |
+------------+ +-----------+
| Subscriber | | Publisher |
+------------+ +-----------+
| |
| Capability Exchange |
|<---------------------------->|
| |
| |
| establish-subscription |
|----------------------------->| (a)
| RPC Reply: OK, id = 22 |
|<-----------------------------| (b)
| |
| notification message (for 22)|
|<-----------------------------|
| |
| |
| establish-subscription |
|----------------------------->|
| notification message (for 22)|
|<-----------------------------|
| RPC Reply: OK, id = 23 |
|<-----------------------------|
| |
| |
| notification message (for 22)|
|<-----------------------------|
| notification message (for 23)|
|<-----------------------------|
| |
Figure 2: Multiple Subscriptions over a NETCONF Session
图2:NETCONF会话上的多个订阅
To provide examples of the information being transported, example messages for interactions (a) and (b) in Figure 2 are detailed below (Figures 3 and 4):
为了提供所传输信息的示例，下面详细介绍了图2中交互（a）和（b）的示例消息（图3和图4）：
<rpc message-id="102" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<establish-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<stream-xpath-filter xmlns:ex="https://example.com/events">
/ex:foo/
</stream-xpath-filter>
<stream>NETCONF</stream>
<dscp>10</dscp>
</establish-subscription>
</rpc>
<rpc message-id="102" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<establish-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<stream-xpath-filter xmlns:ex="https://example.com/events">
/ex:foo/
</stream-xpath-filter>
<stream>NETCONF</stream>
<dscp>10</dscp>
</establish-subscription>
</rpc>
Figure 3: "establish-subscription" Request (a)
图3：“建立订阅”请求（a）
As the NETCONF publisher was able to fully satisfy the request (a), the publisher sends the subscription "id" of the accepted subscription in its reply message (b):
由于NETCONF发布服务器能够完全满足请求（a），发布服务器在其回复消息（b）中发送已接受订阅的订阅“id”：
<rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<id
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
22
</id>
</rpc-reply>
<rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<id
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
22
</id>
</rpc-reply>
Figure 4: A Successful "establish-subscription" (b)
图4：成功的“建立订阅”（b）
If the NETCONF publisher had not been able to fully satisfy the request or the subscriber has no authorization to establish the subscription, the publisher would have sent an RPC error response. For instance, if the "dscp" value of 10 asserted by the subscriber in Figure 3 proved unacceptable, the publisher may have returned:
如果NETCONF发布服务器无法完全满足请求，或者订阅服务器没有建立订阅的授权，则发布服务器将发送RPC错误响应。例如，如果订阅者在图3中断言的“dscp”值10被证明是不可接受的，则发布者可能返回了：
<rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>application</error-type>
<error-tag>invalid-value</error-tag>
<error-severity>error</error-severity>
<error-app-tag>
ietf-subscribed-notifications:dscp-unavailable
</error-app-tag>
</rpc-error>
</rpc-reply>
<rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>application</error-type>
<error-tag>invalid-value</error-tag>
<error-severity>error</error-severity>
<error-app-tag>
ietf-subscribed-notifications:dscp-unavailable
</error-app-tag>
</rpc-error>
</rpc-reply>
Figure 5: An Unsuccessful "establish-subscription"
图5：未成功的“建立订阅”
The subscriber can use this information in future attempts to establish a subscription.
订户可以在将来尝试建立订阅时使用此信息。
An existing subscription may be modified. The following exchange shows a negotiation of such a modification via several exchanges between a subscriber and a publisher. This negotiation consists of a failed RPC modification request/response followed by a successful one.
可以修改现有订阅。下面的交换显示了通过订阅者和发布者之间的多次交换来协商这种修改。此协商由失败的RPC修改请求/响应和成功的RPC修改请求/响应组成。
+------------+ +-----------+
| Subscriber | | Publisher |
+------------+ +-----------+
| |
| notification message (for 23)|
|<-----------------------------|
| |
| modify-subscription (id = 23)|
|----------------------------->| (c)
| RPC error (with hint) |
|<-----------------------------| (d)
| |
| modify-subscription (id = 23)|
|----------------------------->|
| RPC Reply: OK |
|<-----------------------------|
| |
| notification message (for 23)|
|<-----------------------------|
| |
+------------+ +-----------+
| Subscriber | | Publisher |
+------------+ +-----------+
| |
| notification message (for 23)|
|<-----------------------------|
| |
| modify-subscription (id = 23)|
|----------------------------->| (c)
| RPC error (with hint) |
|<-----------------------------| (d)
| |
| modify-subscription (id = 23)|
|----------------------------->|
| RPC Reply: OK |
|<-----------------------------|
| |
| notification message (for 23)|
|<-----------------------------|
| |
Figure 6: Interaction Model for Successful Subscription Modification
图6：成功修改订阅的交互模型
If the subscription being modified in Figure 6 is a datastore subscription as per [RFC8641], the modification request made in (c) may look like that shown in Figure 7. As can be seen, the modifications being attempted are the application of a new XPath filter as well as the setting of a new periodic time interval.
如果图6中修改的订阅是符合[RFC8641]的数据存储订阅，则在（c）中提出的修改请求可能如图7所示。可以看出，尝试的修改包括应用新的XPath过滤器以及设置新的周期性时间间隔。
<rpc message-id="303"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<modify-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"
xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push">
<id>23</id>
<yp:datastore-xpath-filter xmlns:ex="https://example.com/datastore">
/ex:foo/ex:bar
</yp:datastore-xpath-filter>
<yp:periodic>
<yp:period>500</yp:period>
</yp:periodic>
</modify-subscription>
</rpc>
<rpc message-id="303"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<modify-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"
xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push">
<id>23</id>
<yp:datastore-xpath-filter xmlns:ex="https://example.com/datastore">
/ex:foo/ex:bar
</yp:datastore-xpath-filter>
<yp:periodic>
<yp:period>500</yp:period>
</yp:periodic>
</modify-subscription>
</rpc>
Figure 7: Subscription Modification Request (c)
图7：订阅修改请求（c）
If the NETCONF publisher can satisfy both changes, the publisher sends a positive result for the RPC. If the NETCONF publisher cannot satisfy either of the proposed changes, the publisher sends an RPC error response (d). Figure 8 shows an example RPC error response for (d) that includes a hint. This hint is an alternative time period value that might have resulted in a successful modification:
如果NETCONF发布服务器可以满足这两个更改，则发布服务器将为RPC发送一个肯定的结果。如果NETCONF发布服务器无法满足任何一个建议的更改，则发布服务器将发送RPC错误响应（d）。图8显示了（d）的RPC错误响应示例，其中包含提示。此提示是可能导致成功修改的替代时间段值：
<rpc-reply message-id="303"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>application</error-type>
<error-tag>invalid-value</error-tag>
<error-severity>error</error-severity>
<error-app-tag>
ietf-yang-push:period-unsupported
</error-app-tag>
<error-info>
<modify-subscription-datastore-error-info
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
<period-hint>
3000
</period-hint>
</modify-subscription-datastore-error-info>
</error-info>
</rpc-error>
</rpc-reply>
<rpc-reply message-id="303"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>application</error-type>
<error-tag>invalid-value</error-tag>
<error-severity>error</error-severity>
<error-app-tag>
ietf-yang-push:period-unsupported
</error-app-tag>
<error-info>
<modify-subscription-datastore-error-info
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
<period-hint>
3000
</period-hint>
</modify-subscription-datastore-error-info>
</error-info>
</rpc-error>
</rpc-reply>
Figure 8: "modify-subscription" Failure with Hint (d)
图8：“修改订阅”失败，提示（d）
Figure 9 demonstrates the deletion of a subscription. This subscription may have been to either a stream or a datastore.
图9演示了订阅的删除。此订阅可能是指向流或数据存储。
<rpc message-id="103"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<delete-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<id>22</id>
</delete-subscription>
</rpc>
<rpc message-id="103"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<delete-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<id>22</id>
</delete-subscription>
</rpc>
Figure 9: "delete-subscription"
图9：“删除订阅”
If the NETCONF publisher can satisfy the request, the publisher returns a reply indicating success.
如果NETCONF发布服务器可以满足请求，则发布服务器将返回一个指示成功的回复。
If the NETCONF publisher cannot satisfy the request, the publisher sends an <rpc-error> element indicating that the modification didn't work. Figure 10 shows a valid response for an existing valid subscription "id", but that subscription "id" was created on a different NETCONF transport session:
如果NETCONF发布服务器无法满足请求，则发布服务器将发送一个<rpc error>元素，指示修改无效。图10显示了现有有效订阅“id”的有效响应，但该订阅“id”是在不同的NETCONF传输会话上创建的：
<rpc-reply message-id="103"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>application</error-type>
<error-tag>invalid-value</error-tag>
<error-severity>error</error-severity>
<error-app-tag>
ietf-subscribed-notifications:no-such-subscription
</error-app-tag>
</rpc-error>
</rpc-reply>
<rpc-reply message-id="103"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>application</error-type>
<error-tag>invalid-value</error-tag>
<error-severity>error</error-severity>
<error-app-tag>
ietf-subscribed-notifications:no-such-subscription
</error-app-tag>
</rpc-error>
</rpc-reply>
Figure 10: An Unsuccessful "delete-subscription"
图10：一个不成功的“删除订阅”
A publisher will send subscription state notifications for dynamic subscriptions according to the definitions in [RFC8639].
发布者将根据[RFC8639]中的定义发送动态订阅的订阅状态通知。
As per Section 2.7.2 of [RFC8639], a "subscription-modified" might be sent over NETCONF if the definition of a configured filter changes. A subscription state notification encoded in XML would look like:
根据[RFC8639]第2.7.2节，如果配置过滤器的定义发生变化，则可能会通过NETCONF发送“已修改订阅”。以XML编码的订阅状态通知如下所示：
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2007-09-01T10:00:00Z</eventTime>
<subscription-modified
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<id>39</id>
<stream-xpath-filter xmlns:ex="https://example.com/events">
/ex:foo
</stream-xpath-filter>
<stream>NETCONF</stream>
</subscription-modified>
</notification>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2007-09-01T10:00:00Z</eventTime>
<subscription-modified
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<id>39</id>
<stream-xpath-filter xmlns:ex="https://example.com/events">
/ex:foo
</stream-xpath-filter>
<stream>NETCONF</stream>
</subscription-modified>
</notification>
Figure 11: "subscription-modified" Subscription State Notification
图11：“订阅已修改”订阅状态通知
A "subscription-resumed" would look like:
“已恢复订阅”的外观如下所示：
<notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2007-09-01T10:00:00Z</eventTime>
<subscription-resumed
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<id>39</id>
</subscription-resumed>
</notification>
<notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2007-09-01T10:00:00Z</eventTime>
<subscription-resumed
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<id>39</id>
</subscription-resumed>
</notification>
Figure 12: "subscription-resumed" Notification
图12：“已恢复订阅”通知
The "replay-complete" is virtually identical, with "subscription-resumed" simply being replaced by "replay-complete".
“replay complete”实际上是相同的，“subscription resumed”被替换为“replay complete”。
A "subscription-terminated" would look like:
“已终止订阅”看起来像：
<notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2007-09-01T10:00:00Z</eventTime>
<subscription-terminated
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<id>39</id>
<reason>
suspension-timeout
</reason>
</subscription-terminated>
</notification>
<notification
xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2007-09-01T10:00:00Z</eventTime>
<subscription-terminated
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<id>39</id>
<reason>
suspension-timeout
</reason>
</subscription-terminated>
</notification>
Figure 13: "subscription-terminated" Subscription State Notification
图13：“订阅终止”订阅状态通知
The "subscription-suspended" is virtually identical, with "subscription-terminated" simply being replaced by "subscription-suspended".
“暂停订阅”实际上是相同的，“终止订阅”只是被“暂停订阅”取代。
This appendix provides examples that illustrate both XPath and subtree methods of filtering event record contents. The examples are based on the YANG notification "vrrp-protocol-error-event" as defined per the ietf-vrrp YANG data model in [RFC8347]. Event records based on this specification that are generated by the publisher might appear as:
本附录提供了示例，说明了筛选事件记录内容的XPath和子树方法。示例基于[RFC8347]中ietf vrrp YANG数据模型定义的YANG通知“vrrp协议错误事件”。发布服务器生成的基于此规范的事件记录可能显示为：
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2018-09-14T08:22:33.44Z</eventTime>
<vrrp-protocol-error-event
xmlns="urn:ietf:params:xml:ns:yang:ietf-vrrp">
<protocol-error-reason>checksum-error</protocol-error-reason>
</vrrp-protocol-error-event>
</notification>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
<eventTime>2018-09-14T08:22:33.44Z</eventTime>
<vrrp-protocol-error-event
xmlns="urn:ietf:params:xml:ns:yang:ietf-vrrp">
<protocol-error-reason>checksum-error</protocol-error-reason>
</vrrp-protocol-error-event>
</notification>
Figure 14: Example VRRP Notification per RFC 8347
图14：根据RFC 8347的VRRP通知示例
Suppose that a subscriber wanted to establish a subscription that only passes instances of event records where there is a "checksum-error" as part of a Virtual Router Redundancy Protocol (VRRP) protocol event. Also, assume that the publisher places such event records into the NETCONF stream. To get a continuous series of matching event records, the subscriber might request the application of an XPath filter against the NETCONF stream. An "establish-subscription" RPC to meet this objective might be:
假设订户希望建立一个订阅，该订阅只传递作为虚拟路由器冗余协议（VRRP）协议事件的一部分存在“校验和错误”的事件记录实例。另外，假设发布者将此类事件记录放入NETCONF流中。为了获得一系列连续的匹配事件记录，订阅者可能会请求对NETCONF流应用XPath过滤器。满足此目标的“建立订阅”RPC可能是：
<rpc message-id="601" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<establish-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<stream>NETCONF</stream>
<stream-xpath-filter xmlns="urn:ietf:params:xml:ns:yang:ietf-vrrp">
/vrrp-protocol-error-event[
vrrp:protocol-error-reason="vrrp:checksum-error"]
</stream-xpath-filter>
</establish-subscription>
</rpc>
<rpc message-id="601" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<establish-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<stream>NETCONF</stream>
<stream-xpath-filter xmlns="urn:ietf:params:xml:ns:yang:ietf-vrrp">
/vrrp-protocol-error-event[
vrrp:protocol-error-reason="vrrp:checksum-error"]
</stream-xpath-filter>
</establish-subscription>
</rpc>
Figure 15: Establishing a Subscription Error Reason via XPath
图15：通过XPath建立订阅错误原因
For more examples of XPath filters, see [XPATH].
有关XPath筛选器的更多示例，请参见[XPath]。
Suppose that the "establish-subscription" in Figure 15 was accepted. And suppose that a subscriber decided later on that they wanted to broaden this subscription to cover all VRRP protocol events (i.e., not just those with a "checksum-error"). The subscriber might attempt to modify the subscription in a way that replaces the XPath filter with a subtree filter that sends all VRRP protocol events to a subscriber. Such a "modify-subscription" RPC might look like:
假设接受了图15中的“建立订阅”。假设一个订阅者后来决定，他们希望扩大订阅范围，以涵盖所有VRRP协议事件（即，不只是那些有“校验和错误”的事件）。订阅者可能会尝试以将XPath筛选器替换为向订阅者发送所有VRRP协议事件的子树筛选器的方式修改订阅。此类“修改订阅”RPC可能如下所示：
<rpc message-id="602" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<modify-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<id>99</id>
<stream-subtree-filter>
<vrrp-protocol-error-event
xmlns="urn:ietf:params:xml:ns:yang:ietf-vrrp"/>
</stream-subtree-filter>
</modify-subscription>
</rpc>
<rpc message-id="602" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<modify-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<id>99</id>
<stream-subtree-filter>
<vrrp-protocol-error-event
xmlns="urn:ietf:params:xml:ns:yang:ietf-vrrp"/>
</stream-subtree-filter>
</modify-subscription>
</rpc>
Figure 16: Example "modify-subscription" RPC
图16：“修改订阅”RPC示例
For more examples of subtree filters, see [RFC6241], Section 6.4.
有关子树过滤器的更多示例，请参见[RFC6241]，第6.4节。
Acknowledgments
致谢
We wish to acknowledge the helpful contributions, comments, and suggestions that were received from Andy Bierman, Yan Gang, Sharon Chisholm, Hector Trevino, Peipei Guo, Susan Hares, Tim Jenkins, Balazs Lengyel, Martin Bjorklund, Mahesh Jethanandani, Kent Watsen, Qin Wu, and Guangying Zheng.
我们希望感谢安迪·比尔曼、阎刚、莎伦·奇肖姆、赫克托·特雷维诺、郭佩佩、苏珊·哈雷斯、蒂姆·詹金斯、巴拉兹·伦杰尔、马丁·比约克隆德、马赫什·杰塔南达尼、肯特·沃特森、秦武和郑光英所作的有益贡献、评论和建议。
Authors' Addresses
作者地址
Eric Voit Cisco Systems
Eric Voit思科系统公司
Email: evoit@cisco.com
Email: evoit@cisco.com
Alexander Clemm Futurewei
亚历山大·克莱姆未来
Email: ludwig@clemm.org
Email: ludwig@clemm.org
Alberto Gonzalez Prieto Microsoft
Alberto Gonzalez Prieto微软
Email: alberto.gonzalez@microsoft.com
Email: alberto.gonzalez@microsoft.com
Einar Nilsen-Nygaard Cisco Systems
艾纳·尼尔森·尼加德思科系统公司
Email: einarnn@cisco.com
Email: einarnn@cisco.com
Ambika Prasad Tripathy Cisco Systems
Ambika Prasad Tripathy思科系统公司
Email: ambtripa@cisco.com
Email: ambtripa@cisco.com