idnits 2.17.1 draft-voit-netconf-notification-messages-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.) 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 (July 2, 2017) is 2489 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: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF E. Voit 3 Internet-Draft Cisco Systems 4 Intended status: Standards Track A. Bierman 5 Expires: January 3, 2018 YumaWorks 6 A. Clemm 7 Huawei 8 T. Jenkins 9 Cisco Systems 10 July 2, 2017 12 Notification Message Headers and Bundles 13 draft-voit-netconf-notification-messages-01 15 Abstract 17 This document specifies transport independent capabilities for 18 messages transporting event notifications and YANG datastore update 19 records. Included are: 21 o a set of transport agnostic message header objects, and 23 o how to associate a subset of these header objects with one or more 24 events, YANG datastore updates, and/or alarms. 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on January 3, 2018. 43 Copyright Notice 45 Copyright (c) 2017 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 3. Header Objects . . . . . . . . . . . . . . . . . . . . . . . 3 63 4. Transport independent headers for notifications . . . . . . . 4 64 5. Bundled Notifications . . . . . . . . . . . . . . . . . . . . 6 65 6. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 7 66 7. Security Considerations . . . . . . . . . . . . . . . . . . . 13 67 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 68 8.1. Normative References . . . . . . . . . . . . . . . . . . 13 69 8.2. Informative References . . . . . . . . . . . . . . . . . 13 70 Appendix A. Issues being worked . . . . . . . . . . . . . . . . 14 71 Appendix B. Querying an Object Model . . . . . . . . . . . . . . 14 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 74 1. Introduction 76 Mechanisms to support subscription to event notifications and yang 77 datastore push are being defined in [subscribe] and [yang-push]. 78 Work on those documents have shown that existing YANG notifications 79 described in [RFC7950] section 7.16 do not expose some useful 80 transport independent capabilities that application developers are 81 requesting. Communicating information on the following objects 82 should not require knowledge of the underlying transport: 84 o the kind of information encapsulated (event, data objects, alarm?) 86 o the time information was generated 88 o the time the information was sent 90 o a signature to verify authenticity 92 o the process generating the information 94 o an originating request correlation 95 o an ability to bundle information records together in a message 97 o the ability to check for message loss/reordering 99 The document describes information elements needed for the functions 100 above. It also provides YANG Notifications for sending messages 101 containing bone or more events and/or update records to a receiver. 103 2. Terminology 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 107 document are to be interpreted as described in RFC 2119 [RFC2119]. 109 Definitions of Notification, Event, Event Notification, Receiver, and 110 Subscription are defined in [subscribe]. 112 3. Header Objects 114 There are a number of transport independent headers which should have 115 common definition across applications. These include: 117 o record-type: defines the kind of information assembled as a unit. 118 (E.g., is it a YANG datastore update, an alarm, an event, etc.) 120 o subscription-id: provides a reference into the reason the 121 originator believed the receiver wishes to be notified of this 122 specific information. 124 o record-time: the time an event, datastore update, or other item it 125 itself is recognized in the originating system. 127 o record-id: identifies an event notification on an originator. 129 o observation-domain-id: identifies the originator process which 130 discovered and recorded the event notification. (note: look to 131 reuse the domains set up with IPFIX.) 133 o notification-time: the time the message was packaged sent to the 134 transport layer for delivery to the receiver. 136 o signature: allows an application to sign a message so that a 137 receiver can verify the authenticity of the message. 139 o dscp: network qos encoding which an application suggests should be 140 applied to the message. 142 o notification-id: for a specific message generator, this identifies 143 a message which includes one or more event records. 145 o previous-notification-id: the notification-id of the message 146 preceding the current one intended for the same receiver. When 147 used in conjunction with the current notification-id, this allows 148 loss/duplication across previous messages to be discovered. If 149 there was no previous message from a message generator, the 150 reserved id "0" must be sent. 152 o message-generator-id: identifier for the process which created the 153 message notification. This allows disambiguation of an 154 information source, such as the identification of different line 155 cards sending the notification messages. Used in conjunction with 156 previous-notification-id, this can help find drops and 157 duplications when notifications are coming from multiple sources 158 on a device. If there is a message-generator-id in the header, 159 then the previous-notification-id should be the notification-id 160 from the last time that message-generator-id was sent. 162 4. Transport independent headers for notifications 164 Many objects may be placed within a notification. However only a 165 certain subset these objects are of potential use to networking 166 layers prior the notification being interpreted by some receiving 167 application layer process. By exposing this object information as 168 part of a header, and by using standardized object names, it becomes 169 possible for this object information to be leveraged in transit. 171 The objects defined in the previous section effectively become well- 172 known objects where, if in the header, may act as supplemental 173 information in communications between two devices. These well-known 174 header fields are encapsulated within a dedicated subtree which leads 175 off the notification message. This allows header objects to be 176 easily be decoupled, stripped, and processed separately. 178 Typically sequence of information in YANG models is irrelevant. But 179 as part of a transported notification, It is useful to sequence these 180 header objects so that processing is as efficient as possible. This 181 allows the handling or discarding of uninteresting notifications 182 quickly. 184 Below is are record objects contents would include the objects 185 presented in the section above. The proper way this message would be 186 generated would be to look for the well known object names and place 187 them in the header. All other would be placed in the notification 188 record contents. (Note: are there any of these we should rather 189 duplicate than move?) 190 +---n notification-message 191 +--ro notification-message-header 192 | +--ro record-time yang:date-and-time 193 | +--ro record-type? notification-record-format 194 | +--ro subscription-id* uint32 195 | +--ro record-id? uint32 196 | +--ro observation-domain-id? string 197 | +--ro notification-id? uint32 198 | +--ro notification-time? yang:date-and-time 199 | +--ro previous-notification-id? uint32 200 | +--ro dscp? inet:dscp 201 | +--ro message-generator-id? string 202 | +--ro signature? string 203 +--ro receiver-record-contents? 205 An actual instance of a notification might look like: 207 209 210 211 2017-02-14T00:00:02Z 212 213 214 yang-patch 215 216 217 823472 218 219 220 2017-02-14T00:00:05Z 221 222 223 456 224 225 226 567 227 228 229 lKIo8s03fd23..... 230 231 232 233 ...(yang patch here)... 234 235 237 5. Bundled Notifications 239 In many implementations, it may be inefficient to transport every 240 notification independently. Instead, scale and processing speed can 241 be improved by placing multiple notifications into one transportable 242 bundle. 244 When this is done, one additional header field becomes valuable. 245 This is the "record-count" which would tally the quantity of records 246 which make up the contents of the bundle. 248 The format of a bundle would look as below. When compared to the 249 unbundled notification, note that the headers have been split so that 250 one set of headers associated with the notification occur once at the 251 beginning of the message, and additional record specific headers 252 which occur before individual records. 254 +---n bundled-notification-message 255 +--ro bundled-notification-message-header 256 | +--ro notification-id? uint32 257 | +--ro notification-time yang:date-and-time 258 | +--ro previous-notification-id? uint32 259 | +--ro dscp? inet:dscp 260 | +--ro message-generator-id? string 261 | +--ro signature? string 262 | +--ro record-count? uint16 263 +--ro notification-records* 264 +--ro notification-record-header 265 | +--ro record-time yang:date-and-time 266 | +--ro record-type? notification-record-format 267 | +--ro subscription-id* uint32 268 | +--ro record-id? uint32 269 | +--ro observation-domain-id? string 270 +--ro receiver-record-contents? 272 An actual instance of a bundled notification might look like: 274 276 277 278 2017-02-14T00:00:05Z 279 280 281 456 282 283 284 567 285 286 287 lKIo8s03fd23... 288 289 290 2 291 292 293 294 295 296 2017-02-14T00:00:02Z 297 298 299 yang-patch 300 301 302 823472 303 304 305 307 308 ...(yang patch here)... 309 310 311 312 313 ...(record #2)... 314 315 317 6. Data Model 319 file "ietf-notification-messages.yang" 320 module ietf-notification-messages { 321 yang-version 1.1; 322 namespace "urn:ietf:params:xml:ns:yang:ietf-notification-messages"; 323 prefix nm; 325 import ietf-yang-types { 326 prefix yang; 327 } 328 import ietf-inet-types { 329 prefix inet; 330 } 332 organization "IETF"; 333 contact 334 "WG Web: 335 WG List: 337 WG Chair: Mahesh Jethanandani 338 340 WG Chair: Mehmet Ersue 341 343 Editor: Eric Voit 344 346 Editor: Alexander Clemm 347 349 Editor: Tim Jenkins 350 352 Editor: Andy Bierman 353 "; 355 description 356 "This module contains conceptual YANG specifications for 357 notification messages with well known header objects."; 359 revision 2017-04-25 { 360 description 361 "This module includes definitions for two new yang 362 notification message objects: 363 (a) a message format including the definitions for common header 364 information prior to notification payload. 365 (b) a message format allowing the bundling of multiple 366 notifications within it"; 368 reference 369 "draft-voit-netconf-notification-messages-01"; 370 } 372 /* 373 * IDENTITIES 374 */ 376 /* Identities for notification record types */ 378 identity notification-record-format { 379 description 380 "Base identity to represent a different formats for notification 381 records."; 382 } 384 identity system-event { 385 base notification-record-format; 386 description 387 "System XML event"; 388 } 390 identity yang-datastore { 391 base notification-record-format; 392 description 393 "yang data node / tree extract"; 394 } 396 identity yang-patch { 397 base notification-record-format; 398 description 399 "yang patch record"; 400 } 402 identity syslog-entry { 403 base notification-record-format; 404 description 405 "Unstructured syslog entry."; 406 } 408 identity alarm { 409 base notification-record-format; 410 description 411 "Alarm (perhaps link draft-sharma-netmod-fault-model-01 for more 412 info)"; 413 } 415 /* 416 * TYPEDEFs 417 */ 419 typedef notification-record-format { 420 type identityref { 421 base notification-record-format; 422 } 423 description 424 "Type of notification record"; 425 } 427 /* 428 * GROUPINGS 429 */ 431 grouping notification-message-header { 432 description 433 "Header information included with a notification."; 434 leaf notification-id { 435 type uint32; 436 description 437 "unique id for a notification which may go to one or many 438 receivers."; 439 } 440 leaf notification-time { 441 type yang:date-and-time; 442 description 443 "time the notification was generated prior to being sent to 444 transport."; 445 } 446 leaf previous-notification-id { 447 type uint32; 448 description 449 "Notification id previously sent by publisher to a specific 450 receiver (allows detection of loss/duplication)."; 451 } 452 leaf dscp { 453 type inet:dscp; 454 default "0"; 455 description 456 "The push update's IP packet transport priority. This is made 457 visible across network hops to receiver. The transport 458 priority is shared for all receivers of a given 459 subscription."; 460 } 461 leaf message-generator-id { 462 type string; 463 description 464 "Software entity which created the notification message (e.g., 465 linecard 1)."; 466 } 467 leaf signature { 468 type string; 469 description 470 "Any originator signing of the contents of a notification 471 message. This can be useful for originating applications to 472 verify record contents even when shipping over unsecure 473 transport."; 474 } 475 } 477 grouping notification-record-header { 478 description 479 "Common informational objects which might help a receiver 480 interpret the meaning, details, and importance of an event 481 notification."; 482 leaf record-time { 483 type yang:date-and-time; 484 mandatory true; 485 description 486 "Time the system recognized the occurrence of an event."; 487 } 488 leaf record-type { 489 type notification-record-format; 490 description 491 "Describes the type of payload included. This is turn allow 492 the interpretation of the record contents."; 493 } 494 leaf-list subscription-id { 495 type uint32; 496 description 497 "Id of the subscription which led to the notification being 498 generated."; 499 } 500 leaf record-id { 501 type uint32; 502 description 503 "Identifier for the notification record."; 504 } 505 leaf observation-domain-id { 506 type string; 507 description 508 "Software entity which created the notification record (e.g., 509 process id)."; 510 } 511 } 512 /* 513 * NOTIFICATIONS 514 */ 516 notification notification-message { 517 description 518 "Notification message to a receiver containing only one event."; 519 container notification-message-header { 520 description 521 "delineates header info from notification messages for easy 522 parsing."; 523 uses notification-record-header; 524 uses notification-message-header; 525 } 526 anydata receiver-record-contents { 527 description 528 "Non-header info of what actually got sent to receiver after 529 security filter. (Note: Possible to have extra process 530 encryption.)"; 531 } 532 } 534 notification bundled-notification-message { 535 description 536 "Notification message to a receiver containing many events, 537 possibly relating to independent subscriptions."; 538 container bundled-notification-message-header { 539 description 540 "Delineates header info from notification messages for easy 541 parsing."; 542 uses notification-message-header { 543 refine notification-time { 544 mandatory true; 545 } 546 } 547 leaf record-count { 548 type uint16; 549 description 550 "Quantity of events in a bundled-notification-message 551 for a specific receiver. This value is per receiver in 552 case an entire notification record is filtered out."; 553 } 554 } 555 list notification-records { 556 description 557 "Set of messages within a notification to a receiver."; 558 container notification-record-header { 559 description 560 "delineates header info from notification messages for easy 561 parsing."; 562 uses notification-record-header; 563 } 564 anydata receiver-record-contents { 565 description 566 "Non-header info of what actually got sent to receiver after 567 security filter. (Note: Possible to have extra process 568 encryption.)"; 570 } 571 } 572 } 573 } 574 576 7. Security Considerations 578 More needs to be thought through here, as this adds additional 579 information onto notifications, the security implications shouldn't 580 be singificantly beyond those from [subscribe] other than ensuring 581 that data plane devices can accomplish the necessary content 582 filtering despite the potential of a new level of header being 583 applied. 585 8. References 587 8.1. Normative References 589 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 590 Requirement Levels", BCP 14, RFC 2119, 591 DOI 10.17487/RFC2119, March 1997, 592 . 594 [subscribe] 595 Voit, E., Clemm, A., Gonzalez Prieto, A., Prasad Tripathy, 596 A., and E. Nilsen-Nygaard, "Custom Subscription to Event 597 Notifications", April 2017, 598 . 601 8.2. Informative References 603 [initial-version] 604 Voit, E., Bierman, A., Clemm, A., and T. Jenkins, "Custom 605 Subscription to Event Notifications", February 2017, 606 . 609 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 610 RFC 7950, DOI 10.17487/RFC7950, August 2016, 611 . 613 [yang-push] 614 Clemm, A., Voit, E., Gonzalez Prieto, A., Prasad Tripathy, 615 A., and E. Nilsen-Nygaard, "Subscribing to YANG datastore 616 push updates", April 2017, 617 . 620 Appendix A. Issues being worked 622 (To be removed by RFC editor prior to publication) 624 We need to define the ways to invoke and configure the capability 625 within an originating device. This includes defining what header 626 types are selected. This also includes knowning the header types 627 which can be supported by a receiver. 629 We need to do a lot more to discuss transport efficiency 630 implications. 632 Relationship with DTN protocols. 634 Appendix B. Querying an Object Model 636 (This appendix was in a previous iteration of this draft. It has 637 been removed as unlikely to be seen in an implementation. It is 638 being kept in for discussion purposes.) 640 It is also possible that that external entities might want to query 641 message information after it has been sent. And therefore it is 642 possible that an administrator would like to examine the contents of 643 notifications via random access using a YANG model rather that 644 Syslog. There could be several values in such random access. These 645 include: 647 o ability for applications to determine what message bundles were 648 used to transport specific records. 650 o ability for applications to check which receivers have been sent 651 an event notification. 653 o ability for applications to determine the time delta between event 654 identification and transport. 656 o ability to reconstruct message passing during troubleshooting. 658 o ability to extract messages and records to evaluate whether the 659 security filters have been properly applied. 661 o ability to compare the payloads of the same notification message 662 sent to different receivers (again to evaluate the impact of the 663 security filtering). 665 If such random access is needed, it is possible to extend the YANG 666 model data model document to enable random access to the information. 667 A cut at what this might look like can be seen in [initial-version] 669 Authors' Addresses 671 Eric Voit 672 Cisco Systems 674 Email: evoit@cisco.com 676 Andy Bierman 677 YumaWorks 679 Email: andy@yumaworks.com 681 Alexander Clemm 682 Huawei 684 Email: ludwig@clemm.org 686 Tim Jenkins 687 Cisco Systems 689 Email: timjenki@cisco.com