idnits 2.17.1 draft-ietf-tictoc-1588v2-yang-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (October 26, 2017) is 2373 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC7223' is defined on line 1028, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7223 (Obsoleted by RFC 8343) -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE1588' -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Working Group Y. Jiang, Ed. 2 Huawei 3 Internet-Draft X. Liu 4 Independent 5 Intended status: Standards Track J. Xu 6 Huawei 7 R. Cummings, Ed. 8 National Instruments 9 Expires: April 2018 October 26, 2017 11 YANG Data Model for IEEE 1588-2008 12 draft-ietf-tictoc-1588v2-yang-06 14 Abstract 16 This document defines a YANG data model for the configuration of 17 IEEE 1588-2008 devices and clocks, and also retrieval of the 18 configuration information, data set and running states of IEEE 19 1588-2008 clocks. 21 Status of this Memo 23 This Internet-Draft is submitted to IETF in full conformance with 24 the provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF), its areas, and its working groups. Note that 28 other groups may also distribute working documents as Internet- 29 Drafts. 31 Internet-Drafts are draft documents valid for a maximum of six 32 months and may be updated, replaced, or obsoleted by other 33 documents at any time. It is inappropriate to use Internet-Drafts 34 as reference material or to cite them other than as "work in 35 progress." 37 The list of current Internet-Drafts can be accessed at 38 http://www.ietf.org/ietf/1id-abstracts.txt 40 The list of Internet-Draft Shadow Directories can be accessed at 41 http://www.ietf.org/shadow.html 43 This Internet-Draft will expire on April 26, 2018. 45 Copyright Notice 47 Copyright (c) 2017 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with 55 respect to this document. Code Components extracted from this 56 document must include Simplified BSD License text as described in 57 Section 4.e of the Trust Legal Provisions and are provided without 58 warranty as described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction .............................................. 2 63 1.1. Conventions used in this document ...................... 4 64 1.2. Terminology ............................................ 4 65 2. IEEE 1588-2008 YANG Model hierarchy ....................... 5 66 2.1. Interpretations from IEEE 1588 Working Group ........... 8 67 2.2. Configuration and state ................................ 8 68 3. IEEE 1588-2008 YANG Module ................................ 9 69 4. Security Considerations .................................. 22 70 5. IANA Considerations ...................................... 23 71 6. References ............................................... 23 72 6.1. Normative References .................................. 23 73 6.2. Informative References ................................ 23 74 7. Acknowledgments .......................................... 24 75 Appendix A Transferring YANG Work to IEEE 1588 WG (Informational) 76 ................................................................. 25 77 A.1. Assumptions for the Transfer .......................... 25 78 A.2. Intellectual Property Considerations .................. 26 79 A.3. Namespace and Module Name ............................. 27 80 A.4. IEEE 1588 YANG Modules in ASCII Format ................ 28 82 1. Introduction 84 As a synchronization protocol, IEEE 1588-2008 [IEEE1588] is widely 85 supported in the carrier networks, industrial networks, automotive 86 networks, and many other applications. It can provide high 87 precision time synchronization as fine as nano-seconds. The 88 protocol depends on a Precision Time Protocol (PTP) engine to 89 decide its own state automatically, and a PTP transportation layer 90 to carry the PTP timing and various quality messages. The 91 configuration parameters and state data sets of IEEE 1588-2008 are 92 numerous. 94 According to the concepts described in [RFC3444], IEEE 1588-2008 95 itself provides an information model in its normative 96 specifications for the data sets (in IEEE 1588-2008 clause 8). Some 97 standardization organizations including the IETF have specified 98 data models in MIBs (Management Information Bases) for IEEE 1588- 99 2008 data sets (e.g. [RFC8173], [IEEE8021AS]). These MIBs are 100 typically focused on retrieval of state data using the Simple 101 Network Management Protocol (SNMP), furthermore, configuration of 102 PTP data sets is not considered in [RFC8173]. 104 Some service providers and applications require that the management 105 of the IEEE 1588-2008 synchronization network be flexible and more 106 Internet-based (typically overlaid on their transport networks). 107 Software Defined Network (SDN) is another driving factor, which 108 demands an improved configuration capability of synchronization 109 networks. 111 YANG [RFC6020] is a data modeling language used to model 112 configuration and state data manipulated by network management 113 protocols like the Network Configuration Protocol (NETCONF) 114 [RFC6241]. A small set of built-in data types are defined in 115 [RFC6020], and a collection of common data types are further 116 defined in [RFC6991]. Advantages of YANG include Internet based 117 configuration capability, validation, rollback and so on. All of 118 these characteristics make it attractive to become another 119 candidate modeling language for IEEE 1588-2008. 121 This document defines a YANG [RFC6020] data model for the 122 configuration of IEEE 1588-2008 devices and clocks, and retrieval 123 of the state data of IEEE 1588-2008 clocks. The data model is based 124 on the PTP data sets as specified in [IEEE1588]. The technology 125 specific IEEE 1588-2008 information, e.g., those specifically 126 implemented by a bridge, a router or a telecom profile, is out of 127 scope of this document. 129 When used in practice, network products in support of 130 synchronization typically conform to one or more IEEE 1588-2008 131 profiles. Each profile specifies how IEEE 1588-2008 is used in a 132 given industry (e.g. telecom, automotive) and application. A 133 profile can require features that are optional in IEEE 1588-2008, 134 and it can specify new features that use IEEE 1588-2008 as a 135 foundation. 137 It is expected that the IEEE 1588-2008 YANG module will be used as 138 follows: 140 o The IEEE 1588-2008 YANG module can be used as-is for products 141 that conform to one of the default profiles specified in IEEE 1588- 142 2008. 144 o When the IEEE 1588 standard is revised (e.g. the IEEE 1588 145 revision in progress scheduled to be published in 2017), it will 146 add some new optional features to its data sets. The YANG module 147 of this document can be revised and extended to add the new 148 features (e.g. of IEEE 1588-2017). The YANG "revision" can be used 149 to indicate changes to the YANG module. 151 o A profile standard based on IEEE 1588-2008 may create a 152 dedicated YANG module for its profile. The profile's YANG module 153 may use YANG "import" to import the IEEE 1588-2008 YANG module as 154 its foundation. Then the profile's YANG module can use YANG 155 "augment" to add any profile-specific enhancements. 157 o A product that conforms to a profile standard can also create 158 its own YANG module. The product's YANG module can "import" the 159 profile's module, and then use YANG "augment" to add any product- 160 specific enhancements. 162 1.1. Conventions used in this document 164 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 165 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 166 this document are to be interpreted as described in [RFC2119]. 168 1.2. Terminology 170 Most terminologies used in this document are extracted from 171 [IEEE1588]. 173 BC Boundary Clock 175 DS Data Set 177 E2E End-to-End 179 EUI Extended Unique Identifier. 181 GPS Global Positioning System 183 IANA Internet Assigned Numbers Authority 185 IP Internet Protocol 186 NIST National Institute of Standards and Technology 188 NTP Network Time Protocol 190 OC Ordinary Clock 192 P2P Peer-to-Peer 194 PTP Precision Time Protocol 196 TAI International Atomic Time 198 TC Transparent Clock 200 UTC Coordinated Universal Time 202 PTP dataset Structured attributes of clocks (an OC, BC or TC) used 203 for PTP protocol decisions and for providing values for PTP message 204 fields, see Section 8 of [IEEE1588]. 206 PTP instance A PTP implementation in the device (i.e., an OC or BC) 207 represented by a specific PTP dataset. 209 2. IEEE 1588-2008 YANG Model hierarchy 211 This section describes the hierarchy of an IEEE 1588-2008 YANG 212 module. Query and configuration of device wide or port specific 213 configuration information and clock data set is described for this 214 version. 216 Query and configuration of clock information include: 218 - Clock data set attributes in a clock node, including: current-ds, 219 parent-ds, default-ds, time-properties-ds, and transparent-clock- 220 default-ds. 222 - Port-specific data set attributes, including: port-ds and 223 transparent-clock-port-ds. 225 The readers are assumed to be familiar with IEEE 1588-2008. As all 226 PTP terminologies and PTP data set attributes are described in 227 details in IEEE 1588-2008 [IEEE1588], this document only outlines 228 each of them in the YANG module. 230 A simplified graphical representation of the data model is 231 typically used by YANG modules as described in [RFC8040]. This 232 document uses the same representation and the meaning of the 233 symbols in these diagrams is as follows: 235 o Brackets "[" and "]" enclose list keys. 237 o Abbreviations before data node names: "rw" means configuration 238 data (read-write) and "ro" state data (read-only). For IEEE 1588- 239 2008, all data nodes are marked "rw" (see 2.2). 241 o Symbols after data node names: "?" means an optional node, "!" 242 means a presence container, and "*" denotes a list and leaf-list. 244 o Parentheses enclose choice and case nodes, and case nodes are 245 also marked with a colon (":"). 247 o Ellipsis ("...") stands for contents of subtrees that are not 248 shown. 250 o Arrow ("->") stands for a reference to a particular leaf 251 instance in the tree. 253 module: ietf-ptp 254 +--rw ptp 255 +--rw instance-list* [instance-number] 256 | +--rw instance-number uint16 257 | +--rw default-ds 258 | | +--rw two-step-flag? boolean 259 | | +--rw clock-identity? clock-identity-type 260 | | +--rw number-ports? uint16 261 | | +--rw clock-quality 262 | | | +--rw clock-class? uint8 263 | | | +--rw clock-accuracy? uint8 264 | | | +--rw offset-scaled-log-variance? uint16 265 | | +--rw priority1? uint8 266 | | +--rw priority2? uint8 267 | | +--rw domain-number? uint8 268 | | +--rw slave-only? boolean 269 | +--rw current-ds 270 | | +--rw steps-removed? uint16 271 | | +--rw offset-from-master? time-interval-type 272 | | +--rw mean-path-delay? time-interval-type 273 | +--rw parent-ds 274 | | +--rw parent-port-identity 275 | | | +--rw clock-identity? clock-identity-type 276 | | | +--rw port-number? uint16 277 | | +--rw parent-stats? boolean 278 | | +--rw observed-parent-offset-scaled-log-variance? uint16 279 | | +--rw observed-parent-clock-phase-change-rate? int32 280 | | +--rw grandmaster-identity? binary 281 | | +--rw grandmaster-clock-quality 282 | | | +--rw clock-class? uint8 283 | | | +--rw clock-accuracy? uint8 284 | | | +--rw offset-scaled-log-variance? uint16 285 | | +--rw grandmaster-priority1? uint8 286 | | +--rw grandmaster-priority2? uint8 287 | +--rw time-properties-ds 288 | | +--rw current-utc-offset-valid? boolean 289 | | +--rw current-utc-offset? int16 290 | | +--rw leap59? boolean 291 | | +--rw leap61? boolean 292 | | +--rw time-traceable? boolean 293 | | +--rw frequency-traceable? boolean 294 | | +--rw ptp-timescale? boolean 295 | | +--rw time-source? uint8 296 | +--rw port-ds-list* [port-number] 297 | +--rw port-number uint16 298 | +--rw port-state? port-state-enumeration 299 | +--rw underlying-interface? if:interface-ref 300 | +--rw log-min-delay-req-interval? int8 301 | +--rw peer-mean-path-delay? time-interval-type 302 | +--rw log-announce-interval? int8 303 | +--rw announce-receipt-timeout? uint8 304 | +--rw log-sync-interval? int8 305 | +--rw delay-mechanism? delay-mechanism-enumeration 306 | +--rw log-min-pdelay-req-interval? int8 307 | +--rw version-number? uint8 308 +--rw transparent-clock-default-ds 309 | +--rw clock-identity? clock-identity-type 310 | +--rw number-ports? uint16 311 | +--rw delay-mechanism? delay-mechanism-enumeration 312 | +--rw primary-domain? uint8 313 +--rw transparent-clock-port-ds-list* [port-number] 314 +--rw port-number uint16 315 +--rw clock-identity? clock-identity-type 316 +--rw log-min-pdelay-req-interval? int8 317 +--rw faulty-flag? boolean 318 +--rw peer-mean-path-delay? time-interval-type 320 2.1. Interpretations from IEEE 1588 Working Group 322 The preceding model and the associated YANG module have some subtle 323 differences from the data set specifications of IEEE Std 1588-2008. 324 These differences are based on interpretation from the IEEE 1588 325 Working Group, and are intended to provide compatibility with 326 future revisions of the IEEE 1588 standard. 328 In IEEE Std 1588-2008, a physical product can implement multiple 329 PTP clocks (i.e. ordinary, boundary, or transparent clock). As 330 specified in 1588-2008 subclause 7.1, each of the multiple clocks 331 operates in an independent domain. However, the organization of 332 multiple PTP domains was not clear in the data sets of IEEE Std 333 1588-2008. This document introduces the concept of PTP instance as 334 described in the new revision of IEEE 1588. The instance concept is 335 used exclusively to allow for optional support of multiple domains. 336 The instance number has no usage within PTP messages. 338 Based on statements in IEEE 1588-2008 subclauses 8.3.1 and 10.1, 339 most transparent clock products have interpreted the transparent 340 clock data sets to reside as a singleton at the root level of the 341 managed product, and this YANG model reflects that location. 343 2.2. Configuration and state 345 The information model of IEEE Std 1588-2008 classifies each member 346 in PTP data sets as one of the following: 348 - Configurable: Writable by management. 350 - Dynamic: Read-only to management, and the value is changed by 351 1588 protocol operation. 353 - Static: Read-only to management, and the value typically does not 354 change. 356 Under certain circumstances, the classification of an IEEE 1588 357 data set member can change. For details on the classification of 358 each PTP data set member, refer to the IEEE Std 1588-2008 359 specification for that member. 361 3. IEEE 1588-2008 YANG Module 363 file "ietf-ptp@2017-10-20.yang" 365 module ietf-ptp { 366 namespace "urn:ietf:params:xml:ns:yang:ietf-ptp"; 367 prefix "ptp"; 369 import ietf-interfaces { 370 prefix if; 371 } 373 organization "IETF TICTOC Working Group"; 374 contact 375 "WG Web: http://tools.ietf.org/wg/tictoc/ 376 WG List: 377 WG Chair: Karen O'Donoghue 378 379 WG Chair: Yaakov Stein 380 381 Editor: Yuanlong Jiang 382 383 Editor: Rodney Cummings 384 "; 385 description 386 "This YANG module defines a data model for the configuration 387 of IEEE 1588-2008 clocks, and also for retrieval of the state 388 data of IEEE 1588-2008 clocks."; 390 revision "2017-10-20" { 391 description "Version 6.0"; 392 reference "draft-ietf-tictoc-1588v2-yang"; 393 } 395 typedef delay-mechanism-enumeration { 396 type enumeration { 397 enum e2e { 398 value 1; 399 description 400 "The port uses the delay request-response mechanism."; 401 } 402 enum p2p { 403 value 2; 404 description 405 "The port uses the peer delay mechanism."; 406 } 407 enum disabled { 408 value 254; 409 description 410 "The port does not implement any delay mechanism."; 411 } 412 } 413 description 414 "The propagation delay measuring option used by the 415 port. Values for this enumeration are specified 416 by the IEEE 1588 standard exclusively."; 417 reference 418 "IEEE Std 1588-2008: 8.2.5.4.4"; 419 } 421 typedef port-state-enumeration { 422 type enumeration { 423 enum initializing { 424 value 1; 425 description 426 "The port is initializing its data sets, hardware, and 427 communication facilities."; 428 } 429 enum faulty { 430 value 2; 431 description 432 "The port is in the fault state."; 433 } 434 enum disabled { 435 value 3; 436 description 437 "The port is disabled, and is not communicating PTP 438 messages (other than possibly PTP management 439 messages)."; 440 } 441 enum listening { 442 value 4; 443 description 444 "The port is listening for an Announce message."; 445 } 446 enum pre-master { 447 value 5; 448 description 449 "The port is in the pre-master state."; 450 } 451 enum master { 452 value 6; 453 description 454 "The port is behaving as a master port."; 456 } 457 enum passive { 458 value 7; 459 description 460 "The port is in the passive state."; 461 } 462 enum uncalibrated { 463 value 8; 464 description 465 "A master port has been selected, but the port is still 466 in the uncalibrated state."; 467 } 468 enum slave { 469 value 9; 470 description 471 "The port is synchronizing to the selected master port."; 472 } 473 } 475 description 476 "The current state of the protocol engine associated 477 with the port. Values for this enumeration are specified 478 by the IEEE 1588 standard exclusively."; 479 reference 480 "IEEE Std 1588-2008: 8.2.5.3.1, 9.2.5"; 481 } 483 typedef time-interval-type { 484 type int64; 485 description 486 "Derived data type for time interval, represented in units of 487 nanoseconds and multiplied by 2^16"; 488 reference 489 "IEEE Std 1588-2008: 5.3.2"; 490 } 492 typedef clock-identity-type { 493 type binary { 494 length "8"; 495 } 496 description 497 "Derived data type to identify a clock"; 498 reference 499 "IEEE Std 1588-2008: 5.3.4"; 500 } 502 grouping clock-quality-grouping { 503 description 504 "Derived data type for quality of a clock, which contains 505 clockClass, clockAccuracy and offsetScaledLogVariance."; 506 reference 507 "IEEE Std 1588-2008: 5.3.7"; 509 leaf clock-class { 510 type uint8; 511 default 248; 512 description 513 "The clockClass denotes the traceability of the time 514 or frequency distributed by the clock."; 515 } 517 leaf clock-accuracy { 518 type uint8; 519 description 520 "The clockAccuracy indicates the expected accuracy 521 of the clock."; 522 } 524 leaf offset-scaled-log-variance { 525 type uint16; 526 description 527 "The offsetScaledLogVariance provides an estimate of 528 the variations of the clock from a linear timescale 529 when it is not synchronized to another clock 530 using the protocol."; 531 } 532 } 534 container ptp { 535 description 536 "The PTP struct containing all attributes of PTP Dataset, 537 other optional PTP attributes can be augmented as well."; 539 list instance-list { 541 key "instance-number"; 543 description 544 "List of one or more PTP datasets in the device (see IEEE 545 Std 1588-2008 subclause 6.3). 546 Each PTP dataset represents a distinct instance of 547 PTP implementation in the device (i.e. distinct 548 Ordinary Clock or Boundary Clock)."; 550 leaf instance-number { 551 type uint16; 552 description 553 "The instance number of the current PTP instance. 554 This instance number is used for management purposes 555 only. This instance number does not represent the PTP 556 domain number, and is not used in PTP messages."; 557 } 559 container default-ds { 560 description 561 "The default data set of the clock (see IEEE Std 562 1588-2008 subclause 8.2.1)."; 564 leaf two-step-flag { 565 type boolean; 566 description 567 "When set, the clock is a two-step clock; otherwise, 568 the clock is a one-step clock."; 569 } 571 leaf clock-identity { 572 type clock-identity-type; 573 description 574 "The clockIdentity of the local clock"; 575 } 577 leaf number-ports { 578 type uint16; 579 description 580 "The number of PTP ports on the instance."; 581 } 583 container clock-quality { 584 description 585 "The clockQuality of the local clock."; 587 uses clock-quality-grouping; 588 } 590 leaf priority1 { 591 type uint8; 592 description 593 "The priority1 attribute of the local clock."; 594 } 595 leaf priority2{ 596 type uint8; 597 description 598 "The priority2 attribute of the local clock. "; 599 } 601 leaf domain-number { 602 type uint8; 603 description 604 "The domain number of the current syntonization 605 domain."; 606 } 608 leaf slave-only { 609 type boolean; 610 description 611 "When set, the clock is a slave-only clock."; 612 } 614 } 616 container current-ds { 617 description 618 "The current data set of the clock (see IEEE Std 619 1588-2008 subclause 8.2.2)."; 621 leaf steps-removed { 622 type uint16; 623 default 0; 624 description 625 "The number of communication paths traversed 626 between the local clock and the grandmaster clock."; 627 } 629 leaf offset-from-master { 630 type time-interval-type; 631 description 632 "The current value of the time difference between 633 a master and a slave clock as computed by the slave."; 634 } 636 leaf mean-path-delay { 637 type time-interval-type; 638 description 639 "The current value of the mean propagation time between 640 a master and a slave clock as computed by the slave."; 642 } 644 } 646 container parent-ds { 647 description 648 "The parent data set of the clock (see IEEE Std 1588-2008 649 subclause 8.2.3)."; 651 container parent-port-identity { 652 description 653 "The portIdentity of the port on the master, it 654 contains two members: clockIdentity and portNumber."; 655 reference 656 "IEEE Std 1588-2008: 5.3.5"; 658 leaf clock-identity { 659 type clock-identity-type; 660 description 661 "Identity of the clock"; 662 } 664 leaf port-number { 665 type uint16; 666 description 667 "Port number"; 668 } 669 } 671 leaf parent-stats { 672 type boolean; 673 default false; 674 description 675 "When set, the values of 676 observedParentOffsetScaledLogVariance and 677 observedParentClockPhaseChangeRate of parentDS 678 have been measured and are valid."; 679 } 681 leaf observed-parent-offset-scaled-log-variance { 682 type uint16; 683 default 65535; 684 description 685 "An estimate of the parent clock's PTP variance 686 as observed by the slave clock."; 687 } 688 leaf observed-parent-clock-phase-change-rate { 689 type int32; 690 description 691 "An estimate of the parent clock's phase change rate 692 as observed by the slave clock."; 693 } 695 leaf grandmaster-identity { 696 type binary { 697 length "8"; 698 } 699 description 700 "The clockIdentity attribute of the grandmaster clock."; 701 } 703 container grandmaster-clock-quality { 704 description 705 "The clockQuality of the grandmaster clock."; 706 uses clock-quality-grouping; 707 } 709 leaf grandmaster-priority1 { 710 type uint8; 711 description 712 "The priority1 attribute of the grandmaster clock."; 713 } 715 leaf grandmaster-priority2 { 716 type uint8; 717 description 718 "The priority2 attribute of the grandmaster clock."; 719 } 721 } 723 container time-properties-ds { 724 description 725 "The timeProperties data set of the clock (see 726 IEEE Std 1588-2008 subclause 8.2.4)."; 728 leaf current-utc-offset-valid { 729 type boolean; 730 description 731 "When set, the current UTC offset is valid."; 732 } 734 leaf current-utc-offset { 735 type int16; 736 description 737 "The offset between TAI and UTC when the epoch of the 738 PTP system is the PTP epoch, i.e., when ptp-timescale 739 is TRUE; otherwise, the value has no meaning."; 740 } 742 leaf leap59 { 743 type boolean; 744 description 745 "When set, the last minute of the current UTC day 746 contains 59 seconds."; 747 } 749 leaf leap61 { 750 type boolean; 751 description 752 "When set, the last minute of the current UTC day 753 contains 61 seconds."; 754 } 756 leaf time-traceable { 757 type boolean; 758 description 759 "When set, the timescale and the currentUtcOffset are 760 traceable to a primary reference."; 761 } 763 leaf frequency-traceable { 764 type boolean; 765 description 766 "When set, the frequency determining the timescale 767 is traceable to a primary reference."; 768 } 770 leaf ptp-timescale { 771 type boolean; 772 description 773 "When set, the clock timescale of the grandmaster 774 clock is PTP; otherwise, the timescale is ARB 775 (arbitrary)."; 776 } 778 leaf time-source { 779 type uint8; 780 description 781 "The source of time used by the grandmaster clock."; 783 } 784 } 786 list port-ds-list { 787 key "port-number"; 788 description 789 "List of port data sets of the clock (see IEEE Std 790 1588-2008 subclause 8.2.5)."; 792 leaf port-number{ 793 type uint16; 794 description 795 "Port number. 796 The data sets (i.e. information model) of IEEE Std 797 1588-2008 specify a member portDS.portIdentity, which 798 uses a typed struct with members clockIdentity and 799 portNumber. 801 In this YANG data model, portIdentity is not modeled 802 in the port-ds-list, however, its members are provided 803 as follows: 804 portIdentity.portNumber is provided as this port- 805 number leaf in port-ds-list; and 806 portIdentity.clockIdentity is provided as the clock- 807 identity leaf in default-ds of the instance 808 (i.e. ../../default-ds /clock-identity)."; 809 } 811 leaf port-state { 812 type port-state-enumeration; 813 default "initializing"; 814 description 815 "Current state associated with the port."; 816 } 818 leaf underlying-interface { 819 type if:interface-ref; 820 description 821 "Reference to the configured underlying interface that 822 is used by this PTP Port (see RFC 7223)."; 823 } 825 leaf log-min-delay-req-interval { 826 type int8; 827 description 828 "The base-two logarithm of the minDelayReqInterval 829 (the minimum permitted mean time interval between 830 successive Delay_Req messages)."; 831 } 833 leaf peer-mean-path-delay { 834 type time-interval-type; 835 default 0; 836 description 837 "An estimate of the current one-way propagation delay 838 on the link when the delayMechanism is P2P; otherwise, 839 it is zero."; 840 } 842 leaf log-announce-interval { 843 type int8; 844 description 845 "The base-two logarithm of the mean 846 announceInterval (mean time interval between 847 successive Announce messages)."; 848 } 850 leaf announce-receipt-timeout { 851 type uint8; 852 description 853 "The number of announceInterval that have to pass 854 without receipt of an Announce message before the 855 occurrence of the event ANNOUNCE_RECEIPT_TIMEOUT_ 856 EXPIRES."; 857 } 859 leaf log-sync-interval { 860 type int8; 861 description 862 "The base-two logarithm of the mean SyncInterval 863 for multicast messages. The rates for unicast 864 transmissions are negotiated separately on a per port 865 basis and are not constrained by this attribute."; 866 } 868 leaf delay-mechanism { 869 type delay-mechanism-enumeration; 870 description 871 "The propagation delay measuring option used by the 872 port in computing meanPathDelay."; 873 } 875 leaf log-min-pdelay-req-interval { 876 type int8; 877 description 878 "The base-two logarithm of the 879 minPdelayReqInterval (minimum permitted mean time 880 interval between successive Pdelay_Req messages)."; 882 } 884 leaf version-number { 885 type uint8; 886 description 887 "The PTP version in use on the port."; 888 } 890 } 891 } 893 container transparent-clock-default-ds { 894 description 895 "The members of the transparentClockDefault Data Set (see 896 IEEE Std 1588-2008 subclause 8.3.2)."; 898 leaf clock-identity { 899 type clock-identity-type; 900 description 901 "The clockIdentity of the transparent clock."; 902 } 903 leaf number-ports { 904 type uint16; 905 description 906 "The number of PTP ports on the Transparent Clock."; 907 } 908 leaf delay-mechanism { 909 type delay-mechanism-enumeration; 910 description 911 "The propagation delay measuring option 912 used by the transparent clock."; 913 } 914 leaf primary-domain { 915 type uint8; 916 default 0; 917 description 918 "The domainNumber of the primary syntonization domain."; 919 } 921 } 923 list transparent-clock-port-ds-list { 924 key "port-number"; 925 description 926 "List of transparentClockPort data sets of the transparent 927 clock (see IEEE Std 1588-2008 subclause 8.3.3)."; 929 leaf port-number { 930 type uint16; 931 description 932 "Port number. 933 The data sets (i.e. information model) of IEEE Std 934 1588-2008 specify a member 935 transparentClockPortDS.portIdentity, which uses a typed 936 struct with members clockIdentity and portNumber. 938 In this YANG data model, portIdentity is not modeled in 939 the transparent-clock-port-ds-list, however, 940 portIdentity.portNumber is provided as this leaf member 941 in transparent-clock-port-ds-list."; 943 } 945 leaf clock-identity { 946 type clock-identity-type; 947 description 948 "clock-identity. 949 The data sets (i.e. information model) of IEEE Std 950 1588-2008 specify a member 951 transparentClockPortDS.portIdentity, which uses a typed 952 struct with members clockIdentity and portNumber. 954 In this YANG data model, portIdentity is not modeled in 955 the transparent-clock-port-ds-list, however, 956 portIdentity.clockIdentity is provided as this leaf 957 member in transparent-clock-port-ds-list."; 958 } 960 leaf log-min-pdelay-req-interval { 961 type int8; 962 description 963 "The logarithm to the base 2 of the 964 minPdelayReqInterval (minimum permitted mean time 965 interval between successive Pdelay_Req messages)."; 966 } 967 leaf faulty-flag { 968 type boolean; 969 default false; 970 description 971 "When set, the port is faulty."; 972 } 973 leaf peer-mean-path-delay { 974 type time-interval-type; 975 default 0; 976 description 977 "An estimate of the current one-way propagation delay 978 on the link when the delayMechanism is P2P; otherwise, 979 it is zero."; 980 } 982 } 983 } 984 } 986 988 4. Security Considerations 990 YANG modules are designed to be accessed via the NETCONF protocol 991 [RFC6241], thus security considerations in [RFC6241] apply here. 992 Security measures such as using the NETCONF over SSH [RFC6242] and 993 restricting its use with access control [RFC6536] can further 994 improve its security, avoid injection attacks and misuse of the 995 protocol. Furthermore, general security considerations of time 996 protocols are discussed in [RFC7384]. 998 Some data nodes defined in this YANG module are writable, and an 999 inappropriate use of them may adversely impact a synchronization 1000 network. For example, loss of synchronization on a clock, accuracy 1001 degradation on a set of clocks, or even break down of a whole 1002 synchronization network. 1004 5. IANA Considerations 1006 This document registers a URI in the IETF XML registry, and the 1007 following registration is requested to be made: 1008 URI: urn:ietf:params:xml:ns:yang:ietf-ptp-dataset 1010 This document registers a YANG module in the YANG Module Names: 1011 name: ietf-ptp-dataset namespace: urn:ietf:params:xml:ns:yang:ietf- 1012 ptp-dataset 1014 6. References 1016 6.1. Normative References 1018 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1019 Requirement Levels", BCP 14, RFC 2119, March 1997 1021 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1022 Network Configuration Protocol (NETCONF) ", RFC 6020, 1023 October 2010 1025 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1026 July 2013 1028 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1029 Management", RFC 7223, May 2014 1031 [IEEE1588] IEEE, "IEEE Standard for a Precision Clock 1032 Synchronization Protocol for Networked Measurement and 1033 Control Systems", IEEE Std 1588-2008, July 2008 1035 6.2. Informative References 1037 [IEEE8021AS] IEEE, "Timing and Synchronizations for Time-Sensitive 1038 Applications in Bridged Local Area Networks", IEEE 1039 802.1AS-2001, 2011 1041 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 1042 Information Models and Data Models", RFC 3444, January 1043 2003 1045 [RFC4663] Harrington, D., "Transferring MIB Work from IETF Bridge 1046 MIB WG to IEEE 802.1 WG", RFC 4663, September 2006 1048 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 1049 Bierman, "Network Configuration Protocol (NETCONF)", RFC 1050 6241, June 2011 1052 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1053 Shell (SSH)", RFC 6242, June 2011 1055 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1056 Protocol (NETCONF) Access Control Model", RFC 6536, March 1057 2012 1059 [RFC7384] Mizrahi, T., "Security Requirements of Time Protocols in 1060 Packet Switched Networks", RFC 7384, October 2014 1062 [RFC8040] Bierman, A., Bjorklund, M., and Watsen, K., "RESTCONF 1063 protocol", RFC 8040, January 2017 1065 [RFC8173] Shankarkumar, V., Montini, L., Frost, T., and Dowd, G., 1066 "Precision Time Protocol Version 2 (PTPv2) Management 1067 Information Base", RFC 8173, June 2017 1069 7. Acknowledgments 1071 The authors would like to thank Joe Gwinn, Mahesh Jethanandani, Tal 1072 Mizrahi, Opher Ronen, Liang Geng, Alex Campbell, and John Fletcher 1073 for their valuable reviews and suggestions, and thank Benoit Claise 1074 and Radek Krejci for their validation of the YANG module. 1076 Appendix A Transferring YANG Work to IEEE 1588 WG (Informational) 1078 This appendix describes a future plan to transition responsibility 1079 for IEEE 1588 YANG modules from the IETF TICTOC Working Group (WG) 1080 to the IEEE 1588 WG, which develops the time synchronization 1081 technology that the YANG modules are designed to manage. 1083 This appendix is forward-looking with regard to future 1084 standardization roadmaps in IETF and IEEE. Since those roadmaps 1085 cannot be predicted with significant accuracy, this appendix is 1086 informational, and it does not specify imperatives or normative 1087 specifications of any kind. 1089 The IEEE 1588-2008 YANG module of this standard represents a 1090 cooperation between IETF (for YANG) and IEEE (for 1588). For the 1091 initial standardization of IEEE-1588 YANG modules, the information 1092 model is relatively clear (i.e. IEEE 1588 data sets), but expertise 1093 in YANG is required, making IETF an appropriate location for the 1094 standards. The TICTOC WG has expertise with IEEE 1588, making it 1095 the appropriate location within IETF. 1097 The IEEE 1588 WG anticipates future changes to its standard on an 1098 ongoing basis. As IEEE 1588 WG members gain practical expertise 1099 with YANG, the IEEE 1588 WG will become more appropriate for 1100 standardization of its YANG modules. As the IEEE 1588 standard is 1101 revised and/or amended, IEEE 1588 members can more effectively 1102 synchronize the revision of this YANG module with future versions 1103 of the IEEE 1588 standard. 1105 This appendix is meant to establish some clear expectations between 1106 IETF and IEEE about the future transfer of IEEE 1588 YANG modules 1107 to the IEEE 1588 WG. The goal is to assist in making the future 1108 transfer as smooth as possible. As the transfer takes place, some 1109 case-by-case situations are likely to arise, which can be handled 1110 by discussion on the IETF TICTOC WG mailing lists and/or 1111 appropriate liaisons. 1113 This appendix obtained insight from [RFC4663], an informational 1114 memo that described a similar transfer of MIB work from the IETF 1115 Bridge MIB WG to the IEEE 802.1 WG. 1117 A.1. Assumptions for the Transfer 1119 For the purposes of discussion in this appendix, assume that the 1120 IETF TICTOC WG has approved a standard YANG module for a published 1121 IEEE 1588 standard. As of this writing, this is IEEE Std 1588-2008, 1122 but it is possible that YANG for subsequent 1588 revisions could be 1123 published from the IETF TICTOC WG. For discussion in this appendix, 1124 we use the phrase "last IETF 1588 YANG" to refer to most recently 1125 published 1588 YANG from the IETF TICTOC WG. 1127 The IEEE-SA Standards Board New Standards Committee (NesCom) 1128 handles new Project Authorization Requests (PARs) (see 1129 http://standards.ieee.org/board/nes/). PARs are roughly the 1130 equivalent of IETF Working Group Charters and include information 1131 concerning the scope, purpose, and justification for 1132 standardization projects. 1134 Assume that IEEE 1588 has an approved PAR that explicitly specifies 1135 development of a YANG module. The transfer of YANG work will occur 1136 in the context of this IEEE 1588 PAR. For discussion in this 1137 appendix, we use the phrase "first IEEE 1588 YANG" to refer to the 1138 first IEEE 1588 standard for YANG. 1140 Assume that as part of the transfer of YANG work, the IETF TICTOC 1141 WG agrees to cease all work on standard YANG modules for IEEE 1588. 1143 Assume that the IEEE 1588 WG has participated in the development of 1144 the last IETF 1588 YANG module, such that the first IEEE 1588 YANG 1145 module will effectively be a revision of it. In other words, the 1146 transfer of YANG work will be relatively clean. 1148 The actual conditions for the future transfer can be such that the 1149 preceding assumptions do not hold. Exceptions to the assumptions 1150 will need to be addressed on a case-by-case basis at the time of 1151 the transfer. This appendix describes topics that can be addressed 1152 based on the preceding assumptions. 1154 A.2. Intellectual Property Considerations 1156 During review of the legal issues associated with transferring 1157 Bridge MIB WG documents to the IEEE 802.1 WG (Section 3.1 and 1158 Section 9 of [RFC4663]), it was concluded that the IETF does not 1159 have sufficient legal authority to make the transfer to IEEE 1160 without the consent of the document authors. 1162 If the last IETF 1588 YANG is published as a RFC, the work is 1163 required to be transferred from the IETF to the IEEE, so that IEEE 1164 1588 WG can begin working on the first IEEE 1588 YANG. 1166 When work on the first IEEE YANG module begins in the IEEE 1588 WG, 1167 that work derives from the last IETF YANG module of this RFC, 1168 requiring a transfer of that work from the IETF to the IEEE. In 1169 order to avoid having the transfer of that work be dependent on the 1170 availability of this RFC's authors at the time of its publication, 1171 the IEEE Standards Association department of Risk Management and 1172 Licensing provided the appropriate forms and mechanisms for this 1173 document's authors to assign a non-exclusive license for IEEE to 1174 create derivative works from this document. Those IEEE forms and 1175 mechanisms will be updated as needed during the development of this 1176 document and any future IETF YANG modules for IEEE 1588. This will 1177 help to make the future transfer of work from IETF to IEEE occur as 1178 smoothly as possible. 1180 As stated in the initial "Status of this Memo", the YANG module in 1181 this document conforms to the provisions of BCP 78. The IETF will 1182 retain all the rights granted at the time of publication in the 1183 published RFCs. 1185 A.3. Namespace and Module Name 1187 As specified in the "IANA Considerations" section, the YANG module 1188 in this document uses IETF as the root of its URN namespace and 1189 YANG module name. 1191 Use of IETF as the root of these names implies that the YANG module 1192 is standardized in a Working Group of IETF, using the IETF 1193 processes. If the IEEE 1588 Working Group were to continue using 1194 these names rooted in IETF, the IEEE 1588 YANG standardization 1195 would need to continue in the IETF. The goal of transferring the 1196 YANG work is to avoid this sort of dependency between standards 1197 organizations. 1199 IEEE 802 has an active PAR (IEEE P802d) for creating a URN 1200 namespace for IEEE use (see 1201 http://standards.ieee.org/develop/project/802d.html). It is likely 1202 that this IEEE 802 PAR will be approved and published prior to the 1203 transfer of YANG work to the IEEE 1588 WG. If so, the IEEE 1588 WG 1204 can use the IEEE URN namespace for the first IEEE 1588 YANG module, 1205 such as: 1207 urn:ieee:Std:1588:yang:ieee1588-ptp-dataset 1209 where "ieee1588-ptp-dataset" is the registered YANG module name in 1210 the IEEE. 1212 Under the assumptions of section A.1, the first IEEE 1588 YANG 1213 module prefix can be the same as the last IETF 1588 YANG module 1214 prefix (i.e. "ptp-dataset"), since the nodes within both YANG 1215 modules are compatible. 1217 The result of these name changes are that for complete 1218 compatibility, a server (i.e. IEEE 1588 node) can choose to 1219 implement a YANG module for the last IETF 1588 YANG module (with 1220 IETF root) as well as the first IEEE 1588 YANG module (with IEEE 1221 root). Since the content of the YANG module transferred are the 1222 same, the server implementation is effectively common for both. 1224 From a client's perspective, a client of the last IETF 1588 YANG 1225 module (or earlier) looks for the IETF-rooted module name; and a 1226 client of the first IEEE 1588 YANG module (or later) looks for the 1227 IEEE-rooted module name. 1229 A.4. IEEE 1588 YANG Modules in ASCII Format 1231 Although IEEE 1588 can certainly decide to publish YANG modules 1232 only in the PDF format that they use for their standard documents, 1233 without publishing an ASCII version, most network management 1234 systems cannot import the YANG module directly from the PDF. Thus, 1235 not publishing an ASCII version of the YANG module would negatively 1236 impact implementers and deployers of YANG modules and would make 1237 potential IETF reviews of YANG modules more difficult. 1239 This appendix recommends that the IEEE 1588 WG consider future 1240 plans for: 1242 o Public availability of the ASCII YANG modules during project 1243 development. These ASCII files allow IETF participants to access 1244 these documents for pre-standard review purposes. 1246 o Public availability of the YANG portion of published IEEE 1588 1247 standards, provided as an ASCII file for each YANG module. 1248 These ASCII files are intended for use of the published IEEE 1249 1588 standard. 1251 As an example of public availability during project development, 1252 IEEE 802 uses the same repository that IETF uses for YANG module 1253 development (see https://github.com/YangModels/yang). IEEE branches 1254 are provided for experimental work (i.e. pre-PAR) as well as 1255 standard work (post-PAR drafts). IEEE-SA has approved use of this 1256 repository for project development, but not for published standards. 1258 As an example of public availability of YANG modules for published 1259 standards, IEEE 802.1 provides a public list of ASCII files for MIB 1260 (see http://www.ieee802.org/1/files/public/MIBs/ and 1261 http://www.ieee802.org/1/pages/MIBS.html), and analogous lists are 1262 planned for IEEE 802.1 YANG files. 1264 Authors' Addresses 1266 Yuanlong Jiang (Editor) 1267 Huawei Technologies Co., Ltd. 1268 Bantian, Longgang district 1269 Shenzhen 518129, China 1270 Email: jiangyuanlong@huawei.com 1272 Xian Liu 1273 Independent 1274 Shenzhen 518129, China 1275 lene.liuxian@foxmail.com 1277 Jinchun Xu 1278 Huawei Technologies Co., Ltd. 1279 Bantian, Longgang district 1280 Shenzhen 518129, China 1281 xujinchun@huawei.com 1283 Rodney Cummings (Editor) 1284 National Instruments 1285 11500 N. Mopac Expwy 1286 Bldg. C 1287 Austin, TX 78759-3504 1288 Email: Rodney.Cummings@ni.com