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
338
343
344
346 To retrieve etag attributes for "ietf-interfaces", but not for
347 "nacm", a client might send:
349
351
352
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
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