idnits 2.17.00 (12 Aug 2021) /tmp/idnits10988/draft-ietf-netconf-restconf-notif-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 3 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 213 has weird spacing: '...ription estab...' == Line 217 has weird spacing: '...ription res...' == Line 232 has weird spacing: '... stream esta...' == Line 235 has weird spacing: '...ription ret...' == Line 237 has weird spacing: '... stream modi...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o An HTTP end of stream message MUST not be sent until all subscriptions using that HTTP2 stream have completed. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: o An HTTP end of stream message MUST not be sent until all subscriptions using that HTTP2 stream have completed. -- The document date (May 18, 2018) is 1463 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. 'GRPC' == Outdated reference: draft-ietf-netconf-subscribed-notifications has been published as RFC 8639 == Outdated reference: draft-ietf-netconf-yang-push has been published as RFC 8641 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) -- Possible downref: Non-RFC (?) normative reference: ref. 'W3C-20150203' == Outdated reference: draft-ietf-netconf-netconf-event-notifications has been published as RFC 8640 == Outdated reference: draft-ietf-netconf-nmda-restconf has been published as RFC 8527 Summary: 2 errors (**), 0 flaws (~~), 13 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF E. Voit 3 Internet-Draft E. Nilsen-Nygaard 4 Intended status: Standards Track Cisco Systems 5 Expires: November 19, 2018 A. Clemm 6 Huawei 7 A. Bierman 8 YumaWorks 9 May 18, 2018 11 RESTCONF and HTTP Transport for Event Notifications 12 draft-ietf-netconf-restconf-notif-05 14 Abstract 16 This document defines RESTCONF, HTTP2, and HTTP1.1 bindings for the 17 transport of subscription requests and corresponding push updates. 18 Being subscribed may be either publisher defined event streams or 19 nodes/subtrees of YANG Datastores. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on November 19, 2018. 38 Copyright Notice 40 Copyright (c) 2018 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (https://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. Dynamic Subscription . . . . . . . . . . . . . . . . . . . . 3 58 3.1. Transport Connectivity . . . . . . . . . . . . . . . . . 4 59 3.2. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3.3. RESTCONF RPCs and HTTP Status Codes . . . . . . . . . . . 4 61 3.4. Call Flow for HTTP2 . . . . . . . . . . . . . . . . . . . 6 62 3.5. Call flow for HTTP1.1 . . . . . . . . . . . . . . . . . . 8 63 4. Configured Subscription . . . . . . . . . . . . . . . . . . . 10 64 4.1. Transport Connectivity . . . . . . . . . . . . . . . . . 10 65 4.2. Call Flow . . . . . . . . . . . . . . . . . . . . . . . . 11 66 5. QoS Treatment . . . . . . . . . . . . . . . . . . . . . . . . 12 67 6. Mandatory JSON and datastore support . . . . . . . . . . . . 12 68 7. Notification Messages . . . . . . . . . . . . . . . . . . . . 12 69 8. YANG Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 12 70 9. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 13 71 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 72 11. Security Considerations . . . . . . . . . . . . . . . . . . . 16 73 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 17 74 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 17 75 13.1. Normative References . . . . . . . . . . . . . . . . . . 17 76 13.2. Informative References . . . . . . . . . . . . . . . . . 19 77 Appendix A. RESTCONF over GRPC . . . . . . . . . . . . . . . . . 19 78 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 19 79 B.1. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 20 80 B.1.1. Establishing Dynamic Subscriptions . . . . . . . . . 20 81 B.1.2. Modifying Dynamic Subscriptions . . . . . . . . . . . 22 82 B.1.3. Deleting Dynamic Subscriptions . . . . . . . . . . . 24 83 B.2. Configured Subscriptions . . . . . . . . . . . . . . . . 25 84 B.2.1. Creating Configured Subscriptions . . . . . . . . . . 25 85 B.2.2. Modifying Configured Subscriptions . . . . . . . . . 28 86 B.2.3. Deleting Configured Subscriptions . . . . . . . . . . 30 87 B.3. Subscription State Notifications . . . . . . . . . . . . 31 88 B.3.1. subscription-started and subscription-modified . . . 31 89 B.3.2. subscription-completed, subscription-resumed, and 90 replay-complete . . . . . . . . . . . . . . . . . . . 32 91 B.3.3. subscription-terminated and subscription-suspended . 32 92 Appendix C. Changes between revisions . . . . . . . . . . . . . 33 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 34 95 1. Introduction 97 Mechanisms to support event subscription and push are defined in 98 [I-D.draft-ietf-netconf-subscribed-notifications]. Enhancements to 99 [I-D.draft-ietf-netconf-subscribed-notifications] which enable YANG 100 datastore subscription and push are defined in 101 [I-D.ietf-netconf-yang-push]. This document provides a transport 102 specification for these protocols over RESTCONF [RFC8040] and HTTP. 103 Driving these requirements is [RFC7923]. 105 The streaming of notifications encapsulating the resulting 106 information push can be done with either HTTP1.1 [RFC7231] or HTTP2 107 [RFC7540]. 109 2. Terminology 111 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 112 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 113 document are to be interpreted as described in RFC 2119 [RFC2119]. 115 The following terms use the definitions from 116 [I-D.draft-ietf-netconf-subscribed-notifications]: configured 117 subscription, dynamic subscription, event stream, notification 118 message, publisher, receiver, subscriber, and subscription. 120 Other terms reused include datastore, which is defined in [RFC8342], 121 and HTTP2 stream which maps to the definition of "stream" within 122 [RFC7540], Section 2. 124 [ note to the RFC Editor - please replace XXXX within this document 125 with the number of this document ] 127 3. Dynamic Subscription 129 This section provides specifics on how to establish and maintain 130 dynamic subscriptions over HTTP 1.1 and HTTP2 via signaling messages 131 transported over RESTCONF [RFC8040]. Subscribing to event streams is 132 accomplished in this way via a RESTCONF POST into RPCs defined within 133 [I-D.draft-ietf-netconf-subscribed-notifications] Section 2.4. YANG 134 datastore subscription is accomplished via augmentations to 135 [I-D.draft-ietf-netconf-subscribed-notifications] as described within 136 [I-D.ietf-netconf-yang-push] Section 4.4. 138 Common across all HTTP based dynamic subscriptions is that a POST 139 needs to be made against a specific URI on the Publisher. 140 Subscribers cannot pre-determine the URI against which a subscription 141 might exist on a publisher, as the URI will only exist after the 142 "establish-subscription" has been accepted. There subscription URI 143 will be determined and sent as part of the response to the 144 "establish-subscription", and a subsequent POST to this URI will be 145 done in order to start the flow of notification messages back to the 146 subscriber. A subscription does not become ACTIVE as per 147 Section 2.4.1. of [I-D.draft-ietf-netconf-subscribed-notifications] 148 until the POST is received. 150 3.1. Transport Connectivity 152 For a dynamic subscription, where an HTTP client session doesn't 153 already exist, a new client session is initiated from the subscriber. 154 If the subscriber is unsure if HTTP2 is supported by the publisher, 155 HTTP1.1 will be used for initial messages, and these messages will 156 include an HTTP version upgrade request as per [RFC7230], 157 Section 6.7. If a publisher response indicates that HTTP2 is 158 supported, HTTP2 will be used between subscriber and publisher for 159 future HTTP interactions as per [RFC7540]. 161 A subscriber SHOULD establish the HTTP session over TLS [RFC5246] in 162 order to secure the content in transit. 164 Without the involvement of additional protocols, neither HTTP1.1 nor 165 HTTP2 sessions by themselves allow for a quick recognition of when 166 the communication path has been lost with the publisher. Where quick 167 recognition of the loss of a publisher is required, a subscriber 168 SHOULD connect over TLS [RFC5246], and use a TLS heartbeat [RFC6520] 169 to track HTTP session continuity. In the case where a TLS heartbeat 170 is included, it should be sent just from receiver to publisher. Loss 171 of the heartbeat MUST result in any subscription related TCP sessions 172 between those endpoints being torn down. A subscriber can then 173 attempt to re-establish. 175 3.2. Discovery 177 Subscribers can learn what event streams a RESTCONF server supports 178 by querying the "streams" container of ietf-subscribed- 179 notification.yang. Subscribers can learn what datastores a RESTCONF 180 server supports by following [I-D.draft-ietf-netconf-nmda-restconf]. 182 3.3. RESTCONF RPCs and HTTP Status Codes 184 Specific HTTP responses codes as defined in [RFC7231] section 6 will 185 indicate the result of RESTCONF RPC requests with publisher. An HTTP 186 status code of 200 is the proper response to any successful RPC 187 defined within [I-D.draft-ietf-netconf-subscribed-notifications] or 188 [I-D.ietf-netconf-yang-push]. 190 If a publisher fails to serve the RPC request for one of the reasons 191 indicated in [I-D.draft-ietf-netconf-subscribed-notifications] 192 Section 2.4.6 or [I-D.ietf-netconf-yang-push] Appendix A, this will 193 be indicated by "406" status code transported in the HTTP response. 195 When a "406" status code is returned, the RPC reply MUST include an 196 "rpc-error" element per [RFC8040] Section 7.1 with the following 197 parameter values: 199 o an "error-type" node of "application". 201 o an "error-tag" node of "operation-failed". 203 o an "error-app-tag" node with the value being a string that 204 corresponds to an identity associated with the error, as defined 205 in [I-D.draft-ietf-netconf-subscribed-notifications] section 2.4.6 206 for general subscriptions, and [I-D.ietf-netconf-yang-push] 207 Appendix A.1, for datastore subscriptions. The tag to use depends 208 on the RPC for which the error occurred. Viable errors for 209 different RPCs are as follows: 211 RPC select an identity with a base 212 ---------------------- ------------------------------ 213 establish-subscription establish-subscription-error 214 modify-subscription modify-subscription-error 215 delete-subscription delete-subscription-error 216 kill-subscription kill-subscription-error 217 resynch-subscription resynch-subscription-error 219 Each error identity will be inserted as the "error-app-tag" using 220 JSON encoding following the form :. An 221 example of such as valid encoding would be "ietf-subscribed- 222 notifications:no-such-subscription". 224 o In case of error responses to an "establish-subscription" or 225 "modify-subscription" request there is the option of including an 226 "error-info" node. This node may contain hints for parameter 227 settings that might lead to successful RPC requests in the future. 228 Following are the yang-data structures which may be returned: 230 establish-subscription returns hints in yang-data structure 231 ---------------------- ------------------------------------ 232 target: event stream establish-subscription-stream-error-info 233 target: datastore establish-subscription-datastore-error-info 235 modify-subscription returns hints in yang-data structure 236 ---------------------- ------------------------------------ 237 target: event stream modify-subscription-stream-error-info 238 target: datastore modify-subscription-datastore-error-info 240 The yang-data included within "error-info" SHOULD NOT include the 241 optional leaf "error-reason", as such a leaf would be redundant 242 with information that is already placed within the 243 "error-app-tag". 245 In case of an rpc error as a result of a "delete-subscription", a 246 "kill-subscription", or a "resynch-subscription" request, no 247 "error-info" needs to be included, as the "subscription-id" is 248 the only RPC input parameter and no hints regarding this RPC input 249 parameters need to be provided. 251 Note that "error-path" does not need to be included with the "rpc- 252 error" element, as subscription errors are generally not associated 253 with nodes in the datastore but with the choice of RPC input 254 parameters. 256 3.4. Call Flow for HTTP2 258 Requests to [I-D.draft-ietf-netconf-subscribed-notifications] or 259 [I-D.ietf-netconf-yang-push] augmented RPCs are sent on one or more 260 HTTP2 streams indicated by (a) in Figure 1. A successful "establish- 261 subscription" will result in an RPC response returned with both a 262 subscription identifier which uniquely identifies a subscription, as 263 well as a URI which uniquely identifies the location of subscription 264 on the publisher. This URI is defined via the "uri" leaf the Data 265 Model in Section 9. 267 An HTTP POST is then sent on a logically separate HTTP2 stream (b) to 268 the URI on the publisher. This initiates to initiate the flow of 269 notification messages which are sent in HTTP Data frames as a 270 response to the POST. In the case below, a newly established 271 subscription has its associated notification messages pushed over 272 HTTP2 stream (7). These notification messages are placed into a 273 HTTP2 Data frame (see [RFC7540] Section 6.1). 275 +------------+ +------------+ 276 | Subscriber | | Publisher | 277 |HTTP2 Stream| |HTTP2 Stream| 278 | (a) (b) | | (a) (b) | 279 +------------+ +------------+ 280 | RESTCONF POST (RPC:establish-subscription) | 281 |--------------------------------------------->| 282 | HTTP 200 OK (ID,URI)| 283 |<---------------------------------------------| 284 | (7)HTTP POST (URI) (7) 285 | |--------------------------------------------->| 286 | | HTTP 200 OK| 287 | |<---------------------------------------------| 288 | | HTTP Data (notif-message)| 289 | |<---------------------------------------------| 290 | RESTCONF POST (RPC:modify-subscription) | | 291 |--------------------------------------------->| | 292 | | HTTP 200 OK| | 293 |<---------------------------------------------| | 294 | | HTTP Data (subscription-modified)| 295 | |<------------------------------------------(c)| 296 | | HTTP Data (notif-message)| 297 | |<---------------------------------------------| 298 | RESTCONF POST (RPC:delete-subscription) | | 299 |--------------------------------------------->| | 300 | | HTTP 200 OK| | 301 |<---------------------------------------------| | 302 | | HTTP Headers (end of stream)| 303 | (/7)<-----------------------------------------(/7) 304 | 306 Figure 1: Dynamic with HTTP2 308 Additional requirements for dynamic subscriptions over HTTP2 include: 310 o A unique HTTP2 stream MAY be used for each subscription. 312 o A single HTTP2 stream MUST NOT be used for subscriptions with 313 different DSCP values. 315 o All subscription state notifications from a publisher MUST be 316 returned in a separate HTTP Data frame within the HTTP2 stream 317 used by the subscription to which the state change refers. 319 o In addition to an RPC response for a "modify-subscription" RPC 320 traveling over (a), a "subscription-modified" state change 321 notification must be sent within HTTP2 stream (b). This allows 322 the receiver to know exactly when the new terms of the 323 subscription have been applied to the notification messages. See 324 arrow (c). 326 o Additional RPCs for a particular subscription MUST NOT use the 327 HTTP2 stream currently providing notification messages 328 subscriptions. 330 o An HTTP end of stream message MUST not be sent until all 331 subscriptions using that HTTP2 stream have completed. 333 3.5. Call flow for HTTP1.1 335 The call flow is defined in Figure 2. Requests to 336 [I-D.draft-ietf-netconf-subscribed-notifications] or 337 [I-D.ietf-netconf-yang-push] augmented RPCs are sent on a TCP 338 connection indicated by (a). A successful "establish-subscription" 339 will result in an RPC response returned with both a subscription 340 identifier which uniquely identifies a subscription, as well as a URI 341 which uniquely identifies the location of subscription on the 342 publisher (b). This URI is defined via the "uri" leaf the Data Model 343 in Section 9. 345 An HTTP POST is then sent on a logically separate TCP connection (b) 346 to the URI on the publisher. This initiates to initiate the flow of 347 notification messages which are sent in SSE [W3C-20150203] as a 348 response to the POST. 350 +--------------+ +--------------+ 351 | Subscriber | | Publisher | 352 |TCP connection| |TCP connection| 353 | (a) (b) | | (a) (b) | 354 +--------------+ +--------------+ 355 | RESTCONF POST (RPC:establish-subscription) | 356 |--------------------------------------------->| 357 | HTTP 200 OK (ID,URI)| 358 |<---------------------------------------------| 359 | |HTTP GET (URI) | 360 | |--------------------------------------------->| 361 | | HTTP 200 OK| 362 | |<---------------------------------------------| 363 | | SSE (notif-message)| 364 | |<---------------------------------------------| 365 | RESTCONF POST (RPC:modify-subscription) | | 366 |--------------------------------------------->| | 367 | | HTTP 200 OK| | 368 |<---------------------------------------------| | 369 | | SSE (subscription-modified)| 370 | |<------------------------------------------(c)| 371 | | SSE (notif-message)| 372 | |<---------------------------------------------| 373 | RESTCONF POST (RPC:delete-subscription) | | 374 |--------------------------------------------->| | 375 | | HTTP 200 OK| | 376 |<---------------------------------------------| | 377 | | | 378 | | 380 Figure 2: Dynamic with HTTP1.1 382 Additional requirements for dynamic subscriptions over HTTP1.1 383 include: 385 o All subscription state notifications from a publisher MUST be 386 returned in a separate SSE message used by the subscription to 387 which the state change refers. 389 o Subscription RPCs MUST NOT use the TCP connection currently 390 providing notification messages for that subscription. 392 o In addition to an RPC response for a "modify-subscription" RPC 393 traveling over (a), a "subscription-modified" state change 394 notification must be sent within stream (b). This allows the 395 receiver to know exactly when the new terms of the subscription 396 have been applied to the notification messages. See arrow (c). 398 Open question, should we just eliminate this possibility of HTTP1.1 399 for subscriptions? It would make the design simpler. 401 4. Configured Subscription 403 With a configured subscription, all information needed to establish a 404 secure relationship with that receiver is available on the publisher. 405 With this information, the publisher will establish a secure 406 transport connection with the receiver and then begin pushing 407 notification messages to the receiver. Since RESTCONF might not 408 exist on the receiver, it is not desirable to require that subscribed 409 content be pushed with any dependency on RESTCONF. Therefore in 410 place of RESTCONF, an HTTP2 Client connection must be established 411 with an HTTP2 Server located on the receiver. Notification messages 412 will then be sent as part of an extended HTTP POST to the receiver. 414 4.1. Transport Connectivity 416 Configured subscriptions MUST only be connected over HTTP2 via a 417 client session initiated from the publisher. Following are the 418 conditions which MUST be met before estabishing a new HTTP2 419 connection with a receiver: 421 o a configured subscription has a receiver in the CONNECTING state 422 as described in [I-D.draft-ietf-netconf-subscribed-notifications], 423 section 2.5.1., 425 o the transport configured for that subscription is HTTP2, 427 o there are state change notifications or notification messages 428 pending for that receiver, and 430 o no HTTP2 transport session exists to that receiver, 432 If the above conditions are met, then the publisher MUST initiate a 433 transport session via RESTCONF call home [RFC8071], section 4.1 to 434 that receiver. HTTP2 only communications must be used as per 435 [RFC7540], Section 3.3 when the HTTP session over TLS [RFC5246]. and 436 [RFC7540], Section 3.4 when transporting cleartext over TCP. Note 437 that a subscriber SHOULD establish over TLS in order to secure the 438 content in transit. 440 If the RESTCONF call home fails because the publisher receives 441 receiver credentials which are subsequently declined per [RFC8071], 442 Section 4.1, step S5 authentication, then that receiver MUST be 443 placed into the TIMEOUT state. 445 If the call home fails to establish for any other reason, the 446 publisher MUST NOT progress the receiver to the ACTIVE state. 447 Additionally, the publisher SHOULD place the receiver into the 448 TIMEOUT state after a predetermined number of either failed call home 449 attempts or remote transport session termination by the receiver. 451 4.2. Call Flow 453 With HTTP2 connectivity established, a POST of each new 454 "subscription-started" state change notification messages will be 455 addressed to HTTP augmentation code on the receiver capable of 456 accepting and acknowleding to subscription state change 457 notifications. Until the "HTTP 200 OK" at point (c) of Figure 3 for 458 each the "subscription-started" state change notification, a 459 publisher MUST NOT progress the receiver to the ACTIVE state. In 460 other words, is at point (c) which indicates that the receiver is 461 ready for the delivery of subscribed content. At this point a 462 notification-messages including subscribed content may be placed onto 463 an HTTP2 stream for that subscription. 465 +------------+ +------------+ 466 | Receiver | | Publisher | 467 |HTTP2 Stream| |HTTP2 Stream| 468 | (a) (b) | | (a) (b) | 469 +------------+ +------------+ 470 |HTTP Post Headers, Data (subscription-started)| 471 |<---------------------------------------------| 472 | HTTP 200 OK | 473 |-------------------------------------------->(c) 474 | | HTTP Post Headers, Data (notif-message)| 475 | |<---------------------------------------------| 476 | | HTTP Data (notif-message)| 477 | |<---------------------------------------------| 478 | | HTTP Data (sub-terminated)| 479 | |<---------------------------------------------| 480 | |HTTP 200 OK | 481 | |--------------------------------------------->| 483 Figure 3: Configured over HTTP2 485 Additional requirements for configured subscriptions over HTTP2 486 include: 488 o A unique HTTP2 stream MAY be used for each subscription. 490 o A single HTTP2 stream MUST NOT be used for subscriptions with 491 different DSCP values. 493 o All subscription state notifications from a publisher MUST be 494 returned in a separate HTTP Data frame within the HTTP2 stream 495 used by the subscription to which the state change refers. 497 o An HTTP end of stream message MUST not be sent until all 498 subscriptions using that HTTP2 stream have completed. 500 5. QoS Treatment 502 To meet subscription quality of service promises, the publisher MUST 503 take any existing subscription "dscp" and apply it to the DSCP 504 marking in the IP header. 506 In addition, where HTTP2 transport is available to a notification 507 message queued for transport to a receiver, the publisher MUST: 509 o take any existing subscription "priority" and copy it into the 510 HTTP2 stream priority, and 512 o take any existing subscription "dependency" and map the HTTP2 513 stream for the parent subscription into the HTTP2 stream 514 dependency. 516 6. Mandatory JSON and datastore support 518 A publisher supporting [I-D.ietf-netconf-yang-push] MUST support the 519 "operational" datastore as defined by [RFC8342]. 521 The "encode-json" feature of 522 [I-D.draft-ietf-netconf-subscribed-notifications] is mandatory to 523 support. This indicates that JSON is a valid encoding for RPCs, 524 state change notifications, and subscribed content. 526 7. Notification Messages 528 Notification messages transported over HTTP will be encoded using 529 one-way operation schema defined within [RFC5277], section 4. 531 8. YANG Tree 533 The YANG model defined in Section 9 has one leaf augmented into four 534 places of [I-D.draft-ietf-netconf-subscribed-notifications], plus two 535 identities. As the resulting full tree is large, it will only be 536 inserted at later stages of this document. 538 9. YANG module 540 This module references 541 [I-D.draft-ietf-netconf-subscribed-notifications]. 543 file "ietf-http-subscribed-notifications@2018-05-01.yang" 544 module ietf-http-subscribed-notifications { 545 yang-version 1.1; 546 namespace 547 "urn:ietf:params:xml:ns:yang:ietf-http-subscribed-notifications"; 549 prefix hsn; 551 import ietf-subscribed-notifications { 552 prefix sn; 553 } 554 import ietf-yang-types { 555 prefix yang; 556 } 558 organization "IETF NETCONF (Network Configuration) Working Group"; 559 contact 560 "WG Web: 561 WG List: 563 Editor: Eric Voit 564 566 Editor: Alexander Clemm 567 569 Editor: Einar Nilsen-Nygaard 570 "; 572 description 573 "Defines HTTP variants as a supported transports for subscribed 574 event notifications. 576 Copyright (c) 2018 IETF Trust and the persons identified as authors 577 of the code. All rights reserved. 579 Redistribution and use in source and binary forms, with or without 580 modification, is permitted pursuant to, and subject to the license 581 terms contained in, the Simplified BSD License set forth in Section 582 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 583 (https://trustee.ietf.org/license-info). 585 This version of this YANG module is part of RFC XXXX; see the RFC 586 itself for full legal notices."; 588 revision 2018-05-01 { 589 description 590 "Initial version"; 591 reference 592 "RFC XXXX: RESTCONF and HTTP Transport for Event Notifications"; 593 } 595 identity http2 { 596 base sn:transport; 597 base sn:inline-address; 598 base sn:configurable-encoding; 599 description 600 "HTTP2 is used a transport for notification messages and state 601 change notifications."; 602 } 604 identity http1.1 { 605 base sn:transport; 606 base sn:inline-address; 607 base sn:configurable-encoding; 608 description 609 "HTTP1.1 is used a transport for notification messages and state 610 change notifications."; 611 } 613 grouping uri { 614 description 615 "Provides a reusable description of a URI."; 616 leaf uri { 617 config false; 618 type yang:uri; 619 description 620 "Location of a subscription specific URI on the publisher."; 621 } 622 } 624 augment "/sn:establish-subscription/sn:output" { 625 description 626 "This augmentation allows HTTP specific parameters for a 627 response to a publisher's subscription request."; 628 uses uri; 629 } 631 augment "/sn:subscriptions/sn:subscription/sn:target" { 632 description 633 "This augmentation allows HTTP specific parameters to be 634 exposed for a subscription."; 635 uses uri; 636 } 638 augment "/sn:subscription-started/sn:target" { 639 description 640 "This augmentation allows HTTP specific parameters to be included 641 part of the notification that a subscription has started."; 642 uses uri; 643 } 645 augment "/sn:subscription-modified/sn:target" { 646 description 647 "This augmentation allows HTTP specific parameters to be included 648 part of the notification that a subscription has been modified."; 649 uses uri; 650 } 652 /* need to add a constraint that HTTP1.1 not allowed for 653 configured subscriptions - needs the right syntax below... 655 augment "sn:subscriptions/sn:subscription/sn:protocol" { 656 when '../sn:configured-subscription-state' 657 must ' protocol <> "http1.1"' { 658 error-message "HTTP1.1 not used for configured subscriptions"; 659 } 660 } 662 */ 664 } 665 667 10. IANA Considerations 669 This document registers the following namespace URI in the "IETF XML 670 Registry" [RFC3688]: 672 URI: urn:ietf:params:xml:ns:yang:ietf-http-subscribed-notifications 673 Registrant Contact: The IESG. 674 XML: N/A; the requested URI is an XML namespace. 676 This document registers the following YANG module in the "YANG Module 677 Names" registry [RFC6020]: 679 Name: ietf-http-subscribed-notifications 680 Namespace: urn:ietf:params:xml:ns:yang:ietf-http-subscribed- 681 notifications 682 Prefix: hsn 683 Reference: RFC XXXX: RESTCONF and HTTP Transport for Event 684 Notifications 686 11. Security Considerations 688 The YANG module specified in this document defines a schema for data 689 that is designed to be accessed via network management transports 690 such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF 691 layer is the secure transport layer, and the mandatory-to-implement 692 secure transport is Secure Shell (SSH) [RFC6242]. The lowest 693 RESTCONF layer is HTTPS, and the mandatory-to-implement secure 694 transport is TLS [RFC5246]. 696 The one new data node introduced in this YANG module may be 697 considered sensitive or vulnerable in some network environments. It 698 is thus important to control read access (e.g., via get, get-config, 699 or notification) to this data nodes. These are the subtrees and data 700 nodes and their sensitivity/vulnerability: 702 Container: "/subscriptions" 704 o "uri": leaf will show where subscribed resources might be located 705 on a publisher. Access control must be set so that only someone 706 with proper access permissions, and perhaps even HTTP session has 707 the ability to access this resource. 709 One or more publishers of configured subscriptions could be used to 710 overwhelm a receiver which doesn't even support subscriptions. There 711 are two protections needing support on a publisher. First, 712 notification messages for configured subscriptions MUST only be 713 transmittable over encrypted transports. Clients which do not want 714 pushed content need only terminate or refuse any transport sessions 715 from the publisher. Second, the HTTP transport augmentation on the 716 receiver must send an HTTP 200 OK to a subscription started 717 notification before the publisher starts streaming any subscribed 718 content. 720 One or more publishers could overwhelm a receiver which is unable to 721 control or handle the volume of Event Notifications received. In 722 deployments where this might be a concern, HTTP2 transport such as 723 HTTP2) should be selected. 725 The NETCONF Authorization Control Model [RFC6536] SHOULD be used to 726 control and restrict authorization of subscription configuration. 728 12. Acknowledgments 730 We wish to acknowledge the helpful contributions, comments, and 731 suggestions that were received from: Ambika Prasad Tripathy, Alberto 732 Gonzalez Prieto, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent 733 Watsen, Michael Scharf, and Guangying Zheng. 735 13. References 737 13.1. Normative References 739 [GRPC] "RPC framework that runs over HTTP2", August 2017, 740 . 742 [I-D.draft-ietf-netconf-subscribed-notifications] 743 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 744 and E. Nilsen-Nygaard, "Custom Subscription to Event 745 Streams", draft-ietf-netconf-subscribed-notifications-13 746 (work in progress), April 2018. 748 [I-D.ietf-netconf-yang-push] 749 Clemm, A., Voit, E., Gonzalez Prieto, A., Prasad Tripathy, 750 A., Nilsen-Nygaard, E., Bierman, A., and B. Lengyel, 751 "Subscribing to YANG datastore push updates", March 2017, 752 . 755 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 756 Requirement Levels", BCP 14, RFC 2119, 757 DOI 10.17487/RFC2119, March 1997, 758 . 760 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 761 DOI 10.17487/RFC3688, January 2004, 762 . 764 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 765 (TLS) Protocol Version 1.2", RFC 5246, 766 DOI 10.17487/RFC5246, August 2008, 767 . 769 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 770 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 771 . 773 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 774 the Network Configuration Protocol (NETCONF)", RFC 6020, 775 DOI 10.17487/RFC6020, October 2010, 776 . 778 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 779 and A. Bierman, Ed., "Network Configuration Protocol 780 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 781 . 783 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 784 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 785 . 787 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 788 Layer Security (TLS) and Datagram Transport Layer Security 789 (DTLS) Heartbeat Extension", RFC 6520, 790 DOI 10.17487/RFC6520, February 2012, 791 . 793 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 794 Protocol (NETCONF) Access Control Model", RFC 6536, 795 DOI 10.17487/RFC6536, March 2012, 796 . 798 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 799 Protocol (HTTP/1.1): Message Syntax and Routing", 800 RFC 7230, DOI 10.17487/RFC7230, June 2014, 801 . 803 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 804 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 805 DOI 10.17487/RFC7540, May 2015, 806 . 808 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 809 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 810 . 812 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 813 and R. Wilton, "Network Management Datastore Architecture 814 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 815 . 817 [W3C-20150203] 818 "Server-Sent Events, World Wide Web Consortium CR CR- 819 eventsource-20121211", February 2015, 820 . 822 13.2. Informative References 824 [I-D.draft-ietf-netconf-netconf-event-notifications] 825 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 826 Nilsen-Nygaard, E., and A. Tripathy, "NETCONF support for 827 event notifications", May 2018, 828 . 831 [I-D.draft-ietf-netconf-nmda-restconf] 832 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 833 and R. Wilton, "RESTCONF Extensions to Support the Network 834 Management Datastore Architecture", April 2018, 835 . 838 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 839 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 840 DOI 10.17487/RFC7231, June 2014, 841 . 843 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 844 for Subscription to YANG Datastores", RFC 7923, 845 DOI 10.17487/RFC7923, June 2016, 846 . 848 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 849 RFC 8071, DOI 10.17487/RFC8071, February 2017, 850 . 852 Appendix A. RESTCONF over GRPC 854 An initial goal for this document was to support [GRPC] transport 855 seamlessly without any mapping or extra layering. However there is 856 an incompatibility of RESTCONF and GRPC. RESTCONF uses HTTP GET, and 857 GRPC uses HTTP2's POST rather than GET. As GET is used across 858 RESTCONF for things like capabilities exchange, a seamless mapping 859 depends on specification changes outside the scope of this document. 860 If/when GRPC supports GET, or RESTCONF is updated to support POST, 861 this should be revisited. It is hoped that the resulting fix will be 862 transparent to this document. 864 Appendix B. Examples 866 This section is non-normative. To allow easy comparison, this 867 section mirrors the functional examples shown with NETCONF over XML 868 within [I-D.draft-ietf-netconf-netconf-event-notifications]. In 869 addition, HTTP2 vs HTTP1.1 headers are not shown as the contents of 870 the JSON encoded objects are identical within. 872 B.1. Dynamic Subscriptions 874 B.1.1. Establishing Dynamic Subscriptions 876 The following figure shows two successful "establish-subscription" 877 RPC requests as per 878 [I-D.draft-ietf-netconf-subscribed-notifications]. The first request 879 is given a subscription identifier of 22, the second, an identifier 880 of 23. 882 +------------+ +-----------+ 883 | Subscriber | | Publisher | 884 +------------+ +-----------+ 885 | | 886 |establish-subscription | 887 |------------------------------>| (a) 888 | HTTP 200 OK, id#22, URI#1 | 889 |<------------------------------| (b) 890 |POST (URI#1) | 891 |------------------------------>| (c) 892 | HTTP 200 OK,notif-mesg (id#22)| 893 |<------------------------------| 894 | | 895 | | 896 |stablish-subscription | 897 |------------------------------>| 898 | HTTP 200 OK, id#23, URI#2| 899 |<------------------------------| 900 |POST (URI#2) | 901 |------------------------------>| 902 | | 903 | | 904 | notif-mesg (id#22)| 905 |<------------------------------| 906 | HTTP 200 OK,notif-mesg (id#23)| 907 |<------------------------------| 908 | | 910 Figure 4: Multiple subscriptions over RESTCONF/HTTP 912 To provide examples of the information being transported, example 913 messages for interactions in Figure 4 are detailed below: 915 POST /restconf/operations/subscriptions:establish-subscription 917 { 918 "establish-subscription": { 919 "stream": { 920 "ietf-netconf-subscribed-notifications" : "NETCONF" 921 }, 922 "stream-xpath-filter": "/ex:foo/", 923 "dscp": "10" 924 } 925 } 927 Figure 5: establish-subscription request (a) 929 As publisher was able to fully satisfy the request, the publisher 930 sends the subscription identifier of the accepted subscription, and 931 the URI: 933 HTTP status code - 200 935 { 936 "identifier": "22", 937 "uri": "/subscriptions/22" 938 } 940 Figure 6: establish-subscription success (b) 942 Upon receipt of the successful response, the subscriber POSTs to the 943 provided URI to start the flow of notification messages. When the 944 publisher receives this, the subscription becomes ACTIVE (c). 946 POST /restconf/operations/subscriptions/22 948 Figure 7: establish-subscription subsequent POST 950 While not shown in Figure 4, if the publisher had not been able to 951 fully satisfy the request, or subscriber has no authorization to 952 establish the subscription, the publisher would have sent an RPC 953 error response. For instance, if the "dscp" value of 10 asserted by 954 the subscriber in Figure 5 proved unacceptable, the publisher may 955 have returned: 957 HTTP status code - 406 959 { "ietf-restconf:errors" : { 960 "error" : [ 961 { 962 "error-type": "application", 963 "error-tag": "operation-failed", 964 "error-severity": "error", 965 "error-app-tag": 966 "ietf-subscribed-notifications:dscp-unavailable" 967 } 968 ] 969 } 970 } 972 Figure 8: an unsuccessful establish subscription 974 The subscriber can use this information in future attempts to 975 establish a subscription. 977 B.1.2. Modifying Dynamic Subscriptions 979 An existing subscription may be modified. The following exchange 980 shows a negotiation of such a modification via several exchanges 981 between a subscriber and a publisher. This negotiation consists of a 982 failed RPC modification request/response, followed by a successful 983 one. 985 +------------+ +-----------+ 986 | Subscriber | | Publisher | 987 +------------+ +-----------+ 988 | | 989 | notification message (id#23)| 990 |<-----------------------------| 991 | | 992 |modify-subscription (id#23) | 993 |----------------------------->| (d) 994 | HTTP 406 error (with hint)| 995 |<-----------------------------| (e) 996 | | 997 |modify-subscription (id#23) | 998 |----------------------------->| 999 | HTTP 200 OK | 1000 |<-----------------------------| 1001 | | 1002 | notif-mesg (id#23)| 1003 |<-----------------------------| 1004 | | 1006 Figure 9: Interaction model for successful subscription modification 1008 If the subscription being modified in Figure 9 is a datastore 1009 subscription as per [I-D.ietf-netconf-yang-push], the modification 1010 request made in (d) may look like that shown in Figure 10. As can be 1011 seen, the modifications being attempted are the application of a new 1012 xpath filter as well as the setting of a new periodic time interval. 1014 POST /restconf/operations/subscriptions:modify-subscription 1016 { 1017 "modify-subscription": { 1018 "identifier": "23", 1019 { 1020 "ietf-yang-push": "datastore-xpath-filter": 1021 "/interfaces-state/interface/oper-status" 1022 }, 1023 { 1024 "ietf-yang-push": "periodic": "500" 1025 } 1026 } 1027 } 1029 Figure 10: Subscription modification request (c) 1031 If the publisher can satisfy both changes, the publisher sends a 1032 positive result for the RPC. If the publisher cannot satisfy either 1033 of the proposed changes, the publisher sends an RPC error response 1034 (e). The following is an example RPC error response for (e) which 1035 includes a hint. This hint is an alternative time period value which 1036 might have resulted in a successful modification: 1038 HTTP status code - 406 1040 { "ietf-restconf:errors" : { 1041 "error" : [ 1042 "error-type": "application", 1043 "error-tag": "operation-failed", 1044 "error-severity": "error", 1045 "error-app-tag": { 1046 "ietf-yang-push": "ietf-yang-push:period-unsupported" 1047 }, 1048 "error-info": { 1049 "ietf-yang-push": 1050 "modify-subscription-datastore-error-info": { 1051 "period-hint": "3000" 1052 } 1053 } 1054 ] 1055 } 1056 } 1058 Figure 11: Modify subscription failure with Hint (e) 1060 B.1.3. Deleting Dynamic Subscriptions 1062 The following demonstrates deleting a subscription. This 1063 subscription may have been to either a stream or a datastore. 1065 POST /restconf/operations/subscriptions:delete-subscription 1067 { 1068 "delete-subscription": { 1069 "identifier": "22" 1070 } 1071 } 1073 Figure 12: Delete subscription 1075 If the publisher can satisfy the request, the publisher replies with 1076 success to the RPC request. 1078 If the publisher cannot satisfy the request, the publisher sends an 1079 error-rpc element indicating the modification didn't work. Figure 13 1080 shows a valid response for existing valid subscription identifier, 1081 but that subscription identifier was created on a different transport 1082 session: 1084 HTTP status code - 406 1086 { 1087 "ietf-restconf:errors" : { 1088 "error" : [ 1089 "error-type": "application", 1090 "error-tag": "operation-failed", 1091 "error-severity": "error", 1092 "error-app-tag": 1093 "ietf-subscribed-notifications:no-such-subscription" 1094 ] 1095 } 1096 } 1098 Figure 13: Unsuccessful delete subscription 1100 B.2. Configured Subscriptions 1102 Configured subscriptions may be established, modified, and deleted 1103 using configuration operations against the top-level subtree of 1104 [I-D.draft-ietf-netconf-subscribed-notifications] or 1105 [I-D.ietf-netconf-yang-push]. 1107 In this section, we present examples of how to manage the 1108 configuration subscriptions using a HTTP2 client. 1110 B.2.1. Creating Configured Subscriptions 1112 For subscription creation via configuration operations, a RESTCONF 1113 client may send: 1115 POST /restconf/operations/subscriptions/ 1117 { 1118 "edit-config": { 1119 "target": { 1120 "running": null 1121 }, 1122 "default-operation": "none", 1123 "config": { 1124 "subscriptions": { 1125 "subscription": { 1126 "identifier": "22", 1127 "transport": "HTTP2", 1128 "stream": "NETCONF", 1129 "receivers": { 1130 "receiver": { 1131 "name": "receiver1", 1132 "address": "1.2.3.4" 1133 } 1134 } 1135 } 1136 } 1137 } 1138 } 1139 } 1141 Figure 14: Create a configured subscription 1143 If the request is accepted, the publisher will indicate this. If the 1144 request is not accepted because the publisher cannot serve it, no 1145 configuration is changed. In this case the publisher may reply: 1147 HTTP status code - 406 1149 { 1150 "ietf-restconf:errors" : { 1151 "error" : [ 1152 "error-type": "application", 1153 "error-tag": "resource-denied", 1154 "error-severity": "error", 1155 "error-message": { 1156 "@lang": "en", 1157 "#text": "Temporarily the publisher cannot serve this 1158 subscription due to the current workload." 1159 } 1160 ] 1161 } 1162 } 1164 Figure 15: Response to a failed configured subscription establishment 1166 After a subscription has been created and been verified as VALID, 1167 HTTP2 connectivity to each receiver will be established if that 1168 connectivity does not already exist. 1170 The following figure shows the interaction model for the successful 1171 creation of a configured subscription. 1173 +----------+ +-----------+ +---------+ 1174 |Config Ops| | Publisher | | 1.2.3.4 | 1175 +----------+ +-----------+ +---------+ 1176 | | | 1177 | Capability Exchange | | 1178 |<-------------------------->| | 1179 | | | 1180 | | | 1181 | Edit-config | | 1182 |--------------------------->| | 1183 | RPC Reply: OK | | 1184 |<---------------------------| | 1185 | | Call Home | 1186 | |<-------------->| 1187 | | | 1188 | | subscription- | 1189 | | started | 1190 | |--------------->| 1191 | | | 1192 | | notification | 1193 | | message | 1194 | |--------------->| 1196 Figure 16: Interaction model for configured subscription 1197 establishment 1199 B.2.2. Modifying Configured Subscriptions 1201 Configured subscriptions can be modified using configuration 1202 operations against the top-level container "/subscriptions". 1204 For example, the subscription established in the previous section 1205 could be modified as follows, here a adding a second receiver: 1207 POST /restconf/operations/subscriptions 1209 { 1210 "edit-config": { 1211 "target": { 1212 "running": null 1213 }, 1214 "config": { 1215 "subscriptions": { 1216 "subscription": { 1217 "identifier": "1922", 1218 "receivers": { 1219 "receiver": { 1220 "name": "receiver2", 1221 "address": "1.2.3.5" 1222 } 1223 } 1224 } 1225 } 1226 } 1227 } 1228 } 1230 Figure 17: Modify configured subscription 1232 If the request is accepted, the publisher will indicate success. The 1233 result is that the interaction model described in Figure 16 may be 1234 extended as follows. 1236 +----------+ +-----------+ +---------+ +---------+ 1237 |Config Ops| | Publisher | | 1.2.3.4 | | 1.2.3.5 | 1238 +----------+ +-----------+ +---------+ +---------+ 1239 | | notification | | 1240 | | message | | 1241 | |--------------->| | 1242 | Edit-config | | | 1243 |--------------------------->| | | 1244 | RPC Reply: OK | | | 1245 |<---------------------------| | | 1246 | | subscription- | | 1247 | | started | | 1248 | |---------------------------->| 1249 | | | | 1250 | | notification | | 1251 | | message | | 1252 | |--------------->| | 1253 | |---------------------------->| 1254 | | | | 1256 Figure 18: Interaction model for configured subscription modification 1258 Note in the above that in the specific example above, modifying a 1259 configured subscription actually resulted in "subscription-started" 1260 notification. And because of existing HTTP2 connectivity, no 1261 additional call home was needed. Also note that if the edit of the 1262 configuration had impacted the filter, a separate modify-subscription 1263 would have been required for the original receiver. 1265 B.2.3. Deleting Configured Subscriptions 1267 Configured subscriptions can be deleted using configuration 1268 operations against the top-level container "/subscriptions". 1269 Deleting the subscription above would result in the following flow 1270 impacting all active receivers. 1272 +----------+ +-----------+ +---------+ +---------+ 1273 |Config Ops| | Publisher | | 1.2.3.4 | | 1.2.3.5 | 1274 +----------+ +-----------+ +---------+ +---------+ 1275 | | | | 1276 | | notification | | 1277 | | message | | 1278 | |--------------->| | 1279 | |---------------------------->| 1280 | | | | 1281 | Edit-config | | | 1282 |--------------------------->| | | 1283 | RPC Reply: OK | | | 1284 |<---------------------------| | | 1285 | | subscription- | | 1286 | | terminated | | 1287 | |--------------->| | 1288 | |---------------------------->| 1289 | | | | 1291 Figure 19: Interaction model for configured subscription deletion 1293 B.3. Subscription State Notifications 1295 A publisher will send subscription state notifications according to 1296 the definitions within 1297 [I-D.draft-ietf-netconf-subscribed-notifications]). 1299 B.3.1. subscription-started and subscription-modified 1301 A "subscription-started" encoded in JSON would look like: 1303 { 1304 "ietf-restconf:notification" : { 1305 "eventTime": "2007-09-01T10:00:00Z", 1306 "ietf-subscribed-notifications:subscription-started": { 1307 "identifier": "39", 1308 "transport": "HTTP2", 1309 "stream-xpath-filter": "/ex:foo", 1310 "stream": { 1311 "ietf-netconf-subscribed-notifications" : "NETCONF" 1312 } 1313 } 1314 } 1315 } 1317 Figure 20: subscription-started subscription state notification 1319 The "subscription-modified" is identical to Figure 20, with just the 1320 word "started" being replaced by "modified". 1322 B.3.2. subscription-completed, subscription-resumed, and replay- 1323 complete 1325 A "subscription-completed" would look like: 1327 { 1328 "ietf-restconf:notification" : { 1329 "eventTime": "2007-09-01T10:00:00Z", 1330 "ietf-subscribed-notifications:subscription-completed": { 1331 "identifier": "39", 1332 } 1333 } 1334 } 1336 Figure 21: subscription-completed notification in JSON 1338 The "subscription-resumed" and "replay-complete" are virtually 1339 identical, with "subscription-completed" simply being replaced by 1340 "subscription-resumed" and "replay-complete". 1342 B.3.3. subscription-terminated and subscription-suspended 1344 A "subscription-terminated" would look like: 1346 { 1347 "ietf-restconf:notification" : { 1348 "eventTime": "2007-09-01T10:00:00Z", 1349 "ietf-subscribed-notifications:subscription-terminated": { 1350 "identifier": "39", 1351 "error-id": "suspension-timeout" 1352 } 1353 } 1354 } 1356 Figure 22: subscription-terminated subscription state notification 1358 The "subscription-suspended" is virtually identical, with 1359 "subscription-terminated" simply being replaced by "subscription- 1360 suspended". 1362 Appendix C. Changes between revisions 1364 (To be removed by RFC editor prior to publication) 1366 v04 - v05 1368 o Error mechanisms updated to match embedded RESTCONF mechanisms 1370 o Restructured format and sections of document. 1372 o Added a YANG data model for HTTP specific parameters. 1374 o Mirrored the examples from the NETCONF transport draft to allow 1375 easy comparison. 1377 v03 - v04 1379 o Draft not fully synched to new version of subscribed-notifications 1380 yet. 1382 o References updated 1384 v02 - v03 1386 o Event notification reframed to notification message. 1388 o Tweaks to wording/capitalization/format. 1390 v01 - v02 1392 o Removed sections now redundant with 1393 [I-D.draft-ietf-netconf-subscribed-notifications] and 1394 [I-D.ietf-netconf-yang-push] such as: mechanisms for subscription 1395 maintenance, terminology definitions, stream discovery. 1397 o 3rd party subscriptions are out-of-scope. 1399 o SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions 1401 o Timeframes for event tagging are self-defined. 1403 o Clean-up of wording, references to terminology, section numbers. 1405 v00 - v01 1407 o Removed the ability for more than one subscription to go to a 1408 single HTTP2 stream. 1410 o Updated call flows. Extensively. 1412 o SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions 1414 o HTTP is not used to determine that a receiver has gone silent and 1415 is not Receiving Event Notifications 1417 o Many clean-ups of wording and terminology 1419 Authors' Addresses 1421 Eric Voit 1422 Cisco Systems 1424 Email: evoit@cisco.com 1426 Einar Nilsen-Nygaard 1427 Cisco Systems 1429 Email: einarnn@cisco.com 1431 Alexander Clemm 1432 Huawei 1434 Email: ludwig@clemm.org 1436 Andy Bierman 1437 YumaWorks 1439 Email: andy@yumaworks.com