idnits 2.17.1 draft-ietf-netconf-restconf-notif-12.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 208 has weird spacing: '...ription estab...' == Line 227 has weird spacing: '... stream esta...' == Line 230 has weird spacing: '...ription ret...' == Line 232 has weird spacing: '... stream modi...' -- The document date (January 11, 2019) is 1925 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-21 == Outdated reference: A later version (-25) exists of draft-ietf-netconf-yang-push-20 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** 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: 2 errors (**), 0 flaws (~~), 7 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: July 15, 2019 Cisco Systems 6 A. Clemm 7 Huawei 8 A. Bierman 9 YumaWorks 10 January 11, 2019 12 Dynamic subscription to YANG Events and Datastores over RESTCONF 13 draft-ietf-netconf-restconf-notif-12 15 Abstract 17 This document provides a RESTCONF binding to the dynamic subscription 18 capability of both subscribed notifications and YANG-Push. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on July 15, 2019. 37 Copyright Notice 39 Copyright (c) 2019 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . . . 3 57 3.1. Transport Connectivity . . . . . . . . . . . . . . . . . 4 58 3.2. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 4 59 3.3. RESTCONF RPCs and HTTP Status Codes . . . . . . . . . . . 4 60 3.4. Call Flow for Server-Sent Events (SSE) . . . . . . . . . 6 61 4. QoS Treatment . . . . . . . . . . . . . . . . . . . . . . . . 8 62 5. Notification Messages . . . . . . . . . . . . . . . . . . . . 9 63 6. YANG Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 9 64 7. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 9 65 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 66 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 67 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12 68 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 69 11.1. Normative References . . . . . . . . . . . . . . . . . . 12 70 11.2. Informative References . . . . . . . . . . . . . . . . . 14 71 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 14 72 A.1. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 15 73 A.1.1. Establishing Dynamic Subscriptions . . . . . . . . . 15 74 A.1.2. Modifying Dynamic Subscriptions . . . . . . . . . . . 17 75 A.1.3. Deleting Dynamic Subscriptions . . . . . . . . . . . 19 76 A.2. Subscription State Notifications . . . . . . . . . . . . 20 77 A.2.1. subscription-modified . . . . . . . . . . . . . . . . 20 78 A.2.2. subscription-completed, subscription-resumed, and 79 replay-complete . . . . . . . . . . . . . . . . . . . 21 80 A.2.3. subscription-terminated and subscription-suspended . 21 81 A.3. Filter Example . . . . . . . . . . . . . . . . . . . . . 21 82 Appendix B. Changes between revisions . . . . . . . . . . . . . 23 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 85 1. Introduction 87 Mechanisms to support event subscription and push are defined in 88 [I-D.draft-ietf-netconf-subscribed-notifications]. Enhancements to 89 [I-D.draft-ietf-netconf-subscribed-notifications] which enable YANG 90 datastore subscription and push are defined in 91 [I-D.ietf-netconf-yang-push]. This document provides a transport 92 specification for dynamic subscriptions over RESTCONF [RFC8040]. 93 Driving these requirements is [RFC7923]. 95 The streaming of notifications encapsulating the resulting 96 information push is done via the mechanism described in section 6.3 97 of [RFC8040]. 99 2. Terminology 101 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 102 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 103 document are to be interpreted as described in RFC 2119 [RFC2119]. 105 The following terms use the definitions from 106 [I-D.draft-ietf-netconf-subscribed-notifications]: dynamic 107 subscription, event stream, notification message, publisher, 108 receiver, subscriber, and subscription. 110 Other terms reused include datastore, which is defined in [RFC8342], 111 and HTTP2 stream which maps to the definition of "stream" within 112 [RFC7540], Section 2. 114 [ note to the RFC Editor - please replace XXXX within this document 115 with the number of this document ] 117 3. Dynamic Subscriptions 119 This section provides specifics on how to establish and maintain 120 dynamic subscriptions over RESTCONF [RFC8040]. Subscribing to event 121 streams is accomplished in this way via RPCs defined within 122 [I-D.draft-ietf-netconf-subscribed-notifications] Section 2.4, the 123 RPCs are done via RESTCONF POSTs. YANG datastore subscription is 124 accomplished via augmentations to 125 [I-D.draft-ietf-netconf-subscribed-notifications] as described within 126 [I-D.ietf-netconf-yang-push] Section 4.4. 128 As described in [RFC8040] Section 6.3, a GET needs to be made against 129 a specific URI on the publisher. Subscribers cannot pre-determine 130 the URI against which a subscription might exist on a publisher, as 131 the URI will only exist after the "establish-subscription" RPC has 132 been accepted. Therefore, the POST for the "establish-subscription" 133 RPC replaces the GET request for the "location" leaf which is used in 134 [RFC8040] to obtain the URI. The subscription URI will be determined 135 and sent as part of the response to the "establish-subscription" RPC, 136 and a subsequent GET to this URI will be done in order to start the 137 flow of notification messages back to the subscriber. A subscription 138 does not move to the active state as per Section 2.4.1. of 139 [I-D.draft-ietf-netconf-subscribed-notifications] until the GET is 140 received. 142 3.1. Transport Connectivity 144 For a dynamic subscription, where a RESTCONF session doesn't already 145 exist, a new RESTCONF session is initiated from the subscriber. 147 As stated in Section 2.1 of [RFC8040], a subscriber MUST establish 148 the HTTP session over TLS [RFC5246] in order to secure the content in 149 transit. 151 Without the involvement of additional protocols, HTTP sessions by 152 themselves do not allow for a quick recognition of when the 153 communication path has been lost with the publisher. Where quick 154 recognition of the loss of a publisher is required, a subscriber 155 SHOULD use a TLS heartbeat [RFC6520], just from receiver to 156 publisher, to track HTTP session continuity. 158 Loss of the heartbeat MUST result in any subscription related TCP 159 sessions between those endpoints being torn down. A subscriber can 160 then attempt to re-establish the dynamic subscription by using the 161 procedure described in Section 3. 163 3.2. Discovery 165 Subscribers can learn what event streams a RESTCONF server supports 166 by querying the "streams" container of ietf-subscribed- 167 notification.yang in 168 [I-D.draft-ietf-netconf-subscribed-notifications]. Support for the 169 "streams" container of ietf-restconf-monitoring.yang in [RFC8040] is 170 not required. If it is supported, the event streams which are in the 171 "streams" container of ietf-subscribed-notifications.yang SHOULD also 172 be in the "streams" container of ietf-restconf-monitoring.yang. 174 Subscribers can learn what datastores a RESTCONF server supports by 175 following Section 2 of [I-D.draft-ietf-netconf-nmda-restconf]. 177 3.3. RESTCONF RPCs and HTTP Status Codes 179 Specific HTTP responses codes as defined in [RFC7231] section 6 will 180 indicate the result of RESTCONF RPC requests with publisher. An HTTP 181 status code of 200 is the proper response to any successful RPC 182 defined within [I-D.draft-ietf-netconf-subscribed-notifications] or 183 [I-D.ietf-netconf-yang-push]. 185 If a publisher fails to serve the RPC request for one of the reasons 186 indicated in [I-D.draft-ietf-netconf-subscribed-notifications] 187 Section 2.4.6 or [I-D.ietf-netconf-yang-push] Appendix A, this will 188 be indicated by "406" status code transported in the HTTP response. 190 When a "406" status code is returned, the RPC reply MUST include an 191 "rpc-error" element per [RFC8040] Section 7.1 with the following 192 parameter values: 194 o an "error-type" node of "application". 196 o an "error-tag" node of "operation-failed". 198 o an "error-app-tag" node with the value being a string that 199 corresponds to an identity associated with the error, as defined 200 in [I-D.draft-ietf-netconf-subscribed-notifications] section 2.4.6 201 for general subscriptions, and [I-D.ietf-netconf-yang-push] 202 Appendix A.1, for datastore subscriptions. The tag to use depends 203 on the RPC for which the error occurred. Viable errors for 204 different RPCs are as follows: 206 RPC select an identity with a base 207 ---------------------- ------------------------------ 208 establish-subscription establish-subscription-error 209 modify-subscription modify-subscription-error 210 delete-subscription delete-subscription-error 211 kill-subscription delete-subscription-error 212 resync-subscription resync-subscription-error 214 Each error identity will be inserted as the "error-app-tag" using 215 JSON encoding following the form :. An 216 example of such as valid encoding would be "ietf-subscribed- 217 notifications:no-such-subscription". 219 In case of error responses to an "establish-subscription" or "modify- 220 subscription" request there is the option of including an "error- 221 info" node. This node may contain hints for parameter settings that 222 might lead to successful RPC requests in the future. Following are 223 the yang-data structures which may be returned: 225 establish-subscription returns hints in yang-data structure 226 ---------------------- ------------------------------------ 227 target: event stream establish-subscription-stream-error-info 228 target: datastore establish-subscription-datastore-error-info 230 modify-subscription returns hints in yang-data structure 231 ---------------------- ------------------------------------ 232 target: event stream modify-subscription-stream-error-info 233 target: datastore modify-subscription-datastore-error-info 235 The yang-data included within "error-info" SHOULD NOT include the 236 optional leaf "error-reason", as such a leaf would be redundant 237 with information that is already placed within the 238 "error-app-tag". 240 In case of an rpc error as a result of a "delete-subscription", a 241 "kill-subscription", or a "resync-subscription" request, no 242 "error-info" needs to be included, as the "subscription-id" is 243 the only RPC input parameter and no hints regarding this RPC input 244 parameters need to be provided. 246 Note that "error-path" [RFC8040] does not need to be included with 247 the "rpc-error" element, as subscription errors are generally 248 associated with the choice of RPC input parameters. 250 3.4. Call Flow for Server-Sent Events (SSE) 252 The call flow is defined in Figure 1. The logical connections 253 denoted by (a) and (b) can be a TCP connection or an HTTP2 stream 254 (multiple HTTP2 streams can be carried in one TCP connection). 255 Requests to [I-D.draft-ietf-netconf-subscribed-notifications] or 256 [I-D.ietf-netconf-yang-push] augmented RPCs are sent on a connection 257 indicated by (a). A successful "establish-subscription" will result 258 in an RPC response returned with both a subscription identifier which 259 uniquely identifies a subscription, as well as a URI which uniquely 260 identifies the location of subscription on the publisher (b). This 261 URI is defined via the "uri" leaf the Data Model in Section 7. 263 An HTTP GET is then sent on a separate logical connection (b) to the 264 URI on the publisher. This initiates the publisher to initiate the 265 flow of notification messages which are sent in SSE [W3C-20150203] as 266 a response to the GET. 268 +--------------+ +--------------+ 269 | Subscriber | | Publisher | 270 | | | | 271 | Logical | | Logical | 272 | Connection | | Connection | 273 | (a) (b) | | (a) (b) | 274 +--------------+ +--------------+ 275 | RESTCONF POST (RPC:establish-subscription) | 276 |--------------------------------------------->| 277 | HTTP 200 OK (ID,URI)| 278 |<---------------------------------------------| 279 | |HTTP GET (URI) | 280 | |--------------------------------------------->| 281 | | HTTP 200 OK| 282 | |<---------------------------------------------| 283 | | SSE (notif-message)| 284 | |<---------------------------------------------| 285 | RESTCONF POST (RPC:modify-subscription) | | 286 |--------------------------------------------->| | 287 | | HTTP 200 OK| | 288 |<---------------------------------------------| | 289 | | SSE (subscription-modified)| 290 | |<------------------------------------------(c)| 291 | | SSE (notif-message)| 292 | |<---------------------------------------------| 293 | RESTCONF POST (RPC:delete-subscription) | | 294 |--------------------------------------------->| | 295 | | HTTP 200 OK| | 296 |<---------------------------------------------| | 297 | | | | 298 | | | | 299 (a) (b) (a) (b) 301 Figure 1: Dynamic with server-sent events 303 Additional requirements for dynamic subscriptions over SSE include: 305 o All subscription state notifications from a publisher MUST be 306 returned in a separate SSE message used by the subscription to 307 which the state change refers. 309 o Subscription RPCs MUST NOT use the connection currently providing 310 notification messages for that subscription. 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 (b). This allows the receiver to 315 know exactly when the new terms of the subscription have been 316 applied to the notification messages. See arrow (c). 318 o In addition to any required access permissions (e.g., NACM), RPCs 319 modify-subscription, resync-subscription and delete-subscription 320 SHOULD only be allowed by the same RESTCONF username [RFC8040] 321 which invoked establish-subscription. 323 o The kill-subscription RPC can be invoked by any RESTCONF username 324 with the required administrative permissions. 326 A publisher MUST terminate a subscription in the following cases: 328 o Receipt of a "delete-subscription" or a "kill-subscription" RPC 329 for that subscription. 331 o Loss of TLS heartbeat 333 A publisher MAY terminate a subscription at any time as stated in 334 [I-D.draft-ietf-netconf-subscribed-notifications] Section 1.3 336 4. QoS Treatment 338 To meet subscription quality of service promises, the publisher MUST 339 take any existing subscription "dscp" and apply it to the DSCP 340 marking in the IP header. 342 In addition, where HTTP2 transport is available to a notification 343 message queued for transport to a receiver, the publisher MUST: 345 o take any existing subscription "priority", as specified by the 346 "weighting" leaf node in 347 [I-D.draft-ietf-netconf-subscribed-notifications], and copy it 348 into the HTTP2 stream weight, [RFC7540] section 5.3, and 350 o take any existing subscription "dependency", as specified by the 351 "dependency" leaf node in 352 [I-D.draft-ietf-netconf-subscribed-notifications], and use the 353 HTTP2 stream for the parent subscription as the HTTP2 stream 354 dependency, [RFC7540] section 5.3.1, of the dependent 355 subscription. 357 o set the exclusive flag, [RFC7540] section 5.3.1, to 0. 359 5. Notification Messages 361 Notification messages transported over RESTCONF will be encoded 362 according to [RFC8040], section 6.4. 364 6. YANG Tree 366 The YANG model defined in Section 7 has one leaf augmented into three 367 places of [I-D.draft-ietf-netconf-subscribed-notifications]. 369 module: ietf-restconf-subscribed-notifications 370 augment /sn:establish-subscription/sn:output: 371 +--ro uri? inet:uri 372 augment /sn:subscriptions/sn:subscription: 373 +--ro uri? inet:uri 374 augment /sn:subscription-modified: 375 +--ro uri? inet:uri 377 7. YANG module 379 This module references 380 [I-D.draft-ietf-netconf-subscribed-notifications]. 382 file 383 "ietf-restconf-subscribed-notifications@2019-01-11.yang" 384 module ietf-restconf-subscribed-notifications { 385 yang-version 1.1; 386 namespace 387 "urn:ietf:params:xml:ns:yang:" + 388 "ietf-restconf-subscribed-notifications"; 390 prefix rsn; 392 import ietf-subscribed-notifications { 393 prefix sn; 394 } 395 import ietf-inet-types { 396 prefix inet; 397 } 399 organization "IETF NETCONF (Network Configuration) Working Group"; 400 contact 401 "WG Web: 402 WG List: 404 Editor: Eric Voit 405 407 Editor: Alexander Clemm 408 410 Editor: Reshad Rahman 411 "; 413 description 414 "Defines RESTCONF as a supported transport for subscribed 415 event notifications. 417 Copyright (c) 2019 IETF Trust and the persons identified as authors 418 of the code. All rights reserved. 420 Redistribution and use in source and binary forms, with or without 421 modification, is permitted pursuant to, and subject to the license 422 terms contained in, the Simplified BSD License set forth in Section 423 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 424 (https://trustee.ietf.org/license-info). 426 This version of this YANG module is part of RFC XXXX; see the RFC 427 itself for full legal notices."; 429 revision 2019-01-11 { 430 description 431 "Initial version"; 432 reference 433 "RFC XXXX: RESTCONF Transport for Event Notifications"; 434 } 436 grouping uri { 437 description 438 "Provides a reusable description of a URI."; 439 leaf uri { 440 type inet:uri; 441 config false; 442 description 443 "Location of a subscription specific URI on the publisher."; 444 } 445 } 447 augment "/sn:establish-subscription/sn:output" { 448 description 449 "This augmentation allows RESTCONF specific parameters for a 450 response to a publisher's subscription request."; 451 uses uri; 452 } 454 augment "/sn:subscriptions/sn:subscription" { 455 description 456 "This augmentation allows RESTCONF specific parameters to be 457 exposed for a subscription."; 458 uses uri; 459 } 461 augment "/sn:subscription-modified" { 462 description 463 "This augmentation allows RESTCONF specific parameters to be 464 included as part of the notification that a subscription has been 465 modified."; 466 uses uri; 467 } 468 } 469 471 8. IANA Considerations 473 This document registers the following namespace URI in the "IETF XML 474 Registry" [RFC3688]: 476 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed- 477 notifications 478 Registrant Contact: The IESG. 479 XML: N/A; the requested URI is an XML namespace. 481 This document registers the following YANG module in the "YANG Module 482 Names" registry [RFC6020]: 484 Name: ietf-restconf-subscribed-notifications 485 Namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed- 486 notifications 487 Prefix: rsn 488 Reference: RFC XXXX: RESTCONF Transport for Event Notifications 490 9. Security Considerations 492 The YANG module specified in this document defines a schema for data 493 that is designed to be accessed via network management transports 494 such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF 495 layer is the secure transport layer, and the mandatory-to-implement 496 secure transport is Secure Shell (SSH) [RFC6242]. The lowest 497 RESTCONF layer is HTTPS, and the mandatory-to-implement secure 498 transport is TLS [RFC5246]. 500 The one new data node introduced in this YANG module may be 501 considered sensitive or vulnerable in some network environments. It 502 is thus important to control read access (e.g., via get, get-config, 503 or notification) to this data nodes. These are the subtrees and data 504 nodes and their sensitivity/vulnerability: 506 Container: "/subscriptions" 508 o "uri": leaf will show where subscribed resources might be located 509 on a publisher. Access control must be set so that only someone 510 with proper access permissions, and perhaps even HTTP session has 511 the ability to access this resource. 513 The subscription URI is implementation specific and is encrypted via 514 the use of TLS. Therefore, even if an attacker succeeds in guessing 515 the subscription URI, a RESTCONF username [RFC8040] with the required 516 administrative permissions must be used to be able to access or 517 modify that subscription. 519 10. Acknowledgments 521 We wish to acknowledge the helpful contributions, comments, and 522 suggestions that were received from: Ambika Prasad Tripathy, Alberto 523 Gonzalez Prieto, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent 524 Watsen, Michael Scharf, Guangying Zheng, Martin Bjorklund, Qin Wu and 525 Robert Wilton. 527 11. References 529 11.1. Normative References 531 [I-D.draft-ietf-netconf-subscribed-notifications] 532 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 533 and E. Nilsen-Nygaard, "Custom Subscription to Event 534 Streams", draft-ietf-netconf-subscribed-notifications-21 535 (work in progress), January 2019. 537 [I-D.ietf-netconf-yang-push] 538 Clemm, A., Voit, E., Gonzalez Prieto, A., Prasad Tripathy, 539 A., Nilsen-Nygaard, E., Bierman, A., and B. Lengyel, 540 "Subscribing to YANG datastore push updates", draft-ietf- 541 netconf-yang-push-20 (work in progress), October 2018, 542 . 545 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 546 Requirement Levels", BCP 14, RFC 2119, 547 DOI 10.17487/RFC2119, March 1997, 548 . 550 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 551 DOI 10.17487/RFC3688, January 2004, 552 . 554 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 555 (TLS) Protocol Version 1.2", RFC 5246, 556 DOI 10.17487/RFC5246, August 2008, 557 . 559 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 560 the Network Configuration Protocol (NETCONF)", RFC 6020, 561 DOI 10.17487/RFC6020, October 2010, 562 . 564 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 565 and A. Bierman, Ed., "Network Configuration Protocol 566 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 567 . 569 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 570 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 571 . 573 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 574 Layer Security (TLS) and Datagram Transport Layer Security 575 (DTLS) Heartbeat Extension", RFC 6520, 576 DOI 10.17487/RFC6520, February 2012, 577 . 579 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 580 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 581 DOI 10.17487/RFC7540, May 2015, 582 . 584 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 585 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 586 . 588 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 589 and R. Wilton, "Network Management Datastore Architecture 590 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 591 . 593 [W3C-20150203] 594 "Server-Sent Events, World Wide Web Consortium CR CR- 595 eventsource-20121211", February 2015, 596 . 598 11.2. Informative References 600 [I-D.draft-ietf-netconf-netconf-event-notifications] 601 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 602 Nilsen-Nygaard, E., and A. Tripathy, "NETCONF support for 603 event notifications", May 2018, 604 . 607 [I-D.draft-ietf-netconf-nmda-restconf] 608 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 609 and R. Wilton, "RESTCONF Extensions to Support the Network 610 Management Datastore Architecture", April 2018, 611 . 614 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 615 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 616 DOI 10.17487/RFC7231, June 2014, 617 . 619 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 620 for Subscription to YANG Datastores", RFC 7923, 621 DOI 10.17487/RFC7923, June 2016, 622 . 624 [RFC8347] Liu, X., Ed., Kyparlis, A., Parikh, R., Lindem, A., and M. 625 Zhang, "A YANG Data Model for the Virtual Router 626 Redundancy Protocol (VRRP)", RFC 8347, 627 DOI 10.17487/RFC8347, March 2018, 628 . 630 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 631 Version 1.0", November 1999, 632 . 634 Appendix A. Examples 636 This section is non-normative. To allow easy comparison, this 637 section mirrors the functional examples shown with NETCONF over XML 638 within [I-D.draft-ietf-netconf-netconf-event-notifications]. In 639 addition, HTTP2 vs HTTP1.1 headers are not shown as the contents of 640 the JSON encoded objects are identical within. 642 A.1. Dynamic Subscriptions 644 A.1.1. Establishing Dynamic Subscriptions 646 The following figure shows two successful "establish-subscription" 647 RPC requests as per 648 [I-D.draft-ietf-netconf-subscribed-notifications]. The first request 649 is given a subscription identifier of 22, the second, an identifier 650 of 23. 652 +------------+ +-----------+ 653 | Subscriber | | Publisher | 654 +------------+ +-----------+ 655 | | 656 |establish-subscription | 657 |------------------------------>| (a) 658 | HTTP 200 OK, id#22, URI#1 | 659 |<------------------------------| (b) 660 |GET (URI#1) | 661 |------------------------------>| (c) 662 | HTTP 200 OK,notif-mesg (id#22)| 663 |<------------------------------| 664 | | 665 | | 666 |establish-subscription | 667 |------------------------------>| 668 | HTTP 200 OK, id#23, URI#2| 669 |<------------------------------| 670 |GET (URI#2) | 671 |------------------------------>| 672 | | 673 | | 674 | notif-mesg (id#22)| 675 |<------------------------------| 676 | HTTP 200 OK,notif-mesg (id#23)| 677 |<------------------------------| 678 | | 680 Figure 2: Multiple subscriptions over RESTCONF/HTTP 682 To provide examples of the information being transported, example 683 messages for interactions in Figure 2 are detailed below: 685 POST /restconf/operations 686 /ietf-subscribed-notifications:establish-subscription 688 { 689 "ietf-subscribed-notifications:input": { 690 "stream-xpath-filter": "/example-module:foo/", 691 "stream": "NETCONF", 692 "dscp": "10" 693 } 694 } 696 Figure 3: establish-subscription request (a) 698 As publisher was able to fully satisfy the request, the publisher 699 sends the subscription identifier of the accepted subscription, and 700 the URI: 702 HTTP status code - 200 704 { 705 "id": "22", 706 "uri": "https://example.com/restconf/subscriptions/22" 707 } 709 Figure 4: establish-subscription success (b) 711 Upon receipt of the successful response, the subscriber does a GET 712 the provided URI to start the flow of notification messages. When 713 the publisher receives this, the subscription is moved to the active 714 state (c). 716 GET /restconf/subscriptions/22 718 Figure 5: establish-subscription subsequent POST 720 While not shown in Figure 2, if the publisher had not been able to 721 fully satisfy the request, or subscriber has no authorization to 722 establish the subscription, the publisher would have sent an RPC 723 error response. For instance, if the "dscp" value of 10 asserted by 724 the subscriber in Figure 3 proved unacceptable, the publisher may 725 have returned: 727 HTTP status code - 406 729 { "ietf-restconf:errors" : { 730 "error" : [ 731 { 732 "error-type": "application", 733 "error-tag": "operation-failed", 734 "error-severity": "error", 735 "error-app-tag": 736 "ietf-subscribed-notifications:dscp-unavailable" 737 } 738 ] 739 } 740 } 742 Figure 6: an unsuccessful establish subscription 744 The subscriber can use this information in future attempts to 745 establish a subscription. 747 A.1.2. Modifying Dynamic Subscriptions 749 An existing subscription may be modified. The following exchange 750 shows a negotiation of such a modification via several exchanges 751 between a subscriber and a publisher. This negotiation consists of a 752 failed RPC modification request/response, followed by a successful 753 one. 755 +------------+ +-----------+ 756 | Subscriber | | Publisher | 757 +------------+ +-----------+ 758 | | 759 | notification message (id#23)| 760 |<-----------------------------| 761 | | 762 |modify-subscription (id#23) | 763 |----------------------------->| (d) 764 | HTTP 406 error (with hint)| 765 |<-----------------------------| (e) 766 | | 767 |modify-subscription (id#23) | 768 |----------------------------->| 769 | HTTP 200 OK | 770 |<-----------------------------| 771 | | 772 | notif-mesg (id#23)| 773 |<-----------------------------| 774 | | 776 Figure 7: Interaction model for successful subscription modification 778 If the subscription being modified in Figure 7 is a datastore 779 subscription as per [I-D.ietf-netconf-yang-push], the modification 780 request made in (d) may look like that shown in Figure 8. As can be 781 seen, the modifications being attempted are the application of a new 782 xpath filter as well as the setting of a new periodic time interval. 784 POST /restconf/operations 785 /ietf-subscribed-notifications:modify-subscription 787 { 788 "ietf-subscribed-notifications:input": { 789 "id": "23", 790 "ietf-yang-push:datastore-xpath-filter": 791 "/example-module:foo/example-module:bar", 792 "ietf-yang-push:periodic": { 793 "ietf-yang-push:period": "500" 794 } 795 } 796 } 798 Figure 8: Subscription modification request (c) 800 If the publisher can satisfy both changes, the publisher sends a 801 positive result for the RPC. If the publisher cannot satisfy either 802 of the proposed changes, the publisher sends an RPC error response 803 (e). The following is an example RPC error response for (e) which 804 includes a hint. This hint is an alternative time period value which 805 might have resulted in a successful modification: 807 HTTP status code - 406 809 { "ietf-restconf:errors" : { 810 "error" : [ 811 "error-type": "application", 812 "error-tag": "operation-failed", 813 "error-severity": "error", 814 "error-app-tag": "ietf-yang-push:period-unsupported", 815 "error-info": { 816 "ietf-yang-push": 817 "modify-subscription-datastore-error-info": { 818 "period-hint": "3000" 819 } 820 } 821 ] 822 } 823 } 825 Figure 9: Modify subscription failure with Hint (e) 827 A.1.3. Deleting Dynamic Subscriptions 829 The following demonstrates deleting a subscription. This 830 subscription may have been to either a stream or a datastore. 832 POST /restconf/operations 833 /ietf-subscribed-notifications:delete-subscription 835 { 836 "delete-subscription": { 837 "id": "22" 838 } 839 } 841 Figure 10: Delete subscription 843 If the publisher can satisfy the request, the publisher replies with 844 success to the RPC request. 846 If the publisher cannot satisfy the request, the publisher sends an 847 error-rpc element indicating the modification didn't work. Figure 11 848 shows a valid response for existing valid subscription identifier, 849 but that subscription identifier was created on a different transport 850 session: 852 HTTP status code - 406 854 { 855 "ietf-restconf:errors" : { 856 "error" : [ 857 "error-type": "application", 858 "error-tag": "operation-failed", 859 "error-severity": "error", 860 "error-app-tag": 861 "ietf-subscribed-notifications:no-such-subscription" 862 ] 863 } 864 } 866 Figure 11: Unsuccessful delete subscription 868 A.2. Subscription State Notifications 870 A publisher will send subscription state notifications according to 871 the definitions within 872 [I-D.draft-ietf-netconf-subscribed-notifications]). 874 A.2.1. subscription-modified 876 A "subscription-modified" encoded in JSON would look like: 878 { 879 "ietf-restconf:notification" : { 880 "eventTime": "2007-09-01T10:00:00Z", 881 "ietf-subscribed-notifications:subscription-modified": { 882 "id": "39", 883 "uri": "https://example.com/restconf/subscriptions/22" 884 "stream-xpath-filter": "/example-module:foo", 885 "stream": { 886 "ietf-netconf-subscribed-notifications" : "NETCONF" 887 } 888 } 889 } 890 } 892 Figure 12: subscription-modified subscription state notification 894 A.2.2. subscription-completed, subscription-resumed, and replay- 895 complete 897 A "subscription-completed" would look like: 899 { 900 "ietf-restconf:notification" : { 901 "eventTime": "2007-09-01T10:00:00Z", 902 "ietf-subscribed-notifications:subscription-completed": { 903 "id": "39", 904 } 905 } 906 } 908 Figure 13: subscription-completed notification in JSON 910 The "subscription-resumed" and "replay-complete" are virtually 911 identical, with "subscription-completed" simply being replaced by 912 "subscription-resumed" and "replay-complete". 914 A.2.3. subscription-terminated and subscription-suspended 916 A "subscription-terminated" would look like: 918 { 919 "ietf-restconf:notification" : { 920 "eventTime": "2007-09-01T10:00:00Z", 921 "ietf-subscribed-notifications:subscription-terminated": { 922 "id": "39", 923 "error-id": "suspension-timeout" 924 } 925 } 926 } 928 Figure 14: subscription-terminated subscription state notification 930 The "subscription-suspended" is virtually identical, with 931 "subscription-terminated" simply being replaced by "subscription- 932 suspended". 934 A.3. Filter Example 936 This section provides an example which illustrate the method of 937 filtering event record contents. The example is based on the YANG 938 notification "vrrp-protocol-error-event" as defined per the ietf- 939 vrrp.yang module within [RFC8347]. Event records based on this 940 specification which are generated by the publisher might appear as: 942 data: { 943 data: "ietf-restconf:notification" : { 944 data: "eventTime" : "2018-09-14T08:22:33.44Z", 945 data: "ietf-vrrp:vrrp-protocol-error-event" : { 946 data: "protocol-error-reason" : "checksum-error" 947 data: } 948 data: } 949 data: } 951 Figure 15: RFC 8347 (VRRP) - Example Notification 953 Suppose a subscriber wanted to establish a subscription which only 954 passes instances of event records where there is a "checksum-error" 955 as part of a VRRP protocol event. Also assume the publisher places 956 such event records into the NETCONF stream. To get a continuous 957 series of matching event records, the subscriber might request the 958 application of an XPath filter against the NETCONF stream. An 959 "establish-subscription" RPC to meet this objective might be: 961 POST /restconf/operations 962 /ietf-subscribed-notifications:establish-subscription 963 { 964 "ietf-subscribed-notifications:input": { 965 "stream": "NETCONF", 966 "stream-xpath-filter": 967 "/ietf-vrrp:vrrp-protocol-error-event[ 968 protocol-error-reason='checksum-error']/", 969 } 970 } 972 Figure 16: Establishing a subscription error reason via XPath 974 For more examples of XPath filters, see [XPATH]. 976 Suppose the "establish-subscription" in Figure 16 was accepted. And 977 suppose later a subscriber decided they wanted to broaden this 978 subscription cover to all VRRP protocol events (i.e., not just those 979 with a "checksum error"). The subscriber might attempt to modify the 980 subscription in a way which replaces the XPath filter with a subtree 981 filter which sends all VRRP protocol events to a subscriber. Such a 982 "modify-subscription" RPC might look like: 984 POST /restconf/operations 985 /ietf-subscribed-notifications:modify-subscription 986 { 987 "ietf-subscribed-notifications:input": { 988 "stream": "NETCONF", 989 "stream-subtree-filter": { 990 "/ietf-vrrp:vrrp-protocol-error-event" : {} 991 } 992 } 993 } 995 Figure 17 997 For more examples of subtree filters, see [RFC6241], section 6.4. 999 Appendix B. Changes between revisions 1001 (To be removed by RFC editor prior to publication) 1003 v11 - v12 1005 o Added text in 3.2 for expected behavior when ietf-restconf- 1006 monitoring.yang is also supported. 1008 o Added section 2 to the reference to draft-ietf-netconf-nmda- 1009 restconf. 1011 o Replaced kill-subscription-error by delete-subscription-error in 1012 section 3.3. 1014 o Clarified vertical lines (a) and (b) in Figure 1 of section 3.4 1016 o Section 3.4, 3rd bullet after Figure 1, replaced "must" with 1017 "MUST". 1019 o Modified text in section 3.4 regarding access to RPCs modify- 1020 subscription, resync-subscription, delete-subscription and kill- 1021 subscription. 1023 o Section 4, first bullet for HTTP2: replaced dscp and priority with 1024 weighting and weight. 1026 o Section 6, added YANG tree diagram and fixed description of the 1027 module. 1029 o Section 7, fixed indentation of module description statement. 1031 o Section 7, in YANG module changed year in copyright statement to 1032 2019. 1034 o Section 8, added text on how server protects access to the 1035 subscription URI. 1037 o Fixed outdated references and removed unused references. 1039 o Fixed the instances of line too long. 1041 o Fixed example in Figure 3. 1043 v10 - v11 1045 o Per Kent's request, added name attribute to artwork which need to 1046 be extracted 1048 v09 - v10 1050 o Fixed typo for resync. 1052 o Added text wrt RPC permissions and RESTCONF username. 1054 v08 - v09 1056 o Addressed comments received during WGLC. 1058 v07 - v08 1060 o Aligned with RESTCONF mechanism. 1062 o YANG model: removed augment of subscription-started, added 1063 restconf transport. 1065 o Tweaked Appendix A.1 to match draft-ietf-netconf-netconf-event- 1066 notifications-13. 1068 o Added Appendix A.3 for filter example. 1070 v06 - v07 1072 o Removed configured subscriptions. 1074 o Subscription identifier renamed to id. 1076 v05 - v06 1078 o JSON examples updated by Reshad. 1080 v04 - v05 1082 o Error mechanisms updated to match embedded RESTCONF mechanisms 1084 o Restructured format and sections of document. 1086 o Added a YANG data model for HTTP specific parameters. 1088 o Mirrored the examples from the NETCONF transport draft to allow 1089 easy comparison. 1091 v03 - v04 1093 o Draft not fully synched to new version of subscribed-notifications 1094 yet. 1096 o References updated 1098 v02 - v03 1100 o Event notification reframed to notification message. 1102 o Tweaks to wording/capitalization/format. 1104 v01 - v02 1106 o Removed sections now redundant with 1107 [I-D.draft-ietf-netconf-subscribed-notifications] and 1108 [I-D.ietf-netconf-yang-push] such as: mechanisms for subscription 1109 maintenance, terminology definitions, stream discovery. 1111 o 3rd party subscriptions are out-of-scope. 1113 o SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions 1115 o Timeframes for event tagging are self-defined. 1117 o Clean-up of wording, references to terminology, section numbers. 1119 v00 - v01 1121 o Removed the ability for more than one subscription to go to a 1122 single HTTP2 stream. 1124 o Updated call flows. Extensively. 1126 o SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions 1127 o HTTP is not used to determine that a receiver has gone silent and 1128 is not Receiving Event Notifications 1130 o Many clean-ups of wording and terminology 1132 Authors' Addresses 1134 Eric Voit 1135 Cisco Systems 1137 Email: evoit@cisco.com 1139 Reshad Rahman 1140 Cisco Systems 1142 Email: rrahman@cisco.com 1144 Einar Nilsen-Nygaard 1145 Cisco Systems 1147 Email: einarnn@cisco.com 1149 Alexander Clemm 1150 Huawei 1152 Email: ludwig@clemm.org 1154 Andy Bierman 1155 YumaWorks 1157 Email: andy@yumaworks.com