idnits 2.17.1
draft-ietf-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 (September 28, 2017) is 2402 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: April 1, 2018 YumaWorks
6 A. Clemm
7 Huawei
8 T. Jenkins
9 Cisco Systems
10 September 28, 2017
12 Notification Message Headers and Bundles
13 draft-ietf-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 https://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 April 1, 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 (https://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", September 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 Appendix B. Querying an Object Model
634 (This appendix was in a previous iteration of this draft. It has
635 been removed as unlikely to be seen in an implementation. It is
636 being kept in for discussion purposes.)
638 It is also possible that that external entities might want to query
639 message information after it has been sent. And therefore it is
640 possible that an administrator would like to examine the contents of
641 notifications via random access using a YANG model rather that
642 Syslog. There could be several values in such random access. These
643 include:
645 o ability for applications to determine what message bundles were
646 used to transport specific records.
648 o ability for applications to check which receivers have been sent
649 an event notification.
651 o ability for applications to determine the time delta between event
652 identification and transport.
654 o ability to reconstruct message passing during troubleshooting.
656 o ability to extract messages and records to evaluate whether the
657 security filters have been properly applied.
659 o ability to compare the payloads of the same notification message
660 sent to different receivers (again to evaluate the impact of the
661 security filtering).
663 If such random access is needed, it is possible to extend the YANG
664 model data model document to enable random access to the information.
665 A cut at what this might look like can be seen in [initial-version]
667 Authors' Addresses
669 Eric Voit
670 Cisco Systems
672 Email: evoit@cisco.com
674 Andy Bierman
675 YumaWorks
677 Email: andy@yumaworks.com
679 Alexander Clemm
680 Huawei
682 Email: ludwig@clemm.org
684 Tim Jenkins
685 Cisco Systems
687 Email: timjenki@cisco.com