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/