Subject: [Netconf] the name "checksum" in YANG library

From: Martin Bjorklund <[email-masked]>
Date: Thu, 11 Oct 2018 12:46:00 +0200 (CEST)

Hi,

Several reviewers in the IESG have commented that the name "checksum"
in YANG library is misleading.  It is not really a checksum ('There is
no requirement that the same information always results in the same
"checksum" value.')

So since many people have complained, maybe we should change it.

After a quick discussion among (some of the) authors, we suggest that
we call it "YANG library content identifier" or "content-id" for
short.

The changes would be:

OLD:

   o  YANG library checksum: A server-generated checksum of the contents
      of the YANG library.

NEW:

   o  YANG library content identifier: A server-generated identifier of
      the contents of the YANG library.

OLD:

   o  The "/yang-library/checksum" leaf contains the YANG library
      checksum, which is a unique implementation-specific identifier
      representing the current information in the YANG library on a
      specific server.

NEW:

   o  The "/yang-library/content-id" leaf contains the YANG library
      content identifier, which is a unique implementation-specific
      identifier representing the current information in the YANG
      library on a specific server.

... and various simpler search&replaces.

We would also update the schema-mount and netconf-nmda documents to
use the new term.

Does anyone object to this change?

/martin

---

From: Rohit R Ranade <[email-masked]>
Date: Thu, 11 Oct 2018 11:18:51 +0000

Since this leaf has to change every-time the content of YANG library changes, "content-modify-count" can also be used which is simple for a server to implement (just increment when content changes) and also for client or a human reader to understand.

-----Original Message-----
From: Netconf [mailto:[email-masked]] On Behalf Of Martin Bjorklund
Sent: 11 October 2018 16:16
To: [email-masked]
Subject: [Netconf] the name "checksum" in YANG library

Hi,

Several reviewers in the IESG have commented that the name "checksum"
in YANG library is misleading.  It is not really a checksum ('There is no requirement that the same information always results in the same "checksum" value.')

After a quick discussion among (some of the) authors, we suggest that we call it "YANG library content identifier" or "content-id" for short.

The changes would be:

OLD:

NEW:

OLD:

NEW:

.... and various simpler search&replaces.

We would also update the schema-mount and netconf-nmda documents to use the new term.

/martin

_______________________________________________
Netconf mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/netconf

---

From: Martin Bjorklund <[email-masked]>
Date: Thu, 11 Oct 2018 13:31:13 +0200 (CEST)

Rohit R Ranade <[email-masked]> wrote:
> Since this leaf has to change every-time the content of YANG library
> changes, "content-modify-count" can also be used which is simple for a
> server to implement (just increment when content changes) and also for
> client or a human reader to understand.

But it doesn't have to change everytime, it could very well be
implemented as a checksum of the contents.

/martin

---

From: Rohit R Ranade <[email-masked]>
Date: Fri, 12 Oct 2018 05:59:19 +0000

Hi Martin,

" The value of this leaf MUST change whenever the
      information in the YANG library changes." ==> This statement in Section 3, indicates that the value must change when content changes.

The draft has also placed a constraint that it is a " unique implementation-specific identifier". When the contents changes, especially if the length of the data which is used for checksum changes, then the resulting checksum values may not be unique.

So I feel it is simpler, if a counter is used.

With Regards,
Rohit

-----Original Message-----
From: Martin Bjorklund [mailto:[email-masked]] 
Sent: 11 October 2018 17:01
To: Rohit R Ranade <[email-masked]>
Cc: [email-masked]
Subject: Re: [Netconf] the name "checksum" in YANG library

> client or a human reader to understand.

But it doesn't have to change everytime, it could very well be implemented as a checksum of the contents.

/martin

---

From: Vladimir Vassilev <[email-masked]>
Date: Fri, 12 Oct 2018 12:56:34 +0200

Hi,

> So I feel it is simpler, if a counter is used.

There is this usecase where a client can compare the checksum against 
already retrieved checksum or a list of checksums and know that it is 
connected to a device with schema it was designed to work with or not, 
or has already retrieved the yang library contents and compiled and 
cached the schema in case of smarter client etc. I do not think 
replacing this information with the information how many times the 
schema has changed (since the last restart?, has it changed and returned 
back to the same state?) can serve the same purpose as the checksum even 
if the checksum is calculated with implementation dependent algorithm.

That said it is clear that the presented usecase is dependent on what 
the vendor chose to implement as "checksum" algorithm. How probable it 
is that two different yang libraries generate identical checksums etc.

Vladimir

---

From: Robert Wilton <[email-masked]>
Date: Fri, 12 Oct 2018 12:26:50 +0100

Hi Rohit,

If the server restarts, or the YANG management daemon on the server 
restarts, and the YANG library content is the same then it is less work 
on the client to return the same content-id value.

It isn't the end of the world if it is different because it just forces 
the client to re-download and re-parse YANG library. However, it could 
be a problem for the client if the server returns the same value if the 
server reboots and uses a different set of YANG modules after it has 
rebooted (e.g. after a software upgrade).

Perhaps if you write the counter to persistent storage this can still be 
made to work in a reliable way, but using a robust hash function over 
the contents in YANG library is probably a simpler approach.   I would 
predict that if MurmurHash3, generating a 128 bit hash value, is used 
over the Yang Library contents then the risk of a collision (i.e. where 
the content differs, but hashes to the same value) would be extremely 
low in practice.

Thanks,
Rob

On 12/10/2018 06:59, Rohit R Ranade wrote:
> .

---

From: Juergen Schoenwaelder <[email-masked]>
Date: Fri, 12 Oct 2018 13:37:18 +0200

I think the point is that we do not require this to be a counter nor
do we require this to be a hash of the yang library. Implementations
can do what they think is best as long as the content-id changes when
the content of the yang library changes, i.e., the content-id value
can be used to check whether a cached version of yang library can
still be used.

/js

On Fri, Oct 12, 2018 at 12:26:50PM +0100, Robert Wilton wrote:
> restarts, and the YANG library content is the same then it is less work on
> the client to return the same content-id value.
> 
> It isn't the end of the world if it is different because it just forces the
> client to re-download and re-parse YANG library. However, it could be a
> problem for the client if the server returns the same value if the server
> reboots and uses a different set of YANG modules after it has rebooted (e.g.
> after a software upgrade).
> 
> made to work in a reliable way, but using a robust hash function over the
> contents in YANG library is probably a simpler approach.   I would predict
> that if MurmurHash3, generating a 128 bit hash value, is used over the Yang
> Library contents then the risk of a collision (i.e. where the content
> differs, but hashes to the same value) would be extremely low in practice.
> 
> Thanks,
> Rob
> 
> 

-- 
Juergen Schoenwaelder           Jacobs University Bremen gGmbH
Phone: +49 421 200 3587         Campus Ring 1 | 28759 Bremen | Germany
Fax:   +49 421 200 3103         <https://www.jacobs-university.de/>

---

From: Rohit R Ranade <[email-masked]>
Date: Fri, 12 Oct 2018 11:40:23 +0000

Hi Robert,

When I read that the identifier is a "unique implementation-specific identifier", I inferred that this identifier should generate a unique value whenever the contents change.
So I inferred that there should not be a repetition of the identifier values. But the use-cases presented show that to make full use of this leaf, it is better if same content generated the same identifier.

Maybe if we removed the term "unique", then this doubt may not arise.

With Regards,
Rohit

-----Original Message-----
From: Robert Wilton [mailto:[email-masked]] 
Sent: 12 October 2018 16:57
To: Rohit R Ranade <[email-masked]>
Cc: Martin Bjorklund <[email-masked]>; [email-masked]
Subject: Re: [Netconf] the name "checksum" in YANG library

Hi Rohit,

If the server restarts, or the YANG management daemon on the server restarts, and the YANG library content is the same then it is less work on the client to return the same content-id value.

It isn't the end of the world if it is different because it just forces the client to re-download and re-parse YANG library. However, it could be a problem for the client if the server returns the same value if the server reboots and uses a different set of YANG modules after it has rebooted (e.g. after a software upgrade).

Perhaps if you write the counter to persistent storage this can still be made to work in a reliable way, but using a robust hash function over the contents in YANG library is probably a simpler approach.   I would predict that if MurmurHash3, generating a 128 bit hash value, is used over the Yang Library contents then the risk of a collision (i.e. where the content differs, but hashes to the same value) would be extremely low in practice.

Thanks,
Rob

On 12/10/2018 06:59, Rohit R Ranade wrote:
>> changes, "content-modify-count" can also be used which is simple for 
>> a server to implement (just increment when content changes) and also 
>> for client or a human reader to understand.
>> in YANG library is misleading.  It is not really a checksum ('There 
>> is no requirement that the same information always results in the 
>> same "checksum" value.')
>>

---

From: Robert Wilton <[email-masked]>
Date: Fri, 12 Oct 2018 13:24:40 +0100

Hi Rohit,

I'm OK with removing "unique" if the other authors and WG agree with the 
change.

Note that the full context for the current block of text would become 
this (incorporating Martin's proposed changes):

    o  The "/yang-library/content-id" leaf contains the YANG library
       content identifier, which is an implementation-specific
       identifier representing the current information in the YANG
       library on a specific server.  The value of this leaf MUST change
       whenever the information in the YANG library changes.  There is no
       requirement that the same information always results in the same
       "content-id" value.  This leaf allows a client to fetch all schema
       information once, cache it, and only refetch it if the value of
       this leaf has been changed.  If the value of this leaf changes,
       the server also generates a "yang-library-update" notification.

Thanks,
Rob

---

From: Kent Watsen <[email-masked]>
Date: Fri, 12 Oct 2018 17:52:43 +0000

We should not try to ensure that two servers having the same response return the same value.  That would require the definition of a canonical form that we don't have.

We should (IMO) align the checksum value with HTTP Entity-Tag (ETag) [1] and, in particular, using a strong validator [2].  RESTCONF says that ETag SHOULD be available for each resource [3], including {+restconf}/ds/ietf-datastores:operational/ietf-yang-library:yang-library.  I know that we don't have to conflate these two things, but it makes sense to do so.

PS: just realized that nmda-restconf didn't update [4]. This might be a problem.

[1] https://tools.ietf.org/html/rfc7232#section-2.3
[2] https://tools.ietf.org/html/rfc7232#section-2.1
[3] https://tools.ietf.org/html/rfc8040#section-3.5.2
[4] https://tools.ietf.org/html/rfc8040#section-3.4.1.2

Kent // contributor

-----Original Message-----
From: Netconf <[email-masked]> on behalf of Vladimir Vassilev <[email-masked]>
Date: Friday, October 12, 2018 at 6:56 AM
To: Rohit R Ranade <[email-masked]>, Martin Bjorklund <[email-masked]>
Cc: "[email-masked]" <[email-masked]>
Subject: Re: [Netconf] the name "checksum" in YANG library

Hi,

Vladimir

_______________________________________________
Netconf mailing list
[email-masked]
https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_netconf&d=DwICAg&c=HAkYuh63rsuhr6Scbfh0UjBXeMK-ndb3voDTXcWzoCI&r=9zkP0xnJUvZGJ9EPoOH7Yhqn2gsBYaGTvjISlaJdcZo&m=QwcIVKILbN6JGJBCGujvoCFYDuKfhlWPRNXIUv76Wt0&s=FtBu4_qYCzP67ExA8TL8cw1qhrLD6goeVAQMgbOvFTg&e=

---

From: Vladimir Vassilev <[email-masked]>
Date: Sat, 13 Oct 2018 21:42:45 +0200

Hi Kent,

On 10/12/18 7:52 PM, Kent Watsen wrote:
> We should not try to ensure that two servers having the same response return the same value.
I do not disagree with that.
>    That would require the definition of a canonical form that we don't have.

IMO this is doable. There are other usecases apart from the yang library 
one that need canonical form representation of YANG data trees. Does 
"Restrictions for canonical form XML representation of YANG data" sound 
like a useful draft? A 1 page text with restrictions - some for the YANG 
data types lexical representation (identityref and instance-identifier) 
and some for the XML encoding format intended to guarantee the XML 
generated will be canonical nevertheless compatible with RFC 7950.

Vladimir

---

From: Rohit R Ranade <[email-masked]>
Date: Mon, 15 Oct 2018 08:51:32 +0000

Hi Robert,

The text looks fine to me.

With Regards,
Rohit R

From: Robert Wilton [mailto:[email-masked]]
Sent: 12 October 2018 17:55
To: Rohit R Ranade <[email-masked]>; Martin Bjorklund <[email-masked]>; [email-masked]
Subject: Re: [Netconf] the name "checksum" in YANG library

Hi Rohit,

I'm OK with removing "unique" if the other authors and WG agree with the change.
Note that the full context for the current block of text would become this (incorporating Martin's proposed changes):

Thanks,
Rob

Hi Robert,

With Regards,

Rohit

-----Original Message-----

To: Rohit R Ranade <[email-masked]><mailto:[email-masked]>

Cc: Martin Bjorklund <[email-masked]><mailto:[email-masked]>; [email-masked]<mailto:[email-masked]>

Hi Rohit,

Thanks,

Rob

Hi Martin,

With Regards,

Rohit

-----Original Message-----

To: Rohit R Ranade <[email-masked]><mailto:[email-masked]>

Cc: [email-masked]<mailto:[email-masked]>

Rohit R Ranade <[email-masked]><mailto:[email-masked]> wrote:

/martin

-----Original Message-----

From: Netconf [mailto:[email-masked]] On Behalf Of Martin

Bjorklund

To: [email-masked]<mailto:[email-masked]>

Hi,

same "checksum" value.')

short.

The changes would be:

OLD:

       of the YANG library.

NEW:

OLD:

       specific server.

NEW:

use the new term.

/martin

Netconf mailing list

[email-masked]<mailto:[email-masked]>

Netconf mailing list

[email-masked]<mailto:[email-masked]>

.