doc: Add RFC documents

1 files changed, 1067 insertions, 0 deletions

diff --git a/doc/rfc/rfc8640.txt b/doc/rfc/rfc8640.txt
new file mode 100644
index 0000000..f19a45f
--- /dev/null
+++ b/doc/rfc/rfc8640.txt
@@ -0,0 +1,1067 @@
+
+
+
+
+
+
+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
+
+Abstract
+
+   This document provides a Network Configuration Protocol (NETCONF)
+   binding to the dynamic subscription capability of both subscribed
+   notifications and YANG-Push.
+
+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.
+
+   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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al.                 Standards Track                    [Page 1]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+Copyright Notice
+
+   Copyright (c) 2019 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   This document is subject to BCP 78 and the IETF Trust's Legal
+   Provisions Relating to IETF Documents
+   (https://trustee.ietf.org/license-info) in effect on the date of
+   publication of this document.  Please review these documents
+   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.
+
+   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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al.                 Standards Track                    [Page 2]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+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
+
+   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.
+
+   This document assumes that the reader is familiar with the
+   terminology and concepts defined in [RFC8639].
+
+2.  Terminology
+
+   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.
+
+   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.
+
+
+
+Voit, et al.                 Standards Track                    [Page 3]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+3.  Compatibility with <create-subscription> as Defined in RFC 5277
+
+   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:
+
+   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  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.
+
+   If a publisher supports this specification but not subscriptions via
+   [RFC5277], the publisher MUST NOT advertise
+   "urn:ietf:params:netconf:capability:notification:1.0".
+
+4.  Mandatory XML, Event Stream, and Datastore Support
+
+   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.
+
+   A NETCONF publisher supporting event stream subscription via
+   [RFC8639] MUST support the "NETCONF" event stream identified in that
+   document.
+
+5.  NETCONF Connectivity and Dynamic Subscriptions
+
+   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.
+
+   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.
+
+
+
+
+
+Voit, et al.                 Standards Track                    [Page 4]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+6.  Notification Messages
+
+   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.
+
+   For dynamic subscriptions, all notification messages MUST use the
+   NETCONF transport session used by the "establish-subscription" RPC.
+
+7.  Dynamic Subscriptions and RPC Error Responses
+
+   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:
+
+   o  An "error-type" node of "application".
+
+   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:
+
+         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:
+
+         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
+
+
+
+Voit, et al.                 Standards Track                    [Page 5]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+   o  An "error-severity" of "error" (this MAY be included).
+
+   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:
+
+         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:
+
+      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
+
+      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.
+
+
+
+
+Voit, et al.                 Standards Track                    [Page 6]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+8.  Security Considerations
+
+   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.
+
+9.  IANA Considerations
+
+   This document has no IANA actions.
+
+10.  References
+
+10.1.  Normative References
+
+   [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>.
+
+   [RFC5277]  Chisholm, S. and H. Trevino, "NETCONF Event
+              Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
+              <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>.
+
+   [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>.
+
+   [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>.
+
+
+
+
+
+
+Voit, et al.                 Standards Track                    [Page 7]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+   [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>.
+
+   [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>.
+
+10.2.  Informative References
+
+   [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>.
+
+   [XPATH]    Clark, J. and S. DeRose, "XML Path Language (XPath)
+              Version 1.0", November 1999,
+              <https://www.w3.org/TR/1999/REC-xpath-19991116>.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al.                 Standards Track                    [Page 8]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+Appendix A.  Examples
+
+   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.
+
+A.1.  Event Stream Discovery
+
+   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.
+
+   The following XML example [W3C.REC-xml-20081126] illustrates the
+   retrieval of the list of available event streams:
+
+<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
+
+   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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al.                 Standards Track                    [Page 9]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+A.2.  Dynamic Subscriptions
+
+A.2.1.  Establishing Dynamic Subscriptions
+
+   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.
+
+              +------------+                 +-----------+
+              | 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
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al.                 Standards Track                   [Page 10]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+   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):
+
+<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)
+
+   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):
+
+  <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)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al.                 Standards Track                   [Page 11]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+   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:
+
+   <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"
+
+   The subscriber can use this information in future attempts to
+   establish a subscription.
+
+A.2.2.  Modifying Dynamic Subscriptions
+
+   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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al.                 Standards Track                   [Page 12]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+              +------------+                 +-----------+
+              | 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
+
+   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.
+
+<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)
+
+
+
+
+
+
+Voit, et al.                 Standards Track                   [Page 13]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+   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:
+
+   <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)
+
+A.2.3.  Deleting Dynamic Subscriptions
+
+   Figure 9 demonstrates the deletion of a subscription.  This
+   subscription may have been to either a stream or a datastore.
+
+  <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"
+
+
+
+
+
+
+
+
+Voit, et al.                 Standards Track                   [Page 14]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+   If the NETCONF publisher can satisfy the request, the publisher
+   returns a reply indicating success.
+
+   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:
+
+   <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"
+
+A.3.  Subscription State Notifications
+
+   A publisher will send subscription state notifications for dynamic
+   subscriptions according to the definitions in [RFC8639].
+
+A.3.1.  "subscription-modified"
+
+   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:
+
+<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
+
+
+
+
+Voit, et al.                 Standards Track                   [Page 15]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+A.3.2.  "subscription-resumed" and "replay-complete"
+
+   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>
+
+              Figure 12: "subscription-resumed" Notification
+
+   The "replay-complete" is virtually identical, with "subscription-
+   resumed" simply being replaced by "replay-complete".
+
+A.3.3.  "subscription-terminated" and "subscription-suspended"
+
+   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>
+
+   Figure 13: "subscription-terminated" Subscription State Notification
+
+   The "subscription-suspended" is virtually identical, with
+   "subscription-terminated" simply being replaced by "subscription-
+   suspended".
+
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al.                 Standards Track                   [Page 16]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+A.4.  Filter Examples
+
+   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:
+
+  <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
+
+   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:
+
+ <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
+
+   For more examples of XPath filters, see [XPATH].
+
+
+
+
+
+
+
+
+
+Voit, et al.                 Standards Track                   [Page 17]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+   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:
+
+ <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
+
+   For more examples of subtree filters, see [RFC6241], Section 6.4.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al.                 Standards Track                   [Page 18]
+
+RFC 8640                  NETCONF Notifications           September 2019
+
+
+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
+
+   Email: evoit@cisco.com
+
+
+   Alexander Clemm
+   Futurewei
+
+   Email: ludwig@clemm.org
+
+
+   Alberto Gonzalez Prieto
+   Microsoft
+
+   Email: alberto.gonzalez@microsoft.com
+
+
+   Einar Nilsen-Nygaard
+   Cisco Systems
+
+   Email: einarnn@cisco.com
+
+
+   Ambika Prasad Tripathy
+   Cisco Systems
+
+   Email: ambtripa@cisco.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+Voit, et al.                 Standards Track                   [Page 19]
+