idnits 2.17.1 draft-ietf-netconf-restconf-notif-07.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 2 instances of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 206 has weird spacing: '...ription estab...' == Line 210 has weird spacing: '...ription res...' == Line 225 has weird spacing: '... stream esta...' == Line 228 has weird spacing: '...ription ret...' == Line 230 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. -- The document date (September 12, 2018) is 2053 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) == 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 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 (~~), 8 warnings (==), 3 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: March 16, 2019 Cisco Systems 6 A. Clemm 7 Huawei 8 A. Bierman 9 YumaWorks 10 September 12, 2018 12 RESTCONF Transport for Event Notifications 13 draft-ietf-netconf-restconf-notif-07 15 Abstract 17 This document defines a RESTCONF binding to the dynamic subscription 18 capability of both subscribed notifications and YANG-Push. 19 Subscriptions to publisher defined event streams or nodes/subtrees of 20 YANG Datastores is supported. 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 March 16, 2019. 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 . . . . . . . . . . . . . . . . . . . . . . . . 2 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 3. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . . . 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. QoS Treatment . . . . . . . . . . . . . . . . . . . . . . . . 10 65 5. Mandatory JSON and datastore support . . . . . . . . . . . . 10 66 6. Notification Messages . . . . . . . . . . . . . . . . . . . . 10 67 7. YANG Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 10 68 8. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 10 69 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 70 10. Security Considerations . . . . . . . . . . . . . . . . . . . 13 71 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 13 72 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 73 12.1. Normative References . . . . . . . . . . . . . . . . . . 14 74 12.2. Informative References . . . . . . . . . . . . . . . . . 15 75 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 16 76 A.1. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 16 77 A.1.1. Establishing Dynamic Subscriptions . . . . . . . . . 16 78 A.1.2. Modifying Dynamic Subscriptions . . . . . . . . . . . 19 79 A.1.3. Deleting Dynamic Subscriptions . . . . . . . . . . . 20 80 A.2. Subscription State Notifications . . . . . . . . . . . . 21 81 A.2.1. subscription-started and subscription-modified . . . 21 82 A.2.2. subscription-completed, subscription-resumed, and 83 replay-complete . . . . . . . . . . . . . . . . . . . 22 84 A.2.3. subscription-terminated and subscription-suspended . 22 85 Appendix B. Changes between revisions . . . . . . . . . . . . . 23 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 88 1. Introduction 90 Mechanisms to support event subscription and push are defined in 91 [I-D.draft-ietf-netconf-subscribed-notifications]. Enhancements to 92 [I-D.draft-ietf-netconf-subscribed-notifications] which enable YANG 93 datastore subscription and push are defined in 94 [I-D.ietf-netconf-yang-push]. This document provides a transport 95 specification for dynamic subscriptions over RESTCONF [RFC8040]. 96 Driving these requirements is [RFC7923]. 98 The streaming of notifications encapsulating the resulting 99 information push can be done with either HTTP1.1 [RFC7231] or HTTP2 100 [RFC7540]. 102 2. Terminology 104 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 105 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 106 document are to be interpreted as described in RFC 2119 [RFC2119]. 108 The following terms use the definitions from 109 [I-D.draft-ietf-netconf-subscribed-notifications]: dynamic 110 subscription, event stream, notification message, publisher, 111 receiver, subscriber, and subscription. 113 Other terms reused include datastore, which is defined in [RFC8342], 114 and HTTP2 stream which maps to the definition of "stream" within 115 [RFC7540], Section 2. 117 [ note to the RFC Editor - please replace XXXX within this document 118 with the number of this document ] 120 3. Dynamic Subscriptions 122 This section provides specifics on how to establish and maintain 123 dynamic subscriptions over HTTP 1.1 and HTTP2 via signaling messages 124 transported over RESTCONF [RFC8040]. Subscribing to event streams is 125 accomplished in this way via a RESTCONF POST into RPCs defined within 126 [I-D.draft-ietf-netconf-subscribed-notifications] Section 2.4. YANG 127 datastore subscription is accomplished via augmentations to 128 [I-D.draft-ietf-netconf-subscribed-notifications] as described within 129 [I-D.ietf-netconf-yang-push] Section 4.4. 131 Common across all HTTP based dynamic subscriptions is that a POST 132 needs to be made against a specific URI on the Publisher. 133 Subscribers cannot pre-determine the URI against which a subscription 134 might exist on a publisher, as the URI will only exist after the 135 "establish-subscription" has been accepted. The subscription URI 136 will be determined and sent as part of the response to the 137 "establish-subscription", and a subsequent POST to this URI will be 138 done in order to start the flow of notification messages back to the 139 subscriber. A subscription does not move to the active state as per 140 Section 2.4.1. of [I-D.draft-ietf-netconf-subscribed-notifications] 141 until the POST is received. 143 3.1. Transport Connectivity 145 For a dynamic subscription, where an HTTP client session doesn't 146 already exist, a new client session is initiated from the subscriber. 147 If the subscriber is unsure if HTTP2 is supported by the publisher, 148 HTTP1.1 will be used for initial messages, and these messages will 149 include an HTTP version upgrade request as per [RFC7230], 150 Section 6.7. If a publisher response indicates that HTTP2 is 151 supported, HTTP2 will be used between subscriber and publisher for 152 future HTTP interactions as per [RFC7540]. 154 A subscriber SHOULD establish the HTTP session over TLS [RFC5246] in 155 order to secure the content in transit. 157 Without the involvement of additional protocols, neither HTTP1.1 nor 158 HTTP2 sessions by themselves allow for a quick recognition of when 159 the communication path has been lost with the publisher. Where quick 160 recognition of the loss of a publisher is required, a subscriber 161 SHOULD connect over TLS [RFC5246], and use a TLS heartbeat [RFC6520] 162 to track HTTP session continuity. In the case where a TLS heartbeat 163 is included, it should be sent just from receiver to publisher. Loss 164 of the heartbeat MUST result in any subscription related TCP sessions 165 between those endpoints being torn down. A subscriber can then 166 attempt to re-establish. 168 3.2. Discovery 170 Subscribers can learn what event streams a RESTCONF server supports 171 by querying the "streams" container of ietf-subscribed- 172 notification.yang. Subscribers can learn what datastores a RESTCONF 173 server supports by following [I-D.draft-ietf-netconf-nmda-restconf]. 175 3.3. RESTCONF RPCs and HTTP Status Codes 177 Specific HTTP responses codes as defined in [RFC7231] section 6 will 178 indicate the result of RESTCONF RPC requests with publisher. An HTTP 179 status code of 200 is the proper response to any successful RPC 180 defined within [I-D.draft-ietf-netconf-subscribed-notifications] or 181 [I-D.ietf-netconf-yang-push]. 183 If a publisher fails to serve the RPC request for one of the reasons 184 indicated in [I-D.draft-ietf-netconf-subscribed-notifications] 185 Section 2.4.6 or [I-D.ietf-netconf-yang-push] Appendix A, this will 186 be indicated by "406" status code transported in the HTTP response. 188 When a "406" status code is returned, the RPC reply MUST include an 189 "rpc-error" element per [RFC8040] Section 7.1 with the following 190 parameter values: 192 o an "error-type" node of "application". 194 o an "error-tag" node of "operation-failed". 196 o an "error-app-tag" node with the value being a string that 197 corresponds to an identity associated with the error, as defined 198 in [I-D.draft-ietf-netconf-subscribed-notifications] section 2.4.6 199 for general subscriptions, and [I-D.ietf-netconf-yang-push] 200 Appendix A.1, for datastore subscriptions. The tag to use depends 201 on the RPC for which the error occurred. Viable errors for 202 different RPCs are as follows: 204 RPC select an identity with a base 205 ---------------------- ------------------------------ 206 establish-subscription establish-subscription-error 207 modify-subscription modify-subscription-error 208 delete-subscription delete-subscription-error 209 kill-subscription kill-subscription-error 210 resynch-subscription resynch-subscription-error 212 Each error identity will be inserted as the "error-app-tag" using 213 JSON encoding following the form :. An 214 example of such as valid encoding would be "ietf-subscribed- 215 notifications:no-such-subscription". 217 o In case of error responses to an "establish-subscription" or 218 "modify-subscription" request there is the option of including an 219 "error-info" node. This node may contain hints for parameter 220 settings that might lead to successful RPC requests in the future. 221 Following are the yang-data structures which may be returned: 223 establish-subscription returns hints in yang-data structure 224 ---------------------- ------------------------------------ 225 target: event stream establish-subscription-stream-error-info 226 target: datastore establish-subscription-datastore-error-info 228 modify-subscription returns hints in yang-data structure 229 ---------------------- ------------------------------------ 230 target: event stream modify-subscription-stream-error-info 231 target: datastore modify-subscription-datastore-error-info 233 The yang-data included within "error-info" SHOULD NOT include the 234 optional leaf "error-reason", as such a leaf would be redundant 235 with information that is already placed within the 236 "error-app-tag". 238 In case of an rpc error as a result of a "delete-subscription", a 239 "kill-subscription", or a "resynch-subscription" request, no 240 "error-info" needs to be included, as the "subscription-id" is 241 the only RPC input parameter and no hints regarding this RPC input 242 parameters need to be provided. 244 Note that "error-path" does not need to be included with the "rpc- 245 error" element, as subscription errors are generally not associated 246 with nodes in the datastore but with the choice of RPC input 247 parameters. 249 3.4. Call Flow for HTTP2 251 Requests to [I-D.draft-ietf-netconf-subscribed-notifications] or 252 [I-D.ietf-netconf-yang-push] augmented RPCs are sent on one or more 253 HTTP2 streams indicated by (a) in Figure 1. A successful "establish- 254 subscription" will result in an RPC response returned with both a 255 subscription identifier which uniquely identifies a subscription, as 256 well as a URI which uniquely identifies the location of subscription 257 on the publisher. This URI is defined via the "uri" leaf the Data 258 Model in Section 8. 260 An HTTP POST is then sent on a logically separate HTTP2 stream (b) to 261 the URI on the publisher. This initiates to initiate the flow of 262 notification messages which are sent in HTTP Data frames as a 263 response to the POST. In the case below, a newly established 264 subscription has its associated notification messages pushed over 265 HTTP2 stream (7). These notification messages are placed into a 266 HTTP2 Data frame (see [RFC7540] Section 6.1). 268 +------------+ +------------+ 269 | Subscriber | | Publisher | 270 |HTTP2 Stream| |HTTP2 Stream| 271 | (a) (b) | | (a) (b) | 272 +------------+ +------------+ 273 | RESTCONF POST (RPC:establish-subscription) | 274 |--------------------------------------------->| 275 | HTTP 200 OK (ID,URI)| 276 |<---------------------------------------------| 277 | (7)HTTP POST (URI) (7) 278 | |--------------------------------------------->| 279 | | HTTP 200 OK| 280 | |<---------------------------------------------| 281 | | HTTP Data (notif-message)| 282 | |<---------------------------------------------| 283 | RESTCONF POST (RPC:modify-subscription) | | 284 |--------------------------------------------->| | 285 | | HTTP 200 OK| | 286 |<---------------------------------------------| | 287 | | HTTP Data (subscription-modified)| 288 | |<------------------------------------------(c)| 289 | | HTTP Data (notif-message)| 290 | |<---------------------------------------------| 291 | RESTCONF POST (RPC:delete-subscription) | | 292 |--------------------------------------------->| | 293 | | HTTP 200 OK| | 294 |<---------------------------------------------| | 295 | | HTTP Headers (end of stream)| 296 | (/7)<-----------------------------------------(/7) 297 | 299 Figure 1: Dynamic with HTTP2 301 Additional requirements for dynamic subscriptions over HTTP2 include: 303 o A unique HTTP2 stream MAY be used for each subscription. 305 o A single HTTP2 stream MUST NOT be used for subscriptions with 306 different DSCP values. 308 o All subscription state notifications from a publisher MUST be 309 returned in a separate HTTP Data frame within the HTTP2 stream 310 used by the subscription to which the state change refers. 312 o In addition to an RPC response for a "modify-subscription" RPC 313 traveling over (a), a "subscription-modified" state change 314 notification must be sent within HTTP2 stream (b). This allows 315 the receiver to know exactly when the new terms of the 316 subscription have been applied to the notification messages. See 317 arrow (c). 319 o Additional RPCs for a particular subscription MUST NOT use the 320 HTTP2 stream currently providing notification messages 321 subscriptions. 323 o An HTTP end of stream message MUST not be sent until all 324 subscriptions using that HTTP2 stream have completed. 326 3.5. Call flow for HTTP1.1 328 The call flow is defined in Figure 2. Requests to 329 [I-D.draft-ietf-netconf-subscribed-notifications] or 330 [I-D.ietf-netconf-yang-push] augmented RPCs are sent on a TCP 331 connection indicated by (a). A successful "establish-subscription" 332 will result in an RPC response returned with both a subscription 333 identifier which uniquely identifies a subscription, as well as a URI 334 which uniquely identifies the location of subscription on the 335 publisher (b). This URI is defined via the "uri" leaf the Data Model 336 in Section 8. 338 An HTTP POST is then sent on a logically separate TCP connection (b) 339 to the URI on the publisher. This initiates to initiate the flow of 340 notification messages which are sent in SSE [W3C-20150203] as a 341 response to the POST. 343 +--------------+ +--------------+ 344 | Subscriber | | Publisher | 345 |TCP connection| |TCP connection| 346 | (a) (b) | | (a) (b) | 347 +--------------+ +--------------+ 348 | RESTCONF POST (RPC:establish-subscription) | 349 |--------------------------------------------->| 350 | HTTP 200 OK (ID,URI)| 351 |<---------------------------------------------| 352 | |HTTP GET (URI) | 353 | |--------------------------------------------->| 354 | | HTTP 200 OK| 355 | |<---------------------------------------------| 356 | | SSE (notif-message)| 357 | |<---------------------------------------------| 358 | RESTCONF POST (RPC:modify-subscription) | | 359 |--------------------------------------------->| | 360 | | HTTP 200 OK| | 361 |<---------------------------------------------| | 362 | | SSE (subscription-modified)| 363 | |<------------------------------------------(c)| 364 | | SSE (notif-message)| 365 | |<---------------------------------------------| 366 | RESTCONF POST (RPC:delete-subscription) | | 367 |--------------------------------------------->| | 368 | | HTTP 200 OK| | 369 |<---------------------------------------------| | 370 | | | 371 | | 373 Figure 2: Dynamic with HTTP1.1 375 Additional requirements for dynamic subscriptions over HTTP1.1 376 include: 378 o All subscription state notifications from a publisher MUST be 379 returned in a separate SSE message used by the subscription to 380 which the state change refers. 382 o Subscription RPCs MUST NOT use the TCP connection currently 383 providing notification messages for that subscription. 385 o In addition to an RPC response for a "modify-subscription" RPC 386 traveling over (a), a "subscription-modified" state change 387 notification must be sent within stream (b). This allows the 388 receiver to know exactly when the new terms of the subscription 389 have been applied to the notification messages. See arrow (c). 391 Open question, should we just eliminate this possibility of HTTP1.1 392 for subscriptions? It would make the design simpler. 394 4. QoS Treatment 396 To meet subscription quality of service promises, the publisher MUST 397 take any existing subscription "dscp" and apply it to the DSCP 398 marking in the IP header. 400 In addition, where HTTP2 transport is available to a notification 401 message queued for transport to a receiver, the publisher MUST: 403 o take any existing subscription "priority" and copy it into the 404 HTTP2 stream priority, and 406 o take any existing subscription "dependency" and map the HTTP2 407 stream for the parent subscription into the HTTP2 stream 408 dependency. 410 5. Mandatory JSON and datastore support 412 A publisher supporting [I-D.ietf-netconf-yang-push] MUST support the 413 "operational" datastore as defined by [RFC8342]. 415 The "encode-json" feature of 416 [I-D.draft-ietf-netconf-subscribed-notifications] is mandatory to 417 support. This indicates that JSON is a valid encoding for RPCs, 418 state change notifications, and subscribed content. 420 6. Notification Messages 422 Notification messages transported over HTTP will be encoded using 423 one-way operation schema defined within [RFC5277], section 4. 425 7. YANG Tree 427 The YANG model defined in Section 8 has one leaf augmented into four 428 places of [I-D.draft-ietf-netconf-subscribed-notifications], plus two 429 identities. As the resulting full tree is large, it will only be 430 inserted at later stages of this document. 432 8. YANG module 434 This module references 435 [I-D.draft-ietf-netconf-subscribed-notifications]. 437 file "ietf-restconf-subscribed-notifications@2018-09-12.yang" 438 module ietf-restconf-subscribed-notifications { 439 yang-version 1.1; 440 namespace 441 "urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications"; 443 prefix rsn; 445 import ietf-subscribed-notifications { 446 prefix sn; 447 } 448 import ietf-inet-types { 449 prefix inet; 450 } 452 organization "IETF NETCONF (Network Configuration) Working Group"; 453 contact 454 "WG Web: 455 WG List: 457 Editor: Eric Voit 458 460 Editor: Alexander Clemm 461 463 Editor: Reshad Rahman 464 "; 466 description 467 "Defines RESTCONF as a supported transport for subscribed 468 event notifications. 470 Copyright (c) 2018 IETF Trust and the persons identified as authors 471 of the code. All rights reserved. 473 Redistribution and use in source and binary forms, with or without 474 modification, is permitted pursuant to, and subject to the license 475 terms contained in, the Simplified BSD License set forth in Section 476 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 477 (https://trustee.ietf.org/license-info). 479 This version of this YANG module is part of RFC XXXX; see the RFC 480 itself for full legal notices."; 482 revision 2018-09-12 { 483 description 484 "Initial version"; 485 reference 486 "RFC XXXX: RESTCONF Transport for Event Notifications"; 488 } 490 grouping uri { 491 description 492 "Provides a reusable description of a URI."; 493 leaf uri { 494 type inet:uri; 495 config false; 496 description 497 "Location of a subscription specific URI on the publisher."; 498 } 499 } 501 augment "/sn:establish-subscription/sn:output" { 502 description 503 "This augmentation allows HTTP specific parameters for a 504 response to a publisher's subscription request."; 505 uses uri; 506 } 508 augment "/sn:subscriptions/sn:subscription" { 509 description 510 "This augmentation allows HTTP specific parameters to be 511 exposed for a subscription."; 512 uses uri; 513 } 515 augment "/sn:subscription-started" { 516 description 517 "This augmentation allows HTTP specific parameters to be included 518 part of the notification that a subscription has started."; 519 uses uri; 520 } 522 augment "/sn:subscription-modified" { 523 description 524 "This augmentation allows HTTP specific parameters to be included 525 part of the notification that a subscription has been modified."; 526 uses uri; 527 } 529 } 530 531 9. IANA Considerations 533 This document registers the following namespace URI in the "IETF XML 534 Registry" [RFC3688]: 536 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed- 537 notifications 538 Registrant Contact: The IESG. 539 XML: N/A; the requested URI is an XML namespace. 541 This document registers the following YANG module in the "YANG Module 542 Names" registry [RFC6020]: 544 Name: ietf-restconf-subscribed-notifications 545 Namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed- 546 notifications 547 Prefix: rsn 548 Reference: RFC XXXX: RESTCONF Transport for Event Notifications 550 10. Security Considerations 552 The YANG module specified in this document defines a schema for data 553 that is designed to be accessed via network management transports 554 such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF 555 layer is the secure transport layer, and the mandatory-to-implement 556 secure transport is Secure Shell (SSH) [RFC6242]. The lowest 557 RESTCONF layer is HTTPS, and the mandatory-to-implement secure 558 transport is TLS [RFC5246]. 560 The one new data node introduced in this YANG module may be 561 considered sensitive or vulnerable in some network environments. It 562 is thus important to control read access (e.g., via get, get-config, 563 or notification) to this data nodes. These are the subtrees and data 564 nodes and their sensitivity/vulnerability: 566 Container: "/subscriptions" 568 o "uri": leaf will show where subscribed resources might be located 569 on a publisher. Access control must be set so that only someone 570 with proper access permissions, and perhaps even HTTP session has 571 the ability to access this resource. 573 11. Acknowledgments 575 We wish to acknowledge the helpful contributions, comments, and 576 suggestions that were received from: Ambika Prasad Tripathy, Alberto 577 Gonzalez Prieto, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent 578 Watsen, Michael Scharf, and Guangying Zheng. 580 12. References 582 12.1. Normative References 584 [I-D.draft-ietf-netconf-subscribed-notifications] 585 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 586 and E. Nilsen-Nygaard, "Custom Subscription to Event 587 Streams", draft-ietf-netconf-subscribed-notifications-13 588 (work in progress), April 2018. 590 [I-D.ietf-netconf-yang-push] 591 Clemm, A., Voit, E., Gonzalez Prieto, A., Prasad Tripathy, 592 A., Nilsen-Nygaard, E., Bierman, A., and B. Lengyel, 593 "Subscribing to YANG datastore push updates", March 2017, 594 . 597 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 598 Requirement Levels", BCP 14, RFC 2119, 599 DOI 10.17487/RFC2119, March 1997, 600 . 602 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 603 DOI 10.17487/RFC3688, January 2004, 604 . 606 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 607 (TLS) Protocol Version 1.2", RFC 5246, 608 DOI 10.17487/RFC5246, August 2008, 609 . 611 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 612 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 613 . 615 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 616 the Network Configuration Protocol (NETCONF)", RFC 6020, 617 DOI 10.17487/RFC6020, October 2010, 618 . 620 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 621 and A. Bierman, Ed., "Network Configuration Protocol 622 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 623 . 625 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 626 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 627 . 629 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 630 Layer Security (TLS) and Datagram Transport Layer Security 631 (DTLS) Heartbeat Extension", RFC 6520, 632 DOI 10.17487/RFC6520, February 2012, 633 . 635 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 636 Protocol (HTTP/1.1): Message Syntax and Routing", 637 RFC 7230, DOI 10.17487/RFC7230, June 2014, 638 . 640 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 641 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 642 DOI 10.17487/RFC7540, May 2015, 643 . 645 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 646 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 647 . 649 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 650 and R. Wilton, "Network Management Datastore Architecture 651 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 652 . 654 [W3C-20150203] 655 "Server-Sent Events, World Wide Web Consortium CR CR- 656 eventsource-20121211", February 2015, 657 . 659 12.2. Informative References 661 [I-D.draft-ietf-netconf-netconf-event-notifications] 662 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 663 Nilsen-Nygaard, E., and A. Tripathy, "NETCONF support for 664 event notifications", May 2018, 665 . 668 [I-D.draft-ietf-netconf-nmda-restconf] 669 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 670 and R. Wilton, "RESTCONF Extensions to Support the Network 671 Management Datastore Architecture", April 2018, 672 . 675 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 676 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 677 DOI 10.17487/RFC7231, June 2014, 678 . 680 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 681 for Subscription to YANG Datastores", RFC 7923, 682 DOI 10.17487/RFC7923, June 2016, 683 . 685 Appendix A. Examples 687 This section is non-normative. To allow easy comparison, this 688 section mirrors the functional examples shown with NETCONF over XML 689 within [I-D.draft-ietf-netconf-netconf-event-notifications]. In 690 addition, HTTP2 vs HTTP1.1 headers are not shown as the contents of 691 the JSON encoded objects are identical within. 693 A.1. Dynamic Subscriptions 695 A.1.1. Establishing Dynamic Subscriptions 697 The following figure shows two successful "establish-subscription" 698 RPC requests as per 699 [I-D.draft-ietf-netconf-subscribed-notifications]. The first request 700 is given a subscription identifier of 22, the second, an identifier 701 of 23. 703 +------------+ +-----------+ 704 | Subscriber | | Publisher | 705 +------------+ +-----------+ 706 | | 707 |establish-subscription | 708 |------------------------------>| (a) 709 | HTTP 200 OK, id#22, URI#1 | 710 |<------------------------------| (b) 711 |POST (URI#1) | 712 |------------------------------>| (c) 713 | HTTP 200 OK,notif-mesg (id#22)| 714 |<------------------------------| 715 | | 716 | | 717 |establish-subscription | 718 |------------------------------>| 719 | HTTP 200 OK, id#23, URI#2| 720 |<------------------------------| 721 |POST (URI#2) | 722 |------------------------------>| 723 | | 724 | | 725 | notif-mesg (id#22)| 726 |<------------------------------| 727 | HTTP 200 OK,notif-mesg (id#23)| 728 |<------------------------------| 729 | | 731 Figure 3: Multiple subscriptions over RESTCONF/HTTP 733 To provide examples of the information being transported, example 734 messages for interactions in Figure 3 are detailed below: 736 POST /restconf/operations/subscriptions:establish-subscription 738 { 739 "ietf-subscribed-notifications:input": { 740 "stream": "NETCONF", 741 "stream-xpath-filter": "/ex:foo/", 742 "dscp": "10" 743 } 744 } 746 Figure 4: establish-subscription request (a) 748 As publisher was able to fully satisfy the request, the publisher 749 sends the subscription identifier of the accepted subscription, and 750 the URI: 752 HTTP status code - 200 754 { 755 "id": "22", 756 "uri": "/subscriptions/22" 757 } 759 Figure 5: establish-subscription success (b) 761 Upon receipt of the successful response, the subscriber POSTs to the 762 provided URI to start the flow of notification messages. When the 763 publisher receives this, the subscription is moved to the active 764 state (c). 766 POST /restconf/operations/subscriptions/22 768 Figure 6: establish-subscription subsequent POST 770 While not shown in Figure 3, if the publisher had not been able to 771 fully satisfy the request, or subscriber has no authorization to 772 establish the subscription, the publisher would have sent an RPC 773 error response. For instance, if the "dscp" value of 10 asserted by 774 the subscriber in Figure 4 proved unacceptable, the publisher may 775 have returned: 777 HTTP status code - 406 779 { "ietf-restconf:errors" : { 780 "error" : [ 781 { 782 "error-type": "application", 783 "error-tag": "operation-failed", 784 "error-severity": "error", 785 "error-app-tag": 786 "ietf-subscribed-notifications:dscp-unavailable" 787 } 788 ] 789 } 790 } 792 Figure 7: an unsuccessful establish subscription 794 The subscriber can use this information in future attempts to 795 establish a subscription. 797 A.1.2. Modifying Dynamic Subscriptions 799 An existing subscription may be modified. The following exchange 800 shows a negotiation of such a modification via several exchanges 801 between a subscriber and a publisher. This negotiation consists of a 802 failed RPC modification request/response, followed by a successful 803 one. 805 +------------+ +-----------+ 806 | Subscriber | | Publisher | 807 +------------+ +-----------+ 808 | | 809 | notification message (id#23)| 810 |<-----------------------------| 811 | | 812 |modify-subscription (id#23) | 813 |----------------------------->| (d) 814 | HTTP 406 error (with hint)| 815 |<-----------------------------| (e) 816 | | 817 |modify-subscription (id#23) | 818 |----------------------------->| 819 | HTTP 200 OK | 820 |<-----------------------------| 821 | | 822 | notif-mesg (id#23)| 823 |<-----------------------------| 824 | | 826 Figure 8: Interaction model for successful subscription modification 828 If the subscription being modified in Figure 8 is a datastore 829 subscription as per [I-D.ietf-netconf-yang-push], the modification 830 request made in (d) may look like that shown in Figure 9. As can be 831 seen, the modifications being attempted are the application of a new 832 xpath filter as well as the setting of a new periodic time interval. 834 POST /restconf/operations/subscriptions:modify-subscription 836 { 837 "ietf-subscribed-notifications:input": { 838 "id": "23", 839 "ietf-yang-push:datastore-xpath-filter": 840 "/interfaces-state/interface/oper-status" 841 "ietf-yang-push:periodic": { 842 "ietf-yang-push:period": "500" 843 } 844 } 845 } 847 Figure 9: Subscription modification request (c) 849 If the publisher can satisfy both changes, the publisher sends a 850 positive result for the RPC. If the publisher cannot satisfy either 851 of the proposed changes, the publisher sends an RPC error response 852 (e). The following is an example RPC error response for (e) which 853 includes a hint. This hint is an alternative time period value which 854 might have resulted in a successful modification: 856 HTTP status code - 406 858 { "ietf-restconf:errors" : { 859 "error" : [ 860 "error-type": "application", 861 "error-tag": "operation-failed", 862 "error-severity": "error", 863 "error-app-tag": "ietf-yang-push:period-unsupported", 864 "error-info": { 865 "ietf-yang-push": 866 "modify-subscription-datastore-error-info": { 867 "period-hint": "3000" 868 } 869 } 870 ] 871 } 872 } 874 Figure 10: Modify subscription failure with Hint (e) 876 A.1.3. Deleting Dynamic Subscriptions 878 The following demonstrates deleting a subscription. This 879 subscription may have been to either a stream or a datastore. 881 POST /restconf/operations/subscriptions:delete-subscription 883 { 884 "delete-subscription": { 885 "id": "22" 886 } 887 } 889 Figure 11: Delete subscription 891 If the publisher can satisfy the request, the publisher replies with 892 success to the RPC request. 894 If the publisher cannot satisfy the request, the publisher sends an 895 error-rpc element indicating the modification didn't work. Figure 12 896 shows a valid response for existing valid subscription identifier, 897 but that subscription identifier was created on a different transport 898 session: 900 HTTP status code - 406 902 { 903 "ietf-restconf:errors" : { 904 "error" : [ 905 "error-type": "application", 906 "error-tag": "operation-failed", 907 "error-severity": "error", 908 "error-app-tag": 909 "ietf-subscribed-notifications:no-such-subscription" 910 ] 911 } 912 } 914 Figure 12: Unsuccessful delete subscription 916 A.2. Subscription State Notifications 918 A publisher will send subscription state notifications according to 919 the definitions within 920 [I-D.draft-ietf-netconf-subscribed-notifications]). 922 A.2.1. subscription-started and subscription-modified 924 A "subscription-started" encoded in JSON would look like: 926 { 927 "ietf-restconf:notification" : { 928 "eventTime": "2007-09-01T10:00:00Z", 929 "ietf-subscribed-notifications:subscription-started": { 930 "id": "39", 931 "transport": "HTTP2", 932 "stream-xpath-filter": "/ex:foo", 933 "stream": { 934 "ietf-netconf-subscribed-notifications" : "NETCONF" 935 } 936 } 937 } 938 } 940 Figure 13: subscription-started subscription state notification 942 The "subscription-modified" is identical to Figure 13, with just the 943 word "started" being replaced by "modified". 945 A.2.2. subscription-completed, subscription-resumed, and replay- 946 complete 948 A "subscription-completed" would look like: 950 { 951 "ietf-restconf:notification" : { 952 "eventTime": "2007-09-01T10:00:00Z", 953 "ietf-subscribed-notifications:subscription-completed": { 954 "id": "39", 955 } 956 } 957 } 959 Figure 14: subscription-completed notification in JSON 961 The "subscription-resumed" and "replay-complete" are virtually 962 identical, with "subscription-completed" simply being replaced by 963 "subscription-resumed" and "replay-complete". 965 A.2.3. subscription-terminated and subscription-suspended 967 A "subscription-terminated" would look like: 969 { 970 "ietf-restconf:notification" : { 971 "eventTime": "2007-09-01T10:00:00Z", 972 "ietf-subscribed-notifications:subscription-terminated": { 973 "id": "39", 974 "error-id": "suspension-timeout" 975 } 976 } 977 } 979 Figure 15: subscription-terminated subscription state notification 981 The "subscription-suspended" is virtually identical, with 982 "subscription-terminated" simply being replaced by "subscription- 983 suspended". 985 Appendix B. Changes between revisions 987 (To be removed by RFC editor prior to publication) 989 v06 - v07 991 o Removed configured subscriptions. 993 o Subscription identifier renamed to id. 995 v05 - v06 997 o JSON examples updated by Reshad. 999 v04 - v05 1001 o Error mechanisms updated to match embedded RESTCONF mechanisms 1003 o Restructured format and sections of document. 1005 o Added a YANG data model for HTTP specific parameters. 1007 o Mirrored the examples from the NETCONF transport draft to allow 1008 easy comparison. 1010 v03 - v04 1012 o Draft not fully synched to new version of subscribed-notifications 1013 yet. 1015 o References updated 1016 v02 - v03 1018 o Event notification reframed to notification message. 1020 o Tweaks to wording/capitalization/format. 1022 v01 - v02 1024 o Removed sections now redundant with 1025 [I-D.draft-ietf-netconf-subscribed-notifications] and 1026 [I-D.ietf-netconf-yang-push] such as: mechanisms for subscription 1027 maintenance, terminology definitions, stream discovery. 1029 o 3rd party subscriptions are out-of-scope. 1031 o SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions 1033 o Timeframes for event tagging are self-defined. 1035 o Clean-up of wording, references to terminology, section numbers. 1037 v00 - v01 1039 o Removed the ability for more than one subscription to go to a 1040 single HTTP2 stream. 1042 o Updated call flows. Extensively. 1044 o SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions 1046 o HTTP is not used to determine that a receiver has gone silent and 1047 is not Receiving Event Notifications 1049 o Many clean-ups of wording and terminology 1051 Authors' Addresses 1053 Eric Voit 1054 Cisco Systems 1056 Email: evoit@cisco.com 1058 Reshad Rahman 1059 Cisco Systems 1061 Email: rrahman@cisco.com 1062 Einar Nilsen-Nygaard 1063 Cisco Systems 1065 Email: einarnn@cisco.com 1067 Alexander Clemm 1068 Huawei 1070 Email: ludwig@clemm.org 1072 Andy Bierman 1073 YumaWorks 1075 Email: andy@yumaworks.com