idnits 2.17.1 draft-ietf-netconf-restconf-notif-06.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 214 has weird spacing: '...ription estab...' == Line 218 has weird spacing: '...ription res...' == Line 233 has weird spacing: '... stream esta...' == Line 236 has weird spacing: '...ription ret...' == Line 238 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 (June 18, 2018) is 2111 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: A later version (-26) exists of draft-ietf-netconf-subscribed-notifications-13 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7540 (Obsoleted by RFC 9113) -- Possible downref: Non-RFC (?) normative reference: ref. 'W3C-20150203' -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 4 errors (**), 0 flaws (~~), 10 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF E. Voit 3 Internet-Draft R. Rahman 4 Intended status: Standards Track E. Nilsen-Nygaard 5 Expires: December 20, 2018 Cisco Systems 6 A. Clemm 7 Huawei 8 A. Bierman 9 YumaWorks 10 June 18, 2018 12 RESTCONF and HTTP Transport for Event Notifications 13 draft-ietf-netconf-restconf-notif-06 15 Abstract 17 This document defines RESTCONF, HTTP2, and HTTP1.1 bindings for the 18 transport of subscription requests and corresponding push updates. 19 Being subscribed may be either publisher defined event streams or 20 nodes/subtrees of YANG Datastores. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on December 20, 2018. 39 Copyright Notice 41 Copyright (c) 2018 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 3. Dynamic Subscription . . . . . . . . . . . . . . . . . . . . 3 59 3.1. Transport Connectivity . . . . . . . . . . . . . . . . . 4 60 3.2. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 4 61 3.3. RESTCONF RPCs and HTTP Status Codes . . . . . . . . . . . 4 62 3.4. Call Flow for HTTP2 . . . . . . . . . . . . . . . . . . . 6 63 3.5. Call flow for HTTP1.1 . . . . . . . . . . . . . . . . . . 8 64 4. Configured Subscription . . . . . . . . . . . . . . . . . . . 10 65 4.1. Transport Connectivity . . . . . . . . . . . . . . . . . 10 66 4.2. Call Flow . . . . . . . . . . . . . . . . . . . . . . . . 11 67 5. QoS Treatment . . . . . . . . . . . . . . . . . . . . . . . . 12 68 6. Mandatory JSON and datastore support . . . . . . . . . . . . 12 69 7. Notification Messages . . . . . . . . . . . . . . . . . . . . 12 70 8. YANG Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 12 71 9. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 13 72 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 73 11. Security Considerations . . . . . . . . . . . . . . . . . . . 15 74 12. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 16 75 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 16 76 13.1. Normative References . . . . . . . . . . . . . . . . . . 17 77 13.2. Informative References . . . . . . . . . . . . . . . . . 18 78 Appendix A. RESTCONF over GRPC . . . . . . . . . . . . . . . . . 19 79 Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . 19 80 B.1. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 19 81 B.1.1. Establishing Dynamic Subscriptions . . . . . . . . . 19 82 B.1.2. Modifying Dynamic Subscriptions . . . . . . . . . . . 22 83 B.1.3. Deleting Dynamic Subscriptions . . . . . . . . . . . 23 84 B.2. Configured Subscriptions . . . . . . . . . . . . . . . . 24 85 B.2.1. Creating Configured Subscriptions . . . . . . . . . . 25 86 B.2.2. Modifying Configured Subscriptions . . . . . . . . . 27 87 B.2.3. Deleting Configured Subscriptions . . . . . . . . . . 29 88 B.3. Subscription State Notifications . . . . . . . . . . . . 30 89 B.3.1. subscription-started and subscription-modified . . . 30 90 B.3.2. subscription-completed, subscription-resumed, and 91 replay-complete . . . . . . . . . . . . . . . . . . . 31 92 B.3.3. subscription-terminated and subscription-suspended . 31 93 Appendix C. Changes between revisions . . . . . . . . . . . . . 32 94 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33 96 1. Introduction 98 Mechanisms to support event subscription and push are defined in 99 [I-D.draft-ietf-netconf-subscribed-notifications]. Enhancements to 100 [I-D.draft-ietf-netconf-subscribed-notifications] which enable YANG 101 datastore subscription and push are defined in 102 [I-D.ietf-netconf-yang-push]. This document provides a transport 103 specification for these protocols over RESTCONF [RFC8040] and HTTP. 104 Driving these requirements is [RFC7923]. 106 The streaming of notifications encapsulating the resulting 107 information push can be done with either HTTP1.1 [RFC7231] or HTTP2 108 [RFC7540]. 110 2. Terminology 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 114 document are to be interpreted as described in RFC 2119 [RFC2119]. 116 The following terms use the definitions from 117 [I-D.draft-ietf-netconf-subscribed-notifications]: configured 118 subscription, dynamic subscription, event stream, notification 119 message, publisher, receiver, subscriber, and subscription. 121 Other terms reused include datastore, which is defined in [RFC8342], 122 and HTTP2 stream which maps to the definition of "stream" within 123 [RFC7540], Section 2. 125 [ note to the RFC Editor - please replace XXXX within this document 126 with the number of this document ] 128 3. Dynamic Subscription 130 This section provides specifics on how to establish and maintain 131 dynamic subscriptions over HTTP 1.1 and HTTP2 via signaling messages 132 transported over RESTCONF [RFC8040]. Subscribing to event streams is 133 accomplished in this way via a RESTCONF POST into RPCs defined within 134 [I-D.draft-ietf-netconf-subscribed-notifications] Section 2.4. YANG 135 datastore subscription is accomplished via augmentations to 136 [I-D.draft-ietf-netconf-subscribed-notifications] as described within 137 [I-D.ietf-netconf-yang-push] Section 4.4. 139 Common across all HTTP based dynamic subscriptions is that a POST 140 needs to be made against a specific URI on the Publisher. 141 Subscribers cannot pre-determine the URI against which a subscription 142 might exist on a publisher, as the URI will only exist after the 143 "establish-subscription" has been accepted. The subscription URI 144 will be determined and sent as part of the response to the 145 "establish-subscription", and a subsequent POST to this URI will be 146 done in order to start the flow of notification messages back to the 147 subscriber. A subscription does not move to the active state as per 148 Section 2.4.1. of [I-D.draft-ietf-netconf-subscribed-notifications] 149 until the POST is received. 151 3.1. Transport Connectivity 153 For a dynamic subscription, where an HTTP client session doesn't 154 already exist, a new client session is initiated from the subscriber. 155 If the subscriber is unsure if HTTP2 is supported by the publisher, 156 HTTP1.1 will be used for initial messages, and these messages will 157 include an HTTP version upgrade request as per [RFC7230], 158 Section 6.7. If a publisher response indicates that HTTP2 is 159 supported, HTTP2 will be used between subscriber and publisher for 160 future HTTP interactions as per [RFC7540]. 162 A subscriber SHOULD establish the HTTP session over TLS [RFC5246] in 163 order to secure the content in transit. 165 Without the involvement of additional protocols, neither HTTP1.1 nor 166 HTTP2 sessions by themselves allow for a quick recognition of when 167 the communication path has been lost with the publisher. Where quick 168 recognition of the loss of a publisher is required, a subscriber 169 SHOULD connect over TLS [RFC5246], and use a TLS heartbeat [RFC6520] 170 to track HTTP session continuity. In the case where a TLS heartbeat 171 is included, it should be sent just from receiver to publisher. Loss 172 of the heartbeat MUST result in any subscription related TCP sessions 173 between those endpoints being torn down. A subscriber can then 174 attempt to re-establish. 176 3.2. Discovery 178 Subscribers can learn what event streams a RESTCONF server supports 179 by querying the "streams" container of ietf-subscribed- 180 notification.yang. Subscribers can learn what datastores a RESTCONF 181 server supports by following [I-D.draft-ietf-netconf-nmda-restconf]. 183 3.3. RESTCONF RPCs and HTTP Status Codes 185 Specific HTTP responses codes as defined in [RFC7231] section 6 will 186 indicate the result of RESTCONF RPC requests with publisher. An HTTP 187 status code of 200 is the proper response to any successful RPC 188 defined within [I-D.draft-ietf-netconf-subscribed-notifications] or 189 [I-D.ietf-netconf-yang-push]. 191 If a publisher fails to serve the RPC request for one of the reasons 192 indicated in [I-D.draft-ietf-netconf-subscribed-notifications] 193 Section 2.4.6 or [I-D.ietf-netconf-yang-push] Appendix A, this will 194 be indicated by "406" status code transported in the HTTP response. 196 When a "406" status code is returned, the RPC reply MUST include an 197 "rpc-error" element per [RFC8040] Section 7.1 with the following 198 parameter values: 200 o an "error-type" node of "application". 202 o an "error-tag" node of "operation-failed". 204 o an "error-app-tag" node with the value being a string that 205 corresponds to an identity associated with the error, as defined 206 in [I-D.draft-ietf-netconf-subscribed-notifications] section 2.4.6 207 for general subscriptions, and [I-D.ietf-netconf-yang-push] 208 Appendix A.1, for datastore subscriptions. The tag to use depends 209 on the RPC for which the error occurred. Viable errors for 210 different RPCs are as follows: 212 RPC select an identity with a base 213 ---------------------- ------------------------------ 214 establish-subscription establish-subscription-error 215 modify-subscription modify-subscription-error 216 delete-subscription delete-subscription-error 217 kill-subscription kill-subscription-error 218 resynch-subscription resynch-subscription-error 220 Each error identity will be inserted as the "error-app-tag" using 221 JSON encoding following the form :. An 222 example of such as valid encoding would be "ietf-subscribed- 223 notifications:no-such-subscription". 225 o In case of error responses to an "establish-subscription" or 226 "modify-subscription" request there is the option of including an 227 "error-info" node. This node may contain hints for parameter 228 settings that might lead to successful RPC requests in the future. 229 Following are the yang-data structures which may be returned: 231 establish-subscription returns hints in yang-data structure 232 ---------------------- ------------------------------------ 233 target: event stream establish-subscription-stream-error-info 234 target: datastore establish-subscription-datastore-error-info 236 modify-subscription returns hints in yang-data structure 237 ---------------------- ------------------------------------ 238 target: event stream modify-subscription-stream-error-info 239 target: datastore modify-subscription-datastore-error-info 241 The yang-data included within "error-info" SHOULD NOT include the 242 optional leaf "error-reason", as such a leaf would be redundant 243 with information that is already placed within the 244 "error-app-tag". 246 In case of an rpc error as a result of a "delete-subscription", a 247 "kill-subscription", or a "resynch-subscription" request, no 248 "error-info" needs to be included, as the "subscription-id" is 249 the only RPC input parameter and no hints regarding this RPC input 250 parameters need to be provided. 252 Note that "error-path" does not need to be included with the "rpc- 253 error" element, as subscription errors are generally not associated 254 with nodes in the datastore but with the choice of RPC input 255 parameters. 257 3.4. Call Flow for HTTP2 259 Requests to [I-D.draft-ietf-netconf-subscribed-notifications] or 260 [I-D.ietf-netconf-yang-push] augmented RPCs are sent on one or more 261 HTTP2 streams indicated by (a) in Figure 1. A successful "establish- 262 subscription" will result in an RPC response returned with both a 263 subscription identifier which uniquely identifies a subscription, as 264 well as a URI which uniquely identifies the location of subscription 265 on the publisher. This URI is defined via the "uri" leaf the Data 266 Model in Section 9. 268 An HTTP POST is then sent on a logically separate HTTP2 stream (b) to 269 the URI on the publisher. This initiates to initiate the flow of 270 notification messages which are sent in HTTP Data frames as a 271 response to the POST. In the case below, a newly established 272 subscription has its associated notification messages pushed over 273 HTTP2 stream (7). These notification messages are placed into a 274 HTTP2 Data frame (see [RFC7540] Section 6.1). 276 +------------+ +------------+ 277 | Subscriber | | Publisher | 278 |HTTP2 Stream| |HTTP2 Stream| 279 | (a) (b) | | (a) (b) | 280 +------------+ +------------+ 281 | RESTCONF POST (RPC:establish-subscription) | 282 |--------------------------------------------->| 283 | HTTP 200 OK (ID,URI)| 284 |<---------------------------------------------| 285 | (7)HTTP POST (URI) (7) 286 | |--------------------------------------------->| 287 | | HTTP 200 OK| 288 | |<---------------------------------------------| 289 | | HTTP Data (notif-message)| 290 | |<---------------------------------------------| 291 | RESTCONF POST (RPC:modify-subscription) | | 292 |--------------------------------------------->| | 293 | | HTTP 200 OK| | 294 |<---------------------------------------------| | 295 | | HTTP Data (subscription-modified)| 296 | |<------------------------------------------(c)| 297 | | HTTP Data (notif-message)| 298 | |<---------------------------------------------| 299 | RESTCONF POST (RPC:delete-subscription) | | 300 |--------------------------------------------->| | 301 | | HTTP 200 OK| | 302 |<---------------------------------------------| | 303 | | HTTP Headers (end of stream)| 304 | (/7)<-----------------------------------------(/7) 305 | 307 Figure 1: Dynamic with HTTP2 309 Additional requirements for dynamic subscriptions over HTTP2 include: 311 o A unique HTTP2 stream MAY be used for each subscription. 313 o A single HTTP2 stream MUST NOT be used for subscriptions with 314 different DSCP values. 316 o All subscription state notifications from a publisher MUST be 317 returned in a separate HTTP Data frame within the HTTP2 stream 318 used by the subscription to which the state change refers. 320 o In addition to an RPC response for a "modify-subscription" RPC 321 traveling over (a), a "subscription-modified" state change 322 notification must be sent within HTTP2 stream (b). This allows 323 the receiver to know exactly when the new terms of the 324 subscription have been applied to the notification messages. See 325 arrow (c). 327 o Additional RPCs for a particular subscription MUST NOT use the 328 HTTP2 stream currently providing notification messages 329 subscriptions. 331 o An HTTP end of stream message MUST not be sent until all 332 subscriptions using that HTTP2 stream have completed. 334 3.5. Call flow for HTTP1.1 336 The call flow is defined in Figure 2. Requests to 337 [I-D.draft-ietf-netconf-subscribed-notifications] or 338 [I-D.ietf-netconf-yang-push] augmented RPCs are sent on a TCP 339 connection indicated by (a). A successful "establish-subscription" 340 will result in an RPC response returned with both a subscription 341 identifier which uniquely identifies a subscription, as well as a URI 342 which uniquely identifies the location of subscription on the 343 publisher (b). This URI is defined via the "uri" leaf the Data Model 344 in Section 9. 346 An HTTP POST is then sent on a logically separate TCP connection (b) 347 to the URI on the publisher. This initiates to initiate the flow of 348 notification messages which are sent in SSE [W3C-20150203] as a 349 response to the POST. 351 +--------------+ +--------------+ 352 | Subscriber | | Publisher | 353 |TCP connection| |TCP connection| 354 | (a) (b) | | (a) (b) | 355 +--------------+ +--------------+ 356 | RESTCONF POST (RPC:establish-subscription) | 357 |--------------------------------------------->| 358 | HTTP 200 OK (ID,URI)| 359 |<---------------------------------------------| 360 | |HTTP GET (URI) | 361 | |--------------------------------------------->| 362 | | HTTP 200 OK| 363 | |<---------------------------------------------| 364 | | SSE (notif-message)| 365 | |<---------------------------------------------| 366 | RESTCONF POST (RPC:modify-subscription) | | 367 |--------------------------------------------->| | 368 | | HTTP 200 OK| | 369 |<---------------------------------------------| | 370 | | SSE (subscription-modified)| 371 | |<------------------------------------------(c)| 372 | | SSE (notif-message)| 373 | |<---------------------------------------------| 374 | RESTCONF POST (RPC:delete-subscription) | | 375 |--------------------------------------------->| | 376 | | HTTP 200 OK| | 377 |<---------------------------------------------| | 378 | | | 379 | | 381 Figure 2: Dynamic with HTTP1.1 383 Additional requirements for dynamic subscriptions over HTTP1.1 384 include: 386 o All subscription state notifications from a publisher MUST be 387 returned in a separate SSE message used by the subscription to 388 which the state change refers. 390 o Subscription RPCs MUST NOT use the TCP connection currently 391 providing notification messages for that subscription. 393 o In addition to an RPC response for a "modify-subscription" RPC 394 traveling over (a), a "subscription-modified" state change 395 notification must be sent within stream (b). This allows the 396 receiver to know exactly when the new terms of the subscription 397 have been applied to the notification messages. See arrow (c). 399 Open question, should we just eliminate this possibility of HTTP1.1 400 for subscriptions? It would make the design simpler. 402 4. Configured Subscription 404 With a configured subscription, all information needed to establish a 405 secure relationship with that receiver is available on the publisher. 406 With this information, the publisher will establish a secure 407 transport connection with the receiver and then begin pushing 408 notification messages to the receiver. Since RESTCONF might not 409 exist on the receiver, it is not desirable to require that subscribed 410 content be pushed with any dependency on RESTCONF. Therefore in 411 place of RESTCONF, an HTTP2 Client connection must be established 412 with an HTTP2 Server located on the receiver. Notification messages 413 will then be sent as part of an extended HTTP POST to the receiver. 415 4.1. Transport Connectivity 417 Configured subscriptions MUST only be connected over HTTP2 via a 418 client session initiated from the publisher. Following are the 419 conditions which MUST be met before establishing a new HTTP2 420 connection with a receiver: 422 o a configured subscription has a receiver in the connecting state 423 as described in [I-D.draft-ietf-netconf-subscribed-notifications], 424 section 2.5.1., 426 o the transport configured for that subscription is HTTP2, 428 o there are state change notifications or notification messages 429 pending for that receiver, and 431 o no HTTP2 transport session exists to that receiver, 433 If the above conditions are met, then the publisher MUST initiate a 434 transport session via RESTCONF call home [RFC8071], section 4.1 to 435 that receiver. HTTP2 only communications must be used as per 436 [RFC7540], Section 3.3 when the HTTP session over TLS [RFC5246]. and 437 [RFC7540], Section 3.4 when transporting cleartext over TCP. Note 438 that a subscriber SHOULD establish over TLS in order to secure the 439 content in transit. 441 If the RESTCONF call home fails because the publisher receives 442 receiver credentials which are subsequently declined per [RFC8071], 443 Section 4.1, step S5 authentication, then that receiver MUST be 444 placed into the timeout state. 446 If the call home fails to establish for any other reason, the 447 publisher MUST NOT progress the receiver to the active state. 448 Additionally, the publisher SHOULD place the receiver into the 449 timeout state after a predetermined number of either failed call home 450 attempts or remote transport session termination by the receiver. 452 4.2. Call Flow 454 With HTTP2 connectivity established, a POST of each new 455 "subscription-started" state change notification messages will be 456 addressed to HTTP augmentation code on the receiver capable of 457 accepting and acknowledging to subscription state change 458 notifications. Until the "HTTP 200 OK" at point (c) of Figure 3 for 459 each the "subscription-started" state change notification, a 460 publisher MUST NOT progress the receiver to the active state. In 461 other words, is at point (c) which indicates that the receiver is 462 ready for the delivery of subscribed content. At this point a 463 notification-messages including subscribed content may be placed onto 464 an HTTP2 stream for that subscription. 466 +------------+ +------------+ 467 | Receiver | | Publisher | 468 |HTTP2 Stream| |HTTP2 Stream| 469 | (a) (b) | | (a) (b) | 470 +------------+ +------------+ 471 |HTTP Post Headers, Data (subscription-started)| 472 |<---------------------------------------------| 473 | HTTP 200 OK | 474 |-------------------------------------------->(c) 475 | | HTTP Post Headers, Data (notif-message)| 476 | |<---------------------------------------------| 477 | | HTTP Data (notif-message)| 478 | |<---------------------------------------------| 479 | | HTTP Data (sub-terminated)| 480 | |<---------------------------------------------| 481 | |HTTP 200 OK | 482 | |--------------------------------------------->| 484 Figure 3: Configured over HTTP2 486 Additional requirements for configured subscriptions over HTTP2 487 include: 489 o A unique HTTP2 stream MAY be used for each subscription. 491 o A single HTTP2 stream MUST NOT be used for subscriptions with 492 different DSCP values. 494 o All subscription state notifications from a publisher MUST be 495 returned in a separate HTTP Data frame within the HTTP2 stream 496 used by the subscription to which the state change refers. 498 o An HTTP end of stream message MUST not be sent until all 499 subscriptions using that HTTP2 stream have completed. 501 5. QoS Treatment 503 To meet subscription quality of service promises, the publisher MUST 504 take any existing subscription "dscp" and apply it to the DSCP 505 marking in the IP header. 507 In addition, where HTTP2 transport is available to a notification 508 message queued for transport to a receiver, the publisher MUST: 510 o take any existing subscription "priority" and copy it into the 511 HTTP2 stream priority, and 513 o take any existing subscription "dependency" and map the HTTP2 514 stream for the parent subscription into the HTTP2 stream 515 dependency. 517 6. Mandatory JSON and datastore support 519 A publisher supporting [I-D.ietf-netconf-yang-push] MUST support the 520 "operational" datastore as defined by [RFC8342]. 522 The "encode-json" feature of 523 [I-D.draft-ietf-netconf-subscribed-notifications] is mandatory to 524 support. This indicates that JSON is a valid encoding for RPCs, 525 state change notifications, and subscribed content. 527 7. Notification Messages 529 Notification messages transported over HTTP will be encoded using 530 one-way operation schema defined within [RFC5277], section 4. 532 8. YANG Tree 534 The YANG model defined in Section 9 has one leaf augmented into four 535 places of [I-D.draft-ietf-netconf-subscribed-notifications], plus two 536 identities. As the resulting full tree is large, it will only be 537 inserted at later stages of this document. 539 9. YANG module 541 This module references 542 [I-D.draft-ietf-netconf-subscribed-notifications]. 544 file "ietf-http-subscribed-notifications@2018-06-11.yang" 545 module ietf-http-subscribed-notifications { 546 yang-version 1.1; 547 namespace 548 "urn:ietf:params:xml:ns:yang:ietf-http-subscribed-notifications"; 550 prefix hsn; 552 import ietf-subscribed-notifications { 553 prefix sn; 554 } 555 import ietf-inet-types { 556 prefix inet; 557 } 559 organization "IETF NETCONF (Network Configuration) Working Group"; 560 contact 561 "WG Web: 562 WG List: 564 Editor: Eric Voit 565 567 Editor: Alexander Clemm 568 570 Editor: Reshad Rahman 571 "; 573 description 574 "Defines HTTP variants as a supported transports for subscribed 575 event notifications. 577 Copyright (c) 2018 IETF Trust and the persons identified as authors 578 of the code. All rights reserved. 580 Redistribution and use in source and binary forms, with or without 581 modification, is permitted pursuant to, and subject to the license 582 terms contained in, the Simplified BSD License set forth in Section 583 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 584 (https://trustee.ietf.org/license-info). 586 This version of this YANG module is part of RFC XXXX; see the RFC 587 itself for full legal notices."; 589 revision 2018-06-11 { 590 description 591 "Initial version"; 592 reference 593 "RFC XXXX: RESTCONF and HTTP Transport for Event Notifications"; 594 } 596 identity http2 { 597 base sn:transport; 598 base sn:inline-address; 599 base sn:configurable-encoding; 600 description 601 "HTTP2 is used a transport for notification messages and state 602 change notifications."; 603 } 605 identity http1.1 { 606 base sn:transport; 607 base sn:inline-address; 608 base sn:configurable-encoding; 609 description 610 "HTTP1.1 is used a transport for notification messages and state 611 change notifications."; 612 } 614 grouping uri { 615 description 616 "Provides a reusable description of a URI."; 617 leaf uri { 618 type inet:uri; 619 config false; 620 description 621 "Location of a subscription specific URI on the publisher."; 622 } 623 } 625 augment "/sn:establish-subscription/sn:output" { 626 description 627 "This augmentation allows HTTP specific parameters for a 628 response to a publisher's subscription request."; 629 uses uri; 630 } 632 augment "/sn:subscriptions/sn:subscription" { 633 description 634 "This augmentation allows HTTP specific parameters to be 635 exposed for a subscription."; 636 uses uri; 637 } 639 augment "/sn:subscription-started" { 640 description 641 "This augmentation allows HTTP specific parameters to be included 642 part of the notification that a subscription has started."; 643 uses uri; 644 } 646 augment "/sn:subscription-modified" { 647 description 648 "This augmentation allows HTTP specific parameters to be included 649 part of the notification that a subscription has been modified."; 650 uses uri; 651 } 653 } 654 656 10. IANA Considerations 658 This document registers the following namespace URI in the "IETF XML 659 Registry" [RFC3688]: 661 URI: urn:ietf:params:xml:ns:yang:ietf-http-subscribed-notifications 662 Registrant Contact: The IESG. 663 XML: N/A; the requested URI is an XML namespace. 665 This document registers the following YANG module in the "YANG Module 666 Names" registry [RFC6020]: 668 Name: ietf-http-subscribed-notifications 669 Namespace: urn:ietf:params:xml:ns:yang:ietf-http-subscribed- 670 notifications 671 Prefix: hsn 672 Reference: RFC XXXX: RESTCONF and HTTP Transport for Event 673 Notifications 675 11. Security Considerations 677 The YANG module specified in this document defines a schema for data 678 that is designed to be accessed via network management transports 679 such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF 680 layer is the secure transport layer, and the mandatory-to-implement 681 secure transport is Secure Shell (SSH) [RFC6242]. The lowest 682 RESTCONF layer is HTTPS, and the mandatory-to-implement secure 683 transport is TLS [RFC5246]. 685 The one new data node introduced in this YANG module may be 686 considered sensitive or vulnerable in some network environments. It 687 is thus important to control read access (e.g., via get, get-config, 688 or notification) to this data nodes. These are the subtrees and data 689 nodes and their sensitivity/vulnerability: 691 Container: "/subscriptions" 693 o "uri": leaf will show where subscribed resources might be located 694 on a publisher. Access control must be set so that only someone 695 with proper access permissions, and perhaps even HTTP session has 696 the ability to access this resource. 698 One or more publishers of configured subscriptions could be used to 699 overwhelm a receiver which doesn't even support subscriptions. There 700 are two protections needing support on a publisher. First, 701 notification messages for configured subscriptions MUST only be 702 transmittable over encrypted transports. Clients which do not want 703 pushed content need only terminate or refuse any transport sessions 704 from the publisher. Second, the HTTP transport augmentation on the 705 receiver must send an HTTP 200 OK to a subscription started 706 notification before the publisher starts streaming any subscribed 707 content. 709 One or more publishers could overwhelm a receiver which is unable to 710 control or handle the volume of Event Notifications received. In 711 deployments where this might be a concern, HTTP2 transport such as 712 HTTP2) should be selected. 714 The NETCONF Authorization Control Model [RFC6536] SHOULD be used to 715 control and restrict authorization of subscription configuration. 717 12. Acknowledgments 719 We wish to acknowledge the helpful contributions, comments, and 720 suggestions that were received from: Ambika Prasad Tripathy, Alberto 721 Gonzalez Prieto, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent 722 Watsen, Michael Scharf, and Guangying Zheng. 724 13. References 725 13.1. Normative References 727 [GRPC] "RPC framework that runs over HTTP2", August 2017, 728 . 730 [I-D.draft-ietf-netconf-subscribed-notifications] 731 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 732 and E. Nilsen-Nygaard, "Custom Subscription to Event 733 Streams", draft-ietf-netconf-subscribed-notifications-13 734 (work in progress), April 2018. 736 [I-D.ietf-netconf-yang-push] 737 Clemm, A., Voit, E., Gonzalez Prieto, A., Prasad Tripathy, 738 A., Nilsen-Nygaard, E., Bierman, A., and B. Lengyel, 739 "Subscribing to YANG datastore push updates", March 2017, 740 . 743 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 744 Requirement Levels", BCP 14, RFC 2119, 745 DOI 10.17487/RFC2119, March 1997, 746 . 748 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 749 DOI 10.17487/RFC3688, January 2004, 750 . 752 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 753 (TLS) Protocol Version 1.2", RFC 5246, 754 DOI 10.17487/RFC5246, August 2008, 755 . 757 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 758 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 759 . 761 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 762 the Network Configuration Protocol (NETCONF)", RFC 6020, 763 DOI 10.17487/RFC6020, October 2010, 764 . 766 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 767 and A. Bierman, Ed., "Network Configuration Protocol 768 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 769 . 771 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 772 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 773 . 775 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 776 Layer Security (TLS) and Datagram Transport Layer Security 777 (DTLS) Heartbeat Extension", RFC 6520, 778 DOI 10.17487/RFC6520, February 2012, 779 . 781 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 782 Protocol (NETCONF) Access Control Model", RFC 6536, 783 DOI 10.17487/RFC6536, March 2012, 784 . 786 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 787 Protocol (HTTP/1.1): Message Syntax and Routing", 788 RFC 7230, DOI 10.17487/RFC7230, June 2014, 789 . 791 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 792 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 793 DOI 10.17487/RFC7540, May 2015, 794 . 796 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 797 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 798 . 800 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 801 and R. Wilton, "Network Management Datastore Architecture 802 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 803 . 805 [W3C-20150203] 806 "Server-Sent Events, World Wide Web Consortium CR CR- 807 eventsource-20121211", February 2015, 808 . 810 13.2. Informative References 812 [I-D.draft-ietf-netconf-netconf-event-notifications] 813 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 814 Nilsen-Nygaard, E., and A. Tripathy, "NETCONF support for 815 event notifications", May 2018, 816 . 819 [I-D.draft-ietf-netconf-nmda-restconf] 820 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 821 and R. Wilton, "RESTCONF Extensions to Support the Network 822 Management Datastore Architecture", April 2018, 823 . 826 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 827 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 828 DOI 10.17487/RFC7231, June 2014, 829 . 831 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 832 for Subscription to YANG Datastores", RFC 7923, 833 DOI 10.17487/RFC7923, June 2016, 834 . 836 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 837 RFC 8071, DOI 10.17487/RFC8071, February 2017, 838 . 840 Appendix A. RESTCONF over GRPC 842 An initial goal for this document was to support [GRPC] transport 843 seamlessly without any mapping or extra layering. However there is 844 an incompatibility of RESTCONF and GRPC. RESTCONF uses HTTP GET, and 845 GRPC uses HTTP2's POST rather than GET. As GET is used across 846 RESTCONF for things like capabilities exchange, a seamless mapping 847 depends on specification changes outside the scope of this document. 848 If/when GRPC supports GET, or RESTCONF is updated to support POST, 849 this should be revisited. It is hoped that the resulting fix will be 850 transparent to this document. 852 Appendix B. Examples 854 This section is non-normative. To allow easy comparison, this 855 section mirrors the functional examples shown with NETCONF over XML 856 within [I-D.draft-ietf-netconf-netconf-event-notifications]. In 857 addition, HTTP2 vs HTTP1.1 headers are not shown as the contents of 858 the JSON encoded objects are identical within. 860 B.1. Dynamic Subscriptions 862 B.1.1. Establishing Dynamic Subscriptions 864 The following figure shows two successful "establish-subscription" 865 RPC requests as per 866 [I-D.draft-ietf-netconf-subscribed-notifications]. The first request 867 is given a subscription identifier of 22, the second, an identifier 868 of 23. 870 +------------+ +-----------+ 871 | Subscriber | | Publisher | 872 +------------+ +-----------+ 873 | | 874 |establish-subscription | 875 |------------------------------>| (a) 876 | HTTP 200 OK, id#22, URI#1 | 877 |<------------------------------| (b) 878 |POST (URI#1) | 879 |------------------------------>| (c) 880 | HTTP 200 OK,notif-mesg (id#22)| 881 |<------------------------------| 882 | | 883 | | 884 |establish-subscription | 885 |------------------------------>| 886 | HTTP 200 OK, id#23, URI#2| 887 |<------------------------------| 888 |POST (URI#2) | 889 |------------------------------>| 890 | | 891 | | 892 | notif-mesg (id#22)| 893 |<------------------------------| 894 | HTTP 200 OK,notif-mesg (id#23)| 895 |<------------------------------| 896 | | 898 Figure 4: Multiple subscriptions over RESTCONF/HTTP 900 To provide examples of the information being transported, example 901 messages for interactions in Figure 4 are detailed below: 903 POST /restconf/operations/subscriptions:establish-subscription 905 { 906 "ietf-subscribed-notifications:input": { 907 "stream": "NETCONF", 908 "stream-xpath-filter": "/ex:foo/", 909 "dscp": "10" 910 } 911 } 913 Figure 5: establish-subscription request (a) 915 As publisher was able to fully satisfy the request, the publisher 916 sends the subscription identifier of the accepted subscription, and 917 the URI: 919 HTTP status code - 200 921 { 922 "identifier": "22", 923 "uri": "/subscriptions/22" 924 } 926 Figure 6: establish-subscription success (b) 928 Upon receipt of the successful response, the subscriber POSTs to the 929 provided URI to start the flow of notification messages. When the 930 publisher receives this, the subscription is moved to the active 931 state (c). 933 POST /restconf/operations/subscriptions/22 935 Figure 7: establish-subscription subsequent POST 937 While not shown in Figure 4, if the publisher had not been able to 938 fully satisfy the request, or subscriber has no authorization to 939 establish the subscription, the publisher would have sent an RPC 940 error response. For instance, if the "dscp" value of 10 asserted by 941 the subscriber in Figure 5 proved unacceptable, the publisher may 942 have returned: 944 HTTP status code - 406 946 { "ietf-restconf:errors" : { 947 "error" : [ 948 { 949 "error-type": "application", 950 "error-tag": "operation-failed", 951 "error-severity": "error", 952 "error-app-tag": 953 "ietf-subscribed-notifications:dscp-unavailable" 954 } 955 ] 956 } 957 } 959 Figure 8: an unsuccessful establish subscription 961 The subscriber can use this information in future attempts to 962 establish a subscription. 964 B.1.2. Modifying Dynamic Subscriptions 966 An existing subscription may be modified. The following exchange 967 shows a negotiation of such a modification via several exchanges 968 between a subscriber and a publisher. This negotiation consists of a 969 failed RPC modification request/response, followed by a successful 970 one. 972 +------------+ +-----------+ 973 | Subscriber | | Publisher | 974 +------------+ +-----------+ 975 | | 976 | notification message (id#23)| 977 |<-----------------------------| 978 | | 979 |modify-subscription (id#23) | 980 |----------------------------->| (d) 981 | HTTP 406 error (with hint)| 982 |<-----------------------------| (e) 983 | | 984 |modify-subscription (id#23) | 985 |----------------------------->| 986 | HTTP 200 OK | 987 |<-----------------------------| 988 | | 989 | notif-mesg (id#23)| 990 |<-----------------------------| 991 | | 993 Figure 9: Interaction model for successful subscription modification 995 If the subscription being modified in Figure 9 is a datastore 996 subscription as per [I-D.ietf-netconf-yang-push], the modification 997 request made in (d) may look like that shown in Figure 10. As can be 998 seen, the modifications being attempted are the application of a new 999 xpath filter as well as the setting of a new periodic time interval. 1001 POST /restconf/operations/subscriptions:modify-subscription 1003 { 1004 "ietf-subscribed-notifications:input": { 1005 "identifier": "23", 1006 "ietf-yang-push:datastore-xpath-filter": 1007 "/interfaces-state/interface/oper-status" 1008 "ietf-yang-push:periodic": { 1009 "ietf-yang-push:period": "500" 1010 } 1011 } 1012 } 1014 Figure 10: Subscription modification request (c) 1016 If the publisher can satisfy both changes, the publisher sends a 1017 positive result for the RPC. If the publisher cannot satisfy either 1018 of the proposed changes, the publisher sends an RPC error response 1019 (e). The following is an example RPC error response for (e) which 1020 includes a hint. This hint is an alternative time period value which 1021 might have resulted in a successful modification: 1023 HTTP status code - 406 1025 { "ietf-restconf:errors" : { 1026 "error" : [ 1027 "error-type": "application", 1028 "error-tag": "operation-failed", 1029 "error-severity": "error", 1030 "error-app-tag": "ietf-yang-push:period-unsupported", 1031 "error-info": { 1032 "ietf-yang-push": 1033 "modify-subscription-datastore-error-info": { 1034 "period-hint": "3000" 1035 } 1036 } 1037 ] 1038 } 1039 } 1041 Figure 11: Modify subscription failure with Hint (e) 1043 B.1.3. Deleting Dynamic Subscriptions 1045 The following demonstrates deleting a subscription. This 1046 subscription may have been to either a stream or a datastore. 1048 POST /restconf/operations/subscriptions:delete-subscription 1050 { 1051 "delete-subscription": { 1052 "identifier": "22" 1053 } 1054 } 1056 Figure 12: Delete subscription 1058 If the publisher can satisfy the request, the publisher replies with 1059 success to the RPC request. 1061 If the publisher cannot satisfy the request, the publisher sends an 1062 error-rpc element indicating the modification didn't work. Figure 13 1063 shows a valid response for existing valid subscription identifier, 1064 but that subscription identifier was created on a different transport 1065 session: 1067 HTTP status code - 406 1069 { 1070 "ietf-restconf:errors" : { 1071 "error" : [ 1072 "error-type": "application", 1073 "error-tag": "operation-failed", 1074 "error-severity": "error", 1075 "error-app-tag": 1076 "ietf-subscribed-notifications:no-such-subscription" 1077 ] 1078 } 1079 } 1081 Figure 13: Unsuccessful delete subscription 1083 B.2. Configured Subscriptions 1085 Configured subscriptions may be established, modified, and deleted 1086 using configuration operations against the top-level subtree of 1087 [I-D.draft-ietf-netconf-subscribed-notifications] or 1088 [I-D.ietf-netconf-yang-push]. 1090 In this section, we present examples of how to manage the 1091 configuration subscriptions using a HTTP2 client. 1093 B.2.1. Creating Configured Subscriptions 1095 For subscription creation via configuration operations, a RESTCONF 1096 client may send: 1098 POST /restconf/operations/subscriptions/ 1100 { 1101 "edit-config": { 1102 "target": { 1103 "running": null 1104 }, 1105 "default-operation": "none", 1106 "config": { 1107 "subscriptions": { 1108 "subscription": { 1109 "identifier": "22", 1110 "transport": "HTTP2", 1111 "stream": "NETCONF", 1112 "receivers": { 1113 "receiver": { 1114 "name": "receiver1", 1115 "address": "1.2.3.4" 1116 } 1117 } 1118 } 1119 } 1120 } 1121 } 1122 } 1124 Figure 14: Create a configured subscription 1126 If the request is accepted, the publisher will indicate this. If the 1127 request is not accepted because the publisher cannot serve it, no 1128 configuration is changed. In this case the publisher may reply: 1130 HTTP status code - 406 1132 { 1133 "ietf-restconf:errors" : { 1134 "error" : [ 1135 "error-type": "application", 1136 "error-tag": "resource-denied", 1137 "error-severity": "error", 1138 "error-message": { 1139 "@lang": "en", 1140 "#text": "Temporarily the publisher cannot serve this 1141 subscription due to the current workload." 1142 } 1143 ] 1144 } 1145 } 1147 Figure 15: Response to a failed configured subscription establishment 1149 After a subscription has been created and been verified as VALID, 1150 HTTP2 connectivity to each receiver will be established if that 1151 connectivity does not already exist. 1153 The following figure shows the interaction model for the successful 1154 creation of a configured subscription. 1156 +----------+ +-----------+ +---------+ 1157 |Config Ops| | Publisher | | 1.2.3.4 | 1158 +----------+ +-----------+ +---------+ 1159 | | | 1160 | Capability Exchange | | 1161 |<-------------------------->| | 1162 | | | 1163 | | | 1164 | Edit-config | | 1165 |--------------------------->| | 1166 | RPC Reply: OK | | 1167 |<---------------------------| | 1168 | | Call Home | 1169 | |<-------------->| 1170 | | | 1171 | | subscription- | 1172 | | started | 1173 | |--------------->| 1174 | | | 1175 | | notification | 1176 | | message | 1177 | |--------------->| 1179 Figure 16: Interaction model for configured subscription 1180 establishment 1182 B.2.2. Modifying Configured Subscriptions 1184 Configured subscriptions can be modified using configuration 1185 operations against the top-level container "/subscriptions". 1187 For example, the subscription established in the previous section 1188 could be modified as follows, here a adding a second receiver: 1190 POST /restconf/operations/subscriptions 1192 { 1193 "edit-config": { 1194 "target": { 1195 "running": null 1196 }, 1197 "config": { 1198 "subscriptions": { 1199 "subscription": { 1200 "identifier": "1922", 1201 "receivers": { 1202 "receiver": { 1203 "name": "receiver2", 1204 "address": "1.2.3.5" 1205 } 1206 } 1207 } 1208 } 1209 } 1210 } 1211 } 1213 Figure 17: Modify configured subscription 1215 If the request is accepted, the publisher will indicate success. The 1216 result is that the interaction model described in Figure 16 may be 1217 extended as follows. 1219 +----------+ +-----------+ +---------+ +---------+ 1220 |Config Ops| | Publisher | | 1.2.3.4 | | 1.2.3.5 | 1221 +----------+ +-----------+ +---------+ +---------+ 1222 | | notification | | 1223 | | message | | 1224 | |--------------->| | 1225 | Edit-config | | | 1226 |--------------------------->| | | 1227 | RPC Reply: OK | | | 1228 |<---------------------------| | | 1229 | | subscription- | | 1230 | | started | | 1231 | |---------------------------->| 1232 | | | | 1233 | | notification | | 1234 | | message | | 1235 | |--------------->| | 1236 | |---------------------------->| 1237 | | | | 1239 Figure 18: Interaction model for configured subscription modification 1241 Note in the above that in the specific example above, modifying a 1242 configured subscription actually resulted in "subscription-started" 1243 notification. And because of existing HTTP2 connectivity, no 1244 additional call home was needed. Also note that if the edit of the 1245 configuration had impacted the filter, a separate modify-subscription 1246 would have been required for the original receiver. 1248 B.2.3. Deleting Configured Subscriptions 1250 Configured subscriptions can be deleted using configuration 1251 operations against the top-level container "/subscriptions". 1252 Deleting the subscription above would result in the following flow 1253 impacting all active receivers. 1255 +----------+ +-----------+ +---------+ +---------+ 1256 |Config Ops| | Publisher | | 1.2.3.4 | | 1.2.3.5 | 1257 +----------+ +-----------+ +---------+ +---------+ 1258 | | | | 1259 | | notification | | 1260 | | message | | 1261 | |--------------->| | 1262 | |---------------------------->| 1263 | | | | 1264 | Edit-config | | | 1265 |--------------------------->| | | 1266 | RPC Reply: OK | | | 1267 |<---------------------------| | | 1268 | | subscription- | | 1269 | | terminated | | 1270 | |--------------->| | 1271 | |---------------------------->| 1272 | | | | 1274 Figure 19: Interaction model for configured subscription deletion 1276 B.3. Subscription State Notifications 1278 A publisher will send subscription state notifications according to 1279 the definitions within 1280 [I-D.draft-ietf-netconf-subscribed-notifications]). 1282 B.3.1. subscription-started and subscription-modified 1284 A "subscription-started" encoded in JSON would look like: 1286 { 1287 "ietf-restconf:notification" : { 1288 "eventTime": "2007-09-01T10:00:00Z", 1289 "ietf-subscribed-notifications:subscription-started": { 1290 "identifier": "39", 1291 "transport": "HTTP2", 1292 "stream-xpath-filter": "/ex:foo", 1293 "stream": { 1294 "ietf-netconf-subscribed-notifications" : "NETCONF" 1295 } 1296 } 1297 } 1298 } 1300 Figure 20: subscription-started subscription state notification 1302 The "subscription-modified" is identical to Figure 20, with just the 1303 word "started" being replaced by "modified". 1305 B.3.2. subscription-completed, subscription-resumed, and replay- 1306 complete 1308 A "subscription-completed" would look like: 1310 { 1311 "ietf-restconf:notification" : { 1312 "eventTime": "2007-09-01T10:00:00Z", 1313 "ietf-subscribed-notifications:subscription-completed": { 1314 "identifier": "39", 1315 } 1316 } 1317 } 1319 Figure 21: subscription-completed notification in JSON 1321 The "subscription-resumed" and "replay-complete" are virtually 1322 identical, with "subscription-completed" simply being replaced by 1323 "subscription-resumed" and "replay-complete". 1325 B.3.3. subscription-terminated and subscription-suspended 1327 A "subscription-terminated" would look like: 1329 { 1330 "ietf-restconf:notification" : { 1331 "eventTime": "2007-09-01T10:00:00Z", 1332 "ietf-subscribed-notifications:subscription-terminated": { 1333 "identifier": "39", 1334 "error-id": "suspension-timeout" 1335 } 1336 } 1337 } 1339 Figure 22: subscription-terminated subscription state notification 1341 The "subscription-suspended" is virtually identical, with 1342 "subscription-terminated" simply being replaced by "subscription- 1343 suspended". 1345 Appendix C. Changes between revisions 1347 (To be removed by RFC editor prior to publication) 1349 v05 - v06 1351 o JSON examples updated by Reshad. 1353 v04 - v05 1355 o Error mechanisms updated to match embedded RESTCONF mechanisms 1357 o Restructured format and sections of document. 1359 o Added a YANG data model for HTTP specific parameters. 1361 o Mirrored the examples from the NETCONF transport draft to allow 1362 easy comparison. 1364 v03 - v04 1366 o Draft not fully synched to new version of subscribed-notifications 1367 yet. 1369 o References updated 1371 v02 - v03 1373 o Event notification reframed to notification message. 1375 o Tweaks to wording/capitalization/format. 1377 v01 - v02 1379 o Removed sections now redundant with 1380 [I-D.draft-ietf-netconf-subscribed-notifications] and 1381 [I-D.ietf-netconf-yang-push] such as: mechanisms for subscription 1382 maintenance, terminology definitions, stream discovery. 1384 o 3rd party subscriptions are out-of-scope. 1386 o SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions 1388 o Timeframes for event tagging are self-defined. 1390 o Clean-up of wording, references to terminology, section numbers. 1392 v00 - v01 1393 o Removed the ability for more than one subscription to go to a 1394 single HTTP2 stream. 1396 o Updated call flows. Extensively. 1398 o SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions 1400 o HTTP is not used to determine that a receiver has gone silent and 1401 is not Receiving Event Notifications 1403 o Many clean-ups of wording and terminology 1405 Authors' Addresses 1407 Eric Voit 1408 Cisco Systems 1410 Email: evoit@cisco.com 1412 Reshad Rahman 1413 Cisco Systems 1415 Email: rrahman@cisco.com 1417 Einar Nilsen-Nygaard 1418 Cisco Systems 1420 Email: einarnn@cisco.com 1422 Alexander Clemm 1423 Huawei 1425 Email: ludwig@clemm.org 1427 Andy Bierman 1428 YumaWorks 1430 Email: andy@yumaworks.com