idnits 2.17.1 draft-ietf-netconf-partial-lock-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 20, 2009) is 5301 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 4741 (ref. 'NETCONF') (Obsoleted by RFC 6241) == Outdated reference: A later version (-13) exists of draft-ietf-netmod-yang-07 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF B. Lengyel 3 Internet-Draft Ericsson 4 Intended status: Standards Track M. Bjorklund 5 Expires: April 23, 2010 Tail-f Systems 6 October 20, 2009 8 Partial Lock RPC for NETCONF 9 draft-ietf-netconf-partial-lock-11 11 Status of this Memo 13 This Internet-Draft is submitted to IETF in full conformance with the 14 provisions of BCP 78 and BCP 79. This document may contain material 15 from IETF Documents or IETF Contributions published or made publicly 16 available before November 10, 2008. The person(s) controlling the 17 copyright in some of this material may not have granted the IETF 18 Trust the right to allow modifications of such material outside the 19 IETF Standards Process. Without obtaining an adequate license from 20 the person(s) controlling the copyright in such materials, this 21 document may not be modified outside the IETF Standards Process, and 22 derivative works of it may not be created outside the IETF Standards 23 Process, except to format it for publication as an RFC or to 24 translate it into languages other than English. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF), its areas, and its working groups. Note that 28 other groups may also distribute working documents as Internet- 29 Drafts. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 The list of current Internet-Drafts can be accessed at 37 http://www.ietf.org/ietf/1id-abstracts.txt. 39 The list of Internet-Draft Shadow Directories can be accessed at 40 http://www.ietf.org/shadow.html. 42 This Internet-Draft will expire on April 23, 2010. 44 Copyright Notice 46 Copyright (c) 2009 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents in effect on the date of 51 publication of this document (http://trustee.ietf.org/license-info). 52 Please review these documents carefully, as they describe your rights 53 and restrictions with respect to this document. 55 Abstract 57 The NETCONF protocol defines the lock and unlock RPCs, used to lock 58 entire configuration datastores. In some situations, a way to lock 59 only parts of a configuration datastore is required. This document 60 defines a capability-based extension to the NETCONF protocol for 61 locking portions of a configuration datastore. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 1.1. Definition of Terms . . . . . . . . . . . . . . . . . . . 4 67 2. Partial Locking Capability . . . . . . . . . . . . . . . . . . 4 68 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 69 2.1.1. Usage Scenarios . . . . . . . . . . . . . . . . . . . 5 70 2.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 6 71 2.3. Capability Identifier . . . . . . . . . . . . . . . . . . 6 72 2.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 6 73 2.4.1. . . . . . . . . . . . . . . . . . . . . 6 74 2.4.2. . . . . . . . . . . . . . . . . . . . 10 75 2.5. Modifications to Existing Operations . . . . . . . . . . . 11 76 2.6. Interactions with Other Capabilities . . . . . . . . . . . 12 77 2.6.1. Candidate Configuration Capability . . . . . . . . . . 12 78 2.6.2. Confirmed Commit Capability . . . . . . . . . . . . . 12 79 2.6.3. Distinct Startup Capability . . . . . . . . . . . . . 12 80 3. Security Considerations . . . . . . . . . . . . . . . . . . . 12 81 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 82 5. Appendix A - XML Schema for Partial Locking (normative) . . 15 83 6. Appendix B - YANG Module for Partial Locking 84 (non-normative) . . . . . . . . . . . . . . . . . . . . . . . 18 85 7. Appendix C - Usage Example - Reserving nodes for future 86 editing (non-normative) . . . . . . . . . . . . . . . . . . . 20 87 8. Appendix D - Change Log . . . . . . . . . . . . . . . . . . 24 88 8.1. 10-11 . . . . . . . . . . . . . . . . . . . . . . . . . . 24 89 8.2. 09-10 . . . . . . . . . . . . . . . . . . . . . . . . . . 24 90 8.3. 08-09 . . . . . . . . . . . . . . . . . . . . . . . . . . 24 91 8.4. 07-08 . . . . . . . . . . . . . . . . . . . . . . . . . . 24 92 8.5. 06-07 . . . . . . . . . . . . . . . . . . . . . . . . . . 24 93 8.6. 05-06 . . . . . . . . . . . . . . . . . . . . . . . . . . 24 94 8.7. 04-05 . . . . . . . . . . . . . . . . . . . . . . . . . . 24 95 8.8. 03-04 . . . . . . . . . . . . . . . . . . . . . . . . . . 25 96 8.9. 02-03 . . . . . . . . . . . . . . . . . . . . . . . . . . 25 97 8.10. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 25 98 8.11. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 25 99 8.12. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 100 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 27 101 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 102 10.1. Normative References . . . . . . . . . . . . . . . . . . . 28 103 10.2. Informative References . . . . . . . . . . . . . . . . . . 28 104 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29 106 1. Introduction 108 The [NETCONF] protocol describes the lock and unlock operations that 109 operate on entire configuration datastores. Often, multiple 110 management sessions need to be able to modify the configuration of a 111 managed device in parallel. In these cases, locking only parts of a 112 configuration datastore is needed. This document defines a 113 capability based extension to the NETCONF protocol to support partial 114 locking of the NETCONF running datastore using a mechanism based on 115 the existing XPath filtering mechanisms. 117 1.1. Definition of Terms 119 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 120 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 121 "OPTIONAL" in this document are to be interpreted as described in BCP 122 14, [RFC2119]. 124 Additionally the following terms are defined: 126 o Instance Identifier: an XPath expression identifying a specific 127 node in the conceptual XML datastore. It contains an absolute 128 path expression in abbreviated syntax, where predicates are used 129 only to specify values for nodes defined as keys to distinguish 130 multiple instances. 132 o Scope of the lock: initially the set of nodes returned by the 133 XPath expressions in a successful partial-lock operation. The set 134 might be modified if some of the nodes are deleted by the session 135 owning the lock. 137 o Protected area: the set of nodes that are protected from 138 modification by the lock. This set consists of nodes in the scope 139 of the lock and nodes in subtrees under them. 141 2. Partial Locking Capability 143 2.1. Overview 145 The :partial-lock capability indicates that the device supports the 146 locking of its configuration with a more limited scope than a 147 complete configuration datastore. The scope to be locked is 148 specified by using restricted or full XPath expressions. Partial 149 locking only affects configuration data and only the running 150 datastore. The candidate or the start-up datastore are not affected. 152 The system MUST ensure that configuration resources covered by the 153 lock are not modified by other NETCONF or non-NETCONF management 154 operations such as SNMP and the CLI. 156 The duration of the partial lock begins when the partial lock is 157 granted and lasts until (1) either the corresponding 158 operation succeeds or (2) the NETCONF session terminates. 160 A NETCONF session MAY have multiple parts of the running datastore 161 locked using partial lock operations. 163 The operation returns a lock-id to identify each 164 successfully acquired lock. The lock-id is unique at any given time 165 for a NETCONF server for all partial-locks granted to any NETCONF or 166 non-NETCONF sessions. 168 2.1.1. Usage Scenarios 170 In the following we describe a few scenarios for partial locking. 171 Besides the two described here, there are many other usage scenarios 172 possible. 174 2.1.1.1. Multiple managers handling the writable running datastore with 175 overlapping sections 177 Multiple managers are handling the same NETCONF agent simultaneously. 178 The agent is handled via the writable running datastore. Each 179 manager has his or her own task, which might involve the modification 180 of overlapping sections of the datastore. 182 After collecting and analyzing input and preparing the NETCONF 183 operations off-line, the manager locks the areas that are important 184 for his task using one single operation. The manager 185 executes a number of operations to modify the 186 configuration, then releases the partial-lock. The lock should be 187 held for the shortest possible time (e.g. seconds rather then 188 minutes). The manager should collect all human input before locking 189 anything. As each manager locks only a part of the data model, 190 usually multiple operators can execute the operations 191 simultaneously. 193 2.1.1.2. Multiple managers handling the writable running datastore, 194 distinct management areas 196 Multiple managers are handling the same NETCONF agent simultaneously. 197 The agent is handled via the writable running datastore. The agent's 198 data model contains a number of well defined separate areas that can 199 be configured without impacting other areas. An example can be a 200 server with multiple applications running on it, or a number of a 201 network elements with a common NETCONF agent for management. 203 Each manager has his or her own task, which does not involve the 204 modification of overlapping sections of the datastore. 206 The manager locks his area with a operation, uses a 207 number of commands to modify it, later releases the 208 lock. As each manager has his functional area assigned to him, and 209 he locks only that area, multiple managers can edit the configuration 210 simultaneously. Locks can be held for extended periods (e.g. 211 minutes, hours), as this will not hinder other managers. 213 This scenario assumes that the global lock operation from [NETCONF] 214 is not used. 216 2.2. Dependencies 218 The device MUST support restricted XPath expressions in the select 219 element, as described in Section 2.4.1. Optionally, if the :xpath 220 capability is also supported (as defined in [NETCONF] chapter 8.9. 221 XPath Capability), the device MUST also support using any XPath 1.0 222 expression in the select element. 224 2.3. Capability Identifier 226 urn:ietf:params:netconf:capability:partial-lock:1.0 228 2.4. New Operations 230 2.4.1. 232 The operation allows the client to lock a portion of 233 the running datastore. The portion to lock is specified with XPath 234 expressions in the "select" elements in the operation. 235 Each XPath expression MUST return a node set. 237 When a NETCONF session holds a lock on a node, no other session or 238 non-NETCONF mechanism of the system can change that node or any node 239 in the hierarchy of nodes beneath it. 241 Locking a node protects the node itself and the complete subtree 242 under the node from modification by others. The set of locked nodes 243 is called the scope of the lock, while all the locked nodes and the 244 nodes in the subtrees under them make up the protected area. 246 The XPath expressions are evaluated only once at lock time. 247 Thereafter, the scope of the lock is maintained as a set of nodes, 248 i.e. the returned nodeset, and not by the XPath expression. If the 249 configuration data is later altered in a way that would make the 250 original XPath expressions evaluate to a different set of nodes, this 251 does not affect the scope of the partial lock. 253 Let's say the agent's data model includes a list of interface nodes. 254 If the XPath expression in the partial lock operation covers all 255 interface nodes at locking, the scope of the lock will be maintained 256 as the list of interface nodes at the time when the lock was granted. 257 If someone later creates a new interface, this new interface will not 258 be included in the locked-nodes list created previously so the new 259 interface will not be locked. 261 A operation MUST be handled atomically by the NETCONF 262 server. The server either locks all requested parts of the datastore 263 or none. If during the operation one of the requested 264 parts cannot be locked, the server MUST unlock all parts that have 265 already been locked during that operation. 267 If a node in the scope of the lock is deleted by the session owning 268 the lock, it is removed from the scope of the lock, so any other 269 session or non-NETCONF mechanism can recreate it. If all nodes in 270 the scope of the lock are deleted, the lock will still be present. 271 However, its scope will become empty (since the lock will not cover 272 any nodes). 274 A NETCONF server that supports partial locking MUST be able to grant 275 multiple simultaneous partial locks to a single NETCONF session. If 276 the protected area of the individual locks overlap, nodes in the 277 common area MUST be protected until all of the overlapping locks are 278 released. 280 A partial lock operation MUST fail if: 282 o Any NETCONF session (including the current session) owns the 283 global lock on the running datastore. 285 o Any part of the area to be protected is already locked (or 286 protected by partial locking) by another management session, 287 including other NETCONF sessions using or any other 288 non-NETCONF management method. 290 o The requesting user is not successfully authenticated. 292 o The NETCONF server implements access control, and the locking user 293 does not have sufficient access rights. The exact handling of 294 access rights is outside the scope of this document, but it is 295 assumed that there is an access control system that MAY deny or 296 allow the partial lock operation. 298 The operation is designed for simplicity, so when a 299 partial lock is executed you get what you asked for: a set of nodes 300 that are locked for writing. As a consequence users must observe the 301 following: 303 o Locking does not affect read operations. 305 o If part of the running datastore is locked, this has no effect on 306 any unlocked parts of the datastore. If this is a problem (e.g., 307 changes depend on data values or nodes outside the protected part 308 of the datastore), these nodes SHOULD be included in the protected 309 area of the lock. 311 o Configuration data can be edited both inside and outside the 312 protected area of a lock. It is the responsibility of the NETCONF 313 client application to lock all relevant parts of the datastore 314 that are crucial for a specific management action. 316 Note: The operation does not modify the global 317 operation defined in the base NETCONF Protocol [NETCONF]. If part of 318 the running datastore is already locked by , then a 319 global lock for the running datastore MUST fail even if the global 320 lock is requested by the NETCONF session that owns the partial lock. 322 2.4.1.1. Parameters, Result, Examples 324 Parameters: 326 select: One or more 'select' elements, each containing an XPath 327 expression. The XPath expression is evaluated in a context where 328 the context node is the root of the server's conceptual data 329 model, and the set of namespace declarations are those in scope 330 on the select element. 332 The nodes returned from the select expressions are reported in 333 the rpc-reply message. 335 Each select expression MUST return a node set, and at least one 336 of the node sets MUST be non-empty. 338 If the device supports the :xpath capability, any valid XPath 1.0 339 expression can be used. If the device does not support the 340 :xpath capability, the XPath expression MUST be limited to an 341 Instance Identifier expression. An Instance Identifier is an 342 absolute path expression in abbreviated syntax, where predicates 343 are used only to specify values for nodes defined as keys to 344 distinguish multiple instances. 346 Example: Lock virtual router 1 and interface eth1 348 352 353 356 359 360 362 366 127 367 368 /rte:routing/rte:virtualRouter[rte:routerName='router1'] 369 370 371 /if:interfaces/if:interface[if:id='eth1'] 372 373 375 Note: The XML Schema in [NETCONF] has a known bug which requires the 376 XML element in a . This means that the above 377 examples will not validate using the XML Schema found in [NETCONF]. 379 Positive Response: 381 If the device was able to satisfy the request, an is sent 382 with a element (lock identifier) in the 383 element. A list of locked nodes is also returned in Instance 384 Identifier format. 386 Negative Response: 388 If any select expression is an invalid XPath expression, the is 'invalid-value'. 391 If any select expression returns something other than a node set, the 392 is 'invalid-value', and the is 'not-a- 393 node-set'. 395 If all the select expressions return an empty node set, the is 'operation-failed', and the is 'no-matches'. 398 If the :xpath capability is not supported and the XPath expression is 399 not an Instance Identifier, the is 'invalid-value', the 400 is 'invalid-lock-specification'. 402 If access control denies the partial lock, the is 403 'access-denied'. Access control SHOULD be checked before checking 404 for conflicting locks to avoid giving out information about other 405 sessions to an unauthorized client. 407 If a lock is already held by another session on any node within the 408 subtrees to be locked, the element is 'lock-denied' and 409 the element includes the of the lock owner. 410 If the lock is held by a non-NETCONF session, a of 0 411 (zero) SHOULD be included. The same error response is returned if 412 the requesting session already holds the (global) lock for the 413 running datastore. 415 If needed the returned session-id may be used to the 416 NETCONF session holding the lock. 418 2.4.1.2. Deadlock Avoidance 420 As with most locking systems, it is possible that two management 421 sessions trying to lock different parts of the configuration could 422 become dead-locked. To avoid this situation, clients SHOULD lock 423 everything they need in one operation. If locking fails, the client 424 MUST back-off, release any previously acquired locks, and SHOULD 425 retry the procedure after waiting some randomized time interval. 427 2.4.2. 429 The operation unlocks the parts of the running datastore that were 430 previously locked using during the same session. The 431 operation unlocks the parts that are covered by the lock identified 432 by the lock-id parameter. In case of multiple potentially 433 overlapping locks, only the lock identified by the lock-id is 434 removed. 436 Parameters: 438 lock-id: Identity of the lock to be unlocked. This lock-id MUST 439 have been received as a response to a lock request by the manager 440 during the current session, and MUST NOT have been sent in a 441 previous unlock request. 443 Example: Unlock a previously created lock 445 448 449 127 450 451 453 Positive Response: 455 If the device was able to satisfy the request, an is sent 456 that contains an element. A positive response MUST be sent even 457 if all of the locked parts of the datastore have already been 458 deleted. 460 Negative Response: 462 If the parameter does not identify a lock which is owned by 463 the session, an 'invalid-value' error is returned. 465 2.5. Modifications to Existing Operations 467 A successful partial lock will cause a subsequent operation to fail 468 if that operation attempts to modify nodes in the protected area of 469 the lock and is executed in a NETCONF session other than the session 470 that has been granted the lock. The 'in-use' and the 471 'locked' is returned. All operations that modify the 472 running datastore are affected, including: , , , and . If partial 474 lock prevents modifying some data, but the operation 475 includes the continue-on-error option, modification of other parts of 476 the datastore, which are not protected by partial locking, might 477 still succeed. 479 If the datastore contains nodes locked by partial lock, this will 480 cause the (global) operation to fail. The element 481 'lock-denied' and an element including the 482 of the lock owner will be returned. If the lock is held by a non- 483 NETCONF session, a of 0 (zero) is returned. 485 All of these operations are affected only if they are targeting the 486 running datastore. 488 2.6. Interactions with Other Capabilities 490 2.6.1. Candidate Configuration Capability 492 The candidate datastore can not be locked using the 493 operation. 495 2.6.2. Confirmed Commit Capability 497 If: 499 o a partial lock is requested for the running datastore, and 501 o the NETCONF server implements the :confirmed-commit capability, 502 and 504 o there was a recent confirmed operation where the 505 confirming operation has not been received 507 then the lock MUST be denied, because if the confirmation does not 508 arrive, the running datastore MUST be rolled back to its state before 509 the commit. The NETCONF server might therefore need to modify the 510 configuration. 511 In this case the 'in-use' and the 512 'outstanding-confirmed-commit' is returned. 514 2.6.3. Distinct Startup Capability 516 The startup datastore can not be locked using the 517 operation. 519 3. Security Considerations 521 The same considerations are relevant as for the base NETCONF Protocol 522 [NETCONF]. and RPCs MUST only be 523 allowed for an authenticated user. and RPCs SHOULD only be allowed for an authorized user. However 525 as NETCONF access control is not standardized and not a mandatory 526 part of a NETCONF implementation, it is strongly recommended, but 527 OPTIONAL. (although nearly all implementations include some kind of 528 access control) 529 A lock (either a partial lock or a global lock) might prevent other 530 users from configuring the system. The following mechanisms are in 531 place to prevent the misuse of this possibility: 533 A user, that is not successfully authenticated, MUST NOT be 534 granted a partial lock. 536 Only an authorized user SHOULD be able to request a partial lock. 538 The partial lock is automatically released when a session is 539 terminated regardless of how the session ends. 541 The operation makes it possible to terminate other 542 users's sessions. 544 The NETCONF server MAY log partial lock requests in an audit 545 trail. 547 A lock that is hung for some reason (e.g., a broken TCP connection 548 that the server has not yet recognised) can be released using another 549 NETCONF session by explicitly killing the session owning that lock 550 using the operation. 552 Partial locking is not an authorization mechanism; it SHOULD NOT be 553 used to provide security or access control. Partial locking SHOULD 554 only be used as a mechanism for providing consistency when multiple 555 managers are trying to configure the node. It is vital that users 556 easily understand the exact scope of a lock. This is why the scope 557 is determined when granting a lock and is not modified thereafter. 559 4. IANA Considerations 561 This document registers one capability identifier URN from the 562 "Network Configuration Protocol (NETCONF) Capability URNs" registry, 563 and one URI for the NETCONF XML namespace in the "IETF XML registry" 564 [RFC3688]. Note that the capability URN is compliant to [NETCONF] 565 section 10.3. 567 +---------------+---------------------------------------------------+ 568 | Index | Capability Identifier | 569 +---------------+---------------------------------------------------+ 570 | :partial-lock | urn:ietf:params:netconf:capability:partial-lock:1 | 571 | | .0 | 572 +---------------+---------------------------------------------------+ 573 URI: urn:ietf:params:xml:ns:netconf:partial-lock:1.0 575 Registrant Contact: The IESG. 577 XML: N/A, the requested URI is an XML namespace. 579 5. Appendix A - XML Schema for Partial Locking (normative) 581 The following XML Schema defines the and operations: 584 -- RFC Ed.: Insert license information for code as appropriate 585 587 588 594 595 596 Schema defining the partial-lock and unlock operations. 597 organization "IETF NETCONF Working Group" 599 contact 600 Netconf Working Group 601 Mailing list: netconf@ietf.org 602 Web: http://www.ietf.org/html.charters/netconf-charter.html 604 Balazs Lengyel 605 balazs.lengyel@ericsson.com" 607 revision 2009-10-19 608 description Initial version, published as RFC yyyy. 609 -- RFC Ed.: replace yyyy with actual RFC number and remove this note. 610 611 613 616 617 618 619 A number identifying a specific 620 partial-lock granted to a session. 621 It is allocated by the system, and SHOULD 622 be used in the unlock operation. 623 624 625 626 627 628 629 630 A NETCONF operation that locks parts of 631 the running datastore. 632 633 634 635 636 637 639 640 641 XPath expression that specifies the scope 642 of the lock. An Instance Identifier 643 expression must be used unless the :xpath 644 capability is supported in which case any 645 XPath 1.0 expression is allowed. 646 647 648 649 650 651 652 654 655 656 657 A NETCONF operation that releases a previously acquired 658 partial-lock. 659 660 661 662 663 664 665 666 667 Identifies the lock to be released. MUST 668 be the value received in the response to 669 the partial-lock operation. 670 671 672 673 674 676 677 679 680 683 684 687 689 690 691 692 The content of the reply to a successful 693 partial-lock request MUST conform to this complex type. 694 695 696 697 698 699 700 Identifies the lock to be released. Must be the value 701 received in the response to a partial-lock operation. 702 703 704 705 707 708 709 List of locked nodes in the running datastore. 710 711 712 713 714 715 717 719 6. Appendix B - YANG Module for Partial Locking (non-normative) 721 The following YANG module defines the and operations. The YANG language is defined in 723 [I-D.ietf-netmod-yang]. 725 -- RFC Ed.: Insert license information for code as appropriate 726 728 module ietf-netconf-partial-lock { 730 namespace urn:ietf:params:xml:ns:netconf:partial-lock:1.0; 731 prefix pl; 733 organization "IETF Network Configuration (netconf) Working Group"; 735 contact 736 "Netconf Working Group 737 Mailing list: netconf@ietf.org 738 Web: http://www.ietf.org/html.charters/netconf-charter.html 740 Balazs Lengyel 741 Ericsson 742 balazs.lengyel@ericsson.com"; 744 description 745 "This YANG module defines the and 746 operations."; 748 revision 2009-10-19 { 749 description 750 "Initial version, published as RFC yyyy."; 751 // RFC Ed.: replace yyyy with actual RFC number & remove this note. 752 } 754 typedef lock-id-type { 755 type uint32; 756 description 757 "A number identifying a specific partial-lock granted to a session. 758 It is allocated by the system, and SHOULD be used in the 759 partial-unlock operation."; 760 } 762 rpc partial-lock { 763 description 764 "A NETCONF operation that locks parts of the running datastore."; 765 input { 766 leaf-list select { 767 type string; 768 min-elements 1; 769 description 770 "XPath expression that specifies the scope of the lock. 771 An Instance Identifier expression MUST be used unless the 772 :xpath capability is supported, in which case any XPath 1.0 773 expression is allowed."; 774 } 775 } 776 output { 777 leaf lock-id { 778 type lock-id-type; 779 description 780 "Identifies the lock, if granted. The lock-id SHOULD be 781 used in the partial-unlock rpc."; 782 } 783 leaf-list locked-node { 784 type instance-identifier; 785 min-elements 1; 786 description 787 "List of locked nodes in the running datastore"; 788 } 789 } 790 } 792 rpc partial-unlock { 793 description 794 "A NETCONF operation that releases a previously acquired 795 partial-lock."; 796 input { 797 leaf lock-id { 798 type lock-id-type; 799 description 800 "Identifies the lock to be released. MUST be the value 801 received in the response to a partial-lock operation."; 802 } 803 } 804 } 805 } 807 809 7. Appendix C - Usage Example - Reserving nodes for future editing 810 (non-normative) 812 Partial lock cannot be used to lock non-existent nodes, which would 813 effectively attempt to reserve them for future use. To guarantee 814 that a node cannot be created by some other session, the parent node 815 should be locked, the top level node of the new subtree created, and 816 then locked with another operation. After this, the 817 lock on the parent node should be removed. 819 In this chapter an example illustrating the above is given. 821 We want to create Joe under , and start editing it. 822 Editing might take a number of minutes. We want to immediately lock 823 Joe so no one will touch it before we are finished with the editing. 825 We also want to minimize locking other parts of the running datastore 826 as multiple managers might be adding users near simultaneously. 828 First we check what users are already defined. 830 Step 1 - Read existing users 832 834 835 836 837 838 839 840 841 842 843 844 846 The NETCONF server sends the following reply. 848 Step 2 - Receiving existing data 850 852 853 854 855 856 fred 857 8327 858 859 860 861 862 864 We want to add the new user "Joe" and immediately lock him using 865 partial locking. The way to do this, is to first lock all 866 nodes by locking the node. 868 Note that if we would lock all the nodes using the select 869 expression '/usr:top/usr:users/usr:user' ; this would not lock the 870 new user "Joe", which we will create after locking. So we rather 871 have to lock the node. 873 Step 3 - Lock users 875 879 880 883 884 886 The NETCONF server grants the partial lock. The scope of the lock 887 includes only the node. The lock protects the node 888 and all nodes below it from modification (by other sessions). 890 Step 4 - Receive lock 892 896 1 897 898 /usr:top/usr:users 899 900 902 Next we create user Joe. Joe is protected by the lock received above, 903 as it is under the sub-tree rooted at the node. 905 Step 5 - Create user Joe 907 909 910 911 912 913 914 915 916 917 Joe 918 919 920 921 922 923 925 We receive a positive reply to the (not shown). Next 926 we request a lock, that locks only Joe, and release the lock 927 on the node. This will allow other managers to create 928 additional new users. 930 Step 6 - Lock user Joe 932 936 937 940 941 943 The NETCONF server grants the partial lock. The scope of this second 944 lock includes only the node with name Joe. The lock protects 945 all data below this particular node. 947 Step 7 - Receive lock 949 953 2 954 955 /usr:top/usr:users/user[usr:name="Joe"]" 956 957 959 The scope of the second lock is the node Joe. It protects this 960 node and any data below it (e.g. phone number). At this point 961 of time these nodes are protected both by the first and second lock. 962 Next we unlock the other s and the node, to allow other 963 managers to work on them. We still keep the second lock, so the 964 node Joe and the sub-tree below is still protected. 966 Step 8 - Release lock on 968 971 972 1 973 974 976 8. Appendix D - Change Log 978 8.1. 10-11 980 Minor clarifications 982 8.2. 09-10 984 Clarifications 986 Only the running datastore can be locked 988 8.3. 08-09 990 Clarifications 992 8.4. 07-08 994 Clarifications 996 8.5. 06-07 998 Changed XSD and YANG to allow additional proprietary datastores to be 999 locked. 1001 8.6. 05-06 1003 Added usage example 1005 Clarified error messages 1007 Clarified interaction with edit-config continue-on-error 1009 Improved YANG: indentation, canonical order, contact info 1011 Added usage example in appendix C 1013 Synchronized YANG and XSD 1015 8.7. 04-05 1017 Language and editorial updates 1019 all app-tags are with dashes without spaces 1021 Added usage scenarios 1023 Changed encoding 1024 Clarified definitions, separated scope of lock and protected area 1026 8.8. 03-04 1028 Minor clarifications 1030 Added list of locked-nodes to the output of partial-lock. 1032 Added wrapper around datastore names. 1034 Allowed atomic/one operation locking of datastore parts in multiple 1035 datastores. 1037 Improved English (hopefully) 1039 Removed the element from rpc-reply following the text of 1040 rfc4741. 1042 8.9. 02-03 1044 Minor clarifications 1046 Same descriptions in XSD and YANG. 1048 8.10. 01-02 1050 Made XSD normative 1052 Clarified that no specific access control is assumed. 1054 Clarified that non-existing nodes are NOT covered by the lock, even 1055 if they where existing and covered by the lock when it was originally 1056 granted. 1058 Some rewording 1060 Added app-tags for two of the error cases. 1062 Made YANG an informative reference 1064 Enhanced security considerations. 1066 8.11. 00-01 1068 Added YANG module. 1070 8.12. -00 1072 Created from draft-lengyel-ngo-partial-lock-01.txt 1074 9. Acknowledgements 1076 Thanks to Andy Bierman, Sharon Chisholm, Phil Shafer , David 1077 Harrington, Mehmet Ersue, Wes Hardaker, Juergen Schoenwaelder, Washam 1078 Fan and many other members of the NETCONF WG for providing important 1079 input to this document. 1081 10. References 1083 10.1. Normative References 1085 [NETCONF] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 1086 December 2006. 1088 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1089 Requirement Levels", BCP 14, RFC 2119, March 1997. 1091 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1092 January 2004. 1094 10.2. Informative References 1096 [I-D.ietf-netmod-yang] 1097 Bjorklund, M., "YANG - A data modeling language for 1098 NETCONF", draft-ietf-netmod-yang-07 (work in progress), 1099 July 2009. 1101 Authors' Addresses 1103 Balazs Lengyel 1104 Ericsson 1106 Email: balazs.lengyel@ericsson.com 1108 Martin Bjorklund 1109 Tail-f Systems 1111 Email: mbj@tail-f.com