idnits 2.17.1
draft-ietf-netconf-yang-push-14.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 :
----------------------------------------------------------------------------
** 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 223: '...hat, a dampening period MAY be used to...'
RFC 2119 keyword, line 250: '...cription request SHOULD be declined if...'
RFC 2119 keyword, line 285: '... publisher MAY accept an on-change s...'
RFC 2119 keyword, line 297: '...ely, a publisher MAY decide to simply ...'
RFC 2119 keyword, line 300: '...on, the subscription MAY be suspended....'
(64 more instances...)
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Line 867 has weird spacing: '...ro time yan...'
== Line 926 has weird spacing: '...ntifier sub...'
== Line 966 has weird spacing: '...ntifier sub...'
== Line 969 has weird spacing: '...ntifier sub...'
== Line 982 has weird spacing: '...ntifier sub...'
== (8 more instances...)
-- The exact meaning of the all-uppercase expression 'MAY NOT' is not
defined in RFC 2119. If it is intended as a requirements expression, it
should be rewritten using one of the combinations defined in RFC 2119;
otherwise it should not be all-uppercase.
== The expression 'MAY NOT', while looking like RFC 2119 requirements text,
is not defined in RFC 2119, and should not be used. Consider using 'MUST
NOT' instead (if that is what you mean).
Found 'MAY NOT' in this paragraph:
Update records for a single subscription MAY NOT be resequenced
prior to transport.
== The document seems to contain a disclaimer for pre-RFC5378 work, but was
first submitted on or after 10 November 2008. The disclaimer is usually
necessary only for documents that revise or obsolete older RFCs, and that
take significant amounts of text from those RFCs. If you can contact all
authors of the source material and they are willing to grant the BCP78
rights to the IETF Trust, you can and should remove the disclaimer.
Otherwise, the disclaimer is needed and you can ignore this comment.
(See the Legal Provisions document at
https://trustee.ietf.org/license-info for more information.)
-- The document date (February 09, 2018) is 2239 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-06
== Outdated reference: A later version (-10) exists of
draft-ietf-netmod-revised-datastores-04
== Outdated reference: A later version (-09) exists of
draft-ietf-netconf-rfc6536bis-05
-- Possible downref: Normative reference to a draft: ref. 'RFC6536bis'
** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525)
-- Obsolete informational reference (is this intentional?): RFC 7223
(Obsoleted by RFC 8343)
Summary: 2 errors (**), 0 flaws (~~), 12 warnings (==), 4 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: August 13, 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 February 09, 2018
17 YANG Datastore Subscription
18 draft-ietf-netconf-yang-push-14
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 objects enables new capabilities based
26 on the remote mirroring of configuration and operational state.
28 Status of This Memo
30 This Internet-Draft is submitted in full conformance with the
31 provisions of BCP 78 and BCP 79.
33 Internet-Drafts are working documents of the Internet Engineering
34 Task Force (IETF). Note that other groups may also distribute
35 working documents as Internet-Drafts. The list of current Internet-
36 Drafts is at https://datatracker.ietf.org/drafts/current/.
38 Internet-Drafts are draft documents valid for a maximum of six months
39 and may be updated, replaced, or obsoleted by other documents at any
40 time. It is inappropriate to use Internet-Drafts as reference
41 material or to cite them other than as "work in progress."
43 This Internet-Draft will expire on August 13, 2018.
45 Copyright Notice
47 Copyright (c) 2018 IETF Trust and the persons identified as the
48 document authors. All rights reserved.
50 This document is subject to BCP 78 and the IETF Trust's Legal
51 Provisions Relating to IETF Documents
52 (https://trustee.ietf.org/license-info) in effect on the date of
53 publication of this document. Please review these documents
54 carefully, as they describe your rights and restrictions with respect
55 to this document. Code Components extracted from this document must
56 include Simplified BSD License text as described in Section 4.e of
57 the Trust Legal Provisions and are provided without warranty as
58 described in the Simplified BSD License.
60 This document may contain material from IETF Documents or IETF
61 Contributions published or made publicly available before November
62 10, 2008. The person(s) controlling the copyright in some of this
63 material may not have granted the IETF Trust the right to allow
64 modifications of such material outside the IETF Standards Process.
65 Without obtaining an adequate license from the person(s) controlling
66 the copyright in such materials, this document may not be modified
67 outside the IETF Standards Process, and derivative works of it may
68 not be created outside the IETF Standards Process, except to format
69 it for publication as an RFC or to translate it into languages other
70 than English.
72 Table of Contents
74 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
75 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 4
76 3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 4
77 3.1. Subscription Model . . . . . . . . . . . . . . . . . . . 5
78 3.2. Negotiation of Subscription Policies . . . . . . . . . . 6
79 3.3. On-Change Considerations . . . . . . . . . . . . . . . . 6
80 3.4. Promise-Theory Considerations . . . . . . . . . . . . . . 8
81 3.5. Data Encodings . . . . . . . . . . . . . . . . . . . . . 8
82 3.6. Datastore Selection . . . . . . . . . . . . . . . . . . . 9
83 3.7. Streaming Updates . . . . . . . . . . . . . . . . . . . . 10
84 3.8. Subscription Management . . . . . . . . . . . . . . . . . 12
85 3.9. Receiver Authorization . . . . . . . . . . . . . . . . . 14
86 3.10. On-change Notifiable YANG objects . . . . . . . . . . . . 16
87 3.11. Other Considerations . . . . . . . . . . . . . . . . . . 16
88 4. A YANG data model for management of datastore push
89 subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 17
90 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 17
91 4.2. Subscription configuration . . . . . . . . . . . . . . . 25
92 4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 26
93 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 27
94 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 32
95 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48
96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 49
97 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 49
98 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 49
99 9.1. Normative References . . . . . . . . . . . . . . . . . . 49
100 9.2. Informative References . . . . . . . . . . . . . . . . . 50
101 Appendix A. Appendix A: Subscription Errors . . . . . . . . . . 51
102 A.1. RPC Failures . . . . . . . . . . . . . . . . . . . . . . 51
103 A.2. Notifications of Failure . . . . . . . . . . . . . . . . 52
104 Appendix B. Changes between revisions . . . . . . . . . . . . . 52
105 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55
107 1. Introduction
109 Traditional approaches to remote visibility have been built on
110 polling. With polling, data is periodically requested and retrieved
111 by a client from a server to stay up-to-date. However, there are
112 issues associated with polling-based management:
114 o Polling incurs significant latency. This latency prohibits many
115 application types.
117 o Polling cycles may be missed, requests may be delayed or get lost,
118 often when the network is under stress and the need for the data
119 is the greatest.
121 o Polling requests may undergo slight fluctuations, resulting in
122 intervals of different lengths. The resulting data is difficult
123 to calibrate and compare.
125 o For applications that monitor for changes, many remote polling
126 cycles place ultimately fruitless load on the network, devices,
127 and applications.
129 A more effective alternative to polling is for an application to
130 receive automatic and continuous updates from a targeted subset of a
131 datastore. Accordingly, there is a need for a service that allows
132 applications to subscribe to updates from a datastore and that
133 enables the publisher to push and in effect stream those updates.
134 The requirements for such a service have been documented in
135 [RFC7923].
137 This document defines a corresponding solution that is built on top
138 of "Custom Subscription to Event Streams"
139 [I-D.draft-ietf-netconf-subscribed-notifications]. Supplementing
140 that work are YANG data model augmentations, extended RPCs, and new
141 datastore specific update notifications. Transport options for
142 [I-D.draft-ietf-netconf-subscribed-notifications] will work
143 seamlessly with this solution.
145 2. Definitions and Acronyms
147 The terms below supplement those defined in
148 [I-D.draft-ietf-netconf-subscribed-notifications]. In addition, the
149 term "datastore" is defined in
150 [I-D.draft-ietf-netmod-revised-datastores].
152 Datastore node: An instance of management information in a datastore.
153 Also known as "object".
155 Datastore node update: A data item containing the current value/
156 property of a datastore node at the time the datastore node update
157 was created.
159 Datastore subtree: An instantiated datastore node and the datastore
160 nodes that are hierarchically contained within it.
162 Update record: A representation datastore node update(s) resulting
163 from the application of a selection filter for a subscription. An
164 update record will include the value/property of one or more
165 datastore nodes at a point in time. It may contain the update type
166 for each datastore node (e.g., add, change, delete). Also included
167 may be metadata/headers such as a subscription identifier.
169 Selection filter: Evaluation and/or selection criteria, which may be
170 applied against a targeted set of objects.
172 Update trigger: A mechanism that determines when an update record
173 needs to be generated.
175 YANG-Push: The subscription and push mechanism for datastore updates
176 that is specified in this document.
178 3. Solution Overview
180 This document specifies a solution for a push update subscription
181 service. This solution supports dynamic as well as configured
182 subscriptions to information updates from datastores. Subscriptions
183 specify when notification messages should be sent and what data to
184 include in update records. YANG objects are subsequently pushed from
185 the publisher to the receiver per the terms of the subscription.
187 3.1. Subscription Model
189 YANG-push subscriptions are defined using a data model that is itself
190 defined in YANG. This model enhances the subscription model defined
191 in [I-D.draft-ietf-netconf-subscribed-notifications] with
192 capabilities that allow subscribers to subscribe to datastore node
193 updates, specifically to specify the triggers defining when to
194 generate update records as well as what to include in an update
195 record. Key enhancements include:
197 o Specification of selection filters which identify targeted YANG
198 datastore nodes and/or subtrees within a datastore for which
199 updates are to be pushed.
201 o An encoding (using anydata) for the contents of periodic and on-
202 change push updates.
204 o Specification of update policies contain conditions which trigger
205 the generation and pushing of new update records. There are two
206 types of triggers for subscriptions: periodic and on-change.
208 * For periodic subscriptions, the trigger is specified by two
209 parameters that define when updates are to be pushed. These
210 parameters are the period interval with which to report
211 updates, and an anchor time which can be used to calculate at
212 which point in time updates need to be assembled and sent.
214 * For on-change subscriptions, a trigger occurs whenever a change
215 in the subscribed information is detected. Included are
216 additional parameters such as:
218 + Dampening period: In an on-change subscription, detected
219 object changes should be sent as quickly as possible.
220 However it may be undesirable to send a rapid series of
221 object changes. Such behavior has the potential to exhaust
222 of resources in the publisher or receiver. In order to
223 protect against that, a dampening period MAY be used to
224 specify the interval which must pass before successive
225 update records for the same subscription are generated for a
226 receiver. The dampening period collectively applies to the
227 set of all datastore nodes selected by a single subscription
228 and sent to a single receiver. This means that when there
229 is a change to one or more subscribed objects, an update
230 record containing those objects is created either
231 immediately when no dampening period is in effect, or at the
232 end of a dampening period. If multiple changes to a single
233 object occur during a dampening period, only the value that
234 is in effect at the time the update record is created is
235 included. The dampening period goes into effect every time
236 an update record completes assembly.
238 + Change type: This parameter can be used to reduce the types
239 of datastore changes for which updates are sent (e.g., you
240 might only send when an object is created or deleted, but
241 not when an object value changes).
243 + No Synch on start: defines whether or not a complete push-
244 update of all subscribed data will be sent at the beginning
245 of a subscription. Such early synchronization establishes
246 the frame of reference for subsequent updates.
248 3.2. Negotiation of Subscription Policies
250 A dynamic subscription request SHOULD be declined if a publisher's
251 assessment is that it may be unable to provide update records meeting
252 the terms of an "establish-subscription" or "modify-subscription" rpc
253 request. In this case, a subscriber may quickly follow up with a new
254 rpc request using different parameters.
256 Random guessing at different parameters by a subscriber is to be
257 discouraged. Therefore, in order to minimize the number of
258 subscription iterations between subscriber and publisher, dynamic
259 subscription supports a simple negotiation between subscribers and
260 publishers for subscription parameters. This negotiation is in the
261 form of supplemental information which may be inserted within error
262 responses to a failed rpc request. This returned error response
263 information, when considered, should increase the likelihood of
264 success for subsequent rpc requests. Such hints include suggested
265 periodic time intervals, acceptable dampening periods, and size
266 estimates for the number or objects which would be returned from a
267 proposed selection filter. However, there are no guarantees that
268 subsequent requests which consider these hints will be accepted.
270 3.3. On-Change Considerations
272 On-change subscriptions allow subscribers to receive updates whenever
273 changes to targeted objects occur. As such, on-change subscriptions
274 are particularly effective for data that changes infrequently, yet
275 for which applications need to be quickly notified whenever a change
276 does occur with minimal delay.
278 On-change subscriptions tend to be more difficult to implement than
279 periodic subscriptions. Accordingly, on-change subscriptions may not
280 be supported by all implementations or for every object.
282 Whether or not to accept or reject on-change subscription requests
283 when the scope of the subscription contains objects for which on-
284 change is not supported is up to the publisher implementation. A
285 publisher MAY accept an on-change subscription even when the scope of
286 the subscription contains objects for which on-change is not
287 supported. In that case, updates are sent only for those objects
288 within the scope that do support on-change updates whereas other
289 objects are excluded from update records, whether or not their values
290 actually change. In order for a subscriber to determine whether
291 objects support on-change subscriptions, objects are marked
292 accordingly on a publisher. Accordingly, when subscribing, it is the
293 responsibility of the subscriber to ensure it is aware of which
294 objects support on-change and which do not. For more on how objects
295 are so marked, see Section 3.10.
297 Alternatively, a publisher MAY decide to simply reject an on-change
298 subscription in case the scope of the subscription contains objects
299 for which on-change is not supported. In case of a configured
300 subscription, the subscription MAY be suspended.
302 To avoid flooding receivers with repeated updates for subscriptions
303 containing fast-changing objects, or objects with oscillating values,
304 an on-change subscription allows for the definition of a dampening
305 period. Once an update record for a given object is generated, no
306 other updates for this particular subscription will be created until
307 the end of the dampening period. Values sent at the end of the
308 dampening period are the current values of all changed objects which
309 are current at the time the dampening period expires. Changed
310 objects include those which were deleted or newly created during that
311 dampening period. If an object has returned to its original value
312 (or even has been created and then deleted) during the dampening-
313 period, the last change will still be sent. This will indicate churn
314 is occurring on that object.
316 On-change subscriptions can be refined to let users subscribe only to
317 certain types of changes. For example, a subscriber might only want
318 object creations and deletions, but not modifications of object
319 values.
321 Putting it all together, following is the conceptual process for
322 creating an push-change-update notification:
324 1. Just before a change, or at the start of a dampening period,
325 evaluate any filtering and any access control rules. The result
326 is a set "A" of datastore nodes and subtrees.
328 2. Just after a change, or at the end of a dampening period,
329 evaluate any filtering and any (possibly new) access control
330 rules. The result is a set "B" of datastore nodes and subtrees.
332 3. Construct a YANG patch record for going from A to B. If the
333 record is non-empty, send it to the receiver.
335 Note: In cases where a subscriber wants to have separate dampening
336 periods for different objects, multiple subscriptions with different
337 objects in a selection filter can be created.
339 3.4. Promise-Theory Considerations
341 A subscription to updates from a datastore is intended to obviate the
342 need for polling. However, in order to do so, it is critical that
343 subscribers can rely on the subscription and have confidence that
344 they will indeed receive the subscribed updates without having to
345 worry updates being silently dropped. In other words, a subscription
346 constitutes a promise on the side of the publisher to provide the
347 receivers with updates per the terms of the subscription.
349 Now, there are many reasons why a publisher may at some point no
350 longer be able to fulfill the terms of the subscription, even if the
351 subscription had been entered into with good faith. For example, the
352 volume of data objects may be larger than anticipated, the interval
353 may prove too short to send full updates in rapid succession, or an
354 internal problem may prevent objects from being collected. If for
355 some reason the publisher of a subscription is not able to keep its
356 promise, receivers MUST be notified immediately and reliably. The
357 publisher MAY also suspend the subscription.
359 A publisher SHOULD reject a request for a subscription if it is
360 unlikely that the publisher will be able fulfill the terms of that
361 subscription request. In such cases, it is preferable to have a
362 subscriber request a less resource intensive subscription than to
363 deal with frequently degraded behavior.
365 3.5. Data Encodings
367 3.5.1. Periodic Subscriptions
369 In a periodic subscription, the data included as part of an update
370 corresponds to data that could have been read using a retrieval
371 operation.
373 3.5.2. On-Change Subscriptions
375 In an on-change subscription, updates need to indicate not only
376 values of changed datastore nodes but also the types of changes that
377 occurred since the last update. Therefore encoding rules for data in
378 on-change updates will generally follow YANG-patch operation as
379 specified in [RFC8072]. The YANG-patch will describe what needs to
380 be applied to the earlier state reported by the preceding update, to
381 result in the now-current state. Note that contrary to [RFC8072],
382 objects encapsulated are not restricted to configuration objects
383 only.
385 However a patch must be able to do more than just describe the delta
386 from the previous state to the current state. As per Section 3.3, it
387 must also be able to identify if transient changes have occurred on
388 an object during a dampening period. To support this, it is valid to
389 encode a YANG patch operation so that its application would result in
390 a no change between the previous and current state. This indicates
391 that some churn has occurred on the object. An example of this would
392 be a patch that does a "create" operation for a datastore node where
393 the receiver believes one already exists, or a "merge" operation
394 which replaces a previous value with the same value. Note that this
395 means that the "create" and "delete" errors described in [RFC8072]
396 section 2.5 are not errors, and are valid operations with YANG push.
398 3.6. Datastore Selection
400 A subscription must specify both the selection filters and the
401 datastore against which these selection filters will be applied.
402 This information is used to choose and subsequently push data from
403 the publisher's datastore to the receivers.
405 Only a single selection filter can be applied to a subscription at a
406 time. An rpc request proposing a new selection filter MUST remove
407 any existing filter. The following selection filter types are
408 included in the yang-push data model, and may be applied against a
409 datastore:
411 o subtree: A subtree selection filter identifies one or more
412 datastore subtrees. When specified, update records will only come
413 from the datastore nodes of selected datastore subtree(s). The
414 syntax and semantics correspond to that specified for [RFC6241]
415 section 6.
417 o xpath: An xpath selection filter is an XPath expression that
418 returns a node set. When specified, updates will only come from
419 the selected data nodes.
421 These filters are intended to be used as selectors that define which
422 objects are within the scope of a subscription. A publisher MUST
423 support at least one type of selection filter.
425 Xpath itself provides powerful filtering constructs and care must be
426 used in filter definition. As an example, consider an xpath filter
427 with a boolean result; such a result will not provide an easily
428 interpretable subset of a datastore. Beyond the boolean example, it
429 is quite possible to define an xpath filter where results are easy
430 for an application to mis-interpret. Consider an xpath filter which
431 only passes a datastore object when an interface is up. It is up to
432 the receiver to understand implications of the presence or absence of
433 objects in each update.
435 When the set of selection filtering criteria is applied for periodic
436 subscription, all selected datastore nodes to which a receiver has
437 access are provided to a receiver. If the same filtering criteria is
438 applied to an on-change subscription, only the subset of those
439 datastore nodes supporting on-change is provided. A datastore node
440 which doesn't support on-change is never sent as part of an on-change
441 subscription's "push-update" or "push-change-update".
443 3.7. Streaming Updates
445 Contrary to traditional data retrieval requests, datastore
446 subscription enables an unbounded series of update records to be
447 streamed over time. Two generic YANG notifications for update
448 records have been defined for this: "push-update" and "push-change-
449 update".
451 A "push-update" notification defines a complete, filtered update of
452 the datastore per the terms of a subscription. This type of YANG
453 notification is used for continuous updates of periodic
454 subscriptions. A "push-update" notification can also be used for the
455 on-change subscriptions in two cases. First it will be used as the
456 initial "push-update" if there is a need to synchronize the receiver
457 at the start of a new subscription. It also MAY be sent if the
458 publisher later chooses to resynch an on-change subscription. The
459 "push-update" update record contains a data snippet that contains an
460 instantiated datastore subtree with all of the subscribed contents.
461 The content of the update record is equivalent to the contents that
462 would be obtained had the same data been explicitly retrieved using
463 e.g., a NETCONF "get" operation, with the same filters applied.
465 A "push-change-update" notification is the most common type of update
466 for on-change subscriptions. The update record in this case contains
467 a data snippet that indicates the set of changes that datastore nodes
468 have undergone since the last notification message. In other words,
469 this indicates which datastore nodes have been created, deleted, or
470 have had changes to their values. In cases where multiple changes
471 have occurred and the object has not been deleted, the object's most
472 current value is reported. (In other words, for each object, only
473 one change is reported, not its entire history. Doing so would
474 defeat the purpose of the dampening period.)
476 These new "push-update" or "push-change-update" are encoded and
477 placed within notification messages, and ultimately queued for egress
478 over the specified transport.
480 The following is an example of a notification message for a
481 subscription tracking the operational status of a single Ethernet
482 port (per [RFC7223]). This notification message is encoded XML over
483 NETCONF as per [I-D.draft-ietf-netconf-netconf-event-notifications].
485
486 2017-10-25T08:00:11.22Z
487
488 1011
489
490
491
492 eth0
493 up
494
495
496
497
498
500 Figure 1: Push example
502 The following is an example of an on-change notification message for
503 the same subscription.
505
506 2017-10-25T08:22:33.44Z
507
508 89
509
510
511 1
512
513 edit1
514 merge
515 /ietf-interfaces:interfaces-state
516
517
518
519 eth0
520 down
521
522
523
524
525
526
527
528
530 Figure 2: Push example for on change
532 Of note in the above example is the 'patch-id' with a value of '1'.
533 Per [RFC8072], the 'patch-id' is an arbitrary string. With YANG
534 Push, the publisher SHOULD put into the 'patch-id' a counter starting
535 at '1' which increments with every 'push-change-update' generated for
536 a subscription. If used as a counter, this counter MUST be reset to
537 '1' anytime a resynchronization occurs (i.e., with the sending of a
538 'push-update'). Also if used as a counter, the counter MUST be reset
539 to '1' the after passing a maximum value of '99999'. Such a
540 mechanism allows easy identification of lost or out-of-sequence
541 update records.
543 3.8. Subscription Management
545 The RPCs defined within
546 [I-D.draft-ietf-netconf-subscribed-notifications] have been enhanced
547 to support datastore subscription negotiation. Included in these
548 enhancements are error codes which can indicate why a datastore
549 subscription attempt has failed.
551 A datastore subscription can be rejected for multiple reasons. This
552 includes a too large subtree request, or the inability of the
553 publisher to push update records as frequently as requested. In such
554 cases, no subscription is established. Instead, the subscription-
555 result with the failure reason is returned as part of the RPC
556 response. As part of this response, a set of alternative
557 subscription parameters MAY be returned that would likely have
558 resulted in acceptance of the subscription request. The subscriber
559 may consider these as part of future subscription attempts.
561 The specific parameters to be returned in as part of the RPC error
562 response depend on the specific transport that is used to manage the
563 subscription. In the case of NETCONF
564 [I-D.draft-ietf-netconf-netconf-event-notifications], the NETCONF RPC
565 reply MUST include an "rpc-error" element with the following
566 additional elements:
568 o "error-type" of "application".
570 o "error-tag" of "operation-failed".
572 o Optionally, an "error-severity" of "error" (this MAY but does not
573 have to be included).
575 o "error-app-tag" with the value being a string that corresponds to
576 an identity with a base of "establish-subscription-error" (for
577 error responses to an establish-subscription request), "modify-
578 subscription-error" (for error responses to a modify-subscription
579 request), "delete-subscription-error" (for error responses to a
580 delete-subscription request), "resynch-subscription-error" (for
581 error responses to resynch-subscription request), or "kill-
582 subscription-error" (for error responses to a kill-subscription
583 request), respectively.
585 o In case of error responses to an establish-subscription or modify-
586 subscription request: optionally, "error-info" containing XML-
587 encoded data with hints regarding parameter settings that might
588 lead to successful requests in the future, per yang-data
589 definitions "establish-subscription-error-datastore" (for error
590 responses to an establish-subscription request) or "modify-
591 subscription-error-datastore (for error responses to a modify-
592 subscription request), respectively. In case of an rpc error as a
593 result of a delete-subscription, or a kill-subscription, or a
594 resynch-subscription request, no error-info needs to be included,
595 as the subscription-id is the only RPC input parameter and no
596 hints regarding RPC input parameters need to be provided.
598 For instance, for the following request:
600
602
605
606 ds:operational
607
608
610 /ex:foo
611
612
613 500
614
615
616
618 Figure 3: Establish-Subscription example
620 the publisher might return:
622
624
625 application
626 operation-failed
627 period-unsupported
628
629
632
633 2000
634
635
636
637
638
640 Figure 4: Error response example
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 [RFC6536bis],
678 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 object types on-change. Reasons for
699 this might be that the value of the datastore node changes frequently
700 (e.g., [RFC7223]'s in-octets counter), that small object changes are
701 frequent and meaningless (e.g., a temperature gauge changing 0.1
702 degrees), or that the implementation is not capable of on-change
703 notification for a particular object.
705 In those cases, it will be important for client applications to have
706 a way to identify for which objects on-change notifications are
707 supported and for which ones they are not supported. Otherwise
708 client applications will have no way of knowing whether they can
709 indeed rely on their on-change subscription to provide them with the
710 change updates that they are interested in. In other words, if
711 implementations do not provide a solution and do not support
712 comprehensive on-change notifiability, clients of those
713 implementations will have no way of knowing what their on-change
714 subscription actually covers.
716 Implementations are therefore strongly advised to provide a solution
717 to this problem. It is expected that such a solution will be
718 standardized at some point in the future. In the meantime and until
719 this occurs, implementations will be expected to provide their own
720 solution.
722 3.11. Other Considerations
724 3.11.1. Robustness and reliability
726 Particularly in the case of on-change updates, it is important that
727 these updates do not get lost. Or in case the loss of an update is
728 unavoidable, it is critical that the receiver is notified
729 accordingly.
731 Update records for a single subscription MAY NOT be resequenced prior
732 to transport.
734 It is conceivable that under certain circumstances, a publisher will
735 recognize that it is unable to include within an update record the
736 full set of objects desired per the terms of a subscription. In this
737 case, the publisher MUST take one or more of the following actions.
739 o A publisher MUST set the "updates-not-sent" flag on any update
740 record which is known to be missing information.
742 o It MAY choose to suspend a subscription as per
743 [I-D.draft-ietf-netconf-subscribed-notifications].
745 o When resuming an on-change subscription, the publisher SHOULD
746 generate a complete patch from the previous update record. If
747 this is not possible and the "no-synch-on-start" option is not
748 present for the subscription, then the full datastore contents MAY
749 be sent via a "push-update" instead (effectively replacing the
750 previous contents). If neither of these are possible, then an
751 "updates-not-sent" flag MUST be included on the next "push-change-
752 update".
754 Note: It is perfectly acceptable to have a series of "push-change-
755 update" notifications (and even "push update" notifications) serially
756 queued at the transport layer awaiting transmission. It is not
757 required to merge pending update messages. I.e., the dampening
758 period applies to update record creation, not transmission.
760 3.11.2. Publisher capacity
762 It is far preferable to decline a subscription request than to accept
763 such a request when it cannot be met.
765 Whether or not a subscription can be supported will be determined by
766 a combination of several factors such as the subscription trigger
767 (on-change or periodic), the period in which to report changes (one
768 second periods will consume more resources than one hour periods),
769 the amount of data in the datastore subtree that is being subscribed
770 to, and the number and combination of other subscriptions that are
771 concurrently being serviced.
773 4. A YANG data model for management of datastore push subscriptions
775 4.1. Overview
777 The YANG data model for datastore push subscriptions is depicted in
778 the following figure. Following YANG tree convention in the
779 depiction, brackets enclose list keys, "rw" means configuration, "ro"
780 operational state data, "?" designates optional nodes, "*" designates
781 nodes that can have multiple instances. Parentheses with a name in
782 the middle enclose choice and case nodes. New schema objects defined
783 here (i.e., beyond those from
784 [I-D.draft-ietf-netconf-subscribed-notifications]) are identified
785 with "yp".
787 module: ietf-subscribed-notifications
788 +--ro streams
789 | +--ro stream* [name]
790 | +--ro name string
791 | +--ro description string
792 | +--ro replay-support? empty {replay}?
793 | +--ro replay-log-creation-time? yang:date-and-time {replay}?
794 | +--ro replay-log-aged-time? yang:date-and-time {replay}?
795 +--rw filters
796 | +--rw stream-filter* [identifier]
797 | | +--rw identifier filter-id
798 | | +--rw (filter-spec)?
799 | | +--:(stream-subtree-filter)
800 | | | +--rw stream-subtree-filter? {subtree}?
801 | | +--:(stream-xpath-filter)
802 | | +--rw stream-xpath-filter? yang:xpath1.0 {xpath}?
803 | +--rw yp:selection-filter* [identifier]
804 | +--rw yp:identifier sn:filter-id
805 | +--rw (yp:filter-spec)?
806 | +--:(yp:datastore-subtree-filter)
807 | | +--rw yp:datastore-subtree-filter?
808 | | {sn:subtree}?
809 | +--:(yp:datastore-xpath-filter)
810 | +--rw yp:datastore-xpath-filter?
811 | yang:xpath1.0 {sn:xpath}?
812 +--rw subscriptions
813 +--rw subscription* [identifier]
814 +--rw identifier subscription-id
815 +--ro configured-subscription-state? enumeration {configured}?
816 +--rw purpose? string {configured}?
817 +--rw protocol transport {configured}?
818 +--rw encoding encoding
819 +--rw (target)
820 | +--:(stream)
821 | | +--rw (stream-filter)?
822 | | | +--:(by-reference)
823 | | | | +--rw stream-filter-ref stream-filter-ref
824 | | | +--:(within-subscription)
825 | | | +--rw (filter-spec)?
826 | | | +--:(stream-subtree-filter)
827 | | | | +--rw stream-subtree-filter?
828 | | | {subtree}?
829 | | | +--:(stream-xpath-filter)
830 | | | +--rw stream-xpath-filter?
831 | | | yang:xpath1.0 {xpath}?
832 | | +--rw stream stream-ref
833 | | +--rw replay-start-time? yang:date-and-time {replay}?
834 | +--:(yp:datastore)
835 | +--rw yp:datastore identityref
836 | +--rw (yp:selected-content)?
837 | +--:(yp:by-reference)
838 | | +--rw yp:selection-filter-ref selection-filter-ref
839 | +--:(yp:within-subscription)
840 | +--rw (yp:filter-spec)?
841 | +--:(yp:datastore-subtree-filter)
842 | | +--rw yp:datastore-subtree-filter?
843 | {sn:subtree}?
844 | +--:(yp:datastore-xpath-filter)
845 | +--rw yp:datastore-xpath-filter?
846 | yang:xpath1.0 {sn:xpath}?
847 +--rw stop-time? yang:date-and-time
848 +--rw dscp? inet:dscp {qos}?
849 +--rw weighting? uint8 {qos}?
850 +--rw dependency? subscription-id {qos}?
851 +--rw (notification-message-origin)?
852 | +--:(interface-originated)
853 | | +--rw source-interface? if:interface-ref
854 | +--:(address-originated)
855 | +--rw source-vrf? ->
856 | /ni:network-instances/network-instance/name {supports-vrf}?
857 | +--rw source-address? inet:ip-address-no-zone
858 +--rw receivers
859 | +--rw receiver* [address port]
860 | +--rw address inet:host
861 | +--rw port inet:port-number
862 | +--ro pushed-notifications? yang:counter64
863 | +--ro excluded-notifications? yang:counter64
864 | +--ro status enumeration
865 | +---x reset
866 | +--ro output
867 | +--ro time yang:date-and-time
868 +--rw (yp:update-trigger)?
869 +--:(yp:periodic)
870 | +--rw yp:periodic!
871 | +--rw yp:period yang:timeticks
872 | +--rw yp:anchor-time? yang:date-and-time
873 +--:(yp:on-change) {on-change}?
874 +--rw yp:on-change!
875 +--rw yp:dampening-period? yang:timeticks
876 +--rw yp:no-synch-on-start? empty
877 +--rw yp:excluded-change* change-type
879 rpcs:
880 +---x establish-subscription
881 | +---w input
882 | | +---w encoding? encoding
883 | | +---w (target)
884 | | | +--:(stream)
885 | | | | +---w (stream-filter)?
886 | | | | | +--:(by-reference)
887 | | | | | | +---w stream-filter-ref stream-filter-ref
888 | | | | | +--:(within-subscription)
889 | | | | | +---w (filter-spec)?
890 | | | | | +--:(stream-subtree-filter)
891 | | | | | | +---w stream-subtree-filter?
892 | | | | | {subtree}?
893 | | | | | +--:(stream-xpath-filter)
894 | | | | | +---w stream-xpath-filter?
895 | | | | | yang:xpath1.0 {xpath}?
896 | | | | +---w stream stream-ref
897 | | | | +---w replay-start-time? yang:date-and-time {replay}?
898 | | | +--:(yp:datastore)
899 | | | +---w yp:datastore identityref
900 | | | +---w (yp:selected-content)?
901 | | | +--:(yp:by-reference)
902 | | | | +---w yp:selection-filter-ref selection-filter-ref
903 | | | +--:(yp:within-subscription)
904 | | | +---w (yp:filter-spec)?
905 | | | +--:(yp:datastore-subtree-filter)
906 | | | | +---w yp:datastore-subtree-filter?
907 | | | | {sn:subtree}?
908 | | | +--:(yp:datastore-xpath-filter)
909 | | | +---w yp:datastore-xpath-filter?
910 | | | yang:xpath1.0 {sn:xpath}?
911 | | +---w stop-time? yang:date-and-time
912 | | +---w dscp? inet:dscp {qos}?
913 | | +---w weighting? uint8 {qos}?
914 | | +---w dependency? subscription-id {qos}?
915 | | +---w (yp:update-trigger)?
916 | | +--:(yp:periodic)
917 | | | +---w yp:periodic!
918 | | | +---w yp:period yang:timeticks
919 | | | +---w yp:anchor-time? yang:date-and-time
920 | | +--:(yp:on-change) {on-change}?
921 | | +---w yp:on-change!
922 | | +---w yp:dampening-period? yang:timeticks
923 | | +---w yp:no-synch-on-start? empty
924 | | +---w yp:excluded-change* change-type
925 | +--ro output
926 | +--ro identifier subscription-id
927 +---x modify-subscription
928 | +---w input
929 | +---w identifier? subscription-id
930 | +---w (target)
931 | | +--:(stream)
932 | | | +---w (stream-filter)?
933 | | | +--:(by-reference)
934 | | | | +---w stream-filter-ref stream-filter-ref
935 | | | +--:(within-subscription)
936 | | | +---w (filter-spec)?
937 | | | +--:(stream-subtree-filter)
938 | | | | +---w stream-subtree-filter?
939 | | | {subtree}?
940 | | | +--:(stream-xpath-filter)
941 | | | +---w stream-xpath-filter?
942 | | | yang:xpath1.0 {xpath}?
943 | | +--:(yp:datastore)
944 | | +---w (yp:selected-content)?
945 | | +--:(yp:by-reference)
946 | | | +---w yp:selection-filter-ref selection-filter-ref
947 | | +--:(yp:within-subscription)
948 | | +---w (yp:filter-spec)?
949 | | +--:(yp:datastore-subtree-filter)
950 | | | +---w yp:datastore-subtree-filter?
951 | | | {sn:subtree}?
952 | | +--:(yp:datastore-xpath-filter)
953 | | +---w yp:datastore-xpath-filter?
954 | | yang:xpath1.0 {sn:xpath}?
955 | +---w stop-time? yang:date-and-time
956 | +---w (yp:update-trigger)?
957 | +--:(yp:periodic)
958 | | +---w yp:periodic!
959 | | +---w yp:period yang:timeticks
960 | | +---w yp:anchor-time? yang:date-and-time
961 | +--:(yp:on-change) {on-change}?
962 | +---w yp:on-change!
963 | +---w yp:dampening-period? yang:timeticks
964 +---x delete-subscription
965 | +---w input
966 | +---w identifier subscription-id
967 +---x kill-subscription
968 +---w input
969 +---w identifier subscription-id
971 yang-data (for placement into rpc error responses)
972 +-- establish-subscription-error-stream
973 | +--ro reason? identityref
974 | +--ro filter-failure-hint? string
975 | +--ro replay-start-time-hint? yang:date-and-time
976 +-- modify-subscription-error-stream
977 +--ro reason? identityref
978 +--ro filter-failure-hint? string
980 notifications:
981 +---n replay-completed {replay}?
982 | +--ro identifier subscription-id
983 +---n subscription-completed
984 | +--ro identifier subscription-id
985 +---n subscription-started {configured}?
986 | +--ro identifier subscription-id
987 | +--ro protocol transport {configured}?
988 | +--ro encoding encoding
989 | +--ro (target)
990 | | +--:(stream)
991 | | | +--ro (stream-filter)?
992 | | | | +--:(by-reference)
993 | | | | | +--ro stream-filter-ref stream-filter-ref
994 | | | | +--:(within-subscription)
995 | | | | +--ro (filter-spec)?
996 | | | | +--:(stream-subtree-filter)
997 | | | | | +--ro stream-subtree-filter?
998 | | | | | {subtree}?
999 | | | | +--:(stream-xpath-filter)
1000 | | | | +--ro stream-xpath-filter?
1001 | | | | yang:xpath1.0 {xpath}?
1002 | | | +--ro stream stream-ref
1003 | | | +--ro replay-start-time? yang:date-and-time {replay}?
1004 | | +--:(yp:datastore)
1005 | | +--ro yp:datastore identityref
1006 | | +--ro (yp:selected-content)?
1007 | | +--:(yp:by-reference)
1008 | | | +--ro yp:selection-filter-ref selection-filter-ref
1009 | | +--:(yp:within-subscription)
1010 | | +--ro (yp:filter-spec)?
1011 | | +--:(yp:datastore-subtree-filter)
1012 | | | +--ro yp:datastore-subtree-filter?
1013 | | {sn:subtree}?
1014 | | +--:(yp:datastore-xpath-filter)
1015 | | +--ro yp:datastore-xpath-filter?
1016 | | yang:xpath1.0 {sn:xpath}?
1017 | +--ro stop-time? yang:date-and-time
1018 | +--ro dscp? inet:dscp {qos}?
1019 | +--ro weighting? uint8 {qos}?
1020 | +--ro dependency? subscription-id {qos}?
1021 | +--ro (yp:update-trigger)?
1022 | +--:(yp:periodic)
1023 | | +--ro yp:periodic!
1024 | | +--ro yp:period yang:timeticks
1025 | | +--ro yp:anchor-time? yang:date-and-time
1026 | +--:(yp:on-change) {on-change}?
1027 | +--ro yp:on-change!
1028 | +--ro yp:dampening-period? yang:timeticks
1029 | +--ro yp:no-synch-on-start? empty
1030 | +--ro yp:excluded-change* change-type
1031 +---n subscription-resumed
1032 | +--ro identifier subscription-id
1033 +---n subscription-modified
1034 | +--ro identifier subscription-id
1035 | +--ro protocol transport {configured}?
1036 | +--ro encoding encoding
1037 | +--ro (target)
1038 | | +--:(stream)
1039 | | | +--ro (stream-filter)?
1040 | | | | +--:(by-reference)
1041 | | | | | +--ro stream-filter-ref stream-filter-ref
1042 | | | | +--:(within-subscription)
1043 | | | | +--ro (filter-spec)?
1044 | | | | +--:(stream-subtree-filter)
1045 | | | | | +--ro stream-subtree-filter?
1046 | | | | | {subtree}?
1047 | | | | +--:(stream-xpath-filter)
1048 | | | | +--ro stream-xpath-filter?
1049 | | | | yang:xpath1.0 {xpath}?
1050 | | | +--ro stream stream-ref
1051 | | | +--ro replay-start-time? yang:date-and-time {replay}?
1052 | | +--:(yp:datastore)
1053 | | +--ro yp:datastore identityref
1054 | | +--ro (yp:selected-content)?
1055 | | +--:(yp:by-reference)
1056 | | | +--ro yp:selection-filter-ref selection-filter-ref
1057 | | +--:(yp:within-subscription)
1058 | | +--ro (yp:filter-spec)?
1059 | | +--:(yp:datastore-subtree-filter)
1060 | | | +--ro yp:datastore-subtree-filter?
1061 | | | {sn:subtree}?
1062 | | +--:(yp:datastore-xpath-filter)
1063 | | +--ro yp:datastore-xpath-filter?
1064 | | yang:xpath1.0 {sn:xpath}?
1065 | +--ro stop-time? yang:date-and-time
1066 | +--ro dscp? inet:dscp {qos}?
1067 | +--ro weighting? uint8 {qos}?
1068 | +--ro dependency? subscription-id {qos}?
1069 | +--ro (yp:update-trigger)?
1070 | +--:(yp:periodic)
1071 | | +--ro yp:periodic!
1072 | | +--ro yp:period yang:timeticks
1073 | | +--ro yp:anchor-time? yang:date-and-time
1074 | +--:(yp:on-change) {on-change}?
1075 | +--ro yp:on-change!
1076 | +--ro yp:dampening-period? yang:timeticks
1077 | +--ro yp:no-synch-on-start? empty
1078 | +--ro yp:excluded-change* change-type
1079 +---n subscription-terminated
1080 | +--ro identifier subscription-id
1081 | +--ro reason identityref
1082 +---n subscription-suspended
1083 +--ro identifier subscription-id
1084 +--ro reason identityref
1086 module: ietf-yang-push
1088 rpcs:
1089 +---x resynch-subscription {on-change}?
1090 +---w input
1091 +---w identifier sn:subscription-id
1093 yang-data: (for placement into rpc error responses)
1094 +-- resynch-subscription-error
1095 | +--ro reason? identityref
1096 | +--ro period-hint? timeticks
1097 | +--ro filter-failure-hint? string
1098 | +--ro object-count-estimate? uint32
1099 | +--ro object-count-limit? uint32
1100 | +--ro kilobytes-estimate? uint32
1101 | +--ro kilobytes-limit? uint32
1102 +-- establish-subscription-error-datastore
1103 | +--ro reason? identityref
1104 | +--ro period-hint? timeticks
1105 | +--ro filter-failure-hint? string
1106 | +--ro object-count-estimate? uint32
1107 | +--ro object-count-limit? uint32
1108 | +--ro kilobytes-estimate? uint32
1109 | +--ro kilobytes-limit? uint32
1110 +-- modify-subscription-error-datastore
1111 +--ro reason? identityref
1112 +--ro period-hint? timeticks
1113 +--ro filter-failure-hint? string
1114 +--ro object-count-estimate? uint32
1115 +--ro object-count-limit? uint32
1116 +--ro kilobytes-estimate? uint32
1117 +--ro kilobytes-limit? uint32
1119 notifications:
1120 +---n push-update
1121 | +--ro subscription-id? sn:subscription-id
1122 | +--ro updates-not-sent? empty
1123 | +--ro datastore-contents?
1124 +---n push-change-update {on-change}?
1125 +--ro subscription-id? sn:subscription-id
1126 +--ro updates-not-sent? empty
1127 +--ro datastore-changes?
1129 Figure 6: Model structure
1131 Selected components of the model are summarized below.
1133 4.2. Subscription configuration
1135 Both configured and dynamic subscriptions are represented within the
1136 list subscription. But only configured subscriptions are listed
1137 within list subscription-config. In both lists, each subscription
1138 has own list elements. New and enhanced parameters extending the
1139 basic subscription data model in
1140 [I-D.draft-ietf-netconf-subscribed-notifications] include:
1142 o The targeted datastore from which the selection is being made.
1143 The potential datastores include those from
1144 [I-D.draft-ietf-netmod-revised-datastores]. A platform may also
1145 choose to support a custom datastore.
1147 o A selection filter identifying yang nodes of interest within a
1148 datastore. Filter contents are specified via a reference to an
1149 existing filter, or via an in-line definition for only that
1150 subscription. Referenced filters allows an implementation to
1151 avoid evaluating filter acceptability during a dynamic
1152 subscription request. The case statement differentiates the
1153 options.
1155 o For periodic subscriptions, triggered updates will occur at the
1156 boundaries of a specified time interval. These boundaries many be
1157 calculated from the periodic parameters:
1159 * a "period" which defines duration between period push updates.
1161 * an "anchor-time"; update intervals always fall on the points in
1162 time that are a multiple of a "period" from an "anchor-time".
1163 If "anchor-time" is not provided, then the "anchor-time" MUST
1164 be set with the creation time of the initial update record.
1166 o For on-change subscriptions, assuming any dampening period has
1167 completed, triggering occurs whenever a change in the subscribed
1168 information is detected. On-change subscriptions have more
1169 complex semantics that is guided by its own set of parameters:
1171 * a "dampening-period" specifies the interval that must pass
1172 before a successive update for the subscription is sent. If no
1173 dampening period is in effect, the update is sent immediately.
1174 If a subsequent change is detected, another update is only sent
1175 once the dampening period has passed for this subscription.
1177 * an "excluded-change" flag which allows restriction of the types
1178 of changes for which updates should be sent (e.g., only add to
1179 an update record on object creation).
1181 * a "no-synch-on-start" flag which specifies whether a complete
1182 update with all the subscribed data is to be sent at the
1183 beginning of a subscription.
1185 4.3. YANG Notifications
1187 4.3.1. State Change Notifications
1189 Subscription state notifications and mechanism are reused from
1190 [I-D.draft-ietf-netconf-subscribed-notifications]. Some have been
1191 augmented to include the datastore specific objects.
1193 4.3.2. Notifications for Subscribed Content
1195 Along with the subscribed content, there are other objects which
1196 might be part of a "push-update" or "push-change-update"
1198 A "subscription-id" MUST be transported along with the subscribed
1199 contents. An [RFC5277] Section 4 one-way notification MAY be used
1200 for encoding updates. Where it is, the relevant "subscription-id"
1201 MUST be encoded as the first element within each "push-update" or
1202 "push-change-update". This allows a receiver to differentiate which
1203 subscription resulted in a particular push.
1205 A "time-of-update" which represents the time an update record
1206 snapshot was generated. A receiver MAY assume that a publisher's
1207 objects have these pushed values at this point in time.
1209 An "updates-not-sent" object. This object indicates that not all
1210 changes which have occurred since the last update are actually
1211 included with this update. In other words, the publisher has failed
1212 to fulfill its full subscription obligations. (For example a
1213 datastore was unable to providing the full set of datastore nodes to
1214 a publisher process.) To facilitate re-synchronization of on-change
1215 subscriptions, a publisher MAY subsequently send a "push-update"
1216 containing a full selection snapshot of subscribed data.
1218 4.4. YANG RPCs
1220 YANG-Push subscriptions are established, modified, and deleted using
1221 RPCs augmented from
1222 [I-D.draft-ietf-netconf-subscribed-notifications].
1224 4.4.1. Establish-subscription RPC
1226 The subscriber sends an establish-subscription RPC with the
1227 parameters in section 3.1. An example might look like:
1229
1231
1234
1235
1236 ds:operational
1237
1238
1241
1242
1243 500
1244
1245
1246
1248 Figure 7: Establish-subscription RPC
1250 The publisher MUST respond explicitly positively (i.e., subscription
1251 accepted) or negatively (i.e., subscription rejected) to the request.
1252 Positive responses include the "identifier" of the accepted
1253 subscription. In that case a publisher MAY respond:
1255
1257
1259 ok
1260
1261
1263 52
1264
1265
1267 Figure 8: Establish-subscription positive RPC response
1269 A subscription can be rejected for multiple reasons, including the
1270 lack of authorization to establish a subscription, no capacity to
1271 serve the subscription at the publisher, or the inability of the
1272 publisher to select datastore content at the requested cadence.
1274 If a request is rejected because the publisher is not able to serve
1275 it, the publisher SHOULD include in the returned error hints which
1276 help a subscriber understand subscription parameters might have been
1277 accepted for the request. These hints would be included within the
1278 yang-data structure "establish-subscription-error-datastore".
1279 However even with these hints, there are no guarantee that subsequent
1280 requests will in fact be accepted.
1282 The specific parameters to be returned in as part of the RPC error
1283 response depend on the specific transport that is used to manage the
1284 subscription. In the case of NETCONF
1285 [I-D.draft-ietf-netconf-netconf-event-notifications], when a
1286 subscription request is rejected, the NETCONF RPC reply MUST include
1287 an "rpc-error" element with the following elements:
1289 o "error-type" of "application".
1291 o "error-tag" of "operation-failed".
1293 o Optionally, an "error-severity" of "error" (this MAY but does not
1294 have to be included).
1296 o "error-app-tag" with the value being a string that corresponds to
1297 an identity with a base of "establish-subscription-error".
1299 o Optionally, "error-info" containing XML-encoded data with hints
1300 for parameter settings that might result in future RPC success per
1301 yang-data definition "establish-subscription-error-datastore".
1303 For example, for the following request:
1305
1307
1310
1312 ds:operational
1313
1314
1316 /ex:foo
1317
1318
1319 100
1320
1321
1322
1324 Figure 9: Establish-subscription request example 2
1326 a publisher that cannot serve on-change updates but periodic updates
1327 might return the following:
1329
1331
1332 application
1333 operation-failed
1334 error
1335
1336 on-change-unsupported
1337
1338
1340 /yp:periodic/yp:period
1341
1342
1343
1345 Figure 10: Establish-subscription error response example 2
1347 4.4.2. Modify-subscription RPC
1349 The subscriber MAY invoke the "modify-subscription" RPC for a
1350 subscription it previously established. The subscriber will include
1351 newly desired values in the "modify-subscription" RPC. Parameters
1352 not included MUST remain unmodified. Below is an example where a
1353 subscriber attempts to modify the "period" of a subscription.
1355
1357
1360 1011
1361
1363 ds:operational
1364
1365
1367 /ex:bar
1368
1369
1370 250
1371
1372
1373
1375 Figure 11: Modify subscription request
1377 The publisher MUST respond explicitly positively or negatively to the
1378 request. If the subscription modification is rejected, the
1379 subscription is maintained as it was before the modification request.
1380 In addition, the publisher MUST send an rpc error response. This rpc
1381 error response may contain hints encapsulated within the yang-data
1382 structure "modify-subscription-error-datastore". A subscription MAY
1383 be modified multiple times.
1385 The specific parameters to be returned in as part of the RPC error
1386 response depend on the specific transport that is used to manage the
1387 subscription. In the case of NETCONF
1388 [I-D.draft-ietf-netconf-netconf-event-notifications], when a
1389 subscription request is rejected, the NETCONF RPC reply MUST include
1390 an "rpc-error" element with the following elements:
1392 o "error-type" of "application".
1394 o "error-tag" of "operation-failed".
1396 o Optionally, an "error-severity" of "error" (this MAY but does not
1397 have to be included).
1399 o "error-app-tag" with the value being a string that corresponds to
1400 an identity with a base of "modify-subscription-error".
1402 o "error-path" pointing to the object or parameter that caused the
1403 rejection.
1405 o Optionally, "error-info" containing XML-encoded data with hints
1406 for parameter settings that might result in future RPC success per
1407 yang-data definition "modify-subscription-error-datastore".
1409 A configured subscription cannot be modified using "modify-
1410 subscription" RPC. Instead, the configuration needs to be edited as
1411 needed.
1413 4.4.3. Delete-subscription RPC
1415 To stop receiving updates from a subscription and effectively delete
1416 a subscription that had previously been established using an
1417 "establish-subscription" RPC, a subscriber can send a "delete-
1418 subscription" RPC, which takes as only input the subscription's
1419 "identifier".
1421 Configured subscriptions cannot be deleted via RPC, but have to be
1422 removed from the configuration. This RPC is identical to the RPC
1423 from [I-D.draft-ietf-netconf-subscribed-notifications].
1425 4.4.4. Resynch-subscription RPC
1427 This RPC is only applicable only for on-change subscriptions
1428 previously been established using an "establish-subscription" RPC.
1429 For example:
1431
1433
1436 1011
1437
1438
1440 Resynch subscription
1442 On receipt, a publisher must either accept the request and quickly
1443 follow with a "push-update", or send an appropriate error within an
1444 rpc error response. Within an error response, the publisher may
1445 include supplemental information about the reasons within the yang-
1446 data structure "resynch-subscription-error".
1448 4.4.5. YANG Module Synchronization
1450 To make subscription requests, the subscriber needs to know the YANG
1451 module library available on the publisher. The YANG 1.0 module
1452 library information is sent by a NETCONF server in the NETCONF
1453 "hello" message. For YANG 1.1 modules and all modules used with the
1454 RESTCONF [RFC8040] protocol, this information is provided by the YANG
1455 Library module (ietf-yang-library.yang from [RFC7895]. This YANG
1456 library information is important for the receiver to reproduce the
1457 set of object definitions used within the publisher.
1459 The YANG library includes a module list with the name, revision,
1460 enabled features, and applied deviations for each YANG module
1461 implemented by the publisher. The receiver is expected to know the
1462 YANG library information before starting a subscription. The
1463 "/modules-state/module-set-id" leaf in the "ietf-yang-library" module
1464 can be used to cache the YANG library information.
1466 The set of modules, revisions, features, and deviations can change at
1467 run-time (if supported by the publisher implementation). In this
1468 case, the receiver needs to be informed of module changes before
1469 datastore nodes from changed modules can be processed correctly. The
1470 YANG library provides a simple "yang-library-change" notification
1471 that informs the subscriber that the library has changed. The
1472 receiver then needs to re-read the entire YANG library data for the
1473 replicated publisher in order to detect the specific YANG library
1474 changes. The "ietf-netconf-notifications" module defined in
1475 [RFC6470] contains a "netconf-capability-change" notification that
1476 can identify specific module changes. For example, the module URI
1477 capability of a newly loaded module will be listed in the "added-
1478 capability" leaf-list, and the module URI capability of an removed
1479 module will be listed in the "deleted-capability" leaf-list.
1481 5. YANG module
1483 ; file "ietf-yang-push@2018-02-05.yang"
1484 module ietf-yang-push {
1485 yang-version 1.1;
1486 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push";
1487 prefix yp;
1489 import ietf-yang-types {
1490 prefix yang;
1491 }
1492 import ietf-subscribed-notifications {
1493 prefix sn;
1494 }
1495 import ietf-datastores {
1496 prefix ds;
1497 }
1498 import ietf-restconf {
1499 prefix rc;
1500 }
1502 organization "IETF";
1503 contact
1504 "WG Web:
1505 WG List:
1507 Editor: Alexander Clemm
1508
1510 Editor: Eric Voit
1511
1513 Editor: Alberto Gonzalez Prieto
1514
1516 Editor: Ambika Prasad Tripathy
1517
1519 Editor: Einar Nilsen-Nygaard
1520
1522 Editor: Andy Bierman
1523
1525 Editor: Balazs Lengyel
1526 ";
1528 description
1529 "This module contains YANG specifications for YANG push.";
1531 revision 2018-02-05 {
1532 description
1533 "Initial revision.";
1534 reference
1535 "draft-ietf-netconf-yang-push-13";
1536 }
1538 /*
1539 * FEATURES
1540 */
1542 feature on-change {
1543 description
1544 "This feature indicates that on-change triggered subscriptions
1545 are supported.";
1546 }
1548 /*
1549 * IDENTITIES
1550 */
1552 /* Error type identities for datastore subscription */
1554 identity resynch-subscription-error {
1555 description
1556 "Problem found while attempting to fulfill an
1557 'resynch-subscription' rpc request. ";
1558 }
1560 identity cant-exclude {
1561 base sn:establish-subscription-error;
1562 description
1563 "Unable to remove the set of 'excluded-changes'. This means the
1564 publisher is unable to restrict 'push-change-update's to just the
1565 change types requested for this subscription.";
1566 }
1568 identity datastore-not-subscribable {
1569 base sn:establish-subscription-error;
1570 base sn:subscription-terminated-reason;
1571 description
1572 "This is not a subscribable datastore.";
1573 }
1575 identity no-such-subscription-resynch {
1576 base resynch-subscription-error;
1577 description
1578 "Referenced subscription doesn't exist. This may be as a result of
1579 a non-existent subscription ID, an ID which belongs to another
1580 subscriber, or an ID for configured subscription.";
1581 }
1583 identity on-change-unsupported {
1584 base sn:establish-subscription-error;
1585 description
1586 "On-change is not supported for any objects which are selectable
1587 by this filter.";
1589 }
1591 identity on-change-synch-unsupported {
1592 base sn:establish-subscription-error;
1593 description
1594 "Neither synch on start nor resynchronization are supported for
1595 this subscription. This error will be used for two reasons. First
1596 if an 'establish-subscription' RPC doesn't include
1597 'no-synch-on-start', yet the publisher can't support sending a
1598 'push-update' for this subscription for reasons other than
1599 'on-change-unsupported' or 'synchronization-size'. And second, if
1600 the 'resynch-subscription' RPC is invoked either for an existing
1601 periodic subscription, or for an on-change subscription which
1602 can't support resynchronization.";
1603 }
1605 identity period-unsupported {
1606 base sn:establish-subscription-error;
1607 base sn:modify-subscription-error;
1608 base sn:subscription-suspended-reason;
1609 description
1610 "Requested time period is too short. This can be for both
1611 periodic and on-change subscriptions (with or without
1612 dampening.)
1614 Hints suggesting an acceptable period setting may be returned
1615 as supplemental information in a corresponding RPC error
1616 response, as applicable.";
1617 }
1619 identity result-too-big {
1620 base sn:establish-subscription-error;
1621 base sn:modify-subscription-error;
1622 base sn:subscription-suspended-reason;
1623 description
1624 "Periodic or on-change push update datatrees exceed a maximum
1625 size limit.
1627 Hints on a parameter setting that would result in a reasonable
1628 size may be returned as supplemental information in a
1629 corresponding RPC error response, as applicable.";
1630 }
1632 identity synchronization-size {
1633 base sn:establish-subscription-error;
1634 base sn:modify-subscription-error;
1635 base resynch-subscription-error;
1636 base sn:subscription-suspended-reason;
1637 description
1638 "Synch-on-start or resynchronization datatree exceeds a maximum
1639 size limit.
1641 Hints on a parameter setting that would result in a reasonable
1642 size may be returned as supplemental information in a
1643 corresponding RPC error response, as applicable.";
1644 }
1646 identity unchanging-selection {
1647 base sn:establish-subscription-error;
1648 base sn:modify-subscription-error;
1649 base sn:subscription-terminated-reason;
1650 description
1651 "Selection filter is unlikely to ever select datatree nodes. This
1652 means that based on the subscriber's current access rights, the
1653 publisher recognizes that the selection filter is unlikely to ever
1654 select datatree nodes which change. Examples for this might be
1655 that node or subtree doesn't exist, read access is not permitted
1656 for a receiver, or static objects that only change at reboot have
1657 been chosen.";
1658 }
1660 /*
1661 * TYPE DEFINITIONS
1662 */
1664 typedef change-type {
1665 type enumeration {
1666 enum "create" {
1667 description
1668 "Create a new data resource if it does not already exist. If
1669 it already exists, replace.";
1670 }
1671 enum "delete" {
1672 description
1673 "Delete a data resource if it already exists. If it does not
1674 exists, take no action.";
1675 }
1676 enum "insert" {
1677 description
1678 "Insert a new user-ordered data resource";
1679 }
1680 enum "merge" {
1681 description
1682 "merge the edit value with the target data resource; create
1683 if it does not already exist";
1684 }
1685 enum "move" {
1686 description
1687 "Reorder the target data resource";
1688 }
1689 enum "replace" {
1690 description
1691 "Replace the target data resource with the edit value";
1692 }
1693 enum "remove" {
1694 description
1695 "Remove a data resource if it already exists ";
1696 }
1697 }
1698 description
1699 "Specifies different types of datastore changes.";
1700 reference
1701 "RFC 8072 section 2.5, with a delta that it is valid for a
1702 receiver to process an update record which performs a create
1703 operation on a datastore node the receiver believes exists, or to
1704 process a delete on a datastore node the receiver believes is
1705 missing.";
1706 }
1708 typedef selection-filter-ref {
1709 type leafref {
1710 path "/sn:filters/yp:selection-filter/yp:identifier";
1711 }
1712 description
1713 "This type is used to reference a selection filter.";
1714 }
1716 /*
1717 * GROUP DEFINITIONS
1718 */
1720 grouping datastore-criteria {
1721 description
1722 "A grouping to define criteria for which selected objects from
1723 a targeted datastore should be included in push updates.";
1724 leaf datastore {
1725 type identityref {
1726 base ds:datastore;
1727 }
1728 mandatory true;
1729 description
1730 "Datastore from which to retrieve data.";
1731 }
1732 uses selection-filter-objects;
1734 }
1736 grouping selection-filter-types {
1737 description
1738 "This grouping defines a selector for objects from a
1739 datastore.";
1740 choice filter-spec {
1741 description
1742 "The content filter specification for this request.";
1743 anydata datastore-subtree-filter {
1744 if-feature "sn:subtree";
1745 description
1746 "This parameter identifies the portions of the
1747 target datastore to retrieve.";
1748 }
1749 leaf datastore-xpath-filter {
1750 if-feature "sn:xpath";
1751 type yang:xpath1.0;
1752 description
1753 "This parameter contains an XPath expression identifying the
1754 portions of the target datastore to retrieve.
1756 If the expression returns a node-set, all nodes in the
1757 node-set are selected by the filter. Otherwise, if the
1758 expression does not return a node-set, the filter
1759 doesn't select any nodes.
1761 The expression is evaluated in the following XPath context:
1763 o The set of namespace declarations are those in scope on
1764 the 'xpath-filter' leaf element.
1766 o The set of variable bindings is empty.
1768 o The function library is the core function library, and
1769 the XPath functions defined in section 10 in RFC 7950.
1771 o The context node is the root node of the target
1772 datastore.";
1773 }
1774 }
1775 }
1777 grouping selection-filter-objects {
1778 description
1779 "This grouping defines a selector for objects from a
1780 datastore.";
1781 choice selected-content {
1782 description
1783 "The source of the selection filter applied to the subscription.
1784 This will come either referenced from a global list, or be
1785 provided within the subscription itself.";
1786 case by-reference {
1787 description
1788 "Incorporate a filter that has been configured separately.";
1789 leaf selection-filter-ref {
1790 type selection-filter-ref;
1791 mandatory true;
1792 description
1793 "References an existing selection filter which is to be
1794 applied to the subscription.";
1795 }
1796 }
1797 case within-subscription {
1798 description
1799 "Local definition allows a filter to have the same lifecycle
1800 as the subscription.";
1801 uses selection-filter-types;
1803 }
1804 }
1805 }
1807 grouping update-policy-modifiable {
1808 description
1809 "This grouping describes the datastore specific subscription
1810 conditions that can be changed during the lifetime of the
1811 subscription.";
1812 choice update-trigger {
1813 description
1814 "Defines necessary conditions for sending an event record to
1815 the subscriber.";
1816 case periodic {
1817 container periodic {
1818 presence "indicates an periodic subscription";
1819 description
1820 "The publisher is requested to notify periodically the
1821 current values of the datastore as defined by the selection
1822 filter.";
1823 leaf period {
1824 type yang:timeticks;
1825 mandatory true;
1826 description
1827 "Duration of time which should occur between periodic
1828 push updates. Where the anchor-time is
1829 available, the push will include the objects and their
1830 values which exist at an exact multiple of timeticks
1831 aligning to this start-time anchor.";
1832 }
1833 leaf anchor-time {
1834 type yang:date-and-time;
1835 description
1836 "Designates a timestamp before or after which a series of
1837 periodic push updates are determined. The next update
1838 will take place at a whole multiple interval from the
1839 anchor time. For example, for an anchor time is set for
1840 the top of a particular minute and a period interval of a
1841 minute, updates will be sent at the top of every minute
1842 this subscription is active.";
1843 }
1844 }
1845 }
1846 case on-change {
1847 if-feature "on-change";
1848 container on-change {
1849 presence "indicates an on-change subscription";
1850 description
1851 "The publisher is requested to notify changes in values in
1852 the datastore subset as defined by a selection filter.";
1853 leaf dampening-period {
1854 type yang:timeticks;
1855 default 0;
1856 description
1857 "Specifies the minimum interval between the assembly of
1858 successive update records for a single receiver of a
1859 subscription. Whenever subscribed objects change, and a
1860 dampening period interval (which may be zero) has elapsed
1861 since the previous update record creation for a receiver,
1862 then any subscribed objects and properties which have
1863 changed since the previous update record will have their
1864 current values marshalled and placed into a new update
1865 record.";
1866 }
1867 }
1868 }
1869 }
1870 }
1872 grouping update-policy {
1873 description
1874 "This grouping describes the datastore specific subscription
1875 conditions of a subscription.";
1876 uses update-policy-modifiable {
1877 augment "update-trigger/on-change/on-change" {
1878 description
1879 "Includes objects not modifiable once subscription is
1880 established.";
1881 leaf no-synch-on-start {
1882 type empty;
1883 description
1884 "The presence of this object restricts an on-change
1885 subscription from sending push-update notifications. When
1886 present, pushing a full selection per the terms of the
1887 selection filter MUST NOT be done for this subscription.
1888 Only updates about changes, i.e. only push-change-update
1889 notifications are sent. When absent (default behavior),
1890 in order to facilitate a receiver's synchronization, a full
1891 update is sent when the subscription starts using a
1892 push-update notification, just like in the case of a
1893 periodic subscription. After that, push-change-update
1894 notifications are exclusively sent unless the publisher
1895 chooses to resynch the subscription via a new push-update
1896 notification.";
1897 }
1898 leaf-list excluded-change {
1899 type change-type;
1900 description
1901 "Use to restrict which changes trigger an update.
1902 For example, if modify is excluded, only creation and
1903 deletion of objects is reported.";
1904 }
1905 }
1906 }
1907 }
1909 grouping hints {
1910 description
1911 "Parameters associated with some error on for a subscription made
1912 upon a datastore.";
1913 leaf period-hint {
1914 type yang:timeticks;
1915 description
1916 "Returned when the requested time period is too short. This
1917 hint can assert a viable period for either a periodic push
1918 cadence or an on-change dampening interval.";
1919 }
1920 leaf filter-failure-hint {
1921 type string;
1922 description
1923 "Information describing where and/or why a provided filter
1924 was unsupportable for a subscription.";
1925 }
1926 leaf object-count-estimate {
1927 type uint32;
1928 description
1929 "If there are too many objects which could potentially be
1930 returned by the selection filter, this identifies the estimate
1931 of the number of objects which the filter would potentially
1932 pass.";
1933 }
1934 leaf object-count-limit {
1935 type uint32;
1936 description
1937 "If there are too many objects which could be returned by the
1938 selection filter, this identifies the upper limit of the
1939 publisher's ability to service for this subscription.";
1940 }
1941 leaf kilobytes-estimate {
1942 type uint32;
1943 description
1944 "If the returned information could be beyond the capacity of
1945 the publisher, this would identify the data size which could
1946 result from this selection filter.";
1947 }
1948 leaf kilobytes-limit {
1949 type uint32;
1950 description
1951 "If the returned information would be beyond the capacity of
1952 the publisher, this identifies the upper limit of the
1953 publisher's ability to service for this subscription.";
1954 }
1955 }
1957 /*
1958 * RPCs
1959 */
1961 rpc resynch-subscription {
1962 if-feature "on-change";
1963 description
1964 "This RPC allows a subscriber of an active on-change
1965 subscription to request a full push of objects in there current
1966 state. A successful result would be the set of YANG objects
1967 equivalent to a Get using the existing selection criteria. This
1968 request may only come from the same subscriber using the
1969 establish-subscription RPC.";
1970 input {
1971 leaf identifier {
1972 type sn:subscription-id;
1973 mandatory true;
1974 description
1975 "Identifier of the subscription that is to be resynched.";
1976 }
1977 }
1978 }
1980 rc:yang-data resynch-subscription-error {
1981 container resynch-subscription-error {
1982 description
1983 "If a 'resynch-subscription' RPC fails, the subscription is not
1984 resynched and the RPC error response MUST indicate the reason
1985 for this failure. This yang-data MAY be inserted as structured
1986 data within a subscription's RPC error response to indicate the
1987 failure reason.";
1988 leaf reason {
1989 type identityref {
1990 base resynch-subscription-error;
1991 }
1992 mandatory true;
1993 description
1994 "Indicates the reason why the publisher has declined a request
1995 for subscription resynchronization.";
1996 }
1997 uses hints;
1998 }
1999 }
2001 augment "/sn:establish-subscription/sn:input" {
2002 description
2003 "This augmentation adds additional subscription parameters that
2004 apply specifically to datastore updates to RPC input.";
2005 uses update-policy;
2006 }
2008 augment "/sn:establish-subscription/sn:input/sn:target" {
2009 description
2010 "This augmentation adds the datastore as a valid parameter object
2011 for the subscription to RPC input. This provides a target for
2012 the filter.";
2013 case datastore {
2014 description
2015 "Information specifying the parameters of an request for a
2016 datastore subscription.";
2017 uses datastore-criteria;
2018 }
2019 }
2020 rc:yang-data establish-subscription-error-datastore {
2021 container establish-subscription-error-datastore {
2022 description
2023 "If any 'establish-subscription' RPC parameters are
2024 unsupportable against the datastore, a subscription is not
2025 created and the RPC error response MUST indicate the reason why
2026 the subscription failed to be created. This yang-data MAY be
2027 inserted as structured data within a subscription's RPC error
2028 response to indicate the failure reason. This yang-data MUST be
2029 inserted if hints are to be provided back to the subscriber.";
2030 leaf reason {
2031 type identityref {
2032 base sn:establish-subscription-error;
2033 }
2034 description
2035 "Indicates the reason why the subscription has failed to
2036 be created to a targeted datastore.";
2037 }
2038 uses hints;
2039 }
2040 }
2042 augment "/sn:modify-subscription/sn:input" {
2043 description
2044 "This augmentation adds additional subscription parameters
2045 specific to datastore updates.";
2046 uses update-policy-modifiable;
2047 }
2049 augment "/sn:modify-subscription/sn:input/sn:target" {
2050 description
2051 "This augmentation adds the datastore as a valid parameter object
2052 for the subscription to RPC input. This provides a target for
2053 the filter.";
2054 case datastore {
2055 description
2056 "Information specifying the parameters of an request for a
2057 datastore subscription.";
2058 uses selection-filter-objects;
2059 }
2060 }
2062 rc:yang-data modify-subscription-error-datastore {
2063 container modify-subscription-error-datastore {
2064 description
2065 "This yang-data MAY be provided as part of a subscription's RPC
2066 error response when there is a failure of a
2067 'modify-subscription' RPC which has been made against a
2068 datastore. This yang-data MUST be used if hints are to be
2069 provides back to the subscriber.";
2070 leaf reason {
2071 type identityref {
2072 base sn:modify-subscription-error;
2073 }
2074 description
2075 "Indicates the reason why the subscription has failed to
2076 be modified.";
2077 }
2078 uses hints;
2079 }
2080 }
2082 /*
2083 * NOTIFICATIONS
2084 */
2086 notification push-update {
2087 description
2088 "This notification contains a push update, containing data
2089 subscribed to via a subscription. This notification is sent for
2090 periodic updates, for a periodic subscription. It can also be
2091 used for synchronization updates of an on-change subscription.
2092 This notification shall only be sent to receivers of a
2093 subscription; it does not constitute a general-purpose
2094 notification.";
2095 leaf subscription-id {
2096 type sn:subscription-id;
2097 description
2098 "This references the subscription which drove the notification
2099 to be sent.";
2100 }
2101 leaf updates-not-sent {
2102 type empty;
2103 description
2104 "This is a flag which indicates that not all datastore nodes
2105 subscribed to are included with this update. In other words,
2106 the publisher has failed to fulfill its full subscription
2107 obligations, and despite its best efforts is providing an
2108 incomplete set of objects.";
2109 }
2110 anydata datastore-contents {
2111 description
2112 "This contains the updated data. It constitutes a snapshot
2113 at the time-of-update of the set of data that has been
2114 subscribed to. The format and syntax of the data
2115 corresponds to the format and syntax of data that would be
2116 returned in a corresponding get operation with the same
2117 selection filter parameters applied.";
2118 }
2119 }
2121 notification push-change-update {
2122 if-feature "on-change";
2123 description
2124 "This notification contains an on-change push update. This
2125 notification shall only be sent to the receivers of a
2126 subscription; it does not constitute a general-purpose
2127 notification.";
2128 leaf subscription-id {
2129 type sn:subscription-id;
2130 description
2131 "This references the subscription which drove the notification
2132 to be sent.";
2133 }
2134 leaf updates-not-sent {
2135 type empty;
2136 description
2137 "The presence of this object indicates not all changes which
2138 have occurred since the last update are included with this
2139 update. In other words, the publisher has failed to
2140 fulfill its full subscription obligations, for example in
2141 cases where it was not able to keep up with a change burst.";
2142 }
2143 anydata datastore-changes {
2144 description
2145 "This contains the set of datastore changes needed
2146 to update a remote datastore starting at the time of the
2147 previous update, per the terms of the subscription. Changes
2148 are encoded analogous to the syntax of a corresponding yang-
2149 patch operation, i.e. a yang-patch operation applied to the
2150 datastore implied by the previous update to result in the
2151 current state.";
2152 reference
2153 "RFC 8072 section 2.5, with a delta that it is ok to receive
2154 ability create on an existing node, or receive a delete on a
2155 missing node.";
2156 }
2157 }
2159 augment "/sn:subscription-started" {
2160 description
2161 "This augmentation adds many datastore specific objects to
2162 the notification that a subscription has started.";
2163 uses update-policy;
2165 }
2167 augment "/sn:subscription-started/sn:target" {
2168 description
2169 "This augmentation allows the datastore to be included as part
2170 of the notification that a subscription has started.";
2171 case datastore {
2172 uses datastore-criteria {
2173 refine "selected-content/within-subscription" {
2174 description
2175 "Specifies where the selection filter, and where came from
2176 within the subscription and then populated within this
2177 notification. If the 'selection-filter-ref' is populated,
2178 the filter within the subscription came from the 'filters'
2179 container. Otherwise it is populated in-line as part of the
2180 subscription itself.";
2181 }
2182 }
2183 }
2184 }
2186 augment "/sn:subscription-modified" {
2187 description
2188 "This augmentation adds many datastore specific objects to
2189 the notification that a subscription has been modified.";
2190 uses update-policy;
2191 }
2192 augment "/sn:subscription-modified/sn:target" {
2193 description
2194 "This augmentation allows the datastore to be included as part
2195 of the notification that a subscription has been modified.";
2196 case datastore {
2197 uses datastore-criteria {
2198 refine "selected-content/within-subscription" {
2199 description
2200 "Specifies where the selection filter, and where came from
2201 within the subscription and then populated within this
2202 notification. If the 'selection-filter-ref' is populated,
2203 the filter within the subscription came from the 'filters'
2204 container. Otherwise it is populated in-line as part of the
2205 subscription itself.";
2206 }
2207 }
2208 }
2209 }
2211 /*
2212 * DATA NODES
2213 */
2215 augment "/sn:filters" {
2216 description
2217 "This augmentation allows the datastore to be included as part
2218 of the selection filtering criteria for a subscription.";
2219 list selection-filter {
2220 key "identifier";
2221 description
2222 "A list of pre-positioned filters that can be applied
2223 to datastore subscriptions.";
2224 leaf identifier {
2225 type sn:filter-id;
2226 description
2227 "An identifier to differentiate between selection filters.";
2228 }
2229 uses selection-filter-types;
2230 }
2231 }
2233 augment "/sn:subscriptions/sn:subscription" {
2234 description
2235 "This augmentation adds many datastore specific objects to a
2236 subscription.";
2237 uses update-policy;
2238 }
2239 augment "/sn:subscriptions/sn:subscription/sn:target" {
2240 description
2241 "This augmentation allows the datastore to be included as part
2242 of the selection filtering criteria for a subscription.";
2243 case datastore {
2244 uses datastore-criteria;
2245 }
2246 }
2247 }
2249
2251 6. IANA Considerations
2253 This document registers the following namespace URI in the "IETF XML
2254 Registry" [RFC3688]:
2256 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push
2257 Registrant Contact: The IESG.
2258 XML: N/A; the requested URI is an XML namespace.
2260 This document registers the following YANG module in the "YANG Module
2261 Names" registry [RFC6020]:
2263 Name: ietf-yang-push
2264 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push
2265 Prefix: yp
2266 Reference: draft-ietf-netconf-yang-push-12.txt (RFC form)
2268 7. Security Considerations
2270 All security considerations from
2271 [I-D.draft-ietf-netconf-subscribed-notifications] are relevant for
2272 datastores. In addition there are specific security considerations
2273 for receivers defined in Section 3.9
2275 If the access control permissions on subscribed YANG nodes change
2276 during the lifecycle of a subscription, a publisher MUST either
2277 transparently conform to the new access control permissions, or must
2278 terminate or restart the subscriptions so that new access control
2279 permissions are re-established.
2281 The NETCONF Authorization Control Model SHOULD be used to restrict
2282 the delivery of YANG nodes for which the receiver has no access.
2284 8. Acknowledgments
2286 For their valuable comments, discussions, and feedback, we wish to
2287 acknowledge Tim Jenkins, Kent Watsen, Susan Hares, Yang Geng, Peipei
2288 Guo, Michael Scharf, Martin Bjorklund, and Guangying Zheng.
2290 9. References
2292 9.1. Normative References
2294 [I-D.draft-ietf-netconf-subscribed-notifications]
2295 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A.,
2296 and E. Nilsen-Nygaard, "Custom Subscription to Event
2297 Streams", draft-ietf-netconf-subscribed-notifications-06
2298 (work in progress), January 2018.
2300 [I-D.draft-ietf-netmod-revised-datastores]
2301 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
2302 and R. Wilton, "Network Management Datastore
2303 Architecture", draft-ietf-netmod-revised-datastores-04
2304 (work in progress), August 2017.
2306 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
2307 DOI 10.17487/RFC3688, January 2004,
2308 .
2310 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
2311 the Network Configuration Protocol (NETCONF)", RFC 6020,
2312 DOI 10.17487/RFC6020, October 2010,
2313 .
2315 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF)
2316 Base Notifications", RFC 6470, DOI 10.17487/RFC6470,
2317 February 2012, .
2319 [RFC6536bis]
2320 Bierman, A. and M. Bjorklund, "Network Configuration
2321 Protocol (NETCONF) Access Control Model", draft-ietf-
2322 netconf-rfc6536bis-05 (work in progress), September 2017.
2324 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
2325 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016,
2326 .
2328 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch
2329 Media Type", RFC 8072, DOI 10.17487/RFC8072, February
2330 2017, .
2332 9.2. Informative References
2334 [I-D.draft-ietf-netconf-netconf-event-notifications]
2335 Gonzalez Prieto, A., Clemm, A., Voit, E., Nilsen-Nygaard,
2336 E., and A. Tripathy, "NETCONF Support for Event
2337 Notifications", September 2017.
2339 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
2340 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
2341 .
2343 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
2344 and A. Bierman, Ed., "Network Configuration Protocol
2345 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
2346 .
2348 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface
2349 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014,
2350 .
2352 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements
2353 for Subscription to YANG Datastores", RFC 7923,
2354 DOI 10.17487/RFC7923, June 2016,
2355 .
2357 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2358 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
2359 .
2361 Appendix A. Appendix A: Subscription Errors
2363 A.1. RPC Failures
2365 Rejection of an RPC for any reason is indicated by via RPC error
2366 response from the publisher. Valid RPC errors returned include both
2367 existing transport layer RPC error codes, such as those seen with
2368 NETCONF in [RFC6241], as well as subscription specific errors such as
2369 those defined within the YANG model. As a result, how subscription
2370 errors are encoded within an RPC error response is transport
2371 dependent.
2373 References to specific identities within the either the subscribed-
2374 notifications YANG model or the yang-push YANG model may be returned
2375 as part of the error responses resulting from failed attempts at
2376 datastore subscription. Following are valid errors per RPC (note:
2377 throughout this section the prefix 'sn' indicates an item imported
2378 from the subscribed-notifications.yang model):
2380 establish-subscription modify-subscription
2381 ---------------------- -------------------
2382 cant-exclude sn:filter-unsupported
2383 datastore-not-subscribable sn:insufficient-resources
2384 sn:dscp-unavailable sn:no-such-subscription
2385 sn:filter-unsupported period-unsupported
2386 sn:insufficient-resources result-too-big
2387 on-change-unsupported synchronization-size
2388 on-change-synch-unsupported unchanging-selection
2389 period-unsupported
2390 result-too-big resynch-subscription
2391 synchronization-size --------------------
2392 unchanging-selection no-such-subscription-resynch
2393 synchronization-size
2395 delete-subscription kill-subscription
2396 ---------------------- -----------------
2397 sn:no-such-subscription sn:no-such-subscription
2399 There is one final set of transport independent RPC error elements
2400 included in the YANG model. These are the following four yang-data
2401 structures for failed datastore subscriptions:
2403 1. yang-data establish-subscription-error-datastore
2404 This MUST be returned if an RPC error reason has not been placed
2405 elsewhere within the transport portion of a failed "establish-
2406 subscription" RPC response. This MUST be sent if hints on how to
2407 overcome the RPC error are included.
2409 2. yang-data modify-subscription-error-datastore
2410 This MUST be returned if an RPC error reason has not been placed
2411 elsewhere within the transport portion of a failed "modify-subscription"
2412 RPC response. This MUST be sent if hints on how to overcome the RPC
2413 error are included.
2415 3. yang-data sn:delete-subscription-error
2416 This MUST be returned if an RPC error reason has not been placed
2417 elsewhere within the transport portion of a failed "delete-subscription"
2418 or "kill-subscription" RPC response.
2420 4. yang-data resynch-subscription-error
2421 This MUST be returned if an RPC error reason has not been placed
2422 elsewhere within the transport portion of a failed "resynch-
2423 subscription" RPC response.
2425 A.2. Notifications of Failure
2427 A subscription may be unexpectedly terminated or suspended
2428 independent of any RPC or configuration operation. In such cases,
2429 indications of such a failure MUST be provided. To accomplish this,
2430 the following types of error identities may be returned within the
2431 corresponding subscription state change notification:
2433 subscription-terminated subscription-suspended
2434 ----------------------- ----------------------
2435 datastore-not-subscribable sn:insufficient-resources
2436 sn:filter-unavailable period-unsupported
2437 sn:no-such-subscription result-too-big
2438 sn:suspension-timeout synchronization-size
2439 unchanging-selection
2441 Appendix B. Changes between revisions
2443 (To be removed by RFC editor prior to publication)
2445 v13 - v14
2446 o Minor text fixes.
2448 v12 - v13
2450 o Hint negotiation models now show error examples.
2452 o yang-data structures for rpc errors.
2454 v11 - v12
2456 o Included Martin's review clarifications.
2458 o QoS moved to subscribed-notifications
2460 o time-of-update removed as it is redundant with RFC5277's
2461 eventTime, and other times from notification-messages.
2463 o Error model moved to match existing implementations
2465 o On-change notifiable removed, how to do this is implementation
2466 specific.
2468 o NMDA model supported. Non NMDA version at https://github.com/
2469 netconf-wg/yang-push/
2471 v10 - v11
2473 o Promise model reference added.
2475 o Error added for no-such-datastore
2477 o Inherited changes from subscribed notifications (such as optional
2478 feature definitions).
2480 o scrubbed the examples for proper encodings
2482 v09 - v10
2484 o Returned to the explicit filter subtyping of v00-v05
2486 o identityref to ds:datastore made explicit
2488 o Returned ability to modify a selection filter via RPC.
2490 v08 - v09
2492 o Minor tweaks cleaning up text, removing appendicies, and making
2493 reference to revised-datastores.
2495 o Subscription-id optional in push updates, except when encoded in
2496 RFC5277, Section 4 one-way notification.
2498 o Finished adding the text descibing the resynch subscription RPC.
2500 o Removed relationships to other drafts and future technology
2501 appendicies as this work is being explored elsewhere.
2503 o Deferred the multi-line card issue to new drafts
2505 o Simplified the NACM interactions.
2507 v07 - v08
2509 o Updated YANG models with minor tweaks to accommodate changes of
2510 ietf-subscribed-notifications.
2512 v06 - v07
2514 o Clarifying text tweaks.
2516 o Clarification that filters act as selectors for subscribed
2517 datastore nodes; support for value filters not included but
2518 possible as a future extension
2520 o Filters don't have to be matched to existing YANG objects
2522 v05 - v06
2524 o Security considerations updated.
2526 o Base YANG model in [subscribe] updated as part of move to
2527 identities, YANG augmentations in this doc matched up
2529 o Terms refined and text updates throughout
2531 o Appendix talking about relationship to other drafts added.
2533 o Datastore replaces stream
2535 o Definitions of filters improved
2537 v04 to v05
2539 o Referenced based subscription document changed to Subscribed
2540 Notifications from 5277bis.
2542 o Getting operational data from filters
2543 o Extension notifiable-on-change added
2545 o New appendix on potential futures. Moved text into there from
2546 several drafts.
2548 o Subscription configuration section now just includes changed
2549 parameters from Subscribed Notifications
2551 o Subscription monitoring moved into Subscribed Notifications
2553 o New error and hint mechanisms included in text and in the yang
2554 model.
2556 o Updated examples based on the error definitions
2558 o Groupings updated for consistency
2560 o Text updates throughout
2562 v03 to v04
2564 o Updates-not-sent flag added
2566 o Not notifiable extension added
2568 o Dampening period is for whole subscription, not single objects
2570 o Moved start/stop into rfc5277bis
2572 o Client and Server changed to subscriber, publisher, and receiver
2574 o Anchor time for periodic
2576 o Message format for synchronization (i.e. synch-on-start)
2578 o Material moved into 5277bis
2580 o QoS parameters supported, by not allowed to be modified by RPC
2582 o Text updates throughout
2584 Authors' Addresses
2586 Alexander Clemm
2587 Huawei
2589 Email: ludwig@clemm.org
2590 Eric Voit
2591 Cisco Systems
2593 Email: evoit@cisco.com
2595 Alberto Gonzalez Prieto
2596 VMware
2598 Email: agonzalezpri@vmware.com
2600 Ambika Prasad Tripathy
2601 Cisco Systems
2603 Email: ambtripa@cisco.com
2605 Einar Nilsen-Nygaard
2606 Cisco Systems
2608 Email: einarnn@cisco.com
2610 Andy Bierman
2611 YumaWorks
2613 Email: andy@yumaworks.com
2615 Balazs Lengyel
2616 Ericsson
2618 Email: balazs.lengyel@ericsson.com