Subject: Re: [Netconf] Confirmed commit

From: Jonathan Hansford <[email-masked]>
Date: Fri, 20 Sep 2013 11:29:31 +0100

I propose the following changes to address Andy's issue relating to
consecutive confirmed commits and my issue relating to the confusing
terminology: 

8.4.1. Description (paras 2-6)
A <commit> operation with
the <confirmed> parameter (an unconfirmed <commit>) MUST be reverted if
a confirming commit is not issued within the timeout period (by default
600 seconds = 10 minutes). The confirming commit is a <commit> operation
without the <confirmed> parameter and, if successful, cannot be
reverted. The timeout period can be adjusted with the <confirm-timeout>
parameter. If a follow-up unconfirmed <commit> operation is issued
before the timer expires, the timer is reset to the new value (600
seconds by default). Both the confirming commit and a follow-up
unconfirmed <commit> operation MAY introduce additional changes to the
configuration.
If the <persist> element is not given in the unconfirmed
commit operation, any follow-up commit and the confirming commit MUST be
issued on the same session that issued the unconfirmed commit. If the
<persist> element is given in the unconfirmed <commit> operation, a
follow-up commit and the confirming commit can be given on any session,
and they MUST include a <persist-id> element with a value equal to the
given value of the <persist> element.
If the server also advertises the
:startup capability, a <copy-config> from running to startup is also
necessary to save the changes to startup. If the session issuing a
sequence of one or more unconfirmed commits is terminated for any reason
before the confirm timeout expires, the server MUST restore the
configuration to its state before the sequence of unconfirmed commits
was issued, unless the last unconfirmed commit also included a <persist>
element.
If the device reboots for any reason before the confirm timeout
expires, the server MUST restore the configuration to its state before
the sequence of unconfirmed commits was issued.
If a confirming commit
is not issued, the device will revert its configuration to the state
prior to the issuance of the first in the current sequence of
unconfirmed commits. To cancel the current sequence of unconfirmed
commits and revert changes without waiting for the confirm timeout to
expire, the client can explicitly restore the configuration to its state
before the sequence of unconfirmed commits was issued, by using the
<cancel-commit> operation.
:
8.4.4.1.
<cancel-commit>
Description:
Cancels an ongoing sequence of unconfirmed
commits. If the <persist-id> parameter is not given, the <cancel-commit>
operation MUST be issued on the same session that issued the sequence of
unconfirmed commits.
Parameters:
persist-id:
Cancels a persistent
sequence of unconfirmed commits. The value MUST be equal to the value
given in the <persist> parameter to the <commit> operation. If the value
does not match, the operation fails with an "invalid-value"
error.
:
8.4.5.1. <commit>
The :confirmed-commit:1.1 capability allows 4
additional parameters to the <commit>
operation.
Parameters:
confirmed:
Perform an unconfirmed <commit>
operation.
confirm-timeout:
Timeout period for confirmed commit, in
seconds. If unspecified, the confirm timeout defaults to 600
seconds.
persist:
Make the unconfirmed commit survive a session
termination, and set a token on the ongoing sequence of unconfirmed
commits.
persist-id:
Used to issue a follow-up unconfirmed commit or a
confirming commit from any session, with the token from the previous
<commit> operation.

On 2013-09-20 11:08, Bert Wijnen (IETF) wrote: 

