idnits 2.17.1 draft-lindblad-netconf-transaction-id-00.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The exact meaning of the all-uppercase expression 'NOT REQUIRED' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. -- The document date (2 November 2020) is 1264 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 (~~), 1 warning (==), 2 comments (--). 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 2 November 2020 5 Expires: 6 May 2021 7 Transaction ID Mechanism for NETCONF 8 draft-lindblad-netconf-transaction-id-00 10 Abstract 12 TODO Abstract 14 Discussion Venues 16 This note is to be removed before publishing as an RFC. 18 Source for this draft and an issue tracker can be found at 19 https://github.com/janlindblad/netconf-transaction-id. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 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 This Internet-Draft will expire on 6 May 2021. 38 Copyright Notice 40 Copyright (c) 2020 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 45 license-info) in effect on the date of publication of this document. 46 Please review these documents carefully, as they describe your rights 47 and restrictions with respect to this document. Code Components 48 extracted from this document must include Simplified BSD License text 49 as described in Section 4.e of the Trust Legal Provisions and are 50 provided without warranty as described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3 56 3. NETCONF Extension . . . . . . . . . . . . . . . . . . . . . . 3 57 4. Configuration Retreival . . . . . . . . . . . . . . . . . . . 4 58 4.1. Configuration Response Pruning . . . . . . . . . . . . . 5 59 5. Configuration Update . . . . . . . . . . . . . . . . . . . . 7 60 5.1. Conditional Configuration Update . . . . . . . . . . . . 10 61 6. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 13 62 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16 63 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 64 9. Normative References . . . . . . . . . . . . . . . . . . . . 16 65 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 16 66 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16 68 1. Introduction 70 When a NETCONF client connects with a NETCONF server, a frequently 71 occurring use case is for the client to find out if the configuration 72 has changed since it was last connected. Such changes could occur 73 for example if another NETCONF client has made changes, or another 74 system or operator made changes through other means than NETCONF. 76 One way of detecting a change for a client would be to retrieve the 77 entire configuration from the server, then compare the result with a 78 previously stored copy at the client side. This approach is not 79 popular with most NETCONF users, however, since it would often be 80 very expensive in terms of communications and computation cost. 82 Furthermore, even if the configuration is reported to be unchanged, 83 that will not guarantee that the configuration remains unchanged when 84 a client sends a subsequent change request, which arrives soon 85 thereafter. 87 Evidence of a transaction-id feature being demanded by clients is 88 that several server implementors have built proprietary and mutually 89 incompatible mechanisms for obtaining a transaction id from a NETCONF 90 server. 92 RESTCONF, RFC 8040 RFC8040 (https://tools.ietf.org/html/rfc8040), 93 defines a mechanism for detecting changes in configuration subtrees 94 based on Entity-tags (ETags). In conjunction with this, RESTCONF 95 provides a way to make configuration changes conditional on the 96 server confiuguration being untouched by others. This mechanism 97 leverages RFC 7232 RFC7232 (https://tools.ietf.org/html/rfc7232) 98 "Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests". 100 This document defines similar functionality for NETCONF, RFC 6241 101 RFC6241 (https://tools.ietf.org/html/rfc6241). 103 2. Conventions and Definitions 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 107 "OPTIONAL" in this document are to be interpreted as described in BCP 108 14 [RFC2119] [RFC8174] when, and only when, they appear in all 109 capitals, as shown here. 111 3. NETCONF Extension 113 This document describes a NETCONF extension which modifies the 114 behavior of get-config, get-data, edit-config and edit-data such that 115 clients are able to conditionally retrieve and update the 116 configuration in a NETCONF server. NETCONF servers that supports 117 this extension MUST announce the capability "FIXME". 119 The extended operations defined in this document pertains to YANG 120 containers and list elements. It is NOT REQUIRED that a conforming 121 server allows the extended operations to apply to all containers and 122 list elements in the server configuration. The set of containers and 123 list elements that the server supports with respect to this NETCONF 124 extension are collectively referred to as the "versioned elements". 126 The NETCONF server will maintain a record of the transaction that 127 last changed each versioned element. This transaction-id meta level 128 data is communicated between the server and client in the form of an 129 XML attribute called "entag". The values for the entag attribute is 130 up to the clients and servers to decice as opaque quantities. It is 131 essential that the entag values have a large value space in order to 132 not run out or collide. They SHOULD be at least 32-bit quantities. 134 Entag attribute values are encoded as YANG strings. 136 Comment, to be removed 138 Do we want to limit the entag attribute strings in some way? E.g. 139 only base64 characters, some min or max length, ...? 141 4. Configuration Retreival 143 When a NETCONF client retrieves the configuration from a NETCONF 144 server that implement this specification, it may request that the 145 configuration is entity tagged. The entity tags are XML attributes 146 added to some of the retrieved configuration elements by the server. 147 These elements are collectively called the "versioned elements". 149 The entity-tag (entag) attributes are guaranteed to change every time 150 there has been a configuration change at or below the element bearing 151 the attribute. 153 Clients request entity tags to be added by setting the ietf-netconf- 154 transaction-id:entag attribute to the value "?" on one or more 155 elements in the request. Entags MUST be returned for all descendant 156 versioned elements. In order to request that entags are returned for 157 the entire configuration, the client can place the attribute on the 158 top edit-config or edit-data tags. For more specific retrieval, the 159 client inserts entag attributes in the filter section. 161 To retrieve entag attributes across the entire NETCONF server 162 configuration, a client might send: 164 167 168 170 To retrieve entag attributes for "ietf-interfaces", but not for 171 "nacm", a client might send: 173 176 177 178 179 180 181 183 184 185 186 187 When a NETCONF server receives a get-config or get-data request 188 containing ietf-netconf-transaction-id:entag attributes with the 189 value "?", it MUST return entag attributes for all versioned elements 190 below this point included in the reply. 192 The server's response to request above might look like: 194 198 199 201 202 GigabitEthernet-0/0 203 Management Interface 204 ianaift:ethernetCsmacd 205 true 206 207 208 GigabitEthernet-0/1 209 Upward Interface 210 ianaift:ethernetCsmacd 211 true 212 213 214 215 216 217 admin 218 sakura 219 joe 220 221 222 223 224 226 4.1. Configuration Response Pruning 228 A NETCONF client that already knows some entag values may request 229 that the configuration retrieval request is pruned with respect to 230 the client's prior knowledge. 232 By specifying the previously received entag attribute values in the 233 get-config or get-data request, the client indicates that child 234 elements of already known parts of the configuration SHALL be 235 omitted. 237 To retrieve only changes for "ietf-interfaces" since the last known 238 transaction-id "abc12345678", but include the entire configuration 239 for "nacm", a client might send: 241 244 245 246 247 248 249 251 252 253 254 256 When a NETCONF server receives a get-config or get-data request 257 containing ietf-netconf-transaction-id:entag attributes with the same 258 value as the entag value known by the server for that element, it 259 MUST prune the contents of that subtree. 261 In case the element with a matching entag value is a container, the 262 container tag is returned with an entag attribute value of "=". No 263 child elements are returned for the container. 265 In case the element with a matching entag value is a list element, 266 the list element tag is returned with an entag attribute value of 267 "=". The list element will include the list elemenet keys, but no 268 other child elements. 270 For example, assuming the NETCONF server configuration is the same as 271 in the previous rpc-reply example, the server's response to request 272 above might look like: 274 278 279 281 282 GigabitEthernet-0/0 283 Management Interface 284 ianaift:ethernetCsmacd 285 true 286 287 288 GigabitEthernet-0/1 289 290 291 292 293 294 admin 295 sakura 296 joe 297 298 299 300 301 303 5. Configuration Update 305 When a NETCONF client sends an edit-config or edit-data request to a 306 NETCONF server that implements this specification, the client MAY 307 specify a transaction-id value. 309 If specified, the server MUST use this value as the new value for all 310 entag attribute values of any versioned element touched by the 311 transaction, if and only if the operation is successful. The entag 312 value must be updated regardless of whether an actual value change 313 took place or not. An element is touched if it is mentioned in the 314 transaction, even if it merely sets the element to the same value it 315 already has. 317 If the server side configuration changes for any reason, and there is 318 no transaction-id value specified by a client, servers that supports 319 this specification MUST update the entag values as if a NETCONF 320 client had made the change and specified a transaction-id. In this 321 case, the server MUST choose a random transaction-id value to use. 323 Comment, to be removed 325 Is talk about "random" good enough, or do we need to get specific? 327 Every time a versioned element has its entag value updated, the same 328 value must be set to all parent versioned elements' entag attributes, 329 cascading all the way to the datastore root. 331 For example, if a client wishes to update the interface description 332 for interface "GigabitEthernet-0/1" to "Downward Interface", under 333 transaction-id "ghi55550101", it might send: 335 338 339 340 341 342 test-then-set 343 344 ghi55550101 345 346 347 349 350 GigabitEthernet-0/1 351 Downward Interface 352 353 354 355 356 358 A subsequent get-config request for "ietf-interfaces", with ietf- 359 netconf-transaction-id:entag="?" might then return: 361 365 366 368 369 GigabitEthernet-0/0 370 Management Interface 371 ianaift:ethernetCsmacd 372 true 373 374 375 GigabitEthernet-0/1 376 Downward Interface 377 ianaift:ethernetCsmacd 378 true 379 380 381 382 384 In case the server received a configuration change from another 385 source, such as a CLI operator, adding an MTU value for the interface 386 "GigabitEthernet-0/0", a subsequent get-config request for "ietf- 387 interfaces", with ietf-netconf-transaction-id:entag="?" might then 388 return: 390 394 395 397 398 GigabitEthernet-0/0 399 Management Interface 400 ianaift:ethernetCsmacd 401 true 402 768 403 404 405 GigabitEthernet-0/1 406 Downward Interface 407 ianaift:ethernetCsmacd 408 true 409 410 411 412 414 5.1. Conditional Configuration Update 416 Conditional Transactions are useful when a client is interested to 417 make a configuration change, being sure that the server configuration 418 has not changed since the client last inspected it. 420 By supplying the latest entag values known to the client in its 421 change requests (edit-config etc.), it can request the server to 422 reject the transaction in case any changes have occurred at the 423 server that the client is not yet aware of. 425 Even if a client is constantly connected to a device, and even 426 possibly receiving notifications when a server device's configuration 427 changes, there is always a possibility that a change is introduced by 428 another party in the time window between when the client last 429 received an update about the server's configuration until the server 430 executes a configuration change request. 432 By leveraging conditional transactions, this race condition can be 433 eliminated efficiently. If the client provides the transaction-id it 434 expects the device to have as part of it's configuration change 435 request, and the device guarantees to only execute the request in 436 case the transaction-id in the request matches that on the server, 437 the race condition is removed. 439 When a NETCONF client sends an edit-config or edit-data request to a 440 NETCONF server that implements this specification, the client MAY 441 specify expected entag values on the versioned elements touched by 442 the transaction. 444 If such an entag value differs from the entag value stored on the 445 server, the server MUST reject the transaction. 447 If the server rejects the transaction because the configuration entag 448 value differs from the client's expectation, ther server MUST return 449 an rpc-error with the following values: 451 error-tag: operation-failed 452 error-type: protocol 453 error-severity: error 455 Additionally, the error-info tag MUST contain a sx:structure entag- 456 value-mismatch-error-info, with mismatch-path set to the instance 457 identifier value identifying one of the versioned elements that had 458 an entag value mismatch, and mismatch-entag-value set to the server's 459 current value of the entag attribute for that versioned element. 461 For example, if a client wishes to delete the interface 462 "GigabitEthernet-0/1" if and only if its configuration has not been 463 altered since this client last synchronized its configuration with 464 the server (at which point it received a transaction-id 465 "ghi55550101"), regardless of any possible changes to other 466 interfaces, it might send: 468 472 473 474 475 476 test-then-set 477 478 480 482 GigabitEthernet-0/1 483 484 485 486 487 489 If interface "GigabitEthernet-0/1" has the entag value "ghi55550101", 490 as expected by the client, the transaction goes through. 492 A subsequent get-config request for "ietf-interfaces", with ietf- 493 netconf-transaction-id:entag="?" might then return: 495 499 500 502 503 GigabitEthernet-0/0 504 Management Interface 505 ianaift:ethernetCsmacd 506 true 507 508 509 510 512 If interface "GigabitEthernet-0/1" did not have the entag value 513 "ghi55550101", the server rejects the transaction, and might send: 515 519 message-id="1"> 520 521 protocol 522 operation-failed 523 error 524 525 526 527 /if:interfaces/if:interface[if:name="GigabitEthernet-0/0"] 528 529 530 auto77775511 531 532 533 534 535 537 Comment, to be removed 539 In order to reach the full flexibility with the above transaction 540 rejection mechanism, it might make sense to reference parts of the 541 configuration just to see that they have not moved, with no intent 542 to make changes there. To support this use case, a new operation 543 mode "nocreate" might be useful. This would allow an edit config 544 to talk about parts of the configuration which are expected to 545 exist with a particular confiuguration, and to abort the 546 transaction if they do not exist. 548 Comment, to be removed 550 NETCONF clients may be equally interested to apply a mechanism 551 similar to entags when retrieving operational state as well, since 552 there is often vey much of this data, and some if changes rather 553 rarely. To support this use case, some sort of server maintained 554 change indicators may be invented, and combined with a similar 555 retrieval filter. 557 6. YANG Modules 559 Comment, to be removed 561 This is YANG 1.1. Do we also want 1.0? Makes it possible to 562 implement on 1.0 servers 564 module ietf-netconf-transaction-id { 565 yang-version 1.1; 566 namespace 567 'urn:ietf:params:xml:ns:yang:ietf-netconf-transaction-id'; 568 prefix ietf-netconf-transaction-id; 570 import ietf-netconf { 571 prefix nc; 572 } 574 import ietf-netconf-nmda { 575 prefix ncds; 576 } 578 import ietf-yang-structure-ext { 579 prefix sx; 580 } 582 organization 583 "IETF NETCONF (Network Configuration) Working Group"; 585 contact 586 "WG Web: 587 WG List: 589 Author: Jan Lindblad 590 "; 592 description 593 "NETCONF Transaction ID aware operations for NMDA. 595 Copyright (c) 2020 IETF Trust and the persons identified as 596 the document authors. All rights reserved. 598 Redistribution and use in source and binary forms, with or 599 without modification, is permitted pursuant to, and subject 600 to the license terms contained in, the Simplified BSD License 601 set forth in Section 4.c of the IETF Trust's Legal Provisions 602 Relating to IETF Documents 603 (http://trustee.ietf.org/license-info). 605 This version of this YANG module is part of RFC XXXX; see 606 the RFC itself for full legal notices."; 608 revision 2020-10-01 { 609 description 610 "Initial revision"; 611 reference 612 "RFC XXXX: Xxxxxxxxx"; 613 } 615 typedef transaction-id-t { 616 type string; 617 description 618 "Unique value representing a specific transaction"; 619 } 621 grouping transaction-id-grouping { 622 leaf transaction-id { 623 type transaction-id-t; 624 description 625 "Transaction-id value selected by the client. This string 626 should be chosen to give a high probability to be unique on 627 the server."; 628 } 629 description 630 "Grouping for transaction-id, to be augmented into rpcs 631 that modify configuration data stores."; 632 } 634 augment /nc:edit-config/nc:input { 635 uses transaction-id-grouping; 636 description 637 "Injects the transaction-id leaf into the edit-config 638 operation"; 639 } 641 augment /ncds:edit-data/ncds:input { 642 uses transaction-id-grouping; 643 description 644 "Injects the transaction-id leaf into the edit-data 645 operation"; 646 } 648 sx:structure entag-value-mismatch-error-info { 649 container entag-value-mismatch-error-info { 650 description 651 "This error is returned by a NETCONF server when a client 652 sends a configuration change request, with the additonal 653 condition that the server aborts the transaction if the 654 server's configuration has changed from what the client 655 expects, and the configuration is found not to actually 656 not match the client's expectation."; 657 leaf mismatch-path { 658 type instance-identifier; 659 description 660 "Indicates the YANG path to the element with a mismatching 661 entag value."; 662 } 663 leaf mismatch-entag-value { 664 type transaction-id-t; 665 description 666 "Indicates server's value of the entag attribute for one 667 mismatching element."; 668 } 669 } 670 } 671 } 673 7. Security Considerations 675 TODO Security 677 8. IANA Considerations 679 This document has no IANA actions. 681 9. Normative References 683 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 684 Requirement Levels", BCP 14, RFC 2119, 685 DOI 10.17487/RFC2119, March 1997, 686 . 688 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 689 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 690 May 2017, . 692 Acknowledgments 694 TODO acknowledge. 696 Author's Address 698 Jan Lindblad 699 Cisco Systems 701 Email: jlindbla@cisco.com