idnits 2.17.1
draft-ietf-netconf-yang-push-08.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** There are 8 instances of too long lines in the document, the longest one
being 9 characters in excess of 72.
** The document seems to lack a both a reference to RFC 2119 and the
recommended RFC 2119 boilerplate, even if it appears to use RFC 2119
keywords.
RFC 2119 keyword, line 253: '...cription request SHOULD be declined ba...'
RFC 2119 keyword, line 262: '... subscriptions SHOULD support a simp...'
RFC 2119 keyword, line 265: '...-success message SHOULD include in the...'
RFC 2119 keyword, line 292: '... MAY accept an on-change subscriptio...'
RFC 2119 keyword, line 303: '...tively, a server MAY decide to simply ...'
(43 more instances...)
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Line 814 has weird spacing: '...er-type eve...'
== Line 825 has weird spacing: '...er-type sel...'
== Line 871 has weird spacing: '...er-type sel...'
== Line 919 has weird spacing: '...er-type sel...'
== Line 972 has weird spacing: '...-period yan...'
== (9 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 (August 20, 2017) is 2433 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 2223, but no explicit
reference was found in the text
== Outdated reference: A later version (-09) exists of
draft-ietf-netconf-rfc6536bis-04
-- 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: 3 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: February 21, 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 August 20, 2017
17 Subscribing to YANG datastore push updates
18 draft-ietf-netconf-yang-push-08
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 http://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 February 21, 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 (http://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 . . . . . . . . . . . . . . . . . . . . . . 5
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 . . . . . . . . . . . . . . 8
81 3.5. Data Encodings . . . . . . . . . . . . . . . . . . . . . 8
82 3.6. Datastore filters . . . . . . . . . . . . . . . . . . . . 9
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 . . . . . . . . . . . . 15
87 3.11. Other considerations . . . . . . . . . . . . . . . . . . 16
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 . . . . . . . . . . . . . . . . . . . 25
93 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 26
94 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 31
95 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46
96 7. Security Considerations . . . . . . . . . . . . . . . . . . . 46
97 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 47
98 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 47
99 9.1. Normative References . . . . . . . . . . . . . . . . . . 47
100 9.2. Informative References . . . . . . . . . . . . . . . . . 48
101 Appendix A. Relationships to other drafts . . . . . . . . . . . 48
102 A.1. ietf-netconf-subscribed-notifications . . . . . . . . . . 49
103 A.2. ietf-netconf-netconf-event-notif . . . . . . . . . . . . 49
104 A.3. ietf-netconf-restconf-notif . . . . . . . . . . . . . . . 49
105 A.4. voit-notifications2 . . . . . . . . . . . . . . . . . . . 49
106 Appendix B. Technologies to be considered for future iterations 50
107 B.1. Proxy YANG Subscription when the Subscriber and Receiver
108 are different . . . . . . . . . . . . . . . . . . . . . . 50
109 B.2. OpState and Filters . . . . . . . . . . . . . . . . . . . 50
110 B.3. Splitting push updates . . . . . . . . . . . . . . . . . 51
111 B.4. Potential Subscription Parameters . . . . . . . . . . . . 52
112 Appendix C. Changes between revisions . . . . . . . . . . . . . 52
113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 54
115 1. Introduction
117 Traditional approaches to remote visibility have been built on
118 polling. With polling, data is periodically requested and retrieved
119 by a client from a server to stay up-to-date. However, there are
120 issues associated with polling-based management:
122 o Polling incurs significant latency. This latency prohibits many
123 application types.
125 o Polling cycles may be missed, requests may be delayed or get lost,
126 often when the network is under stress and the need for the data
127 is the greatest.
129 o Polling requests may undergo slight fluctuations, resulting in
130 intervals of different lengths. The resulting data is difficult
131 to calibrate and compare.
133 o For applications that monitor for changes, many remote polling
134 cycles place ultimately fruitless load on the network, devices,
135 and applications.
137 A more effective alternative to polling is for an application to
138 receive automatic and continuous updates from a targeted subset of a
139 datastore. Accordingly, there is a need for a service that allows
140 applications to subscribe to updates from a YANG datastore and that
141 enables the publisher to push and in effect stream those updates.
142 The requirements for such a service have been documented in
143 [RFC7923].
145 This document defines a corresponding solution that is built on top
146 of "Custom Subscription to Event Notifications" [subscribe].
147 Supplementing that work are YANG data model augmentations, extended
148 RPCs, and new datastore specific update notifications. Transport
149 options for [subscribe] will work seamlessly with this solution.
151 2. Definitions and Acronyms
153 The terms below supplement those defined in [subscribe].
155 Data node: An instance of management information in a YANG datastore.
157 Data node update: A data item containing the current value/property
158 of a Data node at the time the data node update was created.
160 Datastore: A conceptual store of instantiated management information,
161 with individual data items represented by data nodes which are
162 arranged in hierarchical manner.
164 Data subtree: An instantiated data node and the data nodes that are
165 hierarchically contained within it.
167 Notification message: A transport encapsulated update record(s) and/
168 or event notification(s) intended to be sent to a receiver.
170 Update notification message: A notification message that contains an
171 update record.
173 Update record: A representation data node update(s) resulting from
174 the application of a filter for a subscription. An update record
175 will include the value/property of one or more data nodes at a point
176 in time. It may contain the update type for each data node (e.g.,
177 add, change, delete). Also included may be metadata/headers such as
178 a subscription-id.
180 Update trigger: A mechanism that determines when an update record
181 needs to be generated.
183 YANG-Push: The subscription and push mechanism for YANG datastores
184 that is specified in this document.
186 3. Solution Overview
188 This document specifies a solution for a push update subscription
189 service. This solution supports the dynamic as well as configured
190 subscriptions to information updates from YANG datastores.
191 Subscriptions specify when update notification messages should be
192 sent and what data to include in update records. YANG objects are
193 subsequently pushed from the publisher to the receiver per the terms
194 of the subscription.
196 3.1. Event Subscription Model
198 YANG-push subscriptions are defined using a data model that is itself
199 defined in YANG. This model enhances the event subscription model
200 defined in [subscribe] with capabilities that allow subscribers to
201 subscribe to data node updates, specifically to specify the triggers
202 when to generate update records as well as what to include in an
203 update record. Key enhancements include:
205 o Specification of selection filters which identify targeted YANG
206 data nodes and/or subtrees within a datastore for which updates
207 are to be pushed.
209 o An encoding (using anydata) for the contents of periodic and on-
210 change push updates.
212 o Specification of update policies that specify the conditions that
213 trigger the generation and pushing of new update records. There
214 are two types of subscriptions, periodic and on-change.
216 * For periodic subscriptions, the trigger is specified by two
217 parameters that define when updates are to be pushed. These
218 parameters are the period interval with which to report
219 updates, and an anchor time which can be used to calculate at
220 which point in time updates need to be assembled and sent.
222 * For on-change subscriptions, a trigger occurs whenever a change
223 in the subscribed information is detected. Included are
224 additional parameters such as:
226 + Dampening period: In an on-change subscription, the first
227 change that is detected results in an update to be sent
228 immediately. However, sending successive updates whenever
229 further changes are detected might result in quick
230 exhaustion of resources in case of very rapid changes. In
231 order to protect against that, a dampening period is used to
232 specify the interval which must pass before successive
233 update records for the same subscription are generated. The
234 dampening period collectively applies to the set of all data
235 nodes of a single subscription. This means that on change
236 of an object being subscribed to, an update record
237 containing that object is created either immediately when no
238 dampening period is already in effect, or at the end of a
239 dampening period.
241 + Change type: This parameter can be used to reduce the types
242 of datastore changes for which updates are sent (e.g., you
243 might only send when an object is created or deleted, but
244 not when an object value changes).
246 + No Synch on start: defines whether or not a complete push-
247 update of all subscribed data will be sent at the beginning
248 of a subscription. Such synchronization establishes the
249 frame of reference for subsequent updates.
251 3.2. Negotiation of Subscription Policies
253 A dynamic subscription request SHOULD be declined based on
254 publisher's assessment that it may be unable to provide update
255 records that would meet the terms of the request. However a
256 subscriber may quickly follow up with a new subscription request
257 using different parameters.
259 Random guessing at different parameters by a subscriber is to be
260 discouraged. Therefore, in order to minimize the number of
261 subscription iterations between subscriber and publisher, dynamic
262 subscriptions SHOULD support a simple negotiation between subscribers
263 and publishers for subscription parameters. This negotiation is in
264 the form of a no-success response to a failed establish or modify
265 subscription request. The no-success message SHOULD include in the
266 returned error response information that, when considered, increases
267 the likelihood of success for subsequent requests. However, there
268 are no guarantees that subsequent requests for this subscriber will
269 in fact be accepted.
271 Such negotiation information returned from a publisher beyond that
272 from [subscribe] includes hints at acceptable time intervals, size
273 estimates for the number or objects which would be returned from a
274 filter, and the names of targeted objects not found in the
275 publisher's YANG tree.
277 3.3. On-Change Considerations
279 On-change subscriptions allow subscribers to subscribe to updates
280 whenever changes to objects occur. As such, on-change subscriptions
281 are particularly effective for data that changes infrequently, yet
282 that requires applications to be notified whenever a change does
283 occur with minimal delay.
285 On-change subscriptions tend to be more difficult to implement than
286 periodic subscriptions. Accordingly, on-change subscriptions may not
287 be supported by all implementations or for every object.
289 Whether or not to accept or reject on-change subscription requests
290 when the scope of the subscription contains objects for which on-
291 change is not supported is up to the server implementation: A server
292 MAY accept an on-change subscription even when the scope of the
293 subscription contains objects for which on-change is not supported.
294 In that case, updates are sent only for those objects within the
295 scope that do support on-change updates whereas other objects are
296 excluded from update records, whether or not their values actually
297 change. In order for a client to determine whether objects support
298 on-change subcriptions, objects are marked accordingly by a server.
299 Accordingly, when subscribing, it is the responsibility of the client
300 to ensure it is aware of which objects support on-change and which do
301 not. For more on how objects are so marked, see Section 3.10.
303 Alternatively, a server MAY decide to simply reject an on-change
304 subscription in case the scope of the subscription contains objects
305 for which on-change is not supported. In case of a configured
306 subscription, the subsription can be marked as suspended respectively
307 inoperational.
309 To avoid flooding receivers with repeated updates for subscriptions
310 containing fast-changing objects, or objects with oscillating values,
311 an on-change subscription allows for the definition of a dampening
312 period. Once an update record for a given object is generated, no
313 other updates for this particular subscription will be created until
314 the end of the dampening period. Values sent at the end of the
315 dampening period are the current values of all changed objects which
316 are current at the time the dampening period expires. Changed
317 objects includes those which were deleted or newly created during
318 that dampening period. If an object has returned to its original
319 value (or even has been created and then deleted) during the
320 dampening-period, the last change will still be sent. This will
321 indicate churn is occuring on that object.
323 In cases where a client wants to have separate dampening periods for
324 different objects, multiple subscriptions with different objects in
325 subscription scope can be created.
327 On-change subscriptions can be refined to let users subscribe only to
328 certain types of changes, for example, only to object creations and
329 deletions, but not to modifications of object values.
331 3.4. Promise-Theory Considerations
333 A subscription to updates from a YANG datastore is intended to
334 obviate the need for polling. However, in order to do so, it is of
335 utmost importance that subscribers can rely on the subscription and
336 have confidence that they will indeed receive the subscribed updates
337 without having to worry updates being silently dropped. In other
338 words, a subscription constitutes a promise on the side of the server
339 to provide the receivers with updates per the terms of the
340 subscription.
342 Now, there are many reasons why a server may at some point no longer
343 be able to fulfill the terms of the subscription, even if the
344 subscription had been entered into with good faith. For example, the
345 volume of data objects may be larger than anticipated, the interval
346 may prove too short to send full updates in rapid succession, or an
347 internal problem may prevent updates from being collected. If for
348 some reason the server of a subscription is not able to keep its
349 promise, receivers MUST be notified immediately and reliably. The
350 server MUST also update the state of the subscription to indicate
351 that the subscription is in a detrimental state.
353 A server SHOULD reject a request for a subscription if it is unlikely
354 that the server will be able fulfill the terms of the subscription.
355 In such cases, it is preferable to have a client request another
356 subscription that is less resource intensive (for example, a
357 subscription with longer periodic update intervals), than to
358 subsequently frustrate the receiver with `frequent subscription
359 suspensions.
361 3.5. Data Encodings
363 Subscribed data is encoded in either XML or JSON format. A publisher
364 MUST support XML encoding and MAY support JSON encoding.
366 3.5.1. Periodic Subscriptions
368 In a periodic subscription, the data included as part of an update
369 corresponds to data that could have been simply retrieved using a get
370 operation and is encoded in the same way. XML encoding rules for
371 data nodes are defined in [RFC7950]. JSON encoding rules are defined
372 in [RFC7951].
374 3.5.2. On-Change Subscriptions
376 In an on-change subscription, updates need to indicate not only
377 values of changed data nodes but also the types of changes that
378 occurred since the last update. Therefore encoding rules for data in
379 on-change updates will follow YANG-patch operation as specified in
380 [RFC8072]. The YANG-patch will describe what needs to be applied to
381 the earlier state reported by the preceding update, to result in the
382 now-current state. Note that contrary to [RFC8072], objects
383 encapsulated are not restricted to configuration objects only.
385 3.6. Datastore filters
387 Subscription policy specifies both the filters and the datastores
388 against which the filters will be applied. The result is the push of
389 information necessary to remotely maintain an extract of publisher's
390 datastore.
392 Only a single filter can be applied to a subscription at a time. The
393 following selection filter types are included in the yang-push data
394 model, and may be applied against a datastore:
396 o subtree: A subtree filter identifies one or more subtrees. When
397 specified, updates will only come from the data nodes of selected
398 YANG subtree(s). The syntax and semantics correspond to that
399 specified for [RFC6241] section 6.
401 o xpath: An xpath filter is an XPath expression which may be
402 meaningfully applied to a datastore. It is the results of this
403 expression which will be pushed.
405 Filters are intended to be used as selectors that define which
406 objects are within the scope of a subscription. Filters are not
407 intended to be used to store objects based on their current value.
408 Doing so would have a number of implications that would result in
409 significant additional complexity. For example, withough extending
410 encodings for on-change subscriptions, a receiver would not be able
411 to distinguish cases in which an object is no longer included in an
412 update because it was deleted, as opposed to its value simply no
413 longer meeting the filter criteria. While it is possible to define
414 extensions in the future that will support filtering based on values,
415 this is not supported in this version of yang-push and a server MAY
416 reject a subscription request that contains a filter for object
417 values.
419 Xpath itself provides powerful filtering constructs, and care must be
420 used in filter definition. As an example, consider an xpath filter
421 with a boolean result; such a result will not provide an easily
422 interpretable subset of a datastore. Beyond the boolean example, it
423 is quite possible to define an xpath filter where results are easy
424 for an application to mis-interpret. Consider an xpath filter which
425 only passes a datastore object when interface=up. It is up to the
426 receiver to understand implications of the presence or absence of
427 objects in each update.
429 It is not expected that implementations will support comprehensive
430 filter syntax and boundless complexity. It will be up to
431 implementations to describe what is viable, but the goal is to
432 provide equivalent capabilities to what is available with a GET.
433 Implementations MUST reject dynamic subscriptions or suspend
434 configured subscriptions if they include filters which are
435 unsupportable on a platform.
437 3.7. Streaming updates
439 Contrary to traditional data retrieval requests, datastore
440 subscription enables an unbounded series of update records to be
441 streamed over time. Two generic notifications for update records
442 have been defined for this: "push-update" and "push-change-update".
444 A push-update notification defines a complete, filtered update of the
445 datastore per the terms of a subscription. This type of notification
446 is used for continuous updates of periodic subscriptions. A push-
447 update notification can also used be for the on-change subscriptions
448 in two cases. First it will be used as the initial push-update if
449 there is a need to synchronize the receiver at the start of a new
450 subscription. It also MAY be sent if the publisher later chooses to
451 resynch an on-change subscription. The push-update record contains a
452 data snippet that contains an instantiated subtree with the
453 subscribed contents. The content of the update record is equivalent
454 to the contents that would be obtained had the same data been
455 explicitly retrieved using e.g., a NETCONF "get" operation, with the
456 same filters applied.
458 A push-change-update notification is the most common type of update
459 for on-change subscriptions. The update record in this case contains
460 a data snippet that indicates the set of changes that data nodes have
461 undergone since the last notification of YANG objects. In other
462 words, this indicates which data nodes have been created, deleted, or
463 have had changes to their values. In cases where multiple changes
464 have occurred and the object has not been deleted, the object's most
465 current value is reported. (In other words, for each object, only
466 one change is reported, not its entire history. Doing so would
467 defeat the purpose of the dampening period.)
469 These new YANG notifications are encoded and placed within
470 notification messages, which are then queued for egress over the
471 specified transport. The following is an example of an XML encoded
472 notification message over NETCONF transport as per [netconf-notif].
474
476 2015-03-09T19:14:56Z
477
479 1011
480 2015-03-09T19:14:56.233Z
481
482
483 some_string
484
485
486
487
489 Figure 1: Push example
491 The following is an example of an on-change notification. It
492 contains an update for subscription 89, including a new value for a
493 leaf called beta, which is a child of a top-level container called
494 alpha:
496
498 2015-03-09T19:14:56Z
499
501 89
502 2015-03-09T19:14:56.233Z
503
504
505 1500
506
507
508
509
511 Figure 2: Push example for on change
513 The equivalent update when requesting json encoding:
515
517 2015-03-09T19:14:56Z
518
520 89
521 2015-03-09T19:14:56.233Z
522
523 {
524 "ietf-yang-patch:yang-patch": {
525 "patch-id": [
526 null
527 ],
528 "edit": [
529 {
530 "edit-id": "edit1",
531 "operation": "merge",
532 "target": "/alpha/beta",
533 "value": {
534 "beta": 1500
535 }
536 }
537 ]
538 }
539 }
540
541
542
544 Figure 3: Push example for on change with JSON
546 When the beta leaf is deleted, the publisher may send
547
549 2015-03-09T19:14:56Z
550
552 89
553 2015-03-09T19:14:56.233Z
554
555
556
558
559
560
561
563 Figure 4: 2nd push example for on change update
565 3.8. Subscription management
567 [subscribe] has been enhanced to support YANG datastore subscription
568 negotiation. These enhancements provide information on why a
569 datastore subscription attempt has failed.
571 A datastore subscription can be rejected for multiple reasons. This
572 includes the lack of read authorization on a requested data node, or
573 the inability of the publisher push update records as frequently as
574 requested. In such cases, no subscription is established. Instead,
575 the subscription-result with the failure reason is returned as part
576 of the RPC response. As part of this response, a set of alternative
577 subscription parameters MAY be returned that would likely have
578 resulted in acceptance of the subscription request. The subscriber
579 may consider these as part of future subscription attempts.
581 It should be noted that a rejected subscription does not result in
582 the generation of an rpc-reply with an rpc-error element, as neither
583 the specification of YANG-push specific errors nor the specification
584 of additional data parameters to be returned in an error case are
585 supported as part of a YANG data model.
587 For instance, for the following request:
589
591
593 push-update
594
597 500
598 encode-xml
599
600
602 Figure 5: Establish-Subscription example
604 the publisher might return:
606
608
610 error-insufficient-resources
611
612 2000
613
615 Figure 6: Error response example
617 3.9. Receiver Authorization
619 A receiver of subscription data MUST only be sent updates for which
620 they have proper authorization. A server MUST ensure that no non-
621 authorized data is included in push updates. To do so, it needs to
622 apply all corresponding checks applicable at the time of a specific
623 pushed update and if necessary silently remove any non-authorized
624 data from subtrees. This enables YANG data pushed based on
625 subscriptions to be authorized equivalently to a regular data
626 retrieval (get) operation.
628 Alternatively, a server that wants to avoid having to perform
629 filtering of authorized content on each update MAY instead simply
630 reject a subscription request that contains non-authorized data. It
631 MAY subsequently suspend a subscription in case new objects are
632 created during the course of the subscription for which the receiver
633 does not have the necessary authorization, or in case the
634 authorization privileges of a receiver change over the course of the
635 subscription.
637 The contextual authorization model for data in YANG datastores is the
638 NETCONF Access Control Model [RFC6536bis], Section 3.2.3. However,
639 there are some differences.
641 One of these clarifications is that datastore selection MUST NOT
642 return continuous errors as part of an on-change subscription. This
643 includes errors such as when there is not read access to every data
644 node specifically named within the filter. Non-authorized data needs
645 to be either simply dropped or, alternatively, the subscription
646 SHOULD be suspended.
648 +-------------+ +-------------+
649 establish / | protocol | | filter |
650 modify --> | operation | -------------> | data node |
651 subscription | allowed? | datastore | access |
652 +-------------+ objects | allowed? |
653 +-------------+
655 Figure 7: Access control for subscription
657 Another clarification to [RFC6536bis] is that each of the individual
658 nodes in a resulting update record MUST also have applied access
659 control to resulting pushed messages. This includes validating that
660 read access into new nodes added since the last update record. If
661 read access into previously accessible nodes not explicitly named in
662 the filter are lost mid-subscription, that can be treated as a
663 'delete' for on-change subscriptions. If not capable of handling
664 such permission changes for dynamic subscriptions, publisher
665 implementations MAY choose to terminate the subscription and to force
666 re-establishment with appropriate filtering.
668 +-------------+ +-------------------+
669 push-update / --> | data node | yes | |
670 push-change-update | access | ---> | add data node |
671 | allowed? | | to update message |
672 +-------------+ +-------------------+
674 Figure 8: Access control for push updates
676 3.10. On-change notifiable YANG objects
678 In some cases, a publisher supporting on-change notifications may not
679 be able to push updates for some object types on-change. Reasons for
680 this might be that the value of the data node changes frequently
681 (e.g., [RFC7223]'s in-octets counter), that small object changes are
682 frequent and meaningless (e.g., a temperature gauge changing 0.1
683 degrees), or that the implementation is not capable of on-change
684 notification for a particular object.
686 Support for on-change notification is usually specific to the
687 individual YANG model and/or implementation so it is possible to
688 define in design time. System integrators need this information
689 (without reading any data from a live node).
691 The default assumption is that no data nodes support on-change
692 notification. Schema nodes and subtrees that support on-change
693 notifications MUST be marked by accordingly with the YANG extension
694 "notifiable-on-change". This extension is defined in the data model
695 below.
697 When an on-change subscription is established, data-nodes are
698 automatically excluded unless they are marked with notifiable-on-
699 change as true. This also means that authorization checks SHALL NOT
700 be performed on them. A client can identify which nodes will be
701 included in on-change updated by retrieving the data nodes in the
702 subscription's scope and checking for which notifiable-on-change is
703 marked as true.
705 Adding notifiable-on-change markings will in general require updating
706 the corresponding YANG models. A simple way to avoid having to
707 modify existing module definitions is to add notifiable-on-change
708 markings by defining module deviations. This means that when a YANG
709 model designer wants to add a notifiable-on-change marking to nodes
710 of an existing module without modifying the module definitions, a new
711 module is introduced that contains deviation statements which add
712 "notifiable-on-change" statements as appicable.
714 deviation /sys:system/sys:system-time {
715 deviate add {
716 yp:notifiable-on-change false;
717 }
718 }
720 Figure 9: Deviation Example
722 3.11. Other considerations
724 3.11.1. Robustness and reliability
726 Particularly in the case of on-change push updates, it is important
727 that push updates do not get lost or, in case the loss of an update
728 is unavoidable, that the receiver is notified accordingly.
730 Update messages for a single subscription MAY NOT be resequenced.
732 It is conceivable that under certain circumstances, a publisher will
733 recognize that it is unable to include within an update record the
734 full set of objects desired per the terms of a subscription. In this
735 case, the publisher MUST take one or more of the following actions.
737 o A publisher MUST set the updates-not-sent flag on any update
738 record which is known to be missing information.
740 o It MAY choose to suspend a subscription as per [subscribe].
742 o When resuming an on-change subscription, the publisher SHOULD
743 generate a complete patch from the previous update record. If
744 this is not possible and the synch-on-start option is configured,
745 then the full datastore contents MAY be sent instead (effectively
746 replacing the previous contents). If neither of these are
747 possible, then an updates-not-sent flag MUST be included on the
748 next push-change-update.
750 Note: It is perfectly acceptable to have a series of push-change-
751 updates (and even push updates) serially queued at the transport
752 layer awaiting transmission. It is not required to merge pending
753 update messages. I.e., the dampening period applies to update record
754 creation, not transmission.
756 3.11.2. Update size and fragmentation
758 Depending on the subscription, the volume of updates can become quite
759 large. Additionally, based on the platform, it is possible that
760 update records for a single subscription are best sent independently
761 from different line-cards. Therefore, it may not always be practical
762 to send the entire update record in a single chunk. Implementations
763 may therefore choose, at their discretion, to "chunk" update records,
764 breaking one subscription's objects across several update records.
765 In this case the updates-not-sent flag will indicate that no single
766 update record is complete, and it is permissible for multiple updates
767 to come into a receiver for a single periodic interval or on-change
768 dampening period.
770 Care must be taken in chunking as problems may arrise for objects
771 that have containment or referential dependencies. The publisher
772 must consider these issues if chunking is provided.
774 3.11.3. Publisher capacity
776 It is far preferable to decline a subscription request than to accept
777 such a request when it cannot be met.
779 Whether or not a subscription can be supported will be determined by
780 a combination of several factors such as the subscription policy (on-
781 change or periodic), the period in which to report changes (1 second
782 periods will consume more resources than 1 hour periods), the amount
783 of data in the subtree that is being subscribed to, and the number
784 and combination of other subscriptions that are concurrently being
785 serviced.
787 4. A YANG data model for management of datastore push subscriptions
789 4.1. Overview
791 The YANG data model for datastore push subscriptions is depicted in
792 the following figure. Following YANG tree convention in the
793 depiction, brackets enclose list keys, "rw" means configuration, "ro"
794 operational state data, "?" designates optional nodes, "*" designates
795 nodes that can have multiple instances. Parentheses with a name in
796 the middle enclose choice and case nodes. New YANG objects defined
797 here (i.e., beyond those from [subscribe]) are identified with "yp".
799 module: ietf-subscribed-notifications
800 +--ro streams
801 | +--ro stream* [stream]
802 | | +--ro stream stream
803 | | +--ro description string
804 | | +--ro replay-support? empty
805 | | +--ro replay-log-creation-time? yang:date-and-time
806 | | +--ro replay-log-aged-time? yang:date-and-time
807 | +--ro yp:datastores
808 | +--ro yp:datastore* datastore
809 +--rw filters
810 | +--rw filter* [identifier]
811 | +--rw identifier filter-id
812 | +--rw (filter-type)?
813 | +--:(event-filter)
814 | +--rw event-filter-type event-filter-type
815 | +--rw event-filter
816 +--rw subscription-config {configured-subscriptions}?
817 | +--rw subscription* [identifier]
818 | +--rw identifier subscription-id
819 | +--rw encoding? encoding
820 | +--rw (target)
821 | | +--:(event-stream)
822 | | | +--rw stream stream
823 | | +--:(yp:datastore)
824 | | +--rw yp:datastore datastore
825 | | +--rw yp:selection-filter-type selection-filter-type
826 | | +--rw yp:selection-filter
827 | +--rw (applied-filter)
828 | | +--:(by-reference)
829 | | | +--rw filter-ref filter-ref
830 | | +--:(within-subscription)
831 | | +--rw (filter-type)?
832 | | +--:(event-filter)
833 | | +--rw event-filter-type event-filter-type
834 | | +--rw event-filter
835 | +--rw stop-time? yang:date-and-time
836 | +--rw receivers
837 | | +--rw receiver* [address port]
838 | | +--rw address inet:host
839 | | +--rw port inet:port-number
840 | | +--rw protocol? transport-protocol
841 | +--rw (notification-origin)?
842 | | +--:(interface-originated)
843 | | | +--rw source-interface? if:interface-ref
844 | | +--:(address-originated)
845 | | +--rw source-vrf? string
846 | | +--rw source-address inet:ip-address-no-zone
847 | +--rw (yp:update-trigger)?
848 | | +--:(yp:periodic)
849 | | | +--rw yp:period yang:timeticks
850 | | | +--rw yp:anchor-time? yang:date-and-time
851 | | +--:(yp:on-change) {on-change}?
852 | | +--rw yp:dampening-period yang:timeticks
853 | | +--rw yp:no-synch-on-start? empty
854 | | +--rw yp:excluded-change* change-type
855 | +--rw yp:dscp? inet:dscp
856 | +--rw yp:weighting? uint8
857 | +--rw yp:dependency? sn:subscription-id
858 +--ro subscriptions
859 +--ro subscription* [identifier]
860 +--ro identifier subscription-id
861 +--ro configured-subscription? empty
862 | {configured-subscriptions}?
863 +--ro encoding? encoding
864 +--ro (target)
865 | +--:(event-stream)
866 | | +--ro stream stream
867 | | +--ro replay-start-time? yang:date-and-time
868 | | {replay}?
869 | +--:(yp:datastore)
870 | +--ro yp:datastore datastore
871 | +--ro yp:selection-filter-type selection-filter-type
872 | +--ro yp:selection-filter
873 +--ro (applied-filter)
874 | +--:(by-reference)
875 | | +--ro filter-ref filter-ref
876 | +--:(within-subscription)
877 | +--ro (filter-type)?
878 | +--:(event-filter)
879 | +--ro event-filter-type event-filter-type
880 | +--ro event-filter
881 +--ro stop-time? yang:date-and-time
882 +--ro (notification-origin)?
883 | +--:(interface-originated)
884 | | +--ro source-interface? if:interface-ref
885 | +--:(address-originated)
886 | +--ro source-vrf? string
887 | +--ro source-address inet:ip-address-no-zone
888 +--ro receivers
889 | +--ro receiver* [address port]
890 | +--ro address inet:host
891 | +--ro port inet:port-number
892 | +--ro protocol? transport-protocol
893 | +--ro pushed-notifications? yang:counter64
894 | +--ro excluded-notifications? yang:counter64
895 | +--ro status subscription-status
896 +--ro (yp:update-trigger)?
897 | +--:(yp:periodic)
898 | | +--ro yp:period yang:timeticks
899 | | +--ro yp:anchor-time? yang:date-and-time
900 | +--:(yp:on-change) {on-change}?
901 | +--ro yp:dampening-period yang:timeticks
902 | +--ro yp:no-synch-on-start? empty
903 | +--ro yp:excluded-change* change-type
904 +--ro yp:dscp? inet:dscp
905 +--ro yp:weighting? uint8
906 +--ro yp:dependency? sn:subscription-id
908 rpcs:
909 +---x establish-subscription
910 | +---w input
911 | | +---w encoding? encoding
912 | | +---w (target)
913 | | | +--:(event-stream)
914 | | | | +---w stream stream
915 | | | | +---w replay-start-time? yang:date-and-time
916 | | | | {replay}?
917 | | | +--:(yp:datastore)
918 | | | +---w yp:datastore datastore
919 | | | +---w yp:selection-filter-type selection-filter-type
920 | | | +---w yp:selection-filter
921 | | +---w (applied-filter)
922 | | | +--:(by-reference)
923 | | | | +---w filter-ref filter-ref
924 | | | +--:(within-subscription)
925 | | | +---w (filter-type)?
926 | | | +--:(event-filter)
927 | | | +---w event-filter-type event-filter-type
928 | | | +---w event-filter
929 | | +---w stop-time? yang:date-and-time
930 | | +---w (yp:update-trigger)?
931 | | | +--:(yp:periodic)
932 | | | | +---w yp:period yang:timeticks
933 | | | | +---w yp:anchor-time? yang:date-and-time
934 | | | +--:(yp:on-change) {on-change}?
935 | | | +---w yp:dampening-period yang:timeticks
936 | | | +---w yp:no-synch-on-start? empty
937 | | | +---w yp:excluded-change* change-type
938 | | +---w yp:dscp? inet:dscp
939 | | +---w yp:weighting? uint8
940 | | +---w yp:dependency? sn:subscription-id
941 | +--ro output
942 | +--ro subscription-result subscription-result
943 | +--ro (result)?
944 | +--:(no-success)
945 | | +--ro filter-failure? string
946 | | +--ro replay-start-time-hint? yang:date-and-time
947 | | +--ro yp:period-hint? yang:timeticks
948 | | +--ro yp:error-path? string
949 | | +--ro yp:object-count-estimate? uint32
950 | | +--ro yp:object-count-limit? uint32
951 | | +--ro yp:kilobytes-estimate? uint32
952 | | +--ro yp:kilobytes-limit? uint32
953 | +--:(success)
954 | +--ro identifier subscription-id
955 +---x modify-subscription
956 | +---w input
957 | | +---w identifier? subscription-id
958 | | +---w (applied-filter)
959 | | | +--:(by-reference)
960 | | | | +---w filter-ref filter-ref
961 | | | +--:(within-subscription)
962 | | | +---w (filter-type)?
963 | | | +--:(event-filter)
964 | | | +---w event-filter-type event-filter-type
965 | | | +---w event-filter
966 | | +---w stop-time? yang:date-and-time
967 | | +---w (yp:update-trigger)?
968 | | +--:(yp:periodic)
969 | | | +---w yp:period yang:timeticks
970 | | | +---w yp:anchor-time? yang:date-and-time
971 | | +--:(yp:on-change) {on-change}?
972 | | +---w yp:dampening-period yang:timeticks
973 | +--ro output
974 | +--ro subscription-result subscription-result
975 | +--ro (result)?
976 | +--:(no-success)
977 | +--ro filter-failure? string
978 | +--ro yp:period-hint? yang:timeticks
979 | +--ro yp:error-path? string
980 | +--ro yp:object-count-estimate? uint32
981 | +--ro yp:object-count-limit? uint32
982 | +--ro yp:kilobytes-estimate? uint32
983 | +--ro yp:kilobytes-limit? uint32
984 +---x delete-subscription
985 | +---w input
986 | | +---w identifier subscription-id
987 | +--ro output
988 | +--ro subscription-result subscription-result
989 +---x kill-subscription
990 +---w input
991 | +---w identifier subscription-id
992 +--ro output
993 +--ro subscription-result subscription-result
995 notifications:
996 +---n replay-complete
997 | +--ro identifier subscription-id
998 +---n notification-complete
999 | +--ro identifier subscription-id
1000 +---n subscription-started
1001 | +--ro identifier subscription-id
1002 | +--ro encoding? encoding
1003 | +--ro (target)
1004 | | +--:(event-stream)
1005 | | | +--ro stream stream
1006 | | | +--ro replay-start-time? yang:date-and-time
1007 | | | {replay}?
1008 | | +--:(yp:datastore)
1009 | | +--ro yp:datastore datastore
1010 | | +--ro yp:selection-filter-type selection-filter-type
1011 | | +--ro yp:selection-filter
1012 | +--ro (applied-filter)
1013 | | +--:(by-reference)
1014 | | | +--ro filter-ref filter-ref
1015 | | +--:(within-subscription)
1016 | | +--ro (filter-type)?
1017 | | +--:(event-filter)
1018 | | +--ro event-filter-type event-filter-type
1019 | | +--ro event-filter
1020 | +--ro stop-time? yang:date-and-time
1021 | +--ro (yp:update-trigger)?
1022 | | +--:(yp:periodic)
1023 | | | +--ro yp:period yang:timeticks
1024 | | | +--ro yp:anchor-time? yang:date-and-time
1025 | | +--:(yp:on-change) {on-change}?
1026 | | +--ro yp:dampening-period yang:timeticks
1027 | | +--ro yp:no-synch-on-start? empty
1028 | | +--ro yp:excluded-change* change-type
1029 | +--ro yp:dscp? inet:dscp
1030 | +--ro yp:weighting? uint8
1031 | +--ro yp:dependency? sn:subscription-id
1032 +---n subscription-resumed
1033 | +--ro identifier subscription-id
1034 +---n subscription-modified
1035 | +--ro identifier subscription-id
1036 | +--ro encoding? encoding
1037 | +--ro (target)
1038 | | +--:(event-stream)
1039 | | +--ro stream stream
1040 | | +--ro replay-start-time? yang:date-and-time {replay}?
1041 | +--ro (applied-filter)
1042 | | +--:(by-reference)
1043 | | | +--ro filter-ref filter-ref
1044 | | +--:(within-subscription)
1045 | | +--ro (filter-type)?
1046 | | +--:(event-filter)
1047 | | +--ro event-filter-type event-filter-type
1048 | | +--ro event-filter
1049 | +--ro stop-time? yang:date-and-time
1050 | +--ro (yp:update-trigger)?
1051 | | +--:(yp:periodic)
1052 | | | +--ro yp:period yang:timeticks
1053 | | | +--ro yp:anchor-time? yang:date-and-time
1054 | | +--:(yp:on-change) {on-change}?
1055 | | +--ro yp:dampening-period yang:timeticks
1056 | | +--ro yp:no-synch-on-start? empty
1057 | | +--ro yp:excluded-change* change-type
1058 | +--ro yp:dscp? inet:dscp
1059 | +--ro yp:weighting? uint8
1060 | +--ro yp:dependency? sn:subscription-id
1061 +---n subscription-terminated
1062 | +--ro identifier subscription-id
1063 | +--ro error-id subscription-errors
1064 | +--ro filter-failure? string
1065 +---n subscription-suspended
1066 +--ro identifier subscription-id
1067 +--ro error-id subscription-errors
1068 +--ro filter-failure? string
1070 module: ietf-yang-push
1072 notifications:
1073 +---n push-update
1074 | +--ro subscription-id sn:subscription-id
1075 | +--ro time-of-update? yang:date-and-time
1076 | +--ro updates-not-sent? empty
1077 | +--ro datastore-contents?
1078 +---n push-change-update {on-change}?
1079 +--ro subscription-id sn:subscription-id
1080 +--ro time-of-update? yang:date-and-time
1081 +--ro updates-not-sent? empty
1082 +--ro datastore-changes?
1084 Figure 10: Model structure
1086 Selected components of the model are summarized below.
1088 4.2. Subscription configuration
1090 Both configured and dynamic subscriptions are represented within the
1091 list subscription-config. Each subscription has own list elements.
1092 New and enhanced parameters extending the basic subscription data
1093 model in [subscribe] include:
1095 o An update filter identifying yang nodes of interest. Filter
1096 contents are specified via a reference to an existing filter, or
1097 via an in-line definition for only that subscription. This
1098 facilitates the reuse of filter definitions, which can be
1099 important in case of complex filter conditions. Referenced
1100 filters can also allow an implementation to avoid evaluating
1101 filter acceptability during a dynamic subscription request. The
1102 case statement differentiates the options.
1104 o For periodic subscriptions, triggered updates will occur at the
1105 boundaries of a specified time interval. These boundaries many be
1106 calculated from the periodic parameters:
1108 * a "period" which defines duration between period push updates.
1110 * an "anchor-time"; update intervals always fall on the points in
1111 time that are a multiple of a period after the anchor time. If
1112 anchor time is not provided, then the anchor time MUST be set
1113 with the creation time of the initial update record.
1115 o For on-change subscriptions, assuming the dampening period has
1116 completed, triggered occurs whenever a change in the subscribed
1117 information is detected. On-change subscriptions have more
1118 complex semantics that is guided by its own set of parameters:
1120 * a "dampening-period" specifies the interval that must pass
1121 before a successive update for the subscription is sent. If no
1122 dampening period is in effect, the update is sent immediately.
1123 If a subsequent change is detected, another update is only sent
1124 once the dampening period has passed for this subscription.
1126 * an "excluded-change" flag which allows restriction of the types
1127 of changes for which updates should be sent (e.g., only add to
1128 an update record on object creation).
1130 * a "no-synch-on-start" flag which specifies whether a complete
1131 update with all the subscribed data is to be sent at the
1132 beginning of a subscription.
1134 o Optional qos parameters to indicate the treatment of a
1135 subscription relative to other traffic between publisher and
1136 receiver. These include:
1138 * A "dscp" QoS marking which MUST be stamped on notification
1139 messages to differentiate network QoS behavior.
1141 * A "weighting" so that bandwidth proportional to this weighting
1142 can be allocated to this subscription relative to others for
1143 that receiver.
1145 * a "dependency" upon another subscription. Notification
1146 messages MUST NOT be sent prior to other notification messages
1147 containing update record(s) for the referenced subscription.
1149 o A subscription's weighting MUST work identically to stream
1150 dependency weighting as described within RFC 7540, section 5.3.2.
1152 o A subscription's dependency MUST work identically to stream
1153 dependency as described within RFC 7540, sections 5.3.1, 5.3.3,
1154 and 5.3.4. If a dependency is attempted via an RPC, but the
1155 referenced subscription does not exist, the dependency will be
1156 removed.
1158 4.3. YANG Notifications
1159 4.3.1. Monitoring and OAM Notifications
1161 OAM notifications and mechanism are reused from [subscribe]. Some
1162 have been augmented to include the YANG datastore specific objects.
1164 4.3.2. New Notifications for update records
1166 The data model introduces two YANG notifications to encode
1167 information for update records: "push-update" and "push-change-
1168 update".
1170 "Push-update" is used to send a complete snapshot of the filtered
1171 subscription data. This type of notification is used to carry the
1172 update records of a periodic subscription. The "push-update"
1173 notification is also used with on-change subscriptions for the
1174 purposes of allowing a receiver to "synch" on a complete set of
1175 subscribed datastore contents. This synching may be done the start
1176 of an on-change subscription, and then later in that subscription to
1177 force resynchronization. If the "updates-not-sent" flag is set, this
1178 indicates that the update record is incomplete.
1180 "Push-change-update" is used to send datastore changes that have
1181 occurred in subscribed data since the previous update. This
1182 notification is used only in conjunction with on-change
1183 subscriptions. This will be encoded as yang-patch data.
1185 If the application detects an informational discontinuity in either
1186 notification, the notification MUST include a flag "updates-not-
1187 sent". This flag which indicates that not all changes which have
1188 occurred since the last update are actually included with this
1189 update. In other words, the publisher has failed to fulfill its full
1190 subscription obligations. (For example a datastore missed a window
1191 in providing objects to a publisher process.) To facilitate
1192 synchronization, a publisher MAY subsequently send a push-update
1193 containing a full snapshot of subscribed data.
1195 4.4. YANG RPCs
1197 YANG-Push subscriptions are established, modified, and deleted using
1198 RPCs augmented from [subscribe].
1200 4.4.1. Establish-subscription RPC
1202 The subscriber sends an establish-subscription RPC with the
1203 parameters in section 3.1. An example might look like:
1205
1207
1209
1212 500
1213 encode-xml
1214
1215
1217 Figure 11: Establish-subscription RPC
1219 The publisher MUST respond explicitly positively (i.e., subscription
1220 accepted) or negatively (i.e., subscription rejected) to the request.
1221 Positive responses include the subscription-id of the accepted
1222 subscription. In that case a publisher MAY respond:
1224
1226
1228 ok
1229
1230
1232 52
1233
1234
1236 Figure 12: Establish-subscription positive RPC response
1238 A subscription can be rejected for multiple reasons, including the
1239 lack of authorization to establish a subscription, the lack of read
1240 authorization on the requested data node, or the inability of the
1241 publisher to provide a stream with the requested semantics.
1243 When the requester is not authorized to read the requested data node,
1244 the returned information indicates the node is unavailable. For
1245 instance, if the above request was unauthorized to read node "ex:foo"
1246 the publisher may return:
1248
1250
1252 subtree-unavailable
1253
1254
1256 /ex:foo
1257
1258
1260 Figure 13: Establish-subscription access denied response
1262 If a request is rejected because the publisher is not able to serve
1263 it, the publisher SHOULD include in the returned error what
1264 subscription parameters would have been accepted for the request.
1265 However, there are no guarantee that subsequent requests using this
1266 info will in fact be accepted.
1268 For example, for the following request:
1270
1272
1274 running
1275
1278 10
1279 encode-xml
1280
1281
1283 Figure 14: Establish-subscription request example 2
1285 a publisher that cannot serve on-change updates but periodic updates
1286 might return the following:
1288
1290
1292 period-unsupported
1293
1294 100
1295
1297 Figure 15: Establish-subscription error response example 2
1299 4.4.2. Modify-subscription RPC
1301 The subscriber MAY invoke the modify-subscription RPC for a
1302 subscription it previously established. The subscriber will include
1303 newly desired values in the modify-subscription RPC. Parameters not
1304 included MUST remain unmodified. Below is an example where a
1305 subscriber attempts to modify the period of a subscription.
1307
1309
1311 running
1312
1313 1011
1314
1315 250
1316
1317
1319 Figure 16: Modify subscription request
1321 The publisher MUST respond explicitly positively or negatively to the
1322 request. A response to a successful modification might look like:
1324
1326
1328 ok
1329
1330
1332 Figure 17: Modify subscription response
1334 If the subscription modification is rejected, the publisher MUST send
1335 a response like it does for an establish-subscription and maintain
1336 the subscription as it was before the modification request.
1337 Responses MAY include hints. A subscription MAY be modified multiple
1338 times.
1340 A configured subscription cannot be modified using modify-
1341 subscription RPC. Instead, the configuration needs to be edited as
1342 needed.
1344 4.4.3. Delete-subscription RPC
1346 To stop receiving updates from a subscription and effectively delete
1347 a subscription that had previously been established using an
1348 establish-subscription RPC, a subscriber can send a delete-
1349 subscription RPC, which takes as only input the subscription-id. For
1350 example:
1352
1354
1356
1357 1011
1358
1359
1360
1362
1364
1366 ok
1367
1368
1370 Figure 18: Delete subscription
1372 Configured subscriptions cannot be deleted via RPC, but have to be
1373 removed from the configuration.
1375 4.4.4. YANG Module Synchronization
1377 To make subscription requests, the subscriber needs to know the YANG
1378 module library available on the publisher. The YANG 1.0 module
1379 library information is sent by a NETCONF server in the NETCONF
1380 'hello' message. For YANG 1.1 modules and all modules used with the
1381 RESTCONF [RFC8040] protocol, this information is provided by the YANG
1382 Library module (ietf-yang-library.yang from [RFC7895]. The YANG
1383 library information is important for the receiver to reproduce the
1384 set of object definitions used by the replicated datastore.
1386 The YANG library includes a module list with the name, revision,
1387 enabled features, and applied deviations for each YANG module
1388 implemented by the publisher. The receiver is expected to know the
1389 YANG library information before starting a subscription. The
1390 "/modules-state/module-set-id" leaf in the "ietf-yang-library" module
1391 can be used to cache the YANG library information.
1393 The set of modules, revisions, features, and deviations can change at
1394 run-time (if supported by the server implementation). In this case,
1395 the receiver needs to be informed of module changes before data nodes
1396 from changed modules can be processed correctly. The YANG library
1397 provides a simple "yang-library-change" notification that informs the
1398 client that the library has changed. The receiver then needs to re-
1399 read the entire YANG library data for the replicated server in order
1400 to detect the specific YANG library changes. The "ietf-netconf-
1401 notifications" module defined in [RFC6470] contains a "netconf-
1402 capability-change" notification that can identify specific module
1403 changes. For example, the module URI capability of a newly loaded
1404 module will be listed in the "added-capability" leaf-list, and the
1405 module URI capability of an removed module will be listed in the
1406 "deleted-capability" leaf-list.
1408 5. YANG module
1410 ; file "ietf-yang-push@2017-08-20.yang"
1411 module ietf-yang-push {
1412 yang-version 1.1;
1413 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push";
1414 prefix yp;
1416 import ietf-inet-types {
1417 prefix inet;
1418 }
1419 import ietf-yang-types {
1420 prefix yang;
1421 }
1422 import ietf-subscribed-notifications {
1423 prefix sn;
1424 }
1426 organization "IETF";
1427 contact
1428 "WG Web:
1429 WG List:
1430 WG Chair: Mahesh Jethanandani
1431
1433 WG Chair: Kent Watsen
1434
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-08-20 {
1462 description
1463 "Initial revision.";
1464 reference
1465 "YANG Datastore Push, draft-ietf-netconf-yang-push-08";
1466 }
1468 /*
1469 * EXTENSIONS
1470 */
1472 extension notifiable-on-change {
1473 argument "value";
1474 description
1475 "Indicates whether changes to the data node are reportable in
1476 on-change subscriptions.
1478 The statement MUST only be a substatement of the leaf, leaf-list,
1479 container, list, anyxml, anydata statements. Zero or One
1480 notifiable-on-change statement is allowed per parent statement.
1481 NO substatements are allowed.
1483 The argument is a boolean value indicating whether on-change
1484 notifications are supported. If notifiable-on-change is not
1485 specified, the default is the same as the parent data node's
1486 value. For top level data nodes the default value is false.";
1487 }
1489 /*
1490 * FEATURES
1491 */
1493 feature on-change {
1494 description
1495 "This feature indicates that on-change updates are
1496 supported.";
1497 }
1499 /*
1500 * IDENTITIES
1501 */
1503 /* Error type identities for datastore subscription */
1504 identity period-unsupported {
1505 base sn:error;
1506 description
1507 "Requested time period is too short. This can be for both
1508 periodic and on-change dampening.";
1509 }
1511 identity qos-unsupported {
1512 base sn:error;
1513 description
1514 "Subscription QoS parameters not supported on this platform.";
1515 }
1517 identity dscp-unavailable {
1518 base sn:error;
1519 description
1520 "Requested DSCP marking not allocatable.";
1521 }
1523 identity on-change-unsupported {
1524 base sn:error;
1525 description
1526 "On-change not supported.";
1527 }
1529 identity synch-on-start-unsupported {
1530 base sn:error;
1531 description
1532 "On-change synch-on-start not supported.";
1533 }
1535 identity synch-on-start-datatree-size {
1536 base sn:error;
1537 description
1538 "Synch-on-start would push a datatree which exceeds size limit.";
1539 }
1541 identity reference-mismatch {
1542 base sn:error;
1543 description
1544 "Mismatch in filter key and referenced yang subtree.";
1545 }
1547 identity data-unavailable {
1548 base sn:error;
1549 description
1550 "Referenced yang node or subtree doesn't exist, or read
1551 access is not permitted.";
1552 }
1554 identity datatree-size {
1555 base sn:error;
1556 description
1557 "Resulting push updates would exceed size limit.";
1558 }
1560 /* Datastore identities */
1561 identity datastore {
1562 description
1563 "Abstract base identity for datastore identities. More are in the
1564 process of being defined within
1565 draft-ietf-netmod-revised-datastores. ";
1566 }
1567 identity candidate {
1568 base datastore;
1569 description
1570 "The candidate datastore per RFC-6241.";
1571 reference "RFC-6241, #5.1";
1572 }
1573 identity running {
1574 base datastore;
1575 description
1576 "The running datastore per RFC-6241.";
1577 reference "RFC-6241, #5.1";
1578 }
1579 identity startup {
1580 base datastore;
1581 description
1582 "The startup datastore per RFC-6241.";
1583 reference "RFC-6241, #5.1";
1584 }
1585 identity operational {
1586 base datastore;
1587 description
1588 "The operational datastore contains all configuration data
1589 actually used by the system, including all applied configuration,
1590 system-provided configuration and values defined by any supported
1591 data models. In addition, the operational datastore also
1592 contains state data.";
1593 reference
1594 "the original text came from draft-ietf-netmod-revised-datastores
1595 -01, section #4.3. This definition is expected to remain stable
1596 meaning later reconciliation between the drafts unnecessary.";
1597 }
1598 identity intended {
1599 base datastore;
1600 description
1601 "The intended datastore per draft-ietf-netmod-revised-datastores.";
1602 reference
1603 "draft-ietf-netmod-revised-datastores";
1604 }
1605 identity custom-datastore {
1606 base datastore;
1607 description
1608 "Another datastore not defined via an identity in this model";
1609 }
1611 /* Selection filter identities */
1612 identity selection-filter {
1613 description
1614 "Evaluation criteria encoded in a syntax which allows the
1615 selection of nodes from a target. If the filter is applied
1616 against a datastore for periodic extracts, the resulting node-set
1617 result is passed along. If the filter is applied against a
1618 datastore looking for changes, deltas from the last update in the
1619 form of a patch result are passed along. An empty node set is a
1620 valid result of this filter type.";
1621 }
1622 identity subtree-selection-filter {
1623 base selection-filter;
1624 description
1625 "An RFC-6241 based selection-filter which may be used to select
1626 nodes within a datastore.";
1627 reference "RFC-6241, #5.1";
1628 }
1629 identity xpath-selection-filter {
1630 base selection-filter;
1631 description
1632 "A selection-filter which may be applied to a datastore which
1633 follows the syntax specified in yang:xpath1.0. Nodes that evaluate
1634 to true are included in the selection.";
1635 reference "XPATH: http://www.w3.org/TR/1999/REC-xpath-19991116";
1636 }
1638 /*
1639 * TYPE DEFINITIONS
1640 */
1642 typedef change-type {
1643 type enumeration {
1644 enum "create" {
1645 description
1646 "Create a new data resource if it does not already exist. If
1647 it already exists, replace.";
1648 }
1649 enum "delete" {
1650 description
1651 "Delete a data resource if it already exists. If it does not
1652 exists, take no action.";
1653 }
1654 enum "insert" {
1655 description
1656 "Insert a new user-ordered data resource";
1657 }
1658 enum "merge" {
1659 description
1660 "merge the edit value with the target data resource; create
1661 if it does not already exist";
1662 }
1663 enum "move" {
1664 description
1665 "Reorder the target data resource";
1666 }
1667 enum "replace" {
1668 description
1669 "Replace the target data resource with the edit value";
1671 }
1672 enum "remove" {
1673 description
1674 "Remove a data resource if it already exists ";
1675 }
1676 }
1677 description
1678 "Specifies different types of datastore changes.";
1679 reference
1680 "RFC 8072 section 2.5, with a delta that it is ok to receive
1681 ability create on an existing node, or recieve a delete on a
1682 missing node.";
1683 }
1685 typedef datastore {
1686 type identityref {
1687 base datastore;
1688 }
1689 description
1690 "Specifies a system-provided datastore. May also specify ability
1691 portion of a datastore, so as to reduce the filtering effort.";
1692 }
1694 typedef selection-filter-type {
1695 type identityref {
1696 base selection-filter;
1697 }
1698 description
1699 "Specifies a known type of selection filter.";
1700 }
1702 /*
1703 * GROUP DEFINITIONS
1704 */
1706 grouping datastore-criteria {
1707 description
1708 "A grouping to define criteria for which objects from which
1709 datastore to include in push updates.";
1710 leaf datastore {
1711 type datastore;
1712 mandatory true;
1713 description
1714 "Datastore against which the subscription has been
1715 applied.";
1716 }
1717 uses selection-filter-objects;
1719 }
1721 grouping selection-filter-objects {
1722 description
1723 "This grouping defines a selector for objects from a
1724 datastore.";
1725 leaf selection-filter-type {
1726 type selection-filter-type;
1727 mandatory true;
1728 description
1729 "A filter needs to be a known and understood syntax if it is
1730 to be interpretable by a device.";
1731 }
1732 anyxml selection-filter {
1733 mandatory true;
1734 description
1735 "Datastore evaluation criteria encoded in a syntax of a
1736 supported type of selection filter.";
1737 }
1738 }
1740 grouping update-policy-modifiable {
1741 description
1742 "This grouping describes the datastore specific subscription
1743 conditions that can be changed during the lifetime of the
1744 subscription.";
1745 choice update-trigger {
1746 description
1747 "Defines necessary conditions for sending an event to
1748 the subscriber.";
1749 case periodic {
1750 description
1751 "The agent is requested to notify periodically the current
1752 values of the datastore as defined by the selection filter.";
1753 leaf period {
1754 type yang:timeticks;
1755 mandatory true;
1756 description
1757 "Duration of time which should occur between periodic
1758 push updates. Where the anchor of a start-time is
1759 available, the push will include the objects and their
1760 values which exist at an exact multiple of timeticks
1761 aligning to this start-time anchor.";
1762 }
1763 leaf anchor-time {
1764 type yang:date-and-time;
1765 description
1766 "Designates a timestamp from which the series of periodic
1767 push updates are computed. The next update will take place
1768 at the next period interval from the anchor time. For
1769 example, for an anchor time at the top of a minute and a
1770 period interval of a minute, the next update will be sent
1771 at the top of the next minute.";
1772 }
1773 }
1774 case on-change {
1775 if-feature "on-change";
1776 description
1777 "The agent is requested to notify changes in values in the
1778 datastore subset as defined by a selection filter.";
1779 leaf dampening-period {
1780 type yang:timeticks;
1781 mandatory true;
1782 description
1783 "The shortest time duration which is allowed between the
1784 creation of independent yang object update messages.
1785 Effectively this is the amount of time that needs to have
1786 passed since the last update.";
1787 }
1788 }
1789 }
1790 }
1792 grouping update-policy {
1793 description
1794 "This grouping describes the datastore specific subscription
1795 conditions of a subscription.";
1796 uses update-policy-modifiable {
1797 augment "update-trigger/on-change" {
1798 description
1799 "Includes objects not modifiable once subscription is
1800 established.";
1801 leaf no-synch-on-start {
1802 type empty;
1803 description
1804 "This leaf acts as a flag that determines behavior at the
1805 start of the subscription. When present, synchronization
1806 of state at the beginning of the subscription is outside
1807 the scope of the subscription. Only updates about changes
1808 that are observed from the start time, i.e. only push-
1809 change-update notifications are sent. When absent (default
1810 behavior), in order to facilitate a receiver's
1811 synchronization, a full update is sent when the
1812 subscription starts using a push-update notification, just
1813 like in the case of a periodic subscription. After that,
1814 push-change-update notifications only are sent unless the
1815 Publisher chooses to resynch the subscription again.";
1816 }
1817 leaf-list excluded-change {
1818 type change-type;
1819 description
1820 "Use to restrict which changes trigger an update.
1821 For example, if modify is excluded, only creation and
1822 deletion of objects is reported.";
1823 }
1824 }
1825 }
1826 }
1828 grouping update-qos {
1829 description
1830 "This grouping describes Quality of Service information
1831 concerning a subscription. This information is passed to lower
1832 layers for transport prioritization and treatment";
1833 leaf dscp {
1834 type inet:dscp;
1835 default "0";
1836 description
1837 "The push update's IP packet transport priority. This is made
1838 visible across network hops to receiver. The transport
1839 priority is shared for all receivers of a given subscription.";
1840 }
1841 leaf weighting {
1842 type uint8 {
1843 range "0 .. 255";
1844 }
1845 description
1846 "Relative weighting for a subscription. Allows an underlying
1847 transport layer perform informed load balance allocations
1848 between various subscriptions";
1849 reference
1850 "RFC-7540, section 5.3.2";
1851 }
1852 leaf dependency {
1853 type sn:subscription-id;
1854 description
1855 "Provides the Subscription ID of a parent subscription which
1856 has absolute priority should that parent have push updates
1857 ready to egress the publisher. In other words, there should be
1858 no streaming of objects from the current subscription if of
1859 the parent has something ready to push.";
1860 reference
1861 "RFC-7540, section 5.3.1";
1862 }
1864 }
1866 grouping update-error-hints {
1867 description
1868 "Allow return additional negotiation hints that apply
1869 specifically to push updates.";
1870 leaf period-hint {
1871 type yang:timeticks;
1872 description
1873 "Returned when the requested time period is too short. This
1874 hint can assert an viable period for both periodic push
1875 cadence and on-change dampening.";
1876 }
1877 leaf error-path {
1878 type string;
1879 description
1880 "Reference to a YANG path which is associated with the error
1881 being returned.";
1882 }
1883 leaf object-count-estimate {
1884 type uint32;
1885 description
1886 "If there are too many objects which could potentially be
1887 returned by the selection filter, this identifies the estimate
1888 of the number of objects which the filter would potentially
1889 pass.";
1890 }
1891 leaf object-count-limit {
1892 type uint32;
1893 description
1894 "If there are too many objects which could be returned by the
1895 selection filter, this identifies the upper limit of the
1896 publisher's ability to service for this subscription.";
1897 }
1898 leaf kilobytes-estimate {
1899 type uint32;
1900 description
1901 "If the returned information could be beyond the capacity of
1902 the publisher, this would identify the data size which could
1903 result from this selection filter.";
1904 }
1905 leaf kilobytes-limit {
1906 type uint32;
1907 description
1908 "If the returned information would be beyond the capacity of
1909 the publisher, this identifies the upper limit of the
1910 publisher's ability to service for this subscription.";
1911 }
1913 }
1915 /*
1916 * DATA NODES
1917 */
1919 augment "/sn:streams" {
1920 description
1921 "This augmentation adds datastores to the list of items that
1922 can be subscribed.";
1923 container datastores {
1924 config false;
1925 description
1926 "This container contains a leaf list of built-in
1927 streams that are provided by the system.";
1928 leaf-list datastore {
1929 type datastore;
1930 description
1931 "Identifies the built-in datastores that are supported by
1932 the system. Built-in datastores are associated with their
1933 own identities. In case configurable custom datastores are
1934 supported, as indicated by the custom-datastore identity.
1935 The configuration and delivery of those custom datastores is
1936 provided separately.";
1937 }
1938 }
1939 }
1940 augment "/sn:establish-subscription/sn:input" {
1941 description
1942 "This augmentation adds additional subscription parameters that
1943 apply specifically to datastore updates to RPC input.";
1944 uses update-policy;
1945 uses update-qos;
1946 }
1947 augment "/sn:establish-subscription/sn:input/sn:target" {
1948 description
1949 "This augmentation adds the datastore as a valid parameter object
1950 for the subscription to RPC input. This provides a target for
1951 the filter.";
1952 case datastore {
1953 uses datastore-criteria;
1954 }
1955 }
1956 augment "/sn:establish-subscription/sn:output/"+
1957 "sn:result/sn:no-success" {
1958 description
1959 "This augmentation adds datastore specific error info
1960 and hints to RPC output.";
1962 uses update-error-hints;
1963 }
1964 augment "/sn:modify-subscription/sn:input" {
1965 description
1966 "This augmentation adds additional subscription parameters
1967 specific to datastore updates.";
1968 uses update-policy-modifiable;
1969 }
1970 augment "/sn:modify-subscription/sn:output/"+
1971 "sn:result/sn:no-success" {
1972 description
1973 "This augmentation adds push datastore error info and hints to
1974 RPC output.";
1975 uses update-error-hints;
1976 }
1977 notification push-update {
1978 description
1979 "This notification contains a push update, containing data
1980 subscribed to via a subscription. This notification is sent for
1981 periodic updates, for a periodic subscription. It can also be
1982 used for synchronization updates of an on-change subscription.
1983 This notification shall only be sent to receivers of a
1984 subscription; it does not constitute a general-purpose
1985 notification.";
1986 leaf subscription-id {
1987 type sn:subscription-id;
1988 mandatory true;
1989 description
1990 "This references the subscription because of which the
1991 notification is sent.";
1992 }
1993 leaf time-of-update {
1994 type yang:date-and-time;
1995 description
1996 "This leaf contains the time of the update.";
1997 }
1998 leaf updates-not-sent {
1999 type empty;
2000 description
2001 "This is a flag which indicates that not all data nodes
2002 subscribed to are included with this update. In other words,
2003 the publisher has failed to fulfill its full subscription
2004 obligations. This may lead to intermittent loss of
2005 synchronization of data at the client. Synchronization at the
2006 client can occur when the next push-update is received.";
2007 }
2008 anydata datastore-contents {
2009 description
2010 "This contains the updated data. It constitutes a snapshot
2011 at the time-of-update of the set of data that has been
2012 subscribed to. The format and syntax of the data
2013 corresponds to the format and syntax of data that would be
2014 returned in a corresponding get operation with the same
2015 selection filter parameters applied.";
2016 }
2017 }
2018 notification push-change-update {
2019 if-feature "on-change";
2020 description
2021 "This notification contains an on-change push update. This
2022 notification shall only be sent to the receivers of a
2023 subscription; it does not constitute a general-purpose
2024 notification.";
2025 leaf subscription-id {
2026 type sn:subscription-id;
2027 mandatory true;
2028 description
2029 "This references the subscription because of which the
2030 notification is sent.";
2031 }
2032 leaf time-of-update {
2033 type yang:date-and-time;
2034 description
2035 "This leaf contains the time of the update, i.e. the time at
2036 which the change was observed.";
2037 }
2038 leaf updates-not-sent {
2039 type empty;
2040 description
2041 "This is a flag which indicates that not all changes which
2042 have occurred since the last update are included with this
2043 update. In other words, the publisher has failed to
2044 fulfill its full subscription obligations, for example in
2045 cases where it was not able to keep up with a change burst.
2046 To facilitate synchronization, a publisher may subsequently
2047 send a push-update containing a full snapshot of subscribed
2048 data. Such a push-update might also be triggered by a
2049 subscriber requesting an on-demand synchronization.";
2050 }
2051 anydata datastore-changes {
2052 description
2053 "This contains datastore contents that has changed since the
2054 previous update, per the terms of the subscription. Changes
2055 are encoded analogous to the syntax of a corresponding yang-
2056 patch operation, i.e. a yang-patch operation applied to the
2057 YANG datastore implied by the previous update to result in the
2058 current state (and assuming yang-patch could also be applied
2059 to operational data).";
2060 }
2061 }
2062 augment "/sn:subscription-started" {
2063 description
2064 "This augmentation adds many yang datastore specific objects to
2065 the notification that a subscription has started.";
2066 uses update-policy;
2067 uses update-qos;
2068 }
2069 augment "/sn:subscription-started/sn:target" {
2070 description
2071 "This augmentation allows the datastore to be included as part
2072 of the notification that a subscription has started.";
2073 case datastore {
2074 uses datastore-criteria;
2075 }
2076 }
2077 augment "/sn:subscription-modified" {
2078 description
2079 "This augmentation adds many yang datastore specific objects to
2080 the notification that a subscription has been modified.";
2081 uses update-policy;
2082 uses update-qos;
2083 }
2084 augment "/sn:subscription-config/sn:subscription" {
2085 description
2086 "This augmentation adds many yang datastore specific objects
2087 which can be configured as opposed to established via RPC.";
2088 uses update-policy;
2089 uses update-qos;
2090 }
2091 augment "/sn:subscription-config/sn:subscription/sn:target" {
2092 description
2093 "This augmentation adds the datastore to the selection filtering
2094 criteria for a subscription.";
2095 case datastore {
2096 uses datastore-criteria;
2097 }
2098 }
2099 augment "/sn:subscriptions/sn:subscription" {
2100 yp:notifiable-on-change true;
2101 description
2102 "This augmentation adds many datastore specific objects to a
2103 subscription.";
2104 uses update-policy;
2105 uses update-qos;
2107 }
2108 augment "/sn:subscriptions/sn:subscription/sn:target" {
2109 description
2110 "This augmentation allows the datastore to be included as part
2111 of the selection filtering criteria for a subscription.";
2112 case datastore {
2113 uses datastore-criteria;
2114 }
2115 }
2116 }
2118
2120 6. IANA Considerations
2122 This document registers the following namespace URI in the "IETF XML
2123 Registry" [RFC3688]:
2125 URI: urn:ietf:params:xml:ns:yang:ietf-yang-push
2126 Registrant Contact: The IESG.
2127 XML: N/A; the requested URI is an XML namespace.
2129 This document registers the following YANG module in the "YANG Module
2130 Names" registry [RFC6020]:
2132 Name: ietf-yang-push
2133 Namespace: urn:ietf:params:xml:ns:yang:ietf-yang-push
2134 Prefix: yp
2135 Reference: draft-ietf-netconf-yang-push-08.txt (RFC form)
2137 7. Security Considerations
2139 All security considerations from [subscribe] are relevant for
2140 datastores. In addition there are specific security considerations
2141 for receviers defined in Section 3.9
2143 If the access control permissions on subscribed YANG nodes change
2144 during the lifecycle of a subscription, a publisher MUST either
2145 transparently conform to the new access control permissions, or must
2146 terminate or restart the subscriptions so that new access control
2147 permissions are re-established.
2149 The NETCONF Authorization Control Model SHOULD be used to restrict
2150 the delivery of YANG nodes for which the receiver has no access.
2152 8. Acknowledgments
2154 For their valuable comments, discussions, and feedback, we wish to
2155 acknowledge Tim Jenkins, Kent Watsen, Susan Hares, Yang Geng, Peipei
2156 Guo, Michael Scharf, Sharon Chisholm, and Guangying Zheng.
2158 9. References
2160 9.1. Normative References
2162 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
2163 DOI 10.17487/RFC3688, January 2004, .
2166 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
2167 the Network Configuration Protocol (NETCONF)", RFC 6020,
2168 DOI 10.17487/RFC6020, October 2010, .
2171 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF)
2172 Base Notifications", RFC 6470, DOI 10.17487/RFC6470,
2173 February 2012, .
2175 [RFC6536bis]
2176 Bierman, A. and M. Bjorklund, "Network Configuration
2177 Protocol (NETCONF) Access Control Model", draft-ietf-
2178 netconf-rfc6536bis-04 (work in progress), June 2017.
2180 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
2181 Library", RFC 7895, DOI 10.17487/RFC7895, June 2016,
2182 .
2184 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
2185 RFC 7950, DOI 10.17487/RFC7950, August 2016,
2186 .
2188 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG",
2189 RFC 7951, DOI 10.17487/RFC7951, August 2016,
2190 .
2192 [RFC8072] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch
2193 Media Type", RFC 8072, DOI 10.17487/RFC8072, February
2194 2017, .
2196 [subscribe]
2197 Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A.,
2198 and E. Nilsen-Nygaard, "Custom Subscription to Event
2199 Notifications", draft-ietf-netconf-subscribed-
2200 notifications-03 (work in progress), July 2017.
2202 9.2. Informative References
2204 [http-notif]
2205 Voit, E., Gonzalez Prieto, A., Tripathy, A., Nilsen-
2206 Nygaard, E., Clemm, A., and A. Bierman, "Restconf and HTTP
2207 Transport for Event Notifications", August 2017.
2209 [netconf-notif]
2210 Gonzalez Prieto, A., Clemm, A., Voit, E., Nilsen-Nygaard,
2211 E., and A. Tripathy, "NETCONF Support for Event
2212 Notifications", July 2017.
2214 [notifications2]
2215 Voit, E., Bierman, A., Clemm, A., and T. Jenkins, "YANG
2216 Notification Headers and Bundles", July 2017.
2218 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
2219 and A. Bierman, Ed., "Network Configuration Protocol
2220 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
2221 .
2223 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface
2224 Management", RFC 7223, DOI 10.17487/RFC7223, May 2014,
2225 .
2227 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements
2228 for Subscription to YANG Datastores", RFC 7923,
2229 DOI 10.17487/RFC7923, June 2016, .
2232 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2233 Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
2234 .
2236 Appendix A. Relationships to other drafts
2238 There are other related drafts which are progressing in the NETCONF
2239 WG. This section details the relationship of this draft to those
2240 others.
2242 A.1. ietf-netconf-subscribed-notifications
2244 The draft [subscribe] is the techical foundation around which the
2245 rest of the YANG push datastore specific mechanisms are layered.
2247 A.2. ietf-netconf-netconf-event-notif
2249 The [netconf-notif] draft supports yang-push by defining NETCONF
2250 transport specifics. Included are:
2252 o bindings for RPC communications and Event Notifications over
2253 NETCONF.
2255 o encoded examples
2257 A.3. ietf-netconf-restconf-notif
2259 The [http-notif] draft supports yang-push by defining transport
2260 specific guidance where some form of HTTP is used underneath.
2261 Included are:
2263 o bindings for RPC communications over RESTCONF
2265 o bindings for Event Notifications over HTTP2 and HTTP1.1
2267 o encoded examples
2269 o end-to-end deployment guidance for Call Home and TLS Heartbeat
2271 A.4. voit-notifications2
2273 The draft [notifications2] is not required to implement yang-push.
2274 Instead it defines data plane notification elements which improve the
2275 delivered experience. The following capabilities are specified:
2277 o Defines common encapsulation headers objects to support
2278 functionality such as event severity, message signing, message
2279 loss discovery, message de-duplication, originating process
2280 identification.
2282 o Defines how to bundle multiple event records into a single
2283 notification message.
2285 These capabilities would be delivered by adding the drafts newly
2286 proposed header objects to the push-update and push-change-update
2287 notifications defined here. This draft is not yet adopted by the
2288 NETCONF WG.
2290 Appendix B. Technologies to be considered for future iterations
2292 B.1. Proxy YANG Subscription when the Subscriber and Receiver are
2293 different
2295 The properties of Dynamic and Configured Subscriptions can be
2296 combined to enable deployment models where the Subscriber and
2297 Receiver are different. Such separation can be useful with some
2298 combination of:
2300 o An operator does not want the subscription to be dependent on the
2301 maintenance of transport level keep-alives. (Transport
2302 independence provides different scalability characteristics.)
2304 o There is not a transport session binding, and a transient
2305 Subscription needs to survive in an environment where there is
2306 unreliable connectivity with the Receiver and/or Subscriber.
2308 o An operator wants the Publisher to include highly restrictive
2309 capacity management and Subscription security mechanisms outside
2310 of domain of existing operational or programmatic interfaces.
2312 To build a Proxy Subscription, first the necessary information must
2313 be signaled as part of the . Using this set
2314 of Subscriber provided information; the same process described within
2315 section 3 will be followed.
2317 After a successful establishment, if the Subscriber wishes to track
2318 the state of Receiver subscriptions, it may choose to place a
2319 separate on-change Subscription into the "Subscriptions" subtree of
2320 the YANG Datastore on the Publisher.
2322 B.2. OpState and Filters
2324 Currently the concept of datastores is undergoing a transformation.
2325 A new Network Management Datastore Architecture (NMDA) is currently
2326 being defined that will allow for improved handling and distinction
2327 of intended versus applied configurations. It will also extend the
2328 notion of a datastore to operational data. For implementations that
2329 are NMDA compliant in the future, some of the objects that are
2330 currently defined as operational data will no longer be required
2331 because they will in effect be redundant. Specifically, this
2332 concerns many of the objects in the read-only subscriptions branch of
2333 the tree. By omitting those objects, the model could be optimized
2334 further. However, there is no harm in the redundant objects and they
2335 allow for common management of YANG-Push subscriptions whether or not
2336 the underlying platform is fully NMDA-compliant, as opposed to
2337 exposing client applications to heterogeneity in platform NMDA
2338 capabilities.
2340 It is conceivable that filters are defined that apply to metadata,
2341 such as data nodes for which metadata has been defined that meets a
2342 certain criteria.
2344 It is also conceivable to define in the future filters that are
2345 applied to actual data node values. Doing so would allow
2346 applications to subscribe to updates that are sent only when object
2347 values meet certain criteria, such as being outside a certain range.
2349 Defining any such subscription filters at this point would be highly
2350 speculative in nature. However, it should be noted that
2351 corresponding extensions may be defined in future specifications.
2352 Any such extensions will be straightforward to accommodate by
2353 introducing a model that defines new filter types, and augmenting the
2354 new filter type into the subscription model.
2356 B.3. Splitting push updates
2358 Push updates may become fairly large and extend across multiple
2359 subsystems in a YANG-Push Server. As a result, it conceivable to not
2360 combine all updates into a single update message, but to split
2361 updates into multiple separate update messages. Such splitting could
2362 occur along multiple criteria: limiting the number of data nodes
2363 contained in a single update, grouping updates by subtree, grouping
2364 updates by internal subsystems (e.g., by line card), or grouping them
2365 by other criteria.
2367 Splitting updates bears some resemblance to fragmenting packets. In
2368 effect, it can be seen as fragmenting update messages at an
2369 application level. However, from a transport perspective, splitting
2370 of update messages is not required as long as the transport does not
2371 impose a size limitation or provides its own fragmentation mechanism
2372 if needed. We assume this to be the case for YANG-Push. In the case
2373 of NETCONF, RESTCONF, HTTP/2, no limit on message size is imposed.
2374 In case of other transports, any message size limitations need to be
2375 handled by the corresponding transport mapping.
2377 There may be some scenarios in which splitting updates might still
2378 make sense. For example, if updates are collected from multiple
2379 independent subsystems, those updates could be sent separately
2380 without need for combining. However, if updates were to be split,
2381 other issues arise. Examples include indicating the number of
2382 updates to the receiver, distinguishing a missed fragment from a
2383 missed update, and the ordering with which updates are received.
2384 Proper addressing those issues would result in considerable
2385 complexity, while resulting in only very limited gains. In addition,
2386 if a subscription is found to result in updates that are too large, a
2387 publisher can always reject the request for a subscription while the
2388 subscriber is always free to break a subscription up into multiple
2389 subscriptions.
2391 B.4. Potential Subscription Parameters
2393 A possible is the introduction of an additional parameter "changes-
2394 only" for periodic subscription. Including this flag would results
2395 in sending at the end of each period an update containing only
2396 changes since the last update (i.e. a change-update as in the case of
2397 an on-change subscription), not a full snapshot of the subscribed
2398 information. Such an option might be interesting in case of data
2399 that is largely static and bandwidth-constrained environments.
2401 Appendix C. Changes between revisions
2403 (To be removed by RFC editor prior to publication)
2405 v07 - v08
2407 o Updated YANG models with minor tweaks to accommodate changes of
2408 ietf-subscribed-notifications.
2410 v06 - v07
2412 o Clarifying text tweaks.
2414 o Clarification that filters act as selectors for subscribed data
2415 nodes; support for value filters not included but possible as a
2416 future extension
2418 o Filters don't have to be matched to existing YANG objects
2420 v05 - v06
2422 o Security considerations updated.
2424 o Base YANG model in [sn] updated as part of move to identities,
2425 YANG augmentations in this doc matched up
2427 o Terms refined and text updates throughout
2429 o Appendix talking about relationship to other drafts added.
2431 o Datastore replaces stream
2432 o Definitions of filters improved
2434 v04 to v05
2436 o Referenced based subscription document changed to Subscribed
2437 Notifications from 5277bis.
2439 o Getting operational data from filters
2441 o Extension notifiable-on-change added
2443 o New appendix on potential futures. Moved text into there from
2444 several drafts.
2446 o Subscription configuration section now just includes changed
2447 parameters from Subscribed Notifications
2449 o Subscription monitoring moved into Subscribed Notifications
2451 o New error and hint mechanisms included in text and in the yang
2452 model.
2454 o Updated examples based on the error definitions
2456 o Groupings updated for consistency
2458 o Text updates throughout
2460 v03 to v04
2462 o Updates-not-sent flag added
2464 o Not notifiable extension added
2466 o Dampening period is for whole subscription, not single objects
2468 o Moved start/stop into rfc5277bis
2470 o Client and Server changed to subscriber, publisher, and receiver
2472 o Anchor time for periodic
2474 o Message format for synchronization (i.e. synch-on-start)
2476 o Material moved into 5277bis
2478 o QoS parameters supported, by not allowed to be modified by RPC
2479 o Text updates throughout
2481 Authors' Addresses
2483 Alexander Clemm
2484 Huawei
2486 Email: ludwig@clemm.org
2488 Eric Voit
2489 Cisco Systems
2491 Email: evoit@cisco.com
2493 Alberto Gonzalez Prieto
2494 VMware
2496 Email: agonzalezpri@vmware.com
2498 Ambika Prasad Tripathy
2499 Cisco Systems
2501 Email: ambtripa@cisco.com
2503 Einar Nilsen-Nygaard
2504 Cisco Systems
2506 Email: einarnn@cisco.com
2508 Andy Bierman
2509 YumaWorks
2511 Email: andy@yumaworks.com
2513 Balazs Lengyel
2514 Ericsson
2516 Email: balazs.lengyel@ericsson.com