idnits 2.17.1
draft-ietf-netconf-yang-push-07.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 :
----------------------------------------------------------------------------
** There are 2 instances of too long lines in the document, the longest one
being 9 characters in excess of 72.
** The document seems to lack a both a reference to RFC 2119 and the
recommended RFC 2119 boilerplate, even if it appears to use RFC 2119
keywords.
RFC 2119 keyword, line 254: '...cription request SHOULD be declined ba...'
RFC 2119 keyword, line 263: '... subscriptions SHOULD support a simp...'
RFC 2119 keyword, line 266: '...-success message SHOULD include in the...'
RFC 2119 keyword, line 293: '... MAY accept an on-change subscriptio...'
RFC 2119 keyword, line 304: '...tively, a server MAY decide to simply ...'
(43 more instances...)
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Line 804 has weird spacing: '...er-type fil...'
== Line 946 has weird spacing: '...-period yan...'
== Line 960 has weird spacing: '...ntifier sub...'
== Line 962 has weird spacing: '...-result sub...'
== Line 965 has weird spacing: '...ntifier sub...'
== (5 more instances...)
-- The exact meaning of the all-uppercase expression 'MAY NOT' is not
defined in RFC 2119. If it is intended as a requirements expression, it
should be rewritten using one of the combinations defined in RFC 2119;
otherwise it should not be all-uppercase.
== The expression 'MAY NOT', while looking like RFC 2119 requirements text,
is not defined in RFC 2119, and should not be used. Consider using 'MUST
NOT' instead (if that is what you mean).
Found 'MAY NOT' in this paragraph:
Update messages for a single subscription MAY NOT be resequenced.
== The document seems to contain a disclaimer for pre-RFC5378 work, but was
first submitted on or after 10 November 2008. The disclaimer is usually
necessary only for documents that revise or obsolete older RFCs, and that
take significant amounts of text from those RFCs. If you can contact all
authors of the source material and they are willing to grant the BCP78
rights to the IETF Trust, you can and should remove the disclaimer.
Otherwise, the disclaimer is needed and you can ignore this comment.
(See the Legal Provisions document at
https://trustee.ietf.org/license-info for more information.)
-- The document date (June 26, 2017) is 2496 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)
== Unused Reference: 'RFC7223' is defined on line 2119, but no explicit
reference was found in the text
== Outdated reference: A later version (-09) exists of
draft-ietf-netconf-rfc6536bis-01
-- Possible downref: Normative reference to a draft: ref. 'RFC6536bis'
** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525)
-- Obsolete informational reference (is this intentional?): RFC 7223
(Obsoleted by RFC 8343)
Summary: 3 errors (**), 0 flaws (~~), 11 warnings (==), 4 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 NETCONF A. Clemm
3 Internet-Draft Huawei
4 Intended status: Standards Track E. Voit
5 Expires: December 28, 2017 Cisco Systems
6 A. Gonzalez Prieto
8 A. Tripathy
9 E. Nilsen-Nygaard
10 Cisco Systems
11 A. Bierman
12 YumaWorks
13 B. Lengyel
14 Ericsson
15 June 26, 2017
17 Subscribing to YANG datastore push updates
18 draft-ietf-netconf-yang-push-07
20 Abstract
22 Providing rapid visibility into changes made on YANG configuration
23 and operational objects enables new capabilities such as remote
24 mirroring of configuration and operational state. Via the mechanism
25 described in this document, subscriber applications may request a
26 continuous, customized stream of updates from a YANG datastore.
28 Status of This Memo
30 This Internet-Draft is submitted in full conformance with the
31 provisions of BCP 78 and BCP 79.
33 Internet-Drafts are working documents of the Internet Engineering
34 Task Force (IETF). Note that other groups may also distribute
35 working documents as Internet-Drafts. The list of current Internet-
36 Drafts is at http://datatracker.ietf.org/drafts/current/.
38 Internet-Drafts are draft documents valid for a maximum of six months
39 and may be updated, replaced, or obsoleted by other documents at any
40 time. It is inappropriate to use Internet-Drafts as reference
41 material or to cite them other than as "work in progress."
43 This Internet-Draft will expire on December 28, 2017.
45 Copyright Notice
47 Copyright (c) 2017 IETF Trust and the persons identified as the
48 document authors. All rights reserved.
50 This document is subject to BCP 78 and the IETF Trust's Legal
51 Provisions Relating to IETF Documents
52 (http://trustee.ietf.org/license-info) in effect on the date of
53 publication of this document. Please review these documents
54 carefully, as they describe your rights and restrictions with respect
55 to this document. Code Components extracted from this document must
56 include Simplified BSD License text as described in Section 4.e of
57 the Trust Legal Provisions and are provided without warranty as
58 described in the Simplified BSD License.
60 This document may contain material from IETF Documents or IETF
61 Contributions published or made publicly available before November
62 10, 2008. The person(s) controlling the copyright in some of this
63 material may not have granted the IETF Trust the right to allow
64 modifications of such material outside the IETF Standards Process.
65 Without obtaining an adequate license from the person(s) controlling
66 the copyright in such materials, this document may not be modified
67 outside the IETF Standards Process, and derivative works of it may
68 not be created outside the IETF Standards Process, except to format
69 it for publication as an RFC or to translate it into languages other
70 than English.
72 Table of Contents
74 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
75 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 4
76 3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 5
77 3.1. Event Subscription Model . . . . . . . . . . . . . . . . 5
78 3.2. Negotiation of Subscription Policies . . . . . . . . . . 6
79 3.3. On-Change Considerations . . . . . . . . . . . . . . . . 6
80 3.4. Promise-Theory Considerations . . . . . . . . . . . . . . 8
81 3.5. Data Encodings . . . . . . . . . . . . . . . . . . . . . 8
82 3.6. Datastore filters . . . . . . . . . . . . . . . . . . . . 9
83 3.7. Streaming updates . . . . . . . . . . . . . . . . . . . . 10
84 3.8. Subscription management . . . . . . . . . . . . . . . . . 13
85 3.9. Receiver Authorization . . . . . . . . . . . . . . . . . 14
86 3.10. On-change notifiable YANG objects . . . . . . . . . . . . 15
87 3.11. Other considerations . . . . . . . . . . . . . . . . . . 16
88 4. A YANG data model for management of datastore push
89 subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 18
90 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 18
91 4.2. Subscription configuration . . . . . . . . . . . . . . . 23
92 4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 25
93 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 26
94 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 30
95 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 43
96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 44
97 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 44
98 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 44
99 9.1. Normative References . . . . . . . . . . . . . . . . . . 44
100 9.2. Informative References . . . . . . . . . . . . . . . . . 45
101 Appendix A. Relationships to other drafts . . . . . . . . . . . 46
102 A.1. ietf-netconf-subscribed-notifications . . . . . . . . . . 46
103 A.2. ietf-netconf-netconf-event-notif . . . . . . . . . . . . 46
104 A.3. ietf-netconf-restconf-notif . . . . . . . . . . . . . . . 46
105 A.4. voit-notifications2 . . . . . . . . . . . . . . . . . . . 47
106 Appendix B. Technologies to be considered for future iterations 47
107 B.1. Proxy YANG Subscription when the Subscriber and Receiver
108 are different . . . . . . . . . . . . . . . . . . . . . . 47
109 B.2. OpState and Filters . . . . . . . . . . . . . . . . . . . 48
110 B.3. Splitting push updates . . . . . . . . . . . . . . . . . 48
111 B.4. Potential Subscription Parameters . . . . . . . . . . . . 49
112 Appendix C. Issues that are currently being worked and resolved 49
113 Appendix D. Changes between revisions . . . . . . . . . . . . . 49
114 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 51
116 1. Introduction
118 Traditional approaches to remote visibility have been built on
119 polling. With polling, data is periodically requested and retrieved
120 by a client from a server to stay up-to-date. However, there are
121 issues associated with polling-based management:
123 o Polling incurs significant latency. This latency prohibits many
124 application types.
126 o Polling cycles may be missed, requests may be delayed or get lost,
127 often when the network is under stress and the need for the data
128 is the greatest.
130 o Polling requests may undergo slight fluctuations, resulting in
131 intervals of different lengths. The resulting data is difficult
132 to calibrate and compare.
134 o For applications that monitor for changes, many remote polling
135 cycles place ultimately fruitless load on the network, devices,
136 and applications.
138 A more effective alternative to polling is for an application to
139 receive automatic and continuous updates from a targeted subset of a
140 datastore. Accordingly, there is a need for a service that allows
141 applications to subscribe to updates from a YANG datastore and that
142 enables the publisher to push and in effect stream those updates.
143 The requirements for such a service have been documented in
144 [RFC7923].
146 This document defines a corresponding solution that is built on top
147 of "Custom Subscription to Event Notifications" [subscribe].
148 Supplementing that work are YANG data model augmentations, extended
149 RPCs, and new datastore specific update notifications. Transport
150 options for [subscribe] will work seamlessly with this solution.
152 2. Definitions and Acronyms
154 The terms below supplement those defined in [subscribe].
156 Data node: An instance of management information in a YANG datastore.
158 Data node update: A data item containing the current value/property
159 of a Data node at the time the data node update was created.
161 Datastore: A conceptual store of instantiated management information,
162 with individual data items represented by data nodes which are
163 arranged in hierarchical manner.
165 Data subtree: An instantiated data node and the data nodes that are
166 hierarchically contained within it.
168 Notification message: A transport encapsulated update record(s) and/
169 or event notification(s) intended to be sent to a receiver.
171 Update notification message: A notification message that contains an
172 update record.
174 Update record: A representation data node update(s) resulting from
175 the application of a filter for a subscription. An update record
176 will include the value/property of one or more data nodes at a point
177 in time. It may contain the update type for each data node (e.g.,
178 add, change, delete). Also included may be metadata/headers such as
179 a subscription-id.
181 Update trigger: A mechanism that determines when an update record
182 needs to be generated.
184 YANG-Push: The subscription and push mechanism for YANG datastores
185 that is specified in this document.
187 3. Solution Overview
189 This document specifies a solution for a push update subscription
190 service. This solution supports the dynamic as well as configured
191 subscriptions to information updates from YANG datastores.
192 Subscriptions specify when update notification messages should be
193 sent and what data to include in update records. YANG objects are
194 subsequently pushed from the publisher to the receiver per the terms
195 of the subscription.
197 3.1. Event Subscription Model
199 YANG-push subscriptions are defined using a data model that is itself
200 defined in YANG. This model enhances the event subscription model
201 defined in [subscribe] with capabilities that allow subscribers to
202 subscribe to data node updates, specifically to specify the triggers
203 when to generate update records as well as what to include in an
204 update record. Key enhancements include:
206 o Specification of selection filters which identify targeted YANG
207 data nodes and/or subtrees within a datastore for which updates
208 are to be pushed.
210 o An encoding (using anydata) for the contents of periodic and on-
211 change push updates.
213 o Specification of update policies that specify the conditions that
214 trigger the generation and pushing of new update records. There
215 are two types of subscriptions, periodic and on-change.
217 * For periodic subscriptions, the trigger is specified by two
218 parameters that define when updates are to be pushed. These
219 parameters are the period interval with which to report
220 updates, and an anchor time which can be used to calculate at
221 which point in time updates need to be assembled and sent.
223 * For on-change subscriptions, a trigger occurs whenever a change
224 in the subscribed information is detected. Included are
225 additional parameters such as:
227 + Dampening period: In an on-change subscription, the first
228 change that is detected results in an update to be sent
229 immediately. However, sending successive updates whenever
230 further changes are detected might result in quick
231 exhaustion of resources in case of very rapid changes. In
232 order to protect against that, a dampening period is used to
233 specify the interval which must pass before successive
234 update records for the same subscription are generated. The
235 dampening period collectively applies to the set of all data
236 nodes of a single subscription. This means that on change
237 of an object being subscribed to, an update record
238 containing that object is created either immediately when no
239 dampening period is already in effect, or at the end of a
240 dampening period.
242 + Change type: This parameter can be used to reduce the types
243 of datastore changes for which updates are sent (e.g., you
244 might only send when an object is created or deleted, but
245 not when an object value changes).
247 + No Synch on start: defines whether or not a complete push-
248 update of all subscribed data will be sent at the beginning
249 of a subscription. Such synchronization establishes the
250 frame of reference for subsequent updates.
252 3.2. Negotiation of Subscription Policies
254 A dynamic subscription request SHOULD be declined based on
255 publisher's assessment that it may be unable to provide update
256 records that would meet the terms of the request. However a
257 subscriber may quickly follow up with a new subscription request
258 using different parameters.
260 Random guessing at different parameters by a subscriber is to be
261 discouraged. Therefore, in order to minimize the number of
262 subscription iterations between subscriber and publisher, dynamic
263 subscriptions SHOULD support a simple negotiation between subscribers
264 and publishers for subscription parameters. This negotiation is in
265 the form of a no-success response to a failed establish or modify
266 subscription request. The no-success message SHOULD include in the
267 returned error response information that, when considered, increases
268 the likelihood of success for subsequent requests. However, there
269 are no guarantees that subsequent requests for this subscriber will
270 in fact be accepted.
272 Such negotiation information returned from a publisher beyond that
273 from [subscribe] includes hints at acceptable time intervals, size
274 estimates for the number or objects which would be returned from a
275 filter, and the names of targeted objects not found in the
276 publisher's YANG tree.
278 3.3. On-Change Considerations
280 On-change subscriptions allow subscribers to subscribe to updates
281 whenever changes to objects occur. As such, on-change subscriptions
282 are particularly effective for data that changes infrequently, yet
283 that requires applications to be notified whenever a change does
284 occur with minimal delay.
286 On-change subscriptions tend to be more difficult to implement than
287 periodic subscriptions. Accordingly, on-change subscriptions may not
288 be supported by all implementations or for every object.
290 Whether or not to accept or reject on-change subscription requests
291 when the scope of the subscription contains objects for which on-
292 change is not supported is up to the server implementation: A server
293 MAY accept an on-change subscription even when the scope of the
294 subscription contains objects for which on-change is not supported.
295 In that case, updates are sent only for those objects within the
296 scope that do support on-change updates whereas other objects are
297 excluded from update records, whether or not their values actually
298 change. In order for a client to determine whether objects support
299 on-change subcriptions, objects are marked accordingly by a server.
300 Accordingly, when subscribing, it is the responsibility of the client
301 to ensure it is aware of which objects support on-change and which do
302 not. For more on how objects are so marked, see Section 3.10.
304 Alternatively, a server MAY decide to simply reject an on-change
305 subscription in case the scope of the subscription contains objects
306 for which on-change is not supported. In case of a configured
307 subscription, the subsription can be marked as suspended respectively
308 inoperational.
310 To avoid flooding receivers with repeated updates for subscriptions
311 containing fast-changing objects, or objects with oscillating values,
312 an on-change subscription allows for the definition of a dampening
313 period. Once an update record for a given object is generated, no
314 other updates for this particular subscription will be created until
315 the end of the dampening period. Values sent at the end of the
316 dampening period are the current values of all changed objects which
317 are current at the time the dampening period expires. Changed
318 objects includes those which were deleted or newly created during
319 that dampening period. If an object has returned to its original
320 value (or even has been created and then deleted) during the
321 dampening-period, the last change will still be sent. This will
322 indicate churn is occuring on that object.
324 In cases where a client wants to have separate dampening periods for
325 different objects, multiple subscriptions with different objects in
326 subscription scope can be created.
328 On-change subscriptions can be refined to let users subscribe only to
329 certain types of changes, for example, only to object creations and
330 deletions, but not to modifications of object values.
332 3.4. Promise-Theory Considerations
334 A subscription to updates from a YANG datastore is intended to
335 obviate the need for polling. However, in order to do so, it is of
336 utmost importance that subscribers can rely on the subscription and
337 have confidence that they will indeed receive the subscribed updates
338 without having to worry updates being silently dropped. In other
339 words, a subscription constitutes a promise on the side of the server
340 to provide the receivers with updates per the terms of the
341 subscription.
343 Now, there are many reasons why a server may at some point no longer
344 be able to fulfill the terms of the subscription, even if the
345 subscription had been entered into with good faith. For example, the
346 volume of data objects may be larger than anticipated, the interval
347 may prove too short to send full updates in rapid succession, or an
348 internal problem may prevent updates from being collected. If for
349 some reason the server of a subscription is not able to keep its
350 promise, receivers MUST be notified immediately and reliably. The
351 server MUST also update the state of the subscription to indicate
352 that the subscription is in a detrimental state.
354 A server SHOULD reject a request for a subscription if it is unlikely
355 that the server will be able fulfill the terms of the subscription.
356 In such cases, it is preferable to have a client request another
357 subscription that is less resource intensive (for example, a
358 subscription with longer periodic update intervals), than to
359 subsequently frustrate the receiver with `frequent subscription
360 suspensions.
362 3.5. Data Encodings
364 Subscribed data is encoded in either XML or JSON format. A publisher
365 MUST support XML encoding and MAY support JSON encoding.
367 3.5.1. Periodic Subscriptions
369 In a periodic subscription, the data included as part of an update
370 corresponds to data that could have been simply retrieved using a get
371 operation and is encoded in the same way. XML encoding rules for
372 data nodes are defined in [RFC7950]. JSON encoding rules are defined
373 in [RFC7951].
375 3.5.2. On-Change Subscriptions
377 In an on-change subscription, updates need to indicate not only
378 values of changed data nodes but also the types of changes that
379 occurred since the last update. Therefore encoding rules for data in
380 on-change updates will follow YANG-patch operation as specified in
381 [RFC8072]. The YANG-patch will describe what needs to be applied to
382 the earlier state reported by the preceding update, to result in the
383 now-current state. Note that contrary to [RFC8072], objects
384 encapsulated are not restricted to configuration objects only.
386 3.6. Datastore filters
388 Subscription policy specifies both the filters and the datastores
389 against which the filters will be applied. The result is the push of
390 information necessary to remotely maintain an extract of publisher's
391 datastore.
393 Only a single filter can be applied to a subscription at a time. The
394 following selection filter types are included in the yang-push data
395 model, and may be applied against a datastore:
397 o subtree: A subtree filter identifies one or more subtrees. When
398 specified, updates will only come from the data nodes of selected
399 YANG subtree(s). The syntax and semantics correspond to that
400 specified for [RFC6241] section 6.
402 o xpath: An xpath filter is an XPath expression which may be
403 meaningfully applied to a datastore. It is the results of this
404 expression which will be pushed.
406 Filters are intended to be used as selectors that define which
407 objects are within the scope of a subscription. Filters are not
408 intended to be used to store objects based on their current value.
409 Doing so would have a number of implications that would result in
410 significant additional complexity. For example, withough extending
411 encodings for on-change subscriptions, a receiver would not be able
412 to distinguish cases in which an object is no longer included in an
413 update because it was deleted, as opposed to its value simply no
414 longer meeting the filter criteria. While it is possible to define
415 extensions in the future that will support filtering based on values,
416 this is not supported in this version of yang-push and a server MAY
417 reject a subscription request that contains a filter for object
418 values.
420 Xpath itself provides powerful filtering constructs, and care must be
421 used in filter definition. As an example, consider an xpath filter
422 with a boolean result; such a result will not provide an easily
423 interpretable subset of a datastore. Beyond the boolean example, it
424 is quite possible to define an xpath filter where results are easy
425 for an application to mis-interpret. Consider an xpath filter which
426 only passes a datastore object when interface=up. It is up to the
427 receiver to understand implications of the presence or absence of
428 objects in each update.
430 It is not expected that implementations will support comprehensive
431 filter syntax and boundless complexity. It will be up to
432 implementations to describe what is viable, but the goal is to
433 provide equivalent capabilities to what is available with a GET.
434 Implementations MUST reject dynamic subscriptions or suspend
435 configured subscriptions if they include filters which are
436 unsupportable on a platform.
438 3.7. Streaming updates
440 Contrary to traditional data retrieval requests, datastore
441 subscription enables an unbounded series of update records to be
442 streamed over time. Two generic notifications for update records
443 have been defined for this: "push-update" and "push-change-update".
445 A push-update notification defines a complete, filtered update of the
446 datastore per the terms of a subscription. This type of notification
447 is used for continuous updates of periodic subscriptions. A push-
448 update notification can also used be for the on-change subscriptions
449 in two cases. First it will be used as the initial push-update if
450 there is a need to synchronize the receiver at the start of a new
451 subscription. It also MAY be sent if the publisher later chooses to
452 resynch an on-change subscription. The push-update record contains a
453 data snippet that contains an instantiated subtree with the
454 subscribed contents. The content of the update record is equivalent
455 to the contents that would be obtained had the same data been
456 explicitly retrieved using e.g., a NETCONF "get" operation, with the
457 same filters applied.
459 A push-change-update notification is the most common type of update
460 for on-change subscriptions. The update record in this case contains
461 a data snippet that indicates the set of changes that data nodes have
462 undergone since the last notification of YANG objects. In other
463 words, this indicates which data nodes have been created, deleted, or
464 have had changes to their values. In cases where multiple changes
465 have occurred and the object has not been deleted, the object's most
466 current value is reported. (In other words, for each object, only
467 one change is reported, not its entire history. Doing so would
468 defeat the purpose of the dampening period.)
470 These new YANG notifications are encoded and placed within
471 notification messages, which are then queued for egress over the
472 specified transport. The following is an example of an XML encoded
473 notification message over NETCONF transport as per [netconf-notif].
475
477 2015-03-09T19:14:56Z
478
480 1011
481 2015-03-09T19:14:56.233Z
482
483
484 some_string
485
486
487
488
490 Figure 1: Push example
492 The following is an example of an on-change notification. It
493 contains an update for subscription 89, including a new value for a
494 leaf called beta, which is a child of a top-level container called
495 alpha:
497
499 2015-03-09T19:14:56Z
500
502 89
503 2015-03-09T19:14:56.233Z
504
505
506 1500
507
508
509
510
512 Figure 2: Push example for on change
514 The equivalent update when requesting json encoding:
516
518 2015-03-09T19:14:56Z
519
521 89
522 2015-03-09T19:14:56.233Z
523
524 {
525 "ietf-yang-patch:yang-patch": {
526 "patch-id": [
527 null
528 ],
529 "edit": [
530 {
531 "edit-id": "edit1",
532 "operation": "merge",
533 "target": "/alpha/beta",
534 "value": {
535 "beta": 1500
536 }
537 }
538 ]
539 }
540 }
541
542
543
545 Figure 3: Push example for on change with JSON
547 When the beta leaf is deleted, the publisher may send
548
550 2015-03-09T19:14:56Z
551
553 89
554 2015-03-09T19:14:56.233Z
555
556
557
559
560
561
562
564 Figure 4: 2nd push example for on change update
566 3.8. Subscription management
568 [subscribe] has been enhanced to support YANG datastore subscription
569 negotiation. These enhancements provide information on why a
570 datastore subscription attempt has failed.
572 A datastore subscription can be rejected for multiple reasons. This
573 includes the lack of read authorization on a requested data node, or
574 the inability of the publisher push update records as frequently as
575 requested. In such cases, no subscription is established. Instead,
576 the subscription-result with the failure reason is returned as part
577 of the RPC response. As part of this response, a set of alternative
578 subscription parameters MAY be returned that would likely have
579 resulted in acceptance of the subscription request. The subscriber
580 may consider these as part of future subscription attempts.
582 It should be noted that a rejected subscription does not result in
583 the generation of an rpc-reply with an rpc-error element, as neither
584 the specification of YANG-push specific errors nor the specification
585 of additional data parameters to be returned in an error case are
586 supported as part of a YANG data model.
588 For instance, for the following request:
590
592
594 push-update
595
598 500
599 encode-xml
600
601
603 Figure 5: Establish-Subscription example
605 the publisher might return:
607
609
611 error-insufficient-resources
612
613 2000
614
616 Figure 6: Error response example
618 3.9. Receiver Authorization
620 A receiver of subscription data MUST only be sent updates for which
621 they have proper authorization. A server MUST ensure that no non-
622 authorized data is included in push updates. To do so, it needs to
623 apply all corresponding checks applicable at the time of a specific
624 pushed update and if necessary silently remove any non-authorized
625 data from subtrees. This enables YANG data pushed based on
626 subscriptions to be authorized equivalently to a regular data
627 retrieval (get) operation.
629 Alternatively, a server that wants to avoid having to perform
630 filtering of authorized content on each update MAY instead simply
631 reject a subscription request that contains non-authorized data. It
632 MAY subsequently suspend a subscription in case new objects are
633 created during the course of the subscription for which the receiver
634 does not have the necessary authorization, or in case the
635 authorization privileges of a receiver change over the course of the
636 subscription.
638 The contextual authorization model for data in YANG datastores is the
639 NETCONF Access Control Model [RFC6536bis], Section 3.2.3. However,
640 there are some differences.
642 One of these clarifications is that datastore selection MUST NOT
643 return continuous errors as part of an on-change subscription. This
644 includes errors such as when there is not read access to every data
645 node specifically named within the filter. Non-authorized data needs
646 to be either simply dropped or, alternatively, the subscription
647 SHOULD be suspended.
649 +-------------+ +-------------+
650 establish / | protocol | | filter |
651 modify --> | operation | -------------> | data node |
652 subscription | allowed? | datastore | access |
653 +-------------+ objects | allowed? |
654 +-------------+
656 Figure 7: Access control for subscription
658 Another clarification to [RFC6536bis] is that each of the individual
659 nodes in a resulting update record MUST also have applied access
660 control to resulting pushed messages. This includes validating that
661 read access into new nodes added since the last update record. If
662 read access into previously accessible nodes not explicitly named in
663 the filter are lost mid-subscription, that can be treated as a
664 'delete' for on-change subscriptions. If not capable of handling
665 such permission changes for dynamic subscriptions, publisher
666 implementations MAY choose to terminate the subscription and to force
667 re-establishment with appropriate filtering.
669 +-------------+ +-------------------+
670 push-update / --> | data node | yes | |
671 push-change-update | access | ---> | add data node |
672 | allowed? | | to update message |
673 +-------------+ +-------------------+
675 Figure 8: Access control for push updates
677 3.10. On-change notifiable YANG objects
679 In some cases, a publisher supporting on-change notifications may not
680 be able to push updates for some object types on-change. Reasons for
681 this might be that the value of the data node changes frequently
682 (e.g., [RFC7223]'s in-octets counter), that small object changes are
683 frequent and meaningless (e.g., a temperature gauge changing 0.1
684 degrees), or that the implementation is not capable of on-change
685 notification for a particular object.
687 Support for on-change notification is usually specific to the
688 individual YANG model and/or implementation so it is possible to
689 define in design time. System integrators need this information
690 (without reading any data from a live node).
692 The default assumption is that no data nodes support on-change
693 notification. Schema nodes and subtrees that support on-change
694 notifications MUST be marked by accordingly with the YANG extension
695 "notifiable-on-change". This extension is defined in the data model
696 below.
698 When an on-change subscription is established, data-nodes are
699 automatically excluded unless they are marked with notifiable-on-
700 change as true. This also means that authorization checks SHALL NOT
701 be performed on them. A client can identify which nodes will be
702 included in on-change updated by retrieving the data nodes in the
703 subscription's scope and checking for which notifiable-on-change is
704 marked as true.
706 Adding notifiable-on-change markings will in general require updating
707 the corresponding YANG models. A simple way to avoid having to
708 modify existing module definitions is to add notifiable-on-change
709 markings by defining module deviations. This means that when a YANG
710 model designer wants to add a notifiable-on-change marking to nodes
711 of an existing module without modifying the module definitions, a new
712 module is introduced that contains deviation statements which add
713 "notifiable-on-change" statements as appicable.
715 deviation /sys:system/sys:system-time {
716 deviate add {
717 yp:notifiable-on-change false;
718 }
719 }
721 Figure 9: Deviation Example
723 3.11. Other considerations
725 3.11.1. Robustness and reliability
727 Particularly in the case of on-change push updates, it is important
728 that push updates do not get lost or, in case the loss of an update
729 is unavoidable, that the receiver is notified accordingly.
731 Update messages for a single subscription MAY NOT be resequenced.
733 It is conceivable that under certain circumstances, a publisher will
734 recognize that it is unable to include within an update record the
735 full set of objects desired per the terms of a subscription. In this
736 case, the publisher MUST take one or more of the following actions.
738 o A publisher MUST set the updates-not-sent flag on any update
739 record which is known to be missing information.
741 o It MAY choose to suspend a subscription as per [subscribe].
743 o When resuming an on-change subscription, the publisher SHOULD
744 generate a complete patch from the previous update record. If
745 this is not possible and the synch-on-start option is configured,
746 then the full datastore contents MAY be sent instead (effectively
747 replacing the previous contents). If neither of these are
748 possible, then an updates-not-sent flag MUST be included on the
749 next push-change-update.
751 Note: It is perfectly acceptable to have a series of push-change-
752 updates (and even push updates) serially queued at the transport
753 layer awaiting transmission. It is not required to merge pending
754 update messages. I.e., the dampening period applies to update record
755 creation, not transmission.
757 3.11.2. Update size and fragmentation
759 Depending on the subscription, the volume of updates can become quite
760 large. Additionally, based on the platform, it is possible that
761 update records for a single subscription are best sent independently
762 from different line-cards. Therefore, it may not always be practical
763 to send the entire update record in a single chunk. Implementations
764 may therefore choose, at their discretion, to "chunk" update records,
765 breaking one subscription's objects across several update records.
766 In this case the updates-not-sent flag will indicate that no single
767 update record is complete, and it is permissible for multiple updates
768 to come into a receiver for a single periodic interval or on-change
769 dampening period.
771 Care must be taken in chunking as problems may arrise for objects
772 that have containment or referential dependencies. The publisher
773 must consider these issues if chunking is provided.
775 3.11.3. Publisher capacity
777 It is far preferable to decline a subscription request than to accept
778 such a request when it cannot be met.
780 Whether or not a subscription can be supported will be determined by
781 a combination of several factors such as the subscription policy (on-
782 change or periodic), the period in which to report changes (1 second
783 periods will consume more resources than 1 hour periods), the amount
784 of data in the subtree that is being subscribed to, and the number
785 and combination of other subscriptions that are concurrently being
786 serviced.
788 4. A YANG data model for management of datastore push subscriptions
790 4.1. Overview
792 The YANG data model for datastore push subscriptions is depicted in
793 the following figure. Following YANG tree convention in the
794 depiction, brackets enclose list keys, "rw" means configuration, "ro"
795 operational state data, "?" designates optional nodes, "*" designates
796 nodes that can have multiple instances. Parentheses with a name in
797 the middle enclose choice and case nodes. New YANG objects defined
798 here (i.e., beyond those from [subscribe]) are identified with "yp".
800 module: ietf-subscribed-notifications
801 +--rw filters
802 | +--rw filter* [identifier]
803 | +--rw identifier filter-id
804 | +--rw filter-type filter-type
805 | +--rw filter
806 +--rw subscription-config {configured-subscriptions}?
807 | +--rw subscription* [identifier]
808 | +--rw identifier subscription-id
809 | +--rw encoding? encoding
810 | +--rw (target)
811 | | +--:(event-stream)
812 | | | +--rw stream stream
813 | | +--:(yp:datastore)
814 | | +--rw yp:datastore datastore
815 | +--rw (applied-filter)
816 | | +--:(by-reference)
817 | | | +--rw filter-ref filter-ref
818 | | +--:(locally-configured)
819 | | +--rw filter-type filter-type
820 | | +--rw filter
821 | +--rw stop-time? yang:date-and-time
822 | +--rw receivers
823 | | +--rw receiver* [address port]
824 | | +--rw address inet:host
825 | | +--rw port inet:port-number
826 | | +--rw protocol? transport-protocol
827 | +--rw (notification-origin)?
828 | | +--:(interface-originated)
829 | | | +--rw source-interface? if:interface-ref
830 | | +--:(address-originated)
831 | | +--rw source-vrf? string
832 | | +--rw source-address inet:ip-address-no-zone
833 | +--rw (yp:update-trigger)?
834 | | +--:(yp:periodic)
835 | | | +--rw yp:period yang:timeticks
836 | | | +--rw yp:anchor-time? yang:date-and-time
837 | | +--:(yp:on-change) {on-change}?
838 | | +--rw yp:dampening-period yang:timeticks
839 | | +--rw yp:no-synch-on-start? empty
840 | | +--rw yp:excluded-change* change-type
841 | +--rw yp:dscp? inet:dscp
842 | +--rw yp:weighting? uint8
843 | +--rw yp:dependency? sn:subscription-id
844 +--ro subscriptions
845 +--ro subscription* [identifier]
846 +--ro identifier subscription-id
847 +--ro configured-subscription?
848 | empty {configured-subscriptions}?
849 +--ro encoding? encoding
850 +--ro (target)
851 | +--:(event-stream)
852 | | +--ro stream stream
853 | | +--ro replay-start-time? yang:date-and-time {replay}?
854 | +--:(yp:datastore)
855 | +--ro yp:datastore datastore
856 +--ro (applied-filter)
857 | +--:(by-reference)
858 | | +--ro filter-ref filter-ref
859 | +--:(locally-configured)
860 | +--ro filter-type filter-type
861 | +--ro filter
862 +--ro stop-time? yang:date-and-time
863 +--ro (notification-origin)?
864 | +--:(interface-originated)
865 | | +--ro source-interface? if:interface-ref
866 | +--:(address-originated)
867 | +--ro source-vrf? string
868 | +--ro source-address inet:ip-address-no-zone
869 +--ro receivers
870 | +--ro receiver* [address port]
871 | +--ro address inet:host
872 | +--ro port inet:port-number
873 | +--ro protocol? transport-protocol
874 | +--ro pushed-notifications? yang:counter64
875 | +--ro excluded-notifications? yang:counter64
876 | +--ro status subscription-status
877 +--ro (yp:update-trigger)?
878 | +--:(yp:periodic)
879 | | +--ro yp:period yang:timeticks
880 | | +--ro yp:anchor-time? yang:date-and-time
881 | +--:(yp:on-change) {on-change}?
882 | +--ro yp:dampening-period yang:timeticks
883 | +--ro yp:no-synch-on-start? empty
884 | +--ro yp:excluded-change* change-type
885 +--ro yp:dscp? inet:dscp
886 +--ro yp:weighting? uint8
887 +--ro yp:dependency? sn:subscription-id
889 rpcs:
890 +---x establish-subscription
891 | +---w input
892 | | +---w encoding? encoding
893 | | +---w (target)
894 | | | +--:(event-stream)
895 | | | | +---w stream stream
896 | | | | +---w replay-start-time? yang:date-and-time {replay}?
897 | | | +--:(yp:datastore)
898 | | | +---w yp:datastore datastore
899 | | +---w (applied-filter)
900 | | | +--:(by-reference)
901 | | | | +---w filter-ref filter-ref
902 | | | +--:(locally-configured)
903 | | | +---w filter-type filter-type
904 | | | +---w filter
905 | | +---w stop-time? yang:date-and-time
906 | | +---w (yp:update-trigger)?
907 | | | +--:(yp:periodic)
908 | | | | +---w yp:period yang:timeticks
909 | | | | +---w yp:anchor-time? yang:date-and-time
910 | | | +--:(yp:on-change) {on-change}?
911 | | | +---w yp:dampening-period yang:timeticks
912 | | | +---w yp:no-synch-on-start? empty
913 | | | +---w yp:excluded-change* change-type
914 | | +---w yp:dscp? inet:dscp
915 | | +---w yp:weighting? uint8
916 | | +---w yp:dependency? sn:subscription-id
917 | +--ro output
918 | +--ro subscription-result subscription-result
919 | +--ro (result)?
920 | +--:(no-success)
921 | | +--ro filter-failure? string
922 | | +--ro replay-start-time-hint? yang:date-and-time
923 | | +--ro yp:period-hint? yang:timeticks
924 | | +--ro yp:error-path? string
925 | | +--ro yp:object-count-estimate? uint32
926 | | +--ro yp:object-count-limit? uint32
927 | | +--ro yp:kilobytes-estimate? uint32
928 | | +--ro yp:kilobytes-limit? uint32
929 | +--:(success)
930 | +--ro identifier subscription-id
931 +---x modify-subscription
932 | +---w input
933 | | +---w identifier? subscription-id
934 | | +---w (applied-filter)
935 | | | +--:(by-reference)
936 | | | | +---w filter-ref filter-ref
937 | | | +--:(locally-configured)
938 | | | +---w filter-type filter-type
939 | | | +---w filter
940 | | +---w stop-time? yang:date-and-time
941 | | +---w (yp:update-trigger)?
942 | | +--:(yp:periodic)
943 | | | +---w yp:period yang:timeticks
944 | | | +---w yp:anchor-time? yang:date-and-time
945 | | +--:(yp:on-change) {on-change}?
946 | | +---w yp:dampening-period yang:timeticks
947 | +--ro output
948 | +--ro subscription-result subscription-result
949 | +--ro (result)?
950 | +--:(no-success)
951 | +--ro filter-failure? string
952 | +--ro yp:period-hint? yang:timeticks
953 | +--ro yp:error-path? string
954 | +--ro yp:object-count-estimate? uint32
955 | +--ro yp:object-count-limit? uint32
956 | +--ro yp:kilobytes-estimate? uint32
957 | +--ro yp:kilobytes-limit? uint32
958 +---x delete-subscription
959 | +---w input
960 | | +---w identifier subscription-id
961 | +--ro output
962 | +--ro subscription-result subscription-result
963 +---x kill-subscription
964 +---w input
965 | +---w identifier subscription-id
966 +--ro output
967 +--ro subscription-result subscription-result
969 notifications:
970 +---n replay-complete
971 | +--ro identifier subscription-id
972 +---n notification-complete
973 | +--ro identifier subscription-id
974 +---n subscription-started
975 | +--ro identifier subscription-id
976 | +--ro encoding? encoding
977 | +--ro (target)
978 | | +--:(event-stream)
979 | | | +--ro stream stream
980 | | | +--ro replay-start-time? yang:date-and-time {replay}?
981 | | +--:(yp:datastore)
982 | | +--ro yp:datastore datastore
983 | +--ro (applied-filter)
984 | | +--:(by-reference)
985 | | | +--ro filter-ref filter-ref
986 | | +--:(locally-configured)
987 | | +--ro filter-type filter-type
988 | | +--ro filter
989 | +--ro stop-time? yang:date-and-time
990 | +--ro (yp:update-trigger)?
991 | | +--:(yp:periodic)
992 | | | +--ro yp:period yang:timeticks
993 | | | +--ro yp:anchor-time? yang:date-and-time
994 | | +--:(yp:on-change) {on-change}?
995 | | +--ro yp:dampening-period yang:timeticks
996 | | +--ro yp:no-synch-on-start? empty
997 | | +--ro yp:excluded-change* change-type
998 | +--ro yp:dscp? inet:dscp
999 | +--ro yp:weighting? uint8
1000 | +--ro yp:dependency? sn:subscription-id
1001 +---n subscription-resumed
1002 | +--ro identifier subscription-id
1003 +---n subscription-modified
1004 | +--ro identifier subscription-id
1005 | +--ro encoding? encoding
1006 | +--ro (target)
1007 | | +--:(event-stream)
1008 | | +--ro stream stream
1009 | | +--ro replay-start-time? yang:date-and-time {replay}?
1010 | +--ro (applied-filter)
1011 | | +--:(by-reference)
1012 | | | +--ro filter-ref filter-ref
1013 | | +--:(locally-configured)
1014 | | +--ro filter-type filter-type
1015 | | +--ro filter
1016 | +--ro stop-time? yang:date-and-time
1017 | +--ro (yp:update-trigger)?
1018 | | +--:(yp:periodic)
1019 | | | +--ro yp:period yang:timeticks
1020 | | | +--ro yp:anchor-time? yang:date-and-time
1021 | | +--:(yp:on-change) {on-change}?
1022 | | +--ro yp:dampening-period yang:timeticks
1023 | | +--ro yp:no-synch-on-start? empty
1024 | | +--ro yp:excluded-change* change-type
1025 | +--ro yp:dscp? inet:dscp
1026 | +--ro yp:weighting? uint8
1027 | +--ro yp:dependency? sn:subscription-id
1028 +---n subscription-terminated
1029 | +--ro identifier subscription-id
1030 | +--ro error-id subscription-errors
1031 | +--ro filter-failure? string
1032 +---n subscription-suspended
1033 +--ro identifier subscription-id
1034 +--ro error-id subscription-errors
1035 +--ro filter-failure? string
1037 module: ietf-yang-push
1038 notifications:
1039 +---n push-update
1040 | +--ro subscription-id sn:subscription-id
1041 | +--ro time-of-update? yang:date-and-time
1042 | +--ro updates-not-sent? empty
1043 | +--ro datastore-contents?
1044 +---n push-change-update {on-change}?
1045 +--ro subscription-id sn:subscription-id
1046 +--ro time-of-update? yang:date-and-time
1047 +--ro updates-not-sent? empty
1048 +--ro datastore-changes?
1050 Figure 10: Model structure
1052 Selected components of the model are summarized below.
1054 4.2. Subscription configuration
1056 Both configured and dynamic subscriptions are represented within the
1057 list subscription-config. Each subscription has own list elements.
1058 New and enhanced parameters extending the basic subscription data
1059 model in [subscribe] include:
1061 o An update filter identifying yang nodes of interest. Filter
1062 contents are specified via a reference to an existing filter, or
1063 via an in-line definition for only that subscription. This
1064 facilitates the reuse of filter definitions, which can be
1065 important in case of complex filter conditions. Referenced
1066 filters can also allow an implementation to avoid evaluating
1067 filter acceptability during a dynamic subscription request. The
1068 case statement differentiates the options.
1070 o For periodic subscriptions, triggered updates will occur at the
1071 boundaries of a specified time interval. These boundaries many be
1072 calculated from the periodic parameters:
1074 * a "period" which defines duration between period push updates.
1076 * an "anchor-time"; update intervals always fall on the points in
1077 time that are a multiple of a period after the anchor time. If
1078 anchor time is not provided, then the anchor time MUST be set
1079 with the creation time of the initial update record.
1081 o For on-change subscriptions, assuming the dampening period has
1082 completed, triggered occurs whenever a change in the subscribed
1083 information is detected. On-change subscriptions have more
1084 complex semantics that is guided by its own set of parameters:
1086 * a "dampening-period" specifies the interval that must pass
1087 before a successive update for the subscription is sent. If no
1088 dampening period is in effect, the update is sent immediately.
1089 If a subsequent change is detected, another update is only sent
1090 once the dampening period has passed for this subscription.
1092 * an "excluded-change" flag which allows restriction of the types
1093 of changes for which updates should be sent (e.g., only add to
1094 an update record on object creation).
1096 * a "no-synch-on-start" flag which specifies whether a complete
1097 update with all the subscribed data is to be sent at the
1098 beginning of a subscription.
1100 o Optional qos parameters to indicate the treatment of a
1101 subscription relative to other traffic between publisher and
1102 receiver. These include:
1104 * A "dscp" QoS marking which MUST be stamped on notification
1105 messages to differentiate network QoS behavior.
1107 * A "weighting" so that bandwidth proportional to this weighting
1108 can be allocated to this subscription relative to others for
1109 that receiver.
1111 * a "dependency" upon another subscription. Notification
1112 messages MUST NOT be sent prior to other notification messages
1113 containing update record(s) for the referenced subscription.
1115 o A subscription's weighting MUST work identically to stream
1116 dependency weighting as described within RFC 7540, section 5.3.2.
1118 o A subscription's dependency MUST work identically to stream
1119 dependency as described within RFC 7540, sections 5.3.1, 5.3.3,
1120 and 5.3.4. If a dependency is attempted via an RPC, but the
1121 referenced subscription does not exist, the dependency will be
1122 removed.
1124 4.3. YANG Notifications
1126 4.3.1. Monitoring and OAM Notifications
1128 OAM notifications and mechanism are reused from [subscribe]. Some
1129 have been augmented to include the YANG datastore specific objects.
1131 4.3.2. New Notifications for update records
1133 The data model introduces two YANG notifications to encode
1134 information for update records: "push-update" and "push-change-
1135 update".
1137 "Push-update" is used to send a complete snapshot of the filtered
1138 subscription data. This type of notification is used to carry the
1139 update records of a periodic subscription. The "push-update"
1140 notification is also used with on-change subscriptions for the
1141 purposes of allowing a receiver to "synch" on a complete set of
1142 subscribed datastore contents. This synching may be done the start
1143 of an on-change subscription, and then later in that subscription to
1144 force resynchronization. If the "updates-not-sent" flag is set, this
1145 indicates that the update record is incomplete.
1147 "Push-change-update" is used to send datastore changes that have
1148 occurred in subscribed data since the previous update. This
1149 notification is used only in conjunction with on-change
1150 subscriptions. This will be encoded as yang-patch data.
1152 If the application detects an informational discontinuity in either
1153 notification, the notification MUST include a flag "updates-not-
1154 sent". This flag which indicates that not all changes which have
1155 occurred since the last update are actually included with this
1156 update. In other words, the publisher has failed to fulfill its full
1157 subscription obligations. (For example a datastore missed a window
1158 in providing objects to a publisher process.) To facilitate
1159 synchronization, a publisher MAY subsequently send a push-update
1160 containing a full snapshot of subscribed data.
1162 4.4. YANG RPCs
1164 YANG-Push subscriptions are established, modified, and deleted using
1165 RPCs augmented from [subscribe].
1167 4.4.1. Establish-subscription RPC
1169 The subscriber sends an establish-subscription RPC with the
1170 parameters in section 3.1. An example might look like:
1172
1174
1176
1179 500
1180 encode-xml
1181
1182
1184 Figure 11: Establish-subscription RPC
1186 The publisher MUST respond explicitly positively (i.e., subscription
1187 accepted) or negatively (i.e., subscription rejected) to the request.
1188 Positive responses include the subscription-id of the accepted
1189 subscription. In that case a publisher MAY respond:
1191
1193
1195 ok
1196
1197
1199 52
1200
1201
1203 Figure 12: Establish-subscription positive RPC response
1205 A subscription can be rejected for multiple reasons, including the
1206 lack of authorization to establish a subscription, the lack of read
1207 authorization on the requested data node, or the inability of the
1208 publisher to provide a stream with the requested semantics.
1210 When the requester is not authorized to read the requested data node,
1211 the returned information indicates the node is unavailable. For
1212 instance, if the above request was unauthorized to read node "ex:foo"
1213 the publisher may return:
1215
1217
1219 subtree-unavailable
1220
1221
1223 /ex:foo
1224
1225
1227 Figure 13: Establish-subscription access denied response
1229 If a request is rejected because the publisher is not able to serve
1230 it, the publisher SHOULD include in the returned error what
1231 subscription parameters would have been accepted for the request.
1232 However, there are no guarantee that subsequent requests using this
1233 info will in fact be accepted.
1235 For example, for the following request:
1237
1239
1241 running
1242
1245 10
1246 encode-xml
1247
1248
1250 Figure 14: Establish-subscription request example 2
1252 a publisher that cannot serve on-change updates but periodic updates
1253 might return the following:
1255
1257
1259 period-unsupported
1260
1261 100
1262
1264 Figure 15: Establish-subscription error response example 2
1266 4.4.2. Modify-subscription RPC
1268 The subscriber MAY invoke the modify-subscription RPC for a
1269 subscription it previously established. The subscriber will include
1270 newly desired values in the modify-subscription RPC. Parameters not
1271 included MUST remain unmodified. Below is an example where a
1272 subscriber attempts to modify the period of a subscription.
1274
1276
1278 running
1279
1280 1011
1281
1282 250
1283
1284
1286 Figure 16: Modify subscription request
1288 The publisher MUST respond explicitly positively or negatively to the
1289 request. A response to a successful modification might look like:
1291
1293
1295 ok
1296
1297
1299 Figure 17: Modify subscription response
1301 If the subscription modification is rejected, the publisher MUST send
1302 a response like it does for an establish-subscription and maintain
1303 the subscription as it was before the modification request.
1304 Responses MAY include hints. A subscription MAY be modified multiple
1305 times.
1307 A configured subscription cannot be modified using modify-
1308 subscription RPC. Instead, the configuration needs to be edited as
1309 needed.
1311 4.4.3. Delete-subscription RPC
1313 To stop receiving updates from a subscription and effectively delete
1314 a subscription that had previously been established using an
1315 establish-subscription RPC, a subscriber can send a delete-
1316 subscription RPC, which takes as only input the subscription-id. For
1317 example:
1319
1321
1323
1324 1011
1325
1326
1327
1329
1331
1333 ok
1334
1335
1337 Figure 18: Delete subscription
1339 Configured subscriptions cannot be deleted via RPC, but have to be
1340 removed from the configuration.
1342 4.4.4. YANG Module Synchronization
1344 To make subscription requests, the subscriber needs to know the YANG
1345 module library available on the publisher. The YANG 1.0 module
1346 library information is sent by a NETCONF server in the NETCONF
1347 'hello' message. For YANG 1.1 modules and all modules used with the
1348 RESTCONF [RFC8040] protocol, this information is provided by the YANG
1349 Library module (ietf-yang-library.yang from [RFC7895]. The YANG
1350 library information is important for the receiver to reproduce the
1351 set of object definitions used by the replicated datastore.
1353 The YANG library includes a module list with the name, revision,
1354 enabled features, and applied deviations for each YANG module
1355 implemented by the publisher. The receiver is expected to know the
1356 YANG library information before starting a subscription. The
1357 "/modules-state/module-set-id" leaf in the "ietf-yang-library" module
1358 can be used to cache the YANG library information.
1360 The set of modules, revisions, features, and deviations can change at
1361 run-time (if supported by the server implementation). In this case,
1362 the receiver needs to be informed of module changes before data nodes
1363 from changed modules can be processed correctly. The YANG library
1364 provides a simple "yang-library-change" notification that informs the
1365 client that the library has changed. The receiver then needs to re-
1366 read the entire YANG library data for the replicated server in order
1367 to detect the specific YANG library changes. The "ietf-netconf-
1368 notifications" module defined in [RFC6470] contains a "netconf-
1369 capability-change" notification that can identify specific module
1370 changes. For example, the module URI capability of a newly loaded
1371 module will be listed in the "added-capability" leaf-list, and the
1372 module URI capability of an removed module will be listed in the
1373 "deleted-capability" leaf-list.
1375 5. YANG module
1377 ; file "ietf-yang-push@2017-06-26.yang"
1378 module ietf-yang-push {
1379 yang-version 1.1;
1380 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push";
1381 prefix yp;
1383 import ietf-inet-types {
1384 prefix inet;
1385 }
1386 import ietf-yang-types {
1387 prefix yang;
1388 }
1389 import ietf-subscribed-notifications {
1390 prefix sn;
1391 }
1393 organization "IETF";
1394 contact
1395 "WG Web:
1396 WG List:
1397 WG Chair: Mahesh Jethanandani
1398
1400 WG Chair: Mehmet Ersue
1401
1403 Editor: Alexander Clemm
1404
1406 Editor: Eric Voit
1407
1409 Editor: Alberto Gonzalez Prieto
1410
1412 Editor: Ambika Prasad Tripathy
1413
1415 Editor: Einar Nilsen-Nygaard
1416
1418 Editor: Andy Bierman
1419
1421 Editor: Balazs Lengyel
1422 ";
1424 description
1425 "This module contains conceptual YANG specifications
1426 for YANG push.";
1428 revision 2017-06-26 {
1429 description
1430 "Move to identities for filters, datastores.";
1431 reference
1432 "YANG Datastore Push, draft-ietf-netconf-yang-push-07";
1433 }
1435 /*
1436 * EXTENSIONS
1437 */
1439 extension notifiable-on-change {
1440 argument "value";
1441 description
1442 "Indicates whether changes to the data node are reportable in
1443 on-change subscriptions.
1445 The statement MUST only be a substatement of the leaf, leaf-list,
1446 container, list, anyxml, anydata statements. Zero or One
1447 notifiable-on-change statement is allowed per parent statement.
1448 NO substatements are allowed.
1450 The argument is a boolean value indicating whether on-change
1451 notifications are supported. If notifiable-on-change is not
1452 specified, the default is the same as the parent data node's
1453 value. For top level data nodes the default value is false.";
1454 }
1456 /*
1457 * FEATURES
1458 */
1460 feature on-change {
1461 description
1462 "This feature indicates that on-change updates are
1463 supported.";
1464 }
1466 /*
1467 * IDENTITIES
1468 */
1470 /* Error type identities for datastore subscription */
1471 identity period-unsupported {
1472 base sn:error;
1473 description
1474 "Requested time period is too short. This can be for both
1475 periodic and on-change dampening.";
1476 }
1478 identity qos-unsupported {
1479 base sn:error;
1480 description
1481 "Subscription QoS parameters not supported on this platform.";
1482 }
1484 identity dscp-unavailable {
1485 base sn:error;
1486 description
1487 "Requested DSCP marking not allocatable.";
1488 }
1490 identity on-change-unsupported {
1491 base sn:error;
1492 description
1493 "On-change not supported.";
1494 }
1496 identity synch-on-start-unsupported {
1497 base sn:error;
1498 description
1499 "On-change synch-on-start not supported.";
1500 }
1502 identity synch-on-start-datatree-size {
1503 base sn:error;
1504 description
1505 "Synch-on-start would push a datatree which exceeds size limit.";
1506 }
1508 identity reference-mismatch {
1509 base sn:error;
1510 description
1511 "Mismatch in filter key and referenced yang subtree.";
1512 }
1514 identity data-unavailable {
1515 base sn:error;
1516 description
1517 "Referenced yang node or subtree doesn't exist, or read
1518 access is not permitted.";
1519 }
1521 identity datatree-size {
1522 base sn:error;
1523 description
1524 "Resulting push updates would exceed size limit.";
1525 }
1527 /* Datastore identities */
1528 identity datastore {
1529 description
1530 "A datastore.";
1531 }
1532 identity candidate {
1533 base datastore;
1534 description
1535 "The candidate datastore per RFC-6241.";
1536 reference "RFC-6241, #5.1";
1537 }
1538 identity running {
1539 base datastore;
1540 description
1541 "The running datastore per RFC-6241.";
1542 reference "RFC-6241, #5.1";
1543 }
1544 identity startup {
1545 base datastore;
1546 description
1547 "The startup datastore per RFC-6241.";
1548 reference "RFC-6241, #5.1";
1549 }
1550 identity operational {
1551 base datastore;
1552 description
1553 "The operational datastore contains all configuration data
1554 actually used by the system, including all applied configuration,
1555 system-provided configuration and values defined by any supported
1556 data models. In addition, the operational datastore also
1557 contains state data.";
1558 reference
1559 "the original text came from draft-ietf-netmod-revised-datastores
1560 -01, section #4.3. This definition is expected to remain stable
1561 meaning later reconciliation between the drafts unnecessary.";
1562 }
1564 /* New filter identities (adds to 'sn') */
1565 identity subtree {
1566 base sn:filter;
1567 description
1568 "A filter which follows the subtree filter syntax specified
1569 in RFC 6241.";
1570 reference "RFC 6241 section 6";
1571 }
1573 /*
1574 * TYPE DEFINITIONS
1575 */
1577 typedef change-type {
1578 type enumeration {
1579 enum "create" {
1580 description
1581 "Create a new data resource if it does not already exist. If
1582 it already exists, replace.";
1583 }
1584 enum "delete" {
1585 description
1586 "Delete a data resource if it already exists. If it does not
1587 exists, take no action.";
1588 }
1589 enum "insert" {
1590 description
1591 "Insert a new user-ordered data resource";
1592 }
1593 enum "merge" {
1594 description
1595 "merge the edit value with the target data resource; create
1596 if it does not already exist";
1597 }
1598 enum "move" {
1599 description
1600 "Reorder the target data resource";
1601 }
1602 enum "replace" {
1603 description
1604 "Replace the target data resource with the edit value";
1605 }
1606 enum "remove" {
1607 description
1608 "Remove a data resource if it already exists ";
1609 }
1610 }
1611 description
1612 "Specifies different types of datastore changes.";
1613 reference
1614 "RFC 8072 section 2.5, with a delta that it is ok to receive
1615 ability create on an existing node, or recieve a delete on a
1616 missing node.";
1617 }
1619 typedef datastore {
1620 type identityref {
1621 base datastore;
1622 }
1623 description
1624 "Specifies a system-provided datastore. May also specify ability
1625 portion of a datastore, so as to reduce the filtering effort.";
1626 }
1628 /*
1629 * GROUP DEFINITIONS
1630 */
1632 grouping datastore-criteria {
1633 description
1634 "A reusable place to define the meaning of datastore.";
1635 leaf datastore {
1636 type datastore;
1637 mandatory true;
1638 description
1639 "Datastore against which the subscription has been applied.";
1640 }
1641 }
1643 grouping update-policy-modifiable {
1644 description
1645 "This grouping describes the datastore specific subscription
1646 conditions that can be changed during the lifetime of the
1647 subscription.";
1648 choice update-trigger {
1649 description
1650 "Defines necessary conditions for sending an event to
1651 the subscriber.";
1652 case periodic {
1653 description
1654 "The agent is requested to notify periodically the current
1655 values of the datastore as defined by the filter.";
1656 leaf period {
1657 type yang:timeticks;
1658 mandatory true;
1659 description
1660 "Duration of time which should occur between periodic
1661 push updates. Where the anchor of a start-time is
1662 available, the push will include the objects and their
1663 values which exist at an exact multiple of timeticks
1664 aligning to this start-time anchor.";
1665 }
1666 leaf anchor-time {
1667 type yang:date-and-time;
1668 description
1669 "Designates a timestamp from which the series of periodic
1670 push updates are computed. The next update will take place
1671 at the next period interval from the anchor time. For
1672 example, for an anchor time at the top of a minute and a
1673 period interval of a minute, the next update will be sent
1674 at the top of the next minute.";
1675 }
1676 }
1677 case on-change {
1678 if-feature "on-change";
1679 description
1680 "The agent is requested to notify changes in values in the
1681 datastore subset as defined by a filter.";
1682 leaf dampening-period {
1683 type yang:timeticks;
1684 mandatory true;
1685 description
1686 "The shortest time duration which is allowed between the
1687 creation of independent yang object update messages.
1688 Effectively this is the amount of time that needs to have
1689 passed since the last update.";
1690 }
1691 }
1692 }
1693 }
1695 grouping update-policy {
1696 description
1697 "This grouping describes the datastore specific subscription
1698 conditions of a subscription.";
1699 uses update-policy-modifiable {
1700 augment "update-trigger/on-change" {
1701 description
1702 "Includes objects not modifiable once subscription is
1703 established.";
1704 leaf no-synch-on-start {
1705 type empty;
1706 description
1707 "This leaf acts as a flag that determines behavior at the
1708 start of the subscription. When present, synchronization
1709 of state at the beginning of the subscription is outside
1710 the scope of the subscription. Only updates about changes
1711 that are observed from the start time, i.e. only push-
1712 change-update notifications are sent. When absent (default
1713 behavior), in order to facilitate a receiver's
1714 synchronization, a full update is sent when the
1715 subscription starts using a push-update notification, just
1716 like in the case of a periodic subscription. After that,
1717 push-change-update notifications only are sent unless the
1718 Publisher chooses to resynch the subscription again.";
1719 }
1720 leaf-list excluded-change {
1721 type change-type;
1722 description
1723 "Use to restrict which changes trigger an update.
1724 For example, if modify is excluded, only creation and
1725 deletion of objects is reported.";
1726 }
1727 }
1728 }
1729 }
1731 grouping update-qos {
1732 description
1733 "This grouping describes Quality of Service information
1734 concerning a subscription. This information is passed to lower
1735 layers for transport prioritization and treatment";
1736 leaf dscp {
1737 type inet:dscp;
1738 default "0";
1739 description
1740 "The push update's IP packet transport priority. This is made
1741 visible across network hops to receiver. The transport
1742 priority is shared for all receivers of a given subscription.";
1743 }
1744 leaf weighting {
1745 type uint8 {
1746 range "0 .. 255";
1747 }
1748 description
1749 "Relative weighting for a subscription. Allows an underlying
1750 transport layer perform informed load balance allocations
1751 between various subscriptions";
1752 reference
1753 "RFC-7540, section 5.3.2";
1754 }
1755 leaf dependency {
1756 type sn:subscription-id;
1757 description
1758 "Provides the Subscription ID of a parent subscription which
1759 has absolute priority should that parent have push updates
1760 ready to egress the publisher. In other words, there should be
1761 no streaming of objects from the current subscription if of
1762 the parent has something ready to push.";
1763 reference
1764 "RFC-7540, section 5.3.1";
1765 }
1766 }
1768 grouping update-error-hints {
1769 description
1770 "Allow return additional negotiation hints that apply
1771 specifically to push updates.";
1772 leaf period-hint {
1773 type yang:timeticks;
1774 description
1775 "Returned when the requested time period is too short. This
1776 hint can assert an viable period for both periodic push
1777 cadence and on-change dampening.";
1778 }
1779 leaf error-path {
1780 type string;
1781 description
1782 "Reference to a YANG path which is associated with the error
1783 being returned.";
1784 }
1785 leaf object-count-estimate {
1786 type uint32;
1787 description
1788 "If there are too many objects which could potentially be
1789 returned by the filter, this identifies the estimate of the
1790 number of objects which the filter would potentially pass.";
1791 }
1792 leaf object-count-limit {
1793 type uint32;
1794 description
1795 "If there are too many objects which could be returned by the
1796 filter, this identifies the upper limit of the publisher's
1797 ability to service for this subscription.";
1798 }
1799 leaf kilobytes-estimate {
1800 type uint32;
1801 description
1802 "If the returned information could be beyond the capacity of
1803 the publisher, this would identify the data size which could
1804 result from this filter.";
1805 }
1806 leaf kilobytes-limit {
1807 type uint32;
1808 description
1809 "If the returned information would be beyond the capacity of
1810 the publisher, this identifies the upper limit of the
1811 publisher's ability to service for this subscription.";
1812 }
1813 }
1815 /*
1816 * DATA NODES
1817 */
1819 augment "/sn:establish-subscription/sn:input" {
1820 description
1821 "This augmentation adds additional subscription parameters that
1822 apply specifically to datastore updates to RPC input.";
1823 uses update-policy;
1824 uses update-qos;
1825 }
1826 augment "/sn:establish-subscription/sn:input/sn:target" {
1827 description
1828 "This augmentation adds the datastore as a valid parameter object
1829 for the subscription to RPC input. This provides a target for
1830 the filter.";
1831 case datastore {
1832 uses datastore-criteria;
1833 }
1834 }
1835 augment "/sn:establish-subscription/sn:output/"+
1836 "sn:result/sn:no-success" {
1837 description
1838 "This augmentation adds datastore specific error info
1839 and hints to RPC output.";
1840 uses update-error-hints;
1841 }
1842 augment "/sn:modify-subscription/sn:input" {
1843 description
1844 "This augmentation adds additional subscription parameters
1845 specific to datastore updates.";
1846 uses update-policy-modifiable;
1847 }
1848 augment "/sn:modify-subscription/sn:output/"+
1849 "sn:result/sn:no-success" {
1850 description
1851 "This augmentation adds push datastore error info and hints to
1852 RPC output.";
1853 uses update-error-hints;
1854 }
1856 notification push-update {
1857 description
1858 "This notification contains a push update, containing data
1859 subscribed to via a subscription. This notification is sent for
1860 periodic updates, for a periodic subscription. It can also be
1861 used for synchronization updates of an on-change subscription.
1862 This notification shall only be sent to receivers of a
1863 subscription; it does not constitute a general-purpose
1864 notification.";
1865 leaf subscription-id {
1866 type sn:subscription-id;
1867 mandatory true;
1868 description
1869 "This references the subscription because of which the
1870 notification is sent.";
1871 }
1872 leaf time-of-update {
1873 type yang:date-and-time;
1874 description
1875 "This leaf contains the time of the update.";
1876 }
1877 leaf updates-not-sent {
1878 type empty;
1879 description
1880 "This is a flag which indicates that not all data nodes
1881 subscribed to are included with this update. In other words,
1882 the publisher has failed to fulfill its full subscription
1883 obligations. This may lead to intermittent loss of
1884 synchronization of data at the client. Synchronization at the
1885 client can occur when the next push-update is received.";
1886 }
1887 anydata datastore-contents {
1888 description
1889 "This contains the updated data. It constitutes a snapshot
1890 at the time-of-update of the set of data that has been
1891 subscribed to. The format and syntax of the data
1892 corresponds to the format and syntax of data that would be
1893 returned in a corresponding get operation with the same
1894 filter parameters applied.";
1895 }
1896 }
1897 notification push-change-update {
1898 if-feature "on-change";
1899 description
1900 "This notification contains an on-change push update. This
1901 notification shall only be sent to the receivers of a
1902 subscription; it does not constitute a general-purpose
1903 notification.";
1904 leaf subscription-id {
1905 type sn:subscription-id;
1906 mandatory true;
1907 description
1908 "This references the subscription because of which the
1909 notification is sent.";
1910 }
1911 leaf time-of-update {
1912 type yang:date-and-time;
1913 description
1914 "This leaf contains the time of the update, i.e. the time at
1915 which the change was observed.";
1916 }
1917 leaf updates-not-sent {
1918 type empty;
1919 description
1920 "This is a flag which indicates that not all changes which
1921 have occurred since the last update are included with this
1922 update. In other words, the publisher has failed to
1923 fulfill its full subscription obligations, for example in
1924 cases where it was not able to keep up with a change burst.
1926 To facilitate synchronization, a publisher may subsequently
1927 send a push-update containing a full snapshot of subscribed
1928 data. Such a push-update might also be triggered by a
1929 subscriber requesting an on-demand synchronization.";
1930 }
1931 anydata datastore-changes {
1932 description
1933 "This contains datastore contents that has changed since the
1934 previous update, per the terms of the subscription. Changes
1935 are encoded analogous to the syntax of a corresponding yang-
1936 patch operation, i.e. a yang-patch operation applied to the
1937 YANG datastore implied by the previous update to result in the
1938 current state (and assuming yang-patch could also be applied
1939 to operational data).";
1940 }
1941 }
1943 augment "/sn:subscription-started" {
1944 description
1945 "This augmentation adds many yang datastore specific objects to
1946 the notification that a subscription has started.";
1947 uses update-policy;
1948 uses update-qos;
1949 }
1950 augment "/sn:subscription-started/sn:target" {
1951 description
1952 "This augmentation allows the datastore to be included as part
1953 of the notification that a subscription has started.";
1954 case datastore {
1955 uses datastore-criteria;
1956 }
1957 }
1958 augment "/sn:subscription-modified" {
1959 description
1960 "This augmentation adds many yang datastore specific objects to
1961 the notification that a subscription has been modified.";
1962 uses update-policy;
1963 uses update-qos;
1964 }
1966 augment "/sn:subscription-config/sn:subscription" {
1967 description
1968 "This augmentation adds many yang datastore specific objects
1969 which can be configured as opposed to established via RPC.";
1970 uses update-policy;
1971 uses update-qos;
1972 }
1973 augment "/sn:subscription-config/sn:subscription/sn:target" {
1974 description
1975 "This augmentation adds the datastore to the filtering
1976 criteria for a subscription.";
1977 case datastore {
1978 uses datastore-criteria;
1979 }
1980 }
1981 augment "/sn:subscriptions/sn:subscription" {
1982 yp:notifiable-on-change true;
1983 description
1984 "This augmentation adds many datastore specific objects to a
1985 subscription.";
1986 uses update-policy;
1987 uses update-qos;
1988 }
1989 augment "/sn:subscriptions/sn:subscription/sn:target" {
1990 description
1991 "This augmentation allows the datastore to be displayed as part
1992 of the filtering criteria for a subscription.";
1993 case datastore {
1994 uses datastore-criteria;
1995 }
1996 }
1997 /* YANG Parser Pyang crashing below, due to fixed bug
1998 https://github.com/mbj4668/pyang/issues/300
2000 deviation "/sn:subscriptions/sn:subscription/sn:receivers/"
2001 + "sn:receiver/sn:pushed-notifications" {
2002 deviate add {
2003 yp:notifiable-on-change false;
2004 }
2005 }
2006 deviation "/sn:subscriptions/sn:subscription/sn:receivers/"
2007 + "sn:receiver/sn:excluded-notifications" {
2008 deviate add {
2009 yp:notifiable-on-change false;
2010 }
2011 }
2012 YANG Parser Pyang crashing on the following syntax above */
2013 }
2014
2016 6. IANA Considerations
2018 This document registers the following namespace URI in the "IETF XML
2019 Registry" [RFC3688]:
2021 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push
2022 Registrant Contact: The IESG.
2023 XML: N/A; the requested URI is an XML namespace.
2025 This document registers the following YANG module in the "YANG Module
2026 Names" registry [RFC6020]:
2028 Name: ietf-yang-push
2029 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push
2030 Prefix: yp
2031 Reference: draft-ietf-netconf-yang-push-07.txt (RFC form)
2033 7. Security Considerations
2035 All security considerations from [subscribe] are relevant for
2036 datastores. In addition there are specific security considerations
2037 for receviers defined in Section 3.9
2039 If the access control permissions on subscribed YANG nodes change
2040 during the lifecycle of a subscription, a publisher MUST either
2041 transparently conform to the new access control permissions, or must
2042 terminate or restart the subscriptions so that new access control
2043 permissions are re-established.
2045 The NETCONF Authorization Control Model SHOULD be used to restrict
2046 the delivery of YANG nodes for which the receiver has no access.
2048 8. Acknowledgments
2050 For their valuable comments, discussions, and feedback, we wish to
2051 acknowledge Tim Jenkins, Kent Watsen, Susan Hares, Yang Geng, Peipei
2052 Guo, Michael Scharf, Sharon Chisholm, and Guangying Zheng.
2054 9. References
2056 9.1. Normative References
2058 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
2059 DOI 10.17487/RFC3688, January 2004,
2060 .
2062 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
2063 the Network Configuration Protocol (NETCONF)", RFC 6020,
2064 DOI 10.17487/RFC6020, October 2010,
2065 .
2067 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF)
2068 Base Notifications", RFC 6470, DOI 10.17487/RFC6470,
2069 February 2012, .
2071 [RFC6536bis]
2072 Bierman, A. and M. Bjorklund, "Network Configuration
2073 Protocol (NETCONF) Access Control Model", draft-ietf-
2074 netconf-rfc6536bis-01 (work in progress), March 2017.
2076 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
2077 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016,
2078 .
2080 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
2081 RFC 7950, DOI 10.17487/RFC7950, August 2016,
2082 .
2084 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG",
2085 RFC 7951, DOI 10.17487/RFC7951, August 2016,
2086 .
2088 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch
2089 Media Type", RFC 8072, DOI 10.17487/RFC8072, February
2090 2017, .
2092 [subscribe]
2093 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A.,
2094 and E. Nilsen-Nygaard, "Custom Subscription to Event
2095 Notifications", draft-ietf-netconf-subscribed-
2096 notifications-01 (work in progress), April 2017.
2098 9.2. Informative References
2100 [http-notif]
2101 Voit, E., Gonzalez Prieto, A., Tripathy, A., Nilsen-
2102 Nygaard, E., Clemm, A., and A. Bierman, "Restconf and HTTP
2103 Transport for Event Notifications", March 2017.
2105 [netconf-notif]
2106 Gonzalez Prieto, A., Clemm, A., Voit, E., Tripathy, A.,
2107 Nilsen-Nygaard, E., Chisholm, S., and H. Trevino, "NETCONF
2108 Support for Event Notifications", October 2016.
2110 [notifications2]
2111 Voit, E., Bierman, A., Clemm, A., and T. Jenkins, "YANG
2112 Notification Headers and Bundles", April 2017.
2114 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
2115 and A. Bierman, Ed., "Network Configuration Protocol
2116 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
2117 .
2119 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface
2120 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014,
2121 .
2123 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements
2124 for Subscription to YANG Datastores", RFC 7923,
2125 DOI 10.17487/RFC7923, June 2016,
2126 .
2128 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2129 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
2130 .
2132 Appendix A. Relationships to other drafts
2134 There are other related drafts which are progressing in the NETCONF
2135 WG. This section details the relationship of this draft to those
2136 others.
2138 A.1. ietf-netconf-subscribed-notifications
2140 The draft [subscribe] is the techical foundation around which the
2141 rest of the YANG push datastore specific mechanisms are layered.
2143 A.2. ietf-netconf-netconf-event-notif
2145 The [netconf-notif] draft supports yang-push by defining NETCONF
2146 transport specifics. Included are:
2148 o bindings for RPC communications and Event Notifications over
2149 NETCONF.
2151 o encoded examples
2153 A.3. ietf-netconf-restconf-notif
2155 The [http-notif] draft supports yang-push by defining transport
2156 specific guidance where some form of HTTP is used underneath.
2157 Included are:
2159 o bindings for RPC communications over RESTCONF
2161 o bindings for Event Notifications over HTTP2 and HTTP1.1
2162 o encoded examples
2164 o end-to-end deployment guidance for Call Home and TLS Heartbeat
2166 A.4. voit-notifications2
2168 The draft [notifications2] is not required to implement yang-push.
2169 Instead it defines data plane notification elements which improve the
2170 delivered experience. The following capabilities are specified:
2172 o Defines common encapsulation headers objects to support
2173 functionality such as event severity, message signing, message
2174 loss discovery, message de-duplication, originating process
2175 identification.
2177 o Defines how to bundle multiple event records into a single
2178 notification message.
2180 These capabilities would be delivered by adding the drafts newly
2181 proposed header objects to the push-update and push-change-update
2182 notifications defined here. This draft is not yet adopted by the
2183 NETCONF WG.
2185 Appendix B. Technologies to be considered for future iterations
2187 B.1. Proxy YANG Subscription when the Subscriber and Receiver are
2188 different
2190 The properties of Dynamic and Configured Subscriptions can be
2191 combined to enable deployment models where the Subscriber and
2192 Receiver are different. Such separation can be useful with some
2193 combination of:
2195 o An operator does not want the subscription to be dependent on the
2196 maintenance of transport level keep-alives. (Transport
2197 independence provides different scalability characteristics.)
2199 o There is not a transport session binding, and a transient
2200 Subscription needs to survive in an environment where there is
2201 unreliable connectivity with the Receiver and/or Subscriber.
2203 o An operator wants the Publisher to include highly restrictive
2204 capacity management and Subscription security mechanisms outside
2205 of domain of existing operational or programmatic interfaces.
2207 To build a Proxy Subscription, first the necessary information must
2208 be signaled as part of the . Using this set
2209 of Subscriber provided information; the same process described within
2210 section 3 will be followed.
2212 After a successful establishment, if the Subscriber wishes to track
2213 the state of Receiver subscriptions, it may choose to place a
2214 separate on-change Subscription into the "Subscriptions" subtree of
2215 the YANG Datastore on the Publisher.
2217 B.2. OpState and Filters
2219 Currently there are ongoing discussions to revise the concept of
2220 datastores, allowing for proper handling and distinction of intended
2221 versus applied configurations and extending the notion of a datastore
2222 to operational data. When finalized, the new concept may open up the
2223 possibility for new types of subscription filters, for example,
2224 targeting specific datastores and targeting (potentially) differences
2225 in datatrees across different datastores.
2227 Likewise, it is conceivable that filters are defined that apply to
2228 metadata, such as data nodes for which metadata has been defined that
2229 meets a certain criteria.
2231 Defining any such subscription filters at this point would be highly
2232 speculative in nature. However, it should be noted that
2233 corresponding extensions may be defined in future specifications.
2234 Any such extensions will be straightforward to accommodate by
2235 introducing a model that defines new filter types, and augmenting the
2236 new filter type into the subscription model.
2238 B.3. Splitting push updates
2240 Push updates may become fairly large and extend across multiple
2241 subsystems in a YANG-Push Server. As a result, it conceivable to not
2242 combine all updates into a single update message, but to split
2243 updates into multiple separate update messages. Such splitting could
2244 occur along multiple criteria: limiting the number of data nodes
2245 contained in a single update, grouping updates by subtree, grouping
2246 updates by internal subsystems (e.g., by line card), or grouping them
2247 by other criteria.
2249 Splitting updates bears some resemblance to fragmenting packets. In
2250 effect, it can be seen as fragmenting update messages at an
2251 application level. However, from a transport perspective, splitting
2252 of update messages is not required as long as the transport does not
2253 impose a size limitation or provides its own fragmentation mechanism
2254 if needed. We assume this to be the case for YANG-Push. In the case
2255 of NETCONF, RESTCONF, HTTP/2, no limit on message size is imposed.
2257 In case of other transports, any message size limitations need to be
2258 handled by the corresponding transport mapping.
2260 There may be some scenarios in which splitting updates might still
2261 make sense. For example, if updates are collected from multiple
2262 independent subsystems, those updates could be sent separately
2263 without need for combining. However, if updates were to be split,
2264 other issues arise. Examples include indicating the number of
2265 updates to the receiver, distinguishing a missed fragment from a
2266 missed update, and the ordering with which updates are received.
2267 Proper addressing those issues would result in considerable
2268 complexity, while resulting in only very limited gains. In addition,
2269 if a subscription is found to result in updates that are too large, a
2270 publisher can always reject the request for a subscription while the
2271 subscriber is always free to break a subscription up into multiple
2272 subscriptions.
2274 B.4. Potential Subscription Parameters
2276 A possible is the introduction of an additional parameter "changes-
2277 only" for periodic subscription. Including this flag would results
2278 in sending at the end of each period an update containing only
2279 changes since the last update (i.e. a change-update as in the case of
2280 an on-change subscription), not a full snapshot of the subscribed
2281 information. Such an option might be interesting in case of data
2282 that is largely static and bandwidth-constrained environments.
2284 Appendix C. Issues that are currently being worked and resolved
2286 (To be removed by RFC editor prior to publication)
2288 Issue #6: Data plane notifications and layered headers. Specifically
2289 how do we want to enable standard header unification and bundle
2290 support vs. the data plane notifications currently defined.
2292 Appendix D. Changes between revisions
2294 (To be removed by RFC editor prior to publication)
2296 v06 - v07
2298 o Clarifying text tweaks.
2300 o Clarification that filters act as selectors for subscribed data
2301 nodes; support for value filters not included but possible as a
2302 future extension
2304 o Filters don't have to be matched to existing YANG objects
2305 v05 - v06
2307 o Security considerations updated.
2309 o Base YANG model in [sn] updated as part of move to identities,
2310 YANG augmentations in this doc matched up
2312 o Terms refined and text updates throughout
2314 o Appendix talking about relationship to other drafts added.
2316 o Datastore replaces stream
2318 o Definitions of filters improved
2320 v04 to v05
2322 o Referenced based subscription document changed to Subscribed
2323 Notifications from 5277bis.
2325 o Getting operational data from filters
2327 o Extension notifiable-on-change added
2329 o New appendix on potential futures. Moved text into there from
2330 several drafts.
2332 o Subscription configuration section now just includes changed
2333 parameters from Subscribed Notifications
2335 o Subscription monitoring moved into Subscribed Notifications
2337 o New error and hint mechanisms included in text and in the yang
2338 model.
2340 o Updated examples based on the error definitions
2342 o Groupings updated for consistency
2344 o Text updates throughout
2346 v03 to v04
2348 o Updates-not-sent flag added
2350 o Not notifiable extension added
2352 o Dampening period is for whole subscription, not single objects
2353 o Moved start/stop into rfc5277bis
2355 o Client and Server changed to subscriber, publisher, and receiver
2357 o Anchor time for periodic
2359 o Message format for synchronization (i.e. synch-on-start)
2361 o Material moved into 5277bis
2363 o QoS parameters supported, by not allowed to be modified by RPC
2365 o Text updates throughout
2367 Authors' Addresses
2369 Alexander Clemm
2370 Huawei
2372 Email: ludwig@clemm.org
2374 Eric Voit
2375 Cisco Systems
2377 Email: evoit@cisco.com
2379 Alberto Gonzalez Prieto
2381 Email: albert.gonzalezprieto@yahoo.com
2383 Ambika Prasad Tripathy
2384 Cisco Systems
2386 Email: ambtripa@cisco.com
2388 Einar Nilsen-Nygaard
2389 Cisco Systems
2391 Email: einarnn@cisco.com
2392 Andy Bierman
2393 YumaWorks
2395 Email: andy@yumaworks.com
2397 Balazs Lengyel
2398 Ericsson
2400 Email: balazs.lengyel@ericsson.com