< draft-ietf-netconf-yang-push-14.txt   draft-ietf-netconf-yang-push-15.txt >
NETCONF A. Clemm NETCONF A. Clemm
Internet-Draft Huawei Internet-Draft Huawei
Intended status: Standards Track E. Voit Intended status: Standards Track E. Voit
Expires: August 13, 2018 Cisco Systems Expires: August 27, 2018 Cisco Systems
A. Gonzalez Prieto A. Gonzalez Prieto
VMware VMware
A. Tripathy A. Tripathy
E. Nilsen-Nygaard E. Nilsen-Nygaard
Cisco Systems Cisco Systems
A. Bierman A. Bierman
YumaWorks YumaWorks
B. Lengyel B. Lengyel
Ericsson Ericsson
February 09, 2018 February 23, 2018
YANG Datastore Subscription YANG Datastore Subscription
draft-ietf-netconf-yang-push-14 draft-ietf-netconf-yang-push-15
Abstract Abstract
Via the mechanism described in this document, subscriber applications Via the mechanism described in this document, subscriber applications
may request a continuous, customized stream of updates from a YANG may request a continuous, customized stream of updates from a YANG
datastore. Providing such visibility into changes made upon YANG datastore. Providing such visibility into changes made upon YANG
configuration and operational objects enables new capabilities based configuration and operational objects enables new capabilities based
on the remote mirroring of configuration and operational state. on the remote mirroring of configuration and operational state.
Status of This Memo Status of This Memo
skipping to change at page 1, line 44 skipping to change at page 1, line 44
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 13, 2018. This Internet-Draft will expire on August 27, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 42 skipping to change at page 2, line 42
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 4 2. Definitions and Acronyms . . . . . . . . . . . . . . . . . . 4
3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 4 3. Solution Overview . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Subscription Model . . . . . . . . . . . . . . . . . . . 5 3.1. Subscription Model . . . . . . . . . . . . . . . . . . . 5
3.2. Negotiation of Subscription Policies . . . . . . . . . . 6 3.2. Negotiation of Subscription Policies . . . . . . . . . . 6
3.3. On-Change Considerations . . . . . . . . . . . . . . . . 6 3.3. On-Change Considerations . . . . . . . . . . . . . . . . 6
3.4. Promise-Theory Considerations . . . . . . . . . . . . . . 8 3.4. Promise-Theory Considerations . . . . . . . . . . . . . . 8
3.5. Data Encodings . . . . . . . . . . . . . . . . . . . . . 8 3.5. Data Encodings . . . . . . . . . . . . . . . . . . . . . 8
3.6. Datastore Selection . . . . . . . . . . . . . . . . . . . 9 3.6. Defining the Selection with a Datastore . . . . . . . . . 9
3.7. Streaming Updates . . . . . . . . . . . . . . . . . . . . 10 3.7. Streaming Updates . . . . . . . . . . . . . . . . . . . . 10
3.8. Subscription Management . . . . . . . . . . . . . . . . . 12 3.8. Subscription Management . . . . . . . . . . . . . . . . . 12
3.9. Receiver Authorization . . . . . . . . . . . . . . . . . 14 3.9. Receiver Authorization . . . . . . . . . . . . . . . . . 14
3.10. On-change Notifiable YANG objects . . . . . . . . . . . . 16 3.10. On-change Notifiable YANG objects . . . . . . . . . . . . 16
3.11. Other Considerations . . . . . . . . . . . . . . . . . . 16 3.11. Other Considerations . . . . . . . . . . . . . . . . . . 16
4. A YANG data model for management of datastore push 4. A YANG data model for management of datastore push
subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 17 subscriptions . . . . . . . . . . . . . . . . . . . . . . . . 17
4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 17 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2. Subscription configuration . . . . . . . . . . . . . . . 25 4.2. Subscription configuration . . . . . . . . . . . . . . . 25
4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 26 4.3. YANG Notifications . . . . . . . . . . . . . . . . . . . 26
4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 27 4.4. YANG RPCs . . . . . . . . . . . . . . . . . . . . . . . . 27
5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 32 5. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 32
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 48
7. Security Considerations . . . . . . . . . . . . . . . . . . . 49 7. Security Considerations . . . . . . . . . . . . . . . . . . . 48
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 49 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 49
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 49 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 49
9.1. Normative References . . . . . . . . . . . . . . . . . . 49 9.1. Normative References . . . . . . . . . . . . . . . . . . 49
9.2. Informative References . . . . . . . . . . . . . . . . . 50 9.2. Informative References . . . . . . . . . . . . . . . . . 50
Appendix A. Appendix A: Subscription Errors . . . . . . . . . . 51 Appendix A. Appendix A: Subscription Errors . . . . . . . . . . 50
A.1. RPC Failures . . . . . . . . . . . . . . . . . . . . . . 51 A.1. RPC Failures . . . . . . . . . . . . . . . . . . . . . . 50
A.2. Notifications of Failure . . . . . . . . . . . . . . . . 52 A.2. Notifications of Failure . . . . . . . . . . . . . . . . 52
Appendix B. Changes between revisions . . . . . . . . . . . . . 52 Appendix B. Changes between revisions . . . . . . . . . . . . . 52
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 56
1. Introduction 1. Introduction
Traditional approaches to remote visibility have been built on Traditional approaches to remote visibility have been built on
polling. With polling, data is periodically requested and retrieved polling. With polling, data is periodically requested and retrieved
by a client from a server to stay up-to-date. However, there are by a client from a server to stay up-to-date. However, there are
issues associated with polling-based management: issues associated with polling-based management:
o Polling incurs significant latency. This latency prohibits many o Polling incurs significant latency. This latency prohibits many
application types. application types.
skipping to change at page 5, line 19 skipping to change at page 5, line 19
in [I-D.draft-ietf-netconf-subscribed-notifications] with in [I-D.draft-ietf-netconf-subscribed-notifications] with
capabilities that allow subscribers to subscribe to datastore node capabilities that allow subscribers to subscribe to datastore node
updates, specifically to specify the triggers defining when to updates, specifically to specify the triggers defining when to
generate update records as well as what to include in an update generate update records as well as what to include in an update
record. Key enhancements include: record. Key enhancements include:
o Specification of selection filters which identify targeted YANG o Specification of selection filters which identify targeted YANG
datastore nodes and/or subtrees within a datastore for which datastore nodes and/or subtrees within a datastore for which
updates are to be pushed. updates are to be pushed.
o An encoding (using anydata) for the contents of periodic and on-
change push updates.
o Specification of update policies contain conditions which trigger o Specification of update policies contain conditions which trigger
the generation and pushing of new update records. There are two the generation and pushing of new update records. There are two
types of triggers for subscriptions: periodic and on-change. types of triggers for subscriptions: periodic and on-change.
* For periodic subscriptions, the trigger is specified by two * For periodic subscriptions, the trigger is specified by two
parameters that define when updates are to be pushed. These parameters that define when updates are to be pushed. These
parameters are the period interval with which to report parameters are the period interval with which to report
updates, and an anchor time which can be used to calculate at updates, and an anchor time which can be used to calculate at
which point in time updates need to be assembled and sent. which point in time updates need to be assembled and sent.
skipping to change at page 6, line 17 skipping to change at page 6, line 15
+ Change type: This parameter can be used to reduce the types + Change type: This parameter can be used to reduce the types
of datastore changes for which updates are sent (e.g., you of datastore changes for which updates are sent (e.g., you
might only send when an object is created or deleted, but might only send when an object is created or deleted, but
not when an object value changes). not when an object value changes).
+ No Synch on start: defines whether or not a complete push- + No Synch on start: defines whether or not a complete push-
update of all subscribed data will be sent at the beginning update of all subscribed data will be sent at the beginning
of a subscription. Such early synchronization establishes of a subscription. Such early synchronization establishes
the frame of reference for subsequent updates. the frame of reference for subsequent updates.
o An encoding (using anydata) for the contents of periodic and on-
change push updates.
3.2. Negotiation of Subscription Policies 3.2. Negotiation of Subscription Policies
A dynamic subscription request SHOULD be declined if a publisher's A dynamic subscription request SHOULD be declined if a publisher's
assessment is that it may be unable to provide update records meeting assessment is that it may be unable to provide update records meeting
the terms of an "establish-subscription" or "modify-subscription" rpc the terms of an "establish-subscription" or "modify-subscription" rpc
request. In this case, a subscriber may quickly follow up with a new request. In this case, a subscriber may quickly follow up with a new
rpc request using different parameters. rpc request using different parameters.
Random guessing at different parameters by a subscriber is to be Random guessing at different parameters by a subscriber is to be
discouraged. Therefore, in order to minimize the number of discouraged. Therefore, in order to minimize the number of
skipping to change at page 8, line 9 skipping to change at page 8, line 9
creating an push-change-update notification: creating an push-change-update notification:
1. Just before a change, or at the start of a dampening period, 1. Just before a change, or at the start of a dampening period,
evaluate any filtering and any access control rules. The result evaluate any filtering and any access control rules. The result
is a set "A" of datastore nodes and subtrees. is a set "A" of datastore nodes and subtrees.
2. Just after a change, or at the end of a dampening period, 2. Just after a change, or at the end of a dampening period,
evaluate any filtering and any (possibly new) access control evaluate any filtering and any (possibly new) access control
rules. The result is a set "B" of datastore nodes and subtrees. rules. The result is a set "B" of datastore nodes and subtrees.
3. Construct a YANG patch record for going from A to B. If the 3. Construct a YANG patch record for going from A to B.
record is non-empty, send it to the receiver.
4. If there were any changes made between A and B which canceled
each other out, insert into the YANG patch record the last change
made for any object which otherwise wouldn't have appeared.
5. If the resulting patch record is non-empty, send it to the
receiver.
Note: In cases where a subscriber wants to have separate dampening Note: In cases where a subscriber wants to have separate dampening
periods for different objects, multiple subscriptions with different periods for different objects, multiple subscriptions with different
objects in a selection filter can be created. objects in a selection filter can be created.
3.4. Promise-Theory Considerations 3.4. Promise-Theory Considerations
A subscription to updates from a datastore is intended to obviate the A subscription to updates from a datastore is intended to obviate the
need for polling. However, in order to do so, it is critical that need for polling. However, in order to do so, it is critical that
subscribers can rely on the subscription and have confidence that subscribers can rely on the subscription and have confidence that
they will indeed receive the subscribed updates without having to they will indeed receive the subscribed updates without having to
worry updates being silently dropped. In other words, a subscription worry about updates being silently dropped. In other words, a
constitutes a promise on the side of the publisher to provide the subscription constitutes a promise on the side of the publisher to
receivers with updates per the terms of the subscription. provide the receivers with updates per the terms of the subscription.
Now, there are many reasons why a publisher may at some point no Now, there are many reasons why a publisher may at some point no
longer be able to fulfill the terms of the subscription, even if the longer be able to fulfill the terms of the subscription, even if the
subscription had been entered into with good faith. For example, the subscription had been entered into with good faith. For example, the
volume of data objects may be larger than anticipated, the interval volume of data objects may be larger than anticipated, the interval
may prove too short to send full updates in rapid succession, or an may prove too short to send full updates in rapid succession, or an
internal problem may prevent objects from being collected. If for internal problem may prevent objects from being collected. If for
some reason the publisher of a subscription is not able to keep its some reason the publisher of a subscription is not able to keep its
promise, receivers MUST be notified immediately and reliably. The promise, receivers MUST be notified immediately and reliably. The
publisher MAY also suspend the subscription. publisher MAY also suspend the subscription.
skipping to change at page 9, line 22 skipping to change at page 9, line 27
be applied to the earlier state reported by the preceding update, to be applied to the earlier state reported by the preceding update, to
result in the now-current state. Note that contrary to [RFC8072], result in the now-current state. Note that contrary to [RFC8072],
objects encapsulated are not restricted to configuration objects objects encapsulated are not restricted to configuration objects
only. only.
However a patch must be able to do more than just describe the delta However a patch must be able to do more than just describe the delta
from the previous state to the current state. As per Section 3.3, it from the previous state to the current state. As per Section 3.3, it
must also be able to identify if transient changes have occurred on must also be able to identify if transient changes have occurred on
an object during a dampening period. To support this, it is valid to an object during a dampening period. To support this, it is valid to
encode a YANG patch operation so that its application would result in encode a YANG patch operation so that its application would result in
a no change between the previous and current state. This indicates no change between the previous and current state. This indicates
that some churn has occurred on the object. An example of this would that some churn has occurred on the object. An example of this would
be a patch that does a "create" operation for a datastore node where be a patch that does a "create" operation for a datastore node where
the receiver believes one already exists, or a "merge" operation the receiver believes one already exists, or a "merge" operation
which replaces a previous value with the same value. Note that this which replaces a previous value with the same value. Note that this
means that the "create" and "delete" errors described in [RFC8072] means that the "create" and "delete" errors described in [RFC8072]
section 2.5 are not errors, and are valid operations with YANG push. section 2.5 are not errors, and are valid operations with YANG push.
3.6. Datastore Selection 3.6. Defining the Selection with a Datastore
A subscription must specify both the selection filters and the A subscription must specify both the selection filters and the
datastore against which these selection filters will be applied. datastore against which these selection filters will be applied.
This information is used to choose and subsequently push data from This information is used to choose and subsequently push data from
the publisher's datastore to the receivers. the publisher's datastore to the receivers.
Only a single selection filter can be applied to a subscription at a Only a single selection filter can be applied to a subscription at a
time. An rpc request proposing a new selection filter MUST remove time. An rpc request proposing a new selection filter MUST remove
any existing filter. The following selection filter types are any existing filter. The following selection filter types are
included in the yang-push data model, and may be applied against a included in the yang-push data model, and may be applied against a
skipping to change at page 10, line 14 skipping to change at page 10, line 20
These filters are intended to be used as selectors that define which These filters are intended to be used as selectors that define which
objects are within the scope of a subscription. A publisher MUST objects are within the scope of a subscription. A publisher MUST
support at least one type of selection filter. support at least one type of selection filter.
Xpath itself provides powerful filtering constructs and care must be Xpath itself provides powerful filtering constructs and care must be
used in filter definition. As an example, consider an xpath filter used in filter definition. As an example, consider an xpath filter
with a boolean result; such a result will not provide an easily with a boolean result; such a result will not provide an easily
interpretable subset of a datastore. Beyond the boolean example, it interpretable subset of a datastore. Beyond the boolean example, it
is quite possible to define an xpath filter where results are easy is quite possible to define an xpath filter where results are easy
for an application to mis-interpret. Consider an xpath filter which for an application to misinterpret. Consider an xpath filter which
only passes a datastore object when an interface is up. It is up to only passes a datastore object when an interface is up. It is up to
the receiver to understand implications of the presence or absence of the receiver to understand implications of the presence or absence of
objects in each update. objects in each update.
When the set of selection filtering criteria is applied for periodic When the set of selection filtering criteria is applied for a
subscription, all selected datastore nodes to which a receiver has periodic subscription, all selected datastore nodes to which a
access are provided to a receiver. If the same filtering criteria is receiver has access are provided to that receiver. If the same
applied to an on-change subscription, only the subset of those filtering criteria is applied to an on-change subscription, only the
datastore nodes supporting on-change is provided. A datastore node subset of those datastore nodes supporting on-change is provided. A
which doesn't support on-change is never sent as part of an on-change datastore node which doesn't support on-change is never sent as part
subscription's "push-update" or "push-change-update". of an on-change subscription's "push-update" or "push-change-update".
3.7. Streaming Updates 3.7. Streaming Updates
Contrary to traditional data retrieval requests, datastore Contrary to traditional data retrieval requests, datastore
subscription enables an unbounded series of update records to be subscription enables an unbounded series of update records to be
streamed over time. Two generic YANG notifications for update streamed over time. Two generic YANG notifications for update
records have been defined for this: "push-update" and "push-change- records have been defined for this: "push-update" and "push-change-
update". update".
A "push-update" notification defines a complete, filtered update of A "push-update" notification defines a complete, filtered update of
the datastore per the terms of a subscription. This type of YANG the datastore per the terms of a subscription. This type of YANG
notification is used for continuous updates of periodic notification is used for continuous updates of periodic
subscriptions. A "push-update" notification can also be used for the subscriptions. A "push-update" notification can also be used for the
on-change subscriptions in two cases. First it will be used as the on-change subscriptions in two cases. First it will be used as the
initial "push-update" if there is a need to synchronize the receiver initial "push-update" if there is a need to synchronize the receiver
at the start of a new subscription. It also MAY be sent if the at the start of a new subscription. It also MAY be sent if the
publisher later chooses to resynch an on-change subscription. The publisher later chooses to resynch an on-change subscription. The
"push-update" update record contains a data snippet that contains an "push-update" update record contains an instantiated datastore
instantiated datastore subtree with all of the subscribed contents. subtree with all of the subscribed contents. The content of the
The content of the update record is equivalent to the contents that update record is equivalent to the contents that would be obtained
would be obtained had the same data been explicitly retrieved using had the same data been explicitly retrieved using a datastore
e.g., a NETCONF "get" operation, with the same filters applied. retrieval operation using the same transport with the same filters
applied.
A "push-change-update" notification is the most common type of update A "push-change-update" notification is the most common type of update
for on-change subscriptions. The update record in this case contains for on-change subscriptions. The update record in this case contains
a data snippet that indicates the set of changes that datastore nodes the set of changes that datastore nodes have undergone since the last
have undergone since the last notification message. In other words, notification message. In other words, this indicates which datastore
this indicates which datastore nodes have been created, deleted, or nodes have been created, deleted, or have had changes to their
have had changes to their values. In cases where multiple changes values. In cases where multiple changes have occurred and the object
have occurred and the object has not been deleted, the object's most has not been deleted, the object's most current value is reported.
current value is reported. (In other words, for each object, only (In other words, for each object, only one change is reported, not
one change is reported, not its entire history. Doing so would its entire history. Doing so would defeat the purpose of the
defeat the purpose of the dampening period.) dampening period.)
These new "push-update" or "push-change-update" are encoded and These new "push-update" or "push-change-update" are encoded and
placed within notification messages, and ultimately queued for egress placed within notification messages, and ultimately queued for egress
over the specified transport. over the specified transport.
The following is an example of a notification message for a The following is an example of a notification message for a
subscription tracking the operational status of a single Ethernet subscription tracking the operational status of a single Ethernet
port (per [RFC7223]). This notification message is encoded XML over port (per [RFC7223]). This notification message is encoded XML over
NETCONF as per [I-D.draft-ietf-netconf-netconf-event-notifications]. NETCONF as per [I-D.draft-ietf-netconf-netconf-event-notifications].
skipping to change at page 16, line 49 skipping to change at page 16, line 49
accordingly. accordingly.
Update records for a single subscription MAY NOT be resequenced prior Update records for a single subscription MAY NOT be resequenced prior
to transport. to transport.
It is conceivable that under certain circumstances, a publisher will It is conceivable that under certain circumstances, a publisher will
recognize that it is unable to include within an update record the recognize that it is unable to include within an update record the
full set of objects desired per the terms of a subscription. In this full set of objects desired per the terms of a subscription. In this
case, the publisher MUST take one or more of the following actions. case, the publisher MUST take one or more of the following actions.
o A publisher MUST set the "updates-not-sent" flag on any update o A publisher MUST set the "incomplete-update" flag on any update
record which is known to be missing information. record which is known to be missing information.
o It MAY choose to suspend a subscription as per o It MAY choose to suspend a subscription as per
[I-D.draft-ietf-netconf-subscribed-notifications]. [I-D.draft-ietf-netconf-subscribed-notifications].
o When resuming an on-change subscription, the publisher SHOULD o When resuming an on-change subscription, the publisher SHOULD
generate a complete patch from the previous update record. If generate a complete patch from the previous update record. If
this is not possible and the "no-synch-on-start" option is not this is not possible and the "no-synch-on-start" option is not
present for the subscription, then the full datastore contents MAY present for the subscription, then the full datastore contents MAY
be sent via a "push-update" instead (effectively replacing the be sent via a "push-update" instead (effectively replacing the
previous contents). If neither of these are possible, then an previous contents). If neither of these are possible, then an
"updates-not-sent" flag MUST be included on the next "push-change- "incomplete-update" flag MUST be included on the next "push-
update". change-update".
Note: It is perfectly acceptable to have a series of "push-change- Note: It is perfectly acceptable to have a series of "push-change-
update" notifications (and even "push update" notifications) serially update" notifications (and even "push update" notifications) serially
queued at the transport layer awaiting transmission. It is not queued at the transport layer awaiting transmission. It is not
required to merge pending update messages. I.e., the dampening required to merge pending update messages. I.e., the dampening
period applies to update record creation, not transmission. period applies to update record creation, not transmission.
3.11.2. Publisher capacity 3.11.2. Publisher capacity
It is far preferable to decline a subscription request than to accept It is far preferable to decline a subscription request than to accept
skipping to change at page 18, line 50 skipping to change at page 18, line 50
| | | +--:(stream-subtree-filter) | | | +--:(stream-subtree-filter)
| | | | +--rw stream-subtree-filter? | | | | +--rw stream-subtree-filter?
| | | <anydata> {subtree}? | | | <anydata> {subtree}?
| | | +--:(stream-xpath-filter) | | | +--:(stream-xpath-filter)
| | | +--rw stream-xpath-filter? | | | +--rw stream-xpath-filter?
| | | yang:xpath1.0 {xpath}? | | | yang:xpath1.0 {xpath}?
| | +--rw stream stream-ref | | +--rw stream stream-ref
| | +--rw replay-start-time? yang:date-and-time {replay}? | | +--rw replay-start-time? yang:date-and-time {replay}?
| +--:(yp:datastore) | +--:(yp:datastore)
| +--rw yp:datastore identityref | +--rw yp:datastore identityref
| +--rw (yp:selected-content)? | +--rw (yp:selection-filter)?
| +--:(yp:by-reference) | +--:(yp:by-reference)
| | +--rw yp:selection-filter-ref selection-filter-ref | | +--rw yp:selection-filter-ref selection-filter-ref
| +--:(yp:within-subscription) | +--:(yp:within-subscription)
| +--rw (yp:filter-spec)? | +--rw (yp:filter-spec)?
| +--:(yp:datastore-subtree-filter) | +--:(yp:datastore-subtree-filter)
| | +--rw yp:datastore-subtree-filter? | | +--rw yp:datastore-subtree-filter?
| <anydata> {sn:subtree}? | <anydata> {sn:subtree}?
| +--:(yp:datastore-xpath-filter) | +--:(yp:datastore-xpath-filter)
| +--rw yp:datastore-xpath-filter? | +--rw yp:datastore-xpath-filter?
| yang:xpath1.0 {sn:xpath}? | yang:xpath1.0 {sn:xpath}?
skipping to change at page 20, line 18 skipping to change at page 20, line 18
| | | | | +--:(stream-subtree-filter) | | | | | +--:(stream-subtree-filter)
| | | | | | +---w stream-subtree-filter? | | | | | | +---w stream-subtree-filter?
| | | | | <anydata> {subtree}? | | | | | <anydata> {subtree}?
| | | | | +--:(stream-xpath-filter) | | | | | +--:(stream-xpath-filter)
| | | | | +---w stream-xpath-filter? | | | | | +---w stream-xpath-filter?
| | | | | yang:xpath1.0 {xpath}? | | | | | yang:xpath1.0 {xpath}?
| | | | +---w stream stream-ref | | | | +---w stream stream-ref
| | | | +---w replay-start-time? yang:date-and-time {replay}? | | | | +---w replay-start-time? yang:date-and-time {replay}?
| | | +--:(yp:datastore) | | | +--:(yp:datastore)
| | | +---w yp:datastore identityref | | | +---w yp:datastore identityref
| | | +---w (yp:selected-content)? | | | +---w (yp:selection-filter)?
| | | +--:(yp:by-reference) | | | +--:(yp:by-reference)
| | | | +---w yp:selection-filter-ref selection-filter-ref | | | | +---w yp:selection-filter-ref selection-filter-ref
| | | +--:(yp:within-subscription) | | | +--:(yp:within-subscription)
| | | +---w (yp:filter-spec)? | | | +---w (yp:filter-spec)?
| | | +--:(yp:datastore-subtree-filter) | | | +--:(yp:datastore-subtree-filter)
| | | | +---w yp:datastore-subtree-filter? | | | | +---w yp:datastore-subtree-filter?
| | | | <anydata> {sn:subtree}? | | | | <anydata> {sn:subtree}?
| | | +--:(yp:datastore-xpath-filter) | | | +--:(yp:datastore-xpath-filter)
| | | +---w yp:datastore-xpath-filter? | | | +---w yp:datastore-xpath-filter?
| | | yang:xpath1.0 {sn:xpath}? | | | yang:xpath1.0 {sn:xpath}?
skipping to change at page 21, line 14 skipping to change at page 21, line 14
| | | | +---w stream-filter-ref stream-filter-ref | | | | +---w stream-filter-ref stream-filter-ref
| | | +--:(within-subscription) | | | +--:(within-subscription)
| | | +---w (filter-spec)? | | | +---w (filter-spec)?
| | | +--:(stream-subtree-filter) | | | +--:(stream-subtree-filter)
| | | | +---w stream-subtree-filter? | | | | +---w stream-subtree-filter?
| | | <anydata> {subtree}? | | | <anydata> {subtree}?
| | | +--:(stream-xpath-filter) | | | +--:(stream-xpath-filter)
| | | +---w stream-xpath-filter? | | | +---w stream-xpath-filter?
| | | yang:xpath1.0 {xpath}? | | | yang:xpath1.0 {xpath}?
| | +--:(yp:datastore) | | +--:(yp:datastore)
| | +---w (yp:selected-content)? | | +---w (yp:selection-filter)?
| | +--:(yp:by-reference) | | +--:(yp:by-reference)
| | | +---w yp:selection-filter-ref selection-filter-ref | | | +---w yp:selection-filter-ref selection-filter-ref
| | +--:(yp:within-subscription) | | +--:(yp:within-subscription)
| | +---w (yp:filter-spec)? | | +---w (yp:filter-spec)?
| | +--:(yp:datastore-subtree-filter) | | +--:(yp:datastore-subtree-filter)
| | | +---w yp:datastore-subtree-filter? | | | +---w yp:datastore-subtree-filter?
| | | <anydata> {sn:subtree}? | | | <anydata> {sn:subtree}?
| | +--:(yp:datastore-xpath-filter) | | +--:(yp:datastore-xpath-filter)
| | +---w yp:datastore-xpath-filter? | | +---w yp:datastore-xpath-filter?
| | yang:xpath1.0 {sn:xpath}? | | yang:xpath1.0 {sn:xpath}?
skipping to change at page 22, line 28 skipping to change at page 22, line 28
| | | | +--:(stream-subtree-filter) | | | | +--:(stream-subtree-filter)
| | | | | +--ro stream-subtree-filter? | | | | | +--ro stream-subtree-filter?
| | | | | <anydata> {subtree}? | | | | | <anydata> {subtree}?
| | | | +--:(stream-xpath-filter) | | | | +--:(stream-xpath-filter)
| | | | +--ro stream-xpath-filter? | | | | +--ro stream-xpath-filter?
| | | | yang:xpath1.0 {xpath}? | | | | yang:xpath1.0 {xpath}?
| | | +--ro stream stream-ref | | | +--ro stream stream-ref
| | | +--ro replay-start-time? yang:date-and-time {replay}? | | | +--ro replay-start-time? yang:date-and-time {replay}?
| | +--:(yp:datastore) | | +--:(yp:datastore)
| | +--ro yp:datastore identityref | | +--ro yp:datastore identityref
| | +--ro (yp:selected-content)? | | +--ro (yp:selection-filter)?
| | +--:(yp:by-reference) | | +--:(yp:by-reference)
| | | +--ro yp:selection-filter-ref selection-filter-ref | | | +--ro yp:selection-filter-ref selection-filter-ref
| | +--:(yp:within-subscription) | | +--:(yp:within-subscription)
| | +--ro (yp:filter-spec)? | | +--ro (yp:filter-spec)?
| | +--:(yp:datastore-subtree-filter) | | +--:(yp:datastore-subtree-filter)
| | | +--ro yp:datastore-subtree-filter? | | | +--ro yp:datastore-subtree-filter?
| | <anydata> {sn:subtree}? | | <anydata> {sn:subtree}?
| | +--:(yp:datastore-xpath-filter) | | +--:(yp:datastore-xpath-filter)
| | +--ro yp:datastore-xpath-filter? | | +--ro yp:datastore-xpath-filter?
| | yang:xpath1.0 {sn:xpath}? | | yang:xpath1.0 {sn:xpath}?
skipping to change at page 23, line 28 skipping to change at page 23, line 28
| | | | +--:(stream-subtree-filter) | | | | +--:(stream-subtree-filter)
| | | | | +--ro stream-subtree-filter? | | | | | +--ro stream-subtree-filter?
| | | | | <anydata> {subtree}? | | | | | <anydata> {subtree}?
| | | | +--:(stream-xpath-filter) | | | | +--:(stream-xpath-filter)
| | | | +--ro stream-xpath-filter? | | | | +--ro stream-xpath-filter?
| | | | yang:xpath1.0 {xpath}? | | | | yang:xpath1.0 {xpath}?
| | | +--ro stream stream-ref | | | +--ro stream stream-ref
| | | +--ro replay-start-time? yang:date-and-time {replay}? | | | +--ro replay-start-time? yang:date-and-time {replay}?
| | +--:(yp:datastore) | | +--:(yp:datastore)
| | +--ro yp:datastore identityref | | +--ro yp:datastore identityref
| | +--ro (yp:selected-content)? | | +--ro (yp:selection-filter)?
| | +--:(yp:by-reference) | | +--:(yp:by-reference)
| | | +--ro yp:selection-filter-ref selection-filter-ref | | | +--ro yp:selection-filter-ref selection-filter-ref
| | +--:(yp:within-subscription) | | +--:(yp:within-subscription)
| | +--ro (yp:filter-spec)? | | +--ro (yp:filter-spec)?
| | +--:(yp:datastore-subtree-filter) | | +--:(yp:datastore-subtree-filter)
| | | +--ro yp:datastore-subtree-filter? | | | +--ro yp:datastore-subtree-filter?
| | | <anydata> {sn:subtree}? | | | <anydata> {sn:subtree}?
| | +--:(yp:datastore-xpath-filter) | | +--:(yp:datastore-xpath-filter)
| | +--ro yp:datastore-xpath-filter? | | +--ro yp:datastore-xpath-filter?
| | yang:xpath1.0 {sn:xpath}? | | yang:xpath1.0 {sn:xpath}?
skipping to change at page 24, line 48 skipping to change at page 24, line 48
+--ro period-hint? timeticks +--ro period-hint? timeticks
+--ro filter-failure-hint? string +--ro filter-failure-hint? string
+--ro object-count-estimate? uint32 +--ro object-count-estimate? uint32
+--ro object-count-limit? uint32 +--ro object-count-limit? uint32
+--ro kilobytes-estimate? uint32 +--ro kilobytes-estimate? uint32
+--ro kilobytes-limit? uint32 +--ro kilobytes-limit? uint32
notifications: notifications:
+---n push-update +---n push-update
| +--ro subscription-id? sn:subscription-id | +--ro subscription-id? sn:subscription-id
| +--ro updates-not-sent? empty | +--ro incomplete-update? empty
| +--ro datastore-contents? <anydata> | +--ro datastore-contents? <anydata>
+---n push-change-update {on-change}? +---n push-change-update {on-change}?
+--ro subscription-id? sn:subscription-id +--ro subscription-id? sn:subscription-id
+--ro updates-not-sent? empty +--ro incomplete-update? empty
+--ro datastore-changes? <anydata> +--ro datastore-changes? <anydata>
Figure 6: Model structure Figure 6: Model structure
Selected components of the model are summarized below. Selected components of the model are summarized below.
4.2. Subscription configuration 4.2. Subscription configuration
Both configured and dynamic subscriptions are represented within the Both configured and dynamic subscriptions are represented within the
list subscription. But only configured subscriptions are listed list subscription. New and enhanced parameters extending the basic
within list subscription-config. In both lists, each subscription subscription data model in
has own list elements. New and enhanced parameters extending the
basic subscription data model in
[I-D.draft-ietf-netconf-subscribed-notifications] include: [I-D.draft-ietf-netconf-subscribed-notifications] include:
o The targeted datastore from which the selection is being made. o The targeted datastore from which the selection is being made.
The potential datastores include those from The potential datastores include those from
[I-D.draft-ietf-netmod-revised-datastores]. A platform may also [I-D.draft-ietf-netmod-revised-datastores]. A platform may also
choose to support a custom datastore. choose to support a custom datastore.
o A selection filter identifying yang nodes of interest within a o A selection filter identifying yang nodes of interest within a
datastore. Filter contents are specified via a reference to an datastore. Filter contents are specified via a reference to an
existing filter, or via an in-line definition for only that existing filter, or via an in-line definition for only that
skipping to change at page 26, line 40 skipping to change at page 26, line 40
contents. An [RFC5277] Section 4 one-way notification MAY be used contents. An [RFC5277] Section 4 one-way notification MAY be used
for encoding updates. Where it is, the relevant "subscription-id" for encoding updates. Where it is, the relevant "subscription-id"
MUST be encoded as the first element within each "push-update" or MUST be encoded as the first element within each "push-update" or
"push-change-update". This allows a receiver to differentiate which "push-change-update". This allows a receiver to differentiate which
subscription resulted in a particular push. subscription resulted in a particular push.
A "time-of-update" which represents the time an update record A "time-of-update" which represents the time an update record
snapshot was generated. A receiver MAY assume that a publisher's snapshot was generated. A receiver MAY assume that a publisher's
objects have these pushed values at this point in time. objects have these pushed values at this point in time.
An "updates-not-sent" object. This object indicates that not all An "incomplete-update" object. This object indicates that not all
changes which have occurred since the last update are actually changes which have occurred since the last update are actually
included with this update. In other words, the publisher has failed included with this update. In other words, the publisher has failed
to fulfill its full subscription obligations. (For example a to fulfill its full subscription obligations. (For example a
datastore was unable to providing the full set of datastore nodes to datastore was unable to providing the full set of datastore nodes to
a publisher process.) To facilitate re-synchronization of on-change a publisher process.) To facilitate re-synchronization of on-change
subscriptions, a publisher MAY subsequently send a "push-update" subscriptions, a publisher MAY subsequently send a "push-update"
containing a full selection snapshot of subscribed data. containing a full selection snapshot of subscribed data.
4.4. YANG RPCs 4.4. YANG RPCs
skipping to change at page 31, line 28 skipping to change at page 31, line 28
A configured subscription cannot be modified using "modify- A configured subscription cannot be modified using "modify-
subscription" RPC. Instead, the configuration needs to be edited as subscription" RPC. Instead, the configuration needs to be edited as
needed. needed.
4.4.3. Delete-subscription RPC 4.4.3. Delete-subscription RPC
To stop receiving updates from a subscription and effectively delete To stop receiving updates from a subscription and effectively delete
a subscription that had previously been established using an a subscription that had previously been established using an
"establish-subscription" RPC, a subscriber can send a "delete- "establish-subscription" RPC, a subscriber can send a "delete-
subscription" RPC, which takes as only input the subscription's subscription" RPC, which takes as only input the subscription's
"identifier". "identifier". This RPC is unmodified from
[I-D.draft-ietf-netconf-subscribed-notifications].
Configured subscriptions cannot be deleted via RPC, but have to be
removed from the configuration. This RPC is identical to the RPC
from [I-D.draft-ietf-netconf-subscribed-notifications].
4.4.4. Resynch-subscription RPC 4.4.4. Resynch-subscription RPC
This RPC is only applicable only for on-change subscriptions This RPC is only applicable only for on-change subscriptions
previously been established using an "establish-subscription" RPC. previously established using an "establish-subscription" RPC. For
For example: example:
<netconf:rpc message-id="103" <netconf:rpc message-id="103"
xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
<resynch-subscription <resynch-subscription
xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push" xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push"
xmlns:sn="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"> xmlns:sn="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
<identifier>1011</identifier> <identifier>1011</identifier>
</resynch-subscription> </resynch-subscription>
</netconf:rpc> </netconf:rpc>
skipping to change at page 32, line 43 skipping to change at page 32, line 40
replicated publisher in order to detect the specific YANG library replicated publisher in order to detect the specific YANG library
changes. The "ietf-netconf-notifications" module defined in changes. The "ietf-netconf-notifications" module defined in
[RFC6470] contains a "netconf-capability-change" notification that [RFC6470] contains a "netconf-capability-change" notification that
can identify specific module changes. For example, the module URI can identify specific module changes. For example, the module URI
capability of a newly loaded module will be listed in the "added- capability of a newly loaded module will be listed in the "added-
capability" leaf-list, and the module URI capability of an removed capability" leaf-list, and the module URI capability of an removed
module will be listed in the "deleted-capability" leaf-list. module will be listed in the "deleted-capability" leaf-list.
5. YANG module 5. YANG module
<CODE BEGINS>; file "ietf-yang-push@2018-02-05.yang" <CODE BEGINS>; file "ietf-yang-push@2018-02-23.yang"
module ietf-yang-push { module ietf-yang-push {
yang-version 1.1; yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push"; namespace "urn:ietf:params:xml:ns:yang:ietf-yang-push";
prefix yp; prefix yp;
import ietf-yang-types { import ietf-yang-types {
prefix yang; prefix yang;
} }
import ietf-subscribed-notifications { import ietf-subscribed-notifications {
prefix sn; prefix sn;
skipping to change at page 33, line 43 skipping to change at page 33, line 39
Editor: Andy Bierman Editor: Andy Bierman
<mailto:andy@yumaworks.com> <mailto:andy@yumaworks.com>
Editor: Balazs Lengyel Editor: Balazs Lengyel
<mailto:balazs.lengyel@ericsson.com>"; <mailto:balazs.lengyel@ericsson.com>";
description description
"This module contains YANG specifications for YANG push."; "This module contains YANG specifications for YANG push.";
revision 2018-02-05 { revision 2018-02-23 {
description description
"Initial revision."; "Initial revision.";
reference reference
"draft-ietf-netconf-yang-push-13"; "draft-ietf-netconf-yang-push-15";
} }
/* /*
* FEATURES * FEATURES
*/ */
feature on-change { feature on-change {
description description
"This feature indicates that on-change triggered subscriptions "This feature indicates that on-change triggered subscriptions
are supported."; are supported.";
skipping to change at page 34, line 21 skipping to change at page 34, line 17
/* /*
* IDENTITIES * IDENTITIES
*/ */
/* Error type identities for datastore subscription */ /* Error type identities for datastore subscription */
identity resynch-subscription-error { identity resynch-subscription-error {
description description
"Problem found while attempting to fulfill an "Problem found while attempting to fulfill an
'resynch-subscription' rpc request. "; 'resynch-subscription' RPC request. ";
} }
identity cant-exclude { identity cant-exclude {
base sn:establish-subscription-error; base sn:establish-subscription-error;
description description
"Unable to remove the set of 'excluded-changes'. This means the "Unable to remove the set of 'excluded-changes'. This means the
publisher is unable to restrict 'push-change-update's to just the publisher is unable to restrict 'push-change-update's to just the
change types requested for this subscription."; change types requested for this subscription.";
} }
skipping to change at page 35, line 30 skipping to change at page 35, line 25
identity period-unsupported { identity period-unsupported {
base sn:establish-subscription-error; base sn:establish-subscription-error;
base sn:modify-subscription-error; base sn:modify-subscription-error;
base sn:subscription-suspended-reason; base sn:subscription-suspended-reason;
description description
"Requested time period is too short. This can be for both "Requested time period is too short. This can be for both
periodic and on-change subscriptions (with or without periodic and on-change subscriptions (with or without
dampening.) dampening.)
Hints suggesting an acceptable period setting may be returned Hints suggesting alternative periods may be returned as
as supplemental information in a corresponding RPC error supplemental information when this expressed.";
response, as applicable.";
} }
identity result-too-big { identity result-too-big {
base sn:establish-subscription-error; base sn:establish-subscription-error;
base sn:modify-subscription-error; base sn:modify-subscription-error;
base sn:subscription-suspended-reason; base sn:subscription-suspended-reason;
description description
"Periodic or on-change push update datatrees exceed a maximum "Periodic or on-change push update datatrees exceed a maximum size
size limit. limit. Hints on estimated size of what was too big may be
returned as supplemental information when this expressed.";
Hints on a parameter setting that would result in a reasonable
size may be returned as supplemental information in a
corresponding RPC error response, as applicable.";
} }
identity synchronization-size { identity synchronization-size {
base sn:establish-subscription-error; base sn:establish-subscription-error;
base sn:modify-subscription-error; base sn:modify-subscription-error;
base resynch-subscription-error; base resynch-subscription-error;
base sn:subscription-suspended-reason; base sn:subscription-suspended-reason;
description description
"Synch-on-start or resynchronization datatree exceeds a maximum "Synch-on-start or resynchronization datatree exceeds a maximum
size limit. size limit.
Hints on a parameter setting that would result in a reasonable Where this identity is referenced as an 'error-app-tag' within an
size may be returned as supplemental information in a RPC response, the response's 'error-info' may contain:";
corresponding RPC error response, as applicable.";
} }
identity unchanging-selection { identity unchanging-selection {
base sn:establish-subscription-error; base sn:establish-subscription-error;
base sn:modify-subscription-error; base sn:modify-subscription-error;
base sn:subscription-terminated-reason; base sn:subscription-terminated-reason;
description description
"Selection filter is unlikely to ever select datatree nodes. This "Selection filter is unlikely to ever select datatree nodes. This
means that based on the subscriber's current access rights, the means that based on the subscriber's current access rights, the
publisher recognizes that the selection filter is unlikely to ever publisher recognizes that the selection filter is unlikely to ever
select datatree nodes which change. Examples for this might be select datatree nodes which change. Examples for this might be
that node or subtree doesn't exist, read access is not permitted that node or subtree doesn't exist, read access is not permitted
skipping to change at page 36, line 36 skipping to change at page 36, line 27
/* /*
* TYPE DEFINITIONS * TYPE DEFINITIONS
*/ */
typedef change-type { typedef change-type {
type enumeration { type enumeration {
enum "create" { enum "create" {
description description
"Create a new data resource if it does not already exist. If "Create a new data resource if it does not already exist. If
it already exists, replace."; it already exists, replace it.";
} }
enum "delete" { enum "delete" {
description description
"Delete a data resource if it already exists. If it does not "Delete a data resource if it already exists. If it does not
exists, take no action."; exist, take no action.";
} }
enum "insert" { enum "insert" {
description description
"Insert a new user-ordered data resource"; "Insert a new user-ordered data resource";
} }
enum "merge" { enum "merge" {
description description
"merge the edit value with the target data resource; create "merge the edit value with the target data resource; create
if it does not already exist"; if it does not already exist";
} }
skipping to change at page 38, line 4 skipping to change at page 37, line 43
a targeted datastore should be included in push updates."; a targeted datastore should be included in push updates.";
leaf datastore { leaf datastore {
type identityref { type identityref {
base ds:datastore; base ds:datastore;
} }
mandatory true; mandatory true;
description description
"Datastore from which to retrieve data."; "Datastore from which to retrieve data.";
} }
uses selection-filter-objects; uses selection-filter-objects;
} }
grouping selection-filter-types { grouping selection-filter-types {
description description
"This grouping defines a selector for objects from a "This grouping defines the types of selectors for objects from a
datastore."; datastore.";
choice filter-spec { choice filter-spec {
description description
"The content filter specification for this request."; "The content filter specification for this request.";
anydata datastore-subtree-filter { anydata datastore-subtree-filter {
if-feature "sn:subtree"; if-feature "sn:subtree";
description description
"This parameter identifies the portions of the "This parameter identifies the portions of the
target datastore to retrieve."; target datastore to retrieve.";
} }
leaf datastore-xpath-filter { leaf datastore-xpath-filter {
if-feature "sn:xpath"; if-feature "sn:xpath";
type yang:xpath1.0; type yang:xpath1.0;
description description
skipping to change at page 38, line 52 skipping to change at page 38, line 43
o The context node is the root node of the target o The context node is the root node of the target
datastore."; datastore.";
} }
} }
} }
grouping selection-filter-objects { grouping selection-filter-objects {
description description
"This grouping defines a selector for objects from a "This grouping defines a selector for objects from a
datastore."; datastore.";
choice selected-content { choice selection-filter {
description description
"The source of the selection filter applied to the subscription. "The source of the selection filter applied to the subscription.
This will come either referenced from a global list, or be This will come either referenced from a global list, or be
provided within the subscription itself."; provided within the subscription itself.";
case by-reference { case by-reference {
description description
"Incorporate a filter that has been configured separately."; "Incorporate a filter that has been configured separately.";
leaf selection-filter-ref { leaf selection-filter-ref {
type selection-filter-ref; type selection-filter-ref;
mandatory true; mandatory true;
skipping to change at page 39, line 50 skipping to change at page 39, line 41
presence "indicates an periodic subscription"; presence "indicates an periodic subscription";
description description
"The publisher is requested to notify periodically the "The publisher is requested to notify periodically the
current values of the datastore as defined by the selection current values of the datastore as defined by the selection
filter."; filter.";
leaf period { leaf period {
type yang:timeticks; type yang:timeticks;
mandatory true; mandatory true;
description description
"Duration of time which should occur between periodic "Duration of time which should occur between periodic
push updates. Where the anchor-time is push updates.";
available, the push will include the objects and their
values which exist at an exact multiple of timeticks
aligning to this start-time anchor.";
} }
leaf anchor-time { leaf anchor-time {
type yang:date-and-time; type yang:date-and-time;
description description
"Designates a timestamp before or after which a series of "Designates a timestamp before or after which a series of
periodic push updates are determined. The next update periodic push updates are determined. The next update
will take place at a whole multiple interval from the will take place at a whole multiple interval from the
anchor time. For example, for an anchor time is set for anchor time. For example, for an anchor time is set for
the top of a particular minute and a period interval of a the top of a particular minute and a period interval of a
minute, updates will be sent at the top of every minute minute, updates will be sent at the top of every minute
skipping to change at page 41, line 18 skipping to change at page 41, line 6
type empty; type empty;
description description
"The presence of this object restricts an on-change "The presence of this object restricts an on-change
subscription from sending push-update notifications. When subscription from sending push-update notifications. When
present, pushing a full selection per the terms of the present, pushing a full selection per the terms of the
selection filter MUST NOT be done for this subscription. selection filter MUST NOT be done for this subscription.
Only updates about changes, i.e. only push-change-update Only updates about changes, i.e. only push-change-update
notifications are sent. When absent (default behavior), notifications are sent. When absent (default behavior),
in order to facilitate a receiver's synchronization, a full in order to facilitate a receiver's synchronization, a full
update is sent when the subscription starts using a update is sent when the subscription starts using a
push-update notification, just like in the case of a push-update notification. After that, push-change-update
periodic subscription. After that, push-change-update
notifications are exclusively sent unless the publisher notifications are exclusively sent unless the publisher
chooses to resynch the subscription via a new push-update chooses to resynch the subscription via a new push-update
notification."; notification.";
} }
leaf-list excluded-change { leaf-list excluded-change {
type change-type; type change-type;
description description
"Use to restrict which changes trigger an update. "Use to restrict which changes trigger an update.
For example, if modify is excluded, only creation and For example, if modify is excluded, only creation and
deletion of objects is reported."; deletion of objects is reported.";
} }
} }
} }
} }
grouping hints { grouping hints {
description description
"Parameters associated with some error on for a subscription made "Parameters associated with some error for a subscription made
upon a datastore."; upon a datastore.";
leaf period-hint { leaf period-hint {
type yang:timeticks; type yang:timeticks;
description description
"Returned when the requested time period is too short. This "Returned when the requested time period is too short. This
hint can assert a viable period for either a periodic push hint can assert a viable period for either a periodic push
cadence or an on-change dampening interval."; cadence or an on-change dampening interval.";
} }
leaf filter-failure-hint { leaf filter-failure-hint {
type string; type string;
skipping to change at page 42, line 43 skipping to change at page 42, line 30
} }
/* /*
* RPCs * RPCs
*/ */
rpc resynch-subscription { rpc resynch-subscription {
if-feature "on-change"; if-feature "on-change";
description description
"This RPC allows a subscriber of an active on-change "This RPC allows a subscriber of an active on-change
subscription to request a full push of objects in there current subscription to request a full push of objects in their current
state. A successful result would be the set of YANG objects state. A successful result would invoke a push-update of all
equivalent to a Get using the existing selection criteria. This datastore objects that the subscriber is permitted to access.
request may only come from the same subscriber using the This request may only come from the same subscriber using the
establish-subscription RPC."; establish-subscription RPC.";
input { input {
leaf identifier { leaf identifier {
type sn:subscription-id; type sn:subscription-id;
mandatory true; mandatory true;
description description
"Identifier of the subscription that is to be resynched."; "Identifier of the subscription that is to be resynched.";
} }
} }
} }
skipping to change at page 43, line 41 skipping to change at page 43, line 28
augment "/sn:establish-subscription/sn:input" { augment "/sn:establish-subscription/sn:input" {
description description
"This augmentation adds additional subscription parameters that "This augmentation adds additional subscription parameters that
apply specifically to datastore updates to RPC input."; apply specifically to datastore updates to RPC input.";
uses update-policy; uses update-policy;
} }
augment "/sn:establish-subscription/sn:input/sn:target" { augment "/sn:establish-subscription/sn:input/sn:target" {
description description
"This augmentation adds the datastore as a valid parameter object "This augmentation adds the datastore as a valid target
for the subscription to RPC input. This provides a target for for the subscription to RPC input.";
the filter.";
case datastore { case datastore {
description description
"Information specifying the parameters of an request for a "Information specifying the parameters of an request for a
datastore subscription."; datastore subscription.";
uses datastore-criteria; uses datastore-criteria;
} }
} }
rc:yang-data establish-subscription-error-datastore { rc:yang-data establish-subscription-error-datastore {
container establish-subscription-error-datastore { container establish-subscription-error-datastore {
description description
"If any 'establish-subscription' RPC parameters are "If any 'establish-subscription' RPC parameters are
unsupportable against the datastore, a subscription is not unsupportable against the datastore, a subscription is not
created and the RPC error response MUST indicate the reason why created and the RPC error response MUST indicate the reason why
the subscription failed to be created. This yang-data MAY be the subscription failed to be created. This yang-data MAY be
inserted as structured data within a subscription's RPC error inserted as structured data within a subscription's RPC error
response to indicate the failure reason. This yang-data MUST be response to indicate the failure reason. This yang-data MUST be
inserted if hints are to be provided back to the subscriber."; inserted if hints are to be provided back to the subscriber.";
skipping to change at page 44, line 35 skipping to change at page 44, line 21
augment "/sn:modify-subscription/sn:input" { augment "/sn:modify-subscription/sn:input" {
description description
"This augmentation adds additional subscription parameters "This augmentation adds additional subscription parameters
specific to datastore updates."; specific to datastore updates.";
uses update-policy-modifiable; uses update-policy-modifiable;
} }
augment "/sn:modify-subscription/sn:input/sn:target" { augment "/sn:modify-subscription/sn:input/sn:target" {
description description
"This augmentation adds the datastore as a valid parameter object "This augmentation adds the datastore as a valid target
for the subscription to RPC input. This provides a target for for the subscription to RPC input.";
the filter.";
case datastore { case datastore {
description description
"Information specifying the parameters of an request for a "Information specifying the parameters of an request for a
datastore subscription."; datastore subscription.";
uses selection-filter-objects; uses selection-filter-objects;
} }
} }
rc:yang-data modify-subscription-error-datastore { rc:yang-data modify-subscription-error-datastore {
container modify-subscription-error-datastore { container modify-subscription-error-datastore {
skipping to change at page 45, line 37 skipping to change at page 45, line 22
used for synchronization updates of an on-change subscription. used for synchronization updates of an on-change subscription.
This notification shall only be sent to receivers of a This notification shall only be sent to receivers of a
subscription; it does not constitute a general-purpose subscription; it does not constitute a general-purpose
notification."; notification.";
leaf subscription-id { leaf subscription-id {
type sn:subscription-id; type sn:subscription-id;
description description
"This references the subscription which drove the notification "This references the subscription which drove the notification
to be sent."; to be sent.";
} }
leaf updates-not-sent { leaf incomplete-update {
type empty; type empty;
description description
"This is a flag which indicates that not all datastore nodes "This is a flag which indicates that not all datastore nodes
subscribed to are included with this update. In other words, subscribed to are included with this update. In other words,
the publisher has failed to fulfill its full subscription the publisher has failed to fulfill its full subscription
obligations, and despite its best efforts is providing an obligations, and despite its best efforts is providing an
incomplete set of objects."; incomplete set of objects.";
} }
anydata datastore-contents { anydata datastore-contents {
description description
skipping to change at page 46, line 22 skipping to change at page 46, line 7
"This notification contains an on-change push update. This "This notification contains an on-change push update. This
notification shall only be sent to the receivers of a notification shall only be sent to the receivers of a
subscription; it does not constitute a general-purpose subscription; it does not constitute a general-purpose
notification."; notification.";
leaf subscription-id { leaf subscription-id {
type sn:subscription-id; type sn:subscription-id;
description description
"This references the subscription which drove the notification "This references the subscription which drove the notification
to be sent."; to be sent.";
} }
leaf updates-not-sent { leaf incomplete-update {
type empty; type empty;
description description
"The presence of this object indicates not all changes which "The presence of this object indicates not all changes which
have occurred since the last update are included with this have occurred since the last update are included with this
update. In other words, the publisher has failed to update. In other words, the publisher has failed to
fulfill its full subscription obligations, for example in fulfill its full subscription obligations, for example in
cases where it was not able to keep up with a change burst."; cases where it was not able to keep up with a change burst.";
} }
anydata datastore-changes { anydata datastore-changes {
description description
skipping to change at page 47, line 4 skipping to change at page 46, line 37
ability create on an existing node, or receive a delete on a ability create on an existing node, or receive a delete on a
missing node."; missing node.";
} }
} }
augment "/sn:subscription-started" { augment "/sn:subscription-started" {
description description
"This augmentation adds many datastore specific objects to "This augmentation adds many datastore specific objects to
the notification that a subscription has started."; the notification that a subscription has started.";
uses update-policy; uses update-policy;
} }
augment "/sn:subscription-started/sn:target" { augment "/sn:subscription-started/sn:target" {
description description
"This augmentation allows the datastore to be included as part "This augmentation allows the datastore to be included as part
of the notification that a subscription has started."; of the notification that a subscription has started.";
case datastore { case datastore {
uses datastore-criteria { uses datastore-criteria {
refine "selected-content/within-subscription" { refine "selection-filter/within-subscription" {
description description
"Specifies where the selection filter, and where came from "Specifies where the selection filter, and where it came
within the subscription and then populated within this from within the subscription and then populated within this
notification. If the 'selection-filter-ref' is populated, notification. If the 'selection-filter-ref' is populated,
the filter within the subscription came from the 'filters' the filter within the subscription came from the 'filters'
container. Otherwise it is populated in-line as part of the container. Otherwise it is populated in-line as part of the
subscription itself."; subscription itself.";
} }
} }
} }
} }
augment "/sn:subscription-modified" { augment "/sn:subscription-modified" {
skipping to change at page 47, line 38 skipping to change at page 47, line 22
"This augmentation adds many datastore specific objects to "This augmentation adds many datastore specific objects to
the notification that a subscription has been modified."; the notification that a subscription has been modified.";
uses update-policy; uses update-policy;
} }
augment "/sn:subscription-modified/sn:target" { augment "/sn:subscription-modified/sn:target" {
description description
"This augmentation allows the datastore to be included as part "This augmentation allows the datastore to be included as part
of the notification that a subscription has been modified."; of the notification that a subscription has been modified.";
case datastore { case datastore {
uses datastore-criteria { uses datastore-criteria {
refine "selected-content/within-subscription" { refine "selection-filter/within-subscription" {
description description
"Specifies where the selection filter, and where came from "Specifies where the selection filter, and where it came
within the subscription and then populated within this from within the subscription and then populated within this
notification. If the 'selection-filter-ref' is populated, notification. If the 'selection-filter-ref' is populated,
the filter within the subscription came from the 'filters' the filter within the subscription came from the 'filters'
container. Otherwise it is populated in-line as part of the container. Otherwise it is populated in-line as part of the
subscription itself."; subscription itself.";
} }
} }
} }
} }
/* /*
skipping to change at page 52, line 9 skipping to change at page 52, line 5
synchronization-size synchronization-size
delete-subscription kill-subscription delete-subscription kill-subscription
---------------------- ----------------- ---------------------- -----------------
sn:no-such-subscription sn:no-such-subscription sn:no-such-subscription sn:no-such-subscription
There is one final set of transport independent RPC error elements There is one final set of transport independent RPC error elements
included in the YANG model. These are the following four yang-data included in the YANG model. These are the following four yang-data
structures for failed datastore subscriptions: structures for failed datastore subscriptions:
1. yang-data establish-subscription-error-datastore 1. yang-data establish-subscription-error-datastore
This MUST be returned if an RPC error reason has not been placed This MUST be returned if information identifying the reason for an
elsewhere within the transport portion of a failed "establish- RPC error has not been placed elsewhere within the transport
subscription" RPC response. This MUST be sent if hints on how to portion of a failed "establish-subscription" RPC response. This
overcome the RPC error are included. MUST be sent if hints are included.
2. yang-data modify-subscription-error-datastore 2. yang-data modify-subscription-error-datastore
This MUST be returned if an RPC error reason has not been placed This MUST be returned if information identifying the reason for an
elsewhere within the transport portion of a failed "modify-subscription" RPC error has not been placed elsewhere within the transport
RPC response. This MUST be sent if hints on how to overcome the RPC portion of a failed "modifiy-subscription" RPC response. This
error are included. MUST be sent if hints are included.
3. yang-data sn:delete-subscription-error 3. yang-data sn:delete-subscription-error
This MUST be returned if an RPC error reason has not been placed This MUST be returned if information identifying the reason for an
elsewhere within the transport portion of a failed "delete-subscription" RPC error has not been placed elsewhere within the transport
or "kill-subscription" RPC response. portion of a failed "delete-subscription" or "kill-subscription"
RPC response.
4. yang-data resynch-subscription-error 4. yang-data resynch-subscription-error
This MUST be returned if an RPC error reason has not been placed This MUST be returned if information identifying the reason for an
elsewhere within the transport portion of a failed "resynch- RPC error has not been placed elsewhere within the transport
subscription" RPC response. portion of a failed "resynch-subscription" RPC response.
A.2. Notifications of Failure A.2. Notifications of Failure
A subscription may be unexpectedly terminated or suspended A subscription may be unexpectedly terminated or suspended
independent of any RPC or configuration operation. In such cases, independent of any RPC or configuration operation. In such cases,
indications of such a failure MUST be provided. To accomplish this, indications of such a failure MUST be provided. To accomplish this,
the following types of error identities may be returned within the the following types of error identities may be returned within the
corresponding subscription state change notification: corresponding subscription state change notification:
subscription-terminated subscription-suspended subscription-terminated subscription-suspended
skipping to change at page 52, line 51 skipping to change at page 52, line 48
datastore-not-subscribable sn:insufficient-resources datastore-not-subscribable sn:insufficient-resources
sn:filter-unavailable period-unsupported sn:filter-unavailable period-unsupported
sn:no-such-subscription result-too-big sn:no-such-subscription result-too-big
sn:suspension-timeout synchronization-size sn:suspension-timeout synchronization-size
unchanging-selection unchanging-selection
Appendix B. Changes between revisions Appendix B. Changes between revisions
(To be removed by RFC editor prior to publication) (To be removed by RFC editor prior to publication)
v14 - v15
o Minor text fixes. Includes a fix to on-change update calculation
to cover churn when an object changes to and from a value during a
dampening period.
v13 - v14 v13 - v14
o Minor text fixes. o Minor text fixes.
v12 - v13 v12 - v13
o Hint negotiation models now show error examples. o Hint negotiation models now show error examples.
o yang-data structures for rpc errors. o yang-data structures for rpc errors.
v11 - v12 v11 - v12
 End of changes. 65 change blocks. 
128 lines changed or deleted 125 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/