idnits 2.17.1 draft-voit-netmod-yang-notifications2-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.) ** The abstract seems to contain references ([RFC7950]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (February 21, 2017) is 2622 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETMOD E. Voit 3 Internet-Draft Cisco Systems 4 Intended status: Standards Track A. Bierman 5 Expires: August 25, 2017 YumaWorks 6 A. Clemm 7 Huawei 8 T. Jenkins 9 Cisco Systems 10 February 21, 2017 12 YANG Notification Headers and Bundles 13 draft-voit-netmod-yang-notifications2-00 15 Abstract 17 There are useful capabilities not available with existing YANG 18 notifications as described in Section 7.16 of [RFC7950]. These 19 include: 21 1. what are the set of transport agnostic header objects which might 22 be usefully placed within YANG notifications. 24 2. how might a set of YANG notifications be bundled into a single 25 transport message. 27 3. how do you query the originator of a notification to troubleshoot 28 the bundling process 30 This specification provides technologies enabling these three 31 capabilities. 33 Status of This Memo 35 This Internet-Draft is submitted in full conformance with the 36 provisions of BCP 78 and BCP 79. 38 Internet-Drafts are working documents of the Internet Engineering 39 Task Force (IETF). Note that other groups may also distribute 40 working documents as Internet-Drafts. The list of current Internet- 41 Drafts is at http://datatracker.ietf.org/drafts/current/. 43 Internet-Drafts are draft documents valid for a maximum of six months 44 and may be updated, replaced, or obsoleted by other documents at any 45 time. It is inappropriate to use Internet-Drafts as reference 46 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on August 25, 2017. 50 Copyright Notice 52 Copyright (c) 2017 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. Code Components extracted from this document must 61 include Simplified BSD License text as described in Section 4.e of 62 the Trust Legal Provisions and are provided without warranty as 63 described in the Simplified BSD License. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 68 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 69 3. Header Objects . . . . . . . . . . . . . . . . . . . . . . . 3 70 4. Headers added to an RFC7950 Notification . . . . . . . . . . 4 71 5. Bundled Notifications . . . . . . . . . . . . . . . . . . . . 5 72 6. Querying an Object Model . . . . . . . . . . . . . . . . . . 7 73 7. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 9 74 8. Security Considerations . . . . . . . . . . . . . . . . . . . 19 75 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 20 76 9.1. Normative References . . . . . . . . . . . . . . . . . . 20 77 9.2. Informative References . . . . . . . . . . . . . . . . . 20 78 Appendix A. Issues being worked . . . . . . . . . . . . . . . . 20 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 81 1. Introduction 83 Mechanisms to support subscription to event notifications and yang 84 datastore push are being defined in [sn] and [yang-push]. Work on 85 those documents has shown that additional capabilities in YANG 86 notifications would be helpful. Three of these capabilities include: 88 1. what are the set of transport agnostic header objects which might 89 be usefully placed within YANG notifications. 91 2. how might a set of YANG notifications be bundled into a single 92 transport message. 94 3. how do you query the originator of a notification to troubleshoot 95 the bundling process. 97 As none of these three capabilities are specific to subscriptions, it 98 would be good to define them in a transport protocol agnostic way. 100 2. Terminology 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 104 document are to be interpreted as described in RFC 2119 [RFC2119]. 106 Definitions of Notification, Event, Event Notification, Publisher, 107 Receiver, and Subscription are defined in [sn]. 109 3. Header Objects 111 There are a number of transport independent headers which should have 112 common definition across applications. These include: 114 o record-type: what kind of information and have been assembled as 115 part of this notification. (E.g., is it a YANG datastore update, 116 an alarm, a syslog message, etc.) 118 o subscription-id: provides a reference into the reason the 119 originator believed the receiver wishes to be notified of this 120 specific information. 122 o record-severity: how important the originator feels this message 123 to be. 125 o record-time: the time an event notification itself was recorded in 126 the originating system. 128 o record-id: identifies an event notification on an originator. 130 o observation-domain-id: identifies the originator process which 131 discovered and recorded the event notification. (note: look to 132 reuse the domains set up with IPFIX.) 134 o notification-time: the time the message was packaged sent to the 135 transport layer for delivery to the receiver. 137 o signature: allows an application to sign a message so that a 138 receiver can verify the authenticity of the message. 140 o notification-id: identifies a message which includes one or more 141 event records. 143 o previous-notification-id: the Notification id previously sent to a 144 receiver. When used in conjunction with notification-id, this 145 allow loss/duplication across previous messages to be discovered. 147 o message-generator-id: process which created the message 148 notification. Allows identification of different line cards 149 sending the notification messages. Used in conjunction with 150 previous-notification-id, can help find drops and duplication when 151 notifications are coming from multiple sources on a device. The 152 logic is simple: if there is a message-generator-id in the header, 153 then the previous-notification-id should been the notification-id 154 the last time the message-generator-id was sent. 156 4. Headers added to an RFC7950 Notification 158 With the headers defined, they may now be applied to extend an 159 RFC-7950 notification. This section provides examples of this. 161 The first thing which is done is to encapsulate these header fields 162 within their own subtree in the notification message so that these 163 objects can easily be decoupled, processed, and removed from any 164 notification record payload. 166 It is useful to sequence these objects so that processing by the 167 receiver is as efficient as possible, allowing the discarding of 168 uninteresting notifications as quickly as possible. One record 169 priority encoding would include the objects presented in the sequence 170 above to help minimize event record processing CPU cycles. (Need to 171 add more here, and acknowledge that different payloads and systems 172 might benefit from alternative sequencing.) 174 +---n notification-message 175 +--ro notification-message-header 176 | +--ro record-time 177 | +--ro record-type? 178 | +--ro record-id? 179 | +--ro record-severity? 180 | +--ro observation-domain-id? 181 | +--ro subscription-id? 182 | +--ro notification-time? 183 | +--ro notification-id? 184 | +--ro previous-notification-id? 185 | +--ro signature? 186 | +--ro message-generator-id? 187 +--ro receiver-record-contents? 189 An actual instance of a notification might look like: 191 193 194 195 2017-02-14T00:00:02Z 196 197 198 yang-patch 199 200 201 823472 202 203 204 2017-02-14T00:00:05Z 205 206 207 456 208 209 210 567 211 212 213 lKIo8s03fd23..... 214 215 216 217 ...(yang patch here)... 218 219 221 5. Bundled Notifications 223 In many implementations, it may be inefficient to transport every 224 notification independently. Instead, scale and processing speed can 225 be improved by placing multiple notifications into one transportable 226 bundle. 228 When this is done, one additional of a header field becomes valuable. 229 This is the "record-count" which would tally the quantity of records 230 which make up the contents of the bundle. 232 The format of a bundle would look as below. When compared to the 233 unbundled notification, note that the headers have been split so that 234 one set of headers associated with the notification occur once at the 235 beginning of the message, and additional record specific headers 236 which occur before individual records. 238 +---n bundled-notification-message 239 +--ro notification-message-header 240 | +--ro notification-time 241 | +--ro notification-id? 242 | +--ro previous-notification-id? 243 | +--ro signature? 244 | +--ro message-generator-id? 245 | +--ro record-count? 246 +--ro notification-records* 247 +--ro notification-record-header 248 | +--ro record-time 249 | +--ro record-type? 250 | +--ro record-id? 251 | +--ro record-severity? 252 | +--ro observation-domain-id? 253 | +--ro subscription-id? 254 +--ro receiver-record-contents? 256 An actual instance of a bundled notification might look like: 258 260 261 262 2017-02-14T00:00:05Z 263 264 265 456 266 267 268 567 269 270 271 lKIo8s03fd23... 272 273 274 2 275 276 277 278 279 280 2017-02-14T00:00:02Z 281 282 283 yang-patch 284 285 286 823472 287 288 289 291 292 ...(yang patch here)... 293 294 295 296 297 ...(record #2)... 298 299 301 6. Querying an Object Model 303 It is possible that an administrator would like to examine the 304 contents of notifications via random access using a YANG model. 305 There could be several values in such random access. These include: 307 o ability for applications to determine what message bundles were 308 used to transport specific records. 310 o ability for applications to check which receivers have been sent 311 an event notification. 313 o ability for applications to determine the time delta between event 314 identification and transport. 316 o ability to reconstruct message passing during troubleshooting. 318 o ability to extract messages and records to evaluate whether the 319 security filters have been properly applied. 321 o ability to compare the payloads of the same notification message 322 sent to different receivers (again to evaluate the impact of the 323 security filtering). 325 If such random access is needed, the YANG model structure below would 326 enable random access to the information. 328 +--ro notification-records 329 | +--ro notification-record* [record-id] 330 | +--ro record-time yang:date-and-time 331 | +--ro record-type notification-record-format-type 332 | +--ro record-id uint32 333 | +--ro record-severity? string 334 | +--ro observation-domain-id? string 335 | +--ro notification-record-contents 336 | +--ro subscription-id* subscription-ref 337 +--ro notification-messages 338 | +--ro notification-message* [notification-id] 339 | +--ro notification-id uint32 340 | +--ro signature? string 341 | +--ro message-generator-id? string 342 | +--ro notification-record notification-record-ref 343 | +--ro receiver-notification-messages 344 | +--ro receiver-notification-message* 345 | +--ro receiver? receiver-ref 346 | +--ro notification-time yang:date-and-time 347 | +--ro previous-notification-id? uint32 348 | +--ro receiver-record-contents 349 +--ro bundled-notification-messages 350 +--ro bundled-notification-message* [notification-id] 351 +--ro notification-id uint32 352 +--ro signature? string 353 +--ro message-generator-id? string 354 +--ro included-notification-records 355 | +--ro included-notification-record* 356 | +--ro notification-record? notification-record-ref 357 +--ro receiver-notification-messages 358 +--ro receiver-notification-message* 359 +--ro receiver? receiver-ref 360 +--ro notification-time yang:date-and-time 361 +--ro previous-notification-id? uint32 362 +--ro record-count? uint16 363 +--ro included-notification-records 364 +--ro notification-record* 365 +--ro receiver-record-contents 367 If such random access is not seen as needed, the model above should 368 be discarded. This will also simplify the YANG model is the 369 following section. 371 7. Data Model 373 file "ietf-yang-notifications2.yang" 374 module ietf-yang-notifications2 { 375 yang-version 1.1; 376 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-notifications2"; 377 prefix yn2; 379 import ietf-yang-types { 380 prefix yang; 381 } 382 import ietf-subscribed-notifications { 383 prefix sn; 384 } 386 organization "IETF"; 387 contact 388 "WG Web: 389 WG List: 391 WG Chair: Lou Berger 392 394 WG Chair: Kent Watsen 395 397 Editor: Eric Voit 398 400 Editor: Alexander Clemm 401 403 Editor: Tim Jenkins 404 406 Editor: Andy Bierman 407 "; 409 description 410 "This module contains conceptual YANG specifications for NETCONF 411 Event Notifications."; 413 revision 2017-02-23 { 414 description 415 "This module includes several definitions for two new yang 416 notification message formats: 417 (a) a message format including the definitions for common header 418 information prior to notification payload. 419 (b) a message format allowing the bundling of multiple 420 notifications within it 422 It also includes data nodes for querying related information such 423 as: 424 - ability to see contents of notifications both before and 425 after any NACM filtering has been applied. 426 - ability to see which message numbers have been sent to which 427 receivers."; 429 reference 430 "draft-voit-netmod-yang-notifications2-00"; 431 } 433 /* 434 * IDENTITIES 435 */ 437 /* Identities for notification record types */ 439 identity notification-record-format { 440 description 441 "Base identity to represent a different formats for notification 442 records."; 443 } 445 identity system-event { 446 base notification-record-format; 447 description 448 "System XML event"; 449 } 451 identity yang-datastore { 452 base notification-record-format; 453 description 454 "yang tree info"; 455 } 457 identity yang-patch { 458 base notification-record-format; 459 description 460 "yang patch record"; 461 } 463 identity syslog-entry { 464 base notification-record-format; 465 description 466 "Entry into syslog (figure linkage to existing draft."; 467 } 469 identity alarm { 470 base notification-record-format; 471 description 472 "Alarm (perhaps link draft-sharma-netmod-fault-model-01 for more 473 info)"; 474 } 476 /* 477 * TYPEDEFs 478 */ 480 typedef notification-record-ref { 481 type leafref { 482 path "/notification-records/notification-record/record-id"; 483 } 484 description 485 "This type is used to reference a notification record (a.k.a., 486 event)."; 487 } 489 typedef receiver-ref { 490 type leafref { 491 path "/sn:subscriptions/sn:subscription/sn:receivers/"+ 492 "sn:receiver/sn:address"; 493 } 494 description 495 "This type is used to reference a receiver."; 496 } 498 typedef subscription-ref { 499 type leafref { 500 path "/sn:subscriptions/sn:subscription/sn:identifier"; 501 } 502 description 503 "This type is used to reference a receiver."; 504 } 506 typedef notification-record-format-type { 507 type identityref { 508 base notification-record-format; 509 } 510 description 511 "Type of notification record"; 512 } 514 /* 515 * GROUPINGS 516 */ 518 grouping notification-message-header { 519 description 520 "Header information included with a notification."; 521 leaf notification-id { 522 type uint32; 523 description 524 "unique id for a notification which may go to one or many 525 receivers."; 526 } 527 leaf signature { 528 type string; 529 description 530 "Any originator signing of the contents of a notification 531 message. This can be useful for originating applications to 532 verify record contents even when shipping over unsecure 533 transport."; 534 } 535 leaf message-generator-id { 536 type string; 537 description 538 "Software entity which created the notification message (e.g., 539 linecard 1)."; 540 } 541 } 543 grouping notification-message-receiver-header { 544 description 545 "Header information included with a notification which is 546 specific to a receiver."; 547 leaf notification-time { 548 type yang:date-and-time; 549 description 550 "time the notification was generated prior to being sent to 551 transport."; 552 } 553 leaf previous-notification-id { 554 type uint32; 555 description 556 "Notification id previously sent by publisher to a specific 557 receiver (allows detection of loss/duplication)."; 558 } 559 } 561 grouping notification-record-header { 562 description 563 "Common informational objects which might help a receiver 564 interpret the meaning, details, and importance of an event 565 notification."; 566 leaf record-time { 567 type yang:date-and-time; 568 mandatory true; 569 description 570 "Time the system recognized the occurence of an event."; 571 } 572 leaf record-type { 573 type notification-record-format-type; 574 description 575 "Describes the type of payload included. This is turn allow 576 the interpretation of the record contents."; 577 } 578 leaf record-id { 579 type uint32; 580 description 581 "Identifier for the notification record."; 582 } 583 leaf record-severity { 584 type string; 585 description 586 "System assigned severity. (Likely we need to build/find an 587 enumeration of common ones.)"; 588 } 589 leaf observation-domain-id { 590 type string; 591 description 592 "Software entity which created the notification record (e.g., 593 process id)."; 594 } 595 } 597 grouping subscribed-notification-record-header { 598 description 599 "Header information included with a notification."; 600 uses notification-record-header; 601 leaf subscription-id { 602 type uint32; 603 description 604 "Id of the subscription which led to the notification being 605 generated."; 606 } 607 } 609 /* 610 * NOTIFICATIONS 611 */ 613 notification notification-message { 614 description 615 "Notification message to a receiver containing only one event."; 616 container notification-message-header { 617 description 618 "delineates header info from notification messages for easy 619 parsing."; 620 uses subscribed-notification-record-header; 621 uses notification-message-header; 622 uses notification-message-receiver-header; 623 } 624 anydata receiver-record-contents { 625 description 626 "Non-header info of what actually got sent to receiver after 627 security filter. (Note: Possible to have extra process 628 encryption.)"; 629 } 630 } 632 notification bundled-notification-message { 633 description 634 "Notification message to a receiver containing many events, 635 possibly relating to independent subscriptions."; 636 container bundled-notification-message-header { 637 description 638 "Delineates header info from notification messages for easy 639 parsing."; 640 uses notification-message-header; 641 uses notification-message-receiver-header { 642 refine notification-time { 643 mandatory true; 644 } 645 } 646 leaf record-count { 647 type uint16; 648 description 649 "Quantity of events in a bundled-notification-message 650 for a specific receiver. This value is per receiver in 651 case an entire notification record is filtered out."; 652 } 653 } 655 list notification-records { 656 description 657 "Set of messages within a notification to a receiver."; 658 container notification-record-header { 659 description 660 "delineates header info from notification messages for easy 661 parsing."; 662 uses subscribed-notification-record-header; 664 } 665 anydata receiver-record-contents { 666 description 667 "Non-header info of what actually got sent to receiver after 668 security filter. (Note: Possible to have extra process 669 encryption.)"; 671 } 672 } 673 } 675 /* 676 * DATA NODES 677 */ 679 container notification-records { 680 config false; 681 description 682 "Maintains instances of event notifications recorded by the 683 system."; 684 list notification-record { 685 key "record-id"; 686 description 687 "Specific instances of event notifications recorded by the 688 system."; 689 uses notification-record-header { 690 refine record-id { 691 mandatory true; 692 } 693 refine record-type { 694 mandatory true; 695 } 696 } 697 anydata notification-record-contents { 698 mandatory true; 699 description 700 "Notification event contents independent of any receiver 701 security filtering."; 702 } 703 leaf-list subscription-id { 704 type subscription-ref; 705 description 706 "Instances of subscriptions which should receive or have 707 received this event notification record."; 708 } 709 } 710 } 711 container notification-messages { 712 config false; 713 description 714 "Contains a history of the notification messages which have been 715 generated."; 716 list notification-message { 717 key "notification-id"; 718 description 719 "Instances of notification messages generated with the intent 720 of sending them to one or more receivers."; 721 uses notification-message-header { 722 refine notification-id { 723 mandatory true; 724 } 725 } 726 leaf notification-record { 727 type notification-record-ref; 728 mandatory true; 729 description 730 "Included notification. The record itself, or elements of 731 this record might not be sent to any included receiver based 732 on security permissions for that receiver."; 733 } 734 container receiver-notification-messages { 735 description 736 "Contains a history of messages targeted for a receiver."; 737 list receiver-notification-message { 738 description 739 "Maintains instances of messages targeted for a receiver."; 740 leaf receiver { 741 type receiver-ref; 742 description 743 "Reference to the recipient targeted for this 744 notification message. (This also allows the unique 745 identification of the subscription.)"; 746 } 747 uses notification-message-receiver-header { 748 refine notification-time { 749 mandatory true; 750 } 751 } 752 anydata receiver-record-contents { 753 mandatory true; 754 description 755 "The specific security filtered contents of one record 756 going to a receiver."; 757 } 758 } 759 } 761 } 762 } 763 container bundled-notification-messages { 764 config false; 765 description 766 "Contains a history of bundled notification messages which have 767 been generated."; 768 list bundled-notification-message { 769 key "notification-id"; 770 min-elements 1; 771 description 772 "Maintains instances of a bundled notification messages 773 generated with the intent of sending them to one or more 774 receivers."; 775 uses notification-message-header{ 776 refine notification-id { 777 mandatory true; 778 } 779 } 780 container included-notification-records { 781 description 782 "Contains specific records included in the bundle."; 783 list included-notification-record { 784 description 785 "A specific instance of record included in a bundle."; 786 leaf notification-record { 787 type notification-record-ref; 788 description 789 "Included notification within the bundle. Full records 790 or elements of this record might not be sent to any 791 included receiver based on security permissions for that 792 receiver."; 793 } 794 } 795 } 796 container receiver-notification-messages { 797 description 798 "Contains instances of messages generated for a specific 799 receiver."; 800 list receiver-notification-message { 801 description 802 "Maintains instances of bundled messages targeted for a 803 receiver."; 804 leaf receiver { 805 type receiver-ref; 806 description 807 "Reference to the recipient targeted for this bundled 808 notification message. (As a receiver is unique to a 809 subscription, this also identifies the subscription 810 explicitly. If something other than receiver is used, a 811 method to identify the subscription is also needed as it 812 can't automatically be derived from the notification 813 record."; 814 } 815 uses notification-message-receiver-header { 816 refine notification-time { 817 mandatory true; 818 } 819 } 820 leaf record-count { 821 type uint16; 822 description 823 "Number of records actually sent to a receiver after 824 considering the application of NACM policies on the 825 notification records."; 826 } 827 container included-notification-records { 828 description 829 "Contains the records sent to a receiver within a 830 specific notification message."; 831 list notification-record { 832 description 833 "Maintains instances of records sent to a receiver."; 834 anydata receiver-record-contents { 835 mandatory true; 836 description 837 "The specific security filtered contents of one 838 record going to a receiver."; 839 } 840 } 841 } 842 } 843 } 844 } 845 } 846 } 847 849 8. Security Considerations 851 to be populated 853 9. References 855 9.1. Normative References 857 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 858 Requirement Levels", BCP 14, RFC 2119, 859 DOI 10.17487/RFC2119, March 1997, 860 . 862 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 863 RFC 7950, DOI 10.17487/RFC7950, August 2016, 864 . 866 9.2. Informative References 868 [sn] Voit, E., Clemm, A., Gonzalez Prieto, A., Prasad Tripathy, 869 A., and E. Nilsen-Nygaard, "Subscribing to Event 870 Notifications", February 2017, 871 . 874 [yang-push] 875 Clemm, A., Voit, E., Gonzalez Prieto, A., Prasad Tripathy, 876 A., and E. Nilsen-Nygaard, "Subscribing to YANG datastore 877 push updates", February 2017, 878 . 881 Appendix A. Issues being worked 883 (To be removed by RFC editor prior to publication) 885 We need to define the ways to invoke and configure the capability 886 within an originating device. This includes defining what header 887 types are selected. 889 Should we allow multiple subscriptions to be associated with an 890 update record via a leaf-list? 892 Should the subscription id in a notification actually be a leafref? 894 We need to do a lot more to discuss transport efficiency 895 implications. 897 Authors' Addresses 899 Eric Voit 900 Cisco Systems 902 Email: evoit@cisco.com 904 Andy Bierman 905 YumaWorks 907 Email: andy@yumaworks.com 909 Alexander Clemm 910 Huawei 912 Email: ludwig@clemm.org 914 Tim Jenkins 915 Cisco Systems 917 Email: timjenki@cisco.com