YANG Data Model for the Precision Time Protocol (PTP)
draft-ietf-tictoc-1588v2-yang-11

[Ballot comment]

Original DISCUSS notes for the record: Discuss (2018-10-11 for -10)

The model was not reviewed by YANG doctors, at least there is no record of such review. It should be, especially given the subject area of the model is not a native IETF technology.

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

The IANA Functions Operator has completed its review of draft-ietf-tictoc-1588v2-yang-10. If any part of this review is inaccurate, please let us know.

The IANA Functions Operator understands that upon approval of this document, there are two actions to complete.

First, in the ns registry on the IETF XML Registry page located at

https://www.iana.org/assignments/xml-registry/

a single new namespace will be registered:

ID: yang:ietf-ptp
URI: urn:ietf:params:xml:ns:yang:ietf-ptp
Filename: [ TBD-at-Registration ]
Reference: [ RFC-to-be ]

This proposed registration has already been reviewed and approved by the designated expert.

Second, in the YANG Module Names registry at

https://www.iana.org/assignments/yang-parameters/

a single new YANG module will be registered:

Name: ietf-ptp
File: [ TBD-at-Registration ]
Maintained by IANA? No
Namespace: urn:ietf:params:xml:ns:yang:ietf-ptp
Prefix: ptp
Module:
Reference: [ RFC-to-be ]

While the YANG module name will be registered after the IESG approves the document, the YANG module file will be posted after the RFC Editor notifies us that the document has been published.

The IANA Functions Operator understands that these are the only actions required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.

Thank you,

Amanda Baber
Lead IANA Services Specialist

The following Last Call announcement was sent out (ends 2018-11-14):

From: The IESG
To: IETF-Announce
CC: odonoghue@isoc.org, Karen O'Donoghue , tictoc-chairs@ietf.org, tictoc@ietf.org, draft-ietf-tictoc-1588v2-yang@ietf.org, suresh@kaloom.com
Reply-To: ietf@ietf.org
Sender:
Subject: SECOND Last Call:  (YANG Data Model for IEEE 1588-2008) to Proposed Standard


The IESG has received a request from the Timing over IP Connection and
Transfer of Clock WG (tictoc) to consider the following document: - 'YANG
Data Model for IEEE 1588-2008'
  as Proposed Standard

This document is going through a SECOND IETF Last Call because one of
the Normative References for this document "[IEEE1588]" is not publicly
available and the IESG felt that this might have caused some people to
not review this document. If you would like to review this document and
would like a copy of the [IEEE1588] reference specification, please send a
note to the Responsible AD  and the tictoc working
group chairs  and we will provide you a copy of
the document.

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2018-11-14. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the beginning of
the Subject line to allow automated sorting.

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. The YANG module in this document conforms to the
  Network Management Datastore Architecture (NMDA).




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-tictoc-1588v2-yang/

IESG discussion can be tracked via
https://datatracker.ietf.org/doc/draft-ietf-tictoc-1588v2-yang/ballot/


No IPR declarations have been submitted directly on this I-D.

[Ballot comment]
I've cleared my discuss, since the discussion I wanted to make sure happened has happened. I'm copying it below for reference purposes:


§2 contains the following paragraph:

"  The readers are assumed to be familiar with IEEE 1588-2008. As all
  PTP terminologies and PTP data set attributes are described in
  details in IEEE 1588-2008 [IEEE1588], this document only outlines
  each of them in the YANG module."

If I understand correctly, IEEE 1588-2008 is not available without payment. If so, then I don't see how we can assume that reviewers of this draft are actually familiar with IEEE 1588-2008. It seems like that makes it hard for the draft to get sufficient review to be considered a standards-track IETF consensus document. I recognize that we do not have a policy against normative references to paywalled sources, but I read the disclaimer to make the IEEE document more foundational than just any normative reference.




§1, 2nd bullet: "The YANG module of this document MAY be revised..."
That seems more a statement of fact than permission.

§2.2, definition of "static": If it "typically" doesn't change, does that mean it sometimes does change?
-- 5th paragraph: "In such a case, an implementation MAY choose to return a warning upon writing to a read-only member"
MAY seems week here; does it ever make sense to silently write to a read-only member?

