< draft-ietf-netconf-restconf-notif-11.txt		draft-ietf-netconf-restconf-notif-12.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: June 16, 2019 Cisco Systems		Expires: July 15, 2019 Cisco Systems
	A. Clemm		A. Clemm
	Huawei		Huawei
	A. Bierman		A. Bierman
	YumaWorks		YumaWorks
	December 13, 2018		January 11, 2019
	Dynamic subscription to YANG Events and Datastores over RESTCONF		Dynamic subscription to YANG Events and Datastores over RESTCONF
	draft-ietf-netconf-restconf-notif-11		draft-ietf-netconf-restconf-notif-12
	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 June 16, 2019.		This Internet-Draft will expire on July 15, 2019.
	Copyright Notice		Copyright Notice
	Copyright (c) 2018 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
	carefully, as they describe your rights and restrictions with respect		carefully, as they describe your rights and restrictions with respect
	to this document. Code Components extracted from this document must		to this document. Code Components extracted from this document must
	include Simplified BSD License text as described in Section 4.e of		include Simplified BSD License text as described in Section 4.e of
	the Trust Legal Provisions and are provided without warranty as		the Trust Legal Provisions and are provided without warranty as
	skipping to change at page 2, line 17 ¶		skipping to change at page 2, line 17 ¶
	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) . . . . . . . . . 6
	4. QoS Treatment . . . . . . . . . . . . . . . . . . . . . . . . 8		4. QoS Treatment . . . . . . . . . . . . . . . . . . . . . . . . 8
	5. Notification Messages . . . . . . . . . . . . . . . . . . . . 8		5. Notification Messages . . . . . . . . . . . . . . . . . . . . 9
	6. YANG Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 8		6. YANG Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 9
	7. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 9		7. YANG module . . . . . . . . . . . . . . . . . . . . . . . . . 9
	8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10		8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
	9. Security Considerations . . . . . . . . . . . . . . . . . . . 11		9. Security Considerations . . . . . . . . . . . . . . . . . . . 11
	10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11		10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12
	11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12		11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12
	11.1. Normative References . . . . . . . . . . . . . . . . . . 12		11.1. Normative References . . . . . . . . . . . . . . . . . . 12
	11.2. Informative References . . . . . . . . . . . . . . . . . 13		11.2. Informative References . . . . . . . . . . . . . . . . . 14
	Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 14		Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 14
	A.1. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 14		A.1. Dynamic Subscriptions . . . . . . . . . . . . . . . . . . 15
	A.1.1. Establishing Dynamic Subscriptions . . . . . . . . . 14		A.1.1. Establishing Dynamic Subscriptions . . . . . . . . . 15
	A.1.2. Modifying Dynamic Subscriptions . . . . . . . . . . . 17		A.1.2. Modifying Dynamic Subscriptions . . . . . . . . . . . 17
	A.1.3. Deleting Dynamic Subscriptions . . . . . . . . . . . 18		A.1.3. Deleting Dynamic Subscriptions . . . . . . . . . . . 19
	A.2. Subscription State Notifications . . . . . . . . . . . . 19		A.2. Subscription State Notifications . . . . . . . . . . . . 20
	A.2.1. subscription-modified . . . . . . . . . . . . . . . . 19		A.2.1. subscription-modified . . . . . . . . . . . . . . . . 20
	A.2.2. subscription-completed, subscription-resumed, and		A.2.2. subscription-completed, subscription-resumed, and
	replay-complete . . . . . . . . . . . . . . . . . . . 20		replay-complete . . . . . . . . . . . . . . . . . . . 21
	A.2.3. subscription-terminated and subscription-suspended . 20		A.2.3. subscription-terminated and subscription-suspended . 21
	A.3. Filter Example . . . . . . . . . . . . . . . . . . . . . 21		A.3. Filter Example . . . . . . . . . . . . . . . . . . . . . 21
	Appendix B. Changes between revisions . . . . . . . . . . . . . 22		Appendix B. Changes between revisions . . . . . . . . . . . . . 23
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 26
	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 4, line 33 ¶		skipping to change at page 4, line 33 ¶
	then attempt to re-establish the dynamic subscription by using the		then attempt to re-establish the dynamic subscription by using the
	procedure described in Section 3.		procedure described in Section 3.
	3.2. Discovery		3.2. Discovery
	Subscribers can learn what event streams a RESTCONF server supports		Subscribers can learn what event streams a RESTCONF server supports
	by querying the "streams" container of ietf-subscribed-		by querying the "streams" container of ietf-subscribed-
	notification.yang in		notification.yang in
	[I-D.draft-ietf-netconf-subscribed-notifications]. Support for the		[I-D.draft-ietf-netconf-subscribed-notifications]. Support for the
	"streams" container of ietf-restconf-monitoring.yang in [RFC8040] is		"streams" container of ietf-restconf-monitoring.yang in [RFC8040] is
	not required.		not required. If it is supported, the event streams which are in the
			"streams" container of ietf-subscribed-notifications.yang SHOULD also
			be in the "streams" container of ietf-restconf-monitoring.yang.
	Subscribers can learn what datastores a RESTCONF server supports by		Subscribers can learn what datastores a RESTCONF server supports by
	following [I-D.draft-ietf-netconf-nmda-restconf].		following Section 2 of [I-D.draft-ietf-netconf-nmda-restconf].
	3.3. RESTCONF RPCs and HTTP Status Codes		3.3. RESTCONF RPCs and HTTP Status Codes
	Specific HTTP responses codes as defined in [RFC7231] section 6 will		Specific HTTP responses codes as defined in [RFC7231] section 6 will
	indicate the result of RESTCONF RPC requests with publisher. An HTTP		indicate the result of RESTCONF RPC requests with publisher. An HTTP
	status code of 200 is the proper response to any successful RPC		status code of 200 is the proper response to any successful RPC
	defined within [I-D.draft-ietf-netconf-subscribed-notifications] or		defined within [I-D.draft-ietf-netconf-subscribed-notifications] or
	[I-D.ietf-netconf-yang-push].		[I-D.ietf-netconf-yang-push].
	If a publisher fails to serve the RPC request for one of the reasons		If a publisher fails to serve the RPC request for one of the reasons
	skipping to change at page 5, line 26 ¶		skipping to change at page 5, line 26 ¶
	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 kill-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 as 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
	skipping to change at page 7, line 34 ¶		skipping to change at page 7, line 34 ¶
	| | HTTP 200 OK| |		| | HTTP 200 OK| |
	|<---------------------------------------------| |		|<---------------------------------------------| |
	| | SSE (subscription-modified)|		| | SSE (subscription-modified)|
	| |<------------------------------------------(c)|		| |<------------------------------------------(c)|
	| | SSE (notif-message)|		| | SSE (notif-message)|
	| |<---------------------------------------------|		| |<---------------------------------------------|
	| RESTCONF POST (RPC:delete-subscription) | |		| RESTCONF POST (RPC:delete-subscription) | |
	|--------------------------------------------->| |		|--------------------------------------------->| |
	| | HTTP 200 OK| |		| | HTTP 200 OK| |
	|<---------------------------------------------| |		|<---------------------------------------------| |
	| | |		| | | |
	| |		| | | |
			(a) (b) (a) (b)
	Figure 1: Dynamic with server-sent events		Figure 1: Dynamic with server-sent events
	Additional requirements for dynamic subscriptions over SSE include:		Additional requirements for dynamic subscriptions over SSE include:
	o All subscription state notifications from a publisher MUST be		o All subscription state notifications from a publisher MUST be
	returned in a separate SSE message used by the subscription to		returned in a separate SSE message used by the subscription to
	which the state change refers.		which the state change refers.
	o Subscription RPCs MUST NOT use the connection currently providing		o Subscription RPCs MUST NOT use the connection currently providing
	notification messages for that subscription.		notification messages for that subscription.
	o In addition to an RPC response for a "modify-subscription" RPC		o In addition to an RPC response for a "modify-subscription" RPC
	traveling over (a), a "subscription-modified" state change		traveling over (a), a "subscription-modified" state change
	notification must be sent within (b). This allows the receiver to		notification MUST be sent within (b). This allows the receiver to
	know exactly when the new terms of the subscription have been		know exactly when the new terms of the subscription have been
	applied to the notification messages. See arrow (c).		applied to the notification messages. See arrow (c).
	o RPCs modify-subscription, resync-subscription and delete-		o In addition to any required access permissions (e.g., NACM), RPCs
	subscription can only be done by the same RESTCONF username		modify-subscription, resync-subscription and delete-subscription
	[RFC8040] who did the establish-subscription, or by a RESTCONF		SHOULD only be allowed by the same RESTCONF username [RFC8040]
	username with the required administrative permissions. The latter		which invoked establish-subscription.
	also has access to the kill-subscription RPC.
			o The kill-subscription RPC can be invoked by any RESTCONF username
			with the required administrative permissions.
	A publisher MUST terminate a subscription in the following cases:		A publisher MUST terminate a subscription in the following cases:
	o Receipt of a "delete-subscription" or a "kill-subscription" RPC		o Receipt of a "delete-subscription" or a "kill-subscription" RPC
	for that subscription.		for that subscription.
	o Loss of TLS heartbeat		o Loss of TLS heartbeat
	A publisher MAY terminate a subscription at any time as stated in		A publisher MAY terminate a subscription at any time as stated in
	[I-D.draft-ietf-netconf-subscribed-notifications] Section 1.3		[I-D.draft-ietf-netconf-subscribed-notifications] Section 1.3
	skipping to change at page 8, line 31 ¶		skipping to change at page 8, line 35 ¶
	4. QoS Treatment		4. QoS Treatment
	To meet subscription quality of service promises, the publisher MUST		To meet subscription quality of service promises, the publisher MUST
	take any existing subscription "dscp" and apply it to the DSCP		take any existing subscription "dscp" and apply it to the DSCP
	marking in the IP header.		marking in the IP header.
	In addition, where HTTP2 transport is available to a notification		In addition, where HTTP2 transport is available to a notification
	message queued for transport to a receiver, the publisher MUST:		message queued for transport to a receiver, the publisher MUST:
	o take any existing subscription "priority", as specified by the		o take any existing subscription "priority", as specified by the
	"dscp" leaf node in		"weighting" leaf node in
	[I-D.draft-ietf-netconf-subscribed-notifications], and copy it		[I-D.draft-ietf-netconf-subscribed-notifications], and copy it
	into the HTTP2 stream priority, [RFC7540] section 5.3, and		into the HTTP2 stream weight, [RFC7540] section 5.3, and
	o take any existing subscription "dependency", as specified by the		o take any existing subscription "dependency", as specified by the
	"dependency" leaf node in		"dependency" leaf node in
	[I-D.draft-ietf-netconf-subscribed-notifications], and use the		[I-D.draft-ietf-netconf-subscribed-notifications], and use the
	HTTP2 stream for the parent subscription as the HTTP2 stream		HTTP2 stream for the parent subscription as the HTTP2 stream
	dependency, [RFC7540] section 5.3.1, of the dependent		dependency, [RFC7540] section 5.3.1, of the dependent
	subscription.		subscription.
			o set the exclusive flag, [RFC7540] section 5.3.1, to 0.
	5. Notification Messages		5. Notification Messages
	Notification messages transported over RESTCONF will be encoded		Notification messages transported over RESTCONF will be encoded
	according to [RFC8040], section 6.4.		according to [RFC8040], section 6.4.
	6. YANG Tree		6. YANG Tree
	The YANG model defined in Section 7 has one leaf augmented into four		The YANG model defined in Section 7 has one leaf augmented into three
	places of [I-D.draft-ietf-netconf-subscribed-notifications], plus two		places of [I-D.draft-ietf-netconf-subscribed-notifications].
	identities. As the resulting full tree is large, it will only be
	inserted at later stages of this document.		module: ietf-restconf-subscribed-notifications
			augment /sn:establish-subscription/sn:output:
			+--ro uri? inet:uri
			augment /sn:subscriptions/sn:subscription:
			+--ro uri? inet:uri
			augment /sn:subscription-modified:
			+--ro uri? inet:uri
	7. YANG module		7. YANG module
	This module references		This module references
	[I-D.draft-ietf-netconf-subscribed-notifications].		[I-D.draft-ietf-netconf-subscribed-notifications].
	<CODE BEGINS> file "ietf-restconf-subscribed-notifications@2018-10-19.yang"		<CODE BEGINS> file
			"ietf-restconf-subscribed-notifications@2019-01-11.yang"
	module ietf-restconf-subscribed-notifications {		module ietf-restconf-subscribed-notifications {
	yang-version 1.1;		yang-version 1.1;
	namespace		namespace
	"urn:ietf:params:xml:ns:yang:ietf-restconf-subscribed-notifications";		"urn:ietf:params:xml:ns:yang:" +
			"ietf-restconf-subscribed-notifications";
	prefix rsn;		prefix rsn;
	import ietf-subscribed-notifications {		import ietf-subscribed-notifications {
	prefix sn;		prefix sn;
	}		}
	import ietf-inet-types {		import ietf-inet-types {
	prefix inet;		prefix inet;
	}		}
	skipping to change at page 9, line 41 ¶		skipping to change at page 10, line 13 ¶
	<mailto:evoit@cisco.com>		<mailto:evoit@cisco.com>
	Editor: Alexander Clemm		Editor: Alexander Clemm
	<mailto:ludwig@clemm.org>		<mailto:ludwig@clemm.org>
	Editor: Reshad Rahman		Editor: Reshad Rahman
	<mailto:rrahman@cisco.com>";		<mailto:rrahman@cisco.com>";
	description		description
	"Defines RESTCONF as a supported transport for subscribed		"Defines RESTCONF as a supported transport for subscribed
	event notifications.		event notifications.
	Copyright (c) 2018 IETF Trust and the persons identified as authors		Copyright (c) 2019 IETF Trust and the persons identified as authors
	of the code. All rights reserved.		of the code. All rights reserved.
	Redistribution and use in source and binary forms, with or without		Redistribution and use in source and binary forms, with or without
	modification, is permitted pursuant to, and subject to the license		modification, is permitted pursuant to, and subject to the license
	terms contained in, the Simplified BSD License set forth in Section		terms contained in, the Simplified BSD License set forth in Section
	4.c of the IETF Trust's Legal Provisions Relating to IETF Documents		4.c of the IETF Trust's Legal Provisions Relating to IETF Documents
	(https://trustee.ietf.org/license-info).		(https://trustee.ietf.org/license-info).
	This version of this YANG module is part of RFC XXXX; see the RFC		This version of this YANG module is part of RFC XXXX; see the RFC
	itself for full legal notices.";		itself for full legal notices.";
	revision 2018-10-19 {		revision 2019-01-11 {
	description		description
	"Initial version";		"Initial version";
	reference		reference
	"RFC XXXX: RESTCONF Transport for Event Notifications";		"RFC XXXX: RESTCONF Transport for Event Notifications";
	}		}
	grouping uri {		grouping uri {
	description		description
	"Provides a reusable description of a URI.";		"Provides a reusable description of a URI.";
	leaf uri {		leaf uri {
	skipping to change at page 10, line 40 ¶		skipping to change at page 11, line 12 ¶
	augment "/sn:subscriptions/sn:subscription" {		augment "/sn:subscriptions/sn:subscription" {
	description		description
	"This augmentation allows RESTCONF specific parameters to be		"This augmentation allows RESTCONF specific parameters to be
	exposed for a subscription.";		exposed for a subscription.";
	uses uri;		uses uri;
	}		}
	augment "/sn:subscription-modified" {		augment "/sn:subscription-modified" {
	description		description
	"This augmentation allows RESTCONF specific parameters to be included		"This augmentation allows RESTCONF specific parameters to be
	part of the notification that a subscription has been modified.";		included as part of the notification that a subscription has been
			modified.";
	uses uri;		uses uri;
	}		}
	}		}
	<CODE ENDS>		<CODE ENDS>
	8. IANA Considerations		8. IANA Considerations
	This document registers the following namespace URI in the "IETF XML		This document registers the following namespace URI in the "IETF XML
	Registry" [RFC3688]:		Registry" [RFC3688]:
	skipping to change at page 11, line 42 ¶		skipping to change at page 12, line 14 ¶
	or notification) to this data nodes. These are the subtrees and data		or notification) to this data nodes. These are the subtrees and data
	nodes and their sensitivity/vulnerability:		nodes and their sensitivity/vulnerability:
	Container: "/subscriptions"		Container: "/subscriptions"
	o "uri": leaf will show where subscribed resources might be located		o "uri": leaf will show where subscribed resources might be located
	on a publisher. Access control must be set so that only someone		on a publisher. Access control must be set so that only someone
	with proper access permissions, and perhaps even HTTP session has		with proper access permissions, and perhaps even HTTP session has
	the ability to access this resource.		the ability to access this resource.
			The subscription URI is implementation specific and is encrypted via
			the use of TLS. Therefore, even if an attacker succeeds in guessing
			the subscription URI, a RESTCONF username [RFC8040] with the required
			administrative permissions must be used to be able to access or
			modify that subscription.
	10. Acknowledgments		10. Acknowledgments
	We wish to acknowledge the helpful contributions, comments, and		We wish to acknowledge the helpful contributions, comments, and
	suggestions that were received from: Ambika Prasad Tripathy, Alberto		suggestions that were received from: Ambika Prasad Tripathy, Alberto
	Gonzalez Prieto, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent		Gonzalez Prieto, Susan Hares, Tim Jenkins, Balazs Lengyel, Kent
	Watsen, Michael Scharf, Guangying Zheng, Martin Bjorklund and Qin Wu.		Watsen, Michael Scharf, Guangying Zheng, Martin Bjorklund, Qin Wu and
			Robert Wilton.
	11. References		11. References
	11.1. Normative References		11.1. Normative References
	[I-D.draft-ietf-netconf-subscribed-notifications]		[I-D.draft-ietf-netconf-subscribed-notifications]
	Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A.,		Voit, E., Clemm, A., Gonzalez Prieto, A., Tripathy, A.,
	and E. Nilsen-Nygaard, "Custom Subscription to Event		and E. Nilsen-Nygaard, "Custom Subscription to Event
	Streams", draft-ietf-netconf-subscribed-notifications-13		Streams", draft-ietf-netconf-subscribed-notifications-21
	(work in progress), April 2018.		(work in progress), January 2019.
	[I-D.ietf-netconf-yang-push]		[I-D.ietf-netconf-yang-push]
	Clemm, A., Voit, E., Gonzalez Prieto, A., Prasad Tripathy,		Clemm, A., Voit, E., Gonzalez Prieto, A., Prasad Tripathy,
	A., Nilsen-Nygaard, E., Bierman, A., and B. Lengyel,		A., Nilsen-Nygaard, E., Bierman, A., and B. Lengyel,
	"Subscribing to YANG datastore push updates", March 2017,		"Subscribing to YANG datastore push updates", draft-ietf-
			netconf-yang-push-20 (work in progress), October 2018,
	<https://datatracker.ietf.org/doc/		<https://datatracker.ietf.org/doc/
	draft-ietf-netconf-yang-push/>.		draft-ietf-netconf-yang-push/>.
	[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate		[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
	Requirement Levels", BCP 14, RFC 2119,		Requirement Levels", BCP 14, RFC 2119,
	DOI 10.17487/RFC2119, March 1997,		DOI 10.17487/RFC2119, March 1997,
	<https://www.rfc-editor.org/info/rfc2119>.		<https://www.rfc-editor.org/info/rfc2119>.
	[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,		[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
	DOI 10.17487/RFC3688, January 2004,		DOI 10.17487/RFC3688, January 2004,
	<https://www.rfc-editor.org/info/rfc3688>.		<https://www.rfc-editor.org/info/rfc3688>.
	[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security		[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
	(TLS) Protocol Version 1.2", RFC 5246,		(TLS) Protocol Version 1.2", RFC 5246,
	DOI 10.17487/RFC5246, August 2008,		DOI 10.17487/RFC5246, August 2008,
	<https://www.rfc-editor.org/info/rfc5246>.		<https://www.rfc-editor.org/info/rfc5246>.
	[RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event
	Notifications", RFC 5277, DOI 10.17487/RFC5277, July 2008,
	<https://www.rfc-editor.org/info/rfc5277>.
	[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for		[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
	the Network Configuration Protocol (NETCONF)", RFC 6020,		the Network Configuration Protocol (NETCONF)", RFC 6020,
	DOI 10.17487/RFC6020, October 2010,		DOI 10.17487/RFC6020, October 2010,
	<https://www.rfc-editor.org/info/rfc6020>.		<https://www.rfc-editor.org/info/rfc6020>.
	[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,		[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
	and A. Bierman, Ed., "Network Configuration Protocol		and A. Bierman, Ed., "Network Configuration Protocol
	(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,		(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
	<https://www.rfc-editor.org/info/rfc6241>.		<https://www.rfc-editor.org/info/rfc6241>.
	[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure		[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
	Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,		Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
	<https://www.rfc-editor.org/info/rfc6242>.		<https://www.rfc-editor.org/info/rfc6242>.
	[RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport		[RFC6520] Seggelmann, R., Tuexen, M., and M. Williams, "Transport
	Layer Security (TLS) and Datagram Transport Layer Security		Layer Security (TLS) and Datagram Transport Layer Security
	(DTLS) Heartbeat Extension", RFC 6520,		(DTLS) Heartbeat Extension", RFC 6520,
	DOI 10.17487/RFC6520, February 2012,		DOI 10.17487/RFC6520, February 2012,
	<https://www.rfc-editor.org/info/rfc6520>.		<https://www.rfc-editor.org/info/rfc6520>.
	[RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
	Protocol (HTTP/1.1): Message Syntax and Routing",
	RFC 7230, DOI 10.17487/RFC7230, June 2014,
	<https://www.rfc-editor.org/info/rfc7230>.
	[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext		[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
	Transfer Protocol Version 2 (HTTP/2)", RFC 7540,		Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
	DOI 10.17487/RFC7540, May 2015,		DOI 10.17487/RFC7540, May 2015,
	<https://www.rfc-editor.org/info/rfc7540>.		<https://www.rfc-editor.org/info/rfc7540>.
	[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF		[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
	Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,		Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
	<https://www.rfc-editor.org/info/rfc8040>.		<https://www.rfc-editor.org/info/rfc8040>.
	[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,		[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
	skipping to change at page 15, line 38 ¶		skipping to change at page 16, line 5 ¶
	|<------------------------------|		|<------------------------------|
	| HTTP 200 OK,notif-mesg (id#23)|		| HTTP 200 OK,notif-mesg (id#23)|
	|<------------------------------|		|<------------------------------|
	| |		| |
	Figure 2: Multiple subscriptions over RESTCONF/HTTP		Figure 2: Multiple subscriptions over RESTCONF/HTTP
	To provide examples of the information being transported, example		To provide examples of the information being transported, example
	messages for interactions in Figure 2 are detailed below:		messages for interactions in Figure 2 are detailed below:
	POST /restconf/operations/ietf-subscribed-notifications:establish-subscription		POST /restconf/operations
			/ietf-subscribed-notifications:establish-subscription
	{		{
	"ietf-subscribed-notifications:input": {		"ietf-subscribed-notifications:input": {
	"stream": "NETCONF",		"stream-xpath-filter": "/example-module:foo/",
	"stream-xpath-filter": "/example-module:foo/",		"stream": "NETCONF",
	"dscp": "10"		"dscp": "10"
			}
	}		}
	}
	Figure 3: establish-subscription request (a)		Figure 3: establish-subscription request (a)
	As publisher was able to fully satisfy the request, the publisher		As publisher was able to fully satisfy the request, the publisher
	sends the subscription identifier of the accepted subscription, and		sends the subscription identifier of the accepted subscription, and
	the URI:		the URI:
	HTTP status code - 200		HTTP status code - 200
	{		{
	skipping to change at page 18, line 5 ¶		skipping to change at page 18, line 34 ¶
	| |		| |
	Figure 7: Interaction model for successful subscription modification		Figure 7: Interaction model for successful subscription modification
	If the subscription being modified in Figure 7 is a datastore		If the subscription being modified in Figure 7 is a datastore
	subscription as per [I-D.ietf-netconf-yang-push], the modification		subscription as per [I-D.ietf-netconf-yang-push], the modification
	request made in (d) may look like that shown in Figure 8. As can be		request made in (d) may look like that shown in Figure 8. As can be
	seen, the modifications being attempted are the application of a new		seen, the modifications being attempted are the application of a new
	xpath filter as well as the setting of a new periodic time interval.		xpath filter as well as the setting of a new periodic time interval.
	POST /restconf/operations/ietf-subscribed-notifications:modify-subscription		POST /restconf/operations
			/ietf-subscribed-notifications:modify-subscription
	{		{
	"ietf-subscribed-notifications:input": {		"ietf-subscribed-notifications:input": {
	"id": "23",		"id": "23",
	"ietf-yang-push:datastore-xpath-filter": "/example-module:foo/example-module:bar",		"ietf-yang-push:datastore-xpath-filter":
	"ietf-yang-push:periodic": {		"/example-module:foo/example-module:bar",
	"ietf-yang-push:period": "500"		"ietf-yang-push:periodic": {
	}		"ietf-yang-push:period": "500"
	}		}
	}		}
			}
	Figure 8: Subscription modification request (c)		Figure 8: Subscription modification request (c)
	If the publisher can satisfy both changes, the publisher sends a		If the publisher can satisfy both changes, the publisher sends a
	positive result for the RPC. If the publisher cannot satisfy either		positive result for the RPC. If the publisher cannot satisfy either
	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:
	skipping to change at page 19, line 5 ¶		skipping to change at page 19, line 34 ¶
	}		}
	}		}
	Figure 9: Modify subscription failure with Hint (e)		Figure 9: Modify subscription failure with Hint (e)
	A.1.3. Deleting Dynamic Subscriptions		A.1.3. Deleting Dynamic Subscriptions
	The following demonstrates deleting a subscription. This		The following demonstrates deleting a subscription. This
	subscription may have been to either a stream or a datastore.		subscription may have been to either a stream or a datastore.
	POST /restconf/operations/ietf-subscribed-notifications:delete-subscription		POST /restconf/operations
			/ietf-subscribed-notifications:delete-subscription
	{		{
	"delete-subscription": {		"delete-subscription": {
	"id": "22"		"id": "22"
	}		}
	}		}
	Figure 10: Delete subscription		Figure 10: Delete subscription
	If the publisher can satisfy the request, the publisher replies with		If the publisher can satisfy the request, the publisher replies with
	success to the RPC request.		success to the RPC request.
	If the publisher cannot satisfy the request, the publisher sends an		If the publisher cannot satisfy the request, the publisher sends an
	error-rpc element indicating the modification didn't work. Figure 11		error-rpc element indicating the modification didn't work. Figure 11
	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
	skipping to change at page 22, line 5 ¶		skipping to change at page 22, line 24 ¶
	Figure 15: RFC 8347 (VRRP) - Example Notification		Figure 15: RFC 8347 (VRRP) - Example Notification
	Suppose a subscriber wanted to establish a subscription which only		Suppose a subscriber wanted to establish a subscription which only
	passes instances of event records where there is a "checksum-error"		passes instances of event records where there is a "checksum-error"
	as part of a VRRP protocol event. Also assume the publisher places		as part of a VRRP protocol event. Also assume the publisher places
	such event records into the NETCONF stream. To get a continuous		such event records into the NETCONF stream. To get a continuous
	series of matching event records, the subscriber might request the		series of matching event records, the subscriber might request the
	application of an XPath filter against the NETCONF stream. An		application of an XPath filter against the NETCONF stream. An
	"establish-subscription" RPC to meet this objective might be:		"establish-subscription" RPC to meet this objective might be:
	POST /restconf/operations/ietf-subscribed-notifications:establish-subscription		POST /restconf/operations
	{		/ietf-subscribed-notifications:establish-subscription
	"ietf-subscribed-notifications:input": {		{
	"stream": "NETCONF",		"ietf-subscribed-notifications:input": {
	"stream-xpath-filter": "/ietf-vrrp:vrrp-protocol-error-event[protocol-error-reason='checksum-error']/",		"stream": "NETCONF",
			"stream-xpath-filter":
			"/ietf-vrrp:vrrp-protocol-error-event[
			protocol-error-reason='checksum-error']/",
			}
	}		}
	}
	Figure 16: Establishing a subscription error reason via XPath		Figure 16: Establishing a subscription error reason via XPath
	For more examples of XPath filters, see [XPATH].		For more examples of XPath filters, see [XPATH].
	Suppose the "establish-subscription" in Figure 16 was accepted. And		Suppose the "establish-subscription" in Figure 16 was accepted. And
	suppose later a subscriber decided they wanted to broaden this		suppose later a subscriber decided they wanted to broaden this
	subscription cover to all VRRP protocol events (i.e., not just those		subscription cover to all VRRP protocol events (i.e., not just those
	with a "checksum error"). The subscriber might attempt to modify the		with a "checksum error"). The subscriber might attempt to modify the
	subscription in a way which replaces the XPath filter with a subtree		subscription in a way which replaces the XPath filter with a subtree
	filter which sends all VRRP protocol events to a subscriber. Such a		filter which sends all VRRP protocol events to a subscriber. Such a
	"modify-subscription" RPC might look like:		"modify-subscription" RPC might look like:
	POST /restconf/operations/ietf-subscribed-notifications:modify-subscription		POST /restconf/operations
	{		/ietf-subscribed-notifications:modify-subscription
	"ietf-subscribed-notifications:input": {		{
	"stream": "NETCONF",		"ietf-subscribed-notifications:input": {
	"stream-subtree-filter": {		"stream": "NETCONF",
	"/ietf-vrrp:vrrp-protocol-error-event" : {}		"stream-subtree-filter": {
			"/ietf-vrrp:vrrp-protocol-error-event" : {}
			}
	}		}
	}		}
	}
	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)
			v11 - v12
			o Added text in 3.2 for expected behavior when ietf-restconf-
			monitoring.yang is also supported.
			o Added section 2 to the reference to draft-ietf-netconf-nmda-
			restconf.
			o Replaced kill-subscription-error by delete-subscription-error in
			section 3.3.
			o Clarified vertical lines (a) and (b) in Figure 1 of section 3.4
			o Section 3.4, 3rd bullet after Figure 1, replaced "must" with
			"MUST".
			o Modified text in section 3.4 regarding access to RPCs modify-
			subscription, resync-subscription, delete-subscription and kill-
			subscription.
			o Section 4, first bullet for HTTP2: replaced dscp and priority with
			weighting and weight.
			o Section 6, added YANG tree diagram and fixed description of the
			module.
			o Section 7, fixed indentation of module description statement.
			o Section 7, in YANG module changed year in copyright statement to
			2019.
			o Section 8, added text on how server protects access to the
			subscription URI.
			o Fixed outdated references and removed unused references.
			o Fixed the instances of line too long.
			o Fixed example in Figure 3.
	v10 - v11		v10 - v11
	o Per Kent's request, added name attribute to artwork which need to		o Per Kent's request, added name attribute to artwork which need to
	be extracted		be extracted
	v09 - v10		v09 - v10
	o Fixed typo for resync.		o Fixed typo for resync.
	o Added text wrt RPC permissions and RESTCONF username.		o Added text wrt RPC permissions and RESTCONF username.
End of changes. 49 change blocks.
	100 lines changed or deleted		163 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/