THat is one (and probably good) approach.
> So can the
authors/experts suggest some text that makes
> sense as a fix (or better
clarification) to a possible
> erratum?
> Bert
> On 9/20/13 10:00
AM, Jonathan Hansford wrote:
> 
>> Would it be worth agreeing text
online then raising an erratum? Sent from my BlackBerry -----Original
Message----- From: "Bert Wijnen (IETF)" <[email-masked] [1]> Date:
Fri, 20 Sep 2013 08:41:42 To: Andy Bierman<[email-masked] [2]>;
Jonathan Hansford<[email-masked] [3]>; Netconf<[email-masked]
[4]> Subject: Re: [Netconf] Confirmed commit See at bottom On 9/20/13
7:13 AM, Juergen Schoenwaelder wrote: 
>>> On Thu, Sep 19, 2013 at
01:39:28PM -0700, Andy Bierman wrote: 
>>>> Hi, I always found
section 8.4.1, para 2 confusing. T0: /int8.1 does not exist 
merge /int8.1 value=20 commit confirmed confirm-timeout=60
>>>> T1:
/int8.1 = 20 merge /int8.1 value=30 commit confirmed confirm-timeout=60
T2: /int8.1 = 30 T3: timeout occurs: para 6 says: If a confirming commit
is not issued, the device will revert its configuration to the state
prior to the issuance of the confirmed commit. The problem is that there
are 2 confirmed commit operations. At time T3 does the server go back to
state T1 or T0? (Our server goes back to T0). The 2nd commit contains a
confirmed parameter, and para 2 sentence 2 clearly says this is not a
confirming commit. The text does not actually define a "confirmed
commit", but I assume it is a commit with a confirmed parameter.
Therefore, paragraphs 5 - 7 are wrong where they refer to "the confirmed
commit", because there are 2 of them.
>>> Yes, this corner case where
multiple confirmed commits are issued is not described well. Your
interpretation that subsequent confirmed commits effectively extend the
first one makes sense to me.
>> Can wee keep this somewhere so we
clarify it if we ever have to open up and update the document? Bert 

>>> /js

Links:
------
[1] mailto:[email-masked]
[2]
mailto:[email-masked]
[3] mailto:[email-masked]
[4]
mailto:[email-masked]

---

From: Jonathan Hansford <[email-masked]>
Date: Fri, 20 Sep 2013 11:41:18 +0100

I realise these changes have a knock-on impact on other parts of the
document (e.g. Appendices C and E), but I thought it important to try
and propose core changes before visiting those other sections. 

On
2013-09-20 11:29, Jonathan Hansford wrote: 

> I propose the following
changes to address Andy's issue relating to consecutive confirmed
commits and my issue relating to the confusing terminology: 
> 
> 8.4.1.
Description (paras 2-6)
> A <commit> operation with the <confirmed>
parameter (an unconfirmed <commit>) MUST be reverted if a confirming
commit is not issued within the timeout period (by default 600 seconds =
10 minutes). The confirming commit is a <commit> operation without the
<confirmed> parameter and, if successful, cannot be reverted. The
timeout period can be adjusted with the <confirm-timeout> parameter. If
a follow-up unconfirmed <commit> operation is issued before the timer
expires, the timer is reset to the new value (600 seconds by default).
Both the confirming commit and a follow-up unconfirmed <commit>
operation MAY introduce additional changes to the configuration.
> If
the <persist> element is not given in the unconfirmed commit operation,
any follow-up commit and the confirming commit MUST be issued on the
same session that issued the unconfirmed commit. If the <persist>
element is given in the unconfirmed <commit> operation, a follow-up
commit and the confirming commit can be given on any session, and they
MUST include a <persist-id> element with a value equal to the given
value of the <persist> element.
> If the device reboots for any reason before the confirm
timeout expires, the server MUST restore the configuration to its state
before the sequence of unconfirmed commits was issued.
> If a confirming
commit is not issued, the device will revert its configuration to the
state prior to the issuance of the first in the current sequence of
unconfirmed commits. To cancel the current sequence of unconfirmed
commits and revert changes without waiting for the confirm timeout to
expire, the client can explicitly restore the configuration to its state
before the sequence of unconfirmed commits was issued, by using the
<cancel-commit> operation.
> 8.4.4.1. <cancel-commit>
Description:
> Cancels an ongoing sequence of unconfirmed commits. If
the <persist-id> parameter is not given, the <cancel-commit> operation
MUST be issued on the same session that issued the sequence of
unconfirmed commits.
sequence of unconfirmed commits. The value MUST be equal to the value
given in the <persist> parameter to the <commit> operation. If the value
does not match, the operation fails with an "invalid-value" error.
8.4.5.1. <commit>
> The :confirmed-commit:1.1 capability allows 4
additional parameters to the <commit> operation.
confirmed:
> Perform an unconfirmed <commit> operation.
>
confirm-timeout:
> Timeout period for confirmed commit, in seconds. If
unspecified, the confirm timeout defaults to 600 seconds.
> persist:
Make the unconfirmed commit survive a session termination, and set a
token on the ongoing sequence of unconfirmed commits.
> persist-id:
Used to issue a follow-up unconfirmed commit or a confirming commit from
any session, with the token from the previous <commit> operation.
On 2013-09-20 11:08, Bert Wijnen (IETF) wrote: 
> 
>> THat is one (and
probably good) approach.
>> 
>> So can the authors/experts suggest some
text that makes
>> sense as a fix (or better clarification) to a
possible
>> erratum?
>> 
>> Bert
>> 
>> On 9/20/13 10:00 AM, Jonathan
Hansford wrote:
>> 
>>> Would it be worth agreeing text online then
raising an erratum? Sent from my BlackBerry -----Original Message-----
From: "Bert Wijnen (IETF)" <[email-masked] [1]> Date: Fri, 20 Sep
2013 08:41:42 To: Andy Bierman<[email-masked] [2]>; Jonathan
Hansford<[email-masked] [3]>; Netconf<[email-masked] [4]>
Subject: Re: [Netconf] Confirmed commit See at bottom On 9/20/13 7:13

