idnits 2.17.1 draft-voit-netconf-notification-messages-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.) 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 (April 25, 2017) is 2530 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: October 27, 2017 YumaWorks 6 A. Clemm 7 Huawei 8 T. Jenkins 9 Cisco Systems 10 April 25, 2017 12 Notification Message Headers and Bundles 13 draft-voit-netconf-notification-messages-00 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 October 27, 2017. 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. 150 o message-generator-id: identifier for the process which created the 151 message notification. This allows disambiguation of an 152 information source, such as the identification of different line 153 cards sending the notification messages. Used in conjunction with 154 previous-notification-id, this can help find drops and 155 duplications when notifications are coming from multiple sources 156 on a device. If there is a message-generator-id in the header, 157 then the previous-notification-id should be the notification-id 158 from the last time that message-generator-id was sent. 160 4. Transport independent headers for notifications 162 Many objects may be placed within a notification. However only a 163 certain subset these objects are of potential use to networking 164 layers prior the notification being interpreted by some receiving 165 application layer process. By exposing this object information as 166 part of a header, and by using standardized object names, it becomes 167 possible for this object information to be leveraged in transit. 169 The objects defined in the previous section effectively become well- 170 known objects where, if in the header, may act as supplemental 171 information in communications between two devices. These well-known 172 header fields are encapsulated within a dedicated subtree which leads 173 off the notification message. This allows header objects to be 174 easily be decoupled, stripped, and processed separately. 176 Typically sequence of information in YANG models is irrelevant. But 177 as part of a transported notification, It is useful to sequence these 178 header objects so that processing is as efficient as possible. This 179 allows the handling or discarding of uninteresting notifications 180 quickly. 182 Below is are record objects contents would include the objects 183 presented in the section above. The proper way this message would be 184 generated would be to look for the well known object names and place 185 them in the header. All other would be placed in the notification 186 record contents. (Note: are there any of these we should rather 187 duplicate than move?) 188 +---n notification-message 189 +--ro notification-message-header 190 | +--ro record-time yang:date-and-time 191 | +--ro record-type? notification-record-format 192 | +--ro subscription-id* uint32 193 | +--ro record-id? uint32 194 | +--ro observation-domain-id? string 195 | +--ro notification-id? uint32 196 | +--ro notification-time? yang:date-and-time 197 | +--ro previous-notification-id? uint32 198 | +--ro dscp? inet:dscp 199 | +--ro message-generator-id? string 200 | +--ro signature? string 201 +--ro receiver-record-contents? 203 An actual instance of a notification might look like: 205 207 208 209 2017-02-14T00:00:02Z 210 211 212 yang-patch 213 214 215 823472 216 217 218 2017-02-14T00:00:05Z 219 220 221 456 222 223 224 567 225 226 227 lKIo8s03fd23..... 228 229 230 231 ...(yang patch here)... 232 233 235 5. Bundled Notifications 237 In many implementations, it may be inefficient to transport every 238 notification independently. Instead, scale and processing speed can 239 be improved by placing multiple notifications into one transportable 240 bundle. 242 When this is done, one additional header field becomes valuable. 243 This is the "record-count" which would tally the quantity of records 244 which make up the contents of the bundle. 246 The format of a bundle would look as below. When compared to the 247 unbundled notification, note that the headers have been split so that 248 one set of headers associated with the notification occur once at the 249 beginning of the message, and additional record specific headers 250 which occur before individual records. 252 +---n bundled-notification-message 253 +--ro bundled-notification-message-header 254 | +--ro notification-id? uint32 255 | +--ro notification-time yang:date-and-time 256 | +--ro previous-notification-id? uint32 257 | +--ro dscp? inet:dscp 258 | +--ro message-generator-id? string 259 | +--ro signature? string 260 | +--ro record-count? uint16 261 +--ro notification-records* 262 +--ro notification-record-header 263 | +--ro record-time yang:date-and-time 264 | +--ro record-type? notification-record-format 265 | +--ro subscription-id* uint32 266 | +--ro record-id? uint32 267 | +--ro observation-domain-id? string 268 +--ro receiver-record-contents? 270 An actual instance of a bundled notification might look like: 272 274 275 276 2017-02-14T00:00:05Z 277 278 279 456 280 281 282 567 283 284 285 lKIo8s03fd23... 286 287 288 2 289 290 291 292 293 294 2017-02-14T00:00:02Z 295 296 297 yang-patch 298 299 300 823472 301 302 303 305 306 ...(yang patch here)... 307 308 309 310 311 ...(record #2)... 312 313 315 6. Data Model 317 file "ietf-notification-messages.yang" 318 module ietf-notification-messages { 319 yang-version 1.1; 320 namespace "urn:ietf:params:xml:ns:yang:ietf-notification-messages"; 321 prefix nm; 323 import ietf-yang-types { 324 prefix yang; 325 } 326 import ietf-inet-types { 327 prefix inet; 328 } 330 organization "IETF"; 331 contact 332 "WG Web: 333 WG List: 335 WG Chair: Mahesh Jethanandani 336 338 WG Chair: Mehmet Ersue 339 341 Editor: Eric Voit 342 344 Editor: Alexander Clemm 345 347 Editor: Tim Jenkins 348 350 Editor: Andy Bierman 351 "; 353 description 354 "This module contains conceptual YANG specifications for 355 notification messages with well known header objects."; 357 revision 2017-04-25 { 358 description 359 "This module includes definitions for two new yang 360 notification message objects: 361 (a) a message format including the definitions for common header 362 information prior to notification payload. 363 (b) a message format allowing the bundling of multiple 364 notifications within it"; 366 reference 367 "draft-voit-netconf-notification-messages-00"; 368 } 370 /* 371 * IDENTITIES 372 */ 374 /* Identities for notification record types */ 376 identity notification-record-format { 377 description 378 "Base identity to represent a different formats for notification 379 records."; 380 } 381 identity system-event { 382 base notification-record-format; 383 description 384 "System XML event"; 385 } 386 identity yang-datastore { 387 base notification-record-format; 388 description 389 "yang data node / tree extract"; 390 } 391 identity yang-patch { 392 base notification-record-format; 393 description 394 "yang patch record"; 395 } 396 identity syslog-entry { 397 base notification-record-format; 398 description 399 "Unstructured syslog entry."; 400 } 401 identity alarm { 402 base notification-record-format; 403 description 404 "Alarm (perhaps link draft-sharma-netmod-fault-model-01 for more 405 info)"; 406 } 408 /* 409 * TYPEDEFs 410 */ 412 typedef notification-record-format { 413 type identityref { 414 base notification-record-format; 416 } 417 description 418 "Type of notification record"; 419 } 421 /* 422 * GROUPINGS 423 */ 425 grouping notification-message-header { 426 description 427 "Header information included with a notification."; 428 leaf notification-id { 429 type uint32; 430 description 431 "unique id for a notification which may go to one or many 432 receivers."; 433 } 434 leaf notification-time { 435 type yang:date-and-time; 436 description 437 "time the notification was generated prior to being sent to 438 transport."; 439 } 440 leaf previous-notification-id { 441 type uint32; 442 description 443 "Notification id previously sent by publisher to a specific 444 receiver (allows detection of loss/duplication)."; 445 } 446 leaf dscp { 447 type inet:dscp; 448 default "0"; 449 description 450 "The push update's IP packet transport priority. This is made 451 visible across network hops to receiver. The transport 452 priority is shared for all receivers of a given 453 subscription."; 454 } 455 leaf message-generator-id { 456 type string; 457 description 458 "Software entity which created the notification message (e.g., 459 linecard 1)."; 460 } 461 leaf signature { 462 type string; 463 description 464 "Any originator signing of the contents of a notification 465 message. This can be useful for originating applications to 466 verify record contents even when shipping over unsecure 467 transport."; 468 } 469 } 471 grouping notification-record-header { 472 description 473 "Common informational objects which might help a receiver 474 interpret the meaning, details, and importance of an event 475 notification."; 476 leaf record-time { 477 type yang:date-and-time; 478 mandatory true; 479 description 480 "Time the system recognized the occurrence of an event."; 481 } 482 leaf record-type { 483 type notification-record-format; 484 description 485 "Describes the type of payload included. This is turn allow 486 the interpretation of the record contents."; 487 } 488 leaf-list subscription-id { 489 type uint32; 490 description 491 "Id of the subscription which led to the notification being 492 generated."; 493 } 494 leaf record-id { 495 type uint32; 496 description 497 "Identifier for the notification record."; 498 } 499 leaf observation-domain-id { 500 type string; 501 description 502 "Software entity which created the notification record (e.g., 503 process id)."; 504 } 505 } 507 /* 508 * NOTIFICATIONS 509 */ 511 notification notification-message { 512 description 513 "Notification message to a receiver containing only one event."; 514 container notification-message-header { 515 description 516 "delineates header info from notification messages for easy 517 parsing."; 518 uses notification-record-header; 519 uses notification-message-header; 520 } 521 anydata receiver-record-contents { 522 description 523 "Non-header info of what actually got sent to receiver after 524 security filter. (Note: Possible to have extra process 525 encryption.)"; 526 } 527 } 529 notification bundled-notification-message { 530 description 531 "Notification message to a receiver containing many events, 532 possibly relating to independent subscriptions."; 533 container bundled-notification-message-header { 534 description 535 "Delineates header info from notification messages for easy 536 parsing."; 537 uses notification-message-header { 538 refine notification-time { 539 mandatory true; 540 } 541 } 542 leaf record-count { 543 type uint16; 544 description 545 "Quantity of events in a bundled-notification-message 546 for a specific receiver. This value is per receiver in 547 case an entire notification record is filtered out."; 548 } 549 } 550 list notification-records { 551 description 552 "Set of messages within a notification to a receiver."; 553 container notification-record-header { 554 description 555 "delineates header info from notification messages for easy 556 parsing."; 557 uses notification-record-header; 558 } 559 anydata receiver-record-contents { 560 description 561 "Non-header info of what actually got sent to receiver after 562 security filter. (Note: Possible to have extra process 563 encryption.)"; 565 } 566 } 567 } 568 } 569 571 7. Security Considerations 573 More needs to be thought through here, as this adds additional 574 information onto notifications, the security implications shouldn't 575 be singificantly beyond those from [subscribe] other than ensuring 576 that data plane devices can accomplish the necessary content 577 filtering despite the potential of a new level of header being 578 applied. 580 8. References 582 8.1. Normative References 584 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 585 Requirement Levels", BCP 14, RFC 2119, 586 DOI 10.17487/RFC2119, March 1997, 587 . 589 [subscribe] 590 Voit, E., Clemm, A., Gonzalez Prieto, A., Prasad Tripathy, 591 A., and E. Nilsen-Nygaard, "Custom Subscription to Event 592 Notifications", April 2017, 593 . 596 8.2. Informative References 598 [initial-version] 599 Voit, E., Bierman, A., Clemm, A., and T. Jenkins, "Custom 600 Subscription to Event Notifications", February 2017, 601 . 604 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 605 RFC 7950, DOI 10.17487/RFC7950, August 2016, 606 . 608 [yang-push] 609 Clemm, A., Voit, E., Gonzalez Prieto, A., Prasad Tripathy, 610 A., and E. Nilsen-Nygaard, "Subscribing to YANG datastore 611 push updates", April 2017, 612 . 615 Appendix A. Issues being worked 617 (To be removed by RFC editor prior to publication) 619 We need to define the ways to invoke and configure the capability 620 within an originating device. This includes defining what header 621 types are selected. This also includes knowning the header types 622 which can be supported by a receiver. 624 We need to do a lot more to discuss transport efficiency 625 implications. 627 Relationship with DTN protocols. 629 Appendix B. Querying an Object Model 631 (This appendix was in a previous iteration of this draft. It has 632 been removed as unlikely to be seen in an implementation. It is 633 being kept in for discussion purposes.) 635 It is also possible that that external entities might want to query 636 message information after it has been sent. And therefore it is 637 possible that an administrator would like to examine the contents of 638 notifications via random access using a YANG model rather that 639 Syslog. There could be several values in such random access. These 640 include: 642 o ability for applications to determine what message bundles were 643 used to transport specific records. 645 o ability for applications to check which receivers have been sent 646 an event notification. 648 o ability for applications to determine the time delta between event 649 identification and transport. 651 o ability to reconstruct message passing during troubleshooting. 653 o ability to extract messages and records to evaluate whether the 654 security filters have been properly applied. 656 o ability to compare the payloads of the same notification message 657 sent to different receivers (again to evaluate the impact of the 658 security filtering). 660 If such random access is needed, it is possible to extend the YANG 661 model data model document to enable random access to the information. 662 A cut at what this might look like can be seen in [initial-version] 664 Authors' Addresses 666 Eric Voit 667 Cisco Systems 669 Email: evoit@cisco.com 671 Andy Bierman 672 YumaWorks 674 Email: andy@yumaworks.com 676 Alexander Clemm 677 Huawei 679 Email: ludwig@clemm.org 681 Tim Jenkins 682 Cisco Systems 684 Email: timjenki@cisco.com