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