idnits 2.17.1 draft-lindblad-netconf-transaction-id-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (22 October 2021) is 910 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NETCONF J. Lindblad 3 Internet-Draft Cisco Systems 4 Intended status: Standards Track 22 October 2021 5 Expires: 25 April 2022 7 Transaction ID Mechanism for NETCONF 8 draft-lindblad-netconf-transaction-id-01 10 Abstract 12 NETCONF clients and servers often need to have a synchronized view of 13 the server's configuration data stores. The volume of configuration 14 data in a server may be very large, while data store changes 15 typically are small when observed at typical client resynchronization 16 intervals. 18 Rereading the entire data store and analyzing the response for 19 changes is an inefficient mechanism for synchronization. This 20 document specifies an extension to NETCONF that allows clients and 21 servers to keep synchronized with a much smaller data exchange and 22 without any need for servers to store information about the clients. 24 Discussion Venues 26 This note is to be removed before publishing as an RFC. 28 Source for this draft and an issue tracker can be found at 29 https://github.com/janlindblad/netconf-transaction-id. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at https://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on 25 April 2022. 48 Copyright Notice 50 Copyright (c) 2021 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 55 license-info) in effect on the date of publication of this document. 56 Please review these documents carefully, as they describe your rights 57 and restrictions with respect to this document. Code Components 58 extracted from this document must include Simplified BSD License text 59 as described in Section 4.e of the Trust Legal Provisions and are 60 provided without warranty as described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 65 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3 66 3. NETCONF Transaction id Extension . . . . . . . . . . . . . . 3 67 3.1. General Principles . . . . . . . . . . . . . . . . . . . 4 68 3.2. Conditional Transactions . . . . . . . . . . . . . . . . 5 69 3.3. Other NETCONF Operations . . . . . . . . . . . . . . . . 6 70 4. ETag Transaction id Mechanism . . . . . . . . . . . . . . . . 6 71 4.1. ETag attribute . . . . . . . . . . . . . . . . . . . . . 6 72 4.2. Configuration Retreival . . . . . . . . . . . . . . . . . 7 73 4.2.1. Initial Configuration Response . . . . . . . . . . . 7 74 4.2.2. Configuration Response Pruning . . . . . . . . . . . 9 75 4.3. Configuration Update . . . . . . . . . . . . . . . . . . 11 76 4.3.1. Conditional Configuration Update . . . . . . . . . . 14 77 4.4. ETags with Other NETCONF Operations . . . . . . . . . . . 16 78 5. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 17 79 6. Security Considerations . . . . . . . . . . . . . . . . . . . 20 80 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 81 8. Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 82 8.1. Major changes in -01 since -00 . . . . . . . . . . . . . 21 83 9. Normative References . . . . . . . . . . . . . . . . . . . . 22 84 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 22 85 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 22 87 1. Introduction 89 When a NETCONF client connects with a NETCONF server, a frequently 90 occurring use case is for the client to find out if the configuration 91 has changed since it was last connected. Such changes could occur 92 for example if another NETCONF client has made changes, or another 93 system or operator made changes through other means than NETCONF. 95 One way of detecting a change for a client would be to retrieve the 96 entire configuration from the server, then compare the result with a 97 previously stored copy at the client side. This approach is not 98 popular with most NETCONF users, however, since it would often be 99 very expensive in terms of communications and computation cost. 101 Furthermore, even if the configuration is reported to be unchanged, 102 that will not guarantee that the configuration remains unchanged when 103 a client sends a subsequent change request, a few moments later. 105 Evidence of a transaction id feature being demanded by clients is 106 that several server implementors have built proprietary and mutually 107 incompatible mechanisms for obtaining a transaction id from a NETCONF 108 server. 110 RESTCONF, RFC 8040 (https://tools.ietf.org/html/rfc8040), defines a 111 mechanism for detecting changes in configuration subtrees based on 112 Entity-tags (ETags). In conjunction with this, RESTCONF provides a 113 way to make configuration changes conditional on the server 114 confiuguration being untouched by others. This mechanism leverages 115 RFC 7232 (https://tools.ietf.org/html/rfc7232) "Hypertext Transfer 116 Protocol (HTTP/1.1): Conditional Requests". 118 This document defines similar functionality for NETCONF, RFC 6241 119 (https://tools.ietf.org/html/rfc6241). 121 2. Conventions and Definitions 123 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 124 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 125 "OPTIONAL" in this document are to be interpreted as described in BCP 126 14 [RFC2119] [RFC8174] when, and only when, they appear in all 127 capitals, as shown here. 129 3. NETCONF Transaction id Extension 131 This document describes a NETCONF extension which modifies the 132 behavior of get-config, get-data, edit-config, edit-data, discard- 133 changes, copy-config, delete-config and commit such that clients are 134 able to conditionally retrieve and update the configuration in a 135 NETCONF server. NETCONF servers that support this extension MUST 136 announce the capability 137 "urn:ietf:params:netconf:capability:txid:1.0". 139 Several low level mechanisms could be defined to fulfill the 140 requirements for efficient client-server transaction id 141 synchronization. This document defines only one mechanism, but 142 additional mechanisms could be added in future versions of this 143 document, or in separate documents. 145 The common use cases for such mecahnisms are briefly discussed here. 147 Initial configuration retrieval When the client initially connects 148 to a server, it may be interested to acquire a current view of 149 (parts of) the server's configuration. 150 In order to be able to efficiently detect changes later, it may 151 also be interested to store meta level transaction id information 152 about subtrees of the configuration. 154 Subsequent configuration retrieval When a client needs to reread 155 (parts of) the server's configuration, it may be interested to 156 leverage the transaction id meta data it has stored by requesting 157 the server to prune the response so that it does not repeat 158 configuration data that the client is already aware of. 160 Configuration update with transaction id return When a client issues 161 a transaction towards a server, it may be interested to also learn 162 the new transaction id meta data the server has stored for the 163 updated parts of the configuration. 165 Configuration update with transaction id specification When a client 166 issues a transaction towards a server, it may be interested to 167 also specify the new transaction id meta data that the server 168 stores for the updated parts of the configuration. 170 Conditional configuration update When a client issues a transaction 171 towards a server, it may specify transaction id data for the 172 transaction in order to allow the server to verify that the client 173 is up to date with any changes in the parts of the configuration 174 that it is concerned with. If the transaction id information in 175 the server is different than the client expected, the server 176 rejects the transaction with a specific error message. 178 3.1. General Principles 180 All transaction id mechanisms SHALL maintain a transaction id value 181 for each configuration datastore supported by the server. Some 182 transaction id mechanisms will also maintain transaction id values 183 for elements deeper in the YANG data tree. The elements for which 184 the server maintains transaction ids are collectively referred to as 185 the "versioned elements". 187 The server returning transaction id values for the versioned elements 188 MUST ensure the transaction id values are changed every time there 189 has been a configuration change at or below the element associated 190 with the value. This means any update of a config true element will 191 result in a new transaction id value for all ancestor versioned 192 elements, up to and including the datastore root itself. 194 This also means a server MUST update the transaction id value for any 195 elements that change as a result of a configuration change, 196 regardless of source, even if the changed elements are not explicitly 197 part of the change payload. An example of this is dependent data 198 under YANG RFC 7950 (https://tools.ietf.org/html/rfc7950) when- or 199 choice-statements. 201 The server MUST NOT change the transaction id value of a versioned 202 element unless a child element of that element has been changed. The 203 server MUST NOT change any transaction id values due to changes in 204 config false data. 206 3.2. Conditional Transactions 208 Conditional transactions are useful when a client is interested to 209 make a configuration change, being sure that the server configuration 210 has not changed since the client last inspected it. 212 By supplying the latest transaction id values known to the client in 213 its change requests (edit-config etc.), it can request the server to 214 reject the transaction in case any relevant changes have occurred at 215 the server that the client is not yet aware of. 217 This allows a client to reliably compute and send confiuguration 218 changes to a server without either acquiring a global datastore lock 219 for a potentially extended period of time, or risk that a change from 220 another client disrupts the intent in the time window between a read 221 (get-config etc.) and write (edit-config etc.) operation. 223 If the server rejects the transaction because the configuration 224 transaction id value differs from the client's expectation, the 225 server MUST return an rpc-error with the following values: 227 error-tag: operation-failed 228 error-type: protocol 229 error-severity: error 231 Additionally, the error-info tag SHOULD contain an sx:structure 232 containing relevant details about the mismatching transaction ids. 234 3.3. Other NETCONF Operations 236 discard-changes The discard-changes operation resets the candidate 237 datastore to the contents of the running datastore. The server 238 MUST ensure the transaction id values in the candidate datastore 239 get the same values as in the running datastore when this 240 operation runs. 242 copy-config The copy-config operation can be used to copy contents 243 between datastores. The server MUST ensure the transaction id 244 values retain the same values as in the soruce datastore. 246 If copy-config is used to copy from a file, URL or other source 247 that is not a datastore, the server MUST ensure the transaction id 248 values are changed. 250 delete-config The server MUST ensure the datastore transaction id 251 value is changed. 253 commit At commit, with regards to the transaction id values, the 254 server MUST treat the contents of the candidate datastore as if 255 any transaction id value provided by the client when updating the 256 candidate was provided in a single edit-config towards the running 257 datastore. If the transaction is rejected due to transaction id 258 value mismatch, an rpc-error as described in section Conditional 259 Transactions (Section 3.2) MUST be sent. 261 4. ETag Transaction id Mechanism 263 4.1. ETag attribute 265 Central to the ETag configuration retrieval and update mechanism 266 described in the following sections is a meta data XML attribute 267 called "etag". The etag attribute is defined in the namespace 268 "urn:ietf:params:xml:ns:netconf:txid:1.0". 270 Servers MUST maintain a top-level etag value for each configuration 271 datastore they implement. Servers SHOULD maintain etag values for 272 YANG containers that hold configuration for different subsystems. 273 Servers MAY maintain etag values for any YANG container or list 274 element they implement. 276 The etag attribute values are opaque UTF-8 strings chosen freely, 277 except that the etag string must not contain space, backslash or 278 double quotes. The point of this restriction is to make it easy to 279 reuse implementations that adhere to section 2.3.1 in RFC 7232 280 (https://tools.ietf.org/html/rfc7232). The probability SHOULD be 281 made very low that an etag value that has been used historically by a 282 server is used again by that server. 284 The detailed rules for when to update the etag value are described in 285 section Configuration Update (Section 4.3). These rules are chosen 286 to be consistent with the ETag mechanism in RESTCONF, RFC 8040 287 (https://tools.ietf.org/html/rfc8040), specifically sections 3.4.1.2, 288 3.4.1.3 and 3.5.2. 290 4.2. Configuration Retreival 292 Clients MAY request the server to return etag attribute values in the 293 response by adding one or more etag attributes in get-config or get- 294 data requests. 296 The etag attribute may be added directly on the get-config or get- 297 data requests, in which case it pertains to the entire datastore. A 298 client MAY also add etag attributes to zero or more individual 299 elements in the get-config or get-data filter, in which case it 300 pertains to the subtree rooted at that element. 302 For each element that the client requests etag attributes, the server 303 MUST return etags for all versioned elements at or below that point 304 that are part of the server's respone. ETags are returned as 305 attributes on the element they pertain to. The datastore root etag 306 value is returned on the top-level data tag in the response. 308 If the client is requesting an etag value for an element that is not 309 among the server's versioned elements, then the server MUST return 310 the etag attribute on the closest ancestor that is a versioned 311 element, and all children of that ancestor. The datastore root is 312 always a versioned element. 314 4.2.1. Initial Configuration Response 316 When the client adds etag attributes to a get-config or get-data 317 request, it should specify the last known etag values it has seen for 318 the elements it is asking about. Initially, the client will not know 319 any etag value and should use "?". 321 To retrieve etag attributes across the entire NETCONF server 322 configuration, a client might send: 324 326 327 329 To retrieve etag attributes for a specific interface using an xpath 330 filter, a client might send: 332 334 335 336 337 338 343 344 346 To retrieve etag attributes for "ietf-interfaces", but not for 347 "nacm", a client might send: 349 351 352 353 354 355 356 358 359 360 361 363 When a NETCONF server receives a get-config or get-data request 364 containing txid:etag attributes with the value "?", it MUST return 365 etag attributes for all versioned elements below this point included 366 in the reply. 368 If the server considers the container "interfaces" and the list 369 "interface" elements to be versioned elements, the server's response 370 to the request above might look like: 372 375 376 378 379 GigabitEthernet-0/0 380 Management Interface 381 ianaift:ethernetCsmacd 382 true 383 384 385 GigabitEthernet-0/1 386 Upward Interface 387 ianaift:ethernetCsmacd 388 true 389 390 391 392 393 394 admin 395 sakura 396 joe 397 398 399 400 401 403 4.2.2. Configuration Response Pruning 405 A NETCONF client that already knows some etag values MAY request that 406 the configuration retrieval request is pruned with respect to the 407 client's prior knowledge. 409 To retrieve only changes for "ietf-interfaces" that do not have the 410 last known etag value "abc12345678", but include the entire 411 configuration for "nacm", regardless of etags, a client might send: 413 415 416 417 418 419 420 422 423 424 425 427 When a NETCONF server receives a get-config or get-data request 428 containing an element with a client specified etag attribute, there 429 are several different cases: 431 * The element is not a versioned element, i.e. the server does not 432 maintain an etag value for this element. In this case, the server 433 MUST look up the closest ancestor that is a versioned element, and 434 proceed as if the client had specified the etag value for that 435 element. 437 * The element is a versioned element, and the client specified etag 438 attribute value is different than the server's etag value for this 439 element. In this case the server MUST return the contents as it 440 would otherwise have done, adding the etag attributes of all child 441 versioned elements to the response. In case the client has 442 specified etag attributes for some child elements, then these 443 cases MUST be re-evaluated for those elements. 445 * The element is a versioned element, and the client specified etag 446 attribute value matches the server's etag value. In this case the 447 server MUST return the element decorated with an etag attribute 448 with the value "=", and child elements pruned. 450 For list elements, pruning child elements means that key elements 451 MUST be included in the response, and other child elements MUST NOT 452 be included. For containers, child elements MUST NOT be included. 454 For example, assuming the NETCONF server configuration is the same as 455 in the previous rpc-reply example, the server's response to request 456 above might look like: 458 461 462 464 465 GigabitEthernet-0/0 466 Management Interface 467 ianaift:ethernetCsmacd 468 true 469 470 471 GigabitEthernet-0/1 472 473 474 475 476 477 admin 478 sakura 479 joe 480 481 482 483 484 486 4.3. Configuration Update 488 Whenever the configuration on a server changes for any reason, the 489 server MUST update the etag value for all versioned elements that 490 have children that changed. 492 If the change is due to a NETCONF client edit-config or edit-data 493 request that includes the ietf-netconf-txid:with-etag presence 494 container, the server MUST return the etag value of the targeted 495 datastore as an attribute on the XML ok tag in the rpc-reply. 497 The server MUST NOT change the etag value of a versioned element 498 unless a child element of that element has been changed. The server 499 MUST NOT change any etag values due to changes in config false data. 501 How the server selects a new etag value to use for the changed 502 elements is described in section ETag attribute (Section 4.1). 504 For example, if a client wishes to update the interface description 505 for interface "GigabitEthernet-0/1" to "Downward Interface", it might 506 send: 508 509 512 513 514 515 test-then-set 516 517 518 520 521 GigabitEthernet-0/1 522 Downward Interface 523 524 525 526 527 529 The server would update the description leaf in the candidate 530 datastore, and return an rpc-reply as follows: 532 535 536 538 A subsequent get-config request for "ietf-interfaces", with 539 txid:etag="?" might then return: 541 544 545 547 548 GigabitEthernet-0/0 549 Management Interface 550 ianaift:ethernetCsmacd 551 true 552 553 554 GigabitEthernet-0/1 555 Downward Interface 556 ianaift:ethernetCsmacd 557 true 558 559 560 561 563 In case the server at this point received a configuration change from 564 another source, such as a CLI operator, adding an MTU value for the 565 interface "GigabitEthernet-0/0", a subsequent get-config request for 566 "ietf-interfaces", with txid:etag="?" might then return: 568 571 572 574 575 GigabitEthernet-0/0 576 Management Interface 577 ianaift:ethernetCsmacd 578 true 579 768 580 581 582 GigabitEthernet-0/1 583 Downward Interface 584 ianaift:ethernetCsmacd 585 true 586 587 588 589 591 4.3.1. Conditional Configuration Update 593 When a NETCONF client sends an edit-config or edit-data request to a 594 NETCONF server that implements this specification, the client MAY 595 specify expected etag values on the versioned elements touched by the 596 transaction. 598 If such an etag value differs from the etag value stored on the 599 server, the server MUST reject the transaction and return an rpc- 600 error as specified in section Conditional Transactions (Section 3.2). 602 Additionally, the error-info tag MUST contain an sx:structure etag- 603 value-mismatch-error-info as defined in the module ietf-netconf-txid, 604 with mismatch-path set to the instance identifier value identifying 605 one of the versioned elements that had an etag value mismatch, and 606 mismatch-etag-value set to the server's current value of the etag 607 attribute for that versioned element. 609 For example, if a client wishes to delete the interface 610 "GigabitEthernet-0/1" if and only if its configuration has not been 611 altered since this client last synchronized its configuration with 612 the server (at which point it received the etag "ghi55550101"), 613 regardless of any possible changes to other interfaces, it might 614 send: 616 621 622 623 624 625 test-then-set 626 627 628 630 632 GigabitEthernet-0/1 633 634 635 636 637 639 If interface "GigabitEthernet-0/1" has the etag value "ghi55550101", 640 as expected by the client, the transaction goes through, and the 641 server responds something like: 643 646 647 649 A subsequent get-config request for "ietf-interfaces", with 650 txid:etag="?" might then return: 652 655 656 658 659 GigabitEthernet-0/0 660 Management Interface 661 ianaift:ethernetCsmacd 662 true 663 664 665 666 668 In case interface "GigabitEthernet-0/1" did not have the expected 669 etag value "ghi55550101", the server rejects the transaction, and 670 might send: 672 676 message-id="1"> 677 678 protocol 679 operation-failed 680 error 681 682 683 684 /if:interfaces/if:interface[if:name="GigabitEthernet-0/0"] 685 686 687 cli22223333 688 689 690 691 692 694 4.4. ETags with Other NETCONF Operations 696 The following NETCONF Operations also need some special 697 considerations. 699 discard-changes The server MUST ensure the etag attributes in the 700 candidate datastore get the same values as in the running 701 datastore when this operation runs. 703 copy-config The server MUST ensure the etag attributes retain the 704 same values as in the soruce datastore. 706 If copy-config is used to copy from a source that is not a 707 datastore, the server MUST ensure etags are given new values. 709 delete-config The server MUST ensure the datastore etag is given a 710 new value. 712 commit At commit, with regards to the etag values, the server MUST 713 treat the contents of the candidate datastore as if any etag 714 attributes provided by the client were provided in a single edit- 715 config towards the running datastore. If the commit is rejected 716 due to etag mismatch, the rpc-error message specified in section 717 Conditional Configuration Update (Section 4.3.1) MUST be sent. 719 The client MAY request that the new etag value is returned as an 720 attribute on the ok response for a successful commit. The client 721 requests this by adding with-etag to the commit operation. 723 For example, a client might send: 725 727 xmlns:ietf-netconf-txid= 728 "urn:ietf:params:xml:ns:yang:ietf-netconf-txid" 729 730 731 732 734 Assuming the server accepted the transaction, it might respond: 736 739 740 742 5. YANG Modules 743 module ietf-netconf-txid { 744 yang-version 1.1; 745 namespace 746 'urn:ietf:params:xml:ns:yang:ietf-netconf-txid'; 747 prefix ietf-netconf-txid; 749 import ietf-netconf { 750 prefix nc; 751 } 753 import ietf-netconf-nmda { 754 prefix ncds; 755 } 757 import ietf-yang-structure-ext { 758 prefix sx; 759 } 761 organization 762 "IETF NETCONF (Network Configuration) Working Group"; 764 contact 765 "WG Web: 766 WG List: 768 Author: Jan Lindblad 769 "; 771 description 772 "NETCONF Transaction ID aware operations for NMDA. 774 Copyright (c) 2021 IETF Trust and the persons identified as 775 the document authors. All rights reserved. 777 Redistribution and use in source and binary forms, with or 778 without modification, is permitted pursuant to, and subject 779 to the license terms contained in, the Simplified BSD License 780 set forth in Section 4.c of the IETF Trust's Legal Provisions 781 Relating to IETF Documents 782 (http://trustee.ietf.org/license-info). 784 This version of this YANG module is part of RFC XXXX; see 785 the RFC itself for full legal notices."; 787 revision 2021-11-01 { 788 description 789 "Initial revision"; 790 reference 791 "RFC XXXX: Xxxxxxxxx"; 792 } 794 typedef etag-t { 795 type string { 796 pattern ".* .*" { 797 modifier invert-match; 798 } 799 pattern ".*\".*" { 800 modifier invert-match; 801 } 802 pattern ".*\\.*" { 803 modifier invert-match; 804 } 805 } 806 description 807 "Unique Entity-tag value representing a specific transaction. 808 Could be any string that does not contain spaces, double 809 quotes or backslash. The values '?' and '=' have special 810 meaning."; 811 } 813 grouping transaction-id-grouping { 814 container with-etag { 815 presence 816 "Indicates that the client requests the server to include a 817 txid:etag transaction id in the rpc-reply"; 818 } 819 description 820 "Grouping for transaction id mechanisms, to be augmented into 821 rpcs that modify configuration data stores."; 822 } 824 augment /nc:edit-config/nc:input { 825 uses transaction-id-grouping; 826 description 827 "Injects the transaction id mechanisms into the 828 edit-config operation"; 829 } 831 augment /nc:commit/nc:input { 832 uses transaction-id-grouping; 833 description 834 "Injects the transaction id mechanisms into the 835 commit operation"; 836 } 838 augment /ncds:edit-data/ncds:input { 839 uses transaction-id-grouping; 840 description 841 "Injects the transaction id mechanisms into the 842 edit-data operation"; 844 sx:structure etag-value-mismatch-error-info { 845 container etag-value-mismatch-error-info { 846 description 847 "This error is returned by a NETCONF server when a client 848 sends a configuration change request, with the additonal 849 condition that the server aborts the transaction if the 850 server's configuration has changed from what the client 851 expects, and the configuration is found not to actually 852 not match the client's expectation."; 853 leaf mismatch-path { 854 type instance-identifier; 855 description 856 "Indicates the YANG path to the element with a mismatching 857 etag value."; 858 } 859 leaf mismatch-etag-value { 860 type etag-t; 861 description 862 "Indicates server's value of the etag attribute for one 863 mismatching element."; 864 } 865 } 866 } 867 } 869 6. Security Considerations 871 TODO Security 873 7. IANA Considerations 875 This document registers the following capability identifier URN in 876 the 'Network Configuration Protocol (NETCONF) Capability URNs' 877 registry: 879 urn:ietf:params:netconf:capability:txid:1.0 881 This document registers two XML namespace URNs in the 'IETF XML 882 registry', following the format defined in RFC 3688 883 (https://tools.ietf.org/html/rfc3688). 885 URI: urn:ietf:params:xml:ns:netconf:txid:1.0 887 URI: urn:ietf:params:xml:ns:yang:ietf-netconf-txid 889 Registrant Contact: The NETCONF WG of the IETF. 891 XML: N/A, the requested URIs are XML namespaces. 893 This document registers one module name in the 'YANG Module Names' 894 registry, defined in RFC 6020 (https://tools.ietf.org/html/rfc6020). 896 name: ietf-netconf-txid 898 prefix: ietf-netconf-txid 900 namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-txid 902 RFC: XXXX 904 8. Changes 906 8.1. Major changes in -01 since -00 908 * Updated the text on numerous points in order to answer questions 909 that appeared on the mailing list. 911 * Changed the document structure into a general transaction id part 912 and one etag specific part. 914 * Renamed entag attribute to etag, prefix to txid, namespace to 915 urn:ietf:params:xml:ns:yang:ietf-netconf-txid. 917 * Set capability string to 918 urn:ietf:params:netconf:capability:txid:1.0 920 * Changed YANG module name, namespace and prefix to match names 921 above. 923 * Harmonized/slightly adjusted etag value space with RFC 7232 and 924 RFC 8040. 926 * Removed all text discussing etag values provided by the client 927 (although this is still an interesting idea, if you ask the 928 author) 930 * Clarified the etag attribute mechanism, especially when it comes 931 to matching against non-versioned elements, its cascading upwards 932 in the tree and secondary effects from when- and choice- 933 statements. 935 * Added a mechanism for returning the server assigned etag value in 936 get-config and get-data. 938 * Added section describing how the NETCONF discard-changes, copy- 939 config, delete-config and commit operations work with respect to 940 etags. 942 * Added IANA Considerations section. 944 * Removed all comments about open questions. 946 9. Normative References 948 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 949 Requirement Levels", BCP 14, RFC 2119, 950 DOI 10.17487/RFC2119, March 1997, 951 . 953 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 954 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 955 May 2017, . 957 Acknowledgments 959 The author wishes to thank Benoit Claise for making this work happen, 960 and the following individuals, who all provided helpful comments: Per 961 Andersson, Kent Watsen, Andy Bierman, Robert Wilton, Qiufang Ma. 963 Author's Address 965 Jan Lindblad 966 Cisco Systems 968 Email: jlindbla@cisco.com