idnits 2.17.1
draft-ietf-netconf-yang-push-12.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** The document seems to lack 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 220: '...hat, a dampening period MAY be used to...'
RFC 2119 keyword, line 247: '...cription request SHOULD be declined if...'
RFC 2119 keyword, line 258: '...-success message SHOULD include in the...'
RFC 2119 keyword, line 286: '... publisher MAY accept an on-change s...'
RFC 2119 keyword, line 298: '...ely, a publisher MAY decide to simply ...'
(47 more instances...)
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Line 846 has weird spacing: '...address ine...'
== Line 912 has weird spacing: '...ro time yan...'
== Line 1032 has weird spacing: '...ntifier sub...'
== Line 1034 has weird spacing: '...-result sub...'
== Line 1037 has weird spacing: '...ntifier sub...'
== (9 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 records for a single subscription MAY NOT be resequenced
prior to transport.
== 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 (December 22, 2017) is 2317 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)
== Outdated reference: A later version (-26) exists of
draft-ietf-netconf-subscribed-notifications-06
== Outdated reference: A later version (-10) exists of
draft-ietf-netmod-revised-datastores-04
== Outdated reference: A later version (-09) exists of
draft-ietf-netconf-rfc6536bis-05
-- 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: 2 errors (**), 0 flaws (~~), 12 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: June 25, 2018 Cisco Systems
6 A. Gonzalez Prieto
7 VMware
8 A. Tripathy
9 E. Nilsen-Nygaard
10 Cisco Systems
11 A. Bierman
12 YumaWorks
13 B. Lengyel
14 Ericsson
15 December 22, 2017
17 YANG Datastore Subscription
18 draft-ietf-netconf-yang-push-12
20 Abstract
22 Via the mechanism described in this document, subscriber applications
23 may request a continuous, customized stream of updates from a YANG
24 datastore. Providing such visibility into changes made upon YANG
25 configuration and operational objects enables new capabilities based
26 on the remote mirroring of configuration and operational state.
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 https://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 June 25, 2018.
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 (https://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 . . . . . . . . . . . . . . . . . . . . . . 4
77 3.1. Subscription Model . . . . . . . . . . . . . . . . . . . 4
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 Selection . . . . . . . . . . . . . . . . . . . 9
83 3.7. Streaming Updates . . . . . . . . . . . . . . . . . . . . 10
84 3.8. Subscription Management . . . . . . . . . . . . . . . . . 12
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 . . . . . . . . . . . . . . . . . . . . . . . . 17
90 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 17
91 4.2. Subscription configuration . . . . . . . . . . . . . . . 25
92 4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 26
93 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 27
94 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 32
95 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47
96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 47
97 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 48
98 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 48
99 9.1. Normative References . . . . . . . . . . . . . . . . . . 48
100 9.2. Informative References . . . . . . . . . . . . . . . . . 49
101 Appendix A. Changes between revisions . . . . . . . . . . . . . 49
102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 52
104 1. Introduction
106 Traditional approaches to remote visibility have been built on
107 polling. With polling, data is periodically requested and retrieved
108 by a client from a server to stay up-to-date. However, there are
109 issues associated with polling-based management:
111 o Polling incurs significant latency. This latency prohibits many
112 application types.
114 o Polling cycles may be missed, requests may be delayed or get lost,
115 often when the network is under stress and the need for the data
116 is the greatest.
118 o Polling requests may undergo slight fluctuations, resulting in
119 intervals of different lengths. The resulting data is difficult
120 to calibrate and compare.
122 o For applications that monitor for changes, many remote polling
123 cycles place ultimately fruitless load on the network, devices,
124 and applications.
126 A more effective alternative to polling is for an application to
127 receive automatic and continuous updates from a targeted subset of a
128 datastore. Accordingly, there is a need for a service that allows
129 applications to subscribe to updates from a datastore and that
130 enables the publisher to push and in effect stream those updates.
131 The requirements for such a service have been documented in
132 [RFC7923].
134 This document defines a corresponding solution that is built on top
135 of "Custom Subscription to Event Streams"
136 [I-D.draft-ietf-netconf-subscribed-notifications]. Supplementing
137 that work are YANG data model augmentations, extended RPCs, and new
138 datastore specific update notifications. Transport options for
139 [I-D.draft-ietf-netconf-subscribed-notifications] will work
140 seamlessly with this solution.
142 2. Definitions and Acronyms
144 The terms below supplement those defined in
145 [I-D.draft-ietf-netconf-subscribed-notifications]. In addition, the
146 term "datastore" is defined in
147 [I-D.draft-ietf-netmod-revised-datastores].
149 Datastore node: An instance of management information in a datastore.
150 Also known as "object".
152 Datastore node update: A data item containing the current value/
153 property of a datastore node at the time the datastore node update
154 was created.
156 Datastore subtree: An instantiated datastore node and the datastore
157 nodes that are hierarchically contained within it.
159 Update record: A representation datastore node update(s) resulting
160 from the application of a selection filter for a subscription. An
161 update record will include the value/property of one or more
162 datastore nodes at a point in time. It may contain the update type
163 for each datastore node (e.g., add, change, delete). Also included
164 may be metadata/headers such as a subscription identifier.
166 Selection filter: Evaluation and/or selection criteria, which may be
167 applied against a targeted set of objects.
169 Update trigger: A mechanism that determines when an update record
170 needs to be generated.
172 YANG-Push: The subscription and push mechanism for datastores that is
173 specified in this document.
175 3. Solution Overview
177 This document specifies a solution for a push update subscription
178 service. This solution supports the dynamic as well as configured
179 subscriptions to information updates from datastores. Subscriptions
180 specify when notification messages should be sent and what data to
181 include in update records. YANG objects are subsequently pushed from
182 the publisher to the receiver per the terms of the subscription.
184 3.1. Subscription Model
186 YANG-push subscriptions are defined using a data model that is itself
187 defined in YANG. This model enhances the subscription model defined
188 in [I-D.draft-ietf-netconf-subscribed-notifications] with
189 capabilities that allow subscribers to subscribe to datastore node
190 updates, specifically to specify the triggers defining when to
191 generate update records as well as what to include in an update
192 record. Key enhancements include:
194 o Specification of selection filters which identify targeted YANG
195 datastore nodes and/or subtrees within a datastore for which
196 updates are to be pushed.
198 o An encoding (using anydata) for the contents of periodic and on-
199 change push updates.
201 o Specification of update policies contain conditions which trigger
202 the generation and pushing of new update records. There are two
203 types of triggers for subscriptions: periodic and on-change.
205 * For periodic subscriptions, the trigger is specified by two
206 parameters that define when updates are to be pushed. These
207 parameters are the period interval with which to report
208 updates, and an anchor time which can be used to calculate at
209 which point in time updates need to be assembled and sent.
211 * For on-change subscriptions, a trigger occurs whenever a change
212 in the subscribed information is detected. Included are
213 additional parameters such as:
215 + Dampening period: In an on-change subscription, detected
216 object changes should be sent as quickly as possible.
217 However it may be undesirable to send a rapid series of
218 object changes. Such behavior has the potential to exhaust
219 of resources in the publisher or receiver. In order to
220 protect against that, a dampening period MAY be used to
221 specify the interval which must pass before successive
222 update records for the same subscription are generated for a
223 receiver. The dampening period collectively applies to the
224 set of all datastore nodes selected by a single subscription
225 and sent to a single receiver. This means that when there
226 is a change to one or more subscribed objects, an update
227 record containing those objects is created either
228 immediately when no dampening period is in effect, or at the
229 end of a dampening period. If multiple changes to a single
230 object occur during a dampening period, only the value that
231 is in effect is included as part of the update record. The
232 dampening period goes into effect every time an update
233 record completes assembly.
235 + Change type: This parameter can be used to reduce the types
236 of datastore changes for which updates are sent (e.g., you
237 might only send when an object is created or deleted, but
238 not when an object value changes).
240 + No Synch on start: defines whether or not a complete push-
241 update of all subscribed data will be sent at the beginning
242 of a subscription. Such early synchronization establishes
243 the frame of reference for subsequent updates.
245 3.2. Negotiation of Subscription Policies
247 A dynamic subscription request SHOULD be declined if a publisher's
248 assessment is that it may be unable to provide update records meeting
249 the terms of the request. In this case, a subscriber may quickly
250 follow up with a new subscription request using different parameters.
252 Random guessing at different parameters by a subscriber is to be
253 discouraged. Therefore, in order to minimize the number of
254 subscription iterations between subscriber and publisher, dynamic
255 subscriptions supports a simple negotiation between subscribers and
256 publishers for subscription parameters. This negotiation is in the
257 form of a no-success response to a failed establish or modify
258 subscription request. The no-success message SHOULD include in the
259 returned error response information that, when considered, increases
260 the likelihood of success for subsequent requests. However, there
261 are no guarantees that subsequent requests for this subscriber will
262 be accepted.
264 [I-D.draft-ietf-netconf-subscribed-notifications] contains several
265 negotiable subscription parameters. Additional yang-push negotiation
266 information defined in this specification includes hints at
267 acceptable time intervals, size estimates for the number or objects
268 which would be returned from a filter, and the location of an error
269 in a provided filter.
271 3.3. On-Change Considerations
273 On-change subscriptions allow subscribers to receive updates whenever
274 changes to targeted objects occur. As such, on-change subscriptions
275 are particularly effective for data that changes infrequently, yet
276 for which applications need to be quickly notified whenever a change
277 does occur with minimal delay.
279 On-change subscriptions tend to be more difficult to implement than
280 periodic subscriptions. Accordingly, on-change subscriptions may not
281 be supported by all implementations or for every object.
283 Whether or not to accept or reject on-change subscription requests
284 when the scope of the subscription contains objects for which on-
285 change is not supported is up to the publisher implementation. A
286 publisher MAY accept an on-change subscription even when the scope of
287 the subscription contains objects for which on-change is not
288 supported. In that case, updates are sent only for those objects
289 within the scope that do support on-change updates whereas other
290 objects are excluded from update records, whether or not their values
291 actually change. In order for a subscriber to determine whether
292 objects support on-change subscriptions, objects are marked
293 accordingly on a publisher. Accordingly, when subscribing, it is the
294 responsibility of the subscriber to ensure it is aware of which
295 objects support on-change and which do not. For more on how objects
296 are so marked, see Section 3.10.
298 Alternatively, a publisher MAY decide to simply reject an on-change
299 subscription in case the scope of the subscription contains objects
300 for which on-change is not supported. In case of a configured
301 subscription, the subscription MAY be suspended.
303 To avoid flooding receivers with repeated updates for subscriptions
304 containing fast-changing objects, or objects with oscillating values,
305 an on-change subscription allows for the definition of a dampening
306 period. Once an update record for a given object is generated, no
307 other updates for this particular subscription will be created until
308 the end of the dampening period. Values sent at the end of the
309 dampening period are the current values of all changed objects which
310 are current at the time the dampening period expires. Changed
311 objects include those which were deleted or newly created during that
312 dampening period. If an object has returned to its original value
313 (or even has been created and then deleted) during the dampening-
314 period, the last change will still be sent. This will indicate churn
315 is occurring on that object.
317 On-change subscriptions can be refined to let users subscribe only to
318 certain types of changes. For example, a subscriber might only want
319 object creations and deletions, but not modifications of object
320 values.
322 Putting it all together, following is the conceptual process for
323 creating an push-change-update notification:
325 1. Just before a change, or at the start of a dampening period,
326 evaluate any filtering and any access control rules. The result
327 is a set "A" of datastore nodes and subtrees.
329 2. Just after a change, or at the end of a dampening period,
330 evaluate any filtering and any (possibly new) access control
331 rules. The result is a set "B" of datastore nodes and subtrees.
333 3. Construct a YANG patch record for going from A to B. If the
334 record is non-empty, send it to the receiver.
336 Note: In cases where a subscriber wants to have separate dampening
337 periods for different objects, multiple subscriptions with different
338 objects in a selection filter can be created.
340 3.4. Promise-Theory Considerations
342 A subscription to updates from a datastore is intended to obviate the
343 need for polling. However, in order to do so, it is critical that
344 subscribers can rely on the subscription and have confidence that
345 they will indeed receive the subscribed updates without having to
346 worry updates being silently dropped. In other words, a subscription
347 constitutes a promise on the side of the publisher to provide the
348 receivers with updates per the terms of the subscription.
350 Now, there are many reasons why a publisher may at some point no
351 longer be able to fulfill the terms of the subscription, even if the
352 subscription had been entered into with good faith. For example, the
353 volume of data objects may be larger than anticipated, the interval
354 may prove too short to send full updates in rapid succession, or an
355 internal problem may prevent objects from being collected. If for
356 some reason the publisher of a subscription is not able to keep its
357 promise, receivers MUST be notified immediately and reliably. The
358 publisher MAY also suspend the subscription.
360 A publisher SHOULD reject a request for a subscription if it is
361 unlikely that the publisher will be able fulfill the terms of that
362 subscription request. In such cases, it is preferable to have a
363 subscriber request a less resource intensive subscription than to
364 deal with frequently degraded behavior.
366 3.5. Data Encodings
368 3.5.1. Periodic Subscriptions
370 In a periodic subscription, the data included as part of an update
371 corresponds to data that could have been read using a retrieval
372 operation over that subscription's transport.
374 3.5.2. On-Change Subscriptions
376 In an on-change subscription, updates need to indicate not only
377 values of changed datastore nodes but also the types of changes that
378 occurred since the last update. Therefore encoding rules for data in
379 on-change updates will generally follow YANG-patch operation as
380 specified in [RFC8072]. The YANG-patch will describe what needs to
381 be applied to the earlier state reported by the preceding update, to
382 result in the now-current state. Note that contrary to [RFC8072],
383 objects encapsulated are not restricted to configuration objects
384 only.
386 However a patch must be able to do more than just describe the delta
387 from the previous state to the current state. As per Section 3.3, it
388 must also be able to identify if transient changes have occurred on
389 an object during a dampening period. To support this, it is valid to
390 encode a YANG patch operation so that its application would result in
391 a no change between the previous and current state. This indicates
392 that some churn has occurred on the object. An example of this would
393 be a patch that does a "create" operation for a datastore node where
394 the receiver believes one already exists, or a "merge" operation
395 which replaces a previous value with the same value. Note that this
396 means that the "create" and "delete" errors described in [RFC8072]
397 section 2.5 are not errors, and are valid operations with YANG push.
399 3.6. Datastore Selection
401 A subscription must specify both the selection filters and the
402 datastore against which these selection filters will be applied.
403 This information is used to choose and subsequently push data from
404 the publisher's datastore to the receivers.
406 Only a single selection filter can be applied to a subscription at a
407 time. The following selection filter types are included in the yang-
408 push data model, and may be applied against a datastore:
410 o subtree: A subtree selection filter identifies one or more
411 datastore subtrees. When specified, update records will only come
412 from the datastore nodes of selected datastore subtree(s). The
413 syntax and semantics correspond to that specified for [RFC6241]
414 section 6.
416 o xpath: An xpath selection filter is an XPath expression that
417 returns a node set. When specified, updates will only come from
418 the selected data nodes.
420 These filters are intended to be used as selectors that define which
421 objects are within the scope of a subscription. A publisher MUST
422 support at least one type of selection filter.
424 Selection filters are not intended to be used for property value
425 filtering for non-key objects. Supporting non-key property value
426 filtering so would have a number of implications that would result in
427 significant complexity. While it is possible to define extensions in
428 the future that will support selection filtering based on values,
429 this is not supported in this version of yang-push and a publisher
430 MAY reject a subscription request that contains a filter for object
431 values.
433 Xpath itself provides powerful filtering constructs, and care must be
434 used in filter definition. As an example, consider an xpath filter
435 with a boolean result; such a result will not provide an easily
436 interpretable subset of a datastore. Beyond the boolean example, it
437 is quite possible to define an xpath filter where results are easy
438 for an application to mis-interpret. Consider an xpath filter which
439 only passes a datastore object when an interface is up. It is up to
440 the receiver to understand implications of the presence or absence of
441 objects in each update.
443 When the set of selection filtering criteria is applied for periodic
444 subscription, all selected datastore nodes for which a receiver has
445 access are provided to a receiver. If the same filtering criteria is
446 applied to an on-change subscription, only the subset of those
447 datastore nodes supporting on-change are provided. A datastore node
448 which doesn't support on-change is never sent as part of an on-change
449 subscription's "push-update" or "push-change-update".
451 3.7. Streaming Updates
453 Contrary to traditional data retrieval requests, datastore
454 subscription enables an unbounded series of update records to be
455 streamed over time. Two generic YANG notifications for update
456 records have been defined for this: "push-update" and "push-change-
457 update".
459 A "push-update" notification defines a complete, filtered update of
460 the datastore per the terms of a subscription. This type of YANG
461 notification is used for continuous updates of periodic
462 subscriptions. A "push-update" notification can also be used for the
463 on-change subscriptions in two cases. First it will be used as the
464 initial "push-update" if there is a need to synchronize the receiver
465 at the start of a new subscription. It also MAY be sent if the
466 publisher later chooses to resynch an on-change subscription. The
467 "push-update" update record contains a data snippet that contains an
468 instantiated datastore subtree with the subscribed contents. The
469 content of the update record is equivalent to the contents that would
470 be obtained had the same data been explicitly retrieved using e.g., a
471 NETCONF "get" operation, with the same filters applied.
473 A "push-change-update" notification is the most common type of update
474 for on-change subscriptions. The update record in this case contains
475 a data snippet that indicates the set of changes that datastore nodes
476 have undergone since the last notification message. In other words,
477 this indicates which datastore nodes have been created, deleted, or
478 have had changes to their values. In cases where multiple changes
479 have occurred and the object has not been deleted, the object's most
480 current value is reported. (In other words, for each object, only
481 one change is reported, not its entire history. Doing so would
482 defeat the purpose of the dampening period.)
484 These new "push-update" or "push-change-update" are encoded and
485 placed within notification messages, and ultimately queued for egress
486 over the specified transport.
488 The following is an example of a notification message for a
489 subscription tracking the operational status of a single Ethernet
490 port (per [RFC7223]). This notification message is encoded XML over
491 NETCONF as per [I-D.draft-ietf-netconf-netconf-event-notifications].
493
494 2017-10-25T08:00:11.22Z
495
496 1011
497
498
499
500 eth0
501 up
502
503
504
505
506
508 Figure 1: Push example
510 The following is an example of an on-change notification message for
511 the same subscription.
513
514 2017-10-25T08:22:33.44Z
515
516 89
517
518
519 1
520
521 edit1
522 merge
523 /ietf-interfaces:interfaces-state
524
525
526
527 eth0
528 down
529
530
531
532
533
534
535
536
538 Figure 2: Push example for on change
540 Of Note in the above example is the 'patch-id' with a value of '1'.
541 Per [RFC8072], the 'patch-id' is an arbitrary string. With YANG
542 Push, the publisher SHOULD put into the 'patch-id' a counter starting
543 at '1' which increments with every 'push-change-update' generated for
544 a subscription. If used as a counter, this counter MUST be reset to
545 '1' anytime a resynchronization occurs (i.e., with the sending of a
546 'push-update'). Also if used as a counter, the counter MUST be reset
547 to '1' the after passing a maximum value of '99999'. Such a
548 mechanism allows easy identification of lost or out-of-sequence
549 update records.
551 3.8. Subscription Management
553 The RPCs defined within
554 [I-D.draft-ietf-netconf-subscribed-notifications] have been enhanced
555 to support datastore subscription negotiation. Included in these
556 enhancements are error codes which can indicate why a datastore
557 subscription attempt has failed.
559 A datastore subscription can be rejected for multiple reasons. This
560 includes a too large subtree request, or the inability of the
561 publisher push update records as frequently as requested. In such
562 cases, no subscription is established. Instead, the subscription-
563 result with the failure reason is returned as part of the RPC
564 response. As part of this response, a set of alternative
565 subscription parameters MAY be returned that would likely have
566 resulted in acceptance of the subscription request. The subscriber
567 may consider these as part of future subscription attempts.
569 For instance, for the following request:
571
573
576
577 ds:operational
578
579
581 /ex:foo
582
583
584 500
585
586
587
589 Figure 3: Establish-Subscription example
591 the publisher might return:
593
595
598 yp:period-unsupported
599
600
601 2000
602
603
605 Figure 4: Error response example
607 As can be seen above the rejected subscription does not result in the
608 generation of an rpc-reply with an rpc-error element. YANG-push
609 specific errors and negotiation hints part are returned as part of
610 normal RPC operations.
612 3.9. Receiver Authorization
614 A receiver of subscription data MUST only be sent updates for which
615 they have proper authorization. A publisher MUST ensure that no non-
616 authorized data is included in push updates. To do so, it needs to
617 apply all corresponding checks applicable at the time of a specific
618 pushed update and if necessary silently remove any non-authorized
619 data from datastore subtrees. This enables YANG data pushed based on
620 subscriptions to be authorized equivalently to a regular data
621 retrieval (get) operation.
623 A publisher MUST allow for the possibility that a subscription's
624 selection filter references non-existent or access-protected data.
625 Such support permits a receiver the ability to monitor the entire
626 lifecyle of some datastore tree. In this case, all "push-update"
627 notifications must be sent empty, and no "push-change-update"
628 notifications will be sent until some data becomes visible for a
629 receiver.
631 A publisher MAY choose reject an establish-subscription request which
632 selects non-existent or access-protected data. In addition, a
633 publisher MAY choose to terminate a dynamic subscription or suspend a
634 configured receiver when the authorization privileges of a receiver
635 change, or the access controls for subscribed objects change. Such a
636 capability enables the publisher to avoid having to support a
637 continuous, and total filtering of an entire subscription's content.
639 In these cases above, the error identity "data-unavailable" SHOULD be
640 returned. This reduces the possibility of leakage of access
641 controlled objects.
643 The conceptual authorization model for datastores is the NETCONF
644 Access Control Model [RFC6536bis], Section 3.2.4. A clarification to
645 this is that each of the individual nodes in a resulting update
646 record MUST also have applied access control to resulting pushed
647 messages. This includes validating that read access is ok for any
648 nodes newly selected since the last update record for each receiver.
650 +-----------------+ +--------------------+
651 push-update or --> | datastore node | yes | add datastore node |
652 push-change-update | access allowed? | ---> | to update message |
653 +-----------------+ +--------------------+
655 Figure 5: Access control for push updates
657 If read access into previously accessible nodes has been lost due to
658 a receiver permissions change, this SHOULD be reported as a patch
659 "delete" operation for on-change subscriptions. If not capable of
660 handling such receiver permission changes with such a "delete",
661 publisher implementations MUST force dynamic subscription re-
662 establishment or configured subscription re-initialization so that
663 appropriate filtering is installed.
665 3.10. On-change Notifiable YANG objects
667 In some cases, a publisher supporting on-change notifications may not
668 be able to push updates for some object types on-change. Reasons for
669 this might be that the value of the datastore node changes frequently
670 (e.g., [RFC7223]'s in-octets counter), that small object changes are
671 frequent and meaningless (e.g., a temperature gauge changing 0.1
672 degrees), or that the implementation is not capable of on-change
673 notification for a particular object.
675 Support for on-change notification is specific to the individual YANG
676 model and/or implementation, and is useful to define in design time.
677 System integrators need this information (without reading any data
678 from a live node).
680 The default assumption is that no datastore nodes support on-change
681 notification. Schema nodes and subtrees that support on-change
682 notifications MUST be marked by accordingly with the YANG extension
683 "notifiable-on-change". This extension is defined in the data model
684 below.
686 When an on-change subscription is established, data-nodes are
687 automatically excluded unless they are marked with notifiable-on-
688 change as true. This also means that authorization checks SHALL NOT
689 be performed on them. A subscriber can identify which nodes may be
690 included in on-change updates by retrieving the datastore nodes in
691 the subscription's scope and checking for which notifiable-on-change
692 is marked as true.
694 In theory, adding "notifiable-on-change" markings can be done within
695 corresponding YANG models. But a more extensible way to avoid having
696 to modify existing module definitions is to add "notifiable-on-
697 change" markings within separate module deviations. This means that
698 when a YANG model designer wants to add a "notifiable-on-change"
699 marking to nodes of an existing module without modifying the module
700 definitions, a new module is introduced that contains deviation
701 statements which add "notifiable-on-change" statements as applicable.
703 deviation /sys:system/sys:system-time {
704 deviate add {
705 yp:notifiable-on-change false;
706 }
707 }
709 Figure 6: Deviation Example
711 3.11. Other Considerations
713 3.11.1. Robustness and reliability
715 Particularly in the case of on-change updates, it is important that
716 these updates do not get lost. Or in case the loss of an update is
717 unavoidable, it is critical that the receiver is notified
718 accordingly.
720 Update records for a single subscription MAY NOT be resequenced prior
721 to transport.
723 It is conceivable that under certain circumstances, a publisher will
724 recognize that it is unable to include within an update record the
725 full set of objects desired per the terms of a subscription. In this
726 case, the publisher MUST take one or more of the following actions.
728 o A publisher MUST set the "updates-not-sent" flag on any update
729 record which is known to be missing information.
731 o It MAY choose to suspend a subscription as per
732 [I-D.draft-ietf-netconf-subscribed-notifications].
734 o When resuming an on-change subscription, the publisher SHOULD
735 generate a complete patch from the previous update record. If
736 this is not possible and the "no-synch-on-start" option is not
737 present for the subscription, then the full datastore contents MAY
738 be sent via a "push-update" instead (effectively replacing the
739 previous contents). If neither of these are possible, then an
740 "updates-not-sent" flag MUST be included on the next "push-change-
741 update".
743 Note: It is perfectly acceptable to have a series of "push-change-
744 update" notifications (and even "push update" notifications) serially
745 queued at the transport layer awaiting transmission. It is not
746 required to merge pending update messages. I.e., the dampening
747 period applies to update record creation, not transmission.
749 3.11.2. Publisher capacity
751 It is far preferable to decline a subscription request than to accept
752 such a request when it cannot be met.
754 Whether or not a subscription can be supported will be determined by
755 a combination of several factors such as the subscription trigger
756 (on-change or periodic), the period in which to report changes (one
757 second periods will consume more resources than one hour periods),
758 the amount of data in the datastore subtree that is being subscribed
759 to, and the number and combination of other subscriptions that are
760 concurrently being serviced.
762 4. A YANG data model for management of datastore push subscriptions
764 4.1. Overview
766 The YANG data model for datastore push subscriptions is depicted in
767 the following figure. Following YANG tree convention in the
768 depiction, brackets enclose list keys, "rw" means configuration, "ro"
769 operational state data, "?" designates optional nodes, "*" designates
770 nodes that can have multiple instances. Parentheses with a name in
771 the middle enclose choice and case nodes. New schema objects defined
772 here (i.e., beyond those from
773 [I-D.draft-ietf-netconf-subscribed-notifications]) are identified
774 with "yp".
776 module: ietf-subscribed-notifications
777 +--rw streams
778 | +--rw stream* [name]
779 | +--rw name string
780 | +--rw description string
781 | +--rw replay-support? empty {replay}?
782 | +--rw replay-log-creation-time? yang:date-and-time {replay}?
783 | +--rw replay-log-aged-time? yang:date-and-time {replay}?
784 +--rw filters
785 | +--rw stream-filter* [identifier]
786 | | +--rw identifier filter-id
787 | | +--rw (filter-spec)?
788 | | +--:(stream-subtree-filter)
789 | | | +--rw stream-subtree-filter? {subtree}?
790 | | +--:(stream-xpath-filter)
791 | | +--rw stream-xpath-filter? yang:xpath1.0 {xpath}?
792 | +--rw yp:selection-filter* [identifier]
793 | +--rw yp:identifier sn:filter-id
794 | +--rw (yp:filter-spec)?
795 | +--:(yp:datastore-subtree-filter)
796 | | +--rw yp:datastore-subtree-filter? {sn:subtree}?
797 | +--:(yp:datastore-xpath-filter)
798 | +--rw yp:datastore-xpath-filter?
799 | yang:xpath1.0 {sn:xpath}?
800 +--rw subscription-config {configured}?
801 | +--rw subscription* [identifier]
802 | +--rw identifier subscription-id
803 | +--rw purpose? string
804 | +--rw protocol transport {configured}?
805 | +--rw encoding encoding
806 | +--rw (target)
807 | | +--:(stream)
808 | | | +--rw (stream-filter)?
809 | | | | +--:(by-reference)
810 | | | | | +--rw stream-filter-ref stream-filter-ref
811 | | | | +--:(within-subscription)
812 | | | | +--rw (filter-spec)?
813 | | | | +--:(stream-subtree-filter)
814 | | | | | +--rw stream-subtree-filter? {subtree}?
815 | | | | +--:(stream-xpath-filter)
816 | | | | +--rw stream-xpath-filter?
817 | | | | yang:xpath1.0 {sn:xpath}?
818 | | | +--rw stream? stream-ref
819 | | | +--rw replay-start-time? yang:date-and-time {replay}?
820 | | +--:(yp:datastore)
821 | | +--rw yp:datastore identityref
822 | | +--rw (yp:selected-content)?
823 | | +--:(yp:by-reference)
824 | | | +--rw yp:selection-filter-ref selection-filter-ref
825 | | +--:(yp:within-subscription)
826 | | +--rw (yp:filter-spec)?
827 | | +--:(yp:datastore-subtree-filter)
828 | | | +--rw yp:datastore-subtree-filter?
829 | | {sn:subtree}?
830 | | +--:(yp:datastore-xpath-filter)
831 | | +--rw yp:datastore-xpath-filter?
832 | | yang:xpath1.0 {sn:xpath}?
833 | +--rw stop-time? yang:date-and-time
834 | +--rw dscp? inet:dscp {qos}?
835 | +--rw weighting? uint8 {qos}?
836 | +--rw dependency? sn:subscription-id {qos}?
837 | +--rw (notification-message-origin)?
838 | | +--:(interface-originated)
839 | | | +--rw source-interface? if:interface-ref
840 | | +--:(address-originated)
841 | | +--rw source-vrf? -> /ni:network-instances/
842 | | network-instance/name {supports-vrf}?
843 | | +--rw source-address? inet:ip-address-no-zone
844 | +--rw receivers
845 | | +--rw receiver* [address port]
846 | | +--rw address inet:host
847 | | +--rw port inet:port-number
848 | +--rw (yp:update-trigger)
849 | +--:(yp:periodic)
850 | | +--rw yp:periodic!
851 | | +--rw yp:period yang:timeticks
852 | | +--rw yp:anchor-time? yang:date-and-time
853 | +--:(yp:on-change) {on-change}?
854 | +--rw yp:on-change!
855 | +--rw yp:dampening-period? yang:timeticks
856 | +--rw yp:no-synch-on-start? empty
857 | +--rw yp:excluded-change* change-type
858 +--ro subscriptions
859 +--ro subscription* [identifier]
860 +--ro identifier subscription-id
861 +--ro configured-subscription-state? enumeration {configured}?
862 +--ro purpose? string {configured}?
863 +--ro protocol transport {configured}?
864 +--ro encoding encoding
865 +--ro (target)
866 | +--:(stream)
867 | | +--ro (stream-filter)?
868 | | | +--:(by-reference)
869 | | | | +--ro stream-filter-ref stream-filter-ref
870 | | | +--:(within-subscription)
871 | | | +--ro (filter-spec)?
872 | | | +--:(stream-subtree-filter)
873 | | | | +--ro stream-subtree-filter? {subtree}?
874 | | | +--:(stream-xpath-filter)
875 | | | +--ro stream-xpath-filter?
876 | | | yang:xpath1.0 {sn:xpath}?
877 | | +--ro stream? stream-ref
878 | | +--ro replay-start-time? yang:date-and-time {replay}?
879 | +--:(yp:datastore)
880 | +--ro yp:datastore identityref
881 | +--ro (yp:selected-content)?
882 | +--:(yp:by-reference)
883 | | +--ro yp:selection-filter-ref selection-filter-ref
884 | +--:(yp:within-subscription)
885 | +--ro (yp:filter-spec)?
886 | +--:(yp:datastore-subtree-filter)
887 | | +--ro yp:datastore-subtree-filter?
888 | {sn:subtree}?
889 | +--:(yp:datastore-xpath-filter)
890 | +--ro yp:datastore-xpath-filter?
891 | yang:xpath1.0 {sn:xpath}?
892 +--ro stop-time? yang:date-and-time
893 +--ro dscp? inet:dscp {qos}?
894 +--ro weighting? uint8 {qos}?
895 +--ro dependency? sn:subscription-id {qos}?
896 +--ro (notification-message-origin)?
897 | +--:(interface-originated)
898 | | +--ro source-interface? if:interface-ref
899 | +--:(address-originated)
900 | +--ro source-vrf? -> /ni:network-instances/
901 | | network-instance/name {supports-vrf}?
902 | +--ro source-address? inet:ip-address-no-zone
903 +--ro receivers
904 | +--ro receiver* [address port]
905 | +--ro address inet:host
906 | +--ro port inet:port-number
907 | +--ro pushed-notifications? yang:counter64
908 | +--ro excluded-notifications? yang:counter64
909 | +--ro status enumeration
910 | +---x reset
911 | +--ro output
912 | +--ro time yang:date-and-time
913 +--ro (yp:update-trigger)
914 +--:(yp:periodic)
915 | +--ro yp:periodic!
916 | +--ro yp:period yang:timeticks
917 | +--ro yp:anchor-time? yang:date-and-time
918 +--:(yp:on-change) {on-change}?
919 +--ro yp:on-change!
920 +--ro yp:dampening-period? yang:timeticks
921 +--ro yp:no-synch-on-start? empty
922 +--ro yp:excluded-change* change-type
924 rpcs:
925 +---x establish-subscription
926 | +---w input
927 | | +---w encoding? encoding
928 | | +---w (target)
929 | | | +--:(stream)
930 | | | | +---w (stream-filter)?
931 | | | | | +--:(by-reference)
932 | | | | | | +---w stream-filter-ref stream-filter-ref
933 | | | | | +--:(within-subscription)
934 | | | | | +---w (filter-spec)?
935 | | | | | +--:(stream-subtree-filter)
936 | | | | | | +---w stream-subtree-filter? {subtree}?
937 | | | | | +--:(stream-xpath-filter)
938 | | | | | +---w stream-xpath-filter?
939 | | | | | yang:xpath1.0 {sn:xpath}?
940 | | | | +---w stream? stream-ref
941 | | | | +---w replay-start-time? yang:date-and-time {replay}?
942 | | | +--:(yp:datastore)
943 | | | +---w yp:datastore identityref
944 | | | +---w (yp:selected-content)?
945 | | | +--:(yp:by-reference)
946 | | | | +---w yp:selection-filter-ref selection-filter-ref
947 | | | +--:(yp:within-subscription)
948 | | | +---w (yp:filter-spec)?
949 | | | +--:(yp:datastore-subtree-filter)
950 | | | | +---w yp:datastore-subtree-filter?
951 | | | | {sn:subtree}?
952 | | | +--:(yp:datastore-xpath-filter)
953 | | | +---w yp:datastore-xpath-filter?
954 | | | yang:xpath1.0 {sn:xpath}?
955 | | +---w stop-time? yang:date-and-time
956 | | +---w dscp? inet:dscp {qos}?
957 | | +---w weighting? uint8 {qos}?
958 | | +---w dependency? sn:subscription-id {qos}?
959 | | +---w (yp:update-trigger)
960 | | +--:(yp:periodic)
961 | | | +---w yp:periodic!
962 | | | +---w yp:period yang:timeticks
963 | | | +---w yp:anchor-time? yang:date-and-time
964 | | +--:(yp:on-change) {on-change}?
965 | | +---w yp:on-change!
966 | | +---w yp:dampening-period? yang:timeticks
967 | | +---w yp:no-synch-on-start? empty
968 | | +---w yp:excluded-change* change-type
969 | +--ro output
970 | +--ro subscription-result subscription-result
971 | +--ro (result)?
972 | +--:(no-success)
973 | | +--ro filter-failure? string
974 | | +--ro replay-start-time-hint? yang:date-and-time
975 | | +--ro yp:period-hint? yang:timeticks
976 | | +--ro yp:error-path? string
977 | | +--ro yp:object-count-estimate? uint32
978 | | +--ro yp:object-count-limit? uint32
979 | | +--ro yp:kilobytes-estimate? uint32
980 | | +--ro yp:kilobytes-limit? uint32
981 | +--:(success)
982 | +--ro identifier subscription-id
983 +---x modify-subscription
984 | +---w input
985 | | +---w identifier? subscription-id
986 | | +---w (target)
987 | | | +--:(stream)
988 | | | | +---w (stream-filter)?
989 | | | | +--:(by-reference)
990 | | | | | +---w stream-filter-ref stream-filter-ref
991 | | | | +--:(within-subscription)
992 | | | | +---w (filter-spec)?
993 | | | | +--:(stream-subtree-filter)
994 | | | | | +---w stream-subtree-filter? {subtree}?
995 | | | | +--:(stream-xpath-filter)
996 | | | | +---w stream-xpath-filter?
997 | | | | yang:xpath1.0 {sn:xpath}?
998 | | | +--:(yp:datastore)
999 | | | +---w (yp:selected-content)?
1000 | | | +--:(yp:by-reference)
1001 | | | | +---w yp:selection-filter-ref selection-filter-ref
1002 | | | +--:(yp:within-subscription)
1003 | | | +---w (yp:filter-spec)?
1004 | | | +--:(yp:datastore-subtree-filter)
1005 | | | | +---w yp:datastore-subtree-filter?
1006 | | | | {sn:subtree}?
1007 | | | +--:(yp:datastore-xpath-filter)
1008 | | | +---w yp:datastore-xpath-filter?
1009 | | | yang:xpath1.0 {sn:xpath}?
1010 | | +---w stop-time? yang:date-and-time
1011 | | +---w (yp:update-trigger)
1012 | | +--:(yp:periodic)
1013 | | | +---w yp:periodic!
1014 | | | +---w yp:period yang:timeticks
1015 | | | +---w yp:anchor-time? yang:date-and-time
1016 | | +--:(yp:on-change) {on-change}?
1017 | | +---w yp:on-change!
1018 | | +---w yp:dampening-period? yang:timeticks
1019 | +--ro output
1020 | +--ro subscription-result subscription-result
1021 | +--ro (result)?
1022 | +--:(no-success)
1023 | +--ro filter-failure? string
1024 | +--ro yp:period-hint? yang:timeticks
1025 | +--ro yp:error-path? string
1026 | +--ro yp:object-count-estimate? uint32
1027 | +--ro yp:object-count-limit? uint32
1028 | +--ro yp:kilobytes-estimate? uint32
1029 | +--ro yp:kilobytes-limit? uint32
1030 +---x delete-subscription
1031 | +---w input
1032 | | +---w identifier subscription-id
1033 | +--ro output
1034 | +--ro subscription-result subscription-result
1035 +---x kill-subscription
1036 +---w input
1037 | +---w identifier subscription-id
1038 +--ro output
1039 +--ro subscription-result subscription-result
1041 notifications:
1042 +---n replay-completed {replay}?
1043 | +--ro identifier subscription-id
1044 +---n subscription-completed
1045 | +--ro identifier subscription-id
1046 +---n subscription-started {configured}?
1047 | +--ro identifier subscription-id
1048 | +--ro protocol transport {configured}?
1049 | +--ro encoding encoding
1050 | +--ro (target)
1051 | | +--:(stream)
1052 | | | +--ro (stream-filter)?
1053 | | | | +--:(by-reference)
1054 | | | | | +--ro stream-filter-ref stream-filter-ref
1055 | | | | +--:(within-subscription)
1056 | | | | +--ro (filter-spec)?
1057 | | | | +--:(stream-subtree-filter)
1058 | | | | | +--ro stream-subtree-filter? {subtree}?
1059 | | | | +--:(stream-xpath-filter)
1060 | | | | +--ro stream-xpath-filter?
1061 | | | | yang:xpath1.0 {sn:xpath}?
1062 | | | +--ro stream? stream-ref
1063 | | | +--ro replay-start-time? yang:date-and-time {replay}?
1064 | | +--:(yp:datastore)
1065 | | +--ro yp:datastore identityref
1066 | | +--ro (yp:selected-content)?
1067 | | +--:(yp:by-reference)
1068 | | | +--ro yp:selection-filter-ref selection-filter-ref
1069 | | +--:(yp:within-subscription)
1070 | | +--ro (yp:filter-spec)?
1071 | | +--:(yp:datastore-subtree-filter)
1072 | | | +--ro yp:datastore-subtree-filter?{sn:subtree}?
1073 | | +--:(yp:datastore-xpath-filter)
1074 | | +--ro yp:datastore-xpath-filter?
1075 | | yang:xpath1.0 {sn:xpath}?
1076 | +--ro stop-time? yang:date-and-time
1077 | +--ro dscp? inet:dscp {qos}?
1078 | +--ro weighting? uint8 {qos}?
1079 | +--ro dependency? sn:subscription-id {qos}?
1080 | +--ro (yp:update-trigger)
1081 | +--:(yp:periodic)
1082 | | +--ro yp:periodic!
1083 | | +--ro yp:period yang:timeticks
1084 | | +--ro yp:anchor-time? yang:date-and-time
1085 | +--:(yp:on-change) {on-change}?
1086 | +--ro yp:on-change!
1087 | +--ro yp:dampening-period? yang:timeticks
1088 | +--ro yp:no-synch-on-start? empty
1089 | +--ro yp:excluded-change* change-type
1090 +---n subscription-resumed
1091 | +--ro identifier subscription-id
1092 +---n subscription-modified
1093 | +--ro identifier subscription-id
1094 | +--ro protocol transport {configured}?
1095 | +--ro encoding encoding
1096 | +--ro (target)
1097 | | +--:(stream)
1098 | | | +--ro (stream-filter)?
1099 | | | | +--:(by-reference)
1100 | | | | | +--ro stream-filter-ref stream-filter-ref
1101 | | | | +--:(within-subscription)
1102 | | | | +--ro (filter-spec)?
1103 | | | | +--:(stream-subtree-filter)
1104 | | | | | +--ro stream-subtree-filter? {subtree}?
1105 | | | | +--:(stream-xpath-filter)
1106 | | | | +--ro stream-xpath-filter?
1107 | | | | yang:xpath1.0 {sn:xpath}?
1108 | | | +--ro stream? stream-ref
1109 | | | +--ro replay-start-time? yang:date-and-time {replay}?
1110 | | +--:(yp:datastore)
1111 | | +--ro yp:datastore identityref
1112 | | +--ro (yp:selected-content)?
1113 | | +--:(yp:by-reference)
1114 | | | +--ro yp:selection-filter-ref selection-filter-ref
1115 | | +--:(yp:within-subscription)
1116 | | +--ro (yp:filter-spec)?
1117 | | +--:(yp:datastore-subtree-filter)
1118 | | | +--ro yp:datastore-subtree-filter?{sn:subtree}?
1119 | | +--:(yp:datastore-xpath-filter)
1120 | | +--ro yp:datastore-xpath-filter?
1121 | | yang:xpath1.0 {sn:xpath}?
1122 | +--ro stop-time? yang:date-and-time
1123 | +--ro dscp? inet:dscp {qos}?
1124 | +--ro weighting? uint8 {qos}?
1125 | +--ro dependency? sn:subscription-id {qos}?
1126 | +--ro (yp:update-trigger)
1127 | +--:(yp:periodic)
1128 | | +--ro yp:periodic!
1129 | | +--ro yp:period yang:timeticks
1130 | | +--ro yp:anchor-time? yang:date-and-time
1131 | +--:(yp:on-change) {on-change}?
1132 | +--ro yp:on-change!
1133 | +--ro yp:dampening-period? yang:timeticks
1134 | +--ro yp:no-synch-on-start? empty
1135 | +--ro yp:excluded-change* change-type
1136 +---n subscription-terminated
1137 | +--ro identifier subscription-id
1138 | +--ro error-id subscription-errors
1139 | +--ro filter-failure? string
1140 +---n subscription-suspended
1141 +--ro identifier subscription-id
1142 +--ro error-id subscription-errors
1143 +--ro filter-failure? string
1145 module: ietf-yang-push
1147 rpcs:
1148 +---x resynch-subscription {on-change}?
1149 +---w input
1150 | +---w identifier sn:subscription-id
1151 +--ro output
1152 +--ro subscription-result sn:subscription-result
1154 notifications:
1155 +---n push-update
1156 | +--ro subscription-id? sn:subscription-id
1157 | +--ro updates-not-sent? empty
1158 | +--ro datastore-contents?
1159 +---n push-change-update {on-change}?
1160 +--ro subscription-id? sn:subscription-id
1161 +--ro updates-not-sent? empty
1162 +--ro datastore-changes?
1164 Figure 7: Model structure
1166 Selected components of the model are summarized below.
1168 4.2. Subscription configuration
1170 Both configured and dynamic subscriptions are represented within the
1171 list subscription. But only configured subscriptions are listed
1172 within list subscription-config. In both lists, each subscription
1173 has own list elements. New and enhanced parameters extending the
1174 basic subscription data model in
1175 [I-D.draft-ietf-netconf-subscribed-notifications] include:
1177 o The targeted datastore from which the selection is being made.
1178 The potential datastores include those from
1180 [I-D.draft-ietf-netmod-revised-datastores]. A platform may also
1181 choose to support a custom datastore.
1183 o A selection filter identifying yang nodes of interest within a
1184 datastore. Filter contents are specified via a reference to an
1185 existing filter, or via an in-line definition for only that
1186 subscription. Referenced filters allows an implementation to
1187 avoid evaluating filter acceptability during a dynamic
1188 subscription request. The case statement differentiates the
1189 options.
1191 o For periodic subscriptions, triggered updates will occur at the
1192 boundaries of a specified time interval. These boundaries many be
1193 calculated from the periodic parameters:
1195 * a "period" which defines duration between period push updates.
1197 * an "anchor-time"; update intervals always fall on the points in
1198 time that are a multiple of a "period" from an "anchor-time".
1199 If "anchor-time" is not provided, then the "anchor-time" MUST
1200 be set with the creation time of the initial update record.
1202 o For on-change subscriptions, assuming any dampening period has
1203 completed, triggering occurs whenever a change in the subscribed
1204 information is detected. On-change subscriptions have more
1205 complex semantics that is guided by its own set of parameters:
1207 * a "dampening-period" specifies the interval that must pass
1208 before a successive update for the subscription is sent. If no
1209 dampening period is in effect, the update is sent immediately.
1210 If a subsequent change is detected, another update is only sent
1211 once the dampening period has passed for this subscription.
1213 * an "excluded-change" flag which allows restriction of the types
1214 of changes for which updates should be sent (e.g., only add to
1215 an update record on object creation).
1217 * a "no-synch-on-start" flag which specifies whether a complete
1218 update with all the subscribed data is to be sent at the
1219 beginning of a subscription.
1221 4.3. YANG Notifications
1223 4.3.1. State Change Notifications
1225 Subscription state notifications and mechanism are reused from
1226 [I-D.draft-ietf-netconf-subscribed-notifications]. Some have been
1227 augmented to include the datastore specific objects.
1229 4.3.2. Notifications for Subscribed Content
1231 Along with the subscribed content, there are other objects which
1232 might be part of a "push-update" or "push-change-update"
1234 A "subscription-id" MUST be transported along with the subscribed
1235 contents. An [RFC5277] Section 4 one-way notification MAY be used
1236 for encoding updates. Where it is, the relevant "subscription-id"
1237 MUST be encoded as the first element within each "push-update" or
1238 "push-change-update". This allows a receiver to differentiate which
1239 subscription resulted in a particular push.
1241 A "time-of-update" which represents the time an update record
1242 snapshot was generated. A receiver MAY assume that a publisher's
1243 objects have these pushed values at this point in time.
1245 An "updates-not-sent" object. This object indicates that not all
1246 changes which have occurred since the last update are actually
1247 included with this update. In other words, the publisher has failed
1248 to fulfill its full subscription obligations. (For example a
1249 datastore was unable to providing the full set of datastore nodes to
1250 a publisher process.) To facilitate re-synchronization of on-change
1251 subscriptions, a publisher MAY subsequently send a "push-update"
1252 containing a full selection snapshot of subscribed data.
1254 4.4. YANG RPCs
1256 YANG-Push subscriptions are established, modified, and deleted using
1257 RPCs augmented from
1258 [I-D.draft-ietf-netconf-subscribed-notifications].
1260 4.4.1. Establish-subscription RPC
1262 The subscriber sends an establish-subscription RPC with the
1263 parameters in section 3.1. An example might look like:
1265
1267
1270
1271
1272 ds:operational
1273
1274
1277
1278
1279 500
1280
1281
1282
1284 Figure 8: Establish-subscription RPC
1286 The publisher MUST respond explicitly positively (i.e., subscription
1287 accepted) or negatively (i.e., subscription rejected) to the request.
1288 Positive responses include the "identifier" of the accepted
1289 subscription. In that case a publisher MAY respond:
1291
1293
1295 ok
1296
1297
1299 52
1300
1301
1303 Figure 9: Establish-subscription positive RPC response
1305 A subscription can be rejected for multiple reasons, including the
1306 lack of authorization to establish a subscription, no capacity to
1307 serve the subscription at the publisher, or the inability of the
1308 publisher to select datastore content at the requested cadence.
1310 If a request is rejected because the publisher is not able to serve
1311 it, the publisher SHOULD include in the returned error hints ar what
1312 subscription parameters might have been accepted for the request.
1314 However, there are no guarantee that subsequent requests using this
1315 info will in fact be accepted.
1317 For example, for the following request:
1319
1321
1324
1326 ds:operational
1327
1328
1330 /ex:foo
1331
1332
1333 10
1334
1335
1336
1338 Figure 10: Establish-subscription request example 2
1340 a publisher that cannot serve on-change updates but periodic updates
1341 might return the following:
1343
1345
1348 yp:period-unsupported
1349
1350
1351 100
1352
1353
1355 Figure 11: Establish-subscription error response example 2
1357 4.4.2. Modify-subscription RPC
1359 The subscriber MAY invoke the "modify-subscription" RPC for a
1360 subscription it previously established. The subscriber will include
1361 newly desired values in the "modify-subscription" RPC. Parameters
1362 not included MUST remain unmodified. Below is an example where a
1363 subscriber attempts to modify the "period" of a subscription.
1365
1367
1370 1011
1371
1373 ds:operational
1374
1375
1377 /ex:bar
1378
1379
1380 250
1381
1382
1383
1385 Figure 12: Modify subscription request
1387 The publisher MUST respond explicitly positively or negatively to the
1388 request. A response to a successful modification might look like:
1390
1392
1394 ok
1395
1396
1398 Figure 13: Modify subscription response
1400 If the subscription modification is rejected, the publisher MUST send
1401 a response like it does for an "establish-subscription" and maintain
1402 the subscription as it was before the modification request.
1403 Responses MAY include hints. A subscription MAY be modified multiple
1404 times.
1406 A configured subscription cannot be modified using "modify-
1407 subscription" RPC. Instead, the configuration needs to be edited as
1408 needed.
1410 4.4.3. Delete-subscription RPC
1412 To stop receiving updates from a subscription and effectively delete
1413 a subscription that had previously been established using an
1414 "establish-subscription" RPC, a subscriber can send a "delete-
1415 subscription" RPC, which takes as only input the subscription's
1416 "identifier".
1418 Configured subscriptions cannot be deleted via RPC, but have to be
1419 removed from the configuration. This RPC is identical to the RPC
1420 from [I-D.draft-ietf-netconf-subscribed-notifications].
1422 4.4.4. Resynch-subscription RPC
1424 This RPC is only applicable only for on-change subscriptions
1425 previously been established using an "establish-subscription" RPC.
1426 On receipt, a publisher must either reply "ok" and quickly follow
1427 with a "push-update", or send an appropriate error such as "on-
1428 change-synch-unsupported". For example:
1430
1432
1435 1011
1436
1437
1439
1441
1444 sn:ok
1445
1446
1448 Resynch subscription
1450 4.4.5. YANG Module Synchronization
1452 To make subscription requests, the subscriber needs to know the YANG
1453 module library available on the publisher. The YANG 1.0 module
1454 library information is sent by a NETCONF server in the NETCONF
1455 "hello" message. For YANG 1.1 modules and all modules used with the
1456 RESTCONF [RFC8040] protocol, this information is provided by the YANG
1457 Library module (ietf-yang-library.yang from [RFC7895]. This YANG
1458 library information is important for the receiver to reproduce the
1459 set of object definitions used within the publisher.
1461 The YANG library includes a module list with the name, revision,
1462 enabled features, and applied deviations for each YANG module
1463 implemented by the publisher. The receiver is expected to know the
1464 YANG library information before starting a subscription. The
1465 "/modules-state/module-set-id" leaf in the "ietf-yang-library" module
1466 can be used to cache the YANG library information.
1468 The set of modules, revisions, features, and deviations can change at
1469 run-time (if supported by the publisher implementation). In this
1470 case, the receiver needs to be informed of module changes before
1471 datastore nodes from changed modules can be processed correctly. The
1472 YANG library provides a simple "yang-library-change" notification
1473 that informs the subscriber that the library has changed. The
1474 receiver then needs to re-read the entire YANG library data for the
1475 replicated publisher in order to detect the specific YANG library
1476 changes. The "ietf-netconf-notifications" module defined in
1477 [RFC6470] contains a "netconf-capability-change" notification that
1478 can identify specific module changes. For example, the module URI
1479 capability of a newly loaded module will be listed in the "added-
1480 capability" leaf-list, and the module URI capability of an removed
1481 module will be listed in the "deleted-capability" leaf-list.
1483 5. YANG module
1485 ; file "ietf-yang-push.yang"
1486 module ietf-yang-push {
1487 yang-version 1.1;
1488 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push";
1489 prefix yp;
1491 import ietf-yang-types {
1492 prefix yang;
1493 }
1494 import ietf-subscribed-notifications {
1495 prefix sn;
1496 }
1497 import ietf-datastores {
1498 prefix ds;
1499 }
1501 organization "IETF";
1502 contact
1503 "WG Web:
1504 WG List:
1505 Editor: Alexander Clemm
1506
1508 Editor: Eric Voit
1509
1511 Editor: Alberto Gonzalez Prieto
1512
1514 Editor: Ambika Prasad Tripathy
1515
1517 Editor: Einar Nilsen-Nygaard
1518
1520 Editor: Andy Bierman
1521
1523 Editor: Balazs Lengyel
1524 ";
1526 description
1527 "This module contains YANG specifications for YANG push.";
1529 revision 2017-12-20 {
1530 description
1531 "Initial revision.";
1532 reference
1533 "draft-ietf-netconf-yang-push-12";
1534 }
1536 /*
1537 * EXTENSIONS
1538 */
1540 extension notifiable-on-change {
1541 argument "value";
1542 description
1543 "Indicates whether changes to the datastore node are reportable in
1544 on-change subscriptions.
1546 The statement MUST only be a substatement of the leaf, leaf-list,
1547 container, list, anyxml, anydata statements. Zero or One
1548 notifiable-on-change statement is allowed per parent statement.
1549 NO substatements are allowed.
1551 The argument is a boolean value indicating whether on-change
1552 notifications are supported. If notifiable-on-change is not
1553 specified, the default is the same as the parent datastore node's
1554 value. For top level datastore nodes the default value is false.";
1555 }
1557 /*
1558 * FEATURES
1559 */
1561 feature on-change {
1562 description
1563 "This feature indicates that on-change triggered subscriptions
1564 are supported.";
1565 }
1567 /*
1568 * IDENTITIES
1569 */
1571 /* Error type identities for datastore subscription */
1572 identity period-unsupported {
1573 base sn:error;
1574 description
1575 "Requested time period is too short. This can be for both
1576 periodic and on-change dampening.";
1577 }
1579 identity on-change-unsupported {
1580 base sn:error;
1581 description
1582 "On-change is not supported for any objects which are selectable
1583 by this filter.";
1584 }
1586 identity on-change-synch-unsupported {
1587 base sn:error;
1588 description
1589 "Neither synch on start nor resynchonization are supported for
1590 this subscription. This error will be used for two reasons. First
1591 if an 'establish-subscription' RPC doesn't include
1592 'no-synch-on-start', yet the publisher can't support sending a
1593 'push update' for this subscription for reasons other that
1594 'on-change-unsupported' or 'result-too-big'. And second, if the
1595 'resynch-subscription' RPC is invoked either for an existing
1596 periodic subscription, or for an on-change subscription which
1597 can't support resynchronization.";
1598 }
1600 identity data-unavailable {
1601 base sn:error;
1602 description
1603 "Referenced datatree node or subtree doesn't exist, or read
1604 access is not permitted.";
1605 }
1607 identity result-too-big {
1608 base sn:error;
1609 description
1610 "Resulting periodic or on-change push updates may exceed a size
1611 limit during normal conditions.";
1612 }
1614 identity synchronization-size {
1615 base sn:error;
1616 description
1617 "The resulting synch-on-start or resynchronization would push a
1618 datatree which exceeds size limit for a one-time update.";
1619 }
1621 identity datastore-not-subscribable {
1622 base sn:error;
1623 description
1624 "This is not a subscribable datastore.";
1625 }
1627 /*
1628 * TYPE DEFINITIONS
1629 */
1631 typedef change-type {
1632 type enumeration {
1633 enum "create" {
1634 description
1635 "Create a new data resource if it does not already exist. If
1636 it already exists, replace.";
1637 }
1638 enum "delete" {
1639 description
1640 "Delete a data resource if it already exists. If it does not
1641 exists, take no action.";
1642 }
1643 enum "insert" {
1644 description
1645 "Insert a new user-ordered data resource";
1646 }
1647 enum "merge" {
1648 description
1649 "merge the edit value with the target data resource; create
1650 if it does not already exist";
1651 }
1652 enum "move" {
1653 description
1654 "Reorder the target data resource";
1655 }
1656 enum "replace" {
1657 description
1658 "Replace the target data resource with the edit value";
1659 }
1660 enum "remove" {
1661 description
1662 "Remove a data resource if it already exists ";
1663 }
1664 }
1665 description
1666 "Specifies different types of datastore changes.";
1667 reference
1668 "RFC 8072 section 2.5, with a delta that it is valid for a
1669 receiver to process an update record which performs a create
1670 operation on a datastore node the receiver believes exists, or to
1671 process a delete on a datastore node the receiver believes is
1672 missing.";
1673 }
1675 typedef selection-filter-ref {
1676 type leafref {
1677 path "/sn:filters/yp:selection-filter/yp:identifier";
1678 }
1679 description
1680 "This type is used to reference a selection filter.";
1681 }
1683 /*
1684 * GROUP DEFINITIONS
1685 */
1687 grouping datastore-criteria {
1688 description
1689 "A grouping to define criteria for which selected objects from
1690 a targeted datastore should be included in push updates.";
1691 leaf datastore {
1692 type identityref {
1693 base ds:datastore;
1694 }
1695 mandatory true;
1696 description
1697 "Datastore from which to retrieve data.";
1698 }
1699 uses selection-filter-objects;
1700 }
1702 grouping selection-filter-types {
1703 description
1704 "This grouping defines a selector for objects from a
1705 datastore.";
1706 choice filter-spec {
1707 description
1708 "The content filter specification for this request.";
1709 anydata datastore-subtree-filter {
1710 if-feature "sn:subtree";
1711 description
1712 "This parameter identifies the portions of the
1713 target datastore to retrieve.";
1714 }
1715 leaf datastore-xpath-filter {
1716 if-feature "sn:xpath";
1717 type yang:xpath1.0;
1718 description
1719 "This parameter contains an XPath expression identifying the
1720 portions of the target datastore to retrieve.
1722 If the expression returns a node-set, all nodes in the
1723 node-set are selected by the filter. Otherwise, if the
1724 expression does not return a node-set, the filter
1725 doesn't select any nodes.
1727 The expression is evaluated in the following XPath context:
1729 o The set of namespace declarations are those in scope on
1730 the 'xpath-filter' leaf element.
1732 o The set of variable bindings is empty.
1734 o The function library is the core function library, and
1735 the XPath functions defined in section 10 in RFC 7950.
1737 o The context node is the root node of the target
1738 datastore.";
1739 }
1740 }
1741 }
1743 grouping selection-filter-objects {
1744 description
1745 "This grouping defines a selector for objects from a
1746 datastore.";
1747 choice selected-content {
1748 description
1749 "The source of the selection filter applied to the subscription.
1750 This will come either referenced from a global list, or be
1751 provided within the subscription itself.";
1752 case by-reference {
1753 description
1754 "Incorporate a filter that has been configured separately.";
1755 leaf selection-filter-ref {
1756 type selection-filter-ref;
1757 mandatory true;
1758 description
1759 "References an existing selection filter which is to be
1760 applied to the subscription.";
1761 }
1762 }
1763 case within-subscription {
1764 description
1765 "Local definition allows a filter to have the same lifecycle
1766 as the subscription.";
1767 uses selection-filter-types;
1769 }
1770 }
1771 }
1773 grouping update-policy-modifiable {
1774 description
1775 "This grouping describes the datastore specific subscription
1776 conditions that can be changed during the lifetime of the
1777 subscription.";
1778 choice update-trigger {
1779 when "../yp:target/yp:datastore/yp:datastore";
1780 mandatory true;
1781 description
1782 "Defines necessary conditions for sending an event record to
1783 the subscriber.";
1784 case periodic {
1785 container periodic {
1786 presence "indicates an periodic subscription";
1787 description
1788 "The publisher is requested to notify periodically the
1789 current values of the datastore as defined by the selection
1790 filter.";
1791 leaf period {
1792 type yang:timeticks;
1793 mandatory true;
1794 description
1795 "Duration of time which should occur between periodic
1796 push updates. Where the anchor-time is
1797 available, the push will include the objects and their
1798 values which exist at an exact multiple of timeticks
1799 aligning to this start-time anchor.";
1800 }
1801 leaf anchor-time {
1802 type yang:date-and-time;
1803 description
1804 "Designates a timestamp before or after which a series of
1805 periodic push updates are determined. The next update
1806 will take place at a whole multiple interval from the
1807 anchor time. For example, for an anchor time is set for
1808 the top of a particular minute and a period interval of a
1809 minute, updates will be sent at the top of every minute
1810 this subscription is active.";
1811 }
1812 }
1813 }
1814 case on-change {
1815 if-feature "on-change";
1816 container on-change {
1817 presence "indicates an on-change subscription";
1818 description
1819 "The publisher is requested to notify changes in values in
1820 the datastore subset as defined by a selection filter.";
1821 leaf dampening-period {
1822 type yang:timeticks;
1823 default 0;
1824 description
1825 "Specifies the minimum interval between the assembly of
1826 successive update records for a single receiver of a
1827 subscription. Whenever subscribed objects change, and a
1828 dampening period interval (which may be zero) has elapsed
1829 since the previous update record creation for a receiver,
1830 then any subscribed objects and properties which have
1831 changed since the previous update record will have their
1832 current values marshalled and placed into a new update
1833 record.";
1834 }
1835 }
1836 }
1837 }
1838 }
1840 grouping update-policy {
1841 description
1842 "This grouping describes the datastore specific subscription
1843 conditions of a subscription.";
1844 uses update-policy-modifiable {
1845 augment "update-trigger/on-change/on-change" {
1846 description
1847 "Includes objects not modifiable once subscription is
1848 established.";
1849 leaf no-synch-on-start {
1850 type empty;
1851 description
1852 "The presence of this object restricts an on-change
1853 subscription from sending push-update notifications. When
1854 present, pushing a full selection per the terms of the
1855 selection filter MUST NOT be done for this subscription.
1856 Only updates about changes, i.e. only push-change-update
1857 notifications are sent. When absent (default behavior),
1858 in order to facilitate a receiver's synchronization, a full
1859 update is sent when the subscription starts using a
1860 push-update notification, just like in the case of a
1861 periodic subscription. After that, push-change-update
1862 notifications are exclusively sent unless the publisher
1863 chooses to resynch the subscription via a new push-update
1864 notification.";
1865 }
1866 leaf-list excluded-change {
1867 type change-type;
1868 description
1869 "Use to restrict which changes trigger an update.
1870 For example, if modify is excluded, only creation and
1871 deletion of objects is reported.";
1872 }
1873 }
1874 }
1875 }
1877 grouping update-error-hints {
1878 description
1879 "Allow return additional negotiation hints that apply
1880 specifically to push updates.";
1881 leaf period-hint {
1882 type yang:timeticks;
1883 description
1884 "Returned when the requested time period is too short. This
1885 hint can assert an viable period for both periodic push
1886 cadence and on-change dampening.";
1887 }
1888 leaf error-path {
1889 type string;
1890 description
1891 "Reference to a YANG path which is associated with the error
1892 being returned.";
1893 }
1894 leaf object-count-estimate {
1895 type uint32;
1896 description
1897 "If there are too many objects which could potentially be
1898 returned by the selection filter, this identifies the estimate
1899 of the number of objects which the filter would potentially
1900 pass.";
1901 }
1902 leaf object-count-limit {
1903 type uint32;
1904 description
1905 "If there are too many objects which could be returned by the
1906 selection filter, this identifies the upper limit of the
1907 publisher's ability to service for this subscription.";
1908 }
1909 leaf kilobytes-estimate {
1910 type uint32;
1911 description
1912 "If the returned information could be beyond the capacity of
1913 the publisher, this would identify the data size which could
1914 result from this selection filter.";
1915 }
1916 leaf kilobytes-limit {
1917 type uint32;
1918 description
1919 "If the returned information would be beyond the capacity of
1920 the publisher, this identifies the upper limit of the
1921 publisher's ability to service for this subscription.";
1922 }
1923 }
1925 /*
1926 * RPCs
1927 */
1929 rpc resynch-subscription {
1930 if-feature "on-change";
1931 description
1932 "This RPC allows a subscriber of an active on-change
1933 subscription to request a full push of objects in there current
1934 state. A successful result would be the set of YANG objects
1935 equivalent to a Get using the existing selection criteria. This
1936 request may only come from the same subscriber using the
1937 establish-subscription RPC.";
1938 input {
1939 leaf identifier {
1940 type sn:subscription-id;
1941 mandatory true;
1942 description
1943 "Identifier of the subscription that is to be resynched.";
1944 }
1945 }
1946 output {
1947 leaf subscription-result {
1948 type sn:subscription-result;
1949 mandatory true;
1950 description
1951 "Indicates whether the request for the subscription resynch
1952 has been accepted, or why it has been denied.";
1953 }
1954 }
1955 }
1957 /*
1958 * DATA NODES
1959 */
1961 augment "/sn:establish-subscription/sn:input" {
1962 when "sn:target/yp:datastore/yp:datastore";
1963 description
1964 "This augmentation adds additional subscription parameters that
1965 apply specifically to datastore updates to RPC input.";
1966 uses update-policy;
1967 }
1968 augment "/sn:establish-subscription/sn:input/sn:target" {
1969 description
1970 "This augmentation adds the datastore as a valid parameter object
1971 for the subscription to RPC input. This provides a target for
1972 the filter.";
1973 case datastore {
1974 uses datastore-criteria;
1975 }
1976 }
1977 augment "/sn:establish-subscription/sn:output/"+
1978 "sn:result/sn:no-success" {
1979 description
1980 "This augmentation adds datastore specific error info
1981 and hints to RPC output.";
1982 uses update-error-hints;
1983 }
1984 augment "/sn:modify-subscription/sn:input" {
1985 description
1986 "This augmentation adds additional subscription parameters
1987 specific to datastore updates.";
1988 uses update-policy-modifiable;
1989 }
1990 augment "/sn:modify-subscription/sn:input/sn:target" {
1991 description
1992 "This augmentation adds the datastore as a valid parameter object
1993 for the subscription to RPC input. This provides a target for
1994 the filter.";
1995 case datastore {
1996 uses selection-filter-objects;
1997 }
1998 }
1999 augment "/sn:modify-subscription/sn:output/"+
2000 "sn:result/sn:no-success" {
2001 description
2002 "This augmentation adds push datastore error info and hints to
2003 RPC output.";
2004 uses update-error-hints;
2005 }
2007 notification push-update {
2008 description
2009 "This notification contains a push update, containing data
2010 subscribed to via a subscription. This notification is sent for
2011 periodic updates, for a periodic subscription. It can also be
2012 used for synchronization updates of an on-change subscription.
2013 This notification shall only be sent to receivers of a
2014 subscription; it does not constitute a general-purpose
2015 notification.";
2016 leaf subscription-id {
2017 type sn:subscription-id;
2018 description
2019 "This references the subscription which drove the notification
2020 to be sent.";
2021 }
2022 leaf updates-not-sent {
2023 type empty;
2024 description
2025 "This is a flag which indicates that not all datastore nodes
2026 subscribed to are included with this update. In other words,
2027 the publisher has failed to fulfill its full subscription
2028 obligations, and despite its best efforts is providing an
2029 incomplete set of objects.";
2030 }
2031 anydata datastore-contents {
2032 description
2033 "This contains the updated data. It constitutes a snapshot
2034 at the time-of-update of the set of data that has been
2035 subscribed to. The format and syntax of the data
2036 corresponds to the format and syntax of data that would be
2037 returned in a corresponding get operation with the same
2038 selection filter parameters applied.";
2039 }
2040 }
2042 notification push-change-update {
2043 if-feature "on-change";
2044 description
2045 "This notification contains an on-change push update. This
2046 notification shall only be sent to the receivers of a
2047 subscription; it does not constitute a general-purpose
2048 notification.";
2049 leaf subscription-id {
2050 type sn:subscription-id;
2051 description
2052 "This references the subscription which drove the notification
2053 to be sent.";
2054 }
2055 leaf updates-not-sent {
2056 type empty;
2057 description
2058 "The presence of this object indicates not all changes which
2059 have occurred since the last update are included with this
2060 update. In other words, the publisher has failed to
2061 fulfill its full subscription obligations, for example in
2062 cases where it was not able to keep up with a change burst.";
2063 }
2064 anydata datastore-changes {
2065 description
2066 "This contains the set of datastore changes needed
2067 to update a remote datastore starting at the time of the
2068 previous update, per the terms of the subscription. Changes
2069 are encoded analogous to the syntax of a corresponding yang-
2070 patch operation, i.e. a yang-patch operation applied to the
2071 datastore implied by the previous update to result in the
2072 current state.";
2073 reference
2074 "RFC 8072 section 2.5, with a delta that it is ok to receive
2075 ability create on an existing node, or receive a delete on a
2076 missing node.";
2077 }
2078 }
2080 augment "/sn:subscription-started" {
2081 description
2082 "This augmentation adds many datastore specific objects to
2083 the notification that a subscription has started.";
2084 uses update-policy;
2085 }
2086 augment "/sn:subscription-started/sn:target" {
2087 description
2088 "This augmentation allows the datastore to be included as part
2089 of the notification that a subscription has started.";
2090 case datastore {
2091 uses datastore-criteria {
2092 refine "selected-content/within-subscription" {
2093 description
2094 "Specifies where the selection filter, and where came from
2095 within the subscription and then populated within this
2096 notification. If the 'selection-filter-ref' is populated,
2097 the filter within the subscription came from the 'filters'
2098 container. Otherwise it is populated in-line as part of the
2099 subscription itself.";
2100 }
2101 }
2102 }
2103 }
2105 augment "/sn:filters" {
2106 description
2107 "This augmentation allows the datastore to be included as part
2108 of the selection filtering criteria for a subscription.";
2109 list selection-filter {
2110 key "identifier";
2111 description
2112 "A list of pre-positioned filters that can be applied
2113 to datastore subscriptions.";
2114 leaf identifier {
2115 type sn:filter-id;
2116 description
2117 "An identifier to differentiate between selection filters.";
2118 }
2119 uses selection-filter-types;
2120 }
2121 }
2122 augment "/sn:subscription-modified" {
2123 description
2124 "This augmentation adds many datastore specific objects to
2125 the notification that a subscription has been modified.";
2126 uses update-policy;
2127 }
2128 augment "/sn:subscription-modified/sn:target" {
2129 description
2130 "This augmentation allows the datastore to be included as part
2131 of the notification that a subscription has been modified.";
2132 case datastore {
2133 uses datastore-criteria {
2134 refine "selected-content/within-subscription" {
2135 description
2136 "Specifies where the selection filter, and where came from
2137 within the subscription and then populated within this
2138 notification. If the 'selection-filter-ref' is populated,
2139 the filter within the subscription came from the 'filters'
2140 container. Otherwise it is populated in-line as part of the
2141 subscription itself.";
2142 }
2143 }
2144 }
2145 }
2147 augment "/sn:subscription-config/sn:subscription" {
2148 description
2149 "This augmentation adds many datastore specific objects
2150 which can be configured as opposed to established via RPC.";
2151 uses update-policy;
2152 }
2153 augment "/sn:subscription-config/sn:subscription/sn:target" {
2154 description
2155 "This augmentation adds the datastore to the selection filtering
2156 criteria for a subscription.";
2157 case datastore {
2158 uses datastore-criteria;
2159 }
2160 }
2161 augment "/sn:subscriptions/sn:subscription" {
2162 yp:notifiable-on-change true;
2163 description
2164 "This augmentation adds many datastore specific objects to a
2165 subscription.";
2166 uses update-policy;
2167 }
2168 augment "/sn:subscriptions/sn:subscription/sn:target" {
2169 description
2170 "This augmentation allows the datastore to be included as part
2171 of the selection filtering criteria for a subscription.";
2172 case datastore {
2173 uses datastore-criteria;
2174 }
2175 }
2177 /* YANG Parser Pyang crashing on syntax below, due to fixed bug
2178 https://github.com/mbj4668/pyang/issues/300
2180 deviation "/sn:subscriptions/sn:subscription/sn:receivers/"
2181 + "sn:receiver/sn:pushed-notifications" {
2182 deviate add {
2183 yp:notifiable-on-change false;
2184 }
2185 }
2186 deviation "/sn:subscriptions/sn:subscription/sn:receivers/"
2187 + "sn:receiver/sn:excluded-notifications" {
2188 deviate add {
2189 yp:notifiable-on-change false;
2190 }
2191 }
2192 YANG Parser Pyang crashing on syntax above */
2193 }
2195
2197 6. IANA Considerations
2199 This document registers the following namespace URI in the "IETF XML
2200 Registry" [RFC3688]:
2202 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push
2203 Registrant Contact: The IESG.
2204 XML: N/A; the requested URI is an XML namespace.
2206 This document registers the following YANG module in the "YANG Module
2207 Names" registry [RFC6020]:
2209 Name: ietf-yang-push
2210 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push
2211 Prefix: yp
2212 Reference: draft-ietf-netconf-yang-push-12.txt (RFC form)
2214 7. Security Considerations
2216 All security considerations from
2217 [I-D.draft-ietf-netconf-subscribed-notifications] are relevant for
2218 datastores. In addition there are specific security considerations
2219 for receivers defined in Section 3.9
2221 If the access control permissions on subscribed YANG nodes change
2222 during the lifecycle of a subscription, a publisher MUST either
2223 transparently conform to the new access control permissions, or must
2224 terminate or restart the subscriptions so that new access control
2225 permissions are re-established.
2227 The NETCONF Authorization Control Model SHOULD be used to restrict
2228 the delivery of YANG nodes for which the receiver has no access.
2230 8. Acknowledgments
2232 For their valuable comments, discussions, and feedback, we wish to
2233 acknowledge Tim Jenkins, Kent Watsen, Susan Hares, Yang Geng, Peipei
2234 Guo, Michael Scharf, Martin Bjorklund, and Guangying Zheng.
2236 9. References
2238 9.1. Normative References
2240 [I-D.draft-ietf-netconf-subscribed-notifications]
2241 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A.,
2242 and E. Nilsen-Nygaard, "Custom Subscription to Event
2243 Streams", draft-ietf-netconf-subscribed-notifications-06
2244 (work in progress), October 2017.
2246 [I-D.draft-ietf-netmod-revised-datastores]
2247 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
2248 and R. Wilton, "Network Management Datastore
2249 Architecture", draft-ietf-netmod-revised-datastores-04
2250 (work in progress), August 2017.
2252 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
2253 DOI 10.17487/RFC3688, January 2004,
2254 .
2256 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
2257 the Network Configuration Protocol (NETCONF)", RFC 6020,
2258 DOI 10.17487/RFC6020, October 2010,
2259 .
2261 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF)
2262 Base Notifications", RFC 6470, DOI 10.17487/RFC6470,
2263 February 2012, .
2265 [RFC6536bis]
2266 Bierman, A. and M. Bjorklund, "Network Configuration
2267 Protocol (NETCONF) Access Control Model", draft-ietf-
2268 netconf-rfc6536bis-05 (work in progress), September 2017.
2270 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
2271 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016,
2272 .
2274 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch
2275 Media Type", RFC 8072, DOI 10.17487/RFC8072, February
2276 2017, .
2278 9.2. Informative References
2280 [I-D.draft-ietf-netconf-netconf-event-notifications]
2281 Gonzalez Prieto, A., Clemm, A., Voit, E., Nilsen-Nygaard,
2282 E., and A. Tripathy, "NETCONF Support for Event
2283 Notifications", September 2017.
2285 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
2286 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
2287 .
2289 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
2290 and A. Bierman, Ed., "Network Configuration Protocol
2291 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
2292 .
2294 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface
2295 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014,
2296 .
2298 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements
2299 for Subscription to YANG Datastores", RFC 7923,
2300 DOI 10.17487/RFC7923, June 2016,
2301 .
2303 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2304 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
2305 .
2307 Appendix A. Changes between revisions
2309 (To be removed by RFC editor prior to publication)
2311 v11 - v12
2313 o Included Martin's review clarifications.
2315 o QoS moved to subscribed-notifications
2316 o time-of-update removed as it is redundant with RFC5277's
2317 eventTime, and other times from notification-messages.
2319 v10 - v11
2321 o Promise model reference added.
2323 o Error added for no-such-datastore
2325 o Inherited changes from subscribed notifications (such as optional
2326 feature definitions).
2328 o scrubbed the examples for proper encodings
2330 v09 - v10
2332 o Returned to the explicit filter subtyping of v00-v05
2334 o identityref to ds:datastore made explicit
2336 o Returned ability to modify a selection filter via RPC.
2338 v08 - v09
2340 o Minor tweaks cleaning up text, removing appendicies, and making
2341 reference to revised-datastores.
2343 o Subscription-id optional in push updates, except when encoded in
2344 RFC5277, Section 4 one-way notification.
2346 o Finished adding the text descibing the resynch subscription RPC.
2348 o Removed relationships to other drafts and future technology
2349 appendicies as this work is being explored elsewhere.
2351 o Deferred the multi-line card issue to new drafts
2353 o Simplified the NACM interactions.
2355 v07 - v08
2357 o Updated YANG models with minor tweaks to accommodate changes of
2358 ietf-subscribed-notifications.
2360 v06 - v07
2362 o Clarifying text tweaks.
2364 o Clarification that filters act as selectors for subscribed
2365 datastore nodes; support for value filters not included but
2366 possible as a future extension
2368 o Filters don't have to be matched to existing YANG objects
2370 v05 - v06
2372 o Security considerations updated.
2374 o Base YANG model in [subscribe] updated as part of move to
2375 identities, YANG augmentations in this doc matched up
2377 o Terms refined and text updates throughout
2379 o Appendix talking about relationship to other drafts added.
2381 o Datastore replaces stream
2383 o Definitions of filters improved
2385 v04 to v05
2387 o Referenced based subscription document changed to Subscribed
2388 Notifications from 5277bis.
2390 o Getting operational data from filters
2392 o Extension notifiable-on-change added
2394 o New appendix on potential futures. Moved text into there from
2395 several drafts.
2397 o Subscription configuration section now just includes changed
2398 parameters from Subscribed Notifications
2400 o Subscription monitoring moved into Subscribed Notifications
2402 o New error and hint mechanisms included in text and in the yang
2403 model.
2405 o Updated examples based on the error definitions
2407 o Groupings updated for consistency
2409 o Text updates throughout
2411 v03 to v04
2412 o Updates-not-sent flag added
2414 o Not notifiable extension added
2416 o Dampening period is for whole subscription, not single objects
2418 o Moved start/stop into rfc5277bis
2420 o Client and Server changed to subscriber, publisher, and receiver
2422 o Anchor time for periodic
2424 o Message format for synchronization (i.e. synch-on-start)
2426 o Material moved into 5277bis
2428 o QoS parameters supported, by not allowed to be modified by RPC
2430 o Text updates throughout
2432 Authors' Addresses
2434 Alexander Clemm
2435 Huawei
2437 Email: ludwig@clemm.org
2439 Eric Voit
2440 Cisco Systems
2442 Email: evoit@cisco.com
2444 Alberto Gonzalez Prieto
2445 VMware
2447 Email: agonzalezpri@vmware.com
2449 Ambika Prasad Tripathy
2450 Cisco Systems
2452 Email: ambtripa@cisco.com
2453 Einar Nilsen-Nygaard
2454 Cisco Systems
2456 Email: einarnn@cisco.com
2458 Andy Bierman
2459 YumaWorks
2461 Email: andy@yumaworks.com
2463 Balazs Lengyel
2464 Ericsson
2466 Email: balazs.lengyel@ericsson.com