Appendix A: The appendix seems more like a liaison statement than something that belongs in an RFC defining a data model. Won't this become outdated whenever the change of control is (or is not) made? If it does need to go in an RFC, have people considered publishing it separately from the model?

[Ballot discuss]
The model was not reviewed by YANG doctors, at least there is no record of such review. It should be, especially given the subject area of the model is not a native IETF technology.

[Ballot discuss]
I appreciate that there has been some previous work in this area, but it
seems that there are still many instances of bare integral types with no
indication of what units are used to report a numerical value, whether
larger or smaller priority values indicate a more preferred status, how the
sign of an "offset" measurement should be interpreted, etc.  This leaves
the specification unimplementable in an interoperable way.  A (possibly
incomplete) list of such values includes:

clock-class (is this really more like an enum than an int?)
clock-accuracy (ditto?)
offset-scaled-log-variance
priority1 (are small or large values more-preferred?)
priority2 (ditto)
offset-from-master (interpretation of sign bit)
observed-parent-offset-scaled-log-variance
observed-parent-clock-phase-change-rate
grandmaster-priority1
grandmaster-priority2
current-utc-offset (sign bit)
time-source (is this more like an enum?)
log-min-delay-req-interval (units have to be scaled out before log operation)
log-announce-intervale (ditto)
log-sync-interval (ditto)
log-min-pdelay-req-interval (ditto, two different nodes)

[Ballot comment]
Section 1

  o  When the IEEE 1588 standard is revised (e.g. the IEEE 1588
  revision in progress at the time of writing this document), it will
  add some new optional features to its data sets.  The YANG module
  of this document MAY be revised and extended to support these new
  features. Moreover, the YANG "revision" SHOULD be used to indicate
  changes to the YANG module under such a circumstance.

It's not clear that a 2119 SHOULD is best here; I would have expected
either an 8174 "should" or a 2119 "MUST".

Section 3

time-interval-type says "units of nanoseconds and multiplied by 2^16".
I assume I'm interperting that wrong, since there doesn't seem to be much
point in claiming a precision in yoctoseconds.

Most "log" values specify the "base-two logarithm", but
offsetScaledLogVariance has a much more vague description.  Lacking access
to IEEE 1588-2008, I can't tell if it is possible to be more precise for
describing this field.  (Also, you can only take the log of a dimensionless
quantity, so the input units need to be specified, per my Discuss.)

> slave-only clock

So we had this long discussion on ietf@ietf.org about potentially offensive
terminology, including "master"/"slave".

We have leap59/leap61; might we need a leap62?

Section 4

(I guess you don't need to talk about sensitive ro nodes when all the nodes
are under the sensitive rw nodes already mentioned.)

[Ballot comment]
Thanks for the work on this document to everyone involved. I have a few minor
comments and one question.

---------------------------------------------------------------------------

>  A simplified YANG tree diagram [RFC8340] representing the data
>  model is typically used by YANG modules. This document uses the
>  same tree diagram syntax as described in [RFC8340].

As RFC 8340 is necessary reading to understand this section, I believe it should
be a normative reference rather than an informative reference.

---------------------------------------------------------------------------

§2.1:

>  Based on statements in IEEE 1588-2008 subclauses 8.3.1 and 10.1,
>  most transparent clock products have interpreted the transparent
>  clock data sets to reside as a singleton at the root level of the
>  managed product, and this YANG model reflects that location.

I'll note that "most" is not "all." Is there any guidance that can be provided
to implementors of this module for products that fall outside this common case?

---------------------------------------------------------------------------

Page 14:

>          leaf priority1 {
>            type uint8;
>            description
>              "The priority1 attribute of the local clock.";
>          }

This description seems to be of very limited utility. Consider adding a
description that will be more informative to operators. This is true for
clock-quality and priority2 as well.

---------------------------------------------------------------------------

Appendix A:

I'm a little surprised that this appendix doesn't treat the matter of whether
the Last IETF 1588 YANG module will be left as a standards track document,
obsoleted by an IETF document that points to the First IEEE 1588 YANG module,
or simply moved to historic. While we can certainly figure this mechanism out
when the time comes for a transfer, it would probably make such a transfer
more smooth if the documented plan included a proposed process for the formal
sunsetting of the IETF document.

