idnits 2.17.00 (12 Aug 2021) /tmp/idnits6327/draft-ietf-netconf-restconf-notif-09.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 10 instances of too long lines in the document, the longest one being 37 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...' -- The document date (October 19, 2018) is 1309 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) == Unused Reference: 'RFC5277' is defined on line 530, but no explicit reference was found in the text == Unused Reference: 'RFC7230' is defined on line 554, but no explicit reference was found in the text == Outdated reference: draft-ietf-netconf-subscribed-notifications has been published as RFC 8639 == Outdated reference: draft-ietf-netconf-yang-push has been published as RFC 8641 ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Possible downref: Non-RFC (?) normative reference: ref. 'W3C-20150203' == Outdated reference: draft-ietf-netconf-netconf-event-notifications has been published as RFC 8640 == Outdated reference: draft-ietf-netconf-nmda-restconf has been published as RFC 8527 Summary: 2 errors (**), 0 flaws (~~), 12 warnings (==), 2 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: April 22, 2019 Cisco Systems 6 A. Clemm 7 Huawei 8 A. Bierman 9 YumaWorks 10 October 19, 2018 12 Dynamic subscription to YANG Events and Datastores over RESTCONF 13 draft-ietf-netconf-restconf-notif-09 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 April 22, 2019. 37 Copyright Notice 39 Copyright (c) 2018 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 . . . . . . . . . . . . . . . . . . . . 8 63 6. YANG Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 8 64 7. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 8 65 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 66 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 67 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 68 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 69 11.1. Normative References . . . . . . . . . . . . . . . . . . 11 70 11.2. Informative References . . . . . . . . . . . . . . . . . 13 71 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 14 72 A.1. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 14 73 A.1.1. Establishing Dynamic Subscriptions . . . . . . . . . 14 74 A.1.2. Modifying Dynamic Subscriptions . . . . . . . . . . . 17 75 A.1.3. Deleting Dynamic Subscriptions . . . . . . . . . . . 18 76 A.2. Subscription State Notifications . . . . . . . . . . . . 19 77 A.2.1. subscription-modified . . . . . . . . . . . . . . . . 19 78 A.2.2. subscription-completed, subscription-resumed, and 79 replay-complete . . . . . . . . . . . . . . . . . . . 20 80 A.2.3. subscription-terminated and subscription-suspended . 20 81 A.3. Filter Example . . . . . . . . . . . . . . . . . . . . . 21 82 Appendix B. Changes between revisions . . . . . . . . . . . . . 22 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 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. 172 Subscribers can learn what datastores a RESTCONF server supports by 173 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 In case of error responses to an "establish-subscription" or "modify- 218 subscription" request there is the option of including an "error- 219 info" node. This node may contain hints for parameter settings that 220 might lead to successful RPC requests in the future. Following are 221 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" [RFC8040] does not need to be included with 245 the "rpc-error" element, as subscription errors are generally 246 associated with the choice of RPC input parameters. 248 3.4. Call Flow for Server-Sent Events (SSE) 250 The call flow is defined in Figure 1. The logical connections 251 denoted by (a) and (b) can be a TCP connection or an HTTP2 stream 252 (multiple HTTP2 streams can be carried in one TCP connection). 253 Requests to [I-D.draft-ietf-netconf-subscribed-notifications] or 254 [I-D.ietf-netconf-yang-push] augmented RPCs are sent on a connection 255 indicated by (a). A successful "establish-subscription" will result 256 in an RPC response returned with both a subscription identifier which 257 uniquely identifies a subscription, as well as a URI which uniquely 258 identifies the location of subscription on the publisher (b). This 259 URI is defined via the "uri" leaf the Data Model in Section 7. 261 An HTTP GET is then sent on a separate logical connection (b) to the 262 URI on the publisher. This initiates the publisher to initiate the 263 flow of notification messages which are sent in SSE [W3C-20150203] as 264 a response to the GET. 266 +--------------+ +--------------+ 267 | Subscriber | | Publisher | 268 | | | | 269 | Logical | | Logical | 270 | Connection | | Connection | 271 | (a) (b) | | (a) (b) | 272 +--------------+ +--------------+ 273 | RESTCONF POST (RPC:establish-subscription) | 274 |--------------------------------------------->| 275 | HTTP 200 OK (ID,URI)| 276 |<---------------------------------------------| 277 | |HTTP GET (URI) | 278 | |--------------------------------------------->| 279 | | HTTP 200 OK| 280 | |<---------------------------------------------| 281 | | SSE (notif-message)| 282 | |<---------------------------------------------| 283 | RESTCONF POST (RPC:modify-subscription) | | 284 |--------------------------------------------->| | 285 | | HTTP 200 OK| | 286 |<---------------------------------------------| | 287 | | SSE (subscription-modified)| 288 | |<------------------------------------------(c)| 289 | | SSE (notif-message)| 290 | |<---------------------------------------------| 291 | RESTCONF POST (RPC:delete-subscription) | | 292 |--------------------------------------------->| | 293 | | HTTP 200 OK| | 294 |<---------------------------------------------| | 295 | | | 296 | | 298 Figure 1: Dynamic with server-sent events 300 Additional requirements for dynamic subscriptions over SSE include: 302 o All subscription state notifications from a publisher MUST be 303 returned in a separate SSE message used by the subscription to 304 which the state change refers. 306 o Subscription RPCs MUST NOT use the connection currently providing 307 notification messages for that subscription. 309 o In addition to an RPC response for a "modify-subscription" RPC 310 traveling over (a), a "subscription-modified" state change 311 notification must be sent within (b). This allows the receiver to 312 know exactly when the new terms of the subscription have been 313 applied to the notification messages. See arrow (c). 315 A publisher MUST terminate a subscription in the following cases: 317 o Receipt of a "delete-subscription" or a "kill-subscription" RPC 318 for that subscription. 320 o Loss of TLS heartbeat 322 A publisher MAY terminate a subscription at any time as stated in 323 [I-D.draft-ietf-netconf-subscribed-notifications] Section 1.3 325 4. QoS Treatment 327 To meet subscription quality of service promises, the publisher MUST 328 take any existing subscription "dscp" and apply it to the DSCP 329 marking in the IP header. 331 In addition, where HTTP2 transport is available to a notification 332 message queued for transport to a receiver, the publisher MUST: 334 o take any existing subscription "priority", as specified by the 335 "dscp" leaf node in 336 [I-D.draft-ietf-netconf-subscribed-notifications], and copy it 337 into the HTTP2 stream priority, [RFC7540] section 5.3, and 339 o take any existing subscription "dependency", as specified by the 340 "dependency" leaf node in 341 [I-D.draft-ietf-netconf-subscribed-notifications], and use the 342 HTTP2 stream for the parent subscription as the HTTP2 stream 343 dependency, [RFC7540] section 5.3.1, of the dependent 344 subscription. 346 5. Notification Messages 348 Notification messages transported over RESTCONF will be encoded 349 according to [RFC8040], section 6.4. 351 6. YANG Tree 353 The YANG model defined in Section 7 has one leaf augmented into four 354 places of [I-D.draft-ietf-netconf-subscribed-notifications], plus two 355 identities. As the resulting full tree is large, it will only be 356 inserted at later stages of this document. 358 7. YANG module 360 This module references 361 [I-D.draft-ietf-netconf-subscribed-notifications]. 363 file "ietf-restconf-subscribed-notifications@2018-10-19.yang" 364 module ietf-restconf-subscribed-notifications { 365 yang-version 1.1; 366 namespace 367 "urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications"; 369 prefix rsn; 371 import ietf-subscribed-notifications { 372 prefix sn; 373 } 374 import ietf-inet-types { 375 prefix inet; 376 } 378 organization "IETF NETCONF (Network Configuration) Working Group"; 379 contact 380 "WG Web: 381 WG List: 383 Editor: Eric Voit 384 386 Editor: Alexander Clemm 387 389 Editor: Reshad Rahman 390 "; 392 description 393 "Defines RESTCONF as a supported transport for subscribed 394 event notifications. 396 Copyright (c) 2018 IETF Trust and the persons identified as authors 397 of the code. All rights reserved. 399 Redistribution and use in source and binary forms, with or without 400 modification, is permitted pursuant to, and subject to the license 401 terms contained in, the Simplified BSD License set forth in Section 402 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 403 (https://trustee.ietf.org/license-info). 405 This version of this YANG module is part of RFC XXXX; see the RFC 406 itself for full legal notices."; 408 revision 2018-10-19 { 409 description 410 "Initial version"; 412 reference 413 "RFC XXXX: RESTCONF Transport for Event Notifications"; 414 } 416 grouping uri { 417 description 418 "Provides a reusable description of a URI."; 419 leaf uri { 420 type inet:uri; 421 config false; 422 description 423 "Location of a subscription specific URI on the publisher."; 424 } 425 } 427 augment "/sn:establish-subscription/sn:output" { 428 description 429 "This augmentation allows RESTCONF specific parameters for a 430 response to a publisher's subscription request."; 431 uses uri; 432 } 434 augment "/sn:subscriptions/sn:subscription" { 435 description 436 "This augmentation allows RESTCONF specific parameters to be 437 exposed for a subscription."; 438 uses uri; 439 } 441 augment "/sn:subscription-modified" { 442 description 443 "This augmentation allows RESTCONF specific parameters to be included 444 part of the notification that a subscription has been modified."; 445 uses uri; 446 } 447 } 448 450 8. IANA Considerations 452 This document registers the following namespace URI in the "IETF XML 453 Registry" [RFC3688]: 455 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed- 456 notifications 457 Registrant Contact: The IESG. 458 XML: N/A; the requested URI is an XML namespace. 460 This document registers the following YANG module in the "YANG Module 461 Names" registry [RFC6020]: 463 Name: ietf-restconf-subscribed-notifications 464 Namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed- 465 notifications 466 Prefix: rsn 467 Reference: RFC XXXX: RESTCONF Transport for Event Notifications 469 9. Security Considerations 471 The YANG module specified in this document defines a schema for data 472 that is designed to be accessed via network management transports 473 such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF 474 layer is the secure transport layer, and the mandatory-to-implement 475 secure transport is Secure Shell (SSH) [RFC6242]. The lowest 476 RESTCONF layer is HTTPS, and the mandatory-to-implement secure 477 transport is TLS [RFC5246]. 479 The one new data node introduced in this YANG module may be 480 considered sensitive or vulnerable in some network environments. It 481 is thus important to control read access (e.g., via get, get-config, 482 or notification) to this data nodes. These are the subtrees and data 483 nodes and their sensitivity/vulnerability: 485 Container: "/subscriptions" 487 o "uri": leaf will show where subscribed resources might be located 488 on a publisher. Access control must be set so that only someone 489 with proper access permissions, and perhaps even HTTP session has 490 the ability to access this resource. 492 10. Acknowledgments 494 We wish to acknowledge the helpful contributions, comments, and 495 suggestions that were received from: Ambika Prasad Tripathy, Alberto 496 Gonzalez Prieto, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent 497 Watsen, Michael Scharf, Guangying Zheng, Martin Bjorklund and Qin Wu. 499 11. References 501 11.1. Normative References 503 [I-D.draft-ietf-netconf-subscribed-notifications] 504 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 505 and E. Nilsen-Nygaard, "Custom Subscription to Event 506 Streams", draft-ietf-netconf-subscribed-notifications-13 507 (work in progress), April 2018. 509 [I-D.ietf-netconf-yang-push] 510 Clemm, A., Voit, E., Gonzalez Prieto, A., Prasad Tripathy, 511 A., Nilsen-Nygaard, E., Bierman, A., and B. Lengyel, 512 "Subscribing to YANG datastore push updates", March 2017, 513 . 516 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 517 Requirement Levels", BCP 14, RFC 2119, 518 DOI 10.17487/RFC2119, March 1997, 519 . 521 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 522 DOI 10.17487/RFC3688, January 2004, 523 . 525 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 526 (TLS) Protocol Version 1.2", RFC 5246, 527 DOI 10.17487/RFC5246, August 2008, 528 . 530 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 531 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 532 . 534 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 535 the Network Configuration Protocol (NETCONF)", RFC 6020, 536 DOI 10.17487/RFC6020, October 2010, 537 . 539 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 540 and A. Bierman, Ed., "Network Configuration Protocol 541 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 542 . 544 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 545 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 546 . 548 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 549 Layer Security (TLS) and Datagram Transport Layer Security 550 (DTLS) Heartbeat Extension", RFC 6520, 551 DOI 10.17487/RFC6520, February 2012, 552 . 554 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 555 Protocol (HTTP/1.1): Message Syntax and Routing", 556 RFC 7230, DOI 10.17487/RFC7230, June 2014, 557 . 559 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 560 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 561 DOI 10.17487/RFC7540, May 2015, 562 . 564 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 565 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 566 . 568 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 569 and R. Wilton, "Network Management Datastore Architecture 570 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 571 . 573 [W3C-20150203] 574 "Server-Sent Events, World Wide Web Consortium CR CR- 575 eventsource-20121211", February 2015, 576 . 578 11.2. Informative References 580 [I-D.draft-ietf-netconf-netconf-event-notifications] 581 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 582 Nilsen-Nygaard, E., and A. Tripathy, "NETCONF support for 583 event notifications", May 2018, 584 . 587 [I-D.draft-ietf-netconf-nmda-restconf] 588 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 589 and R. Wilton, "RESTCONF Extensions to Support the Network 590 Management Datastore Architecture", April 2018, 591 . 594 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 595 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 596 DOI 10.17487/RFC7231, June 2014, 597 . 599 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 600 for Subscription to YANG Datastores", RFC 7923, 601 DOI 10.17487/RFC7923, June 2016, 602 . 604 [RFC8347] Liu, X., Ed., Kyparlis, A., Parikh, R., Lindem, A., and M. 605 Zhang, "A YANG Data Model for the Virtual Router 606 Redundancy Protocol (VRRP)", RFC 8347, 607 DOI 10.17487/RFC8347, March 2018, 608 . 610 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 611 Version 1.0", November 1999, 612 . 614 Appendix A. Examples 616 This section is non-normative. To allow easy comparison, this 617 section mirrors the functional examples shown with NETCONF over XML 618 within [I-D.draft-ietf-netconf-netconf-event-notifications]. In 619 addition, HTTP2 vs HTTP1.1 headers are not shown as the contents of 620 the JSON encoded objects are identical within. 622 A.1. Dynamic Subscriptions 624 A.1.1. Establishing Dynamic Subscriptions 626 The following figure shows two successful "establish-subscription" 627 RPC requests as per 628 [I-D.draft-ietf-netconf-subscribed-notifications]. The first request 629 is given a subscription identifier of 22, the second, an identifier 630 of 23. 632 +------------+ +-----------+ 633 | Subscriber | | Publisher | 634 +------------+ +-----------+ 635 | | 636 |establish-subscription | 637 |------------------------------>| (a) 638 | HTTP 200 OK, id#22, URI#1 | 639 |<------------------------------| (b) 640 |GET (URI#1) | 641 |------------------------------>| (c) 642 | HTTP 200 OK,notif-mesg (id#22)| 643 |<------------------------------| 644 | | 645 | | 646 |establish-subscription | 647 |------------------------------>| 648 | HTTP 200 OK, id#23, URI#2| 649 |<------------------------------| 650 |GET (URI#2) | 651 |------------------------------>| 652 | | 653 | | 654 | notif-mesg (id#22)| 655 |<------------------------------| 656 | HTTP 200 OK,notif-mesg (id#23)| 657 |<------------------------------| 658 | | 660 Figure 2: Multiple subscriptions over RESTCONF/HTTP 662 To provide examples of the information being transported, example 663 messages for interactions in Figure 2 are detailed below: 665 POST /restconf/operations/ietf-subscribed-notifications:establish-subscription 667 { 668 "ietf-subscribed-notifications:input": { 669 "stream": "NETCONF", 670 "stream-xpath-filter": "/example-module:foo/", 671 "dscp": "10" 672 } 673 } 675 Figure 3: establish-subscription request (a) 677 As publisher was able to fully satisfy the request, the publisher 678 sends the subscription identifier of the accepted subscription, and 679 the URI: 681 HTTP status code - 200 683 { 684 "id": "22", 685 "uri": "https://example.com/restconf/subscriptions/22" 686 } 688 Figure 4: establish-subscription success (b) 690 Upon receipt of the successful response, the subscriber does a GET 691 the provided URI to start the flow of notification messages. When 692 the publisher receives this, the subscription is moved to the active 693 state (c). 695 GET /restconf/subscriptions/22 697 Figure 5: establish-subscription subsequent POST 699 While not shown in Figure 2, if the publisher had not been able to 700 fully satisfy the request, or subscriber has no authorization to 701 establish the subscription, the publisher would have sent an RPC 702 error response. For instance, if the "dscp" value of 10 asserted by 703 the subscriber in Figure 3 proved unacceptable, the publisher may 704 have returned: 706 HTTP status code - 406 708 { "ietf-restconf:errors" : { 709 "error" : [ 710 { 711 "error-type": "application", 712 "error-tag": "operation-failed", 713 "error-severity": "error", 714 "error-app-tag": 715 "ietf-subscribed-notifications:dscp-unavailable" 716 } 717 ] 718 } 719 } 721 Figure 6: an unsuccessful establish subscription 723 The subscriber can use this information in future attempts to 724 establish a subscription. 726 A.1.2. Modifying Dynamic Subscriptions 728 An existing subscription may be modified. The following exchange 729 shows a negotiation of such a modification via several exchanges 730 between a subscriber and a publisher. This negotiation consists of a 731 failed RPC modification request/response, followed by a successful 732 one. 734 +------------+ +-----------+ 735 | Subscriber | | Publisher | 736 +------------+ +-----------+ 737 | | 738 | notification message (id#23)| 739 |<-----------------------------| 740 | | 741 |modify-subscription (id#23) | 742 |----------------------------->| (d) 743 | HTTP 406 error (with hint)| 744 |<-----------------------------| (e) 745 | | 746 |modify-subscription (id#23) | 747 |----------------------------->| 748 | HTTP 200 OK | 749 |<-----------------------------| 750 | | 751 | notif-mesg (id#23)| 752 |<-----------------------------| 753 | | 755 Figure 7: Interaction model for successful subscription modification 757 If the subscription being modified in Figure 7 is a datastore 758 subscription as per [I-D.ietf-netconf-yang-push], the modification 759 request made in (d) may look like that shown in Figure 8. As can be 760 seen, the modifications being attempted are the application of a new 761 xpath filter as well as the setting of a new periodic time interval. 763 POST /restconf/operations/ietf-subscribed-notifications:modify-subscription 765 { 766 "ietf-subscribed-notifications:input": { 767 "id": "23", 768 "ietf-yang-push:datastore-xpath-filter": "/example-module:foo/example-module:bar", 769 "ietf-yang-push:periodic": { 770 "ietf-yang-push:period": "500" 771 } 772 } 773 } 775 Figure 8: Subscription modification request (c) 777 If the publisher can satisfy both changes, the publisher sends a 778 positive result for the RPC. If the publisher cannot satisfy either 779 of the proposed changes, the publisher sends an RPC error response 780 (e). The following is an example RPC error response for (e) which 781 includes a hint. This hint is an alternative time period value which 782 might have resulted in a successful modification: 784 HTTP status code - 406 786 { "ietf-restconf:errors" : { 787 "error" : [ 788 "error-type": "application", 789 "error-tag": "operation-failed", 790 "error-severity": "error", 791 "error-app-tag": "ietf-yang-push:period-unsupported", 792 "error-info": { 793 "ietf-yang-push": 794 "modify-subscription-datastore-error-info": { 795 "period-hint": "3000" 796 } 797 } 798 ] 799 } 800 } 802 Figure 9: Modify subscription failure with Hint (e) 804 A.1.3. Deleting Dynamic Subscriptions 806 The following demonstrates deleting a subscription. This 807 subscription may have been to either a stream or a datastore. 809 POST /restconf/operations/ietf-subscribed-notifications:delete-subscription 811 { 812 "delete-subscription": { 813 "id": "22" 814 } 815 } 817 Figure 10: Delete subscription 819 If the publisher can satisfy the request, the publisher replies with 820 success to the RPC request. 822 If the publisher cannot satisfy the request, the publisher sends an 823 error-rpc element indicating the modification didn't work. Figure 11 824 shows a valid response for existing valid subscription identifier, 825 but that subscription identifier was created on a different transport 826 session: 828 HTTP status code - 406 830 { 831 "ietf-restconf:errors" : { 832 "error" : [ 833 "error-type": "application", 834 "error-tag": "operation-failed", 835 "error-severity": "error", 836 "error-app-tag": 837 "ietf-subscribed-notifications:no-such-subscription" 838 ] 839 } 840 } 842 Figure 11: Unsuccessful delete subscription 844 A.2. Subscription State Notifications 846 A publisher will send subscription state notifications according to 847 the definitions within 848 [I-D.draft-ietf-netconf-subscribed-notifications]). 850 A.2.1. subscription-modified 852 A "subscription-modified" encoded in JSON would look like: 854 { 855 "ietf-restconf:notification" : { 856 "eventTime": "2007-09-01T10:00:00Z", 857 "ietf-subscribed-notifications:subscription-modified": { 858 "id": "39", 859 "uri": "https://example.com/restconf/subscriptions/22" 860 "stream-xpath-filter": "/example-module:foo", 861 "stream": { 862 "ietf-netconf-subscribed-notifications" : "NETCONF" 863 } 864 } 865 } 866 } 868 Figure 12: subscription-modified subscription state notification 870 A.2.2. subscription-completed, subscription-resumed, and replay- 871 complete 873 A "subscription-completed" would look like: 875 { 876 "ietf-restconf:notification" : { 877 "eventTime": "2007-09-01T10:00:00Z", 878 "ietf-subscribed-notifications:subscription-completed": { 879 "id": "39", 880 } 881 } 882 } 884 Figure 13: subscription-completed notification in JSON 886 The "subscription-resumed" and "replay-complete" are virtually 887 identical, with "subscription-completed" simply being replaced by 888 "subscription-resumed" and "replay-complete". 890 A.2.3. subscription-terminated and subscription-suspended 892 A "subscription-terminated" would look like: 894 { 895 "ietf-restconf:notification" : { 896 "eventTime": "2007-09-01T10:00:00Z", 897 "ietf-subscribed-notifications:subscription-terminated": { 898 "id": "39", 899 "error-id": "suspension-timeout" 900 } 901 } 902 } 904 Figure 14: subscription-terminated subscription state notification 906 The "subscription-suspended" is virtually identical, with 907 "subscription-terminated" simply being replaced by "subscription- 908 suspended". 910 A.3. Filter Example 912 This section provides an example which illustrate the method of 913 filtering event record contents. The example is based on the YANG 914 notification "vrrp-protocol-error-event" as defined per the ietf- 915 vrrp.yang module within [RFC8347]. Event records based on this 916 specification which are generated by the publisher might appear as: 918 data: { 919 data: "ietf-restconf:notification" : { 920 data: "eventTime" : "2018-09-14T08:22:33.44Z", 921 data: "ietf-vrrp:vrrp-protocol-error-event" : { 922 data: "protocol-error-reason" : "checksum-error" 923 data: } 924 data: } 925 data: } 927 Figure 15: RFC 8347 (VRRP) - Example Notification 929 Suppose a subscriber wanted to establish a subscription which only 930 passes instances of event records where there is a "checksum-error" 931 as part of a VRRP protocol event. Also assume the publisher places 932 such event records into the NETCONF stream. To get a continuous 933 series of matching event records, the subscriber might request the 934 application of an XPath filter against the NETCONF stream. An 935 "establish-subscription" RPC to meet this objective might be: 937 POST /restconf/operations/ietf-subscribed-notifications:establish-subscription 938 { 939 "ietf-subscribed-notifications:input": { 940 "stream": "NETCONF", 941 "stream-xpath-filter": "/ietf-vrrp:vrrp-protocol-error-event[protocol-error-reason='checksum-error']/", 942 } 943 } 945 Figure 16: Establishing a subscription error reason via XPath 947 For more examples of XPath filters, see [XPATH]. 949 Suppose the "establish-subscription" in Figure 16 was accepted. And 950 suppose later a subscriber decided they wanted to broaden this 951 subscription cover to all VRRP protocol events (i.e., not just those 952 with a "checksum error"). The subscriber might attempt to modify the 953 subscription in a way which replaces the XPath filter with a subtree 954 filter which sends all VRRP protocol events to a subscriber. Such a 955 "modify-subscription" RPC might look like: 957 POST /restconf/operations/ietf-subscribed-notifications:modify-subscription 958 { 959 "ietf-subscribed-notifications:input": { 960 "stream": "NETCONF", 961 "stream-subtree-filter": { 962 "/ietf-vrrp:vrrp-protocol-error-event" : {} 963 } 964 } 965 } 967 Figure 17 969 For more examples of subtree filters, see [RFC6241], section 6.4. 971 Appendix B. Changes between revisions 973 (To be removed by RFC editor prior to publication) 975 v08 - v09 977 o Addressed comments received during WGLC. 979 v07 - v08 981 o Aligned with RESTCONF mechanism. 983 o YANG model: removed augment of subscription-started, added 984 restconf transport. 986 o Tweaked Appendix A.1 to match draft-ietf-netconf-netconf-event- 987 notifications-13. 989 o Added Appendix A.3 for filter example. 991 v06 - v07 993 o Removed configured subscriptions. 995 o Subscription identifier renamed to id. 997 v05 - v06 999 o JSON examples updated by Reshad. 1001 v04 - v05 1003 o Error mechanisms updated to match embedded RESTCONF mechanisms 1005 o Restructured format and sections of document. 1007 o Added a YANG data model for HTTP specific parameters. 1009 o Mirrored the examples from the NETCONF transport draft to allow 1010 easy comparison. 1012 v03 - v04 1014 o Draft not fully synched to new version of subscribed-notifications 1015 yet. 1017 o References updated 1019 v02 - v03 1021 o Event notification reframed to notification message. 1023 o Tweaks to wording/capitalization/format. 1025 v01 - v02 1027 o Removed sections now redundant with 1028 [I-D.draft-ietf-netconf-subscribed-notifications] and 1029 [I-D.ietf-netconf-yang-push] such as: mechanisms for subscription 1030 maintenance, terminology definitions, stream discovery. 1032 o 3rd party subscriptions are out-of-scope. 1034 o SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions 1036 o Timeframes for event tagging are self-defined. 1038 o Clean-up of wording, references to terminology, section numbers. 1040 v00 - v01 1042 o Removed the ability for more than one subscription to go to a 1043 single HTTP2 stream. 1045 o Updated call flows. Extensively. 1047 o SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions 1049 o HTTP is not used to determine that a receiver has gone silent and 1050 is not Receiving Event Notifications 1052 o Many clean-ups of wording and terminology 1054 Authors' Addresses 1056 Eric Voit 1057 Cisco Systems 1059 Email: evoit@cisco.com 1061 Reshad Rahman 1062 Cisco Systems 1064 Email: rrahman@cisco.com 1066 Einar Nilsen-Nygaard 1067 Cisco Systems 1069 Email: einarnn@cisco.com 1071 Alexander Clemm 1072 Huawei 1074 Email: ludwig@clemm.org 1075 Andy Bierman 1076 YumaWorks 1078 Email: andy@yumaworks.com