idnits 2.17.1 draft-ietf-netconf-netconf-event-notifications-10.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 251 has weird spacing: '...ription estab...' == Line 255 has weird spacing: '...ription res...' == Line 271 has weird spacing: '... stream esta...' == Line 274 has weird spacing: '...ription ret...' == Line 276 has weird spacing: '... stream modi...' -- The document date (July 2, 2018) is 2124 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-14 == Outdated reference: A later version (-36) exists of draft-ietf-netconf-netconf-client-server-06 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: January 3, 2019 Huawei 6 A. Gonzalez Prieto 7 VMware 8 E. Nilsen-Nygaard 9 A. Tripathy 10 Cisco Systems 11 July 2, 2018 13 NETCONF Support for Event Notifications 14 draft-ietf-netconf-netconf-event-notifications-10 16 Abstract 18 This document provides a NETCONF binding to subscribed notifications 19 and to 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 January 3, 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 . . . . . . 4 62 5. NETCONF connectivity and the subscription lifecycle . . . . . 4 63 5.1. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 4 64 5.2. Configured Subscriptions . . . . . . . . . . . . . . . . 4 65 6. Notification Messages . . . . . . . . . . . . . . . . . . . . 5 66 7. Dynamic Subscriptions and RPC Error Responses . . . . . . . . 5 67 8. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 7 68 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 69 10. Security Considerations . . . . . . . . . . . . . . . . . . . 9 70 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 71 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 72 12.1. Normative References . . . . . . . . . . . . . . . . . . 10 73 12.2. Informative References . . . . . . . . . . . . . . . . . 11 74 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 11 75 A.1. Event Stream Discovery . . . . . . . . . . . . . . . . . 11 76 A.2. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 12 77 A.3. Configured Subscriptions . . . . . . . . . . . . . . . . 16 78 A.4. Subscription State Notifications . . . . . . . . . . . . 22 79 Appendix B. Changes between revisions . . . . . . . . . . . . . 24 80 B.1. v09 to v10 . . . . . . . . . . . . . . . . . . . . . . . 24 81 B.2. v08 to v09 . . . . . . . . . . . . . . . . . . . . . . . 24 82 B.3. v07 to v08 . . . . . . . . . . . . . . . . . . . . . . . 24 83 B.4. v06 to v07 . . . . . . . . . . . . . . . . . . . . . . . 24 84 B.5. v05 to v06 . . . . . . . . . . . . . . . . . . . . . . . 25 85 B.6. v03 to v04 . . . . . . . . . . . . . . . . . . . . . . . 25 86 B.7. v01 to v03 . . . . . . . . . . . . . . . . . . . . . . . 25 87 B.8. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 25 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 25 90 1. Introduction 92 This document provides a binding for events streamed over the NETCONF 93 protocol [RFC6241] as per 94 [I-D.draft-ietf-netconf-subscribed-notifications]. In addition, as 95 [I-D.ietf-netconf-yang-push] is itself built upon 96 [I-D.draft-ietf-netconf-subscribed-notifications], this document 97 enables a NETCONF client to request and receive updates from a YANG 98 datastore located on a NETCONF server. 100 2. Terminology 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 104 "OPTIONAL" in this document are to be interpreted as described in BCP 105 14 [RFC2119] [RFC8174] when, and only when, they appear in all 106 capitals, as shown here. 108 The following terms are defined in 109 [I-D.draft-ietf-netconf-subscribed-notifications]: notification 110 message, event stream, publisher, receiver, subscriber, subscription, 111 configured subscription. 113 3. Compatibility with RFC-5277's create-subscription 115 A publisher is allowed to concurrently support configured 116 subscriptions and dynamic subscription RPCs of 117 [I-D.draft-ietf-netconf-subscribed-notifications] at the same time as 118 [RFC5277]'s "create-subscription" RPC. However a single NETCONF 119 transport session cannot support both this specification and a 120 subscription established by [RFC5277]'s "create-subscription" RPC. 121 To protect against any attempts to use a single NETCONF transport 122 session in this way: 124 o A solution must reply with the [RFC6241] error "operation-not- 125 supported" if a "create-subscription" RPC is received on a NETCONF 126 session where any other 127 [I-D.draft-ietf-netconf-subscribed-notifications] or [RFC5277] 128 subscription exists. 129 o It is a prohibited to send updates or state change notifications 130 for a configured subscription on a NETCONF session where the 131 create-subscription RPC has successfully [RFC5277] created 132 subscription. 133 o A "create-subscription" RPC MUST be rejected if any 134 [I-D.draft-ietf-netconf-subscribed-notifications] or 135 [RFC5277]subscription is active across that NETCONF transport 136 session. 138 If a publisher supports this specification but not subscriptions via 139 [RFC5277], the publisher MUST NOT advertise 140 "urn:ietf:params:netconf:capability:notification:1.0". 142 4. Mandatory XML, event stream and datastore support 144 The "encode-xml" feature of 145 [I-D.draft-ietf-netconf-subscribed-notifications] is mandatory to 146 support. This indicates that XML is a valid encoding for RPCs, state 147 change notifications, and subscribed content. 149 A NETCONF publisher supporting event stream subscription via 150 [I-D.draft-ietf-netconf-subscribed-notifications] MUST support the 151 "NETCONF" event stream identified in that draft. 153 A NETCONF publisher supporting [I-D.ietf-netconf-yang-push] MUST 154 support the operational state datastore as defined by [RFC8342]. 156 5. NETCONF connectivity and the subscription lifecycle 158 This section describes how the availability of NETCONF transport 159 impacts the establishment and lifecycle of different types of 160 [I-D.draft-ietf-netconf-subscribed-notifications] subscriptions. 162 5.1. Dynamic Subscriptions 164 For a dynamic subscription, if the NETCONF session involved with the 165 "establish-subscription" terminates, the subscription MUST be 166 deleted. 168 For a dynamic subscription a "modify-subscription", "delete- 169 subscription", or "resynch-subscription" RPC MUST be sent using same 170 the NETCONF session upon which the referenced subscription was 171 established.". 173 5.2. Configured Subscriptions 175 When a configured subscription enters the "valid" state, there is no 176 guarantee a usable NETCONF transport session is currently in place 177 with each associated receiver. As a result, the first configured 178 subscription to a specific receiver MUST establish a NETCONF 179 transport session via NETCONF call home [RFC8071], section 4.1. This 180 transport session MUST then be used by additional configured 181 subscriptions targeting that the same receiver. This same receiver 182 is identifiable on the publisher as one which targets the same IP 183 address and port used to establish the existing NETCONF call home 184 connection. This transport session MAY also be used by dynamic 185 subscriptions and/or non-subscription related NETCONF operations 186 originated by the NETCONF client. 188 The method of identifying the targeted recevier IP address, port, and 189 security credentials are left up to implementers of this 190 specification. For implementation guidance and a YANG model for this 191 function, please look to 192 [I-D.draft-ietf-netconf-netconf-client-server]. 194 If the call home fails because the publisher receives receiver 195 credentials which are subsequently declined per [RFC8071], 196 Section 4.1, step S5 authentication, then that receiver MUST be 197 placed into the "timeout" state. 199 If the call home fails to establish for any other reason, the 200 publisher MUST NOT progress the receiver to the "active" state. 201 Additionally, the publisher SHOULD place the receiver into the 202 "timeout" state after a predetermined number of either failed call 203 home attempts or NETCONF sessions remotely terminated by the 204 receiver. 206 NETCONF transport session connectivity SHOULD be verified as 207 described in [RFC8071], Section 4.1, step S7. 209 Until NETCONF transport with a receiver has been established, and a 210 "subscription-started" state change notification has been 211 successfully sent for a configured subscription, that subscription's 212 receiver MUST remain in either the "connecting" or the "timeout" 213 state. 215 If a NETCONF session is disconnected but the "stop-time" of a 216 subscription being transported over that session has not been 217 reached, the publisher restarts the call home process and return the 218 receiver to the "connecting" state. 220 6. Notification Messages 222 Notification messages transported over the NETCONF protocol will use 223 the "notification" message defined within [RFC5277], section 4. 225 All notification messages MUST use the NETCONF transport session used 226 by the "establish-subscription" RPC. 228 7. Dynamic Subscriptions and RPC Error Responses 230 Management of dynamic subscriptions occurs via RPCs as defined in 231 [I-D.ietf-netconf-yang-push] and 232 [I-D.draft-ietf-netconf-subscribed-notifications]. When an RPC error 233 occurs, the NETCONF RPC reply MUST include an "rpc-error" element per 234 [RFC6241] with the error information populated as follows: 236 o an "error-type" node of "application". 237 o an "error-tag" node of "operation-failed". 239 o an "error-severity" of "error" (this MAY but does not have to be 240 included). 241 o an "error-app-tag" node with the value being a string that 242 corresponds to an identity associated with the error, as defined 243 in [I-D.draft-ietf-netconf-subscribed-notifications] section 2.4.6 244 for general subscriptions, and [I-D.ietf-netconf-yang-push] 245 Appendix A.1, for datastore subscriptions. The identityname to 246 use depends on the RPC for which the error occurred. Viable 247 errors for different RPCs are as follows: 249 RPC use base identity 250 ---------------------- ---------------------------- 251 establish-subscription establish-subscription-error 252 modify-subscription modify-subscription-error 253 delete-subscription delete-subscription-error 254 kill-subscription kill-subscription-error 255 resynch-subscription resynch-subscription-error 257 Each error identity will be inserted as the "error-app-tag" using 258 JSON encoding following the form :. An 259 example of such as valid encoding would be "ietf-subscribed- 260 notifications:no-such-subscription". 262 o In case of error responses to an "establish-subscription" or 263 "modify-subscription" request there is the option of including an 264 "error-info" node. This node may contain XML-encoded data with 265 hints for parameter settings that might lead to successful RPC 266 requests in the future. Following are the yang-data structures 267 which may be returned: 269 establish-subscription returns hints in yang-data structure 270 ---------------------- ------------------------------------ 271 target: event stream establish-subscription-stream-error-info 272 target: datastore establish-subscription-datastore-error-info 274 modify-subscription returns hints in yang-data structure 275 ---------------------- ------------------------------------ 276 target: event stream modify-subscription-stream-error-info 277 target: datastore modify-subscription-datastore-error-info 279 The yang-data included within "error-info" SHOULD NOT include the 280 optional leaf "error-reason", as such a leaf would be redundant 281 with information that is already placed within the 282 "error-app-tag". 284 In case of an rpc error as a result of a "delete-subscription", a 285 "kill-subscription", or a "resynch-subscription" request, no 286 "error-info" needs to be included, as the "subscription-id" is 287 the only RPC input parameter and no hints regarding this RPC input 288 parameters need to be provided. 290 8. YANG module 292 This module references 293 [I-D.draft-ietf-netconf-subscribed-notifications]. 295 [ note to the RFC Editor - please replace XXXX within this YANG model 296 with the number of this document ] 298 file 299 "ietf-netconf-subscribed-notifications@2018-04-20.yang" 300 module ietf-netconf-subscribed-notifications { 301 yang-version 1.1; 302 namespace 303 "urn:ietf:params:xml:ns:yang:ietf-netconf-subscribed-notifications"; 305 prefix nsn; 307 import ietf-subscribed-notifications { 308 prefix sn; 309 } 311 organization "IETF NETCONF (Network Configuration) Working Group"; 312 contact 313 "WG Web: 314 WG List: 316 Editor: Eric Voit 317 319 Editor: Alexander Clemm 320 322 Editor: Alberto Gonzalez Prieto 323 325 Editor: Ambika Prasad Tripathy 326 328 Editor: Einar Nilsen-Nygaard 329 "; 331 description 332 "Defines NETCONF as a supported transport for subscribed event 333 notifications. 335 Copyright (c) 2018 IETF Trust and the persons identified as authors 336 of the code. All rights reserved. 338 Redistribution and use in source and binary forms, with or without 339 modification, is permitted pursuant to, and subject to the license 340 terms contained in, the Simplified BSD License set forth in Section 341 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents 342 (https://trustee.ietf.org/license-info). 344 This version of this YANG module is part of RFC XXXX; see the RFC 345 itself for full legal notices."; 347 revision 2018-04-20 { 348 description 349 "Initial version"; 350 reference 351 "RFC XXXX: NETCONF Support for Event Notifications"; 352 } 354 identity netconf { 355 base sn:transport; 356 base sn:inline-address; 357 description 358 "NETCONF is used as a transport for notification messages and 359 state change notifications."; 360 } 361 } 362 363 9. IANA Considerations 365 This document registers the following namespace URI in the "IETF XML 366 Registry" [RFC3688]: 368 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-subscribed- 369 notifications 370 Registrant Contact: The IESG. 371 XML: N/A; the requested URI is an XML namespace. 373 This document registers the following YANG module in the "YANG Module 374 Names" registry [RFC6020]: 376 Name: ietf-netconf-subscribed-notifications 377 Namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-subscribed- 378 notifications 379 Prefix: nsn 380 Reference: RFC XXXX: NETCONF Support for Event Notifications 382 10. Security Considerations 384 Notification messages (including state change notifications) are 385 never sent before the NETCONF capabilities exchange has completed. 387 If a malicious or buggy NETCONF subscriber sends a number of 388 establish-subscription requests, then these subscriptions accumulate 389 and may use up system resources. In such a situation, subscriptions 390 MAY be terminated by terminating the underlying NETCONF session. The 391 publisher MAY also suspend or terminate a subset of the active 392 subscriptions on that NETCONF session. 394 This draft has a YANG module which consists of a single identity. As 395 a result additional security concerns beyond those of the imported 396 modules are not introduced. 398 11. Acknowledgments 400 We wish to acknowledge the helpful contributions, comments, and 401 suggestions that were received from: Andy Bierman, Yan Gang, Sharon 402 Chisholm, Hector Trevino, Peipei Guo, Susan Hares, Tim Jenkins, 403 Balazs Lengyel, Martin Bjorklund, Mahesh Jethanandani, Kent Watsen, 404 and Guangying Zheng. 406 12. References 407 12.1. Normative References 409 [I-D.draft-ietf-netconf-subscribed-notifications] 410 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A., 411 and E. Nilsen-Nygaard, "Customized Subscriptions to a 412 Publisher's Event Streams", draft-ietf-netconf-subscribed- 413 notifications-14 (work in progress), July 2018. 415 [I-D.ietf-netconf-yang-push] 416 Clemm, Alexander., Voit, Eric., Gonzalez Prieto, Alberto., 417 Tripathy, A., Nilsen-Nygaard, E., Bierman, A., and B. 418 Lengyel, "YANG Datastore Subscription", June 2018, 419 . 422 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 423 Requirement Levels", BCP 14, RFC 2119, 424 DOI 10.17487/RFC2119, March 1997, 425 . 427 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 428 DOI 10.17487/RFC3688, January 2004, 429 . 431 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 432 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 433 . 435 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 436 the Network Configuration Protocol (NETCONF)", RFC 6020, 437 DOI 10.17487/RFC6020, October 2010, 438 . 440 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 441 and A. Bierman, Ed., "Network Configuration Protocol 442 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 443 . 445 [RFC8071] Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 446 RFC 8071, DOI 10.17487/RFC8071, February 2017, 447 . 449 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 450 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 451 May 2017, . 453 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 454 and R. Wilton, "Network Management Datastore Architecture 455 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 456 . 458 12.2. Informative References 460 [I-D.draft-ietf-netconf-netconf-client-server] 461 Watsen, K. and G. Wu, "NETCONF Client and Server Models", 462 draft-ietf-netconf-netconf-client-server-06 (work in 463 progress), June 2018. 465 Appendix A. Examples 467 This section is non-normative. 469 A.1. Event Stream Discovery 471 As defined in [I-D.draft-ietf-netconf-subscribed-notifications] an 472 event stream exposes a continuous set of events available for 473 subscription. A NETCONF client can retrieve the list of available 474 event streams from a NETCONF publisher using the "get" operation 475 against the top-level container "/streams" defined in 476 [I-D.draft-ietf-netconf-subscribed-notifications] Section 3.1. 478 The following example illustrates the retrieval of the list of 479 available event streams: 481 483 484 485 487 488 489 491 Figure 1: Get streams request 493 After such a request, the NETCONF publisher returns a list of event 494 streams available, as well as additional information which might 495 exist in the container. 497 A.2. Dynamic Subscriptions 499 A.2.1. Establishing Dynamic Subscriptions 501 The following figure shows two successful "establish-subscription" 502 RPC requests as per 503 [I-D.draft-ietf-netconf-subscribed-notifications]. The first request 504 is given a subscription identifier of 22, the second, an identifier 505 of 23. 507 +------------+ +-----------+ 508 | Subscriber | | Publisher | 509 +------------+ +-----------+ 510 | | 511 | Capability Exchange | 512 |<---------------------------->| 513 | | 514 | | 515 | establish-subscription | 516 |----------------------------->| (a) 517 | RPC Reply: OK, id = 22 | 518 |<-----------------------------| (b) 519 | | 520 | notification message (for 22)| 521 |<-----------------------------| 522 | | 523 | | 524 | establish-subscription | 525 |----------------------------->| 526 | notification message (for 22)| 527 |<-----------------------------| 528 | RPC Reply: OK, id = 23 | 529 |<-----------------------------| 530 | | 531 | | 532 | notification message (for 22)| 533 |<-----------------------------| 534 | notification message (for 23)| 535 |<-----------------------------| 536 | | 538 Figure 2: Multiple subscriptions over a NETCONF session 540 To provide examples of the information being transported, example 541 messages for interactions (a) and (b) in Figure 2 are detailed below: 543 544 546 NETCONF 547 548 /ex:foo/ 549 550 10 551 552 554 Figure 3: establish-subscription request (a) 556 As NETCONF publisher was able to fully satisfy the request (a), the 557 publisher sends the subscription identifier of the accepted 558 subscription within message (b): 560 562 564 22 565 566 568 Figure 4: establish-subscription success (b) 570 If the NETCONF publisher had not been able to fully satisfy the 571 request, or subscriber has no authorization to establish the 572 subscription, the publisher would have sent an RPC error response. 573 For instance, if the "dscp" value of 10 asserted by the subscriber in 574 Figure 3 proved unacceptable, the publisher may have returned: 576 578 579 application 580 operation-failed 581 error 582 583 ietf-subscribed-notifications:dscp-unavailable 584 585 586 588 Figure 5: an unsuccessful establish subscription 590 The subscriber can use this information in future attempts to 591 establish a subscription. 593 A.2.2. Modifying Dynamic Subscriptions 595 An existing subscription may be modified. The following exchange 596 shows a negotiation of such a modification via several exchanges 597 between a subscriber and a publisher. This negotiation consists of a 598 failed RPC modification request/response, followed by a successful 599 one. 601 +------------+ +-----------+ 602 | Subscriber | | Publisher | 603 +------------+ +-----------+ 604 | | 605 | notification message (for 23)| 606 |<-----------------------------| 607 | | 608 | modify-subscription (id = 23)| 609 |----------------------------->| (c) 610 | RPC error (with hint) | 611 |<-----------------------------| (d) 612 | | 613 | modify-subscription (id = 23)| 614 |----------------------------->| 615 | RPC Reply: OK | 616 |<-----------------------------| 617 | | 618 | notification message (for 23)| 619 |<-----------------------------| 620 | | 622 Figure 6: Interaction model for successful subscription modification 624 If the subscription being modified in Figure 6 is a datastore 625 subscription as per [I-D.ietf-netconf-yang-push], the modification 626 request made in (c) may look like that shown in Figure 7. As can be 627 seen, the modifications being attempted are the application of a new 628 xpath filter as well as the setting of a new periodic time interval. 630 632 635 23 636 637 /interfaces-state/interface/oper-status 638 639 640 500 641 642 643 645 Figure 7: Subscription modification request (c) 647 If the NETCONF publisher can satisfy both changes, the publisher 648 sends a positive result for the RPC. If the NETCONF publisher cannot 649 satisfy either of the proposed changes, the publisher sends an RPC 650 error response (d). The following is an example RPC error response 651 for (d) which includes a hint. This hint is an alternative time 652 period value which might have resulted in a successful modification: 654 656 657 application 658 operation-failed 659 error 660 661 ietf-yang-push:period-unsupported 662 663 665 666 667 3000 668 669 670 671 672 674 Figure 8: Modify subscription failure with Hint (d) 676 A.2.3. Deleting Dynamic Subscriptions 678 The following demonstrates deleting a subscription. This 679 subscription may have been to either a stream or a datastore. 681 683 685 22 686 687 689 Figure 9: Delete subscription 691 If the NETCONF publisher can satisfy the request, the publisher 692 replies with success to the RPC request. 694 If the NETCONF publisher cannot satisfy the request, the publisher 695 sends an error-rpc element indicating the modification didn't work. 696 Figure 10 shows a valid response for existing valid subscription 697 identifier, but that subscription identifier was created on a 698 different NETCONF transport session: 700 702 703 application 704 operation-failed 705 error 706 707 ietf-subscribed-notifications:no-such-subscription 708 709 710 712 Figure 10: Unsuccessful delete subscription 714 A.3. Configured Subscriptions 716 Configured subscriptions may be established, modified, and deleted 717 using configuration operations against the top-level subtree of 718 [I-D.draft-ietf-netconf-subscribed-notifications] or 719 [I-D.ietf-netconf-yang-push]. 721 In this section, we present examples of how to manage the 722 configuration subscriptions using a NETCONF client. 724 A.3.1. Creating Configured Subscriptions 726 For subscription creation, a NETCONF client may send: 728 729 730 731 732 733 none 734 735 737 738 1922 739 741 nsn:netconf 742 743 NETCONF 744 745 746 receiver1 747 748 749 750 751 752 753 755 Figure 11: Create a configured subscription 757 If the request is accepted, the publisher will indicate this. If the 758 request is not accepted because the publisher cannot serve it, no 759 configuration is changed. In this case the publisher may reply: 761 763 764 application 765 resource-denied 766 error 767 768 Temporarily the publisher cannot serve this 769 subscription due to the current workload. 770 771 772 774 Figure 12: Response to a failed configured subscription establishment 776 After a subscription has been created, NETCONF connectivity to each 777 receiver will be established if it does not already exist. This will 778 be accomplished through the association on the publisher with the 779 networking parameters needed to establish connectivity with each 780 configured receiver. These parameters will be used as needed by 781 NETCONF call home [RFC8071]. 783 The following figure shows the interaction model for the successful 784 creation of a configured subscription. 786 +----------+ +-----------+ +---------+ 787 |Config Ops| | Publisher | |Receiver1| 788 +----------+ +-----------+ +---------+ 789 | | | 790 | Capability Exchange | | 791 |<-------------------------->| | 792 | | | 793 | | | 794 | Edit-config | | 795 |--------------------------->| | 796 | RPC Reply: OK | | 797 |<---------------------------| | 798 | | Call Home | 799 | |<-------------->| 800 | | | 801 | | subscription- | 802 | | started | 803 | |--------------->| 804 | | | 805 | | notification | 806 | | message | 807 | |--------------->| 809 Figure 13: Interaction model for configured subscription 810 establishment 812 A.3.2. Modifying Configured Subscriptions 814 Configured subscriptions can be modified using configuration 815 operations against the top-level container "/subscriptions". 817 For example, the subscription established in the previous section 818 could be modified as follows, here a adding a second receiver: 820 821 822 823 824 825 826 828 829 830 1922 831 832 833 834 receiver2 835 836 837 838 839 840 841 843 Figure 14: Modify configured subscription 845 If the request is accepted, the publisher will indicate success. The 846 result is that the interaction model described in Figure 13 may be 847 extended as follows. 849 +----------+ +-----------+ +---------+ +---------+ 850 |Config Ops| | Publisher | |Receiver1| |Receiver2| 851 +----------+ +-----------+ +---------+ +---------+ 852 | | notification | | 853 | | message | | 854 | |--------------->| | 855 | Edit-config | | | 856 |--------------------------->| | | 857 | RPC Reply: OK | | | 858 |<---------------------------| | | 859 | | subscription- | | 860 | | started | | 861 | |---------------------------->| 862 | | | | 863 | | notification | | 864 | | message | | 865 | |--------------->| | 866 | |---------------------------->| 867 | | | | 869 Figure 15: Interaction model for configured subscription modification 871 Note in the above that in the specific example above, modifying a 872 configured subscription actually resulted in "subscription-started" 873 notification. And because of an existing NETCONF session, no 874 additional call home was needed. Also note that if the edit of the 875 configuration had impacted the filter, a separate modify-subscription 876 would have been required for the original receiver. 878 A.3.3. Deleting Configured Subscriptions 880 Configured subscriptions can be deleted using configuration 881 operations against the top-level container "/subscriptions". 882 Deleting the subscription above would result in the following flow 883 impacting all active receivers. 885 +----------+ +-----------+ +---------+ +---------+ 886 |Config Ops| | Publisher | |Receiver1| |Receiver2| 887 +----------+ +-----------+ +---------+ +---------+ 888 | | | | 889 | | notification | | 890 | | message | | 891 | |--------------->| | 892 | |---------------------------->| 893 | | | | 894 | Edit-config | | | 895 |--------------------------->| | | 896 | RPC Reply: OK | | | 897 |<---------------------------| | | 898 | | subscription- | | 899 | | terminated | | 900 | |--------------->| | 901 | |---------------------------->| 902 | | | | 904 Figure 16: Interaction model for configured subscription deletion 906 A.4. Subscription State Notifications 908 A publisher will send subscription state notifications according to 909 the definitions within 910 [I-D.draft-ietf-netconf-subscribed-notifications]). 912 A.4.1. subscription-started and subscription-modified 914 A "subscription-started" over NETCONF encoded in XML would look like: 916 917 2007-09-01T10:00:00Z 918 920 39 921 923 nsn:netconf 924 925 926 /ex:foo 927 928 NETCONF 929 930 932 Figure 17: subscription-started subscription state notification 934 The "subscription-modified" is identical to Figure 17, with just the 935 word "started" being replaced by "modified". 937 A.4.2. subscription-completed, subscription-resumed, and replay- 938 complete 940 A "subscription-completed" would look like: 942 944 2007-09-01T10:00:00Z 945 947 39 948 949 951 Figure 18: subscription-completed notification in XML 953 The "subscription-resumed" and "replay-complete" are virtually 954 identical, with "subscription-completed" simply being replaced by 955 "subscription-resumed" and "replay-complete". 957 A.4.3. subscription-terminated and subscription-suspended 959 A "subscription-terminated" would look like: 961 963 2007-09-01T10:00:00Z 964 966 39 967 968 suspension-timeout 969 970 971 973 Figure 19: subscription-terminated subscription state notification 975 The "subscription-suspended" is virtually identical, with 976 "subscription-terminated" simply being replaced by "subscription- 977 suspended". 979 Appendix B. Changes between revisions 981 (To be removed by RFC editor prior to publication) 983 B.1. v09 to v10 985 o Tweaks to examples and text. 986 o Downshifted state names. 987 o Removed address from examples. 989 B.2. v08 to v09 991 o Tweaks based on Kent's comments. 992 o Updated examples in Appendix A. And updates to some object names 993 based on changes in the subscribed-notifications draft. 994 o Added a YANG model for the NETCONF identity. 996 B.3. v07 to v08 998 o Tweaks and clarification on :interleave. 1000 B.4. v06 to v07 1002 o XML encoding and operational datastore mandatory. 1003 o Error mechanisms and examples updated. 1005 B.5. v05 to v06 1007 o Moved examples to appendices 1008 o All examples rewritten based on namespace learnings 1009 o Normative text consolidated in front 1010 o Removed all mention of JSON 1011 o Call home process detailed 1012 o Note: this is a major revision attempting to cover those comments 1013 received from two week review. 1015 B.6. v03 to v04 1017 o Added additional detail to "configured subscriptions" 1018 o Added interleave capability 1019 o Adjusted terminology to that in draft-ietf-netconf-subscribed- 1020 notifications 1021 o Corrected namespaces in examples 1023 B.7. v01 to v03 1025 o Text simplifications throughout 1026 o v02 had no meaningful changes 1028 B.8. v00 to v01 1030 o Added Call Home in solution for configured subscriptions. 1031 o Clarified support for multiple subscription on a single session. 1032 No need to support multiple create-subscription. 1033 o Added mapping between terminology in yang-push and [RFC6241] (the 1034 one followed in this document). 1035 o Editorial improvements. 1037 Authors' Addresses 1039 Eric Voit 1040 Cisco Systems 1042 Email: evoit@cisco.com 1044 Alexander Clemm 1045 Huawei 1047 Email: ludwig@clemm.org 1048 Alberto Gonzalez Prieto 1049 VMware 1051 Email: agonzalezpri@vmware.com 1053 Einar Nilsen-Nygaard 1054 Cisco Systems 1056 Email: einarnn@cisco.com 1058 Ambika Prasad Tripathy 1059 Cisco Systems 1061 Email: ambtripa@cisco.com