Subject: Re: [netmod] WG Last Call resolutions incorporated in draft-ietf-tictoc-1588v2-yang-06

From: Jiangyuanlong <[email-masked]>
Date: Tue, 7 Nov 2017 07:53:26 +0000

Hi Alex,

Sorry for a late reply as I spent the last week for an urgent business trip.
Please see my comments in line with [YJ]

Thanks,
Yuanlong

-----Original Message-----
From: Alex Campbell [mailto:[email-masked]] 
Sent: Monday, October 30, 2017 10:15 AM
To: Jiangyuanlong; [email-masked]
Cc: Xian Liu; Xujinchun; [email-masked]
Subject: Re: WG Last Call resolutions incorporated in draft-ietf-tictoc-1588v2-yang-06

Hi,
I've reviewed this latest draft and have some more comments.

1. I find the introduction to be unnecessarily wordy; it feels like it was written with a view of not missing any information out, rather than trying to keep it concise.
   For example, there is no need to elaborate on YANG data types here. It is also not here to sell YANG.

[YJ] Yes, we are trying to give some introductory information for an outsider who may not be familiar with PTP or YANG, and explain why a YANG for PTP is needed. The juicy part of this document is its YANG module, and people can skip all the other texts if they are familiar with PTP and YANG.
Besides, these texts have been contributed by multiple sources and undergone several rounds of reviews, thus I will wait for a clear message from the TICTOC chairs to introduce any big changes at this last call stage.

OLD:

   As a synchronization protocol, IEEE 1588-2008 [IEEE1588] is widely
   supported in the carrier networks, industrial networks, automotive
   networks, and many other applications. It can provide high
   precision time synchronization as fine as nano-seconds. The
   protocol depends on a Precision Time Protocol (PTP) engine to
   decide its own state automatically, and a PTP transportation layer
   to carry the PTP timing and various quality messages. The
   configuration parameters and state data sets of IEEE 1588-2008 are
   numerous.

   According to the concepts described in [RFC3444], IEEE 1588-2008
   itself provides an information model in its normative
   specifications for the data sets (in IEEE 1588-2008 clause 8). Some
   standardization organizations including the IETF have specified
   data models in MIBs (Management Information Bases) for IEEE 1588-
   2008 data sets (e.g. [RFC8173], [IEEE8021AS]). These MIBs are
   typically focused on retrieval of state data using the Simple
   Network Management Protocol (SNMP), furthermore, configuration of
   PTP data sets is not considered in [RFC8173].

   Some service providers and applications require that the management
   of the IEEE 1588-2008 synchronization network be flexible and more
   Internet-based (typically overlaid on their transport networks).
   Software Defined Network (SDN) is another driving factor, which
   demands an improved configuration capability of synchronization
   networks.

   YANG [RFC6020] is a data modeling language used to model
   configuration and state data manipulated by network management
   protocols like the Network Configuration Protocol (NETCONF)
   [RFC6241]. A small set of built-in data types are defined in
   [RFC6020], and a collection of common data types are further
   defined in [RFC6991]. Advantages of YANG include Internet based
   configuration capability, validation, rollback and so on. All of
   these characteristics make it attractive to become another
   candidate modeling language for IEEE 1588-2008.

NEW:

   IEEE 1588-2008 is a time protocol that provides high precision time
   synchronization as fine as nano-seconds.

   IEEE 1588-2008 itself provides an information model in its normative
   specifications for the data sets (IEEE 1588-2008 clause 8).
   Standard information models (e.g. [RFC8173], [IEEE8021AS]) have been
   previously defined as MIBs focused on the retrieval of state data using
   SNMP [RFC1157].

   YANG [RFC6020] is a data modeling language used to model configuration
   and state data manipulated by network management protocols like NETCONF
   [RFC6241].

2. Can we refer to the system as simply PTP rather than IEEE 1588(-2008)?
[YJ] Advice from IEEE 1588 is, we need to use "1588-2008" as much as possible to help clarify that the scope of this YANG is limited to the published 1588 standard.

