draft-ietf-netconf-restconf-notif-03.txt   draft-ietf-netconf-restconf-notif-04.txt 
NETCONF E. Voit NETCONF E. Voit
Internet-Draft A. Tripathy Internet-Draft A. Tripathy
Intended status: Standards Track E. Nilsen-Nygaard Intended status: Standards Track E. Nilsen-Nygaard
Expires: February 5, 2018 Cisco Systems Expires: August 4, 2018 Cisco Systems
A. Clemm A. Clemm
Huawei Huawei
A. Gonzalez Prieto A. Gonzalez Prieto
VMWare VMWare
A. Bierman A. Bierman
YumaWorks YumaWorks
August 4, 2017 January 31, 2018
Restconf and HTTP Transport for Event Notifications RESTCONF and HTTP Transport for Event Notifications
draft-ietf-netconf-restconf-notif-03 draft-ietf-netconf-restconf-notif-04
Abstract Abstract
This document defines Restconf, HTTP2, and HTTP1.1 bindings for the This document defines RESTCONF, HTTP2, and HTTP1.1 bindings for the
transport of Subscription requests and corresponding push updates. transport of subscription requests and corresponding push updates.
Being subscribed may be either publisher defined event streams or Being subscribed may be either publisher defined event streams or
nodes/subtrees of YANG Datastores. nodes/subtrees of YANG Datastores.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on February 5, 2018. This Internet-Draft will expire on August 4, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3.1. Dynamic YANG Subscription with RESTCONF control . . . . . 3 3.1. Dynamic YANG Subscription with RESTCONF control . . . . . 3
3.2. Subscription Multiplexing . . . . . . . . . . . . . . . . 6 4. Mandatory JSON and datastore support . . . . . . . . . . . . 6
4. Encoded Subscription and Notification Message Examples . . . 7 5. Notification Messages . . . . . . . . . . . . . . . . . . . . 7
4.1. Restconf Subscription and Events over HTTP1.1 . . . . . . 7 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7
4.2. Event Notification over HTTP2 . . . . . . . . . . . . . . 12 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 7
5. Security Considerations . . . . . . . . . . . . . . . . . . . 12 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 7
6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 13 8.1. Normative References . . . . . . . . . . . . . . . . . . 7
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 8.2. Informative References . . . . . . . . . . . . . . . . . 8
7.1. Normative References . . . . . . . . . . . . . . . . . . 13 Appendix A. End-to-End Deployment Guidance . . . . . . . . . . . 9
7.2. Informative References . . . . . . . . . . . . . . . . . 14 A.1. Call Home . . . . . . . . . . . . . . . . . . . . . . . . 9
Appendix A. End-to-End Deployment Guidance . . . . . . . . . . . 14 A.2. TLS Heartbeat . . . . . . . . . . . . . . . . . . . . . . 9
A.1. Call Home . . . . . . . . . . . . . . . . . . . . . . . . 14 Appendix B. RESTCONF over GRPC . . . . . . . . . . . . . . . . . 9
A.2. TLS Heartbeat . . . . . . . . . . . . . . . . . . . . . . 15 Appendix C. Encoded Subscription and Notification Message
Appendix B. RESTCONF over GRPC . . . . . . . . . . . . . . . . . 15 Examples . . . . . . . . . . . . . . . . . . . . . . 10
Appendix C. Changes between revisions . . . . . . . . . . . . . 15 C.1. RESTCONF Subscription and Events over HTTP1.1 . . . . . . 10
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16 C.2. Event Notification over HTTP2 . . . . . . . . . . . . . . 14
Appendix D. Changes between revisions . . . . . . . . . . . . . 14
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15
1. Introduction 1. Introduction
Mechanisms to support Event subscription and push are defined in Mechanisms to support event subscription and push are defined in
[sn]. Enhancements to [sn] which enable YANG Datastore subscription [I-D.draft-ietf-netconf-subscribed-notifications]. Enhancements to
and push are defined in [yang-push]. This document provides a [I-D.draft-ietf-netconf-subscribed-notifications] which enable YANG
transport specification for these protocols over Restconf and HTTP. Datastore subscription and push are defined in
Driving these requirements is [RFC7923]. [I-D.ietf-netconf-yang-push]. This document provides a transport
specification for these protocols over RESTCONF and HTTP. Driving
these requirements is [RFC7923].
The streaming of notifications encapsulating the resulting The streaming of notifications encapsulating the resulting
information push can be done with either HTTP1.1 and HTTP2. When information push can be done with either HTTP1.1 and HTTP2. When
using HTTP2 [RFC7540] benefits which can be realized include: using HTTP2 [RFC7540] benefits which can be realized include:
o Elimination of head-of-line blocking o Elimination of head-of-line blocking
o Weighting and proportional dequeuing of Events from different o Weighting and proportional dequeuing of Events from different
subscriptions subscriptions
o Explicit precedence in subscriptions so that events from one o Explicit precedence in subscriptions so that events from one
subscription must be sent before another dequeues subscription must be sent before another dequeues
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
skipping to change at page 3, line 11 skipping to change at page 3, line 16
o Explicit precedence in subscriptions so that events from one o Explicit precedence in subscriptions so that events from one
subscription must be sent before another dequeues subscription must be sent before another dequeues
2. Terminology 2. Terminology
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [RFC2119]. document are to be interpreted as described in RFC 2119 [RFC2119].
The following terms use the defintions from [sn]: configured The following terms use the definitions from
subscription, dynamic subscription, event notification, publisher, [I-D.draft-ietf-netconf-subscribed-notifications]: configured
subscription, dynamic subscription, notification message, publisher,
receiver, subscriber, and subscription. receiver, subscriber, and subscription.
3. Solution 3. Solution
Subscribing to event streams is defined in [sn], YANG Datastore Subscribing to event streams is defined in
subscription is defined in [yang-push]. This section specifies [I-D.draft-ietf-netconf-subscribed-notifications], YANG Datastore
transport mechanisms applicable to both. subscription is defined in [I-D.ietf-netconf-yang-push]. This
section specifies transport mechanisms applicable to both.
3.1. Dynamic YANG Subscription with RESTCONF control 3.1. Dynamic YANG Subscription with RESTCONF control
Dynamic Subscriptions for both [sn] and its [yang-push] augmentations Dynamic subscriptions for both
are configured and managed via signaling messages transported over [I-D.draft-ietf-netconf-subscribed-notifications] and its
[RFC8040]. These interactions will be accomplished via a Restconf [I-D.ietf-netconf-yang-push] augmentations are configured and managed
POST into RPCs located on the Publisher. HTTP responses codes will via signaling messages transported over [RFC8040]. These
indicate the results of the interaction with the Publisher. An HTTP interactions will be accomplished via a RESTCONF POST into RPCs
status code of 200 is the proper response to a successful <establish- located on the publisher. HTTP responses codes will indicate the
results of the interaction with the publisher. An HTTP status code
of 200 is the proper response to a successful <establish-
subscription> RPC call. The successful <establish-subscription> will subscription> RPC call. The successful <establish-subscription> will
result in a HTTP message with returned subscription URI on a result in a HTTP message with returned subscription URI on a
logically separate mechanism than was used for the original Restconf logically separate mechanism than was used for the original RESTCONF
POST. This mechanism is via a parallel TCP connection in the case of POST. This mechanism is via a parallel TCP connection in the case of
HTTP 1.x, or in the case of HTTP2 via a separate HTTP stream within HTTP 1.x, or in the case of HTTP2 via a separate HTTP stream within
the HTTP connection. When a being returned by the Publisher, failure the HTTP connection. When a being returned by the publisher, failure
will be indicated by error codes transported in payload. will be indicated by 4xx range status codes transported in payload.
Anytime hints are returned from the publisher status code 412 is used
with the error-tag "operation-failed".
Once established, the resulting stream of notification messages are Once established, the resulting stream of notification messages are
then delivered via SSE for HTTP1.1 and via HTTP Data for HTTP2. then delivered via SSE for HTTP1.1 and via an HTTP2 DATA frame for
HTTP2.
3.1.1. Call Flow for HTTP2 3.1.1. Call Flow for HTTP2
Requests to [sn] or [yang-push] augmented RPCs are sent on one or Requests to [I-D.draft-ietf-netconf-subscribed-notifications] or
more HTTP2 streams indicated by (a) in Figure 2. Notification [I-D.ietf-netconf-yang-push] augmented RPCs are sent on one or more
messages related to a single subscription are pushed on a unique HTTP2 streams indicated by (a) in Figure 2. Notification messages
logical channel (b). In the case below, a newly established related to a single subscription are pushed on a unique logical
subscription has its associated messages pushed over HTTP2 stream channel (b). In the case below, a newly established subscription has
(7). its associated messages pushed over HTTP2 stream (7).
+------------+ +------------+ +------------+ +------------+
| Subscriber | | Publisher | | Subscriber | | Publisher |
|HTTP2 Stream| |HTTP2 Stream| |HTTP2 Stream| |HTTP2 Stream|
| (a) (b) | | (a) (b) | | (a) (b) | | (a) (b) |
+------------+ +------------+ +------------+ +------------+
| Restconf POST (RPC:establish-subscription) | | RESTCONF POST (RPC:establish-subscription) |
|--------------------------------------------->| |--------------------------------------------->|
| HTTP 200 OK (URI)| | HTTP 200 OK (URI)|
|<---------------------------------------------| |<---------------------------------------------|
| (7)HTTP POST (URI) (7) | (7)HTTP POST (URI) (7)
| |--------------------------------------------->| | |--------------------------------------------->|
| | HTTP 200 OK| | | HTTP 200 OK|
| |<---------------------------------------------| | |<---------------------------------------------|
| | HTTP Data (event-notif)| | | HTTP Data (event-notif)|
| |<---------------------------------------------| | |<---------------------------------------------|
| Restconf POST (RPC:modify-subscription) | | | RESTCONF POST (RPC:modify-subscription) | |
|--------------------------------------------->| | |--------------------------------------------->| |
| | HTTP 200 OK| | | | HTTP 200 OK| |
|<---------------------------------------------| | |<---------------------------------------------| |
| | HTTP Data (subscription-modified)| | | HTTP Data (subscription-modified)|
| |<---------------------------------------------| | |<---------------------------------------------|
| | HTTP Data (event-notif)| | | HTTP Data (event-notif)|
| |<---------------------------------------------| | |<---------------------------------------------|
| Restconf POST (RPC:delete-subscription) | | | RESTCONF POST (RPC:delete-subscription) | |
|--------------------------------------------->| | |--------------------------------------------->| |
| | HTTP 200 OK| | | | HTTP 200 OK| |
|<---------------------------------------------| | |<---------------------------------------------| |
| | HTTP Headers (end of stream)| | | HTTP Headers (end of stream)|
| (/7)<-----------------------------------------(/7) | (/7)<-----------------------------------------(/7)
| |
Figure 1: Dynamic with HTTP2 Figure 1: Dynamic with HTTP2
3.1.2. Call flow for HTTP1.1 3.1.2. Call flow for HTTP1.1
Requests to [yang-push] RPCs are sent on the TCP connection indicated Requests to [I-D.ietf-netconf-yang-push] RPCs are sent on the TCP
by (a). Notification messages are pushed on a separate connection connection indicated by (a). Notification messages are pushed on a
(b). This connection (b) will be used for all notification messages separate connection (b). This connection (b) will be used for all
across all subscriptions. notification messages across all subscriptions.
+--------------+ +--------------+ +--------------+ +--------------+
| Subscriber | | Publisher | | Subscriber | | Publisher |
|TCP connection| |TCP connection| |TCP connection| |TCP connection|
| (a) (b) | | (a) (b) | | (a) (b) | | (a) (b) |
+--------------+ +--------------+ +--------------+ +--------------+
| Restconf POST (RPC:establish-subscription) | | RESTCONF POST (RPC:establish-subscription) |
|--------------------------------------------->| |--------------------------------------------->|
| HTTP 200 OK (URI)| | HTTP 200 OK (URI)|
|<---------------------------------------------| |<---------------------------------------------|
| |HTTP GET (URI) | | |HTTP GET (URI) |
| |--------------------------------------------->| | |--------------------------------------------->|
| | HTTP 200 OK| | | HTTP 200 OK|
| |<---------------------------------------------| | |<---------------------------------------------|
| | SSE (event-notif)| | | SSE (event-notif)|
| |<---------------------------------------------| | |<---------------------------------------------|
| Restconf POST (RPC:modify-subscription) | | | RESTCONF POST (RPC:modify-subscription) | |
|--------------------------------------------->| | |--------------------------------------------->| |
| | HTTP 200 OK| | | | HTTP 200 OK| |
|<---------------------------------------------| | |<---------------------------------------------| |
| | SSE (subscription-modified)| | | SSE (subscription-modified)|
| |<---------------------------------------------| | |<---------------------------------------------|
| | SSE (event-notif)| | | SSE (event-notif)|
| |<---------------------------------------------| | |<---------------------------------------------|
| Restconf POST (RPC:delete-subscription) | | | RESTCONF POST (RPC:delete-subscription) | |
|--------------------------------------------->| | |--------------------------------------------->| |
| | HTTP 200 OK| | | | HTTP 200 OK| |
|<---------------------------------------------| | |<---------------------------------------------| |
| | | | | |
| | | |
Figure 2: Dynamic with HTTP1.1 Figure 2: Dynamic with HTTP1.1
3.1.3. Configured Subscription over HTTP2 3.1.3. Configured Subscription over HTTP2
With a Configured Subscription, all information needed to establish a With a configured subscription, all information needed to establish a
secure relationship with that Receiver is available on the Publisher. secure relationship with that receiver is available on the publisher.
With this information, the Publisher will establish a secure With this information, the publisher will establish a secure
transport connection with the Receiver and then begin pushing transport connection with the receiver and then begin pushing
notification messages to the Receiver. Since Restconf might not notification messages to the receiver. Since RESTCONF might not
exist on the Receiver, it is not desirable to require that subscribed exist on the receiver, it is not desirable to require that subscribed
content be pushed with any dependency on Restconf. Nor is there content be pushed with any dependency on RESTCONF. Therefore in
value which Restconf provides on top of HTTP. Therefore in place of place of RESTCONF, a TLS secured HTTP2 Client connection must be
Restconf, a TLS secured HTTP2 Client connection must be established established with an HTTP2 Server located on the receiver.
with an HTTP2 Server located on the Receiver. Notification messages Notification messages will then be sent as part of an extended HTTP
will then be sent as part of an extended HTTP POST to the Receiver. POST to the receiver.
POST messages will be addressed to HTTP augmentation code on the POST messages will be addressed to HTTP augmentation code on the
Receiver capable of accepting and responding to state change receiver capable of accepting and responding to state change
notifications and subscribed content notification messages. The notifications and subscribed content notification messages. The
first POST message must be a subscription-started notification. first POST message must be a subscription-started notification.
Notifications which include any subscribed content must not be sent Notifications which include any subscribed content must not be sent
until the receipt of an HTTP 200 OK for this initial notification. until the receipt of an HTTP 200 OK for this initial notification.
The 200 OK will indicate that the Receiver is ready for the delivery The 200 OK will indicate that the receiver is ready for the delivery
of subscribed content. At this point a Subscription must be of subscribed content. At this point a subscription must be
allocated its own HTTP2 stream. Figure 4 depicts this message flow. allocated its own HTTP2 stream. Figure 4 depicts this message flow.
+------------+ +------------+ +------------+ +------------+
| Receiver | | Publisher | | Receiver | | Publisher |
|HTTP2 Stream| |HTTP2 Stream| |HTTP2 Stream| |HTTP2 Stream|
| (a) (b) | | (a) (b) | | (a) (b) | | (a) (b) |
+------------+ +------------+ +------------+ +------------+
| HTTP Post Headers, Data (sub-start, SubID)| | HTTP Post Headers, Data (sub-start, SubID)|
|<---------------------------------------------| |<---------------------------------------------|
| HTTP 200 OK | | HTTP 200 OK |
skipping to change at page 6, line 32 skipping to change at page 6, line 32
| |<---------------------------------------------| | |<---------------------------------------------|
| | HTTP Data (event-notif)| | | HTTP Data (event-notif)|
| |<---------------------------------------------| | |<---------------------------------------------|
| | HTTP Data (sub-terminate)| | | HTTP Data (sub-terminate)|
| |<---------------------------------------------| | |<---------------------------------------------|
| |HTTP 200 OK | | |HTTP 200 OK |
| |--------------------------------------------->| | |--------------------------------------------->|
Figure 3: Configured over HTTP2 Figure 3: Configured over HTTP2
As the HTTP2 transport is available to the Receiver, the Publisher As the HTTP2 transport is available to the receiver, the publisher
should: should:
o take any subscription-priority and copy it into the HTTP2 stream o take any subscription-priority and copy it into the HTTP2 stream
priority, and priority, and
o take a subscription-dependency if it has been provided and map the o take a subscription-dependency if it has been provided and map the
HTTP2 stream for the parent subscription into the HTTP2 stream HTTP2 stream for the parent subscription into the HTTP2 stream
dependency. dependency.
3.2. Subscription Multiplexing 4. Mandatory JSON and datastore support
It is possible that updates across subscriptions might be delivered A publisher MUST support JSON encoding of RPCs and Notifications.
in a different sequence than the encapsulated records were generated.
Reasons for this might include (but are not limited to):
o generation of event records on different line cards A publisher supporting [I-D.ietf-netconf-yang-push] MUST support the
"operational" datastore as defined by
[I.D.draft-ietf-netmod-revised-datastores].
o replay of pushed information, and 5. Notification Messages
o temporary loss of transport connectivity, with update buffering
and different dequeuing priorities per Subscription
o population, marshalling and bundling across independent Notification messages transported over NETCONF will be identical in
Subscription Updates, and format and content to those encoded using one-way operations defined
within [RFC5277], section 4.
Therefore each notification message will include a timestamp to 6. Security Considerations
provide a Receiver with its best information indicating when a
particular record was generated. Use of this timestamp can give an
indication of the state of objects at a Publisher. This is
especially important when state-entangled information is received
across different subscriptions. Note that use of notification
message timestamps may not indicate a the exact time of occurrence.
So when state-entangled updates have inconsistent object values and
temporally close timestamps, a Receiver might consider performing a
GET to validate the current state of a Publisher.
4. Encoded Subscription and Notification Message Examples One or more publishers of configured subscriptions could be used to
overwhelm a receiver which doesn't even support subscriptions. There
are two protections needing support on a publisher. First,
notification messages for configured subscriptions MUST only be
transmittable over encrypted transports. Clients which do not want
pushed content need only terminate or refuse any transport sessions
from the publisher. Second, the HTTP transport augmentation on the
receiver must send an HTTP 200 OK to a subscription started
notification before the publisher starts streaming any subscribed
content.
4.1. Restconf Subscription and Events over HTTP1.1 One or more publishers could overwhelm a receiver which is unable to
control or handle the volume of Event Notifications received. In
deployments where this might be a concern, HTTP2 transport such as
HTTP2) should be selected.
The NETCONF Authorization Control Model [RFC6536] SHOULD be used to
control and restrict authorization of subscription configuration.
7. Acknowledgments
We wish to acknowledge the helpful contributions, comments, and
suggestions that were received from: Susan Hares, Tim Jenkins, Balazs
Lengyel, Kent Watsen, Michael Scharf, and Guangying Zheng.
8. References
8.1. Normative References
[I-D.draft-ietf-netconf-subscribed-notifications]
Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A.,
and E. Nilsen-Nygaard, "Custom Subscription to Event
Streams", draft-ietf-netconf-subscribed-notifications-06
(work in progress), January 2018.
[I.D.draft-ietf-netmod-revised-datastores]
Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
and R. Wilton, "Network Management Datastore
Architecture", draft-ietf-netmod-revised-datastores-04
(work in progress), August 2017.
[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>.
[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>.
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
Protocol (NETCONF) Access Control Model", RFC 6536,
DOI 10.17487/RFC6536, March 2012,
<https://www.rfc-editor.org/info/rfc6536>.
[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>.
8.2. Informative References
[GRPC] "RPC framework that runs over HTTP2", August 2017,
<https://grpc.io/>.
[I-D.ietf-netconf-yang-push]
Clemm, A., Voit, E., Gonzalez Prieto, A., Prasad Tripathy,
A., Nilsen-Nygaard, E., Bierman, A., and B. Lengyel,
"Subscribing to YANG datastore push updates", March 2017,
<https://datatracker.ietf.org/doc/
draft-ietf-netconf-yang-push/>.
[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>.
[RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home",
RFC 8071, DOI 10.17487/RFC8071, February 2017,
<https://www.rfc-editor.org/info/rfc8071>.
[W3C-20150203]
"Server-Sent Events, World Wide Web Consortium CR CR-
eventsource-20121211", February 2015,
<https://www.w3.org/TR/2015/REC-eventsource-20150203/>.
Appendix A. End-to-End Deployment Guidance
Several technologies are expected to be seen within a deployment to
achieve security and ease-of-use requirements. These are not
necessary for an implementation of this specification, but will be
useful to consider when considering the operational context.
A.1. Call Home
Implementations should include the ability to transparently
incorporate 'call home' [RFC8071] so that secure TLS connections can
originate from the desired device.
A.2. TLS Heartbeat
HTTP sessions might not quickly allow a subscriber to recognize when
the communication path has been lost from the publisher. To
recognize this, it is possible for a receiver to establish a TLS
heartbeat [RFC6520]. In the case where a TLS heartbeat is included,
it should be sent just from receiver to publisher. Loss of the
heartbeat should result in any subscription related TCP sessions
between those endpoints being torn down. The subscription can then
attempt to re-establish.
Appendix B. RESTCONF over GRPC
An initial goal for this document was to support [GRPC] transport
seamlessly without any mapping or extra layering. However there is
an incompatibility of RESTCONF and GRPC. RESTCONF uses HTTP GET, and
GRPC uses HTTP2's POST rather than GET. As GET is used across
RESTCONF for things like capabilities exchange, a seamless mapping
depends on specification changes outside the scope of this document.
If/when GRPC supports GET, or RESTCONF is updated to support POST,
this should be revisited. It is hoped that the resulting fix will be
transparent to this document.
Appendix C. Encoded Subscription and Notification Message Examples
(Note: examples in this section need significant updates)
C.1. RESTCONF Subscription and Events over HTTP1.1
Subscribers can dynamically learn whether a RESTCONF server supports Subscribers can dynamically learn whether a RESTCONF server supports
various types of Event or Yang datastore subscription capabilities. various types of Event or Yang datastore subscription capabilities.
This is done by issuing an HTTP request OPTIONS, HEAD, or GET on the This is done by issuing an HTTP request OPTIONS, HEAD, or GET on the
stream. Some examples building upon the Call flow for HTTP1.1 from stream. Some examples building upon the Call flow for HTTP1.1 from
Section 3.2.2 are: Section 3.2.2 are:
GET /restconf/data/ietf-restconf-monitoring:restconf-state/ GET /restconf/data/ietf-restconf-monitoring:restconf-state/
streams/stream=yang-push HTTP/1.1 streams/stream=yang-push HTTP/1.1
Host: example.com Host: example.com
skipping to change at page 8, line 33 skipping to change at page 11, line 5
HTTP/1.1 404 Not Found HTTP/1.1 404 Not Found
Date: Mon, 25 Apr 2012 11:10:30 GMT Date: Mon, 25 Apr 2012 11:10:30 GMT
Server: example-server Server: example-server
Subscribers can determine the URL to receive updates by sending an Subscribers can determine the URL to receive updates by sending an
HTTP GET as a request for the "location" leaf with the stream list HTTP GET as a request for the "location" leaf with the stream list
entry. The stream to use for may be selected from the Event Stream entry. The stream to use for may be selected from the Event Stream
list provided in the capabilities exchange. Note that different list provided in the capabilities exchange. Note that different
encodings are supporting using different Event Stream locations. For encodings are supporting using different Event Stream locations. For
example, the Subscriber might send the following request: example, the subscriber might send the following request:
GET /restconf/data/ietf-restconf-monitoring:restconf-state/ GET /restconf/data/ietf-restconf-monitoring:restconf-state/
streams/stream=yang-push/access=xml/location HTTP/1.1 streams/stream=yang-push/access=xml/location HTTP/1.1
Host: example.com Host: example.com
Accept: application/yang.data+xml Accept: application/yang.data+xml
The Publisher might send the following response: The publisher might send the following response:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/yang.api+xml Content-Type: application/yang.api+xml
<location <location
xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring"> xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring">
https://example.com/streams/yang-push-xml https://example.com/streams/yang-push-xml
</location> </location>
To subscribe and start receiving updates, the subscriber can then To subscribe and start receiving updates, the subscriber can then
send an HTTP GET request for the URL returned by the Publisher in the send an HTTP GET request for the URL returned by the publisher in the
request above. The accept header must be "text/event-stream". The request above. The accept header must be "text/event-stream". The
Publisher uses the Server Sent Events [W3C-20150203] transport publisher uses the Server Sent Events [W3C-20150203] transport
strategy to push filtered events from the event stream. strategy to push filtered events from the event stream.
The Publisher MUST support individual parameters within the POST The publisher MUST support individual parameters within the POST
request body for all the parameters of a subscription. The only request body for all the parameters of a subscription. The only
exception is the encoding, which is embedded in the URI. An example exception is the encoding, which is embedded in the URI. An example
of this is: of this is:
// subtree filter = /foo // subtree filter = /foo
// periodic updates, every 5 seconds // periodic updates, every 5 seconds
POST /restconf/operations/ietf-event-notifications: POST /restconf/operations/ietf-subscribed-notifications:
establish-subscription HTTP/1.1 establish-subscription HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data+json Content-Type: application/yang-data+json
{ {
"ietf-event-notifications:input" : { "ietf-subscribed-notifications:input" : {
"stream": "push-data" "stream": "push-data"
"period" : 5, "period" : 5,
"xpath-filter" : "/ex:foo[starts-with('bar'.'some']" "xpath-filter" : "/ex:foo[starts-with('bar'.'some']"
} }
} }
Should the publisher not support the requested subscription, it may Should the publisher not support the requested subscription, it may
reply: reply:
HTTP/1.1 501 Not Implemented HTTP/1.1 501 Not Implemented
skipping to change at page 10, line 45 skipping to change at page 12, line 45
"error-message": "Xpath filters not supported." "error-message": "Xpath filters not supported."
"error-info": { "error-info": {
"datastore-push:supported-subscription": { "datastore-push:supported-subscription": {
"subtree-filter": [null] "subtree-filter": [null]
} }
} }
} }
} }
} }
The following is an example of a pushed content for the Subscription The following is an example of a pushed content for the subscription
above. It contains a subtree with root foo that contains a leaf above. It contains a subtree with root foo that contains a leaf
called bar: called bar:
XML encoding representation: XML encoding representation:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf"> <notification xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
<subscription-id xmlns="urn:ietf:params:xml:ns:restconf: <subscription-id xmlns="urn:ietf:params:xml:ns:restconf:
datastore-push:1.0"> datastore-push:1.0">
my-sub my-sub
</subscription-id> </subscription-id>
skipping to change at page 11, line 34 skipping to change at page 13, line 34
{ {
"ietf-restconf:notification": { "ietf-restconf:notification": {
"datastore-push:subscription-id": "my-sub", "datastore-push:subscription-id": "my-sub",
"eventTime": "2015-03-09T19:14:56.233Z", "eventTime": "2015-03-09T19:14:56.233Z",
"datastore-push:datastore-contents": { "datastore-push:datastore-contents": {
"example-mod:foo": { "bar": "some_string" } "example-mod:foo": { "bar": "some_string" }
} }
} }
} }
To modify a Subscription, the subscriber issues another POST request To modify a subscription, the subscriber issues another POST request
on the provided URI using the same subscription-id as in the original on the provided URI using the same subscription-id as in the original
request. For example, to modify the update period to 10 seconds, the request. For example, to modify the update period to 10 seconds, the
subscriber may send: subscriber may send:
POST /restconf/operations/ietf-event-notifications: POST /restconf/operations/ietf-subscribed-notifications:
modify-subscription HTTP/1.1 modify-subscription HTTP/1.1
Host: example.com Host: example.com
Content-Type: application/yang-data+json Content-Type: application/yang-data+json
{ {
"ietf-event-notifications:input" : { "ietf-subscribed-notifications:input" : {
"subscription-id": 100, "subscription-id": 100,
"period" : 10 "period" : 10
} }
} }
To delete a Subscription, the Subscriber issues a DELETE request on To delete a subscription, the subscriber issues a DELETE request on
the provided URI using the same subscription-id as in the original the provided URI using the same subscription-id as in the original
request request
4.2. Event Notification over HTTP2 C.2. Event Notification over HTTP2
The basic encoding will look as below. It will consists of a JSON The basic encoding will look as below. It will consists of a JSON
representation wrapped in an HTTP2 header. representation wrapped in an HTTP2 header.
HyperText Transfer Protocol 2 HyperText Transfer Protocol 2
Stream: HEADERS, Stream ID: 5 Stream: HEADERS, Stream ID: 5
Header: :method: POST Header: :method: POST
Stream: HEADERS, Stream ID: 5 Stream: HEADERS, Stream ID: 5
{ {
"ietf-yangpush:notification": { "ietf-yangpush:notification": {
"datastore-push:subscription-id": "my-sub", "datastore-push:subscription-id": "my-sub",
"eventTime": "2015-03-09T19:14:56.233Z", "eventTime": "2015-03-09T19:14:56.233Z",
"datastore-push:datastore-contents": { "datastore-push:datastore-contents": {
"foo": { "bar": "some_string" } "foo": { "bar": "some_string" }
} }
} }
} }
5. Security Considerations Appendix D. Changes between revisions
Subscriptions could be used to intentionally or accidentally overload
the resources of a Publisher. For this reason, it is important that
the Publisher has the ability to prioritize the establishment and
push of notification messages where there is the potential for
resource exhaust. In addition, a server needs to be able to suspend
existing Subscriptions when needed. When this occurs, the
subscription status must be updated accordingly and the Receivers
notified.
A Subscription could be used to attempt retrieve information for
which a Receiver has no authorized access. Therefore it is important
that data pushed via a Subscription is authorized equivalently with
regular data retrieval operations. Data being pushed to a Receiver
needs therefore to be filtered accordingly, just like if the data
were being retrieved on-demand. The Netconf Authorization Control
Model [RFC6536] applies even though the transport is not NETCONF.
One or more Publishers of Configured Subscriptions could be used to
overwhelm a Receiver which doesn't even support Subscriptions. There
are two protections here. First, notification messages for
Configured Subscriptions MUST only be transmittable over encrypted
transports. Clients which do not want pushed content need only
terminate or refuse any transport sessions from the Publisher.
Second, the HTTP transport augmentation on the Receiver must send an
HTTP 200 OK to a subscription started notification before the
Publisher starts streaming any subscribed content.
One or more Publishers could overwhelm a Receiver which is unable to
control or handle the volume of Event Notifications received. In
deployments where this might be a concern, HTTP2 transport such as
HTTP2) should be selected.
6. Acknowledgments
We wish to acknowledge the helpful contributions, comments, and
suggestions that were received from: Susan Hares, Tim Jenkins, Balazs
Lengyel, Kent Watsen, Michael Scharf, and Guangying Zheng.
7. References
7.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,
<http://www.rfc-editor.org/info/rfc2119>.
[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,
<http://www.rfc-editor.org/info/rfc6520>.
[RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
Protocol (NETCONF) Access Control Model", RFC 6536,
DOI 10.17487/RFC6536, March 2012,
<http://www.rfc-editor.org/info/rfc6536>.
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
DOI 10.17487/RFC7540, May 2015,
<http://www.rfc-editor.org/info/rfc7540>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<http://www.rfc-editor.org/info/rfc8040>.
[sn] Voit, E., Clemm, A., Gonzalez Prieto, A., Prasad Tripathy,
A., and E. Nilsen-Nygaard, "Subscribing to Event
Notifications", February 2017,
<https://datatracker.ietf.org/doc/draft-ietf-netconf-
subscribed-notifications/>.
7.2. Informative References
[GRPC] "RPC framework that runs over HTTP2", August 2017,
<https://grpc.io/>.
[RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements
for Subscription to YANG Datastores", RFC 7923,
DOI 10.17487/RFC7923, June 2016,
<http://www.rfc-editor.org/info/rfc7923>.
[RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG",
RFC 7951, DOI 10.17487/RFC7951, August 2016,
<http://www.rfc-editor.org/info/rfc7951>.
[RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home",
RFC 8071, DOI 10.17487/RFC8071, February 2017,
<http://www.rfc-editor.org/info/rfc8071>.
[W3C-20150203]
"Server-Sent Events, World Wide Web Consortium CR CR-
eventsource-20121211", February 2015,
<https://www.w3.org/TR/2015/REC-eventsource-20150203/>.
[yang-push]
Clemm, A., Voit, E., Gonzalez Prieto, A., Prasad Tripathy,
A., Nilsen-Nygaard, E., Bierman, A., and B. Lengyel,
"Subscribing to YANG datastore push updates", March 2017,
<https://datatracker.ietf.org/doc/draft-ietf-netconf-yang-
push/>.
Appendix A. End-to-End Deployment Guidance
Several technologies are expected to be seen within a deployment to
achieve security and ease-of-use requirements. These are not
necessary for an implementation of this specification, but will be
useful to consider when considering the operational context.
A.1. Call Home
Implementations should include the ability to transparently
incorporate 'call home' [RFC8071] so that secure TLS connections can
originate from the desired device.
A.2. TLS Heartbeat
HTTP sessions might not quickly allow a Subscriber to recognize when
the communication path has been lost from the Publisher. To
recognize this, it is possible for a Receiver to establish a TLS
heartbeat [RFC6520]. In the case where a TLS heartbeat is included,
it should be sent just from Receiver to Publisher. Loss of the
heartbeat should result in any Subscription related TCP sessions
between those endpoints being torn down. The subscription can then
attempt to re-establish.
Appendix B. RESTCONF over GRPC (To be removed by RFC editor prior to publication)
An initial goal for this document was to support [GRPC] transport v03 - v04
seamlessly without any mapping or extra layering. However there is
an incompatibility of RESTCONF and GRPC. RESTCONF uses HTTP GET, and
GRPC uses HTTP2's POST rather than GET. As GET is used across
RESTCONF for things like capabilities exchange, a seamless mapping
depends on specification changes outside the scope of this document.
If/when GRPC supports GET, or RESTCONF is updated to support POST,
this should be revisited. It is hoped that the resulting fix will be
transparent to this document.
Appendix C. Changes between revisions o Draft not fully synched to new version of subscribed-notifications
yet.
(To be removed by RFC editor prior to publication) o References updated
v01 - v03 v02 - v03
o Terminoology aligned with draft-voit-netconf-notification- o Event notification reframed to notification message.
messages.
o Tweaks to wording/capitalization/format. o Tweaks to wording/capitalization/format.
v01 - v02 v01 - v02
o Removed sections now redundant with [sn] and [yang-push] such as: o Removed sections now redundant with
mechanisms for subscription maintenance, terminology definitions, [I-D.draft-ietf-netconf-subscribed-notifications] and
stream discovery. [I-D.ietf-netconf-yang-push] such as: mechanisms for subscription
maintenance, terminology definitions, stream discovery.
o 3rd party subscriptions are out-of-scope. o 3rd party subscriptions are out-of-scope.
o SSE only used with Restconf and HTTP1.1 Dynamic Subscriptions o SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions
o Timeframes for event tagging are self-defined. o Timeframes for event tagging are self-defined.
o Clean-up of wording, references to terminology, section numbers. o Clean-up of wording, references to terminology, section numbers.
v00 - v01 v00 - v01
o Removed the ability for more than one subscription to go to a o Removed the ability for more than one subscription to go to a
single HTTP2 stream. single HTTP2 stream.
o Updated call flows. Extensively. o Updated call flows. Extensively.
o SSE only used with Restconf and HTTP1.1 Dynamic Subscriptions o SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions
o HTTP is not used to determine that a Receiver has gone silent and o HTTP is not used to determine that a receiver has gone silent and
is not Receiving Event Notifications is not Receiving Event Notifications
o Many clean-ups of wording and terminology o Many clean-ups of wording and terminology
Authors' Addresses Authors' Addresses
Eric Voit Eric Voit
Cisco Systems Cisco Systems
Email: evoit@cisco.com Email: evoit@cisco.com
 End of changes. 61 change blocks. 
261 lines changed or deleted 265 lines changed or added

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