rfc8650xml2.original.xml   rfc8650.xml 
<?xml version="1.0" encoding="US-ASCII"?> <?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd"> <!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent">
<?rfc toc="yes"?> <rfc xmlns:xi="http://www.w3.org/2001/XInclude"
<?rfc tocompact="yes"?> number="8650"
<?rfc tocdepth="3"?> docName="draft-ietf-netconf-restconf-notif-15"
<?rfc tocindent="yes"?> updates=""
<?rfc symrefs="yes"?> obsoletes=""
<?rfc sortrefs="yes"?> category="std"
<?rfc comments="yes"?> consensus="true"
<?rfc inline="yes"?> submissionType="IETF"
<?rfc compact="yes"?> ipr="trust200902"
<?rfc subcompact="no"?> tocInclude="true"
<rfc category="std" docName="draft-ietf-netconf-restconf-notif-15" symRefs="true"
ipr="trust200902"> sortRefs="true"
xml:lang="en"
version="3">
<front> <front>
<title abbrev="RESTCONF-Notif">Dynamic subscription to YANG Events and Datas tores over RESTCONF</title>
<title abbrev="RESTCONF Transport for Event Notifications">Dynamic Subscript
ion to YANG Events and Datastores over RESTCONF</title>
<seriesInfo name="RFC" value="8650"/>
<author fullname="Eric Voit" initials="E." surname="Voit"> <author fullname="Eric Voit" initials="E." surname="Voit">
<organization>Cisco Systems</organization> <organization>Cisco Systems</organization>
<address> <address>
<email>evoit@cisco.com</email> <email>evoit@cisco.com</email>
</address> </address>
</author> </author>
<author fullname="Reshad Rahman" initials="R." surname="Rahman">
<author fullname="Reshad Rahman" initials="R"
surname="Rahman">
<organization>Cisco Systems</organization> <organization>Cisco Systems</organization>
<address> <address>
<email>rrahman@cisco.com</email> <email>rrahman@cisco.com</email>
</address> </address>
</author> </author>
<author fullname="Einar Nilsen-Nygaard" initials="E." surname="Nilsen-Nygaar
<author fullname="Einar Nilsen-Nygaard" initials="E" d">
surname="Nilsen-Nygaard">
<organization>Cisco Systems</organization> <organization>Cisco Systems</organization>
<address> <address>
<email>einarnn@cisco.com</email> <email>einarnn@cisco.com</email>
</address> </address>
</author> </author>
<author fullname="Alexander Clemm" initials="A." surname="Clemm">
<author fullname="Alexander Clemm" initials="A" surname="Clemm"> <organization>Futurewei</organization>
<organization>Huawei</organization> <address>
<address> <email>ludwig@clemm.org</email>
<email>ludwig@clemm.org</email> </address>
</address>
</author> </author>
<author fullname="Andy Bierman" initials="A." surname="Bierman">
<author fullname="Andy Bierman" initials="A"
surname="Bierman">
<organization>YumaWorks</organization> <organization>YumaWorks</organization>
<address> <address>
<email>andy@yumaworks.com</email> <email>andy@yumaworks.com</email>
</address> </address>
</author> </author>
<date month="November" year="2019"/>
<date day="11" month="June" year="2019"/>
<area>Operations &amp; Management</area> <area>Operations &amp; Management</area>
<workgroup>NETCONF</workgroup> <workgroup>NETCONF</workgroup>
<keyword>Draft</keyword> <keyword>YANG-Push</keyword>
<abstract> <abstract>
<t>This document provides a RESTCONF binding to the dynamic subscription <t>This document provides a RESTCONF binding to the dynamic subscription
capability of both subscribed notifications and YANG-Push.</t> capability of both subscribed notifications and YANG-Push.</t>
</abstract> </abstract>
</front> </front>
<middle> <middle>
<section title="Introduction"> <section numbered="true" toc="default">
<t>Mechanisms to support event subscription and push are defined in <xref <name>Introduction</name>
target="I-D.draft-ietf-netconf-subscribed-notifications"/>. Enhancements to <xre
f target="I-D.draft-ietf-netconf-subscribed-notifications"/> which enable YANG d
atastore subscription and push are defined in <xref target="I-D.ietf-netconf-yan
g-push"/>. This document provides a transport specification for dynamic subscrip
tions over RESTCONF <xref target="RFC8040"/>. Requirements for these mechanisms
are captured in <xref target="RFC7923"/>.</t>
<t>The streaming of notifications encapsulating the resulting information
push is done via the mechanism described in section 6.3 of <xref target="RFC8040
"/>. </t>
<t>Mechanisms to support event subscription and YANG-Push are defined in <
xref target="RFC8639" format="default"/>. Enhancements to <xref target="RFC8639"
format="default"/> that enable YANG datastore subscription and YANG-Push are de
fined in <xref target="RFC8641" format="default"/>.
This document provides a transport specification for dynamic subscriptions over
RESTCONF <xref target="RFC8040" format="default"/>. Requirements for these mech
anisms are captured in <xref target="RFC7923" format="default"/>.</t>
<t>The streaming of notifications that encapsulate the resulting informati
on push is done via the mechanism described in <xref target="RFC8040" sectionFor
mat="of" section="6.3" format="default"/>. </t>
</section> </section>
<section numbered="true" toc="default">
<name>Terminology</name>
<t>
The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14>REQU
IRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL
NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>
RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
"<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are to
be interpreted as
described in BCP&nbsp;14 <xref target="RFC2119"/> <xref target="RFC8174"/>
when, and only when, they appear in all capitals, as shown here.
</t>
<section title="Terminology"> <t>The following terms use the definitions from <xref target="RFC8639" for
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", mat="default"/>: dynamic subscription, event stream, notification message, publi
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and sher, receiver, subscriber, and subscription.</t>
"OPTIONAL" in this document are to be interpreted as described in BCP <t>Other terms reused include datastore, which is defined in <xref target=
14 <xref target="RFC2119"/> <xref target="RFC8174"/> when, and only when, the "RFC8342" format="default"/>, and HTTP/2 stream, which maps to the definition of
y appear in all "stream" within <xref target="RFC7540" sectionFormat="comma" section="2" format
capitals, as shown here.</t> ="default"/>.</t>
<t>The following terms use the definitions from <xref target="I-D.draft-ie
tf-netconf-subscribed-notifications"/>: dynamic subscription, event stream, noti
fication message, publisher, receiver, subscriber, and subscription.</t>
<t>Other terms reused include datastore, which is defined in <xref target=
"RFC8342"/>, and HTTP2 stream which maps to the definition of "stream" within <x
ref target="RFC7540"/>, Section 2.</t>
<t>[ note to the RFC Editor - please replace XXXX within this document wit
h the number of this document ]</t>
</section> </section>
<section anchor="dyn-subs" numbered="true" toc="default">
<name>Dynamic Subscriptions</name>
<t>This section provides specifics on how to establish and maintain dynami
c subscriptions over RESTCONF <xref target="RFC8040" format="default"/>. Subscri
bing to event streams is accomplished in this way via RPCs defined within <xref
target="RFC8639" sectionFormat="comma" section="2.4" format="default"/>. The RPC
s are done via RESTCONF POSTs. YANG datastore subscription is accomplished via a
ugmentations to <xref target="RFC8639" format="default"/> as described within <x
ref target="RFC8641" sectionFormat="comma" section="4.4" format="default"/>.</t>
<section anchor="dyn-subs" title="Dynamic Subscriptions"> <t>As described in <xref target="RFC8040" sectionFormat="of"
section="6.3" format="default"/>, a GET needs to be performed on a
<t>This section provides specifics on how to establish and maintain dynami specific URI on the publisher. Subscribers cannot predetermine the URI
c subscriptions over RESTCONF <xref target="RFC8040"/>. Subscribing to event str against which a subscription might exist on a publisher, as the URI will
eams is accomplished in this way via RPCs defined within <xref target="I-D.draft only exist after the "establish-subscription" RPC has been
-ietf-netconf-subscribed-notifications"/> Section 2.4. The RPCs are done via RES accepted. Therefore, the POST for the "establish-subscription" RPC
TCONF POSTs. YANG datastore subscription is accomplished via augmentations to <x replaces the GET request for the "location" leaf that is used in <xref
ref target="I-D.draft-ietf-netconf-subscribed-notifications"/> as described with target="RFC8040" format="default"/> to obtain the URI. The subscription
in <xref target="I-D.ietf-netconf-yang-push"/> Section 4.4.</t> URI will be determined and sent as part of the response to the
"establish-subscription" RPC, and a subsequent GET to this URI will be
<t>As described in <xref target="RFC8040"/> Section 6.3, a GET needs to be done in order to start the flow of notification messages back to the
made against a specific URI on the publisher. Subscribers cannot pre-determine subscriber. As specified in <xref target="RFC8639" sectionFormat="of"
the URI against which a subscription might exist on a publisher, as the URI will section="2.4.1" format="default"/>, a subscription does not move to the ac
only exist after the "establish-subscription" RPC has been accepted. Therefore, tive state
the POST for the "establish-subscription" RPC replaces the GET request for the until the GET is received.</t>
"location" leaf which is used in <xref target="RFC8040"/> to obtain the URI. The <section numbered="true" toc="default">
subscription URI will be determined and sent as part of the response to the "es <name>Transport Connectivity</name>
tablish-subscription" RPC, and a subsequent GET to this URI will be done in orde <t>For a dynamic subscription, when a RESTCONF session doesn't already e
r to start the flow of notification messages back to the subscriber. A subscrip xist, a new RESTCONF session is initiated from the subscriber.</t>
tion does not move to the active state as per Section 2.4.1. of <xref target="I- <t>As stated in <xref target="RFC8040" sectionFormat="of" section="2.1"
D.draft-ietf-netconf-subscribed-notifications"/> until the GET is received. </t> format="default"/>, a subscriber <bcp14>MUST</bcp14> establish the HTTP session
over TLS <xref target="RFC8446" format="default"/> in order to secure the conten
<section title="Transport Connectivity"> t in transit.</t>
<t>For a dynamic subscription, where a RESTCONF session doesn't already
exist, a new RESTCONF session is initiated from the subscriber.</t>
<t>As stated in Section 2.1 of <xref target="RFC8040"/>, a subscriber MU
ST establish the HTTP session over TLS <xref target="RFC8446"/> in order to secu
re the content in transit.</t>
<t>Without the involvement of additional protocols, HTTP sessions by the <t>Without the involvement of additional protocols, HTTP sessions by
mselves do not allow for a quick recognition of when the communication path has themselves do not support quick recognition of the loss of the
been lost with the publisher. Where quick recognition of the loss of a publishe communication path to the publisher. Where quick recognition of the loss of a
r is required, a subscriber SHOULD use a TLS heartbeat <xref target="RFC6520"/>, publisher is required, a subscriber <bcp14>SHOULD</bcp14> use a TLS heartbeat <
just from subscriber to publisher, to track HTTP session continuity.</t> xref target="RFC6520" format="default"/>, just from subscriber to publisher, to
<t>Loss of the heartbeat MUST result in any subscription related TCP ses track HTTP session continuity.</t>
sions between those endpoints being torn down. A subscriber can then attempt to
re-establish the dynamic subscription by using the procedure described in <xref
target="SSE"/>.</t>
<t>Loss of the heartbeat <bcp14>MUST</bcp14> result in the teardown
of any subscription-related TCP sessions between those endpoints.
A subscriber can then attempt to re-establish the dynamic subscription by using
the procedure described in <xref target="SSE" format="default"/>.</t>
</section> </section>
<section numbered="true" toc="default">
<section title="Discovery"> <name>Discovery</name>
<t>Subscribers can learn which event streams a RESTCONF server supports
<t>Subscribers can learn what event streams a RESTCONF server supports b by querying the "streams" container of ietf-subscribed-notifications.yang in <xr
y querying the "streams" container of ietf-subscribed-notification.yang in <xref ef target="RFC8639" format="default"/>. Support for the "streams" container of i
target="I-D.draft-ietf-netconf-subscribed-notifications"/>. Support for the "st etf-restconf-monitoring.yang in <xref target="RFC8040" format="default"/> is not
reams" container of ietf-restconf-monitoring.yang in <xref target="RFC8040"/> is required. In the case when the RESTCONF binding specified by this document is u
not required. In the case when the RESTCONF binding specified by this document sed to convey the "streams" container from ietf-restconf-monitoring.yang (i.e.,
is used to convey the "streams" container from ietf-restconf-monitoring.yang (i. that feature is supported), any event streams contained therein are also expecte
e., that feature is supported), any event streams contained therein are also exp d to be present in the "streams" container of ietf-restconf-monitoring.yang.</t>
ected to be present in the "streams" container of ietf-restconf-monitoring.yang. <t>Subscribers can learn which datastores a RESTCONF server supports by
</t> following <xref target="RFC8527" sectionFormat="of" section="2" format="default"
<t>Subscribers can learn what datastores a RESTCONF server supports by f />. </t>
ollowing Section 2 of <xref target="I-D.draft-ietf-netconf-nmda-restconf"/>. </t
>
</section> </section>
<section numbered="true" toc="default">
<name>RESTCONF RPCs and HTTP Status Codes</name>
<t>Specific HTTP response codes as defined in <xref target="RFC7231" sec
tionFormat="of" section="6" format="default"/> will indicate the result of RESTC
ONF RPC requests with the publisher. An HTTP status code of 200 is the proper r
esponse to any successful RPC defined within <xref target="RFC8639" format="defa
ult"/> or <xref target="RFC8641" format="default"/>.</t>
<t>If a publisher fails to serve the RPC request for one of the reasons
indicated in <xref target="RFC8639" sectionFormat="of" section="2.4.6" format="d
efault"/> or <xref target="RFC8641" sectionFormat="of" section="A" format="defau
lt"/>, this will be indicated by an appropriate error code, as shown below, tran
sported in the HTTP response.</t>
<section title="RESTCONF RPCs and HTTP Status Codes"> <t>When an HTTP error code is returned, the RPC reply <bcp14>MUST</bcp14
> include
<t>Specific HTTP responses codes as defined in <xref target="RFC7231"/> an &lt;rpc-error&gt; element per <xref target="RFC8040" sectionFormat="of" secti
section 6 will indicate the result of RESTCONF RPC requests with the publisher. on="7.1" format="default"/>
An HTTP status code of 200 is the proper response to any successful RPC defined with the following parameter values:
within <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/> or <xre </t>
f target="I-D.ietf-netconf-yang-push"/>.</t> <ul spacing="normal">
<li>an "error-type" node of "application".</li>
<t>If a publisher fails to serve the RPC request for one of the reasons <li>an "error-tag" node whose value is a string that corresponds
indicated in <xref target="I-D.draft-ietf-netconf-subscribed-notifications"/> Se to an identity associated with the error. This "error-tag" will
ction 2.4.6 or <xref target="I-D.ietf-netconf-yang-push"/> Appendix A, this will come from one of two places and will correspond to the error
be indicated by an appropriate error code, as shown below, transported in the H identities either within
TTP response.</t> <xref target="RFC8639" sectionFormat="of" section="2.4.6" format="def
ault"/>
<t>When an HTTP error code is returned, the RPC reply MUST include an "r for general subscription errors (<xref target="gen-sub-errors" format
pc-error" element per <xref target="RFC8040"/> Section 7.1 with the following pa ="default"/>)
rameter values: or within <xref target="RFC8641" sectionFormat="of" section="A.1" for
<list style="symbols"> mat="default"/>
<t>an "error-type" node of "application".</t> for subscription errors specific to YANG datastores (<xref
<t>an "error-tag" node with the value being a string that corresponds to a target="datastore-specific-errors" format="default"/>).</li>
n identity associated with the error. This "error-tag" will come from one of tw <li>an "error-app-tag" node whose value is a string that corresponds t
o places. Either it will correspond to the error identities within <xref target o an
="I-D.draft-ietf-netconf-subscribed-notifications"/> section 2.4.6 for general s identity associated with the error, as defined in
ubscription errors:</t> <xref target="RFC8639" sectionFormat="of" section="2.4.6" format="def
</list></t> ault"/>
for general subscriptions or
<figure align="left"> <xref target="RFC8641" sectionFormat="of" section="A.1" format="defau
<artwork><![CDATA[ lt"/>
error identity uses error-tag HTTP Code for subscription errors specific to YANG datastores. The tag to use d
---------------------- -------------- --------- epends on the RPC for which the
dscp-unavailable invalid-value 400 error occurred. Viable errors for different RPCs are found in <xref
encoding-unsupported invalid-value 400 target="rpc-errors" format="default"/>.</li>
filter-unsupported invalid-value 400 </ul>
insufficient-resources resource-denied 409
no-such-subscription invalid-value 404
replay-unsupported operation-not-supported 501
]]></artwork>
</figure>
<t><list style="none">
<t>Or this "error-tag" will correspond to the error identities within <xr
ef target="I-D.ietf-netconf-yang-push"/> Appendix A.1 for subscription errors sp
ecific to YANG datastores:</t>
</list></t>
<figure align="left">
<artwork><![CDATA[
error identity uses error-tag HTTP Code
---------------------- -------------- ---------
cant-exclude operation-not-supported 501
datastore-not-subscribable invalid-value 400
no-such-subscription-resync invalid-value 404
on-change-unsupported operation-not-supported 501
on-change-sync-unsupported operation-not-supported 501
period-unsupported invalid-value 400
update-too-big too-big 400
sync-too-big too-big 400
unchanging-selection operation-failed 500
]]></artwork>
</figure>
<t><list style="symbols">
<t>an "error-app-tag" node with the value being a string that correspo
nds to an identity associated with the error, as defined in <xref target="I-D.dr
aft-ietf-netconf-subscribed-notifications"/> section 2.4.6 for general subscript
ions, and <xref target="I-D.ietf-netconf-yang-push"/> Appendix A.1, for datastor
e subscriptions. The tag to use depends on the RPC for which the error occurred.
Viable errors for different RPCs are as follows:</t>
</list></t>
<figure align="left">
<artwork><![CDATA[
RPC select an identity with a base
---------------------- ------------------------------
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
]]></artwork>
</figure>
<table anchor="gen-sub-errors">
<name>General Subscription Error Identities and Associated "error-tag" Us
e</name>
<thead>
<tr>
<th>Error identity</th>
<th>Uses "error-tag"</th>
<th>HTTP code</th>
</tr>
</thead>
<tbody>
<tr>
<td>dscp-unavailable</td>
<td>invalid-value</td>
<td>400</td>
</tr>
<tr>
<td>encoding-unsupported</td>
<td>invalid-value</td>
<td>400</td>
</tr>
<tr>
<td>filter-unsupported</td>
<td>invalid-value</td>
<td>400</td>
</tr>
<tr>
<td>insufficient-resources</td>
<td>resource-denied</td>
<td>409</td>
</tr>
<tr>
<td>no-such-subscription</td>
<td>invalid-value</td>
<td>404</td>
</tr>
<tr>
<td>replay-unsupported</td>
<td>operation-not-supported</td>
<td>501</td>
</tr>
</tbody>
</table>
<table anchor="datastore-specific-errors">
<name>Datastore-Specific Error Identities and Associated "error-tag" Use<
/name>
<thead>
<tr>
<th>Error identity</th>
<th>Uses "error-tag"</th>
<th>HTTP code</th>
</tr>
</thead>
<tbody>
<tr>
<td>cant-include</td>
<td>operation-not-supported</td>
<td>501</td>
</tr>
<tr>
<td>datastore-not-subscribable</td>
<td>invalid-value</td>
<td>400</td>
</tr>
<tr>
<td>no-such-subscription-resync</td>
<td>invalid-value</td>
<td>404</td>
</tr>
<tr>
<td>on-change-unsupported</td>
<td>operation-not-supported</td>
<td>501</td>
</tr>
<tr>
<td>on-change-sync-unsupported</td>
<td>operation-not-supported</td>
<td>501</td>
</tr>
<tr>
<td>period-unsupported</td>
<td>invalid-value</td>
<td>400</td>
</tr>
<tr>
<td>update-too-big</td>
<td>too-big</td>
<td>400</td>
</tr>
<tr>
<td>sync-too-big</td>
<td>too-big</td>
<td>400</td>
</tr>
<tr>
<td>unchanging-selection</td>
<td>operation-failed</td>
<td>500</td>
</tr>
</tbody>
</table>
<table anchor="rpc-errors">
<name>RPC Errors and Associated Error Identities</name>
<thead>
<tr>
<th>RPC</th>
<th>Select an identity with a base</th>
</tr>
</thead>
<tbody>
<tr>
<td>establish-subscription</td>
<td>establish-subscription-error</td>
</tr>
<tr>
<td>modify-subscription</td>
<td>modify-subscription-error</td>
</tr>
<tr>
<td>delete-subscription</td>
<td>delete-subscription-error</td>
</tr>
<tr>
<td>kill-subscription</td>
<td>delete-subscription-error</td>
</tr>
<tr>
<td>resync-subscription</td>
<td>resync-subscription-error</td>
</tr>
</tbody>
</table>
<t>Each error identity will be inserted as the "error-app-tag" using JSO N encoding following the form &lt;modulename&gt;:&lt;identityname&gt;. An examp le of such a valid encoding would be "ietf-subscribed-notifications:no-such-subs cription".</t> <t>Each error identity will be inserted as the "error-app-tag" using JSO N encoding following the form &lt;modulename&gt;:&lt;identityname&gt;. An examp le of such a valid encoding would be "ietf-subscribed-notifications:no-such-subs cription".</t>
<t>In the case of error responses to an "establish-subscription" or
"modify-subscription" request, there is the option to include an
"error-info" node. This node may contain hints for parameter settings
that might lead to successful RPC requests in the future. Tables <xref ta
rget="error-info-estab-sub" format="counter"/> and <xref target="error-info-mod-
sub" format="counter"/> show the yang-data structures that may be returned.</t>
<t>In case of error responses to an "establish-subscription" or "modify- <table anchor="error-info-estab-sub">
subscription" request there is the option of including an "error-info" node. Th <name>Optional "error-info" Node Hints for an "establish-subscription" Re
is node may contain hints for parameter settings that might lead to successful R quest</name>
PC requests in the future. Following are the yang-data structures which may be <thead>
returned:</t> <tr>
<th>Target:</th>
<figure align="left"> <th>Return hints in yang-data structure</th>
<artwork><![CDATA[ </tr>
establish-subscription returns hints in yang-data structure </thead>
---------------------- ------------------------------------ <tbody>
target: event stream establish-subscription-stream-error-info <tr>
target: datastore establish-subscription-datastore-error-info <td>event stream</td>
<td>establish-subscription-stream-error-info</td>
modify-subscription returns hints in yang-data structure </tr>
---------------------- ------------------------------------ <tr>
target: event stream modify-subscription-stream-error-info <td>datastore</td>
target: datastore modify-subscription-datastore-error-info <td>establish-subscription-datastore-error-info</td>
</tr>
The yang-data included within "error-info" SHOULD NOT include the </tbody>
</table>
<table anchor="error-info-mod-sub">
<name>Optional "error-info" Node Hints for an "modify-subscription" Requ
est</name>
<thead>
<tr>
<th>Target:</th>
<th>Returns hints in yang-data structure</th>
</tr>
</thead>
<tbody>
<tr>
<td>event stream</td>
<td>modify-subscription-stream-error-info</td>
</tr>
<tr>
<td>datastore</td>
<td>modify-subscription-datastore-error-info</td>
</tr>
</tbody>
</table>
<t>The yang-data included within "error-info" <bcp14>SHOULD NOT</bcp14> in
clude the
optional leaf "reason", as such a leaf would be redundant optional leaf "reason", as such a leaf would be redundant
with information that is already placed within the with information that is already placed within the
"error-app-tag". "error-app-tag".
</t>
In case of an rpc error as a result of a "delete-subscription", a <t>In case of an &lt;rpc-error&gt; as a result of a "delete-subscription", a
"kill-subscription", or a "resync-subscription" request, no "kill-subscription", or a "resync-subscription" request, no
"error-info" needs to be included, as the "subscription-id" is "error-info" needs to be included, as the "subscription-id" is
the only RPC input parameter and no hints regarding this RPC input the only RPC input parameter, and no hints regarding this RPC input
parameters need to be provided. parameters need to be provided.
]]></artwork> </t>
</figure> <t>Note that "error-path" <xref target="RFC8040" format="default"/> does
not need to be included with the &lt;rpc-error&gt; element, as subscription err
<t>Note that "error-path" <xref target="RFC8040"/> does not need to be i ors are generally associated with the choice of RPC input parameters. </t>
ncluded with the "rpc-error" element, as subscription errors are generally assoc
iated with the choice of RPC input parameters. </t>
</section> </section>
<section anchor="SSE" numbered="true" toc="default">
<section anchor="SSE" title="Call Flow for Server-Sent Events"> <name>Call Flow for Server-Sent Events</name>
<t>The call flow for Server-Sent Events (SSE) is defined in <xref target <t>The call flow for Server-Sent Events (SSE) is defined in <xref
="dyn-sse"/>. The logical connections denoted by (a) and (b) can be a TCP conne target="dyn-sse" format="default"/>. The logical connections denoted
ction or an HTTP2 stream (if HTTP2 is used, multiple HTTP2 streams can be carrie by (a) and (b) can be a TCP connection or an HTTP/2 stream (if HTTP/2
d in one TCP connection). Requests to <xref target="I-D.draft-ietf-netconf-subsc is used, multiple HTTP/2 streams can be carried in one TCP
ribed-notifications"/> or <xref target="I-D.ietf-netconf-yang-push"/> augmented connection). Requests to RPCs as defined in <xref target="RFC8639"
RPCs are sent on a connection indicated by (a). A successful "establish-subscri format="default"/> or <xref target="RFC8641" format="default"/> are
ption" will result in an RPC response returned with both a subscription identifi sent on a connection indicated by (a). A successful
er which uniquely identifies a subscription, as well as a URI which uniquely ide "establish-subscription" will result in an RPC response returned with
ntifies the location of subscription on the publisher (b). This URI is defined v both a subscription identifier that uniquely identifies a
ia the "uri" leaf the Data Model in <xref target="YANG-module"/>. </t> subscription, as well as a URI that uniquely identifies the location
of subscription on the publisher (b). This URI is defined via the
<t>An HTTP GET is then sent on a separate logical connection (b) to the "uri" leaf in the data model in <xref target="YANG-module"
URI on the publisher. This signals the publisher to initiate the flow of notifi format="default"/>. </t>
cation messages which are sent in SSE <xref target="W3C-20150203"/> as a respons <t>An HTTP GET is then sent on a separate logical connection (b) to the
e to the GET. There cannot be two or more simultaneous GET requests on a subscri URI on the publisher. This signals the publisher to initiate the flow of notifi
ption URI: any GET request received while there is a current GET request on the cation messages that are sent in SSE <xref target="W3C-20150203" format="default
same URI MUST be rejected with HTTP error code 409.</t> "/> as a response to the GET. There cannot be two or more simultaneous GET reque
sts on a subscription URI: any GET request received while there is a current GET
<t>As described in <xref target="RFC8040"/> Section 6.4, RESTCONF server request on the same URI <bcp14>MUST</bcp14> be rejected with HTTP error code 40
s SHOULD NOT send the "event" or "id" fields in the SSE event notifications.</t> 9.</t>
<t>As described in <xref target="RFC8040" sectionFormat="of" section="6.
<figure title="Dynamic with server-sent events" 4" format="default"/>, RESTCONF servers <bcp14>SHOULD NOT</bcp14> send the "even
anchor="dyn-sse" t" or "id" fields in the SSE event notifications.</t>
align="center"> <figure anchor="dyn-sse">
<artwork height="29" xml:space="preserve"><![CDATA[ <name>Dynamic Subscriptions with Server-Sent Events</name>
<artwork name="" type="" align="left" alt=""><![CDATA[
+--------------+ +--------------+ +--------------+ +--------------+
| Subscriber | | Publisher | | Subscriber | | Publisher |
| | | | | | | |
| Logical | | Logical | | Logical | | Logical |
| Connection | | Connection | | Connection | | Connection |
| (a) (b) | | (a) (b) | | (a) (b) | | (a) (b) |
+--------------+ +--------------+ +--------------+ +--------------+
| RESTCONF POST (RPC:establish-subscription) | | RESTCONF POST (RPC:establish-subscription) |
|--------------------------------------------->| |--------------------------------------------->|
| HTTP 200 OK (ID,URI)| | HTTP 200 OK (ID,URI)|
skipping to change at line 258 skipping to change at line 388
| | SSE (notif-message)| | | SSE (notif-message)|
| |<---------------------------------------------| | |<---------------------------------------------|
| RESTCONF POST (RPC:delete-subscription) | | | RESTCONF POST (RPC:delete-subscription) | |
|--------------------------------------------->| | |--------------------------------------------->| |
| | HTTP 200 OK| | | | HTTP 200 OK| |
|<---------------------------------------------| | |<---------------------------------------------| |
| | | | | | | |
| | | | | | | |
(a) (b) (a) (b) ]]></artwork> (a) (b) (a) (b) ]]></artwork>
</figure> </figure>
<t>Additional requirements for dynamic subscriptions over SSE include:</ t> <t>Additional requirements for dynamic subscriptions over SSE include:</ t>
<t><list style="symbols"> <ul spacing="normal">
<t>All subscription state notifications from a publisher MUST be retur
ned in a separate SSE message used by the subscription to which the state change
refers.</t>
<t>Subscription RPCs MUST NOT use the connection currently providing n
otification messages for that subscription.</t>
<t>In addition to an RPC response for a "modify-subscription" RPC trav
eling over (a), a "subscription-modified" state change notification MUST be sent
within (b). This allows the receiver to know exactly when, within the stream o
f events, the new terms of the subscription have been applied to the notificatio
n messages. See arrow (c).</t>
<t>In addition to any required access permissions (e.g., NACM), RPCs m
odify-subscription, resync-subscription and
delete-subscription SHOULD only be allowed by the same RESTCONF username <xref t
arget="RFC8040"/> which invoked establish-subscription. Such a restriction gener
ally serves to preserve users' privacy, but exceptions might be made for adminis
trators that may need to modify or delete other users' subscriptions.</t>
<t>The kill-subscription RPC can be invoked by any RESTCONF username w
ith the required administrative permissions.</t>
</list></t>
<t>A publisher MUST terminate a subscription in the following cases:</t>
<t><list style="symbols">
<t>Receipt of a "delete-subscription" or a "kill-subscription" RPC for
that subscription.</t>
<t>Loss of TLS heartbeat</t>
</list></t>
<t>A publisher MAY terminate a subscription at any time as stated in <xr
ef target="I-D.draft-ietf-netconf-subscribed-notifications"/> Section 1.3 </t>
</section>
</section>
<section title="QoS Treatment">
<t>Qos treatment for event streams is described in <xref target="I-D.draft
-ietf-netconf-subscribed-notifications"/> Section 2.3. In addition, if HTTP2 is
used, the publisher MUST:</t>
<t><list style="symbols"> <li>
<t>take the "weighting" leaf node in <xref target="I-D.draft-ietf-netcon A publisher <bcp14>MUST</bcp14> return all subscription state notifications
f-subscribed-notifications"/>, and copy it into the HTTP2 stream weight, <xref t in a separate SSE message used by the subscription to
arget="RFC7540"/> section 5.3, and </t> which the state change refers.
</li>
<t>take any existing subscription "dependency", as specified by the "dep <li>Subscription RPCs <bcp14>MUST NOT</bcp14> use the connection curre
endency" leaf node in <xref target="I-D.draft-ietf-netconf-subscribed-notificati ntly providing notification messages for that subscription.</li>
ons"/>, and use the HTTP2 stream for the parent subscription as the HTTP2 strea <li>In addition to an RPC response for a "modify-subscription" RPC tra
m dependency, <xref target="RFC7540"/> section 5.3.1, of the dependent subscript veling over (a), a "subscription-modified" state change notification <bcp14>MUST
ion.</t> </bcp14> be sent within (b). This allows the receiver to know exactly when, wit
<t>set the exclusive flag, <xref target="RFC7540"/> section 5.3.1, to 0. hin the stream of events, the new terms of the subscription have been applied to
</t> the notification messages. See arrow (c).</li>
</list></t> <li>In addition to any required access permissions (e.g., Network Conf
<t>For dynamic subscriptions with the same DSCP value to a specific publis iguration Access Control Model (NACM)), the RPCs "modify-subscription", "resync-
her, it is recommended that the subscriber sends all URI GET requests on a commo subscription", and
n HTTP2 session (if HTTP2 is used). Conversely, a subscriber can not use a commo "delete-subscription" <bcp14>SHOULD</bcp14> only be allowed by the same RESTCONF
n HTTP2 session for subscriptions with different DSCP values.</t> username <xref target="RFC8040" format="default"/> that invoked "establish-subs
cription". Such a restriction generally serves to preserve users' privacy, but e
xceptions might be made for administrators that may need to modify or delete oth
er users' subscriptions.</li>
<li>The "kill-subscription" RPC can be invoked by any RESTCONF usernam
e with the required administrative permissions.</li>
</ul>
<t>A publisher <bcp14>MUST</bcp14> terminate a subscription in the follo
wing cases:</t>
<ul spacing="normal">
<li>Receipt of a "delete-subscription" or a "kill-subscription" RPC fo
r that subscription</li>
<li>Loss of TLS heartbeat</li>
</ul>
<t>A publisher <bcp14>MAY</bcp14> terminate a subscription at any time a
s stated in <xref target="RFC8639" sectionFormat="of" section="1.3" format="defa
ult"/>.</t>
</section>
</section> </section>
<section numbered="true" toc="default">
<section title="Notification Messages"> <name>QoS Treatment</name>
<t>Notification messages transported over RESTCONF will be encoded accordi <t>Qos treatment for event streams is described in <xref target="RFC8639"
ng to <xref target="RFC8040"/>, section 6.4.</t> sectionFormat="of" section="2.3" format="default"/>. In addition, if HTTP/2 is u
sed, the publisher <bcp14>MUST</bcp14>:</t>
<ul spacing="normal">
<li>Take the "weighting" leaf node in <xref target="RFC8639"
format="default"/> and copy it into the HTTP/2 stream weight, <xref targe
t="RFC7540" sectionFormat="of" section="5.3" format="default"/>, and </li>
<li>Take any existing subscription "dependency", as specified by the
"dependency" leaf node in <xref target="RFC8639" format="default"/>,
and use the HTTP/2 stream for the parent subscription as the HTTP/2
stream dependency (as described in <xref target="RFC7540" sectionFormat="
of"
section="5.3.1" format="default"/>) of the dependent
subscription.</li>
<li>Set the exclusive flag (<xref target="RFC7540" sectionFormat="of" se
ction="5.3.1" format="default"/>) to 0.</li>
</ul>
<t>For dynamic subscriptions with the same Differentiated Services Code Po
int (DSCP) value to a specific publisher, it is recommended that the subscriber
sends all URI GET requests on a common HTTP/2 session (if HTTP/2 is used). Conve
rsely, a subscriber cannot use a common HTTP/2 session for subscriptions with di
fferent DSCP values.</t>
</section>
<section numbered="true" toc="default">
<name>Notification Messages</name>
<t>Notification messages transported over RESTCONF will be encoded accordi
ng to <xref target="RFC8040" sectionFormat="comma" section="6.4" format="default
"/>.</t>
</section> </section>
<section anchor="YANG-tree" numbered="true" toc="default">
<name>YANG Tree</name>
<section title="YANG Tree" anchor="YANG-tree" > <t> The YANG module defined in <xref target="YANG-module"
format="default"/> has one leaf that augments three nodes of <xref target=
"RFC8639" format="default"/>.</t>
<t> The YANG model defined in <xref target="YANG-module"/> has one leaf au <sourcecode name="" type="yangtree"><![CDATA[
gmented into three places of <xref target="I-D.draft-ietf-netconf-subscribed-not
ifications"/>.</t>
<figure>
<artwork><![CDATA[
module: ietf-restconf-subscribed-notifications module: ietf-restconf-subscribed-notifications
augment /sn:establish-subscription/sn:output: augment /sn:establish-subscription/sn:output:
+--ro uri? inet:uri +--ro uri? inet:uri
augment /sn:subscriptions/sn:subscription: augment /sn:subscriptions/sn:subscription:
+--ro uri? inet:uri +--ro uri? inet:uri
augment /sn:subscription-modified: augment /sn:subscription-modified:
+--ro uri? inet:uri +--ro uri? inet:uri ]]></sourcecode>
]]></artwork>
</figure>
</section> </section>
<section anchor="YANG-module" numbered="true" toc="default">
<name>YANG Module</name>
<t>This module references <xref target="RFC8639" format="default"/>.</t>
<section title="YANG module" anchor="YANG-module" > <sourcecode name="ietf-restconf-subscribed-notifications@2019-10-15.yang"
type="yang" markers="true"><![CDATA[
<t>This module references <xref target="I-D.draft-ietf-netconf-subscribed-
notifications"/>.</t>
<figure>
<artwork name="ietf-restconf-subscribed-notifications@2019-01-11.yang">
<![CDATA[
<CODE BEGINS> file
"ietf-restconf-subscribed-notifications@2019-01-11.yang"
module ietf-restconf-subscribed-notifications { module ietf-restconf-subscribed-notifications {
yang-version 1.1; yang-version 1.1;
namespace namespace "urn:ietf:params:xml:ns:yang:"
"urn:ietf:params:xml:ns:yang:" + + "ietf-restconf-subscribed-notifications";
"ietf-restconf-subscribed-notifications";
prefix rsn; prefix rsn;
import ietf-subscribed-notifications { import ietf-subscribed-notifications {
prefix sn; prefix sn;
} }
import ietf-inet-types { import ietf-inet-types {
prefix inet; prefix inet;
} }
organization "IETF NETCONF (Network Configuration) Working Group"; organization
"IETF NETCONF (Network Configuration) Working Group";
contact contact
"WG Web: <http:/tools.ietf.org/wg/netconf/> "WG Web: <https://datatracker.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org> WG List: <mailto:netconf@ietf.org>
Editor: Eric Voit Editor: Eric Voit
<mailto:evoit@cisco.com> <mailto:evoit@cisco.com>
Editor: Alexander Clemm Editor: Alexander Clemm
<mailto:ludwig@clemm.org> <mailto:ludwig@clemm.org>
Editor: Reshad Rahman Editor: Reshad Rahman
<mailto:rrahman@cisco.com>"; <mailto:rrahman@cisco.com>";
skipping to change at line 347 skipping to change at line 478
WG List: <mailto:netconf@ietf.org> WG List: <mailto:netconf@ietf.org>
Editor: Eric Voit Editor: Eric Voit
<mailto:evoit@cisco.com> <mailto:evoit@cisco.com>
Editor: Alexander Clemm Editor: Alexander Clemm
<mailto:ludwig@clemm.org> <mailto:ludwig@clemm.org>
Editor: Reshad Rahman Editor: Reshad Rahman
<mailto:rrahman@cisco.com>"; <mailto:rrahman@cisco.com>";
description description
"Defines RESTCONF as a supported transport for subscribed "Defines RESTCONF as a supported transport for subscribed
event notifications. event notifications.
Copyright (c) 2019 IETF Trust and the persons identified as authors Copyright (c) 2019 IETF Trust and the persons identified
of the code. All rights reserved. as authors of the code. All rights reserved.
Redistribution and use in source and binary forms, with or without Redistribution and use in source and binary forms, with or
modification, is permitted pursuant to, and subject to the license without modification, is permitted pursuant to, and subject to
terms contained in, the Simplified BSD License set forth in Section the license terms contained in, the Simplified BSD License set
4.c of the IETF Trust's Legal Provisions Relating to IETF Documents forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(https://trustee.ietf.org/license-info). (https://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see the RFC This version of this YANG module is part of RFC 8650; see the
itself for full legal notices."; RFC itself for full legal notices.";
revision 2019-01-11 { revision 2019-10-15 {
description description
"Initial version"; "Initial version";
reference reference
"RFC XXXX: RESTCONF Transport for Event Notifications"; "RFC 8650: Dynamic Subscription to YANG Events and Datastores
over RESTCONF";
} }
grouping uri { grouping uri {
description description
"Provides a reusable description of a URI."; "Provides a reusable description of a URI.";
leaf uri { leaf uri {
type inet:uri; type inet:uri;
config false; config false;
description description
"Location of a subscription specific URI on the publisher."; "Location of a subscription-specific URI on the publisher.";
} }
} }
augment "/sn:establish-subscription/sn:output" { augment "/sn:establish-subscription/sn:output" {
description description
"This augmentation allows RESTCONF specific parameters for a "This augmentation allows RESTCONF-specific parameters for a
response to a publisher's subscription request."; response to a publisher's subscription request.";
uses uri; uses uri;
} }
augment "/sn:subscriptions/sn:subscription" { augment "/sn:subscriptions/sn:subscription" {
description description
"This augmentation allows RESTCONF specific parameters to be "This augmentation allows RESTCONF-specific parameters to be
exposed for a subscription."; exposed for a subscription.";
uses uri; uses uri;
} }
augment "/sn:subscription-modified" { augment "/sn:subscription-modified" {
description description
"This augmentation allows RESTCONF specific parameters to be "This augmentation allows RESTCONF-specific parameters to be
included as part of the notification that a subscription has been included as part of the notification that a subscription has
modified."; been modified.";
uses uri; uses uri;
} }
} }
<CODE ENDS> ]]></sourcecode>
]]></artwork>
</figure>
</section> </section>
<section title="IANA Considerations"> <section numbered="true" toc="default">
<t> <name>IANA Considerations</name>
This document registers the following namespace URI in the "IETF XML Regis
try" <xref target="RFC3688"/>:
</t>
<t> <t>
URI: This document registers the following namespace URI in the "ns"
urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications subregistry of the "IETF XML Registry" <xref target="RFC3688" format="defa
<vspace/> ult"/>:
Registrant Contact: The IESG.
<vspace/>
XML: N/A; the requested URI is an XML namespace.
</t> </t>
<dl>
<dt>URI:</dt>
<dd>urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications</
dd>
<dt>Registrant Contact:</dt>
<dd>The IESG.</dd>
<dt>XML:</dt>
<dd>N/A; the requested URI is an XML namespace.</dd>
</dl>
<t> <t>
This document registers the following YANG module in the "YANG Module Name This document registers the following YANG module in the "YANG Module
s" registry <xref target="RFC6020"/>: Names" registry <xref target="RFC6020" format="default"/>:
</t> </t>
<t> <dl>
Name: ietf-restconf-subscribed-notifications <dt>Name:</dt>
<vspace/> <dd>ietf-restconf-subscribed-notifications</dd>
Namespace: <dt>Namespace:</dt>
urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications <dd>urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications</
<vspace/> dd>
Prefix: rsn <dt>Prefix:</dt>
<vspace/> <dd>rsn</dd>
Reference: RFC XXXX: RESTCONF Transport for Event Notifications <dt>Reference:</dt>
</t> <dd>RFC 8650</dd>
</dl>
</section> </section>
<section anchor="security" numbered="true" toc="default">
<section anchor="security" title="Security Considerations"> <name>Security Considerations</name>
<t>The YANG module specified in this document defines a schema for data th
<t>The YANG module specified in this document defines a schema for data th at is designed to be accessed via network management transports such as NETCONF
at is designed to be accessed via network management transports such as NETCONF <xref target="RFC6241" format="default"/> or RESTCONF <xref target="RFC8040" for
<xref target="RFC6241"/> or RESTCONF <xref target="RFC8040"/>. The lowest NETCO mat="default"/>. The lowest NETCONF layer is the secure transport layer, and th
NF layer is the secure transport layer, and the mandatory-to-implement secure tr e mandatory-to-implement secure transport is Secure Shell (SSH) <xref target="RF
ansport is Secure Shell (SSH) <xref target="RFC6242"/>. The lowest RESTCONF lay C6242" format="default"/>. The lowest RESTCONF layer is HTTPS, and the mandator
er is HTTPS, and the mandatory-to-implement secure transport is TLS <xref target y-to-implement secure transport is TLS <xref target="RFC8446" format="default"/>
="RFC8446"/>.</t> .</t>
<t>The Network Configuration Access Control Model (NACM) <xref target="RFC
<t>The one new data node introduced in this YANG module may be considered 8341" format="default"/>
sensitive or vulnerable in some network environments. It is thus important to c provides the means to restrict access for particular NETCONF or
ontrol read access (e.g., via get, get-config, or notification) to this data nod RESTCONF users to a preconfigured subset of all available NETCONF
es. These are the subtrees and data nodes and their sensitivity/vulnerability:< or RESTCONF protocol operations and content.</t>
/t> <t>The one new data node introduced in this YANG module may be considered
sensitive or vulnerable in some network environments. It is thus important to c
ontrol read access (e.g., via get, get-config, or notification) to this data nod
e. These are the subtrees and data nodes and their sensitivity/vulnerability:</
t>
<t>Container: "/subscriptions"</t> <t>Container: "/subscriptions"</t>
<t><list style="symbols"> <ul spacing="normal">
<t>"uri": leaf will show where subscribed resources might be located on <li>"uri": leaf will show where subscribed resources might be located on
a publisher. Access control must be set so that only someone with proper access a publisher. Access control must be set so that only someone with proper acces
permissions, i.e., the same RESTCONF <xref target="RFC8040"/> user credentials s permissions, i.e., the same RESTCONF <xref target="RFC8040" format="default"/>
which invoked the corresponding "establish-subscription", has the ability to acc user credentials that invoked the corresponding "establish-subscription", has t
ess this resource.</t> he ability to access this resource.</li>
</list></t> </ul>
<t>The subscription URI is implementation specific and is encrypted via th <t>The subscription URI is implementation specific and is encrypted via th
e use of TLS. Therefore, even if an attacker succeeds in guessing the subscripti e use of TLS. Therefore, even if an attacker succeeds in guessing the subscripti
on URI, a RESTCONF username <xref target="RFC8040"/> with the required administr on URI, a RESTCONF username <xref target="RFC8040" format="default"/> with the r
ative permissions must be used to be able to access or modify that subscription. equired administrative permissions must be used to be able to access or modify t
It is recommended that the subscription URI values not be easily predictable.</ hat subscription. It is recommended that the subscription URI values not be easi
t> ly predictable.</t>
<t>The access permission considerations for the RPCs modify-subscription, <t>The access permission considerations for the RPCs "modify-subscription"
resync-subscription, delete-subscription and kill-subscription are described in , "resync-subscription", "delete-subscription", and "kill-subscription" are desc
<xref target="SSE"/>.</t> ribed in <xref target="SSE" format="default"/>.</t>
<t>If a buggy or compromised RESTCONF subscriber sends a number of "establ ish-subscription" requests, then these subscriptions accumulate and may <t>If a buggy or compromised RESTCONF subscriber sends a number of "establ ish-subscription" requests, then these subscriptions accumulate and may
use up system resources. In such a situation, the publisher MAY also suspen d or terminate a subset of the active use up system resources. In such a situation, the publisher <bcp14>MAY</bcp 14> also suspend or terminate a subset of the active
subscriptions from that RESTCONF subscriber in order to reclaim resources an d preserve normal operation for the other subscriptions. subscriptions from that RESTCONF subscriber in order to reclaim resources an d preserve normal operation for the other subscriptions.
</t> </t>
</section> </section>
<section title="Acknowledgments">
<t>We wish to acknowledge the helpful contributions, comments, and suggest
ions that were received from: Ambika Prasad Tripathy, Alberto Gonzalez Prieto, S
usan Hares, Tim Jenkins, Balazs Lengyel, Kent Watsen, Michael Scharf, Guangying
Zheng, Martin Bjorklund, Qin Wu and Robert Wilton.</t>
</section>
</middle> </middle>
<back> <back>
<references title="Normative References"> <references>
<?rfc include="reference.RFC.2119"?> <name>References</name>
<?rfc include="reference.RFC.3688"?> <references>
<?rfc include="reference.RFC.6020"?> <name>Normative References</name>
<?rfc include="reference.RFC.6241"?> <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
<?rfc include="reference.RFC.6242"?> ence.RFC.2119.xml"/>
<?rfc include="reference.RFC.6520"?> <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
<?rfc include="reference.RFC.7540"?> ence.RFC.3688.xml"/>
<?rfc include="reference.RFC.8040"?> <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
<?rfc include="reference.RFC.8174"?> ence.RFC.6020.xml"/>
<?rfc include="reference.RFC.8342"?> <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
<?rfc include="reference.RFC.8446"?> ence.RFC.6241.xml"/>
<xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
<reference anchor="I-D.draft-ietf-netconf-subscribed-notifications"> ence.RFC.6242.xml"/>
<front> <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
<title>Custom Subscription to Event Streams</title> ence.RFC.6520.xml"/>
<author fullname="Eric Voit" initials="E" surname="Voit"> <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
<organization/> ence.RFC.7540.xml"/>
</author> <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
<author fullname="Alexander Clemm" initials="A" surname="Clemm"> ence.RFC.8040.xml"/>
<organization/> <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
</author> ence.RFC.8174.xml"/>
<author fullname="Alberto Gonzalez Prieto" initials="A" <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
surname="Gonzalez Prieto"> ence.RFC.8341.xml"/>
<organization/> <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
</author> ence.RFC.8342.xml"/>
<author fullname="Ambika Prasad Tripathy" initials="A" <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
surname="Tripathy"> ence.RFC.8446.xml"/>
<organization/> <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
</author> ence.RFC.8639.xml"/>
<author fullname="Einar Nilsen-Nygaard" initials="E" <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
surname="Nilsen-Nygaard"> ence.RFC.8641.xml"/>
<organization/> <reference anchor="W3C-20150203" target="https://www.w3.org/TR/2015/REC-eve
</author> ntsource-20150203/">
<date month="January" year="2019"/> <front>
</front> <title>Server-Sent Events</title>
<seriesInfo name="Internet-Draft" value="draft-ietf-netconf-subscribed-n <author fullname="I Hickson" initials="I" surname="Hickson">
otifications-21"/> <organization/>
<format target="https://datatracker.ietf.org/doc/draft-ietf-netconf-subs </author>
cribed-notifications/" <date day="03" month="February" year="2015"/>
type="TXT"/> </front>
</reference> <seriesInfo name="W3C" value="Recommendation"/>
<annotation>Latest version available at &lt;<eref target="https://www.w3.org/TR/
<reference anchor="I-D.ietf-netconf-yang-push" eventsource/" />&gt;.</annotation>
target="https://datatracker.ietf.org/doc/draft-ietf-netconf-yan </reference>
g-push/"> </references>
<front> <references>
<title>Subscribing to YANG datastore push updates</title> <name>Informative References</name>
<xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
<author fullname="Alexander Clemm" initials="A" surname="Clemm"> ence.RFC.7231.xml"/>
<organization>Huawei</organization> <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
</author> ence.RFC.7923.xml"/>
<xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
<author fullname="Eric Voit" initials="E" surname="Voit"> ence.RFC.7951.xml"/>
<organization>Cisco</organization> <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
</author> ence.RFC.8347.xml"/>
<xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
<author fullname="Alberto Gonzalez Prieto" initials="A" ence.RFC.8527.xml"/>
surname="Gonzalez Prieto"> <xi:include href="https://xml2rfc.tools.ietf.org/public/rfc/bibxml/refer
<organization>VMWare</organization> ence.RFC.8640.xml"/>
</author> <reference anchor="XPATH" target="http://www.w3.org/TR/1999/REC-xpath-19
991116">
<author fullname="Ambika Prasad Tripathy" initials="A" <front>
surname="Prasad Tripathy"> <title>XML Path Language (XPath) Version 1.0</title>
<organization>Cisco</organization> <author fullname="J Clark" initials="J" surname="Clark"/>
</author> <author fullname="S DeRose" initials="S" surname="DeRose"/>
<date day="16" month="November" year="1999"/>
<author fullname="Einar Nilsen-Nygaard" initials="E" </front>
surname="Nilsen-Nygaard"> <seriesInfo name="W3C" value="Recommendation"/>
<organization>Cisco</organization> <annotation>Latest version available at &lt;<eref target="https://www.w3.org/TR/
</author> xpath/" />&gt;.</annotation>
</reference>
<author fullname="Andy Bierman" initials="A" </references>
surname="Bierman">
<organization>YumaWorks</organization>
</author>
<author fullname="B Lengyel" initials="B"
surname="Lengyel">
<organization>Ericsson</organization>
</author>
<date day="22" month="October" year="2018"/>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-netconf-yang-push-20
"/>
<format target="https://datatracker.ietf.org/doc/draft-ietf-netconf-yang
-push/"
type="TXT"/>
</reference>
<reference anchor="W3C-20150203"
target="https://www.w3.org/TR/2015/REC-eventsource-20150203/">
<front>
<title>Server-Sent Events, World Wide Web Consortium CR
CR-eventsource-20121211</title>
<author fullname="I Hickson">
<organization/>
</author>
<date month="February" year="2015"/>
</front>
</reference>
</references>
<references title="Informative References">
<?rfc include="reference.RFC.7231"?>
<?rfc include="reference.RFC.7923"?>
<?rfc include="reference.RFC.7951"?>
<?rfc include="reference.RFC.8347"?>
<reference anchor="I-D.draft-ietf-netconf-nmda-restconf"
target="https://datatracker.ietf.org/doc/draft-ietf-netconf-nmd
a-restconf/">
<front>
<title>RESTCONF Extensions to Support the Network Management Datastore
Architecture</title>
<author fullname="Martin Bjorklund" initials="M" surname="Bjorklund"><
/author>
<author fullname="Juergen Schoenwaelder" initials="J" surname="Schoenw
aelder"></author>
<author fullname="Phil Shafer" initials="P" surname="Shafer"></author>
<author fullname="Kent Watsen" initials="K" surname="Watsen"></author>
<author fullname="Rob Wilton" initials="R" surname="Wilton"></author>
<date month="April" year="2018"/>
</front>
</reference>
<reference anchor="I-D.draft-ietf-netconf-netconf-event-notifications"
target="https://datatracker.ietf.org/doc/draft-ietf-netconf-net
conf-event-notifications/">
<front>
<title>NETCONF support for event notifications</title>
<author fullname="A Clemm" initials="Alexander" surname="Clemm"></auth
or>
<author fullname="E Voit" initials="Eric" surname="Voit"></author>
<author fullname="A Gonzalez Prieto" initials="Alberto" surname="Gonza
lez Prieto"></author>
<author fullname="Einar Nilsen-Nygaard" initials="E" surname="Nilsen-N
ygaard"></author>
<author fullname="Ambika Prasad Tripathy" initials="A" surname="Tripat
hy"></author>
<date month="May" year="2018"/>
</front>
</reference>
<reference anchor="XPATH"
target="http://www.w3.org/TR/1999/REC-xpath-19991116">
<front>
<title>XML Path Language (XPath) Version 1.0</title>
<author fullname="J Clark" initials="J" surname="Clark"></author>
<author fullname="S DeRose" initials="S" surname="DeRose"></author>
<date month="November" year="1999"/>
</front>
</reference>
</references> </references>
<section numbered="true" toc="default">
<section title="Examples"> <name>Examples</name>
<t>This section is non-normative. To allow easy comparison, this section
<t>This section is non-normative. To allow easy comparison, this section mirrors the functional examples shown with NETCONF over XML within <xref target=
mirrors the functional examples shown with NETCONF over XML within <xref target= "RFC8640" format="default"/>. In addition, HTTP/2 vs HTTP/1.1 headers are not s
"I-D.draft-ietf-netconf-netconf-event-notifications"/>. In addition, HTTP2 vs H hown as the contents of the JSON encoded objects are identical within.</t>
TTP1.1 headers are not shown as the contents of the JSON encoded objects are ide <t>The subscription URI values used in the examples in this section are pu
ntical within.</t> rely illustrative, and are not indicative of the expected usage that is describe
<t>The subscription URI values used in the examples in this section are pu d in <xref target="security" format="default"/>.</t>
rely illustrative, and are not indicative of the expected usage which is describ <t>The DSCP values are only for example purposes and are all indicated in
ed in <xref target="security"/>.</t> decimal since the encoding is JSON <xref target="RFC7951" format="default"/>.</t
<t>The DSCP values are only for example purposes and are all indicated in >
decimal since the encoding is JSON <xref target="RFC7951"/>.</t> <section numbered="true" toc="default">
<section title="Dynamic Subscriptions"> <name>Dynamic Subscriptions</name>
<section numbered="true" toc="default">
<section title="Establishing Dynamic Subscriptions"> <name>Establishing Dynamic Subscriptions</name>
<t>The following figure shows two successful
<t>The following figure shows two successful "establish-subscription" "establish-subscription" RPC requests as per <xref target="RFC8639"
RPC requests as per <xref target="I-D.draft-ietf-netconf-subscribed-notification format="default"/>. The first request is given a subscription
s"/>. The first request is given a subscription identifier of 22, the second, a identifier of 22, and the second, an identifier of 23.</t>
n identifier of 23.</t> <figure anchor="mess-flow-establishment">
<name>Multiple Subscriptions over RESTCONF/HTTP</name>
<figure anchor = "mess-flow-establishment" <artwork name="" type="" align="left" alt=""><![CDATA[
title="Multiple subscriptions over RESTCONF/HTTP">
<artwork><![CDATA[
+------------+ +-----------+ +------------+ +-----------+
| Subscriber | | Publisher | | Subscriber | | Publisher |
+------------+ +-----------+ +------------+ +-----------+
| | | |
|establish-subscription | |establish-subscription |
|------------------------------>| (a) |------------------------------>| (a)
| HTTP 200 OK, id#22, URI#1 | | HTTP 200 OK, id#22, URI#1 |
|<------------------------------| (b) |<------------------------------| (b)
|GET (URI#1) | |GET (URI#1) |
|------------------------------>| (c) |------------------------------>| (c)
skipping to change at line 650 skipping to change at line 683
| HTTP 200 OK, id#23, URI#2| | HTTP 200 OK, id#23, URI#2|
|<------------------------------| |<------------------------------|
|GET (URI#2) | |GET (URI#2) |
|------------------------------>| |------------------------------>|
| | | |
| | | |
| notif-mesg (id#22)| | notif-mesg (id#22)|
|<------------------------------| |<------------------------------|
| HTTP 200 OK,notif-mesg (id#23)| | HTTP 200 OK,notif-mesg (id#23)|
|<------------------------------| |<------------------------------|
| | | | ]]></artwork>
]]></artwork>
</figure> </figure>
<t>To provide examples of the information being transported, example m
<t>To provide examples of the information being transported, example m essages for interactions in <xref target="mess-flow-establishment" format="defa
essages for interactions in <xref target="mess-flow-establishment"/> are detail ult"/> are detailed below:</t>
ed below:</t> <figure anchor="establish-subs">
<name>"establish-subscription" Request (a)</name>
<figure align="center" anchor="establish-subs" title="establish-subscr <artwork name="ex-establish-subscription.json" type=""
iption request (a)"> align="left" alt=""><![CDATA[
<artwork name="ex-establish-subscription.json"><![CDATA[
POST /restconf/operations POST /restconf/operations
/ietf-subscribed-notifications:establish-subscription /ietf-subscribed-notifications:establish-subscription
{ {
"ietf-subscribed-notifications:input": { "ietf-subscribed-notifications:input": {
"stream-xpath-filter": "/example-module:foo/", "stream-xpath-filter": "/example-module:foo/",
"stream": "NETCONF", "stream": "NETCONF",
"dscp": 10 "dscp": 10
} }
} } ]]></artwork>
]]></artwork>
</figure> </figure>
<t>As the publisher was able to fully satisfy the request, the publish
<t>As publisher was able to fully satisfy the request, the publisher s er sends the subscription identifier of the accepted subscription and the URI:</
ends the subscription identifier of the accepted subscription, and the URI:</t> t>
<figure anchor="positive-establish-subs">
<figure align="center" anchor="positive-establish-subs" title="establi <name>"establish-subscription" Success (b)</name>
sh-subscription success (b)"> <artwork name="" type="" align="left" alt=""><![CDATA[
<artwork><![CDATA[
HTTP status code - 200 HTTP status code - 200
{ {
"id": 22, "id": 22,
"uri": "https://example.com/restconf/subscriptions/22" "uri": "https://example.com/restconf/subscriptions/22"
} } ]]></artwork>
]]></artwork>
</figure> </figure>
<t>Upon receipt of the successful response, the subscriber does a
<t>Upon receipt of the successful response, the subscriber does a GET GET to the provided URI to start the flow of notification messages.
the provided URI to start the flow of notification messages. When the publisher When the publisher receives this, the subscription is moved to the
receives this, the subscription is moved to the active state (c).</t> active state (c).</t>
<figure anchor="positive-establish-post">
<figure align="center" anchor="positive-establish-post" title="establi <name>"establish-subscription" Subsequent POST</name>
sh-subscription subsequent POST"> <artwork name="" type="" align="left" alt=""><![CDATA[
<artwork><![CDATA[ GET /restconf/subscriptions/22 ]]></artwork>
GET /restconf/subscriptions/22
]]></artwork>
</figure> </figure>
<t>While not shown in <xref target="mess-flow-establishment" format="d efault"/>, if the publisher had not been able to fully satisfy the request, or t he 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 a sserted by the subscriber in <xref target="establish-subs" format="default"/> pr oved unacceptable, the publisher may have returned:</t>
<t>While not shown in <xref target="mess-flow-establishment"/>, if the <figure anchor="negative-establish-subs">
publisher had not been able to fully satisfy the request, or subscriber has no <name>An Unsuccessful "establish-subscription"</name>
authorization to establish the subscription, the publisher would have sent an RP <artwork name="" type="" align="left" alt=""><![CDATA[
C error response. For instance, if the "dscp" value of 10 asserted by the subscr HTTP status code - 400
iber in <xref target="establish-subs"/> proved unacceptable, the publisher may h
ave returned:</t>
<figure align="center" anchor="negative-establish-subs" title="an unsu
ccessful establish subscription">
<artwork><![CDATA[
HTTP status code - 400
{ "ietf-restconf:errors" : { { "ietf-restconf:errors" : {
"error" : [ "error" : [
{ {
"error-type": "application", "error-type": "application",
"error-tag": "invalid-value", "error-tag": "invalid-value",
"error-severity": "error", "error-severity": "error",
"error-app-tag": "error-app-tag":
"ietf-subscribed-notifications:dscp-unavailable" "ietf-subscribed-notifications:dscp-unavailable"
}
]
}
} }
]
]]></artwork> }
} ]]></artwork>
</figure> </figure>
<t>The subscriber can use this information in future attempts to estab lish a subscription.</t> <t>The subscriber can use this information in future attempts to estab lish a subscription.</t>
</section> </section>
<section numbered="true" toc="default">
<section title="Modifying Dynamic Subscriptions"> <name>Modifying Dynamic Subscriptions</name>
<t>An existing subscription may be modified. The following exchange s
<t>An existing subscription may be modified. The following exchange s hows a negotiation of such a modification via several exchanges between a subscr
hows a negotiation of such a modification via several exchanges between a subscr iber and a publisher. This negotiation consists of a failed RPC modification re
iber and a publisher. This negotiation consists of a failed RPC modification re quest/response followed by a successful one.</t>
quest/response, followed by a successful one.</t> <figure anchor="mess-flow-subs-modification">
<name>Interaction Model for Successful Subscription Modification</na
<figure anchor = "mess-flow-subs-modification" me>
title="Interaction model for successful subscription modificatio <artwork name="" type="" align="left" alt=""><![CDATA[
n">
<artwork><![CDATA[
+------------+ +-----------+ +------------+ +-----------+
| Subscriber | | Publisher | | Subscriber | | Publisher |
+------------+ +-----------+ +------------+ +-----------+
| | | |
| notification message (id#23)| | notification message (id#23)|
|<-----------------------------| |<-----------------------------|
| | | |
|modify-subscription (id#23) | |modify-subscription (id#23) |
|----------------------------->| (d) |----------------------------->| (d)
| HTTP 400 error (with hint)| | HTTP 400 error (with hint)|
|<-----------------------------| (e) |<-----------------------------| (e)
| | | |
|modify-subscription (id#23) | |modify-subscription (id#23) |
|----------------------------->| |----------------------------->|
| HTTP 200 OK | | HTTP 200 OK |
|<-----------------------------| |<-----------------------------|
| | | |
| notif-mesg (id#23)| | notif-mesg (id#23)|
|<-----------------------------| |<-----------------------------|
| | | | ]]></artwork>
]]></artwork>
</figure> </figure>
<t>If the subscription being modified in <xref target="mess-flow-subs-
<t>If the subscription being modified in <xref target="mess-flow-subs- modification" format="default"/> is a datastore subscription as per <xref target
modification"/> is a datastore subscription as per <xref target="I-D.ietf-netcon ="RFC8641" format="default"/>, the modification request made in (d) may look lik
f-yang-push"/>, the modification request made in (d) may look like that shown in e that shown in <xref target="simple-modify-subs" format="default"/>. As can be
<xref target="simple-modify-subs"/>. As can be seen, the modifications being a seen, the modifications being attempted are the application of a new XML Path L
ttempted are the application of a new xpath filter as well as the setting of a n anguage (XPath) filter as well as the setting of a new periodic time interval.</
ew periodic time interval.</t> t>
<figure anchor="simple-modify-subs">
<figure align="center" anchor="simple-modify-subs" title="Subscription <name>Subscription Modification Request (c)</name>
modification request (c)"> <artwork name="ex-modify-subscription.json" type="" align="left" alt
<artwork name="ex-modify-subscription.json"><![CDATA[ =""><![CDATA[
POST /restconf/operations POST /restconf/operations
/ietf-subscribed-notifications:modify-subscription /ietf-subscribed-notifications:modify-subscription
{ {
"ietf-subscribed-notifications:input": { "ietf-subscribed-notifications:input": {
"id": 23, "id": 23,
"ietf-yang-push:datastore-xpath-filter": "ietf-yang-push:datastore-xpath-filter":
"/example-module:foo/example-module:bar", "/example-module:foo/example-module:bar",
"ietf-yang-push:periodic": { "ietf-yang-push:periodic": {
"ietf-yang-push:period": 500 "ietf-yang-push:period": 500
} }
} }
} } ]]></artwork>
]]></artwork>
</figure> </figure>
<t>If the publisher can satisfy both changes, the publisher sends a po
sitive result for the RPC. If the publisher cannot satisfy either of the propose
d changes, the publisher sends an RPC error response (e). The following is an e
xample RPC error response for (e) that includes a hint. This hint is an alternat
ive time period value that might have resulted in a successful modification:</t>
<figure anchor="negative-modify-subs">
<name>"modify-subscription" Failure with Hint (e)</name>
<artwork name="" type="" align="left" alt=""><![CDATA[
HTTP status code - 400
<t>If the publisher can satisfy both changes, the publisher sends a po { "ietf-restconf:errors" : {
sitive result for the RPC. If the publisher cannot satisfy either of the propose "error" : [
d changes, the publisher sends an RPC error response (e). The following is an e "error-type": "application",
xample RPC error response for (e) which includes a hint. This hint is an alterna "error-tag": "invalid-value",
tive time period value which might have resulted in a successful modification:</ "error-severity": "error",
t> "error-app-tag": "ietf-yang-push:period-unsupported",
"error-info": {
<figure align="center" anchor="negative-modify-subs" title="Modify sub "ietf-yang-push":
scription failure with Hint (e)"> "modify-subscription-datastore-error-info": {
<artwork><![CDATA[ "period-hint": 3000
HTTP status code - 400
{ "ietf-restconf:errors" : {
"error" : [
"error-type": "application",
"error-tag": "invalid-value",
"error-severity": "error",
"error-app-tag": "ietf-yang-push:period-unsupported",
"error-info": {
"ietf-yang-push":
"modify-subscription-datastore-error-info": {
"period-hint": 3000
}
}
]
} }
} }
]]></artwork> ]
}
} ]]></artwork>
</figure> </figure>
</section> </section>
<section numbered="true" toc="default">
<section title="Deleting Dynamic Subscriptions"> <name>Deleting Dynamic Subscriptions</name>
<t>The following demonstrates deleting a subscription. This subscript ion may have been to either a stream or a datastore.</t> <t>The following demonstrates deleting a subscription. This subscript ion may have been to either a stream or a datastore.</t>
<figure anchor="simple-delete-subs">
<figure align="center" anchor="simple-delete-subs" title="Delete subsc <name>"delete-subscription" Request</name>
ription"> <artwork name="ex-delete-subscription.json" type="" align="left" alt
<artwork name="ex-delete-subscription.json"><![CDATA[ =""><![CDATA[
POST /restconf/operations POST /restconf/operations
/ietf-subscribed-notifications:delete-subscription /ietf-subscribed-notifications:delete-subscription
{ {
"delete-subscription": { "delete-subscription": {
"id": "22" "id": "22"
} }
} } ]]></artwork>
]]></artwork>
</figure> </figure>
<t>If the publisher can satisfy the request, the publisher replies wit h success to the RPC request.</t> <t>If the publisher can satisfy the request, the publisher replies wit h success to the RPC request.</t>
<t>If the publisher cannot satisfy the request, the publisher sends
an &lt;rpc-error&gt; element indicating the modification didn't work. <
xref
target="negative-delete-subs" format="default"/> shows a valid
response for an existing valid subscription identifier, but that subscr
iption identifier was created on a different transport session:</t>
<figure anchor="negative-delete-subs">
<name>Unsuccessful "delete-subscription"</name>
<artwork name="" type="" align="left" alt=""><![CDATA[
HTTP status code - 404
<t>If the publisher cannot satisfy the request, the publisher sends an {
error-rpc element indicating the modification didn't work. <xref target="negati "ietf-restconf:errors" : {
ve-delete-subs"/> shows a valid response for existing valid subscription identif "error" : [
ier, but that subscription identifier was created on a different transport sessi "error-type": "application",
on:</t> "error-tag": "invalid-value",
"error-severity": "error",
<figure align="center" anchor="negative-delete-subs" title="Unsuccessful "error-app-tag":
delete subscription"> "ietf-subscribed-notifications:no-such-subscription"
<artwork><![CDATA[ ]
HTTP status code - 404 }
} ]]></artwork>
{
"ietf-restconf:errors" : {
"error" : [
"error-type": "application",
"error-tag": "invalid-value",
"error-severity": "error",
"error-app-tag":
"ietf-subscribed-notifications:no-such-subscription"
]
}
}
]]></artwork>
</figure> </figure>
</section> </section>
</section> </section>
<section numbered="true" toc="default">
<section title="Subscription State Notifications"> <name>Subscription State Notifications</name>
<t>A publisher will send subscription state notifications according to t
<t>A publisher will send subscription state notifications according to he definitions within <xref target="RFC8639" format="default"/>.</t>
the definitions within <xref target="I-D.draft-ietf-netconf-subscribed-notificat <section numbered="true" toc="default">
ions"/>).</t> <name>"subscription-modified"</name>
<section title="subscription-modified">
<t>A "subscription-modified" encoded in JSON would look like:</t> <t>A "subscription-modified" encoded in JSON would look like:</t>
<figure anchor="subscription-modified-ctrl-plane-notif">
<figure align="center" anchor="subscription-modified-ctrl-plane-notif" <name>"subscription-modified" Subscription State Notification</name>
title="subscription-modified subscription state notification"> <sourcecode name="" type="json"><![CDATA[
<artwork><![CDATA[
{ {
"ietf-restconf:notification" : { "ietf-restconf:notification" : {
"eventTime": "2007-09-01T10:00:00Z", "eventTime": "2007-09-01T10:00:00Z",
"ietf-subscribed-notifications:subscription-modified": { "ietf-subscribed-notifications:subscription-modified": {
"id": 39, "id": 39,
"uri": "https://example.com/restconf/subscriptions/22" "uri": "https://example.com/restconf/subscriptions/22"
"stream-xpath-filter": "/example-module:foo", "stream-xpath-filter": "/example-module:foo",
"stream": { "stream": {
"ietf-netconf-subscribed-notifications" : "NETCONF" "ietf-netconf-subscribed-notifications" : "NETCONF"
} }
} }
} }
} } ]]></sourcecode>
]]></artwork>
</figure> </figure>
</section> </section>
<section numbered="true" toc="default">
<section title="subscription-completed, subscription-resumed, and replay <name>"subscription-completed", "subscription-resumed", and "replay-co
-complete"> mpleted"</name>
<t>A "subscription-completed" notification would look like:</t>
<t>A "subscription-completed" would look like:</t> <figure anchor="subscription-completed">
<name>"subscription-completed" Notification in JSON</name>
<figure align="center" <sourcecode name="ex-subscription-completed.json" type="json"><![CDA
anchor="subscription-completed" TA[
title="subscription-completed notification in JSON">
<artwork name="ex-subscription-completed.json"><![CDATA[
{ {
"ietf-restconf:notification" : { "ietf-restconf:notification" : {
"eventTime": "2007-09-01T10:00:00Z", "eventTime": "2007-09-01T10:00:00Z",
"ietf-subscribed-notifications:subscription-completed": { "ietf-subscribed-notifications:subscription-completed": {
"id": 39, "id": 39,
} }
} }
} } ]]></sourcecode>
]]></artwork>
</figure> </figure>
<t>The "subscription-resumed" and "replay-complete" are virtually iden tical, with "subscription-completed" simply being replaced by "subscription-resu med" and "replay-complete".</t> <t>The "subscription-resumed" and "replay-complete" are virtually iden tical, with "subscription-completed" simply being replaced by "subscription-resu med" and "replay-complete".</t>
</section> </section>
<section numbered="true" toc="default">
<section title="subscription-terminated and subscription-suspended"> <name>"subscription-terminated" and "subscription-suspended"</name>
<t>A "subscription-terminated" would look like:</t> <t>A "subscription-terminated" would look like:</t>
<figure anchor="subscription-terminated">
<figure align="center" <name>"subscription-terminated" Subscription State Notification</nam
anchor="subscription-terminated" e>
title="subscription-terminated subscription state notification <sourcecode name="ex-subscription-terminated.json" type="json"><![CD
"> ATA[
<artwork name="ex-subscription-terminated.json"><![CDATA[
{ {
"ietf-restconf:notification" : { "ietf-restconf:notification" : {
"eventTime": "2007-09-01T10:00:00Z", "eventTime": "2007-09-01T10:00:00Z",
"ietf-subscribed-notifications:subscription-terminated": { "ietf-subscribed-notifications:subscription-terminated": {
"id": 39, "id": 39,
"error-id": "suspension-timeout" "error-id": "suspension-timeout"
} }
} }
} } ]]></sourcecode>
]]></artwork>
</figure> </figure>
<t>The "subscription-suspended" is virtually identical, with "subscrip tion-terminated" simply being replaced by "subscription-suspended".</t> <t>The "subscription-suspended" is virtually identical, with "subscrip tion-terminated" simply being replaced by "subscription-suspended".</t>
</section> </section>
</section> </section>
<section numbered="true" toc="default">
<section title="Filter Example"> <name>Filter Example</name>
<t>This section provides an example that illustrates the method of filte
<t>This section provides an example which illustrate the method of filteri ring event record contents. The example is based on the YANG notification "vrrp
ng event record contents. The example is based on the YANG notification "vrrp-p -protocol-error-event" as defined per the ietf-vrrp.yang module within <xref tar
rotocol-error-event" as defined per the ietf-vrrp.yang module within <xref targe get="RFC8347" format="default"/>. Event records based on this specification tha
t="RFC8347"/>. Event records based on this specification which are generated by t are generated by the publisher might appear as:</t>
the publisher might appear as:</t> <figure anchor="VRRP-notification">
<name>RFC 8347 (VRRP) - Example Notification</name>
<figure align="center" <artwork name="" type="" align="left" alt=""><![CDATA[
anchor="VRRP-notification" data: {
title="RFC 8347 (VRRP) - Example Notification"> data: "ietf-restconf:notification" : {
<artwork><![CDATA[ data: "eventTime" : "2018-09-14T08:22:33.44Z",
data: { data: "ietf-vrrp:vrrp-protocol-error-event" : {
data: "ietf-restconf:notification" : { data: "protocol-error-reason" : "checksum-error"
data: "eventTime" : "2018-09-14T08:22:33.44Z", data: }
data: "ietf-vrrp:vrrp-protocol-error-event" : { data: }
data: "protocol-error-reason" : "checksum-error" data: } ]]></artwork>
data: } </figure>
data: } <t>Suppose a subscriber wanted to establish a subscription that only pas
data: } ses instances of event records where there is a "checksum-error" as part of a Vi
]]></artwork> rtual Router Redundancy Protocol (VRRP) protocol event. Also assume the publish
</figure> er places such event records into the NETCONF stream. To get a continuous serie
s of matching event records, the subscriber might request the application of an
<t>Suppose a subscriber wanted to establish a subscription which only pass XPath filter against the NETCONF stream. An "establish-subscription" RPC to mee
es instances of event records where there is a "checksum-error" as part of a VRR t this objective might be:</t>
P protocol event. Also assume the publisher places such event records into the <figure anchor="VRRP-XPATH">
NETCONF stream. To get a continuous series of matching event records, the subsc <name>Establishing a Subscription Error Reason via XPath</name>
riber might request the application of an XPath filter against the NETCONF strea <artwork name="ex-establish-subscription-filter-xpath.json" type="" al
m. An "establish-subscription" RPC to meet this objective might be:</t> ign="left" alt=""><![CDATA[
<figure align="center"
anchor="VRRP-XPATH"
title="Establishing a subscription error reason via XPath">
<artwork name="ex-establish-subscription-filter-xpath.json"><!
[CDATA[
POST /restconf/operations POST /restconf/operations
/ietf-subscribed-notifications:establish-subscription /ietf-subscribed-notifications:establish-subscription
{ {
"ietf-subscribed-notifications:input": { "ietf-subscribed-notifications:input": {
"stream": "NETCONF", "stream": "NETCONF",
"stream-xpath-filter": "stream-xpath-filter":
"/ietf-vrrp:vrrp-protocol-error-event[ "/ietf-vrrp:vrrp-protocol-error-event[
protocol-error-reason='checksum-error']/", protocol-error-reason='checksum-error']/",
} }
} } ]]></artwork>
]]></artwork> </figure>
</figure> <t>For more examples of XPath filters, see <xref target="XPATH" format="
default"/>.</t>
<t>For more examples of XPath filters, see <xref target="XPATH"/>.</t> <t>Suppose the "establish-subscription" in <xref target="VRRP-XPATH" for
mat="default"/> was accepted. And suppose later a subscriber decided they wanted
<t>Suppose the "establish-subscription" in <xref target="VRRP-XPATH"/> was to broaden this subscription cover to all VRRP protocol events (i.e., not just
accepted. And suppose later a subscriber decided they wanted to broaden this su those with a "checksum error"). The subscriber might attempt to modify the subs
bscription cover to all VRRP protocol events (i.e., not just those with a "check cription in a way that replaces the XPath filter with a subtree filter that send
sum error"). The subscriber might attempt to modify the subscription in a way w s all VRRP protocol events to a subscriber. Such a "modify-subscription" RPC mig
hich replaces the XPath filter with a subtree filter which sends all VRRP protoc ht look like:</t>
ol events to a subscriber. Such a "modify-subscription" RPC might look like:</t>
<figure align="center" <figure anchor="VRRP-Subtree">
anchor="VRRP-Subtree" <name>Example "modify-subscription" RPC</name>
title=""> <artwork name="ex-modify-subscription-filter-subtree.json" type="" ali
<artwork name="ex-modify-subscription-filter-subtree.json"><![ gn="left" alt=""><![CDATA[
CDATA[
POST /restconf/operations POST /restconf/operations
/ietf-subscribed-notifications:modify-subscription /ietf-subscribed-notifications:modify-subscription
{ {
"ietf-subscribed-notifications:input": { "ietf-subscribed-notifications:input": {
"stream": "NETCONF", "stream": "NETCONF",
"stream-subtree-filter": { "stream-subtree-filter": {
"/ietf-vrrp:vrrp-protocol-error-event" : {} "/ietf-vrrp:vrrp-protocol-error-event" : {}
} }
} }
} } ]]></artwork>
]]></artwork> </figure>
</figure> <t>For more examples of subtree filters, see <xref target="RFC6241" sect
ionFormat="comma" section="6.4" format="default"/>.</t>
<t>For more examples of subtree filters, see <xref target="RFC6241"/>, sec </section>
tion 6.4.</t>
</section>
</section> </section>
<section title="Changes between revisions"> <section numbered="false" toc="default">
<t>(To be removed by RFC editor prior to publication)</t> <name>Acknowledgments</name>
<t>We wish to acknowledge the helpful contributions, comments, and suggest
<t>v14 - v15</t> ions that were received from Ambika Prasad Tripathy, Alberto Gonzalez Prieto, Su
<t><list style="symbols"> san Hares, Tim Jenkins, Balazs Lengyel, Kent Watsen, Michael Scharf, Guangying Z
<t>Addressed review comments from Kent.</t> heng, Martin Bjorklund, Qin Wu, and Robert Wilton.</t>
</list>
</t>
<t>v13 - v14</t>
<t><list style="symbols">
<t>Addressed review comments from IESG.</t>
</list>
</t>
<t>v12 - v13</t>
<t><list style="symbols">
<t>Enhanced "error-tag" values based on SN review.</t>
</list>
</t>
<t>v11 - v12</t>
<t><list style="symbols">
<t>Added text in 3.2 for expected behavior when ietf-restconf-monito
ring.yang is also supported.</t>
<t>Added section 2 to the reference to draft-ietf-netconf-nmda-restc
onf.</t>
<t>Replaced kill-subscription-error by delete-subscription-error in
section 3.3.</t>
<t>Clarified vertical lines (a) and (b) in Figure 1 of section 3.4</
t>
<t>Section 3.4, 3rd bullet after Figure 1, replaced "must" with "MUS
T".</t>
<t>Modified text in section 3.4 regarding access to RPCs modify-subs
cription, resync-subscription, delete-subscription and kill-subscription.</t>
<t>Section 4, first bullet for HTTP2: replaced dscp and priority wit
h weighting and weight.</t>
<t>Section 6, added YANG tree diagram and fixed description of the m
odule.</t>
<t>Section 7, fixed indentation of module description statement.</t>
<t>Section 7, in YANG module changed year in copyright statement to
2019.</t>
<t>Section 8, added text on how server protects access to the subscr
iption URI.</t>
<t>Fixed outdated references and removed unused references.</t>
<t>Fixed the instances of line too long.</t>
<t>Fixed example in Figure 3.</t>
</list>
</t>
<t>v10 - v11</t>
<t><list style="symbols">
<t>Per Kent's request, added name attribute to artwork which need to
be extracted</t>
</list>
</t>
<t>v09 - v10</t>
<t><list style="symbols">
<t>Fixed typo for resync.</t>
<t>Added text wrt RPC permissions and RESTCONF username.</t>
</list>
</t>
<t>v08 - v09</t>
<t><list style="symbols">
<t>Addressed comments received during WGLC.</t>
</list>
</t>
<t>v07 - v08</t>
<t><list style="symbols">
<t>Aligned with RESTCONF mechanism.</t>
<t>YANG model: removed augment of subscription-started, added restco
nf transport.</t>
<t>Tweaked Appendix A.1 to match draft-ietf-netconf-netconf-event-no
tifications-13.</t>
<t>Added Appendix A.3 for filter example.</t>
</list>
</t>
<t>v06 - v07</t>
<t><list style="symbols">
<t>Removed configured subscriptions.</t>
<t>Subscription identifier renamed to id.</t>
</list>
</t>
<t>v05 - v06</t>
<t><list style="symbols">
<t>JSON examples updated by Reshad.</t>
</list>
</t>
<t>v04 - v05</t>
<t><list style="symbols">
<t>Error mechanisms updated to match embedded RESTCONF mechanisms</t
>
<t>Restructured format and sections of document.</t>
<t>Added a YANG data model for HTTP specific parameters.</t>
<t>Mirrored the examples from the NETCONF transport draft to allow e
asy comparison.</t>
</list>
</t>
<t>v03 - v04</t>
<t><list style="symbols">
<t>Draft not fully synched to new version of subscribed-notification
s yet.</t>
<t>References updated</t>
</list>
</t>
<t>v02 - v03</t>
<t><list style="symbols">
<t>Event notification reframed to notification message.</t>
<t>Tweaks to wording/capitalization/format.</t>
</list>
</t>
<t>v01 - v02</t>
<t><list style="symbols">
<t>Removed sections now redundant with <xref target="I-D.draft-ietf-
netconf-subscribed-notifications"/> and <xref target="I-D.ietf-netconf-yang-push
"/> such as: mechanisms for subscription maintenance, terminology definitions,
stream discovery.</t>
<t>3rd party subscriptions are out-of-scope.</t>
<t>SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions</t>
<t>Timeframes for event tagging are self-defined.</t>
<t>Clean-up of wording, references to terminology, section numbers.<
/t>
</list>
</t>
<t>v00 - v01</t>
<t><list style="symbols">
<t>Removed the ability for more than one subscription to go to a sin
gle HTTP2 stream.</t>
<t>Updated call flows. Extensively.</t>
<t>SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions</t>
<t>HTTP is not used to determine that a receiver has gone silent and
is not Receiving Event Notifications</t>
<t>Many clean-ups of wording and terminology</t>
</list>
</t>
</section> </section>
</back> </back>
</rfc> </rfc>
 End of changes. 118 change blocks. 
1018 lines changed or deleted 838 lines changed or added

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