idnits 2.17.1 draft-ietf-netconf-partial-lock-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 634. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 645. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 652. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 658. 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 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 13, 2008) is 5794 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-00 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF B. Lengyel 3 Internet-Draft Ericsson Hungary 4 Intended status: Standards Track M. Bjorklund 5 Expires: December 15, 2008 Tail-f Systems 6 June 13, 2008 8 Partial Lock RPC for NETCONF 9 draft-ietf-netconf-partial-lock-02 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on December 15, 2008. 36 Copyright Notice 38 Copyright (C) The IETF Trust (2008). 40 Abstract 42 The NETCONF protocol defines the lock and unlock RPCs that lock 43 entire configuration datastores. In some situations, a way to lock 44 only parts of a configuration datastore is required. This document 45 defines a capability-based extension to the NETCONF protocol for 46 locking portions of a configuration datastore. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 1.1. Definition of Terms . . . . . . . . . . . . . . . . . . . 3 52 2. Partial Locking Capability . . . . . . . . . . . . . . . . . . 3 53 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 2.2. Dependencies . . . . . . . . . . . . . . . . . . . . . . . 4 55 2.3. Capability Identifier . . . . . . . . . . . . . . . . . . 4 56 2.4. New Operations . . . . . . . . . . . . . . . . . . . . . . 4 57 2.4.1. . . . . . . . . . . . . . . . . . . . . 4 58 2.4.2. . . . . . . . . . . . . . . . . . . . 8 59 2.5. Modifications to Existing Operations . . . . . . . . . . . 9 60 2.6. Interactions with Other Capabilities . . . . . . . . . . . 9 61 2.6.1. Writable-Running Capability . . . . . . . . . . . . . 9 62 2.6.2. Candidate Configuration Capability . . . . . . . . . . 9 63 2.6.3. Distinct Startup Capability . . . . . . . . . . . . . 9 64 3. Security Considerations . . . . . . . . . . . . . . . . . . . 9 65 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 66 5. Appendix A - XML Schema for Partial Locking (normative) . . 11 67 6. Appendix B - YANG Module for Partial Locking 68 (non-normative) . . . . . . . . . . . . . . . . . . . . . . . 13 69 7. Appendix C - Change Log . . . . . . . . . . . . . . . . . . 15 70 7.1. 01-02 . . . . . . . . . . . . . . . . . . . . . . . . . . 15 71 7.2. 00-01 . . . . . . . . . . . . . . . . . . . . . . . . . . 15 72 7.3. -00 . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 73 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 16 74 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 75 9.1. Normative References . . . . . . . . . . . . . . . . . . . 17 76 9.2. Informative References . . . . . . . . . . . . . . . . . . 17 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 18 78 Intellectual Property and Copyright Statements . . . . . . . . . . 19 80 1. Introduction 82 The NETCONF protocol [NETCONF] describes the lock and unlock RPCs 83 that operate on entire configuration datastores. Often, multiple 84 management sessions need to be able to modify the configuration of a 85 managed device in parallel. In these cases, locking only parts of a 86 configuration datastore is needed. This document defines an 87 extension to the NETCONF protocol to allow this. 89 The mechanism for partial locking is based on the existing XPath 90 filtering mechanisms. 92 Partial locking is defined as a capability to NETCONF. 94 1.1. Definition of Terms 96 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 97 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 98 "OPTIONAL" in this document are to be interpreted as described in BCP 99 14, [RFC2119]. 101 2. Partial Locking Capability 103 2.1. Overview 105 The :partial-lock capability indicates that the device supports the 106 locking of its configuration with a scope smaller then a complete 107 configuration datastore. The scope to be locked is specified by 108 using restricted or full XPath expressions. Partial locking covers 109 configuration data, but not state data. 111 The system MUST ensure that configuration resources covered by the 112 lock are not modified by other NETCONF or non-NETCONF management 113 operations such as SNMP and the CLI. 115 The duration of the partial lock is defined as beginning when the 116 partial lock is granted and lasting until either the corresponding 117 operation succeeds or the NETCONF session 118 terminates. 120 A NETCONF session MAY have multiple parts of one or more datastores 121 (running, candidate,startup) locked using partial lock operations. 122 The operation returns a lock-id to identify each 123 successfully acquired lock. 125 2.2. Dependencies 127 The device MUST support the restricted XPath expressions in the 128 select element, as described in Section 2.4.1 If optionally the 129 :xpath capability is also supported, the device MUST also support the 130 usage of any XPath 1.0 expression in the select element. 132 2.3. Capability Identifier 134 urn:ietf:params:netconf:capability:partial-lock:1.0 136 2.4. New Operations 138 2.4.1. 140 The operation allows the client to lock a portion of a 141 data store. The portion to lock is specified by using XPath 142 expressions in the select elements of the operation. 143 Each XPath expression MUST return a node set. 145 The select XPath expressions are evaluated only once at lock time, 146 thereafter the scope of the lock is maintained as a set of nodes. If 147 the configuration data is later altered in a way that would make the 148 original select XPath expressions evaluate to a different set of 149 nodes, this does not affect the scope of the partial lock. 151 XPath is only used for the creation of the partial lock. 152 Conceptually the scope of the lock is defined by the returned node 153 set and not by the XPath expression. 155 A operation MUST be handled atomically by the NETCONF 156 server. The server either locks all requested parts of the data 157 store or none; I.e. if during the operation one of the requested 158 parts cannot be locked the server MUST unlock all parts that have 159 been already locked during that operation. 161 If a node is locked by a session, only that same session is able to 162 modify that node or any node in the subtree underneath it. 164 If a top level node of a locked subtree is deleted, any other session 165 can recreate it, as it is not covered by the lock anymore. If all 166 top level nodes are deleted, the lock will still be present, however 167 it's scope will become nil i.e. it will not cover any nodes. 169 A partial lock MUST fail if: 171 o Any NETCONF session (including the current session) owns the 172 global lock on the datastore. 174 o Any part of the scope to be locked is already locked by another 175 management session/protocol, including other NETCONF sessions 176 using the or any other non-NETCONF management 177 method. 179 o The NETCONF server implements access control and the locking user 180 does not have sufficient privileges, to all parts of the datastore 181 section to be locked. The exact handling of access rights is 182 outside the scope of this document, but it is assumed that there 183 is an access control system that MAY deny or allow the partial 184 lock operation. 186 Note: If partial lock is requested for the running datastore, and the 187 NETCONF server implements the :confirmed-commit capability, and there 188 was a recent confirmed operation, where the confirming 189 operation has not been received. In this case the lock MUST 190 be denied, because if the confirmation does not arrive, the running 191 datastore MUST be rolled back to its state before the commit, thus 192 the NETCONF server might need to modify the configuration. 194 As with most locking systems, there is a possibility that two 195 management sessions trying to lock different parts of the 196 configuration become dead-locked. To avoid this situation, clients 197 SHOULD lock everything they need in one operation. If that operation 198 still fails, the client SHOULD back down, release any already 199 acquired locks, and retry the procedure after some time interval. 200 The length of the interval should preferably be random to avoid 201 repeated dead-locks when both (or all) clients back down and then 202 repeat locking. 204 It is the intention to keep partial-locking simple, so when a partial 205 lock is executed you get what you asked for: a set of nodes that are 206 locked for writing. There are some other issues that are 207 intentionally not addressed for the sake of simplicity: 209 o Locking does not affect read operations. 211 o If a part of a datastore is locked, this has no effect on any 212 unlocked parts of the datastore. If this is a problem e.g. the 213 operator's changes depend on data values in the unlocked part of 214 the datastore, the operator should include these values in the 215 scope of the lock. 217 o An operator is allowed to edit the configuration both inside and 218 outside the scope of a lock. It is the operator's responsibility 219 to lock all parts of the datastore that are crucial for a specific 220 management action. 222 Note: The operation does not modify the global 223 operation defined in the base NETCONF Protocol [NETCONF]. If part of 224 a datastore is already locked by , then a global lock 225 for that datastore fails even if the global lock is attempted by the 226 same NETCONF session which owns the partial-lock. 228 Parameters: 230 target: Name of the configuration datastore of which a part shall be 231 locked. One operation can affect only one of the 232 datastores. URLs are not accepted. 234 select: One or more 'select' elements each containing an XPath 235 expression. The XPath expression is evaluated in a context where 236 the context node is the root of the server's conceptual data 237 model, and the set of namespace declarations are those in scope 238 on the select element. 240 The select expressions MUST each return a node set, and at least 241 one of the node sets must be non-empty. 243 If the device supports the :xpath capability as well any valid 244 XPath 1.0 expression can be used, if not, the XPath expression 245 MUST be limited to an Instance Identifier expression. An 246 Instance Identifier is an absolute path expression in abbreviated 247 syntax, where predicates are used only to specify values for 248 nodes defined as keys to distinguish multiple instances. 250 Example: Lock virtual router 1 and interface eth1 252 256 xmlns:if="http://example.com/ns/interface"> 257 nc:message-id="135"> 258 259 260 261 262 263 265 269 xmlns:if="http://example.com/ns/interface"> 270 nc:message-id="135"> 271 272 127 273 274 276 Positive Response: 278 If the device was able to satisfy the request, an is sent 279 with a element (lock identifier) in the element. 281 Negative Response: 283 If a lock is already held on any node within the subtrees to be 284 locked, the element is 'lock-denied' and the 285 element includes the of the lock owner. If the lock is 286 held by a non-NETCONF entity, a of 0 (zero) is included. 288 If the select expressions return an empty node set, the 289 is 'operation-failed', and the is 'no-matches'. 291 If any select expression returns anything but a node set, the is 'invalid-value', the is 'XPath does not 293 return a node set'. 295 If the :xpath capability is not supported and the XPath expression is 296 not an Instance Identifier, the is 'invalid-value', the 297 is ':xpath capability not supported'. 299 If access control denies the partial lock, the is 300 'access-denied'. 302 2.4.1.1. Reserving model sections for future work 304 Partial lock can not be used to lock non-existing nodes, effectively 305 reserving them for future use. To make sure that a node cannot be 306 created by some other session, the parent node should be locked, the 307 top level node of the new section created, and then locked with 308 another operation. After this the lock on the parent 309 node should be removed. 311 2.4.2. 313 The operation unlocks a part of a datastore that was previously 314 locked using during the same session. 316 Parameters: 318 lock-id: Lock identifier to unlock; taken from a reply to a previous 319 operation. 321 Example: Unlock 323 326 327 127 328 329 331 Positive Response: 333 If the device was able to satisfy the request, an is sent 334 that contains an element. A positive response MUST be sent even 335 if all of the locked part of the datastore has already been deleted. 337 Negative Response: 339 If the parameter does not identify a lock which is owned by 340 the session, an 'invalid-value' error is returned. 342 2.5. Modifications to Existing Operations 344 A granted partial-lock will cause operations that want to modify the 345 locked area to fail, if executed in a NETCONF session other then the 346 one that owns the lock. Affected operations include: , 347 , , and . A 348 granted partial-lock will also cause the (global) operation to 349 fail. All of these operations are affected only if they are for the 350 same datastore. 352 2.6. Interactions with Other Capabilities 354 2.6.1. Writable-Running Capability 356 Partial locking of the running datastore can only be done if the 357 :writable-running capability is supported by the device. 359 2.6.2. Candidate Configuration Capability 361 Partial locking of the candidate datastore can only be done if the 362 :candidate capability is supported by the device. The partial 363 locking of the candidate datastore does not depend on whether the 364 datastore was modified or not. 366 2.6.3. Distinct Startup Capability 368 Partial locking of the startup datastore can only be done if the 369 :startup capability is supported by the device. 371 3. Security Considerations 373 The same considerations as for the base NETCONF Protocol [NETCONF] 374 are valid. It is assumed that the and RPCs are only allowed for an authenticated user after passing 376 some access control mechanism. 378 A lock either a partial-lock or a global lock might prevent other 379 users from configuring the system. The following mechanisms are in 380 place to prevent the misuse of this possibility: 382 Only an authenticated user after passing access control can 383 request a partial-lock. 385 The partial-lock is automatically released when a session is 386 terminated irrespective of the manner the session ends. 388 The operation allows terminating other users 389 sessions. 391 The NETCONF server may log partial-lock requests in an audit 392 trail. 394 Partial locking is NOT an authorization mechanism, it should not be 395 used to provide security or access control. Partial locking should 396 only be used as a mechanism to provide consistency in case of 397 multiple managers trying to configure the node. It is vital that the 398 operator can easily understand the exact scope of a lock, for this 399 reason the scope is determined when granting a lock and is not 400 modified dynamically later. 402 4. IANA Considerations 404 This document registers two URIs for the NETCONF XML namespace in the 405 IETF XML registry [RFC3688]. Note that the capability URN is 406 compliant to [NETCONF] section 10.3. 408 +---------------+---------------------------------------------------+ 409 | Index | Capability Identifier | 410 +---------------+---------------------------------------------------+ 411 | :partial-lock | urn:ietf:params:netconf:capability:partial-lock:1 | 412 | | .0 | 413 +---------------+---------------------------------------------------+ 415 URI: urn:ietf:params:xml:ns:netconf:partial-lock:1.0 417 Registrant Contact: The IESG. 419 XML: N/A, the requested URI is an XML namespace. 421 5. Appendix A - XML Schema for Partial Locking (normative) 423 The following XML Schema defines the and operations: 426 427 433 434 435 Schema defining the partial-lock and unlock operations. 436 organization "IETF NETCONF Working Group" 437 contact 438 "Balazs Lengyel 439 Ericsson Hungary, Inc. 440 balazs.lengyel@ericsson.com" 441 442 444 447 448 449 450 451 452 454 455 456 457 459 460 461 462 463 464 465 466 467 468 469 472 473 476 477 479 481 6. Appendix B - YANG Module for Partial Locking (non-normative) 483 The following YANG module defines the and operations. The YANG language is defined in 485 [I-D.ietf-netmod-yang]. 487 module netconf-partial-lock { 489 namespace urn:ietf:params:xml:ns:netconf:partial-lock:1.0; 490 prefix pl; 492 organization "IETF NETCONF Working Group"; 494 contact 495 "Balazs Lengyel 496 Ericsson Hungary, Inc. 497 balazs.lengyel@ericsson.com"; 499 description 500 "This YANG module defines the and 501 operations."; 503 revision 2008-06-06 { 504 description "Initial version."; 505 } 507 grouping configName { 508 description 509 "A choice to list the datastore names for NETCONF. 510 This could be moved to a netconf.yang module."; 511 choice configNameType { 512 leaf running { type empty; } 513 leaf candidate { type empty; } 514 leaf startup { type empty; } 515 } 516 } 518 rpc partial-lock { 519 description "A NETCONF operation that locks part of a datastore."; 520 input { 521 uses configName; 522 leaf-list select { 523 description 524 "XPath expression that specifies the scope of the lock. 525 An Instance Identifier expression must be used unless the 526 :xpath capability is supported in which case any XPath 1.0 527 expression is allowed."; 528 type string; 529 min-elements 1; 530 } 531 } 532 output { 533 leaf lockId { 534 description 535 "Identifies the lock, if granted. The lockId must be 536 used in the partial-unlock rpc."; 537 type uint32; 538 } 539 } 540 } 542 rpc partial-unlock { 543 input { 544 leaf lockId { 545 description 546 "Identifies the lock to be released. Must be the value 547 received in the response to the partial-lock operation."; 548 type uint32; 549 } 550 } 551 } 552 } 554 7. Appendix C - Change Log 556 7.1. 01-02 558 Made XSD normative 560 Clarified that no specific access control is assumed. 562 Clarified that non-existing nodes are NOT covered by the lock, even 563 if they where existing and covered by the lock when it was originally 564 granted. 566 Some rewording 568 Added app-tags for two of the error cases. 570 Made YANG an informative reference 572 Enhanced security considerations. 574 7.2. 00-01 576 Added YANG module. 578 7.3. -00 580 Created from draft-lengyel-ngo-partial-lock-01.txt 582 8. Acknowledgements 584 Thanks to Andy Bierman, Sharon Chisholm, Phil Shafer , David 585 Harrington, Mehmet Ersue and many other members of the NETCONF WG for 586 providing important input to this document. 588 9. References 590 9.1. Normative References 592 [NETCONF] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 593 December 2006. 595 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 596 Requirement Levels", BCP 14, RFC 2119, March 1997. 598 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 599 January 2004. 601 9.2. Informative References 603 [I-D.ietf-netmod-yang] 604 Bjorklund, M., "YANG - A data modeling language for 605 NETCONF", draft-ietf-netmod-yang-00 (work in progress), 606 May 2008. 608 Authors' Addresses 610 Balazs Lengyel 611 Ericsson Hungary 613 Email: balazs.lengyel@ericsson.com 615 Martin Bjorklund 616 Tail-f Systems 618 Email: mbj@tail-f.com 620 Full Copyright Statement 622 Copyright (C) The IETF Trust (2008). 624 This document is subject to the rights, licenses and restrictions 625 contained in BCP 78, and except as set forth therein, the authors 626 retain all their rights. 628 This document and the information contained herein are provided on an 629 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 630 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 631 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 632 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 633 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 634 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 636 Intellectual Property 638 The IETF takes no position regarding the validity or scope of any 639 Intellectual Property Rights or other rights that might be claimed to 640 pertain to the implementation or use of the technology described in 641 this document or the extent to which any license under such rights 642 might or might not be available; nor does it represent that it has 643 made any independent effort to identify any such rights. Information 644 on the procedures with respect to rights in RFC documents can be 645 found in BCP 78 and BCP 79. 647 Copies of IPR disclosures made to the IETF Secretariat and any 648 assurances of licenses to be made available, or the result of an 649 attempt made to obtain a general license or permission for the use of 650 such proprietary rights by implementers or users of this 651 specification can be obtained from the IETF on-line IPR repository at 652 http://www.ietf.org/ipr. 654 The IETF invites any interested party to bring to its attention any 655 copyrights, patents or patent applications, or other proprietary 656 rights that may cover technology that may be required to implement 657 this standard. Please address the information to the IETF at 658 ietf-ipr@ietf.org. 660 Acknowledgment 662 Funding for the RFC Editor function is provided by the IETF 663 Administrative Support Activity (IASA).