idnits 2.17.1
draft-ietf-netconf-yang-push-04.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** The document seems to lack an IANA Considerations section. (See Section
2.2 of https://www.ietf.org/id-info/checklist for how to handle the case
when there are no actions for IANA.)
** 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 368: '... SHOULD include in the returned erro...'
RFC 2119 keyword, line 407: '...cription request MUST be rejected. As...'
RFC 2119 keyword, line 443: '... MUST support XML encoding and MAY s...'
RFC 2119 keyword, line 677: '... MAY be returned that would likely h...'
RFC 2119 keyword, line 805: '... Implementations MAY therefore choose,...'
(6 more instances...)
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Line 909 has weird spacing: '...lter-id fil...'
== Line 943 has weird spacing: '...-period yan...'
== Line 955 has weird spacing: '...address ine...'
== The document seems to contain a disclaimer for pre-RFC5378 work, but was
first submitted on or after 10 November 2008. The disclaimer is usually
necessary only for documents that revise or obsolete older RFCs, and that
take significant amounts of text from those RFCs. If you can contact all
authors of the source material and they are willing to grant the BCP78
rights to the IETF Trust, you can and should remove the disclaimer.
Otherwise, the disclaimer is needed and you can ignore this comment.
(See the Legal Provisions document at
https://trustee.ietf.org/license-info for more information.)
-- The document date (October 28, 2016) is 2730 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)
-- No information found for draft-ietf-netconf-5277bis - is the name
correct?
-- Possible downref: Normative reference to a draft: ref.
'I-D.ietf-netconf-5277bis'
== Outdated reference: A later version (-14) exists of
draft-ietf-netconf-yang-patch-12
** Obsolete normative reference: RFC 6536 (Obsoleted by RFC 8341)
** Obsolete normative reference: RFC 7895 (Obsoleted by RFC 8525)
== Outdated reference: A later version (-18) exists of
draft-ietf-netconf-restconf-17
Summary: 4 errors (**), 0 flaws (~~), 7 warnings (==), 3 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
1 Network Working Group A. Clemm
2 Internet-Draft Sympotech
3 Intended status: Standards Track E. Voit
4 Expires: May 1, 2017 A. Gonzalez Prieto
5 A. Tripathy
6 E. Nilsen-Nygaard
7 Pre-release version Cisco Systems
8 A. Bierman
9 YumaWorks
10 B. Lengyel
11 Ericsson
12 October 28, 2016
14 Subscribing to YANG datastore push updates
15 draft-ietf-netconf-yang-push-04
17 Abstract
19 This document defines a subscription and push mechanism for YANG
20 datastores. This mechanism allows subscriber applications to request
21 updates from a YANG datastore, which are then pushed by the publisher
22 to a receiver per a subscription policy, without requiring additional
23 subscriber requests.
25 Status of This Memo
27 This Internet-Draft is submitted in full conformance with the
28 provisions of BCP 78 and BCP 79.
30 Internet-Drafts are working documents of the Internet Engineering
31 Task Force (IETF). Note that other groups may also distribute
32 working documents as Internet-Drafts. The list of current Internet-
33 Drafts is at http://datatracker.ietf.org/drafts/current/.
35 Internet-Drafts are draft documents valid for a maximum of six months
36 and may be updated, replaced, or obsoleted by other documents at any
37 time. It is inappropriate to use Internet-Drafts as reference
38 material or to cite them other than as "work in progress."
40 This Internet-Draft will expire on May 1, 2017.
42 Copyright Notice
44 Copyright (c) 2016 IETF Trust and the persons identified as the
45 document authors. All rights reserved.
47 This document is subject to BCP 78 and the IETF Trust's Legal
48 Provisions Relating to IETF Documents
49 (http://trustee.ietf.org/license-info) in effect on the date of
50 publication of this document. Please review these documents
51 carefully, as they describe your rights and restrictions with respect
52 to this document. Code Components extracted from this document must
53 include Simplified BSD License text as described in Section 4.e of
54 the Trust Legal Provisions and are provided without warranty as
55 described in the Simplified BSD License.
57 This document may contain material from IETF Documents or IETF
58 Contributions published or made publicly available before November
59 10, 2008. The person(s) controlling the copyright in some of this
60 material may not have granted the IETF Trust the right to allow
61 modifications of such material outside the IETF Standards Process.
62 Without obtaining an adequate license from the person(s) controlling
63 the copyright in such materials, this document may not be modified
64 outside the IETF Standards Process, and derivative works of it may
65 not be created outside the IETF Standards Process, except to format
66 it for publication as an RFC or to translate it into languages other
67 than English.
69 Table of Contents
71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
72 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 5
73 3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 6
74 3.1. Subscription Model . . . . . . . . . . . . . . . . . . . 6
75 3.2. Negotiation of Subscription Policies . . . . . . . . . . 8
76 3.3. On-Change Considerations . . . . . . . . . . . . . . . . 9
77 3.4. Data Encodings . . . . . . . . . . . . . . . . . . . . . 10
78 3.5. YANG object filters . . . . . . . . . . . . . . . . . . . 11
79 3.6. Push Data Stream and Transport Mapping . . . . . . . . . 11
80 3.7. Subscription management . . . . . . . . . . . . . . . . . 15
81 3.8. Other considerations . . . . . . . . . . . . . . . . . . 16
82 4. A YANG data model for management of datastore push
83 subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 20
84 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 20
85 4.2. Update streams . . . . . . . . . . . . . . . . . . . . . 26
86 4.3. Filters . . . . . . . . . . . . . . . . . . . . . . . . . 27
87 4.4. Subscription configuration . . . . . . . . . . . . . . . 27
88 4.5. Subscription monitoring . . . . . . . . . . . . . . . . . 29
89 4.6. Notifications . . . . . . . . . . . . . . . . . . . . . . 29
90 4.7. RPCs . . . . . . . . . . . . . . . . . . . . . . . . . . 31
91 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 35
92 6. Security Considerations . . . . . . . . . . . . . . . . . . . 47
93 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 48
94 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 48
95 8.1. Normative References . . . . . . . . . . . . . . . . . . 48
96 8.2. Informative References . . . . . . . . . . . . . . . . . 48
97 Appendix A. Issues that are currently being worked and resolved 49
98 A.1. Unresolved and yet-to-be addressed issues . . . . . . . . 49
99 A.2. Agreement in principal . . . . . . . . . . . . . . . . . 49
100 Appendix B. Changes between revisions . . . . . . . . . . . . . 50
101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 50
103 1. Introduction
105 YANG [RFC7950] was originally designed for the Netconf protocol
106 [RFC6241] which focused on configuration data. However, YANG can be
107 used to model both configuration and operational data. It is
108 therefore reasonable to expect YANG datastores will increasingly be
109 used to support applications that care about about both.
111 For example, service assurance applications will need to be aware of
112 any remote updates to configuration and operational objects. Rapid
113 awareness of object changes will enable such things as validating and
114 maintaining cross-network integrity and consistency, or monitoring
115 state and key performance indicators of remote devices.
117 Traditional approaches to remote visibility have been built on
118 polling. With polling, data is periodically explicitly retrieved by
119 a client from a server to stay up-to-date. However, there are issues
120 associated with polling-based management:
122 o It introduces additional load on network, devices, and
123 applications. Each polling cycle requires a separate yet arguably
124 redundant request that results in an interrupt, requires parsing,
125 consumes bandwidth.
127 o It lacks robustness. Polling cycles may be missed, requests may
128 be delayed or get lost, often particularly in cases when the
129 network is under stress and hence exactly when the need for the
130 data is the greatest.
132 o Data may be difficult to calibrate and compare. Polling requests
133 may undergo slight fluctuations, resulting in intervals of
134 different lengths which makes data hard to compare. Likewise,
135 pollers may have difficulty issuing requests that reach all
136 devices at the same time, resulting in offset polling intervals
137 which again make data hard to compare.
139 A more effective alternative to polling is when an application can
140 request to be automatically updated on current relevant content of a
141 datastore. If such a request is accepted, interesting updates will
142 subsequently be pushed from that datastore.
144 Dependence on polling-based management is typically considered an
145 important shortcoming of applications that rely on MIBs polled using
146 SNMP [RFC1157]. However, without a provision to support a push-based
147 alternative, there is no reason to believe that management
148 applications that operate on YANG datastores will be any more
149 effective, as they would follow the same request/response pattern.
151 While YANG allows the definition of push notifications, such
152 notifications generally indicate the occurrence of certain well-
153 specified event conditions, such as the onset of an alarm condition
154 or the occurrence of an error. A capability to subscribe to and
155 deliver such pre-defined event notifications has been defined in
156 [RFC5277]. In addition, configuration change notifications have been
157 defined in [RFC6470]. These change notifications pertain only to
158 configuration information, not to operational state, and convey the
159 root of the subtree to which changes were applied along with the
160 edits, but not the modified data nodes and their values.
161 Furthermore, while delivery of updates using notifications is a
162 viable option, some applications desire the ability to stream updates
163 using other transports.
165 Accordingly, there is a need for a service that allows applications
166 to dynamically subscribe to updates of a YANG datastore and that
167 allows the publisher to push those updates, possibly using one of
168 several delivery mechanisms. Additionally, support for subscriptions
169 configured directly on the publisher are also useful when dynamic
170 signaling is undesirable or unsupported. The requirements for such a
171 service are documented in [RFC7923].
173 This document proposes a solution. The solution builds on top of the
174 Netconf Event Model [I-D.ietf-netconf-5277bis] which defines a
175 mechanism for the management of event subscriptions. At its core,
176 the solution defined here introduces a new set of event streams which
177 maybe subscribed, introduces datastore push update mechanisms, and
178 provides extensions to the event subscription model. The document
179 also includes YANG data model augmentations which extend the model
180 and RPCs defined within [I-D.ietf-netconf-5277bis].
182 Key capabilities worth highlighting include:
184 o An extension to event subscription mechanisms allowing clients to
185 subscribe to event streams containing automatic datastore updates.
186 The subscription allows clients to specify which data they are
187 interested in, what types of updates (e.g. create, delete,
188 modify), and to provide optional filters with criteria that data
189 must meet for updates to be sent. Furthermore, subscriptions can
190 specify a policy that directs when updates are provided. For
191 example, a client may request to be updated periodically in
192 certain intervals, or whenever data changes occur.
194 o Format and contents of the YANG push updates themselves.
196 o The ability for a publisher to push back on requested subscription
197 parameters. Because not every publisher may support every
198 requested update policy for every piece of data, it is necessary
199 for a publisher to be able to indicate whether or not it is
200 capable of supporting a requested subscription, and possibly allow
201 to negotiate push update subscription parameters. For example,
202 some publishers may have a lower limit to the period with which
203 they can send updates, or they may not support on-change updates
204 for every piece of data.
206 o Subscription parameters which allow the specification of QoS
207 extensions to address prioritization between independent streams
208 of updates.
210 2. Definitions and Acronyms
212 Many of the terms in this document are defined in
213 [I-D.ietf-netconf-5277bis]. Please see that document for these
214 definitions.
216 Data node: An instance of management information in a YANG datastore.
218 Data node update: A data item containing the current value/property
219 of a Data node at the time the data node update was created.
221 Data record: A record containing a set of one or more data node
222 instances and their associated values.
224 Datastore: A conceptual store of instantiated management information,
225 with individual data items represented by data nodes which are
226 arranged in hierarchical manner.
228 Datastream: A continuous stream of data records, each including a set
229 of updates, i.e. data node instances and their associated values.
231 Data subtree: An instantiated data node and the data nodes that are
232 hierarchically contained within it.
234 Push-update stream: A conceptual data stream of a datastore that
235 streams the entire datastore contents continuously and perpetually.
237 Update: A data item containing the current value of a data node.
239 Update notification: An Event Notification including those data node
240 update(s) to be pushed in order to meet the obligations of a single
241 Subscription. All included data node updates must reflect the state
242 of a Datastore at a snapshot in time.
244 Update record: A representation of a data node update as a data
245 record. An update record can be included as part of an update
246 stream. It can also be logged for retrieval. In general, an update
247 record will include the value/property of a data node. It may also
248 include information about the type of data node update, i.e. whether
249 the data node was modified/updated, or newly created, or deleted.
251 Update trigger: A mechanism, as specified by a Subscription Policy,
252 that determines when a data node update is to be communicated. (e.g.,
253 a change trigger, invoked when the value of a data node changes or a
254 data node is created or deleted, or a time trigger, invoked after the
255 laps of a periodic time interval.)
257 YANG object filter: A filter that contains evaluation criteria which
258 are evaluated against YANG objects of a subscription. An update is
259 only published if the object meets the specified filter criteria.
261 YANG-Push: The subscription and push mechanism for YANG datastores
262 that is specified in this document.
264 3. Solution Overview
266 This document specifies a solution for a push update subscription
267 service. This solution supports the dynamic as well as configured
268 subscriptions to information updates from YANG datastores. A
269 subscription might target exposed operational and/or configuration
270 YANG objects on a device. YANG objects are subsequently pushed from
271 the publisher to the receiver per the terms of the subscription.
273 3.1. Subscription Model
275 YANG-push subscriptions are defined using a data model that is itself
276 defined in YANG. This model augments the event subscription model
277 defined in [I-D.ietf-netconf-5277bis] and introduces several new
278 parameters that allow subscribers to specify what to include in an
279 update notification and what triggers such an update notification.
281 The subscription model assumes the presence of one or more conceptual
282 perpetual datastreams of continuous subscribable YANG updates. There
283 are several datastreams with predefined semantics, such as the stream
284 of updates of all operational data or the stream of updates of all
285 config data. In addition, it is possible to define custom streams
286 with customizable semantics. The model includes the list of update
287 datastreams that are supported by a system and available for
288 subscription.
290 The subscription model augments the [I-D.ietf-netconf-5277bis]
291 subscription model with a set of parameters:
293 o Anydata encoding for periodic and on-change push updates.
295 o A subscription policy definition regarding the update trigger when
296 to send new update notifications.
298 * For periodic subscriptions, the trigger is defined by two
299 parameters that defines the interval with which updates are to
300 be pushed. These parameters are the period/interval of
301 reporting duration, and an anchor time which can be used to
302 calculate at which times updates needs to be assembled and
303 sent.
305 * EDITOR'S NOTE: A possible option to discuss concerns the
306 introduction of an additional parameter "changes-only" for
307 periodic subscription. Including this flag would results in
308 sending at the end of each period an update containing only
309 changes since the last update (i.e. a change-update as in the
310 case of an on-change subscription), not a full snapshot of the
311 subscribed information. Such an option might be interesting in
312 case of data that is largely static and bandwidth-constrained
313 environments.
315 * For on-change subscriptions, the trigger occurs whenever a
316 change in the subscribed information is detected. On-change
317 subscriptions have more complex semantics that can be guided by
318 additional parameters. Please refer also to Section 3.3.
320 + One parameter specifies the dampening period, i.e. the
321 interval that must pass before a successive update
322 notification for the same Subscription is sent. Note that
323 the dampening period applies to the set of all data nodes
324 within a single subscription. This means that on the first
325 change of an object, an update notification containing that
326 object is sent either immediately or at the end of a
327 dampening period already in effect.
329 + Another parameter allows to restrict the types of changes
330 for which updates are sent (changes to object values, object
331 creation or deletion events). It is conceivable to augment
332 the data model with additional parameters in the future to
333 specify even more refined policies, such as parameters that
334 specify the magnitude of a change that must occur before an
335 update is triggered.
337 + A third parameter specifies whether or not a complete update
338 with all the subscribed data should be sent at the beginning
339 of a subscription to facilitate synchronization and
340 establish the frame of reference for subsequent updates.
342 o Optionally, a filter, or set of filters, describing the subset of
343 data node updates that are of interest to the subscriber. The
344 publisher must only send to the subscriber those data node updates
345 that can traverse applied filter(s). The absence of a filter
346 indicates that all data items from the stream are of interest to
347 the subscriber and all data records must be sent in their entirety
348 to the subscriber. The following types of filters are supported:
349 subtree filters, with the same semantics as defined in
350 [RFC6241][RFC6241], and XPath filters. Additional filter types
351 can be added through augmentations. Filters can be specified
352 "inline" as part of the subscription, or can be configured
353 separately and referenced by a subscription, in order to
354 facilitate reuse of complex filters.
356 The subscription data model is specified as part of the YANG data
357 model described later in this specification. It is conceivable that
358 additional subscription parameters might be added in the future.
359 This can be accomplished through augmentation of the subscription
360 data model.
362 3.2. Negotiation of Subscription Policies
364 Dynamic subscriptions must support a simple negotiation between
365 subscribers and publishers for subscription parameters. This
366 negotiation is limited to a single pair of subscription request and
367 response messages. For negative response messages, the publisher
368 SHOULD include in the returned error what subscription parameters
369 would have been accepted for the request. The returned acceptable
370 parameters constitute suggestions that, when followed, increase the
371 likelihood of success for subsequent requests. However, there are no
372 guarantee that subsequent requests for this subscriber will in fact
373 be accepted.
375 A subscription request might be declined based on publisher's
376 assessment that it may be unable to provide a filtered update
377 notification stream that would meet the terms of the establish-
378 subscription request.
380 In case a subscriber requests an encoding other than XML, and this
381 encoding is not supported by the publisher, the publisher simply
382 indicates in the response that the encoding is not supported.
384 A subscription negotiation capability has been introduced as part of
385 the NETCONF Event Notifications model. However, the ability to
386 negotiate subscriptions is of particular importance in conjunction
387 with push updates, as publisher implementations may have limitations
388 with regards to what updates can be generated and at what velocity.
390 3.3. On-Change Considerations
392 On-change subscriptions allow subscribers to subscribe to updates
393 whenever changes to objects occur. As such, on-change subscriptions
394 are of particular interest for data that changes relatively
395 infrequently, yet that require applications to be notified with
396 minimal delay when changes do occur.
398 On-change subscriptions tend to be more difficult to implement than
399 periodic subscriptions. Specifically, on-change subscriptions may
400 involve a notion of state to see if a change occurred between past
401 and current state, or the ability to tap into changes as they occur
402 in the underlying system. Accordingly, on-change subscriptions may
403 not be supported by all implementations or for every object.
405 When an on-change subscription is requested for a datastream with a
406 given subtree filter, where not all objects support on-change update
407 triggers, the subscription request MUST be rejected. As a result,
408 on-change subscription requests will tend to be directed at very
409 specific, targeted subtrees with only few objects.
411 Any updates for an on-change subscription will include only objects
412 for which a change was detected. To avoid flooding receivers with
413 repeated updates for fast-changing objects, or objects with
414 oscillating values, an on-change subscription allows for the
415 definition of a dampening period. Once an update for a given object
416 is sent, no other updates for this particular object are sent until
417 the end of the dampening period. Values sent at the end of the
418 dampening period are the values current when that dampening period
419 expires. In addition, updates include information about objects that
420 were deleted and ones that were newly created.
422 On-change subscriptions can be refined to let users subscribe only to
423 certain types of changes, for example, only to object creations and
424 deletions, but not to modifications of object values.
426 Additional refinements are conceivable. For example, in order to
427 avoid sending updates on objects whose values undergo only a
428 negligible change, additional parameters might be added to an on-
429 change subscription specifying a YANG object filter that states how
430 large or "significant" a change has to be before an update is sent.
431 A simple policy is a "delta-policy" that states, for integer-valued
432 data nodes, the minimum difference between the current value and the
433 value that was last reported that triggers an update. Also more
434 sophisticated policies are conceivable, such as policies specified in
435 percentage terms or policies that take into account the rate of
436 change. While not specified as part of this draft, such policies can
437 be accommodated by augmenting the subscription data model
438 accordingly.
440 3.4. Data Encodings
442 Subscribed data is encoded in either XML or JSON format. A publisher
443 MUST support XML encoding and MAY support JSON encoding.
445 It is conceivable that additional encodings may be supported as
446 options in the future. This can be accomplished by augmenting the
447 subscription data model with additional identity statements used to
448 refer to requested encodings.
450 3.4.1. Periodic Subscriptions
452 In a periodic subscription, the data included as part of an update
453 corresponds to data that could have been simply retrieved using a get
454 operation and is encoded in the same way. XML encoding rules for
455 data nodes are defined in [RFC7950]. JSON encoding rules are defined
456 in [RFC7951]. This encoding is valid JSON, but also has special
457 encoding rules to identify module namespaces and provide consistent
458 type processing of YANG data.
460 3.4.2. On-Change Subscriptions
462 In an on-change subscription, updates need to indicate not only
463 values of changed data nodes but also the types of changes that
464 occurred since the last update, such as whether data nodes were newly
465 created since the last update or whether they were merely modified,
466 as well as which data nodes were deleted.
468 Encoding rules for data in on-change updates correspond to how data
469 would be encoded in a YANG-patch operation as specified in
470 [I-D.ietf-netconf-yang-patch]. The "YANG-patch" would in this case
471 be applied to the earlier state reported by the preceding update, to
472 result in the now-current state of YANG data. Of course, contrary to
473 a YANG-patch operation, the data is sent from the publisher to the
474 receiver and is not restricted to configuration data.
476 3.5. YANG object filters
478 Subscriptions can specify filters for subscribed data. The following
479 filters are supported:
481 o subtree-filter: A subtree filter specifies a subtree that the
482 subscription refers to. When specified, updates will only concern
483 data nodes from this subtree. Syntax and semantics correspond to
484 that specified for [RFC6241] section 6.
486 o xpath-filter: An XPath filter specifies an XPath expression
487 applied to the data in an update, assuming XML-encoded data.
489 Only a single filter can be applied to a subscription at a time.
491 It is conceivable for implementations to support other filters. For
492 example, an on-change filter might specify that changes in values
493 should be sent only when the magnitude of the change since previous
494 updates exceeds a certain threshold. It is possible to augment the
495 subscription data model with additional filter types.
497 3.6. Push Data Stream and Transport Mapping
499 Pushing data based on a subscription could be considered analogous to
500 a response to a data retrieval request, e.g. a "get" request.
501 However, contrary to such a request, multiple responses to the same
502 request may get sent over a longer period of time.
504 An applicable mechanism is that of a notification. There are however
505 some specifics that need to be considered. Contrary to other
506 notifications that are associated with alarms and unexpected event
507 occurrences, update notifications are solicited, i.e. tied to a
508 particular subscription which triggered the notification.
510 A push update notification contains several parameters:
512 o A subscription correlator, referencing the name of the
513 subscription on whose behalf the notification is sent.
515 o Data nodes containing a representation of the datastore subtree(s)
516 containing the updates. In all cases, the subtree(s) are filtered
517 per access control rules to contain only data that the subscriber
518 is authorized to see. For on-change subscriptions, the subtree
519 may only contain the data nodes which have changed since the start
520 of the previous dampening interval.
522 This document introduces two generic notifications: "push-update" and
523 "push-change-update". Those notifications may be encapsulated on a
524 transport (e.g. Netconf notifications and HTTP) to carry data
525 records with updates of datastore contents as specified by a
526 subscription. It is possible also map notifications to other
527 transports and encodings and use the same subscription model;
528 however, the definition of such mappings is outside the scope of this
529 document.
531 A push-update notification defines a complete update of the datastore
532 per the terms of a subscription. This type of notification is used
533 for continuous updates of periodic subscriptions. A push-update
534 notification can also used be for the on-change subscriptions in two
535 cases. First it will be used as the initial push-update if there is
536 a need to synchronize the receiver at the start of a new
537 subscription. It also may be sent if the publisher later chooses to
538 resynch a previously synched on-change subscription. The push-update
539 record contains a data snippet that contains an instantiated subtree
540 with the subscribed contents. The content of the update notification
541 is equivalent to the contents that would be obtained had the same
542 data been explicitly retrieved using e.g. a Netconf "get"-operation,
543 with the same filters applied.
545 The contents of the notification conceptually represents the union of
546 all data nodes in the yang modules supported by the publisher.
547 However, in a YANG data model, it is not practical to model the
548 precise data contained in the updates as part of the notification.
549 This is because the specific data nodes supported depend on the
550 implementing system and may even vary dynamically. Therefore, to
551 capture this data, a single parameter that can represent any
552 datastore contents is used, not parameters that represent data nodes
553 one at a time.
555 A push-change-update notification is the most common type of update
556 for on-change subscriptions. It is not used for periodic
557 subscriptions. The update record in this case contains a data
558 snippet that indicates the full set of changes that data nodes have
559 undergone since the last notification of YANG objects. In other
560 words, this indicates which data nodes have been created, deleted, or
561 have had changes to their values. The format of the data snippet
562 follows YANG-patch [I-D.ietf-netconf-yang-patch], i.e. the same
563 format that would be used with a YANG-patch operation to apply
564 changes to a data tree, indicating the creates, deletes, and
565 modifications of data nodes. Please note that as the update can
566 include a mix of configuration and operational data
568 The following is an example of push notification. It contains an
569 update for subscription 1011, including a subtree with root foo that
570 contains a leaf, bar:
572
574 2015-03-09T19:14:56Z
575
577 1011
578 2015-03-09T19:14:56.233Z
579
580
581 some_string
582
583
584
585
587 Figure 1: Push example
589 The following is an example of an on-change notification. It
590 contains an update for subscription 89, including a new value for a
591 leaf called beta, which is a child of a top-level container called
592 alpha:
594
596 2015-03-09T19:14:56Z
597
599 89
600 2015-03-09T19:14:56.233Z
601
602
603 1500
604
605
606
607
609 Figure 2: Push example for on change
611 The equivalent update when requesting json encoding:
613
615 2015-03-09T19:14:56Z
616
618 89
619 2015-03-09T19:14:56.233Z
620
621 {
622 "ietf-yang-patch:yang-patch": {
623 "patch-id": [
624 null
625 ],
626 "edit": [
627 {
628 "edit-id": "edit1",
629 "operation": "merge",
630 "target": "/alpha/beta",
631 "value": {
632 "beta": 1500
633 }
634 }
635 ]
636 }
637 }
638
639
640
642 Figure 3: Push example for on change with JSON
644 When the beta leaf is deleted, the publisher may send
645
647 2015-03-09T19:14:56Z
648
650 89
651 2015-03-09T19:14:56.233Z
652
653
654
656
657
658
659
661 Figure 4: 2nd push example for on change update
663 3.7. Subscription management
665 A [[I-D.ietf-netconf-5277bis] subscription needs enhancment to
666 support YANG Push subscription negotiation. Specifically, these
667 enhancements are needed to signal to the subscriber why an attempt
668 has failed.
670 A subscription can be rejected for multiple reasons, including the
671 lack of authorization to establish a subscription, the lack of read
672 authorization on the requested data node, or the inability of the
673 publisher to provide a stream with the requested semantics. In such
674 cases, no subscription is established. Instead, the subscription-
675 result with the failure reason is returned as part of the RPC
676 response. In addition, a set of alternative subscription parameters
677 MAY be returned that would likely have resulted in acceptance of the
678 subscription request, which the subscriber may try for a future
679 subscription attempt.
681 It should be noted that a rejected subscription does not result in
682 the generation of an rpc-reply with an rpc-error element, as neither
683 the specification of YANG-push specific errors nor the specification
684 of additional data parameters to be returned in an error case are
685 supported as part of a YANG data model.
687 For instance, for the following request:
689
691
693 push-update
694
697 500
698 encode-xml
699
700
702 Figure 5: Establish-Subscription example
704 the publisher might return:
706
708
710 error-insufficient-resources
711
712 2000
713
715 Figure 6: Error response example
717 3.8. Other considerations
719 3.8.1. Authorization
721 A receiver of subscription data may only be sent updates for which
722 they have proper authorization. Data that is being pushed therefore
723 needs to be subjected to a filter that applies all corresponding
724 rules applicable at the time of a specific pushed update, silently
725 removing any non-authorized data from subtrees.
727 The authorization model for data in YANG datastores is described in
728 the Netconf Access Control Model [RFC6536]. However, some
729 clarifications to that RFC are needed so that the desired access
730 control behavior is applied to pushed updates.
732 One of these clarifications is that a subscription may only be
733 established if the receiver has read access to the target data node.
735 +-------------+ +-------------+
736 subscription | protocol | | target |
737 request --> | operation | -------------> | data node |
738 | allowed? | datastore | access |
739 +-------------+ or state | allowed? |
740 data access +-------------+
742 Figure 7: Access control for subscription
744 Likewise if a receiver no longer has read access permission to a
745 target data node, the subscription must be abnormally terminated
746 (with loss of access permission as the reason provided).
748 Another clarification to [RFC6536] is that each of the individual
749 nodes in a pushed update must also go through access control
750 filtering. This includes new nodes added since the last update
751 notification, as well as existing nodes. For each of these read
752 access must be verified. The methods of doing this efficiently are
753 left to implementation.
755 +-------------+ +-------------------+
756 subscription | data node | yes | |
757 update --> | access | ---> | add data node |
758 | allowed? | | to update message |
759 +-------------+ +-------------------+
761 Figure 8: Access control for push updates
763 If there are read access control changes applied under the target
764 node, no notifications indicating the fact that this has occurred
765 should be provided.
767 3.8.2. Robustness and reliability considerations
769 Particularly in the case of on-change push updates, it is important
770 that push updates do not get lost.
772 Update notifications will typically traverse a secure and reliable
773 transport. Notifications will not be reordered, and will also
774 contain a time stamp. Despite these protections for on-change, it is
775 possible that complete update notifications get lost. For this
776 reason, patch-ids may be included in a subscription so that an
777 application can determine if an update has been lost.
779 At the same time, it is conceivable that under certain circumstances,
780 a publisher will recognize that it is unable to include within an
781 update notification the full set of objects desired per the terms of
782 a subscription. In this case, the publisher must take one or more of
783 the following actions.
785 o A publisher must set the updates-not-sent flag on any update
786 notification which is known to be missing information.
788 o It may choose to suspend and resume a subscription as per
789 [I-D.ietf-netconf-5277bis].
791 o When resuming an on-change subscription, the publisher should
792 generate a complete patch from the previous update notification.
793 If this is not possible and the synch-on-start option is
794 configured, then the full datastore contents may be sent instead
795 (effectively replacing the previous contents). If neither of
796 these are possible, then an updates-not-sent flag must be included
797 on the next push-change-update.
799 3.8.3. Update size and fragmentation considerations
801 Depending on the subscription, the volume of updates can become quite
802 large. There is no inherent limitation to the amount of data that
803 can be included in a notification. That said, it may not always be
804 practical to send the entire update in a single chunk.
805 Implementations MAY therefore choose, at their discretion, to "chunk"
806 updates and break them out into several update notifications.
808 3.8.4. Push data streams
810 There are several conceptual data streams introduced in this
811 specification:
813 o yang-push includes the entirety of YANG data, including both
814 configuration and operational data.
816 o operational-push includes all operational (read-only) YANG data
818 o config-push includes all YANG configuration data.
820 It is conceivable to introduce other data streams with more limited
821 scope, for example:
823 o operdata-nocounts-push, a datastream containing all operational
824 (read-only) data with the exception of counters
826 o other custom datastreams
828 Those data streams make particular sense for use cases involving
829 service assurance (not relying on operational data), and for use
830 cases requiring on-change update triggers which make no sense to
831 support in conjunction with fast-changing counters. While it is
832 possible to specify subtree filters on yang-push to the same effect,
833 having those data streams greatly simplifies articulating
834 subscriptions in such scenarios.
836 3.8.5. Implementation considerations
838 Implementation specifics are outside the scope of this specification.
839 That said,it should be noted that monitoring of operational state
840 changes inside a system can be associated with significant
841 implementation challenges.
843 Even periodic retrieval and push of operational counters may consume
844 considerable system resources. In addition the on-change push of
845 small amounts of configuration data may, depending on the
846 implementation, require invocation of APIs, possibly on an object-by-
847 object basis, possibly involving additional internal interrupts, etc.
849 For those reasons, it is important for an implementation to
850 understand what subscriptions it can or cannot support. It is far
851 preferable to decline a subscription request then to accept such a
852 request when it cannot be met.
854 Whether or not a subscription can be supported will in general be
855 determined by a combination of several factors, including the
856 subscription policy (on-change or periodic, with on-change in general
857 being the more challenging of the two), the period in which to report
858 changes (1 second periods will consume more resources than 1 hour
859 periods), the amount of data in the subtree that is being subscribed
860 to, and the number and combination of other subscriptions that are
861 concurrently being serviced.
863 When providing access control to every node in a pushed update, it is
864 possible to make and update efficient access control filters for an
865 update. These filters can be set upon subscription and applied
866 against a stream of updates. These filters need only be updated when
867 (a) there is a new node added/removed from the subscribed tree with
868 different permissions than its parent, or (b) read access permissions
869 have been changed on nodes under the target node for the subscriber.
871 3.8.6. Not Notifiable YANG Objects
873 In some cases, a publisher supporting "on-change" notifications may
874 not be able to push updates for some object types "on-change".
875 Reasons for this might be that the value of the data node changes
876 frequently (e.g., a received-octets-counter), that small object
877 changes are frequent and meaningless (e.g., a temperature gauge
878 changing 0.1 degrees), or that the implementation is not capable of
879 on-change notification of an object type.
881 The default assumption is that changes on all data nodes will be
882 reported on-change. However if a certain data node cannot do this,
883 it SHOULD be marked with the YANG extension not-notifiable-on-change.
885 4. A YANG data model for management of datastore push subscriptions
887 4.1. Overview
889 The YANG data model for datastore push subscriptions is depicted in
890 the following figure. Following Yang tree convention in the
891 depiction, brackets enclose list keys, "rw" means configuration, "ro"
892 operational state data, "?" designates optional nodes, "*" designates
893 nodes that can have multiple instances. Parantheses with a name in
894 the middle enclose choice and case nodes. A "+" at the end of a line
895 indicates that the line is to be concatenated with the subsequent
896 line. New YANG tree notation is the i] which indicates that the node
897 in that line has been brought in / imported from another model, and
898 an (a) which indicates this is the specific imported node augmented.
899 In the figure below, all have been imported from 5277bis. The model
900 consists mostly of augmentations to RPCs and notifications defined in
901 the data model for subscriptions for event notifications of
902 [I-D.ietf-netconf-5277bis].
904 module: ietf-yang-push
905 i] +--ro streams
906 i] | +--ro stream* stream
907 i] +--rw filters
908 i] | +--rw filter* [filter-id]
909 i] | +--rw filter-id filter-id
910 i] | +--rw (filter-type)?
911 i] | +--:(rfc5277)
912 i] | | +--rw filter?
913 | +--:(update-filter)
914 | +--rw (update-filter)?
915 | +--:(subtree)
916 | | +--rw subtree-filter?
917 | +--:(xpath)
918 | +--rw xpath-filter? yang:xpath1.0
919 i] +--rw subscription-config {configured-subscriptions}?
920 i] | +--rw subscription* [subscription-id]
921 i] | +--rw subscription-id subscription-id
922 i] | +--rw stream? stream
923 i] | +--rw encoding? encoding
924 (a) | +--rw (filter-type)?
925 i] | | +--:(rfc5277)
926 i] | | | +--rw filter?
927 | | +--:(update-filter)
928 | | | +--rw (update-filter)?
929 | | | +--:(subtree)
930 | | | | +--ro subtree-filter?
931 | | | +--:(xpath)
932 | | | +--rw xpath-filter? yang:xpath1.0
933 i] | | +--:(by-reference)
934 i] | | +--rw filter-ref? filter-ref
935 i] | +--rw startTime? yang:date-and-time
936 i] | +--rw stopTime? yang:date-and-time
937 | +--rw (update-trigger)?
938 | | +--:(periodic)
939 | | | +--rw period yang:timeticks
940 | | | +--rw anchor-time? yang:date-and-time
941 | | +--:(on-change) {on-change}?
942 | | +--rw no-synch-on-start? empty
943 | | +--rw dampening-period yang:timeticks
944 | | +--rw excluded-change* change-type
945 i] | +--rw receivers
946 i] | | +--rw receiver* [address]
947 i] | | +--rw address inet:host
948 i] | | +--rw port inet:port-number
949 i] | | +--rw protocol? transport-protocol
950 i] | +--rw (push-source)?
951 i] | | +--:(interface-originated)
952 i] | | | +--rw source-interface? if:interface-ref
953 i] | | +--:(address-originated)
954 i] | | +--rw source-vrf? uint32
955 i] | | +--rw source-address inet:ip-address-no-zone
956 | +--rw dscp? inet:dscp
957 | +--rw subscription-priority? uint8
958 | +--rw subscription-dependency? string
959 (a) +--ro subscriptions
960 i] +--ro subscription*
961 i] +--ro subscription-id
962 i] +--ro configured-subscription?
963 i] +--ro subscription-status?
964 i] +--ro stream?
965 i] +--ro encoding?
966 (a) +--ro (filter-type)?
967 i] | +--:(rfc5277)
968 i] | | +--ro filter?
969 | +--:(update-filter)
970 | | +--ro (update-filter)?
971 | | +--:(subtree)
972 | | | +--ro subtree-filter?
973 | | +--:(xpath)
974 | | +--ro xpath-filter?
975 i] | +--:(by-reference)
976 i] | +--ro filter-ref?
977 i] +--ro startTime?
978 i] +--ro stopTime?
979 +--ro (update-trigger)?
980 | +--:(periodic)
981 | | +--ro period
982 | | +--ro anchor-time?
983 | +--:(on-change) {on-change}?
984 | +--ro no-synch-on-start?
985 | +--ro dampening-period
986 | +--ro excluded-change*
987 i] +--ro receivers
988 i] | +--ro receiver*
989 i] | +--ro address
990 i] | +--ro port
991 i] | +--ro protocol?
992 i] +--ro (push-source)?
993 i] | +--:(interface-originated)
994 i] | | +--ro source-interface?
995 i] | +--:(address-originated)
996 i] | +--ro source-vrf?
997 i] | +--ro source-address
998 +--ro dscp?
999 +--ro subscription-priority?
1000 +--ro subscription-dependency?
1001 i] rpcs:
1002 i] +---x establish-subscription
1003 (a) | +---w input
1004 i] | | +---w stream?
1005 i] | | +---w encoding?
1006 (a) | | +---w (filter-type)?
1007 i] | | | +--:(rfc5277)
1008 i] | | | | +---w filter?
1009 | | | +--:(update-filter)
1010 | | | | +---w (update-filter)?
1011 | | | | +--:(subtree)
1012 | | | | | +---w subtree-filter?
1013 | | | | +--:(xpath)
1014 | | | | +---w xpath-filter?
1015 i] | | | +--:(by-reference)
1016 i] | | | +---w filter-ref?
1017 i] | | +---w startTime?
1018 i] | | +---w stopTime?
1019 | | +---w (update-trigger)?
1020 | | | +--:(periodic)
1021 | | | | +---w period
1022 | | | | +---w anchor-time?
1023 | | | +--:(on-change) {on-change}?
1024 | | | +---w no-synch-on-start?
1025 | | | +---w dampening-period
1026 | | | +---w excluded-change*
1027 | | +---w dscp?
1028 | | +---w subscription-priority?
1029 | | +---w subscription-dependency?
1030 i] | +--ro output
1031 i] | +--ro subscription-result
1032 i] | +--ro (result)?
1033 i] | +--:(success)
1034 i] | | +--ro subscription-id
1035 (a) | +--:(no-success)
1036 i] | +--ro stream?
1037 i] | +--ro encoding?
1038 (a) | +--ro (filter-type)?
1039 i] | | +--:(rfc5277)
1040 i] | | | +--ro filter?
1041 | | +--:(update-filter)
1042 | | | +---w (update-filter)?
1043 | | | +--:(subtree)
1044 | | | | +---w subtree-filter?
1045 | | | +--:(xpath)
1046 | | | +---w xpath-filter?
1047 i] | | +--:(by-reference)
1048 i] | | +--ro filter-ref?
1049 i] | +--ro startTime?
1050 i] | +--ro stopTime?
1051 | +--ro (update-trigger)?
1052 | | +--:(periodic)
1053 | | | +--ro period
1054 | | | +--ro anchor-time?
1055 | | +--:(on-change) {on-change}?
1056 | | +--ro no-synch-on-start?
1057 | | +--ro dampening-period
1058 | | +--ro excluded-change*
1059 | +--ro dscp?
1060 | +--ro subscription-priority?
1061 | +--ro subscription-dependency?
1062 i] +---x modify-subscription
1063 i] | +---w input
1064 i] | | +---w subscription-id?
1065 i] | | +---w (filter-type)?
1066 i] | | | +--:(rfc5277)
1067 i] | | | | +---w filter?
1068 | | | +--:(update-filter)
1069 | | | | +---w (update-filter)?
1070 | | | | +--:(subtree)
1071 | | | | | +---w subtree-filter?
1072 | | | | +--:(xpath)
1073 | | | | +---w xpath-filter?
1074 i] | | | +--:(by-reference)
1075 i] | | | +---w filter-ref?
1076 i] | | +---w startTime?
1077 i] | | +---w stopTime?
1078 | | +---w (update-trigger)?
1079 | | +--:(periodic)
1080 | | | +---w period
1081 | | | +---w anchor-time?
1082 | | +--:(on-change) {on-change}?
1083 | | +---w dampening-period
1084 | | +---w excluded-change*
1085 i] | +--ro output
1086 i] | +--ro subscription-result
1087 i] | +--ro (result)?
1088 i] | +--:(success)
1089 i] | | +--ro subscription-id
1090 i] | +--:(no-success)
1091 i] | +--ro stream?
1092 i] | +--ro encoding?
1093 i] | +--ro (filter-type)?
1094 i] | | +--:(rfc5277)
1095 i] | | | +--ro filter?
1096 | | +--:(update-filter)
1097 | | | +---w (update-filter)?
1098 | | | +--:(subtree)
1099 | | | | +---w subtree-filter?
1100 | | | +--:(xpath)
1101 | | | +---w xpath-filter?
1102 i] | | +--:(by-reference)
1103 i] | | +--ro filter-ref?
1104 i] | +--ro startTime?
1105 i] | +--ro stopTime?
1106 | +--ro (update-trigger)?
1107 | | +--:(periodic)
1108 | | | +--ro period
1109 | | | +--ro anchor-time?
1110 | | +--:(on-change) {on-change}?
1111 | | +--ro no-synch-on-start?
1112 | | +--ro dampening-period
1113 | | +--ro excluded-change*
1114 | +--ro dscp?
1115 | +--ro subscription-priority?
1116 | +--ro subscription-dependency?
1117 i] +---x delete-subscription
1118 i] +---w input
1119 i] | +---w subscription-id
1120 i] +--ro output
1121 i] +--ro subscription-result
1123 (a) notifications
1124 (a) +---n subscription-started
1125 i] | +--ro subscription-id
1126 i] | +--ro stream?
1127 i] | +--ro encoding?
1128 (a) | +--ro (filter-type)?
1129 i] | | +--:(rfc5277)
1130 i] | | | +--ro filter?
1131 | | +--:(update-filter)
1132 | | | +--rw (update-filter)?
1133 | | | +--:(subtree)
1134 | | | | +--ro subtree-filter?
1135 | | | +--:(xpath)
1136 | | | +--rw xpath-filter?
1137 i] | | +--:(by-reference)
1138 i] | | +--ro filter-ref?
1139 i] | +--ro startTime?
1140 i] | +--ro stopTime?
1141 | +--ro (update-trigger)?
1142 | | +--:(periodic)
1143 | | | +--ro period
1144 | | | +--ro anchor-time?
1145 | | +--:(on-change) {on-change}?
1146 | | +--ro no-synch-on-start?
1147 | | +--ro dampening-period
1148 | | +--ro excluded-change*
1149 | +--ro dscp?
1150 | +--ro subscription-priority?
1151 | +--ro subscription-dependency?
1152 (a) +---n subscription-modified
1153 i] | +--ro subscription-id
1154 i] | +--ro stream?
1155 i] | +--ro encoding?
1156 (a) | +--ro (filter-type)?
1157 i] | | +--:(rfc5277)
1158 i] | | | +--ro filter?
1159 | | +--:(update-filter)
1160 | | | +--rw (update-filter)?
1161 | | | +--:(subtree)
1162 | | | | +--ro subtree-filter?
1163 | | | +--:(xpath)
1164 | | | +--rw xpath-filter?
1165 i] | | +--:(by-reference)
1166 i] | | +--ro filter-ref?
1167 i] | +--ro startTime?
1168 i] | +--ro stopTime?
1169 | +--ro (update-trigger)?
1170 | | +--:(periodic)
1171 | | | +--ro period
1172 | | | +--ro anchor-time?
1173 | | +--:(on-change) {on-change}?
1174 | | +--ro no-synch-on-start?
1175 | | +--ro dampening-period
1176 | | +--ro excluded-change*
1177 | +--ro dscp?
1178 | +--ro subscription-priority?
1179 | +--ro subscription-dependency?
1180 i] +---n subscription-terminated
1181 i] | +--ro subscription-id
1182 i] | +--ro reason?
1183 i] +---n subscription-suspended
1184 i] | +--ro subscription-id
1185 i] | +--ro reason?
1186 i] +---n subscription-resumed
1187 i] | +--ro subscription-id
1188 i] +---n replay-complete
1189 i] | +--ro subscription-id
1190 i] +---n notification-complete
1191 i] | +--ro subscription-id
1192 +---n push-update
1193 | +--ro subscription-id
1194 | +--ro time-of-update?
1195 | +--ro updates-not-sent?
1196 | +--ro datastore-contents?
1197 +---n push-change-update {on-change}?
1198 +--ro subscription-id
1199 +--ro time-of-update?
1200 +--ro updates-not-sent?
1201 +--ro datastore-changes?
1203 Figure 9: Model structure
1205 The components of the model are described in the following
1206 subsections.
1208 4.2. Update streams
1210 Container "update-streams" is used to indicate which data streams are
1211 provided by the system and can be subscribed to. For this purpose,
1212 it contains a leaf list of data nodes identifying the supported
1213 streams.
1215 4.3. Filters
1217 Container "filters" contains a list of configurable data filters,
1218 each specified in its own list element. This allows users to
1219 configure filters separately from an actual subscription, which can
1220 then be referenced from a subscription. This facilitates the reuse
1221 of filter definitions, which can be important in case of complex
1222 filter conditions.
1224 One of three types of filters can be specified as part of a filter
1225 list element. Subtree filters follow syntax and semantics of RFC
1226 6241 and allow to specify which subtree(s) to subscribe to. In
1227 addition, XPath filters can be specified for more complex filter
1228 conditions. Finally, filters can be specified using syntax and
1229 semantics of RFC5277.
1231 It is conceivable to introduce other types of filters; in that case,
1232 the data model needs to be augmented accordingly.
1234 4.4. Subscription configuration
1236 As an optional feature, configured-subscriptions, allows for the
1237 configuration of subscriptions as opposed to RPC. Subscriptions
1238 configurations are represented by list subscription-config. Each
1239 subscription is represented through its own list element and includes
1240 the following components:
1242 o "subscription-id" is an identifier used to refer to the
1243 subscription.
1245 o "stream" refers to the stream being subscribed to. The
1246 subscription model assumes the presence of perpetual and
1247 continuous streams of updates. Various streams are defined:
1248 "push-update" covers the entire set of YANG data in the publisher.
1249 "operational-push" covers all operational data, while "config-
1250 push" covers all configuration data. Other streams could be
1251 introduced in augmentations to the model by introducing additional
1252 identities.
1254 o "encoding" refers to the encoding requested for the data updates.
1255 By default, updates are encoded using XML. However, JSON can be
1256 requested as an option if the json-enconding feature is supported.
1257 Other encodings may be supported in the future.
1259 o "anchor-time" is a timestamp. When used in conjunction with
1260 period, the boundaries of periodic update periods may be
1261 calculated.
1263 o Filters for a subscription can be specified using a choice,
1264 allowing to either reference a filter that has been separately
1265 configured or entering its definition inline.
1267 o A choice of subscription policies allows to define when to send
1268 new updates - periodic or on change.
1270 * For periodic subscriptions, the trigger is defined by a
1271 "period", a parameter that defines the interval with which
1272 updates are to be pushed. The start time of the subscription
1273 serves as anchor time, defining one specific point in time at
1274 which an update needs to be sent. Update intervals always fall
1275 on the points in time that are a multiple of a period after the
1276 start time.
1278 * For on-change subscriptions, the trigger occurs whenever a
1279 change in the subscribed information is detected. On-change
1280 subscriptions have more complex semantics that is guided by
1281 additional parameters. "dampening-period" specifies the
1282 interval that must pass before a successive update for the same
1283 data node is sent. The first time a change is detected, the
1284 update is sent immediately. If a subsequent change is
1285 detected, another update is only sent once the dampening period
1286 has passed, containing the value of the data node that is then
1287 valid. "excluded-change" allows to restrict the types of
1288 changes for which updates are sent (changes to object values,
1289 object creation or deletion events). "no-synch-on-start" is a
1290 flag that allows to specify whether or not a complete update
1291 with all the subscribed data should be sent at the beginning of
1292 a subscription; if the flag is omitted, a complete update is
1293 sent to facilitate synchronization. It is conceivable to
1294 augment the data model with additional parameters in the future
1295 to specify even more refined policies, such as parameters that
1296 specify the magnitude of a change that must occur before an
1297 update is triggered.
1299 o This is followed with a list of receivers for the subscription,
1300 indicating for each receiver the transport that should be used for
1301 push updates (if options other than Netconf are supported). It
1302 should be noted that the receiver does not have to be the same
1303 system that configures the subscription.
1305 o Finally, "push-source" can be used to specify the source of push
1306 updates, either a specific interface or publisher address.
1308 A subscription established through configuration cannot be deleted
1309 using an RPC. Likewise, subscriptions established through RPC cannot
1310 be deleted through configuration.
1312 The deletion of a subscription, whether through RPC or configuration,
1313 results in immediate termination of the subsciption.
1315 4.5. Subscription monitoring
1317 Subscriptions can be subjected to management themselves. For
1318 example, it is possible that a publisher may no longer be able to
1319 serve a subscription that it had previously accepted. Perhaps it has
1320 run out of resources, or internal errors may have occurred. When
1321 this is the case, a publisher needs to be able to temporarily suspend
1322 the subscription, or even to terminate it. More generally, the
1323 publisher should provide a means by which the status of subscriptions
1324 can be monitored.
1326 Container "subscriptions" contains the state of all subscriptions
1327 that are currently active. This includes subscriptions that were
1328 established (and have not yet been deleted) using RPCs, as well as
1329 subscriptions that have been configured as part of configuration.
1331 Each subscription is represented as a list element "datastore-push-
1332 subscription". The associated information includes an identifier for
1333 the subscription, a subscription status, as well as the various
1334 subscription parameters that are in effect. The subscription status
1335 indicates whether the subscription is currently active and healthy,
1336 or if it is degraded in some form. Leaf "configured-subscription"
1337 indicates whether the subscription came into being via configuration
1338 or via RPC.
1340 Subscriptions that were established by RPC are removed from the list
1341 once they expire (reaching stop-time )or when they are terminated.
1342 Subscriptions that were established by configuration need to be
1343 deleted from the configuration by a configuration editing operation.
1345 4.6. Notifications
1347 4.6.1. Monitoring and OAM Notifications
1349 OAM notifications are reused from [I-D.ietf-netconf-5277bis]. Some
1350 have augmentations to include new objects defined in this draft.
1352 Still to be investigated is whether a publisher might also provide
1353 additional information about subscriptions, such as statistics about
1354 the number of data updates that were sent. However, such information
1355 is currently outside the scope of this specification.
1357 4.6.2. Update Notifications
1359 The data model introduces two YANG notifications for the actual
1360 updates themselves.
1362 Notification "push-update" is used to send a complete snapshot of the
1363 data that has been subscribed to, with all YANG object filters
1364 applied. The notification is used for periodic subscription updates
1365 in a periodic subscription.
1367 The notification can also be used in an on-change subscription for
1368 the purposes of allowing a receiver to "synch". Specifically, it is
1369 used at the start of an on-change subscription, unless no-synch-on-
1370 start is specified for the subscription. In addition, it MAY be used
1371 during the subscription, for example if change updates were not sent
1372 as indicated by the "updates-not-sent" flag (see below), or for synch
1373 updates at longer period intervals (such as once per day) to mitigate
1374 the possibility of any application-dependent synchronization drift.
1375 The trigger for sending a push-update notification in conjunction
1376 with on-change subscriptions are at this point outside the scope of
1377 the specification.
1379 The format and syntax of the contained data corresponds to the format
1380 and syntax of data that would be returned in a corresponding get
1381 operation with the same filter parameters applied.
1383 Notification "push-change-update" is used to send data updates for
1384 changes that have occurred in the subscribed data. This notification
1385 is used only in conjunction with on-change subscriptions.
1387 The data updates are encoded analogous to the syntax of a
1388 corresponding yang-patch operation. It corresponds to the data that
1389 would be contained in a yang-patch operation applied to the YANG
1390 datastore at the previous update, to result in the current state (and
1391 applying it also to operational data).
1393 In rare circumstances, the notification can include a flag "updates-
1394 not-sent". This is a flag which indicates that not all changes which
1395 have occurred since the last update are actually included with this
1396 update. In other words, the publisher has failed to fulfill its full
1397 subscription obligations, for example in cases where it was not able
1398 to keep up with a change burst. To facilitate synchronization, a
1399 publisher MAY subsequently send a push-update containing a full
1400 snapshot of subscribed data. Such a push-update might also be
1401 triggered by a subscriber requesting an on-demand synchronization.
1403 4.7. RPCs
1405 YANG-Push subscriptions are established, modified, and deleted using
1406 three RPCs.
1408 4.7.1. Establish-subscription RPC
1410 The subscriber sends an establish-subscription RPC with the
1411 parameters in section 3.1. For instance
1413
1415
1417 push-update
1418
1421 500
1422 encode-xml
1423
1424
1426 Figure 10: Establish-subscription RPC
1428 The publisher must respond explicitly positively (i.e., subscription
1429 accepted) or negatively (i.e., subscription rejected) to the request.
1430 Positive responses include the subscription-id of the accepted
1431 subscription. In that case a publisher may respond:
1433
1435
1437 ok
1438
1439
1441 52
1442
1443
1445 Figure 11: Establish-subscription positive RPC response
1447 A subscription can be rejected for multiple reasons, including the
1448 lack of authorization to establish a subscription, the lack of read
1449 authorization on the requested data node, or the inability of the
1450 publisher to provide a stream with the requested semantics.
1452 When the requester is not authorized to read the requested data node,
1453 the returned "error-info"; indicates an authorization error and the
1454 requested node. For instance, if the above request was unauthorized
1455 to read node "ex:foo" the publisher may return:
1457
1459
1461 error-data-not-authorized
1462
1463
1465 Figure 12: Establish-subscription access denied response
1467 If a request is rejected because the publisher is not able to serve
1468 it, the publisher SHOULD include in the returned error what
1469 subscription parameters would have been accepted for the request.
1470 However, there are no guarantee that subsequent requests for this
1471 subscriber or others will in fact be accepted.
1473 For example, for the following request:
1475
1477
1479 push-update
1480
1483 10
1484 encode-xml
1485
1486
1488 Figure 13: Establish-subscription request example 2
1490 A publisher that cannot serve on-change updates but periodic updates
1491 might return the following:
1493
1495
1497 error-no-such-option
1498
1499 100
1500
1502 Figure 14: Establish-subscription error response example 2
1504 4.7.2. Modify-subscription RPC
1506 The subscriber may send a modify-subscription PRC for a subscription
1507 previously established using RPC The subscriber may change any
1508 subscription parameters by including the new values in the modify-
1509 subscription RPC. Parameters not included in the rpc should remain
1510 unmodified. For illustration purposes we include an exchange example
1511 where a subscriber modifies the period of the subscription.
1513
1515
1517 push-update
1518
1519 1011
1520
1521
1524 250
1525 encode-xml
1526
1527
1529 Figure 15: Modify subscription request
1531 The publisher must respond explicitly positively (i.e., subscription
1532 accepted) or negatively (i.e., subscription rejected) to the request.
1533 Positive responses include the subscription-id of the accepted
1534 subscription. In that case a publisher may respond:
1536
1538
1540 ok
1541
1542
1544 1011
1545
1546
1548 Figure 16: Modify subscription response
1550 If the subscription modification is rejected, the publisher must send
1551 a response like it does for an establish-subscription and maintain
1552 the subscription as it was before the modification request. A
1553 subscription may be modified multiple times.
1555 A configured subscription cannot be modified using modify-
1556 subscription RPC. Instead, the configuration needs to be edited as
1557 needed.
1559 4.7.3. Delete-subscription RPC
1561 To stop receiving updates from a subscription and effectively delete
1562 a subscription that had previously been established using an
1563 establish-subscription RPC, a subscriber can send a delete-
1564 subscription RPC, which takes as only input the subscription-id. For
1565 example:
1567
1569
1571
1572 1011
1573
1574
1575
1577
1579
1580
1582 Figure 17: Delete subscription
1584 Configured subscriptions cannot be deleted via RPC, but have to be
1585 removed from the configuration.
1587 4.7.4. YANG Module Synchronization
1589 In order to fully support datastore replication, the receiver needs
1590 to know the YANG module library that is in use by server that is
1591 being replicated. The YANG 1.0 module library information is sent by
1592 a NETCONF server in the NETCONF 'hello' message. For YANG 1.1
1593 modules and all modules used with the RESTCONF
1594 [I-D.ietf-netconf-restconf] protocol, this information is provided by
1595 the YANG Library module (ietf-yang-library.yang from [RFC7895]. The
1596 YANG library information is important for the receiver to reproduce
1597 the set of object definitions used by the replicated datastore.
1599 The YANG library includes a module list with the name, revision,
1600 enabled features, and applied deviations for each YANG YANG module
1601 implemented by the server. The receiver is expected to know the YANG
1602 library information before starting a subscription. The "/modules-
1603 state/module-set-id" leaf in the "ietf-yang-library" module can be
1604 used to cache the YANG library information. [ED. NOTE: Should
1605 "module-set-id" be added to establish-subscription response?]
1607 The set of modules, revisions, features, and deviations can change at
1608 run-time (if supported by the server implementation). In this case,
1609 the receiver needs to be informed of module changes before data nodes
1610 from changed modules can be processed correctly. The YANG library
1611 provides a simple "yang-library-change" notification that informs the
1612 client that the library has changed somehow. The receiver then needs
1613 to re-read the entire YANG library data for the replicated server in
1614 order to detect the specific YANG library changes. The "ietf-
1615 netconf-notifications" module defined in [RFC6470] contains a
1616 "netconf-capability-change" notification that can identify specific
1617 module changes. For example, the module URI capability of a newly
1618 loaded module will be listed in the "added-capability" leaf-list, and
1619 the module URI capability of an removed module will be listed in the
1620 "deleted-capability" leaf-list.
1622 5. YANG module
1624 file "ietf-yang-push@2016-10-28.yang"
1625 module ietf-yang-push {
1626 yang-version 1.1;
1627 namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push";
1628 prefix yp;
1630 import ietf-inet-types {
1631 prefix inet;
1633 }
1634 import ietf-yang-types {
1635 prefix yang;
1636 }
1637 import ietf-event-notifications {
1638 prefix notif-bis;
1639 }
1641 organization "IETF";
1642 contact
1643 "WG Web:
1644 WG List:
1646 WG Chair: Mahesh Jethanandani
1647
1649 WG Chair: Mehmet Ersue
1650
1652 Editor: Alexander Clemm
1653
1655 Editor: Eric Voit
1656
1658 Editor: Alberto Gonzalez Prieto
1659
1661 Editor: Ambika Prasad Tripathy
1662
1664 Editor: Einar Nilsen-Nygaard
1665
1667 Editor: Andy Bierman
1668
1670 Editor: Balazs Lengyel
1671 ";
1673 description
1674 "This module contains conceptual YANG specifications
1675 for YANG push.";
1677 revision 2016-10-28 {
1678 description
1679 "Updates to simplify modify-subscription, add anchor-time";
1680 reference "YANG Datastore Push, draft-ietf-netconf-yang-push-04";
1682 }
1684 feature on-change {
1685 description
1686 "This feature indicates that on-change updates are
1687 supported.";
1688 }
1690 /*
1691 * IDENTITIES
1692 */
1694 /* Additional errors for subscription operations */
1695 identity error-data-not-authorized {
1696 base notif-bis:error;
1697 description
1698 "No read authorization for a requested data node.";
1699 }
1701 /* Additional types of streams */
1702 identity update-stream {
1703 description
1704 "Base identity to represent a conceptual system-provided
1705 datastream of datastore updates with predefined semantics.";
1706 }
1708 identity yang-push {
1709 base update-stream;
1710 description
1711 "A conceptual datastream consisting of all datastore
1712 updates, including operational and configuration data.";
1713 }
1715 identity operational-push {
1716 base update-stream;
1717 description
1718 "A conceptual datastream consisting of updates of all
1719 operational data.";
1720 }
1722 identity config-push {
1723 base update-stream;
1724 description
1725 "A conceptual datastream consisting of updates of all
1726 configuration data.";
1727 }
1728 identity custom-stream {
1729 base update-stream;
1730 description
1731 "A conceptual datastream for datastore
1732 updates with custom updates as defined by a user.";
1733 }
1735 /* Additional transport option */
1736 identity http2 {
1737 base notif-bis:transport;
1738 description
1739 "HTTP2 notifications as a transport";
1740 }
1742 /*
1743 * TYPE DEFINITIONS
1744 */
1746 typedef filter-id {
1747 type uint32;
1748 description
1749 "A type to identify filters which can be associated with a
1750 subscription.";
1751 }
1753 typedef change-type {
1754 type enumeration {
1755 enum "create" {
1756 description
1757 "A new data node was created";
1758 }
1759 enum "delete" {
1760 description
1761 "A data node was deleted";
1762 }
1763 enum "modify" {
1764 description
1765 "The value of a data node has changed";
1766 }
1767 }
1768 description
1769 "Specifies different types of changes that may occur
1770 to a datastore.";
1771 }
1773 typedef update-stream {
1774 type identityref {
1775 base update-stream;
1777 }
1778 description
1779 "Specifies a system-provided datastream.";
1780 }
1782 grouping update-filter {
1783 description
1784 "This groupings defines filters for push updates for a
1785 datastore tree. The filters define which updates are of
1786 interest in a push update subscription. Mixing and matching
1787 of multiple filters does not occur at the level of this
1788 grouping. When a push-update subscription is created, the
1789 filter can be a regular subscription filter, or one of the
1790 additional filters that are defined in this grouping.";
1791 choice update-filter {
1792 description
1793 "Define filters regarding which data nodes to include
1794 in push updates";
1795 case subtree {
1796 description
1797 "Subtree filter.";
1798 anyxml subtree-filter {
1799 description
1800 "Subtree-filter used to specify the data nodes targeted
1801 for subscription within a subtree, or subtrees, of a
1802 conceptual YANG datastore. Objects matching the filter
1803 criteria will traverse the filter. The syntax follows
1804 the subtree filter syntax specified in RFC 6241,
1805 section 6.";
1806 reference "RFC 6241 section 6";
1807 }
1808 }
1809 case xpath {
1810 description
1811 "XPath filter";
1812 leaf xpath-filter {
1813 type yang:xpath1.0;
1814 description
1815 "Xpath defining the data items of interest.";
1816 }
1817 }
1818 }
1819 }
1821 grouping update-policy {
1822 description
1823 "This grouping describes the conditions under which an
1824 update will be sent as part of an update stream.";
1826 choice update-trigger {
1827 description
1828 "Defines necessary conditions for sending an event to
1829 the subscriber.";
1830 case periodic {
1831 description
1832 "The agent is requested to notify periodically the
1833 current values of the datastore or the subset
1834 defined by the filter.";
1835 leaf period {
1836 type yang:timeticks;
1837 mandatory true;
1838 description
1839 "Duration of time which should occur between periodic
1840 push updates. Where the anchor of a start-time is
1841 available, the push will include the objects and their
1842 values which exist at an exact multiple of timeticks
1843 aligning to this start-time anchor.";
1844 }
1845 leaf anchor-time {
1846 type yang:date-and-time;
1847 description
1848 "Designates a timestamp from which the series of
1849 periodic push updates are computed. The next update
1850 will take place at the next period interval from the
1851 anchor time. For example, for an anchor time at the
1852 top of a minute and a period interval of a minute,
1853 the next update will be sent at the top of the next
1854 minute.";
1855 }
1856 }
1857 case on-change {
1858 if-feature "on-change";
1859 description
1860 "The agent is requested to notify changes in
1861 values in the datastore or a subset of it defined
1862 by a filter.";
1863 leaf no-synch-on-start {
1864 type empty;
1865 description
1866 "This leaf acts as a flag that determines behavior at the
1867 start of the subscription. When present,
1868 synchronization of state at the beginning of the
1869 subscription is outside the scope of the subscription.
1870 Only updates about changes that are observed from the
1871 start time, i.e. only push-change-update notifications
1872 are sent.
1873 When absent (default behavior), in order to facilitate
1874 a receiver's synchronization, a full update is sent
1875 when the subscription starts using a push-update
1876 notification, just like in the case of a periodic
1877 subscription. After that, push-change-update
1878 notifications only are sent unless the Publisher chooses
1879 to resynch the subscription again.";
1880 }
1881 leaf dampening-period {
1882 type yang:timeticks;
1883 mandatory true;
1884 description
1885 "Minimum amount of time that needs to have
1886 passed since the last time an update was
1887 provided.";
1888 }
1889 leaf-list excluded-change {
1890 type change-type;
1891 description
1892 "Use to restrict which changes trigger an update.
1893 For example, if modify is excluded, only creation and
1894 deletion of objects is reported.";
1895 }
1896 }
1897 }
1898 }
1900 grouping subscription-qos {
1901 description
1902 "This grouping describes Quality of Service information
1903 concerning a subscription. This information is passed to lower
1904 layers for transport priortization and treatment";
1905 leaf dscp {
1906 if-feature "notif-bis:configured-subscriptions";
1907 type inet:dscp;
1908 default "0";
1909 description
1910 "The push update's IP packet transport priority.
1911 This is made visible across network hops to receiver.
1912 The transport priority is shared for all receivers of
1913 a given subscription.";
1914 }
1915 leaf subscription-priority {
1916 type uint8;
1917 description
1918 "Relative priority for a subscription. Allows an
1919 underlying transport layer perform informed load
1920 balance allocations between various subscriptions";
1921 }
1922 leaf subscription-dependency {
1923 type string;
1924 description
1925 "Provides the Subscription ID of a parent subscription
1926 without which this subscription should not exist. In
1927 other words, there is no reason to stream these objects
1928 if another subscription is missing.";
1929 }
1930 }
1932 augment "/notif-bis:establish-subscription/notif-bis:input" {
1933 description
1934 "Define additional subscription parameters that apply
1935 specifically to push updates";
1936 uses update-policy;
1937 uses subscription-qos;
1938 }
1939 augment "/notif-bis:establish-subscription/notif-bis:input/"+
1940 "notif-bis:filter-type" {
1941 description
1942 "Add push filters to selection of filter types.";
1943 case update-filter {
1944 description
1945 "Additional filter options for push subscription.";
1946 uses update-filter;
1947 }
1948 }
1949 augment "/notif-bis:establish-subscription/notif-bis:output" {
1950 description
1951 "Allow to return additional subscription parameters that apply
1952 specifically to push updates.";
1953 uses update-policy;
1954 uses subscription-qos;
1955 }
1956 augment "/notif-bis:establish-subscription/notif-bis:output/"+
1957 "notif-bis:result/notif-bis:no-success/notif-bis:filter-type" {
1958 description
1959 "Add push filters to selection of filter types.";
1960 case update-filter {
1961 description
1962 "Additional filter options for push subscription.";
1963 uses update-filter;
1964 }
1965 }
1966 augment "/notif-bis:modify-subscription/notif-bis:input" {
1967 description
1968 "Define additional subscription parameters that apply
1969 specifically to push updates.";
1971 uses update-policy;
1972 }
1973 augment "/notif-bis:modify-subscription/notif-bis:input/"+
1974 "notif-bis:filter-type" {
1975 description
1976 "Add push filters to selection of filter types.";
1977 case update-filter {
1978 description
1979 "Additional filter options for push subscription.";
1980 uses update-filter;
1981 }
1982 }
1983 augment "/notif-bis:modify-subscription/notif-bis:output" {
1984 description
1985 "Allow to retun additional subscription parameters that apply
1986 specifically to push updates.";
1987 uses update-policy;
1988 uses subscription-qos;
1989 }
1990 augment "/notif-bis:modify-subscription/notif-bis:output/"+
1991 "notif-bis:result/notif-bis:no-success/notif-bis:filter-type" {
1992 description
1993 "Add push filters to selection of filter types.";
1994 case update-filter {
1995 description
1996 "Additional filter options for push subscription.";
1997 uses update-filter;
1998 }
1999 }
2000 notification push-update {
2001 description
2002 "This notification contains a push update, containing
2003 data subscribed to via a subscription.
2004 This notification is sent for periodic updates, for a
2005 periodic subscription. It can also be used for
2006 synchronization updates of an on-change subscription.
2007 This notification shall only be sent to receivers
2008 of a subscription; it does not constitute a general-purpose
2009 notification.";
2010 leaf subscription-id {
2011 type notif-bis:subscription-id;
2012 mandatory true;
2013 description
2014 "This references the subscription because of which the
2015 notification is sent.";
2016 }
2017 leaf time-of-update {
2018 type yang:date-and-time;
2019 description
2020 "This leaf contains the time of the update.";
2021 }
2022 leaf updates-not-sent {
2023 type empty;
2024 description
2025 "This is a flag which indicates that not all data nodes
2026 subscribed to are included included with this
2027 update. In other words, the publisher has failed to
2028 fulfill its full subscription obligations.
2029 This may lead to intermittent loss of synchronization
2030 of data at the client. Synchronization at the client
2031 can occur when the next push-update is received.";
2032 }
2033 anydata datastore-contents {
2034 description
2035 "This contains the updated data. It constitutes a snapshot
2036 at the time-of-update of the set of data that has been
2037 subscribed to. The format and syntax of the data
2038 corresponds to the format and syntax of data that would be
2039 returned in a corresponding get operation with the same
2040 filter parameters applied.";
2041 }
2042 }
2043 notification push-change-update {
2044 if-feature "on-change";
2045 description
2046 "This notification contains an on-change push update.
2047 This notification shall only be sent to the receivers
2048 of a subscription; it does not constitute a general-purpose
2049 notification.";
2050 leaf subscription-id {
2051 type notif-bis:subscription-id;
2052 mandatory true;
2053 description
2054 "This references the subscription because of which the
2055 notification is sent.";
2056 }
2057 leaf time-of-update {
2058 type yang:date-and-time;
2059 description
2060 "This leaf contains the time of the update, i.e. the
2061 time at which the change was observed.";
2062 }
2063 leaf updates-not-sent {
2064 type empty;
2065 description
2066 "This is a flag which indicates that not all changes which
2067 have occured since the last update are included with this
2068 update. In other words, the publisher has failed to
2069 fulfill its full subscription obligations, for example in
2070 cases where it was not able to keep up with a change burst.
2071 To facilitate synchronization, a publisher MAY subsequently
2072 send a push-update containing a full snapshot of subscribed
2073 data. Such a push-update might also be triggered by a
2074 subscriber requesting an on-demand synchronization.";
2075 }
2076 anydata datastore-changes {
2077 description
2078 "This contains datastore contents that has changed
2079 since the previous update, per the terms of the
2080 subscription. Changes are encoded analogous to
2081 the syntax of a corresponding yang-patch operation,
2082 i.e. a yang-patch operation applied to the YANG datastore
2083 implied by the previous update to result in the current
2084 state (and assuming yang-patch could also be applied to
2085 operational data).";
2086 }
2087 }
2088 augment "/notif-bis:subscription-started" {
2089 description
2090 "This augmentation adds push subscription parameters
2091 to the notification that a subscription has
2092 started and data updates are beginning to be sent.
2093 This notification shall only be sent to receivers
2094 of a subscription; it does not constitute a general-purpose
2095 notification.";
2096 uses update-policy;
2097 uses subscription-qos;
2098 }
2099 augment "/notif-bis:subscription-started/notif-bis:filter-type" {
2100 description
2101 "This augmentation allows to include additional update filters
2102 options to be included as part of the notification that a
2103 subscription has started.";
2104 case update-filter {
2105 description
2106 "Additional filter options for push subscription.";
2107 uses update-filter;
2108 }
2109 }
2110 augment "/notif-bis:subscription-modified" {
2111 description
2112 "This augmentation adds push subscription parameters
2113 to the notification that a subscription has
2114 been modified.
2116 This notification shall only be sent to receivers
2117 of a subscription; it does not constitute a general-purpose
2118 notification.";
2119 uses update-policy;
2120 uses subscription-qos;
2121 }
2122 augment "/notif-bis:subscription-modified/notif-bis:filter-type" {
2123 description
2124 "This augmentation allows to include additional update
2125 filters options to be included as part of the notification
2126 that a subscription has been modified.";
2127 case update-filter {
2128 description
2129 "Additional filter options for push subscription.";
2130 uses update-filter;
2131 }
2132 }
2133 augment "/notif-bis:filters/notif-bis:filter/"+
2134 "notif-bis:filter-type" {
2135 description
2136 "This container adds additional update filter options
2137 to the list of configurable filters
2138 that can be applied to subscriptions. This facilitates
2139 the reuse of complex filters once defined.";
2140 case update-filter {
2141 uses update-filter;
2142 }
2143 }
2144 augment "/notif-bis:subscription-config/notif-bis:subscription" {
2145 description
2146 "Contains the list of subscriptions that are configured,
2147 as opposed to established via RPC or other means.";
2148 uses update-policy;
2149 uses subscription-qos;
2150 }
2151 augment "/notif-bis:subscription-config/notif-bis:subscription/"+
2152 "notif-bis:filter-type" {
2153 description
2154 "Add push filters to selection of filter types.";
2155 case update-filter {
2156 uses update-filter;
2157 }
2158 }
2159 augment "/notif-bis:subscriptions/notif-bis:subscription" {
2160 description
2161 "Contains the list of currently active subscriptions,
2162 i.e. subscriptions that are currently in effect,
2163 used for subscription management and monitoring purposes.
2165 This includes subscriptions that have been setup via RPC
2166 primitives, e.g. establish-subscription, delete-subscription,
2167 and modify-subscription, as well as subscriptions that
2168 have been established via configuration.";
2169 uses update-policy;
2170 uses subscription-qos;
2171 }
2172 augment "/notif-bis:subscriptions/notif-bis:subscription/"+
2173 "notif-bis:filter-type" {
2174 description
2175 "Add push filters to selection of filter types.";
2176 case update-filter {
2177 description
2178 "Additional filter options for push subscription.";
2179 uses update-filter;
2180 }
2181 }
2182 }
2184
2186 6. Security Considerations
2188 Subscriptions could be used to attempt to overload publishers of YANG
2189 datastores. For this reason, it is important that the publisher has
2190 the ability to decline a subscription request if it would deplete its
2191 resources. In addition, a publisher needs to be able to suspend an
2192 existing subscription when needed. When this occur, the subscription
2193 status is updated accordingly and the receivers are notified.
2194 Likewise, requests for subscriptions need to be properly authorized.
2196 A subscription could be used to retrieve data in subtrees that a
2197 receiver has no authorized access to. Therefore it is important that
2198 data pushed based on subscriptions is authorized in the same way that
2199 regular data retrieval operations are. Data being pushed to a
2200 receiver needs therefore to be filtered accordingly, just like if the
2201 data were being retrieved on-demand. The Netconf Authorization
2202 Control Model applies.
2204 A subscription could be configured on another receiver's behalf, with
2205 the goal of flooding that receiver with updates. One or more
2206 publishers could be used to overwhelm a receiver which doesn't even
2207 support subscriptions. Receivers which do not want pushed data need
2208 only terminate or refuse any transport sessions from the publisher.
2209 In addition, the Netconf Authorization Control Model SHOULD be used
2210 to control and restrict authorization of subscription configuration.
2212 7. Acknowledgments
2214 For their valuable comments, discussions, and feedback, we wish to
2215 acknowledge Tim Jenkins, Kent Watsen, Susan Hares, Yang Geng, Peipei
2216 Guo, Michael Scharf, Sharon Chisholm, and Guangying Zheng.
2218 8. References
2220 8.1. Normative References
2222 [I-D.ietf-netconf-5277bis]
2223 Clemm, A., Gonzalez Prieto, A., Voit, E., Tripathy, A.,
2224 Nilsen-Nygaard, E., Chisholm, S., and H. Trevino,
2225 "Subscribing to YANG-Defined Event Notifications", draft-
2226 ietf-netconf-5277bis-01 (work in progress), October 2016.
2228 [I-D.ietf-netconf-yang-patch]
2229 Bierman, A., Bjorklund, M., and K. Watsen, "YANG Patch
2230 Media Type", draft-ietf-netconf-yang-patch-12 (work in
2231 progress), September 2016.
2233 [RFC6470] Bierman, A., "Network Configuration Protocol (NETCONF)
2234 Base Notifications", RFC 6470, February 2012.
2236 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration
2237 Protocol (NETCONF) Access Control Model", RFC 6536, March
2238 2012.
2240 [RFC7895] Bierman, A., Bjorklund, M., and K. Watsen, "YANG Module
2241 Library", RFC 7895, June 2016.
2243 [RFC7950] Bjorklund, M., "The YANG 1.1 Data Modeling Language",
2244 RFC 7950, August 2016.
2246 [RFC7951] Lhotka, L., "JSON Encoding of Data Modeled with YANG",
2247 RFC 7951, August 2016.
2249 8.2. Informative References
2251 [I-D.ietf-netconf-restconf]
2252 Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
2253 Protocol", I-D draft-ietf-netconf-restconf-17, September
2254 2016.
2256 [RFC1157] Case, J., "A Simple Network Management Protocol (SNMP)",
2257 RFC 1157, May 1990.
2259 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
2260 Notifications", RFC 5277, July 2008.
2262 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A.
2263 Bierman, "Network Configuration Protocol (NETCONF)",
2264 RFC 6241, June 2011.
2266 [RFC7923] Voit, E., Clemm, A., and A. Gonzalez Prieto, "Requirements
2267 for Subscription to YANG Datastores", RFC 7923, June 2016.
2269 Appendix A. Issues that are currently being worked and resolved
2271 (To be removed by RFC editor prior to publication)
2273 A.1. Unresolved and yet-to-be addressed issues
2275 Which stream types to introduce, if any based on implications of
2276 opstate. Current list includes streams for all operational and for
2277 all config data. Consider adding stream for operational data minus
2278 counters.
2280 We need a new Metadata filter. But so does traditional GET. This
2281 should be relevant independent of subscriptions. This has
2282 implications of ephemeral requirements from I2RS
2284 Should we allow an interplay of filter types in a single
2285 subscription. Or should we keep them fully independent.
2287 Do we add a counter for the number of object changes during a
2288 dampening period?
2290 A.2. Agreement in principal
2292 Do we need an extension for NACM to support filter out datastore
2293 nodes for which the receiver has no read access? (And how does this
2294 differ from existing GET, which must do the same filtering?) In
2295 5277, such filtering is done at the notification level. Yang-push
2296 includes notification-content filtering. This may be very expensive
2297 in terms of processing. Andy suggestion: only accept Yang-push
2298 subscriptions for subtrees the user has rights for all the nodes in
2299 the subtree. Changes to those rights trigger a subscription
2300 termination. Should we codify this, or let vendors determine when
2301 per subtree filtering might be applied?
2303 Need to add a new RPC to request enabling a resynch for an existing
2304 on-change subscription exposed on publisher
2306 Appendix B. Changes between revisions
2308 (To be removed by RFC editor prior to publication)
2310 v03 to v04
2312 o Updates-not-sent flag added
2314 o Not notifiable extension added
2316 o Dampening period is for whole subscription, not single objects
2318 o Moved start/stop into rfc5277bis
2320 o Client and Server changed to subscriber, publisher, and receiver
2322 o Anchor time for periodic
2324 o Message format for synchronization (i.e. synch-on-start)
2326 o Material moved into 5277bis
2328 o QoS parameters supported, by not allowed to be modified by RPC
2330 o Text updates throughout
2332 Authors' Addresses
2334 Alexander Clemm
2335 Sympotech
2337 Email: alex@sympotech.com
2339 Eric Voit
2340 Cisco Systems
2342 Email: evoit@cisco.com
2344 Alberto Gonzalez Prieto
2345 Cisco Systems
2347 Email: albertgo@cisco.com
2348 Ambika Prasad Tripathy
2349 Cisco Systems
2351 Email: ambtripa@cisco.com
2353 Einar Nilsen-Nygaard
2354 Cisco Systems
2356 Email: einarnn@cisco.com
2358 Andy Bierman
2359 YumaWorks
2361 Email: andy@yumaworks.com
2363 Balazs Lengyel
2364 Ericsson
2366 Email: balazs.lengyel@ericsson.com