>>>>>> merge /int8.1 value=20 commit confirmed confirm-timeout=60
T1: /int8.1 = 20 merge /int8.1 value=30 commit confirmed
confirm-timeout=60 T2: /int8.1 = 30 T3: timeout occurs: para 6 says: If
a confirming commit is not issued, the device will revert its
configuration to the state prior to the issuance of the confirmed
commit. The problem is that there are 2 confirmed commit operations. At
time T3 does the server go back to state T1 or T0? (Our server goes back
to T0). The 2nd commit contains a confirmed parameter, and para 2
sentence 2 clearly says this is not a confirming commit. The text does
not actually define a "confirmed commit", but I assume it is a commit
with a confirmed parameter. Therefore, paragraphs 5 - 7 are wrong where
they refer to "the confirmed commit", because there are 2 of them.
Yes, this corner case where multiple confirmed commits are issued is not
described well. Your interpretation that subsequent confirmed commits
effectively extend the first one makes sense to me.
>>> Can wee keep
this somewhere so we clarify it if we ever have to open up and update
the document? Bert 
>>>> /js

Links:
------
[1]
mailto:[email-masked]
[2] mailto:[email-masked]
[3]
mailto:[email-masked]
[4] mailto:[email-masked]

---

From: Martin Bjorklund <[email-masked]>
Date: Fri, 20 Sep 2013 12:57:18 +0200 (CEST)

Hi,

I don't think we should change the terminology in an errata.
(and actually I don't think we should change it at all - I agree there
might be a better term, but the term "confirmed commit" has been used
for several years and people are used to it)

Your text about sequence of commits is fine; but I think we should
stick to the current terminology.

/martin

---

From: Jonathan Hansford <[email-masked]>
Date: Fri, 20 Sep 2013 12:50:05 +0100

Hi, 

I agree that changing the terminology would be confusing for
those who are used to it, but in its current form it is extremely
confusing to those who come to it cold. To my mind there needs, at
least, to be something that seeks to explain the current terminology. It
has taken me several readings, a trawl of the NETCONF list archive and
Internet search to reach some kind of understanding and even then it had
to be confirmed by someone "in the know". 

However, putting that to one
side for now, my text without the changed terminology becomes: 

