idnits 2.17.1
draft-ietf-netconf-yang-push-19.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 243: '...dampening period MAY be used to specif...'
RFC 2119 keyword, line 273: '...cription request SHOULD be declined if...'
RFC 2119 keyword, line 308: '... publisher MAY accept an on-change s...'
RFC 2119 keyword, line 320: '...ely, a publisher MAY decide to simply ...'
RFC 2119 keyword, line 323: '...n, the publisher MAY suspend the subsc...'
(61 more instances...)
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Line 1009 has weird spacing: '...---w id sn:...'
== Line 1050 has weird spacing: '...eration enu...'
== 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 (September 21, 2018) is 2043 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: 'RFC6470' is defined on line 2271, but no explicit
reference was found in the text
== Unused Reference: 'RFC6991' is defined on line 2275, but no explicit
reference was found in the text
== Unused Reference: 'RFC5277' is defined on line 2317, 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 (~~), 8 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: March 25, 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 September 21, 2018
17 YANG Datastore Subscription
18 draft-ietf-netconf-yang-push-19
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 updates enables new
25 capabilities based on the remote mirroring and monitoring of
26 configuration and operational state.
28 Via the mechanism described in this document, subscriber applications
29 may request a continuous, customized stream of updates from a YANG
30 datastore. Providing such visibility into updates enables new
31 capabilities based on the remote mirroring and monitoring of
32 configuration and operational state.
34 Status of This Memo
36 This Internet-Draft is submitted in full conformance with the
37 provisions of BCP 78 and BCP 79.
39 Internet-Drafts are working documents of the Internet Engineering
40 Task Force (IETF). Note that other groups may also distribute
41 working documents as Internet-Drafts. The list of current Internet-
42 Drafts is at https://datatracker.ietf.org/drafts/current/.
44 Internet-Drafts are draft documents valid for a maximum of six months
45 and may be updated, replaced, or obsoleted by other documents at any
46 time. It is inappropriate to use Internet-Drafts as reference
47 material or to cite them other than as "work in progress."
48 This Internet-Draft will expire on March 25, 2019.
50 Copyright Notice
52 Copyright (c) 2018 IETF Trust and the persons identified as the
53 document authors. All rights reserved.
55 This document is subject to BCP 78 and the IETF Trust's Legal
56 Provisions Relating to IETF Documents
57 (https://trustee.ietf.org/license-info) in effect on the date of
58 publication of this document. Please review these documents
59 carefully, as they describe your rights and restrictions with respect
60 to this document. Code Components extracted from this document must
61 include Simplified BSD License text as described in Section 4.e of
62 the Trust Legal Provisions and are provided without warranty as
63 described in the Simplified BSD License.
65 This document may contain material from IETF Documents or IETF
66 Contributions published or made publicly available before November
67 10, 2008. The person(s) controlling the copyright in some of this
68 material may not have granted the IETF Trust the right to allow
69 modifications of such material outside the IETF Standards Process.
70 Without obtaining an adequate license from the person(s) controlling
71 the copyright in such materials, this document may not be modified
72 outside the IETF Standards Process, and derivative works of it may
73 not be created outside the IETF Standards Process, except to format
74 it for publication as an RFC or to translate it into languages other
75 than English.
77 Table of Contents
79 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
80 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 4
81 3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 5
82 3.1. Subscription Model . . . . . . . . . . . . . . . . . . . 5
83 3.2. Negotiation of Subscription Policies . . . . . . . . . . 6
84 3.3. On-Change Considerations . . . . . . . . . . . . . . . . 7
85 3.4. Reliability Considerations . . . . . . . . . . . . . . . 8
86 3.5. Data Encodings . . . . . . . . . . . . . . . . . . . . . 9
87 3.6. Defining the Selection with a Datastore . . . . . . . . . 10
88 3.7. Streaming Updates . . . . . . . . . . . . . . . . . . . . 11
89 3.8. Subscription Management . . . . . . . . . . . . . . . . . 13
90 3.9. Receiver Authorization . . . . . . . . . . . . . . . . . 15
91 3.10. On-Change Notifiable Datastore Nodes . . . . . . . . . . 16
92 3.11. Other Considerations . . . . . . . . . . . . . . . . . . 17
93 4. A YANG Data Model for Management of Datastore Push
94 Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 18
95 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 18
96 4.2. Subscription Configuration . . . . . . . . . . . . . . . 23
97 4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 24
98 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 25
99 5. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 30
100 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47
101 7. Security Considerations . . . . . . . . . . . . . . . . . . . 47
102 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 48
103 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 49
104 9.1. Normative References . . . . . . . . . . . . . . . . . . 49
105 9.2. Informative References . . . . . . . . . . . . . . . . . 50
106 Appendix A. Appendix A: Subscription Errors . . . . . . . . . . 51
107 A.1. RPC Failures . . . . . . . . . . . . . . . . . . . . . . 51
108 A.2. Notifications of Failure . . . . . . . . . . . . . . . . 52
109 Appendix B. Changes Between Revisions . . . . . . . . . . . . . 52
110 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 56
112 1. Introduction
114 Traditional approaches to providing visibility into managed entities
115 from remote have been built on polling. With polling, data is
116 periodically requested and retrieved by a client from a server to
117 stay up-to-date. However, there are issues associated with polling-
118 based management:
120 o Polling incurs significant latency. This latency prohibits many
121 application types.
123 o Polling cycles may be missed, requests may be delayed or get lost,
124 often when the network is under stress and the need for the data
125 is the greatest.
127 o Polling requests may undergo slight fluctuations, resulting in
128 intervals of different lengths. The resulting data is difficult
129 to calibrate and compare.
131 o For applications that monitor for changes, many remote polling
132 cycles place unwanted and ultimately wasteful load on the network,
133 devices, and applications, particularly when changes occur only
134 infrequently.
136 A more effective alternative to polling is for an application to
137 receive automatic and continuous updates from a targeted subset of a
138 datastore. Accordingly, there is a need for a service that allows
139 applications to subscribe to updates from a datastore and that
140 enables the server (also referred to as publisher) to push and in
141 effect stream those updates. The requirements for such a service
142 have been documented in [RFC7923].
144 This document defines a corresponding solution that is built on top
145 of "Custom Subscription to Event Streams"
146 [I-D.draft-ietf-netconf-subscribed-notifications]. Supplementing
147 that work are YANG data model augmentations, extended RPCs, and new
148 datastore specific update notifications. Transport options for
149 [I-D.draft-ietf-netconf-subscribed-notifications] will work
150 seamlessly with this solution.
152 2. Definitions and Acronyms
154 This document uses the terminology defined in [RFC7950], [RFC8341],
155 [RFC8342], and [I-D.draft-ietf-netconf-subscribed-notifications]. In
156 addition, the following terms are introduced:
158 o Datastore node: A node in the instantiated YANG data tree
159 associated with a datastore. In this document, datastore nodes
160 are often also simply referred to as "objects"
162 o Datastore node update: A data item containing the current value of
163 a datastore node at the time the datastore node update was
164 created, as well as the path to the datastore node.
166 o Datastore subscription: A subscription to a stream of datastore
167 node updates.
169 o Datastore subtree: A datastore node and all its descendant
170 datastore nodes
172 o On-change subscription: A datastore subscription with updates that
173 are triggered when changes in subscribed datastore nodes are
174 detected.
176 o Periodic subscription: A datastore subscription with updates that
177 are triggered periodically according to some time interval.
179 o Selection filter: Evaluation and/or selection criteria, which may
180 be applied against a targeted set of objects.
182 o Update record: A representation of one or more datastore node
183 updates. In addition, an update record may contain which type of
184 update led to the datastore node update (e.g., whether the
185 datastore node was added, changed, deleted). Also included in the
186 update record may be other metadata, such as a subscription id of
187 the subscription as part of which the update record was generated.
188 In this document, update records are often also simply referred to
189 as "updates".
191 o Update trigger: A mechanism that determines when an update record
192 needs to be generated.
194 o YANG-Push: The subscription and push mechanism for datastore
195 updates that is specified in this document.
197 3. Solution Overview
199 This document specifies a solution that provides a subscription
200 service for updates from a datastore. This solution supports dynamic
201 as well as configured subscriptions to updates of datastore nodes.
202 Subscriptions specify when notification messages (also referred to as
203 "push updates") should be sent and what data to include in update
204 records. Datastore node updates are subsequently pushed from the
205 publisher to the receiver per the terms of the subscription.
207 3.1. Subscription Model
209 YANG-push subscriptions are defined using a YANG data model. This
210 model enhances the subscription model defined in
211 [I-D.draft-ietf-netconf-subscribed-notifications] with capabilities
212 that allow subscribers to subscribe to datastore node updates,
213 specifically to specify the update triggers defining when to generate
214 update records as well as what to include in an update record. Key
215 enhancements include:
217 o Specification of selection filters which identify targeted YANG
218 datastore nodes and/or datastore subtrees for which updates are to
219 be pushed.
221 o Specification of update policies contain conditions which trigger
222 the generation and pushing of new update records. There are two
223 types of subscriptions, distinguished by how updates are
224 triggered: periodic and on-change.
226 * For periodic subscriptions, the update trigger is specified by
227 two parameters that define when updates are to be pushed.
228 These parameters are the period interval with which to report
229 updates, and an "anchor time", i.e. a reference point in time
230 that can be used to calculate at which points in time periodic
231 updates need to be assembled and sent.
233 * For on-change subscriptions, an update trigger occurs whenever
234 a change in the subscribed information is detected. Included
235 are additional parameters that include:
237 + Dampening period: In an on-change subscription, detected
238 object changes should be sent as quickly as possible.
240 However it may be undesirable to send a rapid series of
241 object changes. Such behavior has the potential to exhaust
242 resources in the publisher or receiver. In order to protect
243 against that, a dampening period MAY be used to specify the
244 interval which has to pass before successive update records
245 for the same subscription are generated for a receiver. The
246 dampening period collectively applies to the set of all
247 datastore nodes selected by a single subscription. This
248 means that when there is a change to one or more subscribed
249 objects, an update record containing those objects is
250 created immediately (when no dampening period is in effect)
251 or at the end of a dampening period (when a dampening period
252 is in fact in effect). If multiple changes to a single
253 object occur during a dampening period, only the value that
254 is in effect at the time when the update record is created
255 is included. The dampening period goes into effect every
256 time an update record completes assembly.
258 + Change type: This parameter can be used to reduce the types
259 of datastore changes for which updates are sent (e.g., you
260 might only send an update when an object is created or
261 deleted, but not when an object value changes).
263 + No sync on start: defines whether or not a complete push-
264 update of all subscribed data will be sent at the beginning
265 of a subscription. Such early synchronization establishes
266 the frame of reference for subsequent updates.
268 o An encoding (using anydata) for the contents of periodic and on-
269 change push updates.
271 3.2. Negotiation of Subscription Policies
273 A dynamic subscription request SHOULD be declined if a publisher's
274 assessment is that it may be unable to provide update records meeting
275 the terms of an "establish-subscription" or "modify-subscription" RPC
276 request. In this case, a subscriber may quickly follow up with a new
277 RPC request using different parameters.
279 Random guessing of different parameters by a subscriber is to be
280 discouraged. Therefore, in order to minimize the number of
281 subscription iterations between subscriber and publisher, a dynamic
282 subscription supports a simple negotiation between subscribers and
283 publishers for subscription parameters. This negotiation is in the
284 form of supplemental information which should be inserted within
285 error responses to a failed RPC request. This returned error
286 response information, when considered, should increase the likelihood
287 of success for subsequent RPC requests. Such hints include suggested
288 periodic time intervals, acceptable dampening periods, and size
289 estimates for the number or objects which would be returned from a
290 proposed selection filter. However, there are no guarantees that
291 subsequent requests which consider these hints will be accepted.
293 3.3. On-Change Considerations
295 On-change subscriptions allow receivers to receive updates whenever
296 changes to targeted objects occur. As such, on-change subscriptions
297 are particularly effective for data that changes infrequently, yet
298 for which applications need to be quickly notified whenever a change
299 does occur with minimal delay.
301 On-change subscriptions tend to be more difficult to implement than
302 periodic subscriptions. Accordingly, on-change subscriptions may not
303 be supported by all implementations or for every object.
305 Whether or not to accept or reject on-change subscription requests
306 when the scope of the subscription contains objects for which on-
307 change is not supported is up to the publisher implementation. A
308 publisher MAY accept an on-change subscription even when the scope of
309 the subscription contains objects for which on-change is not
310 supported. In that case, updates are sent only for those objects
311 within the scope that do support on-change updates, whereas other
312 objects are excluded from update records, even if their values
313 change. In order for a subscriber to determine whether objects
314 support on-change subscriptions, objects are marked accordingly on a
315 publisher. Accordingly, when subscribing, it is the responsibility
316 of the subscriber to ensure it is aware of which objects support on-
317 change and which do not. For more on how objects are so marked, see
318 Section 3.10.
320 Alternatively, a publisher MAY decide to simply reject an on-change
321 subscription in case the scope of the subscription contains objects
322 for which on-change is not supported. In case of a configured
323 subscription, the publisher MAY suspend the subscription.
325 To avoid flooding receivers with repeated updates for subscriptions
326 containing fast-changing objects, or objects with oscillating values,
327 an on-change subscription allows for the definition of a dampening
328 period. Once an update record for a given object is generated, no
329 other updates for this particular subscription will be created until
330 the end of the dampening period. Values sent at the end of the
331 dampening period are the values that are current at the end of the
332 dampening period of all changed objects. Changed objects include
333 those which were deleted or newly created during that dampening
334 period. If an object has returned to its original value (or even has
335 been created and then deleted) during the dampening-period, that
336 value (and not the interim change) will still be sent. This will
337 indicate churn is occurring on that object.
339 On-change subscriptions can be refined to let users subscribe only to
340 certain types of changes. For example, a subscriber might only want
341 object creations and deletions, but not modifications of object
342 values.
344 Putting it all together, following is the conceptual process for
345 creating an update record as part of an on-change subscription:
347 1. Just before a change, or at the start of a dampening period,
348 evaluate any filtering and any access control rules to ensure
349 receiver is authorized to view all subscribed datastore nodes
350 (filtering out any nodes for which this is not the case). The
351 result is a set "A" of datastore nodes and subtrees.
353 2. Just after a change, or at the end of a dampening period,
354 evaluate any filtering and any (possibly new) access control
355 rules. The result is a set "B" of datastore nodes and subtrees.
357 3. Construct an update record, which takes the form of YANG patch
358 record [RFC8072] for going from A to B.
360 4. If there were any changes made between A and B which canceled
361 each other out, insert into the YANG patch record the last change
362 made, even if the new value is no different from the original
363 value (since changes that were made in the interim were canceled
364 out). In case the changes involve creating a new datastore node,
365 then deleting it, the YANG patch record will indicate deletion of
366 the datastore node. Similarly, in case the changes involve
367 deleting a new datastore node, then recreating it, the YANG patch
368 record will indicate creation of the datastore node.
370 5. If the resulting patch record is non-empty, send it to the
371 receiver.
373 Note: In cases where a subscriber wants to have separate dampening
374 periods for different objects, the subscriber has the option to
375 create multiple subscriptions with different selection filters.
377 3.4. Reliability Considerations
379 A subscription to updates from a datastore is intended to obviate the
380 need for polling. However, in order to do so, it is critical that
381 subscribers can rely on the subscription and have confidence that
382 they will indeed receive the subscribed updates without having to
383 worry about updates being silently dropped. In other words, a
384 subscription constitutes a promise on the side of the publisher to
385 provide the receivers with updates per the terms of the subscription.
387 Now, there are many reasons why a publisher may at some point no
388 longer be able to fulfill the terms of the subscription, even if the
389 subscription had been entered into with good faith. For example, the
390 volume of datastore nodes may be larger than anticipated, the
391 interval may prove too short to send full updates in rapid
392 succession, or an internal problem may prevent objects from being
393 collected. For this reason, the solution that is defined in this
394 document mandates that a publisher notifies receivers immediately and
395 reliably whenever it encounters a situation in which it is unable to
396 keep the terms of the subscription, and provides the publisher with
397 the option to suspend the subscription in such a case. This includes
398 indicating the fact that an update is incomplete as part of a push-
399 update or push-change-update notification, as well as emitting a
400 subscription-suspended notification as applicable. This is described
401 further in Section 3.11.1.
403 A publisher SHOULD reject a request for a subscription if it is
404 unlikely that the publisher will be able to fulfill the terms of that
405 subscription request. In such cases, it is preferable to have a
406 subscriber request a less resource intensive subscription than to
407 deal with frequently degraded behavior.
409 3.5. Data Encodings
411 3.5.1. Periodic Subscriptions
413 In a periodic subscription, the data included as part of an update
414 record corresponds to data that could have been read using a
415 retrieval operation.
417 3.5.2. On-Change Subscriptions
419 In an on-change subscription, update records need to indicate not
420 only values of changed datastore nodes but also the types of changes
421 that occurred since the last update. Therefore, encoding rules for
422 data in on-change updates will generally follow YANG-patch operation
423 as specified in [RFC8072]. The YANG-patch will describe what needs
424 to be applied to the earlier state reported by the preceding update,
425 to result in the now-current state. Note that contrary to [RFC8072],
426 objects encapsulated are not restricted to only configuration
427 objects.
429 A publisher indicates the type of change to a datastore node using
430 the different YANG patch operations: the "create" operation is used
431 for newly created objects (except entries in a user-ordered list),
432 the "delete" operation is used for deleted objects (including in
433 user-ordered lists), the "replace" operation is used when only the
434 object value changes, the "insert" operation is used when a new entry
435 is inserted in a list, and the "move" operation is used when an
436 existing entry in a user-ordered list is moved.
438 However, a patch must be able to do more than just describe the delta
439 from the previous state to the current state. As per Section 3.3, it
440 must also be able to identify whether transient changes have occurred
441 on an object during a dampening period. To support this, it is valid
442 to encode a YANG patch operation so that its application would result
443 in no change between the previous and current state. This indicates
444 that some churn has occurred on the object. An example of this would
445 be a patch that indicates a "create" operation for a datastore node
446 where the receiver believes one already exists, or a "replace"
447 operation which replaces a previous value with the same value. Note
448 that this means that the "create" and "delete" errors described in
449 [RFC8072] section 2.5 are not errors, and are valid operations with
450 YANG-Push.
452 3.6. Defining the Selection with a Datastore
454 A subscription must specify both the selection filters and the
455 datastore against which these selection filters will be applied.
456 This information is used to choose and subsequently push data from
457 the publisher's datastore to the receivers.
459 Only a single selection filter can be applied to a subscription at a
460 time. An RPC request proposing a new selection filter replaces any
461 existing filter. The following selection filter types are included
462 in the yang-push data model, and may be applied against a datastore:
464 o subtree: A subtree selection filter identifies one or more
465 datastore subtrees. When specified, update records will only come
466 from the datastore nodes of selected datastore subtree(s). The
467 syntax and semantics correspond to that specified for [RFC6241]
468 section 6.
470 o xpath: An "xpath" selection filter is an XPath expression that
471 returns a node set. When specified, updates will only come from
472 the selected datastore nodes.
474 These filters are intended to be used as selectors that define which
475 objects are within the scope of a subscription. A publisher MUST
476 support at least one type of selection filter.
478 XPath itself provides powerful filtering constructs and care must be
479 used in filter definition. Consider an XPath filter which only
480 passes a datastore node when an interface is up. It is up to the
481 receiver to understand implications of the presence or absence of
482 objects in each update.
484 When the set of selection filtering criteria is applied for a
485 periodic subscription, then they are applied whenever a periodic
486 update record is constructed, and only datastore nodes that pass the
487 filter and to which a receiver has access are provided to that
488 receiver. If the same filtering criteria is applied to an on-change
489 subscription, only the subset of those datastore nodes supporting on-
490 change is provided. A datastore node which doesn't support on-change
491 is never sent as part of an on-change subscription's "push-update" or
492 "push-change-update" (see Section 3.7).
494 3.7. Streaming Updates
496 Contrary to traditional data retrieval requests, datastore
497 subscription enables an unbounded series of update records to be
498 streamed over time. Two generic YANG notifications for update
499 records have been defined for this: "push-update" and "push-change-
500 update".
502 A "push-update" notification defines a complete, filtered update of
503 the datastore per the terms of a subscription. This type of YANG
504 notification is used for continuous updates of periodic
505 subscriptions. A "push-update" notification can also be used for the
506 on-change subscriptions in two cases. First, it MUST be used as the
507 initial "push-update" if there is a need to synchronize the receiver
508 at the start of a new subscription. It also MAY be sent if the
509 publisher later chooses to resync an on-change subscription. The
510 "push-update" update record contains an instantiated datastore
511 subtree with all of the subscribed contents. The content of the
512 update record is equivalent to the contents that would be obtained
513 had the same data been explicitly retrieved using a datastore
514 retrieval operation using the same transport with the same filters
515 applied.
517 A "push-change-update" notification is the most common type of update
518 for on-change subscriptions. The update record in this case contains
519 the set of changes that datastore nodes have undergone since the last
520 notification message. In other words, this indicates which datastore
521 nodes have been created, deleted, or have had changes to their
522 values. In cases where multiple changes have occurred over the
523 course of a dampening period and the object has not been deleted, the
524 object's most current value is reported. (In other words, for each
525 object, only one change is reported, not its entire history. Doing
526 so would defeat the purpose of the dampening period.)
527 "Push-update" and "push-change-update" are encoded and placed within
528 notification messages, and ultimately queued for egress over the
529 specified transport.
531 The following is an example of a notification message for a
532 subscription tracking the operational status of a single Ethernet
533 interface (per [RFC8343]). This notification message is encoded XML
534 over NETCONF as per
535 [I-D.draft-ietf-netconf-netconf-event-notifications].
537
538 2017-10-25T08:00:11.22Z
539
540 1011
541
542
543
544 eth0
545 up
546
547
548
549
550
552 Figure 1: Push example
554 The following is an example of an on-change notification message for
555 the same subscription.
557
558 2017-10-25T08:22:33.44Z
559
560 89
561
562
563 0
564
565 edit1
566 replace
567 /ietf-interfaces:interfaces
568
569
570
571 eth0
572 down
573
574
575
576
577
578
579
580
582 Figure 2: Push example for on change
584 Of note in the above example is the 'patch-id' with a value of '0'.
585 Per [RFC8072], the 'patch-id' is an arbitrary string. With YANG
586 Push, the publisher SHOULD put into the 'patch-id' a counter starting
587 at '0' which increments with every 'push-change-update' generated for
588 a subscription. If used as a counter, this counter MUST be reset to
589 '0' anytime a resynchronization occurs (i.e., with the sending of a
590 'push-update'). Also if used as a counter, the counter MUST be reset
591 to '0' after passing a maximum value of '4294967295' (i.e. maximum
592 value that can be represented using uint32 data type). Such a
593 mechanism allows easy identification of lost or out-of-sequence
594 update records.
596 3.8. Subscription Management
598 The RPCs defined within
599 [I-D.draft-ietf-netconf-subscribed-notifications] have been enhanced
600 to support datastore subscription negotiation. Also, new error codes
601 have been added that are able to indicate why a datastore
602 subscription attempt has failed, along with new yang-data that MAY be
603 used to include details on input parameters that might result in a
604 successful subsequent RPC invocation.
606 The establishment or modification of a datastore subscription can be
607 rejected for multiple reasons. This includes a too large subtree
608 request, or the inability of the publisher to push update records as
609 frequently as requested. In such cases, no subscription is
610 established. Instead, the subscription-result with the failure
611 reason is returned as part of the RPC response. As part of this
612 response, a set of alternative subscription parameters MAY be
613 returned that would likely have resulted in acceptance of the
614 subscription request. The subscriber may consider these as part of
615 future subscription attempts.
617 In the case of a rejected request for an establishment of a datastore
618 subscription, if there are hints, the hints SHOULD be transported
619 within a yang-data "establish-subscription-datastore-error-info"
620 container inserted into the RPC error response, in lieu of the
621 "establish-subscription-stream-error-info" that is inserted in case
622 of a stream subscription.
624 Below is a tree diagram for "establish-subscription-datastore-error-
625 info". All tree diagrams used in this document follow the notation
626 defined in [RFC8340]
628 yang-data establish-subscription-datastore-error-info
629 +--ro establish-subscription-datastore-error-info
630 +--ro reason? identityref
631 +--ro period-hint? yang:timeticks
632 +--ro filter-failure-hint? string
633 +--ro object-count-estimate? uint32
634 +--ro object-count-limit? uint32
635 +--ro kilobytes-estimate? uint32
636 +--ro kilobytes-limit? uint32
638 Figure 3: Tree diagram for establish-subscription-datastore-error-
639 info
641 Similarly, in the case of a rejected request for modification of a
642 datastore subscription, if there are hints, the hints SHOULD be
643 transported within a yang-data "modify-subscription-datastore-error-
644 info" container inserted into the RPC error response, in lieu of the
645 "modify-subscription-stream-error-info" that is inserted in case of a
646 stream subscription.
648 Below is a tree diagram for "modify-subscription-datastore-error-
649 info".
651 yang-data modify-subscription-datastore-error-info
652 +--ro modify-subscription-datasore-error-info
653 +--ro reason? identityref
654 +--ro period-hint? yang:timeticks
655 +--ro filter-failure-hint? string
656 +--ro object-count-estimate? uint32
657 +--ro object-count-limit? uint32
658 +--ro kilobytes-estimate? uint32
659 +--ro kilobytes-limit? uint32
661 Figure 4: Tree diagram for modify-subscription-datastore-error-info
663 3.9. Receiver Authorization
665 A receiver of subscription data MUST only be sent updates for which
666 it has proper authorization. A publisher MUST ensure that no non-
667 authorized data is included in push updates. To do so, it needs to
668 apply all corresponding checks applicable at the time of a specific
669 pushed update and if necessary silently remove any non-authorized
670 data from datastore subtrees. This enables YANG data pushed based on
671 subscriptions to be authorized equivalently to a regular data
672 retrieval (get) operation.
674 Each "push-update" and "push-change-update" MUST have access control
675 applied, as is depicted in the following diagram. This includes
676 validating that read access is permitted for any new objects selected
677 since the last notification message was sent to a particular
678 receiver. To accomplish this, implementations SHOULD support the
679 conceptual authorization model of [RFC8341], specifically section
680 3.2.4.
682 +-----------------+ +--------------------+
683 push-update or --> | datastore node | yes | add datastore node |
684 push-change-update | access allowed? | ---> | to update record |
685 +-----------------+ +--------------------+
687 Figure 5: Updated [RFC8341] access control for push updates
689 A publisher MUST allow for the possibility that a subscription's
690 selection filter references non-existent data or data that a receiver
691 is not allowed to access. Such support permits a receiver the
692 ability to monitor the entire lifecyle of some datastore tree without
693 needing to explicitly enumerate every individual datastore node. If,
694 after access control has been applied, there are no objects remaining
695 in an update record, then (in case of a periodic subscription) only a
696 single empty "push-update" notification MUST be sent. Empty "push-
697 change-update" messages (in case of an on-change subscription) MUST
698 NOT be sent. This is required to ensure that clients cannot
699 surreptitiously monitor objects that they do not have access to via
700 carefully crafted selection filters. By the same token, changes to
701 objects that are filtered MUST NOT affect any dampening intervals.
703 A publisher MAY choose to reject an establish-subscription request
704 which selects non-existent data or data that a receiver is not
705 allowed to access. As reason, the error identity "unchanging-
706 selection" SHOULD be returned. In addition, a publisher MAY choose
707 to terminate a dynamic subscription or suspend a configured receiver
708 when the authorization privileges of a receiver change, or the access
709 controls for subscribed objects change. In that case, the publisher
710 SHOULD include the error identity "unchanging-selection" as reason
711 when sending the "subscription-terminated" notification. Such a
712 capability enables the publisher to avoid having to support
713 continuous and total filtering of a subscription's content for every
714 update record. It also reduces the possibility of leakage of access-
715 controlled objects.
717 If read access into previously accessible nodes has been lost due to
718 a receiver permissions change, this SHOULD be reported as a patch
719 "delete" operation for on-change subscriptions. If not capable of
720 handling such receiver permission changes with such a "delete",
721 publisher implementations MUST force dynamic subscription re-
722 establishment or configured subscription re-initialization so that
723 appropriate filtering is installed.
725 3.10. On-Change Notifiable Datastore Nodes
727 In some cases, a publisher supporting on-change notifications may not
728 be able to push on-change updates for some object types. Reasons for
729 this might be that the value of the datastore node changes frequently
730 (e.g., [RFC8343]'s in-octets counter), that small object changes are
731 frequent and meaningless (e.g., a temperature gauge changing 0.1
732 degrees), or that the implementation is not capable of on-change
733 notification for a particular object.
735 In those cases, it will be important for client applications to have
736 a way to identify for which objects on-change notifications are
737 supported and for which ones they are not supported. Otherwise
738 client applications will have no way of knowing whether they can
739 indeed rely on their on-change subscription to provide them with the
740 change updates that they are interested in. In other words, if
741 implementations do not provide a solution and do not support
742 comprehensive on-change notifiability, clients of those
743 implementations will have no way of knowing what their on-change
744 subscription actually covers.
746 Implementations are therefore strongly advised to provide a solution
747 to this problem. It is expected that such a solution will be
748 standardized at some point in the future. In the meantime and until
749 this occurs, implementations SHOULD provide their own solution.
751 3.11. Other Considerations
753 3.11.1. Robustness and reliability
755 Particularly in the case of on-change updates, it is important that
756 these updates do not get lost. In case the loss of an update is
757 unavoidable, it is critical that the receiver is notified
758 accordingly.
760 Update records for a single subscription MUST NOT be resequenced
761 prior to transport.
763 It is conceivable that under certain circumstances, a publisher will
764 recognize that it is unable to include within an update record the
765 full set of objects desired per the terms of a subscription. In this
766 case, the publisher MUST act as follows.
768 o The publisher MUST set the "incomplete-update" flag on any update
769 record which is known to be missing information.
771 o The publisher MAY choose to suspend the subscription as per
772 [I-D.draft-ietf-netconf-subscribed-notifications]. If the
773 publisher does not create an update record at all, it MUST suspend
774 the subscription.
776 o When resuming an on-change subscription, the publisher SHOULD
777 generate a complete patch from the previous update record. If
778 this is not possible and the "sync-on-start" option is true for
779 the subscription, then the full datastore contents MAY be sent via
780 a "push-update" instead (effectively replacing the previous
781 contents). If neither of these are possible, then an "incomplete-
782 update" flag MUST be included on the next "push-change-update".
784 Note: It is perfectly acceptable to have a series of "push-change-
785 update" notifications (and even "push update" notifications) serially
786 queued at the transport layer awaiting transmission. It is not
787 required for the publisher to merge pending update records sent at
788 the the same time.
790 3.11.2. Publisher capacity
792 It is far preferable to decline a subscription request than to accept
793 such a request when it cannot be met.
795 Whether or not a subscription can be supported will be determined by
796 a combination of several factors such as the subscription update
797 trigger (on-change or periodic), the period in which to report
798 changes (one second periods will consume more resources than one hour
799 periods), the amount of data in the datastore subtree that is being
800 subscribed to, and the number and combination of other subscriptions
801 that are concurrently being serviced.
803 4. A YANG Data Model for Management of Datastore Push Subscriptions
805 4.1. Overview
807 The YANG data model for datastore push subscriptions is depicted in
808 the following figure. The tree diagram follows the notiation defined
809 in [RFC8340]. New schema objects defined here (i.e., beyond those
810 from [I-D.draft-ietf-netconf-subscribed-notifications]) are
811 identified with "yp". For the reader's convenience, in order to
812 compact the tree representation, some nodes that are defined in ietf-
813 subscribed-notifications and that are not essential to the
814 understanding of the data model defined here have been removed. This
815 is indicated by "..." in the diagram where applicable.
817 module: ietf-subscribed-notifications
818 ...
819 +--rw filters
820 | ...
821 | +--rw yp:selection-filter* [filter-id]
822 | +--rw yp:filter-id string
823 | +--rw (yp:filter-spec)?
824 | +--:(yp:datastore-subtree-filter)
825 | | +--rw yp:datastore-subtree-filter?
826 | | {sn:subtree}?
827 | +--:(yp:datastore-xpath-filter)
828 | +--rw yp:datastore-xpath-filter? yang:xpath1.0
829 | {sn:xpath}?
830 +--rw subscriptions
831 +--rw subscription* [id]
832 | ...
833 +--rw (target)
834 | +--:(stream)
835 | | ...
836 | +--:(yp:datastore)
837 | +--rw yp:datastore identityref
838 | +--rw (yp:selection-filter)?
839 | +--:(yp:by-reference)
840 | | +--rw yp:selection-filter-ref
841 | | selection-filter-ref
842 | +--:(yp:within-subscription)
843 | +--rw (yp:filter-spec)?
844 | +--:(yp:datastore-subtree-filter)
845 | | +--rw yp:datastore-subtree-filter?
846 | | {sn:subtree}?
847 | +--:(yp:datastore-xpath-filter)
848 | +--rw yp:datastore-xpath-filter?
849 | yang:xpath1.0 {sn:xpath}?
850 | ...
851 +--rw (yp:update-trigger)
852 +--:(yp:periodic)
853 | +--rw yp:periodic!
854 | +--rw yp:period yang:timeticks
855 | +--rw yp:anchor-time? yang:date-and-time
856 +--:(yp:on-change) {on-change}?
857 +--rw yp:on-change!
858 +--rw yp:dampening-period? yang:timeticks
859 +--rw yp:sync-on-start? boolean
860 +--rw yp:excluded-change* change-type
862 rpcs:
863 +---x establish-subscription
864 | +---w input
865 | | ...
866 | | +---w (target)
867 | | | +--:(stream)
868 | | | | ...
869 | | | +--:(yp:datastore)
870 | | | +---w yp:datastore identityref
871 | | | +---w (yp:selection-filter)?
872 | | | +--:(yp:by-reference)
873 | | | | +---w yp:selection-filter-ref
874 | | | | selection-filter-ref
875 | | | +--:(yp:within-subscription)
876 | | | +---w (yp:filter-spec)?
877 | | | +--:(yp:datastore-subtree-filter)
878 | | | | +---w yp:datastore-subtree-filter?
879 | | | | {sn:subtree}?
880 | | | +--:(yp:datastore-xpath-filter)
881 | | | +---w yp:datastore-xpath-filter?
882 | | | yang:xpath1.0 {sn:xpath}?
883 | | | ...
884 | | +---w (yp:update-trigger)
885 | | +--:(yp:periodic)
886 | | | +---w yp:periodic!
887 | | | +---w yp:period yang:timeticks
888 | | | +---w yp:anchor-time? yang:date-and-time
889 | | +--:(yp:on-change) {on-change}?
890 | | +---w yp:on-change!
891 | | +---w yp:dampening-period? yang:timeticks
892 | | +---w yp:sync-on-start? boolean
893 | | +---w yp:excluded-change* change-type
894 | +--ro output
895 | +--ro id subscription-id
896 | +--ro replay-start-time-revision? yang:date-and-time
897 | {replay}?
898 +---x modify-subscription
899 | +---w input
900 | ...
901 | +---w (target)
902 | | ...
903 | | +--:(yp:datastore)
904 | | +---w (yp:selection-filter)?
905 | | +--:(yp:by-reference)
906 | | | +---w yp:selection-filter-ref
907 | | | selection-filter-ref
908 | | +--:(yp:within-subscription)
909 | | +---w (yp:filter-spec)?
910 | | +--:(yp:datastore-subtree-filter)
911 | | | +---w yp:datastore-subtree-filter?
912 | | | {sn:subtree}?
913 | | +--:(yp:datastore-xpath-filter)
914 | | +---w yp:datastore-xpath-filter?
915 | | yang:xpath1.0 {sn:xpath}?
916 | | ...
917 | +---w (yp:update-trigger)
918 | +--:(yp:periodic)
919 | | +---w yp:periodic!
920 | | +---w yp:period yang:timeticks
921 | | +---w yp:anchor-time? yang:date-and-time
922 | +--:(yp:on-change) {on-change}?
923 | +---w yp:on-change!
924 | +---w yp:dampening-period? yang:timeticks
925 +---x delete-subscription
926 | ...
927 +---x kill-subscription
928 ...
930 yang-data (for placement into rpc error responses)
931 ...
933 notifications:
935 +---n replay-completed {replay}?
936 | ...
937 +---n subscription-completed
938 | ...
939 +---n subscription-started {configured}?
940 | | ...
941 | +--ro (target)
942 | | ...
943 | | +--:(yp:datastore)
944 | | +--ro yp:datastore identityref
945 | | +--ro (yp:selection-filter)?
946 | | +--:(yp:by-reference)
947 | | | +--ro yp:selection-filter-ref
948 | | | selection-filter-ref
949 | | +--:(yp:within-subscription)
950 | | +--ro (yp:filter-spec)?
951 | | +--:(yp:datastore-subtree-filter)
952 | | | +--ro yp:datastore-subtree-filter?
953 | | | {sn:subtree}?
954 | | +--:(yp:datastore-xpath-filter)
955 | | +--ro yp:datastore-xpath-filter?
956 | | yang:xpath1.0 {sn:xpath}?
957 | ...
958 | +--ro (yp:update-trigger)
959 | +--:(yp:periodic)
960 | | +--ro yp:periodic!
961 | | +--ro yp:period yang:timeticks
962 | | +--ro yp:anchor-time? yang:date-and-time
963 | +--:(yp:on-change) {on-change}?
964 | +--ro yp:on-change!
965 | +--ro yp:dampening-period? yang:timeticks
966 | +--ro yp:sync-on-start? boolean
967 | +--ro yp:excluded-change* change-type
968 +---n subscription-resumed
969 | ...
970 +---n subscription-modified
971 | ...
972 | +--ro (target)
973 | | | ...
974 | | +--:(yp:datastore)
975 | | +--ro yp:datastore identityref
976 | | +--ro (yp:selection-filter)?
977 | | +--:(yp:by-reference)
978 | | | +--ro yp:selection-filter-ref
979 | | | selection-filter-ref
980 | | +--:(yp:within-subscription)
981 | | +--ro (yp:filter-spec)?
982 | | +--:(yp:datastore-subtree-filter)
983 | | | +--ro yp:datastore-subtree-filter?
984 | | | {sn:subtree}?
985 | | +--:(yp:datastore-xpath-filter)
986 | | +--ro yp:datastore-xpath-filter?
987 | | yang:xpath1.0 {sn:xpath}?
988 | ...
989 | +--ro (yp:update-trigger)?
990 | +--:(yp:periodic)
991 | | +--ro yp:periodic!
992 | | +--ro yp:period yang:timeticks
993 | | +--ro yp:anchor-time? yang:date-and-time
994 | +--:(yp:on-change) {on-change}?
995 | +--ro yp:on-change!
996 | +--ro yp:dampening-period? yang:timeticks
997 | +--ro yp:sync-on-start? boolean
998 | +--ro yp:excluded-change* change-type
999 +---n subscription-terminated
1000 | ...
1001 +---n subscription-suspended
1002 ...
1004 module: ietf-yang-push
1006 rpcs:
1007 +---x resync-subscription {on-change}?
1008 +---w input
1009 +---w id sn:subscription-id
1011 yang-data: (for placement into rpc error responses)
1012 +-- resync-subscription-error
1013 | +--ro reason? identityref
1014 | +--ro period-hint? timeticks
1015 | +--ro filter-failure-hint? string
1016 | +--ro object-count-estimate? uint32
1017 | +--ro object-count-limit? uint32
1018 | +--ro kilobytes-estimate? uint32
1019 | +--ro kilobytes-limit? uint32
1020 +-- establish-subscription-error-datastore
1021 | +--ro reason? identityref
1022 | +--ro period-hint? timeticks
1023 | +--ro filter-failure-hint? string
1024 | +--ro object-count-estimate? uint32
1025 | +--ro object-count-limit? uint32
1026 | +--ro kilobytes-estimate? uint32
1027 | +--ro kilobytes-limit? uint32
1028 +-- modify-subscription-error-datastore
1029 +--ro reason? identityref
1030 +--ro period-hint? timeticks
1031 +--ro filter-failure-hint? string
1032 +--ro object-count-estimate? uint32
1033 +--ro object-count-limit? uint32
1034 +--ro kilobytes-estimate? uint32
1035 +--ro kilobytes-limit? uint32
1037 notifications:
1038 +---n push-update
1039 | +--ro id? sn:subscription-id
1040 | +--ro datastore-contents?
1041 | +--ro incomplete-update? empty
1042 +---n push-change-update {on-change}?
1043 +--ro id? sn:subscription-id
1044 +--ro datastore-changes?
1045 | +--ro ypatch:yang-patch
1046 | +--ro patch-id string
1047 | +--ro ypatch:comment? string
1048 | +--ro ypatch:edit* [edit-id]
1049 | +--ro ypatch:edit-id string
1050 | +--ro ypatch:operation enumeration
1051 | +--ro ypatch:target target-resource-offset
1052 | +--ro ypatch:point? target-resource-offset
1053 | +--ro ypatch:where? enumeration
1054 | +--ro ypatch:value?
1055 +--ro incomplete-update? empty
1057 Figure 6: Model structure
1059 Selected components of the model are summarized below.
1061 4.2. Subscription Configuration
1063 Both configured and dynamic subscriptions are represented within the
1064 list "subscription". New parameters extending the basic subscription
1065 data model in [I-D.draft-ietf-netconf-subscribed-notifications]
1066 include:
1068 o The targeted datastore from which the selection is being made.
1069 The potential datastores include those from [RFC8341]. A platform
1070 may also choose to support a custom datastore.
1072 o A selection filter identifying yang nodes of interest within a
1073 datastore. Filter contents are specified via a reference to an
1074 existing filter, or via an in-line definition for only that
1075 subscription. Referenced filters allows an implementation to
1076 avoid evaluating filter acceptability during a dynamic
1077 subscription request. The case statement differentiates the
1078 options.
1080 o For periodic subscriptions, triggered updates will occur at the
1081 boundaries of a specified time interval. These boundaries can be
1082 calculated from the periodic parameters:
1084 * a "period" which defines the duration between push updates.
1086 * an "anchor-time"; update intervals fall on the points in time
1087 that are a multiple of a "period" from an "anchor-time". If
1088 "anchor-time" is not provided, then the "anchor-time" MUST be
1089 set with the creation time of the initial update record.
1091 o For on-change subscriptions, assuming any dampening period has
1092 completed, triggering occurs whenever a change in the subscribed
1093 information is detected. On-change subscriptions have more
1094 complex semantics that is guided by its own set of parameters:
1096 * a "dampening-period" specifies the interval that must pass
1097 before a successive update for the subscription is sent. If no
1098 dampening period is in effect, the update is sent immediately.
1099 If a subsequent change is detected, another update is only sent
1100 once the dampening period has passed for this subscription.
1102 * an "excluded-change" parameter which allows restriction of the
1103 types of changes for which updates should be sent (e.g., only
1104 add to an update record on object creation).
1106 * a "sync-on-start" specifies whether a complete update with all
1107 the subscribed data is to be sent at the beginning of a
1108 subscription.
1110 4.3. YANG Notifications
1112 4.3.1. State Change Notifications
1114 Subscription state notifications and mechanism are reused from
1115 [I-D.draft-ietf-netconf-subscribed-notifications]. Notifications
1116 "subscription-started" and "subscription-modified" have been
1117 augmented to include the datastore specific objects.
1119 4.3.2. Notifications for Subscribed Content
1121 Along with the subscribed content, there are other objects which
1122 might be part of a "push-update" or "push-change-update"
1123 notification.
1125 An "id" (that identifies the subscription) MUST be transported along
1126 with the subscribed contents. This allows a receiver to
1127 differentiate which subscription resulted in a particular update
1128 record.
1130 A "time-of-update" which represents the time an update record
1131 snapshot was generated. A receiver MAY assume that at this point in
1132 time a publisher's objects have the values that were pushed.
1134 An "incomplete-update" leaf. This leaf indicates that not all
1135 changes which have occurred since the last update are actually
1136 included with this update. In other words, the publisher has failed
1137 to fulfill its full subscription obligations. (For example a
1138 datastore was unable to provide the full set of datastore nodes to a
1139 publisher process.) To facilitate re-synchronization of on-change
1140 subscriptions, a publisher MAY subsequently send a "push-update"
1141 containing a full selection snapshot of subscribed data.
1143 4.4. YANG RPCs
1145 YANG-Push subscriptions are established, modified, and deleted using
1146 RPCs augmented from
1147 [I-D.draft-ietf-netconf-subscribed-notifications].
1149 4.4.1. Establish-subscription RPC
1151 The subscriber sends an establish-subscription RPC with the
1152 parameters in section 3.1. An example might look like:
1154
1156
1159
1160 ds:operational
1161
1162
1164 /ex:foo
1165
1166
1167 500
1168
1169
1170
1172 Figure 7: Establish-subscription RPC
1174 A positive response includes the "id" of the accepted subscription.
1175 In that case a publisher may respond:
1177
1179
1181 52
1182
1183
1185 Figure 8: Establish-subscription positive RPC response
1187 A subscription can be rejected for multiple reasons, including the
1188 lack of authorization to establish a subscription, no capacity to
1189 serve the subscription at the publisher, or the inability of the
1190 publisher to select datastore content at the requested cadence.
1192 If a request is rejected because the publisher is not able to serve
1193 it, the publisher SHOULD include in the returned error hints which
1194 help a subscriber understand subscription parameters might have been
1195 accepted for the request. These hints would be included within the
1196 yang-data structure "establish-subscription-error-datastore".
1197 However even with these hints, there are no guarantee that subsequent
1198 requests will in fact be accepted.
1200 The specific parameters to be returned as part of the RPC error
1201 response depend on the specific transport that is used to manage the
1202 subscription. For example, in the case of NETCONF
1203 [I-D.draft-ietf-netconf-netconf-event-notifications], when a
1204 subscription request is rejected, the NETCONF RPC reply would be
1205 expected to include an "rpc-error" element with the following
1206 elements:
1208 o "error-type" of "application".
1210 o "error-tag" of "operation-failed".
1212 o Optionally, an "error-severity" of "error".
1214 o Optionally, "error-info" containing XML-encoded data with hints
1215 for parameter settings that might result in future RPC success per
1216 yang-data definition "establish-subscription-error-datastore".
1218 For example, for the following request:
1220
1222
1225
1227 ds:operational
1228
1229
1231 /ex:foo
1232
1233
1234 100
1235
1236
1237
1239 Figure 9: Establish-subscription request example 2
1241 a publisher that cannot serve on-change updates but periodic updates
1242 might return the following:
1244
1247
1248 application
1249 operation-failed
1250 error
1251 /yp:periodic/yp:period
1252
1253
1254 yp:on-change-unsupported
1255
1256
1257
1258
1260 Figure 10: Establish-subscription error response example 2
1262 4.4.2. Modify-subscription RPC
1264 The subscriber MAY invoke the "modify-subscription" RPC for a
1265 subscription it previously established. The subscriber will include
1266 newly desired values in the "modify-subscription" RPC. Parameters
1267 not included MUST remain unmodified. Below is an example where a
1268 subscriber attempts to modify the period and datastore XPath filter
1269 of a subscription.
1271
1273
1276 1011
1277
1279 ds:operational
1280
1281
1283 /ex:bar
1284
1285
1286 250
1287
1288
1289
1291 Figure 11: Modify subscription request
1293 The publisher MUST respond to the subscription modification request.
1294 If the request is rejected, the existing subscription is left
1295 unchanged, and the publisher MUST send an RPC error response. This
1296 response might have hints encapsulated within the yang-data structure
1297 "modify-subscription-error-datastore". A subscription MAY be
1298 modified multiple times.
1300 The specific parameters to be returned in as part of the RPC error
1301 response depend on the specific transport that is used to manage the
1302 subscription. In the case of NETCONF
1303 [I-D.draft-ietf-netconf-netconf-event-notifications], when a
1304 subscription request is rejected, the NETCONF RPC reply MUST include
1305 an "rpc-error" element with the following elements:
1307 o "error-type" of "application".
1309 o "error-tag" of "operation-failed".
1311 o Optionally, an "error-severity" of "error" (this MAY but does not
1312 have to be included).
1314 o "error-path" pointing to the object or parameter that caused the
1315 rejection.
1317 o Optionally, "error-info" containing XML-encoded data with hints
1318 for parameter settings that might result in future RPC success per
1319 yang-data definition "modify-subscription-error-datastore".
1321 A configured subscription cannot be modified using "modify-
1322 subscription" RPC. Instead, the configuration needs to be edited as
1323 needed.
1325 4.4.3. Delete-subscription RPC
1327 To stop receiving updates from a subscription and effectively delete
1328 a subscription that had previously been established using an
1329 "establish-subscription" RPC, a subscriber can send a "delete-
1330 subscription" RPC, which takes as only input the subscription's "id".
1331 This RPC is unmodified from
1332 [I-D.draft-ietf-netconf-subscribed-notifications].
1334 4.4.4. Resync-subscription RPC
1336 This RPC is supported only for on-change subscriptions previously
1337 established using an "establish-subscription" RPC. For example:
1339
1341
1344 1011
1345
1346
1348 Resync subscription
1350 On receipt, a publisher must either accept the request and quickly
1351 follow with a "push-update", or send an appropriate error within an
1352 rpc error response. Within an error response, the publisher MAY
1353 include supplemental information about the reasons within the yang-
1354 data structure "resync-subscription-error".
1356 4.4.5. YANG Module Synchronization
1358 To make subscription requests, the subscriber needs to know the YANG
1359 datastore schemas used by the publisher, which are available via the
1360 YANG Library module, ietf-yang-library.yang from [RFC7895]. The
1361 receiver is expected to know the YANG library information before
1362 starting a subscription.
1364 The set of modules, revisions, features, and deviations can change at
1365 run-time (if supported by the publisher implementation). For this
1366 purpose, the YANG library provides a simple "yang-library-change"
1367 notification that informs the subscriber that the library has
1368 changed. In this case, a subscription may need to be updated to take
1369 the updates into account. The receiver may also need to be informed
1370 of module changes in order to process updates regarding datastore
1371 nodes from changed modules correctly.
1373 5. YANG Module
1375 file "ietf-yang-push@2018-09-21.yang"
1376 module ietf-yang-push {
1377 yang-version 1.1;
1378 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push";
1379 prefix yp;
1381 import ietf-yang-types {
1382 prefix yang;
1383 reference
1384 "RFC 6991: Common YANG Data Types";
1385 }
1386 import ietf-subscribed-notifications {
1387 prefix sn;
1388 reference
1389 "draft-ietf-netconf-subscribed-notifications:
1390 Customized Subscriptions to a Publisher's Event Streams
1392 NOTE TO RFC Editor: Please replace above reference to
1393 draft-ietf-netconf-subscribed-notifications with RFC number
1394 when published (i.e. RFC xxxx).";
1395 }
1396 import ietf-datastores {
1397 prefix ds;
1398 reference
1399 "RFC 8342: Network Management Datastore Architecture (NMDA)";
1400 }
1401 import ietf-restconf {
1402 prefix rc;
1403 reference
1404 "RFC 8040: RESTCONF Protocol";
1405 }
1407 import ietf-yang-patch {
1408 prefix ypatch;
1409 reference
1410 "RFC 8072: YANG Patch";
1411 }
1412 organization "IETF";
1413 contact
1414 "WG Web:
1415 WG List:
1417 Editor: Alexander Clemm
1418
1420 Editor: Eric Voit
1421
1423 Editor: Alberto Gonzalez Prieto
1424
1426 Editor: Ambika Prasad Tripathy
1427
1429 Editor: Einar Nilsen-Nygaard
1430
1432 Editor: Andy Bierman
1433
1435 Editor: Balazs Lengyel
1436 ";
1438 description
1439 "This module contains YANG specifications for YANG push.
1441 Copyright (c) 2018 IETF Trust and the persons identified as authors
1442 of the code. All rights reserved.
1444 Redistribution and use in source and binary forms, with or without
1445 modification, is permitted pursuant to, and subject to the license
1446 terms contained in, the Simplified BSD License set forth in Section
1447 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents
1448 (https://trustee.ietf.org/license-info).
1450 This version of this YANG module is part of
1451 draft-ietf-netconf-yang-push-19; see the RFC itself for full
1452 legal notices.
1454 NOTE TO RFC EDITOR: Please replace above reference to
1455 draft-ietf-netconf-yang-push-19 with RFC number when published
1456 (i.e. RFC xxxx).";
1458 revision 2018-09-21 {
1459 description
1460 "Initial revision.
1461 NOTE TO RFC EDITOR:
1462 (1)Please replace the above revision date to
1463 the date of RFC publication when published.
1464 (2) Please replace the date in the file name
1465 (ietf-yang-push@2018-09-21.yang) to the date of RFC publication.
1466 (3) Please replace the following reference to
1467 draft-ietf-netconf-yang-push-19 with RFC number when published
1468 (i.e. RFC xxxx).";
1469 reference
1470 "draft-ietf-netconf-yang-push-19";
1471 }
1473 /*
1474 * FEATURES
1475 */
1477 feature on-change {
1478 description
1479 "This feature indicates that on-change triggered subscriptions
1480 are supported.";
1481 }
1483 /*
1484 * IDENTITIES
1485 */
1487 /* Error type identities for datastore subscription */
1489 identity resync-subscription-error {
1490 description
1491 "Problem found while attempting to fulfill an
1492 'resync-subscription' RPC request. ";
1493 }
1495 identity cant-exclude {
1496 base sn:establish-subscription-error;
1497 description
1498 "Unable to remove the set of 'excluded-changes'. This means the
1499 publisher is unable to restrict 'push-change-update's to just the
1500 change types requested for this subscription.";
1501 }
1503 identity datastore-not-subscribable {
1504 base sn:establish-subscription-error;
1505 base sn:subscription-terminated-reason;
1506 description
1507 "This is not a subscribable datastore.";
1508 }
1510 identity no-such-subscription-resync {
1511 base resync-subscription-error;
1512 description
1513 "Referenced subscription doesn't exist. This may be as a result of
1514 a non-existent subscription ID, an ID which belongs to another
1515 subscriber, or an ID for configured subscription.";
1516 }
1518 identity on-change-unsupported {
1519 base sn:establish-subscription-error;
1520 description
1521 "On-change is not supported for any objects which are selectable
1522 by this filter.";
1523 }
1525 identity on-change-sync-unsupported {
1526 base sn:establish-subscription-error;
1527 description
1528 "Neither sync on start nor resynchronization are supported for
1529 this subscription. This error will be used for two reasons.
1530 First if an 'establish-subscription' RPC includes
1531 'sync-on-start', yet the publisher can't support sending a
1532 'push-update' for this subscription for reasons other than
1533 'on-change-unsupported' or 'sync-too-big'. And second,
1534 if the 'resync-subscription' RPC is invoked either for an
1535 existing periodic subscription, or for an on-change subscription
1536 which can't support resynchronization.";
1537 }
1539 identity period-unsupported {
1540 base sn:establish-subscription-error;
1541 base sn:modify-subscription-error;
1542 base sn:subscription-suspended-reason;
1543 description
1544 "Requested time period or dampening-period is too short. This
1545 can be for both periodic and on-change subscriptions (with or
1546 without dampening.) Hints suggesting alternative periods may
1547 be returned as supplemental information.";
1548 }
1550 identity update-too-big {
1551 base sn:establish-subscription-error;
1552 base sn:modify-subscription-error;
1553 base sn:subscription-suspended-reason;
1554 description
1555 "Periodic or on-change push update datatrees exceed a maximum
1556 size limit. Hints on estimated size of what was too big may
1557 be returned as supplemental information.";
1558 }
1560 identity sync-too-big {
1561 base sn:establish-subscription-error;
1562 base sn:modify-subscription-error;
1563 base resync-subscription-error;
1564 base sn:subscription-suspended-reason;
1565 description
1566 "Sync-on-start or resynchronization datatree exceeds a maximum
1567 size limit. Hints on estimated size of what was too big may be
1568 returned as supplemental information.";
1569 }
1571 identity unchanging-selection {
1572 base sn:establish-subscription-error;
1573 base sn:modify-subscription-error;
1574 base sn:subscription-terminated-reason;
1575 description
1576 "Selection filter is unlikely to ever select datatree nodes. This
1577 means that based on the subscriber's current access rights, the
1578 publisher recognizes that the selection filter is unlikely to ever
1579 select datatree nodes which change. Examples for this might be
1580 that node or subtree doesn't exist, read access is not permitted
1581 for a receiver, or static objects that only change at reboot have
1582 been chosen.";
1583 }
1585 /*
1586 * TYPE DEFINITIONS
1587 */
1589 typedef change-type {
1590 type enumeration {
1591 enum "create" {
1592 description
1593 "A change that refers to the creation of a new datastore node.";
1594 }
1595 enum "delete" {
1596 description
1597 "A change that refers to the deletion of a datastore node.";
1598 }
1599 enum "insert" {
1600 description
1601 "A change that refers to the insertion of a new
1602 user-ordered datastore node.";
1603 }
1604 enum "move" {
1605 description
1606 "A change that refers to a reordering of the target datastore
1607 node";
1608 }
1609 enum "replace" {
1610 description
1611 "A change that refers to a replacement of the target
1612 datastore node's value.";
1613 }
1614 }
1615 description
1616 "Specifies different types of datastore changes.";
1617 reference
1618 "RFC 8072 section 2.5, with a delta that it is valid for a
1619 receiver to process an update record which performs a create
1620 operation on a datastore node the receiver believes exists, or to
1621 process a delete on a datastore node the receiver believes is
1622 missing.";
1623 }
1625 typedef selection-filter-ref {
1626 type leafref {
1627 path "/sn:filters/yp:selection-filter/yp:filter-id";
1628 }
1629 description
1630 "This type is used to reference a selection filter.";
1631 }
1633 /*
1634 * GROUP DEFINITIONS
1635 */
1637 grouping datastore-criteria {
1638 description
1639 "A grouping to define criteria for which selected objects from
1640 a targeted datastore should be included in push updates.";
1641 leaf datastore {
1642 type identityref {
1643 base ds:datastore;
1644 }
1645 mandatory true;
1646 description
1647 "Datastore from which to retrieve data.";
1648 }
1649 uses selection-filter-objects;
1650 }
1652 grouping selection-filter-types {
1653 description
1654 "This grouping defines the types of selectors for objects from a
1655 datastore.";
1656 choice filter-spec {
1657 description
1658 "The content filter specification for this request.";
1659 anydata datastore-subtree-filter {
1660 if-feature "sn:subtree";
1661 description
1662 "This parameter identifies the portions of the
1663 target datastore to retrieve.";
1664 reference
1665 "RFC 6241: Network Configuration Protocol, Section 6.";
1666 }
1667 leaf datastore-xpath-filter {
1668 if-feature "sn:xpath";
1669 type yang:xpath1.0;
1670 description
1671 "This parameter contains an XPath expression identifying the
1672 portions of the target datastore to retrieve.
1674 If the expression returns a node-set, all nodes in the
1675 node-set are selected by the filter. Otherwise, if the
1676 expression does not return a node-set, the filter
1677 doesn't select any nodes.
1679 The expression is evaluated in the following XPath context:
1681 o The set of namespace declarations are those in scope on
1682 the 'datastore-xpath-filter' leaf element.
1684 o The set of variable bindings is empty.
1686 o The function library is the core function library, and
1687 the XPath functions defined in section 10 in RFC 7950.
1689 o The context node is the root node of the target
1690 datastore.";
1691 }
1692 }
1693 }
1695 grouping selection-filter-objects {
1696 description
1697 "This grouping defines a selector for objects from a
1698 datastore.";
1699 choice selection-filter {
1700 description
1701 "The source of the selection filter applied to the subscription.
1702 This will come either referenced from a global list, or be
1703 provided within the subscription itself.";
1704 case by-reference {
1705 description
1706 "Incorporate a filter that has been configured separately.";
1707 leaf selection-filter-ref {
1708 type selection-filter-ref;
1709 mandatory true;
1710 description
1711 "References an existing selection filter which is to be
1712 applied to the subscription.";
1713 }
1714 }
1715 case within-subscription {
1716 description
1717 "Local definition allows a filter to have the same lifecycle
1718 as the subscription.";
1719 uses selection-filter-types;
1721 }
1722 }
1724 }
1726 grouping update-policy-modifiable {
1727 description
1728 "This grouping describes the datastore specific subscription
1729 conditions that can be changed during the lifetime of the
1730 subscription.";
1731 choice update-trigger {
1732 mandatory true;
1733 description
1734 "Defines necessary conditions for sending an event record to
1735 the subscriber.";
1736 case periodic {
1737 container periodic {
1738 presence "indicates a periodic subscription";
1739 description
1740 "The publisher is requested to notify periodically the
1741 current values of the datastore as defined by the selection
1742 filter.";
1743 leaf period {
1744 type yang:timeticks;
1745 mandatory true;
1746 description
1747 "Duration of time which should occur between periodic
1748 push updates.";
1749 }
1750 leaf anchor-time {
1751 type yang:date-and-time;
1752 description
1753 "Designates a timestamp before or after which a series of
1754 periodic push updates are determined. The next update
1755 will take place at a whole multiple interval from the
1756 anchor time. For example, for an anchor time is set for
1757 the top of a particular minute and a period interval of a
1758 minute, updates will be sent at the top of every minute
1759 this subscription is active.";
1760 }
1761 }
1762 }
1763 case on-change {
1764 if-feature "on-change";
1765 container on-change {
1766 presence "indicates an on-change subscription";
1767 description
1768 "The publisher is requested to notify changes in values in
1769 the datastore subset as defined by a selection filter.";
1770 leaf dampening-period {
1771 type yang:timeticks;
1772 default 0;
1773 description
1774 "Specifies the minimum interval between the assembly of
1775 successive update records for a single receiver of a
1776 subscription. Whenever subscribed objects change, and a
1777 dampening period interval (which may be zero) has elapsed
1778 since the previous update record creation for a receiver,
1779 then any subscribed objects and properties which have
1780 changed since the previous update record will have their
1781 current values marshalled and placed into a new update
1782 record.";
1783 }
1784 }
1785 }
1786 }
1787 }
1789 grouping update-policy {
1790 description
1791 "This grouping describes the datastore specific subscription
1792 conditions of a subscription.";
1793 uses update-policy-modifiable {
1794 augment "update-trigger/on-change/on-change" {
1795 description
1796 "Includes objects not modifiable once subscription is
1797 established.";
1798 leaf sync-on-start {
1799 type boolean;
1800 default "true";
1801 description
1802 "When this object is set to false, it restricts an on-change
1803 subscription from sending push-update notifications. When
1804 false, pushing a full selection per the terms of the
1805 selection filter MUST NOT be done for this subscription.
1806 Only updates about changes, i.e. only push-change-update
1807 notifications are sent. When true (default behavior),
1808 in order to facilitate a receiver's synchronization, a full
1809 update is sent when the subscription starts using a
1810 push-update notification. After that, push-change-update
1811 notifications are exclusively sent unless the publisher
1812 chooses to resync the subscription via a new push-update
1813 notification.";
1814 }
1815 leaf-list excluded-change {
1816 type change-type;
1817 description
1818 "Use to restrict which changes trigger an update.
1819 For example, if modify is excluded, only creation and
1820 deletion of objects is reported.";
1821 }
1822 }
1823 }
1824 }
1826 grouping hints {
1827 description
1828 "Parameters associated with some error for a subscription made
1829 upon a datastore.";
1830 leaf period-hint {
1831 type yang:timeticks;
1832 description
1833 "Returned when the requested time period is too short. This
1834 hint can assert a viable period for either a periodic push
1835 cadence or an on-change dampening interval.";
1836 }
1837 leaf filter-failure-hint {
1838 type string;
1839 description
1840 "Information describing where and/or why a provided filter
1841 was unsupportable for a subscription.";
1842 }
1843 leaf object-count-estimate {
1844 type uint32;
1845 description
1846 "If there are too many objects which could potentially be
1847 returned by the selection filter, this identifies the estimate
1848 of the number of objects which the filter would potentially
1849 pass.";
1850 }
1851 leaf object-count-limit {
1852 type uint32;
1853 description
1854 "If there are too many objects which could be returned by the
1855 selection filter, this identifies the upper limit of the
1856 publisher's ability to service for this subscription.";
1857 }
1858 leaf kilobytes-estimate {
1859 type uint32;
1860 description
1861 "If the returned information could be beyond the capacity of
1862 the publisher, this would identify the data size which could
1863 result from this selection filter.";
1864 }
1865 leaf kilobytes-limit {
1866 type uint32;
1867 description
1868 "If the returned information would be beyond the capacity of
1869 the publisher, this identifies the upper limit of the
1870 publisher's ability to service for this subscription.";
1871 }
1872 }
1874 /*
1875 * RPCs
1876 */
1878 rpc resync-subscription {
1879 if-feature "on-change";
1880 description
1881 "This RPC allows a subscriber of an active on-change
1882 subscription to request a full push of objects.
1883 A successful invocation results in a push-update of all
1884 datastore nodes that the subscriber is permitted to access.
1885 This RPC can only be invoked on the same session on which the
1886 subscription is currently active. In case of an error, a
1887 resync-subscription-error is sent as part of an error
1888 response.";
1889 input {
1890 leaf id {
1891 type sn:subscription-id;
1892 mandatory true;
1893 description
1894 "id of the subscription that is to be resynced.";
1895 }
1896 }
1897 }
1899 rc:yang-data resync-subscription-error {
1900 container resync-subscription-error {
1901 description
1902 "If a 'resync-subscription' RPC fails, the subscription is not
1903 resynced and the RPC error response MUST indicate the reason
1904 for this failure. This yang-data MAY be inserted as structured
1905 data within a subscription's RPC error response to indicate the
1906 failure reason.";
1907 leaf reason {
1908 type identityref {
1909 base resync-subscription-error;
1910 }
1911 mandatory true;
1912 description
1913 "Indicates the reason why the publisher has declined a request
1914 for subscription resynchronization.";
1916 }
1917 uses hints;
1918 }
1919 }
1921 augment "/sn:establish-subscription/sn:input" {
1922 when "sn:target/yp:datastore";
1923 description
1924 "This augmentation adds additional subscription parameters that
1925 apply specifically to datastore updates to RPC input.";
1926 uses update-policy;
1927 }
1929 augment "/sn:establish-subscription/sn:input/sn:target" {
1930 description
1931 "This augmentation adds the datastore as a valid target
1932 for the subscription to RPC input.";
1933 case datastore {
1934 description
1935 "Information specifying the parameters of an request for a
1936 datastore subscription.";
1937 uses datastore-criteria;
1938 }
1939 }
1941 rc:yang-data establish-subscription-datastore-error-info {
1942 container establish-subscription-datastore-error-info {
1943 description
1944 "If any 'establish-subscription' RPC parameters are
1945 unsupportable against the datastore, a subscription is not
1946 created and the RPC error response MUST indicate the reason why
1947 the subscription failed to be created. This yang-data MAY be
1948 inserted as structured data within a subscription's RPC error
1949 response to indicate the failure reason. This yang-data MUST be
1950 inserted if hints are to be provided back to the subscriber.";
1951 leaf reason {
1952 type identityref {
1953 base sn:establish-subscription-error;
1954 }
1955 description
1956 "Indicates the reason why the subscription has failed to
1957 be created to a targeted datastore.";
1958 }
1959 uses hints;
1960 }
1961 }
1963 augment "/sn:modify-subscription/sn:input" {
1964 when "sn:target/yp:datastore";
1965 description
1966 "This augmentation adds additional subscription parameters
1967 specific to datastore updates.";
1968 uses update-policy-modifiable;
1969 }
1971 augment "/sn:modify-subscription/sn:input/sn:target" {
1972 description
1973 "This augmentation adds the datastore as a valid target
1974 for the subscription to RPC input.";
1975 case datastore {
1976 description
1977 "Information specifying the parameters of an request for a
1978 datastore subscription.";
1979 uses selection-filter-objects;
1980 }
1981 }
1983 rc:yang-data modify-subscription-datastore-error-info {
1984 container modify-subscription-datastore-error-info {
1985 description
1986 "This yang-data MAY be provided as part of a subscription's RPC
1987 error response when there is a failure of a
1988 'modify-subscription' RPC which has been made against a
1989 datastore. This yang-data MUST be used if hints are to be
1990 provides back to the subscriber.";
1991 leaf reason {
1992 type identityref {
1993 base sn:modify-subscription-error;
1994 }
1995 description
1996 "Indicates the reason why the subscription has failed to
1997 be modified.";
1998 }
1999 uses hints;
2000 }
2001 }
2003 /*
2004 * NOTIFICATIONS
2005 */
2007 notification push-update {
2008 description
2009 "This notification contains a push update, containing data
2010 subscribed to via a subscription. This notification is sent for
2011 periodic updates, for a periodic subscription. It can also be
2012 used for synchronization updates of an on-change subscription.
2013 This notification shall only be sent to receivers of a
2014 subscription. It does not constitute a general-purpose
2015 notification that would be subscribable as part of the NETCONF
2016 event stream by any receiver.";
2017 leaf id {
2018 type sn:subscription-id;
2019 description
2020 "This references the subscription which drove the notification
2021 to be sent.";
2022 }
2023 anydata datastore-contents {
2024 description
2025 "This contains the updated data. It constitutes a snapshot
2026 at the time-of-update of the set of data that has been
2027 subscribed to. The snapshot corresponds to the same
2028 snapshot that would be returned in a corresponding get
2029 operation with the same selection filter parameters
2030 applied.";
2031 }
2032 leaf incomplete-update {
2033 type empty;
2034 description
2035 "This is a flag which indicates that not all datastore nodes
2036 subscribed to are included with this update. In other words,
2037 the publisher has failed to fulfill its full subscription
2038 obligations, and despite its best efforts is providing an
2039 incomplete set of objects.";
2040 }
2041 }
2043 notification push-change-update {
2044 if-feature "on-change";
2045 description
2046 "This notification contains an on-change push update. This
2047 notification shall only be sent to the receivers of a
2048 subscription; it does not constitute a general-purpose
2049 notification.";
2050 leaf id {
2051 type sn:subscription-id;
2052 description
2053 "This references the subscription which drove the notification
2054 to be sent.";
2055 }
2056 container datastore-changes {
2057 description
2058 "This contains the set of datastore changes of the
2059 target datastore starting at the time of the
2060 previous update, per the terms of the subscription.
2061 The datastore changes are encoded per RFC 8027
2062 (YANG Patch).";
2063 uses ypatch:yang-patch;
2064 }
2065 leaf incomplete-update {
2066 type empty;
2067 description
2068 "The presence of this object indicates not all changes which
2069 have occurred since the last update are included with this
2070 update. In other words, the publisher has failed to
2071 fulfill its full subscription obligations, for example in
2072 cases where it was not able to keep up with a change burst.";
2073 }
2074 }
2076 augment "/sn:subscription-started" {
2077 description
2078 "This augmentation adds datastore-specific objects to
2079 the notification that a subscription has started.";
2080 uses update-policy;
2081 }
2083 augment "/sn:subscription-started/sn:target" {
2084 description
2085 "This augmentation allows the datastore to be included as part
2086 of the notification that a subscription has started.";
2087 case datastore {
2088 uses datastore-criteria {
2089 refine "selection-filter/within-subscription" {
2090 description
2091 "Specifies the selection filter and where it originated
2092 from. If the 'selection-filter-ref' is populated,
2093 the filter within the subscription came from the 'filters'
2094 container. Otherwise it is populated in-line as part of the
2095 subscription itself.";
2096 }
2097 }
2098 }
2099 }
2101 augment "/sn:subscription-modified" {
2102 description
2103 "This augmentation adds datastore-specific objects to
2104 the notification that a subscription has been modified.";
2105 uses update-policy;
2106 }
2107 augment "/sn:subscription-modified/sn:target" {
2108 description
2109 "This augmentation allows the datastore to be included as part
2110 of the notification that a subscription has been modified.";
2111 case datastore {
2112 uses datastore-criteria {
2113 refine "selection-filter/within-subscription" {
2114 description
2115 "Specifies where the selection filter, and where it came
2116 from within the subscription and then populated within this
2117 notification. If the 'selection-filter-ref' is populated,
2118 the filter within the subscription came from the 'filters'
2119 container. Otherwise it is populated in-line as part of the
2120 subscription itself.";
2121 }
2122 }
2123 }
2124 }
2126 /*
2127 * DATA NODES
2128 */
2130 augment "/sn:filters" {
2131 description
2132 "This augmentation allows the datastore to be included as part
2133 of the selection filtering criteria for a subscription.";
2134 list selection-filter {
2135 key "filter-id";
2136 description
2137 "A list of pre-configured filters that can be applied
2138 to datastore subscriptions.";
2139 leaf filter-id {
2140 type string;
2141 description
2142 "An id to differentiate between selection filters.";
2143 }
2144 uses selection-filter-types;
2145 }
2146 }
2148 augment "/sn:subscriptions/sn:subscription" {
2149 when "sn:target/yp:datastore";
2150 description
2151 "This augmentation adds many datastore specific objects to a
2152 subscription.";
2153 uses update-policy;
2154 }
2155 augment "/sn:subscriptions/sn:subscription/sn:target" {
2156 description
2157 "This augmentation allows the datastore to be included as part
2158 of the selection filtering criteria for a subscription.";
2159 case datastore {
2160 uses datastore-criteria;
2161 }
2162 }
2163 }
2165
2167 6. IANA Considerations
2169 This document registers the following namespace URI in the "IETF XML
2170 Registry" [RFC3688]:
2172 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push
2173 Registrant Contact: The IESG.
2174 XML: N/A; the requested URI is an XML namespace.
2176 This document registers the following YANG module in the "YANG Module
2177 Names" registry [RFC6020]:
2179 Name: ietf-yang-push
2180 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push
2181 Prefix: yp
2182 Reference: draft-ietf-netconf-yang-push-19.txt (RFC form)
2184 7. Security Considerations
2186 The YANG module specified in this document defines a schema for data
2187 that is designed to be accessed via network management protocols such
2188 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer
2189 is the secure transport layer, and the mandatory-to-implement secure
2190 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer
2191 is HTTPS, and the mandatory-to-implement secure transport is TLS
2192 [RFC5246].
2194 The Network Configuration Access Control Model (NACM) [RFC8341]
2195 provides the means to restrict access for particular NETCONF or
2196 RESTCONF users to a preconfigured subset of all available NETCONF or
2197 RESTCONF protocol operations and content.
2199 There are a number of data nodes defined in this YANG module that are
2200 writable/creatable/deletable (i.e., config true, which is the
2201 default). These data nodes may be considered sensitive or vulnerable
2202 in some network environments. Write operations (e.g., edit-config)
2203 to these data nodes without proper protection can have a negative
2204 effect on network operations. These are the subtrees and data nodes
2205 and their sensitivity/vulnerability. (It should be noted that the
2206 YANG module augments the YANG module from
2207 [I-D.draft-ietf-netconf-subscribed-notifications]. All security
2208 considerations that are listed there are relevant also for datastore
2209 subscriptions. In the following, we focus on the data nodes that are
2210 newly introduced here.)
2212 o Subtree "selection-filter" under container "filters": This subtree
2213 allows to specify which objects or subtrees to include in a
2214 datastore subscription. An attacker could attempt to modify the
2215 filter. For example, the filter might be modified to result in
2216 very few objects being filtered in order to attempt to overwhelm
2217 the receiver. Alternatively, the filter might be modified to
2218 result in certain objects to be excluded from updates, in order to
2219 have certain changes go unnoticed.
2221 o Subtree "datastore" in choice "target" in list "subscription":
2222 Analogous to "selection filter", an attacker might attempt to
2223 modify the objects being filtered in order to overwhelm a receiver
2224 with a larger volume of object updates than expected, or to have
2225 certain changes go unnoticed.
2227 o Choice "update-trigger" in list "subscription": By modifying the
2228 update trigger, an attacker might alter the updates that are being
2229 sent in order to confuse a receiver, to withhold certain updates
2230 to be sent to the receiver, and/or to overwhelm a receiver. For
2231 example, an attacker might modify the period with which updates
2232 are reported for a periodic subscription, or it might modify the
2233 dampening period for an on-change subscription, resulting in
2234 greater delay of successive updates (potentially affecting
2235 responsiveness of applications that depend on the updates) or in a
2236 high volume of updates (to exhaust receiver resources).
2238 o RPC "resync-subscription": This RPC allows a subscriber of an on-
2239 change subscription to request a full push of objects in the
2240 subscription's scope. This can result in a large volume of data.
2241 An attacker could attempt to use this RPC to exhaust resources on
2242 the server to generate the data, and attempt to overwhelm a
2243 receiver with the resulting data volume.
2245 8. Acknowledgments
2247 For their valuable comments, discussions, and feedback, we wish to
2248 acknowledge Tim Jenkins, Martin Bjorklund, Kent Watsen, Susan Hares,
2249 Yang Geng, Peipei Guo, Michael Scharf, Guangying Zheng, Tom Petch,
2250 Henk Birkholz, Reshad Rahman, Qin Wu, Rohit Ranade, and Rob Wilton.
2252 9. References
2254 9.1. Normative References
2256 [I-D.draft-ietf-netconf-subscribed-notifications]
2257 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A.,
2258 and E. Nilsen-Nygaard, "Custom Subscription to Event
2259 Streams", draft-ietf-netconf-subscribed-notifications-13
2260 (work in progress), August 2018.
2262 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
2263 DOI 10.17487/RFC3688, January 2004,
2264 .
2266 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
2267 the Network Configuration Protocol (NETCONF)", RFC 6020,
2268 DOI 10.17487/RFC6020, October 2010,
2269 .
2271 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF)
2272 Base Notifications", RFC 6470, DOI 10.17487/RFC6470,
2273 February 2012, .
2275 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
2276 RFC 6991, DOI 10.17487/RFC6991, July 2013,
2277 .
2279 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
2280 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016,
2281 .
2283 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
2284 RFC 7950, DOI 10.17487/RFC7950, August 2016,
2285 .
2287 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2288 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
2289 .
2291 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch
2292 Media Type", RFC 8072, DOI 10.17487/RFC8072, February
2293 2017, .
2295 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
2296 Access Control Model", STD 91, RFC 8341,
2297 DOI 10.17487/RFC8341, March 2018,
2298 .
2300 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
2301 and R. Wilton, "Network Management Datastore Architecture
2302 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
2303 .
2305 9.2. Informative References
2307 [I-D.draft-ietf-netconf-netconf-event-notifications]
2308 Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard,
2309 E., and A. Tripathy, "NETCONF Support for Event
2310 Notifications", August 2018.
2312 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
2313 (TLS) Protocol Version 1.2", RFC 5246,
2314 DOI 10.17487/RFC5246, August 2008,
2315 .
2317 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
2318 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
2319 .
2321 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
2322 and A. Bierman, Ed., "Network Configuration Protocol
2323 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
2324 .
2326 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
2327 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
2328 .
2330 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements
2331 for Subscription to YANG Datastores", RFC 7923,
2332 DOI 10.17487/RFC7923, June 2016,
2333 .
2335 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
2336 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
2337 .
2339 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface
2340 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018,
2341 .
2343 Appendix A. Appendix A: Subscription Errors
2345 A.1. RPC Failures
2347 Rejection of an RPC for any reason is indicated by via RPC error
2348 response from the publisher. Valid RPC errors returned include both
2349 existing transport layer RPC error codes, such as those seen with
2350 NETCONF in [RFC6241], as well as subscription specific errors such as
2351 those defined within the YANG model. As a result, how subscription
2352 errors are encoded within an RPC error response is transport
2353 dependent.
2355 References to specific identities within the either the subscribed-
2356 notifications YANG model or the yang-push YANG model may be returned
2357 as part of the error responses resulting from failed attempts at
2358 datastore subscription. Following are valid errors per RPC (note:
2359 throughout this section the prefix 'sn' indicates an item imported
2360 from the subscribed-notifications.yang model):
2362 establish-subscription modify-subscription
2363 ---------------------- -------------------
2364 cant-exclude sn:filter-unsupported
2365 datastore-not-subscribable sn:insufficient-resources
2366 sn:dscp-unavailable sn:no-such-subscription
2367 sn:filter-unsupported period-unsupported
2368 sn:insufficient-resources update-too-big
2369 on-change-unsupported sync-too-big
2370 on-change-sync-unsupported unchanging-selection
2371 period-unsupported
2372 update-too-big resync-subscription
2373 sync-too-big --------------------
2374 unchanging-selection no-such-subscription-resync
2375 sync-too-big
2377 delete-subscription kill-subscription
2378 ---------------------- -----------------
2379 sn:no-such-subscription sn:no-such-subscription
2381 There is one final set of transport independent RPC error elements
2382 included in the YANG model. These are the following four yang-data
2383 structures for failed datastore subscriptions:
2385 1. yang-data establish-subscription-error-datastore
2386 This MUST be returned if information identifying the reason for an
2387 RPC error has not been placed elsewhere within the transport
2388 portion of a failed "establish-subscription" RPC response. This
2389 MUST be sent if hints are included.
2391 2. yang-data modify-subscription-error-datastore
2392 This MUST be returned if information identifying the reason for an
2393 RPC error has not been placed elsewhere within the transport
2394 portion of a failed "modifiy-subscription" RPC response. This
2395 MUST be sent if hints are included.
2397 3. yang-data sn:delete-subscription-error
2398 This MUST be returned if information identifying the reason for an
2399 RPC error has not been placed elsewhere within the transport
2400 portion of a failed "delete-subscription" or "kill-subscription"
2401 RPC response.
2403 4. yang-data resync-subscription-error
2404 This MUST be returned if information identifying the reason for an
2405 RPC error has not been placed elsewhere within the transport
2406 portion of a failed "resync-subscription" RPC response.
2408 A.2. Notifications of Failure
2410 A subscription may be unexpectedly terminated or suspended
2411 independent of any RPC or configuration operation. In such cases,
2412 indications of such a failure MUST be provided. To accomplish this,
2413 the following types of error identities may be returned within the
2414 corresponding subscription state change notification:
2416 subscription-terminated subscription-suspended
2417 ----------------------- ----------------------
2418 datastore-not-subscribable sn:insufficient-resources
2419 sn:filter-unavailable period-unsupported
2420 sn:no-such-subscription update-too-big
2421 sn:suspension-timeout synchronization-size
2422 unchanging-selection
2424 Appendix B. Changes Between Revisions
2426 (To be removed by RFC editor prior to publication)
2428 v18 - v19
2430 o Minor updates per WGLC comments.
2432 v17 - v18
2434 o Minor updates per WGLC comments.
2436 v16 - v17
2438 o Minor updates to YANG module, incorporating comments from Tom
2439 Petch.
2441 o Updated references.
2443 v15 - v16
2445 o Updated security considerations.
2447 o Updated references.
2449 o Addressed comments from last call review, specifically comments
2450 received from Martin Bjorklund.
2452 v14 - v15
2454 o Minor text fixes. Includes a fix to on-change update calculation
2455 to cover churn when an object changes to and from a value during a
2456 dampening period.
2458 v13 - v14
2460 o Minor text fixes.
2462 v12 - v13
2464 o Hint negotiation models now show error examples.
2466 o yang-data structures for rpc errors.
2468 v11 - v12
2470 o Included Martin's review clarifications.
2472 o QoS moved to subscribed-notifications
2474 o time-of-update removed as it is redundant with RFC5277's
2475 eventTime, and other times from notification-messages.
2477 o Error model moved to match existing implementations
2478 o On-change notifiable removed, how to do this is implementation
2479 specific.
2481 o NMDA model supported. Non NMDA version at https://github.com/
2482 netconf-wg/yang-push/
2484 v10 - v11
2486 o Promise model reference added.
2488 o Error added for no-such-datastore
2490 o Inherited changes from subscribed notifications (such as optional
2491 feature definitions).
2493 o scrubbed the examples for proper encodings
2495 v09 - v10
2497 o Returned to the explicit filter subtyping of v00-v05
2499 o identityref to ds:datastore made explicit
2501 o Returned ability to modify a selection filter via RPC.
2503 v08 - v09
2505 o Minor tweaks cleaning up text, removing appendicies, and making
2506 reference to revised-datastores.
2508 o Subscription-id (now:id) optional in push updates, except when
2509 encoded in RFC5277, Section 4 one-way notification.
2511 o Finished adding the text descibing the resync subscription RPC.
2513 o Removed relationships to other drafts and future technology
2514 appendicies as this work is being explored elsewhere.
2516 o Deferred the multi-line card issue to new drafts
2518 o Simplified the NACM interactions.
2520 v07 - v08
2522 o Updated YANG models with minor tweaks to accommodate changes of
2523 ietf-subscribed-notifications.
2525 v06 - v07
2526 o Clarifying text tweaks.
2528 o Clarification that filters act as selectors for subscribed
2529 datastore nodes; support for value filters not included but
2530 possible as a future extension
2532 o Filters don't have to be matched to existing YANG objects
2534 v05 - v06
2536 o Security considerations updated.
2538 o Base YANG model in [subscribe] updated as part of move to
2539 identities, YANG augmentations in this doc matched up
2541 o Terms refined and text updates throughout
2543 o Appendix talking about relationship to other drafts added.
2545 o Datastore replaces stream
2547 o Definitions of filters improved
2549 v04 to v05
2551 o Referenced based subscription document changed to Subscribed
2552 Notifications from 5277bis.
2554 o Getting operational data from filters
2556 o Extension notifiable-on-change added
2558 o New appendix on potential futures. Moved text into there from
2559 several drafts.
2561 o Subscription configuration section now just includes changed
2562 parameters from Subscribed Notifications
2564 o Subscription monitoring moved into Subscribed Notifications
2566 o New error and hint mechanisms included in text and in the yang
2567 model.
2569 o Updated examples based on the error definitions
2571 o Groupings updated for consistency
2573 o Text updates throughout
2574 v03 to v04
2576 o Updates-not-sent flag added
2578 o Not notifiable extension added
2580 o Dampening period is for whole subscription, not single objects
2582 o Moved start/stop into rfc5277bis
2584 o Client and Server changed to subscriber, publisher, and receiver
2586 o Anchor time for periodic
2588 o Message format for synchronization (i.e. sync-on-start)
2590 o Material moved into 5277bis
2592 o QoS parameters supported, by not allowed to be modified by RPC
2594 o Text updates throughout
2596 Authors' Addresses
2598 Alexander Clemm
2599 Huawei
2601 Email: ludwig@clemm.org
2603 Eric Voit
2604 Cisco Systems
2606 Email: evoit@cisco.com
2608 Alberto Gonzalez Prieto
2609 VMware
2611 Email: agonzalezpri@vmware.com
2613 Ambika Prasad Tripathy
2614 Cisco Systems
2616 Email: ambtripa@cisco.com
2617 Einar Nilsen-Nygaard
2618 Cisco Systems
2620 Email: einarnn@cisco.com
2622 Andy Bierman
2623 YumaWorks
2625 Email: andy@yumaworks.com
2627 Balazs Lengyel
2628 Ericsson
2630 Email: balazs.lengyel@ericsson.com