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