[Ballot comment]
Thanks for the work on this document to everyone involved. I have a few minor
comments and one question.

---------------------------------------------------------------------------

>  A simplified YANG tree diagram [RFC8340] representing the data
>  model is typically used by YANG modules. This document uses the
>  same tree diagram syntax as described in [RFC8340].

As RFC 8340 is necessary reading to understand this section, I believe it should
be a normative reference rather than an informative reference.

---------------------------------------------------------------------------

§2.1:

>  Based on statements in IEEE 1588-2008 subclauses 8.3.1 and 10.1,
>  most transparent clock products have interpreted the transparent
>  clock data sets to reside as a singleton at the root level of the
>  managed product, and this YANG model reflects that location.

I'll note that "most" is not "all." Is there any guidance that can be provided
to implementors of this module for products that fall outside this common case?

---------------------------------------------------------------------------

Page 14:

>          leaf priority1 {
>            type uint8;
>            description
>              "The priority1 attribute of the local clock.";
>          }

This description seems to be of very limited utility. Consider adding a
description that will be more informative to operators. This is true for
clock-quality and priority2 as well.

---------------------------------------------------------------------------

Appendix A:

I'm a little surprised that this appendix doesn't treat the matter of whether
the Last IETF 1588 YANG module will be left as a standards track document,
obsoleted by an IETF document that points to the First IEEE 1588 YANG module, or
simply moved to historic. While we can certainly figure this mechanism out when
the time comes for a transfer, it would probably make such a transfer more
smooth if this document included, as part of its plan, a proposed process for
the formal sunsetting of the IETF document.

[Ballot comment]
Thanks for the work on this document to everyone involved. I have a few minor
comments and one question.

---------------------------------------------------------------------------

>  A simplified YANG tree diagram [RFC8340] representing the data
>  model is typically used by YANG modules. This document uses the
>  same tree diagram syntax as described in [RFC8340].

As RFC 8340 is necessary reading to understand this section, I believe it should
be a normative reference rather than an informative reference.

---------------------------------------------------------------------------

§2.1:

>  Based on statements in IEEE 1588-2008 subclauses 8.3.1 and 10.1,
>  most transparent clock products have interpreted the transparent
>  clock data sets to reside as a singleton at the root level of the
>  managed product, and this YANG model reflects that location.

I'll note that "most" is not "all." Is there any guidance that can be provided
to implementors of this module for products that fall outside this common case?

---------------------------------------------------------------------------

Page 14:

>          leaf priority1 {
>            type uint8;
>            description
>              "The priority1 attribute of the local clock.";
>          }

This description seems to be of very limited utility. Consider adding a
description that will be more informative to operators. This is true for
clock-quality and priority2 as well.

---------------------------------------------------------------------------

Appendix A:

I'm a little surprised that this appendix doesn't treat the matter of whether
the Last IETF 1588 YANG module will be left as a standards track document,
obsoleted by an IETF document that points to the First IEEE 1588 YANG module, or
simply moved to historic. While we can probably figure this mechanism out when
the time comes for a transfer, it would probably make such a transfer more
smooth if this document included, as part of its plan, a proposed process for
the formal sunsetting of the IETF document.

[Ballot comment]
Rich version of this review at:
https://mozphab-ietf.devsvcdev.mozaws.net/D3264


I concur with Ben Campbell's DISCUSS.

COMMENTS
S 1.
>      2008.
> 
>      o  When the IEEE 1588 standard is revised (e.g. the IEEE 1588
>      revision in progress at the time of writing this document), it will
>      add some new optional features to its data sets.  The YANG module
>      of this document MAY be revised and extended to support these new

Nit: this looks like it's more a statement of fact than normative
langauge.



S 1.
>      dedicated YANG module for its profile. The profile's YANG module
>      SHOULD use YANG "import" to import the IEEE 1588-2008 YANG module
>      as its foundation.  Then the profile's YANG module SHOULD use YANG
>      "augment" to add any profile-specific enhancements.
> 
>      o  A product that conforms to a profile standard can also create

Is the "can" in this statement different from the "may" in the
previous bullet.


