idnits 2.17.1 draft-ietf-netconf-netconf-event-notifications-01.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.) == There are 2 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 31, 2016) is 2734 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) ** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF A. Gonzalez Prieto 3 Internet-Draft Cisco Systems 4 Intended status: Standards Track A. Clemm 5 Expires: May 4, 2017 Sympotech 6 E. Voit 7 E. Nilsen-Nygaard 8 A. Tripathy 9 Cisco Systems 10 S. Chisholm 11 Ciena 12 H. Trevino 13 Cisco Systems 14 October 31, 2016 16 NETCONF Support for Event Notifications 17 draft-ietf-netconf-netconf-event-notifications-01 19 Abstract 21 This document defines the support of [event-notifications] by the 22 Network Configuration protocol (NETCONF). [event-notifications] 23 describes capabilities and operations for providing asynchronous 24 message notification delivery. This document discusses how to 25 provide them on top of NETCONF. The capabilities and operations 26 defined between this document and [event-notifications] are intended 27 to obsolete RFC 5277. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on May 4, 2017. 46 Copyright Notice 48 Copyright (c) 2016 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 65 1.2. Solution Overview . . . . . . . . . . . . . . . . . . . . 5 66 2. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 5 67 2.1. Event Streams . . . . . . . . . . . . . . . . . . . . . . 6 68 2.2. Event Stream Discovery . . . . . . . . . . . . . . . . . 6 69 2.3. Default Event Stream . . . . . . . . . . . . . . . . . . 9 70 2.4. Creating a Subscription . . . . . . . . . . . . . . . . . 9 71 2.5. Establishing a Subscription . . . . . . . . . . . . . . . 11 72 2.6. Modifying a Subscription . . . . . . . . . . . . . . . . 16 73 2.7. Deleting a Subscription . . . . . . . . . . . . . . . . . 21 74 2.8. Configured Subscriptions . . . . . . . . . . . . . . . . 24 75 2.9. Event (Data Plane) Notifications . . . . . . . . . . . . 33 76 2.10. Control Plane Notifications . . . . . . . . . . . . . . . 35 77 3. Backwards Compatibility . . . . . . . . . . . . . . . . . . . 44 78 3.1. Capabilities . . . . . . . . . . . . . . . . . . . . . . 44 79 3.2. Stream Discovery . . . . . . . . . . . . . . . . . . . . 45 80 4. Security Considerations . . . . . . . . . . . . . . . . . . . 45 81 5. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46 82 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 46 83 6.1. Normative References . . . . . . . . . . . . . . . . . . 46 84 6.2. Informative References . . . . . . . . . . . . . . . . . 47 85 Appendix A. Issues that are currently being worked . . . . . . . 47 86 Appendix B. Changes between revisions . . . . . . . . . . . . . 47 87 B.1. v00 to v01 . . . . . . . . . . . . . . . . . . . . . . . 47 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 47 90 1. Introduction 92 [RFC6241] can be conceptually partitioned into four layers: 94 Layer Example 95 +-------------+ +-------------------------------------------+ 96 | Content | | Configuration data | 97 +-------------+ +-------------------------------------------+ 98 | | 99 +-------------+ +-------------------------------------------+ 100 | Operations | |, , | 101 +-------------+ +-------------------------------------------+ 102 | | | 103 +-------------+ +-----------------------------+ | 104 | RPC | | , | | 105 +-------------+ +-----------------------------+ | 106 | | | 107 +-------------+ +-------------------------------------------+ 108 | Transport | | BEEP, SSH, SSL, console | 109 | Protocol | | | 110 +-------------+ +-------------------------------------------+ 112 Figure 1: NETCONF layer architecture 114 This document defines mechanisms that provide an asynchronous message 115 notification delivery service for the NETCONF protocol [RFC6241] 116 based on [event-notifications]. This is an optional capability built 117 on top of the base NETCONF definition. 119 [event-notifications] and this document enhance the capabilities of 120 RFC 5277 while maintaining backwards capability with existing 121 implementations. It is intended that a final version of this 122 document might obsolete [RFC5277]. The enhancements include the 123 ability to terminate subscriptions without terminating the client 124 session, to modify existing subscriptions, and to have multiple 125 subscriptions on a NETCONF session. [RFC5277] clients that do not 126 require these enhancements are not affected by them. 128 [event-notifications] covers the following functionality: 130 o Ability to subscribe to event notifications using two mechanisms: 131 dynamic and configuration subscriptions. 133 o Ability to subscribe to event notifications using two mechanisms: 134 dynamic and configuration subscriptions. 136 o Ability to negotiate acceptable subscription parameters. 138 o Ability to filter the subset of notifications to be pushed with 139 stream-specific semantics. 141 o Ability to support multiple encodings for the notification. 143 o Mechanism to communicate the notifications. 145 o Ability to replay locally logged notifications. 147 To support this functionality, NETCONF agents must implement the 148 operations, configuration and operational state defined in 149 [event-notifications]. In addition, they need to: 151 o support multiple subscriptions over a single NETCONF session. 153 o support a revised definition of the default NETCONF stream 155 o be backwards compatible with RFC 5277 implementations. 157 1.1. Terminology 159 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 160 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 161 document are to be interpreted as described in RFC 2119 [RFC2119]. 163 1.1.1. NETCONF 165 The following terms are defined in [RFC6241] : 167 o Client 169 o Server 171 o Operation 173 o RPC: remote procedure call 175 1.1.2. Event Notifications 177 The following terms are defined in [event-notifications]: 179 o Event 181 o Event notification 183 o Stream (also referred to as "event stream") 185 o Subscriber 186 o Publisher 188 o Receiver 190 o Subscription 192 o Filter 194 o Dynamic subscription 196 o Configured subscription 198 Note that a publisher in [event-notifications] corresponds to a 199 server in [RFC6241]. Similarly, a subscribers corresponds to a 200 client. A receiver is also a client. In the remainder of this 201 document, we will use the terminology in [RFC6241]. 203 1.1.3. NETCONF Access Control 205 The following terms are defined in [RFC6536] : 207 o NACM: NETCONF Access Control Model 209 1.2. Solution Overview 211 [event-notifications] defines mechanisms that provide an asynchronous 212 message notification delivery service. This document discusses its 213 realization on top of the NETCONF protocol [RFC6241]. 215 The functionality to support is defined in [event-notifications]. It 216 is formalized in a set of yang models. The mapping of yang 217 constructs into NETCONF is described in [RFC6020]. 219 Supporting [event-notifications] requires enhancements and 220 modifications in NETCONF. The key enhacement is suporting multiple 221 subscriptions on a NETCONF session. A key modification is the 222 definition of the NETCONF stream. 224 These enhancements do not affect [RFC5277] clients that do not 225 support [event-notifications]. 227 2. Solution 229 In this section, we describe and exemplify how [event-notifications] 230 must be supported over NETCONF. 232 2.1. Event Streams 234 In the context of NETCONF, an event stream is a set of events 235 available for subscription from a NETCONF server. It is out of the 236 scope of this document to identify a) how streams are defined, b) how 237 events are defined/generated, and c) how events are assigned to 238 streams. 240 The following is a high-level description of the flow of a 241 notification. Note that it does not mandate and/or preclude an 242 implementation. As events are raised, they are assigned to streams. 243 An event may be assigned to multiple streams. The event is 244 distributed to subscribers and receivers based on the current 245 subscriptions and access control. Access control is needed because 246 if any receiver of that subscription does not have permission to 247 receive an event, then it never makes it into a notification, and 248 processing of the event is completed for that subscription. 250 2.2. Event Stream Discovery 252 A NETCONF client can retrieve the list of available event streams 253 from a NETCONF server using the operation. The reply contains 254 the elements defined in the YANG model under the container 255 "/streams", which includes the stream identifier. 257 The following example ilustrates the retrieval of the list of 258 available event streams using the operation. 260 262 263 264 266 267 268 270 Figure 2: Get streams 272 The NETCONF server returns a list of event streams available for 273 subscription. In this example, the list contains the NETCONF, SNMP, 274 and syslog-critical streams. 276 278 279 281 NETCONF 282 SNMP 283 syslog-critical 284 NETCONF 285 286 287 289 Figure 3: Get streams response 291 2.2.1. Backwards Compatibility 293 In order to maintain backwards compatibility, clients that only 294 support [RFC5277] can retrieve the list of available event streams 295 executing a operation against the container "/netconf/streams". 297 The following example ilustrates this mechanism. 299 301 302 303 305 306 307 308 309 311 Figure 4: Get streams (backwards compatibility) 313 The NETCONF server returns a list of event streams available for 314 subscription. In this example, the list contains the NETCONF, SNMP, 315 and syslog-critical streams. 317 319 320 322 323 324 325 NETCONF 326 327 328 default NETCONF event stream 329 330 331 true 332 333 334 2016-02-05T00:00:00Z 335 336 337 338 339 SNMP 340 341 342 SNMP notifications 343 344 345 false 346 347 348 349 350 syslog-critical 351 352 353 Critical and higher severity 354 355 356 true 357 358 359 2007-07-01T00:00:00Z 360 361 362 363 364 365 367 Figure 5: Get streams response (backwards compatibility) 369 2.3. Default Event Stream 371 A NETCONF server implementation supporting the notification 372 capability MUST support the "NETCONF" notification event stream. 373 This stream contains all NETCONF XML event notifications supported by 374 the NETCONF server, except for those belonging only to streams that 375 explicitly indicate that they must be excluded from the NETCONF 376 stream. The exact string "NETCONF" is used during the advertisement 377 of stream support during the operation on and during 378 the and operations. 380 2.4. Creating a Subscription 382 This operation was fully defined in [RFC5277]. 384 2.4.1. Usage Example 386 The following demonstrates dynamically creating a subscription. 388 390 392 393 395 Figure 6: Create subscription 397 2.4.2. Positive Response 399 If the NETCONF server can satisfy the request, the server sends an 400 element. 402 404 406 411 412 414 416 417 419 Figure 7: Successful create subscription 421 2.4.3. Negative Response 423 If the request cannot be completed for any reason, an 424 element is included within the . Subscription requests 425 can fail for several reasons including if a filter with invalid 426 syntax is provided or if the name of a non-existent stream is 427 provided. 429 If a stopTime is specified in a request without having specified a 430 startTime, the following error is returned: 432 Tag: missing-element 433 Error-type: protocol 434 Severity: error 435 Error-info: : startTime 436 Description: An expected element is missing. 438 Figure 8: Create subscription missing an element 440 If the optional replay feature is requested but the NETCONF server 441 does not support it, the following error is returned: 443 Tag: operation-failed 444 Error-type: protocol 445 Severity: error 446 Error-info: none 447 Description: Request could not be completed because the 448 requested operation failed for some reason 449 not covered by any other error condition. 451 Figure 9: Create subscription operation failed 453 If a stopTime is requested that is earlier than the specified 454 startTime, the following error is returned: 456 Tag: bad-element 457 Error-type: protocol 458 Severity: error 459 Error-info: : stopTime 460 Description: An element value is not correct; 461 e.g., wrong type, out of range, pattern mismatch. 463 Figure 10: Create subscription incorrect stopTime 465 If a startTime is requested that is later than the current time, the 466 following error is returned: 468 Tag: bad-element 469 Error-type: protocol 470 Severity: error 471 Error-info: : startTime 472 Description: An element value is not correct; 473 e.g., wrong type, out of range, pattern mismatch. 475 Figure 11: Create subscription incorrect startTime 477 2.5. Establishing a Subscription 479 This operation is defined in [event-notifications]. 481 2.5.1. Usage Example 483 The following illustrates the establishment of a simple subscription. 485 487 489 490 492 Figure 12: Establish subscription 494 2.5.2. Positive Response 496 If the NETCONF server can satisfy the request, the server sends a 497 positive element, and the subscription-id of 498 the accepted subscription. 500 502 504 509 510 512 514 516 ok 517 518 520 52 521 522 524 Figure 13: Successful establish-subscription 526 2.5.3. Negative Response 528 If the NETCONF server cannot satisfy the request, the server sends a 529 negative element. 531 If the client has no authorization to establish the subscription, the 532 indicates an authorization error. For 533 instance: 535 537 539 foo 540 541 543 545 547 error-data-not-authorized 548 549 551 Figure 14: Unsuccessful establish subscription 553 If the request is rejected because the server is not able to serve 554 it, the server SHOULD include in the returned error what subscription 555 parameters would have been accepted for the request when it was 556 processed. However, they are no guarantee that subsequent requests 557 with those parameters for this client or others will be accepted. 558 For instance, consider a subscription from [yang-push], which 559 augments the establish-subscription with some additional parameters, 560 including "period". If the client requests a period the NETCONF 561 server cannot serve, the exchange may be: 563 565 567 push-update 568 571 572 500 573 574 encode-xml 575 576 578 580 582 error-insufficient-resources 583 584 586 2000 587 588 590 Figure 15: Subscription establishment negotiation 592 Subscription requests will fail if a filter with invalid syntax is 593 provided or if the name of a non-existent stream is provided. 595 2.5.4. Multiple Subscriptions over a Single NETCONF Session 597 Note that [event-notifications] requires supporting multiple 598 subscription establishments over a single NETCONF session. In 599 contrast, [RFC5277] mandated servers to return an error when a 600 create-subscription was sent while a subscription was active on that 601 session. Note that servers are not required to support multiple 602 create-subscription over a single session, but they MUST support 603 multiple establish-suscription over one session. 605 2.5.5. Message Flow Examples 606 +------------+ +-----------+ 607 | Client | | Server | 608 +------------+ +-----------+ 609 | | 610 | Capability Exchange | 611 |<---------------------------->| 612 | | 613 | | 614 | Establish Subscription | 615 |----------------------------->| 616 | RPC Reply: OK, subs-id = 22 | 617 |<-----------------------------| 618 | | 619 | Notification (subs-id 22) | 620 |<-----------------------------| 621 | | 622 | | 623 | Notification (subs-id 22) | 624 |<-----------------------------| 625 | Notification (subs-id 22) | 626 |<-----------------------------| 627 | | 628 | | 630 Figure 16: Message flow for subscription establishment 632 +------------+ +-----------+ 633 | Client | | Server | 634 +------------+ +-----------+ 635 | | 636 | Capability Exchange | 637 |<---------------------------->| 638 | | 639 | | 640 | Establish Subscription | 641 |----------------------------->| 642 | RPC Reply: OK, subs-id = 22 | 643 |<-----------------------------| 644 | | 645 | Notification (subs-id 22) | 646 |<-----------------------------| 647 | | 648 | | 649 | Establish Subscription | 650 |----------------------------->| 651 | RPC Reply: OK, subs-id = 23 | 652 |<-----------------------------| 653 | | 654 | Notification (subs-id 22) | 655 |<-----------------------------| 656 | | 657 | | 658 | Notification (subs-id 22) | 659 |<-----------------------------| 660 | Notification (subs-id 23) | 661 |<-----------------------------| 662 | | 663 | | 665 Figure 17: Message Flow for multiple subscription establishments over 666 a single session 668 2.6. Modifying a Subscription 670 This operation is defined in [event-notifications]. 672 2.6.1. Usage Example 674 The following demonstrates modifying a subscription. Consider a 675 subscription from [yang-push], which augments the establish- 676 subscription with some additional parameters, including "period". A 677 subscription may be established as follows. 679 681 683 push-update 684 687 688 500 689 690 encode-xml 691 692 694 696 698 ok 699 700 702 1922 703 704 706 Figure 18: Establish subscription to be modified 708 The subscription may be modified with: 710 712 714 1922 715 1000 716 717 719 721 723 ok 724 725 727 1922 728 729 731 Figure 19: Modify subscription 733 2.6.2. Positive Response 735 If the NETCONF server can satisfy the request, the server sends a 736 positive element. This response is like that 737 to an establish-subscription request, but without the subscription-id 738 (which would be redundant). 740 742 744 1922 745 747 1000 748 749 750 752 754 756 ok 757 758 760 Figure 20: Successful modify subscription 762 2.6.3. Negative Response 764 If the NETCONF server cannot satisfy the request, the server sends a 765 negative element. Its contents and semantics 766 are identical to those in an establish-subscription request. For 767 instance: 769 771 773 1922 774 775 100 776 777 778 780 782 784 error-insufficient-resources 785 786 500 787 789 Figure 21: Unsuccessful modify subscription 791 2.6.4. Message Flow Example 792 +------------+ +-----------+ 793 | Client | | Server | 794 +------------+ +-----------+ 795 | | 796 | Capability Exchange | 797 |<---------------------------->| 798 | | 799 | | 800 | Establish Subscription | 801 |----------------------------->| 802 | RPC Reply: OK, subs-id = 22 | 803 |<-----------------------------| 804 | | 805 | Notification (subs-id 22) | 806 |<-----------------------------| 807 | | 808 | | 809 | | 810 | | 811 | Modify Subscription | 812 |----------------------------->| 813 | | 814 | | 815 | Notification (subs-id 22) | 816 |<-----------------------------| 817 | Notification (subs-id 22) | 818 |<-----------------------------| 819 | | 820 | | 822 Figure 22: Message flow for subscription modification 824 2.7. Deleting a Subscription 826 This operation is defined in [event-notifications]. 828 2.7.1. Usage Example 830 The following demonstrates deleting a subscription. 832 834 836 1922 837 838 840 Figure 23: Delete subscription 842 2.7.2. Positive Response 844 If the NETCONF server can satisfy the request, the server sends an OK 845 element. For example: 847 849 851 1922 852 853 855 857 858 860 Figure 24: Successful delete subscription 862 2.7.3. Negative Response 864 If the NETCONF server cannot satisfy the request, the server sends an 865 error-rpc element. For example: 867 869 871 2017 872 873 875 877 878 application 879 invalid-value 880 error 881 883 /t:subscription-id 884 885 886 Subscription-id 2017 does not exist 887 888 889 891 Figure 25: Unsuccessful delete subscription 893 2.7.4. Message Flow Example 894 +------------+ +-----------+ 895 | Client | | Server | 896 +------------+ +-----------+ 897 | | 898 | Capability Exchange | 899 |<---------------------------->| 900 | | 901 | | 902 | Establish Subscription | 903 |----------------------------->| 904 | RPC Reply: OK, subs-id = 22 | 905 |<-----------------------------| 906 | | 907 | Notification (subs-id 22) | 908 |<-----------------------------| 909 | | 910 | | 911 | Notification (subs-id 22) | 912 |<-----------------------------| 913 | Notification (subs-id 22) | 914 |<-----------------------------| 915 | | 916 | | 917 | Delete Subscription | 918 |----------------------------->| 919 | | 920 | | 921 | | 922 | | 924 Figure 26: Message flow for subscription deletion 926 2.8. Configured Subscriptions 928 A configured subscription is a subscription installed via a 929 configuration interface. Configured subscriptions do not support 930 negotiation. 932 Supporting configured subscriptions is optional and advertised during 933 the capabilities exchange using the "configured-subscriptions" 934 feature. 936 Configured susbscriptions are supported by NETCONF servers using 937 NETCONF Call Home [call-home] 939 In this section, we present examples of how to manage configuration 940 subscriptions using a NETCONF client. 942 2.8.1. Call Home for Configured Subscriptions 944 Configured subscriptions are established, modified, and deleted using 945 configuration operations against the top-level subtree subscription- 946 config. Once the configuration is set, the server initiates a Call 947 Home to each of the receivers in the subscription on the address and 948 port specified. Once the NETCONF session between the server and the 949 receiver is established, the server will issue a "subscription- 950 started" notification. After that, the server will send 951 notifications to the receiver as per the subscription notification. 953 Note that the server assumes the receiver is aware that calls on the 954 configured port are intended only for pushing notifications. It also 955 assumes that the receiver is ready to accept notifications on the 956 session created as part of the Call Home as soon as the NETCONF 957 session is established. This may require coordination between the 958 client that configures the subscription and the clients for which the 959 notifications are intended. This coordination is out of the scope of 960 this document. 962 2.8.2. Establishing a Configured Subscription 964 Subscriptions are established using configuration operations against 965 the top-level subtree subscription-config. 967 For example at subscription establishment, a NETCONF client may send: 969 972 973 974 975 976 978 979 980 1922 981 982 983 foo 984 985 986
987 1.2.3.4 988
989 990 1234 991 992 993 994 995 996 998 Figure 27: Establish static subscription 1000 if the request is accepted, the server would reply: 1002 1004 1005 1007 Figure 28: Response to a successful static subscription establishment 1009 if the request is not accepted because the server cannot serve it, 1010 the server may reply: 1012 1013 1014 application 1015 resource-denied 1016 error 1017 1018 Temporarily the server cannot serve this 1019 subscription due to the current workload. 1020 1021 1022 1024 Figure 29: Response to a failed static subscription establishment 1026 2.8.2.1. Message Flow Example 1027 +----------+ +-----------+ +---------+ +---------+ 1028 | Client | | Server | | Rcver A | | Rcver B | 1029 +----------+ +-----------+ +---------+ +---------+ 1030 | | | | 1031 | Capability Exchange | | | 1032 |<-------------------------->| | | 1033 | | | | 1034 | | | | 1035 | Edit-config | | | 1036 |--------------------------->| | | 1037 | RPC Reply: OK | | | 1038 |<---------------------------| | | 1039 | | Call Home | | 1040 | |<-------------->| | 1041 | |<--------------------------->| 1042 | | | | 1043 | | Subscription | | 1044 | | Started | | 1045 | | (subs-id 22) | | 1046 | |--------------->| | 1047 | |---------------------------->| 1048 | | | | 1049 | | Notification | | 1050 | | (subs-id 22) | | 1051 | |--------------->| | 1052 | |---------------------------->| 1053 | | | | 1054 | | | | 1055 | | | | 1056 | | | | 1057 | | | | 1058 | | Notification | | 1059 | | (subs-id 22) | | 1060 | |--------------->| | 1061 | |---------------------------->| 1062 | | | | 1063 | | Notification | | 1064 | | (subs-id 22) | | 1065 | |--------------->| | 1066 | |---------------------------->| 1067 | | | | 1069 Figure 30: Message flow for subscription establishment (configured 1070 subscription) 1072 2.8.3. Modifying a Configured Subscription 1074 Configured subscriptions can be modified using configuration 1075 operations against the top-level subtree subscription-config. 1077 For example, the subscription established in the previous section 1078 could be modified as follows, choosing a different receiver: 1080 1083 1084 1085 1086 1087 1089 1090 1091 1922 1092 1093 1094 foo 1095 1096 1097
1098 1.2.3.5 1099
1100 1101 1234 1102 1103 1104 1105 1106 1107 1109 Figure 31: Modify configured subscription 1111 if the request is accepted, the server would reply: 1113 1115 1116 1118 Figure 32: Response to a successful configured subscription 1119 modification 1121 2.8.3.1. Message Flow Example 1123 +----------+ +-----------+ +---------+ +---------+ 1124 | Client | | Server | | Rcver A | | Rcver B | 1125 +----------+ +-----------+ +---------+ +---------+ 1126 | | | | 1127 | Capability Exchange | | | 1128 |<-------------------------->| | | 1129 | | | | 1130 | | | | 1131 | Edit-config | | | 1132 |--------------------------->| | | 1133 | RPC Reply: OK | | | 1134 |<---------------------------| | | 1135 | | Call Home | | 1136 | |<-------------->| | 1137 | |<--------------------------->| 1138 | | | | 1139 | | Subscription | | 1140 | | Started | | 1141 | | (subs-id 22) | | 1142 | |--------------->| | 1143 | |---------------------------->| 1144 | | | | 1145 | | Notification | | 1146 | | (subs-id 22) | | 1147 | |--------------->| | 1148 | |---------------------------->| 1149 | | | | 1150 | | | | 1151 | | | | 1152 | Edit-config | | | 1153 |--------------------------->| | | 1154 | RPC Reply: OK | | | 1155 |<---------------------------| | | 1156 | | | | 1157 | | | | 1158 | | Subscription | | 1159 | | Modified | | 1160 | | (subs-id 22) | | 1161 | |--------------->| | 1162 | |---------------------------->| 1163 | | | | 1164 | | Notification | | 1165 | | (subs-id 22) | | 1166 | |--------------->| | 1167 | |---------------------------->| 1168 | | | | 1170 Figure 33: Message flow for subscription modification (configured 1171 subscription) 1173 2.8.4. Deleting a Configured Subscription 1175 Subscriptions can be deleted using configuration operations against 1176 the top-level subtree subscription-config. For example: 1178 1180 1181 1182 1183 1184 1186 1187 1188 1922 1189 1190 1191 1192 1193 1195 1197 1198 1200 Figure 34: Deleting a configured subscription 1202 2.8.4.1. Message Flow Example 1204 +----------+ +-----------+ +---------+ +---------+ 1205 | Client | | Server | | Rcver A | | Rcver B | 1206 +----------+ +-----------+ +---------+ +---------+ 1207 | | | | 1208 | Capability Exchange | | | 1209 |<-------------------------->| | | 1210 | | | | 1211 | | | | 1212 | Edit-config | | | 1213 |--------------------------->| | | 1214 | RPC Reply: OK | | | 1215 |<---------------------------| | | 1216 | | Call Home | | 1217 | |<-------------->| | 1218 | |<--------------------------->| 1219 | | | | 1220 | | Subscription | | 1221 | | Started | | 1222 | | (subs-id 22) | | 1223 | |--------------->| | 1224 | |---------------------------->| 1225 | | | | 1226 | | Notification | | 1227 | | (subs-id 22) | | 1228 | |--------------->| | 1229 | |---------------------------->| 1230 | | | | 1231 | | | | 1232 | | | | 1233 | | | | 1234 | | | | 1235 | | Notification | | 1236 | | (subs-id 22) | | 1237 | |--------------->| | 1238 | |---------------------------->| 1239 | | | | 1240 | Edit-config | | | 1241 |--------------------------->| | | 1242 | RPC Reply: OK | | | 1243 |<---------------------------| | | 1244 | | | | 1245 | | | | 1246 | | Subscription | | 1247 | | Terminated | | 1248 | | (subs-id 22) | | 1249 | |--------------->| | 1250 | |---------------------------->| 1251 | | | | 1252 | | | | 1253 | | | | 1254 | | | | 1256 Figure 35: Message flow for subscription deletion (configured 1257 subscription) 1259 2.9. Event (Data Plane) Notifications 1261 Once a subscription has been set up, the NETCONF server sends 1262 (asynchronously) the event notifications from the subscribed stream. 1263 We refer to these as data plane notifications. For dynamic 1264 subscriptions set up via RPC operations, event notifications are sent 1265 over the NETCONF session used to create or establish the 1266 subscription. For static subscriptions, event notifications are sent 1267 over the specified connections. 1269 An event notification is sent to the receiver(s) when an event of 1270 interest (i.e., meeting the specified filtering criteria) has 1271 occurred. An event notification is a complete and well-formed XML 1272 document. Note that is not a Remote Procedure Call 1273 (RPC) method but rather the top-level element identifying the one-way 1274 message as a notification. Note that event notifications never 1275 trigger responses. 1277 The event notification always includes an element. It is 1278 the time the event was generated by the event source. This parameter 1279 is of type dateTime and compliant to [RFC3339]. Implementations must 1280 support time zones. 1282 The event notification also contains notification-specific tagged 1283 content, if any. With the exception of , the content of 1284 the notification is beyond the scope of this document. 1286 For encodings other than XML, notifications include an additional XML 1287 element so that the notification is a well-formed XML. The element 1288 is , E.g., . That element contains the notification contents in the 1290 desired encoding 1292 The following is an example of an event notification from [RFC6020]: 1294 notification link-failure { 1295 description "A link failure has been detected"; 1296 leaf if-name { 1297 type leafref { 1298 path "/interface/name"; 1299 } 1300 } 1301 leaf if-admin-status { 1302 type admin-status; 1303 } 1304 leaf if-oper-status { 1305 type oper-status; 1306 } 1307 } 1309 Figure 36: Definition of a data plane notification 1311 1313 2007-09-01T10:00:00Z 1314 1315 so-1/2/3.0 1316 up 1317 down 1318 1319 1321 Figure 37: Data plane notification 1323 The equivalent using JSON encoding would be 1325 1327 2007-09-01T10:00:00Z 1328 1329 { 1330 "acme-system:link-failure": { 1331 "if-name": "so-1/2/3.0", 1332 "if-admin-status": "up", 1333 "if-oper-status": "down" 1334 } 1335 } 1336 1337 1339 Figure 38: Data plane notification using JSON encoding 1341 2.10. Control Plane Notifications 1343 In addition to data plane notifications, a server may send control 1344 plane notifications (defined in [event-notifications]) to indicate to 1345 receivers that an event related to the subscription management has 1346 occurred. Control plane notifications cannot be filtered out. Next 1347 we exemplify them using both XML, and JSON encondings for the 1348 notification-specific content: 1350 2.10.1. replayComplete 1352 1354 2007-09-01T10:00:00Z 1355 1356 1358 Figure 39: replayComplete control plane notification 1360 The equivalent using JSON encoding would be: 1362 1364 2007-09-01T10:00:00Z 1365 1366 { 1367 "netmod-notif:replayComplete": { } 1368 } 1369 1370 1372 Figure 40: replayComplete control plane notification (JSON encoding) 1374 2.10.1.1. Message Flow Example 1375 +------------+ +-----------+ 1376 | Client | | Server | 1377 +------------+ +-----------+ 1378 | | 1379 | Capability Exchange | 1380 |<---------------------------->| 1381 | | 1382 | | 1383 | Establish Subscription | 1384 |----------------------------->| 1385 | RPC Reply: OK, subs-id = 22 | 1386 |<-----------------------------| 1387 | | 1388 | Notification (subs-id 22) | 1389 |<-----------------------------| 1390 | | 1391 | | 1392 | Notification (subs-id 22) | 1393 |<-----------------------------| 1394 | Replay Complete (subs-id 22) | 1395 |<-----------------------------| 1396 | | 1397 | | 1398 | | 1399 | Notification (subs-id 22) | 1400 |<-----------------------------| 1401 | | 1402 | Notification (subs-id 22) | 1403 |<-----------------------------| 1404 | | 1405 | | 1406 | | 1408 Figure 41: replayComplete notification 1410 2.10.2. notificationComplete 1412 1414 2007-09-01T10:00:00Z 1415 1417 1419 Figure 42: notificationComplete control plane notification 1421 2.10.2.1. Message Flow Example 1422 +------------+ +-----------+ 1423 | Client | | Server | 1424 +------------+ +-----------+ 1425 | | 1426 | Capability Exchange | 1427 |<---------------------------->| 1428 | | 1429 | | 1430 | Establish Subscription | 1431 |----------------------------->| 1432 | RPC Reply: OK, subs-id = 22 | 1433 |<-----------------------------| 1434 | | 1435 | Notification (subs-id 22) | 1436 |<-----------------------------| 1437 | | 1438 | | 1439 | Notification (subs-id 22) | 1440 |<-----------------------------| 1441 | Replay Complete (subs-id 22) | 1442 |<-----------------------------| 1443 | | 1444 | | 1445 | | 1446 | Notification (subs-id 22) | 1447 |<-----------------------------| 1448 | | 1449 | Notification (subs-id 22) | 1450 |<-----------------------------| 1451 | | 1452 | | 1453 | | 1454 | Notification Complete | 1455 | (subs-id 22) | 1456 |<-----------------------------| 1457 | | 1458 | | 1459 | | 1460 | RPC | 1461 |----------------------------->| 1462 | RPC Reply | 1463 |<-----------------------------| 1464 | | 1465 | | 1467 Figure 43: notificationComplete notification 1469 2.10.3. subscription-started 1471 1473 2007-09-01T10:00:00Z 1474 1476 52 1477 1482 1483 1485 Figure 44: subscription-started control plane notification 1487 The equivalent using JSON encoding would be: 1489 1491 2007-09-01T10:00:00Z 1492 1493 { 1494 "notif-bis:subscription-started": { 1495 "subscription-id" : 52 1496 ((Open Item: express filter in json)) 1497 } 1498 } 1499 1500 1502 Figure 45: subscription-started control plane notification (JSON 1503 encoding) 1505 2.10.4. subscription-modified 1506 1508 2007-09-01T10:00:00Z 1509 1511 52 1512 1515 1516 1518 Figure 46: subscription-modified control plane notification 1520 2.10.5. subscription-terminated 1522 1524 2007-09-01T10:00:00Z 1525 1527 52 1528 subscription-deleted 1529 1530 1532 Figure 47: subscription-terminated control plane notification 1534 2.10.6. subscription-suspended 1536 1538 2007-09-01T10:00:00Z 1539 1541 52 1542 internal-error 1543 1544 1546 Figure 48: subscription-suspended control plane notification 1548 2.10.7. subscription-resumed 1549 1551 2007-09-01T10:00:00Z 1552 1554 52 1555 internal-error 1556 1557 1559 Figure 49: subscription-resumed control plane notification 1561 2.10.7.1. Message Flow Examples 1562 +------------+ +-----------+ 1563 | Client | | Server | 1564 +------------+ +-----------+ 1565 | | 1566 | Capability Exchange | 1567 |<---------------------------->| 1568 | | 1569 | | 1570 | Establish Subscription | 1571 |----------------------------->| 1572 | RPC Reply: OK, subs-id = 22 | 1573 |<-----------------------------| 1574 | | 1575 | Notification | 1576 |<-----------------------------| 1577 | | 1578 | | 1579 | Notification | 1580 |<-----------------------------| 1581 | Notification | 1582 |<-----------------------------| 1583 | | 1584 | | 1585 | Subscription Suspended | 1586 |<-----------------------------| 1587 | | 1588 | | 1589 | | 1590 | Subscription Resumed | 1591 |<-----------------------------| 1592 | | 1593 | | 1594 | | 1595 | | 1596 | Notification | 1597 |<-----------------------------| 1598 | | 1599 | | 1601 Figure 50: subscription-suspended and Resumed Notifications 1603 +----------+ +-----------+ +---------+ +---------+ 1604 | Client | | Server | | Rcver A | | Rcver B | 1605 +----------+ +-----------+ +---------+ +---------+ 1606 | | | | 1607 | Capability Exchange | | | 1608 |<-------------------------->| | | 1609 | | | | 1610 | | | | 1611 | Edit-config | | | 1612 |--------------------------->| | | 1613 | RPC Reply: OK | | | 1614 |<---------------------------| | | 1615 | | Subscription | | 1616 | | Started | | 1617 | |--------------->| | 1618 | |---------------------------->| 1619 | | | | 1620 | | Notification | | 1621 | |--------------->| | 1622 | |---------------------------->| 1623 | | | | 1624 | | | | 1625 | | | | 1626 | | | | 1627 | | Subscription | | 1628 | | Suspended | | 1629 | |--------------->| | 1630 | |---------------------------->| 1631 | | | | 1632 | | | | 1633 | | | | 1634 | | | | 1635 | | | | 1636 | | Subscription | | 1637 | | Resumed | | 1638 | |--------------->| | 1639 | |---------------------------->| 1640 | | | | 1641 | | | | 1642 | | | | 1643 | | Notification | | 1644 | |--------------->| | 1645 | |---------------------------->| 1646 | | | | 1647 | | Notification | | 1648 | |--------------->| | 1649 | |---------------------------->| 1650 | | | | 1651 | | | | 1652 | | | | 1653 | | | | 1654 Figure 51: subscription-suspended and subscription-resumed 1655 notifications (configured subscriptions) 1657 3. Backwards Compatibility 1659 3.1. Capabilities 1661 Capabilities are advertised in messages sent by each peer during 1662 session establishment [RFC6241]. Servers supporting the features in 1663 this document must advertise both capabilities 1664 "urn:ietf:params:netconf:capability:notification:1.0" and 1665 "urn:ietf:params:netconf:capability:notification:1.1". 1667 An example of a hello message by a server during session 1668 establishment would be: 1670 1671 1672 1673 urn:ietf:params:xml:ns:netconf:base:1.0 1674 1675 1676 urn:ietf:params:netconf:capability:startup:1.0 1677 1678 1679 urn:ietf:params:netconf:capability:notification:1.0 1680 1681 1682 urn:ietf:params:netconf:capability:notification:1.1 1683 1684 1685 4 1686 1688 Figure 52: Hello message 1690 Clients that only support [RFC5277] recognize capability 1691 "urn:ietf:params:netconf:capability:notification:1.0" and ignore 1692 capability "urn:ietf:params:netconf:capability:notification:1.1". 1693 This allows them interacting with the server as per [RFC5277]. 1694 Clients that support the features in this document recognize both 1695 capabilities. This allows them interacting with the server as per 1696 this document. 1698 3.2. Stream Discovery 1700 In order to maintain backwards compatibility, clients that only 1701 support [RFC5277] can retrieve the list of available event streams 1702 executing a operation against the container "/netconf/streams". 1704 4. Security Considerations 1706 The security considerations from the base NETCONF document [RFC6241] 1707 also apply to the notification capability. 1709 The elements are never sent before the transport layer 1710 and the NETCONF layer, including capabilities exchange, have been 1711 established and the manager has been identified and authenticated. 1713 A secure transport must be used and the server must ensure that the 1714 user has sufficient authorization to perform the function they are 1715 requesting against the specific subset of NETCONF content involved. 1716 When a is received that refers to the content defined in this 1717 memo, clients should only be able to view the content for which they 1718 have sufficient privileges. and operations can be considered like deferred , and 1720 the content that different users can access may vary. This different 1721 access is reflected in the that different users are 1722 able to subscribe to. 1724 The contents of notifications, as well as the names of event streams, 1725 may contain sensitive information and care should be taken to ensure 1726 that they are viewed only by authorized users. The NETCONF server 1727 MUST NOT include any content in a notification that the user is not 1728 authorized to view. 1730 If a malicious or buggy NETCONF client sends a number of requests, then these subscriptions accumulate and may 1732 use up system resources. In such a situation, subscriptions can be 1733 terminated by terminating the suspect underlying NETCONF sessions 1734 using the operation. If the client uses , the server can also suspend or terminate subscriptions 1736 with per-subscription granularity. 1738 A subscription could be configured on another receiver's behalf, with 1739 the goal of flooding that receiver with updates. One or more 1740 publishers could be used to overwhelm a receiver, which doesn't even 1741 support subscriptions. Clients that do not want pushed data need 1742 only terminate or refuse any transport sessions from the publisher. 1743 In addition, the NETCONF Authorization Control Model [RFC6536] SHOULD 1744 be used to control and restrict authorization of subscription 1745 configuration. This control models permits specifying per-user 1746 permissions to receive specific event notification types. The 1747 permissions are specified as a set of access control rules. 1749 Note that streams can define additional authorization requirements. 1750 For instance, in [yang-push] each of the elements in its data plane 1751 notifications must also go through access control. 1753 5. Acknowledgments 1755 We wish to acknowledge the helpful contributions, comments, and 1756 suggestions that were received from: Andy Bierman, Yan Gang, Peipei 1757 Guo, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent Watsen, and 1758 Guangying Zheng. 1760 6. References 1762 6.1. Normative References 1764 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1765 Requirement Levels", BCP 14, RFC 2119, 1766 DOI 10.17487/RFC2119, March 1997, 1767 . 1769 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1770 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1771 . 1773 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1774 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1775 . 1777 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1778 the Network Configuration Protocol (NETCONF)", RFC 6020, 1779 DOI 10.17487/RFC6020, October 2010, 1780 . 1782 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1783 and A. Bierman, Ed., "Network Configuration Protocol 1784 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1785 . 1787 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1788 Protocol (NETCONF) Access Control Model", RFC 6536, 1789 DOI 10.17487/RFC6536, March 2012, 1790 . 1792 6.2. Informative References 1794 [call-home] 1795 Watsen, K., "NETCONF Call Home and RESTCONF Call Home", 1796 December 2015, . 1799 [event-notifications] 1800 Clemm, A., Gonzalez Prieto, A., Voit, Eric., Nilsen- 1801 Nygaard, E., Tripathy, A., Chisholm, S., and H. Trevino, 1802 "Subscribing to Event Notifications", June 2016, 1803 . 1806 [yang-push] 1807 Clemm, A., Gonzalez Prieto, A., Voit, Eric., Tripathy, A., 1808 and E. Nilsen-Nygaard, "Subscribing to YANG datastore push 1809 updates", February 2016, 1810 . 1813 Appendix A. Issues that are currently being worked 1815 (To be removed by RFC editor prior to publication) 1817 o NT1 - Express filter in JSON should be documented. 1819 Appendix B. Changes between revisions 1821 (To be removed by RFC editor prior to publication) 1823 B.1. v00 to v01 1825 o D1 - Added Call Home in solution for configured subscriptions. 1827 o D2 - Clarified support for multiple subscription on a single 1828 session. No need to support multiple create-subscription. 1830 o D3 - Added mapping between terminology in [yang-push] and 1831 [RFC6241] (the one followed in this document). 1833 o D4 - Editorial improvements. 1835 Authors' Addresses 1836 Alberto Gonzalez Prieto 1837 Cisco Systems 1839 Email: albertgo@cisco.com 1841 Alexander Clemm 1842 Sympotech 1844 Email: alex@sympotech.com 1846 Eric Voit 1847 Cisco Systems 1849 Email: evoit@cisco.com 1851 Einar Nilsen-Nygaard 1852 Cisco Systems 1854 Email: einarnn@cisco.com 1856 Ambika Prasad Tripathy 1857 Cisco Systems 1859 Email: ambtripa@cisco.com 1861 Sharon Chisholm 1862 Ciena 1864 Email: schishol@ciena.com 1866 Hector Trevino 1867 Cisco Systems 1869 Email: htrevino@cisco.com