idnits 2.17.1
draft-ietf-netconf-yang-push-16.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 is 1 instance 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: '... 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: '...on, the subscription MAY be suspended....'
(60 more instances...)
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Line 866 has weird spacing: '...ntifier sub...'
== Line 977 has weird spacing: '...ntifier sn:...'
== Line 2308 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 (May 31, 2018) is 2156 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Outdated reference: A later version (-26) exists of
draft-ietf-netconf-subscribed-notifications-12
** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525)
-- Obsolete informational reference (is this intentional?): RFC 5246
(Obsoleted by RFC 8446)
-- Obsolete informational reference (is this intentional?): RFC 7223
(Obsoleted by RFC 8343)
Summary: 3 errors (**), 0 flaws (~~), 6 warnings (==), 3 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: December 2, 2018 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 May 31, 2018
17 YANG Datastore Subscription
18 draft-ietf-netconf-yang-push-16
20 Abstract
22 Via the mechanism described in this document, subscriber applications
23 may request a continuous, customized stream of updates from a YANG
24 datastore. Providing such visibility into changes made upon YANG
25 configuration and operational datastore nodes enables new
26 capabilities based on the remote mirroring of configuration and
27 operational state.
29 Status of This Memo
31 This Internet-Draft is submitted in full conformance with the
32 provisions of BCP 78 and BCP 79.
34 Internet-Drafts are working documents of the Internet Engineering
35 Task Force (IETF). Note that other groups may also distribute
36 working documents as Internet-Drafts. The list of current Internet-
37 Drafts is at https://datatracker.ietf.org/drafts/current/.
39 Internet-Drafts are draft documents valid for a maximum of six months
40 and may be updated, replaced, or obsoleted by other documents at any
41 time. It is inappropriate to use Internet-Drafts as reference
42 material or to cite them other than as "work in progress."
44 This Internet-Draft will expire on December 2, 2018.
46 Copyright Notice
48 Copyright (c) 2018 IETF Trust and the persons identified as the
49 document authors. All rights reserved.
51 This document is subject to BCP 78 and the IETF Trust's Legal
52 Provisions Relating to IETF Documents
53 (https://trustee.ietf.org/license-info) in effect on the date of
54 publication of this document. Please review these documents
55 carefully, as they describe your rights and restrictions with respect
56 to this document. Code Components extracted from this document must
57 include Simplified BSD License text as described in Section 4.e of
58 the Trust Legal Provisions and are provided without warranty as
59 described in the Simplified BSD License.
61 This document may contain material from IETF Documents or IETF
62 Contributions published or made publicly available before November
63 10, 2008. The person(s) controlling the copyright in some of this
64 material may not have granted the IETF Trust the right to allow
65 modifications of such material outside the IETF Standards Process.
66 Without obtaining an adequate license from the person(s) controlling
67 the copyright in such materials, this document may not be modified
68 outside the IETF Standards Process, and derivative works of it may
69 not be created outside the IETF Standards Process, except to format
70 it for publication as an RFC or to translate it into languages other
71 than English.
73 Table of Contents
75 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
76 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 4
77 3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 5
78 3.1. Subscription Model . . . . . . . . . . . . . . . . . . . 5
79 3.2. Negotiation of Subscription Policies . . . . . . . . . . 6
80 3.3. On-Change Considerations . . . . . . . . . . . . . . . . 7
81 3.4. Reliability Considerations . . . . . . . . . . . . . . . 8
82 3.5. Data Encodings . . . . . . . . . . . . . . . . . . . . . 9
83 3.6. Defining the Selection with a Datastore . . . . . . . . . 10
84 3.7. Streaming Updates . . . . . . . . . . . . . . . . . . . . 11
85 3.8. Subscription Management . . . . . . . . . . . . . . . . . 13
86 3.9. Receiver Authorization . . . . . . . . . . . . . . . . . 14
87 3.10. On-change Notifiable YANG objects . . . . . . . . . . . . 15
88 3.11. Other Considerations . . . . . . . . . . . . . . . . . . 16
89 4. A YANG data model for management of datastore push
90 subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 17
91 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 17
92 4.2. Subscription configuration . . . . . . . . . . . . . . . 22
93 4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 23
94 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 24
95 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 29
96 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 45
97 7. Security Considerations . . . . . . . . . . . . . . . . . . . 45
98 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 46
99 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 46
100 9.1. Normative References . . . . . . . . . . . . . . . . . . 47
101 9.2. Informative References . . . . . . . . . . . . . . . . . 47
102 Appendix A. Appendix A: Subscription Errors . . . . . . . . . . 48
103 A.1. RPC Failures . . . . . . . . . . . . . . . . . . . . . . 48
104 A.2. Notifications of Failure . . . . . . . . . . . . . . . . 50
105 Appendix B. Changes between revisions . . . . . . . . . . . . . 50
106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 54
108 1. Introduction
110 Traditional approaches to remote visibility have been built on
111 polling. With polling, data is periodically requested and retrieved
112 by a client from a server to stay up-to-date. However, there are
113 issues associated with polling-based management:
115 o Polling incurs significant latency. This latency prohibits many
116 application types.
118 o Polling cycles may be missed, requests may be delayed or get lost,
119 often when the network is under stress and the need for the data
120 is the greatest.
122 o Polling requests may undergo slight fluctuations, resulting in
123 intervals of different lengths. The resulting data is difficult
124 to calibrate and compare.
126 o For applications that monitor for changes, many remote polling
127 cycles place ultimately fruitless load on the network, devices,
128 and applications.
130 A more effective alternative to polling is for an application to
131 receive automatic and continuous updates from a targeted subset of a
132 datastore. Accordingly, there is a need for a service that allows
133 applications to subscribe to updates from a datastore and that
134 enables the publisher to push and in effect stream those updates.
135 The requirements for such a service have been documented in
136 [RFC7923].
138 This document defines a corresponding solution that is built on top
139 of "Custom Subscription to Event Streams"
140 [I-D.draft-ietf-netconf-subscribed-notifications]. Supplementing
141 that work are YANG data model augmentations, extended RPCs, and new
142 datastore specific update notifications. Transport options for
143 [I-D.draft-ietf-netconf-subscribed-notifications] will work
144 seamlessly with this solution.
146 2. Definitions and Acronyms
148 This document uses the terminology defined in [RFC7950], [RFC8341],
149 and [RFC8342]. In addition, the following terms are introduced:
151 o Datastore node: An instance of a data node in a datastore. In the
152 context of this document sometimes also referred to 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.
182 o Update trigger: A mechanism that determines when an update record
183 needs to be generated.
185 o YANG-Push: The subscription and push mechanism for datastore
186 updates that is specified in this document.
188 3. Solution Overview
190 This document specifies a solution that provides subscription service
191 for updates from a datastore. This solution supports dynamic as well
192 as configured subscriptions to updates of datastore nodes.
193 Subscriptions specify when notification messages should be sent and
194 what data to include in update records. YANG objects are
195 subsequently pushed from the publisher to the receiver per the terms
196 of the subscription.
198 3.1. Subscription Model
200 YANG-push subscriptions are defined using a data model that is itself
201 defined in YANG. This model enhances the subscription model defined
202 in [I-D.draft-ietf-netconf-subscribed-notifications] with
203 capabilities that allow subscribers to subscribe to datastore node
204 updates, specifically to specify the update triggers defining when to
205 generate update records as well as what to include in an update
206 record. Key enhancements include:
208 o Specification of selection filters which identify targeted YANG
209 datastore nodes and/or subtrees within a datastore for which
210 updates are to be pushed.
212 o Specification of update policies contain conditions which trigger
213 the generation and pushing of new update records. There are two
214 types of subscriptions, distinguished by how updates are
215 triggered: periodic and on-change.
217 * For periodic subscriptions, the update trigger is specified by
218 two parameters that define when updates are to be pushed.
219 These parameters are the period interval with which to report
220 updates, and an anchor time which can be used to calculate at
221 which point in time updates need to be assembled and sent.
223 * For on-change subscriptions, an update trigger occurs whenever
224 a change in the subscribed information is detected. Included
225 are additional parameters such as:
227 + Dampening period: In an on-change subscription, detected
228 datastore node changes should be sent as quickly as
229 possible. However, it may be undesirable to send a rapid
230 series of datastore node changes. Such behavior has the
231 potential to exhaust of resources in the publisher or
232 receiver. In order to protect against that, a dampening
233 period MAY be used to specify the interval which must pass
234 before successive update records for the same subscription
235 are generated for a receiver. The dampening period
236 collectively applies to the set of all datastore nodes
237 selected by a single subscription and sent to a single
238 receiver. This means that when there is a change to one or
239 more subscribed objects, an update record containing those
240 objects is created either immediately when no dampening
241 period is in effect, or at the end of a dampening period.
242 If multiple changes to a single datastore node occur during
243 a dampening period, only the value that is in effect at the
244 time the update record is created is included. The
245 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 when a datastore node is created or deleted,
251 but not when a datastore node 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, 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 subscribers 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 datastore node.
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 subscription MAY be suspended.
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 datastore node is
319 generated, no other updates for this particular subscription will be
320 created until the end of the dampening period. Values sent at the
321 end of the dampening period are the current values of all changed
322 objects which are current at the time the dampening period expires.
323 Changed objects include those which were deleted or newly created
324 during that dampening period. If a datastore node has returned to
325 its original value (or even has been created and then deleted) during
326 the dampening-period, the last change will still be sent. This will
327 indicate churn is occurring on that datastore node.
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 datastore node creations and deletions, but not modifications of
332 datastore node values.
334 Putting it all together, following is the conceptual process for
335 creating an push-change-update notification:
337 1. Just before a change, or at the start of a dampening period,
338 evaluate any filtering and any access control rules. The result
339 is a set "A" of datastore nodes and subtrees.
341 2. Just after a change, or at the end of a dampening period,
342 evaluate any filtering and any (possibly new) access control
343 rules. The result is a set "B" of datastore nodes and subtrees.
345 3. Construct a YANG patch record for going from A to B.
347 4. If there were any changes made between A and B which canceled
348 each other out, insert into the YANG patch record the last change
349 made for any datastore node which otherwise wouldn't have
350 appeared.
352 5. If the resulting patch record is non-empty, send it to the
353 receiver.
355 Note: In cases where a subscriber wants to have separate dampening
356 periods for different objects, multiple subscriptions with different
357 objects in a selection filter can be created.
359 3.4. Reliability Considerations
361 A subscription to updates from a datastore is intended to obviate the
362 need for polling. However, in order to do so, it is critical that
363 subscribers can rely on the subscription and have confidence that
364 they will indeed receive the subscribed updates without having to
365 worry about updates being silently dropped. In other words, a
366 subscription constitutes a promise on the side of the publisher to
367 provide the receivers with updates per the terms of the subscription.
369 Now, there are many reasons why a publisher may at some point no
370 longer be able to fulfill the terms of the subscription, even if the
371 subscription had been entered into with good faith. For example, the
372 volume of data objects may be larger than anticipated, the interval
373 may prove too short to send full updates in rapid succession, or an
374 internal problem may prevent objects from being collected. For this
375 reason, the solution that is defined in this document mandates that a
376 publisher notifies receivers immediately and reliably whenever it
377 encounters a situation in which it is unable to keep the terms of the
378 subscription, and provides the publisher with the option to suspend
379 the subscription in such a case.
381 A publisher SHOULD reject a request for a subscription if it is
382 unlikely that the publisher will be able fulfill the terms of that
383 subscription request. In such cases, it is preferable to have a
384 subscriber request a less resource intensive subscription than to
385 deal with frequently degraded behavior.
387 3.5. Data Encodings
389 3.5.1. Periodic Subscriptions
391 In a periodic subscription, the data included as part of an update
392 corresponds to data that could have been read using a retrieval
393 operation.
395 3.5.2. On-Change Subscriptions
397 In an on-change subscription, updates need to indicate not only
398 values of changed datastore nodes but also the types of changes that
399 occurred since the last update. Therefore encoding rules for data in
400 on-change updates will generally follow YANG-patch operation as
401 specified in [RFC8072]. The YANG-patch will describe what needs to
402 be applied to the earlier state reported by the preceding update, to
403 result in the now-current state. Note that contrary to [RFC8072],
404 objects encapsulated are not restricted to configuration objects
405 only.
407 A publisher will indicate a change to the effect that a value of a
408 datstore node has been updated by indicating a "replace" operation
409 (applied to the datastore node) in the patch. When a new datastore
410 node was created (other than an element in a list), a publisher will
411 indicate a "create" operation in the patch. When a datastore node
412 was deleted (other than an element in a list), the publisher
413 indicates this by a "delete". When a new list element was created or
414 removed, the publisher indicates it by an "insert" or "remove",
415 respectively.
417 However a patch must be able to do more than just describe the delta
418 from the previous state to the current state. As per Section 3.3, it
419 must also be able to identify if transient changes have occurred on a
420 datastore node during a dampening period. To support this, it is
421 valid to encode a YANG patch operation so that its application would
422 result in no change between the previous and current state. This
423 indicates that some churn has occurred on the datastore node. An
424 example of this would be a patch that does a "create" operation for a
425 datastore node where the receiver believes one already exists, or a
426 "merge" operation which replaces a previous value with the same
427 value. Note that this means that the "create" and "delete" errors
428 described in [RFC8072] section 2.5 are not errors, and are valid
429 operations with YANG push.
431 3.6. Defining the Selection with a Datastore
433 A subscription must specify both the selection filters and the
434 datastore against which these selection filters will be applied.
435 This information is used to choose and subsequently push data from
436 the publisher's datastore to the receivers.
438 Only a single selection filter can be applied to a subscription at a
439 time. An rpc request proposing a new selection filter MUST remove
440 any existing filter. The following selection filter types are
441 included in the yang-push data model, and may be applied against a
442 datastore:
444 o subtree: A subtree selection filter identifies one or more
445 datastore subtrees. When specified, update records will only come
446 from the datastore nodes of selected datastore subtree(s). The
447 syntax and semantics correspond to that specified for [RFC6241]
448 section 6.
450 o xpath: An "xpath" selection filter is an XPath expression that
451 returns a node set. When specified, updates will only come from
452 the selected datastore nodes.
454 These filters are intended to be used as selectors that define which
455 objects are within the scope of a subscription. A publisher MUST
456 support at least one type of selection filter.
458 Xpath itself provides powerful filtering constructs and care must be
459 used in filter definition. As an example, consider an XPath filter
460 with a boolean result; such a result will not provide an easily
461 interpretable subset of a datastore. Beyond the boolean example, it
462 is quite possible to define an XPath filter where results are easy
463 for an application to misinterpret. Consider an XPath filter which
464 only passes a datastore node when an interface is up. It is up to
465 the receiver to understand implications of the presence or absence of
466 objects in each update.
468 When the set of selection filtering criteria is applied for a
469 periodic subscription, all selected datastore nodes to which a
470 receiver has access are provided to that receiver. If the same
471 filtering criteria is applied to an on-change subscription, only the
472 subset of those datastore nodes supporting on-change is provided. A
473 datastore node which doesn't support on-change is never sent as part
474 of an on-change subscription's "push-update" or "push-change-update".
476 3.7. Streaming Updates
478 Contrary to traditional data retrieval requests, datastore
479 subscription enables an unbounded series of update records to be
480 streamed over time. Two generic YANG notifications for update
481 records have been defined for this: "push-update" and "push-change-
482 update".
484 A "push-update" notification defines a complete, filtered update of
485 the datastore per the terms of a subscription. This type of YANG
486 notification is used for continuous updates of periodic
487 subscriptions. A "push-update" notification can also be used for the
488 on-change subscriptions in two cases. First it will be used as the
489 initial "push-update" if there is a need to synchronize the receiver
490 at the start of a new subscription. It also MAY be sent if the
491 publisher later chooses to resynch an on-change subscription. The
492 "push-update" update record contains an instantiated datastore
493 subtree with all of the subscribed contents. The content of the
494 update record is equivalent to the contents that would be obtained
495 had the same data been explicitly retrieved using a datastore
496 retrieval operation using the same transport with the same filters
497 applied.
499 A "push-change-update" notification is the most common type of update
500 for on-change subscriptions. The update record in this case contains
501 the set of changes that datastore nodes have undergone since the last
502 notification message. In other words, this indicates which datastore
503 nodes have been created, deleted, or have had changes to their
504 values. In cases where multiple changes have occurred and the
505 datastore node has not been deleted, the datastore node's most
506 current value is reported. (In other words, for each datastore node,
507 only one change is reported, not its entire history. Doing so would
508 defeat the purpose of the dampening period.)
510 These new "push-update" or "push-change-update" are encoded and
511 placed within notification messages, and ultimately queued for egress
512 over the specified transport.
514 The following is an example of a notification message for a
515 subscription tracking the operational status of a single Ethernet
516 port (per [RFC7223]). This notification message is encoded XML over
517 NETCONF as per [I-D.draft-ietf-netconf-netconf-event-notifications].
519
520 2017-10-25T08:00:11.22Z
521
522 1011
523
524
525
526 eth0
527 up
528
529
530
531
532
534 Figure 1: Push example
536 The following is an example of an on-change notification message for
537 the same subscription.
539
540 2017-10-25T08:22:33.44Z
541
542 89
543
544
545 1
546
547 edit1
548 merge
549 /ietf-interfaces:interfaces-state
550
551
552
553 eth0
554 down
555
556
557
558
559
560
561
562
564 Figure 2: Push example for on change
566 Of note in the above example is the 'patch-id' with a value of '1'.
567 Per [RFC8072], the 'patch-id' is an arbitrary string. With YANG
568 Push, the publisher SHOULD put into the 'patch-id' a counter starting
569 at '1' which increments with every 'push-change-update' generated for
570 a subscription. If used as a counter, this counter MUST be reset to
571 '1' anytime a resynchronization occurs (i.e., with the sending of a
572 'push-update'). Also if used as a counter, the counter MUST be reset
573 to '1' the after passing a maximum value of '4294967295' (i.e.
574 maximum value that can be represented using uint32 data type). Such
575 a mechanism allows easy identification of lost or out-of-sequence
576 update records.
578 3.8. Subscription Management
580 The RPCs defined within
581 [I-D.draft-ietf-netconf-subscribed-notifications] have been enhanced
582 to support datastore subscription negotiation. Also, new error codes
583 have been added that are able to indicate why a datastore
584 subscription attempt has failed, along with new yang-data that MAY be
585 used to include details on input parameters that might result in a
586 successful subsequent RPC invocation.
588 The establishment or modification of a datastore subscription can be
589 rejected for multiple reasons. This includes a too large subtree
590 request, or the inability of the publisher to push update records as
591 frequently as requested. In such cases, no subscription is
592 established. Instead, the subscription-result with the failure
593 reason is returned as part of the RPC response. As part of this
594 response, a set of alternative subscription parameters MAY be
595 returned that would likely have resulted in acceptance of the
596 subscription request. The subscriber may consider these as part of
597 future subscription attempts.
599 In the case of a rejected request for an establishment of a datastore
600 subscription, the hints MUST be transported within a yang-data
601 "establish-subscription-datastore-error-info" container inserted into
602 the RPC error response, in lieu of the "establish-subscription-
603 stream-error-info" that is inserted in case of a stream subscription.
605 Below is a tree diagram for "establish-subscription-datastore-error-
606 info". All tree diagrams used in this document follow the notation
607 defined in [RFC8340]
608 yang-data establish-subscription-datastore-error-info
609 +--ro establish-subscription-datasore-error-info
610 +--ro reason? identityref
611 +--ro period-hint? yang:timeticks
612 +--ro filter-failure-hint? string
613 +--ro object-count-estimate? uint32
614 +--ro object-count-limit? uint32
615 +--ro kilobytes-estimate? uint32
616 +--ro kilobytes-limit? uint32
618 Figure 3: Tree diagram for establish-subscription-datastore-error-
619 info
621 Similarly, in the case of a rejected request for modification of a
622 datastore subscription, the hints MUST be transported within a yang-
623 data "modify-subscription-datastore-error-info" container inserted
624 into the RPC error response, in lieu of the "modify-subscription-
625 stream-error-info" that is inserted in case of a stream subscription.
627 Below is a tree diagram for "modify-subscription-datastore-error-
628 info".
630 yang-data modify-subscription-datastore-error-info
631 +--ro modify-subscription-datasore-error-info
632 +--ro reason? identityref
633 +--ro period-hint? yang:timeticks
634 +--ro filter-failure-hint? string
635 +--ro object-count-estimate? uint32
636 +--ro object-count-limit? uint32
637 +--ro kilobytes-estimate? uint32
638 +--ro kilobytes-limit? uint32
640 Figure 4: Tree diagram for modify-subscription-datastore-error-info
642 3.9. Receiver Authorization
644 A receiver of subscription data MUST only be sent updates for which
645 they have proper authorization. A publisher MUST ensure that no non-
646 authorized data is included in push updates. To do so, it needs to
647 apply all corresponding checks applicable at the time of a specific
648 pushed update and if necessary silently remove any non-authorized
649 data from datastore subtrees. This enables YANG data pushed based on
650 subscriptions to be authorized equivalently to a regular data
651 retrieval (get) operation.
653 A publisher MUST allow for the possibility that a subscription's
654 selection filter references non-existent or access-protected data.
655 Such support permits a receiver the ability to monitor the entire
656 lifecyle of some datastore tree. In this case, all "push-update"
657 notifications must be sent empty, and no "push-change-update"
658 notifications will be sent until some data becomes visible for a
659 receiver.
661 A publisher MAY choose reject an establish-subscription request which
662 selects non-existent or access-protected data. In addition, a
663 publisher MAY choose to terminate a dynamic subscription or suspend a
664 configured receiver when the authorization privileges of a receiver
665 change, or the access controls for subscribed objects change. Such a
666 capability enables the publisher to avoid having to support a
667 continuous, and total filtering of an entire subscription's content.
669 In these cases above, the error identity "unchanging-selection"
670 SHOULD be returned. This reduces the possibility of leakage of
671 access controlled objects.
673 Each "push-update" and "push-change-update" MUST have access control
674 applied. This includes validating that read access is permitted for
675 any new objects selected since the last notification message was sent
676 to a particular each receiver. To accomplish this, implementations
677 SHOULD support the conceptual authorization model of [RFC8342],
678 specifically section 3.2.4.
680 +-----------------+ +--------------------+
681 push-update or --> | datastore node | yes | add datastore node |
682 push-change-update | access allowed? | ---> | to update message |
683 +-----------------+ +--------------------+
685 Figure 5: Updated [rfc6536bis] access control for push updates
687 If read access into previously accessible nodes has been lost due to
688 a receiver permissions change, this SHOULD be reported as a patch
689 "delete" operation for on-change subscriptions. If not capable of
690 handling such receiver permission changes with such a "delete",
691 publisher implementations MUST force dynamic subscription re-
692 establishment or configured subscription re-initialization so that
693 appropriate filtering is installed.
695 3.10. On-change Notifiable YANG objects
697 In some cases, a publisher supporting on-change notifications may not
698 be able to push updates for some datastore nodes on-change. Reasons
699 for this might be that the value of the datastore node changes
700 frequently (e.g., [RFC7223]'s in-octets counter), that small
701 datastore node changes are frequent and meaningless (e.g., a
702 temperature gauge changing 0.1 degrees), or that the implementation
703 is not capable of on-change notification for a particular datastore
704 node.
706 In those cases, it will be important for client applications to have
707 a way to identify for which objects on-change notifications are
708 supported and for which ones they are not supported. Otherwise
709 client applications will have no way of knowing whether they can
710 indeed rely on their on-change subscription to provide them with the
711 change updates that they are interested in. In other words, if
712 implementations do not provide a solution and do not support
713 comprehensive on-change notifiability, clients of those
714 implementations will have no way of knowing what their on-change
715 subscription actually covers.
717 Implementations are therefore strongly advised to provide a solution
718 to this problem. It is expected that such a solution will be
719 standardized at some point in the future. In the meantime and until
720 this occurs, implementations will be expected to provide their own
721 solution.
723 3.11. Other Considerations
725 3.11.1. Robustness and reliability
727 Particularly in the case of on-change updates, it is important that
728 these updates do not get lost. Or in case the loss of an update is
729 unavoidable, it is critical that the receiver is notified
730 accordingly.
732 Update records for a single subscription MUST NOT be resequenced
733 prior to transport.
735 It is conceivable that under certain circumstances, a publisher will
736 recognize that it is unable to include within an update record the
737 full set of objects desired per the terms of a subscription. In this
738 case, the publisher MUST take one or more of the following actions.
740 o A publisher MUST set the "incomplete-update" flag on any update
741 record which is known to be missing information.
743 o It MAY choose to suspend a subscription as per
744 [I-D.draft-ietf-netconf-subscribed-notifications].
746 o When resuming an on-change subscription, the publisher SHOULD
747 generate a complete patch from the previous update record. If
748 this is not possible and the "no-synch-on-start" option is not
749 present for the subscription, then the full datastore contents MAY
750 be sent via a "push-update" instead (effectively replacing the
751 previous contents). If neither of these are possible, then an
752 "incomplete-update" flag MUST be included on the next "push-
753 change-update".
755 Note: It is perfectly acceptable to have a series of "push-change-
756 update" notifications (and even "push update" notifications) serially
757 queued at the transport layer awaiting transmission. It is not
758 required to merge pending update messages. I.e., the dampening
759 period applies to update record creation, not transmission.
761 3.11.2. Publisher capacity
763 It is far preferable to decline a subscription request than to accept
764 such a request when it cannot be met.
766 Whether or not a subscription can be supported will be determined by
767 a combination of several factors such as the subscription update
768 trigger (on-change or periodic), the period in which to report
769 changes (one second periods will consume more resources than one hour
770 periods), the amount of data in the datastore subtree that is being
771 subscribed to, and the number and combination of other subscriptions
772 that are concurrently being serviced.
774 4. A YANG data model for management of datastore push subscriptions
776 4.1. Overview
778 The YANG data model for datastore push subscriptions is depicted in
779 the following figure. The tree diagram follows the notiation defined
780 in [RFC8340]. New schema objects defined here (i.e., beyond those
781 from [I-D.draft-ietf-netconf-subscribed-notifications]) are
782 identified with "yp". For the reader's convenience, in order to
783 compact the tree representation, some nodes that are defined in ietf-
784 subscribed-notifications and that are not essential to the
785 understanding of the data model defined here have been removed. This
786 is indicated by "..." in the diagram where applicable.
788 module: ietf-subscribed-notifications
789 ...
790 +--rw filters
791 | ...
792 | +--rw yp:selection-filter* [identifier]
793 | +--rw yp:identifier sn:filter-id
794 | +--rw (yp:filter-spec)?
795 | +--:(yp:datastore-subtree-filter)
796 | | +--rw yp:datastore-subtree-filter?
797 | | {sn:subtree}?
798 | +--:(yp:datastore-xpath-filter)
799 | +--rw yp:datastore-xpath-filter? yang:xpath1.0
800 | {sn:xpath}?
801 +--rw subscriptions
802 +--rw subscription* [identifier]
803 | ...
804 +--rw (target)
805 | +--:(stream)
806 | | ...
807 | +--:(yp:datastore)
808 | +--rw yp:datastore identityref
809 | +--rw (yp:selection-filter)?
810 | +--:(yp:by-reference)
811 | | +--rw yp:selection-filter-ref
812 | | selection-filter-ref
813 | +--:(yp:within-subscription)
814 | +--rw (yp:filter-spec)?
815 | +--:(yp:datastore-subtree-filter)
816 | | +--rw yp:datastore-subtree-filter?
817 | | {sn:subtree}?
818 | +--:(yp:datastore-xpath-filter)
819 | +--rw yp:datastore-xpath-filter?
820 | yang:xpath1.0 {sn:xpath}?
821 | ...
822 +--rw (yp:update-trigger)?
823 +--:(yp:periodic)
824 | +--rw yp:periodic!
825 | +--rw yp:period yang:timeticks
826 | +--rw yp:anchor-time? yang:date-and-time
827 +--:(yp:on-change) {on-change}?
828 +--rw yp:on-change!
829 +--rw yp:dampening-period? yang:timeticks
830 +--rw yp:no-synch-on-start? empty
831 +--rw yp:excluded-change* change-type
833 rpcs:
834 +---x establish-subscription
835 | +---w input
836 | | ...
837 | | +---w (target)
838 | | | +--:(stream)
839 | | | | ...
840 | | | +--:(yp:datastore)
841 | | | +---w yp:datastore identityref
842 | | | +---w (yp:selection-filter)?
843 | | | +--:(yp:by-reference)
844 | | | | +---w yp:selection-filter-ref
845 | | | | selection-filter-ref
846 | | | +--:(yp:within-subscription)
847 | | | +---w (yp:filter-spec)?
848 | | | +--:(yp:datastore-subtree-filter)
849 | | | | +---w yp:datastore-subtree-filter?
850 | | | | {sn:subtree}?
851 | | | +--:(yp:datastore-xpath-filter)
852 | | | +---w yp:datastore-xpath-filter?
853 | | | yang:xpath1.0 {sn:xpath}?
854 | | | ...
855 | | +---w (yp:update-trigger)?
856 | | +--:(yp:periodic)
857 | | | +---w yp:periodic!
858 | | | +---w yp:period yang:timeticks
859 | | | +---w yp:anchor-time? yang:date-and-time
860 | | +--:(yp:on-change) {on-change}?
861 | | +---w yp:on-change!
862 | | +---w yp:dampening-period? yang:timeticks
863 | | +---w yp:no-synch-on-start? empty
864 | | +---w yp:excluded-change* change-type
865 | +--ro output
866 | +--ro identifier subscription-id
867 +---x modify-subscription
868 | +---w input
869 | ...
870 | +---w (target)
871 | | ...
872 | | +--:(yp:datastore)
873 | | +---w (yp:selection-filter)?
874 | | +--:(yp:by-reference)
875 | | | +---w yp:selection-filter-ref
876 | | | selection-filter-ref
877 | | +--:(yp:within-subscription)
878 | | +---w (yp:filter-spec)?
879 | | +--:(yp:datastore-subtree-filter)
880 | | | +---w yp:datastore-subtree-filter?
881 | | | {sn:subtree}?
882 | | +--:(yp:datastore-xpath-filter)
883 | | +---w yp:datastore-xpath-filter?
884 | | yang:xpath1.0 {sn:xpath}?
885 | | ...
886 | +---w (yp:update-trigger)?
887 | +--:(yp:periodic)
888 | | +---w yp:periodic!
889 | | +---w yp:period yang:timeticks
890 | | +---w yp:anchor-time? yang:date-and-time
891 | +--:(yp:on-change) {on-change}?
892 | +---w yp:on-change!
893 | +---w yp:dampening-period? yang:timeticks
894 +---x delete-subscription
895 | ...
896 +---x kill-subscription
897 ...
899 yang-data (for placement into rpc error responses)
900 ...
902 notifications:
903 +---n replay-completed {replay}?
904 | ...
905 +---n subscription-completed
906 | ...
907 +---n subscription-started {configured}?
908 | | ...
909 | +--ro (target)
910 | | ...
911 | | +--:(yp:datastore)
912 | | +--ro yp:datastore identityref
913 | | +--ro (yp:selection-filter)?
914 | | +--:(yp:by-reference)
915 | | | +--ro yp:selection-filter-ref
916 | | | selection-filter-ref
917 | | +--:(yp:within-subscription)
918 | | +--ro (yp:filter-spec)?
919 | | +--:(yp:datastore-subtree-filter)
920 | | | +--ro yp:datastore-subtree-filter?
921 | | {sn:subtree}?
922 | | +--:(yp:datastore-xpath-filter)
923 | | +--ro yp:datastore-xpath-filter?
924 | | yang:xpath1.0 {sn:xpath}?
925 | ...
926 | +--ro (yp:update-trigger)?
927 | +--:(yp:periodic)
928 | | +--ro yp:periodic!
929 | | +--ro yp:period yang:timeticks
930 | | +--ro yp:anchor-time? yang:date-and-time
931 | +--:(yp:on-change) {on-change}?
932 | +--ro yp:on-change!
933 | +--ro yp:dampening-period? yang:timeticks
934 | +--ro yp:no-synch-on-start? empty
935 | +--ro yp:excluded-change* change-type
936 +---n subscription-resumed
937 | ...
938 +---n subscription-modified
939 | ...
940 | +--ro (target)
941 | | | ...
942 | | +--:(yp:datastore)
943 | | +--ro yp:datastore identityref
944 | | +--ro (yp:selection-filter)?
945 | | +--:(yp:by-reference)
946 | | | +--ro yp:selection-filter-ref
947 | | | selection-filter-ref
948 | | +--:(yp:within-subscription)
949 | | +--ro (yp:filter-spec)?
950 | | +--:(yp:datastore-subtree-filter)
951 | | | +--ro yp:datastore-subtree-filter?
952 | | | {sn:subtree}?
953 | | +--:(yp:datastore-xpath-filter)
954 | | +--ro yp:datastore-xpath-filter?
955 | | yang:xpath1.0 {sn:xpath}?
956 | ...
957 | +--ro (yp:update-trigger)?
958 | +--:(yp:periodic)
959 | | +--ro yp:periodic!
960 | | +--ro yp:period yang:timeticks
961 | | +--ro yp:anchor-time? yang:date-and-time
962 | +--:(yp:on-change) {on-change}?
963 | +--ro yp:on-change!
964 | +--ro yp:dampening-period? yang:timeticks
965 | +--ro yp:no-synch-on-start? empty
966 | +--ro yp:excluded-change* change-type
967 +---n subscription-terminated
968 | ...
969 +---n subscription-suspended
970 ...
972 module: ietf-yang-push
974 rpcs:
975 +---x resynch-subscription {on-change}?
976 +---w input
977 +---w identifier sn:subscription-id
979 yang-data: (for placement into rpc error responses)
980 +-- resynch-subscription-error
981 | +--ro reason? identityref
982 | +--ro period-hint? timeticks
983 | +--ro filter-failure-hint? string
984 | +--ro object-count-estimate? uint32
985 | +--ro object-count-limit? uint32
986 | +--ro kilobytes-estimate? uint32
987 | +--ro kilobytes-limit? uint32
988 +-- establish-subscription-error-datastore
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 +-- modify-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
1005 notifications:
1006 +---n push-update
1007 | +--ro subscription-id? sn:subscription-id
1008 | +--ro incomplete-update? empty
1009 | +--ro datastore-contents?
1010 +---n push-change-update {on-change}?
1011 +--ro subscription-id? sn:subscription-id
1012 +--ro incomplete-update? empty
1013 +--ro datastore-changes?
1015 Figure 6: Model structure
1017 Selected components of the model are summarized below.
1019 4.2. Subscription configuration
1021 Both configured and dynamic subscriptions are represented within the
1022 list "subscription". New parameters extending the basic subscription
1023 data model in [I-D.draft-ietf-netconf-subscribed-notifications]
1024 include:
1026 o The targeted datastore from which the selection is being made.
1027 The potential datastores include those from [RFC8341]. A platform
1028 may also choose to support a custom datastore.
1030 o A selection filter identifying yang nodes of interest within a
1031 datastore. Filter contents are specified via a reference to an
1032 existing filter, or via an in-line definition for only that
1033 subscription. Referenced filters allows an implementation to
1034 avoid evaluating filter acceptability during a dynamic
1035 subscription request. The case statement differentiates the
1036 options.
1038 o For periodic subscriptions, triggered updates will occur at the
1039 boundaries of a specified time interval. These boundaries can be
1040 calculated from the periodic parameters:
1042 * a "period" which defines the duration between push updates.
1044 * an "anchor-time"; update intervals always fall on the points in
1045 time that are a multiple of a "period" from an "anchor-time".
1046 If "anchor-time" is not provided, then the "anchor-time" MUST
1047 be set with the creation time of the initial update record.
1049 o For on-change subscriptions, assuming any dampening period has
1050 completed, triggering occurs whenever a change in the subscribed
1051 information is detected. On-change subscriptions have more
1052 complex semantics that is guided by its own set of parameters:
1054 * a "dampening-period" specifies the interval that must pass
1055 before a successive update for the subscription is sent. If no
1056 dampening period is in effect, the update is sent immediately.
1057 If a subsequent change is detected, another update is only sent
1058 once the dampening period has passed for this subscription.
1060 * an "excluded-change" flag which allows restriction of the types
1061 of changes for which updates should be sent (e.g., only add to
1062 an update record on datastore node creation).
1064 * a "no-synch-on-start" flag which specifies whether a complete
1065 update with all the subscribed data is to be sent at the
1066 beginning of a subscription.
1068 4.3. YANG Notifications
1070 4.3.1. State Change Notifications
1072 Subscription state notifications and mechanism are reused from
1073 [I-D.draft-ietf-netconf-subscribed-notifications]. Notifications
1074 "subscription-started" and "subscription-modified" have been
1075 augmented to include the datastore specific objects.
1077 4.3.2. Notifications for Subscribed Content
1079 Along with the subscribed content, there are other objects which
1080 might be part of a "push-update" or "push-change-update"
1081 notification.
1083 A "subscription-id" MUST be transported along with the subscribed
1084 contents. An [RFC5277] Section 4 one-way notification MAY be used
1085 for encoding updates. Where it is, the relevant "subscription-id"
1086 MUST be encoded as the first element within each "push-update" or
1087 "push-change-update". This allows a receiver to differentiate which
1088 subscription resulted in a particular push.
1090 A "time-of-update" which represents the time an update record
1091 snapshot was generated. A receiver MAY assume that a publisher's
1092 objects have these pushed values at this point in time.
1094 An "incomplete-update" leaf. This leaf indicates that not all
1095 changes which have occurred since the last update are actually
1096 included with this update. In other words, the publisher has failed
1097 to fulfill its full subscription obligations. (For example a
1098 datastore was unable to providing the full set of datastore nodes to
1099 a publisher process.) To facilitate re-synchronization of on-change
1100 subscriptions, a publisher MAY subsequently send a "push-update"
1101 containing a full selection snapshot of subscribed data.
1103 4.4. YANG RPCs
1105 YANG-Push subscriptions are established, modified, and deleted using
1106 RPCs augmented from
1107 [I-D.draft-ietf-netconf-subscribed-notifications].
1109 4.4.1. Establish-subscription RPC
1111 The subscriber sends an establish-subscription RPC with the
1112 parameters in section 3.1. An example might look like:
1114
1116
1119
1120
1121 ds:operational
1122
1123
1126
1127
1128 500
1129
1130
1131
1133 Figure 7: Establish-subscription RPC
1135 A positive response includes the "identifier" of the accepted
1136 subscription. In that case a publisher MAY respond:
1138
1140
1142 ok
1143
1144
1146 52
1147
1148
1150 Figure 8: Establish-subscription positive RPC response
1152 A subscription can be rejected for multiple reasons, including the
1153 lack of authorization to establish a subscription, no capacity to
1154 serve the subscription at the publisher, or the inability of the
1155 publisher to select datastore content at the requested cadence.
1157 If a request is rejected because the publisher is not able to serve
1158 it, the publisher SHOULD include in the returned error hints which
1159 help a subscriber understand subscription parameters might have been
1160 accepted for the request. These hints would be included within the
1161 yang-data structure "establish-subscription-error-datastore".
1162 However even with these hints, there are no guarantee that subsequent
1163 requests will in fact be accepted.
1165 The specific parameters to be returned in as part of the RPC error
1166 response depend on the specific transport that is used to manage the
1167 subscription. In the case of NETCONF
1168 [I-D.draft-ietf-netconf-netconf-event-notifications], when a
1169 subscription request is rejected, the NETCONF RPC reply MUST include
1170 an "rpc-error" element with the following elements:
1172 o "error-type" of "application".
1174 o "error-tag" of "operation-failed".
1176 o Optionally, an "error-severity" of "error" (this MAY but does not
1177 have to be included).
1179 o "error-app-tag" with the value being a string that corresponds to
1180 an identity with a base of "establish-subscription-error".
1182 o Optionally, "error-info" containing XML-encoded data with hints
1183 for parameter settings that might result in future RPC success per
1184 yang-data definition "establish-subscription-error-datastore".
1186 For example, for the following request:
1188
1190
1193
1195 ds:operational
1196
1197
1199 /ex:foo
1200
1201
1202 100
1203
1204
1205
1207 Figure 9: Establish-subscription request example 2
1209 a publisher that cannot serve on-change updates but periodic updates
1210 might return the following:
1212
1214
1215 application
1216 operation-failed
1217 error
1218
1219 on-change-unsupported
1220
1221
1223 /yp:periodic/yp:period
1224
1225
1226
1228 Figure 10: Establish-subscription error response example 2
1230 4.4.2. Modify-subscription RPC
1232 The subscriber MAY invoke the "modify-subscription" RPC for a
1233 subscription it previously established. The subscriber will include
1234 newly desired values in the "modify-subscription" RPC. Parameters
1235 not included MUST remain unmodified. Below is an example where a
1236 subscriber attempts to modify the "period" of a subscription.
1238
1240
1243 1011
1244
1246 ds:operational
1247
1248
1250 /ex:bar
1251
1252
1253 250
1254
1255
1256
1258 Figure 11: Modify subscription request
1260 The publisher MUST respond explicitly positively or negatively to the
1261 request. If the subscription modification is rejected, the
1262 subscription is maintained as it was before the modification request.
1263 In addition, the publisher MUST send an rpc error response. This rpc
1264 error response may contain hints encapsulated within the yang-data
1265 structure "modify-subscription-error-datastore". A subscription MAY
1266 be modified multiple times.
1268 The specific parameters to be returned in as part of the RPC error
1269 response depend on the specific transport that is used to manage the
1270 subscription. In the case of NETCONF
1271 [I-D.draft-ietf-netconf-netconf-event-notifications], when a
1272 subscription request is rejected, the NETCONF RPC reply MUST include
1273 an "rpc-error" element with the following elements:
1275 o "error-type" of "application".
1277 o "error-tag" of "operation-failed".
1279 o Optionally, an "error-severity" of "error" (this MAY but does not
1280 have to be included).
1282 o "error-app-tag" with the value being a string that corresponds to
1283 an identity with a base of "modify-subscription-error".
1285 o "error-path" pointing to the data node or parameter that caused
1286 the rejection.
1288 o Optionally, "error-info" containing XML-encoded data with hints
1289 for parameter settings that might result in future RPC success per
1290 yang-data definition "modify-subscription-error-datastore".
1292 A configured subscription cannot be modified using "modify-
1293 subscription" RPC. Instead, the configuration needs to be edited as
1294 needed.
1296 4.4.3. Delete-subscription RPC
1298 To stop receiving updates from a subscription and effectively delete
1299 a subscription that had previously been established using an
1300 "establish-subscription" RPC, a subscriber can send a "delete-
1301 subscription" RPC, which takes as only input the subscription's
1302 "identifier". This RPC is unmodified from
1303 [I-D.draft-ietf-netconf-subscribed-notifications].
1305 4.4.4. Resynch-subscription RPC
1307 This RPC is only applicable only for on-change subscriptions
1308 previously established using an "establish-subscription" RPC. For
1309 example:
1311
1313
1316 1011
1317
1318
1320 Resynch subscription
1322 On receipt, a publisher must either accept the request and quickly
1323 follow with a "push-update", or send an appropriate error within an
1324 rpc error response. Within an error response, the publisher may
1325 include supplemental information about the reasons within the yang-
1326 data structure "resynch-subscription-error".
1328 4.4.5. YANG Module Synchronization
1330 To make subscription requests, the subscriber needs to know the YANG
1331 module library available on the publisher. The YANG 1.0 module
1332 library information is sent by a NETCONF server in the NETCONF
1333 "hello" message. For YANG 1.1 modules and all modules used with the
1334 RESTCONF [RFC8040] protocol, this information is provided by the YANG
1335 Library module (ietf-yang-library.yang from [RFC7895]. This YANG
1336 library information is important for the receiver to reproduce the
1337 set of data node definitions used within the publisher.
1339 The YANG library includes a module list with the name, revision,
1340 enabled features, and applied deviations for each YANG module
1341 implemented by the publisher. The receiver is expected to know the
1342 YANG library information before starting a subscription. The
1343 "/modules-state/module-set-id" leaf in the "ietf-yang-library" module
1344 can be used to cache the YANG library information.
1346 The set of modules, revisions, features, and deviations can change at
1347 run-time (if supported by the publisher implementation). In this
1348 case, the receiver needs to be informed of module changes before
1349 datastore nodes from changed modules can be processed correctly. The
1350 YANG library provides a simple "yang-library-change" notification
1351 that informs the subscriber that the library has changed. The
1352 receiver then needs to re-read the entire YANG library data for the
1353 replicated publisher in order to detect the specific YANG library
1354 changes. The "ietf-netconf-notifications" module defined in
1355 [RFC6470] contains a "netconf-capability-change" notification that
1356 can identify specific module changes. For example, the module URI
1357 capability of a newly loaded module will be listed in the "added-
1358 capability" leaf-list, and the module URI capability of an removed
1359 module will be listed in the "deleted-capability" leaf-list.
1361 5. YANG module
1363 file "ietf-yang-push@2018-05-31.yang"
1364 module ietf-yang-push {
1365 yang-version 1.1;
1366 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push";
1367 prefix yp;
1369 import ietf-yang-types {
1370 prefix yang;
1371 }
1372 import ietf-subscribed-notifications {
1373 prefix sn;
1374 }
1375 import ietf-datastores {
1376 prefix ds;
1377 }
1378 import ietf-restconf {
1379 prefix rc;
1380 }
1382 organization
1383 "IETF";
1384 contact
1385 "WG Web:
1386 WG List:
1388 Editor: Alexander Clemm
1389
1391 Editor: Eric Voit
1392
1394 Editor: Alberto Gonzalez Prieto
1395
1397 Editor: Ambika Prasad Tripathy
1398
1400 Editor: Einar Nilsen-Nygaard
1401
1403 Editor: Andy Bierman
1404
1406 Editor: Balazs Lengyel
1407 ";
1408 description
1409 "This module contains YANG specifications for YANG push.";
1411 revision 2018-05-31 {
1412 description
1413 "Initial revision.";
1414 reference "draft-ietf-netconf-yang-push-16";
1415 }
1417 /*
1418 * FEATURES
1419 */
1421 feature on-change {
1422 description
1423 "This feature indicates that on-change triggered subscriptions
1424 are supported.";
1425 }
1427 /*
1428 * IDENTITIES
1429 */
1430 /* Error type identities for datastore subscription */
1432 identity resynch-subscription-error {
1433 description
1434 "Problem found while attempting to fulfill an
1435 'resynch-subscription' RPC request. ";
1436 }
1438 identity cant-exclude {
1439 base sn:establish-subscription-error;
1440 description
1441 "Unable to remove the set of 'excluded-changes'. This means the
1442 publisher is unable to restrict 'push-change-update's to just
1443 the change types requested for this subscription.";
1444 }
1446 identity datastore-not-subscribable {
1447 base sn:establish-subscription-error;
1448 base sn:subscription-terminated-reason;
1449 description
1450 "This is not a subscribable datastore.";
1451 }
1453 identity no-such-subscription-resynch {
1454 base resynch-subscription-error;
1455 description
1456 "Referenced subscription doesn't exist. This may be as a result
1457 of a non-existent subscription ID, an ID which belongs to
1458 another subscriber, or an ID for configured subscription.";
1459 }
1461 identity on-change-unsupported {
1462 base sn:establish-subscription-error;
1463 description
1464 "On-change is not supported for any objects which are selectable
1465 by this filter.";
1466 }
1468 identity on-change-synch-unsupported {
1469 base sn:establish-subscription-error;
1470 description
1471 "Neither synch on start nor resynchronization are supported for
1472 this subscription. This error will be used for two reasons.
1473 First if an 'establish-subscription' RPC doesn't include
1474 'no-synch-on-start', yet the publisher can't support sending a
1475 'push-update' for this subscription for reasons other than
1476 'on-change-unsupported' or 'synchronization-size'. And second,
1477 if the 'resynch-subscription' RPC is invoked either for an
1478 existing periodic subscription, or for an on-change subscription
1479 which can't support resynchronization.";
1480 }
1482 identity period-unsupported {
1483 base sn:establish-subscription-error;
1484 base sn:modify-subscription-error;
1485 base sn:subscription-suspended-reason;
1486 description
1487 "Requested time period is too short. This can be for both
1488 periodic and on-change subscriptions (with or without
1489 dampening.) Hints suggesting alternative periods may be
1490 returned as supplemental information.";
1491 }
1493 identity result-too-big {
1494 base sn:establish-subscription-error;
1495 base sn:modify-subscription-error;
1496 base sn:subscription-suspended-reason;
1497 description
1498 "Periodic or on-change push update datatrees exceed a maximum
1499 size limit. Hints on estimated size of what was too big may
1500 be returned as supplemental information.";
1501 }
1503 identity synchronization-size {
1504 base sn:establish-subscription-error;
1505 base sn:modify-subscription-error;
1506 base resynch-subscription-error;
1507 base sn:subscription-suspended-reason;
1508 description
1509 "Synch-on-start or resynchronization datatree exceeds a maximum
1510 size limit. Hints on estimated size of what was too big may be
1511 returned as supplemental information.";
1512 }
1514 identity unchanging-selection {
1515 base sn:establish-subscription-error;
1516 base sn:modify-subscription-error;
1517 base sn:subscription-terminated-reason;
1518 description
1519 "Selection filter is unlikely to ever select datatree nodes.
1521 This means that based on the subscriber's current access
1522 rights, the publisher recognizes that the selection filter is
1523 unlikely to ever select datatree nodes which change. Examples
1524 for this might be that node or subtree doesn't exist, read
1525 access is not permitted for a receiver, or static objects that
1526 only change at reboot have been chosen.";
1527 }
1529 /*
1530 * TYPE DEFINITIONS
1531 */
1533 typedef change-type {
1534 type enumeration {
1535 enum create {
1536 description
1537 "A change that refers to the creation of a new data node.";
1538 }
1539 enum delete {
1540 description
1541 "A change that refers to the deletion of a data node.";
1542 }
1543 enum insert {
1544 description
1545 "A change that refers to the insertion of a new
1546 user-ordered data node.";
1547 }
1548 enum merge {
1549 description
1550 "A change that refers to a merging of a new value with a
1551 target data node.";
1552 }
1553 enum move {
1554 description
1555 "A change that refers to a reordering of the target data
1556 node";
1557 }
1558 enum replace {
1559 description
1560 "A change that refers to a replacement of the target data
1561 node's value.";
1562 }
1563 enum remove {
1564 description
1565 "A change that refers to the removal of a data node.";
1566 }
1567 }
1568 description
1569 "Specifies different types of datastore changes.";
1570 reference
1571 "RFC 8072 section 2.5, with a delta that it is valid for a
1572 receiver to process an update record which performs a create
1573 operation on a datastore node the receiver believes exists, or
1574 to process a delete on a datastore node the receiver believes
1575 is missing.";
1576 }
1578 typedef selection-filter-ref {
1579 type leafref {
1580 path "/sn:filters/yp:selection-filter/yp:filter-id";
1581 }
1582 description
1583 "This type is used to reference a selection filter.";
1584 }
1586 /*
1587 * GROUP DEFINITIONS
1588 */
1590 grouping datastore-criteria {
1591 description
1592 "A grouping to define criteria for which selected objects from
1593 a targeted datastore should be included in push updates.";
1594 leaf datastore {
1595 type identityref {
1596 base ds:datastore;
1597 }
1598 mandatory true;
1599 description
1600 "Datastore from which to retrieve data.";
1601 }
1602 uses selection-filter-objects;
1603 }
1605 grouping selection-filter-types {
1606 description
1607 "This grouping defines the types of selectors for objects from a
1608 datastore.";
1609 choice filter-spec {
1610 description
1611 "The content filter specification for this request.";
1612 anydata datastore-subtree-filter {
1613 if-feature "sn:subtree";
1614 description
1615 "This parameter identifies the portions of the
1616 target datastore to retrieve.";
1618 }
1619 leaf datastore-xpath-filter {
1620 if-feature "sn:xpath";
1621 type yang:xpath1.0;
1622 description
1623 "This parameter contains an XPath expression identifying the
1624 portions of the target datastore to retrieve.
1626 If the expression returns a node-set, all nodes in the
1627 node-set are selected by the filter. Otherwise, if the
1628 expression does not return a node-set, the filter
1629 doesn't select any nodes.
1631 The expression is evaluated in the following XPath context:
1633 o The set of namespace declarations are those in scope on
1634 the 'datastore-xpath-filter' leaf element.
1636 o The set of variable bindings is empty.
1638 o The function library is the core function library, and
1639 the XPath functions defined in section 10 in RFC 7950.
1641 o The context node is the root node of the target
1642 datastore.";
1643 }
1644 }
1645 }
1647 grouping selection-filter-objects {
1648 description
1649 "This grouping defines a selector for objects from a
1650 datastore.";
1651 choice selection-filter {
1652 description
1653 "The source of the selection filter applied to the
1654 subscription. This will come either referenced from a
1655 global list, or be provided within the subscription
1656 itself.";
1657 case by-reference {
1658 description
1659 "Incorporate a filter that has been configured separately.";
1660 leaf selection-filter-ref {
1661 type selection-filter-ref;
1662 mandatory true;
1663 description
1664 "References an existing selection filter which is to be
1665 applied to the subscription.";
1667 }
1668 }
1669 case within-subscription {
1670 description
1671 "Local definition allows a filter to have the same lifecycle
1672 as the subscription.";
1673 uses selection-filter-types;
1674 }
1675 }
1676 }
1678 grouping update-policy-modifiable {
1679 description
1680 "This grouping describes the datastore specific subscription
1681 conditions that can be changed during the lifetime of the
1682 subscription.";
1683 choice update-trigger {
1684 description
1685 "Defines necessary conditions for sending an event record to
1686 the subscriber.";
1687 case periodic {
1688 container periodic {
1689 presence "indicates an periodic subscription";
1690 description
1691 "The publisher is requested to notify periodically the
1692 current values of the datastore as defined by the
1693 selection filter.";
1694 leaf period {
1695 type yang:timeticks;
1696 mandatory true;
1697 description
1698 "Duration of time which should occur between periodic
1699 push updates.";
1700 }
1701 leaf anchor-time {
1702 type yang:date-and-time;
1703 description
1704 "Designates a timestamp before or after which a series
1705 of periodic push updates are determined. The next
1706 update will take place at a whole multiple interval
1707 from the anchor time. For example, for an anchor time
1708 is set for the top of a particular minute and a period
1709 interval of a minute, updates will be sent at the top
1710 of every minute this subscription is active.";
1711 }
1712 }
1713 }
1714 case on-change {
1715 if-feature "on-change";
1716 container on-change {
1717 presence "indicates an on-change subscription";
1718 description
1719 "The publisher is requested to notify changes in values in
1720 the datastore subset as defined by a selection filter.";
1721 leaf dampening-period {
1722 type yang:timeticks;
1723 default "0";
1724 description
1725 "Specifies the minimum interval between the assembly of
1726 successive update records for a single receiver of a
1727 subscription. Whenever subscribed objects change, and a
1728 dampening period interval (which may be zero) has
1729 elapsed since the previous update record creation for a
1730 receiver, then any subscribed objects and properties
1731 which have changed since the previous update record
1732 will have their current values marshalled and placed
1733 into a new update record.";
1734 }
1735 }
1736 }
1737 }
1738 }
1740 grouping update-policy {
1741 description
1742 "This grouping describes the datastore specific subscription
1743 conditions of a subscription.";
1744 uses update-policy-modifiable {
1745 augment "update-trigger/on-change/on-change" {
1746 description
1747 "Includes objects not modifiable once subscription is
1748 established.";
1749 leaf no-synch-on-start {
1750 type empty;
1751 description
1752 "The presence of this object restricts an on-change
1753 subscription from sending push-update notifications.
1754 When present, pushing a full selection per the terms of
1755 the selection filter MUST NOT be done for this
1756 subscription. Only updates about changes, i.e. only
1757 push-change-update notifications are sent. When absent
1758 (default behavior), in order to facilitate a receiver's
1759 synchronization, a full update is sent when the
1760 subscription starts using a push-update notification.
1761 After that, push-change-update notifications are
1762 exclusively sent unless the publisher chooses to resynch
1763 the subscription via a new push-update notification.";
1764 }
1765 leaf-list excluded-change {
1766 type change-type;
1767 description
1768 "Use to restrict which changes trigger an update.
1769 For example, if modify is excluded, only creation and
1770 deletion of objects is reported.";
1771 }
1772 }
1773 }
1774 }
1776 grouping hints {
1777 description
1778 "Parameters associated with some error for a subscription made
1779 upon a datastore.";
1780 leaf period-hint {
1781 type yang:timeticks;
1782 description
1783 "Returned when the requested time period is too short. This
1784 hint can assert a viable period for either a periodic push
1785 cadence or an on-change dampening interval.";
1786 }
1787 leaf filter-failure-hint {
1788 type string;
1789 description
1790 "Information describing where and/or why a provided filter
1791 was unsupportable for a subscription.";
1792 }
1793 leaf object-count-estimate {
1794 type uint32;
1795 description
1796 "If there are too many objects which could potentially be
1797 returned by the selection filter, this identifies the
1798 estimate of the number of objects which the filter would
1799 potentially pass.";
1800 }
1801 leaf object-count-limit {
1802 type uint32;
1803 description
1804 "If there are too many objects which could be returned by the
1805 selection filter, this identifies the upper limit of the
1806 publisher's ability to service for this subscription.";
1807 }
1808 leaf kilobytes-estimate {
1809 type uint32;
1810 description
1811 "If the returned information could be beyond the capacity of
1812 the publisher, this would identify the data size which could
1813 result from this selection filter.";
1814 }
1815 leaf kilobytes-limit {
1816 type uint32;
1817 description
1818 "If the returned information would be beyond the capacity of
1819 the publisher, this identifies the upper limit of the
1820 publisher's ability to service for this subscription.";
1821 }
1822 }
1824 /*
1825 * RPCs
1826 */
1828 rpc resynch-subscription {
1829 if-feature "on-change";
1830 description
1831 "This RPC allows a subscriber of an active on-change
1832 subscription to request a full push of objects.
1833 A successful invocation results in a push-update of all
1834 datastore objects that the subscriber is permitted to access.
1835 This RPC can only be invoked on the same session on which the
1836 subscription was established (using an establish-subscription
1837 RPC). In case of an error, a resynch-subscription-error is
1838 sent as part of an error response.";
1839 input {
1840 leaf identifier {
1841 type sn:subscription-id;
1842 mandatory true;
1843 description
1844 "Identifier of the subscription that is to be resynched.";
1845 }
1846 }
1847 }
1848 rc:yang-data resynch-subscription-error {
1849 container resynch-subscription-error {
1850 description
1851 "If a 'resynch-subscription' RPC fails, the subscription is
1852 not resynched and the RPC error response MUST indicate the
1853 reason for this failure. This yang-data MAY be inserted as
1854 structured data within a subscription's RPC error response
1855 to indicate the failure reason.";
1856 leaf reason {
1857 type identityref {
1858 base resynch-subscription-error;
1860 }
1861 mandatory true;
1862 description
1863 "Indicates the reason why the publisher has declined a
1864 request for subscription resynchronization.";
1865 }
1866 uses hints;
1867 }
1868 }
1870 augment "/sn:establish-subscription/sn:input" {
1871 description
1872 "This augmentation adds additional subscription parameters that
1873 apply specifically to datastore updates to RPC input.";
1874 uses update-policy;
1875 }
1876 augment "/sn:establish-subscription/sn:input/sn:target" {
1877 description
1878 "This augmentation adds the datastore as a valid target
1879 for the subscription to RPC input.";
1880 case datastore {
1881 description
1882 "Information specifying the parameters of an request for a
1883 datastore subscription.";
1884 uses datastore-criteria;
1885 }
1886 }
1887 rc:yang-data establish-subscription-datastore-error-info {
1888 container establish-subscription-datastore-error-info {
1889 description
1890 "If any 'establish-subscription' RPC parameters are
1891 unsupportable against the datastore, a subscription is not
1892 created and the RPC error response MUST indicate the reason
1893 why the subscription failed to be created. This yang-data MAY
1894 be inserted as structured data within a subscription's RPC
1895 error response to indicate the failure reason. This
1896 yang-data MUST be inserted if hints are to be provided back
1897 to the subscriber.";
1898 leaf reason {
1899 type identityref {
1900 base sn:establish-subscription-error;
1901 }
1902 description
1903 "Indicates the reason why the subscription has failed to
1904 be created to a targeted datastore.";
1905 }
1906 uses hints;
1907 }
1909 }
1911 augment "/sn:modify-subscription/sn:input" {
1912 description
1913 "This augmentation adds additional subscription parameters
1914 specific to datastore updates.";
1915 uses update-policy-modifiable;
1916 }
1917 augment "/sn:modify-subscription/sn:input/sn:target" {
1918 description
1919 "This augmentation adds the datastore as a valid target
1920 for the subscription to RPC input.";
1921 case datastore {
1922 description
1923 "Information specifying the parameters of an request for a
1924 datastore subscription.";
1925 uses selection-filter-objects;
1926 }
1927 }
1928 rc:yang-data modify-subscription-datastore-error-info {
1929 container modify-subscription-datastore-error-info {
1930 description
1931 "This yang-data MAY be provided as part of a subscription's RPC
1932 error response when there is a failure of a
1933 'modify-subscription' RPC which has been made against a
1934 datastore. This yang-data MUST be used if hints are to be
1935 provides back to the subscriber.";
1936 leaf reason {
1937 type identityref {
1938 base sn:modify-subscription-error;
1939 }
1940 description
1941 "Indicates the reason why the subscription has failed to
1942 be modified.";
1943 }
1944 uses hints;
1945 }
1946 }
1948 /*
1949 * NOTIFICATIONS
1950 */
1952 notification push-update {
1953 description
1954 "This notification contains a push update, containing data
1955 subscribed to via a subscription. This notification is sent for
1956 periodic updates, for a periodic subscription. It can also be
1957 used for synchronization updates of an on-change subscription.
1958 This notification shall only be sent to receivers of a
1959 subscription. It does not constitute a general-purpose
1960 notification that would be subscribable as part of the NETCONF
1961 event stream by any receiver.";
1962 leaf subscription-id {
1963 type sn:subscription-id;
1964 description
1965 "This references the subscription which drove the notification
1966 to be sent.";
1967 }
1968 leaf incomplete-update {
1969 type empty;
1970 description
1971 "This is a flag which indicates that not all datastore nodes
1972 subscribed to are included with this update. In other words,
1973 the publisher has failed to fulfill its full subscription
1974 obligations, and despite its best efforts is providing an
1975 incomplete set of objects.";
1976 }
1977 anydata datastore-contents {
1978 description
1979 "This contains the updated data. It constitutes a snapshot
1980 at the time-of-update of the set of data that has been
1981 subscribed to. The snapshot corresponds to the same
1982 snapshot that would be returned in a corresponding get
1983 operation with the same selection filter parameters
1984 applied.";
1985 }
1986 }
1987 notification push-change-update {
1988 if-feature "on-change";
1989 description
1990 "This notification contains an on-change push update. This
1991 notification shall only be sent to the receivers of a
1992 subscription; it does not constitute a general-purpose
1993 notification.";
1994 leaf subscription-id {
1995 type sn:subscription-id;
1996 description
1997 "This references the subscription which drove the notification
1998 to be sent.";
1999 }
2000 leaf incomplete-update {
2001 type empty;
2002 description
2003 "The presence of this object indicates not all changes which
2004 have occurred since the last update are included with this
2005 update. In other words, the publisher has failed to
2006 fulfill its full subscription obligations, for example in
2007 cases where it was not able to keep up with a change burst.";
2008 }
2009 anydata datastore-changes {
2010 description
2011 "This contains the set of datastore changes of the
2012 target datastore starting at the time of the
2013 previous update, per the terms of the subscription.
2014 The datastore changes are encoded per RFC 8027
2015 (YANG Patch).";
2016 }
2017 }
2018 augment "/sn:subscription-started" {
2019 description
2020 "This augmentation adds datastore-specific objects to
2021 the notification that a subscription has started.";
2022 uses update-policy;
2023 }
2024 augment "/sn:subscription-started/sn:target" {
2025 description
2026 "This augmentation allows the datastore to be included as part
2027 of the notification that a subscription has started.";
2028 case datastore {
2029 uses datastore-criteria {
2030 refine "selection-filter/within-subscription" {
2031 description
2032 "Specifies the selection filter and where it originated
2033 from. If the 'selection-filter-ref' is populated,
2034 the filter within the subscription came from the 'filters'
2035 container. Otherwise it is populated in-line as part of
2036 the subscription itself.";
2037 }
2038 }
2039 }
2040 }
2041 augment "/sn:subscription-modified" {
2042 description
2043 "This augmentation adds datastore-specific objects to
2044 the notification that a subscription has been modified.";
2045 uses update-policy;
2046 }
2047 augment "/sn:subscription-modified/sn:target" {
2048 description
2049 "This augmentation allows the datastore to be included as part
2050 of the notification that a subscription has been modified.";
2051 case datastore {
2052 uses datastore-criteria {
2053 refine "selection-filter/within-subscription" {
2054 description
2055 "Specifies where the selection filter, and where it came
2056 from within the subscription and then populated within
2057 this notification. If the 'selection-filter-ref' is
2058 populated, the filter within the subscription came from
2059 the 'filters' container. Otherwise it is populated
2060 in-line as part of the subscription itself.";
2061 }
2062 }
2063 }
2064 }
2066 /*
2067 * DATA NODES
2068 */
2070 augment "/sn:filters" {
2071 description
2072 "This augmentation allows the datastore to be included as part
2073 of the selection filtering criteria for a subscription.";
2074 list selection-filter {
2075 key "filter-id";
2076 description
2077 "A list of pre-configured filters that can be applied
2078 to datastore subscriptions.";
2079 leaf filter-id {
2080 type string;
2081 description
2082 "An identifier to differentiate between selection filters.";
2083 }
2084 uses selection-filter-types;
2085 }
2086 }
2087 augment "/sn:subscriptions/sn:subscription" {
2088 description
2089 "This augmentation adds many datastore specific objects to a
2090 subscription.";
2091 uses update-policy;
2092 }
2093 augment "/sn:subscriptions/sn:subscription/sn:target" {
2094 description
2095 "This augmentation allows the datastore to be included as part
2096 of the selection filtering criteria for a subscription.";
2097 case datastore {
2098 uses datastore-criteria;
2099 }
2100 }
2102 }
2104
2106 6. IANA Considerations
2108 This document registers the following namespace URI in the "IETF XML
2109 Registry" [RFC3688]:
2111 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push
2112 Registrant Contact: The IESG.
2113 XML: N/A; the requested URI is an XML namespace.
2115 This document registers the following YANG module in the "YANG Module
2116 Names" registry [RFC6020]:
2118 Name: ietf-yang-push
2119 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push
2120 Prefix: yp
2121 Reference: draft-ietf-netconf-yang-push-16.txt (RFC form)
2123 7. Security Considerations
2125 The YANG module specified in this document defines a schema for data
2126 that is designed to be accessed via network management protocols such
2127 as NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer
2128 is the secure transport layer, and the mandatory-to-implement secure
2129 transport is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer
2130 is HTTPS, and the mandatory-to-implement secure transport is TLS
2131 [RFC5246].
2133 The NETCONF access control model [RFC8341] provides the means to
2134 restrict access for particular NETCONF or RESTCONF users to a
2135 preconfigured subset of all available NETCONF or RESTCONF protocol
2136 operations and content.
2138 There are a number of data nodes defined in this YANG module that are
2139 writable/creatable/deletable (i.e., config true, which is the
2140 default). These data nodes may be considered sensitive or vulnerable
2141 in some network environments. Write operations (e.g., edit-config)
2142 to these data nodes without proper protection can have a negative
2143 effect on network operations. These are the subtrees and data nodes
2144 and their sensitivity/vulnerability:
2146 First, it should be noted that the YANG module augments the YANG
2147 module from [I-D.draft-ietf-netconf-subscribed-notifications].
2148 All security considerations that are listed there are relevant
2149 also for datastore subscriptions. In the following, we focus on
2150 the data nodes that are newly introduced here.
2152 Subtree "selection-filter" under container "filters": This subtree
2153 allows to specify which objects or subtrees to include in a
2154 datastore subscription. An attacker could attempt to modify the
2155 filter. For example, the filter might be modified to result in
2156 very few objects being filtered in order to attempt to overwhelm
2157 the receiver. Alternatively, the filter might be modified to
2158 result in certain objects to be excluded from updates, in order to
2159 have certain changes go unnoticed.
2161 Subtree "datastore" in choice "target" in list "subscription":
2162 Analogous to "selection filter", an attacker might attempt to
2163 modify the objects being filtered in order to overwhelm a receiver
2164 with a larger volume of datastore node updates than expected, or
2165 to have certain changes go unnoticed.
2167 Choice "update-trigger" in list "subscription": By modifying the
2168 update trigger, an attacker might alter the updates that are being
2169 sent in order to confuse a receiver, to withhold certain updates
2170 to be sent to the receiver, and/or to overwhelm a receiver. For
2171 example, an attacker might modify the period with which updates
2172 are reported for a periodic subscription, or it might modify the
2173 dampening period for an on-change subscription, resulting in
2174 greater delay of successive updates (potentially affecting
2175 responsiveness of applications that depend on the updates) or in a
2176 high volume of updates (to exhaust receiver resources).
2178 RPC "resynch-subscription": This RPC allows a subscriber of an on-
2179 change subscription to request a full push of objects in the
2180 subscription's scope. This can result in a large volume of data.
2181 An attacker could attempt to use this RPC to exhaust resources on
2182 the server to generate the data, and attempt to overwhelm a
2183 receiver with the resulting data volume.
2185 8. Acknowledgments
2187 For their valuable comments, discussions, and feedback, we wish to
2188 acknowledge Tim Jenkins, Kent Watsen, Susan Hares, Yang Geng, Peipei
2189 Guo, Michael Scharf, Martin Bjorklund, and Guangying Zheng.
2191 9. References
2192 9.1. Normative References
2194 [I-D.draft-ietf-netconf-subscribed-notifications]
2195 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A.,
2196 and E. Nilsen-Nygaard, "Custom Subscription to Event
2197 Streams", draft-ietf-netconf-subscribed-notifications-12
2198 (work in progress), April 2018.
2200 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
2201 DOI 10.17487/RFC3688, January 2004,
2202 .
2204 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
2205 the Network Configuration Protocol (NETCONF)", RFC 6020,
2206 DOI 10.17487/RFC6020, October 2010,
2207 .
2209 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF)
2210 Base Notifications", RFC 6470, DOI 10.17487/RFC6470,
2211 February 2012, .
2213 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
2214 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016,
2215 .
2217 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
2218 RFC 7950, DOI 10.17487/RFC7950, August 2016,
2219 .
2221 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch
2222 Media Type", RFC 8072, DOI 10.17487/RFC8072, February
2223 2017, .
2225 [RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
2226 Access Control Model", STD 91, RFC 8341,
2227 DOI 10.17487/RFC8341, March 2018,
2228 .
2230 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
2231 and R. Wilton, "Network Management Datastore Architecture
2232 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
2233 .
2235 9.2. Informative References
2237 [bergstra2014]
2238 Bergstra, J. and M. Burgess, "Promise Theory, Createspace
2239 Independent Publishers, ISBN-13 9781495437779", 2014.
2241 [I-D.draft-ietf-netconf-netconf-event-notifications]
2242 Voit, E., Clemm, A., Gonzalez Prieto, A., Nilsen-Nygaard,
2243 E., and A. Tripathy, "NETCONF Support for Event
2244 Notifications", May 2018.
2246 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
2247 (TLS) Protocol Version 1.2", RFC 5246,
2248 DOI 10.17487/RFC5246, August 2008,
2249 .
2251 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
2252 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
2253 .
2255 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
2256 and A. Bierman, Ed., "Network Configuration Protocol
2257 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
2258 .
2260 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
2261 Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
2262 .
2264 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface
2265 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014,
2266 .
2268 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements
2269 for Subscription to YANG Datastores", RFC 7923,
2270 DOI 10.17487/RFC7923, June 2016,
2271 .
2273 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2274 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
2275 .
2277 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams",
2278 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
2279 .
2281 Appendix A. Appendix A: Subscription Errors
2283 A.1. RPC Failures
2285 Rejection of an RPC for any reason is indicated by via RPC error
2286 response from the publisher. Valid RPC errors returned include both
2287 existing transport layer RPC error codes, such as those seen with
2288 NETCONF in [RFC6241], as well as subscription specific errors such as
2289 those defined within the YANG model. As a result, how subscription
2290 errors are encoded within an RPC error response is transport
2291 dependent.
2293 References to specific identities within the either the subscribed-
2294 notifications YANG model or the yang-push YANG model may be returned
2295 as part of the error responses resulting from failed attempts at
2296 datastore subscription. Following are valid errors per RPC (note:
2297 throughout this section the prefix 'sn' indicates an item imported
2298 from the subscribed-notifications.yang model):
2300 establish-subscription modify-subscription
2301 ---------------------- -------------------
2302 cant-exclude sn:filter-unsupported
2303 datastore-not-subscribable sn:insufficient-resources
2304 sn:dscp-unavailable sn:no-such-subscription
2305 sn:filter-unsupported period-unsupported
2306 sn:insufficient-resources result-too-big
2307 on-change-unsupported synchronization-size
2308 on-change-synch-unsupported unchanging-selection
2309 period-unsupported
2310 result-too-big resynch-subscription
2311 synchronization-size --------------------
2312 unchanging-selection no-such-subscription-resynch
2313 synchronization-size
2315 delete-subscription kill-subscription
2316 ---------------------- -----------------
2317 sn:no-such-subscription sn:no-such-subscription
2319 There is one final set of transport independent RPC error elements
2320 included in the YANG model. These are the following four yang-data
2321 structures for failed datastore subscriptions:
2323 1. yang-data establish-subscription-error-datastore
2324 This MUST be returned if information identifying the reason for an
2325 RPC error has not been placed elsewhere within the transport
2326 portion of a failed "establish-subscription" RPC response. This
2327 MUST be sent if hints are included.
2329 2. yang-data modify-subscription-error-datastore
2330 This MUST be returned if information identifying the reason for an
2331 RPC error has not been placed elsewhere within the transport
2332 portion of a failed "modifiy-subscription" RPC response. This
2333 MUST be sent if hints are included.
2335 3. yang-data sn:delete-subscription-error
2336 This MUST be returned if information identifying the reason for an
2337 RPC error has not been placed elsewhere within the transport
2338 portion of a failed "delete-subscription" or "kill-subscription"
2339 RPC response.
2341 4. yang-data resynch-subscription-error
2342 This MUST be returned if information identifying the reason for an
2343 RPC error has not been placed elsewhere within the transport
2344 portion of a failed "resynch-subscription" RPC response.
2346 A.2. Notifications of Failure
2348 A subscription may be unexpectedly terminated or suspended
2349 independent of any RPC or configuration operation. In such cases,
2350 indications of such a failure MUST be provided. To accomplish this,
2351 the following types of error identities may be returned within the
2352 corresponding subscription state change notification:
2354 subscription-terminated subscription-suspended
2355 ----------------------- ----------------------
2356 datastore-not-subscribable sn:insufficient-resources
2357 sn:filter-unavailable period-unsupported
2358 sn:no-such-subscription result-too-big
2359 sn:suspension-timeout synchronization-size
2360 unchanging-selection
2362 Appendix B. Changes between revisions
2364 (To be removed by RFC editor prior to publication)
2366 v15 - v16
2368 o Updated security considerations.
2370 o Updated references.
2372 o Addressed comments from last call review, specifically comments
2373 received from Martin Bjorklund.
2375 v14 - v15
2377 o Minor text fixes. Includes a fix to on-change update calculation
2378 to cover churn when a object changes to and from a value during a
2379 dampening period.
2381 v13 - v14
2383 o Minor text fixes.
2385 v12 - v13
2387 o Hint negotiation models now show error examples.
2389 o yang-data structures for rpc errors.
2391 v11 - v12
2393 o Included Martin's review clarifications.
2395 o QoS moved to subscribed-notifications
2397 o time-of-update removed as it is redundant with RFC5277's
2398 eventTime, and other times from notification-messages.
2400 o Error model moved to match existing implementations
2402 o On-change notifiable removed, how to do this is implementation
2403 specific.
2405 o NMDA model supported. Non NMDA version at https://github.com/
2406 netconf-wg/yang-push/
2408 v10 - v11
2410 o Promise model reference added.
2412 o Error added for no-such-datastore
2414 o Inherited changes from subscribed notifications (such as optional
2415 feature definitions).
2417 o scrubbed the examples for proper encodings
2418 v09 - v10
2420 o Returned to the explicit filter subtyping of v00-v05
2422 o identityref to ds:datastore made explicit
2424 o Returned ability to modify a selection filter via RPC.
2426 v08 - v09
2428 o Minor tweaks cleaning up text, removing appendicies, and making
2429 reference to revised-datastores.
2431 o Subscription-id optional in push updates, except when encoded in
2432 RFC5277, Section 4 one-way notification.
2434 o Finished adding the text descibing the resynch subscription RPC.
2436 o Removed relationships to other drafts and future technology
2437 appendicies as this work is being explored elsewhere.
2439 o Deferred the multi-line card issue to new drafts
2441 o Simplified the NACM interactions.
2443 v07 - v08
2445 o Updated YANG models with minor tweaks to accommodate changes of
2446 ietf-subscribed-notifications.
2448 v06 - v07
2450 o Clarifying text tweaks.
2452 o Clarification that filters act as selectors for subscribed
2453 datastore nodes; support for value filters not included but
2454 possible as a future extension
2456 o Filters don't have to be matched to existing YANG objects
2458 v05 - v06
2460 o Security considerations updated.
2462 o Base YANG model in [subscribe] updated as part of move to
2463 identities, YANG augmentations in this doc matched up
2465 o Terms refined and text updates throughout
2466 o Appendix talking about relationship to other drafts added.
2468 o Datastore replaces stream
2470 o Definitions of filters improved
2472 v04 to v05
2474 o Referenced based subscription document changed to Subscribed
2475 Notifications from 5277bis.
2477 o Getting operational data from filters
2479 o Extension notifiable-on-change added
2481 o New appendix on potential futures. Moved text into there from
2482 several drafts.
2484 o Subscription configuration section now just includes changed
2485 parameters from Subscribed Notifications
2487 o Subscription monitoring moved into Subscribed Notifications
2489 o New error and hint mechanisms included in text and in the yang
2490 model.
2492 o Updated examples based on the error definitions
2494 o Groupings updated for consistency
2496 o Text updates throughout
2498 v03 to v04
2500 o Updates-not-sent flag added
2502 o Not notifiable extension added
2504 o Dampening period is for whole subscription, not single objects
2506 o Moved start/stop into rfc5277bis
2508 o Client and Server changed to subscriber, publisher, and receiver
2510 o Anchor time for periodic
2512 o Message format for synchronization (i.e. synch-on-start)
2513 o Material moved into 5277bis
2515 o QoS parameters supported, by not allowed to be modified by RPC
2517 o Text updates throughout
2519 Authors' Addresses
2521 Alexander Clemm
2522 Huawei
2524 Email: ludwig@clemm.org
2526 Eric Voit
2527 Cisco Systems
2529 Email: evoit@cisco.com
2531 Alberto Gonzalez Prieto
2532 VMware
2534 Email: agonzalezpri@vmware.com
2536 Ambika Prasad Tripathy
2537 Cisco Systems
2539 Email: ambtripa@cisco.com
2541 Einar Nilsen-Nygaard
2542 Cisco Systems
2544 Email: einarnn@cisco.com
2546 Andy Bierman
2547 YumaWorks
2549 Email: andy@yumaworks.com
2551 Balazs Lengyel
2552 Ericsson
2554 Email: balazs.lengyel@ericsson.com