idnits 2.17.1
draft-ietf-netconf-yang-push-25.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 1054 has weird spacing: '...---w id sn:...'
== Line 1091 has weird spacing: '...atch-id str...'
== Line 1095 has weird spacing: '...eration enu...'
== Line 1670 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 (May 21, 2019) is 1801 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-24
Summary: 0 errors (**), 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 Futurewei
4 Intended status: Standards Track E. Voit
5 Expires: November 22, 2019 Cisco Systems
6 May 21, 2019
8 Subscription to YANG Datastores
9 draft-ietf-netconf-yang-push-25
11 Abstract
13 This document describes a mechanism that allows subscriber
14 applications to request a continuous and customized stream of updates
15 from a YANG datastore. Providing such visibility into updates
16 enables new capabilities based on the remote mirroring and monitoring
17 of configuration and operational state.
19 Status of This Memo
21 This Internet-Draft is submitted in full conformance with the
22 provisions of BCP 78 and BCP 79.
24 Internet-Drafts are working documents of the Internet Engineering
25 Task Force (IETF). Note that other groups may also distribute
26 working documents as Internet-Drafts. The list of current Internet-
27 Drafts is at https://datatracker.ietf.org/drafts/current/.
29 Internet-Drafts are draft documents valid for a maximum of six months
30 and may be updated, replaced, or obsoleted by other documents at any
31 time. It is inappropriate to use Internet-Drafts as reference
32 material or to cite them other than as "work in progress."
34 This Internet-Draft will expire on November 22, 2019.
36 Copyright Notice
38 Copyright (c) 2019 IETF Trust and the persons identified as the
39 document authors. All rights reserved.
41 This document is subject to BCP 78 and the IETF Trust's Legal
42 Provisions Relating to IETF Documents
43 (https://trustee.ietf.org/license-info) in effect on the date of
44 publication of this document. Please review these documents
45 carefully, as they describe your rights and restrictions with respect
46 to this document. Code Components extracted from this document must
47 include Simplified BSD License text as described in Section 4.e of
48 the Trust Legal Provisions and are provided without warranty as
49 described in the Simplified BSD License.
51 This document may contain material from IETF Documents or IETF
52 Contributions published or made publicly available before November
53 10, 2008. The person(s) controlling the copyright in some of this
54 material may not have granted the IETF Trust the right to allow
55 modifications of such material outside the IETF Standards Process.
56 Without obtaining an adequate license from the person(s) controlling
57 the copyright in such materials, this document may not be modified
58 outside the IETF Standards Process, and derivative works of it may
59 not be created outside the IETF Standards Process, except to format
60 it for publication as an RFC or to translate it into languages other
61 than English.
63 Table of Contents
65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
66 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 3
67 3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 5
68 3.1. Subscription Model . . . . . . . . . . . . . . . . . . . 5
69 3.2. Negotiation of Subscription Policies . . . . . . . . . . 6
70 3.3. On-Change Considerations . . . . . . . . . . . . . . . . 7
71 3.4. Reliability Considerations . . . . . . . . . . . . . . . 8
72 3.5. Data Encodings . . . . . . . . . . . . . . . . . . . . . 9
73 3.6. Defining the Selection with a Datastore . . . . . . . . . 10
74 3.7. Streaming Updates . . . . . . . . . . . . . . . . . . . . 11
75 3.8. Subscription Management . . . . . . . . . . . . . . . . . 13
76 3.9. Receiver Authorization . . . . . . . . . . . . . . . . . 15
77 3.10. On-Change Notifiable Datastore Nodes . . . . . . . . . . 16
78 3.11. Other Considerations . . . . . . . . . . . . . . . . . . 17
79 4. A YANG Data Model for Management of Datastore Push
80 Subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 18
81 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 18
82 4.2. Subscription Configuration . . . . . . . . . . . . . . . 24
83 4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 25
84 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 26
85 5. YANG Module . . . . . . . . . . . . . . . . . . . . . . . . . 31
86 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48
87 7. Security Considerations . . . . . . . . . . . . . . . . . . . 48
88 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 50
89 9. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 50
90 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 50
91 10.1. Normative References . . . . . . . . . . . . . . . . . . 50
92 10.2. Informative References . . . . . . . . . . . . . . . . . 51
93 Appendix A. Appendix A: Subscription Errors . . . . . . . . . . 52
94 A.1. RPC Failures . . . . . . . . . . . . . . . . . . . . . . 52
95 A.2. Notifications of Failure . . . . . . . . . . . . . . . . 54
97 Appendix B. Changes Between Revisions . . . . . . . . . . . . . 54
98 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 58
100 1. Introduction
102 Traditional approaches to provide visibility into managed entities
103 from a remote system have been built on polling. With polling, data
104 is periodically requested and retrieved by a client from a server to
105 stay up-to-date. However, there are issues associated with polling-
106 based management:
108 o Polling incurs significant latency. This latency prohibits many
109 types of application.
111 o Polling cycles may be missed and requests may be delayed or get
112 lost, often when the network is under stress and the need for the
113 data is the greatest.
115 o Polling requests may undergo slight fluctuations, resulting in
116 intervals of different lengths. The resulting data is difficult
117 to calibrate and compare.
119 o For applications that monitor for changes, many remote polling
120 cycles place unwanted and ultimately wasteful load on the network,
121 devices, and applications, particularly when changes occur only
122 infrequently.
124 A more effective alternative to polling is for an application to
125 receive automatic and continuous updates from a targeted subset of a
126 datastore. Accordingly, there is a need for a service that allows
127 applications to subscribe to updates from a datastore and that
128 enables the server (also referred to as publisher) to push and in
129 effect stream those updates. The requirements for such a service
130 have been documented in [RFC7923].
132 This document defines a corresponding solution that is built on top
133 of "Custom Subscription to Event Streams"
134 [I-D.draft-ietf-netconf-subscribed-notifications]. Supplementing
135 that work are YANG data model augmentations, extended RPCs, and new
136 datastore specific update notifications. Transport options for
137 [I-D.draft-ietf-netconf-subscribed-notifications] will work
138 seamlessly with this solution.
140 2. Definitions and Acronyms
142 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
143 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
144 "OPTIONAL" in this document are to be interpreted as described in BCP
145 14 [RFC2119] [RFC8174] when, and only when, they appear in all
146 capitals, as shown here.
148 This document uses the terminology defined in [RFC7950], [RFC8341],
149 [RFC8342], and [I-D.draft-ietf-netconf-subscribed-notifications]. In
150 addition, the following terms are introduced:
152 o Datastore node: A node in the instantiated YANG data tree
153 associated with a datastore. In this document, datastore nodes
154 are often also simply referred to as "objects"
156 o Datastore node update: A data item containing the current value of
157 a datastore node at the time the datastore node update was
158 created, as well as the path to the datastore node.
160 o Datastore subscription: A subscription to a stream of datastore
161 node updates.
163 o Datastore subtree: A datastore node and all its descendant
164 datastore nodes
166 o On-change subscription: A datastore subscription with updates that
167 are triggered when changes in subscribed datastore nodes are
168 detected.
170 o Periodic subscription: A datastore subscription with updates that
171 are triggered periodically according to some time interval.
173 o Selection filter: Evaluation and/or selection criteria, which may
174 be applied against a targeted set of objects.
176 o Update record: A representation of one or more datastore node
177 updates. In addition, an update record may contain which type of
178 update led to the datastore node update (e.g., whether the
179 datastore node was added, changed, deleted). Also included in the
180 update record may be other metadata, such as a subscription id of
181 the subscription as part of which the update record was generated.
182 In this document, update records are often also simply referred to
183 as "updates".
185 o Update trigger: A mechanism that determines when an update record
186 needs to be generated.
188 o YANG-Push: The subscription and push mechanism for datastore
189 updates that is specified in this document.
191 3. Solution Overview
193 This document specifies a solution that provides a subscription
194 service for updates from a datastore. This solution supports dynamic
195 as well as configured subscriptions to updates of datastore nodes.
196 Subscriptions specify when notification messages (also referred to as
197 "push updates") should be sent and what data to include in update
198 records. Datastore node updates are subsequently pushed from the
199 publisher to the receiver per the terms of the subscription.
201 3.1. Subscription Model
203 YANG-push subscriptions are defined using a YANG data model. This
204 model enhances the subscription model defined in
205 [I-D.draft-ietf-netconf-subscribed-notifications] with capabilities
206 that allow subscribers to subscribe to datastore node updates,
207 specifically to specify the update triggers defining when to generate
208 update records as well as what to include in an update record. Key
209 enhancements include:
211 o Specification of selection filters which identify targeted YANG
212 datastore nodes and/or datastore subtrees for which updates are to
213 be pushed.
215 o Specification of update policies contain conditions which trigger
216 the generation and pushing of new update records. There are two
217 types of subscriptions, distinguished by how updates are
218 triggered: periodic and on-change.
220 * For periodic subscriptions, the update trigger is specified by
221 two parameters that define when updates are to be pushed.
222 These parameters are the period interval with which to report
223 updates, and an "anchor time", i.e. a reference point in time
224 that can be used to calculate at which points in time periodic
225 updates need to be assembled and sent.
227 * For on-change subscriptions, an update trigger occurs whenever
228 a change in the subscribed information is detected. Included
229 are additional parameters that include:
231 + Dampening period: In an on-change subscription, detected
232 object changes should be sent as quickly as possible.
233 However it may be undesirable to send a rapid series of
234 object changes. Such behavior has the potential to exhaust
235 resources in the publisher or receiver. In order to protect
236 against that, a dampening period MAY be used to specify the
237 interval which has to pass before successive update records
238 for the same subscription are generated for a receiver. The
239 dampening period collectively applies to the set of all
240 datastore nodes selected by a single subscription. This
241 means that when there is a change to one or more subscribed
242 objects, an update record containing those objects is
243 created immediately (when no dampening period is in effect)
244 or at the end of a dampening period (when a dampening period
245 is in fact in effect). If multiple changes to a single
246 object occur during a dampening period, only the value that
247 is in effect at the time when the update record is created
248 is included. The dampening period goes into effect every
249 time an update record completes assembly.
251 + Change type: This parameter can be used to reduce the types
252 of datastore changes for which updates are sent (e.g., you
253 might only send an update when an object is created or
254 deleted, but not when an object value changes).
256 + Sync on start: defines whether or not a complete push-update
257 of all subscribed data will be sent at the beginning of a
258 subscription. Such early synchronization establishes the
259 frame of reference for subsequent updates.
261 o An encoding (using anydata) for the contents of periodic and on-
262 change push updates.
264 3.2. Negotiation of Subscription Policies
266 A dynamic subscription request SHOULD be declined if a publisher's
267 assessment is that it may be unable to provide update records meeting
268 the terms of an "establish-subscription" or "modify-subscription" RPC
269 request. In this case, a subscriber may quickly follow up with a new
270 RPC request using different parameters.
272 Random guessing of different parameters by a subscriber is to be
273 discouraged. Therefore, in order to minimize the number of
274 subscription iterations between subscriber and publisher, a dynamic
275 subscription supports a simple negotiation between subscribers and
276 publishers for subscription parameters. This negotiation is in the
277 form of supplemental information which should be inserted within
278 error responses to a failed RPC request. This returned error
279 response information, when considered, should increase the likelihood
280 of success for subsequent RPC requests. Such hints include suggested
281 periodic time intervals, acceptable dampening periods, and size
282 estimates for the number or objects which would be returned from a
283 proposed selection filter. However, there are no guarantees that
284 subsequent requests which consider these hints will be accepted.
286 3.3. On-Change Considerations
288 On-change subscriptions allow receivers to receive updates whenever
289 changes to targeted objects occur. As such, on-change subscriptions
290 are particularly effective for data that changes infrequently, yet
291 for which applications need to be quickly notified whenever a change
292 does occur with minimal delay.
294 On-change subscriptions tend to be more difficult to implement than
295 periodic subscriptions. Accordingly, on-change subscriptions may not
296 be supported by all implementations or for every object.
298 Whether or not to accept or reject on-change subscription requests
299 when the scope of the subscription contains objects for which on-
300 change is not supported is up to the publisher implementation. A
301 publisher MAY accept an on-change subscription even when the scope of
302 the subscription contains objects for which on-change is not
303 supported. In that case, updates are sent only for those objects
304 within the scope that do support on-change updates, whereas other
305 objects are excluded from update records, even if their values
306 change. In order for a subscriber to determine whether objects
307 support on-change subscriptions, objects are marked accordingly on a
308 publisher. Accordingly, when subscribing, it is the responsibility
309 of the subscriber to ensure it is aware of which objects support on-
310 change and which do not. For more on how objects are so marked, see
311 Section 3.10.
313 Alternatively, a publisher MAY decide to simply reject an on-change
314 subscription in case the scope of the subscription contains objects
315 for which on-change is not supported. In case of a configured
316 subscription, the publisher MAY suspend the subscription.
318 To avoid flooding receivers with repeated updates for subscriptions
319 containing fast-changing objects, or objects with oscillating values,
320 an on-change subscription allows for the definition of a dampening
321 period. Once an update record for a given object is generated, no
322 other updates for this particular subscription will be created until
323 the end of the dampening period. Values sent at the end of the
324 dampening period are the values that are current at the end of the
325 dampening period of all changed objects. Changed objects include
326 those which were deleted or newly created during that dampening
327 period. If an object has returned to its original value (or even has
328 been created and then deleted) during the dampening-period, that
329 value (and not the interim change) will still be sent. This will
330 indicate churn is occurring on that object.
332 On-change subscriptions can be refined to let users subscribe only to
333 certain types of changes. For example, a subscriber might only want
334 object creations and deletions, but not modifications of object
335 values.
337 Putting it all together, following is the conceptual process for
338 creating an update record as part of an on-change subscription:
340 1. Just before a change, or at the start of a dampening period,
341 evaluate any filtering and any access control rules to ensure
342 receiver is authorized to view all subscribed datastore nodes
343 (filtering out any nodes for which this is not the case). The
344 result is a set "A" of datastore nodes and subtrees.
346 2. Just after a change, or at the end of a dampening period,
347 evaluate any filtering and any (possibly new) access control
348 rules. The result is a set "B" of datastore nodes and subtrees.
350 3. Construct an update record, which takes the form of YANG patch
351 record [RFC8072] for going from A to B.
353 4. If there were any changes made between A and B which canceled
354 each other out, insert into the YANG patch record the last change
355 made, even if the new value is no different from the original
356 value (since changes that were made in the interim were canceled
357 out). In case the changes involve creating a new datastore node,
358 then deleting it, the YANG patch record will indicate deletion of
359 the datastore node. Similarly, in case the changes involve
360 deleting a new datastore node, then recreating it, the YANG patch
361 record will indicate creation of the datastore node.
363 5. If the resulting patch record is non-empty, send it to the
364 receiver.
366 Note: In cases where a subscriber wants to have separate dampening
367 periods for different objects, the subscriber has the option to
368 create multiple subscriptions with different selection filters.
370 3.4. Reliability Considerations
372 A subscription to updates from a datastore is intended to obviate the
373 need for polling. However, in order to do so, it is critical that
374 subscribers can rely on the subscription and have confidence that
375 they will indeed receive the subscribed updates without having to
376 worry about updates being silently dropped. In other words, a
377 subscription constitutes a promise on the side of the publisher to
378 provide the receivers with updates per the terms of the subscription.
380 Now, there are many reasons why a publisher may at some point no
381 longer be able to fulfill the terms of the subscription, even if the
382 subscription had been entered into with good faith. For example, the
383 volume of datastore nodes may be larger than anticipated, the
384 interval may prove too short to send full updates in rapid
385 succession, or an internal problem may prevent objects from being
386 collected. For this reason, the solution that is defined in this
387 document mandates that a publisher notifies receivers immediately and
388 reliably whenever it encounters a situation in which it is unable to
389 keep the terms of the subscription, and provides the publisher with
390 the option to suspend the subscription in such a case. This includes
391 indicating the fact that an update is incomplete as part of a push-
392 update or push-change-update notification, as well as emitting a
393 subscription-suspended notification as applicable. This is described
394 further in Section 3.11.1.
396 A publisher SHOULD reject a request for a subscription if it is
397 unlikely that the publisher will be able to fulfill the terms of that
398 subscription request. In such cases, it is preferable to have a
399 subscriber request a less resource intensive subscription than to
400 deal with frequently degraded behavior.
402 The solution builds on
403 [I-D.draft-ietf-netconf-subscribed-notifications]. As defined there,
404 any loss of underlying transport connection will be detected and
405 result in subscription termination (in case of dynamic subscriptions)
406 or suspension (in case of configured subscriptions), ensuring that
407 situations will not occur in which the loss of update notifications
408 would go unnoticed.
410 3.5. Data Encodings
412 3.5.1. Periodic Subscriptions
414 In a periodic subscription, the data included as part of an update
415 record corresponds to data that could have been read using a
416 retrieval operation.
418 3.5.2. On-Change Subscriptions
420 In an on-change subscription, update records need to indicate not
421 only values of changed datastore nodes but also the types of changes
422 that occurred since the last update. Therefore, encoding rules for
423 data in on-change updates will generally follow YANG-patch operation
424 as specified in [RFC8072]. The YANG-patch will describe what needs
425 to be applied to the earlier state reported by the preceding update,
426 to result in the now-current state. Note that contrary to [RFC8072],
427 objects encapsulated are not restricted to only configuration
428 objects.
430 A publisher indicates the type of change to a datastore node using
431 the different YANG patch operations: the "create" operation is used
432 for newly created objects (except entries in a user-ordered list),
433 the "delete" operation is used for deleted objects (including in
434 user-ordered lists), the "replace" operation is used when only the
435 object value changes, the "insert" operation is used when a new entry
436 is inserted in a list, and the "move" operation is used when an
437 existing entry in a user-ordered list is moved.
439 However, a patch must be able to do more than just describe the delta
440 from the previous state to the current state. As per Section 3.3, it
441 must also be able to identify whether transient changes have occurred
442 on an object during a dampening period. To support this, it is valid
443 to encode a YANG patch operation so that its application would result
444 in no change between the previous and current state. This indicates
445 that some churn has occurred on the object. An example of this would
446 be a patch that indicates a "create" operation for a datastore node
447 where the receiver believes one already exists, or a "replace"
448 operation which replaces a previous value with the same value. Note
449 that this means that the "create" and "delete" errors described in
450 [RFC8072] section 2.5 are not errors, and are valid operations with
451 YANG-Push.
453 3.6. Defining the Selection with a Datastore
455 A subscription must specify both the selection filters and the
456 datastore against which these selection filters will be applied.
457 This information is used to choose and subsequently push data from
458 the publisher's datastore to the receivers.
460 Only a single selection filter can be applied to a subscription at a
461 time. An RPC request proposing a new selection filter replaces any
462 existing filter. The following selection filter types are included
463 in the YANG-push data model, and may be applied against a datastore:
465 o subtree: A subtree selection filter identifies one or more
466 datastore subtrees. When specified, update records will only come
467 from the datastore nodes of selected datastore subtree(s). The
468 syntax and semantics correspond to that specified for [RFC6241]
469 section 6.
471 o xpath: An "xpath" selection filter is an XPath expression that
472 returns a node set. (XPath is a query language for selecting
473 nodes in an XML document.) When specified, updates will only come
474 from 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. One solution might involve making discoverable to
753 clients which objects are on-change notifiable, specified using
754 another YANG data model. Such a solution is specified in
755 [I-D.draft-ietf-netconf-notification-capabilities]. Until this
756 solution is standardized, implementations SHOULD provide their own
757 solution.
759 3.11. Other Considerations
761 3.11.1. Robustness and reliability
763 Particularly in the case of on-change updates, it is important that
764 these updates do not get lost. In case the loss of an update is
765 unavoidable, it is critical that the receiver is notified
766 accordingly.
768 Update records for a single subscription MUST NOT be resequenced
769 prior to transport.
771 It is conceivable that under certain circumstances, a publisher will
772 recognize that it is unable to include within an update record the
773 full set of objects desired per the terms of a subscription. In this
774 case, the publisher MUST act as follows.
776 o The publisher MUST set the "incomplete-update" flag on any update
777 record which is known to be missing information.
779 o The publisher MAY choose to suspend the subscription as per
780 [I-D.draft-ietf-netconf-subscribed-notifications]. If the
781 publisher does not create an update record at all, it MUST suspend
782 the subscription.
784 o When resuming an on-change subscription, the publisher SHOULD
785 generate a complete patch from the previous update record. If
786 this is not possible and the "sync-on-start" option is true for
787 the subscription, then the full datastore contents MAY be sent via
788 a "push-update" instead (effectively replacing the previous
789 contents). If neither of these are possible, then an "incomplete-
790 update" flag MUST be included on the next "push-change-update".
792 Note: It is perfectly acceptable to have a series of "push-change-
793 update" notifications (and even "push update" notifications) serially
794 queued at the transport layer awaiting transmission. It is not
795 required for the publisher to merge pending update records sent at
796 the same time.
798 On the receiver side, what action to take when a record with an
799 incomplete-update flag is received depends on the application. It
800 could simply choose to wait and do nothing. It could choose to
801 resynch, actively retrieving all subscribed information. It could
802 also choose to tear down the subscription and start a new one,
803 perhaps with a lesser scope that contains less objects.
805 3.11.2. Publisher capacity
807 It is far preferable to decline a subscription request than to accept
808 such a request when it cannot be met.
810 Whether or not a subscription can be supported will be determined by
811 a combination of several factors such as the subscription update
812 trigger (on-change or periodic), the period in which to report
813 changes (one second periods will consume more resources than one hour
814 periods), the amount of data in the datastore subtree that is being
815 subscribed to, and the number and combination of other subscriptions
816 that are concurrently being serviced.
818 4. A YANG Data Model for Management of Datastore Push Subscriptions
820 4.1. Overview
822 The YANG data model for datastore push subscriptions is depicted in
823 the following figures. The tree diagram that is used follows the
824 notation defined in [RFC8340]. New schema objects defined here
825 (i.e., beyond those from
826 [I-D.draft-ietf-netconf-subscribed-notifications]) are identified
827 with "yp". For the reader's convenience, in order to compact the
828 tree representation, some nodes that are defined in ietf-subscribed-
829 notifications and that are not essential to the understanding of the
830 data model defined here have been removed. This is indicated by
831 "..." in the diagram where applicable.
833 Because the tree diagram is quite large, its depiction is broken up
834 into several figures. The first figure depicts the augmentations
835 that are introduced in module ietf-yang-push to subscription
836 configuration specified in module ietf-subscribed-notifications.
838 module: ietf-subscribed-notifications
839 ...
840 +--rw filters
841 | ...
842 | +--rw yp:selection-filter* [filter-id]
843 | +--rw yp:filter-id string
844 | +--rw (yp:filter-spec)?
845 | +--:(yp:datastore-subtree-filter)
846 | | +--rw yp:datastore-subtree-filter?
847 | | {sn:subtree}?
848 | +--:(yp:datastore-xpath-filter)
849 | +--rw yp:datastore-xpath-filter? yang:xpath1.0
850 | {sn:xpath}?
851 +--rw subscriptions
852 +--rw subscription* [id]
853 | ...
854 +--rw (target)
855 | +--:(stream)
856 | | ...
857 | +--:(yp:datastore)
858 | +--rw yp:datastore identityref
859 | +--rw (yp:selection-filter)?
860 | +--:(yp:by-reference)
861 | | +--rw yp:selection-filter-ref
862 | | selection-filter-ref
863 | +--:(yp:within-subscription)
864 | +--rw (yp:filter-spec)?
865 | +--:(yp:datastore-subtree-filter)
866 | | +--rw yp:datastore-subtree-filter?
867 | | {sn:subtree}?
868 | +--:(yp:datastore-xpath-filter)
869 | +--rw yp:datastore-xpath-filter?
870 | yang:xpath1.0 {sn:xpath}?
871 | ...
872 +--rw (yp:update-trigger)
873 +--:(yp:periodic)
874 | +--rw yp:periodic!
875 | +--rw yp:period centiseconds
876 | +--rw yp:anchor-time? yang:date-and-time
877 +--:(yp:on-change) {on-change}?
878 +--rw yp:on-change!
879 +--rw yp:dampening-period? centiseconds
880 +--rw yp:sync-on-start? boolean
881 +--rw yp:excluded-change* change-type
883 Figure 6: Model structure: subscription configuration
885 The next figure depicts the augmentations of module ietf-yang-push
886 made to RPCs specified in module ietf-subscribed-notifications.
887 Specifically, these augmentations concern the establish-subscription
888 and modify-subscription RPCs, which are augmented with parameters
889 that are needed to specify datastore push subscriptions.
891 rpcs:
892 +---x establish-subscription
893 | +---w input
894 | | ...
895 | | +---w (target)
896 | | | +--:(stream)
897 | | | | ...
898 | | | +--:(yp:datastore)
899 | | | +---w yp:datastore identityref
900 | | | +---w (yp:selection-filter)?
901 | | | +--:(yp:by-reference)
902 | | | | +---w yp:selection-filter-ref
903 | | | | selection-filter-ref
904 | | | +--:(yp:within-subscription)
905 | | | +---w (yp:filter-spec)?
906 | | | +--:(yp:datastore-subtree-filter)
907 | | | | +---w yp:datastore-subtree-filter?
908 | | | | {sn:subtree}?
909 | | | +--:(yp:datastore-xpath-filter)
910 | | | +---w yp:datastore-xpath-filter?
911 | | | yang:xpath1.0 {sn:xpath}?
912 | | | ...
913 | | +---w (yp:update-trigger)
914 | | +--:(yp:periodic)
915 | | | +---w yp:periodic!
916 | | | +---w yp:period centiseconds
917 | | | +---w yp:anchor-time? yang:date-and-time
918 | | +--:(yp:on-change) {on-change}?
919 | | +---w yp:on-change!
920 | | +---w yp:dampening-period? centiseconds
921 | | +---w yp:sync-on-start? boolean
922 | | +---w yp:excluded-change* change-type
923 | +--ro output
924 | +--ro id subscription-id
925 | +--ro replay-start-time-revision? yang:date-and-time
926 | {replay}?
927 +---x modify-subscription
928 | +---w input
929 | ...
930 | +---w (target)
931 | | ...
933 | | +--:(yp:datastore)
934 | | +---w yp:datastore identityref
935 | | +---w (yp:selection-filter)?
936 | | +--:(yp:by-reference)
937 | | | +---w yp:selection-filter-ref
938 | | | selection-filter-ref
939 | | +--:(yp:within-subscription)
940 | | +---w (yp:filter-spec)?
941 | | +--:(yp:datastore-subtree-filter)
942 | | | +---w yp:datastore-subtree-filter?
943 | | | {sn:subtree}?
944 | | +--:(yp:datastore-xpath-filter)
945 | | +---w yp:datastore-xpath-filter?
946 | | yang:xpath1.0 {sn:xpath}?
947 | | ...
948 | +---w (yp:update-trigger)
949 | +--:(yp:periodic)
950 | | +---w yp:periodic!
951 | | +---w yp:period centiseconds
952 | | +---w yp:anchor-time? yang:date-and-time
953 | +--:(yp:on-change) {on-change}?
954 | +---w yp:on-change!
955 | +---w yp:dampening-period? centiseconds
956 +---x delete-subscription
957 | ...
958 +---x kill-subscription
959 ...
961 YANG-data (for placement into rpc error responses)
962 ...
964 Figure 7: Model structure: RPCs
966 The next figure depicts augmentations of module ietf-yang-push to the
967 notifications that are specified in module ietf-subscribed-
968 notifications. The augmentations allow the inclusion of subscription
969 configuration parameters that are specific to datastore push
970 subscriptions as part of subscription-started and subscription-
971 modified notifications.
973 notifications:
974 +---n replay-completed {replay}?
975 | ...
976 +---n subscription-completed
977 | ...
978 +---n subscription-started {configured}?
979 | | ...
980 | +--ro (target)
981 | | ...
982 | | +--:(yp:datastore)
983 | | +--ro yp:datastore identityref
984 | | +--ro (yp:selection-filter)?
985 | | +--:(yp:by-reference)
986 | | | +--ro yp:selection-filter-ref
987 | | | selection-filter-ref
988 | | +--:(yp:within-subscription)
989 | | +--ro (yp:filter-spec)?
990 | | +--:(yp:datastore-subtree-filter)
991 | | | +--ro yp:datastore-subtree-filter?
992 | | | {sn:subtree}?
993 | | +--:(yp:datastore-xpath-filter)
994 | | +--ro yp:datastore-xpath-filter?
995 | | yang:xpath1.0 {sn:xpath}?
996 | ...
997 | +--ro (yp:update-trigger)
998 | +--:(yp:periodic)
999 | | +--ro yp:periodic!
1000 | | +--ro yp:period centiseconds
1001 | | +--ro yp:anchor-time? yang:date-and-time
1002 | +--:(yp:on-change) {on-change}?
1003 | +--ro yp:on-change!
1004 | +--ro yp:dampening-period? centiseconds
1005 | +--ro yp:sync-on-start? boolean
1006 | +--ro yp:excluded-change* change-type
1007 +---n subscription-resumed
1008 | ...
1009 +---n subscription-modified
1010 | ...
1011 | +--ro (target)
1012 | | | ...
1013 | | +--:(yp:datastore)
1014 | | +--ro yp:datastore identityref
1015 | | +--ro (yp:selection-filter)?
1016 | | +--:(yp:by-reference)
1017 | | | +--ro yp:selection-filter-ref
1018 | | | selection-filter-ref
1019 | | +--:(yp:within-subscription)
1020 | | +--ro (yp:filter-spec)?
1021 | | +--:(yp:datastore-subtree-filter)
1022 | | | +--ro yp:datastore-subtree-filter?
1023 | | | {sn:subtree}?
1024 | | +--:(yp:datastore-xpath-filter)
1025 | | +--ro yp:datastore-xpath-filter?
1026 | | yang:xpath1.0 {sn:xpath}?
1027 | ...
1028 | +--ro (yp:update-trigger)?
1029 | +--:(yp:periodic)
1030 | | +--ro yp:periodic!
1031 | | +--ro yp:period centiseconds
1032 | | +--ro yp:anchor-time? yang:date-and-time
1033 | +--:(yp:on-change) {on-change}?
1034 | +--ro yp:on-change!
1035 | +--ro yp:dampening-period? centiseconds
1036 | +--ro yp:sync-on-start? boolean
1037 | +--ro yp:excluded-change* change-type
1038 +---n subscription-terminated
1039 | ...
1040 +---n subscription-suspended
1041 ...
1043 Figure 8: Model structure: Notifications
1045 The final figure in this section depicts the parts of module ietf-
1046 yang-push that are not simply augmentations to another module, but
1047 that are newly introduced.
1049 module: ietf-yang-push
1051 rpcs:
1052 +---x resync-subscription {on-change}?
1053 +---w input
1054 +---w id sn:subscription-id
1056 YANG-data: (for placement into rpc error responses)
1057 +-- resync-subscription-error
1058 | +--ro reason? identityref
1059 | +--ro period-hint? centiseconds
1060 | +--ro filter-failure-hint? string
1061 | +--ro object-count-estimate? uint32
1062 | +--ro object-count-limit? uint32
1063 | +--ro kilobytes-estimate? uint32
1064 | +--ro kilobytes-limit? uint32
1065 +-- establish-subscription-error-datastore
1066 | +--ro reason? identityref
1067 | +--ro period-hint? centiseconds
1068 | +--ro filter-failure-hint? string
1069 | +--ro object-count-estimate? uint32
1070 | +--ro object-count-limit? uint32
1071 | +--ro kilobytes-estimate? uint32
1072 | +--ro kilobytes-limit? uint32
1073 +-- modify-subscription-error-datastore
1074 +--ro reason? identityref
1075 +--ro period-hint? centiseconds
1076 +--ro filter-failure-hint? string
1077 +--ro object-count-estimate? uint32
1078 +--ro object-count-limit? uint32
1079 +--ro kilobytes-estimate? uint32
1080 +--ro kilobytes-limit? uint32
1082 notifications:
1083 +---n push-update
1084 | +--ro id? sn:subscription-id
1085 | +--ro datastore-contents?
1086 | +--ro incomplete-update? empty
1087 +---n push-change-update {on-change}?
1088 +--ro id? sn:subscription-id
1089 +--ro datastore-changes
1090 | +--ro yang-patch
1091 | +--ro patch-id string
1092 | +--ro comment? string
1093 | +--ro edit* [edit-id]
1094 | +--ro edit-id string
1095 | +--ro operation enumeration
1096 | +--ro target target-resource-offset
1097 | +--ro point? target-resource-offset
1098 | +--ro where? enumeration
1099 | +--ro value?
1100 +--ro incomplete-update? empty
1102 Figure 9: Model structure (non-augmentation portions
1104 Selected components of the model are summarized below.
1106 4.2. Subscription Configuration
1108 Both configured and dynamic subscriptions are represented within the
1109 list "subscription". New parameters extending the basic subscription
1110 data model in [I-D.draft-ietf-netconf-subscribed-notifications]
1111 include:
1113 o The targeted datastore from which the selection is being made.
1114 The potential datastores include those from [RFC8341]. A platform
1115 may also choose to support a custom datastore.
1117 o A selection filter identifying YANG nodes of interest within a
1118 datastore. Filter contents are specified via a reference to an
1119 existing filter, or via an in-line definition for only that
1120 subscription. Referenced filters allows an implementation to
1121 avoid evaluating filter acceptability during a dynamic
1122 subscription request. The case statement differentiates the
1123 options.
1125 o For periodic subscriptions, triggered updates will occur at the
1126 boundaries of a specified time interval. These boundaries can be
1127 calculated from the periodic parameters:
1129 * a "period" which defines the duration between push updates.
1131 * an "anchor-time"; update intervals fall on the points in time
1132 that are a multiple of a "period" from an "anchor-time". If
1133 "anchor-time" is not provided, then the "anchor-time" MUST be
1134 set with the creation time of the initial update record.
1136 o For on-change subscriptions, assuming any dampening period has
1137 completed, triggering occurs whenever a change in the subscribed
1138 information is detected. On-change subscriptions have more
1139 complex semantics that are guided by their own set of parameters:
1141 * a "dampening-period" specifies the interval that must pass
1142 before a successive update for the subscription is sent. If no
1143 dampening period is in effect, the update is sent immediately.
1144 If a subsequent change is detected, another update is only sent
1145 once the dampening period has passed for this subscription.
1147 * an "excluded-change" parameter which allows restriction of the
1148 types of changes for which updates should be sent (e.g., only
1149 add to an update record on object creation).
1151 * a "sync-on-start" specifies whether a complete update with all
1152 the subscribed data is to be sent at the beginning of a
1153 subscription.
1155 4.3. YANG Notifications
1157 4.3.1. State Change Notifications
1159 Subscription state notifications and mechanism are reused from
1160 [I-D.draft-ietf-netconf-subscribed-notifications]. Notifications
1161 "subscription-started" and "subscription-modified" have been
1162 augmented to include the datastore specific objects.
1164 4.3.2. Notifications for Subscribed Content
1166 Along with the subscribed content, there are other objects which
1167 might be part of a "push-update" or "push-change-update"
1168 notification.
1170 An "id" (that identifies the subscription) MUST be transported along
1171 with the subscribed contents. This allows a receiver to
1172 differentiate which subscription resulted in a particular update
1173 record.
1175 A "time-of-update" which represents the time an update record
1176 snapshot was generated. A receiver MAY assume that at this point in
1177 time a publisher's objects had the values that were pushed.
1179 An "incomplete-update" leaf. This leaf indicates that not all
1180 changes which have occurred since the last update are actually
1181 included with this update. In other words, the publisher has failed
1182 to fulfill its full subscription obligations. (For example a
1183 datastore was unable to provide the full set of datastore nodes to a
1184 publisher process.) To facilitate re-synchronization of on-change
1185 subscriptions, a publisher MAY subsequently send a "push-update"
1186 containing a full selection snapshot of subscribed data.
1188 4.4. YANG RPCs
1190 YANG-Push subscriptions are established, modified, and deleted using
1191 RPCs augmented from
1192 [I-D.draft-ietf-netconf-subscribed-notifications].
1194 4.4.1. Establish-subscription RPC
1196 The subscriber sends an establish-subscription RPC with the
1197 parameters in section 3.1. An example might look like:
1199
1201
1204
1206 ds:operational
1207
1208
1210 /ex:foo
1211
1212
1213 500
1214
1215
1216
1218 Figure 10: Establish-subscription RPC
1220 A positive response includes the "id" of the accepted subscription.
1221 In that case a publisher may respond:
1223
1225
1227 52
1228
1229
1231 Figure 11: Establish-subscription positive RPC response
1233 A subscription can be rejected for multiple reasons, including the
1234 lack of authorization to establish a subscription, no capacity to
1235 serve the subscription at the publisher, or the inability of the
1236 publisher to select datastore content at the requested cadence.
1238 If a request is rejected because the publisher is not able to serve
1239 it, the publisher SHOULD include in the returned error hints which
1240 help a subscriber understand subscription parameters might have been
1241 accepted for the request. These hints would be included within the
1242 YANG-data structure "establish-subscription-error-datastore".
1243 However even with these hints, there are no guarantee that subsequent
1244 requests will in fact be accepted.
1246 The specific parameters to be returned as part of the RPC error
1247 response depend on the specific transport that is used to manage the
1248 subscription. For NETCONF, those parameters are defined in
1249 [I-D.draft-ietf-netconf-netconf-event-notifications]. For example,
1250 for the following NETCONF request:
1252
1254
1258
1260 ds:operational
1261
1262
1264 /ex:foo
1265
1266
1267 100
1268
1269
1270
1272 Figure 12: Establish-subscription request example 2
1274 a publisher that cannot serve on-change updates but that can serve
1275 periodic updates might return the following NETCONF response:
1277
1280
1281 application
1282 operation-failed
1283 error
1284 /yp:periodic/yp:period
1285
1286
1287 yp:on-change-unsupported
1288
1289
1290
1291
1293 Figure 13: Establish-subscription error response example 2
1295 4.4.2. Modify-subscription RPC
1297 The subscriber MAY invoke the "modify-subscription" RPC for a
1298 subscription it previously established. The subscriber will include
1299 newly desired values in the "modify-subscription" RPC. Parameters
1300 not included MUST remain unmodified. Below is an example where a
1301 subscriber attempts to modify the period and datastore XPath filter
1302 of a subscription using NETCONF.
1304
1306
1310 1011
1311
1313 ds:operational
1314
1315
1317 /ex:bar
1318
1319
1320 250
1321
1322
1323
1325 Figure 14: Modify subscription request
1327 The publisher MUST respond to the subscription modification request.
1328 If the request is rejected, the existing subscription is left
1329 unchanged, and the publisher MUST send an RPC error response. This
1330 response might have hints encapsulated within the YANG-data structure
1331 "modify-subscription-error-datastore". A subscription MAY be
1332 modified multiple times.
1334 The specific parameters to be returned as part of the RPC error
1335 response depend on the specific transport that is used to manage the
1336 subscription. For NETCONF, those parameters are specified in
1337 [I-D.draft-ietf-netconf-netconf-event-notifications].
1339 A configured subscription cannot be modified using "modify-
1340 subscription" RPC. Instead, the configuration needs to be edited as
1341 needed.
1343 4.4.3. Delete-subscription RPC
1345 To stop receiving updates from a subscription and effectively delete
1346 a subscription that had previously been established using an
1347 "establish-subscription" RPC, a subscriber can send a "delete-
1348 subscription" RPC, which takes as only input the subscription's "id".
1349 This RPC is unmodified from
1350 [I-D.draft-ietf-netconf-subscribed-notifications].
1352 4.4.4. Resync-subscription RPC
1354 This RPC is supported only for on-change subscriptions previously
1355 established using an "establish-subscription" RPC. For example:
1357
1359 1011
1362
1363
1365 Figure 15: Resync subscription
1367 On receipt, a publisher must either accept the request and quickly
1368 follow with a "push-update", or send an appropriate error within an
1369 rpc error response. Within an error response, the publisher MAY
1370 include supplemental information about the reasons within the YANG-
1371 data structure "resync-subscription-error".
1373 4.4.5. YANG Module Synchronization
1375 To make subscription requests, the subscriber needs to know the YANG
1376 datastore schemas used by the publisher, which are available via the
1377 YANG Library module, ietf-yang-library.yang from [RFC8525]. The
1378 receiver is expected to know the YANG library information before
1379 starting a subscription.
1381 The set of modules, revisions, features, and deviations can change at
1382 run-time (if supported by the publisher implementation). For this
1383 purpose, the YANG library provides a simple "yang-library-change"
1384 notification that informs the subscriber that the library has
1385 changed. In this case, a subscription may need to be updated to take
1386 the updates into account. The receiver may also need to be informed
1387 of module changes in order to process updates regarding datastore
1388 nodes from changed modules correctly.
1390 5. YANG Module
1392 This YANG module imports typedefs from [RFC6991], identities from
1393 [RFC8342], the YANG-data extension from [RFC8040], and the yang-patch
1394 grouping from [RFC8072]. In addition, it imports and augments many
1395 definitions from [I-D.draft-ietf-netconf-subscribed-notifications].
1397 file "ietf-yang-push@2019-05-21.yang"
1398 module ietf-yang-push {
1399 yang-version 1.1;
1400 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push";
1401 prefix yp;
1403 import ietf-yang-types {
1404 prefix yang;
1405 reference
1406 "RFC 6991: Common YANG Data Types";
1407 }
1408 import ietf-subscribed-notifications {
1409 prefix sn;
1410 reference
1411 "draft-ietf-netconf-subscribed-notifications:
1412 Customized Subscriptions to a Publisher's Event Streams
1413 NOTE TO RFC Editor: Please replace above reference to
1414 draft-ietf-netconf-subscribed-notifications with RFC number
1415 when published (i.e. RFC xxxx).";
1416 }
1417 import ietf-datastores {
1418 prefix ds;
1419 reference
1420 "RFC 8342: Network Management Datastore Architecture (NMDA)";
1421 }
1422 import ietf-restconf {
1423 prefix rc;
1424 reference
1425 "RFC 8040: RESTCONF Protocol";
1426 }
1427 import ietf-yang-patch {
1428 prefix ypatch;
1429 reference
1430 "RFC 8072: YANG Patch Media Type";
1431 }
1433 organization
1434 "IETF NETCONF Working Group";
1435 contact
1436 "WG Web:
1437 WG List:
1439 Editor: Alexander Clemm
1440
1441 Editor: Eric Voit
1442
1443 Editor: Alberto Gonzalez Prieto
1444
1445 Editor: Ambika Prasad Tripathy
1446
1447 Editor: Einar Nilsen-Nygaard
1448
1449 Editor: Andy Bierman
1450
1451 Editor: Balazs Lengyel
1452 ";
1453 description
1454 "This module contains YANG specifications for YANG push.
1456 The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL
1457 NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'NOT RECOMMENDED',
1458 'MAY', and 'OPTIONAL' in this document are to be interpreted as
1459 described in BCP 14 (RFC 2119) (RFC 8174) when, and only when,
1460 they appear in all capitals, as shown here.
1462 Copyright (c) 2019 IETF Trust and the persons identified as
1463 authors of the code. All rights reserved.
1465 Redistribution and use in source and binary forms, with or
1466 without modification, is permitted pursuant to, and subject to
1467 the license terms contained in, the Simplified BSD License set
1468 forth in Section 4.c of the IETF Trust's Legal Provisions
1469 Relating to IETF Documents
1470 (https://trustee.ietf.org/license-info).
1472 This version of this YANG module is part of RFC XXXX;
1473 see the RFC itself for full legal notices.";
1475 // RFC Ed.: replace XXXX with actual RFC number and remove this
1476 // note.
1478 revision 2019-05-21 {
1479 description
1480 "Initial revision.
1481 NOTE TO RFC EDITOR:
1482 (1)Please replace the above revision date to
1483 the date of RFC publication when published.
1484 (2) Please replace the date in the file name
1485 (ietf-yang-push@2019-05-21.yang) to the date of RFC
1486 publication.
1487 (3) Please replace the following reference to
1488 draft-ietf-netconf-yang-push-25 with RFC number when
1489 published (i.e. RFC xxxx).";
1490 reference
1491 "draft-ietf-netconf-yang-push-25";
1492 }
1494 /*
1495 * FEATURES
1496 */
1498 feature on-change {
1499 description
1500 "This feature indicates that on-change triggered subscriptions
1501 are supported.";
1502 }
1504 /*
1505 * IDENTITIES
1506 */
1508 /* Error type identities for datastore subscription */
1510 identity resync-subscription-error {
1511 description
1512 "Problem found while attempting to fulfill an
1513 'resync-subscription' RPC request.";
1514 }
1516 identity cant-exclude {
1517 base sn:establish-subscription-error;
1518 description
1519 "Unable to remove the set of 'excluded-changes'. This means
1520 the publisher is unable to restrict 'push-change-update's to
1521 just the change types requested for this subscription.";
1522 }
1524 identity datastore-not-subscribable {
1525 base sn:establish-subscription-error;
1526 base sn:subscription-terminated-reason;
1527 description
1528 "This is not a subscribable datastore.";
1529 }
1531 identity no-such-subscription-resync {
1532 base resync-subscription-error;
1533 description
1534 "Referenced subscription doesn't exist. This may be as a result
1535 of a non-existent subscription ID, an ID which belongs to
1536 another subscriber, or an ID for configured subscription.";
1537 }
1539 identity on-change-unsupported {
1540 base sn:establish-subscription-error;
1541 description
1542 "On-change is not supported for any objects which are
1543 selectable by this filter.";
1544 }
1546 identity on-change-sync-unsupported {
1547 base sn:establish-subscription-error;
1548 description
1549 "Neither sync on start nor resynchronization are supported for
1550 this subscription. This error will be used for two
1551 reasons. First if an 'establish-subscription' RPC includes
1552 'sync-on-start', yet the publisher can't support sending a
1553 'push-update' for this subscription for reasons other than
1554 'on-change-unsupported' or 'sync-too-big'. And second, if the
1555 'resync-subscription' RPC is invoked either for an existing
1556 periodic subscription, or for an on-change subscription which
1557 can't support resynchronization.";
1558 }
1560 identity period-unsupported {
1561 base sn:establish-subscription-error;
1562 base sn:modify-subscription-error;
1563 base sn:subscription-suspended-reason;
1564 description
1565 "Requested time period or dampening-period is too short. This
1566 can be for both periodic and on-change subscriptions (with or
1567 without dampening.) Hints suggesting alternative periods may
1568 be returned as supplemental information.";
1569 }
1571 identity update-too-big {
1572 base sn:establish-subscription-error;
1573 base sn:modify-subscription-error;
1574 base sn:subscription-suspended-reason;
1575 description
1576 "Periodic or on-change push update datatrees exceed a maximum
1577 size limit. Hints on estimated size of what was too big may
1578 be returned as supplemental information.";
1579 }
1580 identity sync-too-big {
1581 base sn:establish-subscription-error;
1582 base sn:modify-subscription-error;
1583 base resync-subscription-error;
1584 base sn:subscription-suspended-reason;
1585 description
1586 "Sync-on-start or resynchronization datatree exceeds a maximum
1587 size limit. Hints on estimated size of what was too big may
1588 be returned as supplemental information.";
1589 }
1591 identity unchanging-selection {
1592 base sn:establish-subscription-error;
1593 base sn:modify-subscription-error;
1594 base sn:subscription-terminated-reason;
1595 description
1596 "Selection filter is unlikely to ever select datatree nodes.
1597 This means that based on the subscriber's current access
1598 rights, the publisher recognizes that the selection filter is
1599 unlikely to ever select datatree nodes which change. Examples
1600 for this might be that node or subtree doesn't exist, read
1601 access is not permitted for a receiver, or static objects that
1602 only change at reboot have been chosen.";
1603 }
1605 /*
1606 * TYPE DEFINITIONS
1607 */
1609 typedef change-type {
1610 type enumeration {
1611 enum create {
1612 description
1613 "A change that refers to the creation of a new datastore
1614 node.";
1615 }
1616 enum delete {
1617 description
1618 "A change that refers to the deletion of a datastore
1619 node.";
1620 }
1621 enum insert {
1622 description
1623 "A change that refers to the insertion of a new
1624 user-ordered datastore node.";
1625 }
1626 enum move {
1627 description
1628 "A change that refers to a reordering of the target
1629 datastore node.";
1630 }
1631 enum replace {
1632 description
1633 "A change that refers to a replacement of the target
1634 datastore node's value.";
1635 }
1636 }
1637 description
1638 "Specifies different types of datastore changes.
1640 This type is based on the edit operations defined for YANG
1641 Patch, with the difference that it is valid for a receiver to
1642 process an update record which performs a create operation on
1643 a datastore node the receiver believes exists, or to process a
1644 delete on a datastore node the receiver believes is missing.";
1645 reference
1646 "RFC 8072: YANG Patch Media Type, section 2.5";
1647 }
1649 typedef selection-filter-ref {
1650 type leafref {
1651 path "/sn:filters/yp:selection-filter/yp:filter-id";
1652 }
1653 description
1654 "This type is used to reference a selection filter.";
1655 }
1657 typedef centiseconds {
1658 type uint32;
1659 description
1660 "A period of time, measured in units of 0.01 seconds.";
1661 }
1663 /*
1664 * GROUP DEFINITIONS
1665 */
1667 grouping datastore-criteria {
1668 description
1669 "A grouping to define criteria for which selected objects
1670 from a targeted datastore should be included in push
1671 updates.";
1672 leaf datastore {
1673 type identityref {
1674 base ds:datastore;
1676 }
1677 mandatory true;
1678 description
1679 "Datastore from which to retrieve data.";
1680 }
1681 uses selection-filter-objects;
1682 }
1684 grouping selection-filter-types {
1685 description
1686 "This grouping defines the types of selectors for objects
1687 from a datastore.";
1688 choice filter-spec {
1689 description
1690 "The content filter specification for this request.";
1691 anydata datastore-subtree-filter {
1692 if-feature "sn:subtree";
1693 description
1694 "This parameter identifies the portions of the
1695 target datastore to retrieve.";
1696 reference
1697 "RFC 6241: Network Configuration Protocol, Section 6.";
1698 }
1699 leaf datastore-xpath-filter {
1700 if-feature "sn:xpath";
1701 type yang:xpath1.0;
1702 description
1703 "This parameter contains an XPath expression identifying
1704 the portions of the target datastore to retrieve.
1706 If the expression returns a node-set, all nodes in the
1707 node-set are selected by the filter. Otherwise, if the
1708 expression does not return a node-set, the filter
1709 doesn't select any nodes.
1711 The expression is evaluated in the following XPath
1712 context:
1714 o The set of namespace declarations is the set of prefix
1715 and namespace pairs for all YANG modules implemented
1716 by the server, where the prefix is the YANG module
1717 name and the namespace is as defined by the
1718 'namespace' statement in the YANG module.
1720 If the leaf is encoded in XML, all namespace
1721 declarations in scope on the 'stream-xpath-filter'
1722 leaf element are added to the set of namespace
1723 declarations. If a prefix found in the XML is
1724 already present in the set of namespace declarations,
1725 the namespace in the XML is used.
1727 o The set of variable bindings is empty.
1729 o The function library is the core function library, and
1730 the XPath functions defined in section 10 in RFC 7950.
1732 o The context node is the root node of the target
1733 datastore.";
1734 }
1735 }
1736 }
1738 grouping selection-filter-objects {
1739 description
1740 "This grouping defines a selector for objects from a
1741 datastore.";
1742 choice selection-filter {
1743 description
1744 "The source of the selection filter applied to the
1745 subscription. This will come either referenced from a global
1746 list, or be provided within the subscription itself.";
1747 case by-reference {
1748 description
1749 "Incorporate a filter that has been configured
1750 separately.";
1751 leaf selection-filter-ref {
1752 type selection-filter-ref;
1753 mandatory true;
1754 description
1755 "References an existing selection filter which is to be
1756 applied to the subscription.";
1757 }
1758 }
1759 case within-subscription {
1760 description
1761 "Local definition allows a filter to have the same
1762 lifecycle as the subscription.";
1763 uses selection-filter-types;
1764 }
1765 }
1766 }
1768 grouping update-policy-modifiable {
1769 description
1770 "This grouping describes the datastore specific subscription
1771 conditions that can be changed during the lifetime of the
1772 subscription.";
1773 choice update-trigger {
1774 description
1775 "Defines necessary conditions for sending an event record to
1776 the subscriber.";
1777 case periodic {
1778 container periodic {
1779 presence "indicates a periodic subscription";
1780 description
1781 "The publisher is requested to notify periodically the
1782 current values of the datastore as defined by the
1783 selection filter.";
1784 leaf period {
1785 type centiseconds;
1786 mandatory true;
1787 description
1788 "Duration of time which should occur between periodic
1789 push updates, in one hundredths of a second.";
1790 }
1791 leaf anchor-time {
1792 type yang:date-and-time;
1793 description
1794 "Designates a timestamp before or after which a series
1795 of periodic push updates are determined. The next
1796 update will take place at a whole multiple interval
1797 from the anchor time. For example, for an anchor time
1798 is set for the top of a particular minute and a period
1799 interval of a minute, updates will be sent at the top
1800 of every minute this subscription is active.";
1801 }
1802 }
1803 }
1804 case on-change {
1805 if-feature "on-change";
1806 container on-change {
1807 presence "indicates an on-change subscription";
1808 description
1809 "The publisher is requested to notify changes in values
1810 in the datastore subset as defined by a selection
1811 filter.";
1812 leaf dampening-period {
1813 type centiseconds;
1814 default "0";
1815 description
1816 "Specifies the minimum interval between the assembly of
1817 successive update records for a single receiver of a
1818 subscription. Whenever subscribed objects change, and
1819 a dampening period interval (which may be zero) has
1820 elapsed since the previous update record creation for
1821 a receiver, then any subscribed objects and properties
1822 which have changed since the previous update record
1823 will have their current values marshalled and placed
1824 into a new update record.";
1825 }
1826 }
1827 }
1828 }
1829 }
1831 grouping update-policy {
1832 description
1833 "This grouping describes the datastore-specific subscription
1834 conditions of a subscription.";
1835 uses update-policy-modifiable {
1836 augment "update-trigger/on-change/on-change" {
1837 description
1838 "Includes objects not modifiable once subscription is
1839 established.";
1840 leaf sync-on-start {
1841 type boolean;
1842 default "true";
1843 description
1844 "When this object is set to false, it restricts an
1845 on-change subscription from sending push-update
1846 notifications. When false, pushing a full selection per
1847 the terms of the selection filter MUST NOT be done for
1848 this subscription. Only updates about changes,
1849 i.e. only push-change-update notifications are sent.
1850 When true (default behavior), in order to facilitate a
1851 receiver's synchronization, a full update is sent when
1852 the subscription starts using a push-update
1853 notification. After that, push-change-update
1854 notifications are exclusively sent unless the publisher
1855 chooses to resync the subscription via a new push-update
1856 notification.";
1857 }
1858 leaf-list excluded-change {
1859 type change-type;
1860 description
1861 "Use to restrict which changes trigger an update. For
1862 example, if modify is excluded, only creation and
1863 deletion of objects is reported.";
1864 }
1865 }
1866 }
1867 }
1868 grouping hints {
1869 description
1870 "Parameters associated with some error for a subscription
1871 made upon a datastore.";
1872 leaf period-hint {
1873 type centiseconds;
1874 description
1875 "Returned when the requested time period is too short. This
1876 hint can assert a viable period for either a periodic push
1877 cadence or an on-change dampening interval.";
1878 }
1879 leaf filter-failure-hint {
1880 type string;
1881 description
1882 "Information describing where and/or why a provided filter
1883 was unsupportable for a subscription.";
1884 }
1885 leaf object-count-estimate {
1886 type uint32;
1887 description
1888 "If there are too many objects which could potentially be
1889 returned by the selection filter, this identifies the
1890 estimate of the number of objects which the filter would
1891 potentially pass.";
1892 }
1893 leaf object-count-limit {
1894 type uint32;
1895 description
1896 "If there are too many objects which could be returned by
1897 the selection filter, this identifies the upper limit of
1898 the publisher's ability to service for this subscription.";
1899 }
1900 leaf kilobytes-estimate {
1901 type uint32;
1902 description
1903 "If the returned information could be beyond the capacity
1904 of the publisher, this would identify the data size which
1905 could result from this selection filter.";
1906 }
1907 leaf kilobytes-limit {
1908 type uint32;
1909 description
1910 "If the returned information would be beyond the capacity
1911 of the publisher, this identifies the upper limit of the
1912 publisher's ability to service for this subscription.";
1913 }
1914 }
1915 /*
1916 * RPCs
1917 */
1919 rpc resync-subscription {
1920 if-feature "on-change";
1921 description
1922 "This RPC allows a subscriber of an active on-change
1923 subscription to request a full push of objects.
1925 A successful invocation results in a push-update of all
1926 datastore nodes that the subscriber is permitted to access.
1927 This RPC can only be invoked on the same session on which the
1928 subscription is currently active. In case of an error, a
1929 resync-subscription-error is sent as part of an error
1930 response.";
1931 input {
1932 leaf id {
1933 type sn:subscription-id;
1934 mandatory true;
1935 description
1936 "Identifier of the subscription that is to be resynced.";
1937 }
1938 }
1939 }
1941 rc:yang-data resync-subscription-error {
1942 container resync-subscription-error {
1943 description
1944 "If a 'resync-subscription' RPC fails, the subscription is
1945 not resynced and the RPC error response MUST indicate the
1946 reason for this failure. This YANG-data MAY be inserted as
1947 structured data within a subscription's RPC error response
1948 to indicate the failure reason.";
1949 leaf reason {
1950 type identityref {
1951 base resync-subscription-error;
1952 }
1953 mandatory true;
1954 description
1955 "Indicates the reason why the publisher has declined a
1956 request for subscription resynchronization.";
1957 }
1958 uses hints;
1959 }
1960 }
1962 augment "/sn:establish-subscription/sn:input" {
1963 description
1964 "This augmentation adds additional subscription parameters
1965 that apply specifically to datastore updates to RPC input.";
1966 uses update-policy;
1967 }
1969 augment "/sn:establish-subscription/sn:input/sn:target" {
1970 description
1971 "This augmentation adds the datastore as a valid target
1972 for the subscription to RPC input.";
1973 case datastore {
1974 description
1975 "Information specifying the parameters of an request for a
1976 datastore subscription.";
1977 uses datastore-criteria;
1978 }
1979 }
1981 rc:yang-data establish-subscription-datastore-error-info {
1982 container establish-subscription-datastore-error-info {
1983 description
1984 "If any 'establish-subscription' RPC parameters are
1985 unsupportable against the datastore, a subscription is not
1986 created and the RPC error response MUST indicate the reason
1987 why the subscription failed to be created. This YANG-data
1988 MAY be inserted as structured data within a subscription's
1989 RPC error response to indicate the failure reason. This
1990 YANG-data MUST be inserted if hints are to be provided back
1991 to the subscriber.";
1992 leaf reason {
1993 type identityref {
1994 base sn:establish-subscription-error;
1995 }
1996 description
1997 "Indicates the reason why the subscription has failed to
1998 be created to a targeted datastore.";
1999 }
2000 uses hints;
2001 }
2002 }
2004 augment "/sn:modify-subscription/sn:input" {
2005 description
2006 "This augmentation adds additional subscription parameters
2007 specific to datastore updates.";
2008 uses update-policy-modifiable;
2009 }
2010 augment "/sn:modify-subscription/sn:input/sn:target" {
2011 description
2012 "This augmentation adds the datastore as a valid target
2013 for the subscription to RPC input.";
2014 case datastore {
2015 description
2016 "Information specifying the parameters of an request for a
2017 datastore subscription.";
2018 uses datastore-criteria;
2019 }
2020 }
2022 rc:yang-data modify-subscription-datastore-error-info {
2023 container modify-subscription-datastore-error-info {
2024 description
2025 "This YANG-data MAY be provided as part of a subscription's
2026 RPC error response when there is a failure of a
2027 'modify-subscription' RPC which has been made against a
2028 datastore. This YANG-data MUST be used if hints are to be
2029 provides back to the subscriber.";
2030 leaf reason {
2031 type identityref {
2032 base sn:modify-subscription-error;
2033 }
2034 description
2035 "Indicates the reason why the subscription has failed to
2036 be modified.";
2037 }
2038 uses hints;
2039 }
2040 }
2042 /*
2043 * NOTIFICATIONS
2044 */
2046 notification push-update {
2047 description
2048 "This notification contains a push update, containing data
2049 subscribed to via a subscription. This notification is sent
2050 for periodic updates, for a periodic subscription. It can
2051 also be used for synchronization updates of an on-change
2052 subscription. This notification shall only be sent to
2053 receivers of a subscription. It does not constitute a
2054 general-purpose notification that would be subscribable as
2055 part of the NETCONF event stream by any receiver.";
2056 leaf id {
2057 type sn:subscription-id;
2058 description
2059 "This references the subscription which drove the
2060 notification to be sent.";
2061 }
2062 anydata datastore-contents {
2063 description
2064 "This contains the updated data. It constitutes a snapshot
2065 at the time-of-update of the set of data that has been
2066 subscribed to. The snapshot corresponds to the same
2067 snapshot that would be returned in a corresponding get
2068 operation with the same selection filter parameters
2069 applied.";
2070 }
2071 leaf incomplete-update {
2072 type empty;
2073 description
2074 "This is a flag which indicates that not all datastore
2075 nodes subscribed to are included with this update. In
2076 other words, the publisher has failed to fulfill its full
2077 subscription obligations, and despite its best efforts is
2078 providing an incomplete set of objects.";
2079 }
2080 }
2082 notification push-change-update {
2083 if-feature "on-change";
2084 description
2085 "This notification contains an on-change push update. This
2086 notification shall only be sent to the receivers of a
2087 subscription. It does not constitute ageneral-purpose
2088 notification that would be subscribable as part of the
2089 NETCONF event stream by any receiver.";
2090 leaf id {
2091 type sn:subscription-id;
2092 description
2093 "This references the subscription which drove the
2094 notification to be sent.";
2095 }
2096 container datastore-changes {
2097 description
2098 "This contains the set of datastore changes of the target
2099 datastore starting at the time of the previous update, per
2100 the terms of the subscription.";
2101 uses ypatch:yang-patch;
2102 }
2103 leaf incomplete-update {
2104 type empty;
2105 description
2106 "The presence of this object indicates not all changes which
2107 have occurred since the last update are included with this
2108 update. In other words, the publisher has failed to
2109 fulfill its full subscription obligations, for example in
2110 cases where it was not able to keep up with a change
2111 burst.";
2112 }
2113 }
2115 augment "/sn:subscription-started" {
2116 description
2117 "This augmentation adds datastore-specific objects to
2118 the notification that a subscription has started.";
2119 uses update-policy;
2120 }
2122 augment "/sn:subscription-started/sn:target" {
2123 description
2124 "This augmentation allows the datastore to be included as
2125 part of the notification that a subscription has started.";
2126 case datastore {
2127 uses datastore-criteria {
2128 refine "selection-filter/within-subscription" {
2129 description
2130 "Specifies the selection filter and where it originated
2131 from. If the 'selection-filter-ref' is populated, the
2132 filter within the subscription came from the 'filters'
2133 container. Otherwise it is populated in-line as part of
2134 the subscription itself.";
2135 }
2136 }
2137 }
2138 }
2140 augment "/sn:subscription-modified" {
2141 description
2142 "This augmentation adds datastore-specific objects to
2143 the notification that a subscription has been modified.";
2144 uses update-policy;
2145 }
2147 augment "/sn:subscription-modified/sn:target" {
2148 description
2149 "This augmentation allows the datastore to be included as
2150 part of the notification that a subscription has been
2151 modified.";
2152 case datastore {
2153 uses datastore-criteria {
2154 refine "selection-filter/within-subscription" {
2155 description
2156 "Specifies the selection filter and where it originated
2157 from. If the 'selection-filter-ref' is populated, the
2158 filter within the subscription came from the 'filters'
2159 container. Otherwise it is populated in-line as part of
2160 the subscription itself.";
2161 }
2162 }
2163 }
2164 }
2166 /*
2167 * DATA NODES
2168 */
2170 augment "/sn:filters" {
2171 description
2172 "This augmentation allows the datastore to be included as part
2173 of the selection filtering criteria for a subscription.";
2174 list selection-filter {
2175 key "filter-id";
2176 description
2177 "A list of pre-configured filters that can be applied
2178 to datastore subscriptions.";
2179 leaf filter-id {
2180 type string;
2181 description
2182 "An identifier to differentiate between selection
2183 filters.";
2184 }
2185 uses selection-filter-types;
2186 }
2187 }
2189 augment "/sn:subscriptions/sn:subscription" {
2190 when 'yp:datastore';
2191 description
2192 "This augmentation adds many datastore specific objects to a
2193 subscription.";
2194 uses update-policy;
2195 }
2197 augment "/sn:subscriptions/sn:subscription/sn:target" {
2198 description
2199 "This augmentation allows the datastore to be included as
2200 part of the selection filtering criteria for a subscription.";
2201 case datastore {
2202 uses datastore-criteria;
2203 }
2204 }
2205 }
2207
2209 6. IANA Considerations
2211 This document registers the following namespace URI in the "IETF XML
2212 Registry" [RFC3688]:
2214 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push
2215 Registrant Contact: The IESG.
2216 XML: N/A; the requested URI is an XML namespace.
2218 This document registers the following YANG module in the "YANG Module
2219 Names" registry [RFC6020]:
2221 Name: ietf-yang-push
2222 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push
2223 Prefix: yp
2224 Reference: draft-ietf-netconf-yang-push-21.txt (RFC form)
2226 7. Security Considerations
2228 The YANG module specified in this document defines a schema for data
2229 that is designed to be accessed via network management protocols such
2230 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer
2231 is the secure transport layer, and the mandatory-to-implement secure
2232 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer
2233 is HTTPS, and the mandatory-to-implement secure transport is TLS
2234 [RFC8446].
2236 The Network Configuration Access Control Model (NACM) [RFC8341]
2237 provides the means to restrict access for particular NETCONF or
2238 RESTCONF users to a preconfigured subset of all available NETCONF or
2239 RESTCONF protocol operations and content.
2241 There are a number of data nodes defined in this YANG module that are
2242 writable/creatable/deletable (i.e., config true, which is the
2243 default). These data nodes may be considered sensitive or vulnerable
2244 in some network environments. Write operations (e.g., edit-config)
2245 to these data nodes without proper protection can have a negative
2246 effect on network operations. These are the subtrees and data nodes
2247 and their sensitivity/vulnerability. (It should be noted that the
2248 YANG module augments the YANG module from
2250 [I-D.draft-ietf-netconf-subscribed-notifications]. All security
2251 considerations that are listed there are relevant also for datastore
2252 subscriptions. In the following, we focus on the data nodes that are
2253 newly introduced here.)
2255 o Subtree "selection-filter" under container "filters": This subtree
2256 allows to specify which objects or subtrees to include in a
2257 datastore subscription. An attacker could attempt to modify the
2258 filter. For example, the filter might be modified to result in
2259 very few objects being filtered in order to attempt to overwhelm
2260 the receiver. Alternatively, the filter might be modified to
2261 result in certain objects to be excluded from updates, in order to
2262 have certain changes go unnoticed.
2264 o Subtree "datastore" in choice "target" in list "subscription":
2265 Analogous to "selection filter", an attacker might attempt to
2266 modify the objects being filtered in order to overwhelm a receiver
2267 with a larger volume of object updates than expected, or to have
2268 certain changes go unnoticed.
2270 o Choice "update-trigger" in list "subscription": By modifying the
2271 update trigger, an attacker might alter the updates that are being
2272 sent in order to confuse a receiver, to withhold certain updates
2273 to be sent to the receiver, and/or to overwhelm a receiver. For
2274 example, an attacker might modify the period with which updates
2275 are reported for a periodic subscription, or it might modify the
2276 dampening period for an on-change subscription, resulting in
2277 greater delay of successive updates (potentially affecting
2278 responsiveness of applications that depend on the updates) or in a
2279 high volume of updates (to exhaust receiver resources).
2281 o RPC "resync-subscription": This RPC allows a subscriber of an on-
2282 change subscription to request a full push of objects in the
2283 subscription's scope. This can result in a large volume of data.
2284 An attacker could attempt to use this RPC to exhaust resources on
2285 the server to generate the data, and attempt to overwhelm a
2286 receiver with the resulting data volume.
2288 NACM provides one means to mitigate these threats on the publisher
2289 side. In order to address those threats as a subscriber, a
2290 subscriber could monitor the subscription configuration for any
2291 unexpected changes. For this, it can subscribe to updates to the
2292 YANG datastore nodes that represent his datastore subscriptions. As
2293 this data volume is small, a paranoid subscriber could even revert to
2294 occasional polling to guard against a compromised subscription
2295 against subscription configuration updates itself.
2297 8. Acknowledgments
2299 For their valuable comments, discussions, and feedback, we wish to
2300 acknowledge Tim Jenkins, Martin Bjorklund, Kent Watsen, Susan Hares,
2301 Yang Geng, Peipei Guo, Michael Scharf, Guangying Zheng, Tom Petch,
2302 Henk Birkholz, Reshad Rahman, Qin Wu, Rohit Ranade, and Rob Wilton.
2304 9. Contributors
2306 Alberto Gonzalez Prieto
2307 Microsoft
2308 albgonz@microsoft.com
2310 Ambika Prasad Tripathy
2311 Cisco Systems
2312 ambtripa@cisco.com
2314 Einar Nilsen-Nygaard
2315 Cisco Systems
2316 einarnn@cisco.com
2318 Andy Bierman
2319 YumaWorks
2320 andy@yumaworks.com
2322 Balazs Lengyel
2323 Ericsson
2324 balazs.lengyel@ericsson.com
2326 10. References
2328 10.1. Normative References
2330 [I-D.draft-ietf-netconf-subscribed-notifications]
2331 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A.,
2332 and E. Nilsen-Nygaard, "Subscription to YANG Event
2333 Notifications", draft-ietf-netconf-subscribed-
2334 notifications-24 (work in progress), April 2019.
2336 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
2337 Requirement Levels", BCP 14, RFC 2119,
2338 DOI 10.17487/RFC2119, March 1997,
2339 .
2341 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
2342 DOI 10.17487/RFC3688, January 2004,
2343 .
2345 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
2346 the Network Configuration Protocol (NETCONF)", RFC 6020,
2347 DOI 10.17487/RFC6020, October 2010,
2348 .
2350 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
2351 RFC 6991, DOI 10.17487/RFC6991, July 2013,
2352 .
2354 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
2355 RFC 7950, DOI 10.17487/RFC7950, August 2016,
2356 .
2358 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2359 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
2360 .
2362 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch
2363 Media Type", RFC 8072, DOI 10.17487/RFC8072, February
2364 2017, .
2366 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2367 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
2368 May 2017, .
2370 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
2371 Access Control Model", STD 91, RFC 8341,
2372 DOI 10.17487/RFC8341, March 2018,
2373 .
2375 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
2376 and R. Wilton, "Network Management Datastore Architecture
2377 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
2378 .
2380 [RFC8525] Bierman, A., Bjorklund, M., Schoenwaelder, J., Watsen, K.,
2381 and R. Wilton, "YANG Library", RFC 8525,
2382 DOI 10.17487/RFC8525, March 2019,
2383 .
2385 10.2. Informative References
2387 [I-D.draft-ietf-netconf-netconf-event-notifications]
2388 Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard,
2389 E., and A. Tripathy, "Dynamic subscription to YANG Events
2390 and Datastores over NETCONF", April 2019.
2392 [I-D.draft-ietf-netconf-notification-capabilities]
2393 Lengyel, B. and A. Clemm, "YangPush Notification
2394 Capabilities", March 2019.
2396 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
2397 and A. Bierman, Ed., "Network Configuration Protocol
2398 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
2399 .
2401 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
2402 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
2403 .
2405 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements
2406 for Subscription to YANG Datastores", RFC 7923,
2407 DOI 10.17487/RFC7923, June 2016,
2408 .
2410 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
2411 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
2412 .
2414 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface
2415 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018,
2416 .
2418 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
2419 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
2420 .
2422 Appendix A. Appendix A: Subscription Errors
2424 A.1. RPC Failures
2426 Rejection of an RPC for any reason is indicated by via RPC error
2427 response from the publisher. Valid RPC errors returned include both
2428 existing transport layer RPC error codes, such as those seen with
2429 NETCONF in [RFC6241], as well as subscription specific errors such as
2430 those defined within the YANG model. As a result, how subscription
2431 errors are encoded within an RPC error response is transport
2432 dependent.
2434 References to specific identities in the ietf-subscribed-
2435 notifications YANG model or the ietf-yang-push YANG model may be
2436 returned as part of the error responses resulting from failed
2437 attempts at datastore subscription. For errors defined as part of
2438 ietf-subscribed-notifications, please refer to
2440 [I-D.draft-ietf-netconf-subscribed-notifications]. The errors
2441 introduced in this document, grouped per RPC, are as follows:
2443 establish-subscription modify-subscription
2444 ---------------------- -------------------
2445 cant-exclude period-unsupported
2446 datastore-not-subscribable update-too-big
2447 on-change-unsupported sync-too-big
2448 on-change-sync-unsupported unchanging-selection
2449 period-unsupported
2450 update-too-big resync-subscription
2451 sync-too-big --------------------
2452 unchanging-selection no-such-subscription-resync
2453 sync-too-big
2455 There is one final set of transport independent RPC error elements
2456 included in the YANG model. These are the following four YANG-data
2457 structures for failed datastore subscriptions:
2459 1. YANG-data establish-subscription-error-datastore
2460 This MUST be returned if information identifying the reason for an
2461 RPC error has not been placed elsewhere within the transport
2462 portion of a failed "establish-subscription" RPC response. This
2463 MUST be sent if hints are included.
2465 2. YANG-data modify-subscription-error-datastore
2466 This MUST be returned if information identifying the reason for an
2467 RPC error has not been placed elsewhere within the transport
2468 portion of a failed "modifiy-subscription" RPC response. This
2469 MUST be sent if hints are included.
2471 3. YANG-data sn:delete-subscription-error
2472 This MUST be returned if information identifying the reason for an
2473 RPC error has not been placed elsewhere within the transport
2474 portion of a failed "delete-subscription" or "kill-subscription"
2475 RPC response.
2477 4. YANG-data resync-subscription-error
2478 This MUST be returned if information identifying the reason for an
2479 RPC error has not been placed elsewhere within the transport
2480 portion of a failed "resync-subscription" RPC response.
2482 A.2. Notifications of Failure
2484 A subscription may be unexpectedly terminated or suspended
2485 independent of any RPC or configuration operation. In such cases,
2486 indications of such a failure MUST be provided. To accomplish this,
2487 a number of errors can be returned as part of the corresponding
2488 subscription state change notification. For this purpose, the
2489 following error identities have been introduced in this document, in
2490 addition to those that were already defined in
2491 [I-D.draft-ietf-netconf-subscribed-notifications]:
2493 subscription-terminated subscription-suspended
2494 ----------------------- ----------------------
2495 datastore-not-subscribable period-unsupported
2496 unchanging-selection update-too-big
2497 synchronization-size
2499 Appendix B. Changes Between Revisions
2501 (To be removed by RFC editor prior to publication)
2503 v24 - v25
2505 o Minor updates to address IESG review comment regarding referencing
2506 the draft which addresses the notification capabilities problem.
2508 v23 - v24
2510 o Minor updates to address IESG review comments. Moving five of the
2511 coauthors to contributors as requested.
2513 v22 - v23
2515 o Minor updates to address IESG review comments.
2517 v21 - v22
2519 o Minor updates per Martin Bjorklund's YANG doctor review.
2521 v20 - v21
2523 o Minor updates, simplifying RPC input conditions.
2525 v19 - v20
2527 o Minor updates per WGLC comments.
2529 v18 - v19
2531 o Minor updates per WGLC comments.
2533 v17 - v18
2535 o Minor updates per WGLC comments.
2537 v16 - v17
2539 o Minor updates to YANG module, incorporating comments from Tom
2540 Petch.
2542 o Updated references.
2544 v15 - v16
2546 o Updated security considerations.
2548 o Updated references.
2550 o Addressed comments from last call review, specifically comments
2551 received from Martin Bjorklund.
2553 v14 - v15
2555 o Minor text fixes. Includes a fix to on-change update calculation
2556 to cover churn when an object changes to and from a value during a
2557 dampening period.
2559 v13 - v14
2561 o Minor text fixes.
2563 v12 - v13
2565 o Hint negotiation models now show error examples.
2567 o yang-data structures for rpc errors.
2569 v11 - v12
2571 o Included Martin's review clarifications.
2573 o QoS moved to subscribed-notifications
2575 o time-of-update removed as it is redundant with RFC5277's
2576 eventTime, and other times from notification-messages.
2578 o Error model moved to match existing implementations
2580 o On-change notifiable removed, how to do this is implementation
2581 specific.
2583 o NMDA model supported. Non NMDA version at https://github.com/
2584 netconf-wg/yang-push/
2586 v10 - v11
2588 o Promise model reference added.
2590 o Error added for no-such-datastore
2592 o Inherited changes from subscribed notifications (such as optional
2593 feature definitions).
2595 o scrubbed the examples for proper encodings
2597 v09 - v10
2599 o Returned to the explicit filter subtyping of v00-v05
2601 o identityref to ds:datastore made explicit
2603 o Returned ability to modify a selection filter via RPC.
2605 v08 - v09
2607 o Minor tweaks cleaning up text, removing appendicies, and making
2608 reference to revised-datastores.
2610 o Subscription-id (now:id) optional in push updates, except when
2611 encoded in RFC5277, Section 4 one-way notification.
2613 o Finished adding the text descibing the resync subscription RPC.
2615 o Removed relationships to other drafts and future technology
2616 appendicies as this work is being explored elsewhere.
2618 o Deferred the multi-line card issue to new drafts
2620 o Simplified the NACM interactions.
2622 v07 - v08
2624 o Updated YANG models with minor tweaks to accommodate changes of
2625 ietf-subscribed-notifications.
2627 v06 - v07
2629 o Clarifying text tweaks.
2631 o Clarification that filters act as selectors for subscribed
2632 datastore nodes; support for value filters not included but
2633 possible as a future extension
2635 o Filters don't have to be matched to existing YANG objects
2637 v05 - v06
2639 o Security considerations updated.
2641 o Base YANG model in [subscribe] updated as part of move to
2642 identities, YANG augmentations in this doc matched up
2644 o Terms refined and text updates throughout
2646 o Appendix talking about relationship to other drafts added.
2648 o Datastore replaces stream
2650 o Definitions of filters improved
2652 v04 to v05
2654 o Referenced based subscription document changed to Subscribed
2655 Notifications from 5277bis.
2657 o Getting operational data from filters
2659 o Extension notifiable-on-change added
2661 o New appendix on potential futures. Moved text into there from
2662 several drafts.
2664 o Subscription configuration section now just includes changed
2665 parameters from Subscribed Notifications
2667 o Subscription monitoring moved into Subscribed Notifications
2669 o New error and hint mechanisms included in text and in the YANG
2670 model.
2672 o Updated examples based on the error definitions
2674 o Groupings updated for consistency
2675 o Text updates throughout
2677 v03 to v04
2679 o Updates-not-sent flag added
2681 o Not notifiable extension added
2683 o Dampening period is for whole subscription, not single objects
2685 o Moved start/stop into rfc5277bis
2687 o Client and Server changed to subscriber, publisher, and receiver
2689 o Anchor time for periodic
2691 o Message format for synchronization (i.e. sync-on-start)
2693 o Material moved into 5277bis
2695 o QoS parameters supported, by not allowed to be modified by RPC
2697 o Text updates throughout
2699 Authors' Addresses
2701 Alexander Clemm
2702 Futurewei
2704 Email: ludwig@clemm.org
2706 Eric Voit
2707 Cisco Systems
2709 Email: evoit@cisco.com