Dynamic Subscription to YANG Events and Datastores over RESTCONF
Extracted elements (29)
Subscribers cannot predetermine the subscription URI before issuing 'establish-subscription' because the URI only exists after the RPC is accepted. Therefore, the POST for 'establish-subscription' replaces the GET for the 'location' leaf used in RFC 8040, and the URI is returned in the RPC response.
Subscription RPCs (modify, resync, delete) are restricted to the same RESTCONF username that invoked 'establish-subscription' to preserve user privacy, with exceptions allowed for administrators needing to manage other users' subscriptions.
For dynamic subscriptions with the same DSCP value to a specific publisher, it is recommended that the subscriber sends all URI GET requests on a common HTTP/2 session; a subscriber cannot use a common HTTP/2 session for subscriptions with different DSCP values.
Subscribers querying event streams should use the 'streams' container of ietf-subscribed-notifications.yang (RFC 8639); support for the 'streams' container of ietf-restconf-monitoring.yang (RFC 8040) is not required, though when supported, event streams therein must also appear in the RFC 8639 container.
A publisher MUST return all subscription state notifications in a separate SSE message used by the subscription to which the state change refers.
A publisher MUST terminate a subscription upon receipt of a 'delete-subscription' or 'kill-subscription' RPC for that subscription, or upon loss of TLS heartbeat.
A subscriber MUST establish the HTTP session over TLS (RFC 8446) in order to secure the content in transit.
An HTTP status code of 200 is the proper response to any successful RPC defined within RFC 8639 or RFC 8641. When an HTTP error code is returned, the RPC reply MUST include an <rpc-error> element per Section 7.1 of RFC 8040 with error-type 'application', an error-tag, and an error-app-tag.
Any GET request received while there is a current GET request on the same subscription URI MUST be rejected with HTTP error code 409, preventing two or more simultaneous GET requests on a subscription URI.
If HTTP/2 is used, the publisher MUST copy the 'weighting' leaf node into the HTTP/2 stream weight, map subscription 'dependency' to HTTP/2 stream dependency, and set the exclusive flag to 0.
In addition to an RPC response for a 'modify-subscription' RPC traveling over connection (a), a 'subscription-modified' state change notification MUST be sent within connection (b), so the receiver knows exactly when within the stream of events the new subscription terms have been applied.
Loss of the TLS heartbeat MUST result in the teardown of any subscription-related TCP sessions between those endpoints.
Subscription RPCs MUST NOT use the connection currently providing notification messages for that subscription.
The RPCs 'modify-subscription', 'resync-subscription', and 'delete-subscription' SHOULD only be allowed by the same RESTCONF username that invoked 'establish-subscription', to preserve users' privacy.
The yang-data included within 'error-info' SHOULD NOT include the optional leaf 'reason', as such a leaf would be redundant with information already placed within the 'error-app-tag'.
Where quick recognition of the loss of a publisher is required, a subscriber SHOULD use a TLS heartbeat (RFC 6520), just from subscriber to publisher, to track HTTP session continuity.
Dynamic subscriptions are established via RESTCONF POST to the 'establish-subscription' RPC. The response includes a subscription identifier and a URI uniquely identifying the subscription location on the publisher. A subsequent GET to this URI starts the flow of notification messages.
Error identities are inserted as 'error-app-tag' using JSON encoding in the form '<modulename>:<identityname>', for example 'ietf-subscribed-notifications:no-such-subscription'.
For 'establish-subscription' or 'modify-subscription' errors, an optional 'error-info' node may contain hints: for event streams, 'establish-subscription-stream-error-info' or 'modify-subscription-stream-error-info'; for datastores, the corresponding datastore error info structures.
The 'uri' leaf (type inet:uri, config false) represents the location of a subscription-specific URI on the publisher and is returned in the 'establish-subscription' output and included in the 'subscription-modified' notification.
The YANG module 'ietf-restconf-subscribed-notifications' augments three nodes of RFC 8639: the output of 'establish-subscription', the 'subscriptions/subscription' list, and the 'subscription-modified' notification — each with an optional 'uri' leaf of type inet:uri.
This document registers the namespace URI 'urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications' in the 'ns' subregistry of the IETF XML Registry (RFC 3688).
This document registers the YANG module 'ietf-restconf-subscribed-notifications' (prefix: rsn) in the 'YANG Module Names' registry (RFC 6020), referencing RFC 8650.
If a buggy or compromised RESTCONF subscriber sends many 'establish-subscription' requests, subscriptions may accumulate and exhaust system resources; the publisher MAY suspend or terminate a subset of active subscriptions from that subscriber to reclaim resources.
The subscription URI is encrypted via TLS, but it is also recommended that subscription URI values not be easily predictable, as an attacker who guesses a URI still requires valid RESTCONF credentials to access or modify the subscription.
The 'uri' leaf in '/subscriptions' reveals where subscribed resources are located on a publisher; access control must ensure only the RESTCONF user with credentials matching those that invoked 'establish-subscription' can access this resource.
A subscription does not move to the active state until the subscriber sends an HTTP GET to the subscription URI returned by 'establish-subscription'. The subscription is terminated upon receipt of 'delete-subscription' or 'kill-subscription' RPC, or loss of TLS heartbeat.
Notification messages transported over RESTCONF are encoded as Server-Sent Events (SSE) per W3C-20150203, following RFC 8040 Section 6.4. RESTCONF servers SHOULD NOT send the 'event' or 'id' fields in SSE event notifications.
RPC requests use RESTCONF POST to URIs of the form '/restconf/operations/ietf-subscribed-notifications:<rpc-name>'. The response body on success (HTTP 200) contains JSON with 'id' and 'uri' fields. Error responses use the 'ietf-restconf:errors' JSON structure.