8.4.1.
Description (paras 2-6)
A <commit> operation with the <confirmed>
parameter (an unconfirmed <commit>) MUST be reverted if a confirming
commit is not issued within the timeout period (by default 600 seconds =
10 minutes). The confirming commit is a <commit> operation without the
<confirmed> parameter and, if successful, cannot be reverted. The
timeout period can be adjusted with the <confirm-timeout> parameter. If
a follow-up unconfirmed <commit> operation is issued before the timer
expires, the timer is reset to the new value (600 seconds by default).
Both the confirming commit and a follow-up unconfirmed <commit>
operation MAY introduce additional changes to the configuration.
If the
<persist> element is not given in the unconfirmed commit operation, any
follow-up commit and the confirming commit MUST be issued on the same
session that issued the unconfirmed commit. If the <persist> element is
given in the unconfirmed <commit> operation, a follow-up commit and the
confirming commit can be given on any session, and they MUST include a
<persist-id> element with a value equal to the given value of the
<persist> element.
If the server also advertises the :startup
capability, a <copy-config> from running to startup is also necessary to
save the changes to startup. If the session issuing a sequence of one or
more unconfirmed commits is terminated for any reason before the confirm
timeout expires, the server MUST restore the configuration to its state
before the sequence of unconfirmed commits was issued, unless the last
unconfirmed commit also included a <persist> element.
If the device
reboots for any reason before the confirm timeout expires, the server
MUST restore the configuration to its state before the sequence of
unconfirmed commits was issued.
If a confirming commit is not issued,
the device will revert its configuration to the state prior to the
issuance of the first in the current sequence of unconfirmed commits. To
cancel the current sequence of unconfirmed commits and revert changes
without waiting for the confirm timeout to expire, the client can
explicitly restore the configuration to its state before the sequence of
unconfirmed commits was issued, by using the <cancel-commit>
operation.
:
8.4.4.1. <cancel-commit>
Description:
Cancels an ongoing
sequence of unconfirmed commits. If the <persist-id> parameter is not
given, the <cancel-commit> operation MUST be issued on the same session
that issued the sequence of unconfirmed
commits.
Parameters:
persist-id:
Cancels a persistent sequence of
unconfirmed commits. The value MUST be equal to the value given in the
<persist> parameter to the <commit> operation. If the value does not
match, the operation fails with an "invalid-value" error.
:
8.4.5.1.
<commit>
The :confirmed-commit:1.1 capability allows 4 additional
parameters to the <commit> operation.
Parameters:
confirmed:
Perform an
unconfirmed <commit> operation.
confirm-timeout:
Timeout period for
confirmed commit, in seconds. If unspecified, the confirm timeout
defaults to 600 seconds.
persist:
Make the unconfirmed commit survive a
session termination, and set a token on the ongoing sequence of
unconfirmed commits.
persist-id:
Used to issue a follow-up unconfirmed
commit or a confirming commit from any session, with the token from the
previous <commit> operation. 

Jonathan 

On 2013-09-20 11:57, Martin

---

From: "Bert Wijnen (IETF)" <[email-masked]>
Date: Fri, 20 Sep 2013 13:58:14 +0200

Speaking as a technical contributor.

I also think we should stick to the terminology we have been using for
many years now. So I was thinking more about some clarifying or explanatory
text instead of renaming our terminology.

Bert

---

From: Jonathan Hansford <[email-masked]>
Date: Fri, 20 Sep 2013 13:50:16 +0100

In order to address the terminology issue without changing the
terminology, how about changing the first paragraph of 8.4.1 to: 

The
:confirmed-commit:1.1 capability indicates that the server will support
the <cancel-commit> operation, the <confirmed>, <confirm-timeout>,
<persist>, and <persist-id> parameters for the <commit> operation, and
differentiate between a "to be confirmed" <commit> operation (a
"confirmed commit") and a confirming <commit> operation. See Section 8.3
for further details on the <commit> operation. 

Jonathan 

On

