idnits 2.17.1 draft-ietf-netconf-netconf-event-notifications-11.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 : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 181 has weird spacing: '...ription estab...' == Line 185 has weird spacing: '...ription res...' == Line 201 has weird spacing: '... stream esta...' == Line 204 has weird spacing: '...ription ret...' == Line 206 has weird spacing: '... stream modi...' -- The document date (August 3, 2018) is 2086 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-15 Summary: 1 error (**), 0 flaws (~~), 7 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: February 4, 2019 Huawei 6 A. Gonzalez Prieto 7 Microsoft 8 E. Nilsen-Nygaard 9 A. Tripathy 10 Cisco Systems 11 August 3, 2018 13 NETCONF Support for Event Notifications 14 draft-ietf-netconf-netconf-event-notifications-11 16 Abstract 18 This document provides a NETCONF binding to the dynamic subscription 19 capability of both subscribed notifications and YANG push. 21 RFC Editor note: please replace the four references to pre-RFC 22 normative drafts with the actual assigned RFC numbers. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on February 4, 2019. 41 Copyright Notice 43 Copyright (c) 2018 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 3. Compatibility with RFC-5277's create-subscription . . . . . . 3 61 4. Mandatory XML, event stream and datastore support . . . . . . 3 62 5. NETCONF connectivity and the Dynamic Subscriptions . . . . . 4 63 6. Notification Messages . . . . . . . . . . . . . . . . . . . . 4 64 7. Dynamic Subscriptions and RPC Error Responses . . . . . . . . 4 65 8. Security Considerations . . . . . . . . . . . . . . . . . . . 5 66 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 5 67 10. Normative References . . . . . . . . . . . . . . . . . . . . 6 68 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 6 69 A.1. Event Stream Discovery . . . . . . . . . . . . . . . . . 6 70 A.2. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 7 71 A.3. Subscription State Notifications . . . . . . . . . . . . 12 72 Appendix B. Changes between revisions . . . . . . . . . . . . . 13 73 B.1. v10 to v11 . . . . . . . . . . . . . . . . . . . . . . . 14 74 B.2. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . 14 75 B.3. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . 14 76 B.4. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . 14 77 B.5. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . 14 78 B.6. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . 14 79 B.7. v03 to v04 . . . . . . . . . . . . . . . . . . . . . . . 14 80 B.8. v01 to v03 . . . . . . . . . . . . . . . . . . . . . . . 15 81 B.9. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 15 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 84 1. Introduction 86 This document provides a binding for events streamed over the NETCONF 87 protocol [RFC6241] for dyanamic subscriptions as defined in 88 [I-D.draft-ietf-netconf-subscribed-notifications]. In addition, as 89 [I-D.ietf-netconf-yang-push] is itself built upon 90 [I-D.draft-ietf-netconf-subscribed-notifications], this document 91 enables a NETCONF client to request via a dynamic subscription and 92 receive updates from a YANG datastore located on a NETCONF server. 94 2. Terminology 96 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 97 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 98 "OPTIONAL" in this document are to be interpreted as described in BCP 99 14 [RFC2119] [RFC8174] when, and only when, they appear in all 100 capitals, as shown here. 102 The following terms are defined in 103 [I-D.draft-ietf-netconf-subscribed-notifications]: notification 104 message, event stream, publisher, receiver, subscriber, subscription. 106 3. Compatibility with RFC-5277's create-subscription 108 A publisher is allowed to concurrently support dynamic subscription 109 RPCs of [I-D.draft-ietf-netconf-subscribed-notifications] at the same 110 time as [RFC5277]'s "create-subscription" RPC. However a single 111 NETCONF transport session cannot support both this specification and 112 a subscription established by [RFC5277]'s "create-subscription" RPC. 113 To protect against any attempts to use a single NETCONF transport 114 session in this way: 116 o A solution must reply with the [RFC6241] error "operation-not- 117 supported" if a "create-subscription" RPC is received on a NETCONF 118 session where an [I-D.draft-ietf-netconf-subscribed-notifications] 119 established subscription exists. 120 o A solution must reply with the [RFC6241] error "operation-not- 121 supported" if an "establish-subscription" request is been received 122 on a NETCONF session where the "create-subscription" RPC has 123 successfully [RFC5277] created a subscription. 125 If a publisher supports this specification but not subscriptions via 126 [RFC5277], the publisher MUST NOT advertise 127 "urn:ietf:params:netconf:capability:notification:1.0". 129 4. Mandatory XML, event stream and datastore support 131 The "encode-xml" feature of 132 [I-D.draft-ietf-netconf-subscribed-notifications] is mandatory to 133 support. This indicates that XML is a valid encoding for RPCs, state 134 change notifications, and subscribed content. 136 A NETCONF publisher supporting event stream subscription via 137 [I-D.draft-ietf-netconf-subscribed-notifications] MUST support the 138 "NETCONF" event stream identified in that draft. 140 5. NETCONF connectivity and the Dynamic Subscriptions 142 For a dynamic subscription, if the NETCONF session involved with the 143 "establish-subscription" terminates, the subscription MUST be 144 terminated. 146 For a dynamic subscription a "modify-subscription", "delete- 147 subscription", or "resynch-subscription" RPC MUST be sent using same 148 the NETCONF session upon which the referenced subscription was 149 established. 151 6. Notification Messages 153 Notification messages transported over the NETCONF protocol will use 154 the "notification" message defined within [RFC5277], section 4. 156 For dynamic subscriptions, all notification messages MUST use the 157 NETCONF transport session used by the "establish-subscription" RPC. 159 7. Dynamic Subscriptions and RPC Error Responses 161 Management of dynamic subscriptions occurs via RPCs as defined in 162 [I-D.ietf-netconf-yang-push] and 163 [I-D.draft-ietf-netconf-subscribed-notifications]. When an RPC error 164 occurs, the NETCONF RPC reply MUST include an "rpc-error" element per 165 [RFC6241] with the error information populated as follows: 167 o an "error-type" node of "application". 168 o an "error-tag" node of "operation-failed". 169 o an "error-severity" of "error" (this MAY but does not have to be 170 included). 171 o an "error-app-tag" node with the value being a string that 172 corresponds to an identity associated with the error, as defined 173 in [I-D.draft-ietf-netconf-subscribed-notifications] section 2.4.6 174 for general subscriptions, and [I-D.ietf-netconf-yang-push] 175 Appendix A.1, for datastore subscriptions. The identityname to 176 use depends on the RPC for which the error occurred. Viable 177 errors for different RPCs are as follows: 179 RPC use base identity 180 ---------------------- ---------------------------- 181 establish-subscription establish-subscription-error 182 modify-subscription modify-subscription-error 183 delete-subscription delete-subscription-error 184 kill-subscription kill-subscription-error 185 resynch-subscription resynch-subscription-error 187 Each error identity will be inserted as the "error-app-tag" using 188 JSON encoding following the form :. An 189 example of such as valid encoding would be "ietf-subscribed- 190 notifications:no-such-subscription". 192 o In case of error responses to an "establish-subscription" or 193 "modify-subscription" request there is the option of including an 194 "error-info" node. This node may contain XML-encoded data with 195 hints for parameter settings that might lead to successful RPC 196 requests in the future. Following are the yang-data structures 197 which may be returned: 199 establish-subscription returns hints in yang-data structure 200 ---------------------- ------------------------------------ 201 target: event stream establish-subscription-stream-error-info 202 target: datastore establish-subscription-datastore-error-info 204 modify-subscription returns hints in yang-data structure 205 ---------------------- ------------------------------------ 206 target: event stream modify-subscription-stream-error-info 207 target: datastore modify-subscription-datastore-error-info 209 The yang-data included within "error-info" SHOULD NOT include the 210 optional leaf "error-reason", as such a leaf would be redundant 211 with information that is already placed within the 212 "error-app-tag". 214 In case of an rpc error as a result of a "delete-subscription", a 215 "kill-subscription", or a "resynch-subscription" request, no 216 "error-info" needs to be included, as the "subscription-id" is 217 the only RPC input parameter and no hints regarding this RPC input 218 parameters need to be provided. 220 8. Security Considerations 222 If a malicious or buggy NETCONF subscriber sends a number of 223 establish-subscription requests, then these subscriptions accumulate 224 and may use up system resources. In such a situation, subscriptions 225 MAY be terminated by terminating the underlying NETCONF session. The 226 publisher MAY also suspend or terminate a subset of the active 227 subscriptions on that NETCONF session. 229 9. Acknowledgments 231 We wish to acknowledge the helpful contributions, comments, and 232 suggestions that were received from: Andy Bierman, Yan Gang, Sharon 233 Chisholm, Hector Trevino, Peipei Guo, Susan Hares, Tim Jenkins, 234 Balazs Lengyel, Martin Bjorklund, Mahesh Jethanandani, Kent Watsen, 235 and Guangying Zheng. 237 10. Normative References 239 [I-D.draft-ietf-netconf-subscribed-notifications] 240 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 241 and E. Nilsen-Nygaard, "Customized Subscriptions to a 242 Publisher's Event Streams", draft-ietf-netconf-subscribed- 243 notifications-15 (work in progress), August 2018. 245 [I-D.ietf-netconf-yang-push] 246 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 247 Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B. 248 Lengyel, "YANG Datastore Subscription", June 2018, 249 . 252 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 253 Requirement Levels", BCP 14, RFC 2119, 254 DOI 10.17487/RFC2119, March 1997, 255 . 257 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 258 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 259 . 261 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 262 and A. Bierman, Ed., "Network Configuration Protocol 263 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 264 . 266 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 267 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 268 May 2017, . 270 Appendix A. Examples 272 This section is non-normative. 274 A.1. Event Stream Discovery 276 As defined in [I-D.draft-ietf-netconf-subscribed-notifications] an 277 event stream exposes a continuous set of events available for 278 subscription. A NETCONF client can retrieve the list of available 279 event streams from a NETCONF publisher using the "get" operation 280 against the top-level container "/streams" defined in 281 [I-D.draft-ietf-netconf-subscribed-notifications] Section 3.1. 283 The following example illustrates the retrieval of the list of 284 available event streams: 286 288 289 290 292 293 294 296 Figure 1: Get streams request 298 After such a request, the NETCONF publisher returns a list of event 299 streams available, as well as additional information which might 300 exist in the container. 302 A.2. Dynamic Subscriptions 304 A.2.1. Establishing Dynamic Subscriptions 306 The following figure shows two successful "establish-subscription" 307 RPC requests as per 308 [I-D.draft-ietf-netconf-subscribed-notifications]. The first request 309 is given a subscription identifier of 22, the second, an identifier 310 of 23. 312 +------------+ +-----------+ 313 | Subscriber | | Publisher | 314 +------------+ +-----------+ 315 | | 316 | Capability Exchange | 317 |<---------------------------->| 318 | | 319 | | 320 | establish-subscription | 321 |----------------------------->| (a) 322 | RPC Reply: OK, id = 22 | 323 |<-----------------------------| (b) 324 | | 325 | notification message (for 22)| 326 |<-----------------------------| 327 | | 328 | | 329 | establish-subscription | 330 |----------------------------->| 331 | notification message (for 22)| 332 |<-----------------------------| 333 | RPC Reply: OK, id = 23 | 334 |<-----------------------------| 335 | | 336 | | 337 | notification message (for 22)| 338 |<-----------------------------| 339 | notification message (for 23)| 340 |<-----------------------------| 341 | | 343 Figure 2: Multiple subscriptions over a NETCONF session 345 To provide examples of the information being transported, example 346 messages for interactions (a) and (b) in Figure 2 are detailed below: 348 349 351 NETCONF 352 353 /ex:foo/ 354 355 10 356 357 359 Figure 3: establish-subscription request (a) 361 As NETCONF publisher was able to fully satisfy the request (a), the 362 publisher sends the subscription identifier of the accepted 363 subscription within message (b): 365 367 369 22 370 371 373 Figure 4: establish-subscription success (b) 375 If the NETCONF publisher had not been able to fully satisfy the 376 request, or subscriber has no authorization to establish the 377 subscription, the publisher would have sent an RPC error response. 378 For instance, if the "dscp" value of 10 asserted by the subscriber in 379 Figure 3 proved unacceptable, the publisher may have returned: 381 383 384 application 385 operation-failed 386 error 387 388 ietf-subscribed-notifications:dscp-unavailable 389 390 391 393 Figure 5: an unsuccessful establish subscription 395 The subscriber can use this information in future attempts to 396 establish a subscription. 398 A.2.2. Modifying Dynamic Subscriptions 400 An existing subscription may be modified. The following exchange 401 shows a negotiation of such a modification via several exchanges 402 between a subscriber and a publisher. This negotiation consists of a 403 failed RPC modification request/response, followed by a successful 404 one. 406 +------------+ +-----------+ 407 | Subscriber | | Publisher | 408 +------------+ +-----------+ 409 | | 410 | notification message (for 23)| 411 |<-----------------------------| 412 | | 413 | modify-subscription (id = 23)| 414 |----------------------------->| (c) 415 | RPC error (with hint) | 416 |<-----------------------------| (d) 417 | | 418 | modify-subscription (id = 23)| 419 |----------------------------->| 420 | RPC Reply: OK | 421 |<-----------------------------| 422 | | 423 | notification message (for 23)| 424 |<-----------------------------| 425 | | 427 Figure 6: Interaction model for successful subscription modification 429 If the subscription being modified in Figure 6 is a datastore 430 subscription as per [I-D.ietf-netconf-yang-push], the modification 431 request made in (c) may look like that shown in Figure 7. As can be 432 seen, the modifications being attempted are the application of a new 433 xpath filter as well as the setting of a new periodic time interval. 435 437 440 23 441 442 /interfaces-state/interface/oper-status 443 444 445 500 446 447 448 450 Figure 7: Subscription modification request (c) 452 If the NETCONF publisher can satisfy both changes, the publisher 453 sends a positive result for the RPC. If the NETCONF publisher cannot 454 satisfy either of the proposed changes, the publisher sends an RPC 455 error response (d). The following is an example RPC error response 456 for (d) which includes a hint. This hint is an alternative time 457 period value which might have resulted in a successful modification: 459 461 462 application 463 operation-failed 464 error 465 466 ietf-yang-push:period-unsupported 467 468 470 471 472 3000 473 474 475 476 477 479 Figure 8: Modify subscription failure with Hint (d) 481 A.2.3. Deleting Dynamic Subscriptions 483 The following demonstrates deleting a subscription. This 484 subscription may have been to either a stream or a datastore. 486 488 490 22 491 492 494 Figure 9: Delete subscription 496 If the NETCONF publisher can satisfy the request, the publisher 497 replies with success to the RPC request. 499 If the NETCONF publisher cannot satisfy the request, the publisher 500 sends an error-rpc element indicating the modification didn't work. 501 Figure 10 shows a valid response for existing valid subscription 502 identifier, but that subscription identifier was created on a 503 different NETCONF transport session: 505 507 508 application 509 operation-failed 510 error 511 512 ietf-subscribed-notifications:no-such-subscription 513 514 515 517 Figure 10: Unsuccessful delete subscription 519 A.3. Subscription State Notifications 521 A publisher will send subscription state notifications for dynamic 522 subscriptions according to the definitions within 523 [I-D.draft-ietf-netconf-subscribed-notifications]). 525 A.3.1. subscription-modified 527 As per Section 2.7.2 of 528 [I-D.draft-ietf-netconf-subscribed-notifications], a "subscription- 529 modified" might be sent if over NETCONF if the definition of a 530 configured filter changes. A subscription state notification encoded 531 in XML would look like: 533 534 2007-09-01T10:00:00Z 535 537 39 538 540 nsn:netconf 541 542 543 /ex:foo 544 545 NETCONF 546 547 549 Figure 11: subscription-modified subscription state notification 551 A.3.2. subscription-resumed, and replay-complete 553 A "subscription-resumed" would look like: 555 557 2007-09-01T10:00:00Z 558 560 39 561 562 564 Figure 12: subscription-resumed notification in XML 566 The "replay-complete" is virtually identical, with "subscription- 567 resumed" simply being replaced by "replay-complete". 569 A.3.3. subscription-terminated and subscription-suspended 571 A "subscription-terminated" would look like: 573 575 2007-09-01T10:00:00Z 576 578 39 579 580 suspension-timeout 581 582 583 585 Figure 13: subscription-terminated subscription state notification 587 The "subscription-suspended" is virtually identical, with 588 "subscription-terminated" simply being replaced by "subscription- 589 suspended". 591 Appendix B. Changes between revisions 593 (To be removed by RFC editor prior to publication) 595 B.1. v10 to v11 597 o Configured removed. 599 B.2. v09 to v10 601 o Tweaks to examples and text. 602 o Downshifted state names. 603 o Removed address from examples. 605 B.3. v08 to v09 607 o Tweaks based on Kent's comments. 608 o Updated examples in Appendix A. And updates to some object names 609 based on changes in the subscribed-notifications draft. 610 o Added a YANG model for the NETCONF identity. 612 B.4. v07 to v08 614 o Tweaks and clarification on :interleave. 616 B.5. v06 to v07 618 o XML encoding and operational datastore mandatory. 619 o Error mechanisms and examples updated. 621 B.6. v05 to v06 623 o Moved examples to appendices 624 o All examples rewritten based on namespace learnings 625 o Normative text consolidated in front 626 o Removed all mention of JSON 627 o Call home process detailed 628 o Note: this is a major revision attempting to cover those comments 629 received from two week review. 631 B.7. v03 to v04 633 o Added additional detail to "configured subscriptions" 634 o Added interleave capability 635 o Adjusted terminology to that in draft-ietf-netconf-subscribed- 636 notifications 637 o Corrected namespaces in examples 639 B.8. v01 to v03 641 o Text simplifications throughout 642 o v02 had no meaningful changes 644 B.9. v00 to v01 646 o Added Call Home in solution for configured subscriptions. 647 o Clarified support for multiple subscription on a single session. 648 No need to support multiple create-subscription. 649 o Added mapping between terminology in yang-push and [RFC6241] (the 650 one followed in this document). 651 o Editorial improvements. 653 Authors' Addresses 655 Eric Voit 656 Cisco Systems 658 Email: evoit@cisco.com 660 Alexander Clemm 661 Huawei 663 Email: ludwig@clemm.org 665 Alberto Gonzalez Prieto 666 Microsoft 668 Email: alberto.gonzalez@microsoft.com 670 Einar Nilsen-Nygaard 671 Cisco Systems 673 Email: einarnn@cisco.com 675 Ambika Prasad Tripathy 676 Cisco Systems 678 Email: ambtripa@cisco.com