draft-ietf-netconf-partial-lock-02.txt		draft-ietf-netconf-partial-lock-03.txt
	NETCONF B. Lengyel		NETCONF B. Lengyel
	Internet-Draft Ericsson Hungary		Internet-Draft Ericsson Hungary
	Intended status: Standards Track M. Bjorklund		Intended status: Standards Track M. Bjorklund
	Expires: December 15, 2008 Tail-f Systems		Expires: February 7, 2009 Tail-f Systems
	June 13, 2008		August 06, 2008
	Partial Lock RPC for NETCONF		Partial Lock RPC for NETCONF
	draft-ietf-netconf-partial-lock-02		draft-ietf-netconf-partial-lock-03
	Status of this Memo		Status of this Memo
	By submitting this Internet-Draft, each author represents that any		By submitting this Internet-Draft, each author represents that any
	applicable patent or other IPR claims of which he or she is aware		applicable patent or other IPR claims of which he or she is aware
	have been or will be disclosed, and any of which he or she becomes		have been or will be disclosed, and any of which he or she becomes
	aware will be disclosed, in accordance with Section 6 of BCP 79.		aware will be disclosed, in accordance with Section 6 of 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
	skipping to change at page 1, line 35		skipping to change at page 1, line 35
	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 December 15, 2008.		This Internet-Draft will expire on February 7, 2009.
	Copyright Notice		Copyright Notice
	Copyright (C) The IETF Trust (2008).		Copyright (C) The IETF Trust (2008).
	Abstract		Abstract
	The NETCONF protocol defines the lock and unlock RPCs that lock		The NETCONF protocol defines the lock and unlock RPCs that 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
	skipping to change at page 2, line 27		skipping to change at page 2, line 27
	2.6. Interactions with Other Capabilities . . . . . . . . . . . 9		2.6. Interactions with Other Capabilities . . . . . . . . . . . 9
	2.6.1. Writable-Running Capability . . . . . . . . . . . . . 9		2.6.1. Writable-Running Capability . . . . . . . . . . . . . 9
	2.6.2. Candidate Configuration Capability . . . . . . . . . . 9		2.6.2. Candidate Configuration Capability . . . . . . . . . . 9
	2.6.3. Distinct Startup Capability . . . . . . . . . . . . . 9		2.6.3. Distinct Startup Capability . . . . . . . . . . . . . 9
	3. Security Considerations . . . . . . . . . . . . . . . . . . . 9		3. Security Considerations . . . . . . . . . . . . . . . . . . . 9
	4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10		4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
	5. Appendix A - XML Schema for Partial Locking (normative) . . 11		5. Appendix A - XML Schema for Partial Locking (normative) . . 11
	6. Appendix B - YANG Module for Partial Locking		6. Appendix B - YANG Module for Partial Locking
	(non-normative) . . . . . . . . . . . . . . . . . . . . . . . 13		(non-normative) . . . . . . . . . . . . . . . . . . . . . . . 13
	7. Appendix C - Change Log . . . . . . . . . . . . . . . . . . 15		7. Appendix C - Change Log . . . . . . . . . . . . . . . . . . 15
	7.1. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 15		7.1. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 15
	7.2. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 15		7.2. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 15
	7.3. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 15		7.3. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 15
			7.4. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
	8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 16		8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 16
	9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17		9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17
	9.1. Normative References . . . . . . . . . . . . . . . . . . . 17		9.1. Normative References . . . . . . . . . . . . . . . . . . . 17
	9.2. Informative References . . . . . . . . . . . . . . . . . . 17		9.2. Informative References . . . . . . . . . . . . . . . . . . 17
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 18		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 18
	Intellectual Property and Copyright Statements . . . . . . . . . . 19		Intellectual Property and Copyright Statements . . . . . . . . . . 19
	1. Introduction		1. Introduction
	The NETCONF protocol [NETCONF] describes the lock and unlock RPCs		The NETCONF protocol [NETCONF] describes the lock and unlock RPCs
	skipping to change at page 3, line 41		skipping to change at page 3, line 41
	locking of its configuration with a scope smaller then a complete		locking of its configuration with a scope smaller then a complete
	configuration datastore. The scope to be locked is specified by		configuration datastore. The scope to be locked is specified by
	using restricted or full XPath expressions. Partial locking covers		using restricted or full XPath expressions. Partial locking covers
	configuration data, but not state data.		configuration data, but not state data.
	The system MUST ensure that configuration resources covered by the		The system MUST ensure that configuration resources covered by the
	lock are not modified by other NETCONF or non-NETCONF management		lock are not modified by other NETCONF or non-NETCONF management
	operations such as SNMP and the CLI.		operations such as SNMP and the CLI.
	The duration of the partial lock is defined as beginning when the		The duration of the partial lock is defined as beginning when the
	partial lock is granted and lasting until either the corresponding		partial lock is granted. The partial lock lasts until either the
	<partial-unlock> operation succeeds or the NETCONF session		corresponding <partial-unlock> operation succeeds or the NETCONF
	terminates.		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.
	2.2. Dependencies		2.2. Dependencies
	The device MUST support the restricted XPath expressions in the		The device MUST support the restricted XPath expressions in the
	select element, as described in Section 2.4.1 If optionally the		select element, as described in Section 2.4.1. If optionally the
	:xpath capability is also supported, the device MUST also support the		:xpath capability is also supported, the device MUST also support the
	usage of any XPath 1.0 expression in the select element.		usage of any XPath 1.0 expression in the select element.
	2.3. Capability Identifier		2.3. Capability Identifier
	urn:ietf:params:netconf:capability:partial-lock:1.0		urn:ietf:params:netconf:capability:partial-lock:1.0
	2.4. New Operations		2.4. New Operations
	2.4.1. <partial-lock>		2.4.1. <partial-lock>
	The <partial-lock> operation allows the client to lock a portion of a		The <partial-lock> operation allows the client to lock a portion of a
	data store. The portion to lock is specified by using XPath		data store. The portion to lock is specified by using XPath
	expressions in the select elements of the <partial-lock> operation.		expressions in the select elements of the <partial-lock> operation.
	Each XPath expression MUST return a node set.		Each XPath expression MUST return a node set. Locking a node
			protects the complete subtree under it from modification by others.
	The select XPath expressions are evaluated only once at lock time,		The select XPath expressions are evaluated only once at lock time,
	thereafter the scope of the lock is maintained as a set of nodes. If		thereafter the scope of the lock is maintained as a set of nodes. If
	the configuration data is later altered in a way that would make the		the configuration data is later altered in a way that would make the
	original select XPath expressions evaluate to a different set of		original select XPath expressions evaluate to a different set of
	nodes, this does not affect the scope of the partial lock.		nodes, this does not affect the scope of the partial lock.
	XPath is only used for the creation of the partial lock.		XPath is only used for the creation of the partial lock.
	Conceptually the scope of the lock is defined by the returned node		Conceptually the scope of the lock is defined by the returned node
	set and not by the XPath expression.		set and not by the XPath expression.
	skipping to change at page 4, line 49		skipping to change at page 4, line 50
	been already locked during that operation.		been already locked during that operation.
	If a node is locked by a session, only that same session is able to		If a node is locked by a session, only that same session is able to
	modify that node or any node in the subtree underneath it.		modify that node or any node in the subtree underneath it.
	If a top level node of a locked subtree is deleted, any other session		If a top level node of a locked subtree is deleted, any other session
	can recreate it, as it is not covered by the lock anymore. If all		can recreate it, as it is not covered by the lock anymore. If all
	top level nodes are deleted, the lock will still be present, however		top level nodes are deleted, the lock will still be present, however
	it's scope will become nil i.e. it will not cover any nodes.		it's scope will become nil i.e. it will not cover any nodes.
	A partial lock MUST fail if:		A partial lock operation MUST fail if:
	o Any NETCONF session (including the current session) owns the		o Any NETCONF session (including the current session) owns the
	global lock on the datastore.		global lock on the datastore.
	o Any part of the scope to be locked is already locked by another		o Any part of the scope to be locked is already locked by another
	management session/protocol, including other NETCONF sessions		management session/protocol, including other NETCONF sessions
	using the <partial-lock> or any other non-NETCONF management		using the <partial-lock> or any other non-NETCONF management
	method.		method.
	o The NETCONF server implements access control and the locking user		o The NETCONF server implements access control and the locking user
	skipping to change at page 6, line 11		skipping to change at page 6, line 13
	outside the scope of a lock. It is the operator's responsibility		outside the scope of a lock. It is the operator's responsibility
	to lock all parts of the datastore that are crucial for a specific		to lock all parts of the datastore that are crucial for a specific
	management action.		management action.
	Note: The <partial-lock> operation does not modify the global <lock>		Note: The <partial-lock> operation does not modify the global <lock>
	operation defined in the base NETCONF Protocol [NETCONF]. If part of		operation defined in the base NETCONF Protocol [NETCONF]. If part of
	a datastore is already locked by <partial-lock>, then a global lock		a datastore is already locked by <partial-lock>, then a global lock
	for that datastore fails even if the global lock is attempted by the		for that datastore fails even if the global lock is attempted by the
	same NETCONF session which owns the partial-lock.		same NETCONF session which owns the partial-lock.
			2.4.1.1. Parameters, Result, Examples
	Parameters:		Parameters:
	target: Name of the configuration datastore of which a part shall be		target: Name of the configuration datastore of which a part shall be
	locked. One <partial-lock> operation can affect only one of the		locked. One <partial-lock> operation can affect only one of the
	datastores. URLs are not accepted.		datastores. URLs are not accepted.
	select: One or more 'select' elements each containing an XPath		select: One or more 'select' elements each containing an XPath
	expression. The XPath expression is evaluated in a context where		expression. The XPath expression is evaluated in a context where
	the context node is the root of the server's conceptual data		the context node is the root of the server's conceptual data
	model, and the set of namespace declarations are those in scope		model, and the set of namespace declarations are those in scope
	skipping to change at page 7, line 15		skipping to change at page 7, line 15
	Example: Lock virtual router 1 and interface eth1		Example: Lock virtual router 1 and interface eth1
	<nc:rpc		<nc:rpc
	xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"		xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
	xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"		xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
	xmlns:rte="http://example.com/ns/route">		xmlns:rte="http://example.com/ns/route">
	xmlns:if="http://example.com/ns/interface">		xmlns:if="http://example.com/ns/interface">
	nc:message-id="135">		nc:message-id="135">
	<partial-lock>		<partial-lock>
	<nc:running/>		<nc:running/>
	<select>/routing/virtualRouter['routerName=router1']</select>		<select>
			/routing/virtualRouter['routerName=router1']
			</select>
	<select>/interfaces/interface[Id='eth1']</select>		<select>/interfaces/interface[Id='eth1']</select>
	</partial-lock>		</partial-lock>
	</nc:rpc>		</nc:rpc>
	<nc:rpc-reply		<nc:rpc-reply
	xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"		xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
	xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"		xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
	xmlns:rte="http://example.com/ns/route">		xmlns:rte="http://example.com/ns/route">
	xmlns:if="http://example.com/ns/interface">		xmlns:if="http://example.com/ns/interface">
	nc:message-id="135">		nc:message-id="135">
	skipping to change at page 8, line 10		skipping to change at page 8, line 12
	tag> is 'invalid-value', the <error-app-tag> is 'XPath does not		tag> is 'invalid-value', the <error-app-tag> is 'XPath does not
	return a node set'.		return a node set'.
	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 ':xpath capability not supported'.		<error-app-tag> is ':xpath capability not supported'.
	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.1. Reserving model sections for future work		2.4.1.2. Reserving model sections for future work
	Partial lock can not be used to lock non-existing nodes, effectively		Partial lock can not be used to lock non-existing nodes, effectively
	reserving them for future use. To make sure that a node cannot be		reserving them for future use. To make sure that a node cannot be
	created by some other session, the parent node should be locked, the		created by some other session, the parent node should be locked, the
	top level node of the new section created, and then locked with		top level node of the new section created, and then locked with
	another <partial-lock> operation. After this the lock on the parent		another <partial-lock> operation. After this the lock on the parent
	node should be removed.		node should be removed.
	2.4.2. <partial-unlock>		2.4.2. <partial-unlock>
	skipping to change at page 9, line 7		skipping to change at page 9, line 7
	that contains an <ok> element. A positive response MUST be sent even		that contains an <ok> element. A positive response MUST be sent even
	if all of the locked part of the datastore has already been deleted.		if all of the locked part of the datastore has already been deleted.
	Negative Response:		Negative Response:
	If the <lock-id> parameter does not identify a lock which is owned by		If the <lock-id> parameter does not identify a lock which is owned by
	the session, an 'invalid-value' error is returned.		the session, an 'invalid-value' error is returned.
	2.5. Modifications to Existing Operations		2.5. Modifications to Existing Operations
	A granted partial-lock will cause operations that want to modify the		A granted partial-lock will cause another operation to fail, if it
	locked area to fail, if executed in a NETCONF session other then the		tries to modify the locked area and is executed in a NETCONF session
	one that owns the lock. Affected operations include: <edit-config>,		other then the one that owns the lock. Affected operations include:
	<copy-config>, <delete-config>, <commit> and <discard-changes>. A		<edit-config>, <copy-config>, <delete-config>, <commit> and <discard-
	granted partial-lock will also cause the (global) <lock> operation to		changes>. A granted partial-lock will also cause the (global) <lock>
	fail. All of these operations are affected only if they are for the		operation to fail. All of these operations are affected only if they
	same datastore.		are for the same datastore.
	2.6. Interactions with Other Capabilities		2.6. Interactions with Other Capabilities
	2.6.1. Writable-Running Capability		2.6.1. Writable-Running Capability
	Partial locking of the running datastore can only be done if the		Partial locking of the running datastore can only be done if the
	:writable-running capability is supported by the device.		:writable-running capability is supported by the device.
	2.6.2. Candidate Configuration Capability		2.6.2. Candidate Configuration Capability
	skipping to change at page 11, line 32		skipping to change at page 11, line 32
	"Balazs Lengyel		"Balazs Lengyel
	Ericsson Hungary, Inc.		Ericsson Hungary, Inc.
	balazs.lengyel@ericsson.com"		balazs.lengyel@ericsson.com"
	</xs:documentation>		</xs:documentation>
	</xs:annotation>		</xs:annotation>
	<xs:import namespace="urn:ietf:params:xml:ns:netconf:base:1.0"		<xs:import namespace="urn:ietf:params:xml:ns:netconf:base:1.0"
	schemaLocation="netconf.xsd"/>		schemaLocation="netconf.xsd"/>
	<xs:complexType name="partialLockType">		<xs:complexType name="partialLockType">
			<xs:annotation>
			<xs:documentation>
			A NETCONF operation that locks part of a datastore.
			</xs:documentation>
			</xs:annotation>
	<xs:complexContent>		<xs:complexContent>
	<xs:extension base="nc:rpcOperationType">		<xs:extension base="nc:rpcOperationType">
	<xs:sequence>		<xs:sequence>
	<xs:element ref="nc:config-name"/>		<xs:element ref="nc:config-name"/>
	<xs:element name="select" type="xs:string"		<xs:element name="select" type="xs:string"
	maxOccurs="unbounded"/>		maxOccurs="unbounded">
			<xs:annotation>
			<xs:documentation>
			XPath expression that specifies the scope of the lock.
			An Instance Identifier expression must be used unless
			the :xpath capability is supported in which case any
			XPath 1.0 expression is allowed.
			</xs:documentation>
			</xs:annotation>
			</xs:element>
	</xs:sequence>		</xs:sequence>
	</xs:extension>		</xs:extension>
	</xs:complexContent>		</xs:complexContent>
	</xs:complexType>		</xs:complexType>
	<xs:complexType name="partialUnLockType">		<xs:complexType name="partialUnLockType">
			<xs:annotation>
			<xs:documentation>
			A NETCONF operation that releases a previously acquired
			partial-lock.
			</xs:documentation>
			</xs:annotation>
	<xs:complexContent>		<xs:complexContent>
	<xs:extension base="nc:rpcOperationType">		<xs:extension base="nc:rpcOperationType">
	<xs:sequence>		<xs:sequence>
	<xs:element name="lock-id" type="xs:unsignedInt"/>		<xs:element name="lock-id" type="xs:unsignedInt">
			<xs:annotation>
			<xs:documentation>
			Identifies the lock to be released. Must be the value
			received in the response to the partial-lock operation.
			</xs:documentation>
			</xs:annotation>
			</xs:element>
	</xs:sequence>		</xs:sequence>
	</xs:extension>		</xs:extension>
	</xs:complexContent>		</xs:complexContent>
	</xs:complexType>		</xs:complexType>
	<!-- <partial-lock> operation -->		<!-- <partial-lock> operation -->
	<xs:element name="partial-lock" type="partialLockType"		<xs:element name="partial-lock" type="partialLockType"
	substitutionGroup="nc:rpcOperation"/>		substitutionGroup="nc:rpcOperation"/>
	<!-- <partial-unlock> operation -->		<!-- <partial-unlock> operation -->
	<xs:element name="partial-unlock" type="partialUnLockType"		<xs:element name="partial-unlock" type="partialUnLockType"
	substitutionGroup="nc:rpcOperation"/>		substitutionGroup="nc:rpcOperation"/>
	<!-- reply to <partial-lock> -->		<!-- reply to <partial-lock> -->
	<xs:element name="lock-id" type="xs:unsignedInt"/>		<xs:element name="lock-id" type="xs:unsignedInt"/>
	skipping to change at page 14, line 8		skipping to change at page 14, line 8
	description		description
	"XPath expression that specifies the scope of the lock.		"XPath expression that specifies the scope of the lock.
	An Instance Identifier expression must be used unless the		An Instance Identifier expression must be used unless the
	:xpath capability is supported in which case any XPath 1.0		:xpath capability is supported in which case any XPath 1.0
	expression is allowed.";		expression is allowed.";
	type string;		type string;
	min-elements 1;		min-elements 1;
	}		}
	}		}
	output {		output {
	leaf lockId {		leaf lock-id {
	description		description
	"Identifies the lock, if granted. The lockId must be		"Identifies the lock, if granted. The lock-id must be
	used in the partial-unlock rpc.";		used in the partial-unlock rpc.";
	type uint32;		type uint32;
	}		}
	}		}
	}		}
	rpc partial-unlock {		rpc partial-unlock {
			description
			"A NETCONF operation that releases a previously acquired
			partial-lock.";
	input {		input {
	leaf lockId {		leaf lock-id {
	description		description
	"Identifies the lock to be released. Must be the value		"Identifies the lock to be released. Must be the value
	received in the response to the partial-lock operation.";		received in the response to the partial-lock operation.";
	type uint32;		type uint32;
	}		}
	}		}
	}		}
	}		}
	7. Appendix C - Change Log		7. Appendix C - Change Log
	7.1. 01-02		7.1. 02-03
			Minor clarifications
			Same descriptions in XSD and YANG.
			7.2. 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.
	7.2. 00-01		7.3. 00-01
	Added YANG module.		Added YANG module.
	7.3. -00		7.4. -00
	Created from draft-lengyel-ngo-partial-lock-01.txt		Created from draft-lengyel-ngo-partial-lock-01.txt
	8. Acknowledgements		8. Acknowledgements
	Thanks to Andy Bierman, Sharon Chisholm, Phil Shafer , David		Thanks to Andy Bierman, Sharon Chisholm, Phil Shafer , David
	Harrington, Mehmet Ersue and many other members of the NETCONF WG for		Harrington, Mehmet Ersue and many other members of the NETCONF WG for
	providing important input to this document.		providing important input to this document.
	9. References		9. References
End of changes. 24 change blocks.
	30 lines changed or deleted		73 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/