idnits 2.17.1 draft-ietf-netconf-netconf-event-notifications-22.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 216 has weird spacing: '...pported inva...' == Line 219 has weird spacing: '...ription inva...' == Line 229 has weird spacing: '...ribable inval...' == Line 232 has weird spacing: '...pported opera...' == Line 252 has weird spacing: '...ription estab...' == (3 more instances...) == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (May 19, 2019) is 1802 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 8 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF E. Voit 3 Internet-Draft Cisco Systems 4 Intended status: Standards Track A. Clemm 5 Expires: November 20, 2019 Huawei 6 A. Gonzalez Prieto 7 Microsoft 8 E. Nilsen-Nygaard 9 A. Tripathy 10 Cisco Systems 11 May 19, 2019 13 Dynamic subscription to YANG Events and Datastores over NETCONF 14 draft-ietf-netconf-netconf-event-notifications-22 16 Abstract 18 This document provides a Network Configuration Protocol (NETCONF) 19 binding to the dynamic subscription capability of both subscribed 20 notifications and YANG-Push. 22 RFC Editor note: please replace the references to pre-RFC normative 23 drafts with the actual assigned RFC numbers. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at https://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on November 20, 2019. 42 Copyright Notice 44 Copyright (c) 2019 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (https://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 This document may contain material from IETF Documents or IETF 58 Contributions published or made publicly available before November 59 10, 2008. The person(s) controlling the copyright in some of this 60 material may not have granted the IETF Trust the right to allow 61 modifications of such material outside the IETF Standards Process. 62 Without obtaining an adequate license from the person(s) controlling 63 the copyright in such materials, this document may not be modified 64 outside the IETF Standards Process, and derivative works of it may 65 not be created outside the IETF Standards Process, except to format 66 it for publication as an RFC or to translate it into languages other 67 than English. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 72 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 73 3. Compatibility with RFC-5277's create-subscription . . . . . . 3 74 4. Mandatory XML, event stream and datastore support . . . . . . 4 75 5. NETCONF connectivity and the Dynamic Subscriptions . . . . . 4 76 6. Notification Messages . . . . . . . . . . . . . . . . . . . . 4 77 7. Dynamic Subscriptions and RPC Error Responses . . . . . . . . 5 78 8. Security Considerations . . . . . . . . . . . . . . . . . . . 7 79 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 80 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 7 81 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 82 11.1. Normative References . . . . . . . . . . . . . . . . . . 7 83 11.2. Informative References . . . . . . . . . . . . . . . . . 8 84 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 8 85 A.1. Event Stream Discovery . . . . . . . . . . . . . . . . . 8 86 A.2. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 9 87 A.3. Subscription State Notifications . . . . . . . . . . . . 14 88 A.4. Filter Examples . . . . . . . . . . . . . . . . . . . . . 15 89 Appendix B. Changes between revisions . . . . . . . . . . . . . 17 90 B.1. v21 to v22 . . . . . . . . . . . . . . . . . . . . . . . 17 91 B.2. v20 to v21 . . . . . . . . . . . . . . . . . . . . . . . 17 92 B.3. v19 to v20 . . . . . . . . . . . . . . . . . . . . . . . 17 93 B.4. v17 to v19 . . . . . . . . . . . . . . . . . . . . . . . 17 94 B.5. v16 to v17 . . . . . . . . . . . . . . . . . . . . . . . 17 95 B.6. v15 to v16 . . . . . . . . . . . . . . . . . . . . . . . 18 96 B.7. v14 to v15 . . . . . . . . . . . . . . . . . . . . . . . 18 97 B.8. v13 to v14 . . . . . . . . . . . . . . . . . . . . . . . 18 98 B.9. v11 to v13 . . . . . . . . . . . . . . . . . . . . . . . 18 99 B.10. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . 18 100 B.11. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . 18 101 B.12. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . 18 102 B.13. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . 18 103 B.14. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . 19 104 B.15. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . 19 105 B.16. v03 to v04 . . . . . . . . . . . . . . . . . . . . . . . 19 106 B.17. v01 to v03 . . . . . . . . . . . . . . . . . . . . . . . 19 107 B.18. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 19 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 19 110 1. Introduction 112 This document specifies the binding of a stream of events which form 113 part of a dynamic subscription to the NETCONF protocol [RFC6241]. 114 Dynamic subscriptions are defined in 115 [I-D.draft-ietf-netconf-subscribed-notifications]. In addition, as 116 [I-D.draft-ietf-netconf-yang-push] is itself built upon 117 [I-D.draft-ietf-netconf-subscribed-notifications], this document 118 enables a NETCONF client to request via a dynamic subscription and 119 receive updates from a YANG datastore located on a NETCONF server. 121 This document assumes that the reader is familiar with the 122 terminology and concepts defined in 123 [I-D.draft-ietf-netconf-subscribed-notifications]. 125 2. Terminology 127 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 128 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 129 "OPTIONAL" in this document are to be interpreted as described in BCP 130 14 [RFC2119] [RFC8174] when, and only when, they appear in all 131 capitals, as shown here. 133 The following terms are defined in 134 [I-D.draft-ietf-netconf-subscribed-notifications]: dynamic 135 subscription, event stream, notification message, publisher, 136 receiver, subscriber, subscription. No additional terms are defined. 138 3. Compatibility with RFC-5277's create-subscription 140 A publisher is allowed to concurrently support dynamic subscription 141 RPCs of [I-D.draft-ietf-netconf-subscribed-notifications] at the same 142 time as [RFC5277]'s "create-subscription" RPC. However a single 143 NETCONF transport session MUST NOT support both this specification 144 and a subscription established by [RFC5277]'s "create-subscription" 145 RPC. To protect against any attempts to use a single NETCONF 146 transport session in this way: 148 o A solution MUST reply with the [RFC6241] "rpc-error" element 149 containing the "error-tag" value of "operation-not-supported" if a 150 "create-subscription" RPC is received on a NETCONF session where 151 an [I-D.draft-ietf-netconf-subscribed-notifications] established 152 subscription exists. 153 o A solution MUST reply with the [RFC6241] "rpc-error" element 154 containing the "error-tag" value of "operation-not-supported" if 155 an "establish-subscription" request has been received on a NETCONF 156 session where the "create-subscription" RPC has successfully 157 [RFC5277] created a subscription. 159 If a publisher supports this specification but not subscriptions via 160 [RFC5277], the publisher MUST NOT advertise 161 "urn:ietf:params:netconf:capability:notification:1.0". 163 4. Mandatory XML, event stream and datastore support 165 The "encode-xml" feature of 166 [I-D.draft-ietf-netconf-subscribed-notifications] MUST be supported. 167 This indicates that XML is a valid encoding for RPCs, state change 168 notifications, and subscribed content. 170 A NETCONF publisher supporting event stream subscription via 171 [I-D.draft-ietf-netconf-subscribed-notifications] MUST support the 172 "NETCONF" event stream identified in that document. 174 5. NETCONF connectivity and the Dynamic Subscriptions 176 Management of dynamic subscriptions occurs via RPCs as defined in 177 [I-D.draft-ietf-netconf-yang-push] and 178 [I-D.draft-ietf-netconf-subscribed-notifications]. For a dynamic 179 subscription, if the NETCONF session involved with the "establish- 180 subscription" terminates, the subscription MUST be terminated. 182 For a dynamic subscription, any "modify-subscription", "delete- 183 subscription", or "resync-subscription" RPCs MUST be sent using the 184 same NETCONF session upon which the referenced subscription was 185 established. 187 6. Notification Messages 189 Notification messages transported over the NETCONF protocol MUST be 190 encoded in a message as defined within [RFC5277], 191 Section 4. And per [RFC5277]'s "eventTime" object definition, the 192 "eventTime" is populated with the event occurrence time. 194 For dynamic subscriptions, all notification messages MUST use the 195 NETCONF transport session used by the "establish-subscription" RPC. 197 7. Dynamic Subscriptions and RPC Error Responses 199 When an RPC error occurs as defined in 200 [I-D.draft-ietf-netconf-subscribed-notifications] Section 2.4.6 and 201 [I-D.draft-ietf-netconf-yang-push] Appendix A, the NETCONF RPC reply 202 MUST include an "rpc-error" element per [RFC6241] with the error 203 information populated as follows: 205 o An "error-type" node of "application". 206 o An "error-tag" node with the value being a string that corresponds 207 to an identity associated with the error. For the mechanisms 208 specified in this document, this "error-tag" will come from one of 209 two places. Either it will correspond to the error identities 210 within [I-D.draft-ietf-netconf-subscribed-notifications] section 211 2.4.6 for general subscription errors: 213 error identity uses error-tag 214 ---------------------- -------------- 215 dscp-unavailable invalid-value 216 encoding-unsupported invalid-value 217 filter-unsupported invalid-value 218 insufficient-resources resource-denied 219 no-such-subscription invalid-value 220 replay-unsupported operation-not-supported 222 Or this "error-tag" will correspond to the error identities within 223 [I-D.draft-ietf-netconf-yang-push] Appendix A.1 for subscription 224 errors specific to YANG datastores: 226 error identity uses error-tag 227 ---------------------- -------------- 228 cant-exclude operation-not-supported 229 datastore-not-subscribable invalid-value 230 no-such-subscription-resync invalid-value 231 on-change-unsupported operation-not-supported 232 on-change-sync-unsupported operation-not-supported 233 period-unsupported invalid-value 234 update-too-big too-big 235 sync-too-big too-big 236 unchanging-selection operation-failed 238 o an "error-severity" of "error" (this MAY be included). 239 o an "error-app-tag" node with the value being a string that 240 corresponds to an identity associated with the error, as defined 241 in [I-D.draft-ietf-netconf-subscribed-notifications] section 2.4.6 242 for general subscriptions, and [I-D.draft-ietf-netconf-yang-push] 243 Appendix A.1, for datastore subscriptions. The specific identity 244 to use depends on the RPC for which the error occurred. Each 245 error identity will be inserted as the "error-app-tag" following 246 the form :. An example of such as valid 247 encoding would be "ietf-subscribed-notifications:no-such- 248 subscription". Viable errors for different RPCs are as follows: 250 RPC have base identity 251 ---------------------- ---------------------------- 252 establish-subscription establish-subscription-error 253 modify-subscription modify-subscription-error 254 delete-subscription delete-subscription-error 255 kill-subscription delete-subscription-error 256 resync-subscription resync-subscription-error 258 o In case of error responses to an "establish-subscription" or 259 "modify-subscription" request there is the option of including an 260 "error-info" node. This node may contain XML-encoded data with 261 hints for parameter settings that might lead to successful RPC 262 requests in the future. Following are the yang-data structures 263 from [I-D.draft-ietf-netconf-subscribed-notifications] and 264 [I-D.draft-ietf-netconf-yang-push] which may be returned: 266 establish-subscription returns hints in yang-data structure 267 ---------------------- ------------------------------------ 268 target: event stream establish-subscription-stream-error-info 269 target: datastore establish-subscription-datastore-error-info 271 modify-subscription returns hints in yang-data structure 272 ---------------------- ------------------------------------ 273 target: event stream modify-subscription-stream-error-info 274 target: datastore modify-subscription-datastore-error-info 276 The yang-data included within "error-info" SHOULD NOT include the 277 optional leaf "reason", as such a leaf would be redundant 278 with information that is already placed within the 279 "error-app-tag". 281 In case of an rpc error resulting from a "delete-subscription", 282 "kill-subscription", or "resync-subscription" request, no "error- 283 info" needs to be included, as the "subscription-id" is the only RPC 284 input parameter and no hints regarding this RPC input parameters need 285 to be provided. 287 8. Security Considerations 289 This document does not introduce additional Security Considerations 290 for dynamic subscriptions beyond those discussed in 291 [I-D.draft-ietf-netconf-subscribed-notifications]. But there is one 292 consideration worthy of more refinement based on the connection 293 oriented nature of the NETCONF protocol. Specifically, if a buggy or 294 compromised NETCONF subscriber sends a number of "establish- 295 subscription" requests, then these subscriptions accumulate and may 296 use up system resources. In such a situation, subscriptions MAY be 297 terminated by terminating the underlying NETCONF session. The 298 publisher MAY also suspend or terminate a subset of the active 299 subscriptions on that NETCONF session in order to reclaim resources 300 and preserve normal operation for the other subscriptions. 302 9. IANA Considerations 304 This document has no actions for IANA. 306 10. Acknowledgments 308 We wish to acknowledge the helpful contributions, comments, and 309 suggestions that were received from: Andy Bierman, Yan Gang, Sharon 310 Chisholm, Hector Trevino, Peipei Guo, Susan Hares, Tim Jenkins, 311 Balazs Lengyel, Martin Bjorklund, Mahesh Jethanandani, Kent Watsen, 312 Qin Wu, and Guangying Zheng. 314 11. References 316 11.1. Normative References 318 [I-D.draft-ietf-netconf-subscribed-notifications] 319 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 320 and E. Nilsen-Nygaard, "Customized Subscriptions to a 321 Publisher's Event Streams", September 2018, 322 . 325 [I-D.draft-ietf-netconf-yang-push] 326 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 327 Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B. 328 Lengyel, "YANG Datastore Subscription", September 2018, 329 . 332 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 333 Requirement Levels", BCP 14, RFC 2119, 334 DOI 10.17487/RFC2119, March 1997, 335 . 337 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 338 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 339 . 341 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 342 and A. Bierman, Ed., "Network Configuration Protocol 343 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 344 . 346 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 347 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 348 May 2017, . 350 11.2. Informative References 352 [RFC8347] Liu, X., Ed., Kyparlis, A., Parikh, R., Lindem, A., and M. 353 Zhang, "A YANG Data Model for the Virtual Router 354 Redundancy Protocol (VRRP)", RFC 8347, 355 DOI 10.17487/RFC8347, March 2018, 356 . 358 [XPATH] Clark, J. and S. DeRose, "XML Path Language (XPath) 359 Version 1.0", November 1999, 360 . 362 Appendix A. Examples 364 This section is non-normative. Additionally the subscription "id" 365 values of 22, 23, and 39 used below are just examples. In 366 production, the actual values of "id" may not be small integers. 368 A.1. Event Stream Discovery 370 As defined in [I-D.draft-ietf-netconf-subscribed-notifications] an 371 event stream exposes a continuous set of events available for 372 subscription. A NETCONF client can retrieve the list of available 373 event streams from a NETCONF publisher using the "get" operation 374 against the top-level container "/streams" defined in 375 [I-D.draft-ietf-netconf-subscribed-notifications] Section 3.1. 377 The following example illustrates the retrieval of the list of 378 available event streams: 380 382 383 384 386 387 388 390 Figure 1: Get streams request 392 After such a request, the NETCONF publisher returns a list of event 393 streams available, as well as additional information which might 394 exist in the container. 396 A.2. Dynamic Subscriptions 398 A.2.1. Establishing Dynamic Subscriptions 400 The following figure shows two successful "establish-subscription" 401 RPC requests as per 402 [I-D.draft-ietf-netconf-subscribed-notifications]. The first request 403 is given a subscription "id" of 22, the second, an "id" of 23. 405 +------------+ +-----------+ 406 | Subscriber | | Publisher | 407 +------------+ +-----------+ 408 | | 409 | Capability Exchange | 410 |<---------------------------->| 411 | | 412 | | 413 | establish-subscription | 414 |----------------------------->| (a) 415 | RPC Reply: OK, id = 22 | 416 |<-----------------------------| (b) 417 | | 418 | notification message (for 22)| 419 |<-----------------------------| 420 | | 421 | | 422 | establish-subscription | 423 |----------------------------->| 424 | notification message (for 22)| 425 |<-----------------------------| 426 | RPC Reply: OK, id = 23 | 427 |<-----------------------------| 428 | | 429 | | 430 | notification message (for 22)| 431 |<-----------------------------| 432 | notification message (for 23)| 433 |<-----------------------------| 434 | | 436 Figure 2: Multiple subscriptions over a NETCONF session 438 To provide examples of the information being transported, example 439 messages for interactions (a) and (b) in Figure 2 are detailed below: 441 442 444 445 /ex:foo/ 446 447 NETCONF 448 10 449 450 452 Figure 3: establish-subscription request (a) 454 As NETCONF publisher was able to fully satisfy the request (a), the 455 publisher sends the subscription "id" of the accepted subscription 456 within message (b): 458 460 462 22 463 464 466 Figure 4: establish-subscription success (b) 468 If the NETCONF publisher had not been able to fully satisfy the 469 request, or subscriber has no authorization to establish the 470 subscription, the publisher would have sent an RPC error response. 471 For instance, if the "dscp" value of 10 asserted by the subscriber in 472 Figure 3 proved unacceptable, the publisher may have returned: 474 476 477 application 478 invalid-value 479 error 480 481 ietf-subscribed-notifications:dscp-unavailable 482 483 484 486 Figure 5: an unsuccessful establish subscription 488 The subscriber can use this information in future attempts to 489 establish a subscription. 491 A.2.2. Modifying Dynamic Subscriptions 493 An existing subscription may be modified. The following exchange 494 shows a negotiation of such a modification via several exchanges 495 between a subscriber and a publisher. This negotiation consists of a 496 failed RPC modification request/response, followed by a successful 497 one. 499 +------------+ +-----------+ 500 | Subscriber | | Publisher | 501 +------------+ +-----------+ 502 | | 503 | notification message (for 23)| 504 |<-----------------------------| 505 | | 506 | modify-subscription (id = 23)| 507 |----------------------------->| (c) 508 | RPC error (with hint) | 509 |<-----------------------------| (d) 510 | | 511 | modify-subscription (id = 23)| 512 |----------------------------->| 513 | RPC Reply: OK | 514 |<-----------------------------| 515 | | 516 | notification message (for 23)| 517 |<-----------------------------| 518 | | 520 Figure 6: Interaction model for successful subscription modification 522 If the subscription being modified in Figure 6 is a datastore 523 subscription as per [I-D.draft-ietf-netconf-yang-push], the 524 modification request made in (c) may look like that shown in 525 Figure 7. As can be seen, the modifications being attempted are the 526 application of a new XPath filter as well as the setting of a new 527 periodic time interval. 529 531 534 23 535 536 /ex:foo/ex:bar 537 538 539 500 540 541 542 544 Figure 7: Subscription modification request (c) 546 If the NETCONF publisher can satisfy both changes, the publisher 547 sends a positive result for the RPC. If the NETCONF publisher cannot 548 satisfy either of the proposed changes, the publisher sends an RPC 549 error response (d). The following is an example RPC error response 550 for (d) which includes a hint. This hint is an alternative time 551 period value which might have resulted in a successful modification: 553 555 556 application 557 invalid-value 558 error 559 560 ietf-yang-push:period-unsupported 561 562 563 565 566 3000 567 568 569 570 571 573 Figure 8: Modify subscription failure with hint (d) 575 A.2.3. Deleting Dynamic Subscriptions 577 The following demonstrates deleting a subscription. This 578 subscription may have been to either a stream or a datastore. 580 582 584 22 585 586 588 Figure 9: Delete subscription 590 If the NETCONF publisher can satisfy the request, the publisher 591 replies with success to the RPC request. 593 If the NETCONF publisher cannot satisfy the request, the publisher 594 sends an error-rpc element indicating the modification didn't work. 595 Figure 10 shows a valid response for existing valid subscription 596 "id", but that subscription "id" was created on a different NETCONF 597 transport session: 599 601 602 application 603 invalid-value 604 error 605 606 ietf-subscribed-notifications:no-such-subscription 607 608 609 611 Figure 10: Unsuccessful delete subscription 613 A.3. Subscription State Notifications 615 A publisher will send subscription state notifications for dynamic 616 subscriptions according to the definitions within 617 [I-D.draft-ietf-netconf-subscribed-notifications]. 619 A.3.1. subscription-modified 621 As per Section 2.7.2 of 622 [I-D.draft-ietf-netconf-subscribed-notifications], a "subscription- 623 modified" might be sent over NETCONF if the definition of a 624 configured filter changes. A subscription state notification encoded 625 in XML would look like: 627 628 2007-09-01T10:00:00Z 629 631 39 632 633 /ex:foo 634 635 NETCONF 636 637 639 Figure 11: subscription-modified subscription state notification 641 A.3.2. subscription-resumed, and replay-complete 643 A "subscription-resumed" would look like: 645 647 2007-09-01T10:00:00Z 648 650 39 651 652 654 Figure 12: subscription-resumed notification in XML 656 The "replay-complete" is virtually identical, with "subscription- 657 resumed" simply being replaced by "replay-complete". 659 A.3.3. subscription-terminated and subscription-suspended 661 A "subscription-terminated" would look like: 663 665 2007-09-01T10:00:00Z 666 668 39 669 670 suspension-timeout 671 672 673 675 Figure 13: subscription-terminated subscription state notification 677 The "subscription-suspended" is virtually identical, with 678 "subscription-terminated" simply being replaced by "subscription- 679 suspended". 681 A.4. Filter Examples 683 This section provides examples which illustrate both XPath and 684 subtree methods of filtering event record contents. The examples are 685 based on the YANG notification "vrrp-protocol-error-event" as defined 686 per the ietf-vrrp.yang model within [RFC8347]. Event records based 687 on this specification which are generated by the publisher might 688 appear as: 690 691 2018-09-14T08:22:33.44Z 692 694 checksum-error 695 696 698 Figure 14: RFC 8347 (VRRP) - Example Notification 700 Suppose a subscriber wanted to establish a subscription which only 701 passes instances of event records where there is a "checksum-error" 702 as part of a VRRP protocol event. Also assume the publisher places 703 such event records into the NETCONF stream. To get a continuous 704 series of matching event records, the subscriber might request the 705 application of an XPath filter against the NETCONF stream. An 706 "establish-subscription" RPC to meet this objective might be: 708 709 711 NETCONF 712 713 /vrrp-protocol-error-event[ 714 vrrp:protocol-error-reason="vrrp:checksum-error"] 715 716 717 719 Figure 15: Establishing a subscription error reason via XPath 721 For more examples of XPath filters, see [XPATH]. 723 Suppose the "establish-subscription" in Figure 15 was accepted. And 724 suppose later a subscriber decided they wanted to broaden this 725 subscription cover to all VRRP protocol events (i.e., not just those 726 with a "checksum error"). The subscriber might attempt to modify the 727 subscription in a way which replaces the XPath filter with a subtree 728 filter which sends all VRRP protocol events to a subscriber. Such a 729 "modify-subscription" RPC might look like: 731 732 734 99 735 736 738 739 740 742 Figure 16 744 For more examples of subtree filters, see [RFC6241], section 6.4. 746 Appendix B. Changes between revisions 748 (To be removed by RFC editor prior to publication) 750 B.1. v21 to v22 752 o Added "is". 754 B.2. v20 to v21 756 o Including Tom Petch's text to resolve the meaning of 'binding'. 757 o A few small wording tweaks. 759 B.3. v19 to v20 761 o Notes to RFC editor removed, consideration moved under Figure 10 762 in SN. 764 B.4. v17 to v19 766 o Per Benjamin Kaduk's discuss on SN, adjusted IPR to 767 pre5378Trust200902 769 B.5. v16 to v17 771 o During the SN YANG Doctor review, a suggestion was made to update 772 the error-tags to make the mechanism work with embedded NETCONF 773 and RESTCONF error reporting. 774 o Minor text tweaks from review. 776 B.6. v15 to v16 778 o During the shepherd review, two clarifications were requested 779 which do not impact the technical details of this document. These 780 clarifications were: (a) further describing that dynamic 781 subscriptions can have state change notifications, and (b) more 782 details about the recommended text refinement desired for RFC6241. 784 B.7. v14 to v15 786 o Per Kent's request, added name attribute to artwork. This would 787 be needed for an automated extraction. 789 B.8. v13 to v14 791 o Title change. 793 B.9. v11 to v13 795 o Subscription identifier renamed to id. 796 o Appendix A.4 for filter examples 797 o for v13, Tweak of example to /foo/bar 799 B.10. v10 to v11 801 o Configured removed. 803 B.11. v09 to v10 805 o Tweaks to examples and text. 806 o Downshifted state names. 807 o Removed address from examples. 809 B.12. v08 to v09 811 o Tweaks based on Kent's comments. 812 o Updated examples in Appendix A. And updates to some object names 813 based on changes in the subscribed-notifications draft. 814 o Added a YANG model for the NETCONF identity. 816 B.13. v07 to v08 818 o Tweaks and clarification on :interleave. 820 B.14. v06 to v07 822 o XML encoding and operational datastore mandatory. 823 o Error mechanisms and examples updated. 825 B.15. v05 to v06 827 o Moved examples to appendices 828 o All examples rewritten based on namespace learnings 829 o Normative text consolidated in front 830 o Removed all mention of JSON 831 o Call home process detailed 832 o Note: this is a major revision attempting to cover those comments 833 received from two week review. 835 B.16. v03 to v04 837 o Added additional detail to "configured subscriptions" 838 o Added interleave capability 839 o Adjusted terminology to that in draft-ietf-netconf-subscribed- 840 notifications 841 o Corrected namespaces in examples 843 B.17. v01 to v03 845 o Text simplifications throughout 846 o v02 had no meaningful changes 848 B.18. v00 to v01 850 o Added Call Home in solution for configured subscriptions. 851 o Clarified support for multiple subscription on a single session. 852 No need to support multiple create-subscription. 853 o Added mapping between terminology in yang-push and [RFC6241] (the 854 one followed in this document). 855 o Editorial improvements. 857 Authors' Addresses 859 Eric Voit 860 Cisco Systems 862 Email: evoit@cisco.com 863 Alexander Clemm 864 Huawei 866 Email: ludwig@clemm.org 868 Alberto Gonzalez Prieto 869 Microsoft 871 Email: alberto.gonzalez@microsoft.com 873 Einar Nilsen-Nygaard 874 Cisco Systems 876 Email: einarnn@cisco.com 878 Ambika Prasad Tripathy 879 Cisco Systems 881 Email: ambtripa@cisco.com