idnits 2.17.1 draft-gonzalez-netconf-event-notifications-00.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 (June 15, 2016) is 2871 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 A. Clemm 4 Intended status: Standards Track E. Voit 5 Expires: December 17, 2016 E. Nilsen-Nygaard 6 A. Tripathy 7 Cisco Systems 8 S. Chisholm 9 Ciena 10 H. Trevino 11 Cisco Systems 12 June 15, 2016 14 NETCONF Support for Event Notifications 15 draft-gonzalez-netconf-event-notifications-00 17 Abstract 19 This document defines the support of [event-notifications] by the 20 Network Configuration protocol (NETCONF). [event-notifications] 21 describes capabilities and operations for providing asynchronous 22 message notification delivery. This document discussed how to 23 provide them on top of NETCONF. The capabilities and operations 24 defined between this document and [event-notifications] are intended 25 to obsolete RFC 5277. 27 Status of This Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on December 17, 2016. 44 Copyright Notice 46 Copyright (c) 2016 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 62 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 63 1.2. Solution Overview . . . . . . . . . . . . . . . . . . . . 5 64 2. Solution . . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 2.1. Event Streams . . . . . . . . . . . . . . . . . . . . . . 5 66 2.2. Event Stream Discovery . . . . . . . . . . . . . . . . . 6 67 2.3. Default Event Stream . . . . . . . . . . . . . . . . . . 8 68 2.4. Creating a Subscription . . . . . . . . . . . . . . . . . 8 69 2.5. Establishing a Subscription . . . . . . . . . . . . . . . 11 70 2.6. Modifying a Subscription . . . . . . . . . . . . . . . . 15 71 2.7. Deleting a Subscription . . . . . . . . . . . . . . . . . 20 72 2.8. Configured Subscriptions . . . . . . . . . . . . . . . . 23 73 2.9. Event (Data Plane) Notifications . . . . . . . . . . . . 31 74 2.10. Control Plane Notifications . . . . . . . . . . . . . . . 33 75 3. Backwards Compatibility . . . . . . . . . . . . . . . . . . . 43 76 3.1. Capabilities . . . . . . . . . . . . . . . . . . . . . . 43 77 3.2. Stream Discovery . . . . . . . . . . . . . . . . . . . . 44 78 4. Security Considerations . . . . . . . . . . . . . . . . . . . 44 79 5. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 45 80 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 45 81 6.1. Normative References . . . . . . . . . . . . . . . . . . 45 82 6.2. Informative References . . . . . . . . . . . . . . . . . 46 83 Appendix A. Issues being worked and resolved . . . . . . . . . . 46 84 A.1. Unresolved Issues . . . . . . . . . . . . . . . . . . . . 46 85 A.2. Agreement in principal . . . . . . . . . . . . . . . . . 46 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 47 88 1. Introduction 90 [RFC6241] can be conceptually partitioned into four layers: 92 Layer Example 93 +-------------+ +-------------------------------------------+ 94 | Content | | Configuration data | 95 +-------------+ +-------------------------------------------+ 96 | | 97 +-------------+ +-------------------------------------------+ 98 | Operations | |, , | 99 +-------------+ +-------------------------------------------+ 100 | | | 101 +-------------+ +-----------------------------+ | 102 | RPC | | , | | 103 +-------------+ +-----------------------------+ | 104 | | | 105 +-------------+ +-------------------------------------------+ 106 | Transport | | BEEP, SSH, SSL, console | 107 | Protocol | | | 108 +-------------+ +-------------------------------------------+ 110 Figure 1: NETCONF layer architecture 112 This document defines mechanisms that provide an asynchronous message 113 notification delivery service for the NETCONF protocol [RFC6241] 114 based on [event-notifications]. This is an optional capability built 115 on top of the base NETCONF definition. 117 [event-notifications] and this document enhance the capabilities of 118 RFC 5277 while maintaining backwards capability with existing 119 implementations. It is intended that a final version of this 120 document might obsolete [RFC5277]. 122 The enhancements over [RFC5277] include the ability to terminate 123 subscriptions without terminating the client session, to modify 124 existing subscriptions, and to have multiple subscriptions on a 125 NETCONF session. 127 These enhancements do not affect [RFC5277] clients that do not 128 support these particular subscription requirements. 130 [event-notifications] covers the following functionality: 132 o Ability to subscribe to event notifications using two mechanisms: 133 dynamic and configuration subscriptions. 135 o Ability to subscribe to event notifications using two mechanisms: 136 dynamic and configuration subscriptions. 138 o Ability to negotiate acceptable subscription parameters. 140 o Ability to filter the subset of notifications to be pushed with 141 stream-specific semantics. 143 o Ability to support multiple encodings for the notification. 145 o Mechanism to communicate the notifications. 147 o Ability to replay locally logged notifications. 149 To support this functionality, NETCONF agents must implement the 150 operations, configuration and operational state defined in 151 [event-notifications]. In addition, they need to: 153 o support multiple subscriptions over a single NETCONF session. 155 o support a revised definition of the default NETCONF stream 157 o be backwards compatible with RFC 5277 implementations. 159 1.1. Terminology 161 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 162 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 163 document are to be interpreted as described in RFC 2119 [RFC2119]. 165 1.1.1. Event Notifications 167 The following terms are defined in [event-notifications]: 169 o Event 171 o Event notification 173 o Stream (also referred to as "event stream") 175 o Subscriber 177 o Receiver 179 o Subscription 181 o Filter 183 o Dynamic subscription 185 o Configured subscription 187 1.1.2. NETCONF 189 The following terms are defined in [RFC6241] : 191 o Operation 193 o RPC: remote procedure call 195 1.1.3. NETCONF Access Control 197 The following terms are defined in [RFC6536] : 199 o NACM: NETCONF Access Control Model 201 1.2. Solution Overview 203 [event-notifications] defines mechanisms that provide an asynchronous 204 message notification delivery service. This document discusses its 205 realization on top of the NETCONF protocol [RFC6241]. 207 The functionality to support is defined in [event-notifications]. It 208 is formalized in a set of yang models. The mapping of yang 209 constructs into NETCONF is described in [RFC6020]. 211 Supporting [event-notifications] requires enhancements and 212 modifications in NETCONF. The key enhacement is suporting multiple 213 subscriptions on a NETCONF session. A key modification is the 214 definition of the NETCONF stream 216 These enhancements do not affect [RFC5277] clients that do not 217 support [event-notifications]. 219 2. Solution 221 In this section, we describe and exemplify how [event-notifications] 222 must be supported over NETCONF. 224 2.1. Event Streams 226 In the context of NETCONF, an event stream is a set of events 227 available for subscription from a NETCONF server. It is out of the 228 scope of this document to identify a) how streams are defined, b) how 229 events are defined/generated, and c) how events are assigned to 230 streams. 232 The following is a high-level description of the flow of a 233 notification. Note that it does not mandate and/or preclude an 234 implementation. As events are raised, they are assigned to streams. 236 An event may be assigned to multiple streams. The event is 237 distributed to subscribers and receivers based on the current 238 subscriptions and access control. Access control is needed because 239 if any receiver of that subscription does not have permission to 240 receive an event, then it never makes it into a notification, and 241 processing of the event is completed for that subscription. 243 2.2. Event Stream Discovery 245 A NETCONF client can retrieve the list of available event streams 246 from a NETCONF server using the operation. The reply contains 247 the elements defined in the YANG model under the container 248 "/streams", which includes the stream identifier. 250 The following example ilustrates the retrieval of the list of 251 available event streams using the operation. 253 255 256 257 259 260 261 263 Figure 2: Get streams 265 The NETCONF server returns a list of event streams available for 266 subscription. In this example, the list contains the NETCONF, SNMP, 267 and syslog-critical streams. 269 271 272 274 NETCONF 275 SNMP 276 syslog-critical 277 NETCONF 278 279 280 282 Figure 3: Get streams response 284 2.2.1. Backwards Compatibility 286 In order to maintain backwards compatibility, clients that only 287 support [RFC5277] can retrieve the list of available event streams 288 executing a operation against the container "/netconf/streams". 290 The following example ilustrates this mechanism. 292 294 295 296 298 299 300 301 302 304 Figure 4: Get streams (backwards compatibility) 306 The NETCONF server returns a list of event streams available for 307 subscription. In this example, the list contains the NETCONF, SNMP, 308 and syslog-critical streams. 310 312 313 315 316 317 318 NETCONF 319 320 321 default NETCONF event stream 322 323 324 true 325 326 327 2016-02-05T00:00:00Z 328 329 330 331 332 SNMP 333 334 335 SNMP notifications 336 337 338 false 339 340 341 342 343 syslog-critical 344 345 346 Critical and higher severity 347 348 349 true 350 351 352 2007-07-01T00:00:00Z 353 354 355 356 357 358 360 Figure 5: Get streams response (backwards compatibility) 362 2.3. Default Event Stream 364 A NETCONF server implementation supporting the notification 365 capability MUST support the "NETCONF" notification event stream. 366 This stream contains all NETCONF XML event notifications supported by 367 the NETCONF server, except for those belonging only to streams that 368 explicitly indicate that they must be excluded from the NETCONF 369 stream. The exact string "NETCONF" is used during the advertisement 370 of stream support during the operation on and during 371 the and operations. 373 2.4. Creating a Subscription 375 The following illustrates the creation of a simple subscription. 377 2.4.1. Usage Example 379 The following demonstrates dynamically creating a subscription. This 380 operation is fully defined in [RFC5277] 382 384 386 387 389 Figure 6: Create subscription 391 2.4.2. Positive Response 393 If the NETCONF server can satisfy the request, the server sends an 394 element. 396 398 400 405 406 408 410 411 413 Figure 7: Successful create subscription 415 2.4.3. Negative Response 417 If the request cannot be completed for any reason, an 418 element is included within the . Subscription requests 419 can fail for several reasons including if a filter with invalid 420 syntax is provided or if the name of a non-existent stream is 421 provided. 423 If a stopTime is specified in a request without having specified a 424 startTime, the following error is returned: 426 Tag: missing-element 427 Error-type: protocol 428 Severity: error 429 Error-info: : startTime 430 Description: An expected element is missing. 432 Figure 8: Create subscription missing an element 434 If the optional replay feature is requested but the NETCONF server 435 does not support it, the following error is returned: 437 Tag: operation-failed 438 Error-type: protocol 439 Severity: error 440 Error-info: none 441 Description: Request could not be completed because the 442 requested operation failed for some reason 443 not covered by any other error condition. 445 Figure 9: Create subscription pperation failed 447 If a stopTime is requested that is earlier than the specified 448 startTime, the following error is returned: 450 Tag: bad-element 451 Error-type: protocol 452 Severity: error 453 Error-info: : stopTime 454 Description: An element value is not correct; 455 e.g., wrong type, out of range, pattern mismatch. 457 Figure 10: Create subscription incorrect stopTime 459 If a startTime is requested that is later than the current time, the 460 following error is returned: 462 Tag: bad-element 463 Error-type: protocol 464 Severity: error 465 Error-info: : startTime 466 Description: An element value is not correct; 467 e.g., wrong type, out of range, pattern mismatch. 469 Figure 11: Create subscription incorrect startTime 471 2.5. Establishing a Subscription 473 2.5.1. Usage Example 475 The following illustrates the establishment of a simple subscription. 477 479 481 482 484 Figure 12: Establish subscription 486 2.5.2. Positive Response 488 If the NETCONF server can satisfy the request, the server sends a 489 positive element, and the subscription-id of 490 the accepted subscription. 492 494 496 501 502 504 506 508 ok 509 510 512 52 513 514 516 Figure 13: Successful establish subscription 518 2.5.3. Negative Response 520 If the NETCONF server cannot satisfy the request, the server sends a 521 negative element. 523 If the client has no authorization to establish the subscription, the 524 indicates an authorization error. For 525 instance: 527 529 531 foo 532 533 535 537 539 error-data-not-authorized 540 541 543 Figure 14: Unsuccessful establish subscription 545 If the request is rejected because the server is not able to serve 546 it, the server SHOULD include in the returned error what subscription 547 parameters would have been accepted for the request when it was 548 processed. However, they are no guarantee that subsequent requests 549 with those parameters for this client or others will be accepted. 550 For instance, consider a subscription from [netconf-yang-push], which 551 augments the establish-subscription with some additional parameters, 552 including "period". If the client requests a period the NETCONF 553 server cannot serve, the exchange may be: 555 557 559 push-update 560 563 564 500 565 566 encode-xml 567 568 570 572 574 error-insufficient-resources 575 576 578 2000 579 580 582 Figure 15: Subscription establishment negotiation 584 Subscription requests will fail if a filter with invalid syntax is 585 provided or if the name of a non-existent stream is provided. 587 2.5.4. Multiple Subscriptions over a Single NETCONF Session 589 Note that [event-notifications] requires supporting multiple 590 subscriptions over a single NETCONF session. In contrast, [RFC5277] 591 mandated server to return an error when a create-subscription was 592 sent while a subscription was active on that session. 594 2.5.5. Message Flow Examples 595 +------------+ +-----------+ 596 | Client | | Server | 597 +------------+ +-----------+ 598 | | 599 | Capability Exchange | 600 |<---------------------------->| 601 | | 602 | | 603 | Establish Subscription | 604 |----------------------------->| 605 | RPC Reply: OK, subs-id = 22 | 606 |<-----------------------------| 607 | | 608 | Notification (subs-id 22) | 609 |<-----------------------------| 610 | | 611 | | 612 | Notification (subs-id 22) | 613 |<-----------------------------| 614 | Notification (subs-id 22) | 615 |<-----------------------------| 616 | | 617 | | 619 Figure 16: Message flow for subscription establishment 621 +------------+ +-----------+ 622 | Client | | Server | 623 +------------+ +-----------+ 624 | | 625 | Capability Exchange | 626 |<---------------------------->| 627 | | 628 | | 629 | Establish Subscription | 630 |----------------------------->| 631 | RPC Reply: OK, subs-id = 22 | 632 |<-----------------------------| 633 | | 634 | Notification (subs-id 22) | 635 |<-----------------------------| 636 | | 637 | | 638 | Establish Subscription | 639 |----------------------------->| 640 | RPC Reply: OK, subs-id = 23 | 641 |<-----------------------------| 642 | | 643 | Notification (subs-id 22) | 644 |<-----------------------------| 645 | | 646 | | 647 | Notification (subs-id 22) | 648 |<-----------------------------| 649 | Notification (subs-id 23) | 650 |<-----------------------------| 651 | | 652 | | 654 Figure 17: Message Flow for multiple subscription establishments over 655 a single session 657 2.6. Modifying a Subscription 659 2.6.1. Usage Example 661 The following demonstrates modifying a subscription. Consider a 662 subscription from [netconf-yang-push], which augments the establish- 663 subscription with some additional parameters, including "period". A 664 subscription may be established as follows. 666 668 670 push-update 671 674 675 500 676 677 encode-xml 678 679 681 683 685 ok 686 687 689 1922 690 691 693 Figure 18: Establish subscription to be modified 695 The subscription may be modified with: 697 699 701 1922 702 1000 703 704 706 708 710 ok 711 712 714 1922 715 716 718 Figure 19: Modify subscription 720 2.6.2. Positive Response 722 If the NETCONF server can satisfy the request, the server sends a 723 positive element. This response is like that 724 to an establish-subscription request. but without the subscription- 725 id, which would be redundant. 727 729 731 1922 732 734 1000 735 736 737 739 741 743 ok 744 745 747 Figure 20: Successful modify subscription 749 2.6.3. Negative Response 751 If the NETCONF server cannot satisfy the request, the server sends a 752 negative element. Its contents and semantics 753 are identical to those to an establish-subscription request. For 754 instance: 756 758 760 1922 761 762 100 763 764 765 767 769 771 error-insufficient-resources 772 773 500 774 776 Figure 21: Unsuccessful modify subscription 778 2.6.4. Message Flow Example 779 +------------+ +-----------+ 780 | Client | | Server | 781 +------------+ +-----------+ 782 | | 783 | Capability Exchange | 784 |<---------------------------->| 785 | | 786 | | 787 | Establish Subscription | 788 |----------------------------->| 789 | RPC Reply: OK, subs-id = 22 | 790 |<-----------------------------| 791 | | 792 | Notification (subs-id 22) | 793 |<-----------------------------| 794 | | 795 | | 796 | | 797 | | 798 | Modify Subscription | 799 |----------------------------->| 800 | | 801 | | 802 | Notification (subs-id 22) | 803 |<-----------------------------| 804 | Notification (subs-id 22) | 805 |<-----------------------------| 806 | | 807 | | 809 Figure 22: Message flow for subscription modification 811 2.7. Deleting a Subscription 813 2.7.1. Usage Example 815 The following demonstrates deleting a subscription. 817 819 821 1922 822 823 825 Figure 23: Delete subscription 827 2.7.2. Positive Response 829 If the NETCONF server can satisfy the request, the server sends an OK 830 element. For example: 832 834 836 1922 837 838 840 842 843 845 Figure 24: Successful delete subscription 847 2.7.3. Negative Response 849 If the NETCONF server cannot satisfy the request, the server sends an 850 error-rpc element. For example: 852 854 856 2017 857 858 860 862 863 application 864 invalid-value 865 error 866 868 /t:subscription-id 869 870 871 Subscription-id 2017 does not exist 872 873 874 876 Figure 25: Unsuccessful delete subscription 878 2.7.4. Message Flow Example 879 +------------+ +-----------+ 880 | Client | | Server | 881 +------------+ +-----------+ 882 | | 883 | Capability Exchange | 884 |<---------------------------->| 885 | | 886 | | 887 | Establish Subscription | 888 |----------------------------->| 889 | RPC Reply: OK, subs-id = 22 | 890 |<-----------------------------| 891 | | 892 | Notification (subs-id 22) | 893 |<-----------------------------| 894 | | 895 | | 896 | Notification (subs-id 22) | 897 |<-----------------------------| 898 | Notification (subs-id 22) | 899 |<-----------------------------| 900 | | 901 | | 902 | Delete Subscription | 903 |----------------------------->| 904 | | 905 | | 906 | | 907 | | 909 Figure 26: Message flow for subscription deletion 911 2.8. Configured Subscriptions 913 A configured subscription is a subscription installed via a 914 configuration interface, and do not support negotiation. 916 Supporting configured subscriptions is optional and advertised during 917 the capabilities exchange using the "configured-subscriptions" 918 feature. 920 In this section, we present examples of how to manage configuration 921 subscriptions using a NETCONF client. 923 2.8.1. Establishing a Configured Subscription 925 Subscriptions are established using configuration operations against 926 the top-level subtree subscription-config. 928 For example at subscription establishment, a NETCONF client may send: 930 933 934 935 936 937 939 940 941 1922 942 943 944 foo 945 946 947
948 1.2.3.4 949
950 951 1234 952 953 954 955 956 957 959 Figure 27: Establish static subscription 961 if the request is accepted, the server would reply: 963 965 966 968 Figure 28: Response to a successful static subscription establishment 969 if the request is not accepted because the server cannot serve it, 970 the server may reply: 972 973 974 application 975 resource-denied 976 error 977 978 Temporarily the server cannot serve this 979 subscription due to the current workload. 980 981 982 984 Figure 29: Response to a failed static subscription establishment 986 2.8.1.1. Message Flow Example 987 +----------+ +-----------+ +---------+ +---------+ 988 | Client | | Server | | Rcver A | | Rcver B | 989 +----------+ +-----------+ +---------+ +---------+ 990 | | | | 991 | Capability Exchange | | | 992 |<-------------------------->| | | 993 | | | | 994 | | | | 995 | Edit-config | | | 996 |--------------------------->| | | 997 | RPC Reply: OK | | | 998 |<---------------------------| | | 999 | | Subscription | | 1000 | | Started | | 1001 | | (subs-id 22) | | 1002 | |--------------->| | 1003 | |---------------------------->| 1004 | | | | 1005 | | Notification | | 1006 | | (subs-id 22) | | 1007 | |--------------->| | 1008 | |---------------------------->| 1009 | | | | 1010 | | | | 1011 | | | | 1012 | | | | 1013 | | | | 1014 | | Notification | | 1015 | | (subs-id 22) | | 1016 | |--------------->| | 1017 | |---------------------------->| 1018 | | | | 1019 | | Notification | | 1020 | | (subs-id 22) | | 1021 | |--------------->| | 1022 | |---------------------------->| 1023 | | | | 1025 Figure 30: Message flow for subscription establishment (configured 1026 subscription) 1028 2.8.2. Modifying a Configured Subscription 1030 Configured subscriptions can be modified using configuration 1031 operations against the top-level subtree subscription-config. 1033 For example, the subscription established in the previous section 1034 could be modified as follows, choosing a different receiver: 1036 1039 1040 1041 1042 1043 1045 1046 1047 1922 1048 1049 1050 foo 1051 1052 1053
1054 1.2.3.5 1055
1056 1057 1234 1058 1059 1060 1061 1062 1063 1065 Figure 31: Modify configured subscription 1067 if the request is accepted, the server would reply: 1069 1071 1072 1074 Figure 32: Response to a successful configured subscription 1075 modification 1077 2.8.2.1. Message Flow Example 1078 +----------+ +-----------+ +---------+ +---------+ 1079 | Client | | Server | | Rcver A | | Rcver B | 1080 +----------+ +-----------+ +---------+ +---------+ 1081 | | | | 1082 | Capability Exchange | | | 1083 |<-------------------------->| | | 1084 | | | | 1085 | | | | 1086 | Edit-config | | | 1087 |--------------------------->| | | 1088 | RPC Reply: OK | | | 1089 |<---------------------------| | | 1090 | | Subscription | | 1091 | | Started | | 1092 | | (subs-id 22) | | 1093 | |--------------->| | 1094 | |---------------------------->| 1095 | | | | 1096 | | Notification | | 1097 | | (subs-id 22) | | 1098 | |--------------->| | 1099 | |---------------------------->| 1100 | | | | 1101 | | | | 1102 | | | | 1103 | Edit-config | | | 1104 |--------------------------->| | | 1105 | RPC Reply: OK | | | 1106 |<---------------------------| | | 1107 | | | | 1108 | | | | 1109 | | Subscription | | 1110 | | Modified | | 1111 | | (subs-id 22) | | 1112 | |--------------->| | 1113 | |---------------------------->| 1114 | | | | 1115 | | Notification | | 1116 | | (subs-id 22) | | 1117 | |--------------->| | 1118 | |---------------------------->| 1119 | | | | 1121 Figure 33: Message flow for subscription modification (configured 1122 subscription) 1124 2.8.3. Deleting a Configured Subscription 1126 Subscriptions can be deleted using configuration operations against 1127 the top-level subtree subscription-config. For example: 1129 1131 1132 1133 1134 1135 1137 1138 1139 1922 1140 1141 1142 1143 1144 1146 1148 1149 1151 Figure 34: Deleting a configured subscription 1153 2.8.3.1. Message Flow Example 1155 +----------+ +-----------+ +---------+ +---------+ 1156 | Client | | Server | | Rcver A | | Rcver B | 1157 +----------+ +-----------+ +---------+ +---------+ 1158 | | | | 1159 | Capability Exchange | | | 1160 |<-------------------------->| | | 1161 | | | | 1162 | | | | 1163 | Edit-config | | | 1164 |--------------------------->| | | 1165 | RPC Reply: OK | | | 1166 |<---------------------------| | | 1167 | | Subscription | | 1168 | | Started | | 1169 | | (subs-id 22) | | 1170 | |--------------->| | 1171 | |---------------------------->| 1172 | | | | 1173 | | Notification | | 1174 | | (subs-id 22) | | 1175 | |--------------->| | 1176 | |---------------------------->| 1177 | | | | 1178 | | | | 1179 | | | | 1180 | | | | 1181 | | | | 1182 | | Notification | | 1183 | | (subs-id 22) | | 1184 | |--------------->| | 1185 | |---------------------------->| 1186 | | | | 1187 | Edit-config | | | 1188 |--------------------------->| | | 1189 | RPC Reply: OK | | | 1190 |<---------------------------| | | 1191 | | | | 1192 | | | | 1193 | | Subscription | | 1194 | | Terminated | | 1195 | | (subs-id 22) | | 1196 | |--------------->| | 1197 | |---------------------------->| 1198 | | | | 1199 | | | | 1200 | | | | 1201 | | | | 1203 Figure 35: Message flow for subscription deletion (configured 1204 subscription) 1206 2.9. Event (Data Plane) Notifications 1208 Once a subscription has been set up, the NETCONF server sends 1209 (asynchronously) the event notifications from the subscribed stream. 1210 We refer to these as data plane notifications. For dynamic 1211 subscriptions set up via RPC operations, event notifications are sent 1212 over the NETCONF session used to create or establish the 1213 subscription. For static subscriptions, event notifications are sent 1214 over the specified connections. 1216 An event notification is sent to the receiver(s) when an event of 1217 interest (i.e., meeting the specified filtering criteria) has 1218 occurred. An event notification is a complete and well-formed XML 1219 document. Note that is not a Remote Procedure Call 1220 (RPC) method but rather the top-level element identifying the one-way 1221 message as a notification. Note that event notifications never 1222 trigger responses. 1224 The event notification always includes an element. It is 1225 the time the event was generated by the event source. This parameter 1226 is of type dateTime and compliant to [RFC3339]. Implementations must 1227 support time zones. 1229 The event notification also contains notification-specific tagged 1230 content, if any. With the exception of , the content of 1231 the notification is beyond the scope of this document. 1233 For the encodings other than XML, notifications include an additional 1234 XML element so that the notification is a well-formed XML. The 1235 element is , E.g., . That element contains the notification contents in 1237 the desired encoding 1239 The following is an example of an event notification from [RFC6020]: 1241 notification link-failure { 1242 description "A link failure has been detected"; 1243 leaf if-name { 1244 type leafref { 1245 path "/interface/name"; 1246 } 1247 } 1248 leaf if-admin-status { 1249 type admin-status; 1250 } 1251 leaf if-oper-status { 1252 type oper-status; 1253 } 1254 } 1256 Figure 36: Definition of a data plane notification 1258 1260 2007-09-01T10:00:00Z 1261 1262 so-1/2/3.0 1263 up 1264 down 1265 1266 1268 Figure 37: Data plane notification 1270 The equivalent using JSON encoding would be 1272 1274 2007-09-01T10:00:00Z 1275 1276 { 1277 "acme-system:link-failure": { 1278 "if-name": "so-1/2/3.0", 1279 "if-admin-status": "up", 1280 "if-oper-status": "down " 1281 } 1282 } 1283 1284 1286 Figure 38: Data plane notification using JSON encoding 1288 2.10. Control Plane Notifications 1290 In addition to data plane notifications, a server may send control 1291 plane notifications (defined in [event-notifications]) to indicate to 1292 receivers that an event related to the subscription management has 1293 occurred. Control plane notifications cannot be filtered out. Next 1294 we exemplify them using both XML, and JSON encondings for the data: 1296 2.10.1. replayComplete 1298 1300 2007-09-01T10:00:00Z 1301 1302 1304 Figure 39: replayComplete control plane notification 1306 The equivalent using JSON encoding would be: 1308 1310 2007-09-01T10:00:00Z 1311 1312 { 1313 "netmod-notif:replayComplete": { } 1314 } 1315 1316 1318 Figure 40: replayComplete control plane notification (JSON encoding) 1320 2.10.1.1. Message Flow Example 1321 +------------+ +-----------+ 1322 | Client | | Server | 1323 +------------+ +-----------+ 1324 | | 1325 | Capability Exchange | 1326 |<---------------------------->| 1327 | | 1328 | | 1329 | Establish Subscription | 1330 |----------------------------->| 1331 | RPC Reply: OK, subs-id = 22 | 1332 |<-----------------------------| 1333 | | 1334 | Notification (subs-id 22) | 1335 |<-----------------------------| 1336 | | 1337 | | 1338 | Notification (subs-id 22) | 1339 |<-----------------------------| 1340 | Replay Complete (subs-id 22) | 1341 |<-----------------------------| 1342 | | 1343 | | 1344 | | 1345 | Notification (subs-id 22) | 1346 |<-----------------------------| 1347 | | 1348 | Notification (subs-id 22) | 1349 |<-----------------------------| 1350 | | 1351 | | 1352 | | 1354 Figure 41: replayComplete notification 1356 2.10.2. notificationComplete 1358 1360 2007-09-01T10:00:00Z 1361 1363 1365 Figure 42: notificationComplete control plane notification 1367 2.10.2.1. Message Flow Example 1368 +------------+ +-----------+ 1369 | Client | | Server | 1370 +------------+ +-----------+ 1371 | | 1372 | Capability Exchange | 1373 |<---------------------------->| 1374 | | 1375 | | 1376 | Establish Subscription | 1377 |----------------------------->| 1378 | RPC Reply: OK, subs-id = 22 | 1379 |<-----------------------------| 1380 | | 1381 | Notification (subs-id 22) | 1382 |<-----------------------------| 1383 | | 1384 | | 1385 | Notification (subs-id 22) | 1386 |<-----------------------------| 1387 | Replay Complete (subs-id 22) | 1388 |<-----------------------------| 1389 | | 1390 | | 1391 | | 1392 | Notification (subs-id 22) | 1393 |<-----------------------------| 1394 | | 1395 | Notification (subs-id 22) | 1396 |<-----------------------------| 1397 | | 1398 | | 1399 | | 1400 | Notification Complete | 1401 | (subs-id 22) | 1402 |<-----------------------------| 1403 | | 1404 | | 1405 | | 1406 | RPC | 1407 |----------------------------->| 1408 | RPC Reply | 1409 |<-----------------------------| 1410 | | 1411 | | 1413 Figure 43: notificationComplete notification 1415 2.10.3. subscription-started 1417 1419 2007-09-01T10:00:00Z 1420 1422 52 1423 1428 1429 1431 Figure 44: subscription-started control plane notification 1433 The equivalent using JSON encoding would be: 1435 1437 2007-09-01T10:00:00Z 1438 1439 { 1440 "notif-bis:subscription-started": { 1441 "subscription-id" : 52 1442 ((Open Item: express filter in json)) 1443 } 1444 } 1445 1446 1448 Figure 45: subscription-started control plane notification (JSON 1449 encoding) 1451 2.10.4. subscription-modified 1452 1454 2007-09-01T10:00:00Z 1455 1457 52 1458 1461 1462 1464 Figure 46: subscription-modified control plane notification 1466 2.10.5. subscription-terminated 1468 1470 2007-09-01T10:00:00Z 1471 1473 52 1474 subscription-deleted 1475 1476 1478 Figure 47: subscription-terminated control plane notification 1480 2.10.6. subscription-suspended 1482 1484 2007-09-01T10:00:00Z 1485 1487 52 1488 internal-error 1489 1490 1492 Figure 48: subscription-suspended control plane notification 1494 2.10.7. subscription-resumed 1495 1497 2007-09-01T10:00:00Z 1498 1500 52 1501 internal-error 1502 1503 1505 Figure 49: subscription-resumed control plane notification 1507 2.10.7.1. Message Flow Examples 1508 +------------+ +-----------+ 1509 | Client | | Server | 1510 +------------+ +-----------+ 1511 | | 1512 | Capability Exchange | 1513 |<---------------------------->| 1514 | | 1515 | | 1516 | Establish Subscription | 1517 |----------------------------->| 1518 | RPC Reply: OK, subs-id = 22 | 1519 |<-----------------------------| 1520 | | 1521 | Notification | 1522 |<-----------------------------| 1523 | | 1524 | | 1525 | Notification | 1526 |<-----------------------------| 1527 | Notification | 1528 |<-----------------------------| 1529 | | 1530 | | 1531 | Subscription Suspended | 1532 |<-----------------------------| 1533 | | 1534 | | 1535 | | 1536 | Subscription Resumed | 1537 |<-----------------------------| 1538 | | 1539 | | 1540 | | 1541 | | 1542 | Notification | 1543 |<-----------------------------| 1544 | | 1545 | | 1547 Figure 50: subscription-suspended and Resumed Notifications 1549 +----------+ +-----------+ +---------+ +---------+ 1550 | Client | | Server | | Rcver A | | Rcver B | 1551 +----------+ +-----------+ +---------+ +---------+ 1552 | | | | 1553 | Capability Exchange | | | 1554 |<-------------------------->| | | 1555 | | | | 1556 | | | | 1557 | Edit-config | | | 1558 |--------------------------->| | | 1559 | RPC Reply: OK | | | 1560 |<---------------------------| | | 1561 | | Subscription | | 1562 | | Started | | 1563 | |--------------->| | 1564 | |---------------------------->| 1565 | | | | 1566 | | Notification | | 1567 | |--------------->| | 1568 | |---------------------------->| 1569 | | | | 1570 | | | | 1571 | | | | 1572 | | | | 1573 | | Subscription | | 1574 | | Suspended | | 1575 | |--------------->| | 1576 | |---------------------------->| 1577 | | | | 1578 | | | | 1579 | | | | 1580 | | | | 1581 | | | | 1582 | | Subscription | | 1583 | | Resumed | | 1584 | |--------------->| | 1585 | |---------------------------->| 1586 | | | | 1587 | | | | 1588 | | | | 1589 | | Notification | | 1590 | |--------------->| | 1591 | |---------------------------->| 1592 | | | | 1593 | | Notification | | 1594 | |--------------->| | 1595 | |---------------------------->| 1596 | | | | 1597 | | | | 1598 | | | | 1599 | | | | 1600 Figure 51: subscription-suspended and subscription-resumed 1601 notifications (configured subscriptions) 1603 3. Backwards Compatibility 1605 3.1. Capabilities 1607 Capabilities are advertised in messages sent by each peer during 1608 session establishment [RFC6241]. Servers supporting the features in 1609 this document must advertise both capabilities 1610 "urn:ietf:params:netconf:capability:notification:1.0" and 1611 "urn:ietf:params:netconf:capability:notification:1.1". 1613 An example of a hello message by a server during session 1614 establishment would be: 1616 1617 1618 1619 urn:ietf:params:xml:ns:netconf:base:1.0 1620 1621 1622 urn:ietf:params:netconf:capability:startup:1.0 1623 1624 1625 urn:ietf:params:netconf:capability:notification:1.0 1626 1627 1628 urn:ietf:params:netconf:capability:notification:1.1 1629 1630 1631 4 1632 1634 Figure 52: Hello message 1636 Clients that only support [RFC5277] recognize capability 1637 "urn:ietf:params:netconf:capability:notification:1.0" and ignore 1638 capability "urn:ietf:params:netconf:capability:notification:1.1". 1639 This allows them interacting with the server as per [RFC5277]. 1640 Clients that support the features in this document recognize both 1641 capabilities. This allows them interacting with the server as per 1642 this document. 1644 3.2. Stream Discovery 1646 In order to maintain backwards compatibility, clients that only 1647 support [RFC5277] can retrieve the list of available event streams 1648 executing a operation against the container "/netconf/streams". 1650 4. Security Considerations 1652 The security considerations from the base NETCONF document [RFC6241] 1653 also apply to the notification capability. 1655 The elements are never sent before the transport layer 1656 and the NETCONF layer, including capabilities exchange, have been 1657 established and the manager has been identified and authenticated. 1659 A secure transport must be used and the server must ensure that the 1660 user has sufficient authorization to perform the function they are 1661 requesting against the specific subset of NETCONF content involved. 1662 When a is received that refers to the content defined in this 1663 memo, clients should only be able to view the content for which they 1664 have sufficient privileges. and operations can be considered like deferred , and 1666 the content that different users can access may vary. This different 1667 access is reflected in the that different users are 1668 able to subscribe to. 1670 The contents of notifications, as well as the names of event streams, 1671 may contain sensitive information and care should be taken to ensure 1672 that they are viewed only by authorized users. The NETCONF server 1673 MUST NOT include any content in a notification that the user is not 1674 authorized to view. 1676 If a malicious or buggy NETCONF client sends a number of requests, then these subscriptions accumulate and may 1678 use up system resources. In such a situation, subscriptions can be 1679 terminated by terminating the suspect underlying NETCONF sessions 1680 using the operation. If the client uses , the server can also suspend or terminate subscriptions 1682 with per-subscription granularity. 1684 A subscription could be configured on another receiver's behalf, with 1685 the goal of flooding that receiver with updates. One or more 1686 publishers could be used to overwhelm a receiver, which doesn't even 1687 support subscriptions. Clients that do not want pushed data need 1688 only terminate or refuse any transport sessions from the publisher. 1689 In addition, the NETCONF Authorization Control Model [RFC6536] SHOULD 1690 be used to control and restrict authorization of subscription 1691 configuration. This control models permits specifying per-user 1692 permissions to receive specific event notification types. The 1693 permissions are specified as a set of access control rules. 1695 Note that streams can define additional authorization requirements. 1696 For instance, in [netconf-yang-push] each of the elements in its data 1697 plane notifications must also go through access control. 1699 5. Acknowledgments 1701 We wish to acknowledge the helpful contributions, comments, and 1702 suggestions that were received from: Andy Bierman, Yan Gang, Peipei 1703 Guo, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent Watsen, and 1704 Guangying Zheng. 1706 6. References 1708 6.1. Normative References 1710 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1711 Requirement Levels", BCP 14, RFC 2119, 1712 DOI 10.17487/RFC2119, March 1997, 1713 . 1715 [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: 1716 Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002, 1717 . 1719 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1720 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008, 1721 . 1723 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1724 the Network Configuration Protocol (NETCONF)", RFC 6020, 1725 DOI 10.17487/RFC6020, October 2010, 1726 . 1728 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1729 and A. Bierman, Ed., "Network Configuration Protocol 1730 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1731 . 1733 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1734 Protocol (NETCONF) Access Control Model", RFC 6536, 1735 DOI 10.17487/RFC6536, March 2012, 1736 . 1738 6.2. Informative References 1740 [event-notifications] 1741 Gonzalez Prieto, A., Clemm, A., Voit, Eric., Nilsen- 1742 Nygaard, E., Tripathy, A., Chisholm, S., and H. Trevino, 1743 "Subscribing to YANG-Defined Event Notifications", June 1744 2016, . 1747 [netconf-yang-push] 1748 Clemm, A., Gonzalez Prieto, A., Voit, Eric., Tripathy, A., 1749 and E. Nilsen-Nygaard, "Subscribing to YANG datastore push 1750 updates", February 2016, 1751 . 1754 Appendix A. Issues being worked and resolved 1756 (To be removed by RFC editor prior to publication) 1758 A.1. Unresolved Issues 1760 NT1 - Support multiple create-subscriptions over a single NETCONF 1761 session? or only multiple establish-subscription? Recommend only 1762 establish-subscription anytime there may be more than one 1763 subscription, otherwise variations of supported RFCs and error states 1764 proliferate. 1766 NT2 - Configured subscription need to be refined in 1767 [event-notifications] and then adjust this document based on it. 1769 NT3 - Express filter in JSON should be documented. 1771 A.2. Agreement in principal 1773 NT1 - When a list of requirements for secure transport is provided 1774 via a Configured Subscription, this list must be met via Netconf 1775 transport. Specifics still are needed for draft on the "how". 1777 NT2 - Along with rfc5277bis, this draft to obsolete 5277 1779 NT3 - Stream discovery. Adopted mechanism in 5277-bis and include 1780 backwards comptability support. 1782 Authors' Addresses 1784 Alberto Gonzalez Prieto 1785 Cisco Systems 1787 Email: albertgo@cisco.com 1789 Alexander Clemm 1790 Cisco Systems 1792 Email: alex@cisco.com 1794 Eric Voit 1795 Cisco Systems 1797 Email: evoit@cisco.com 1799 Einar Nilsen-Nygaard 1800 Cisco Systems 1802 Email: einarnn@cisco.com 1804 Ambika Prasad Tripathy 1805 Cisco Systems 1807 Email: ambtripa@cisco.com 1809 Sharon Chisholm 1810 Ciena 1812 Email: schishol@ciena.com 1814 Hector Trevino 1815 Cisco Systems 1817 Email: htrevino@cisco.com