3. There is insufficient spacing here to separate the terms from their definitions:
OLD

   PTP dataset  Structured attributes of clocks (an OC, BC or TC) used
   for PTP protocol decisions and for providing values for PTP message
   fields, see Section 8 of [IEEE1588].

   PTP instance A PTP implementation in the device (i.e., an OC or BC)
   represented by a specific PTP dataset.

NEW

   PTP dataset
     Structured attributes of clocks (an OC, BC or TC) used
     for PTP protocol decisions and for providing values for PTP message
     fields, see Section 8 of [IEEE1588].

   PTP instance
     A PTP implementation in the device (i.e., an OC or BC)
     represented by a specific PTP dataset.
[YJ] OK.

4. There's a singular/plural mismatch here:

   module. Query and configuration of device wide or port specific
   configuration information and clock data set is described for this
   version.
[YJ] Good, we will change 'is' to 'are'.

and here:

   Query and configuration of clock information include:

5. The choice of uint16 as instance-number limits implementations to 65536 distinct instances.
   While I have a hard time imagining a system with more than 65536 PTP instances, I would prefer to avoid imposing arbitrary limits.
   I would recommend changing instance-number to a string (and renaming it to instance-name or just name).
[YJ] The 1588-2008 supports multiple instances of PTP, but it is ambiguous in its organization of those PTP instances, especially with regard to management.
 In the 1588 new revision, there is an explicit list of PTP instances, and that list is indexed using a number (not name). Thus to align with the new revision, we need to keep it instance-number.
 If 65536 limit is a concern, how about change it to uint32, any concerns?

6. I still recommend removing -ds from the YANG element names that still include it. It doesn't appear to add any value.
[YJ] Rodney's opinion: the value of using 'ds' is that the 1588 document on which this YANG model is based uses "DefaultDS" as a term. PTP experts even say "default dee ess" verbally when referring to this data. If we changed this to just "default", PTP experts might assume that we are referring to something entirely new to YANG. Thus, to align with 1588-2008, the same set of terminologies are used.

7. What;s the relevance of injection attacks relevant to this YANG module?
[YJ] This is a general statement which is applicable to this YANG module and other YANG modules as well.
Thanks again,
Yuanlong

Alex

________________________________________
From: netmod <[email-masked]> on behalf of Jiangyuanlong <[email-masked]>
Sent: Friday, 27 October 2017 3:21 p.m.
To: [email-masked]
Cc: Xian Liu; Xujinchun; [email-masked]
Subject: [netmod] WG Last Call resolutions incorporated in draft-ietf-tictoc-1588v2-yang-06

Dear all,

Based on all the comments we received during the WG Last Call process, we've updated the document to version 6.
We believe all the LC comments are resolved and the consensus is reflected in this new revision.
Many thanks to Martin, Tal, Opher, Alex, John and many others who had reviewed and commented on this draft.

Cheers,
Yuanlong on behalf of all coauthors

-----Original Message-----
From: [email-masked] [mailto:[email-masked]]
Sent: Friday, October 27, 2017 9:48 AM
To: Xian Liu; Rodney Cummings; [email-masked]; Jiangyuanlong; Xujinchun
Subject: New Version Notification for draft-ietf-tictoc-1588v2-yang-06.txt

A new version of I-D, draft-ietf-tictoc-1588v2-yang-06.txt
has been successfully submitted by Yuanlong Jiang and posted to the IETF repository.

Name:           draft-ietf-tictoc-1588v2-yang
Revision:       06
Title:          YANG Data Model for IEEE 1588-2008
Document date:  2017-10-26
Group:          tictoc
Pages:          30
URL:            https://www.ietf.org/internet-drafts/draft-ietf-tictoc-1588v2-yang-06.txt
Status:         https://datatracker.ietf.org/doc/draft-ietf-tictoc-1588v2-yang/
Htmlized:       https://tools.ietf.org/html/draft-ietf-tictoc-1588v2-yang-06
Htmlized:       https://datatracker.ietf.org/doc/html/draft-ietf-tictoc-1588v2-yang-06
Diff:           https://www.ietf.org/rfcdiff?url2=draft-ietf-tictoc-1588v2-yang-06