S 7.
>      create derivative works from this document. Those IEEE forms and
>      mechanisms will be updated as needed for any future IETF YANG
>      modules for IEEE 1588 (The signed forms are held by the IEEE
>      Standards Association department of Risk Management and Licensing.).
>      This will help to make the future transfer of work from IETF to
>      IEEE occur as smoothly as possible.

I don't mean to be overly legal, but why is it that you think that the
named authors consent is what's relevant here as opposed to the IETF,
or everyone who has submitted text?

[Ballot discuss]
This is a process discuss, or maybe a discuss discuss. I expect to clear it once a discussion has occurred regardless of the outcome, but I want to make sure the discussion happens.

§2 contains the following paragraph:

"  The readers are assumed to be familiar with IEEE 1588-2008. As all
  PTP terminologies and PTP data set attributes are described in
  details in IEEE 1588-2008 [IEEE1588], this document only outlines
  each of them in the YANG module."

If I understand correctly, IEEE 1588-2008 is not available without payment. If so, then I don't see how we can assume that reviewers of this draft are actually familiar with IEEE 1588-2008. It seems like that makes it hard for the draft to get sufficient review to be considered a standards-track IETF consensus document. I recognize that we do not have a policy against normative references to paywalled sources, but I read the disclaimer to make the IEEE document more foundational than just any normative reference.

[Ballot comment]
§1, 2nd bullet: "The YANG module of this document MAY be revised..."
That seems more a statement of fact than permission.

§2.2, definition of "static": If it "typically" doesn't change, does that mean it sometimes does change?
-- 5th paragraph: "In such a case, an implementation MAY choose to return a warning upon writing to a read-only member"
MAY seems week here; does it ever make sense to silently write to a read-only member?

Appendix A: The appendix seems more like a liaison statement than something that belongs in an RFC defining a data model. Won't this become outdated whenever the change of control is (or is not) made? If it does need to go in an RFC, have people considered publishing it separately from the model?

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

The IANA Functions Operator has completed its review of draft-ietf-tictoc-1588v2-yang-09. If any part of this review is inaccurate, please let us know.

The IANA Functions Operator has a question about one of the actions requested in the IANA Considerations section of this document.

The IANA Functions Operator understands that, upon approval of this document, there are two actions which we must complete.

First, in the ns registry on the IETF XML Registry page located at:

https://www.iana.org/assignments/xml-registry/

a single, new namespace will be registered as follows:

ID: yang:ietf-ptp
URI: urn:ietf:params:xml:ns:yang:ietf-ptp
Filename: [ TBD-at-Registration ]
Reference: [ RFC-to-be ]

As this document requests registrations in an Specification Required (see RFC 8126) registry, we will initiate the required Expert Review via a separate request. Expert review will need to be completed before your document can be approved for publication as an RFC.

Second, in the YANG Module Names registry on the YANG Parameters registry page located at:

https://www.iana.org/assignments/yang-parameters/

a single, new YANG module will be registered as follows:

Name: ietf-ptp
File: [ TBD-at-Registration ]
Maintained by IANA?
Namespace: urn:ietf:params:xml:ns:yang:ietf-ptp
Prefix: ptp
Module:
Reference: [ RFC-to-be ]

IANA Question --> What should be the entry for the registry value "Maintained by IANA?" for this new YANG module?

While the YANG module name will be registered after the IESG approves the document, the YANG module file will be posted after the RFC Editor notifies us that the document has been published.

The IANA Functions Operator understands that these are the only actions required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.

Thank you,

Sabrina Tanamal
Senior IANA Services Specialist

The following Last Call announcement was sent out (ends 2018-09-07):

From: The IESG
To: IETF-Announce
CC: odonoghue@isoc.org, Karen O'Donoghue , tictoc-chairs@ietf.org, tictoc@ietf.org, draft-ietf-tictoc-1588v2-yang@ietf.org, suresh@kaloom.com
Reply-To: ietf@ietf.org
Sender:
Subject: Last Call:  (YANG Data Model for IEEE 1588-2008) to Proposed Standard


The IESG has received a request from the Timing over IP Connection and
Transfer of Clock WG (tictoc) to consider the following document: - 'YANG
Data Model for IEEE 1588-2008'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2018-09-07. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the beginning of
the Subject line to allow automated sorting.

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. The YANG module in this document conforms to the
  Network Management Datastore Architecture (NMDA).




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-tictoc-1588v2-yang/

