idnits 2.17.1
draft-ietf-netconf-yang-push-10.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 242: '...cription request SHOULD be declined if...'
RFC 2119 keyword, line 250: '... subscriptions SHOULD support a simp...'
RFC 2119 keyword, line 253: '...-success message SHOULD include in the...'
RFC 2119 keyword, line 280: '... publisher MAY accept an on-change s...'
RFC 2119 keyword, line 292: '...ely, a publisher MAY decide to simply ...'
(48 more instances...)
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Line 998 has weird spacing: '...ntifier sub...'
== Line 1000 has weird spacing: '...-result sub...'
== Line 1003 has weird spacing: '...ntifier sub...'
== Line 1005 has weird spacing: '...-result sub...'
== Line 1009 has weird spacing: '...ntifier sub...'
== (7 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 messages for a single subscription MAY NOT be resequenced.
== 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 (October 2, 2017) is 2397 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Unused Reference: 'RFC7223' is defined on line 2303, but no explicit
reference was found in the text
== 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 (~~), 11 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: April 5, 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 October 2, 2017
17 Subscribing to YANG datastore push updates
18 draft-ietf-netconf-yang-push-10
20 Abstract
22 Providing rapid visibility into changes made on YANG configuration
23 and operational objects enables new capabilities such as remote
24 mirroring of configuration and operational state. Via the mechanism
25 described in this document, subscriber applications may request a
26 continuous, customized stream of updates from a YANG datastore.
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 April 5, 2018.
45 Copyright Notice
47 Copyright (c) 2017 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. Event Subscription Model . . . . . . . . . . . . . . . . 5
78 3.2. Negotiation of Subscription Policies . . . . . . . . . . 6
79 3.3. On-Change Considerations . . . . . . . . . . . . . . . . 6
80 3.4. Promise-Theory Considerations . . . . . . . . . . . . . . 7
81 3.5. Data Encodings . . . . . . . . . . . . . . . . . . . . . 8
82 3.6. Datastore Selection Filters . . . . . . . . . . . . . . . 8
83 3.7. Streaming Updates . . . . . . . . . . . . . . . . . . . . 10
84 3.8. Subscription Management . . . . . . . . . . . . . . . . . 13
85 3.9. Receiver Authorization . . . . . . . . . . . . . . . . . 14
86 3.10. On-change Notifiable YANG objects . . . . . . . . . . . . 16
87 3.11. Other Considerations . . . . . . . . . . . . . . . . . . 17
88 4. A YANG data model for management of datastore push
89 subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 18
90 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 18
91 4.2. Subscription configuration . . . . . . . . . . . . . . . 25
92 4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 27
93 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 28
94 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 33
95 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48
96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 48
97 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 49
98 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 49
99 9.1. Normative References . . . . . . . . . . . . . . . . . . 49
100 9.2. Informative References . . . . . . . . . . . . . . . . . 50
101 Appendix A. Changes between revisions . . . . . . . . . . . . . 50
102 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 53
104 1. Introduction
106 Traditional approaches to remote visibility have been built on
107 polling. With polling, data is periodically requested and retrieved
108 by a client from a server to stay up-to-date. However, there are
109 issues associated with polling-based management:
111 o Polling incurs significant latency. This latency prohibits many
112 application types.
114 o Polling cycles may be missed, requests may be delayed or get lost,
115 often when the network is under stress and the need for the data
116 is the greatest.
118 o Polling requests may undergo slight fluctuations, resulting in
119 intervals of different lengths. The resulting data is difficult
120 to calibrate and compare.
122 o For applications that monitor for changes, many remote polling
123 cycles place ultimately fruitless load on the network, devices,
124 and applications.
126 A more effective alternative to polling is for an application to
127 receive automatic and continuous updates from a targeted subset of a
128 datastore. Accordingly, there is a need for a service that allows
129 applications to subscribe to updates from a YANG datastore and that
130 enables the publisher to push and in effect stream those updates.
131 The requirements for such a service have been documented in
132 [RFC7923].
134 This document defines a corresponding solution that is built on top
135 of "Custom Subscription to Event Notifications" [subscribe].
136 Supplementing that work are YANG data model augmentations, extended
137 RPCs, and new datastore specific update notifications. Transport
138 options for [subscribe] will work seamlessly with this solution.
140 2. Definitions and Acronyms
142 The terms below supplement those defined in [subscribe].
144 Data node: An instance of management information in a YANG datastore.
146 Data node update: A data item containing the current value/property
147 of a Data node at the time the data node update was created.
149 Datastore: A conceptual store of instantiated management information,
150 with individual data items represented by data nodes which are
151 arranged in hierarchical manner.
153 Data subtree: An instantiated data node and the data nodes that are
154 hierarchically contained within it.
156 Notification message: A transport encapsulated update record(s) and/
157 or event notification(s) intended to be sent to a receiver.
159 Update notification message: A notification message that contains an
160 update record.
162 Update record: A representation data node update(s) resulting from
163 the application of a filter for a subscription. An update record
164 will include the value/property of one or more data nodes at a point
165 in time. It may contain the update type for each data node (e.g.,
166 add, change, delete). Also included may be metadata/headers such as
167 a subscription-id.
169 Update trigger: A mechanism that determines when an update record
170 needs to be generated.
172 YANG-Push: The subscription and push mechanism for YANG datastores
173 that is specified in this document.
175 3. Solution Overview
177 This document specifies a solution for a push update subscription
178 service. This solution supports the dynamic as well as configured
179 subscriptions to information updates from YANG datastores.
180 Subscriptions specify when update notification messages should be
181 sent and what data to include in update records. YANG objects are
182 subsequently pushed from the publisher to the receiver per the terms
183 of the subscription.
185 3.1. Event Subscription Model
187 YANG-push subscriptions are defined using a data model that is itself
188 defined in YANG. This model enhances the event subscription model
189 defined in [subscribe] with capabilities that allow subscribers to
190 subscribe to data node updates, specifically to specify the triggers
191 defining when to generate update records as well as what to include
192 in an update record. Key enhancements include:
194 o Specification of selection filters which identify targeted YANG
195 data nodes and/or subtrees within a datastore for which updates
196 are to be pushed.
198 o An encoding (using anydata) for the contents of periodic and on-
199 change push updates.
201 o Specification of update policies contain conditions which trigger
202 the generation and pushing of new update records. There are two
203 types of triggers for subscriptions: periodic and on-change.
205 * For periodic subscriptions, the trigger is specified by two
206 parameters that define when updates are to be pushed. These
207 parameters are the period interval with which to report
208 updates, and an anchor time which can be used to calculate at
209 which point in time updates need to be assembled and sent.
211 * For on-change subscriptions, a trigger occurs whenever a change
212 in the subscribed information is detected. Included are
213 additional parameters such as:
215 + Dampening period: In an on-change subscription, the first
216 change that is detected results in an update to be sent
217 immediately. However, sending successive updates whenever
218 further changes are detected might result in quick
219 exhaustion of resources in case of very rapid changes. In
220 order to protect against that, a dampening period is used to
221 specify the interval which must pass before successive
222 update records for the same subscription are generated. The
223 dampening period collectively applies to the set of all data
224 nodes of a single subscription. This means that when there
225 is a change to a subscribed object, an update record
226 containing that object is created either immediately when no
227 dampening period is already in effect, or at the end of a
228 dampening period.
230 + Change type: This parameter can be used to reduce the types
231 of datastore changes for which updates are sent (e.g., you
232 might only send when an object is created or deleted, but
233 not when an object value changes).
235 + No Synch on start: defines whether or not a complete push-
236 update of all subscribed data will be sent at the beginning
237 of a subscription. Such early synchronization establishes
238 the frame of reference for subsequent updates.
240 3.2. Negotiation of Subscription Policies
242 A dynamic subscription request SHOULD be declined if a publisher's
243 assessment is that it may be unable to provide update records meeting
244 the terms of the request. In this case, a subscriber may quickly
245 follow up with a new subscription request using different parameters.
247 Random guessing at different parameters by a subscriber is to be
248 discouraged. Therefore, in order to minimize the number of
249 subscription iterations between subscriber and publisher, dynamic
250 subscriptions SHOULD support a simple negotiation between subscribers
251 and publishers for subscription parameters. This negotiation is in
252 the form of a no-success response to a failed establish or modify
253 subscription request. The no-success message SHOULD include in the
254 returned error response information that, when considered, increases
255 the likelihood of success for subsequent requests. However, there
256 are no guarantees that subsequent requests for this subscriber will
257 be accepted.
259 [subscribe] contains several negotiable subscription parameters.
260 Additional yang-push negotiation information defined in this
261 specification includes hints at acceptable time intervals, size
262 estimates for the number or objects which would be returned from a
263 filter, and the location of an error in a provided filter.
265 3.3. On-Change Considerations
267 On-change subscriptions allow subscribers to subscribe to updates
268 whenever changes to targeted objects occur. As such, on-change
269 subscriptions are particularly effective for data that changes
270 infrequently, yet for which applications need to be quickly notified
271 whenever a change does occur with minimal delay.
273 On-change subscriptions tend to be more difficult to implement than
274 periodic subscriptions. Accordingly, on-change subscriptions may not
275 be supported by all implementations or for every object.
277 Whether or not to accept or reject on-change subscription requests
278 when the scope of the subscription contains objects for which on-
279 change is not supported is up to the publisher implementation. A
280 publisher MAY accept an on-change subscription even when the scope of
281 the subscription contains objects for which on-change is not
282 supported. In that case, updates are sent only for those objects
283 within the scope that do support on-change updates whereas other
284 objects are excluded from update records, whether or not their values
285 actually change. In order for a subscriber to determine whether
286 objects support on-change subscriptions, objects are marked
287 accordingly on a publisher. Accordingly, when subscribing, it is the
288 responsibility of the subscriber to ensure it is aware of which
289 objects support on-change and which do not. For more on how objects
290 are so marked, see Section 3.10.
292 Alternatively, a publisher MAY decide to simply reject an on-change
293 subscription in case the scope of the subscription contains objects
294 for which on-change is not supported. In case of a configured
295 subscription, the subscription MAY be suspended.
297 To avoid flooding receivers with repeated updates for subscriptions
298 containing fast-changing objects, or objects with oscillating values,
299 an on-change subscription allows for the definition of a dampening
300 period. Once an update record for a given object is generated, no
301 other updates for this particular subscription will be created until
302 the end of the dampening period. Values sent at the end of the
303 dampening period are the current values of all changed objects which
304 are current at the time the dampening period expires. Changed
305 objects include those which were deleted or newly created during that
306 dampening period. If an object has returned to its original value
307 (or even has been created and then deleted) during the dampening-
308 period, the last change will still be sent. This will indicate churn
309 is occurring on that object.
311 In cases where a subscriber wants to have separate dampening periods
312 for different objects, multiple subscriptions with different objects
313 in a selection filter can be created.
315 On-change subscriptions can be refined to let users subscribe only to
316 certain types of changes. For example, a subscriber might only want
317 object creations and deletions, but not modifications of object
318 values.
320 3.4. Promise-Theory Considerations
322 A subscription to updates from a YANG datastore is intended to
323 obviate the need for polling. However, in order to do so, it is
324 critical that subscribers can rely on the subscription and have
325 confidence that they will indeed receive the subscribed updates
326 without having to worry updates being silently dropped. In other
327 words, a subscription constitutes a promise on the side of the
328 publisher to provide the receivers with updates per the terms of the
329 subscription.
331 Now, there are many reasons why a publisher may at some point no
332 longer be able to fulfill the terms of the subscription, even if the
333 subscription had been entered into with good faith. For example, the
334 volume of data objects may be larger than anticipated, the interval
335 may prove too short to send full updates in rapid succession, or an
336 internal problem may prevent objects from being collected. If for
337 some reason the publisher of a subscription is not able to keep its
338 promise, receivers MUST be notified immediately and reliably. The
339 publisher MAY also suspend the subscription.
341 A publisher SHOULD reject a request for a subscription if it is
342 unlikely that the publisher will be able fulfill the terms of that
343 subscription request. In such cases, it is preferable to have a
344 subscriber request a less resource intensive subscription than to
345 deal with frequently degraded behavior.
347 3.5. Data Encodings
349 A publisher MUST support XML encoding and MAY support other encodings
350 such as JSON encoding.
352 3.5.1. Periodic Subscriptions
354 In a periodic subscription, the data included as part of an update
355 corresponds to data that could have been simply retrieved using a get
356 operation and is encoded in the same way. XML encoding rules for
357 data nodes are defined in [RFC7950]. JSON encoding rules are defined
358 in [RFC7951].
360 3.5.2. On-Change Subscriptions
362 In an on-change subscription, updates need to indicate not only
363 values of changed data nodes but also the types of changes that
364 occurred since the last update. Therefore encoding rules for data in
365 on-change updates will follow YANG-patch operation as specified in
366 [RFC8072]. The YANG-patch will describe what needs to be applied to
367 the earlier state reported by the preceding update, to result in the
368 now-current state. Note that contrary to [RFC8072], objects
369 encapsulated are not restricted to configuration objects only.
371 3.6. Datastore Selection Filters
373 Subscription policy specifies both the selection filters and the
374 datastores against which these selection filters will be applied.
376 The result is the push of information necessary to remotely maintain
377 an extract of the publisher's datastore.
379 Only a single selection filter can be applied to a subscription at a
380 time. The following selection filter types are included in the yang-
381 push data model, and may be applied against a datastore:
383 o subtree: A subtree selection filter identifies one or more
384 subtrees. When specified, updates will only come from the data
385 nodes of selected YANG subtree(s). The syntax and semantics
386 correspond to that specified for [RFC6241] section 6.
388 o xpath: An xpath selection filter is an XPath expression which may
389 be meaningfully applied to a datastore. It is the results of this
390 expression which will be pushed.
392 These filters are intended to be used as selectors that define which
393 objects are within the scope of a subscription. Filters are not
394 intended to be used to filter objects based on a non-key property.
395 Supporting non-key property filtering so would have a number of
396 implications that would result in significant complexity. While it
397 is possible to define extensions in the future that will support
398 selection filtering based on values, this is not supported in this
399 version of yang-push and a publisher MAY reject a subscription
400 request that contains a filter for object values.
402 Xpath itself provides powerful filtering constructs, and care must be
403 used in filter definition. As an example, consider an xpath filter
404 with a boolean result; such a result will not provide an easily
405 interpretable subset of a datastore. Beyond the boolean example, it
406 is quite possible to define an xpath filter where results are easy
407 for an application to mis-interpret. Consider an xpath filter which
408 only passes a datastore object when an interface is up. It is up to
409 the receiver to understand implications of the presence or absence of
410 objects in each update.
412 It is not expected that implementations will support comprehensive
413 filter syntax and boundless complexity. It will be up to
414 implementations to describe what is viable, but the goal is to
415 provide equivalent capabilities to what is available with a GET.
416 Implementations MUST reject dynamic subscriptions or suspend
417 configured subscriptions if they include filters which are
418 unsupportable on a platform.
420 3.7. Streaming Updates
422 Contrary to traditional data retrieval requests, datastore
423 subscription enables an unbounded series of update records to be
424 streamed over time. Two generic notifications for update records
425 have been defined for this: "push-update" and "push-change-update".
427 A push-update notification defines a complete, filtered update of the
428 datastore per the terms of a subscription. This type of notification
429 is used for continuous updates of periodic subscriptions. A push-
430 update notification can also be used for the on-change subscriptions
431 in two cases. First it will be used as the initial push-update if
432 there is a need to synchronize the receiver at the start of a new
433 subscription. It also MAY be sent if the publisher later chooses to
434 resynch an on-change subscription. The push-update record contains a
435 data snippet that contains an instantiated subtree with the
436 subscribed contents. The content of the update record is equivalent
437 to the contents that would be obtained had the same data been
438 explicitly retrieved using e.g., a NETCONF "get" operation, with the
439 same filters applied.
441 A push-change-update notification is the most common type of update
442 for on-change subscriptions. The update record in this case contains
443 a data snippet that indicates the set of changes that data nodes have
444 undergone since the last notification of YANG objects. In other
445 words, this indicates which data nodes have been created, deleted, or
446 have had changes to their values. In cases where multiple changes
447 have occurred and the object has not been deleted, the object's most
448 current value is reported. (In other words, for each object, only
449 one change is reported, not its entire history. Doing so would
450 defeat the purpose of the dampening period.)
452 These new push-update or push-change-update are encoded and placed
453 within notification messages, and ultimately queued for egress over
454 the specified transport.
456 The following is an example of an XML encoded notification message
457 over NETCONF transport as per [netconf-notif].
459
461 2015-03-09T19:14:56Z
462
464 1011
465 2015-03-09T19:14:55.233Z
466
467
468 some_string
469
470
471
472
474 Figure 1: Push example
476 The following is an example of an on-change notification. It
477 contains an update for subscription 89, including a new value for a
478 leaf called beta, which is a child of a top-level container called
479 alpha:
481
483 2015-03-09T19:14:56Z
484
486 89
487 2015-03-09T19:14:55.233Z
488
489
490 1500
491
492
493
494
496 Figure 2: Push example for on change
498 The equivalent update when requesting json encoding:
500
502 2015-03-09T19:14:56Z
503
505 89
506 2015-03-09T19:14:55.233Z
507
508 {
509 "ietf-yang-patch:yang-patch": {
510 "patch-id": [
511 null
512 ],
513 "edit": [
514 {
515 "edit-id": "edit1",
516 "operation": "merge",
517 "target": "/alpha/beta",
518 "value": {
519 "beta": 1500
520 }
521 }
522 ]
523 }
524 }
525
526
527
529 Figure 3: Push example for on change with JSON
531 When the beta leaf is deleted, the publisher may send
532
534 2015-03-09T19:14:56Z
535
537 89
538 2015-03-09T19:14:55.233Z
539
540
541
543
544
545
546
548 Figure 4: 2nd push example for on change update
550 3.8. Subscription Management
552 The RPCs defined within [subscribe] have been enhanced to support
553 YANG datastore subscription negotiation. Included in these
554 enhancements are error codes which can indicate why a datastore
555 subscription attempt has failed.
557 A datastore subscription can be rejected for multiple reasons. This
558 includes a too large subtree request, or the inability of the
559 publisher push update records as frequently as requested. In such
560 cases, no subscription is established. Instead, the subscription-
561 result with the failure reason is returned as part of the RPC
562 response. As part of this response, a set of alternative
563 subscription parameters MAY be returned that would likely have
564 resulted in acceptance of the subscription request. The subscriber
565 may consider these as part of future subscription attempts.
567 For instance, for the following request:
569
571
573
574
575
578
579 500
580 encode-xml
581
582
584 Figure 5: Establish-Subscription example
586 the publisher might return:
588
590
592 error-insufficient-resources
593
594 2000
595
597 Figure 6: Error response example
599 As can be seen above the rejected subscription does not result in the
600 generation of an rpc-reply with an rpc-error element. YANG-push
601 specific errors and negotiation hints part are returned as part of
602 normal RPC operations.
604 3.9. Receiver Authorization
606 A receiver of subscription data MUST only be sent updates for which
607 they have proper authorization. A publisher MUST ensure that no non-
608 authorized data is included in push updates. To do so, it needs to
609 apply all corresponding checks applicable at the time of a specific
610 pushed update and if necessary silently remove any non-authorized
611 data from subtrees. This enables YANG data pushed based on
612 subscriptions to be authorized equivalently to a regular data
613 retrieval (get) operation.
615 A publisher MAY allow subscriptions which select non-existent or
616 access-protected data. Such a capability permits a receiver the
617 ability to monitor the entire lifecyle of the data. In this case,
618 all push-updates must be sent empty, and no push-change-updates will
619 be sent until the data becomes visible for a receiver.
621 A publisher MAY alternatively choose not to allow subscriptions which
622 select non-existent or access-protected data. Such a capability
623 enables the publisher to avoid having to perform filtering of
624 authorized content on each update. Relevant scenarios here include:
626 o the rejecting of a subscription request to access-protected
627 objects,
629 o the suspension of a subscription where new access-controlled
630 objects are selected mid-subscription for which the receiver does
631 not have the necessary authorization, or
633 o the authorization privileges of a receiver change over the course
634 of the subscription.
636 In all these cases, the error identity "data-unavailable" SHOULD be
637 returned. This reduces the possibility of access permission leakage.
639 The contextual authorization model for data in YANG datastores is the
640 NETCONF Access Control Model [RFC6536bis], Section 3.2.4. A
641 clarification to this is that each of the individual nodes in a
642 resulting update record MUST also have applied access control to
643 resulting pushed messages. This includes validating that read access
644 is ok for any nodes newly selected since the last update record for
645 each receiver.
647 +-------------+ +-------------------+
648 push-update / --> | data node | yes | |
649 push-change-update | access | ---> | add data node |
650 | allowed? | | to update message |
651 +-------------+ +-------------------+
653 Figure 7: Access control for push updates
655 If read access into previously accessible nodes has been lost due to
656 a receiver permissions change, this SHOULD be reported as node
657 'delete' operations for on-change subscriptions. If not capable of
658 handling such receiver permission changes with such a 'delete',
659 publisher implementations MUST force dynamic subscription re-
660 establishment or configured subscription re-initialization so that
661 appropriate filtering is installed.
663 3.10. On-change Notifiable YANG objects
665 In some cases, a publisher supporting on-change notifications may not
666 be able to push updates for some object types on-change. Reasons for
667 this might be that the value of the data node changes frequently
668 (e.g., [RFC7223]'s in-octets counter), that small object changes are
669 frequent and meaningless (e.g., a temperature gauge changing 0.1
670 degrees), or that the implementation is not capable of on-change
671 notification for a particular object.
673 Support for on-change notification is usually specific to the
674 individual YANG model and/or implementation so it is possible to
675 define in design time. System integrators need this information
676 (without reading any data from a live node).
678 The default assumption is that no data nodes support on-change
679 notification. Schema nodes and subtrees that support on-change
680 notifications MUST be marked by accordingly with the YANG extension
681 "notifiable-on-change". This extension is defined in the data model
682 below.
684 When an on-change subscription is established, data-nodes are
685 automatically excluded unless they are marked with notifiable-on-
686 change as true. This also means that authorization checks SHALL NOT
687 be performed on them. A subscriber can identify which nodes may be
688 included in on-change updates by retrieving the data nodes in the
689 subscription's scope and checking for which notifiable-on-change is
690 marked as true.
692 In theory, adding notifiable-on-change markings can be done within
693 corresponding YANG models. But a more extensible way to avoid having
694 to modify existing module definitions is to add notifiable-on-change
695 markings within separate module deviations. This means that when a
696 YANG model designer wants to add a notifiable-on-change marking to
697 nodes of an existing module without modifying the module definitions,
698 a new module is introduced that contains deviation statements which
699 add "notifiable-on-change" statements as applicable.
701 deviation /sys:system/sys:system-time {
702 deviate add {
703 yp:notifiable-on-change false;
704 }
705 }
707 Figure 8: Deviation Example
709 3.11. Other Considerations
711 3.11.1. Robustness and reliability
713 Particularly in the case of on-change push updates, it is important
714 that push updates do not get lost or, in case the loss of an update
715 is unavoidable, that the receiver is notified accordingly.
717 Update messages for a single subscription MAY NOT be resequenced.
719 It is conceivable that under certain circumstances, a publisher will
720 recognize that it is unable to include within an update record the
721 full set of objects desired per the terms of a subscription. In this
722 case, the publisher MUST take one or more of the following actions.
724 o A publisher MUST set the updates-not-sent flag on any update
725 record which is known to be missing information.
727 o It MAY choose to suspend a subscription as per [subscribe].
729 o When resuming an on-change subscription, the publisher SHOULD
730 generate a complete patch from the previous update record. If
731 this is not possible and the synch-on-start option is configured,
732 then the full datastore contents MAY be sent via a push-update
733 instead (effectively replacing the previous contents). If neither
734 of these are possible, then an updates-not-sent flag MUST be
735 included on the next push-change-update.
737 Note: It is perfectly acceptable to have a series of push-change-
738 updates (and even push updates) serially queued at the transport
739 layer awaiting transmission. It is not required to merge pending
740 update messages. I.e., the dampening period applies to update record
741 creation, not transmission.
743 3.11.2. Publisher capacity
745 It is far preferable to decline a subscription request than to accept
746 such a request when it cannot be met.
748 Whether or not a subscription can be supported will be determined by
749 a combination of several factors such as the subscription trigger
750 (on-change or periodic), the period in which to report changes (1
751 second periods will consume more resources than 1 hour periods), the
752 amount of data in the subtree that is being subscribed to, and the
753 number and combination of other subscriptions that are concurrently
754 being serviced.
756 4. A YANG data model for management of datastore push subscriptions
758 4.1. Overview
760 The YANG data model for datastore push subscriptions is depicted in
761 the following figure. Following YANG tree convention in the
762 depiction, brackets enclose list keys, "rw" means configuration, "ro"
763 operational state data, "?" designates optional nodes, "*" designates
764 nodes that can have multiple instances. Parentheses with a name in
765 the middle enclose choice and case nodes. New YANG objects defined
766 here (i.e., beyond those from [subscribe]) are identified with "yp".
768 module: ietf-subscribed-notifications
769 +--ro streams
770 | +--ro stream* [name]
771 | +--ro name stream
772 | +--ro description string
773 | +--ro replay-support? empty {replay}?
774 | +--ro replay-log-creation-time? yang:date-and-time {replay}?
775 | +--ro replay-log-aged-time? yang:date-and-time {replay}?
776 +--rw filters
777 | +--rw event-filter* [identifier]
778 | | +--rw identifier filter-id
779 | | +--rw (filter-spec)?
780 | | +--:(subtree-filter)
781 | | | +--rw subtree-filter?
782 | | +--:(xpath-filter)
783 | | +--rw xpath-filter? yang:xpath1.0
784 | +--rw yp:selection-filter* [identifier]
785 | +--rw yp:identifier sn:filter-id
786 | +--rw (yp:filter-spec)?
787 | +--:(yp:subtree-filter)
788 | | +--rw yp:subtree-filter?
789 | +--:(yp:xpath-filter)
790 | +--rw yp:xpath-filter? yang:xpath1.0
791 +--rw subscription-config {configured-subscriptions}?
792 | +--rw subscription* [identifier]
793 | +--rw identifier subscription-id
794 | +--rw encoding? encoding
795 | +--rw (target)
796 | | +--:(stream)
797 | | | +--rw (event-filter)?
798 | | | | +--:(by-reference)
799 | | | | | +--rw event-filter-ref event-filter-ref
800 | | | | +--:(within-subscription)
801 | | | | +--rw (filter-spec)?
802 | | | | +--:(subtree-filter)
803 | | | | | +--rw subtree-filter?
804 | | | | +--:(xpath-filter)
805 | | | | +--rw xpath-filter? yang:xpath1.0
806 | | | +--rw stream stream
807 | | | +--rw replay-start-time? yang:date-and-time {replay}?
808 | | +--:(yp:datastore)
809 | | +--rw yp:source identityref
810 | | +--rw (yp:selected-content)?
811 | | +--:(yp:by-reference)
812 | | | +--rw yp:selection-filter-ref selection-filter-ref
813 | | +--:(yp:within-subscription)
814 | | +--rw (yp:filter-spec)?
815 | | +--:(yp:subtree-filter)
816 | | | +--rw yp:subtree-filter?
817 | | +--:(yp:xpath-filter)
818 | | +--rw yp:xpath-filter? yang:xpath1.0
819 | +--rw stop-time? yang:date-and-time
820 | +--rw receivers
821 | | +--rw receiver* [address port]
822 | | +--rw address inet:host
823 | | +--rw port inet:port-number
824 | | +--rw protocol? transport-protocol
825 | +--rw (notification-origin)?
826 | | +--:(interface-originated)
827 | | | +--rw source-interface? if:interface-ref
828 | | +--:(address-originated)
829 | | +--rw source-vrf? string
830 | | +--rw source-address? inet:ip-address-no-zone
831 | +--rw (yp:update-trigger)?
832 | | +--:(yp:periodic)
833 | | | +--rw yp:period yang:timeticks
834 | | | +--rw yp:anchor-time? yang:date-and-time
835 | | +--:(yp:on-change) {on-change}?
836 | | +--rw yp:dampening-period yang:timeticks
837 | | +--rw yp:no-synch-on-start? empty
838 | | +--rw yp:excluded-change* change-type
839 | +--rw yp:dscp? inet:dscp
840 | +--rw yp:weighting? uint8
841 | +--rw yp:dependency? sn:subscription-id
842 +--ro subscriptions
843 +--ro subscription* [identifier]
844 +--ro identifier subscription-id
845 +--ro configured-subscription?
846 | empty {configured-subscriptions}?
847 +--ro encoding? encoding
848 +--ro (target)
849 | +--:(stream)
850 | | +--ro (event-filter)?
851 | | | +--:(by-reference)
852 | | | | +--ro event-filter-ref event-filter-ref
853 | | | +--:(within-subscription)
854 | | | +--ro (filter-spec)?
855 | | | +--:(subtree-filter)
856 | | | | +--ro subtree-filter?
857 | | | +--:(xpath-filter)
858 | | | +--ro xpath-filter? yang:xpath1.0
859 | | +--ro stream stream
860 | | +--ro replay-start-time? yang:date-and-time {replay}?
861 | +--:(yp:datastore)
862 | +--ro yp:source identityref
863 | +--ro (yp:selected-content)?
864 | +--:(yp:by-reference)
865 | | +--ro yp:selection-filter-ref selection-filter-ref
866 | +--:(yp:within-subscription)
867 | +--ro (yp:filter-spec)?
868 | +--:(yp:subtree-filter)
869 | | +--ro yp:subtree-filter?
870 | +--:(yp:xpath-filter)
871 | +--ro yp:xpath-filter? yang:xpath1.0
872 +--ro stop-time? yang:date-and-time
873 +--ro (notification-origin)?
874 | +--:(interface-originated)
875 | | +--ro source-interface? if:interface-ref
876 | +--:(address-originated)
877 | +--ro source-vrf? string
878 | +--ro source-address? inet:ip-address-no-zone
879 +--ro receivers
880 | +--ro receiver* [address port]
881 | +--ro address inet:host
882 | +--ro port inet:port-number
883 | +--ro protocol? transport-protocol
884 | +--ro pushed-notifications? yang:counter64
885 | +--ro excluded-notifications? yang:counter64
886 | +--ro status subscription-status
887 +--ro (yp:update-trigger)?
888 | +--:(yp:periodic)
889 | | +--ro yp:period yang:timeticks
890 | | +--ro yp:anchor-time? yang:date-and-time
891 | +--:(yp:on-change) {on-change}?
892 | +--ro yp:dampening-period yang:timeticks
893 | +--ro yp:no-synch-on-start? empty
894 | +--ro yp:excluded-change* change-type
895 +--ro yp:dscp? inet:dscp
896 +--ro yp:weighting? uint8
897 +--ro yp:dependency? sn:subscription-id
899 rpcs:
901 +---x establish-subscription
902 | +---w input
903 | | +---w encoding? encoding
904 | | +---w (target)
905 | | | +--:(stream)
906 | | | | +---w (event-filter)?
907 | | | | | +--:(by-reference)
908 | | | | | | +---w event-filter-ref event-filter-ref
909 | | | | | +--:(within-subscription)
910 | | | | | +---w (filter-spec)?
911 | | | | | +--:(subtree-filter)
912 | | | | | | +---w subtree-filter?
913 | | | | | +--:(xpath-filter)
914 | | | | | +---w xpath-filter? yang:xpath1.0
915 | | | | +---w stream stream
916 | | | | +---w replay-start-time? yang:date-and-time {replay}?
917 | | | +--:(yp:datastore)
918 | | | +---w yp:source identityref
919 | | | +---w (yp:selected-content)?
920 | | | +--:(yp:by-reference)
921 | | | | +---w yp:selection-filter-ref selection-filter-ref
922 | | | +--:(yp:within-subscription)
923 | | | +---w (yp:filter-spec)?
924 | | | +--:(yp:subtree-filter)
925 | | | | +---w yp:subtree-filter?
926 | | | +--:(yp:xpath-filter)
927 | | | +---w yp:xpath-filter? yang:xpath1.0
928 | | +---w stop-time? yang:date-and-time
929 | | +---w (yp:update-trigger)?
930 | | | +--:(yp:periodic)
931 | | | | +---w yp:period yang:timeticks
932 | | | | +---w yp:anchor-time? yang:date-and-time
933 | | | +--:(yp:on-change) {on-change}?
934 | | | +---w yp:dampening-period yang:timeticks
935 | | | +---w yp:no-synch-on-start? empty
936 | | | +---w yp:excluded-change* change-type
937 | | +---w yp:dscp? inet:dscp
938 | | +---w yp:weighting? uint8
939 | | +---w yp:dependency? sn:subscription-id
940 | +--ro output
941 | +--ro subscription-result subscription-result
942 | +--ro (result)?
943 | +--:(no-success)
944 | | +--ro filter-failure? string
945 | | +--ro replay-start-time-hint? yang:date-and-time
946 | | +--ro yp:period-hint? yang:timeticks
947 | | +--ro yp:error-path? string
948 | | +--ro yp:object-count-estimate? uint32
949 | | +--ro yp:object-count-limit? uint32
950 | | +--ro yp:kilobytes-estimate? uint32
951 | | +--ro yp:kilobytes-limit? uint32
952 | +--:(success)
953 | +--ro identifier subscription-id
954 +---x modify-subscription
955 | +---w input
956 | | +---w identifier? subscription-id
957 | | +---w (target)
958 | | | +--:(stream)
959 | | | | +---w (event-filter)?
960 | | | | +--:(by-reference)
961 | | | | | +---w event-filter-ref event-filter-ref
962 | | | | +--:(within-subscription)
963 | | | | +---w (filter-spec)?
964 | | | | +--:(subtree-filter)
965 | | | | | +---w subtree-filter?
966 | | | | +--:(xpath-filter)
967 | | | | +---w xpath-filter? yang:xpath1.0
968 | | | +--:(yp:datastore)
969 | | | +---w (yp:selected-content)?
970 | | | +--:(yp:by-reference)
971 | | | | +---w yp:selection-filter-ref selection-filter-ref
972 | | | +--:(yp:within-subscription)
973 | | | +---w (yp:filter-spec)?
974 | | | +--:(yp:subtree-filter)
975 | | | | +---w yp:subtree-filter?
976 | | | +--:(yp:xpath-filter)
977 | | | +---w yp:xpath-filter? yang:xpath1.0
978 | | +---w stop-time? yang:date-and-time
979 | | +---w (yp:update-trigger)?
980 | | +--:(yp:periodic)
981 | | | +---w yp:period yang:timeticks
982 | | | +---w yp:anchor-time? yang:date-and-time
983 | | +--:(yp:on-change) {on-change}?
984 | | +---w yp:dampening-period yang:timeticks
985 | +--ro output
986 | +--ro subscription-result subscription-result
987 | +--ro (result)?
988 | +--:(no-success)
989 | +--ro filter-failure? string
990 | +--ro yp:period-hint? yang:timeticks
991 | +--ro yp:error-path? string
992 | +--ro yp:object-count-estimate? uint32
993 | +--ro yp:object-count-limit? uint32
994 | +--ro yp:kilobytes-estimate? uint32
995 | +--ro yp:kilobytes-limit? uint32
996 +---x delete-subscription
997 | +---w input
998 | | +---w identifier subscription-id
999 | +--ro output
1000 | +--ro subscription-result subscription-result
1001 +---x kill-subscription
1002 +---w input
1003 | +---w identifier subscription-id
1004 +--ro output
1005 +--ro subscription-result subscription-result
1007 notifications:
1008 +---n replay-completed
1009 | +--ro identifier subscription-id
1010 +---n subscription-completed
1011 | +--ro identifier subscription-id
1012 +---n subscription-started
1013 | +--ro identifier subscription-id
1014 | +--ro encoding? encoding
1015 | +--ro (target)
1016 | | +--:(stream)
1017 | | | +--ro (event-filter)?
1018 | | | | +--:(by-reference)
1019 | | | | | +--ro event-filter-ref event-filter-ref
1020 | | | | +--:(within-subscription)
1021 | | | | +--ro (filter-spec)?
1022 | | | | +--:(subtree-filter)
1023 | | | | | +--ro subtree-filter?
1024 | | | | +--:(xpath-filter)
1025 | | | | +--ro xpath-filter? yang:xpath1.0
1026 | | | +--ro stream stream
1027 | | | +--ro replay-start-time? yang:date-and-time {replay}?
1028 | | +--:(yp:datastore)
1029 | | +--ro yp:source identityref
1030 | | +--ro (yp:selected-content)?
1031 | | +--:(yp:by-reference)
1032 | | | +--ro yp:selection-filter-ref selection-filter-ref
1033 | | +--:(yp:within-subscription)
1034 | | +--ro (yp:filter-spec)?
1035 | | +--:(yp:subtree-filter)
1036 | | | +--ro yp:subtree-filter?
1037 | | +--:(yp:xpath-filter)
1038 | | +--ro yp:xpath-filter? yang:xpath1.0
1039 | +--ro stop-time? yang:date-and-time
1040 | +--ro (yp:update-trigger)?
1041 | | +--:(yp:periodic)
1042 | | | +--ro yp:period yang:timeticks
1043 | | | +--ro yp:anchor-time? yang:date-and-time
1044 | | +--:(yp:on-change) {on-change}?
1045 | | +--ro yp:dampening-period yang:timeticks
1046 | | +--ro yp:no-synch-on-start? empty
1047 | | +--ro yp:excluded-change* change-type
1048 | +--ro yp:dscp? inet:dscp
1049 | +--ro yp:weighting? uint8
1050 | +--ro yp:dependency? sn:subscription-id
1051 +---n subscription-resumed
1052 | +--ro identifier subscription-id
1053 +---n subscription-modified
1054 | +--ro identifier subscription-id
1055 | +--ro encoding? encoding
1056 | +--ro (target)
1057 | | +--:(stream)
1058 | | | +--ro (event-filter)?
1059 | | | | +--:(by-reference)
1060 | | | | | +--ro event-filter-ref event-filter-ref
1061 | | | | +--:(within-subscription)
1062 | | | | +--ro (filter-spec)?
1063 | | | | +--:(subtree-filter)
1064 | | | | | +--ro subtree-filter?
1065 | | | | +--:(xpath-filter)
1066 | | | | +--ro xpath-filter? yang:xpath1.0
1067 | | | +--ro stream stream
1068 | | | +--ro replay-start-time? yang:date-and-time {replay}?
1069 | | +--:(yp:datastore)
1070 | | +--ro yp:source identityref
1071 | | +--ro (yp:selected-content)?
1072 | | +--:(yp:by-reference)
1073 | | | +--ro yp:selection-filter-ref selection-filter-ref
1074 | | +--:(yp:within-subscription)
1075 | | +--ro (yp:filter-spec)?
1076 | | +--:(yp:subtree-filter)
1077 | | | +--ro yp:subtree-filter?
1078 | | +--:(yp:xpath-filter)
1079 | | +--ro yp:xpath-filter? yang:xpath1.0
1080 | +--ro stop-time? yang:date-and-time
1081 | +--ro (yp:update-trigger)?
1082 | | +--:(yp:periodic)
1083 | | | +--ro yp:period yang:timeticks
1084 | | | +--ro yp:anchor-time? yang:date-and-time
1085 | | +--:(yp:on-change) {on-change}?
1086 | | +--ro yp:dampening-period yang:timeticks
1087 | | +--ro yp:no-synch-on-start? empty
1088 | | +--ro yp:excluded-change* change-type
1089 | +--ro yp:dscp? inet:dscp
1090 | +--ro yp:weighting? uint8
1091 | +--ro yp:dependency? sn:subscription-id
1092 +---n subscription-terminated
1093 | +--ro identifier subscription-id
1094 | +--ro error-id subscription-errors
1095 | +--ro filter-failure? string
1096 +---n subscription-suspended
1097 +--ro identifier subscription-id
1098 +--ro error-id subscription-errors
1099 +--ro filter-failure? string
1101 module: ietf-yang-push
1103 rpcs:
1104 +---x resynch-subscription {on-change}?
1105 +---w input
1106 | +---w identifier sn:subscription-id
1107 +--ro output
1108 +--ro subscription-result sn:subscription-result
1110 notifications:
1111 +---n push-update
1112 | +--ro subscription-id? sn:subscription-id
1113 | +--ro time-of-update? yang:date-and-time
1114 | +--ro updates-not-sent? empty
1115 | +--ro datastore-contents?
1116 +---n push-change-update {on-change}?
1117 +--ro subscription-id? sn:subscription-id
1118 +--ro time-of-update? yang:date-and-time
1119 +--ro updates-not-sent? empty
1120 +--ro datastore-changes?
1122 Figure 9: Model structure
1124 Selected components of the model are summarized below.
1126 4.2. Subscription configuration
1128 Both configured and dynamic subscriptions are represented within the
1129 list subscription. But only configured subscriptions are listed
1130 within list subscription-config. In both lists, each subscription
1131 has own list elements. New and enhanced parameters extending the
1132 basic subscription data model in [subscribe] include:
1134 o The targeted datastore from which the selection is being made.
1135 The potential datastores include those from [revised-datastores].
1136 A platform may also choose to support a custom datastore.
1138 o A selection filter identifying yang nodes of interest within a
1139 datastore. Filter contents are specified via a reference to an
1140 existing filter, or via an in-line definition for only that
1141 subscription. Referenced filters allows an implementation to
1142 avoid evaluating filter acceptability during a dynamic
1143 subscription request. The case statement differentiates the
1144 options.
1146 o For periodic subscriptions, triggered updates will occur at the
1147 boundaries of a specified time interval. These boundaries many be
1148 calculated from the periodic parameters:
1150 * a "period" which defines duration between period push updates.
1152 * an "anchor-time"; update intervals always fall on the points in
1153 time that are a multiple of a period from an anchor time. If
1154 anchor time is not provided, then the anchor time MUST be set
1155 with the creation time of the initial update record.
1157 o For on-change subscriptions, assuming the dampening period has
1158 completed, triggering occurs whenever a change in the subscribed
1159 information is detected. On-change subscriptions have more
1160 complex semantics that is guided by its own set of parameters:
1162 * a "dampening-period" specifies the interval that must pass
1163 before a successive update for the subscription is sent. If no
1164 dampening period is in effect, the update is sent immediately.
1165 If a subsequent change is detected, another update is only sent
1166 once the dampening period has passed for this subscription.
1168 * an "excluded-change" flag which allows restriction of the types
1169 of changes for which updates should be sent (e.g., only add to
1170 an update record on object creation).
1172 * a "no-synch-on-start" flag which specifies whether a complete
1173 update with all the subscribed data is to be sent at the
1174 beginning of a subscription.
1176 o Optional QoS parameters to indicate the treatment of a
1177 subscription relative to other traffic between publisher and
1178 receiver. These include:
1180 * A "dscp" QoS marking which MUST be stamped on notification
1181 messages to differentiate network QoS behavior.
1183 * A "weighting" so that bandwidth proportional to this weighting
1184 can be allocated to this subscription relative to other
1185 subscriptions destined for that receiver.
1187 * a "dependency" upon another subscription. Notification
1188 messages MUST NOT be sent prior to other notification messages
1189 containing update record(s) for the referenced subscription.
1191 o A subscription's weighting MUST work identically to stream
1192 dependency weighting as described within RFC 7540, section 5.3.2.
1194 o A subscription's dependency MUST work identically to stream
1195 dependency as described within RFC 7540, sections 5.3.1, 5.3.3,
1196 and 5.3.4. If a dependency is attempted via an RPC, but the
1197 referenced subscription does not exist, the dependency will be
1198 removed.
1200 4.3. YANG Notifications
1202 4.3.1. State Change Notifications
1204 Subscription state notifications and mechanism are reused from
1205 [subscribe]. Some have been augmented to include the YANG datastore
1206 specific objects.
1208 4.3.2. Notifications for Subscribed Content
1210 Along with the subscribed content, there are other objects which
1211 might be part of a push-update or push-change-update
1213 A subscription-id MUST be transported along with the subscribed
1214 contents. An [RFC5277] Section 4 one-way notification MAY be used
1215 for encoding updates. Where it is, the relevant subscription-id MUST
1216 be encoded as the first element within each push-update or push-
1217 change-update. This allows a receiver to differentiate which
1218 subscription resulted in a particular push.
1220 A "time-of-update" which represents the time an update record
1221 snapshot was generated. A receiver MAY assume that a publisher's
1222 objects have these pushed values at this point in time.
1224 An "updates-not-sent" flag is set, which indicates that the update
1225 record is incomplete. If the application detects an informational
1226 discontinuity in either notification, the notification MUST include a
1227 flag "updates-not-sent". This flag which indicates that not all
1228 changes which have occurred since the last update are actually
1229 included with this update. In other words, the publisher has failed
1230 to fulfill its full subscription obligations. (For example a
1231 datastore missed a window in providing objects to a publisher
1232 process.) To facilitate re-synchronization of on-change
1233 subscriptions, a publisher MAY subsequently send a push-update
1234 containing a full selection snapshot of subscribed data.
1236 4.4. YANG RPCs
1238 YANG-Push subscriptions are established, modified, and deleted using
1239 RPCs augmented from [subscribe].
1241 4.4.1. Establish-subscription RPC
1243 The subscriber sends an establish-subscription RPC with the
1244 parameters in section 3.1. An example might look like:
1246
1248
1250
1251
1252
1255
1256 500
1257 encode-xml
1258
1259
1261 Figure 10: Establish-subscription RPC
1263 The publisher MUST respond explicitly positively (i.e., subscription
1264 accepted) or negatively (i.e., subscription rejected) to the request.
1265 Positive responses include the subscription-id of the accepted
1266 subscription. In that case a publisher MAY respond:
1268
1270
1272 ok
1273
1274
1276 52
1277
1278
1280 Figure 11: Establish-subscription positive RPC response
1282 A subscription can be rejected for multiple reasons, including the
1283 lack of authorization to establish a subscription, the lack of read
1284 authorization on the requested data node, or the inability of the
1285 publisher to provide a stream with the requested semantics.
1287 When the requester is not authorized to read the requested data node,
1288 the returned information indicates the node is unavailable. For
1289 instance, if the above request was unauthorized to read node "ex:foo"
1290 the publisher may return:
1292
1294
1296 subtree-unavailable
1297
1298
1300 /ex:foo
1301
1302
1304 Figure 12: Establish-subscription access denied response
1306 If a request is rejected because the publisher is not able to serve
1307 it, the publisher SHOULD include in the returned error what
1308 subscription parameters would have been accepted for the request.
1309 However, there are no guarantee that subsequent requests using this
1310 info will in fact be accepted.
1312 For example, for the following request:
1314
1316
1318
1319
1320
1323
1324 10
1325 encode-xml
1326
1327
1329 Figure 13: Establish-subscription request example 2
1331 a publisher that cannot serve on-change updates but periodic updates
1332 might return the following:
1334
1336
1338 period-unsupported
1339
1340 100
1341
1343 Figure 14: Establish-subscription error response example 2
1345 4.4.2. Modify-subscription RPC
1347 The subscriber MAY invoke the modify-subscription RPC for a
1348 subscription it previously established. The subscriber will include
1349 newly desired values in the modify-subscription RPC. Parameters not
1350 included MUST remain unmodified. Below is an example where a
1351 subscriber attempts to modify the period of a subscription.
1353
1355
1357
1358
1361
1362
1363 1011
1364
1365 250
1366
1367
1369 Figure 15: Modify subscription request
1371 The publisher MUST respond explicitly positively or negatively to the
1372 request. A response to a successful modification might look like:
1374
1376
1378 ok
1379
1380
1382 Figure 16: Modify subscription response
1384 If the subscription modification is rejected, the publisher MUST send
1385 a response like it does for an establish-subscription and maintain
1386 the subscription as it was before the modification request.
1387 Responses MAY include hints. A subscription MAY be modified multiple
1388 times.
1390 A configured subscription cannot be modified using modify-
1391 subscription RPC. Instead, the configuration needs to be edited as
1392 needed.
1394 4.4.3. Delete-subscription RPC
1396 To stop receiving updates from a subscription and effectively delete
1397 a subscription that had previously been established using an
1398 establish-subscription RPC, a subscriber can send a delete-
1399 subscription RPC, which takes as only input the subscription-id.
1401 Configured subscriptions cannot be deleted via RPC, but have to be
1402 removed from the configuration. This RPC is identical to the RPC
1403 from [subscribe].
1405 4.4.4. Resynch-subscription RPC
1407 This RPC is only applicable only for on-change subscriptions
1408 previously been established using an establish-subscription RPC. On
1409 receipt, a publisher must either reply 'ok' and quickly follow with a
1410 push-update, or send an appropriate error such as on-change-synch-
1411 unsupported. For example:
1413
1415
1417
1418 1011
1419
1420
1421
1423
1425
1427 ok
1428
1429
1431 Resynch subscription
1433 4.4.5. YANG Module Synchronization
1435 To make subscription requests, the subscriber needs to know the YANG
1436 module library available on the publisher. The YANG 1.0 module
1437 library information is sent by a NETCONF server in the NETCONF
1438 'hello' message. For YANG 1.1 modules and all modules used with the
1439 RESTCONF [RFC8040] protocol, this information is provided by the YANG
1440 Library module (ietf-yang-library.yang from [RFC7895]. This YANG
1441 library information is important for the receiver to reproduce the
1442 set of object definitions used within the publisher.
1444 The YANG library includes a module list with the name, revision,
1445 enabled features, and applied deviations for each YANG module
1446 implemented by the publisher. The receiver is expected to know the
1447 YANG library information before starting a subscription. The
1448 "/modules-state/module-set-id" leaf in the "ietf-yang-library" module
1449 can be used to cache the YANG library information.
1451 The set of modules, revisions, features, and deviations can change at
1452 run-time (if supported by the publisher implementation). In this
1453 case, the receiver needs to be informed of module changes before data
1454 nodes from changed modules can be processed correctly. The YANG
1455 library provides a simple "yang-library-change" notification that
1456 informs the subscriber that the library has changed. The receiver
1457 then needs to re-read the entire YANG library data for the replicated
1458 publisher in order to detect the specific YANG library changes. The
1459 "ietf-netconf-notifications" module defined in [RFC6470] contains a
1460 "netconf-capability-change" notification that can identify specific
1461 module changes. For example, the module URI capability of a newly
1462 loaded module will be listed in the "added-capability" leaf-list, and
1463 the module URI capability of an removed module will be listed in the
1464 "deleted-capability" leaf-list.
1466 5. YANG module
1468 ; file "ietf-yang-push.yang"
1469 module ietf-yang-push {
1470 yang-version 1.1;
1471 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push";
1472 prefix yp;
1474 import ietf-inet-types {
1475 prefix inet;
1476 }
1477 import ietf-yang-types {
1478 prefix yang;
1479 }
1480 import ietf-subscribed-notifications {
1481 prefix sn;
1482 }
1483 import ietf-datastores {
1484 prefix ds;
1485 }
1487 organization "IETF";
1488 contact
1489 "WG Web:
1490 WG List:
1492 Editor: Alexander Clemm
1493
1495 Editor: Eric Voit
1496
1498 Editor: Alberto Gonzalez Prieto
1499
1501 Editor: Ambika Prasad Tripathy
1502
1504 Editor: Einar Nilsen-Nygaard
1505
1507 Editor: Andy Bierman
1508
1510 Editor: Balazs Lengyel
1511 ";
1513 description
1514 "This module contains conceptual YANG specifications
1515 for YANG push.";
1517 revision 2017-10-02 {
1518 description
1519 "Initial revision.";
1520 reference
1521 "YANG Datastore Push, draft-ietf-netconf-yang-push-09";
1522 }
1524 /*
1525 * EXTENSIONS
1526 */
1528 extension notifiable-on-change {
1529 argument "value";
1530 description
1531 "Indicates whether changes to the data node are reportable in
1532 on-change subscriptions.
1534 The statement MUST only be a substatement of the leaf, leaf-list,
1535 container, list, anyxml, anydata statements. Zero or One
1536 notifiable-on-change statement is allowed per parent statement.
1537 NO substatements are allowed.
1539 The argument is a boolean value indicating whether on-change
1540 notifications are supported. If notifiable-on-change is not
1541 specified, the default is the same as the parent data node's
1542 value. For top level data nodes the default value is false.";
1543 }
1545 /*
1546 * FEATURES
1547 */
1549 feature on-change {
1550 description
1551 "This feature indicates that on-change triggered subscriptions
1552 are supported.";
1553 }
1555 /*
1556 * IDENTITIES
1557 */
1558 /* Error type identities for datastore subscription */
1559 identity period-unsupported {
1560 base sn:error;
1561 description
1562 "Requested time period is too short. This can be for both
1563 periodic and on-change dampening.";
1564 }
1566 identity qos-unsupported {
1567 base sn:error;
1568 description
1569 "Subscription QoS parameters not supported on this platform.";
1570 }
1572 identity dscp-unavailable {
1573 base sn:error;
1574 description
1575 "Requested DSCP marking not allocatable.";
1576 }
1578 identity on-change-unsupported {
1579 base sn:error;
1580 description
1581 "On-change not supported.";
1582 }
1584 identity on-change-synch-unsupported {
1585 base sn:error;
1586 description
1587 "On-change synch-on-start and resynchonization not supported.";
1588 }
1590 identity reference-mismatch {
1591 base sn:error;
1592 description
1593 "Mismatch in filter key and referenced yang subtree.";
1594 }
1596 identity data-unavailable {
1597 base sn:error;
1598 description
1599 "Referenced yang node or subtree doesn't exist, or read
1600 access is not permitted.";
1601 }
1603 identity datatree-size {
1604 base sn:error;
1605 description
1606 "Resulting periodic or on-change push updates may exceed a size
1607 limit during normal conditions.";
1608 }
1610 identity synchronization-datatree-size {
1611 base sn:error;
1612 description
1613 "The resulting Synch-on-start or resynchronization would push a
1614 datatree which exceeds size limit for a one-time update.";
1615 }
1617 /* Datastore identities */
1619 identity custom-datastore {
1620 base ds:datastore;
1621 description
1622 "A datastore with boundaries not defined within
1623 draft-ietf-netmod-revised-datastores";
1624 }
1626 /*
1627 * TYPE DEFINITIONS
1628 */
1630 typedef change-type {
1631 type enumeration {
1632 enum "create" {
1633 description
1634 "Create a new data resource if it does not already exist. If
1635 it already exists, replace.";
1636 }
1637 enum "delete" {
1638 description
1639 "Delete a data resource if it already exists. If it does not
1640 exists, take no action.";
1641 }
1642 enum "insert" {
1643 description
1644 "Insert a new user-ordered data resource";
1645 }
1646 enum "merge" {
1647 description
1648 "merge the edit value with the target data resource; create
1649 if it does not already exist";
1650 }
1651 enum "move" {
1652 description
1653 "Reorder the target data resource";
1654 }
1655 enum "replace" {
1656 description
1657 "Replace the target data resource with the edit value";
1658 }
1659 enum "remove" {
1660 description
1661 "Remove a data resource if it already exists ";
1662 }
1663 }
1664 description
1665 "Specifies different types of datastore changes.";
1666 reference
1667 "RFC 8072 section 2.5, with a delta that it is ok to receive
1668 ability create on an existing node, or receive a delete on a
1669 missing node.";
1670 }
1672 typedef selection-filter-ref {
1673 type leafref {
1674 path "/sn:filters/yp:selection-filter/yp:identifier";
1675 }
1676 description
1677 "This type is used to reference a selection filter.";
1678 }
1680 /*
1681 * GROUP DEFINITIONS
1682 */
1684 grouping datastore-criteria {
1685 description
1686 "A grouping to define criteria for which selected objects from
1687 a targeted datastore should be included in push updates.";
1688 leaf source {
1689 type identityref {
1690 base ds:datastore;
1691 }
1692 mandatory true;
1693 description
1694 "Datastore from which to retrieve data.";
1695 }
1696 uses selection-filter-objects;
1697 }
1699 grouping selection-filter-types {
1700 description
1701 "This grouping defines a selector for objects from a
1702 datastore.";
1703 choice filter-spec {
1704 description
1705 "The content filter specification for this request.";
1706 anydata subtree-filter {
1707 description
1708 "This parameter identifies the portions of the
1709 target datastore to retrieve.";
1710 reference "RFC 6241, Section 6.";
1711 }
1712 leaf xpath-filter {
1713 type yang:xpath1.0;
1714 description
1715 "This parameter contains an XPath expression identifying the
1716 portions of the target datastore to retrieve.";
1717 reference "http://www.w3.org/TR/1999/REC-xpath-19991116";
1718 }
1719 }
1720 }
1722 grouping selection-filter-objects {
1723 description
1724 "This grouping defines a selector for objects from a
1725 datastore.";
1726 choice selected-content {
1727 description
1728 "The source of the selection filter applied to the subscription.
1729 This will come either referenced from a global list, or be
1730 provided within the subscription itself.";
1731 case by-reference {
1732 description
1733 "Incorporate a filter that has been configured separately.";
1734 leaf selection-filter-ref {
1735 type selection-filter-ref;
1736 mandatory true;
1737 description
1738 "References an existing selection filter which is to be
1739 applied to the subscription.";
1740 }
1741 }
1742 case within-subscription {
1743 description
1744 "Local definition allows a filter to have the same lifecycle
1745 as the subscription.";
1746 uses selection-filter-types;
1748 }
1750 }
1751 }
1753 grouping update-policy-modifiable {
1754 description
1755 "This grouping describes the datastore specific subscription
1756 conditions that can be changed during the lifetime of the
1757 subscription.";
1758 choice update-trigger {
1759 description
1760 "Defines necessary conditions for sending an event to
1761 the subscriber.";
1762 case periodic {
1763 description
1764 "The agent is requested to notify periodically the current
1765 values of the datastore as defined by the selection filter.";
1766 leaf period {
1767 type yang:timeticks;
1768 mandatory true;
1769 description
1770 "Duration of time which should occur between periodic
1771 push updates. Where the anchor-time is
1772 available, the push will include the objects and their
1773 values which exist at an exact multiple of timeticks
1774 aligning to this start-time anchor.";
1775 }
1776 leaf anchor-time {
1777 type yang:date-and-time;
1778 description
1779 "Designates a timestamp before or after which a series of
1780 periodic push updates are determined. The next update will
1781 take place at a whole multiple interval from the anchor
1782 time. For example, for an anchor time is set for the top
1783 of a particular minute and a period interval of a minute,
1784 updates will be sent at the top of every minute this
1785 subscription is active.";
1786 }
1787 }
1788 case on-change {
1789 if-feature "on-change";
1790 description
1791 "The agent is requested to notify changes in values in the
1792 datastore subset as defined by a selection filter.";
1793 leaf dampening-period {
1794 type yang:timeticks;
1795 mandatory true;
1796 description
1797 "The shortest time duration which is allowed between the
1798 creation of independent yang object update messages.
1799 Effectively this is the amount of time that needs to have
1800 passed since the last update. Zero indicates no delay.";
1801 }
1802 }
1803 }
1804 }
1806 grouping update-policy {
1807 description
1808 "This grouping describes the datastore specific subscription
1809 conditions of a subscription.";
1810 uses update-policy-modifiable {
1811 augment "update-trigger/on-change" {
1812 description
1813 "Includes objects not modifiable once subscription is
1814 established.";
1815 leaf no-synch-on-start {
1816 type empty;
1817 description
1818 "This leaf acts as a flag that determines behavior at the
1819 start of the subscription. When present, synchronization
1820 of state at the beginning of the subscription is outside
1821 the scope of the subscription. Only updates about changes
1822 that are observed from the start time, i.e. only push-
1823 change-update notifications are sent. When absent (default
1824 behavior), in order to facilitate a receiver's
1825 synchronization, a full update is sent when the
1826 subscription starts using a push-update notification, just
1827 like in the case of a periodic subscription. After that,
1828 push-change-update notifications only are sent unless the
1829 Publisher chooses to resynch the subscription again.";
1830 }
1831 leaf-list excluded-change {
1832 type change-type;
1833 description
1834 "Use to restrict which changes trigger an update.
1835 For example, if modify is excluded, only creation and
1836 deletion of objects is reported.";
1837 }
1838 }
1839 }
1840 }
1842 grouping update-qos {
1843 description
1844 "This grouping describes Quality of Service information
1845 concerning a subscription. This information is passed to lower
1846 layers for transport prioritization and treatment";
1847 leaf dscp {
1848 type inet:dscp;
1849 default "0";
1850 description
1851 "The push update's IP packet transport priority. This is made
1852 visible across network hops to receiver. The transport
1853 priority is shared for all receivers of a given subscription.";
1854 }
1855 leaf weighting {
1856 type uint8 {
1857 range "0 .. 255";
1858 }
1859 description
1860 "Relative weighting for a subscription. Allows an underlying
1861 transport layer perform informed load balance allocations
1862 between various subscriptions";
1863 reference
1864 "RFC-7540, section 5.3.2";
1865 }
1866 leaf dependency {
1867 type sn:subscription-id;
1868 description
1869 "Provides the Subscription ID of a parent subscription which
1870 has absolute priority should that parent have push updates
1871 ready to egress the publisher. In other words, there should be
1872 no streaming of objects from the current subscription if
1873 the parent has something ready to push.";
1874 reference
1875 "RFC-7540, section 5.3.1";
1876 }
1877 }
1879 grouping update-error-hints {
1880 description
1881 "Allow return additional negotiation hints that apply
1882 specifically to push updates.";
1883 leaf period-hint {
1884 type yang:timeticks;
1885 description
1886 "Returned when the requested time period is too short. This
1887 hint can assert an viable period for both periodic push
1888 cadence and on-change dampening.";
1889 }
1890 leaf error-path {
1891 type string;
1892 description
1893 "Reference to a YANG path which is associated with the error
1894 being returned.";
1895 }
1896 leaf object-count-estimate {
1897 type uint32;
1898 description
1899 "If there are too many objects which could potentially be
1900 returned by the selection filter, this identifies the estimate
1901 of the number of objects which the filter would potentially
1902 pass.";
1903 }
1904 leaf object-count-limit {
1905 type uint32;
1906 description
1907 "If there are too many objects which could be returned by the
1908 selection filter, this identifies the upper limit of the
1909 publisher's ability to service for this subscription.";
1910 }
1911 leaf kilobytes-estimate {
1912 type uint32;
1913 description
1914 "If the returned information could be beyond the capacity of
1915 the publisher, this would identify the data size which could
1916 result from this selection filter.";
1917 }
1918 leaf kilobytes-limit {
1919 type uint32;
1920 description
1921 "If the returned information would be beyond the capacity of
1922 the publisher, this identifies the upper limit of the
1923 publisher's ability to service for this subscription.";
1924 }
1925 }
1927 /*
1928 * RPCs
1929 */
1931 rpc resynch-subscription {
1932 if-feature "on-change";
1933 description
1934 "This RPC allows a subscriber of an active on-change
1935 subscription to request a full push of objects in there current
1936 state. A successful result would be the set of YANG objects
1937 equivalent to a Get using the existing selection criteria. This
1938 request may only come from the same subscriber using the
1939 establish-subscription RPC.";
1940 input {
1941 leaf identifier {
1942 type sn:subscription-id;
1943 mandatory true;
1944 description
1945 "Identifier of the subscription that is to be resynched.";
1946 }
1947 }
1948 output {
1949 leaf subscription-result {
1950 type sn:subscription-result;
1951 mandatory true;
1952 description
1953 "Indicates whether the request for the subscription resynch
1954 has been accepted, or why it has been denied.";
1955 }
1956 }
1957 }
1959 /*
1960 * DATA NODES
1961 */
1963 augment "/sn:establish-subscription/sn:input" {
1964 description
1965 "This augmentation adds additional subscription parameters that
1966 apply specifically to datastore updates to RPC input.";
1967 uses update-policy;
1968 uses update-qos;
1969 }
1970 augment "/sn:establish-subscription/sn:input/sn:target" {
1971 description
1972 "This augmentation adds the datastore as a valid parameter object
1973 for the subscription to RPC input. This provides a target for
1974 the filter.";
1975 case datastore {
1976 uses datastore-criteria;
1977 }
1978 }
1979 augment "/sn:establish-subscription/sn:output/"+
1980 "sn:result/sn:no-success" {
1981 description
1982 "This augmentation adds datastore specific error info
1983 and hints to RPC output.";
1984 uses update-error-hints;
1985 }
1986 augment "/sn:modify-subscription/sn:input" {
1987 description
1988 "This augmentation adds additional subscription parameters
1989 specific to datastore updates.";
1991 uses update-policy-modifiable;
1992 }
1993 augment "/sn:modify-subscription/sn:input/sn:target" {
1994 description
1995 "This augmentation adds the datastore as a valid parameter object
1996 for the subscription to RPC input. This provides a target for
1997 the filter.";
1998 case datastore {
1999 uses selection-filter-objects;
2000 }
2001 }
2002 augment "/sn:modify-subscription/sn:output/"+
2003 "sn:result/sn:no-success" {
2004 description
2005 "This augmentation adds push datastore error info and hints to
2006 RPC output.";
2007 uses update-error-hints;
2008 }
2010 notification push-update {
2011 description
2012 "This notification contains a push update, containing data
2013 subscribed to via a subscription. This notification is sent for
2014 periodic updates, for a periodic subscription. It can also be
2015 used for synchronization updates of an on-change subscription.
2016 This notification shall only be sent to receivers of a
2017 subscription; it does not constitute a general-purpose
2018 notification.";
2019 leaf subscription-id {
2020 type sn:subscription-id;
2021 description
2022 "This references the subscription which drove the notification
2023 to be sent.";
2024 }
2025 leaf time-of-update {
2026 type yang:date-and-time;
2027 description
2028 "This leaf identifies the generation time of the datastore
2029 selection within a push-update.";
2030 }
2031 leaf updates-not-sent {
2032 type empty;
2033 description
2034 "This is a flag which indicates that not all data nodes
2035 subscribed to are included with this update. In other words,
2036 the publisher has failed to fulfill its full subscription
2037 obligations. The result is intermittent loss of
2038 synchronization of data at the receiver.";
2040 }
2041 anydata datastore-contents {
2042 description
2043 "This contains the updated data. It constitutes a snapshot
2044 at the time-of-update of the set of data that has been
2045 subscribed to. The format and syntax of the data
2046 corresponds to the format and syntax of data that would be
2047 returned in a corresponding get operation with the same
2048 selection filter parameters applied.";
2049 }
2050 }
2052 notification push-change-update {
2053 if-feature "on-change";
2054 description
2055 "This notification contains an on-change push update. This
2056 notification shall only be sent to the receivers of a
2057 subscription; it does not constitute a general-purpose
2058 notification.";
2059 leaf subscription-id {
2060 type sn:subscription-id;
2061 description
2062 "This references the subscription which drove the notification
2063 to be sent.";
2064 }
2065 leaf time-of-update {
2066 type yang:date-and-time;
2067 description
2068 "This leaf identifies the generation time of the datastore
2069 changes extract. If a dampening-period was in effect before
2070 the notification was generated, this may not be the time any of
2071 the datastore-changes were actually made.";
2072 }
2073 leaf updates-not-sent {
2074 type empty;
2075 description
2076 "This is a flag which indicates that not all changes which
2077 have occurred since the last update are included with this
2078 update. In other words, the publisher has failed to
2079 fulfill its full subscription obligations, for example in
2080 cases where it was not able to keep up with a change burst.";
2081 }
2082 anydata datastore-changes {
2083 description
2084 "This contains an incremental set of datastore changes needed
2085 to update a remote datastore starting at the time of the
2086 previous update, per the terms of the subscription. Changes
2087 are encoded analogous to the syntax of a corresponding yang-
2088 patch operation, i.e. a yang-patch operation applied to the
2089 YANG datastore implied by the previous update to result in the
2090 current state.";
2091 reference
2092 "RFC 8072 section 2.5, with a delta that it is ok to receive
2093 ability create on an existing node, or receive a delete on a
2094 missing node.";
2095 }
2096 }
2098 augment "/sn:subscription-started" {
2099 description
2100 "This augmentation adds many yang datastore specific objects to
2101 the notification that a subscription has started.";
2102 uses update-policy;
2103 uses update-qos;
2104 }
2105 augment "/sn:subscription-started/sn:target" {
2106 description
2107 "This augmentation allows the datastore to be included as part
2108 of the notification that a subscription has started.";
2109 case datastore {
2110 uses datastore-criteria;
2111 }
2112 }
2113 augment "/sn:filters" {
2114 description
2115 "This augmentation allows the datastore to be included as part
2116 of the selection filtering criteria for a subscription.";
2117 list selection-filter {
2118 key "identifier";
2119 description
2120 "A list of pre-positioned filters that can be applied
2121 to datastore subscriptions.";
2122 leaf identifier {
2123 type sn:filter-id;
2124 description
2125 "An identifier to differentiate between selection filters.";
2126 }
2127 uses selection-filter-types;
2128 }
2129 }
2130 augment "/sn:subscription-modified" {
2131 description
2132 "This augmentation adds many yang datastore specific objects to
2133 the notification that a subscription has been modified.";
2134 uses update-policy;
2135 uses update-qos;
2137 }
2138 augment "/sn:subscription-modified/sn:target" {
2139 description
2140 "This augmentation allows the datastore to be included as part
2141 of the notification that a subscription has been modified.";
2142 case datastore {
2143 uses datastore-criteria;
2144 }
2145 }
2146 augment "/sn:subscription-config/sn:subscription" {
2147 description
2148 "This augmentation adds many yang datastore specific objects
2149 which can be configured as opposed to established via RPC.";
2150 uses update-policy;
2151 uses update-qos;
2152 }
2153 augment "/sn:subscription-config/sn:subscription/sn:target" {
2154 description
2155 "This augmentation adds the datastore to the selection filtering
2156 criteria for a subscription.";
2157 case datastore {
2158 uses datastore-criteria;
2159 }
2160 }
2161 augment "/sn:subscriptions/sn:subscription" {
2162 yp:notifiable-on-change true;
2163 description
2164 "This augmentation adds many datastore specific objects to a
2165 subscription.";
2166 uses update-policy;
2167 uses update-qos;
2168 }
2169 augment "/sn:subscriptions/sn:subscription/sn:target" {
2170 description
2171 "This augmentation allows the datastore to be included as part
2172 of the selection filtering criteria for a subscription.";
2173 case datastore {
2174 uses datastore-criteria;
2175 }
2176 }
2178 /* YANG Parser Pyang crashing on syntax below, due to fixed bug
2179 https://github.com/mbj4668/pyang/issues/300
2181 deviation "/sn:subscriptions/sn:subscription/sn:receivers/"
2182 + "sn:receiver/sn:pushed-notifications" {
2183 deviate add {
2184 yp:notifiable-on-change false;
2186 }
2187 }
2188 deviation "/sn:subscriptions/sn:subscription/sn:receivers/"
2189 + "sn:receiver/sn:excluded-notifications" {
2190 deviate add {
2191 yp:notifiable-on-change false;
2192 }
2193 }
2194 YANG Parser Pyang crashing on syntax above */
2195 }
2197
2199 6. IANA Considerations
2201 This document registers the following namespace URI in the "IETF XML
2202 Registry" [RFC3688]:
2204 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push
2205 Registrant Contact: The IESG.
2206 XML: N/A; the requested URI is an XML namespace.
2208 This document registers the following YANG module in the "YANG Module
2209 Names" registry [RFC6020]:
2211 Name: ietf-yang-push
2212 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push
2213 Prefix: yp
2214 Reference: draft-ietf-netconf-yang-push-08.txt (RFC form)
2216 7. Security Considerations
2218 All security considerations from [subscribe] are relevant for
2219 datastores. In addition there are specific security considerations
2220 for receivers defined in Section 3.9
2222 If the access control permissions on subscribed YANG nodes change
2223 during the lifecycle of a subscription, a publisher MUST either
2224 transparently conform to the new access control permissions, or must
2225 terminate or restart the subscriptions so that new access control
2226 permissions are re-established.
2228 The NETCONF Authorization Control Model SHOULD be used to restrict
2229 the delivery of YANG nodes for which the receiver has no access.
2231 8. Acknowledgments
2233 For their valuable comments, discussions, and feedback, we wish to
2234 acknowledge Tim Jenkins, Kent Watsen, Susan Hares, Yang Geng, Peipei
2235 Guo, Michael Scharf, Sharon Chisholm, and Guangying Zheng.
2237 9. References
2239 9.1. Normative References
2241 [revised-datastores]
2242 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
2243 and R. Wilton, "Network Management Datastore
2244 Architecture", draft-ietf-netmod-revised-datastores-04
2245 (work in progress), August 2017.
2247 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
2248 DOI 10.17487/RFC3688, January 2004,
2249 .
2251 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
2252 the Network Configuration Protocol (NETCONF)", RFC 6020,
2253 DOI 10.17487/RFC6020, October 2010,
2254 .
2256 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF)
2257 Base Notifications", RFC 6470, DOI 10.17487/RFC6470,
2258 February 2012, .
2260 [RFC6536bis]
2261 Bierman, A. and M. Bjorklund, "Network Configuration
2262 Protocol (NETCONF) Access Control Model", draft-ietf-
2263 netconf-rfc6536bis-05 (work in progress), September 2017.
2265 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
2266 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016,
2267 .
2269 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
2270 RFC 7950, DOI 10.17487/RFC7950, August 2016,
2271 .
2273 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG",
2274 RFC 7951, DOI 10.17487/RFC7951, August 2016,
2275 .
2277 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch
2278 Media Type", RFC 8072, DOI 10.17487/RFC8072, February
2279 2017, .
2281 [subscribe]
2282 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A.,
2283 and E. Nilsen-Nygaard, "Custom Subscription to Event
2284 Notifications", draft-ietf-netconf-subscribed-
2285 notifications-04 (work in progress), September 2017.
2287 9.2. Informative References
2289 [netconf-notif]
2290 Gonzalez Prieto, A., Clemm, A., Voit, E., Nilsen-Nygaard,
2291 E., and A. Tripathy, "NETCONF Support for Event
2292 Notifications", September 2017.
2294 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
2295 Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
2296 .
2298 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
2299 and A. Bierman, Ed., "Network Configuration Protocol
2300 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
2301 .
2303 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface
2304 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014,
2305 .
2307 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements
2308 for Subscription to YANG Datastores", RFC 7923,
2309 DOI 10.17487/RFC7923, June 2016,
2310 .
2312 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2313 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
2314 .
2316 Appendix A. Changes between revisions
2318 (To be removed by RFC editor prior to publication)
2320 v09 - v10
2322 o Returned to the explicit filter subtyping of v00-v05
2324 o identityref to ds:datastore made explicit
2325 o Returned ability to modify a selection filter via RPC.
2327 v08 - v09
2329 o Minor tweaks cleaning up text, removing appendicies, and making
2330 reference to revised-datastores.
2332 o Subscription-id optional in push updates, except when encoded in
2333 RFC5277, Section 4 one-way notification.
2335 o Finished adding the text descibing the resynch subscription RPC.
2337 o Removed relationships to other drafts and future technology
2338 appendicies as this work is being explored elsewhere.
2340 o Deferred the multi-line card issue to new drafts
2342 o Simplified the NACM interactions.
2344 v07 - v08
2346 o Updated YANG models with minor tweaks to accommodate changes of
2347 ietf-subscribed-notifications.
2349 v06 - v07
2351 o Clarifying text tweaks.
2353 o Clarification that filters act as selectors for subscribed data
2354 nodes; support for value filters not included but possible as a
2355 future extension
2357 o Filters don't have to be matched to existing YANG objects
2359 v05 - v06
2361 o Security considerations updated.
2363 o Base YANG model in [subscribe] updated as part of move to
2364 identities, YANG augmentations in this doc matched up
2366 o Terms refined and text updates throughout
2368 o Appendix talking about relationship to other drafts added.
2370 o Datastore replaces stream
2372 o Definitions of filters improved
2373 v04 to v05
2375 o Referenced based subscription document changed to Subscribed
2376 Notifications from 5277bis.
2378 o Getting operational data from filters
2380 o Extension notifiable-on-change added
2382 o New appendix on potential futures. Moved text into there from
2383 several drafts.
2385 o Subscription configuration section now just includes changed
2386 parameters from Subscribed Notifications
2388 o Subscription monitoring moved into Subscribed Notifications
2390 o New error and hint mechanisms included in text and in the yang
2391 model.
2393 o Updated examples based on the error definitions
2395 o Groupings updated for consistency
2397 o Text updates throughout
2399 v03 to v04
2401 o Updates-not-sent flag added
2403 o Not notifiable extension added
2405 o Dampening period is for whole subscription, not single objects
2407 o Moved start/stop into rfc5277bis
2409 o Client and Server changed to subscriber, publisher, and receiver
2411 o Anchor time for periodic
2413 o Message format for synchronization (i.e. synch-on-start)
2415 o Material moved into 5277bis
2417 o QoS parameters supported, by not allowed to be modified by RPC
2419 o Text updates throughout
2421 Authors' Addresses
2423 Alexander Clemm
2424 Huawei
2426 Email: ludwig@clemm.org
2428 Eric Voit
2429 Cisco Systems
2431 Email: evoit@cisco.com
2433 Alberto Gonzalez Prieto
2434 VMware
2436 Email: agonzalezpri@vmware.com
2438 Ambika Prasad Tripathy
2439 Cisco Systems
2441 Email: ambtripa@cisco.com
2443 Einar Nilsen-Nygaard
2444 Cisco Systems
2446 Email: einarnn@cisco.com
2448 Andy Bierman
2449 YumaWorks
2451 Email: andy@yumaworks.com
2453 Balazs Lengyel
2454 Ericsson
2456 Email: balazs.lengyel@ericsson.com