Diff: draft-ietf-netconf-restconf-notif-12.txt - draft-ietf-netconf-restconf-notif-13.txt

	< 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.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/