idnits 2.17.1 draft-ietf-netconf-restconf-notif-13.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 206 has weird spacing: '...pported inva...' == Line 209 has weird spacing: '...ription inva...' == Line 219 has weird spacing: '...ribable inval...' == Line 222 has weird spacing: '...pported opera...' == Line 238 has weird spacing: '...ription estab...' == (3 more instances...) -- The document date (February 14, 2019) is 1890 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 (~~), 9 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: August 18, 2019 Cisco Systems 6 A. Clemm 7 Huawei 8 A. Bierman 9 YumaWorks 10 February 14, 2019 12 Dynamic subscription to YANG Events and Datastores over RESTCONF 13 draft-ietf-netconf-restconf-notif-13 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 August 18, 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) . . . . . . . . . 7 61 4. QoS Treatment . . . . . . . . . . . . . . . . . . . . . . . . 9 62 5. Notification Messages . . . . . . . . . . . . . . . . . . . . 10 63 6. YANG Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 10 64 7. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 10 65 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 66 9. Security Considerations . . . . . . . . . . . . . . . . . . . 12 67 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 13 68 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 69 11.1. Normative References . . . . . . . . . . . . . . . . . . 13 70 11.2. Informative References . . . . . . . . . . . . . . . . . 15 71 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 15 72 A.1. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 16 73 A.1.1. Establishing Dynamic Subscriptions . . . . . . . . . 16 74 A.1.2. Modifying Dynamic Subscriptions . . . . . . . . . . . 18 75 A.1.3. Deleting Dynamic Subscriptions . . . . . . . . . . . 20 76 A.2. Subscription State Notifications . . . . . . . . . . . . 21 77 A.2.1. subscription-modified . . . . . . . . . . . . . . . . 21 78 A.2.2. subscription-completed, subscription-resumed, and 79 replay-complete . . . . . . . . . . . . . . . . . . . 22 80 A.2.3. subscription-terminated and subscription-suspended . 22 81 A.3. Filter Example . . . . . . . . . . . . . . . . . . . . . 22 82 Appendix B. Changes between revisions . . . . . . . . . . . . . 24 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27 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 with the value being a string that corresponds 197 to an identity associated with the error. This "error-tag" will 198 come from one of two places. Either it will correspond to the 199 error identities within 200 [I-D.draft-ietf-netconf-subscribed-notifications] section 2.4.6 201 for general subscription errors: 203 error identity uses error-tag 204 ---------------------- -------------- 205 dscp-unavailable invalid-value 206 encoding-unsupported invalid-value 207 filter-unsupported invalid-value 208 insufficient-resources resource-denied 209 no-such-subscription invalid-value 210 replay-unsupported operation-not-supported 212 Or this "error-tag" will correspond to the error identities within 213 [I-D.ietf-netconf-yang-push] Appendix A.1 for subscription errors 214 specific to YANG datastores: 216 error identity uses error-tag 217 ---------------------- -------------- 218 cant-exclude operation-not-supported 219 datastore-not-subscribable invalid-value 220 no-such-subscription-resync invalid-value 221 on-change-unsupported operation-not-supported 222 on-change-sync-unsupported operation-not-supported 223 period-unsupported invalid-value 224 update-too-big too-big 225 sync-too-big too-big 226 unchanging-selection operation-failed 228 o an "error-app-tag" node with the value being a string that 229 corresponds to an identity associated with the error, as defined 230 in [I-D.draft-ietf-netconf-subscribed-notifications] section 2.4.6 231 for general subscriptions, and [I-D.ietf-netconf-yang-push] 232 Appendix A.1, for datastore subscriptions. The tag to use depends 233 on the RPC for which the error occurred. Viable errors for 234 different RPCs are as follows: 236 RPC select an identity with a base 237 ---------------------- ------------------------------ 238 establish-subscription establish-subscription-error 239 modify-subscription modify-subscription-error 240 delete-subscription delete-subscription-error 241 kill-subscription delete-subscription-error 242 resync-subscription resync-subscription-error 244 Each error identity will be inserted as the "error-app-tag" using 245 JSON encoding following the form :. An 246 example of such a valid encoding would be "ietf-subscribed- 247 notifications:no-such-subscription". 249 In case of error responses to an "establish-subscription" or "modify- 250 subscription" request there is the option of including an "error- 251 info" node. This node may contain hints for parameter settings that 252 might lead to successful RPC requests in the future. Following are 253 the yang-data structures which may be returned: 255 establish-subscription returns hints in yang-data structure 256 ---------------------- ------------------------------------ 257 target: event stream establish-subscription-stream-error-info 258 target: datastore establish-subscription-datastore-error-info 260 modify-subscription returns hints in yang-data structure 261 ---------------------- ------------------------------------ 262 target: event stream modify-subscription-stream-error-info 263 target: datastore modify-subscription-datastore-error-info 265 The yang-data included within "error-info" SHOULD NOT include the 266 optional leaf "error-reason", as such a leaf would be redundant 267 with information that is already placed within the 268 "error-app-tag". 270 In case of an rpc error as a result of a "delete-subscription", a 271 "kill-subscription", or a "resync-subscription" request, no 272 "error-info" needs to be included, as the "subscription-id" is 273 the only RPC input parameter and no hints regarding this RPC input 274 parameters need to be provided. 276 Note that "error-path" [RFC8040] does not need to be included with 277 the "rpc-error" element, as subscription errors are generally 278 associated with the choice of RPC input parameters. 280 3.4. Call Flow for Server-Sent Events (SSE) 282 The call flow is defined in Figure 1. The logical connections 283 denoted by (a) and (b) can be a TCP connection or an HTTP2 stream 284 (multiple HTTP2 streams can be carried in one TCP connection). 285 Requests to [I-D.draft-ietf-netconf-subscribed-notifications] or 286 [I-D.ietf-netconf-yang-push] augmented RPCs are sent on a connection 287 indicated by (a). A successful "establish-subscription" will result 288 in an RPC response returned with both a subscription identifier which 289 uniquely identifies a subscription, as well as a URI which uniquely 290 identifies the location of subscription on the publisher (b). This 291 URI is defined via the "uri" leaf the Data Model in Section 7. 293 An HTTP GET is then sent on a separate logical connection (b) to the 294 URI on the publisher. This initiates the publisher to initiate the 295 flow of notification messages which are sent in SSE [W3C-20150203] as 296 a response to the GET. 298 +--------------+ +--------------+ 299 | Subscriber | | Publisher | 300 | | | | 301 | Logical | | Logical | 302 | Connection | | Connection | 303 | (a) (b) | | (a) (b) | 304 +--------------+ +--------------+ 305 | RESTCONF POST (RPC:establish-subscription) | 306 |--------------------------------------------->| 307 | HTTP 200 OK (ID,URI)| 308 |<---------------------------------------------| 309 | |HTTP GET (URI) | 310 | |--------------------------------------------->| 311 | | HTTP 200 OK| 312 | |<---------------------------------------------| 313 | | SSE (notif-message)| 314 | |<---------------------------------------------| 315 | RESTCONF POST (RPC:modify-subscription) | | 316 |--------------------------------------------->| | 317 | | HTTP 200 OK| | 318 |<---------------------------------------------| | 319 | | SSE (subscription-modified)| 320 | |<------------------------------------------(c)| 321 | | SSE (notif-message)| 322 | |<---------------------------------------------| 323 | RESTCONF POST (RPC:delete-subscription) | | 324 |--------------------------------------------->| | 325 | | HTTP 200 OK| | 326 |<---------------------------------------------| | 327 | | | | 328 | | | | 329 (a) (b) (a) (b) 331 Figure 1: Dynamic with server-sent events 333 Additional requirements for dynamic subscriptions over SSE include: 335 o All subscription state notifications from a publisher MUST be 336 returned in a separate SSE message used by the subscription to 337 which the state change refers. 339 o Subscription RPCs MUST NOT use the connection currently providing 340 notification messages for that subscription. 342 o In addition to an RPC response for a "modify-subscription" RPC 343 traveling over (a), a "subscription-modified" state change 344 notification MUST be sent within (b). This allows the receiver to 345 know exactly when the new terms of the subscription have been 346 applied to the notification messages. See arrow (c). 348 o In addition to any required access permissions (e.g., NACM), RPCs 349 modify-subscription, resync-subscription and delete-subscription 350 SHOULD only be allowed by the same RESTCONF username [RFC8040] 351 which invoked establish-subscription. 353 o The kill-subscription RPC can be invoked by any RESTCONF username 354 with the required administrative permissions. 356 A publisher MUST terminate a subscription in the following cases: 358 o Receipt of a "delete-subscription" or a "kill-subscription" RPC 359 for that subscription. 361 o Loss of TLS heartbeat 363 A publisher MAY terminate a subscription at any time as stated in 364 [I-D.draft-ietf-netconf-subscribed-notifications] Section 1.3 366 4. QoS Treatment 368 To meet subscription quality of service promises, the publisher MUST 369 take any existing subscription "dscp" and apply it to the DSCP 370 marking in the IP header. 372 In addition, where HTTP2 transport is available to a notification 373 message queued for transport to a receiver, the publisher MUST: 375 o take any existing subscription "priority", as specified by the 376 "weighting" leaf node in 377 [I-D.draft-ietf-netconf-subscribed-notifications], and copy it 378 into the HTTP2 stream weight, [RFC7540] section 5.3, and 380 o take any existing subscription "dependency", as specified by the 381 "dependency" leaf node in 382 [I-D.draft-ietf-netconf-subscribed-notifications], and use the 383 HTTP2 stream for the parent subscription as the HTTP2 stream 384 dependency, [RFC7540] section 5.3.1, of the dependent 385 subscription. 387 o set the exclusive flag, [RFC7540] section 5.3.1, to 0. 389 5. Notification Messages 391 Notification messages transported over RESTCONF will be encoded 392 according to [RFC8040], section 6.4. 394 6. YANG Tree 396 The YANG model defined in Section 7 has one leaf augmented into three 397 places of [I-D.draft-ietf-netconf-subscribed-notifications]. 399 module: ietf-restconf-subscribed-notifications 400 augment /sn:establish-subscription/sn:output: 401 +--ro uri? inet:uri 402 augment /sn:subscriptions/sn:subscription: 403 +--ro uri? inet:uri 404 augment /sn:subscription-modified: 405 +--ro uri? inet:uri 407 7. YANG module 409 This module references 410 [I-D.draft-ietf-netconf-subscribed-notifications]. 412 file 413 "ietf-restconf-subscribed-notifications@2019-01-11.yang" 414 module ietf-restconf-subscribed-notifications { 415 yang-version 1.1; 416 namespace 417 "urn:ietf:params:xml:ns:yang:" + 418 "ietf-restconf-subscribed-notifications"; 420 prefix rsn; 422 import ietf-subscribed-notifications { 423 prefix sn; 424 } 425 import ietf-inet-types { 426 prefix inet; 427 } 429 organization "IETF NETCONF (Network Configuration) Working Group"; 430 contact 431 "WG Web: 432 WG List: 434 Editor: Eric Voit 435 437 Editor: Alexander Clemm 438 440 Editor: Reshad Rahman 441 "; 443 description 444 "Defines RESTCONF as a supported transport for subscribed 445 event notifications. 447 Copyright (c) 2019 IETF Trust and the persons identified as authors 448 of the code. All rights reserved. 450 Redistribution and use in source and binary forms, with or without 451 modification, is permitted pursuant to, and subject to the license 452 terms contained in, the Simplified BSD License set forth in Section 453 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 454 (https://trustee.ietf.org/license-info). 456 This version of this YANG module is part of RFC XXXX; see the RFC 457 itself for full legal notices."; 459 revision 2019-01-11 { 460 description 461 "Initial version"; 462 reference 463 "RFC XXXX: RESTCONF Transport for Event Notifications"; 464 } 466 grouping uri { 467 description 468 "Provides a reusable description of a URI."; 469 leaf uri { 470 type inet:uri; 471 config false; 472 description 473 "Location of a subscription specific URI on the publisher."; 474 } 475 } 477 augment "/sn:establish-subscription/sn:output" { 478 description 479 "This augmentation allows RESTCONF specific parameters for a 480 response to a publisher's subscription request."; 481 uses uri; 482 } 484 augment "/sn:subscriptions/sn:subscription" { 485 description 486 "This augmentation allows RESTCONF specific parameters to be 487 exposed for a subscription."; 488 uses uri; 489 } 491 augment "/sn:subscription-modified" { 492 description 493 "This augmentation allows RESTCONF specific parameters to be 494 included as part of the notification that a subscription has been 495 modified."; 496 uses uri; 497 } 498 } 499 501 8. IANA Considerations 503 This document registers the following namespace URI in the "IETF XML 504 Registry" [RFC3688]: 506 URI: urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed- 507 notifications 508 Registrant Contact: The IESG. 509 XML: N/A; the requested URI is an XML namespace. 511 This document registers the following YANG module in the "YANG Module 512 Names" registry [RFC6020]: 514 Name: ietf-restconf-subscribed-notifications 515 Namespace: urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed- 516 notifications 517 Prefix: rsn 518 Reference: RFC XXXX: RESTCONF Transport for Event Notifications 520 9. Security Considerations 522 The YANG module specified in this document defines a schema for data 523 that is designed to be accessed via network management transports 524 such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF 525 layer is the secure transport layer, and the mandatory-to-implement 526 secure transport is Secure Shell (SSH) [RFC6242]. The lowest 527 RESTCONF layer is HTTPS, and the mandatory-to-implement secure 528 transport is TLS [RFC5246]. 530 The one new data node introduced in this YANG module may be 531 considered sensitive or vulnerable in some network environments. It 532 is thus important to control read access (e.g., via get, get-config, 533 or notification) to this data nodes. These are the subtrees and data 534 nodes and their sensitivity/vulnerability: 536 Container: "/subscriptions" 538 o "uri": leaf will show where subscribed resources might be located 539 on a publisher. Access control must be set so that only someone 540 with proper access permissions, and perhaps even HTTP session has 541 the ability to access this resource. 543 The subscription URI is implementation specific and is encrypted via 544 the use of TLS. Therefore, even if an attacker succeeds in guessing 545 the subscription URI, a RESTCONF username [RFC8040] with the required 546 administrative permissions must be used to be able to access or 547 modify that subscription. 549 10. Acknowledgments 551 We wish to acknowledge the helpful contributions, comments, and 552 suggestions that were received from: Ambika Prasad Tripathy, Alberto 553 Gonzalez Prieto, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent 554 Watsen, Michael Scharf, Guangying Zheng, Martin Bjorklund, Qin Wu and 555 Robert Wilton. 557 11. References 559 11.1. Normative References 561 [I-D.draft-ietf-netconf-subscribed-notifications] 562 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 563 and E. Nilsen-Nygaard, "Custom Subscription to Event 564 Streams", draft-ietf-netconf-subscribed-notifications-21 565 (work in progress), January 2019. 567 [I-D.ietf-netconf-yang-push] 568 Clemm, A., Voit, E., Gonzalez Prieto, A., Prasad Tripathy, 569 A., Nilsen-Nygaard, E., Bierman, A., and B. Lengyel, 570 "Subscribing to YANG datastore push updates", draft-ietf- 571 netconf-yang-push-20 (work in progress), October 2018, 572 . 575 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 576 Requirement Levels", BCP 14, RFC 2119, 577 DOI 10.17487/RFC2119, March 1997, 578 . 580 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 581 DOI 10.17487/RFC3688, January 2004, 582 . 584 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 585 (TLS) Protocol Version 1.2", RFC 5246, 586 DOI 10.17487/RFC5246, August 2008, 587 . 589 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 590 the Network Configuration Protocol (NETCONF)", RFC 6020, 591 DOI 10.17487/RFC6020, October 2010, 592 . 594 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 595 and A. Bierman, Ed., "Network Configuration Protocol 596 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 597 . 599 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 600 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011, 601 . 603 [RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport 604 Layer Security (TLS) and Datagram Transport Layer Security 605 (DTLS) Heartbeat Extension", RFC 6520, 606 DOI 10.17487/RFC6520, February 2012, 607 . 609 [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext 610 Transfer Protocol Version 2 (HTTP/2)", RFC 7540, 611 DOI 10.17487/RFC7540, May 2015, 612 . 614 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 615 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017, 616 . 618 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 619 and R. Wilton, "Network Management Datastore Architecture 620 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 621 . 623 [W3C-20150203] 624 "Server-Sent Events, World Wide Web Consortium CR CR- 625 eventsource-20121211", February 2015, 626 . 628 11.2. Informative References 630 [I-D.draft-ietf-netconf-netconf-event-notifications] 631 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 632 Nilsen-Nygaard, E., and A. Tripathy, "NETCONF support for 633 event notifications", May 2018, 634 . 637 [I-D.draft-ietf-netconf-nmda-restconf] 638 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 639 and R. Wilton, "RESTCONF Extensions to Support the Network 640 Management Datastore Architecture", April 2018, 641 . 644 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 645 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 646 DOI 10.17487/RFC7231, June 2014, 647 . 649 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements 650 for Subscription to YANG Datastores", RFC 7923, 651 DOI 10.17487/RFC7923, June 2016, 652 . 654 [RFC8347] Liu, X., Ed., Kyparlis, A., Parikh, R., Lindem, A., and M. 655 Zhang, "A YANG Data Model for the Virtual Router 656 Redundancy Protocol (VRRP)", RFC 8347, 657 DOI 10.17487/RFC8347, March 2018, 658 . 660 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 661 Version 1.0", November 1999, 662 . 664 Appendix A. Examples 666 This section is non-normative. To allow easy comparison, this 667 section mirrors the functional examples shown with NETCONF over XML 668 within [I-D.draft-ietf-netconf-netconf-event-notifications]. In 669 addition, HTTP2 vs HTTP1.1 headers are not shown as the contents of 670 the JSON encoded objects are identical within. 672 A.1. Dynamic Subscriptions 674 A.1.1. Establishing Dynamic Subscriptions 676 The following figure shows two successful "establish-subscription" 677 RPC requests as per 678 [I-D.draft-ietf-netconf-subscribed-notifications]. The first request 679 is given a subscription identifier of 22, the second, an identifier 680 of 23. 682 +------------+ +-----------+ 683 | Subscriber | | Publisher | 684 +------------+ +-----------+ 685 | | 686 |establish-subscription | 687 |------------------------------>| (a) 688 | HTTP 200 OK, id#22, URI#1 | 689 |<------------------------------| (b) 690 |GET (URI#1) | 691 |------------------------------>| (c) 692 | HTTP 200 OK,notif-mesg (id#22)| 693 |<------------------------------| 694 | | 695 | | 696 |establish-subscription | 697 |------------------------------>| 698 | HTTP 200 OK, id#23, URI#2| 699 |<------------------------------| 700 |GET (URI#2) | 701 |------------------------------>| 702 | | 703 | | 704 | notif-mesg (id#22)| 705 |<------------------------------| 706 | HTTP 200 OK,notif-mesg (id#23)| 707 |<------------------------------| 708 | | 710 Figure 2: Multiple subscriptions over RESTCONF/HTTP 712 To provide examples of the information being transported, example 713 messages for interactions in Figure 2 are detailed below: 715 POST /restconf/operations 716 /ietf-subscribed-notifications:establish-subscription 718 { 719 "ietf-subscribed-notifications:input": { 720 "stream-xpath-filter": "/example-module:foo/", 721 "stream": "NETCONF", 722 "dscp": "10" 723 } 724 } 726 Figure 3: establish-subscription request (a) 728 As publisher was able to fully satisfy the request, the publisher 729 sends the subscription identifier of the accepted subscription, and 730 the URI: 732 HTTP status code - 200 734 { 735 "id": "22", 736 "uri": "https://example.com/restconf/subscriptions/22" 737 } 739 Figure 4: establish-subscription success (b) 741 Upon receipt of the successful response, the subscriber does a GET 742 the provided URI to start the flow of notification messages. When 743 the publisher receives this, the subscription is moved to the active 744 state (c). 746 GET /restconf/subscriptions/22 748 Figure 5: establish-subscription subsequent POST 750 While not shown in Figure 2, if the publisher had not been able to 751 fully satisfy the request, or subscriber has no authorization to 752 establish the subscription, the publisher would have sent an RPC 753 error response. For instance, if the "dscp" value of 10 asserted by 754 the subscriber in Figure 3 proved unacceptable, the publisher may 755 have returned: 757 HTTP status code - 406 759 { "ietf-restconf:errors" : { 760 "error" : [ 761 { 762 "error-type": "application", 763 "error-tag": "invalid-value", 764 "error-severity": "error", 765 "error-app-tag": 766 "ietf-subscribed-notifications:dscp-unavailable" 767 } 768 ] 769 } 770 } 772 Figure 6: an unsuccessful establish subscription 774 The subscriber can use this information in future attempts to 775 establish a subscription. 777 A.1.2. Modifying Dynamic Subscriptions 779 An existing subscription may be modified. The following exchange 780 shows a negotiation of such a modification via several exchanges 781 between a subscriber and a publisher. This negotiation consists of a 782 failed RPC modification request/response, followed by a successful 783 one. 785 +------------+ +-----------+ 786 | Subscriber | | Publisher | 787 +------------+ +-----------+ 788 | | 789 | notification message (id#23)| 790 |<-----------------------------| 791 | | 792 |modify-subscription (id#23) | 793 |----------------------------->| (d) 794 | HTTP 406 error (with hint)| 795 |<-----------------------------| (e) 796 | | 797 |modify-subscription (id#23) | 798 |----------------------------->| 799 | HTTP 200 OK | 800 |<-----------------------------| 801 | | 802 | notif-mesg (id#23)| 803 |<-----------------------------| 804 | | 806 Figure 7: Interaction model for successful subscription modification 808 If the subscription being modified in Figure 7 is a datastore 809 subscription as per [I-D.ietf-netconf-yang-push], the modification 810 request made in (d) may look like that shown in Figure 8. As can be 811 seen, the modifications being attempted are the application of a new 812 xpath filter as well as the setting of a new periodic time interval. 814 POST /restconf/operations 815 /ietf-subscribed-notifications:modify-subscription 817 { 818 "ietf-subscribed-notifications:input": { 819 "id": "23", 820 "ietf-yang-push:datastore-xpath-filter": 821 "/example-module:foo/example-module:bar", 822 "ietf-yang-push:periodic": { 823 "ietf-yang-push:period": "500" 824 } 825 } 826 } 828 Figure 8: Subscription modification request (c) 830 If the publisher can satisfy both changes, the publisher sends a 831 positive result for the RPC. If the publisher cannot satisfy either 832 of the proposed changes, the publisher sends an RPC error response 833 (e). The following is an example RPC error response for (e) which 834 includes a hint. This hint is an alternative time period value which 835 might have resulted in a successful modification: 837 HTTP status code - 406 839 { "ietf-restconf:errors" : { 840 "error" : [ 841 "error-type": "application", 842 "error-tag": "invalid-value", 843 "error-severity": "error", 844 "error-app-tag": "ietf-yang-push:period-unsupported", 845 "error-info": { 846 "ietf-yang-push": 847 "modify-subscription-datastore-error-info": { 848 "period-hint": "3000" 849 } 850 } 851 ] 852 } 853 } 855 Figure 9: Modify subscription failure with Hint (e) 857 A.1.3. Deleting Dynamic Subscriptions 859 The following demonstrates deleting a subscription. This 860 subscription may have been to either a stream or a datastore. 862 POST /restconf/operations 863 /ietf-subscribed-notifications:delete-subscription 865 { 866 "delete-subscription": { 867 "id": "22" 868 } 869 } 871 Figure 10: Delete subscription 873 If the publisher can satisfy the request, the publisher replies with 874 success to the RPC request. 876 If the publisher cannot satisfy the request, the publisher sends an 877 error-rpc element indicating the modification didn't work. Figure 11 878 shows a valid response for existing valid subscription identifier, 879 but that subscription identifier was created on a different transport 880 session: 882 HTTP status code - 406 884 { 885 "ietf-restconf:errors" : { 886 "error" : [ 887 "error-type": "application", 888 "error-tag": "invalid-value", 889 "error-severity": "error", 890 "error-app-tag": 891 "ietf-subscribed-notifications:no-such-subscription" 892 ] 893 } 894 } 896 Figure 11: Unsuccessful delete subscription 898 A.2. Subscription State Notifications 900 A publisher will send subscription state notifications according to 901 the definitions within 902 [I-D.draft-ietf-netconf-subscribed-notifications]). 904 A.2.1. subscription-modified 906 A "subscription-modified" encoded in JSON would look like: 908 { 909 "ietf-restconf:notification" : { 910 "eventTime": "2007-09-01T10:00:00Z", 911 "ietf-subscribed-notifications:subscription-modified": { 912 "id": "39", 913 "uri": "https://example.com/restconf/subscriptions/22" 914 "stream-xpath-filter": "/example-module:foo", 915 "stream": { 916 "ietf-netconf-subscribed-notifications" : "NETCONF" 917 } 918 } 919 } 920 } 922 Figure 12: subscription-modified subscription state notification 924 A.2.2. subscription-completed, subscription-resumed, and replay- 925 complete 927 A "subscription-completed" would look like: 929 { 930 "ietf-restconf:notification" : { 931 "eventTime": "2007-09-01T10:00:00Z", 932 "ietf-subscribed-notifications:subscription-completed": { 933 "id": "39", 934 } 935 } 936 } 938 Figure 13: subscription-completed notification in JSON 940 The "subscription-resumed" and "replay-complete" are virtually 941 identical, with "subscription-completed" simply being replaced by 942 "subscription-resumed" and "replay-complete". 944 A.2.3. subscription-terminated and subscription-suspended 946 A "subscription-terminated" would look like: 948 { 949 "ietf-restconf:notification" : { 950 "eventTime": "2007-09-01T10:00:00Z", 951 "ietf-subscribed-notifications:subscription-terminated": { 952 "id": "39", 953 "error-id": "suspension-timeout" 954 } 955 } 956 } 958 Figure 14: subscription-terminated subscription state notification 960 The "subscription-suspended" is virtually identical, with 961 "subscription-terminated" simply being replaced by "subscription- 962 suspended". 964 A.3. Filter Example 966 This section provides an example which illustrate the method of 967 filtering event record contents. The example is based on the YANG 968 notification "vrrp-protocol-error-event" as defined per the ietf- 969 vrrp.yang module within [RFC8347]. Event records based on this 970 specification which are generated by the publisher might appear as: 972 data: { 973 data: "ietf-restconf:notification" : { 974 data: "eventTime" : "2018-09-14T08:22:33.44Z", 975 data: "ietf-vrrp:vrrp-protocol-error-event" : { 976 data: "protocol-error-reason" : "checksum-error" 977 data: } 978 data: } 979 data: } 981 Figure 15: RFC 8347 (VRRP) - Example Notification 983 Suppose a subscriber wanted to establish a subscription which only 984 passes instances of event records where there is a "checksum-error" 985 as part of a VRRP protocol event. Also assume the publisher places 986 such event records into the NETCONF stream. To get a continuous 987 series of matching event records, the subscriber might request the 988 application of an XPath filter against the NETCONF stream. An 989 "establish-subscription" RPC to meet this objective might be: 991 POST /restconf/operations 992 /ietf-subscribed-notifications:establish-subscription 993 { 994 "ietf-subscribed-notifications:input": { 995 "stream": "NETCONF", 996 "stream-xpath-filter": 997 "/ietf-vrrp:vrrp-protocol-error-event[ 998 protocol-error-reason='checksum-error']/", 999 } 1000 } 1002 Figure 16: Establishing a subscription error reason via XPath 1004 For more examples of XPath filters, see [XPATH]. 1006 Suppose the "establish-subscription" in Figure 16 was accepted. And 1007 suppose later a subscriber decided they wanted to broaden this 1008 subscription cover to all VRRP protocol events (i.e., not just those 1009 with a "checksum error"). The subscriber might attempt to modify the 1010 subscription in a way which replaces the XPath filter with a subtree 1011 filter which sends all VRRP protocol events to a subscriber. Such a 1012 "modify-subscription" RPC might look like: 1014 POST /restconf/operations 1015 /ietf-subscribed-notifications:modify-subscription 1016 { 1017 "ietf-subscribed-notifications:input": { 1018 "stream": "NETCONF", 1019 "stream-subtree-filter": { 1020 "/ietf-vrrp:vrrp-protocol-error-event" : {} 1021 } 1022 } 1023 } 1025 Figure 17 1027 For more examples of subtree filters, see [RFC6241], section 6.4. 1029 Appendix B. Changes between revisions 1031 (To be removed by RFC editor prior to publication) 1033 v12 - v13 1035 o Enhanced "error-tag" values based on SN review. 1037 v11 - v12 1039 o Added text in 3.2 for expected behavior when ietf-restconf- 1040 monitoring.yang is also supported. 1042 o Added section 2 to the reference to draft-ietf-netconf-nmda- 1043 restconf. 1045 o Replaced kill-subscription-error by delete-subscription-error in 1046 section 3.3. 1048 o Clarified vertical lines (a) and (b) in Figure 1 of section 3.4 1050 o Section 3.4, 3rd bullet after Figure 1, replaced "must" with 1051 "MUST". 1053 o Modified text in section 3.4 regarding access to RPCs modify- 1054 subscription, resync-subscription, delete-subscription and kill- 1055 subscription. 1057 o Section 4, first bullet for HTTP2: replaced dscp and priority with 1058 weighting and weight. 1060 o Section 6, added YANG tree diagram and fixed description of the 1061 module. 1063 o Section 7, fixed indentation of module description statement. 1065 o Section 7, in YANG module changed year in copyright statement to 1066 2019. 1068 o Section 8, added text on how server protects access to the 1069 subscription URI. 1071 o Fixed outdated references and removed unused references. 1073 o Fixed the instances of line too long. 1075 o Fixed example in Figure 3. 1077 v10 - v11 1079 o Per Kent's request, added name attribute to artwork which need to 1080 be extracted 1082 v09 - v10 1084 o Fixed typo for resync. 1086 o Added text wrt RPC permissions and RESTCONF username. 1088 v08 - v09 1090 o Addressed comments received during WGLC. 1092 v07 - v08 1094 o Aligned with RESTCONF mechanism. 1096 o YANG model: removed augment of subscription-started, added 1097 restconf transport. 1099 o Tweaked Appendix A.1 to match draft-ietf-netconf-netconf-event- 1100 notifications-13. 1102 o Added Appendix A.3 for filter example. 1104 v06 - v07 1106 o Removed configured subscriptions. 1108 o Subscription identifier renamed to id. 1110 v05 - v06 1111 o JSON examples updated by Reshad. 1113 v04 - v05 1115 o Error mechanisms updated to match embedded RESTCONF mechanisms 1117 o Restructured format and sections of document. 1119 o Added a YANG data model for HTTP specific parameters. 1121 o Mirrored the examples from the NETCONF transport draft to allow 1122 easy comparison. 1124 v03 - v04 1126 o Draft not fully synched to new version of subscribed-notifications 1127 yet. 1129 o References updated 1131 v02 - v03 1133 o Event notification reframed to notification message. 1135 o Tweaks to wording/capitalization/format. 1137 v01 - v02 1139 o Removed sections now redundant with 1140 [I-D.draft-ietf-netconf-subscribed-notifications] and 1141 [I-D.ietf-netconf-yang-push] such as: mechanisms for subscription 1142 maintenance, terminology definitions, stream discovery. 1144 o 3rd party subscriptions are out-of-scope. 1146 o SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions 1148 o Timeframes for event tagging are self-defined. 1150 o Clean-up of wording, references to terminology, section numbers. 1152 v00 - v01 1154 o Removed the ability for more than one subscription to go to a 1155 single HTTP2 stream. 1157 o Updated call flows. Extensively. 1159 o SSE only used with RESTCONF and HTTP1.1 dynamic subscriptions 1161 o HTTP is not used to determine that a receiver has gone silent and 1162 is not Receiving Event Notifications 1164 o Many clean-ups of wording and terminology 1166 Authors' Addresses 1168 Eric Voit 1169 Cisco Systems 1171 Email: evoit@cisco.com 1173 Reshad Rahman 1174 Cisco Systems 1176 Email: rrahman@cisco.com 1178 Einar Nilsen-Nygaard 1179 Cisco Systems 1181 Email: einarnn@cisco.com 1183 Alexander Clemm 1184 Huawei 1186 Email: ludwig@clemm.org 1188 Andy Bierman 1189 YumaWorks 1191 Email: andy@yumaworks.com