draft-ietf-netconf-partial-lock-00.txt   draft-ietf-netconf-partial-lock-01.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: July 10, 2008 Tail-f Systems Expires: August 28, 2008 Tail-f Systems
January 07, 2008 February 25, 2008
Partial Lock RPC for NETCONF Partial Lock RPC for NETCONF
draft-ietf-netconf-partial-lock-00 draft-ietf-netconf-partial-lock-01
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 July 10, 2008. This Internet-Draft will expire on August 28, 2008.
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
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.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 3 2.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 4
2.3. Capability Identifier . . . . . . . . . . . . . . . . . . 4 2.3. Capability Identifier . . . . . . . . . . . . . . . . . . 4
2.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 4 2.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 4
2.4.1. <partial-lock> . . . . . . . . . . . . . . . . . . . . 4 2.4.1. <partial-lock> . . . . . . . . . . . . . . . . . . . . 4
2.4.2. <partial-unlock> . . . . . . . . . . . . . . . . . . . 7 2.4.2. <partial-unlock> . . . . . . . . . . . . . . . . . . . 7
2.5. Modifications to Existing Operations . . . . . . . . . . . 8 2.5. Modifications to Existing Operations . . . . . . . . . . . 8
2.6. Interactions with Other Capabilities . . . . . . . . . . . 8 2.6. Interactions with Other Capabilities . . . . . . . . . . . 8
2.6.1. Writable-Running Capability . . . . . . . . . . . . . 8 2.6.1. Writable-Running Capability . . . . . . . . . . . . . 8
2.6.2. Candidate Configuration Capability . . . . . . . . . . 8 2.6.2. Candidate Configuration Capability . . . . . . . . . . 8
2.6.3. Distinct Startup Capability . . . . . . . . . . . . . 8 2.6.3. Distinct Startup Capability . . . . . . . . . . . . . 8
3. Security Considerations . . . . . . . . . . . . . . . . . . . 8 3. Security Considerations . . . . . . . . . . . . . . . . . . . 8
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
5. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . 8 5. Appendix A - Change Log . . . . . . . . . . . . . . . . . . 10
5.1. Open Issues . . . . . . . . . . . . . . . . . . . . . . . 8 5.1. Open Issues . . . . . . . . . . . . . . . . . . . . . . . 10
6. XML Schema for Partial Locking . . . . . . . . . . . . . . . . 9 5.2. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 10 5.3. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 10
8. Normative References . . . . . . . . . . . . . . . . . . . . . 10 6. Appendix B - YANG Module for Partial Locking
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 (non-normative) . . . . . . . . . . . . . . . . . . . . . . . 11
Intellectual Property and Copyright Statements . . . . . . . . . . 11 7. Appendix C - XML Schema for Partial Locking
(non-normative) . . . . . . . . . . . . . . . . . . . . . . . 13
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15
9. Normative References . . . . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17
Intellectual Property and Copyright Statements . . . . . . . . . . 18
1. Introduction 1. Introduction
The NETCONF protocol [RFC4741] describes the lock and unlock RPCs The NETCONF protocol [RFC4741] describes the lock and unlock RPCs
that operate on entire configuration datastores. Often, multiple that 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 an configuration datastore is needed. This document defines an
extension to the NETCONF protocol to allow this. extension to the NETCONF protocol to allow this.
The mechanism for partial locking will be based on the existing XPath The mechanism for partial locking is based on the existing XPath
filtering mechanisms. filtering mechanisms.
Partial locking will be introduced as a capability to NETCONF. Partial locking is defined as a capability to NETCONF.
1.1. Definition of Terms 1.1. Definition of Terms
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
document are to be interpreted as described in RFC 2119. "OPTIONAL" in this document are to be interpreted as described in BCP
14, [RFC2119].
2. Partial Locking Capability 2. Partial Locking Capability
2.1. Overview 2.1. Overview
The :partial-lock capability indicates that the device supports the The :partial-lock capability indicates that the device supports the
locking of its configuration with a scope smaller then a complete locking of its configuration with a scope smaller then a complete
configuration datastore. Partial locking covers configuration data, configuration datastore. The scope to be locked is specified by
but not state data. using restricted or full XPath expressions. Partial locking covers
configuration data, but not state data.
The system will ensure that configuration resources covered by the The system ensures that configuration resources covered by the lock
lock will not be modified by other NETCONF or non-NETCONF management are not be 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 and lasting until either the corresponding
<partial-unlock> operation succeeds or the NETCONF session <partial-unlock> operation succeeds or the NETCONF session
terminates. 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
locked using partial lock operations. The <partial-lock> operation locked using partial lock operations. The <partial-lock> operation
returns a lock-id to identify each successfully acquired lock. returns a lock-id to identify each successfully acquired lock.
2.2. Dependencies 2.2. Dependencies
If the :xpath capability is supported, the filter expressions can be Partial locking uses only restricted XPath expressions to describe
full XPath 1.0 expressions. the lock's scope, as described in Section 2.4.1 for the select
element. However if optionally the :xpath capability is also
supported, partial locking can utilize any Xpath 1.0 expression.
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 filter data store. The portion to lock is specified by using XPath
parameters in the <partial-lock> operation. Each XPath expression expressions in the select elements of the <partial-lock> operation.
MUST return a node set. Each XPath expression MUST return a node set.
The XPath filter 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 XPath filter 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 nodeset Conceptually the scope of the lock is defined by the returned nodeset
and not by the XPath expression. and not by the XPath expression.
A <partial-lock> operation MUST be handled atomically by the NETCONF A <partial-lock> operation MUST be handled atomically by the NETCONF
server. The server either locks all requested parts of the data server. The server either locks all requested parts of the data
store or none. store or none.
If a node is locked by a session, only that same session will be able If a node is locked by a session, only that same session is able to
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. can recreate it, as it is not covered by the lock anymore.
A partial lock MUST fail if: A partial lock 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
skipping to change at page 5, line 18 skipping to change at page 5, line 25
locked. To avoid this situation, clients SHOULD lock everything they locked. To avoid this situation, clients SHOULD lock everything they
need in one operation. If that operation still fails, the client need in one operation. If that operation still fails, the client
SHOULD back down, release any already acquired locks, and retry the SHOULD back down, release any already acquired locks, and retry the
procedure after some time interval. The length of the interval procedure after some time interval. The length of the interval
should preferably be random to avoid repeated dead-locks when both should preferably be random to avoid repeated dead-locks when both
(or all) clients back down and then repeat locking. (or all) clients back down and then repeat locking.
It is the intention to keep partial-locking simple, so when a partial It is the intention to keep partial-locking simple, so when a partial
lock is executed you get what you asked for: a set of nodes that are lock is executed you get what you asked for: a set of nodes that are
locked for writing. There are some other issues that are locked for writing. There are some other issues that are
intentionally not addressed to for the sake of simplicity. intentionally not addressed for the sake of simplicity.
o Locking does not effect read operations. o Locking does not effect read operations.
o If a part of a datastore is locked, this has no effect on any o If a part of a datastore is locked, this has no effect on any
unlocked parts of the datastore. If this is a problem e.g. the unlocked parts of the datastore. If this is a problem e.g. the
operators changes depend on data values in the unlocked part of operator's changes depend on data values in the unlocked part of
the datastore, the operator should include these values in the the datastore, the operator should include these values in the
scope of the lock. scope of the lock.
o An operator is allowed to edit the configuration both inside and o An operator is allowed to edit the configuration both inside and
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 [RFC4741]. If part of operation defined in the base NETCONF Protocol [RFC4741]. 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 will fail even if the global lock is attempted by for that datastore fails even if the global lock is attempted by the
the same NETCONF session which owns the partial-lock. same NETCONF session which owns the partial-lock.
Parameters: Parameters:
target: Name of the configuration datastore of which a part will be target: Name of the configuration datastore of which a part shall be
locked. URIs are not accepted. locked. URLs are not accepted.
select: One or more 'select' elements each contain an XPath filter 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
on the select element. on the select element.
The filter MUST return a node set. The select expressions MUST return a node set.
If the device does not support the :xpath capability, the XPath If the device supports the :xpath capability as well any valid
expression MUST be limited to an Instance Identifier expression XPath 1.0 expression can be used, if not, the XPath expression
[Editor's Note: add text or reference. An Instance Identifier is MUST be limited to an Instance Identifier expression [Editor's
an absolute path expression in abbreviated syntax, where Note: add text or reference]. An Instance Identifier is an
predicates are used only to specify values for nodes defined as absolute path expression in abbreviated syntax, where predicates
keys to distinguish multiple instances.] are used only to specify values for nodes defined as keys to
distinguish multiple instances.]
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>
skipping to change at page 6, line 46 skipping to change at page 7, line 11
</nc:rpc-reply> </nc:rpc-reply>
Positive Response: Positive Response:
If the device was able to satisfy the request, an <rpc-reply> is sent If the device was able to satisfy the request, an <rpc-reply> is sent
with a <lock-id> element (lock identifier) in the <data> element. with a <lock-id> element (lock identifier) in the <data> element.
Negative Response: Negative Response:
If a lock is already held on any node within the subtrees to be If a lock is already held on any node within the subtrees to be
locked, the <error-tag> element will be 'lock-denied' and the <error- locked, the <error-tag> element shall be 'lock-denied' and the
info> element will include the <session-id> of the lock owner. If <error-info> element shall include the <session-id> of the lock
the lock is held by a non-NETCONF entity, a <session-id> of 0 (zero) owner. If the lock is held by a non-NETCONF entity, a <session-id>
is included. of 0 (zero) is included.
If the select filters return an empty node set, the <error-tag> will If the select expressions return an empty node set, the <error-tag>
be 'operation-failed', and the <error-app-tag> will be 'no-matches'. shall be 'operation-failed', and the <error-app-tag> shall be 'no-
matches'.
If any select filter returns anything but a node set, the <error-tag> If any select expression returns anything but a node set, the <error-
will be 'invalid-value'. tag> shall be 'invalid-value'.
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> will be 'invalid-value'. not an Instance Identifier, the <error-tag> shall be 'invalid-value'.
If access control denies the partial lock, the <error-tag> will be If access control denies the partial lock, the <error-tag> shall be
'access-denied'. 'access-denied'.
2.4.2. <partial-unlock> 2.4.2. <partial-unlock>
The operation unlocks a part of a datastore that was previously The operation unlocks a part of a datastore that was previously
locked using <partial-lock> during the same session. locked using <partial-lock> during the same session.
Parameters: Parameters:
lock-id: Lock identifier to unlock; taken from a reply to a previous lock-id: Lock identifier to unlock; taken from a reply to a previous
skipping to change at page 8, line 37 skipping to change at page 9, line 7
3. Security Considerations 3. Security Considerations
The same considerations as for the base NETCONF Protocol [RFC4741] The same considerations as for the base NETCONF Protocol [RFC4741]
are valid. It is assumed that the <partial-lock> and <partial- are valid. It is assumed that the <partial-lock> and <partial-
unlock> RPCs are only allowed for an authenticated user after passing unlock> RPCs are only allowed for an authenticated user after passing
some access control mechanism. some access control mechanism.
4. IANA Considerations 4. IANA Considerations
The capability's URI should be registered by IANA. This document registers a URN for the the following NETCONF
capability in the netconf registry (RFC4741], sect 10.3):
5. Change Log +---------------+---------------------------------------------------+
| Index | Capability Identifier |
+---------------+---------------------------------------------------+
| :partial-lock | urn:ietf:params:netconf:capability:partial-lock:1 |
| | .0 |
+---------------+---------------------------------------------------+
draft-00 Initial version 5. Appendix A - Change Log
5.1. Open Issues 5.1. Open Issues
Shall we allow the locking of non-existent nodes? The operator Shall we allow the locking of non-existent nodes? The operator
might want to reserve an object or rather its key/name even if he might want to reserve an object or rather its key/name even if he
will create the object later. will create the object later.
Should we include more detailed information in error results to Should we include more detailed information in error results to
help debug lock conflicts, e.g. the userId of the conflicting help debug lock conflicts, e.g. the userId of the conflicting
session, the XPATH expression of the conflicting session, the session, the XPath expression of the conflicting session, the
instanceId of the first object where the lock conflict was found? instanceId of the first object where the lock conflict was found?
Should we allow users to lock parts of multiple datastores (e.g. Should we allow users to lock parts of multiple datastores (e.g.
/top/routing both in the candidate and the running datastore) in /top/routing both in the candidate and the running datastore) in
one operation? This would decrease the probability of a dead- one operation? This would decrease the probability of a dead-
lock, but currently the (global) <lock> operation doesn't support lock, but currently the (global) <lock> operation doesn't support
this. this.
6. XML Schema for Partial Locking 5.2. -00
Created from draft-lengyel-ngo-partial-lock-01.txt
5.3. 00-01
Added YANG module.
6. Appendix B - YANG Module for Partial Locking (non-normative)
The following Yang modul defines the <partial-lock> and <partial-
unlock> operations.
This and the following Appendix are non-normative as the method to
define NETCONF operations is not yet agreed. Either the YANG or the
XSD or some other model will later probably become normative.
module netconf-partial-lock {
namespace urn:ietf:params:xml:ns:netconf:partial-lock:1.0;
prefix pl;
organization "IETF NETCONF Working Group";
contact
"Balazs Lengyel
Ericsson Hungary, Inc.
balazs.lengyel@ericsson.com";
description
"This YANG module defines the <partial-lock> and
<partial-unlock> operations.";
revision 2008-01-07 {
description "Inital version.";
}
grouping configName {
description
"A choice to list the datastore names for NETCONF.
This could be moved to a netconf.yang module.";
choice configNameType {
leaf running { type empty; }
leaf candidate { type empty; }
leaf startup { type empty; }
}
}
rpc partial-lock {
input {
uses configName;
leaf-list select {
type string;
min-elements 1;
}
}
output {
leaf lockId { type uint32; }
}
}
rpc partial-unlock {
input {
leaf lockId { type uint32; }
}
}
}
7. Appendix C - XML Schema for Partial Locking (non-normative)
The following XML Schema defines the <partial-lock> and <partial- The following XML Schema defines the <partial-lock> and <partial-
unlock> operations: unlock> operations:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0" 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"
targetNamespace="urn:ietf:params:xml:ns:netconf:partial-lock:1.0" targetNamespace="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"
elementFormDefault="qualified" attributeFormDefault="unqualified"> elementFormDefault="qualified" attributeFormDefault="unqualified">
skipping to change at page 10, line 24 skipping to change at page 15, line 5
<!-- <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"/>
</xs:schema> </xs:schema>
7. Acknowledgements 8. Acknowledgements
Thanks to Andy Bierman for providing important input to this Thanks to Andy Bierman, Sharon Chisholm, Phil Shafer and many other
members of the NETCONF WG for providing important input to this
document. document.
8. Normative References 9. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC4741] "NETCONF Configuration Protocol", RFC 4741, December 2006. [RFC4741] "NETCONF Configuration Protocol", RFC 4741, December 2006.
Authors' Addresses Authors' Addresses
Balazs Lengyel Balazs Lengyel
Ericsson Hungary Ericsson Hungary
Email: balazs.lengyel@ericsson.com Email: balazs.lengyel@ericsson.com
 End of changes. 35 change blocks. 
62 lines changed or deleted 150 lines changed or added

This html diff was produced by rfcdiff 1.34. The latest version is available from http://tools.ietf.org/tools/rfcdiff/