--- 1/draft-ietf-netconf-partial-lock-05.txt 2009-02-06 17:12:02.000000000 +0100 +++ 2/draft-ietf-netconf-partial-lock-06.txt 2009-02-06 17:12:03.000000000 +0100 @@ -1,48 +1,54 @@ NETCONF B. Lengyel Internet-Draft Ericsson Intended status: Standards Track M. Bjorklund -Expires: June 11, 2009 Tail-f Systems - December 08, 2008 +Expires: August 10, 2009 Tail-f Systems + February 06, 2009 Partial Lock RPC for NETCONF - draft-ietf-netconf-partial-lock-05 + draft-ietf-netconf-partial-lock-06 Status of this Memo - By submitting this Internet-Draft, each author represents that any - 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 - aware will be disclosed, in accordance with Section 6 of BCP 79. + This Internet-Draft is submitted to IETF in full conformance with the + provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. - This Internet-Draft will expire on June 11, 2009. + This Internet-Draft will expire on August 10, 2009. Copyright Notice - Copyright (C) The IETF Trust (2008). + Copyright (c) 2009 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Abstract The NETCONF protocol defines the lock and unlock RPCs, used to lock entire configuration datastores. In some situations, a way to lock only parts of a configuration datastore is required. This document defines a capability-based extension to the NETCONF protocol for locking portions of a configuration datastore. Table of Contents @@ -60,33 +66,35 @@ 2.5. Modifications to Existing Operations . . . . . . . . . . . 11 2.6. Interactions with Other Capabilities . . . . . . . . . . . 12 2.6.1. Candidate Configuration Capability . . . . . . . . . . 12 2.6.2. Confirmed Commit Capability . . . . . . . . . . . . . 12 2.6.3. Distinct Startup Capability . . . . . . . . . . . . . 12 3. Security Considerations . . . . . . . . . . . . . . . . . . . 12 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 5. Appendix A - XML Schema for Partial Locking (normative) . . 14 6. Appendix B - YANG Module for Partial Locking (non-normative) . . . . . . . . . . . . . . . . . . . . . . . 18 - 7. Appendix C - Change Log . . . . . . . . . . . . . . . . . . 21 - 7.1. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 21 - 7.2. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 21 - 7.3. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 21 - 7.4. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 21 - 7.5. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 22 - 7.6. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 - 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 23 - 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 24 - 9.1. Normative References . . . . . . . . . . . . . . . . . . . 24 - 9.2. Informative References . . . . . . . . . . . . . . . . . . 24 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 25 - Intellectual Property and Copyright Statements . . . . . . . . . . 26 + 7. Appendix C - Usage Example - Reserving nodes for future + editing (non-normative) . . . . . . . . . . . . . . . . . . . 21 + 8. Appendix D - Change Log . . . . . . . . . . . . . . . . . . 26 + 8.1. 05-06 . . . . . . . . . . . . . . . . . . . . . . . . . . 26 + 8.2. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 26 + 8.3. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 26 + 8.4. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 26 + 8.5. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 27 + 8.6. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 27 + 8.7. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 + 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 28 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 + 10.1. Normative References . . . . . . . . . . . . . . . . . . . 29 + 10.2. Informative References . . . . . . . . . . . . . . . . . . 29 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 1. Introduction The [NETCONF] protocol describes the lock and unlock operations that operate on entire configuration datastores. Often, multiple management sessions need to be able to modify the configuration of a managed device in parallel. In these cases, locking only parts of a configuration datastore is needed. This document defines a capability based extension to the NETCONF protocol to support partial locking of NETCONF datastores using a mechanism based on the existing @@ -123,21 +131,21 @@ locking of its configuration with a more limited scope than a complete configuration datastore. The scope to be locked is specified by using restricted or full XPath expressions. Partial locking only affects configuration data. The system MUST ensure that configuration resources covered by the lock are not modified by other NETCONF or non-NETCONF management operations such as SNMP and the CLI. 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 operation succeeds or (2) the NETCONF session terminates. A NETCONF session MAY have multiple parts of one or more datastores (running, candidate, startup) locked using partial lock operations. The operation returns a lock-id to identify each successfully acquired lock. 2.1.1. Usage Scenarios @@ -398,44 +406,41 @@ If a lock is already held by another session on any node within the subtrees to be locked, the element is 'lock-denied' and the element includes the of the lock owner. If the lock is held by a non-NETCONF session, a of 0 (zero) is included. If needed the returned session-id may be used to the NETCONF session holding the lock. The same error response is returned if the requesting session already holds the (global) lock for the same datastore. + If any select expression is an invalid XPath expression, the is 'invalid-value'. + + If any select expression returns something other than a node set, the + is 'invalid-value', and the is 'not-a- + node-set'. + If all the select expressions return an empty node set, the is 'operation-failed', and the is 'no-matches'. - If any select expression returns something other than a node set, the - is 'invalid-value', the is 'not-a-node- - set'. + If any of the target datastors does not exist, the is + 'invalid-value', the is 'invalid-lock-specification' If the :xpath capability is not supported and the XPath expression is not an Instance Identifier, the is 'invalid-value', the is 'invalid-lock-specification'. If access control denies the partial lock, the is 'access-denied'. -2.4.1.2. Reserving nodes for future editing - - Partial lock cannot be used to lock non-existent nodes, which would - effectively attempt to reserve them for future use. To guarantee - that a node cannot be created by some other session, the parent node - should be locked, the top level node of the new section created, and - then locked with another operation. After this, the - lock on the parent node should be removed. - -2.4.1.3. Deadlock Avoidance +2.4.1.2. Deadlock Avoidance As with most locking systems, it is possible that two management sessions trying to lock different parts of the configuration could become dead-locked. To avoid this situation, clients should lock everything they need in one operation. If locking fails, the client should back-off, release any previously acquired locks, and retry the procedure after waiting some randomized time interval. 2.4.2. @@ -472,26 +477,31 @@ the session, an 'invalid-value' error is returned. 2.5. Modifications to Existing Operations A successful partial lock will cause a subsequent operation to fail if that attempts to modify nodes in the protected area of the lock and is executed in a NETCONF session other than the session that has been granted the lock. The 'in-use' and the 'locked' is returned. All operations that modify the datastore are affected, including: , , , and . If a datastore contains - nodes locked by partial lock, this will cause the (global) - operation to fail. The element 'lock-denied' and an - element including the of the lock owner - will be returned. If the lock is held by a non-NETCONF session, a - of 0 (zero) is returned. + config>, and . If partial lock prevents + modifying some data, but the operation includes the + continue-on-error option, modification of other parts of the + datastore, which are not protected by partial locking, might still + succeed. + + If a datastore contains nodes locked by partial lock, this will cause + the (global) operation to fail. The element + 'lock-denied' and an element including the + of the lock owner will be returned. If the lock is held by a non- + NETCONF session, a of 0 (zero) is returned. All of these operations are affected only if they are targeting the same datastore. 2.6. Interactions with Other Capabilities 2.6.1. Candidate Configuration Capability Partial locking of the candidate datastore can only be done if the :candidate capability is supported by the device. Partial locking of @@ -585,24 +595,32 @@ Schema defining the partial-lock and unlock operations. organization "IETF NETCONF Working Group" + contact - "Balazs Lengyel - Ericsson Hungary, Inc. + Netconf Working Group + Mailing list: netconf@ietf.org + Web: http://www.ietf.org/html.charters/netconf-charter.html + + Balazs Lengyel balazs.lengyel@ericsson.com" + + revision 2009-01-23 + description Initial version, published as RFC yyyy. + -- RFC Ed.: replace yyyy with actual RFC number & remove this note. A number identifying a specific @@ -761,151 +779,346 @@ The following YANG module defines the and operations. The YANG language is defined in [I-D.ietf-netmod-yang]. module ietf-netconf-partial-lock { namespace urn:ietf:params:xml:ns:netconf:partial-lock:1.0; prefix pl; - organization "IETF NETCONF Working Group"; + organization "IETF Network Configuration (netconf) Working Group"; contact - "Balazs Lengyel + "Netconf Working Group + Mailing list: netconf@ietf.org + Web: http://www.ietf.org/html.charters/netconf-charter.html + + Balazs Lengyel Ericsson balazs.lengyel@ericsson.com"; description "This YANG module defines the and operations."; - revision 2008-12-08 { - description "Initial version."; + revision 2009-01-23 { + description + "Initial version, published as RFC yyyy."; + // RFC Ed.: replace yyyy with actual RFC number & remove this note. } typedef lock-id-type { - description "A number identifying a specific - partial-lock granted to a session. - It is allocated by the system, and SHOULD - be used in the partial-unlock operation."; type uint32; + description + "A number identifying a specific partial-lock granted to a session. + It is allocated by the system, and SHOULD be used in the + partial-unlock operation."; } rpc partial-lock { description "A NETCONF operation that locks part of one or more datastores."; input { list target { - description "A list of one or more datastore names. - Each list entry must contain a different datastore name."; min-elements 1; max-elements 3; + description + "A list of one or more datastore names. + Each list entry must contain a different datastore name."; choice datastore { leaf running { type empty; } leaf candidate { type empty; } leaf startup { type empty; } } } leaf-list select { + type string; + min-elements 1; description "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."; - type string; - min-elements 1; } } output { leaf lock-id { + type lock-id-type; description "Identifies the lock, if granted. The lock-id SHOULD be used in the partial-unlock rpc."; - type lock-id-type; } container running { leaf-list locked-node { - description "List of locked nodes - in the running datastore"; type instance-identifier; + min-elements 1; + description + "List of locked nodes in the running datastore"; } } container candidate { leaf-list locked-node { - description "List of locked nodes - in the candidate datastore"; type instance-identifier; + min-elements 1; + description + "List of locked nodes in the candidate datastore"; } } container startup { leaf-list locked-node { - description "List of locked nodes - in the startup datastore"; type instance-identifier; + min-elements 1; + description + "List of locked nodes in the startup datastore"; } } } } rpc partial-unlock { description "A NETCONF operation that releases a previously acquired partial-lock."; input { leaf lock-id { + type lock-id-type; description "Identifies the lock to be released. MUST be the value received in the response to the partial-lock operation."; - type lock-id-type; } } } } -7. Appendix C - Change Log +7. Appendix C - Usage Example - Reserving nodes for future editing + (non-normative) -7.1. 04-05 + Partial lock cannot be used to lock non-existent nodes, which would + effectively attempt to reserve them for future use. To guarantee + that a node cannot be created by some other session, the parent node + should be locked, the top level node of the new subtree created, and + then locked with another operation. After this, the + lock on the parent node should be removed. + + In this chapter an example illustrating the above is given. + + We want to create Joe under , and start editing it. + Editing might take a number of minutes. We want to immediately lock + Joe so no one will touch it before we are finished with the editing. + + We also want to minimize locking other parts of the datastore as + multiple managers might be adding users near simultaneously. + + First we check what users are already defined. + + Step 1 - Read existing users + + + + + + + + + + + + + + + The NETCONF server sends the following reply. + + Step 2 - Receiving existing data + + + + + + + fred + 8327 + + + + + + + We want to add the new user "Joe" and immediately lock him using + partial locking. The way to do this, is to first lock all + nodes by locking the node. + + Step 3 - Lock users + + + + + + + + + + + The NETCONF server grants the partial lock. The scope of the lock + includes only the node. The lock protects the node + and all nodes below it from modification (by other sessions). + + Step 4 - Receive lock + + + 1 + + + /usr:top/usr:users + + + + + Next we create user Joe. Joe is protected by the lock received above, + as it is under the sub-tree rooted at the node. + + Step 5 - Create user Joe + + + + + + + + + + + Joe + + + + + + + + We receive a positive reply to the (not shown). Next + we request a lock, that locks only Joe, and release the lock + on the node. This will allow other managers to create + additional new users. + + Step 6 - Lock user Joe + + + + + + + + + + + The NETCONF server grants the partial lock. The scope of this second + lock includes only the node with name Joe. The lock protects + all data below this particular node. + + Step 7 - Receive lock + + + 2 + + + /usr:top/usr:users/user[usr:name="Joe"]" + + + + + The scope of the second lock is the node Joe. It protects this + node and any data below it (e.g. phone number). At this point + of time these nodes are protected both by the first and second lock. + Next we unlock the other s and the node, to allow other + managers to work on them. We still keep the second lock, so the + node Joe and the sub-tree below is still protected. + + Step 8 - Release lock on + + + + 1 + + + +8. Appendix D - Change Log + +8.1. 05-06 + + Added usage example + + Clarified error messages + + Clarified interaction with edit-config continue-on-error + + Improved YANG: indentation, canonical order, contact info + + Added usage example in appendix C + + Synchronized YANG and XSD + +8.2. 04-05 Language and editorial updates all app-tags are with dashes without spaces Added usage scenarios Changed encoding Clarified definitions, separated scope of lock and protected area -7.2. 03-04 +8.3. 03-04 Minor clarifications Added list of locked-nodes to the output of partial-lock. Added wrapper around datastore names. Allowed atomic/one operation locking of datastore parts in multiple datastores. Improved English (hopefully) Removed the element from rpc-reply following the text of rfc4741. -7.3. 02-03 +8.4. 02-03 Minor clarifications - Same descriptions in XSD and YANG. -7.4. 01-02 +8.5. 01-02 Made XSD normative Clarified that no specific access control is assumed. 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 granted. Some rewording @@ -902,106 +1115,63 @@ Made XSD normative Clarified that no specific access control is assumed. 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 granted. Some rewording + Added app-tags for two of the error cases. Made YANG an informative reference Enhanced security considerations. -7.5. 00-01 +8.6. 00-01 Added YANG module. -7.6. -00 +8.7. -00 Created from draft-lengyel-ngo-partial-lock-01.txt -8. Acknowledgements +9. Acknowledgements Thanks to Andy Bierman, Sharon Chisholm, Phil Shafer , David - Harrington, Mehmet Ersue, Wes Hardaker and many other members of the - NETCONF WG for providing important input to this document. + Harrington, Mehmet Ersue, Wes Hardaker, Juergen Schoenwaelder and + many other members of the NETCONF WG for providing important input to + this document. -9. References +10. References -9.1. Normative References +10.1. Normative References [NETCONF] Enns, R., "NETCONF Configuration Protocol", RFC 4741, December 2006. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. -9.2. Informative References +10.2. Informative References [I-D.ietf-netmod-yang] Bjorklund, M., "YANG - A data modeling language for - NETCONF", draft-ietf-netmod-yang-02 (work in progress), - November 2008. + NETCONF", draft-ietf-netmod-yang-03 (work in progress), + January 2009. Authors' Addresses Balazs Lengyel Ericsson Email: balazs.lengyel@ericsson.com Martin Bjorklund Tail-f Systems Email: mbj@tail-f.com - -Full Copyright Statement - - Copyright (C) The IETF Trust (2008). - - This document is subject to the rights, licenses and restrictions - contained in BCP 78, and except as set forth therein, the authors - retain all their rights. - - This document and the information contained herein are provided on an - "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS - OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND - THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS - OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF - THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED - WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. - -Intellectual Property - - The IETF takes no position regarding the validity or scope of any - Intellectual Property Rights or other rights that might be claimed to - pertain to the implementation or use of the technology described in - this document or the extent to which any license under such rights - might or might not be available; nor does it represent that it has - made any independent effort to identify any such rights. Information - on the procedures with respect to rights in RFC documents can be - found in BCP 78 and BCP 79. - - Copies of IPR disclosures made to the IETF Secretariat and any - assurances of licenses to be made available, or the result of an - attempt made to obtain a general license or permission for the use of - such proprietary rights by implementers or users of this - specification can be obtained from the IETF on-line IPR repository at - http://www.ietf.org/ipr. - - The IETF invites any interested party to bring to its attention any - copyrights, patents or patent applications, or other proprietary - rights that may cover technology that may be required to implement - this standard. Please address the information to the IETF at - ietf-ipr@ietf.org. - -Acknowledgment - - Funding for the RFC Editor function is provided by the IETF - Administrative Support Activity (IASA).