idnits 2.17.1 draft-ietf-tictoc-1588v2-yang-09.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 date (July 24, 2018) is 2074 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE1588' Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 2 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: January 2019 July 24, 2018 11 YANG Data Model for IEEE 1588-2008 12 draft-ietf-tictoc-1588v2-yang-09 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. The YANG module in this document conforms to the 20 Network Management Datastore Architecture (NMDA). 22 Status of this Memo 24 This Internet-Draft is submitted to IETF in full conformance with 25 the provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF), its areas, and its working groups. Note that 29 other groups may also distribute working documents as Internet- 30 Drafts. 32 Internet-Drafts are draft documents valid for a maximum of six 33 months and may be updated, replaced, or obsoleted by other 34 documents at any time. It is inappropriate to use Internet-Drafts 35 as reference material or to cite them other than as "work in 36 progress." 38 The list of current Internet-Drafts can be accessed at 39 http://www.ietf.org/ietf/1id-abstracts.txt 41 The list of Internet-Draft Shadow Directories can be accessed at 42 http://www.ietf.org/shadow.html 44 This Internet-Draft will expire on January 24, 2019. 46 Copyright Notice 48 Copyright (c) 2018 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with 56 respect to this document. Code Components extracted from this 57 document must include Simplified BSD License text as described in 58 Section 4.e of the Trust Legal Provisions and are provided without 59 warranty as described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction ............................................... 2 64 1.1. Conventions used in this document ....................... 4 65 1.2. Terminology ............................................. 4 66 2. IEEE 1588-2008 YANG Model hierarchy ........................ 5 67 2.1. Interpretations from IEEE 1588 Working Group ............ 8 68 2.2. Configuration and state ................................. 8 69 3. IEEE 1588-2008 YANG Module ................................. 9 70 4. Security Considerations ................................... 22 71 5. IANA Considerations ....................................... 23 72 6. References ................................................ 23 73 6.1. Normative References ................................... 23 74 6.2. Informative References ................................. 24 75 7. Acknowledgments ........................................... 25 76 Appendix A Transferring YANG Work to IEEE 1588 WG ............. 26 77 A.1. Assumptions for the Transfer ........................... 27 78 A.2. Intellectual Property Considerations ................... 27 79 A.3. Namespace and Module Name .............................. 28 80 A.4. IEEE 1588 YANG Modules in ASCII Format ................. 29 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 [RFC7950] 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 [RFC7950], 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 data model for the configuration of 122 IEEE 1588-2008 devices and clocks, and retrieval of the state data 123 of IEEE 1588-2008 clocks. The data model is based on the PTP data 124 sets as specified in [IEEE1588]. The technology specific IEEE 1588- 125 2008 information, e.g., those specifically implemented by a bridge, 126 a router or a telecom profile, is out of scope of this document. 128 The YANG module in this document conforms to the Network Management 129 Datastore Architecture (NMDA) [RFC8342]. 131 When used in practice, network products in support of 132 synchronization typically conform to one or more IEEE 1588-2008 133 profiles. Each profile specifies how IEEE 1588-2008 is used in a 134 given industry (e.g. telecom, automotive) and application. A 135 profile can require features that are optional in IEEE 1588-2008, 136 and it can specify new features that use IEEE 1588-2008 as a 137 foundation. 139 It is expected that the IEEE 1588-2008 YANG module be used as 140 follows: 142 o The IEEE 1588-2008 YANG module can be used as-is for products 143 that conform to one of the default profiles specified in IEEE 1588- 144 2008. 146 o When the IEEE 1588 standard is revised (e.g. the IEEE 1588 147 revision in progress at the time of writing this document), it will 148 add some new optional features to its data sets. The YANG module 149 of this document MAY be revised and extended to support these new 150 features. Moreover, the YANG "revision" SHOULD be used to indicate 151 changes to the YANG module under such a circumstance. 153 o A profile standard based on IEEE 1588-2008 may create a 154 dedicated YANG module for its profile. The profile's YANG module 155 SHOULD use YANG "import" to import the IEEE 1588-2008 YANG module 156 as its foundation. Then the profile's YANG module SHOULD use YANG 157 "augment" to add any profile-specific enhancements. 159 o A product that conforms to a profile standard can also create 160 its own YANG module. The product's YANG module SHOULD "import" the 161 profile's module, and then use YANG "augment" to add any product- 162 specific enhancements. 164 1.1. Conventions used in this document 166 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 167 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", 168 "MAY", and "OPTIONAL" in this document are to be interpreted as 169 described in BCP 14 [RFC2119] [RFC8174] when, and only when, they 170 appear in all capitals, as shown here. 172 1.2. Terminology 174 Most terminologies used in this document are extracted from 175 [IEEE1588]. 177 BC Boundary Clock, see Section 3.1.3 of [IEEE1588] 179 DS Data Set 181 E2E End-to-End 183 EUI Extended Unique Identifier 185 GPS Global Positioning System 186 IANA Internet Assigned Numbers Authority 188 IP Internet Protocol 190 NIST National Institute of Standards and Technology 192 NTP Network Time Protocol 194 OC Ordinary Clock, see Section 3.1.22 of [IEEE1588] 196 P2P Peer-to-Peer 198 PTP Precision Time Protocol 200 TAI International Atomic Time 202 TC Transparent Clock, see Section 3.1.46 of [IEEE1588] 204 UTC Coordinated Universal Time 206 PTP data set 207 Structured attributes of clocks (an OC, BC or TC) used for 208 PTP protocol decisions and for providing values for PTP 209 message fields, see Section 8 of [IEEE1588]. 211 PTP instance 212 A PTP implementation in the device (i.e., an OC or BC) 213 represented by a specific PTP data set. 215 2. IEEE 1588-2008 YANG Model hierarchy 217 This section describes the hierarchy of an IEEE 1588-2008 YANG 218 module. Query and configuration of device wide or port specific 219 configuration information and clock data set are described for this 220 version. 222 Query and configuration of clock information include: 224 (Note: The attribute names are consistent with IEEE 1588-2008, but 225 changed to the YANG style, i.e., using all lower-case, with dashes 226 between words.) 228 - Clock data set attributes in a clock node, including: current-ds, 229 parent-ds, default-ds, time-properties-ds, and transparent-clock- 230 default-ds. 232 - Port-specific data set attributes, including: port-ds and 233 transparent-clock-port-ds. 235 The readers are assumed to be familiar with IEEE 1588-2008. As all 236 PTP terminologies and PTP data set attributes are described in 237 details in IEEE 1588-2008 [IEEE1588], this document only outlines 238 each of them in the YANG module. 240 A simplified YANG tree diagram [RFC8340] representing the data 241 model is typically used by YANG modules. This document uses the 242 same tree diagram syntax as described in [RFC8340]. 244 module: ietf-ptp 245 +--rw ptp 246 +--rw instance-list* [instance-number] 247 | +--rw instance-number uint32 248 | +--rw default-ds 249 | | +--rw two-step-flag? boolean 250 | | +--ro clock-identity? clock-identity-type 251 | | +--rw number-ports? uint16 252 | | +--rw clock-quality 253 | | | +--rw clock-class? uint8 254 | | | +--rw clock-accuracy? uint8 255 | | | +--rw offset-scaled-log-variance? uint16 256 | | +--rw priority1? uint8 257 | | +--rw priority2? uint8 258 | | +--rw domain-number? uint8 259 | | +--rw slave-only? boolean 260 | +--rw current-ds 261 | | +--rw steps-removed? uint16 262 | | +--rw offset-from-master? time-interval-type 263 | | +--rw mean-path-delay? time-interval-type 264 | +--rw parent-ds 265 | | +--rw parent-port-identity 266 | | | +--rw clock-identity? clock-identity-type 267 | | | +--rw port-number? uint16 268 | | +--rw parent-stats? boolean 269 | | +--rw observed-parent-offset-scaled-log-variance? uint16 270 | | +--rw observed-parent-clock-phase-change-rate? int32 271 | | +--rw grandmaster-identity? clock-identity-type 272 | | +--rw grandmaster-clock-quality 273 | | | +--rw clock-class? uint8 274 | | | +--rw clock-accuracy? uint8 275 | | | +--rw offset-scaled-log-variance? uint16 276 | | +--rw grandmaster-priority1? uint8 277 | | +--rw grandmaster-priority2? uint8 278 | +--rw time-properties-ds 279 | | +--rw current-utc-offset-valid? boolean 280 | | +--rw current-utc-offset? int16 281 | | +--rw leap59? boolean 282 | | +--rw leap61? boolean 283 | | +--rw time-traceable? boolean 284 | | +--rw frequency-traceable? boolean 285 | | +--rw ptp-timescale? boolean 286 | | +--rw time-source? uint8 287 | +--rw port-ds-list* [port-number] 288 | +--rw port-number uint16 289 | +--rw port-state? port-state-enumeration 290 | +--rw underlying-interface? if:interface-ref 291 | +--rw log-min-delay-req-interval? int8 292 | +--rw peer-mean-path-delay? time-interval-type 293 | +--rw log-announce-interval? int8 294 | +--rw announce-receipt-timeout? uint8 295 | +--rw log-sync-interval? int8 296 | +--rw delay-mechanism? delay-mechanism-enumeration 297 | +--rw log-min-pdelay-req-interval? int8 298 | +--rw version-number? uint8 299 +--rw transparent-clock-default-ds 300 | +--ro clock-identity? clock-identity-type 301 | +--rw number-ports? uint16 302 | +--rw delay-mechanism? delay-mechanism-enumeration 303 | +--rw primary-domain? uint8 304 +--rw transparent-clock-port-ds-list* [port-number] 305 +--rw port-number uint16 306 +--rw log-min-pdelay-req-interval? int8 307 +--rw faulty-flag? boolean 308 +--rw peer-mean-path-delay? time-interval-type 310 2.1. Interpretations from IEEE 1588 Working Group 312 The preceding model and the associated YANG module have some subtle 313 differences from the data set specifications of IEEE Std 1588-2008. 314 These differences are based on interpretation from the IEEE 1588 315 Working Group, and are intended to provide compatibility with 316 future revisions of the IEEE 1588 standard. 318 In IEEE Std 1588-2008, a physical product can implement multiple 319 PTP clocks (i.e., ordinary, boundary, or transparent clock). As 320 specified in 1588-2008 subclause 7.1, each of the multiple clocks 321 operates in an independent domain. However, the organization of 322 multiple PTP domains was not clear in the data sets of IEEE Std 323 1588-2008. This document introduces the concept of PTP instance as 324 described in the new revision of IEEE 1588. The instance concept is 325 used exclusively to allow for optional support of multiple domains. 326 The instance number has no usage within PTP messages. 328 Based on statements in IEEE 1588-2008 subclauses 8.3.1 and 10.1, 329 most transparent clock products have interpreted the transparent 330 clock data sets to reside as a singleton at the root level of the 331 managed product, and this YANG model reflects that location. 333 2.2. Configuration and state 335 The information model of IEEE Std 1588-2008 classifies each member 336 in PTP data sets as one of the following: 338 - Configurable: Writable by management. 340 - Dynamic: Read-only to management, and the value is changed by 341 1588 protocol operation. 343 - Static: Read-only to management, and the value typically does not 344 change. 346 For details on the classification of each PTP data set member, 347 refer to the IEEE Std 1588-2008 specification for that member. 349 Under certain circumstances, the classification of an IEEE 1588 350 data set member may change for a YANG implementation, for example, 351 a configurable member needs to be changed to read-only. In such a 352 case, an implementation MAY choose to return a warning upon writing 353 to a read-only member, or use the deviation mechanism to develop a 354 new deviation model as described in Section 7.20.3 of [RFC7950]. 356 3. IEEE 1588-2008 YANG Module 358 This module imports typedef "interface-ref" from [RFC8343]. Most 359 attributes are based on the information model defined in [IEEE1588], 360 but their names are adapted to the YANG style of naming. 362 file "ietf-ptp@2018-07-24.yang" 363 //Note to RFC Editor: update the date to date of publication 364 module ietf-ptp { 365 yang-version 1.1; 366 namespace "urn:ietf:params:xml:ns:yang:ietf-ptp"; 367 prefix "ptp"; 369 import ietf-interfaces { 370 prefix if; 371 reference 372 "RFC8343: A YANG Data Model for Interface Management"; 373 } 375 organization "IETF TICTOC Working Group"; 376 contact 377 "WG Web: http://tools.ietf.org/wg/tictoc/ 378 WG List: 379 Editor: Yuanlong Jiang 380 381 Editor: Rodney Cummings 382 "; 383 description 384 "This YANG module defines a data model for the configuration 385 of IEEE 1588-2008 clocks, and also for retrieval of the state 386 data of IEEE 1588-2008 clocks."; 388 revision "2018-07-24" { 389 //Note to RFC Editor: update the date to date of publication 390 description "Initial version"; 391 reference "RFC XXXX: YANG Data Model for IEEE 1588-2008"; 392 //Note to RFC Editor: update RFC XXXX to the actual RFC number 394 } 396 typedef delay-mechanism-enumeration { 397 type enumeration { 398 enum e2e { 399 value 1; 400 description 401 "The port uses the delay request-response mechanism."; 402 } 403 enum p2p { 404 value 2; 405 description 406 "The port uses the peer delay mechanism."; 407 } 408 enum disabled { 409 value 254; 410 description 411 "The port does not implement any delay mechanism."; 412 } 413 } 414 description 415 "The propagation delay measuring option used by the 416 port. Values for this enumeration are specified 417 by the IEEE 1588 standard exclusively."; 418 reference 419 "IEEE Std 1588-2008: 8.2.5.4.4"; 420 } 422 typedef port-state-enumeration { 423 type enumeration { 424 enum initializing { 425 value 1; 426 description 427 "The port is initializing its data sets, hardware, and 428 communication facilities."; 429 } 430 enum faulty { 431 value 2; 432 description 433 "The port is in the fault state."; 434 } 435 enum disabled { 436 value 3; 437 description 438 "The port is disabled, and is not communicating PTP 439 messages (other than possibly PTP management 440 messages)."; 441 } 442 enum listening { 443 value 4; 444 description 445 "The port is listening for an Announce message."; 446 } 447 enum pre-master { 448 value 5; 449 description 450 "The port is in the pre-master state."; 451 } 452 enum master { 453 value 6; 454 description 455 "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 data set, 537 other optional PTP attributes can be augmented as well."; 539 list instance-list { 541 key "instance-number"; 542 description 543 "List of one or more PTP data sets in the device (see IEEE 544 Std 1588-2008 subclause 6.3). 545 Each PTP data set represents a distinct instance of 546 PTP implementation in the device (i.e., distinct 547 Ordinary Clock or Boundary Clock)."; 549 leaf instance-number { 550 type uint32; 551 description 552 "The instance number of the current PTP instance. 553 This instance number is used for management purposes 554 only. This instance number does not represent the PTP 555 domain number, and is not used in PTP messages."; 556 } 558 container default-ds { 559 description 560 "The default data set of the clock (see IEEE Std 561 1588-2008 subclause 8.2.1)."; 563 leaf two-step-flag { 564 type boolean; 565 description 566 "When set to true, the clock is a two-step clock; 567 otherwise,the clock is a one-step clock."; 568 } 570 leaf clock-identity { 571 type clock-identity-type; 572 config false; 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 } 589 leaf priority1 { 590 type uint8; 591 description 592 "The priority1 attribute of the local clock."; 593 } 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 to true, 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 } 635 leaf mean-path-delay { 636 type time-interval-type; 637 description 638 "The current value of the mean propagation time between 639 a master and a slave clock as computed by the slave."; 641 } 643 } 645 container parent-ds { 646 description 647 "The parent data set of the clock (see IEEE Std 1588-2008 648 subclause 8.2.3)."; 650 container parent-port-identity { 651 description 652 "The portIdentity of the port on the master, it 653 contains two members: clockIdentity and portNumber."; 654 reference 655 "IEEE Std 1588-2008: 5.3.5"; 657 leaf clock-identity { 658 type clock-identity-type; 659 description 660 "Identity of the clock"; 661 } 663 leaf port-number { 664 type uint16; 665 description 666 "Port number"; 667 } 668 } 670 leaf parent-stats { 671 type boolean; 672 default false; 673 description 674 "When set to true, the values of 675 observedParentOffsetScaledLogVariance and 676 observedParentClockPhaseChangeRate of parentDS 677 have been measured and are valid."; 678 } 680 leaf observed-parent-offset-scaled-log-variance { 681 type uint16; 682 default 65535; 683 description 684 "An estimate of the parent clock's PTP variance 685 as observed by the slave clock."; 686 } 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 clock-identity-type; 697 description 698 "The clockIdentity attribute of the grandmaster clock."; 699 } 701 container grandmaster-clock-quality { 702 description 703 "The clockQuality of the grandmaster clock."; 704 uses clock-quality-grouping; 705 } 707 leaf grandmaster-priority1 { 708 type uint8; 709 description 710 "The priority1 attribute of the grandmaster clock."; 711 } 713 leaf grandmaster-priority2 { 714 type uint8; 715 description 716 "The priority2 attribute of the grandmaster clock."; 717 } 719 } 721 container time-properties-ds { 722 description 723 "The timeProperties data set of the clock (see 724 IEEE Std 1588-2008 subclause 8.2.4)."; 726 leaf current-utc-offset-valid { 727 type boolean; 728 description 729 "When set to true, the current UTC offset is valid."; 730 } 731 leaf current-utc-offset { 732 when "../current-utc-offset-valid='true'"; 733 type int16; 734 description 735 "The offset between TAI and UTC when the epoch of the 736 PTP system is the PTP epoch in units of seconds, i.e., 737 when ptp-timescale is TRUE; otherwise, the value has 738 no meaning."; 739 } 741 leaf leap59 { 742 type boolean; 743 description 744 "When set to true, the last minute of the current UTC 745 day contains 59 seconds."; 746 } 748 leaf leap61 { 749 type boolean; 750 description 751 "When set to true, the last minute of the current UTC 752 day contains 61 seconds."; 753 } 755 leaf time-traceable { 756 type boolean; 757 description 758 "When set to true, the timescale and the 759 currentUtcOffset are traceable to a primary 760 reference."; 761 } 763 leaf frequency-traceable { 764 type boolean; 765 description 766 "When set to true, the frequency determining the 767 timescale is traceable to a primary reference."; 768 } 770 leaf ptp-timescale { 771 type boolean; 772 description 773 "When set to true, the clock timescale of the 774 grandmaster clock is PTP; otherwise, the timescale is 775 ARB 776 (arbitrary)."; 777 } 779 leaf time-source { 780 type uint8; 781 description 782 "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; 795 description 796 "Port number. 797 The data sets (i.e., information model) of IEEE Std 798 1588-2008 specify a member portDS.portIdentity, which 799 uses a typed struct with members clockIdentity and 800 portNumber. 802 In this YANG data model, portIdentity is not modeled 803 in the port-ds-list, however, its members are provided 804 as follows: 805 portIdentity.portNumber is provided as this port- 806 number leaf in port-ds-list; and 807 portIdentity.clockIdentity is provided as the clock- 808 identity leaf in default-ds of the instance 809 (i.e., ../../default-ds/clock-identity)."; 810 } 812 leaf port-state { 813 type port-state-enumeration; 814 default "initializing"; 815 description 816 "Current state associated with the port."; 817 } 819 leaf underlying-interface { 820 type if:interface-ref; 821 description 822 "Reference to the configured underlying interface that 823 is used by this PTP Port (see RFC 8343)."; 824 } 826 leaf log-min-delay-req-interval { 827 type int8; 828 description 829 "The base-two logarithm of the minDelayReqInterval 830 (the minimum permitted mean time interval between 831 successive Delay_Req messages)."; 832 } 834 leaf peer-mean-path-delay { 835 type time-interval-type; 836 default 0; 837 description 838 "An estimate of the current one-way propagation delay 839 on the link when the delayMechanism is P2P; otherwise, 840 it is zero."; 841 } 843 leaf log-announce-interval { 844 type int8; 845 description 846 "The base-two logarithm of the mean 847 announceInterval (mean time interval between 848 successive Announce messages)."; 849 } 851 leaf announce-receipt-timeout { 852 type uint8; 853 description 854 "The number of announceInterval that have to pass 855 without receipt of an Announce message before the 856 occurrence of the event ANNOUNCE_RECEIPT_TIMEOUT_ 857 EXPIRES."; 858 } 860 leaf log-sync-interval { 861 type int8; 862 description 863 "The base-two logarithm of the mean SyncInterval 864 for multicast messages. The rates for unicast 865 transmissions are negotiated separately on a per port 866 basis and are not constrained by this attribute."; 868 } 870 leaf delay-mechanism { 871 type delay-mechanism-enumeration; 872 description 873 "The propagation delay measuring option used by the 874 port in computing meanPathDelay."; 875 } 877 leaf log-min-pdelay-req-interval { 878 type int8; 879 description 880 "The base-two logarithm of the 881 minPdelayReqInterval (minimum permitted mean time 882 interval between successive Pdelay_Req messages)."; 884 } 886 leaf version-number { 887 type uint8; 888 description 889 "The PTP version in use on the port."; 890 } 892 } 893 } 895 container transparent-clock-default-ds { 896 description 897 "The members of the transparentClockDefault data set (see 898 IEEE Std 1588-2008 subclause 8.3.2)."; 900 leaf clock-identity { 901 type clock-identity-type; 902 config false; 903 description 904 "The clockIdentity of the transparent clock."; 905 } 907 leaf number-ports { 908 type uint16; 909 description 910 "The number of PTP ports on the transparent clock."; 911 } 913 leaf delay-mechanism { 914 type delay-mechanism-enumeration; 915 description 916 "The propagation delay measuring option 917 used by the transparent clock."; 918 } 920 leaf primary-domain { 921 type uint8; 922 default 0; 923 description 924 "The domainNumber of the primary syntonization domain (see 925 IEEE Std 1588-2008 subclause 10.1)."; 926 } 927 } 929 list transparent-clock-port-ds-list { 930 key "port-number"; 931 description 932 "List of transparentClockPort data sets of the transparent 933 clock (see IEEE Std 1588-2008 subclause 8.3.3)."; 935 leaf port-number { 936 type uint16; 937 description 938 "Port number. 939 The data sets (i.e., information model) of IEEE Std 940 1588-2008 specify a member 941 transparentClockPortDS.portIdentity, which uses a typed 942 struct with members clockIdentity and portNumber. 944 In this YANG data model, portIdentity is not modeled in 945 the transparent-clock-port-ds-list, however, its 946 members are provided as follows: 947 portIdentity.portNumber is provided as this leaf member 948 in transparent-clock-port-ds-list; and 949 portIdentity.clockIdentity is provided as the clock- 950 identity leaf in transparent-clock-default-ds 951 (i.e., ../../transparent-clock-default-ds/clock- 952 identity)."; 954 } 956 leaf log-min-pdelay-req-interval { 957 type int8; 958 description 959 "The logarithm to the base 2 of the 960 minPdelayReqInterval (minimum permitted mean time 961 interval between successive Pdelay_Req messages)."; 962 } 964 leaf faulty-flag { 965 type boolean; 966 default false; 967 description 968 "When set to true, the port is faulty."; 969 } 971 leaf peer-mean-path-delay { 972 type time-interval-type; 973 default 0; 974 description 975 "An estimate of the current one-way propagation delay 976 on the link when the delayMechanism is P2P; otherwise, 977 it is zero."; 978 } 980 } 981 } 982 } 984 986 4. Security Considerations 988 YANG modules are designed to be accessed via the NETCONF protocol 989 [RFC6241], thus security considerations in [RFC6241] apply here. 990 Security measures such as using the NETCONF over SSH [RFC6242] and 991 restricting its use with access control [RFC8341] can further 992 improve its security, avoid injection attacks and misuse of the 993 protocol. Furthermore, general security considerations of time 994 protocols are discussed in [RFC7384]. 996 All subtrees and most data nodes defined in this YANG module are 997 writable: 999 /ptp/instance-list specifies an instance (i.e., PTP data sets) for 1000 an OC or BC. 1002 /ptp/transparent-clock-default-ds specifies a default data set for 1003 a TC. 1005 /ptp/transparent-clock-port-ds-list specifies a list of port data 1006 sets for a TC. 1008 An inappropriate use of them may adversely impact a PTP 1009 synchronization network. For example, loss of synchronization on a 1010 clock, accuracy degradation on a set of clocks, or even break down 1011 of a whole synchronization network. 1013 5. IANA Considerations 1015 This document registers the following URI in the "IETF XML 1016 registry" [RFC3688]: 1017 URI: urn:ietf:params:xml:ns:yang:ietf-ptp 1018 Registrant Contact: The IESG 1019 XML: N/A; the requested URI is an XML namespace 1021 This document registers the following YANG module in the "YANG 1022 Module Names" registry [RFC6020]: 1023 Name: ietf-ptp 1024 Namespace: urn:ietf:params:xml:ns:yang:ietf-ptp 1025 Prefix: ptp 1026 Reference: RFC XXXX 1028 6. References 1030 6.1. Normative References 1032 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1033 Requirement Levels", BCP 14, RFC 2119, March 1997 1035 [RFC3688] Mealling, M., "The IETF XML Registry", RFC 3688, 1036 January 2004, 1038 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1039 Network Configuration Protocol (NETCONF) ", RFC 6020, 1040 October 2010 1042 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 1043 Bierman, "Network Configuration Protocol (NETCONF)", RFC 1044 6241, June 2011 1046 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1047 Shell (SSH)", RFC 6242, June 2011 1049 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1050 July 2013 1052 [RFC7950] Bjorklund, M., "The YANG 1.1 Data Modeling Language", RFC 1053 7950, August 2016 1055 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1056 2119 Key Words", BCP 14, RFC 8174, May 2017 1058 [RFC8341] Bierman, A. and Bjorklund, M., "Network Configuration 1059 Protocol (NETCONF) Access Control Model", RFC 8341, March 1060 2018 1062 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1063 and R. Wilton, "Network Management Datastore Architecture 1064 (NMDA)", RFC 8342, March 2018 1066 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 1067 Management", RFC 8343, March 2018 1069 [IEEE1588] IEEE, "IEEE Standard for a Precision Clock 1070 Synchronization Protocol for Networked Measurement and 1071 Control Systems", IEEE Std 1588-2008, July 2008 1073 6.2. Informative References 1075 [IEEE8021AS] IEEE, "Timing and Synchronizations for Time-Sensitive 1076 Applications in Bridged Local Area Networks", IEEE 1077 802.1AS-2001, 2011 1079 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 1080 Information Models and Data Models", RFC 3444, January 1081 2003 1083 [RFC4663] Harrington, D., "Transferring MIB Work from IETF Bridge 1084 MIB WG to IEEE 802.1 WG", RFC 4663, September 2006 1086 [RFC7384] Mizrahi, T., "Security Requirements of Time Protocols in 1087 Packet Switched Networks", RFC 7384, October 2014 1089 [RFC8340] Bjorklund, M., and Berger, L., "YANG Tree Diagrams", RFC 1090 8340, March 2018 1092 [RFC8173] Shankarkumar, V., Montini, L., Frost, T., and Dowd, G., 1093 "Precision Time Protocol Version 2 (PTPv2) Management 1094 Information Base", RFC 8173, June 2017 1096 7. Acknowledgments 1098 The authors would like to thank Tom Petch, Mahesh Jethanandani, Tal 1099 Mizrahi, Opher Ronen, Liang Geng, Alex Campbell, Joe Gwinn, John 1100 Fletcher, William Zhao and Dave Thaler for their valuable reviews 1101 and suggestions, thank Benoit Claise and Radek Krejci for their 1102 validation of the YANG module, and thank Jingfei Lv and Zitao Wang 1103 for their discussions on IEEE 1588 and YANG respectively. 1105 Appendix A Transferring YANG Work to IEEE 1588 WG 1107 This Appendix is informational. 1109 This appendix describes a future plan to transition responsibility 1110 for IEEE 1588 YANG modules from the IETF TICTOC Working Group (WG) 1111 to the IEEE 1588 WG, which develops the time synchronization 1112 technology that the YANG modules are designed to manage. 1114 This appendix is forward-looking with regard to future 1115 standardization roadmaps in IETF and IEEE. Since those roadmaps 1116 cannot be predicted with significant accuracy, this appendix is 1117 informational, and it does not specify imperatives or normative 1118 specifications of any kind. 1120 The IEEE 1588-2008 YANG module of this standard represents a 1121 cooperation between IETF (for YANG) and IEEE (for 1588). For the 1122 initial standardization of IEEE-1588 YANG modules, the information 1123 model is relatively clear (i.e., IEEE 1588 data sets), but 1124 expertise in YANG is required, making IETF an appropriate location 1125 for the standards. The TICTOC WG has expertise with IEEE 1588, 1126 making it the appropriate location within IETF. 1128 The IEEE 1588 WG anticipates future changes to its standard on an 1129 ongoing basis. As IEEE 1588 WG members gain practical expertise 1130 with YANG, the IEEE 1588 WG will become more appropriate for 1131 standardization of its YANG modules. As the IEEE 1588 standard is 1132 revised and/or amended, IEEE 1588 members can more effectively 1133 synchronize the revision of this YANG module with future versions 1134 of the IEEE 1588 standard. 1136 This appendix is meant to establish some clear expectations between 1137 IETF and IEEE about the future transfer of IEEE 1588 YANG modules 1138 to the IEEE 1588 WG. The goal is to assist in making the future 1139 transfer as smooth as possible. As the transfer takes place, some 1140 case-by-case situations are likely to arise, which can be handled 1141 by discussion on the IETF TICTOC WG mailing lists and/or 1142 appropriate liaisons. 1144 This appendix obtained insight from [RFC4663], an informational 1145 memo that described a similar transfer of MIB work from the IETF 1146 Bridge MIB WG to the IEEE 802.1 WG. 1148 A.1. Assumptions for the Transfer 1150 For the purposes of discussion in this appendix, assume that the 1151 IESG has approved the publication of an RFC containing a YANG 1152 module for a published IEEE 1588 standard. As of this writing, 1153 this is IEEE Std 1588-2008, but it is possible that YANG modules 1154 for subsequent 1588 revisions could be published from the IETF 1155 TICTOC WG. For discussion in this appendix, we use the phrase 1156 "last IETF 1588 YANG" to refer to the most recently published 1588 1157 YANG module from the IETF TICTOC WG. 1159 The IEEE-SA Standards Board New Standards Committee (NesCom) 1160 handles new Project Authorization Requests (PARs) (see 1161 http://standards.ieee.org/board/nes/). PARs are roughly the 1162 equivalent of IETF Working Group Charters and include information 1163 concerning the scope, purpose, and justification for 1164 standardization projects. 1166 Assume that IEEE 1588 has an approved PAR that explicitly specifies 1167 development of a YANG module. The transfer of YANG work will occur 1168 in the context of this IEEE 1588 PAR. For discussion in this 1169 appendix, we use the phrase "first IEEE 1588 YANG" to refer to the 1170 first IEEE 1588 standard for YANG. 1172 Assume that as part of the transfer of YANG work, the IETF TICTOC 1173 WG agrees to cease all work on standard YANG modules for IEEE 1588. 1175 Assume that the IEEE 1588 WG has participated in the development of 1176 the last IETF 1588 YANG module, such that the first IEEE 1588 YANG 1177 module will effectively be a revision of it. In other words, the 1178 transfer of YANG work will be relatively clean. 1180 The actual conditions for the future transfer can be such that the 1181 preceding assumptions do not hold. Exceptions to the assumptions 1182 will need to be addressed on a case-by-case basis at the time of 1183 the transfer. This appendix describes topics that can be addressed 1184 based on the preceding assumptions. 1186 A.2. Intellectual Property Considerations 1188 During review of the legal issues associated with transferring 1189 Bridge MIB WG documents to the IEEE 802.1 WG (Section 3.1 and 1190 Section 9 of [RFC4663]), it was concluded that the IETF does not 1191 have sufficient legal authority to make the transfer to IEEE 1192 without the consent of the document authors. 1194 If the last IETF 1588 YANG is published as a RFC, the work is 1195 required to be transferred from the IETF to the IEEE, so that IEEE 1196 1588 WG can begin working on the first IEEE 1588 YANG. 1198 When work on the first IEEE YANG module begins in the IEEE 1588 WG, 1199 that work derives from the last IETF YANG module of this RFC, 1200 requiring a transfer of that work from the IETF to the IEEE. In 1201 order to avoid having the transfer of that work be dependent on the 1202 availability of this RFC's authors at the time of its publication, 1203 the IEEE Standards Association department of Risk Management and 1204 Licensing provided the appropriate forms and mechanisms for this 1205 document's authors to assign a non-exclusive license for IEEE to 1206 create derivative works from this document. Those IEEE forms and 1207 mechanisms will be updated as needed during the development of this 1208 document (Note: i.e., RFC XXXX, update it to the actual RFC if 1209 published) and any future IETF YANG modules for IEEE 1588. This 1210 will help to make the future transfer of work from IETF to IEEE 1211 occur as smoothly as possible. 1213 As stated in the initial "Status of this Memo", the YANG module in 1214 this document conforms to the provisions of BCP 78. The IETF will 1215 retain all the rights granted at the time of publication in the 1216 published RFCs. 1218 A.3. Namespace and Module Name 1220 As specified in Section 5 "IANA Considerations", the YANG module in 1221 this document uses IETF as the root of its URN namespace and YANG 1222 module name. 1224 Use of IETF as the root of these names implies that the YANG module 1225 is standardized in a Working Group of IETF, using the IETF 1226 processes. If the IEEE 1588 Working Group were to continue using 1227 these names rooted in IETF, the IEEE 1588 YANG standardization 1228 would need to continue in the IETF. The goal of transferring the 1229 YANG work is to avoid this sort of dependency between standards 1230 organizations. 1232 IEEE 802 has an active PAR (IEEE P802d) for creating a URN 1233 namespace for IEEE use (see 1234 http://standards.ieee.org/develop/project/802d.html). It is likely 1235 that this IEEE 802 PAR will be approved and published prior to the 1236 transfer of YANG work to the IEEE 1588 WG. If so, the IEEE 1588 WG 1237 can use the IEEE URN namespace for the first IEEE 1588 YANG module, 1238 such as: 1240 urn:ieee:Std:1588:yang:ieee1588-ptp 1242 where "ieee1588-ptp" is the registered YANG module name in the IEEE. 1244 Under the assumptions of section A.1, the first IEEE 1588 YANG 1245 module prefix can be the same as the last IETF 1588 YANG module 1246 prefix (i.e. "ptp"), since the nodes within both YANG modules are 1247 compatible. 1249 The result of these name changes are that for complete 1250 compatibility, a server (i.e., IEEE 1588 node) can choose to 1251 implement a YANG module for the last IETF 1588 YANG module (with 1252 IETF root) as well as the first IEEE 1588 YANG module (with IEEE 1253 root). Since the content of the YANG module transferred are the 1254 same, the server implementation is effectively common for both. 1256 From a client's perspective, a client of the last IETF 1588 YANG 1257 module (or earlier) looks for the IETF-rooted module name; and a 1258 client of the first IEEE 1588 YANG module (or later) looks for the 1259 IEEE-rooted module name. 1261 A.4. IEEE 1588 YANG Modules in ASCII Format 1263 Although IEEE 1588 can certainly decide to publish YANG modules 1264 only in the PDF format that they use for their standard documents, 1265 without publishing an ASCII version, most network management 1266 systems cannot import the YANG module directly from the PDF. Thus, 1267 not publishing an ASCII version of the YANG module would negatively 1268 impact implementers and deployers of YANG modules and would make 1269 potential IETF reviews of YANG modules more difficult. 1271 This appendix recommends that the IEEE 1588 WG consider future 1272 plans for: 1274 o Public availability of the ASCII YANG modules during project 1275 development. These ASCII files allow IETF participants to access 1276 these documents for pre-standard review purposes. 1278 o Public availability of the YANG portion of published IEEE 1588 1279 standards, provided as an ASCII file for each YANG module. 1280 These ASCII files are intended for use of the published IEEE 1281 1588 standard. 1283 As an example of public availability during project development, 1284 IEEE 802 uses the same repository that IETF uses for YANG module 1285 development (see https://github.com/YangModels/yang). IEEE branches 1286 are provided for experimental work (i.e. pre-PAR) as well as 1287 standard work (post-PAR drafts). IEEE-SA has approved use of this 1288 repository for project development, but not for published standards. 1290 As an example of public availability of YANG modules for published 1291 standards, IEEE 802.1 provides a public list of ASCII files for MIB 1292 (see http://www.ieee802.org/1/files/public/MIBs/ and 1293 http://www.ieee802.org/1/pages/MIBS.html), and analogous lists are 1294 planned for IEEE 802.1 YANG files. 1296 Authors' Addresses 1298 Yuanlong Jiang (Editor) 1299 Huawei Technologies Co., Ltd. 1300 Bantian, Longgang district 1301 Shenzhen 518129, China 1302 Email: jiangyuanlong@huawei.com 1304 Xian Liu 1305 Independent 1306 Shenzhen 518129, China 1307 lene.liuxian@foxmail.com 1309 Jinchun Xu 1310 Huawei Technologies Co., Ltd. 1311 Bantian, Longgang district 1312 Shenzhen 518129, China 1313 xujinchun@huawei.com 1315 Rodney Cummings (Editor) 1316 National Instruments 1317 11500 N. Mopac Expwy 1318 Bldg. C 1319 Austin, TX 78759-3504 1320 Email: Rodney.Cummings@ni.com