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