Abstract:
   This document defines a YANG data model for the configuration of
   IEEE 1588-2008 devices and clocks, and also retrieval of the
   configuration information, data set and running states of IEEE
   1588-2008 clocks.

Please note that it may take a couple of minutes from the time of submission until the htmlized version and diff are available at tools.ietf.org.

The IETF Secretariat

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

---

From: "t.petch" <[email-masked]>
Date: Wed, 8 Nov 2017 13:11:31 -0000

Yuanglong

I think that your Introduction is fine, and would not shorten it at all.
(I think that the Introduction to most I-Ds that describe YANG modules
is woefully weak).

I think too that you are spot on with your terminology; where IEEE
1588-2008 has an accepted way of working, then that is the right way for
this I-D.

One fresh comment arising from that.  You commented earlier that you had
departed from IEEE 1588-2008 in changing camel case to the YANG style
names, with hyphens, and I think that that is a logical choice.  But I
would go further and explain that choice so that those coming from IEEE
1588-2008 understand what has happened and why.  Not sure where to put
that; probably Section 2, perhaps immediately before the tree diagram,
since that is when readers will be exposed to the issue.

If you have done more than just change the style of name, then it would
be worth having a concordance of IEEE 1588-2008 names and YANG names;
this was common practice with MIB Modules.

Tom Petch

----- Original Message -----
From: "Jiangyuanlong" <[email-masked]>
To: "Alex Campbell" <[email-masked]>; <[email-masked]>
Cc: "Xian Liu" <[email-masked]>; "Xujinchun"
<[email-masked]>; <[email-masked]>
Sent: Tuesday, November 07, 2017 7:53 AM
Subject: Re: [netmod] WG Last Call resolutions incorporated in
draft-ietf-tictoc-1588v2-yang-06

> 1. I find the introduction to be unnecessarily wordy; it feels like it
was written with a view of not missing any information out, rather than
trying to keep it concise.
> [YJ] Yes, we are trying to give some introductory information for an
outsider who may not be familiar with PTP or YANG, and explain why a
YANG for PTP is needed. The juicy part of this document is its YANG
module, and people can skip all the other texts if they are familiar
with PTP and YANG.
> Besides, these texts have been contributed by multiple sources and
undergone several rounds of reviews, thus I will wait for a clear
message from the TICTOC chairs to introduce any big changes at this last
call stage.
>    YANG [RFC6020] is a data modeling language used to model
configuration
> [YJ] Advice from IEEE 1588 is, we need to use "1588-2008" as much as
possible to help clarify that the scope of this YANG is limited to the
published 1588 standard.
>    While I have a hard time imagining a system with more than 65536
PTP instances, I would prefer to avoid imposing arbitrary limits.
>    I would recommend changing instance-number to a string (and
renaming it to instance-name or just name).
> [YJ] The 1588-2008 supports multiple instances of PTP, but it is
ambiguous in its organization of those PTP instances, especially with
regard to management.
>  In the 1588 new revision, there is an explicit list of PTP instances,
and that list is indexed using a number (not name). Thus to align with
the new revision, we need to keep it instance-number.
> 6. I still recommend removing -ds from the YANG element names that
still include it. It doesn't appear to add any value.
> [YJ] Rodney's opinion: the value of using 'ds' is that the 1588
document on which this YANG model is based uses "DefaultDS" as a term.
PTP experts even say "default dee ess" verbally when referring to this
data. If we changed this to just "default", PTP experts might assume
that we are referring to something entirely new to YANG. Thus, to align
with 1588-2008, the same set of terminologies are used.
> URL:
https://www.ietf.org/internet-drafts/draft-ietf-tictoc-1588v2-yang-06.tx
t
> Status:
https://datatracker.ietf.org/doc/draft-ietf-tictoc-1588v2-yang/
> Htmlized:
https://tools.ietf.org/html/draft-ietf-tictoc-1588v2-yang-06
> Htmlized:
https://datatracker.ietf.org/doc/html/draft-ietf-tictoc-1588v2-yang-06
> Diff:
https://www.ietf.org/rfcdiff?url2=draft-ietf-tictoc-1588v2-yang-06
> Please note that it may take a couple of minutes from the time of
submission until the htmlized version and diff are available at
tools.ietf.org.

