draft-ietf-netconf-partial-lock-07.txt		draft-ietf-netconf-partial-lock-08.txt
	NETCONF B. Lengyel		NETCONF B. Lengyel
	Internet-Draft Ericsson		Internet-Draft Ericsson
	Intended status: Standards Track M. Bjorklund		Intended status: Standards Track M. Bjorklund
	Expires: August 23, 2009 Tail-f Systems		Expires: December 5, 2009 Tail-f Systems
	February 19, 2009		June 03, 2009
	Partial Lock RPC for NETCONF		Partial Lock RPC for NETCONF
	draft-ietf-netconf-partial-lock-07		draft-ietf-netconf-partial-lock-08
	Status of this Memo		Status of this Memo
	This Internet-Draft is submitted to IETF in full conformance with the		This Internet-Draft is submitted to IETF in full conformance with the
	provisions of BCP 78 and BCP 79.		provisions of BCP 78 and BCP 79.
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF), its areas, and its working groups. Note that		Task Force (IETF), its areas, and its working groups. Note that
	other groups may also distribute working documents as Internet-		other groups may also distribute working documents as Internet-
	Drafts.		Drafts.
	skipping to change at page 1, line 33		skipping to change at page 1, line 33
	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."
	The list of current Internet-Drafts can be accessed at		The list of current Internet-Drafts can be accessed at
	http://www.ietf.org/ietf/1id-abstracts.txt.		http://www.ietf.org/ietf/1id-abstracts.txt.
	The list of Internet-Draft Shadow Directories can be accessed at		The list of Internet-Draft Shadow Directories can be accessed at
	http://www.ietf.org/shadow.html.		http://www.ietf.org/shadow.html.
	This Internet-Draft will expire on August 23, 2009.		This Internet-Draft will expire on December 5, 2009.
	Copyright Notice		Copyright Notice
	Copyright (c) 2009 IETF Trust and the persons identified as the		Copyright (c) 2009 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 in effect on the date of
	(http://trustee.ietf.org/license-info) in effect on the date of		publication of this document (http://trustee.ietf.org/license-info).
	publication of this document. Please review these documents		Please review these documents carefully, as they describe your rights
	carefully, as they describe your rights and restrictions with respect		and restrictions with respect to this document.
	to this document.
	Abstract		Abstract
	The NETCONF protocol defines the lock and unlock RPCs, used to lock		The NETCONF protocol defines the lock and unlock RPCs, used to lock
	entire configuration datastores. In some situations, a way to lock		entire configuration datastores. In some situations, a way to lock
	only parts of a configuration datastore is required. This document		only parts of a configuration datastore is required. This document
	defines a capability-based extension to the NETCONF protocol for		defines a capability-based extension to the NETCONF protocol for
	locking portions of a configuration datastore.		locking portions of a configuration datastore.
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
	1.1. Definition of Terms . . . . . . . . . . . . . . . . . . . 3		1.1. Definition of Terms . . . . . . . . . . . . . . . . . . . 3
	2. Partial Locking Capability . . . . . . . . . . . . . . . . . . 3		2. Partial Locking Capability . . . . . . . . . . . . . . . . . . 3
	2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3		2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3
	2.1.1. Usage Scenarios . . . . . . . . . . . . . . . . . . . 4		2.1.1. Usage Scenarios . . . . . . . . . . . . . . . . . . . 4
	2.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 5		2.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 6
	2.3. Capability Identifier . . . . . . . . . . . . . . . . . . 5		2.3. Capability Identifier . . . . . . . . . . . . . . . . . . 6
	2.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 5		2.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 6
	2.4.1. <partial-lock> . . . . . . . . . . . . . . . . . . . . 6		2.4.1. <partial-lock> . . . . . . . . . . . . . . . . . . . . 6
	2.4.2. <partial-unlock> . . . . . . . . . . . . . . . . . . . 10		2.4.2. <partial-unlock> . . . . . . . . . . . . . . . . . . . 11
	2.5. Modifications to Existing Operations . . . . . . . . . . . 11		2.5. Modifications to Existing Operations . . . . . . . . . . . 11
	2.6. Interactions with Other Capabilities . . . . . . . . . . . 12		2.6. Interactions with Other Capabilities . . . . . . . . . . . 12
	2.6.1. Candidate Configuration Capability . . . . . . . . . . 12		2.6.1. Candidate Configuration Capability . . . . . . . . . . 12
	2.6.2. Confirmed Commit Capability . . . . . . . . . . . . . 12		2.6.2. Confirmed Commit Capability . . . . . . . . . . . . . 12
	2.6.3. Distinct Startup Capability . . . . . . . . . . . . . 12		2.6.3. Distinct Startup Capability . . . . . . . . . . . . . 12
	3. Security Considerations . . . . . . . . . . . . . . . . . . . 12		3. Security Considerations . . . . . . . . . . . . . . . . . . . 12
	4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13		4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
	5. Appendix A - XML Schema for Partial Locking (normative) . . 14		5. Appendix A - XML Schema for Partial Locking (normative) . . 15
	6. Appendix B - YANG Module for Partial Locking		6. Appendix B - YANG Module for Partial Locking
	(non-normative) . . . . . . . . . . . . . . . . . . . . . . . 18		(non-normative) . . . . . . . . . . . . . . . . . . . . . . . 19
	7. Appendix C - Usage Example - Reserving nodes for future		7. Appendix C - Usage Example - Reserving nodes for future
	editing (non-normative) . . . . . . . . . . . . . . . . . . . 21		editing (non-normative) . . . . . . . . . . . . . . . . . . . 22
	8. Appendix D - Change Log . . . . . . . . . . . . . . . . . . 26		8. Appendix D - Change Log . . . . . . . . . . . . . . . . . . 27
	8.1. 06-07 . . . . . . . . . . . . . . . . . . . . . . . . . . 26		8.1. 07-08 . . . . . . . . . . . . . . . . . . . . . . . . . . 27
	8.2. 05-06 . . . . . . . . . . . . . . . . . . . . . . . . . . 26		8.2. 06-07 . . . . . . . . . . . . . . . . . . . . . . . . . . 27
	8.3. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 26		8.3. 05-06 . . . . . . . . . . . . . . . . . . . . . . . . . . 27
	8.4. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 26		8.4. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 27
	8.5. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 27		8.5. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 27
	8.6. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 27		8.6. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 28
	8.7. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 27		8.7. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 28
	8.8. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 27		8.8. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 28
	9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 28		8.9. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
	10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29		9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 29
	10.1. Normative References . . . . . . . . . . . . . . . . . . . 29		10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30
	10.2. Informative References . . . . . . . . . . . . . . . . . . 29		10.1. Normative References . . . . . . . . . . . . . . . . . . . 30
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30		10.2. Informative References . . . . . . . . . . . . . . . . . . 30
			Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 31
	1. Introduction		1. Introduction
	The [NETCONF] protocol describes the lock and unlock operations that		The [NETCONF] protocol describes the lock and unlock operations that
	operate on entire configuration datastores. Often, multiple		operate on entire configuration datastores. Often, multiple
	management sessions need to be able to modify the configuration of a		management sessions need to be able to modify the configuration of a
	managed device in parallel. In these cases, locking only parts of a		managed device in parallel. In these cases, locking only parts of a
	configuration datastore is needed. This document defines a		configuration datastore is needed. This document defines a
	capability based extension to the NETCONF protocol to support partial		capability based extension to the NETCONF protocol to support partial
	locking of NETCONF datastores using a mechanism based on the existing		locking of NETCONF datastores using a mechanism based on the existing
	skipping to change at page 4, line 13		skipping to change at page 4, line 13
	operations such as SNMP and the CLI.		operations such as SNMP and the CLI.
	The duration of the partial lock begins when the partial lock is		The duration of the partial lock begins when the partial lock is
	granted and lasts until (1) either the corresponding <partial-unlock>		granted and lasts until (1) either the corresponding <partial-unlock>
	operation succeeds or (2) the NETCONF session terminates.		operation succeeds or (2) the NETCONF session terminates.
	A NETCONF session MAY have multiple parts of one or more datastores		A NETCONF session MAY have multiple parts of one or more datastores
	(running, candidate, startup) locked using partial lock operations.		(running, candidate, startup) locked using partial lock operations.
	The <partial-lock> operation returns a lock-id to identify each		The <partial-lock> operation returns a lock-id to identify each
	successfully acquired lock.		successfully acquired lock. The lock-id is unique for a NETCONF
			server for all partial-locks granted to any NETCONF or non-NETCONF
			sessions.
	2.1.1. Usage Scenarios		2.1.1. Usage Scenarios
	In the following we describe a few scenarios for partial locking.		In the following we describe a few scenarios for partial locking.
	While scenarios using the running datastore are seen as the most		Partial locking is primarily useful towards the running
	important, as an example a scenario involving the candidate datastore		configuration. However it can be used to lock a candidate datastore
	is also presented. Besides the three described here, there are many		as well. While scenarios using the running datastore are seen as the
	other usage scenarios possible.		most important, as an example a scenario involving the candidate
			datastore is also presented. Besides the three described here, there
			are many other usage scenarios possible.
	2.1.1.1. Multiple managers handling the writable running datastore		2.1.1.1. Multiple managers handling the writable running datastore
	Multiple managers are handling the same NETCONF agent simultaneously.		Multiple managers are handling the same NETCONF agent simultaneously.
	The agent is handled via the writable running datastore. Each		The agent is handled via the writable running datastore. Each
	manager has his or her own task, which might involve the modification		manager has his or her own task, which might involve the modification
	of overlapping sections of the datastore.		of overlapping sections of the datastore.
	After collecting and analyzing input and preparing the NETCONF		After collecting and analyzing input and preparing the NETCONF
	operations off-line, the manager locks the areas that are important		operations off-line, the manager locks the areas that are important
	skipping to change at page 5, line 36		skipping to change at page 5, line 39
	candidate and the running datastore. He executes a number of <edit-		candidate and the running datastore. He executes a number of <edit-
	config> operations to modify the configuration, then releases the		config> operations to modify the configuration, then releases the
	partial-lock. The lock should be held for only a short time (seconds		partial-lock. The lock should be held for only a short time (seconds
	rather then minutes).		rather then minutes).
	Operators coordinate with each other. When all of them finish their		Operators coordinate with each other. When all of them finish their
	tasks one of them orders commit. If any of the operators are still		tasks one of them orders commit. If any of the operators are still
	working, and holds a lock, the commit will fail, and will need to be		working, and holds a lock, the commit will fail, and will need to be
	repeated after all managers finish.		repeated after all managers finish.
			Warning: When multiple managers use the candidate configuration in
			parallel, there is a risk that the interaction of access control
			(which is still implementation specific at the time of this writing)
			and the commit operation might result in a dead-lock, as illustrated
			by the following sequence.
			Manager A only has access to the interfaces branch in the model,
			and edits it in candidate
			Manager B only has access to the routing branch in the model, and
			edits it in candidate
			Manager A terminates it's session
			Now Manager B can not issue <commit> because it can not modify
			interfaces in the running datastore
			Manager B can not issue <discard-changes> because it can not
			modify interfaces in the candidate datastore
			The situation is not a result of partial locking as a lock can be
			easily removed; it is the result of a potential interaction between
			access control, which by nature is specific for different parts of
			the datastore and the global nature of the commit operation.
	2.2. Dependencies		2.2. Dependencies
	The device MUST support restricted XPath expressions in the select		The device MUST support restricted XPath expressions in the select
	element, as described in Section 2.4.1. Optionally, if the :xpath		element, as described in Section 2.4.1. Optionally, if the :xpath
	capability is also supported (as defined in [NETCONF] chapter 8.9.		capability is also supported (as defined in [NETCONF] chapter 8.9.
	XPath Capability), the device MUST also support using any XPath 1.0		XPath Capability), the device MUST also support using any XPath 1.0
	expression in the select element.		expression in the select element.
	2.3. Capability Identifier		2.3. Capability Identifier
	skipping to change at page 10, line 21		skipping to change at page 10, line 32
	If any select expression is an invalid XPath expression, the <error-		If any select expression is an invalid XPath expression, the <error-
	tag> is 'invalid-value'.		tag> is 'invalid-value'.
	If any select expression returns something other than a node set, the		If any select expression returns something other than a node set, the
	<error-tag> is 'invalid-value', and the <error-app-tag> is 'not-a-		<error-tag> is 'invalid-value', and the <error-app-tag> is 'not-a-
	node-set'.		node-set'.
	If all the select expressions return an empty node set, the <error-		If all the select expressions return an empty node set, the <error-
	tag> is 'operation-failed', and the <error-app-tag> is 'no-matches'.		tag> is 'operation-failed', and the <error-app-tag> is 'no-matches'.
	If any of the target datastors does not exist, the <error-tag> is		If any of the target datastores does not exist, the <error-tag> is
	'invalid-value', the <error-app-tag> is 'invalid-lock-specification'		'invalid-value', the <error-app-tag> is 'invalid-lock-specification'
	If the :xpath capability is not supported and the XPath expression is		If the :xpath capability is not supported and the XPath expression is
	not an Instance Identifier, the <error-tag> is 'invalid-value', the		not an Instance Identifier, the <error-tag> is 'invalid-value', the
	<error-app-tag> is 'invalid-lock-specification'.		<error-app-tag> is 'invalid-lock-specification'.
	If access control denies the partial lock, the <error-tag> is		If access control denies the partial lock, the <error-tag> is
	'access-denied'.		'access-denied'.
	2.4.1.2. Deadlock Avoidance		2.4.1.2. Deadlock Avoidance
	skipping to change at page 26, line 7		skipping to change at page 27, line 7
	<nc:rpc xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"		<nc:rpc xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
	xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"		xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
	message-id="105">		message-id="105">
	<partial-unlock>		<partial-unlock>
	<lock-id>1</lock-id>		<lock-id>1</lock-id>
	</partial-unlock>		</partial-unlock>
	</nc:rpc>		</nc:rpc>
	8. Appendix D - Change Log		8. Appendix D - Change Log
	8.1. 06-07		8.1. 07-08
			Clarifications
			8.2. 06-07
	Changed XSD and YANG to allow additional proprietary datastores to be		Changed XSD and YANG to allow additional proprietary datastores to be
	locked.		locked.
	8.2. 05-06		8.3. 05-06
	Added usage example		Added usage example
	Clarified error messages		Clarified error messages
	Clarified interaction with edit-config continue-on-error		Clarified interaction with edit-config continue-on-error
	Improved YANG: indentation, canonical order, contact info		Improved YANG: indentation, canonical order, contact info
	Added usage example in appendix C		Added usage example in appendix C
	Synchronized YANG and XSD		Synchronized YANG and XSD
	8.3. 04-05		8.4. 04-05
	Language and editorial updates		Language and editorial updates
	all app-tags are with dashes without spaces		all app-tags are with dashes without spaces
	Added usage scenarios		Added usage scenarios
	Changed encoding		Changed encoding
	Clarified definitions, separated scope of lock and protected area		Clarified definitions, separated scope of lock and protected area
	8.4. 03-04		8.5. 03-04
	Minor clarifications		Minor clarifications
	Added list of locked-nodes to the output of partial-lock.		Added list of locked-nodes to the output of partial-lock.
	Added <target> wrapper around datastore names.		Added <target> wrapper around datastore names.
	Allowed atomic/one operation locking of datastore parts in multiple		Allowed atomic/one operation locking of datastore parts in multiple
	datastores.		datastores.
	Improved English (hopefully)		Improved English (hopefully)
	Removed the <data> element from rpc-reply following the text of		Removed the <data> element from rpc-reply following the text of
	rfc4741.		rfc4741.
	8.5. 02-03		8.6. 02-03
	Minor clarifications		Minor clarifications
	Same descriptions in XSD and YANG.		Same descriptions in XSD and YANG.
	8.6. 01-02		8.7. 01-02
	Made XSD normative		Made XSD normative
	Clarified that no specific access control is assumed.		Clarified that no specific access control is assumed.
	Clarified that non-existing nodes are NOT covered by the lock, even		Clarified that non-existing nodes are NOT covered by the lock, even
	if they where existing and covered by the lock when it was originally		if they where existing and covered by the lock when it was originally
	granted.		granted.
	Some rewording		Some rewording
	Added app-tags for two of the error cases.		Added app-tags for two of the error cases.
	Made YANG an informative reference		Made YANG an informative reference
	Enhanced security considerations.		Enhanced security considerations.
	8.7. 00-01		8.8. 00-01
	Added YANG module.		Added YANG module.
	8.8. -00		8.9. -00
	Created from draft-lengyel-ngo-partial-lock-01.txt		Created from draft-lengyel-ngo-partial-lock-01.txt
	9. Acknowledgements		9. Acknowledgements
	Thanks to Andy Bierman, Sharon Chisholm, Phil Shafer , David		Thanks to Andy Bierman, Sharon Chisholm, Phil Shafer , David
	Harrington, Mehmet Ersue, Wes Hardaker, Juergen Schoenwaelder and		Harrington, Mehmet Ersue, Wes Hardaker, Juergen Schoenwaelder, Washam
	many other members of the NETCONF WG for providing important input to		Fan and many other members of the NETCONF WG for providing important
	this document.		input to this document.
	10. References		10. References
	10.1. Normative References		10.1. Normative References
	[NETCONF] Enns, R., "NETCONF Configuration Protocol", RFC 4741,		[NETCONF] Enns, R., "NETCONF Configuration Protocol", RFC 4741,
	December 2006.		December 2006.
	[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, March 1997.		Requirement Levels", BCP 14, RFC 2119, March 1997.
	[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,		[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
	January 2004.		January 2004.
	10.2. Informative References		10.2. Informative References
	[I-D.ietf-netmod-yang]		[I-D.ietf-netmod-yang]
	Bjorklund, M., "YANG - A data modeling language for		Bjorklund, M., "YANG - A data modeling language for
	NETCONF", draft-ietf-netmod-yang-03 (work in progress),		NETCONF", draft-ietf-netmod-yang-05 (work in progress),
	January 2009.		April 2009.
	Authors' Addresses		Authors' Addresses
	Balazs Lengyel		Balazs Lengyel
	Ericsson		Ericsson
	Email: balazs.lengyel@ericsson.com		Email: balazs.lengyel@ericsson.com
	Martin Bjorklund		Martin Bjorklund
	Tail-f Systems		Tail-f Systems
End of changes. 23 change blocks.
	49 lines changed or deleted		81 lines changed or added
This html diff was produced by rfcdiff 1.35. The latest version is available from http://tools.ietf.org/tools/rfcdiff/