forked from netconf-wg/private-candidate
-
Notifications
You must be signed in to change notification settings - Fork 0
/
draft-jgc-netconf-privcand-02.xml
1004 lines (995 loc) · 52.6 KB
/
draft-jgc-netconf-privcand-02.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="utf-8"?>
<!--
draft-rfcxml-general-template-standard-01
This template includes examples of the most commonly used features of RFCXML with comments
explaining how to customise them. This template can be quickly turned into an I-D by editing
the examples provided. Look for [REPLACE], [REPLACE/DELETE], [CHECK] and edit accordingly.
Note - 'DELETE' means delete the element or attribute, not just the contents.
Documentation is at https://authors.ietf.org/en/templates-and-schemas
-->
<?xml-model href="rfc7991bis.rnc"?>
<!-- Required for schema validation and schema-aware editing -->
<!-- <?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?> -->
<!-- This third-party XSLT can be enabled for direct transformations in XML processors, including most browsers -->
<!DOCTYPE rfc [
<!ENTITY nbsp " ">
<!ENTITY zwsp "​">
<!ENTITY nbhy "‑">
<!ENTITY wj "⁠">
]>
<!-- If further character entities are required then they should be added to the DOCTYPE above.
Use of an external entity file is not recommended. -->
<rfc xmlns:xi="http://www.w3.org/2001/XInclude" category="std" docName="draft-jgc-netconf-privcand-02" ipr="trust200902" obsoletes="" updates="" submissionType="IETF" xml:lang="en" version="3" consensus="true">
<front>
<title abbrev="NETCONF Private Candidates">NETCONF Private Candidates</title>
<seriesInfo name="Internet-Draft" value="draft-jgc-netconf-privcand-02"/>
<author fullname="James Cumming" initials="JG" surname="Cumming">
<organization>Nokia</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<author fullname="Robert Wills" initials="R" surname="Wills">
<organization>Cisco Systems</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<date day="10" month="7" year="2023"/>
<!-- On draft subbmission:
* If only the current year is specified, the current day and month will be used.
* If the month and year are both specified and are the current ones, the current day will
be used
* If the year is not the current one, it is necessary to specify at least a month and day="1" will be used.
-->
<area>General</area>
<workgroup>Internet Engineering Task Force</workgroup>
<!-- "Internet Engineering Task Force" is fine for individual submissions. If this element is
not present, the default is "Network Working Group", which is used by the RFC Editor as
a nod to the history of the RFC Series. -->
<keyword>NETCONF</keyword>
<abstract>
<t>This document provides a mechanism to extend the Network Configuration Protocol
(NETCONF) and RESTCONF protocol to support multiple clients making configuration changes simultaneously and
ensuring that they commit only those changes that they defined.</t>
<t>This document addresses two specific aspects: The interaction with a private candidate
over the NETCONF and RESTCONF protocols and the methods to identify and resolve conflicts between
clients.</t>
</abstract>
</front>
<middle>
<section>
<name>Introduction</name>
<t><xref target="RFC6241">NETCONF</xref> and <xref target="RFC8040">RESTCONF</xref>
both provide a mechanism for one or more
clients to make configuration changes to a device running as a NETCONF/RESTCONF
server. Each client has the ability to make one or more
configuration change to the servers shared candidate configuration.<br/><br/>
As the name shared candidate suggests, all clients have access to the same candidate
configuration. This means that multiple clients may make changes to the shared
candidate prior to the configuration being committed. This behavior may be
undesirable as one client may unwittingly commit the configuration changes made
by another client. <br/><br/>
NETCONF provides a way to mitigate this behavior by allowing clients
to place a lock on the shared candidate. The placing of this lock means that
no other client may make any changes until that lock is released. This behavior
is, in many situations, also undesirable. <br/><br/>
Many network devices already support private candidates configurations,
where a user (machine or otherwise) is able to edit a personal copy of a devices
configuration without blocking other users from doing so.<br/><br/>
This document details the extensions to the NETCONF protocol in order to support
the use of private candidates. It also describes how the RESTCONF protocol can be
used on a system that implements private candidates.</t>
<section>
<name>Requirements Language</name>
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL",
"SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT
RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in BCP 14 <xref target="RFC2119"/>
<xref target="RFC8174"/> when, and only when, they appear in
all capitals, as shown here.</t>
</section>
</section>
<section>
<name>Definitions and terminology</name>
<section>
<name>Session specific datastore</name>
<t>A session specific datastore is a configuration datastore that,
unlike the candidate and running configuration datastores which
have only one per system, is bound to the specific NETCONF session.
</t>
</section>
<section>
<name>Shared candidate configuration</name>
<t>The candidate configuration datastore defined in
<xref target="RFC6241"/> is referenced as the shared candidate
configuration in this document.</t>
</section>
<section>
<name>Private candidate configuration</name>
<t>A private candidate configuration is a session specific candidate
configuration datastore.</t>
<t>When a private candidate is used by NETCONF, the specific session
(and user) that created the private
candidate configuration is the only session (user) that has access
to it over NETCONF. Devices may expose this to other users through
other interfaces but this is out of scope for this document.</t>
<t>When a private candidate is used by RESTCONF, it exists only for the
duration of the RESTCONF request.</t>
<t>The private candidate configuration contains a full copy of the running
configuration when it is created (in the same way as a branch does in
a source control management system and in the same way as the candidate
configuration datastore as defined in <xref target="RFC6241"/>).
Any changes made to it, for example, through the use of operations such
as <edit-config> and <edit-data>, are made in this private
candidate configuration.</t>
<t>Obtaining this private candidate over NETCONF will display the entire
configuration, including all changes made to it. Performing a <commit>
operation will merge the changes from the private candidate into the
running configuration (the same as a merge in source code management systems).
A <discard-changes> operation will revert the private candidate to the
branch's initial state.</t>
<t>All changes made to this private candidate configuration are held
separately from any other candidate configuration changes, whether
made by other users to the shared candidate or any other private candidate,
and are not visible to or accessible by anyone else.</t>
</section>
</section>
<section>
<name>Limitations using the shared candidate configuration for multiple clients</name>
<t>The following sections describe some limitations and mitigation factors in
more detail for the use of the shared candidate configuration during multi-client
configuration over NETCONF or RESTCONF.</t>
<section>
<name>Issues</name>
<section>
<name>Unintended deployment of alternate users configuration changes</name>
<t>Consider the following scenario:</t>
<ol>
<li>Client 1 modifies item A in the shared candidate configuration</li>
<li>Client 2 then modifies item B in the shared candidate configuration</li>
<li>Client 2 then issues a <commit> RPC</li>
</ol>
<t>In this situation, both client 1 and client 2 configurations will be committed by
client 2. In a machine-to-machine environment client 2 may not have been aware of
the change to item A and, if they had been aware, may have decided not to proceed.
</t>
</section>
</section>
<section>
<name>Current mitigation strategies</name>
<section>
<name>Locking the shared candidate configuration datastore</name>
<t>
In order to resolve unintended deployment of alternate users configuration changes
as described above NETCONF provides the ability to lock a datastore in order to
restrict other users from editing and committed changes.
</t>
<t>This does resolve the specific issue above, however, it introduces another issue.
Whilst one of the clients holds a lock, no other client may edit the configuration.
This will result in the client failing and having to retry. Whilst this may be a
desirable consequence when two clients are editing the same section of the configuration,
where they are editing different sections this behavior may hold up valid operational
activity.</t>
<t>Additionally, a lock placed on the shared candidate configuration must also lock the
running configuration, otherwise changes committed directly into the running datastore
may conflict.</t>
<t>Finally, this locking mechanism isn't available to RESTCONF clients.</t>
</section>
<section>
<name>Always use the running configuration datastore</name>
<t>The use of the running configuration datastore as the target for all configuration
changes does not resolve any issues regarding blocking of system access in the case a
lock is taken, nor does it provide a solution for multiple NETCONF and RESTCONF clients as each
configuration change is applied immediately and the client has no knowledge of the
current configuration at the point in time that they commenced the editing activity nor
at the point they commit the activity.</t>
</section>
<section>
<name>Fine-grained locking</name>
<t><xref target="RFC5717"/> describes a partial lock mechanism that
can be used on specific portions of the shared candidate datastore.</t>
<t>Partial locking does not solve the issues of staging a set of
configuration changes such that only those changes get committed in a
commit operation, nor does it solve the issue of multiple clients
editing the same parts of the configuration at the same time.</t>
<t>Partial locking additionally requires that the client is aware of
any interdependencies within the servers YANG models in order to lock all
parts of the tree.</t>
</section>
</section>
</section>
<section>
<name>Private candidates solution</name>
<t>The use of private candidates resolves the issues
detailed earlier in this document.</t>
<t>NETCONF sessions and RESTCONF requests are able to utilize the concept of private candidates
in order to streamline network operations, particularly for
machine-to-machine communication.</t>
<t>Using this approach clients may improve their performance and reduce the
likelihood of blocking other clients from continuing with valid operational
activities.</t>
<t>One or more private candidates may exist at any one time, however, a
private candidate SHOULD:</t>
<ul>
<li>Be accessible by one client only</li>
<li>Be visible by one client only</li>
</ul>
<t>Additionally, the choice of using a shared candidate configuration
datastore or a private candidate configuration datastore MUST be for
the entire duration of the NETCONF session.</t>
<section>
<name>What is a private candidate</name>
<t>A private candidate is defined earlier in the definitions and terminology
section of this document.</t>
</section>
<section>
<name>When is a private candidate created</name>
<t>A private candidate datastore is created when the first RPC that requires access
to it is sent to the server. This could be, for example, an <edit-config>.</t>
<t>When the private candidate is created a copy of the running configuration is
made and stored in it. This can be considered the same as creating a branch in a
source code repository.</t>
<artwork>
+----------------------------> private candidate
/
/
+------+-------------------------------> running configuration
^
Private candidate created
</artwork>
<t>Closing a session that is operating using a private candidate will
discard all changes in that session's private candidate and destroy
the private candidate.</t>
</section>
<section>
<name>How to signal the use of private candidates</name>
<section>
<name>Server</name>
<t>The server MUST signal its support for private candidates. The server
does this by advertising the :candidate capability as defined in
<xref target="RFC6241"/> and a new :private-candidate capability:</t>
<sourcecode>
urn:ietf:params:netconf:capability:private-candidate:1.0
</sourcecode>
<t>If the server has not signalled these capabilities, or has signalled the
support for :candidate but not :private-candidate, or :private-candidate
but not :candidate the session MUST be terminated when a client attempts
to interact with a private candidate (for example, by explicitly
targeting the private-candidate NMDA datastore).</t>
</section>
<section>
<name>NETCONF client</name>
<t>In order to utilise a private candidate configuration within a NETCONF
session, the client must inform the server that it wishes to do this.</t>
<t>Two approaches are available for a NETCONF client to signal that it wants
to use a private candidate:</t>
<section>
<name>Client capability declaration</name>
<t>When a NETCONF client connects with a server it sends a list of client
capabilities including one of the :base NETCONF version capabilties.</t>
<t>In order to enable private candidate mode for the duration of the NETCONF
client session the NETCONF client sends the following capability:</t>
<sourcecode>
urn:ietf:params:netconf:capability:private-candidate:1.0
</sourcecode>
<t>In order for the use of private candidates to be established both the
NETCONF server and the NETCONF client MUST advertise this capability.
</t>
<t>When a server receives the client capability its mode of operation
will be set to private candidate mode for the duration of the NETCONF
session.</t>
<t>All RPC requests that target the candidate configuration datastore
will operate in exactly the same way as they would do when using the
shared candidate configuration datastore, however, when the server
receives a request to act upon the candidate configuration datastore it
instead uses the session's private candidate configuration datastore.</t>
<t>Using this method, the use of private candidates can be made available to NMDA
and non-NMDA capable servers.</t>
<t>No protocol extensions are required for the transitioning of candidates between
the shared mode and the private mode and no extensions are required for any
RPCs (including <lock>)</t>
</section>
<section>
<name>Private candidate datastore</name>
<t>The private candidate configuration datastore is exposed as its
own datastore similar to other <xref target="RFC8342">NMDA</xref>
capable datastores. This datastore is called private-candidate.</t>
<t>All NMDA operations that support candidate NMDA datastore SHOULD
support the private-candidate datastore.</t>
<t>Any non-NMDA aware NETCONF operations that take a source or target
(destination) may be extended to accept the new datastore.</t>
<t>The ability for the server to support private candidates is optional
and SHOULD be signalled in NMDA supporting servers as a datastore in addition
to the server capabilities described earlier in this document.</t>
<t>The first datastore referenced (either candidate or private-candidate) in
any NETCONF operation will define which mode that NETCONF session will
operate in for its duration. As an example, performing a <get-data>
operation on the private-candidate datastore will switch the session into
private candidate configuration mode and subsequent <edit-config>
operations that reference the candidate configuration datastore will fail.</t>
</section>
</section>
<section>
<name>RESTCONF client</name>
<t>RESTCONF doesn't provide a mechanism for the client to advertise a capability.
Therefore when a RESTCONF server advertises the :private-candidate capability, the
decision of whether to use a private candidate depends on whether a datastore is
explicitly referenced in the request using the
<xref target="RFC8527">RESTCONF extensions for NMDA</xref>.</t>
<t>When the server advertises the :private-candidate capability and the client does
not explicitly reference a datastore in their request, all edits are made to a new
private candidate, and the private candidate is committed. This is analagous to
the behavior of RESTCONF when the :candidate capability is specified by the server.</t>
<t>When the private-candidate datastore is explicitly referenced, edits are made to
a new private candidate and the private candidate is committed.</t>
</section>
</section>
<section>
<name>Interaction between running and private-candidate(s)</name>
<t>Multiple NETCONF operations may be performed on the private candidate in order
to stage changes ready for a commit.</t>
<t>In the simplest example, a session may create a private candidate configuration,
perform multiple NETCONF operations (such as <edit-config>) on it and then
perform a <commit> operation to merge the private candidate configuration
into the running configuration in line with semantics in <xref target="RFC6241"/>.
</t>
<artwork>
commit
+--------------------------+--------> private candidate
/ ^ ^ \
/ edit-config edit-config ⌄
+---+-------------------------------+------> running configuration
^
edit-config
(Private candidate created)
</artwork>
<t>More complex scenarios need to be considered, when multiple private candidate
sessions are working on their own configuration (branches) and they make commits
into the running configuration.</t>
<artwork>
commit
+---------------------+----------------> private candidate 1
/ \
/ edit-config ⌄
+---+------------+-------------+--------------> running configuration
edit-config \
\
+-------------------------> private candidate 2
</artwork>
<t>In this situation, if, how and when private candidate 2 is updated with the
information that the running configuration has changed must be considered.</t>
<t>As described earlier, the client MUST be aware of changes to the running
configuration so it can be assured that it is only committing its own
modifications.</t>
<t>It is possible, during an update, for conflicts to occur and the
detection and resolution of these is discussed later in this document.</t>
<t>Two modes of operation are provided. Both modes may be supported by a
system, however, only one mode MUST be supported per session.</t>
<t>The server MUST advertise which mode is being used by the session by providing
the mode parameter to the :private-candidate capability.</t>
<section>
<name>Static branch mode: Independent private candidate branch</name>
<t>The private candidate is treated as a separate branch and changes made to
the running configuration are not placed into the private candidate datastore
except in one of the following situations:</t>
<ul>
<li>The client requests that the private candidate be refreshed using a
new <update> operation</li>
<li><commit> is issued (which SHOULD automatically issue an <update>
operation)</li>
</ul>
<t>This approach is similar to the standard approach for source code management
systems.</t>
<t>In this model of operation it is possible for the private candidate
configuration to become significantly out of sync with the running configuration
should the private candidate be open for a long time without an operation
being sent that causes a resync (rebase in source code control terminology).</t>
<t>A <compare> operation may be performed against the initial starting
point (head) of the private candidates branch or against the running configuration.</t>
<t>Conflict detection and resolution is discussed later in this document.</t>
<t>The server signals this mode by setting the mode parameter to the :private-candidate
capability to static-branch as follows:</t>
<sourcecode>
urn:ietf:params:netconf:capability:private-candidate:1.0
?mode=static-branch
</sourcecode>
</section>
<section>
<name>Continuous rebase mode: Continually updating private candidate</name>
<t>The private candidate is treated as a separate branch, however, when changes
are made to the running configuration the update operation will automatically
be run on all open private candidate branches.</t>
<t>This is equivalent to all currently open private candidate branches being
rebased onto the running configuration every time a change is made to it
by any session.</t>
<t>In this model of operation the following should be considered:</t>
<ul>
<li>Because the private candidate is automatically re-synchronized (rebased)
with the running configuration each time a change is made in the running
configuration, the NETCONF session is unaware that their private
candidate configuration has changed unless they perform one of the
get operations on the private candidate and analyse it for changes.</li>
<li>A <compare> operation may be performed against the initial starting
point (head) of the private candidates branch or against the running
configuration but these will both report the same results as the starting
point is continually reset.</li>
<li>The output of the <compare> operation may not match the set
of changes made to the session's private candidate but may include
different output due to the changes in the running configuration
made by other sessions.</li>
<li>A conflict may occur in the automatic update process pushing changes from
the running configuration into the private candidate.</li>
</ul>
<t>The server signals this mode by setting the mode parameter to the :private-candidate
capability to continuous-rebase as follows:</t>
<sourcecode>
urn:ietf:params:netconf:capability:private-candidate:1.0
?mode=continuous-rebase
</sourcecode>
<t>Conflict detection and resolution is discussed later in this document.</t>
</section>
</section>
<section>
<name>Detecting and resolving conflicts</name>
<section>
<name>What is a conflict?</name>
<t>A conflict is when the intent of the NETCONF client may have
been different had it had a different starting point. In configuration
terms, a conflict occurs when the same set of nodes in a configuration being
altered by one user are changed between the start of the configuration
preparation (the first <edit-config>/<edit-data> operation)
and the conclusion of this configuration session (terminated by a
<commit> operation).</t>
<t>The situation where conflicts have the potential of occurring are when
multiple configuration sessions are in progress and one session commits
changes into the running configuration after the private candidate
(branch) was created. </t>
<t>When this happens a conflict occurs if the nodes modified in the running
configuration are the same nodes that are modified in the private candidate
configuration.</t>
<t>Examples of conflicts include:</t>
<ul>
<li>An interface has been deleted in the running configuration that existed
when the private candidate was created. A change to a child node of this specific
interface is made in the private candidate using the default merge operation
would, instead of changing the child node, both recreate the interface and then
set the child node.</li>
<li>A leaf has been modified in the running configuration from the value that
it had when the private candidate was created. The private candidate configuration
changes that leaf to another value.</li>
</ul>
</section>
<section>
<name>Detecting and reporting conflicts</name>
<t>A conflict can occur when an <update> operation is triggered. This
can occur in a number of ways:</t>
<ul>
<li>Manually triggered by the <update> NETCONF operation</li>
<li>Automatically triggered by the NETCONF server running an <update>
operation upon a <commit> being issued by the client in the
private candidate session.</li>
<li>Automatically triggered by the NETCONF server running an <update>
operation upon a <commit> being issued by any other configuration
session (or user). This occurs in continual rebase mode only.</li>
</ul>
<t>When a conflict occurs the client MUST be given the opportunity
to re-evaluate its intent based on the new information. The resolution
of the conflict may be manual or automatic depending on the server and
client decision (discussed later in this document).</t>
<t>When a conflict occurs, a <commit> or <update> operation
MUST fail. It MUST inform the client of the conflict and SHOULD detail
the location of the conflict(s).</t>
<t>In continuous rebase mode, it is possible for the automated
<update> operation to fail. In this instance, the next NETCONF
operation (of any type) MUST fail. It MUST inform the client of the conflict
and SHOULD detail the location of the conflict(s).</t>
<t>The location of the conflict(s) should be reported as a list of
xpaths and values.</t>
</section>
<section>
<name>Conflict resolution</name>
<t>Conflict resolution defines which configuration elements are retained
when a conflict is resolved; those from the running configuration or
those from the private candidate configuration.</t>
<t>When a conflict is detected, the client MUST be informed. The client then
has a number of options available to resolve the conflict.</t>
<t>It is worth noting that in the case of continuous rebase mode
automated <update> operations may be performed against multiple
private candidate configurations at once.</t>
<t>The resolution method SHOULD be provided as an input to the <update>
operation described later in this document. This input may be through
a default selection, a specific input or a configuration element.</t>
<t>The following configuration data is used below to describe the behavior
of each resolution method:</t>
<sourcecode type="xml">
<configure>
<interfaces>
<interface>
<name>intf_one</name>
<description>Link to London<description>
</interface>
<interface>
<name>intf_two</name>
<description>Link to Tokyo<description>
</interface>
</interfaces>
</configure>
</sourcecode>
<t>The following workflow diagram is used and the outcome is
the same regardless of whether static branch mode or continuous
rebase mode is being used. For the purpose of the examples
below assume the update operation is manually provided by a
client.</t>
<artwork>
update commit
+--------------------+---+------> private candidate 1
/ / \
/ edit-config / ⌄
+---+--------+--------+--+--------+----> running configuration
edit-config \ ^
\ /
+---+------------------> private candidate 2
commit
</artwork>
<t>There are three defined resolution methods:</t>
<section>
<name>Ignore</name>
<t>When using the ignore resolution method items in the running
configuration that are not in conflict with the private candidate
configuration are merged from the running configuration
into the private candidate configuration. Nodes that are in conflict
are ignored and not merged. The outcome of this is that the private
candidate configuration reflects changes in the running that were not
being worked on and those that are being worked on in the private
candidate remain in the private candidate. Issuing a <commit>
operation at this point will overwrite the running configuration with
the conflicted items from the private candidate configuration.</t>
<t>Example:</t>
<t>Session 1 edits the configuration by submitting the following</t>
<sourcecode type="xml">
<rpc message-id="config"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target><candidate/><target>
<config>
<configure>
<interfaces>
<interface>
<name>intf_one</name>
<description>Link to San Francisco<description>
</interface>
</interfaces>
</configure>
</config>
</edit-config>
</rpc>
</sourcecode>
<t>Session 2 then edits the configuration deleting the
interface intf_one, updating the description on interface
intf_two and committing the configuration to the running
configuration datastore.</t>
<sourcecode type="xml">
<rpc message-id="config"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target><candidate/><target>
<config>
<configure>
<interfaces>
<interface>
<name operation="delete">intf_one</name>
</interface>
<interface>
<name>intf_two</name>
<description>Link moved to Paris</description>
</interface>
</interfaces>
</configure>
</config>
</edit-config>
</rpc>
</sourcecode>
<t>Session 1 then sends an <update> NETCONF operation.</t>
<sourcecode type="xml">
<rpc message-id="update"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<update>
<resolution-mode>ignore</resolution-mode>
</update>
</rpc>
</sourcecode>
<t>The un-conflicting changes are merged and the conflicting
ones are ignored (and not merged from the running into
private candidate 1).</t>
<t>The resulting data in private candidate 1 is:</t>
<sourcecode type="xml">
<configure>
<interfaces>
<interface>
<name>intf_one</name>
<description>Link to San Francisco<description>
</interface>
<interface>
<name>intf_two</name>
<description>Link moved to Paris<description>
</interface>
</interfaces>
</configure>
</sourcecode>
</section>
<section>
<name>Overwrite</name>
<t>When using the overwrite resolution method items in the running
configuration that are not in conflict with the private candidate
configuration are merged from the running configuration into the
private candidate configuration. Nodes that are in conflict are
pushed from the running configuration into the private candidate
configuration, overwriting any previous changes in the private
candidate configuration. The outcome of this is that the private
candidate configuration reflects the changes in the running
configuration that were not being worked on as well as changing
those being worked on in the private candidate to new values.</t>
<t>Example:</t>
<t>Session 1 edits the configuration by submitting the following</t>
<sourcecode type="xml">
<rpc message-id="config"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target><candidate/><target>
<config>
<configure>
<interfaces>
<interface>
<name>intf_one</name>
<description>Link to San Francisco<description>
</interface>
</interfaces>
</configure>
</config>
</edit-config>
</rpc>
</sourcecode>
<t>Session 2 then edits the configuration deleting the
interface intf_one, updating the description on interface
intf_two and committing the configuration to the running
configuration datastore.</t>
<sourcecode type="xml">
<rpc message-id="config"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target><candidate/><target>
<config>
<configure>
<interfaces>
<interface>
<name operation="delete">intf_one</name>
</interface>
<interface>
<name>intf_two</name>
<description>Link moved to Paris</description>
</interface>
</interfaces>
</configure>
</config>
</edit-config>
</rpc>
</sourcecode>
<t>Session 1 then sends an <update> NETCONF operation.</t>
<sourcecode type="xml">
<rpc message-id="update"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<update>
<resolution-mode>overwrite</resolution-mode>
</update>
</rpc>
</sourcecode>
<t>The un-conflicting changes are merged and the conflicting
ones are pushed into the private candidate 1 overwriting the
existing changes.</t>
<t>The resulting data in private candidate 1 is:</t>
<sourcecode type="xml">
<configure>
<interfaces>
<interface>
<name>intf_two</name>
<description>Link moved to Paris<description>
</interface>
</interfaces>
</configure>
</sourcecode>
</section>
<section>
<name>Revert-on-conflict</name>
<t>When using the revert-on-conflict resolution method items and update
will fail to complete when any conflicting node is found. The
session issuing the update will be informed of the failure.</t>
<t>No changes, whether conflicting or un-conflicting are merged into
the private candidate configuration.</t>
<t>The owner of the private candidate session must then take deliberate
and specific action to adjust the private candidate configuration to
rectify the conflict. This may be by issuing further <edit-config>
or <edit-data> operations, by issuing a <discard-changes>
operation or by issuing an <update> operation with a
different resolution method.</t>
<t>This resolution method is the default resolution method as it
provides for the highest level of visibility and control to ensure
operational stability.</t>
<t>This resolution method may not be selected by a system operating
in continuous rebase mode when performing automatic <update>
operations. Clients operating in continuous rebase mode may use
this resolution mode in their <update> operation.</t>
<t>Example:</t>
<t>Session 1 edits the configuration by submitting the following</t>
<sourcecode type="xml">
<rpc message-id="config"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target><candidate/><target>
<config>
<configure>
<interfaces>
<interface>
<name>intf_one</name>
<description>Link to San Francisco<description>
</interface>
</interfaces>
</configure>
</config>
</edit-config>
</rpc>
</sourcecode>
<t>Session 2 then edits the configuration deleting the
interface intf_one, updating the description on interface
intf_two and committing the configuration to the running
configuration datastore.</t>
<sourcecode type="xml">
<rpc message-id="config"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target><candidate/><target>
<config>
<configure>
<interfaces>
<interface>
<name operation="delete">intf_one</name>
</interface>
<interface>
<name>intf_two</name>
<description>Link moved to Paris</description>
</interface>
</interfaces>
</configure>
</config>
</edit-config>
</rpc>
</sourcecode>
<t>Session 1 then sends an <update> NETCONF operation.</t>
<sourcecode type="xml">
<rpc message-id="update"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<update>
<resolution-mode>revert-on-conflict</resolution-mode>
</update>
</rpc>
</sourcecode>
<t>A conflict is detected and no merges/overwrite
operations happen.</t>
<t>The resulting data in private candidate 1 is:</t>
<sourcecode type="xml">
<configure>
<interfaces>
<interface>
<name>intf_one</name>
<description>Link to San Francisco<description>
</interface>
<interface>
<name>intf_two</name>
<description>Link to Tokyo<description>
</interface>
</interfaces>
</configure>
</sourcecode>
</section>
</section>
<section>
<name>Default resolution mode and advertisement of this mode</name>
<t>The default resolution mode is revert-on-conflict, however, a system MAY
choose to select a different default resolution mode.</t>
<t>The default resolution mode MAY be advertised in the :private-candidate
capability by adding the resolution-mode parameter. If the system default
is revert-on-conflict then this is optional.</t>
<t>If a server does not support revert-on-conflict it MUST report the
default resolution mode.</t>
<t>If the system default is chosen to be anything other than revert-on-conflict
then this MUST be signalled using the resolution-mode parameter, for example:</t>
<sourcecode>
urn:ietf:params:netconf:capability:private-candidate:1.0
?mode=static-branch&default-resolution-mode=overwrite
</sourcecode>
</section>
<section>
<name>Supported resolution modes</name>
<t>A server SHOULD support all three resolution modes, however, if the server
does not support all three modes, the server MUST report the supported modes
in the :private-candidate capability using the supported-resolution-modes,
for example:</t>
<sourcecode>
urn:ietf:params:netconf:capability:private-candidate:1.0
?mode=static-branch
&supported-resolution-modes=revert-on-conflict,ignore
</sourcecode>
</section>
</section>
<section>
<name>NETCONF operations</name>
<section>
<name>New NETCONF operations</name>
<section>
<name><update></name>
<t>The <update> operation is provided to allow NETCONF clients
(or servers) to trigger a rebase of the private candidate configuration
against the running configuration.</t>
<t>The <update> operation may be triggered manually by the
client or automatically by the server.</t>
<t>The <update> operation MUST be triggered by a <commit>
operation being executed in any candidate configuration on the device
if the device is operating in continuous rebase mode.</t>
<t>The <update> operation SHOULD be triggered by a specific
NETCONF session issuing a <commit> operation.</t>
<section>
<name><resolution-mode> parameter</name>
<t>The <update> operation takes the
<resolution-mode> parameter</t>
<t>The resolution modes are described earlier in this document
and the accepted inputs are:</t>
<ul>
<li>revert-on-conflict (default)</li>
<li>ignore</li>
<li>overwrite</li>
</ul>
</section>
</section>
</section>
<section>
<name>Updated NETCONF operations</name>
<t>Specific NETCONF operations altered by this document are listed in this section.
Any notable behavior with existing unaltered NETCONF operations is noted in the
appendix.</t>
<section>
<name><edit-config></name>
<t>The <edit-config> operation is updated to accept
private-candidate as valid input to the <target> field.</t>
<t>The use of <edit-config> will create a private candidate
configuration if one does not already exist for that NETCONF
session.</t>
<t>Sending an <edit-config> request to private-candidate
after one has been sent to the shared candidate datastore
in the same session will fail (and visa-versa).</t>
<t>Multiple <edit-config> requests may be sent to the
private-candidate datastore in a single session.</t>
</section>
<section>
<name><lock> and <unlock></name>
<t>Performing a <lock> on the private-candidate datastore is a valid operation and
will also lock the running configuration.</t>
<t>Taking a lock on this datastore will stop other session from committing any
configuration changes, regardless of the datastore.</t>
<t>Other NETCONF sessions are still able to create a new private-candidate
configurations.</t>
<t>Performing an <unlock> on the private-candidate datastore is a valid operation.
This will also unlock the running configuration. Unlocking the private-candidate
datastore allows other sessions to resume <commit> functions. </t>
<t>Changes in the private-candidate datastore are not lost when the
lock is released.</t>
<t>Attempting to perform a <lock> or <unlock> on any other datastore while the
private-candidate datastore is locked will fail. Attempting to perform a <lock>
or <unlock> on any other sessions private-candidate datastore will also fail.</t>
</section>
<section>
<name><compare></name>
<t>Performing a <xref target="RFC9144"><compare></xref>
with the private-candidate datastore as either the <source>
or <target> is a valid operation.</t>
<t>If <compare> is performed prior to a private candidate configuration
being created, one will be created at that point.</t>
<t>The <compare> operation is extended by this document to allow the ability to
compare the private-candidate datastore (at its current point in time) with the
same private-candidate datastore at an earlier point in time. This document adds
the optional <reference-point> node to the input of the <compare>
operation that accepts the values of last-update or creation-point.</t>
<t>Servers MAY support this functionality but are not required to by this document.</t>
<t>The last-update selection of <reference-point> will provide an output
comparing the current private-candidate configuration datastore with the same
private-candidate datastore at the time it was last updated using the <update>
NETCONF operation described in this document (whether automatically or manually triggered).</t>
<t>The creation-point selection of <reference-point> will provide an output
comparing the current private-candidate configuration datastore with the same
private-candidate datastore at the time this private-candidate was initially created.</t>
</section>
<section>
<name><get-config></name>
<t>The <get-config> operation is updated to accept private-candidate as
valid input to the <source> field.</t>
<t>The use of <get-config> will create a private candidate configuration
if one does not already exist for that NETCONF session.</t>
<t>Sending an <get-config> request to private-candidate
after one has been sent to the shared candidate datastore
in the same session will fail (and visa-versa).</t>
</section>
<section>
<name><get-data></name>
<t>The <get-data> operation accepts the private-candidate as a valid datastore.</t>
<t>The use of <get-data> will create a private candidate configuration
if one does not already exist for that NETCONF session.</t>
<t>Sending an <get-data> request to private-candidate
after one has been sent to the shared candidate datastore
in the same session will fail (and visa-versa).</t>
</section>
<section>
<name><copy-config></name>
<t>The <copy-config> operation is updated to accept private-candidate as
a valid input to the <source> or <target> fields.</t>
</section>
<section>
<name><delete-config></name>
<t>The <delete-config> operation is updated to accept private-candidate as
a valid input to the <target> field.</t>
</section>
<section>
<name><commit></name>
<t>The <commit> operation SHOULD trigger an <update> operation.</t>
<t>Nothing in this document alters the standard behavior of the <persist> or
<persist-id> options and these SHOULD work when using the private-candidate
configuration datastore.</t>
</section>
</section>
</section>
</section>
<section anchor="IANA">
<!-- All drafts are required to have an IANA considerations section. See RFC 8126 for a guide.-->
<name>IANA Considerations</name>
<t>This memo includes no request to IANA.</t>
</section>
<section anchor="Security">
<!-- All drafts are required to have a security considerations section. See RFC 3552 for a guide. -->
<name>Security Considerations</name>
<t>This document should not affect the security of the Internet.</t>
</section>
<!-- NOTE: The Acknowledgements and Contributors sections are at the end of this template -->
</middle>
<back>
<references>
<name>References</name>
<references>
<name>Normative References</name>
<xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.2119.xml"/>
<xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.8174.xml"/>
<xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.6241.xml"/>
<xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.8342.xml"/>
<xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.9144.xml"/>
<xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.5717.xml"/>
<xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.8040.xml"/>
<xi:include href="https://www.rfc-editor.org/refs/bibxml/reference.RFC.8527.xml"/>
<!-- The recommended and simplest way to include a well known reference -->
</references>
<references>
<name>Informative References</name>
</references>
</references>
<section>
<name>Behavior with unaltered NETCONF operations</name>
<section>
<name><get></name>
<t>The <get> operation does not accept a datastore value and therefore
this document is not applicable to this operation. The use of the
get operation will not create a private candidate configuration.</t>
</section>
</section>
<section anchor="Contributors" numbered="false">
<name>Contributors</name>
<t>The authors would like to thank Jan Lindblad, Lori-Ann McGrath, Jason Sterne and