>> Hi, I
don't think we should change the terminology in an errata. (and actually
I don't think we should change it at all - I agree there might be a
better term, but the term "confirmed commit" has been used for several
years and people are used to it) Your text about sequence of commits is
fine; but I think we should stick to the current terminology. /martin
Jonathan Hansford <[email-masked] [8]> wrote: 
>>> I propose
the following changes to address Andy's issue relating to consecutive
confirmed commits and my issue relating to the confusing terminology:
8.4.1. Description (paras 2-6) A <commit> operation with the <confirmed>
parameter (an unconfirmed <commit>) MUST be reverted if a confirming
commit is not issued within the timeout period (by default 600 seconds =
10 minutes). The confirming commit is a <commit> operation without the
<confirmed> parameter and, if successful, cannot be reverted. The
timeout period can be adjusted with the <confirm-timeout> parameter. If
a follow-up unconfirmed <commit> operation is issued before the timer
expires, the timer is reset to the new value (600 seconds by default).
Both the confirming commit and a follow-up unconfirmed <commit>
operation MAY introduce additional changes to the configuration. If the
<persist> element is not given in the unconfirmed commit operation, any
follow-up commit and the confirming commit MUST be issued on the same
session that issued the unconfirmed commit. If the <persist> element is
given in the unconfirmed <commit> operation, a follow-up commit and the
confirming commit can be given on any session, and they MUST include a
<persist-id> element with a value equal to the given value of the
<persist> element. If the server also advertises the :startup
capability, a <copy-config> from running to startup is also necessary to
save the changes to startup. If the session issuing a sequence of one or
more unconfirmed commits is terminated for any reason before the confirm
timeout expires, the server MUST restore the configuration to its state
before the sequence of unconfirmed commits was issued, unless the last
unconfirmed commit also included a <persist> element. If the device
reboots for any reason before the confirm timeout expires, the server
MUST restore the configuration to its state before the sequence of
unconfirmed commits was issued. If a confirming commit is not issued,
the device will revert its configuration to the state prior to the
issuance of the first in the current sequence of unconfirmed commits. To
cancel the current sequence of unconfirmed commits and revert changes
without waiting for the confirm timeout to expire, the client can
explicitly restore the configuration to its state before the sequence of
unconfirmed commits was issued, by using the <cancel-commit> operation.
: 8.4.4.1. <cancel-commit> Description: Cancels an ongoing sequence of
unconfirmed commits. If the <persist-id> parameter is not given, the
<cancel-commit> operation MUST be issued on the same session that issued
the sequence of unconfirmed commits. Parameters: persist-id: Cancels a
persistent sequence of unconfirmed commits. The value MUST be equal to
the value given in the <persist> parameter to the <commit> operation. If
the value does not match, the operation fails with an "invalid-value"
error. : 8.4.5.1. <commit> The :confirmed-commit:1.1 capability allows 4
additional parameters to the <commit> operation. Parameters: confirmed:
Perform an unconfirmed <commit> operation. confirm-timeout: Timeout
period for confirmed commit, in seconds. If unspecified, the confirm
timeout defaults to 600 seconds. persist: Make the unconfirmed commit
survive a session termination, and set a token on the ongoing sequence
of unconfirmed commits. persist-id: Used to issue a follow-up
unconfirmed commit or a confirming commit from any session, with the
token from the previous <commit> operation. On 2013-09-20 11:08, Bert
Wijnen (IETF) wrote:THat is one (and probably good) approach. 
So can the
>>> clarification) to a possible Yes, this
corner case where multiple confirmed commits are issued is not described
well. Your interpretation that subsequent confirmed commits effectively
extend the first one makes sense to me. Can wee keep this somewhere so
we clarify it if we ever have to open up and update the document? Bert

Links:
------
[1] mailto:[email-masked]
[2]
mailto:[email-masked]
[3] mailto:[email-masked]
[4]
mailto:[email-masked]
[5] mailto:[email-masked]
[6]
mailto:[email-masked]
[7] mailto:[email-masked]
[8]
mailto:[email-masked]

---

From: Andy Bierman <[email-masked]>
Date: Fri, 20 Sep 2013 08:46:11 -0700

Hi,

I do not think the term "confirmed commit" is confusing.
The use of the term "the" is confusing.

