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