diff options
Diffstat (limited to 'doc/rfc/rfc8650.txt')
| -rw-r--r-- | doc/rfc/rfc8650.txt | 1135 |
1 files changed, 1135 insertions, 0 deletions
diff --git a/doc/rfc/rfc8650.txt b/doc/rfc/rfc8650.txt new file mode 100644 index 0000000..3b92fca --- /dev/null +++ b/doc/rfc/rfc8650.txt @@ -0,0 +1,1135 @@ + + + + +Internet Engineering Task Force (IETF) E. Voit +Request for Comments: 8650 R. Rahman +Category: Standards Track E. Nilsen-Nygaard +ISSN: 2070-1721 Cisco Systems + A. Clemm + Futurewei + A. Bierman + YumaWorks + November 2019 + + + Dynamic Subscription to YANG Events and Datastores over RESTCONF + +Abstract + + This document provides a RESTCONF 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/rfc8650. + +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. + +Table of Contents + + 1. Introduction + 2. Terminology + 3. Dynamic Subscriptions + 3.1. Transport Connectivity + 3.2. Discovery + 3.3. RESTCONF RPCs and HTTP Status Codes + 3.4. Call Flow for Server-Sent Events + 4. QoS Treatment + 5. Notification Messages + 6. YANG Tree + 7. YANG Module + 8. IANA Considerations + 9. Security Considerations + 10. References + 10.1. Normative References + 10.2. Informative References + Appendix A. Examples + A.1. Dynamic Subscriptions + A.1.1. Establishing Dynamic Subscriptions + A.1.2. Modifying Dynamic Subscriptions + A.1.3. Deleting Dynamic Subscriptions + A.2. Subscription State Notifications + A.2.1. "subscription-modified" + A.2.2. "subscription-completed", "subscription-resumed", and + "replay-completed" + A.2.3. "subscription-terminated" and "subscription-suspended" + A.3. Filter Example + Acknowledgments + Authors' Addresses + +1. Introduction + + Mechanisms to support event subscription and YANG-Push are defined in + [RFC8639]. Enhancements to [RFC8639] that enable YANG datastore + subscription and YANG-Push are defined in [RFC8641]. This document + provides a transport specification for dynamic subscriptions over + RESTCONF [RFC8040]. Requirements for these mechanisms are captured + in [RFC7923]. + + The streaming of notifications that encapsulate the resulting + information push is done via the mechanism described in Section 6.3 + of [RFC8040]. + +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 use the definitions from [RFC8639]: dynamic + subscription, event stream, notification message, publisher, + receiver, subscriber, and subscription. + + Other terms reused include datastore, which is defined in [RFC8342], + and HTTP/2 stream, which maps to the definition of "stream" within + [RFC7540], Section 2. + +3. Dynamic Subscriptions + + This section provides specifics on how to establish and maintain + dynamic subscriptions over RESTCONF [RFC8040]. Subscribing to event + streams is accomplished in this way via RPCs defined within + [RFC8639], Section 2.4. The RPCs are done via RESTCONF POSTs. YANG + datastore subscription is accomplished via augmentations to [RFC8639] + as described within [RFC8641], Section 4.4. + + As described in Section 6.3 of [RFC8040], a GET needs to be performed + on a specific URI on the publisher. Subscribers cannot predetermine + the URI against which a subscription might exist on a publisher, as + the URI will only exist after the "establish-subscription" RPC has + been accepted. Therefore, the POST for the "establish-subscription" + RPC replaces the GET request for the "location" leaf that is used in + [RFC8040] to obtain the URI. The subscription 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 done in order to start the + flow of notification messages back to the subscriber. As specified + in Section 2.4.1 of [RFC8639], a subscription does not move to the + active state until the GET is received. + +3.1. Transport Connectivity + + For a dynamic subscription, when a RESTCONF session doesn't already + exist, a new RESTCONF session is initiated from the subscriber. + + As stated in Section 2.1 of [RFC8040], a subscriber MUST establish + the HTTP session over TLS [RFC8446] in order to secure the content in + transit. + + Without the involvement of additional protocols, HTTP sessions by + themselves do not support quick recognition of the loss of the + communication path to the publisher. Where quick recognition of the + loss of a publisher is required, a subscriber SHOULD use a TLS + heartbeat [RFC6520], just from subscriber to publisher, to track HTTP + session continuity. + + Loss of the heartbeat MUST 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 Section 3.4. + +3.2. Discovery + + Subscribers can learn which event streams a RESTCONF server supports + by querying the "streams" container of ietf-subscribed- + notifications.yang in [RFC8639]. Support for the "streams" container + of ietf-restconf-monitoring.yang in [RFC8040] is not required. In + the case when the RESTCONF binding specified by this document is used + to convey the "streams" container from ietf-restconf-monitoring.yang + (i.e., that feature is supported), any event streams contained + therein are also expected to be present in the "streams" container of + ietf-restconf-monitoring.yang. + + Subscribers can learn which datastores a RESTCONF server supports by + following Section 2 of [RFC8527]. + +3.3. RESTCONF RPCs and HTTP Status Codes + + Specific HTTP response codes as defined in Section 6 of [RFC7231] + will indicate the result of RESTCONF RPC requests with the publisher. + An HTTP status code of 200 is the proper response to any successful + RPC defined within [RFC8639] or [RFC8641]. + + If a publisher fails to serve the RPC request for one of the reasons + indicated in Section 2.4.6 of [RFC8639] or Appendix A of [RFC8641], + this will be indicated by an appropriate error code, as shown below, + transported in the HTTP response. + + When an HTTP error code is returned, the RPC reply MUST include an + <rpc-error> element per Section 7.1 of [RFC8040] with the following + parameter values: + + * an "error-type" node of "application". + + * an "error-tag" node whose value is a string that corresponds to an + identity associated with the error. This "error-tag" will come + from one of two places and will correspond to the error identities + either within Section 2.4.6 of [RFC8639] for general subscription + errors (Table 1) or within Appendix A.1 of [RFC8641] for + subscription errors specific to YANG datastores (Table 2). + + * an "error-app-tag" node whose value is a string that corresponds + to an identity associated with the error, as defined in + Section 2.4.6 of [RFC8639] for general subscriptions or + Appendix A.1 of [RFC8641] for subscription errors specific to YANG + datastores. The tag to use depends on the RPC for which the error + occurred. Viable errors for different RPCs are found in Table 3. + + +------------------------+-------------------------+-----------+ + | Error identity | Uses "error-tag" | HTTP code | + +========================+=========================+===========+ + | dscp-unavailable | invalid-value | 400 | + +------------------------+-------------------------+-----------+ + | encoding-unsupported | invalid-value | 400 | + +------------------------+-------------------------+-----------+ + | filter-unsupported | invalid-value | 400 | + +------------------------+-------------------------+-----------+ + | insufficient-resources | resource-denied | 409 | + +------------------------+-------------------------+-----------+ + | no-such-subscription | invalid-value | 404 | + +------------------------+-------------------------+-----------+ + | replay-unsupported | operation-not-supported | 501 | + +------------------------+-------------------------+-----------+ + + Table 1: General Subscription Error Identities and + Associated "error-tag" Use + + +-----------------------------+-------------------------+-----------+ + | Error identity | Uses "error-tag" | HTTP | + | | | code | + +=============================+=========================+===========+ + | cant-include | 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 | + +-----------------------------+-------------------------+-----------+ + + Table 2: Datastore-Specific Error Identities and Associated + "error-tag" Use + + +------------------------+--------------------------------+ + | 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 | + +------------------------+--------------------------------+ + + Table 3: RPC Errors and Associated Error Identities + + Each error identity will be inserted as the "error-app-tag" using + JSON encoding following the form <modulename>:<identityname>. An + example of such a valid encoding would be "ietf-subscribed- + notifications:no-such-subscription". + + 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 4 and 5 show the yang-data structures that may be returned. + + +--------------+---------------------------------------------+ + | Target: | Return hints in yang-data structure | + +==============+=============================================+ + | event stream | establish-subscription-stream-error-info | + +--------------+---------------------------------------------+ + | datastore | establish-subscription-datastore-error-info | + +--------------+---------------------------------------------+ + + Table 4: Optional "error-info" Node Hints for an + "establish-subscription" Request + + +--------------+------------------------------------------+ + | Target: | Returns hints in yang-data structure | + +==============+==========================================+ + | event stream | modify-subscription-stream-error-info | + +--------------+------------------------------------------+ + | datastore | modify-subscription-datastore-error-info | + +--------------+------------------------------------------+ + + Table 5: Optional "error-info" Node Hints for an + "modify-subscription" Request + + The yang-data included within "error-info" SHOULD NOT include the + optional leaf "reason", as such a leaf would be redundant with + information that is already placed within the "error-app-tag". + + In case of an <rpc-error> as a result of a "delete-subscription", a + "kill-subscription", or a "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 parameters + need to be provided. + + Note that "error-path" [RFC8040] does not need to be included with + the <rpc-error> element, as subscription errors are generally + associated with the choice of RPC input parameters. + +3.4. Call Flow for Server-Sent Events + + The call flow for Server-Sent Events (SSE) is defined in Figure 1. + The logical connections denoted by (a) and (b) can be a TCP + connection or an HTTP/2 stream (if HTTP/2 is used, multiple HTTP/2 + streams can be carried in one TCP connection). Requests to RPCs as + defined in [RFC8639] or [RFC8641] are sent on a connection indicated + by (a). A successful "establish-subscription" will result in an RPC + response returned with both a subscription identifier that uniquely + identifies a subscription, as well as a URI that uniquely identifies + the location of subscription on the publisher (b). This URI is + defined via the "uri" leaf in the data model in Section 7. + + An HTTP GET is then sent on a separate logical connection (b) to the + URI on the publisher. This signals the publisher to initiate the + flow of notification messages that are sent in SSE [W3C-20150203] as + a response to the GET. There cannot be two or more simultaneous GET + requests on a subscription URI: any GET request received while there + is a current GET request on the same URI MUST be rejected with HTTP + error code 409. + + As described in Section 6.4 of [RFC8040], RESTCONF servers SHOULD NOT + send the "event" or "id" fields in the SSE event notifications. + + +--------------+ +--------------+ + | Subscriber | | Publisher | + | | | | + | Logical | | Logical | + | Connection | | Connection | + | (a) (b) | | (a) (b) | + +--------------+ +--------------+ + | RESTCONF POST (RPC:establish-subscription) | + |--------------------------------------------->| + | HTTP 200 OK (ID,URI)| + |<---------------------------------------------| + | |HTTP GET (URI) | + | |--------------------------------------------->| + | | HTTP 200 OK| + | |<---------------------------------------------| + | | SSE (notif-message)| + | |<---------------------------------------------| + | RESTCONF POST (RPC:modify-subscription) | | + |--------------------------------------------->| | + | | HTTP 200 OK| | + |<---------------------------------------------| | + | | SSE (subscription-modified)| + | |<------------------------------------------(c)| + | | SSE (notif-message)| + | |<---------------------------------------------| + | RESTCONF POST (RPC:delete-subscription) | | + |--------------------------------------------->| | + | | HTTP 200 OK| | + |<---------------------------------------------| | + | | | | + | | | | + (a) (b) (a) (b) + + Figure 1: Dynamic Subscriptions with Server-Sent Events + + Additional requirements for dynamic subscriptions over SSE include: + + * A publisher MUST return all subscription state notifications in a + separate SSE message used by the subscription to which the state + change refers. + + * Subscription RPCs MUST NOT use the connection currently providing + notification messages for that subscription. + + * In addition to an RPC response for a "modify-subscription" RPC + traveling over (a), a "subscription-modified" state change + notification MUST be sent within (b). This allows the receiver to + know exactly when, within the stream of events, the new terms of + the subscription have been applied to the notification messages. + See arrow (c). + + * In addition to any required access permissions (e.g., Network + Configuration Access Control Model (NACM)), the RPCs "modify- + subscription", "resync-subscription", and "delete-subscription" + SHOULD only be allowed by the same RESTCONF username [RFC8040] + that invoked "establish-subscription". Such a restriction + generally serves to preserve users' privacy, but exceptions might + be made for administrators that may need to modify or delete other + users' subscriptions. + + * The "kill-subscription" RPC can be invoked by any RESTCONF + username with the required administrative permissions. + + A publisher MUST terminate a subscription in the following cases: + + * Receipt of a "delete-subscription" or a "kill-subscription" RPC + for that subscription + + * Loss of TLS heartbeat + + A publisher MAY terminate a subscription at any time as stated in + Section 1.3 of [RFC8639]. + +4. QoS Treatment + + Qos treatment for event streams is described in Section 2.3 of + [RFC8639]. In addition, if HTTP/2 is used, the publisher MUST: + + * Take the "weighting" leaf node in [RFC8639] and copy it into the + HTTP/2 stream weight, Section 5.3 of [RFC7540], and + + * Take any existing subscription "dependency", as specified by the + "dependency" leaf node in [RFC8639], and use the HTTP/2 stream for + the parent subscription as the HTTP/2 stream dependency (as + described in Section 5.3.1 of [RFC7540]) of the dependent + subscription. + + * Set the exclusive flag (Section 5.3.1 of [RFC7540]) to 0. + + For dynamic subscriptions with the same Differentiated Services Code + Point (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). Conversely, a subscriber cannot use a common + HTTP/2 session for subscriptions with different DSCP values. + +5. Notification Messages + + Notification messages transported over RESTCONF will be encoded + according to [RFC8040], Section 6.4. + +6. YANG Tree + + The YANG module defined in Section 7 has one leaf that augments three + nodes of [RFC8639]. + + module: ietf-restconf-subscribed-notifications + augment /sn:establish-subscription/sn:output: + +--ro uri? inet:uri + augment /sn:subscriptions/sn:subscription: + +--ro uri? inet:uri + augment /sn:subscription-modified: + +--ro uri? inet:uri + +7. YANG Module + + This module references [RFC8639]. + + <CODE BEGINS> + file "ietf-restconf-subscribed-notifications@2019-11-17.yang" + module ietf-restconf-subscribed-notifications { + yang-version 1.1; + namespace "urn:ietf:params:xml:ns:yang:" + + "ietf-restconf-subscribed-notifications"; + prefix rsn; + + import ietf-subscribed-notifications { + prefix sn; + } + import ietf-inet-types { + prefix inet; + } + + organization + "IETF NETCONF (Network Configuration) Working Group"; + contact + "WG Web: <https://datatracker.ietf.org/wg/netconf/> + WG List: <mailto:netconf@ietf.org> + + Editor: Eric Voit + <mailto:evoit@cisco.com> + + Editor: Alexander Clemm + <mailto:ludwig@clemm.org> + + Editor: Reshad Rahman + <mailto:rrahman@cisco.com>"; + description + "Defines RESTCONF as a supported transport for subscribed + event notifications. + + Copyright (c) 2019 IETF Trust and the persons identified + as authors of the code. All rights reserved. + + Redistribution and use in source and binary forms, with or + without modification, is permitted pursuant to, and subject to + the license terms contained in, the Simplified BSD License set + forth in Section 4.c of the IETF Trust's Legal Provisions + Relating to IETF Documents + (https://trustee.ietf.org/license-info). + + This version of this YANG module is part of RFC 8650; see the + RFC itself for full legal notices."; + + revision 2019-11-17 { + description + "Initial version"; + reference + "RFC 8650: Dynamic Subscription to YANG Events and Datastores + over RESTCONF"; + } + + grouping uri { + description + "Provides a reusable description of a URI."; + leaf uri { + type inet:uri; + config false; + description + "Location of a subscription-specific URI on the publisher."; + } + } + + augment "/sn:establish-subscription/sn:output" { + description + "This augmentation allows RESTCONF-specific parameters for a + response to a publisher's subscription request."; + uses uri; + } + + augment "/sn:subscriptions/sn:subscription" { + description + "This augmentation allows RESTCONF-specific parameters to be + exposed for a subscription."; + uses uri; + } + + augment "/sn:subscription-modified" { + description + "This augmentation allows RESTCONF-specific parameters to be + included as part of the notification that a subscription has + been modified."; + uses uri; + } + } + <CODE ENDS> + +8. IANA Considerations + + This document registers the following namespace URI in the "ns" + subregistry of the "IETF XML Registry" [RFC3688]: + + URI: + urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications + + Registrant Contact: The IESG. + + XML: N/A; the requested URI is an XML namespace. + + This document registers the following YANG module in the "YANG Module + Names" registry [RFC6020]: + + Name: ietf-restconf-subscribed-notifications + + Namespace: + urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications + + Prefix: rsn + + Reference: RFC 8650 + +9. Security Considerations + + The YANG module specified in this document defines a schema for data + that is designed to be accessed via network management transports + such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF + layer is the secure transport layer, and the mandatory-to-implement + secure transport is Secure Shell (SSH) [RFC6242]. The lowest + RESTCONF layer is HTTPS, and the mandatory-to-implement secure + transport is TLS [RFC8446]. + + The Network Configuration Access Control Model (NACM) [RFC8341] + provides the means to restrict access for particular NETCONF or + RESTCONF users to a preconfigured subset of all available NETCONF or + RESTCONF protocol operations and content. + + 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 control read access (e.g., via get, get-config, + or notification) to this data node. These are the subtrees and data + nodes and their sensitivity/vulnerability: + + Container: "/subscriptions" + + * "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 permissions, i.e., the same RESTCONF [RFC8040] + user credentials that invoked the corresponding "establish- + subscription", has the ability to access this resource. + + The subscription URI is implementation specific and is encrypted via + the use of TLS. Therefore, even if an attacker succeeds in guessing + the subscription URI, a RESTCONF username [RFC8040] with the required + administrative permissions must be used to be able to access or + modify that subscription. It is recommended that the subscription + URI values not be easily predictable. + + The access permission considerations for the RPCs "modify- + subscription", "resync-subscription", "delete-subscription", and + "kill-subscription" are described in Section 3.4. + + If a buggy or compromised RESTCONF subscriber sends a number of + "establish-subscription" requests, then these subscriptions + accumulate and may use up system resources. In such a situation, the + publisher MAY also suspend or terminate a subset of the active + subscriptions from that RESTCONF subscriber in order to reclaim + resources and preserve normal operation for the other subscriptions. + +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>. + + [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, + DOI 10.17487/RFC3688, January 2004, + <https://www.rfc-editor.org/info/rfc3688>. + + [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for + the Network Configuration Protocol (NETCONF)", RFC 6020, + DOI 10.17487/RFC6020, October 2010, + <https://www.rfc-editor.org/info/rfc6020>. + + [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>. + + [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure + Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, + <https://www.rfc-editor.org/info/rfc6242>. + + [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport + Layer Security (TLS) and Datagram Transport Layer Security + (DTLS) Heartbeat Extension", RFC 6520, + DOI 10.17487/RFC6520, February 2012, + <https://www.rfc-editor.org/info/rfc6520>. + + [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext + Transfer Protocol Version 2 (HTTP/2)", RFC 7540, + DOI 10.17487/RFC7540, May 2015, + <https://www.rfc-editor.org/info/rfc7540>. + + [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF + Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, + <https://www.rfc-editor.org/info/rfc8040>. + + [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>. + + [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration + Access Control Model", STD 91, RFC 8341, + DOI 10.17487/RFC8341, March 2018, + <https://www.rfc-editor.org/info/rfc8341>. + + [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., + and R. Wilton, "Network Management Datastore Architecture + (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, + <https://www.rfc-editor.org/info/rfc8342>. + + [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol + Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, + <https://www.rfc-editor.org/info/rfc8446>. + + [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>. + + [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-20150203] + Hickson, I., "Server-Sent Events", W3C Recommendation, 3 + February 2015, + <https://www.w3.org/TR/2015/REC-eventsource-20150203/>. + Latest version available at <https://www.w3.org/TR/ + eventsource/>. + +10.2. Informative References + + [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer + Protocol (HTTP/1.1): Semantics and Content", RFC 7231, + DOI 10.17487/RFC7231, June 2014, + <https://www.rfc-editor.org/info/rfc7231>. + + [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements + for Subscription to YANG Datastores", RFC 7923, + DOI 10.17487/RFC7923, June 2016, + <https://www.rfc-editor.org/info/rfc7923>. + + [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG", + RFC 7951, DOI 10.17487/RFC7951, August 2016, + <https://www.rfc-editor.org/info/rfc7951>. + + [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>. + + [RFC8527] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., + and R. Wilton, "RESTCONF Extensions to Support the Network + Management Datastore Architecture", RFC 8527, + DOI 10.17487/RFC8527, March 2019, + <https://www.rfc-editor.org/info/rfc8527>. + + [RFC8640] Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard, + E., and A. Tripathy, "Dynamic Subscription to YANG Events + and Datastores over NETCONF", RFC 8640, + DOI 10.17487/RFC8640, September 2019, + <https://www.rfc-editor.org/info/rfc8640>. + + [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) + Version 1.0", W3C Recommendation, 16 November 1999, + <http://www.w3.org/TR/1999/REC-xpath-19991116>. Latest + version available at <https://www.w3.org/TR/ xpath/>. + +Appendix A. Examples + + This section is non-normative. To allow easy comparison, this + section mirrors the functional examples shown with NETCONF over XML + within [RFC8640]. In addition, HTTP/2 vs HTTP/1.1 headers are not + shown as the contents of the JSON encoded objects are identical + within. + + The subscription URI values used in the examples in this section are + purely illustrative, and are not indicative of the expected usage + that is described in Section 9. + + The DSCP values are only for example purposes and are all indicated + in decimal since the encoding is JSON [RFC7951]. + +A.1. Dynamic Subscriptions + +A.1.1. Establishing Dynamic Subscriptions + + The following figure shows two successful "establish-subscription" + RPC requests as per [RFC8639]. The first request is given a + subscription identifier of 22, and the second, an identifier of 23. + + +------------+ +-----------+ + | Subscriber | | Publisher | + +------------+ +-----------+ + | | + |establish-subscription | + |------------------------------>| (a) + | HTTP 200 OK, id#22, URI#1 | + |<------------------------------| (b) + |GET (URI#1) | + |------------------------------>| (c) + | HTTP 200 OK,notif-mesg (id#22)| + |<------------------------------| + | | + | | + |establish-subscription | + |------------------------------>| + | HTTP 200 OK, id#23, URI#2| + |<------------------------------| + |GET (URI#2) | + |------------------------------>| + | | + | | + | notif-mesg (id#22)| + |<------------------------------| + | HTTP 200 OK,notif-mesg (id#23)| + |<------------------------------| + | | + + Figure 2: Multiple Subscriptions over RESTCONF/HTTP + + To provide examples of the information being transported, example + messages for interactions in Figure 2 are detailed below: + + POST /restconf/operations + /ietf-subscribed-notifications:establish-subscription + + { + "ietf-subscribed-notifications:input": { + "stream-xpath-filter": "/example-module:foo/", + "stream": "NETCONF", + "dscp": 10 + } + } + + Figure 3: "establish-subscription" Request (a) + + As the publisher was able to fully satisfy the request, the publisher + sends the subscription identifier of the accepted subscription and + the URI: + + HTTP status code - 200 + + { + "id": 22, + "uri": "https://example.com/restconf/subscriptions/22" + } + + Figure 4: "establish-subscription" Success (b) + + Upon receipt of the successful response, the subscriber does a GET to + the provided URI to start the flow of notification messages. When + the publisher receives this, the subscription is moved to the active + state (c). + + GET /restconf/subscriptions/22 + + Figure 5: "establish-subscription" Subsequent POST + + While not shown in Figure 2, if the 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: + + HTTP status code - 400 + + { "ietf-restconf:errors" : { + "error" : [ + { + "error-type": "application", + "error-tag": "invalid-value", + "error-severity": "error", + "error-app-tag": + "ietf-subscribed-notifications:dscp-unavailable" + } + ] + } + } + + Figure 6: An Unsuccessful "establish-subscription" + + The subscriber can use this information in future attempts to + establish a subscription. + +A.1.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. + + +------------+ +-----------+ + | Subscriber | | Publisher | + +------------+ +-----------+ + | | + | notification message (id#23)| + |<-----------------------------| + | | + |modify-subscription (id#23) | + |----------------------------->| (d) + | HTTP 400 error (with hint)| + |<-----------------------------| (e) + | | + |modify-subscription (id#23) | + |----------------------------->| + | HTTP 200 OK | + |<-----------------------------| + | | + | notif-mesg (id#23)| + |<-----------------------------| + | | + + Figure 7: Interaction Model for Successful Subscription Modification + + If the subscription being modified in Figure 7 is a datastore + subscription as per [RFC8641], the modification request made in (d) + may look like that shown in Figure 8. As can be seen, the + modifications being attempted are the application of a new XML Path + Language (XPath) filter as well as the setting of a new periodic time + interval. + + POST /restconf/operations + /ietf-subscribed-notifications:modify-subscription + + { + "ietf-subscribed-notifications:input": { + "id": 23, + "ietf-yang-push:datastore-xpath-filter": + "/example-module:foo/example-module:bar", + "ietf-yang-push:periodic": { + "ietf-yang-push:period": 500 + } + } + } + + Figure 8: Subscription Modification Request (c) + + If the publisher can satisfy both changes, the publisher sends a + positive result for the RPC. If the publisher cannot satisfy either + of the proposed changes, the publisher sends an RPC error response + (e). The following is an example RPC error response for (e) that + includes a hint. This hint is an alternative time period value that + might have resulted in a successful modification: + + 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 + } + } + ] + } + } + + Figure 9: "modify-subscription" Failure with Hint (e) + +A.1.3. Deleting Dynamic Subscriptions + + The following demonstrates deleting a subscription. This + subscription may have been to either a stream or a datastore. + + POST /restconf/operations + /ietf-subscribed-notifications:delete-subscription + + { + "delete-subscription": { + "id": "22" + } + } + + Figure 10: "delete-subscription" Request + + If the publisher can satisfy the request, the publisher replies with + success to the RPC request. + + If the publisher cannot satisfy the request, the publisher sends an + <rpc-error> element indicating the modification didn't work. + Figure 11 shows a valid response for an existing valid subscription + identifier, but that subscription identifier was created on a + different transport session: + + HTTP status code - 404 + + { + "ietf-restconf:errors" : { + "error" : [ + "error-type": "application", + "error-tag": "invalid-value", + "error-severity": "error", + "error-app-tag": + "ietf-subscribed-notifications:no-such-subscription" + ] + } + } + + Figure 11: Unsuccessful "delete-subscription" + +A.2. Subscription State Notifications + + A publisher will send subscription state notifications according to + the definitions within [RFC8639]. + +A.2.1. "subscription-modified" + + A "subscription-modified" encoded in JSON would look like: + + { + "ietf-restconf:notification" : { + "eventTime": "2007-09-01T10:00:00Z", + "ietf-subscribed-notifications:subscription-modified": { + "id": 39, + "uri": "https://example.com/restconf/subscriptions/22" + "stream-xpath-filter": "/example-module:foo", + "stream": { + "ietf-netconf-subscribed-notifications" : "NETCONF" + } + } + } + } + + Figure 12: "subscription-modified" Subscription State Notification + +A.2.2. "subscription-completed", "subscription-resumed", and "replay- + completed" + + A "subscription-completed" notification would look like: + + { + "ietf-restconf:notification" : { + "eventTime": "2007-09-01T10:00:00Z", + "ietf-subscribed-notifications:subscription-completed": { + "id": 39, + } + } + } + + Figure 13: "subscription-completed" Notification in JSON + + The "subscription-resumed" and "replay-complete" are virtually + identical, with "subscription-completed" simply being replaced by + "subscription-resumed" and "replay-complete". + +A.2.3. "subscription-terminated" and "subscription-suspended" + + A "subscription-terminated" would look like: + + { + "ietf-restconf:notification" : { + "eventTime": "2007-09-01T10:00:00Z", + "ietf-subscribed-notifications:subscription-terminated": { + "id": 39, + "error-id": "suspension-timeout" + } + } + } + + Figure 14: "subscription-terminated" Subscription State Notification + + The "subscription-suspended" is virtually identical, with + "subscription-terminated" simply being replaced by "subscription- + suspended". + +A.3. Filter Example + + This section provides an example that illustrates the method of + filtering event record contents. The example is based on the YANG + notification "vrrp-protocol-error-event" as defined per the ietf- + vrrp.yang module within [RFC8347]. Event records based on this + specification that are generated by the publisher might appear as: + + data: { + data: "ietf-restconf:notification" : { + data: "eventTime" : "2018-09-14T08:22:33.44Z", + data: "ietf-vrrp:vrrp-protocol-error-event" : { + data: "protocol-error-reason" : "checksum-error" + data: } + data: } + data: } + + Figure 15: RFC 8347 (VRRP) - Example Notification + + Suppose 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 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: + + POST /restconf/operations + /ietf-subscribed-notifications:establish-subscription + { + "ietf-subscribed-notifications:input": { + "stream": "NETCONF", + "stream-xpath-filter": + "/ietf-vrrp:vrrp-protocol-error-event[ + protocol-error-reason='checksum-error']/", + } + } + + Figure 16: Establishing a Subscription Error Reason via XPath + + For more examples of XPath filters, see [XPATH]. + + Suppose the "establish-subscription" in Figure 16 was accepted. And + suppose later a subscriber decided they wanted to broaden this + subscription cover to 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: + + POST /restconf/operations + /ietf-subscribed-notifications:modify-subscription + { + "ietf-subscribed-notifications:input": { + "stream": "NETCONF", + "stream-subtree-filter": { + "/ietf-vrrp:vrrp-protocol-error-event" : {} + } + } + } + + Figure 17: Example "modify-subscription" RPC + + For more examples of subtree filters, see [RFC6241], Section 6.4. + +Acknowledgments + + We wish to acknowledge the helpful contributions, comments, and + suggestions that were received from Ambika Prasad Tripathy, Alberto + Gonzalez Prieto, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent + Watsen, Michael Scharf, Guangying Zheng, Martin Bjorklund, Qin Wu, + and Robert Wilton. + +Authors' Addresses + + Eric Voit + Cisco Systems + + Email: evoit@cisco.com + + + Reshad Rahman + Cisco Systems + + Email: rrahman@cisco.com + + + Einar Nilsen-Nygaard + Cisco Systems + + Email: einarnn@cisco.com + + + Alexander Clemm + Futurewei + + Email: ludwig@clemm.org + + + Andy Bierman + YumaWorks + + Email: andy@yumaworks.com |