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
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
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