The section also does not make it clear just how dangerous confirmed-commit
is to use without holding locks for the entire procedure. It does not make
it extra clear that using the "persist" parameter will at least cause all
commits
by other users to fail (because they won't know the persist-id to use).

This at least prevents other users from providing the confirming commit
or extending the current confirmed commit.  It does not prevent them from
adding edits to candidate so that when the real confirming commit arrives
(with the correct persist-id) these extra edits will be added to the
running config.

Andy

On Fri, Sep 20, 2013 at 5:50 AM, Jonathan Hansford
<[email-masked]>wrote:

> **
> The :confirmed-commit:1.1 capability indicates that the server will
> support the <cancel-commit> operation, the <confirmed>, <confirm-timeout>,
> differentiate between a “to be confirmed” <commit> operation (a “confirmed
> commit”) and a confirming <commit> operation. See Section 8.3 for further
> details on the <commit> operation.
>
> Jonathan
>
> On 2013-09-20 12:58, Bert Wijnen (IETF) wrote:
>
> Hi, I don't think we should change the terminology in an errata. (and
> actually I don't think we should change it at all - I agree there might be
> a better term, but the term "confirmed commit" has been used for several
> terminology: 8.4.1. Description (paras 2-6) A <commit> operation with the
> <confirmed> parameter (an unconfirmed <commit>) MUST be reverted if a
> confirming commit is not issued within the timeout period (by default 600
> seconds = 10 minutes). The confirming commit is a <commit> operation
> without the <confirmed> parameter and, if successful, cannot be reverted.
> The timeout period can be adjusted with the <confirm-timeout> parameter. If
> expires, the timer is reset to the new value (600 seconds by default). Both
> the confirming commit and a follow-up unconfirmed <commit> operation MAY
> introduce additional changes to the configuration. If the <persist> element
> is not given in the unconfirmed commit operation, any follow-up commit and
> the confirming commit MUST be issued on the same session that issued the
> unconfirmed commit. If the <persist> element is given in the unconfirmed
> <commit> operation, a follow-up commit and the confirming commit can be
> given on any session, and they MUST include a <persist-id> element with a
> value equal to the given value of the <persist> element. If the server also
> advertises the :startup capability, a <copy-config> from running to startup
> is also necessary to save the changes to startup. If the session issuing a
> configuration to its state before the sequence of unconfirmed commits was
> issued, unless the last unconfirmed commit also included a <persist>
> element. If the device reboots for any reason before the confirm timeout
> expires, the server MUST restore the configuration to its state before the
> sequence of unconfirmed commits was issued. If a confirming commit is not
> issued, the device will revert its configuration to the state prior to the
> unconfirmed commits was issued, by using the <cancel-commit> operation. :
> 8.4.4.1. <cancel-commit> Description: Cancels an ongoing sequence of
> persistent sequence of unconfirmed commits. The value MUST be equal to the
> value given in the <persist> parameter to the <commit> operation. If the
> value does not match, the operation fails with an "invalid-value" error. :
> 8.4.5.1. <commit> The :confirmed-commit:1.1 capability allows 4 additional
> parameters to the <commit> operation. Parameters: confirmed: Perform an
> unconfirmed <commit> operation. confirm-timeout: Timeout period for
> confirmed commit, in seconds. If unspecified, the confirm timeout defaults
> to 600 seconds. persist: Make the unconfirmed commit survive a session
> commits. persist-id: Used to issue a follow-up unconfirmed commit or a
> <commit> operation. On 2013-09-20 11:08, Bert Wijnen (IETF) wrote:THat is
> one (and probably good) approach.
>
> So can the
>
> erratum? Bert On 9/20/13 10:00
>
> Jonathan Hansford<[email-masked] [3]>; Netconf<[email-masked][4]>
> Subject: Re: [Netconf] Confirmed commit See at bottom On 9/20/13 7:13 AM,
> Juergen Schoenwaelder wrote:
>
>  On Thu, Sep 19, 2013 at
>
>   section 8.4.1, para 2 confusing. T0: /int8.1 does not existmerge
> /int8.1 value=20 commit confirmed confirm-timeout=60
>
>  T1:
>
> T2: /int8.1 = 30 T3: timeout occurs: para 6 says: If a confirming commit is
> not issued, the device will revert its configuration to the state prior to
> the issuance of the confirmed commit. The problem is that there are 2
> confirmed commit operations. At time T3 does the server go back to state T1
> or T0? (Our server goes back to T0). The 2nd commit contains a confirmed
> parameter, and para 2 sentence 2 clearly says this is not a confirming
> commit. The text does not actually define a "confirmed commit", but I
> assume it is a commit with a confirmed parameter. Therefore, paragraphs 5 -
> 7 are wrong where they refer to "the confirmed commit", because there are 2
> of them.
>
>  Links: ------ [1] mailto:[email-masked] [2] mailto:
> [email-masked] [3] mailto:[email-masked] [4] mailto:
> [email-masked]
>
>
> _______________________________________________
> Netconf mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netconf
>
>