idnits 2.17.1
draft-ietf-netconf-yang-push-17.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** There are 3 instances of too long lines in the document, the longest one
being 3 characters in excess of 72.
** The document seems to lack a both a reference to RFC 2119 and the
recommended RFC 2119 boilerplate, even if it appears to use RFC 2119
keywords.
RFC 2119 keyword, line 231: '...hat, a dampening period MAY be used to...'
RFC 2119 keyword, line 261: '...cription request SHOULD be declined if...'
RFC 2119 keyword, line 296: '... publisher MAY accept an on-change s...'
RFC 2119 keyword, line 308: '...ely, a publisher MAY decide to simply ...'
RFC 2119 keyword, line 311: '...on, the subscription MAY be suspended....'
(60 more instances...)
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Line 861 has weird spacing: '...ntifier sub...'
== Line 972 has weird spacing: '...ntifier sn:...'
== Line 2357 has weird spacing: '...pported unc...'
== 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 (July 1, 2018) is 2126 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Unused Reference: 'RFC6991' is defined on line 2258, but no explicit
reference was found in the text
== Outdated reference: A later version (-26) exists of
draft-ietf-netconf-subscribed-notifications-13
** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525)
-- Obsolete informational reference (is this intentional?): RFC 5246
(Obsoleted by RFC 8446)
Summary: 3 errors (**), 0 flaws (~~), 7 warnings (==), 2 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: January 2, 2019 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 July 1, 2018
17 YANG Datastore Subscription
18 draft-ietf-netconf-yang-push-17
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 January 2, 2019.
45 Copyright Notice
47 Copyright (c) 2018 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 . . . . . . . . . . . . . . . . . . . . . . 5
77 3.1. Subscription Model . . . . . . . . . . . . . . . . . . . 5
78 3.2. Negotiation of Subscription Policies . . . . . . . . . . 6
79 3.3. On-Change Considerations . . . . . . . . . . . . . . . . 7
80 3.4. Reliability Considerations . . . . . . . . . . . . . . . 8
81 3.5. Data Encodings . . . . . . . . . . . . . . . . . . . . . 9
82 3.6. Defining the Selection with a Datastore . . . . . . . . . 10
83 3.7. Streaming Updates . . . . . . . . . . . . . . . . . . . . 11
84 3.8. Subscription Management . . . . . . . . . . . . . . . . . 13
85 3.9. Receiver Authorization . . . . . . . . . . . . . . . . . 14
86 3.10. On-change Notifiable YANG objects . . . . . . . . . . . . 15
87 3.11. Other Considerations . . . . . . . . . . . . . . . . . . 16
88 4. A YANG data model for management of datastore push
89 subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 17
90 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 17
91 4.2. Subscription configuration . . . . . . . . . . . . . . . 22
92 4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 23
93 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 24
94 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 29
95 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46
96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 46
97 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 47
98 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 48
99 9.1. Normative References . . . . . . . . . . . . . . . . . . 48
100 9.2. Informative References . . . . . . . . . . . . . . . . . 49
101 Appendix A. Appendix A: Subscription Errors . . . . . . . . . . 50
102 A.1. RPC Failures . . . . . . . . . . . . . . . . . . . . . . 50
103 A.2. Notifications of Failure . . . . . . . . . . . . . . . . 51
104 Appendix B. Changes between revisions . . . . . . . . . . . . . 51
105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55
107 1. Introduction
109 Traditional approaches to remote visibility have been built on
110 polling. With polling, data is periodically requested and retrieved
111 by a client from a server to stay up-to-date. However, there are
112 issues associated with polling-based management:
114 o Polling incurs significant latency. This latency prohibits many
115 application types.
117 o Polling cycles may be missed, requests may be delayed or get lost,
118 often when the network is under stress and the need for the data
119 is the greatest.
121 o Polling requests may undergo slight fluctuations, resulting in
122 intervals of different lengths. The resulting data is difficult
123 to calibrate and compare.
125 o For applications that monitor for changes, many remote polling
126 cycles place ultimately fruitless load on the network, devices,
127 and applications.
129 A more effective alternative to polling is for an application to
130 receive automatic and continuous updates from a targeted subset of a
131 datastore. Accordingly, there is a need for a service that allows
132 applications to subscribe to updates from a datastore and that
133 enables the publisher to push and in effect stream those updates.
134 The requirements for such a service have been documented in
135 [RFC7923].
137 This document defines a corresponding solution that is built on top
138 of "Custom Subscription to Event Streams"
139 [I-D.draft-ietf-netconf-subscribed-notifications]. Supplementing
140 that work are YANG data model augmentations, extended RPCs, and new
141 datastore specific update notifications. Transport options for
142 [I-D.draft-ietf-netconf-subscribed-notifications] will work
143 seamlessly with this solution.
145 2. Definitions and Acronyms
147 This document uses the terminology defined in [RFC7950], [RFC8341],
148 and [RFC8342]. In addition, the following terms are introduced:
150 o Datastore node: An instance of management information in a
151 datastore. Also known as "object".
153 o Datastore node update: A data item containing the current value of
154 a datastore node at the time the datastore node update was
155 created.
157 o Datastore subscription: A subscription to updates regarding
158 contents of a datastore.
160 o Datastore subtree: An instantiated datastore node and the
161 datastore nodes that are hierarchically contained within it.
163 o On-change subscription: A datastore subscription with updates that
164 are triggered when changes in subscribed datastore nodes are
165 detected.
167 o Periodic subscription: A datastore subscription with updates that
168 are triggered periodically according to some time interval.
170 o Selection filter: Evaluation and/or selection criteria, which may
171 be applied against a targeted set of objects.
173 o Update record: A representation of one or more datastore node
174 updates. In addition, an update record may contain which type of
175 update led to the datastore node update (e.g., whether the
176 datastore node was added, changed, deleted). Also included in the
177 update record may be other metadata, such as a subscription
178 identifier of the subscription as part of which the update record
179 was generated.
181 o Update trigger: A mechanism that determines when an update record
182 needs to be generated.
184 o YANG-Push: The subscription and push mechanism for datastore
185 updates that is specified in this document.
187 3. Solution Overview
189 This document specifies a solution that provides subscription service
190 for updates from a datastore. This solution supports dynamic as well
191 as configured subscriptions to updates of datastore nodes.
192 Subscriptions specify when notification messages should be sent and
193 what data to include in update records. YANG objects are
194 subsequently pushed from the publisher to the receiver per the terms
195 of the subscription.
197 3.1. Subscription Model
199 YANG-push subscriptions are defined using a data model that is itself
200 defined in YANG. This model enhances the subscription model defined
201 in [I-D.draft-ietf-netconf-subscribed-notifications] with
202 capabilities that allow subscribers to subscribe to datastore node
203 updates, specifically to specify the update triggers defining when to
204 generate update records as well as what to include in an update
205 record. Key enhancements include:
207 o Specification of selection filters which identify targeted YANG
208 datastore nodes and/or subtrees within a datastore for which
209 updates are to be pushed.
211 o Specification of update policies contain conditions which trigger
212 the generation and pushing of new update records. There are two
213 types of subscriptions, distinguished by how updates are
214 triggered: periodic and on-change.
216 * For periodic subscriptions, the update trigger is specified by
217 two parameters that define when updates are to be pushed.
218 These parameters are the period interval with which to report
219 updates, and an anchor time which can be used to calculate at
220 which point in time updates need to be assembled and sent.
222 * For on-change subscriptions, an update trigger occurs whenever
223 a change in the subscribed information is detected. Included
224 are additional parameters such as:
226 + Dampening period: In an on-change subscription, detected
227 object changes should be sent as quickly as possible.
228 However it may be undesirable to send a rapid series of
229 object changes. Such behavior has the potential to exhaust
230 of resources in the publisher or receiver. In order to
231 protect against that, a dampening period MAY be used to
232 specify the interval which must pass before successive
233 update records for the same subscription are generated for a
234 receiver. The dampening period collectively applies to the
235 set of all datastore nodes selected by a single subscription
236 and sent to a single receiver. This means that when there
237 is a change to one or more subscribed objects, an update
238 record containing those objects is created either
239 immediately when no dampening period is in effect, or at the
240 end of a dampening period. If multiple changes to a single
241 object occur during a dampening period, only the value that
242 is in effect at the time the update record is created is
243 included. The dampening period goes into effect every time
244 an update record completes assembly.
246 + Change type: This parameter can be used to reduce the types
247 of datastore changes for which updates are sent (e.g., you
248 might only send when an object is created or deleted, but
249 not when an object value changes).
251 + No Synch on start: defines whether or not a complete push-
252 update of all subscribed data will be sent at the beginning
253 of a subscription. Such early synchronization establishes
254 the frame of reference for subsequent updates.
256 o An encoding (using anydata) for the contents of periodic and on-
257 change push updates.
259 3.2. Negotiation of Subscription Policies
261 A dynamic subscription request SHOULD be declined if a publisher's
262 assessment is that it may be unable to provide update records meeting
263 the terms of an "establish-subscription" or "modify-subscription" rpc
264 request. In this case, a subscriber may quickly follow up with a new
265 rpc request using different parameters.
267 Random guessing at different parameters by a subscriber is to be
268 discouraged. Therefore, in order to minimize the number of
269 subscription iterations between subscriber and publisher, dynamic
270 subscription supports a simple negotiation between subscribers and
271 publishers for subscription parameters. This negotiation is in the
272 form of supplemental information which may be inserted within error
273 responses to a failed rpc request. This returned error response
274 information, when considered, should increase the likelihood of
275 success for subsequent rpc requests. Such hints include suggested
276 periodic time intervals, acceptable dampening periods, and size
277 estimates for the number or objects which would be returned from a
278 proposed selection filter. However, there are no guarantees that
279 subsequent requests which consider these hints will be accepted.
281 3.3. On-Change Considerations
283 On-change subscriptions allow subscribers to receive updates whenever
284 changes to targeted objects occur. As such, on-change subscriptions
285 are particularly effective for data that changes infrequently, yet
286 for which applications need to be quickly notified whenever a change
287 does occur with minimal delay.
289 On-change subscriptions tend to be more difficult to implement than
290 periodic subscriptions. Accordingly, on-change subscriptions may not
291 be supported by all implementations or for every object.
293 Whether or not to accept or reject on-change subscription requests
294 when the scope of the subscription contains objects for which on-
295 change is not supported is up to the publisher implementation. A
296 publisher MAY accept an on-change subscription even when the scope of
297 the subscription contains objects for which on-change is not
298 supported. In that case, updates are sent only for those objects
299 within the scope that do support on-change updates whereas other
300 objects are excluded from update records, whether or not their values
301 actually change. In order for a subscriber to determine whether
302 objects support on-change subscriptions, objects are marked
303 accordingly on a publisher. Accordingly, when subscribing, it is the
304 responsibility of the subscriber to ensure it is aware of which
305 objects support on-change and which do not. For more on how objects
306 are so marked, see Section 3.10.
308 Alternatively, a publisher MAY decide to simply reject an on-change
309 subscription in case the scope of the subscription contains objects
310 for which on-change is not supported. In case of a configured
311 subscription, the subscription MAY be suspended.
313 To avoid flooding receivers with repeated updates for subscriptions
314 containing fast-changing objects, or objects with oscillating values,
315 an on-change subscription allows for the definition of a dampening
316 period. Once an update record for a given object is generated, no
317 other updates for this particular subscription will be created until
318 the end of the dampening period. Values sent at the end of the
319 dampening period are the current values of all changed objects which
320 are current at the time the dampening period expires. Changed
321 objects include those which were deleted or newly created during that
322 dampening period. If an object has returned to its original value
323 (or even has been created and then deleted) during the dampening-
324 period, the last change will still be sent. This will indicate churn
325 is occurring on that object.
327 On-change subscriptions can be refined to let users subscribe only to
328 certain types of changes. For example, a subscriber might only want
329 object creations and deletions, but not modifications of object
330 values.
332 Putting it all together, following is the conceptual process for
333 creating an push-change-update notification:
335 1. Just before a change, or at the start of a dampening period,
336 evaluate any filtering and any access control rules. The result
337 is a set "A" of datastore nodes and subtrees.
339 2. Just after a change, or at the end of a dampening period,
340 evaluate any filtering and any (possibly new) access control
341 rules. The result is a set "B" of datastore nodes and subtrees.
343 3. Construct a YANG patch record for going from A to B.
345 4. If there were any changes made between A and B which canceled
346 each other out, insert into the YANG patch record the last change
347 made for any object which otherwise wouldn't have appeared.
349 5. If the resulting patch record is non-empty, send it to the
350 receiver.
352 Note: In cases where a subscriber wants to have separate dampening
353 periods for different objects, multiple subscriptions with different
354 objects in a selection filter can be created.
356 3.4. Reliability Considerations
358 A subscription to updates from a datastore is intended to obviate the
359 need for polling. However, in order to do so, it is critical that
360 subscribers can rely on the subscription and have confidence that
361 they will indeed receive the subscribed updates without having to
362 worry about updates being silently dropped. In other words, a
363 subscription constitutes a promise on the side of the publisher to
364 provide the receivers with updates per the terms of the subscription.
366 Now, there are many reasons why a publisher may at some point no
367 longer be able to fulfill the terms of the subscription, even if the
368 subscription had been entered into with good faith. For example, the
369 volume of data objects may be larger than anticipated, the interval
370 may prove too short to send full updates in rapid succession, or an
371 internal problem may prevent objects from being collected. For this
372 reason, the solution that is defined in this document mandates that a
373 publisher notifies receivers immediately and reliably whenever it
374 encounters a situation in which it is unable to keep the terms of the
375 subscription, and provides the publisher with the option to suspend
376 the subscription in such a case.
378 A publisher SHOULD reject a request for a subscription if it is
379 unlikely that the publisher will be able fulfill the terms of that
380 subscription request. In such cases, it is preferable to have a
381 subscriber request a less resource intensive subscription than to
382 deal with frequently degraded behavior.
384 3.5. Data Encodings
386 3.5.1. Periodic Subscriptions
388 In a periodic subscription, the data included as part of an update
389 corresponds to data that could have been read using a retrieval
390 operation.
392 3.5.2. On-Change Subscriptions
394 In an on-change subscription, updates need to indicate not only
395 values of changed datastore nodes but also the types of changes that
396 occurred since the last update. Therefore encoding rules for data in
397 on-change updates will generally follow YANG-patch operation as
398 specified in [RFC8072]. The YANG-patch will describe what needs to
399 be applied to the earlier state reported by the preceding update, to
400 result in the now-current state. Note that contrary to [RFC8072],
401 objects encapsulated are not restricted to configuration objects
402 only.
404 A publisher will indicate a change to the effect that a value of a
405 datstore node has been updated by indicating a "replace" operation
406 (applied to the datastore node) in the patch. When a new datastore
407 node was created (other than an element in a list), a publisher will
408 indicate a "create" operation in the patch. When a datastore node
409 was deleted (other than an element in a list), the publisher
410 indicates this by a "delete". When a new list element was created or
411 removed, the publisher indicates it by an "insert" or "remove",
412 respectively.
414 However a patch must be able to do more than just describe the delta
415 from the previous state to the current state. As per Section 3.3, it
416 must also be able to identify if transient changes have occurred on
417 an object during a dampening period. To support this, it is valid to
418 encode a YANG patch operation so that its application would result in
419 no change between the previous and current state. This indicates
420 that some churn has occurred on the object. An example of this would
421 be a patch that does a "create" operation for a datastore node where
422 the receiver believes one already exists, or a "merge" operation
423 which replaces a previous value with the same value. Note that this
424 means that the "create" and "delete" errors described in [RFC8072]
425 section 2.5 are not errors, and are valid operations with YANG push.
427 3.6. Defining the Selection with a Datastore
429 A subscription must specify both the selection filters and the
430 datastore against which these selection filters will be applied.
431 This information is used to choose and subsequently push data from
432 the publisher's datastore to the receivers.
434 Only a single selection filter can be applied to a subscription at a
435 time. An rpc request proposing a new selection filter MUST remove
436 any existing filter. The following selection filter types are
437 included in the yang-push data model, and may be applied against a
438 datastore:
440 o subtree: A subtree selection filter identifies one or more
441 datastore subtrees. When specified, update records will only come
442 from the datastore nodes of selected datastore subtree(s). The
443 syntax and semantics correspond to that specified for [RFC6241]
444 section 6.
446 o xpath: An "xpath" selection filter is an XPath expression that
447 returns a node set. When specified, updates will only come from
448 the selected datastore nodes.
450 These filters are intended to be used as selectors that define which
451 objects are within the scope of a subscription. A publisher MUST
452 support at least one type of selection filter.
454 Xpath itself provides powerful filtering constructs and care must be
455 used in filter definition. As an example, consider an XPath filter
456 with a boolean result; such a result will not provide an easily
457 interpretable subset of a datastore. Beyond the boolean example, it
458 is quite possible to define an XPath filter where results are easy
459 for an application to misinterpret. Consider an XPath filter which
460 only passes a datastore object when an interface is up. It is up to
461 the receiver to understand implications of the presence or absence of
462 objects in each update.
464 When the set of selection filtering criteria is applied for a
465 periodic subscription, all selected datastore nodes to which a
466 receiver has access are provided to that receiver. If the same
467 filtering criteria is applied to an on-change subscription, only the
468 subset of those datastore nodes supporting on-change is provided. A
469 datastore node which doesn't support on-change is never sent as part
470 of an on-change subscription's "push-update" or "push-change-update".
472 3.7. Streaming Updates
474 Contrary to traditional data retrieval requests, datastore
475 subscription enables an unbounded series of update records to be
476 streamed over time. Two generic YANG notifications for update
477 records have been defined for this: "push-update" and "push-change-
478 update".
480 A "push-update" notification defines a complete, filtered update of
481 the datastore per the terms of a subscription. This type of YANG
482 notification is used for continuous updates of periodic
483 subscriptions. A "push-update" notification can also be used for the
484 on-change subscriptions in two cases. First it will be used as the
485 initial "push-update" if there is a need to synchronize the receiver
486 at the start of a new subscription. It also MAY be sent if the
487 publisher later chooses to resynch an on-change subscription. The
488 "push-update" update record contains an instantiated datastore
489 subtree with all of the subscribed contents. The content of the
490 update record is equivalent to the contents that would be obtained
491 had the same data been explicitly retrieved using a datastore
492 retrieval operation using the same transport with the same filters
493 applied.
495 A "push-change-update" notification is the most common type of update
496 for on-change subscriptions. The update record in this case contains
497 the set of changes that datastore nodes have undergone since the last
498 notification message. In other words, this indicates which datastore
499 nodes have been created, deleted, or have had changes to their
500 values. In cases where multiple changes have occurred and the object
501 has not been deleted, the object's most current value is reported.
502 (In other words, for each object, only one change is reported, not
503 its entire history. Doing so would defeat the purpose of the
504 dampening period.)
506 These new "push-update" or "push-change-update" are encoded and
507 placed within notification messages, and ultimately queued for egress
508 over the specified transport.
510 The following is an example of a notification message for a
511 subscription tracking the operational status of a single Ethernet
512 port (per [RFC8343]). This notification message is encoded XML over
513 NETCONF as per [I-D.draft-ietf-netconf-netconf-event-notifications].
515
516 2017-10-25T08:00:11.22Z
517
518 1011
519
520
521
522 eth0
523 up
524
525
526
527
528
530 Figure 1: Push example
532 The following is an example of an on-change notification message for
533 the same subscription.
535
536 2017-10-25T08:22:33.44Z
537
538 89
539
540
541 1
542
543 edit1
544 merge
545 /ietf-interfaces:interfaces-state
546
547
548
549 eth0
550 down
551
552
553
554
555
556
557
558
560 Figure 2: Push example for on change
562 Of note in the above example is the 'patch-id' with a value of '1'.
563 Per [RFC8072], the 'patch-id' is an arbitrary string. With YANG
564 Push, the publisher SHOULD put into the 'patch-id' a counter starting
565 at '1' which increments with every 'push-change-update' generated for
566 a subscription. If used as a counter, this counter MUST be reset to
567 '1' anytime a resynchronization occurs (i.e., with the sending of a
568 'push-update'). Also if used as a counter, the counter MUST be reset
569 to '1' the after passing a maximum value of '4294967295' (i.e.
570 maximum value that can be represented using uint32 data type). Such
571 a mechanism allows easy identification of lost or out-of-sequence
572 update records.
574 3.8. Subscription Management
576 The RPCs defined within
577 [I-D.draft-ietf-netconf-subscribed-notifications] have been enhanced
578 to support datastore subscription negotiation. Also, new error codes
579 have been added that are able to indicate why a datastore
580 subscription attempt has failed, along with new yang-data that MAY be
581 used to include details on input parameters that might result in a
582 successful subsequent RPC invocation.
584 The establishment or modification of a datastore subscription can be
585 rejected for multiple reasons. This includes a too large subtree
586 request, or the inability of the publisher to push update records as
587 frequently as requested. In such cases, no subscription is
588 established. Instead, the subscription-result with the failure
589 reason is returned as part of the RPC response. As part of this
590 response, a set of alternative subscription parameters MAY be
591 returned that would likely have resulted in acceptance of the
592 subscription request. The subscriber may consider these as part of
593 future subscription attempts.
595 In the case of a rejected request for an establishment of a datastore
596 subscription, the hints MUST be transported within a yang-data
597 "establish-subscription-datastore-error-info" container inserted into
598 the RPC error response, in lieu of the "establish-subscription-
599 stream-error-info" that is inserted in case of a stream subscription.
601 Below is a tree diagram for "establish-subscription-datastore-error-
602 info". All tree diagrams used in this document follow the notation
603 defined in [RFC8340]
604 yang-data establish-subscription-datastore-error-info
605 +--ro establish-subscription-datasore-error-info
606 +--ro reason? identityref
607 +--ro period-hint? yang:timeticks
608 +--ro filter-failure-hint? string
609 +--ro object-count-estimate? uint32
610 +--ro object-count-limit? uint32
611 +--ro kilobytes-estimate? uint32
612 +--ro kilobytes-limit? uint32
614 Figure 3: Tree diagram for establish-subscription-datastore-error-
615 info
617 Similarly, in the case of a rejected request for modification of a
618 datastore subscription, the hints MUST be transported within a yang-
619 data "modify-subscription-datastore-error-info" container inserted
620 into the RPC error response, in lieu of the "modify-subscription-
621 stream-error-info" that is inserted in case of a stream subscription.
623 Below is a tree diagram for "modify-subscription-datastore-error-
624 info".
626 yang-data modify-subscription-datastore-error-info
627 +--ro modify-subscription-datasore-error-info
628 +--ro reason? identityref
629 +--ro period-hint? yang:timeticks
630 +--ro filter-failure-hint? string
631 +--ro object-count-estimate? uint32
632 +--ro object-count-limit? uint32
633 +--ro kilobytes-estimate? uint32
634 +--ro kilobytes-limit? uint32
636 Figure 4: Tree diagram for modify-subscription-datastore-error-info
638 3.9. Receiver Authorization
640 A receiver of subscription data MUST only be sent updates for which
641 they have proper authorization. A publisher MUST ensure that no non-
642 authorized data is included in push updates. To do so, it needs to
643 apply all corresponding checks applicable at the time of a specific
644 pushed update and if necessary silently remove any non-authorized
645 data from datastore subtrees. This enables YANG data pushed based on
646 subscriptions to be authorized equivalently to a regular data
647 retrieval (get) operation.
649 A publisher MUST allow for the possibility that a subscription's
650 selection filter references non-existent or access-protected data.
651 Such support permits a receiver the ability to monitor the entire
652 lifecyle of some datastore tree. In this case, all "push-update"
653 notifications must be sent empty, and no "push-change-update"
654 notifications will be sent until some data becomes visible for a
655 receiver.
657 A publisher MAY choose reject an establish-subscription request which
658 selects non-existent or access-protected data. In addition, a
659 publisher MAY choose to terminate a dynamic subscription or suspend a
660 configured receiver when the authorization privileges of a receiver
661 change, or the access controls for subscribed objects change. Such a
662 capability enables the publisher to avoid having to support a
663 continuous, and total filtering of an entire subscription's content.
665 In these cases above, the error identity "unchanging-selection"
666 SHOULD be returned. This reduces the possibility of leakage of
667 access controlled objects.
669 Each "push-update" and "push-change-update" MUST have access control
670 applied. This includes validating that read access is permitted for
671 any new objects selected since the last notification message was sent
672 to a particular each receiver. To accomplish this, implementations
673 SHOULD support the conceptual authorization model of [RFC8342],
674 specifically section 3.2.4.
676 +-----------------+ +--------------------+
677 push-update or --> | datastore node | yes | add datastore node |
678 push-change-update | access allowed? | ---> | to update message |
679 +-----------------+ +--------------------+
681 Figure 5: Updated [rfc6536bis] access control for push updates
683 If read access into previously accessible nodes has been lost due to
684 a receiver permissions change, this SHOULD be reported as a patch
685 "delete" operation for on-change subscriptions. If not capable of
686 handling such receiver permission changes with such a "delete",
687 publisher implementations MUST force dynamic subscription re-
688 establishment or configured subscription re-initialization so that
689 appropriate filtering is installed.
691 3.10. On-change Notifiable YANG objects
693 In some cases, a publisher supporting on-change notifications may not
694 be able to push updates for some object types on-change. Reasons for
695 this might be that the value of the datastore node changes frequently
696 (e.g., [RFC8343]'s in-octets counter), that small object changes are
697 frequent and meaningless (e.g., a temperature gauge changing 0.1
698 degrees), or that the implementation is not capable of on-change
699 notification for a particular object.
701 In those cases, it will be important for client applications to have
702 a way to identify for which objects on-change notifications are
703 supported and for which ones they are not supported. Otherwise
704 client applications will have no way of knowing whether they can
705 indeed rely on their on-change subscription to provide them with the
706 change updates that they are interested in. In other words, if
707 implementations do not provide a solution and do not support
708 comprehensive on-change notifiability, clients of those
709 implementations will have no way of knowing what their on-change
710 subscription actually covers.
712 Implementations are therefore strongly advised to provide a solution
713 to this problem. It is expected that such a solution will be
714 standardized at some point in the future. In the meantime and until
715 this occurs, implementations will be expected to provide their own
716 solution.
718 3.11. Other Considerations
720 3.11.1. Robustness and reliability
722 Particularly in the case of on-change updates, it is important that
723 these updates do not get lost. Or in case the loss of an update is
724 unavoidable, it is critical that the receiver is notified
725 accordingly.
727 Update records for a single subscription MUST NOT be resequenced
728 prior to transport.
730 It is conceivable that under certain circumstances, a publisher will
731 recognize that it is unable to include within an update record the
732 full set of objects desired per the terms of a subscription. In this
733 case, the publisher MUST take one or more of the following actions.
735 o A publisher MUST set the "incomplete-update" flag on any update
736 record which is known to be missing information.
738 o It MAY choose to suspend a subscription as per
739 [I-D.draft-ietf-netconf-subscribed-notifications].
741 o When resuming an on-change subscription, the publisher SHOULD
742 generate a complete patch from the previous update record. If
743 this is not possible and the "no-synch-on-start" option is not
744 present for the subscription, then the full datastore contents MAY
745 be sent via a "push-update" instead (effectively replacing the
746 previous contents). If neither of these are possible, then an
747 "incomplete-update" flag MUST be included on the next "push-
748 change-update".
750 Note: It is perfectly acceptable to have a series of "push-change-
751 update" notifications (and even "push update" notifications) serially
752 queued at the transport layer awaiting transmission. It is not
753 required to merge pending update messages. I.e., the dampening
754 period applies to update record creation, not transmission.
756 3.11.2. Publisher capacity
758 It is far preferable to decline a subscription request than to accept
759 such a request when it cannot be met.
761 Whether or not a subscription can be supported will be determined by
762 a combination of several factors such as the subscription update
763 trigger (on-change or periodic), the period in which to report
764 changes (one second periods will consume more resources than one hour
765 periods), the amount of data in the datastore subtree that is being
766 subscribed to, and the number and combination of other subscriptions
767 that are concurrently being serviced.
769 4. A YANG data model for management of datastore push subscriptions
771 4.1. Overview
773 The YANG data model for datastore push subscriptions is depicted in
774 the following figure. The tree diagram follows the notiation defined
775 in [RFC8340]. New schema objects defined here (i.e., beyond those
776 from [I-D.draft-ietf-netconf-subscribed-notifications]) are
777 identified with "yp". For the reader's convenience, in order to
778 compact the tree representation, some nodes that are defined in ietf-
779 subscribed-notifications and that are not essential to the
780 understanding of the data model defined here have been removed. This
781 is indicated by "..." in the diagram where applicable.
783 module: ietf-subscribed-notifications
784 ...
785 +--rw filters
786 | ...
787 | +--rw yp:selection-filter* [identifier]
788 | +--rw yp:identifier sn:filter-id
789 | +--rw (yp:filter-spec)?
790 | +--:(yp:datastore-subtree-filter)
791 | | +--rw yp:datastore-subtree-filter?
792 | | {sn:subtree}?
793 | +--:(yp:datastore-xpath-filter)
794 | +--rw yp:datastore-xpath-filter? yang:xpath1.0
795 | {sn:xpath}?
796 +--rw subscriptions
797 +--rw subscription* [identifier]
798 | ...
799 +--rw (target)
800 | +--:(stream)
801 | | ...
802 | +--:(yp:datastore)
803 | +--rw yp:datastore identityref
804 | +--rw (yp:selection-filter)?
805 | +--:(yp:by-reference)
806 | | +--rw yp:selection-filter-ref
807 | | selection-filter-ref
808 | +--:(yp:within-subscription)
809 | +--rw (yp:filter-spec)?
810 | +--:(yp:datastore-subtree-filter)
811 | | +--rw yp:datastore-subtree-filter?
812 | | {sn:subtree}?
813 | +--:(yp:datastore-xpath-filter)
814 | +--rw yp:datastore-xpath-filter?
815 | yang:xpath1.0 {sn:xpath}?
816 | ...
817 +--rw (yp:update-trigger)?
818 +--:(yp:periodic)
819 | +--rw yp:periodic!
820 | +--rw yp:period yang:timeticks
821 | +--rw yp:anchor-time? yang:date-and-time
822 +--:(yp:on-change) {on-change}?
823 +--rw yp:on-change!
824 +--rw yp:dampening-period? yang:timeticks
825 +--rw yp:no-synch-on-start? empty
826 +--rw yp:excluded-change* change-type
828 rpcs:
829 +---x establish-subscription
830 | +---w input
831 | | ...
832 | | +---w (target)
833 | | | +--:(stream)
834 | | | | ...
835 | | | +--:(yp:datastore)
836 | | | +---w yp:datastore identityref
837 | | | +---w (yp:selection-filter)?
838 | | | +--:(yp:by-reference)
839 | | | | +---w yp:selection-filter-ref
840 | | | | selection-filter-ref
841 | | | +--:(yp:within-subscription)
842 | | | +---w (yp:filter-spec)?
843 | | | +--:(yp:datastore-subtree-filter)
844 | | | | +---w yp:datastore-subtree-filter?
845 | | | | {sn:subtree}?
846 | | | +--:(yp:datastore-xpath-filter)
847 | | | +---w yp:datastore-xpath-filter?
848 | | | yang:xpath1.0 {sn:xpath}?
849 | | | ...
850 | | +---w (yp:update-trigger)?
851 | | +--:(yp:periodic)
852 | | | +---w yp:periodic!
853 | | | +---w yp:period yang:timeticks
854 | | | +---w yp:anchor-time? yang:date-and-time
855 | | +--:(yp:on-change) {on-change}?
856 | | +---w yp:on-change!
857 | | +---w yp:dampening-period? yang:timeticks
858 | | +---w yp:no-synch-on-start? empty
859 | | +---w yp:excluded-change* change-type
860 | +--ro output
861 | +--ro identifier subscription-id
862 +---x modify-subscription
863 | +---w input
864 | ...
865 | +---w (target)
866 | | ...
867 | | +--:(yp:datastore)
868 | | +---w (yp:selection-filter)?
869 | | +--:(yp:by-reference)
870 | | | +---w yp:selection-filter-ref
871 | | | selection-filter-ref
872 | | +--:(yp:within-subscription)
873 | | +---w (yp:filter-spec)?
874 | | +--:(yp:datastore-subtree-filter)
875 | | | +---w yp:datastore-subtree-filter?
876 | | | {sn:subtree}?
877 | | +--:(yp:datastore-xpath-filter)
878 | | +---w yp:datastore-xpath-filter?
879 | | yang:xpath1.0 {sn:xpath}?
880 | | ...
881 | +---w (yp:update-trigger)?
882 | +--:(yp:periodic)
883 | | +---w yp:periodic!
884 | | +---w yp:period yang:timeticks
885 | | +---w yp:anchor-time? yang:date-and-time
886 | +--:(yp:on-change) {on-change}?
887 | +---w yp:on-change!
888 | +---w yp:dampening-period? yang:timeticks
889 +---x delete-subscription
890 | ...
891 +---x kill-subscription
892 ...
894 yang-data (for placement into rpc error responses)
895 ...
897 notifications:
898 +---n replay-completed {replay}?
899 | ...
900 +---n subscription-completed
901 | ...
902 +---n subscription-started {configured}?
903 | | ...
904 | +--ro (target)
905 | | ...
906 | | +--:(yp:datastore)
907 | | +--ro yp:datastore identityref
908 | | +--ro (yp:selection-filter)?
909 | | +--:(yp:by-reference)
910 | | | +--ro yp:selection-filter-ref
911 | | | selection-filter-ref
912 | | +--:(yp:within-subscription)
913 | | +--ro (yp:filter-spec)?
914 | | +--:(yp:datastore-subtree-filter)
915 | | | +--ro yp:datastore-subtree-filter?
916 | | {sn:subtree}?
917 | | +--:(yp:datastore-xpath-filter)
918 | | +--ro yp:datastore-xpath-filter?
919 | | yang:xpath1.0 {sn:xpath}?
920 | ...
921 | +--ro (yp:update-trigger)?
922 | +--:(yp:periodic)
923 | | +--ro yp:periodic!
924 | | +--ro yp:period yang:timeticks
925 | | +--ro yp:anchor-time? yang:date-and-time
926 | +--:(yp:on-change) {on-change}?
927 | +--ro yp:on-change!
928 | +--ro yp:dampening-period? yang:timeticks
929 | +--ro yp:no-synch-on-start? empty
930 | +--ro yp:excluded-change* change-type
931 +---n subscription-resumed
932 | ...
933 +---n subscription-modified
934 | ...
935 | +--ro (target)
936 | | | ...
937 | | +--:(yp:datastore)
938 | | +--ro yp:datastore identityref
939 | | +--ro (yp:selection-filter)?
940 | | +--:(yp:by-reference)
941 | | | +--ro yp:selection-filter-ref
942 | | | selection-filter-ref
943 | | +--:(yp:within-subscription)
944 | | +--ro (yp:filter-spec)?
945 | | +--:(yp:datastore-subtree-filter)
946 | | | +--ro yp:datastore-subtree-filter?
947 | | | {sn:subtree}?
948 | | +--:(yp:datastore-xpath-filter)
949 | | +--ro yp:datastore-xpath-filter?
950 | | yang:xpath1.0 {sn:xpath}?
951 | ...
952 | +--ro (yp:update-trigger)?
953 | +--:(yp:periodic)
954 | | +--ro yp:periodic!
955 | | +--ro yp:period yang:timeticks
956 | | +--ro yp:anchor-time? yang:date-and-time
957 | +--:(yp:on-change) {on-change}?
958 | +--ro yp:on-change!
959 | +--ro yp:dampening-period? yang:timeticks
960 | +--ro yp:no-synch-on-start? empty
961 | +--ro yp:excluded-change* change-type
962 +---n subscription-terminated
963 | ...
964 +---n subscription-suspended
965 ...
967 module: ietf-yang-push
969 rpcs:
970 +---x resynch-subscription {on-change}?
971 +---w input
972 +---w identifier sn:subscription-id
974 yang-data: (for placement into rpc error responses)
975 +-- resynch-subscription-error
976 | +--ro reason? identityref
977 | +--ro period-hint? timeticks
978 | +--ro filter-failure-hint? string
979 | +--ro object-count-estimate? uint32
980 | +--ro object-count-limit? uint32
981 | +--ro kilobytes-estimate? uint32
982 | +--ro kilobytes-limit? uint32
983 +-- establish-subscription-error-datastore
984 | +--ro reason? identityref
985 | +--ro period-hint? timeticks
986 | +--ro filter-failure-hint? string
987 | +--ro object-count-estimate? uint32
988 | +--ro object-count-limit? uint32
989 | +--ro kilobytes-estimate? uint32
990 | +--ro kilobytes-limit? uint32
991 +-- modify-subscription-error-datastore
992 +--ro reason? identityref
993 +--ro period-hint? timeticks
994 +--ro filter-failure-hint? string
995 +--ro object-count-estimate? uint32
996 +--ro object-count-limit? uint32
997 +--ro kilobytes-estimate? uint32
998 +--ro kilobytes-limit? uint32
1000 notifications:
1001 +---n push-update
1002 | +--ro subscription-id? sn:subscription-id
1003 | +--ro incomplete-update? empty
1004 | +--ro datastore-contents?
1005 +---n push-change-update {on-change}?
1006 +--ro subscription-id? sn:subscription-id
1007 +--ro incomplete-update? empty
1008 +--ro datastore-changes?
1010 Figure 6: Model structure
1012 Selected components of the model are summarized below.
1014 4.2. Subscription configuration
1016 Both configured and dynamic subscriptions are represented within the
1017 list "subscription". New parameters extending the basic subscription
1018 data model in [I-D.draft-ietf-netconf-subscribed-notifications]
1019 include:
1021 o The targeted datastore from which the selection is being made.
1022 The potential datastores include those from [RFC8341]. A platform
1023 may also choose to support a custom datastore.
1025 o A selection filter identifying yang nodes of interest within a
1026 datastore. Filter contents are specified via a reference to an
1027 existing filter, or via an in-line definition for only that
1028 subscription. Referenced filters allows an implementation to
1029 avoid evaluating filter acceptability during a dynamic
1030 subscription request. The case statement differentiates the
1031 options.
1033 o For periodic subscriptions, triggered updates will occur at the
1034 boundaries of a specified time interval. These boundaries can be
1035 calculated from the periodic parameters:
1037 * a "period" which defines the duration between push updates.
1039 * an "anchor-time"; update intervals always fall on the points in
1040 time that are a multiple of a "period" from an "anchor-time".
1041 If "anchor-time" is not provided, then the "anchor-time" MUST
1042 be set with the creation time of the initial update record.
1044 o For on-change subscriptions, assuming any dampening period has
1045 completed, triggering occurs whenever a change in the subscribed
1046 information is detected. On-change subscriptions have more
1047 complex semantics that is guided by its own set of parameters:
1049 * a "dampening-period" specifies the interval that must pass
1050 before a successive update for the subscription is sent. If no
1051 dampening period is in effect, the update is sent immediately.
1052 If a subsequent change is detected, another update is only sent
1053 once the dampening period has passed for this subscription.
1055 * an "excluded-change" flag which allows restriction of the types
1056 of changes for which updates should be sent (e.g., only add to
1057 an update record on object creation).
1059 * a "no-synch-on-start" flag which specifies whether a complete
1060 update with all the subscribed data is to be sent at the
1061 beginning of a subscription.
1063 4.3. YANG Notifications
1065 4.3.1. State Change Notifications
1067 Subscription state notifications and mechanism are reused from
1068 [I-D.draft-ietf-netconf-subscribed-notifications]. Notifications
1069 "subscription-started" and "subscription-modified" have been
1070 augmented to include the datastore specific objects.
1072 4.3.2. Notifications for Subscribed Content
1074 Along with the subscribed content, there are other objects which
1075 might be part of a "push-update" or "push-change-update"
1076 notification.
1078 A "subscription-id" MUST be transported along with the subscribed
1079 contents. An [RFC5277] Section 4 one-way notification MAY be used
1080 for encoding updates. Where it is, the relevant "subscription-id"
1081 MUST be encoded as the first element within each "push-update" or
1082 "push-change-update". This allows a receiver to differentiate which
1083 subscription resulted in a particular push.
1085 A "time-of-update" which represents the time an update record
1086 snapshot was generated. A receiver MAY assume that a publisher's
1087 objects have these pushed values at this point in time.
1089 An "incomplete-update" leaf. This leaf indicates that not all
1090 changes which have occurred since the last update are actually
1091 included with this update. In other words, the publisher has failed
1092 to fulfill its full subscription obligations. (For example a
1093 datastore was unable to providing the full set of datastore nodes to
1094 a publisher process.) To facilitate re-synchronization of on-change
1095 subscriptions, a publisher MAY subsequently send a "push-update"
1096 containing a full selection snapshot of subscribed data.
1098 4.4. YANG RPCs
1100 YANG-Push subscriptions are established, modified, and deleted using
1101 RPCs augmented from
1102 [I-D.draft-ietf-netconf-subscribed-notifications].
1104 4.4.1. Establish-subscription RPC
1106 The subscriber sends an establish-subscription RPC with the
1107 parameters in section 3.1. An example might look like:
1109
1111
1114
1115
1116 ds:operational
1117
1118
1121
1122
1123 500
1124
1125
1126
1128 Figure 7: Establish-subscription RPC
1130 A positive response includes the "identifier" of the accepted
1131 subscription. In that case a publisher MAY respond:
1133
1135
1137 ok
1138
1139
1141 52
1142
1143
1145 Figure 8: Establish-subscription positive RPC response
1147 A subscription can be rejected for multiple reasons, including the
1148 lack of authorization to establish a subscription, no capacity to
1149 serve the subscription at the publisher, or the inability of the
1150 publisher to select datastore content at the requested cadence.
1152 If a request is rejected because the publisher is not able to serve
1153 it, the publisher SHOULD include in the returned error hints which
1154 help a subscriber understand subscription parameters might have been
1155 accepted for the request. These hints would be included within the
1156 yang-data structure "establish-subscription-error-datastore".
1157 However even with these hints, there are no guarantee that subsequent
1158 requests will in fact be accepted.
1160 The specific parameters to be returned in as part of the RPC error
1161 response depend on the specific transport that is used to manage the
1162 subscription. In the case of NETCONF
1163 [I-D.draft-ietf-netconf-netconf-event-notifications], when a
1164 subscription request is rejected, the NETCONF RPC reply MUST include
1165 an "rpc-error" element with the following elements:
1167 o "error-type" of "application".
1169 o "error-tag" of "operation-failed".
1171 o Optionally, an "error-severity" of "error" (this MAY but does not
1172 have to be included).
1174 o "error-app-tag" with the value being a string that corresponds to
1175 an identity with a base of "establish-subscription-error".
1177 o Optionally, "error-info" containing XML-encoded data with hints
1178 for parameter settings that might result in future RPC success per
1179 yang-data definition "establish-subscription-error-datastore".
1181 For example, for the following request:
1183
1185
1188
1190 ds:operational
1191
1192
1194 /ex:foo
1195
1196
1197 100
1198
1199
1200
1202 Figure 9: Establish-subscription request example 2
1204 a publisher that cannot serve on-change updates but periodic updates
1205 might return the following:
1207
1209
1210 application
1211 operation-failed
1212 error
1213
1214 on-change-unsupported
1215
1216
1218 /yp:periodic/yp:period
1219
1220
1221
1223 Figure 10: Establish-subscription error response example 2
1225 4.4.2. Modify-subscription RPC
1227 The subscriber MAY invoke the "modify-subscription" RPC for a
1228 subscription it previously established. The subscriber will include
1229 newly desired values in the "modify-subscription" RPC. Parameters
1230 not included MUST remain unmodified. Below is an example where a
1231 subscriber attempts to modify the "period" of a subscription.
1233
1235
1238 1011
1239
1241 ds:operational
1242
1243
1245 /ex:bar
1246
1247
1248 250
1249
1250
1251
1253 Figure 11: Modify subscription request
1255 The publisher MUST respond explicitly positively or negatively to the
1256 request. If the subscription modification is rejected, the
1257 subscription is maintained as it was before the modification request.
1258 In addition, the publisher MUST send an rpc error response. This rpc
1259 error response may contain hints encapsulated within the yang-data
1260 structure "modify-subscription-error-datastore". A subscription MAY
1261 be modified multiple times.
1263 The specific parameters to be returned in as part of the RPC error
1264 response depend on the specific transport that is used to manage the
1265 subscription. In the case of NETCONF
1266 [I-D.draft-ietf-netconf-netconf-event-notifications], when a
1267 subscription request is rejected, the NETCONF RPC reply MUST include
1268 an "rpc-error" element with the following elements:
1270 o "error-type" of "application".
1272 o "error-tag" of "operation-failed".
1274 o Optionally, an "error-severity" of "error" (this MAY but does not
1275 have to be included).
1277 o "error-app-tag" with the value being a string that corresponds to
1278 an identity with a base of "modify-subscription-error".
1280 o "error-path" pointing to the object or parameter that caused the
1281 rejection.
1283 o Optionally, "error-info" containing XML-encoded data with hints
1284 for parameter settings that might result in future RPC success per
1285 yang-data definition "modify-subscription-error-datastore".
1287 A configured subscription cannot be modified using "modify-
1288 subscription" RPC. Instead, the configuration needs to be edited as
1289 needed.
1291 4.4.3. Delete-subscription RPC
1293 To stop receiving updates from a subscription and effectively delete
1294 a subscription that had previously been established using an
1295 "establish-subscription" RPC, a subscriber can send a "delete-
1296 subscription" RPC, which takes as only input the subscription's
1297 "identifier". This RPC is unmodified from
1298 [I-D.draft-ietf-netconf-subscribed-notifications].
1300 4.4.4. Resynch-subscription RPC
1302 This RPC is only applicable only for on-change subscriptions
1303 previously established using an "establish-subscription" RPC. For
1304 example:
1306
1308
1311 1011
1312
1313
1315 Resynch subscription
1317 On receipt, a publisher must either accept the request and quickly
1318 follow with a "push-update", or send an appropriate error within an
1319 rpc error response. Within an error response, the publisher may
1320 include supplemental information about the reasons within the yang-
1321 data structure "resynch-subscription-error".
1323 4.4.5. YANG Module Synchronization
1325 To make subscription requests, the subscriber needs to know the YANG
1326 module library available on the publisher. The YANG 1.0 module
1327 library information is sent by a NETCONF server in the NETCONF
1328 "hello" message. For YANG 1.1 modules and all modules used with the
1329 RESTCONF [RFC8040] protocol, this information is provided by the YANG
1330 Library module (ietf-yang-library.yang from [RFC7895]. This YANG
1331 library information is important for the receiver to reproduce the
1332 set of object definitions used within the publisher.
1334 The YANG library includes a module list with the name, revision,
1335 enabled features, and applied deviations for each YANG module
1336 implemented by the publisher. The receiver is expected to know the
1337 YANG library information before starting a subscription. The
1338 "/modules-state/module-set-id" leaf in the "ietf-yang-library" module
1339 can be used to cache the YANG library information.
1341 The set of modules, revisions, features, and deviations can change at
1342 run-time (if supported by the publisher implementation). In this
1343 case, the receiver needs to be informed of module changes before
1344 datastore nodes from changed modules can be processed correctly. The
1345 YANG library provides a simple "yang-library-change" notification
1346 that informs the subscriber that the library has changed. The
1347 receiver then needs to re-read the entire YANG library data for the
1348 replicated publisher in order to detect the specific YANG library
1349 changes. The "ietf-netconf-notifications" module defined in
1350 [RFC6470] contains a "netconf-capability-change" notification that
1351 can identify specific module changes. For example, the module URI
1352 capability of a newly loaded module will be listed in the "added-
1353 capability" leaf-list, and the module URI capability of an removed
1354 module will be listed in the "deleted-capability" leaf-list.
1356 5. YANG module
1358 file "ietf-yang-push@2018-07-01.yang"
1359 module ietf-yang-push {
1360 yang-version 1.1;
1361 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push";
1362 prefix yp;
1364 import ietf-yang-types {
1365 prefix yang;
1366 reference
1367 "RFC 6991: Common YANG Data Types";
1368 }
1369 import ietf-subscribed-notifications {
1370 prefix sn;
1371 reference
1372 "draft-ietf-netconf-subscribed-notifications:
1373 Customized Subscriptions to a Publisher's Event Streams
1375 NOTE TO RFC Editor: Please replace above reference to
1376 draft-ietf-netconf-subscribed-notifications with RFC number
1377 when published (i.e. RFC xxxx).";
1378 }
1379 import ietf-datastores {
1380 prefix ds;
1381 reference
1382 "RFC 8342: Network Management Datastore Architecture (NMDA)";
1383 }
1384 import ietf-restconf {
1385 prefix rc;
1386 reference
1387 "RFC 8040: RESTCONF Protocol";
1388 }
1390 organization "IETF";
1391 contact
1392 "WG Web:
1393 WG List:
1395 Editor: Alexander Clemm
1396
1398 Editor: Eric Voit
1399
1401 Editor: Alberto Gonzalez Prieto
1402
1404 Editor: Ambika Prasad Tripathy
1405
1407 Editor: Einar Nilsen-Nygaard
1408
1410 Editor: Andy Bierman
1411
1413 Editor: Balazs Lengyel
1414 ";
1416 description
1417 "This module contains YANG specifications for YANG push.
1419 Copyright (c) 2018 IETF Trust and the persons identified as authors
1420 of the code. All rights reserved.
1422 Redistribution and use in source and binary forms, with or without
1423 modification, is permitted pursuant to, and subject to the license
1424 terms contained in, the Simplified BSD License set forth in Section
1425 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents
1426 (https://trustee.ietf.org/license-info).
1428 This version of this YANG module is part of
1429 draft-ietf-netconf-yang-push-17; see the RFC itself for full
1430 legal notices.
1432 NOTE TO RFC EDITOR: Please replace above reference to
1433 draft-ietf-netconf-yang-push-17 with RFC number when published
1434 (i.e. RFC xxxx).";
1436 revision 2018-07-01 {
1437 description
1438 "Initial revision.
1439 NOTE TO RFC EDITOR:
1440 (1)Please replace the above revision date to
1441 the date of RFC publication when published.
1442 (2) Please replace the date in the file name
1443 (ietf-yang-push@2018-07-01.yang) to the date of RFC publication.
1444 (3) Please replace the following reference to
1445 draft-ietf-netconf-yang-push-17 with RFC number when published
1446 (i.e. RFC xxxx).";
1447 reference
1448 "draft-ietf-netconf-yang-push-17";
1449 }
1451 /*
1452 * FEATURES
1453 */
1455 feature on-change {
1456 description
1457 "This feature indicates that on-change triggered subscriptions
1458 are supported.";
1459 }
1461 /*
1462 * IDENTITIES
1463 */
1465 /* Error type identities for datastore subscription */
1466 identity resynch-subscription-error {
1467 description
1468 "Problem found while attempting to fulfill an
1469 'resynch-subscription' RPC request. ";
1470 }
1472 identity cant-exclude {
1473 base sn:establish-subscription-error;
1474 description
1475 "Unable to remove the set of 'excluded-changes'. This means the
1476 publisher is unable to restrict 'push-change-update's to just the
1477 change types requested for this subscription.";
1478 }
1480 identity datastore-not-subscribable {
1481 base sn:establish-subscription-error;
1482 base sn:subscription-terminated-reason;
1483 description
1484 "This is not a subscribable datastore.";
1485 }
1487 identity no-such-subscription-resynch {
1488 base resynch-subscription-error;
1489 description
1490 "Referenced subscription doesn't exist. This may be as a result of
1491 a non-existent subscription ID, an ID which belongs to another
1492 subscriber, or an ID for configured subscription.";
1493 }
1495 identity on-change-unsupported {
1496 base sn:establish-subscription-error;
1497 description
1498 "On-change is not supported for any objects which are selectable
1499 by this filter.";
1500 }
1502 identity on-change-synch-unsupported {
1503 base sn:establish-subscription-error;
1504 description
1505 "Neither synch on start nor resynchronization are supported for
1506 this subscription. This error will be used for two reasons.
1507 First if an 'establish-subscription' RPC doesn't include
1508 'no-synch-on-start', yet the publisher can't support sending a
1509 'push-update' for this subscription for reasons other than
1510 'on-change-unsupported' or 'synchronization-size'. And second,
1511 if the 'resynch-subscription' RPC is invoked either for an
1512 existing periodic subscription, or for an on-change subscription
1513 which can't support resynchronization.";
1515 }
1517 identity period-unsupported {
1518 base sn:establish-subscription-error;
1519 base sn:modify-subscription-error;
1520 base sn:subscription-suspended-reason;
1521 description
1522 "Requested time period is too short. This can be for both
1523 periodic and on-change subscriptions (with or without
1524 dampening.) Hints suggesting alternative periods may be
1525 returned as supplemental information.";
1526 }
1528 identity result-too-big {
1529 base sn:establish-subscription-error;
1530 base sn:modify-subscription-error;
1531 base sn:subscription-suspended-reason;
1532 description
1533 "Periodic or on-change push update datatrees exceed a maximum
1534 size limit. Hints on estimated size of what was too big may
1535 be returned as supplemental information.";
1536 }
1538 identity synchronization-size {
1539 base sn:establish-subscription-error;
1540 base sn:modify-subscription-error;
1541 base resynch-subscription-error;
1542 base sn:subscription-suspended-reason;
1543 description
1544 "Synch-on-start or resynchronization datatree exceeds a maximum
1545 size limit. Hints on estimated size of what was too big may be
1546 returned as supplemental information.";
1547 }
1549 identity unchanging-selection {
1550 base sn:establish-subscription-error;
1551 base sn:modify-subscription-error;
1552 base sn:subscription-terminated-reason;
1553 description
1554 "Selection filter is unlikely to ever select datatree nodes. This
1555 means that based on the subscriber's current access rights, the
1556 publisher recognizes that the selection filter is unlikely to ever
1557 select datatree nodes which change. Examples for this might be
1558 that node or subtree doesn't exist, read access is not permitted
1559 for a receiver, or static objects that only change at reboot have
1560 been chosen.";
1561 }
1562 /*
1563 * TYPE DEFINITIONS
1564 */
1566 typedef change-type {
1567 type enumeration {
1568 enum "create" {
1569 description
1570 "A change that refers to the creation of a new data node.";
1571 }
1572 enum "delete" {
1573 description
1574 "A change that refers to the deletion of a data node.";
1575 }
1576 enum "insert" {
1577 description
1578 "A change that refers to the insertion of a new
1579 user-ordered data node.";
1580 }
1581 enum "merge" {
1582 description
1583 "A change that refers to a merging of a new value with a
1584 target data node.";
1585 }
1586 enum "move" {
1587 description
1588 "A change that refers to a reordering of the target data
1589 node";
1590 }
1591 enum "replace" {
1592 description
1593 "A change that refers to a replacement of the target data
1594 node's value.";
1595 }
1596 enum "remove" {
1597 description
1598 "A change that refers to the removal of a data node.";
1599 }
1600 }
1601 description
1602 "Specifies different types of datastore changes.";
1603 reference
1604 "RFC 8072 section 2.5, with a delta that it is valid for a
1605 receiver to process an update record which performs a create
1606 operation on a datastore node the receiver believes exists, or to
1607 process a delete on a datastore node the receiver believes is
1608 missing.";
1609 }
1610 typedef selection-filter-ref {
1611 type leafref {
1612 path "/sn:filters/yp:selection-filter/yp:filter-id";
1613 }
1614 description
1615 "This type is used to reference a selection filter.";
1616 }
1618 /*
1619 * GROUP DEFINITIONS
1620 */
1622 grouping datastore-criteria {
1623 description
1624 "A grouping to define criteria for which selected objects from
1625 a targeted datastore should be included in push updates.";
1626 leaf datastore {
1627 type identityref {
1628 base ds:datastore;
1629 }
1630 mandatory true;
1631 description
1632 "Datastore from which to retrieve data.";
1633 }
1634 uses selection-filter-objects;
1635 }
1637 grouping selection-filter-types {
1638 description
1639 "This grouping defines the types of selectors for objects from a
1640 datastore.";
1641 choice filter-spec {
1642 description
1643 "The content filter specification for this request.";
1644 anydata datastore-subtree-filter {
1645 if-feature "sn:subtree";
1646 description
1647 "This parameter identifies the portions of the
1648 target datastore to retrieve.";
1649 }
1650 leaf datastore-xpath-filter {
1651 if-feature "sn:xpath";
1652 type yang:xpath1.0;
1653 description
1654 "This parameter contains an XPath expression identifying the
1655 portions of the target datastore to retrieve.
1657 If the expression returns a node-set, all nodes in the
1658 node-set are selected by the filter. Otherwise, if the
1659 expression does not return a node-set, the filter
1660 doesn't select any nodes.
1662 The expression is evaluated in the following XPath context:
1664 o The set of namespace declarations are those in scope on
1665 the 'datastore-xpath-filter' leaf element.
1667 o The set of variable bindings is empty.
1669 o The function library is the core function library, and
1670 the XPath functions defined in section 10 in RFC 7950.
1672 o The context node is the root node of the target
1673 datastore.";
1674 }
1675 }
1676 }
1678 grouping selection-filter-objects {
1679 description
1680 "This grouping defines a selector for objects from a
1681 datastore.";
1682 choice selection-filter {
1683 description
1684 "The source of the selection filter applied to the subscription.
1685 This will come either referenced from a global list, or be
1686 provided within the subscription itself.";
1687 case by-reference {
1688 description
1689 "Incorporate a filter that has been configured separately.";
1690 leaf selection-filter-ref {
1691 type selection-filter-ref;
1692 mandatory true;
1693 description
1694 "References an existing selection filter which is to be
1695 applied to the subscription.";
1696 }
1697 }
1698 case within-subscription {
1699 description
1700 "Local definition allows a filter to have the same lifecycle
1701 as the subscription.";
1702 uses selection-filter-types;
1704 }
1705 }
1707 }
1709 grouping update-policy-modifiable {
1710 description
1711 "This grouping describes the datastore specific subscription
1712 conditions that can be changed during the lifetime of the
1713 subscription.";
1714 choice update-trigger {
1715 description
1716 "Defines necessary conditions for sending an event record to
1717 the subscriber.";
1718 case periodic {
1719 container periodic {
1720 presence "indicates an periodic subscription";
1721 description
1722 "The publisher is requested to notify periodically the
1723 current values of the datastore as defined by the selection
1724 filter.";
1725 leaf period {
1726 type yang:timeticks;
1727 mandatory true;
1728 description
1729 "Duration of time which should occur between periodic
1730 push updates.";
1731 }
1732 leaf anchor-time {
1733 type yang:date-and-time;
1734 description
1735 "Designates a timestamp before or after which a series of
1736 periodic push updates are determined. The next update
1737 will take place at a whole multiple interval from the
1738 anchor time. For example, for an anchor time is set for
1739 the top of a particular minute and a period interval of a
1740 minute, updates will be sent at the top of every minute
1741 this subscription is active.";
1742 }
1743 }
1744 }
1745 case on-change {
1746 if-feature "on-change";
1747 container on-change {
1748 presence "indicates an on-change subscription";
1749 description
1750 "The publisher is requested to notify changes in values in
1751 the datastore subset as defined by a selection filter.";
1752 leaf dampening-period {
1753 type yang:timeticks;
1754 default 0;
1755 description
1756 "Specifies the minimum interval between the assembly of
1757 successive update records for a single receiver of a
1758 subscription. Whenever subscribed objects change, and a
1759 dampening period interval (which may be zero) has elapsed
1760 since the previous update record creation for a receiver,
1761 then any subscribed objects and properties which have
1762 changed since the previous update record will have their
1763 current values marshalled and placed into a new update
1764 record.";
1765 }
1766 }
1767 }
1768 }
1769 }
1771 grouping update-policy {
1772 description
1773 "This grouping describes the datastore specific subscription
1774 conditions of a subscription.";
1775 uses update-policy-modifiable {
1776 augment "update-trigger/on-change/on-change" {
1777 description
1778 "Includes objects not modifiable once subscription is
1779 established.";
1780 leaf no-synch-on-start {
1781 type empty;
1782 description
1783 "The presence of this object restricts an on-change
1784 subscription from sending push-update notifications. When
1785 present, pushing a full selection per the terms of the
1786 selection filter MUST NOT be done for this subscription.
1787 Only updates about changes, i.e. only push-change-update
1788 notifications are sent. When absent (default behavior),
1789 in order to facilitate a receiver's synchronization, a full
1790 update is sent when the subscription starts using a
1791 push-update notification. After that, push-change-update
1792 notifications are exclusively sent unless the publisher
1793 chooses to resynch the subscription via a new push-update
1794 notification.";
1795 }
1796 leaf-list excluded-change {
1797 type change-type;
1798 description
1799 "Use to restrict which changes trigger an update.
1800 For example, if modify is excluded, only creation and
1801 deletion of objects is reported.";
1802 }
1804 }
1805 }
1806 }
1808 grouping hints {
1809 description
1810 "Parameters associated with some error for a subscription made
1811 upon a datastore.";
1812 leaf period-hint {
1813 type yang:timeticks;
1814 description
1815 "Returned when the requested time period is too short. This
1816 hint can assert a viable period for either a periodic push
1817 cadence or an on-change dampening interval.";
1818 }
1819 leaf filter-failure-hint {
1820 type string;
1821 description
1822 "Information describing where and/or why a provided filter
1823 was unsupportable for a subscription.";
1824 }
1825 leaf object-count-estimate {
1826 type uint32;
1827 description
1828 "If there are too many objects which could potentially be
1829 returned by the selection filter, this identifies the estimate
1830 of the number of objects which the filter would potentially
1831 pass.";
1832 }
1833 leaf object-count-limit {
1834 type uint32;
1835 description
1836 "If there are too many objects which could be returned by the
1837 selection filter, this identifies the upper limit of the
1838 publisher's ability to service for this subscription.";
1839 }
1840 leaf kilobytes-estimate {
1841 type uint32;
1842 description
1843 "If the returned information could be beyond the capacity of
1844 the publisher, this would identify the data size which could
1845 result from this selection filter.";
1846 }
1847 leaf kilobytes-limit {
1848 type uint32;
1849 description
1850 "If the returned information would be beyond the capacity of
1851 the publisher, this identifies the upper limit of the
1852 publisher's ability to service for this subscription.";
1853 }
1854 }
1856 /*
1857 * RPCs
1858 */
1860 rpc resynch-subscription {
1861 if-feature "on-change";
1862 description
1863 "This RPC allows a subscriber of an active on-change
1864 subscription to request a full push of objects.
1865 A successful invocation results in a push-update of all
1866 datastore objects that the subscriber is permitted to access.
1867 This RPC can only be invoked on the same session on which the
1868 subscription was established (using an establish-subscription
1869 RPC). In case of an error, a resynch-subscription-error is
1870 sent as part of an error response.";
1871 input {
1872 leaf identifier {
1873 type sn:subscription-id;
1874 mandatory true;
1875 description
1876 "Identifier of the subscription that is to be resynched.";
1877 }
1878 }
1879 }
1881 rc:yang-data resynch-subscription-error {
1882 container resynch-subscription-error {
1883 description
1884 "If a 'resynch-subscription' RPC fails, the subscription is not
1885 resynched and the RPC error response MUST indicate the reason
1886 for this failure. This yang-data MAY be inserted as structured
1887 data within a subscription's RPC error response to indicate the
1888 failure reason.";
1889 leaf reason {
1890 type identityref {
1891 base resynch-subscription-error;
1892 }
1893 mandatory true;
1894 description
1895 "Indicates the reason why the publisher has declined a request
1896 for subscription resynchronization.";
1897 }
1898 uses hints;
1900 }
1901 }
1903 augment "/sn:establish-subscription/sn:input" {
1904 description
1905 "This augmentation adds additional subscription parameters that
1906 apply specifically to datastore updates to RPC input.";
1907 uses update-policy;
1908 }
1910 augment "/sn:establish-subscription/sn:input/sn:target" {
1911 description
1912 "This augmentation adds the datastore as a valid target
1913 for the subscription to RPC input.";
1914 case datastore {
1915 description
1916 "Information specifying the parameters of an request for a
1917 datastore subscription.";
1918 uses datastore-criteria;
1919 }
1920 }
1922 rc:yang-data establish-subscription-datastore-error-info {
1923 container establish-subscription-datastore-error-info {
1924 description
1925 "If any 'establish-subscription' RPC parameters are
1926 unsupportable against the datastore, a subscription is not
1927 created and the RPC error response MUST indicate the reason why
1928 the subscription failed to be created. This yang-data MAY be
1929 inserted as structured data within a subscription's RPC error
1930 response to indicate the failure reason. This yang-data MUST be
1931 inserted if hints are to be provided back to the subscriber.";
1932 leaf reason {
1933 type identityref {
1934 base sn:establish-subscription-error;
1935 }
1936 description
1937 "Indicates the reason why the subscription has failed to
1938 be created to a targeted datastore.";
1939 }
1940 uses hints;
1941 }
1942 }
1944 augment "/sn:modify-subscription/sn:input" {
1945 description
1946 "This augmentation adds additional subscription parameters
1947 specific to datastore updates.";
1949 uses update-policy-modifiable;
1950 }
1952 augment "/sn:modify-subscription/sn:input/sn:target" {
1953 description
1954 "This augmentation adds the datastore as a valid target
1955 for the subscription to RPC input.";
1956 case datastore {
1957 description
1958 "Information specifying the parameters of an request for a
1959 datastore subscription.";
1960 uses selection-filter-objects;
1961 }
1962 }
1964 rc:yang-data modify-subscription-datastore-error-info {
1965 container modify-subscription-datastore-error-info {
1966 description
1967 "This yang-data MAY be provided as part of a subscription's RPC
1968 error response when there is a failure of a
1969 'modify-subscription' RPC which has been made against a
1970 datastore. This yang-data MUST be used if hints are to be
1971 provides back to the subscriber.";
1972 leaf reason {
1973 type identityref {
1974 base sn:modify-subscription-error;
1975 }
1976 description
1977 "Indicates the reason why the subscription has failed to
1978 be modified.";
1979 }
1980 uses hints;
1981 }
1982 }
1984 /*
1985 * NOTIFICATIONS
1986 */
1988 notification push-update {
1989 description
1990 "This notification contains a push update, containing data
1991 subscribed to via a subscription. This notification is sent for
1992 periodic updates, for a periodic subscription. It can also be
1993 used for synchronization updates of an on-change subscription.
1994 This notification shall only be sent to receivers of a
1995 subscription. It does not constitute a general-purpose
1996 notification that would be subscribable as part of the NETCONF
1997 event stream by any receiver.";
1998 leaf subscription-id {
1999 type sn:subscription-id;
2000 description
2001 "This references the subscription which drove the notification
2002 to be sent.";
2003 }
2004 leaf incomplete-update {
2005 type empty;
2006 description
2007 "This is a flag which indicates that not all datastore nodes
2008 subscribed to are included with this update. In other words,
2009 the publisher has failed to fulfill its full subscription
2010 obligations, and despite its best efforts is providing an
2011 incomplete set of objects.";
2012 }
2013 anydata datastore-contents {
2014 description
2015 "This contains the updated data. It constitutes a snapshot
2016 at the time-of-update of the set of data that has been
2017 subscribed to. The snapshot corresponds to the same
2018 snapshot that would be returned in a corresponding get
2019 operation with the same selection filter parameters
2020 applied.";
2021 }
2022 }
2024 notification push-change-update {
2025 if-feature "on-change";
2026 description
2027 "This notification contains an on-change push update. This
2028 notification shall only be sent to the receivers of a
2029 subscription; it does not constitute a general-purpose
2030 notification.";
2031 leaf subscription-id {
2032 type sn:subscription-id;
2033 description
2034 "This references the subscription which drove the notification
2035 to be sent.";
2036 }
2037 leaf incomplete-update {
2038 type empty;
2039 description
2040 "The presence of this object indicates not all changes which
2041 have occurred since the last update are included with this
2042 update. In other words, the publisher has failed to
2043 fulfill its full subscription obligations, for example in
2044 cases where it was not able to keep up with a change burst.";
2046 }
2047 anydata datastore-changes {
2048 description
2049 "This contains the set of datastore changes of the
2050 target datastore starting at the time of the
2051 previous update, per the terms of the subscription.
2052 The datastore changes are encoded per RFC 8027
2053 (YANG Patch).";
2054 }
2055 }
2057 augment "/sn:subscription-started" {
2058 description
2059 "This augmentation adds datastore-specific objects to
2060 the notification that a subscription has started.";
2061 uses update-policy;
2062 }
2064 augment "/sn:subscription-started/sn:target" {
2065 description
2066 "This augmentation allows the datastore to be included as part
2067 of the notification that a subscription has started.";
2068 case datastore {
2069 uses datastore-criteria {
2070 refine "selection-filter/within-subscription" {
2071 description
2072 "Specifies the selection filter and where it originated
2073 from. If the 'selection-filter-ref' is populated,
2074 the filter within the subscription came from the 'filters'
2075 container. Otherwise it is populated in-line as part of the
2076 subscription itself.";
2077 }
2078 }
2079 }
2080 }
2082 augment "/sn:subscription-modified" {
2083 description
2084 "This augmentation adds datastore-specific objects to
2085 the notification that a subscription has been modified.";
2086 uses update-policy;
2087 }
2089 augment "/sn:subscription-modified/sn:target" {
2090 description
2091 "This augmentation allows the datastore to be included as part
2092 of the notification that a subscription has been modified.";
2093 case datastore {
2094 uses datastore-criteria {
2095 refine "selection-filter/within-subscription" {
2096 description
2097 "Specifies where the selection filter, and where it came
2098 from within the subscription and then populated within this
2099 notification. If the 'selection-filter-ref' is populated,
2100 the filter within the subscription came from the 'filters'
2101 container. Otherwise it is populated in-line as part of the
2102 subscription itself.";
2103 }
2104 }
2105 }
2106 }
2108 /*
2109 * DATA NODES
2110 */
2112 augment "/sn:filters" {
2113 description
2114 "This augmentation allows the datastore to be included as part
2115 of the selection filtering criteria for a subscription.";
2116 list selection-filter {
2117 key "filter-id";
2118 description
2119 "A list of pre-configured filters that can be applied
2120 to datastore subscriptions.";
2121 leaf filter-id {
2122 type string;
2123 description
2124 "An identifier to differentiate between selection filters.";
2125 }
2126 uses selection-filter-types;
2127 }
2128 }
2130 augment "/sn:subscriptions/sn:subscription" {
2131 description
2132 "This augmentation adds many datastore specific objects to a
2133 subscription.";
2134 uses update-policy;
2135 }
2136 augment "/sn:subscriptions/sn:subscription/sn:target" {
2137 description
2138 "This augmentation allows the datastore to be included as part
2139 of the selection filtering criteria for a subscription.";
2140 case datastore {
2141 uses datastore-criteria;
2143 }
2144 }
2145 }
2147
2149 6. IANA Considerations
2151 This document registers the following namespace URI in the "IETF XML
2152 Registry" [RFC3688]:
2154 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push
2155 Registrant Contact: The IESG.
2156 XML: N/A; the requested URI is an XML namespace.
2158 This document registers the following YANG module in the "YANG Module
2159 Names" registry [RFC6020]:
2161 Name: ietf-yang-push
2162 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push
2163 Prefix: yp
2164 Reference: draft-ietf-netconf-yang-push-17.txt (RFC form)
2166 7. Security Considerations
2168 The YANG module specified in this document defines a schema for data
2169 that is designed to be accessed via network management protocols such
2170 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer
2171 is the secure transport layer, and the mandatory-to-implement secure
2172 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer
2173 is HTTPS, and the mandatory-to-implement secure transport is TLS
2174 [RFC5246].
2176 The NETCONF access control model [RFC8341] provides the means to
2177 restrict access for particular NETCONF or RESTCONF users to a
2178 preconfigured subset of all available NETCONF or RESTCONF protocol
2179 operations and content.
2181 There are a number of data nodes defined in this YANG module that are
2182 writable/creatable/deletable (i.e., config true, which is the
2183 default). These data nodes may be considered sensitive or vulnerable
2184 in some network environments. Write operations (e.g., edit-config)
2185 to these data nodes without proper protection can have a negative
2186 effect on network operations. These are the subtrees and data nodes
2187 and their sensitivity/vulnerability:
2189 First, it should be noted that the YANG module augments the YANG
2190 module from [I-D.draft-ietf-netconf-subscribed-notifications].
2191 All security considerations that are listed there are relevant
2192 also for datastore subscriptions. In the following, we focus on
2193 the data nodes that are newly introduced here.
2195 Subtree "selection-filter" under container "filters": This subtree
2196 allows to specify which objects or subtrees to include in a
2197 datastore subscription. An attacker could attempt to modify the
2198 filter. For example, the filter might be modified to result in
2199 very few objects being filtered in order to attempt to overwhelm
2200 the receiver. Alternatively, the filter might be modified to
2201 result in certain objects to be excluded from updates, in order to
2202 have certain changes go unnoticed.
2204 Subtree "datastore" in choice "target" in list "subscription":
2205 Analogous to "selection filter", an attacker might attempt to
2206 modify the objects being filtered in order to overwhelm a receiver
2207 with a larger volume of object updates than expected, or to have
2208 certain changes go unnoticed.
2210 Choice "update-trigger" in list "subscription": By modifying the
2211 update trigger, an attacker might alter the updates that are being
2212 sent in order to confuse a receiver, to withhold certain updates
2213 to be sent to the receiver, and/or to overwhelm a receiver. For
2214 example, an attacker might modify the period with which updates
2215 are reported for a periodic subscription, or it might modify the
2216 dampening period for an on-change subscription, resulting in
2217 greater delay of successive updates (potentially affecting
2218 responsiveness of applications that depend on the updates) or in a
2219 high volume of updates (to exhaust receiver resources).
2221 RPC "resynch-subscription": This RPC allows a subscriber of an on-
2222 change subscription to request a full push of objects in the
2223 subscription's scope. This can result in a large volume of data.
2224 An attacker could attempt to use this RPC to exhaust resources on
2225 the server to generate the data, and attempt to overwhelm a
2226 receiver with the resulting data volume.
2228 8. Acknowledgments
2230 For their valuable comments, discussions, and feedback, we wish to
2231 acknowledge Tim Jenkins, Martin Bjorklund, Kent Watsen, Susan Hares,
2232 Yang Geng, Peipei Guo, Michael Scharf, Guangying Zheng, and Tom
2233 Petch.
2235 9. References
2237 9.1. Normative References
2239 [I-D.draft-ietf-netconf-subscribed-notifications]
2240 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A.,
2241 and E. Nilsen-Nygaard, "Custom Subscription to Event
2242 Streams", draft-ietf-netconf-subscribed-notifications-13
2243 (work in progress), June 2018.
2245 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
2246 DOI 10.17487/RFC3688, January 2004,
2247 .
2249 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
2250 the Network Configuration Protocol (NETCONF)", RFC 6020,
2251 DOI 10.17487/RFC6020, October 2010,
2252 .
2254 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF)
2255 Base Notifications", RFC 6470, DOI 10.17487/RFC6470,
2256 February 2012, .
2258 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
2259 RFC 6991, DOI 10.17487/RFC6991, July 2013,
2260 .
2262 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
2263 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016,
2264 .
2266 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
2267 RFC 7950, DOI 10.17487/RFC7950, August 2016,
2268 .
2270 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2271 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
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 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
2279 Access Control Model", STD 91, RFC 8341,
2280 DOI 10.17487/RFC8341, March 2018,
2281 .
2283 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
2284 and R. Wilton, "Network Management Datastore Architecture
2285 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
2286 .
2288 9.2. Informative References
2290 [bergstra2014]
2291 Bergstra, J. and M. Burgess, "Promise Theory, Createspace
2292 Independent Publishers, ISBN-13 9781495437779", 2014.
2294 [I-D.draft-ietf-netconf-netconf-event-notifications]
2295 Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard,
2296 E., and A. Tripathy, "NETCONF Support for Event
2297 Notifications", May 2018.
2299 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
2300 (TLS) Protocol Version 1.2", RFC 5246,
2301 DOI 10.17487/RFC5246, August 2008,
2302 .
2304 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
2305 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
2306 .
2308 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
2309 and A. Bierman, Ed., "Network Configuration Protocol
2310 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
2311 .
2313 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
2314 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
2315 .
2317 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements
2318 for Subscription to YANG Datastores", RFC 7923,
2319 DOI 10.17487/RFC7923, June 2016,
2320 .
2322 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
2323 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
2324 .
2326 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface
2327 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018,
2328 .
2330 Appendix A. Appendix A: Subscription Errors
2332 A.1. RPC Failures
2334 Rejection of an RPC for any reason is indicated by via RPC error
2335 response from the publisher. Valid RPC errors returned include both
2336 existing transport layer RPC error codes, such as those seen with
2337 NETCONF in [RFC6241], as well as subscription specific errors such as
2338 those defined within the YANG model. As a result, how subscription
2339 errors are encoded within an RPC error response is transport
2340 dependent.
2342 References to specific identities within the either the subscribed-
2343 notifications YANG model or the yang-push YANG model may be returned
2344 as part of the error responses resulting from failed attempts at
2345 datastore subscription. Following are valid errors per RPC (note:
2346 throughout this section the prefix 'sn' indicates an item imported
2347 from the subscribed-notifications.yang model):
2349 establish-subscription modify-subscription
2350 ---------------------- -------------------
2351 cant-exclude sn:filter-unsupported
2352 datastore-not-subscribable sn:insufficient-resources
2353 sn:dscp-unavailable sn:no-such-subscription
2354 sn:filter-unsupported period-unsupported
2355 sn:insufficient-resources result-too-big
2356 on-change-unsupported synchronization-size
2357 on-change-synch-unsupported unchanging-selection
2358 period-unsupported
2359 result-too-big resynch-subscription
2360 synchronization-size --------------------
2361 unchanging-selection no-such-subscription-resynch
2362 synchronization-size
2364 delete-subscription kill-subscription
2365 ---------------------- -----------------
2366 sn:no-such-subscription sn:no-such-subscription
2368 There is one final set of transport independent RPC error elements
2369 included in the YANG model. These are the following four yang-data
2370 structures for failed datastore subscriptions:
2372 1. yang-data establish-subscription-error-datastore
2373 This MUST be returned if information identifying the reason for an
2374 RPC error has not been placed elsewhere within the transport
2375 portion of a failed "establish-subscription" RPC response. This
2376 MUST be sent if hints are included.
2378 2. yang-data modify-subscription-error-datastore
2379 This MUST be returned if information identifying the reason for an
2380 RPC error has not been placed elsewhere within the transport
2381 portion of a failed "modifiy-subscription" RPC response. This
2382 MUST be sent if hints are included.
2384 3. yang-data sn:delete-subscription-error
2385 This MUST be returned if information identifying the reason for an
2386 RPC error has not been placed elsewhere within the transport
2387 portion of a failed "delete-subscription" or "kill-subscription"
2388 RPC response.
2390 4. yang-data resynch-subscription-error
2391 This MUST be returned if information identifying the reason for an
2392 RPC error has not been placed elsewhere within the transport
2393 portion of a failed "resynch-subscription" RPC response.
2395 A.2. Notifications of Failure
2397 A subscription may be unexpectedly terminated or suspended
2398 independent of any RPC or configuration operation. In such cases,
2399 indications of such a failure MUST be provided. To accomplish this,
2400 the following types of error identities may be returned within the
2401 corresponding subscription state change notification:
2403 subscription-terminated subscription-suspended
2404 ----------------------- ----------------------
2405 datastore-not-subscribable sn:insufficient-resources
2406 sn:filter-unavailable period-unsupported
2407 sn:no-such-subscription result-too-big
2408 sn:suspension-timeout synchronization-size
2409 unchanging-selection
2411 Appendix B. Changes between revisions
2413 (To be removed by RFC editor prior to publication)
2415 v16 - v17
2417 o Minor updates to YANG module, incorporating comments from Tom
2418 Petch.
2420 o Updated references.
2422 v15 - v16
2424 o Updated security considerations.
2426 o Updated references.
2428 o Addressed comments from last call review, specifically comments
2429 received from Martin Bjorklund.
2431 v14 - v15
2433 o Minor text fixes. Includes a fix to on-change update calculation
2434 to cover churn when an object changes to and from a value during a
2435 dampening period.
2437 v13 - v14
2439 o Minor text fixes.
2441 v12 - v13
2443 o Hint negotiation models now show error examples.
2445 o yang-data structures for rpc errors.
2447 v11 - v12
2449 o Included Martin's review clarifications.
2451 o QoS moved to subscribed-notifications
2453 o time-of-update removed as it is redundant with RFC5277's
2454 eventTime, and other times from notification-messages.
2456 o Error model moved to match existing implementations
2458 o On-change notifiable removed, how to do this is implementation
2459 specific.
2461 o NMDA model supported. Non NMDA version at https://github.com/
2462 netconf-wg/yang-push/
2464 v10 - v11
2466 o Promise model reference added.
2468 o Error added for no-such-datastore
2470 o Inherited changes from subscribed notifications (such as optional
2471 feature definitions).
2473 o scrubbed the examples for proper encodings
2475 v09 - v10
2477 o Returned to the explicit filter subtyping of v00-v05
2479 o identityref to ds:datastore made explicit
2481 o Returned ability to modify a selection filter via RPC.
2483 v08 - v09
2485 o Minor tweaks cleaning up text, removing appendicies, and making
2486 reference to revised-datastores.
2488 o Subscription-id optional in push updates, except when encoded in
2489 RFC5277, Section 4 one-way notification.
2491 o Finished adding the text descibing the resynch subscription RPC.
2493 o Removed relationships to other drafts and future technology
2494 appendicies as this work is being explored elsewhere.
2496 o Deferred the multi-line card issue to new drafts
2498 o Simplified the NACM interactions.
2500 v07 - v08
2502 o Updated YANG models with minor tweaks to accommodate changes of
2503 ietf-subscribed-notifications.
2505 v06 - v07
2507 o Clarifying text tweaks.
2509 o Clarification that filters act as selectors for subscribed
2510 datastore nodes; support for value filters not included but
2511 possible as a future extension
2513 o Filters don't have to be matched to existing YANG objects
2515 v05 - v06
2516 o Security considerations updated.
2518 o Base YANG model in [subscribe] updated as part of move to
2519 identities, YANG augmentations in this doc matched up
2521 o Terms refined and text updates throughout
2523 o Appendix talking about relationship to other drafts added.
2525 o Datastore replaces stream
2527 o Definitions of filters improved
2529 v04 to v05
2531 o Referenced based subscription document changed to Subscribed
2532 Notifications from 5277bis.
2534 o Getting operational data from filters
2536 o Extension notifiable-on-change added
2538 o New appendix on potential futures. Moved text into there from
2539 several drafts.
2541 o Subscription configuration section now just includes changed
2542 parameters from Subscribed Notifications
2544 o Subscription monitoring moved into Subscribed Notifications
2546 o New error and hint mechanisms included in text and in the yang
2547 model.
2549 o Updated examples based on the error definitions
2551 o Groupings updated for consistency
2553 o Text updates throughout
2555 v03 to v04
2557 o Updates-not-sent flag added
2559 o Not notifiable extension added
2561 o Dampening period is for whole subscription, not single objects
2563 o Moved start/stop into rfc5277bis
2564 o Client and Server changed to subscriber, publisher, and receiver
2566 o Anchor time for periodic
2568 o Message format for synchronization (i.e. synch-on-start)
2570 o Material moved into 5277bis
2572 o QoS parameters supported, by not allowed to be modified by RPC
2574 o Text updates throughout
2576 Authors' Addresses
2578 Alexander Clemm
2579 Huawei
2581 Email: ludwig@clemm.org
2583 Eric Voit
2584 Cisco Systems
2586 Email: evoit@cisco.com
2588 Alberto Gonzalez Prieto
2589 VMware
2591 Email: agonzalezpri@vmware.com
2593 Ambika Prasad Tripathy
2594 Cisco Systems
2596 Email: ambtripa@cisco.com
2598 Einar Nilsen-Nygaard
2599 Cisco Systems
2601 Email: einarnn@cisco.com
2603 Andy Bierman
2604 YumaWorks
2606 Email: andy@yumaworks.com
2607 Balazs Lengyel
2608 Ericsson
2610 Email: balazs.lengyel@ericsson.com