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