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