---

From: Jiangyuanlong <[email-masked]>
Date: Thu, 9 Nov 2017 01:58:06 +0000

Tom,

Good to know all your viewpoints. We will add a sentence in Section 2 explaining the logic of YANG style names in this document, maybe put it as a note in the 2nd paragraph (as these names are used in the 3rd paragraph) . 

Thanks,
Yuanlong

-----Original Message-----
From: t.petch [mailto:[email-masked]] 
Sent: Wednesday, November 08, 2017 9:12 PM
To: Jiangyuanlong; Alex Campbell; [email-masked]
Cc: Xian Liu; Xujinchun; [email-masked]
Subject: Re: [netmod] WG Last Call resolutions incorporated in draft-ietf-tictoc-1588v2-yang-06

Yuanglong

I think that your Introduction is fine, and would not shorten it at all.
(I think that the Introduction to most I-Ds that describe YANG modules is woefully weak).

I think too that you are spot on with your terminology; where IEEE
1588-2008 has an accepted way of working, then that is the right way for this I-D.

One fresh comment arising from that.  You commented earlier that you had departed from IEEE 1588-2008 in changing camel case to the YANG style names, with hyphens, and I think that that is a logical choice.  But I would go further and explain that choice so that those coming from IEEE
1588-2008 understand what has happened and why.  Not sure where to put that; probably Section 2, perhaps immediately before the tree diagram, since that is when readers will be exposed to the issue.

If you have done more than just change the style of name, then it would be worth having a concordance of IEEE 1588-2008 names and YANG names; this was common practice with MIB Modules.

Tom Petch

----- Original Message -----
From: "Jiangyuanlong" <[email-masked]>
To: "Alex Campbell" <[email-masked]>; <[email-masked]>
Cc: "Xian Liu" <[email-masked]>; "Xujinchun"

> 1. I find the introduction to be unnecessarily wordy; it feels like it
was written with a view of not missing any information out, rather than trying to keep it concise.
> [YJ] Yes, we are trying to give some introductory information for an
outsider who may not be familiar with PTP or YANG, and explain why a YANG for PTP is needed. The juicy part of this document is its YANG module, and people can skip all the other texts if they are familiar with PTP and YANG.
> Besides, these texts have been contributed by multiple sources and
undergone several rounds of reviews, thus I will wait for a clear message from the TICTOC chairs to introduce any big changes at this last call stage.
configuration
> [YJ] Advice from IEEE 1588 is, we need to use "1588-2008" as much as
possible to help clarify that the scope of this YANG is limited to the published 1588 standard.
> [YJ] The 1588-2008 supports multiple instances of PTP, but it is
ambiguous in its organization of those PTP instances, especially with regard to management.
>  In the 1588 new revision, there is an explicit list of PTP instances,
and that list is indexed using a number (not name). Thus to align with the new revision, we need to keep it instance-number.
document on which this YANG model is based uses "DefaultDS" as a term.
PTP experts even say "default dee ess" verbally when referring to this data. If we changed this to just "default", PTP experts might assume that we are referring to something entirely new to YANG. Thus, to align with 1588-2008, the same set of terminologies are used.
> Please note that it may take a couple of minutes from the time of
submission until the htmlized version and diff are available at tools.ietf.org.