draft-ietf-netconf-restconf-notif-12.txt   draft-ietf-netconf-restconf-notif-13.txt 
NETCONF E. Voit NETCONF E. Voit
Internet-Draft R. Rahman Internet-Draft R. Rahman
Intended status: Standards Track E. Nilsen-Nygaard Intended status: Standards Track E. Nilsen-Nygaard
Expires: July 15, 2019 Cisco Systems Expires: August 18, 2019 Cisco Systems
A. Clemm A. Clemm
Huawei Huawei
A. Bierman A. Bierman
YumaWorks YumaWorks
January 11, 2019 February 14, 2019
Dynamic subscription to YANG Events and Datastores over RESTCONF Dynamic subscription to YANG Events and Datastores over RESTCONF
draft-ietf-netconf-restconf-notif-12 draft-ietf-netconf-restconf-notif-13
Abstract Abstract
This document provides a RESTCONF binding to the dynamic subscription This document provides a RESTCONF binding to the dynamic subscription
capability of both subscribed notifications and YANG-Push. capability of both subscribed notifications and YANG-Push.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
skipping to change at page 1, line 36 skipping to change at page 1, line 36
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 July 15, 2019. This Internet-Draft will expire on August 18, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 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 15 skipping to change at page 2, line 15
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . . . 3 3. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . . . 3
3.1. Transport Connectivity . . . . . . . . . . . . . . . . . 4 3.1. Transport Connectivity . . . . . . . . . . . . . . . . . 4
3.2. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 4 3.2. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 4
3.3. RESTCONF RPCs and HTTP Status Codes . . . . . . . . . . . 4 3.3. RESTCONF RPCs and HTTP Status Codes . . . . . . . . . . . 4
3.4. Call Flow for Server-Sent Events (SSE) . . . . . . . . . 6 3.4. Call Flow for Server-Sent Events (SSE) . . . . . . . . . 7
4. QoS Treatment . . . . . . . . . . . . . . . . . . . . . . . . 8 4. QoS Treatment . . . . . . . . . . . . . . . . . . . . . . . . 9
5. Notification Messages . . . . . . . . . . . . . . . . . . . . 9 5. Notification Messages . . . . . . . . . . . . . . . . . . . . 10
6. YANG Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 9 6. YANG Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 10
7. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 9 7. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 10
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 9. Security Considerations . . . . . . . . . . . . . . . . . . . 12
10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 13
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 13
11.1. Normative References . . . . . . . . . . . . . . . . . . 12 11.1. Normative References . . . . . . . . . . . . . . . . . . 13
11.2. Informative References . . . . . . . . . . . . . . . . . 14 11.2. Informative References . . . . . . . . . . . . . . . . . 15
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 14 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 15
A.1. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 15 A.1. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 16
A.1.1. Establishing Dynamic Subscriptions . . . . . . . . . 15 A.1.1. Establishing Dynamic Subscriptions . . . . . . . . . 16
A.1.2. Modifying Dynamic Subscriptions . . . . . . . . . . . 17 A.1.2. Modifying Dynamic Subscriptions . . . . . . . . . . . 18
A.1.3. Deleting Dynamic Subscriptions . . . . . . . . . . . 19 A.1.3. Deleting Dynamic Subscriptions . . . . . . . . . . . 20
A.2. Subscription State Notifications . . . . . . . . . . . . 20 A.2. Subscription State Notifications . . . . . . . . . . . . 21
A.2.1. subscription-modified . . . . . . . . . . . . . . . . 20 A.2.1. subscription-modified . . . . . . . . . . . . . . . . 21
A.2.2. subscription-completed, subscription-resumed, and A.2.2. subscription-completed, subscription-resumed, and
replay-complete . . . . . . . . . . . . . . . . . . . 21 replay-complete . . . . . . . . . . . . . . . . . . . 22
A.2.3. subscription-terminated and subscription-suspended . 21 A.2.3. subscription-terminated and subscription-suspended . 22
A.3. Filter Example . . . . . . . . . . . . . . . . . . . . . 21 A.3. Filter Example . . . . . . . . . . . . . . . . . . . . . 22
Appendix B. Changes between revisions . . . . . . . . . . . . . 23 Appendix B. Changes between revisions . . . . . . . . . . . . . 24
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 27
1. Introduction 1. Introduction
Mechanisms to support event subscription and push are defined in Mechanisms to support event subscription and push are defined in
[I-D.draft-ietf-netconf-subscribed-notifications]. Enhancements to [I-D.draft-ietf-netconf-subscribed-notifications]. Enhancements to
[I-D.draft-ietf-netconf-subscribed-notifications] which enable YANG [I-D.draft-ietf-netconf-subscribed-notifications] which enable YANG
datastore subscription and push are defined in datastore subscription and push are defined in
[I-D.ietf-netconf-yang-push]. This document provides a transport [I-D.ietf-netconf-yang-push]. This document provides a transport
specification for dynamic subscriptions over RESTCONF [RFC8040]. specification for dynamic subscriptions over RESTCONF [RFC8040].
Driving these requirements is [RFC7923]. Driving these requirements is [RFC7923].
skipping to change at page 5, line 11 skipping to change at page 5, line 11
indicated in [I-D.draft-ietf-netconf-subscribed-notifications] indicated in [I-D.draft-ietf-netconf-subscribed-notifications]
Section 2.4.6 or [I-D.ietf-netconf-yang-push] Appendix A, this will Section 2.4.6 or [I-D.ietf-netconf-yang-push] Appendix A, this will
be indicated by "406" status code transported in the HTTP response. be indicated by "406" status code transported in the HTTP response.
When a "406" status code is returned, the RPC reply MUST include an When a "406" status code is returned, the RPC reply MUST include an
"rpc-error" element per [RFC8040] Section 7.1 with the following "rpc-error" element per [RFC8040] Section 7.1 with the following
parameter values: parameter values:
o an "error-type" node of "application". o an "error-type" node of "application".
o an "error-tag" node of "operation-failed". o an "error-tag" node with the value being a string that corresponds
to an identity associated with the error. This "error-tag" will
come from one of two places. Either it will correspond to the
error identities within
[I-D.draft-ietf-netconf-subscribed-notifications] section 2.4.6
for general subscription errors:
error identity uses error-tag
---------------------- --------------
dscp-unavailable invalid-value
encoding-unsupported invalid-value
filter-unsupported invalid-value
insufficient-resources resource-denied
no-such-subscription invalid-value
replay-unsupported operation-not-supported
Or this "error-tag" will correspond to the error identities within
[I-D.ietf-netconf-yang-push] Appendix A.1 for subscription errors
specific to YANG datastores:
error identity uses error-tag
---------------------- --------------
cant-exclude operation-not-supported
datastore-not-subscribable invalid-value
no-such-subscription-resync invalid-value
on-change-unsupported operation-not-supported
on-change-sync-unsupported operation-not-supported
period-unsupported invalid-value
update-too-big too-big
sync-too-big too-big
unchanging-selection operation-failed
o an "error-app-tag" node with the value being a string that o an "error-app-tag" node with the value being a string that
corresponds to an identity associated with the error, as defined corresponds to an identity associated with the error, as defined
in [I-D.draft-ietf-netconf-subscribed-notifications] section 2.4.6 in [I-D.draft-ietf-netconf-subscribed-notifications] section 2.4.6
for general subscriptions, and [I-D.ietf-netconf-yang-push] for general subscriptions, and [I-D.ietf-netconf-yang-push]
Appendix A.1, for datastore subscriptions. The tag to use depends Appendix A.1, for datastore subscriptions. The tag to use depends
on the RPC for which the error occurred. Viable errors for on the RPC for which the error occurred. Viable errors for
different RPCs are as follows: different RPCs are as follows:
RPC select an identity with a base RPC select an identity with a base
---------------------- ------------------------------ ---------------------- ------------------------------
establish-subscription establish-subscription-error establish-subscription establish-subscription-error
modify-subscription modify-subscription-error modify-subscription modify-subscription-error
delete-subscription delete-subscription-error delete-subscription delete-subscription-error
kill-subscription delete-subscription-error kill-subscription delete-subscription-error
resync-subscription resync-subscription-error resync-subscription resync-subscription-error
Each error identity will be inserted as the "error-app-tag" using Each error identity will be inserted as the "error-app-tag" using
JSON encoding following the form <modulename>:<identityname>. An JSON encoding following the form <modulename>:<identityname>. An
example of such as valid encoding would be "ietf-subscribed- example of such a valid encoding would be "ietf-subscribed-
notifications:no-such-subscription". notifications:no-such-subscription".
In case of error responses to an "establish-subscription" or "modify- In case of error responses to an "establish-subscription" or "modify-
subscription" request there is the option of including an "error- subscription" request there is the option of including an "error-
info" node. This node may contain hints for parameter settings that info" node. This node may contain hints for parameter settings that
might lead to successful RPC requests in the future. Following are might lead to successful RPC requests in the future. Following are
the yang-data structures which may be returned: the yang-data structures which may be returned:
establish-subscription returns hints in yang-data structure establish-subscription returns hints in yang-data structure
---------------------- ------------------------------------ ---------------------- ------------------------------------
skipping to change at page 17, line 11 skipping to change at page 18, line 11
error response. For instance, if the "dscp" value of 10 asserted by error response. For instance, if the "dscp" value of 10 asserted by
the subscriber in Figure 3 proved unacceptable, the publisher may the subscriber in Figure 3 proved unacceptable, the publisher may
have returned: have returned:
HTTP status code - 406 HTTP status code - 406
{ "ietf-restconf:errors" : { { "ietf-restconf:errors" : {
"error" : [ "error" : [
{ {
"error-type": "application", "error-type": "application",
"error-tag": "operation-failed", "error-tag": "invalid-value",
"error-severity": "error", "error-severity": "error",
"error-app-tag": "error-app-tag":
"ietf-subscribed-notifications:dscp-unavailable" "ietf-subscribed-notifications:dscp-unavailable"
} }
] ]
} }
} }
Figure 6: an unsuccessful establish subscription Figure 6: an unsuccessful establish subscription
skipping to change at page 19, line 14 skipping to change at page 20, line 14
of the proposed changes, the publisher sends an RPC error response of the proposed changes, the publisher sends an RPC error response
(e). The following is an example RPC error response for (e) which (e). The following is an example RPC error response for (e) which
includes a hint. This hint is an alternative time period value which includes a hint. This hint is an alternative time period value which
might have resulted in a successful modification: might have resulted in a successful modification:
HTTP status code - 406 HTTP status code - 406
{ "ietf-restconf:errors" : { { "ietf-restconf:errors" : {
"error" : [ "error" : [
"error-type": "application", "error-type": "application",
"error-tag": "operation-failed", "error-tag": "invalid-value",
"error-severity": "error", "error-severity": "error",
"error-app-tag": "ietf-yang-push:period-unsupported", "error-app-tag": "ietf-yang-push:period-unsupported",
"error-info": { "error-info": {
"ietf-yang-push": "ietf-yang-push":
"modify-subscription-datastore-error-info": { "modify-subscription-datastore-error-info": {
"period-hint": "3000" "period-hint": "3000"
} }
} }
] ]
} }
skipping to change at page 20, line 13 skipping to change at page 21, line 13
shows a valid response for existing valid subscription identifier, shows a valid response for existing valid subscription identifier,
but that subscription identifier was created on a different transport but that subscription identifier was created on a different transport
session: session:
HTTP status code - 406 HTTP status code - 406
{ {
"ietf-restconf:errors" : { "ietf-restconf:errors" : {
"error" : [ "error" : [
"error-type": "application", "error-type": "application",
"error-tag": "operation-failed", "error-tag": "invalid-value",
"error-severity": "error", "error-severity": "error",
"error-app-tag": "error-app-tag":
"ietf-subscribed-notifications:no-such-subscription" "ietf-subscribed-notifications:no-such-subscription"
] ]
} }
} }
Figure 11: Unsuccessful delete subscription Figure 11: Unsuccessful delete subscription
A.2. Subscription State Notifications A.2. Subscription State Notifications
skipping to change at page 23, line 24 skipping to change at page 24, line 24
} }
Figure 17 Figure 17
For more examples of subtree filters, see [RFC6241], section 6.4. For more examples of subtree filters, see [RFC6241], section 6.4.
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)
v12 - v13
o Enhanced "error-tag" values based on SN review.
v11 - v12 v11 - v12
o Added text in 3.2 for expected behavior when ietf-restconf- o Added text in 3.2 for expected behavior when ietf-restconf-
monitoring.yang is also supported. monitoring.yang is also supported.
o Added section 2 to the reference to draft-ietf-netconf-nmda- o Added section 2 to the reference to draft-ietf-netconf-nmda-
restconf. restconf.
o Replaced kill-subscription-error by delete-subscription-error in o Replaced kill-subscription-error by delete-subscription-error in
section 3.3. section 3.3.
 End of changes. 12 change blocks. 
32 lines changed or deleted 66 lines changed or added

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