IESG discussion can be tracked via
https://datatracker.ietf.org/doc/draft-ietf-tictoc-1588v2-yang/ballot/


No IPR declarations have been submitted directly on this I-D.

This is the publication request and document shepherd write up for:

YANG Data Model for IEEE 1588-2008
draft-ietf-tictoc-1588v2-yang

Prepared by: Karen O’Donoghue, 29 May 2018

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Is this type of RFC indicated in the title page header?

Proposed Standard

(2) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

Technical Summary:

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.

Working Group Summary:

The document has clear working group consensus for publication, and has been reviewed by several WG participants since its initial adoption as a working group item. In addition, this document has been coordinated with the IEEE 1588 working group.

Document Quality:
 
This document has been reviewed and revised several times during its development. There were no specific external expert reviews conducted.
 
Personnel: 

Karen O'Donoghue is acting as the Document Shepherd.  Suresh Krishnan is the Responsible Area Director.

(3) Briefly describe the review of this document that was performed by the Document Shepherd. If this version of the document is not ready for publication, please explain why the document is being forwarded to the IESG.
 
The document shepherd has followed the working group process and reviewed the final document and feels this document is ready for IESG review.

(4) Does the document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?
 
The document shepherd does not have any concerns about the reviews that were performed.

(5) Do portions of the document need review from a particular or from broader perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or internationalization? If so, describe the review that took place.

This document does not require any special reviews beyond those planned during the IESG review process.
 
(6) Describe any specific concerns or issues that the Document Shepherd has with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here.
 
The Document Shepherd is comfortable with this document. It has been coordinated with IEEE 1588 and includes an editor that is deeply embedded in that community. 

(7) Has each author confirmed that any and all appropriate IPR disclosures required for full conformance with the provisions of BCP 78 and BCP 79 have already been filed. If not, explain why?

The authors have confirmed that they have dealt with all appropriate IPR disclosures.
 
(8) Has an IPR disclosure been filed that references this document? If so, summarize any WG discussion and conclusion regarding the IPR disclosures.

There is no IPR disclosures for this document.
 
(9) How solid is the WG consensus behind this document? Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

The document represents strong WG consensus.
 
(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarize the areas of conflict in separate email messages to the Responsible Area Director.

There have been no threats of anyone appealing the documents.
 
(11) Identify any ID nits the Document Shepherd has found in this document. (See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate checks are not enough; this check needs to be thorough.

There is currently one ID nit that will be fixed during the IESG review and publication process.

  ** Obsolete normative reference: RFC 7223 (Obsoleted by RFC 8343)

(12) Describe how the document meets any required formal review criteria, such as the MIB Doctor, media type, and URI type reviews.

This document has been informally reviewed by the IETF management experts. There will need to be a review as part of the publication process.
 
(13) Have all references within this document been identified as either normative or informative?

All references are tagged as normative or informative.
 
(14) Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the plan for their completion?

All normative references are completed.
 
(15) Are there downward normative references (see RFC 3967)? If so, list these downward references to support the Area Director in the Last Call procedure.

There are no downrefs.

(16) Will publication of this document change the status of any existing RFCs? Are those RFCs listed on the title page header, listed in the abstract, and discussed in the introduction? If the RFCs are not listed in the Abstract and Introduction, explain why, and point to the part of the document where the relationship of this document to the other RFCs is discussed. If this information is not in the document, explain why the WG considers it unnecessary.

This document does not change the status of any existing RFCs.
 
(17) Describe the Document Shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all protocol extensions that the document makes are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that newly created IANA registries include a detailed specification of the initial contents for the registry, that allocations procedures for future registrations are defined, and a reasonable name for the new registry has been suggested (see RFC 5226).

There are no new IANA considerations contained in this document.

(18) List any new IANA registries that require Expert Review for future allocations. Provide any public guidance that the IESG would find useful in selecting the IANA Experts for these new registries.

There are no new IANA considerations contained in this document.
 
(19) Describe reviews and automated checks performed by the Document Shepherd to validate sections of the document written in a formal language, such as XML code, BNF rules, MIB definitions, etc.

This document contains a Yang data model and has been checked for compliance.